\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.