\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{<Additional Output Truncated>}
\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.
