mirror of https://github.com/wwarthen/RomWBW.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
272 lines
14 KiB
272 lines
14 KiB
\chapter{Overview}
|
|
|
|
RomWBW is system software that supports the Z80/Z180 based computing
|
|
platforms produced by the RetroBrew
|
|
Computing Group which is found at http://www.retrobrewcomputers.org. The goal of the
|
|
project is to provide all firmware
|
|
and software needed to make a fully functional computing platform. This
|
|
includes both firmware (ROM) and
|
|
software (disk images). The source code is provided and is licensed under
|
|
GPL v3. A GitHub repository is
|
|
used to maintain all source code and can be found at
|
|
http://www.github.com/RomWBW.
|
|
|
|
Essentially all Z80/Z180 based hardware produced by RetroBrew Computing is
|
|
fully supported by RomWBW. Much of the software was adapted from software
|
|
produced by others in the community (see Acknowledgements) and is packaged
|
|
within RomWBW to provide an integrated solution. A companion document
|
|
(RomWBW System Guide) provides substantial detail on the architecture and
|
|
internal operation of this software.
|
|
|
|
It is worth noting that this software is a perpetual work-in-progress.
|
|
While it has become fairly stable and robust over time, it is undergoing
|
|
constant updates to support new and revised hardware produced by the
|
|
community. Backward compatibility between releases should not be assumed.
|
|
In order to provide a complete solution, the RomWBW package incorporates a
|
|
hardware BIOS (hardware drivers) and selected operating systems and
|
|
application software. All software is derived from the CP/M era of 8-bit
|
|
computing. The operating systems included have been adapted to run under
|
|
the RomWBW architecture. In general, application software has simply been
|
|
included as originally distributed by the vendors and required no adaptation.
|
|
|
|
The RomWBW distribution package includes all the tools required to easily
|
|
build the software from the source that is included in the package. The
|
|
package includes a range of pre-built ROM and disk images. These are
|
|
usually sufficient to get your hardware up and running simply by
|
|
programming a ROM and optionally copying disk image(s) to a floppy disk, CF
|
|
Card, or SD Card. If you wish to highly customize your system software, it
|
|
is straightforward to modify the source code and build your own. At
|
|
present, this requires Microsoft Windows XP or greater. All of the tools
|
|
have counterparts for Linux, so building the software under Linux should be
|
|
possible with a little effort.
|
|
|
|
\section{System Requirements}
|
|
|
|
RomWBW is purely a software project. It assumes you have a fully
|
|
functional hardware platform on which to host the software. A great deal
|
|
of information on procuring and building the appropriate hardware is found
|
|
on the RetroBrew Computing Wiki at http://www.retrobrewcomputing.org.
|
|
Additionally, the RetroBrew Computing Group has a very active forum found at
|
|
http://www.retrobrewcomputing.org/forum. This forum is the ideal place to
|
|
ask questions and get guidance for hardware and software. It is the
|
|
primary forum for supporting RomWBW.
|
|
|
|
The starting point for a hardware platform that will appropriately host
|
|
RomWBW software is one of the following CPU boards:
|
|
|
|
\begin{description}[style=multiline, leftmargin=1.25in, labelindent=0.25in, align=right]
|
|
|
|
\item [SBC]
|
|
This is the original Z80 CPU board produced by the community. It remains a
|
|
very functional platform and is relatively easy to build. Note that v1 has
|
|
a design deficiency that may or may not prevent the proper operation of
|
|
RomWBW (bank switching does not always function reliably). The SBC CPU
|
|
board features an ECB bus connector which allows it to be expanded with a
|
|
backplane and peripheral boards.
|
|
|
|
\item [Zeta]
|
|
The Zeta is very similar to the SBC board and is generally compatible with
|
|
it. However, the Zeta platform is optimized to be a compact, standalone
|
|
system. In addition to the features of the SBC, it includes an onboard
|
|
floppy disk controller and the form factor of the board allows it to be
|
|
mounted directly to a 3.5" floppy disk for a complete computing solution.
|
|
It optionally supports a single daughter board that provides SD Card
|
|
storage, VGA Monitor interface, and PS/2 keyboard interface. Although it
|
|
does not have a bus interface, Zeta is powerful, compact, and fully
|
|
featured. The Zeta v2 primarily adds enhanced bank switching and an
|
|
interrupt controller which is not required by RomWBW.
|
|
|
|
\item [N8]
|
|
The N8 is a very robust SBC. It is significantly larger than the SBC and
|
|
incorporates a wide range of peripherals right on the one board (although
|
|
it also supports expansion via ECB bus). The N8 is based on the Z180 CPU
|
|
and incorporates interfaces for 2 serial ports, 2 parallel ports, IDE Hard
|
|
Disk / CF Card, SD Card, sound synthesizer, video display, PS/2 keyboard
|
|
and mouse interface, and floppy disk controller. This board is very
|
|
powerful, but more challenging to build. It is not compatible with the
|
|
SBC/Zeta -- it implements a different bank switching mechanism.
|
|
|
|
\item [Mark IV]
|
|
The Mark IV by John Coffman is similar to the SBC in that it shares the
|
|
same form factor and ECB for expansion. However, it is substantially more
|
|
powerful featuring a Z180 CPU and onboard CF Card and SD Card interfaces.
|
|
|
|
\end{description}
|
|
|
|
RomWBW fully supports all of the above boards as a starting point. For
|
|
Zeta, the ParPortProp is supported as an option. The other platforms all
|
|
support the ECB bus for adding optional peripheral support boards.
|
|
|
|
In addition to the hardware listed above, RomWBW also runs well on the
|
|
Microsoft Windows based SIMH Altair Z80 simulator which allows you to try
|
|
all of the RomWBW features without any actual hardware. The distribution
|
|
package contains a copy of the simulator software for MS Windows, so it is
|
|
very easy to use it (see Getting Started).
|
|
|
|
Note that RomWBW assumes specific board configuration settings. You must
|
|
ensure that you set the jumpers/switches of each board as required by
|
|
RomWBW (unless you modify RomWBW and produce a custom version that supports
|
|
your specific board configurations). The standard board configuration
|
|
settings are documented in Appendix A.
|
|
|
|
Note that RomWBW assumes there is 512KB of ROM and 512KB of RAM for all
|
|
systems. It is fine if your system has more RAM or ROM than this, but it
|
|
is problematic if you have less. It would be very rare for a system to
|
|
have less that these amounts, but be aware of this constraint. These
|
|
assumptions can be modified via customization later, but the pre-built
|
|
software must have these minimums.
|
|
|
|
All of the host boards include a serial port. RomWBW will use this serial
|
|
port for output when you start your system. By default, RomWBW uses 38,400
|
|
baud, 8 data bits, 1 stop bit, and no parity. You will need to connect the
|
|
primary serial port of the host board to a terminal (or PC running terminal
|
|
emulation software) to see the system output when you start RomWBW.
|
|
|
|
The use of the ECB bus signals is standardized such that any ECB add-on
|
|
board can generally be combined with any of the ECB host boards to provide
|
|
enhanced functionality. Appendix A provides an inventory of the boards
|
|
supported by RomWBW along with relevant notes and required board
|
|
configuration settings. Appendix A also includes a compatibility/support
|
|
matrix between the host boards and the peripheral support boards.
|
|
|
|
\section{Acknowledgements}
|
|
|
|
First, I want to be clear that RomWBW is not the only option available for
|
|
system software on RetroBrew Computing Z80/Z180 hardware. While many
|
|
similar projects are no longer active, they are very useful and may contain
|
|
functionality that has not been incorporated in RomWBW. All of the
|
|
software projects (including RomWBW) are listed in the RetroBrew Computing
|
|
Wiki.
|
|
|
|
The UNA Project from John Coffman is the other currently active software
|
|
project for the Z80/Z180 projects. It is far more advanced than RomWBW in
|
|
that it can support all 4 host boards with a single ROM image and allows
|
|
dynamic system configuration via onboard setup. It does not yet support
|
|
the full range of hardware or video capabilities of RomWBW. Note that
|
|
RomWBW supports an UNA "hybrid" configuration in which the UNA BIOS is
|
|
combined with the RomWBW OS and application layers.
|
|
|
|
The RetroBrew Computing Group has existed in various forms since about 2010
|
|
(?). Many individuals have contributed to the community. The original
|
|
founder of the community has moved on and requested anonymity going
|
|
forward. However, his initiative is greatly appreciated. While there is
|
|
no formal structure to the community, Andrew Bingham has taken the mantle
|
|
of responsibility for the wiki and discussion group. This is a critical
|
|
function and he deserves substantial credit for this effort.
|
|
|
|
Earlier in the community's history, there were multiple branches of
|
|
software development. Frequently, when a new board was produced, someone
|
|
would create an independent code branch to support it. This started to
|
|
lead to a very fragmented set of software that made it very difficult to
|
|
create an integrated system with selected boards. RomWBW came about as an
|
|
effort to create a framework that would allow arbitrary hardware to be
|
|
easily added without creating entirely separate branches of code.
|
|
|
|
RomWBW essentially became a semi-structured place to incorporate all of the
|
|
many software efforts of the community. Initially, most of the RomWBW
|
|
codebase was simply a "cut and paste" of the software produced by others.
|
|
Over time, much of this software has been repeatedly revised such that it
|
|
is no longer similar to the original, but RomWBW owes its existence to the
|
|
contributions of many other individuals. A few of those people are listed
|
|
below and I apologize for anyone that I may have inadvertently omitted. I
|
|
have intentionally omitted the original founder of the community based on
|
|
my understanding of his desire to be anonymous going forward.
|
|
|
|
Douglas Goodall worked in very close collaboration with me during the first
|
|
year of the RomWBW Project. He produced an excellent set of supporting
|
|
utility programs and provided a great deal of design input. Regrettably,
|
|
his utilities no longer have a caretaker and have become unusable as RomWBW
|
|
has evolved, but their legacy continues within the current codebase. The
|
|
source for all of these utilities is still available if anyone wants to
|
|
take responsibility for bringing them back to current status.
|
|
|
|
John Coffman has personally produced a great deal of the hardware designs
|
|
within the community. RomWBW contains many portions of code that John
|
|
contributed over time. Additionally, he has been instrumental in providing
|
|
advice and guidance to me for many years now.
|
|
|
|
Dan Werner has been one of the most prolific coders within the community.
|
|
A great deal of his code was incorporated in the early RomWBW releases.
|
|
David Giles produced some code that also provided a more integrated set of
|
|
software for each host board. Over time, much of his code was incorporated
|
|
in RomWBW. Likewise, Max Scane has produced code that ultimately wound up
|
|
in RomWBW -- specifically, he contributed the CLRDIR application.
|
|
|
|
It is my belief that all code incorporated into RomWBW has been done so
|
|
with the express or implied permission of the original authors. I realize
|
|
there have been many other individuals that have contributed to RomWBW and
|
|
apologize for not naming all of them.
|
|
|
|
\section{RomWBW Distribution Package}
|
|
|
|
RomWBW is distributed as a complete package (a .zip file) that contains
|
|
everything appropriate for the different hardware variations. In other
|
|
words, don't look for a specific distribution for your hardware, you just
|
|
want the current package. Within the package, you will find documentation,
|
|
source code, build tools, and pre-built ROM and disk images.
|
|
|
|
The distribution package is usually hosted at the following locations:
|
|
|
|
|
|
\begin{itemize}
|
|
\item {\bf RetroBrew Computing Wiki}
|
|
|
|
Navigate to https://www.retrobrewcomputers.org. Then, using the navigation
|
|
menu on the left, choose software $\rightarrow$ firmwareos
|
|
$\rightarrow$ romwbw to reach the RomWBW
|
|
Project Page. At the bottom of the page you will find the distribution
|
|
files listed for download.
|
|
|
|
\item {\bf GitHub}
|
|
|
|
Navigate to https://github.com/wwarthen/RomWBW for the RomWBW Project
|
|
on GitHub. Select "releases" to reach the list of distribution files.
|
|
Note that you will see both Prereleases and Releases listed. Unless you
|
|
specifically want to test work-in-progress, please download only a Release
|
|
version.
|
|
\end{itemize}
|
|
|
|
The package should be named something like RomWBW-2.8-Package.zip. Using
|
|
any standard personal computer (Windows, Linux, Mac, etc.), download and
|
|
extract the contents of the zip file using any of the standard zip tools.
|
|
You will see that there are several directories that are used to organize
|
|
the contents. Don't get overwhelmed. Initially, all you really care about
|
|
is the Output directory (and possibly the Doc directory):
|
|
|
|
\begin{description}[style=multiline, leftmargin=1.25in, labelindent=0.25in, align=right]
|
|
|
|
\item [Doc]
|
|
Contains documentation files for many components of the RomWBW distribution
|
|
including operating systems, applications, and other aspects of RomWBW
|
|
itself. In most cases, the name of the file should identify the component
|
|
being documented.
|
|
|
|
\item[Hardware]
|
|
Files that are specific to certain hardware components. For example, it
|
|
has the font ROM images for the video display boards. You do not need any
|
|
of these files for the host boards used initially. Appendix A describes
|
|
the contents of this directory for relevant boards.
|
|
|
|
\item[Images]
|
|
Files that are used to create disk images. Since the disk images are all
|
|
pre-built, you do not need to worry about this directory until you want to
|
|
create custom disk images (documented later).
|
|
|
|
\item[Output]
|
|
The ROM and Disk Images that you need to get started as documented below in
|
|
Getting Started.
|
|
|
|
\item[Source]
|
|
The source code files that are compiled or assembled to create RomWBW.
|
|
Again, the output is pre-built, so you don't need to worry about this
|
|
directory until you want to customize your system.
|
|
|
|
\item[Tools]
|
|
Windows-based applications that are used to build RomWBW. It also contains
|
|
applications that you can use to copy disk images to floppy disks, CF
|
|
Cards, SD Cards, etc. It also has the SIMH simulation software.
|
|
|
|
\end{description}
|
|
|
|
In most cases, you will find a ReadMe.txt file in the directory which
|
|
describes the contents of the directory in more detail.
|
|
|