\chapter{Getting Started} Because of the wide variety of hardware combinations, there is no "one case fits all" approach to getting started. The good news is that RomWBW operates very consistently regardless of the specific hardware. The operating systems, applications, and storage formats are all common. However, building and testing your hardware is entirely outside the scope of this document. The RetroBrew Computing Forum (https://www.retrobrewcomputers.org/forum) is probably the best place to get advice if you get stuck on hardware issues. \section{SIMH Simulator} It is not necessary, but I highly recommend running RomWBW under the SIMH Simulator as a first step. This requires no hardware and will allow you to see how it should look when you use it on real hardware. Since the SIMH software is included in the distribution package, you can start it with a single command. Using a command prompt window, navigate to the high level directory of the distribution. Enter the command "sim" and the simulator should start up. The first few lines of output should look similar to Figure \ref{fig:simhboot}. You may see some benign warning messages that can be ignored. \begin{figure}[ht] \setlength\abovecaptionskip{-0.5em} \begin{Verbatim}[commandchars=\\\{\}, fontsize=\scriptsize, frame=single, rulecolor=\color{cyan}, numbers=left] ROM Image: 'Output\textbackslash{}SBC_simh.rom' RetroBrew HBIOS v2.8.0-pre.5, 2016-06-22 SBC Z80 @ 20.000MHz ROM=512KB RAM=512KB UART0: IO=0x68 8250 MODE=38400,8,N,1 SIMRTC: Wed 2016-06-22 15:10:17 MD: UNITS=2 ROMDISK=384KB RAMDISK=384KB HDSK: UNITS=2 \textsl{} \end{Verbatim} \caption{SIMH Boot Example} \label{fig:simhboot} \end{figure} \section{Board Setup} In all cases, you will want to start with a Z80/Z180 host board. Any of the boards listed in System Requirements will work fine. I strongly recommend that you initially work on getting just the single host board running by itself -- don't even plug it into an ECB backplane. Given a host board that is assembled and passes any hardware checks recommended by the boards designer, you need to make sure the board is configured for RomWBW. Refer to the entry in Appendix A for your board and confirm that all switches and jumpers on the board are set as required by RomWBW. Your initial goal is to locate and program a ROM image for your host board. The ROM images are located in the Output directory. You are looking for the files that end in ".rom". Don't worry about all of the other variations at this point. Refer to Table \ref{tab:basicromfiles} to determine the ROM image that you want. \begin{table}[ht] \center %\renewcommand{\arraystretch}{1.5} \setlength{\arrayrulewidth}{2pt} \begin{tabular}{l l} \toprule \bf CPU Board & \bf ROM Image File \\ \midrule SBC v1/v2 & SBC\_std.rom \\ Zeta v1 & ZETA\_std.rom \\ Zeta v2 & ZETA2\_std.rom \\ N8 (2511) & N8\_2511.rom \\ N8 (2312) & N8\_2312.rom \\ Mark IV & MK4\_std.rom \\ \bottomrule \end{tabular} \caption{Basic ROM Files} \label{tab:basicromfiles} \end{table} Locate the appropriate ROM image file in the Output directory based on Table \ref{tab:basicromfiles}. You should see that the file is exactly 512KB in size. As indicated above in System Requirements, your system should have a ROM capacity of 512KB or greater. You need to program the file to your ROM using whatever tool you have. Programming a ROM chip is beyond the scope of this document, but any feel free to ask for help at the RetroBrew Computing Forum. The ROM image files are pure binary and should be programmed into the ROM chip starting at address 0H thru address 7FFFH (8000H bytes). Insert the programmed ROM chip in your system. Initially, you will need two external connections to your board. Power and serial port. All of the CPU boards provide an onboard power connection. Refer to the board designer's notes on the RBC Wiki for more information on the power connection your board requires. Finally, you must connect the primary serial port of your host board to a terminal using 38,400 baud, 8 data bits, 1 stop bit, and no parity. You can use either a dedicated terminal or use terminal emulation software on your PC\footnote{Under Windows, Tera Term is a good choice for terminal emulation.}. When connecting to a standard PC serial port, a null modem cable is required. There is a good document on the Wiki that explains cabling of serial ports at http://???????. \todo{Need to restore serial port cabling document on Wiki!} \section{Startup} System startup (booting) is accomplished simply by applying power. In some cases, it may be necessary to press the reset button after applying power to get a successful startup. If everything is working properly, you should see something like Figure \ref{fig:boot} on your terminal screen. Your output will vary somewhat depending on your specific hardware. The example shown comes from a Mark IV. \begin{figure}[ht] \setlength\abovecaptionskip{-0.5em} \begin{Verbatim}[commandchars=\\\{\}, fontsize=\scriptsize, frame=single, rulecolor=\color{cyan}, numbers=left] RetroBrew HBIOS v2.8.0-pre.5, 2016-06-03 MARK IV Z180 @ 18.432MHz ROM=512KB RAM=512KB ASCI0: IO=0x46,48 MODE=38400,8,N,1 ASCI1: IO=0x47,49 MODE=38400,8,N,1 DSRTC: MODE=STD Wed 2016-06-22 15:03:06 MD: UNITS=2 ROMDISK=384KB RAMDISK=384KB IDE: MODE=MK4 IO=0x80 UNITS=2 IDE0: NO MEDIA IDE1: NO MEDIA SD: MODE=MK4 FAST OPR=0x89 CNTR=0x4A TRDR=0x4B UNITS=1 SD0: NO MEDIA Unit Device Type Capacity/Mode ---------- ---------- ---------------- -------------------- Disk 0 MD1: RAM Disk 384KB,LBA Disk 1 MD0: ROM Disk 384KB,LBA Disk 2 IDE0: Hard Disk -- Disk 3 IDE1: Hard Disk -- Disk 4 SD0: SD Card -- Serial 0 ASCI0: RS-232 38400,8,N,1 Serial 1 ASCI1: RS-232 38400,8,N,1 MARK IV Z180 Boot Loader Boot: (C)PM, (Z)System, (M)onitor, (L)ist disks, or Disk Unit # ===> \end{Verbatim} \caption{Typical Boot Display} \label{fig:boot} \end{figure} If you see output on your terminal screen, but it is garbled/unreadable, then check the serial port configuration settings on your terminal or terminal emulation software. If you do not see any output of any kind on your terminal screen, the following general areas should be checked: \begin{itemize} \item Confirm power is being applied to the board and the the voltage is in an acceptable range. \item Confirm the ROM is programmed accurately by placing it back in the programmer and using the verify function. \item Verify the serial connection. When connecting to a PC, make sure you have a null modem cable or adapter. \item Review your board's construction carefully for chip orientation, bent pins, missing or bridged solder joints, etc. \end{itemize} You will find that the RetroBrew Computing Group is very helpful if you get stuck. The best way to request assistance is to post a message on the Forum. \section{Boot Display} As illustrated in Figure \ref{fig:boot}, RomWBW displays a lot of information about the system and it's configuration. There are 4 basic sections to the boot display. Line 1 is a banner that identifies the BIOS portion of the ROM including version and build date. Lines 3-12 display the hardware inventory of the system as understood by the ROM. Note that some of this information is \emph{not} discovered dynamically -- it is built into the ROM. So, do not be alarmed if some parts of this display do not match your hardware. For example, the RAM and ROM size are configured into the ROM itself. You can refer to Appendix A for more information on how to read the specific lines. Lines 14-22 contain a table that summarizes the devices in the system. This information is used when the operating system is loaded/configured to assign OS devices to system devices. Lines 24-27 is the display of the boot loader menu and prompt. The boot loader allows you to choose the operating mode you want to initiate. These options will be described the next section. \section{Loader} At the conclusion of a successful system startup, the loader menu/prompt will be displayed on the console. The function of the loader is to load an operating system or system monitor. \subsection{Monitor} Pressing 'M' at the boot loader prompt will launch a basic system monitor. The system monitor provides very basic functions that are primarily useful for testing components of your system. These functions include displaying and modifying memory, reading and writing to I/O ports, etc. Refer to ??? for monitor operation. \subsection{CP/M} Pressing 'C' at the boot loader prompt will launch Digital Research CP/M-80 Version 2.2. A complete copy of the CP/M operating system is imbedded in the ROM and will be loaded directly from there, so no disk access is required. Initially, drive A will be a RAM drive (initialized with no files). Drive B will be a ROM drive. The standard CP/M distribtion files are included on the ROM drive (e.g., ASM, PIP, STAT). Drive B will initially be the logged drive. At this point, you can execute the programs on drive B. Remember that drive B is a ROM drive, so any attempt to write to that drive will result in an error. Refer to Chapter ?? for more information on using CP/M 2.2. \subsection{Z-System} Pressing 'Z' at the boot loader prompt will launch Z-System, a CP/M 2.2 compatible operating system with many enhancements. As with CP/M, this operating system will be loaded directly from ROM. The drive configuration for Z-System is identical to CP/M. Refer to Chapter ?? for more information on using Z-System. \subsection{Disk Boot} The boot loader also supports loading an operating system from a disk device. In this case, you must press the number key corresponding to the disk device containing the operating system to be loaded. The disk device numbers are the ones listed in the device summary table. In order to boot from a disk device, it must be properly initialized using the SYSCOPY application or equivalent. Attempting to boot a disk that has no operating system will result in an error and the boot loader prompt will be redisplayed. You can press 'L' at the boot loader prompt to display a list of the disk devices available. The existence of a disk in this list does \emph{not} mean that it has been initialized with an operating system.