RomWBW Applications Guide \
Version 3.6 \
MartinR \& Phillip Summers () \
-25 Nov 2025
+30 Nov 2025
Summary
RomWBW is supplied with a suite of software applications that enhance
the use of the system. Some of these applications have been written
diff --git a/Catalog/index.html b/Catalog/index.html
index 39249cbd..ec120da6 100644
--- a/Catalog/index.html
+++ b/Catalog/index.html
@@ -336,7 +336,7 @@
RomWBW Disk Catalog \
Version 3.6 \
Mark Pruden \& Mykl Orders () \
-25 Nov 2025
+30 Nov 2025
RomWBW Distribution File Catalog
This document is a reference to the files found on the disk media
distributed with RomWBW. Specifically, RomWBW provides a set of floppy
diff --git a/Hardware/index.html b/Hardware/index.html
index b35296b0..d2276b8c 100644
--- a/Hardware/index.html
+++ b/Hardware/index.html
@@ -212,6 +212,10 @@
@@ -788,7 +798,8 @@ external bank switching.
6Designed by Alan Cox 7Designed by Doug Jackson 8Designed by Dean Netherton
-9MSX Port by Henk Berends
+9MSX Port by Henk Berends
+10Designed by Dan Werner
General Guidance
The standard ROM images will detect and install support for certain
devices and peripherals that are on-board or frequently used with each
@@ -2028,6 +2039,72 @@ additional boards are required.
SD Card interface is configured for CSIO (N8 date code >= 2312)
@@ -3542,7 +3619,7 @@ slave as defined by the IEEE-696 specs.
-
Supported Hardware
+
Supported Hardware
INTRTC: ENABLED
PLDSER: IO=172
@@ -3561,7 +3638,7 @@ slave as defined by the IEEE-696 specs.
PPIDE: MODE=S100B, IO=48, SLAVE
SD: MODE=SC, IO=12, UNITS=1
-
Notes:
+
Notes:
Z180 SBC SW2 (IOBYTE) Dip Switches:
@@ -3665,7 +3742,7 @@ system.
-
Supported Hardware
+
Supported Hardware
FP: LEDIO=13, SWIO=0
DSRTC: MODE=STD, IO=12
@@ -3693,7 +3770,7 @@ system.
PPIDE: IO=32, SLAVE
SD: MODE=SC, IO=12, UNITS=1
-
Notes:
+
Notes:
When disabled, watchdog requires /IM to be pulsed. If an RCBus module
holds the CPU in WAIT for more than this, the watchdog will fire when
@@ -3749,7 +3826,7 @@ RomWBW (and CP/M)
-
Supported Hardware
+
Supported Hardware
FP: LEDIO=0, SWIO=0
DSRTC: MODE=STD, IO=12
@@ -3827,7 +3904,7 @@ RomWBW (and CP/M)
-
Supported Hardware
+
Supported Hardware
INTRTC: ENABLED
ASCI: IO=192, INTERRUPTS ENABLED
@@ -3885,7 +3962,7 @@ RomWBW (and CP/M)
-
Supported Hardware
+
Supported Hardware
FP: LEDIO=160, SWIO=160
DSRTC: MODE=STD, IO=12
@@ -3963,7 +4040,7 @@ RomWBW (and CP/M)
-
Supported Hardware
+
Supported Hardware
FP: LEDIO=160, SWIO=160
DSRTC: MODE=STD, IO=12
@@ -4046,7 +4123,7 @@ RomWBW (and CP/M)
-
Supported Hardware
+
Supported Hardware
FP: LEDIO=0
LCD: IO=170, SIZE=20X4
@@ -4132,7 +4209,7 @@ presented by John’s Basement on youTube)
-
Supported Hardware
+
Supported Hardware
SIO MODE=Z80R, IO=128, CHANNEL A, INTERRUPTS ENABLED
RomWBW Introduction \
Version 3.6 \
Wayne Warthen (wwarthen@gmail.com) \
-25 Nov 2025
+30 Nov 2025
Overview
RomWBW software provides a complete, commercial quality implementation
of CP/M (and work-alike) operating systems and applications for modern
diff --git a/SystemGuide/index.html b/SystemGuide/index.html
index 4a78061e..ac7b55bd 100644
--- a/SystemGuide/index.html
+++ b/SystemGuide/index.html
@@ -659,7 +659,7 @@
RomWBW System Guide \
Version 3.6 \
Wayne Warthen (wwarthen@gmail.com) \
-25 Nov 2025
+30 Nov 2025
Overview
The objective of RomWBW is to provide firmware, operating systems, and
applications targeting the Z80 family of CPUs. The firmware, in the form
diff --git a/UserGuide/index.html b/UserGuide/index.html
index b10f792c..f4a8024d 100644
--- a/UserGuide/index.html
+++ b/UserGuide/index.html
@@ -527,7 +527,7 @@
RomWBW User Guide \
Version 3.6 \
Wayne Warthen (wwarthen@gmail.com) \
-25 Nov 2025
+30 Nov 2025
Preface
This document is a general usage guide for the RomWBW software and is
generally the best place to start with RomWBW.
RomWBW Introduction \
Version 3.6 \
Wayne Warthen (wwarthen@gmail.com) \
-25 Nov 2025
+30 Nov 2025
Overview
RomWBW software provides a complete, commercial quality implementation
of CP/M (and work-alike) operating systems and applications for modern
@@ -704,5 +704,5 @@ control system to ensure their contributions are clearly documented.
diff --git a/search/search_index.json b/search/search_index.json
index 95e37611..b077ece5 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"RomWBW Introduction \\ Version 3.6 \\ Wayne Warthen ( wwarthen@gmail.com ) \\ 25 Nov 2025 Overview RomWBW software provides a complete, commercial quality implementation of CP/M (and work-alike) operating systems and applications for modern Z80/180/280 retro-computing hardware systems. A wide variety of platforms are supported including those produced by these developer communities: RetroBrew Computers ( https://www.retrobrewcomputers.org ) RC2014 ( https://rc2014.co.uk ), RC2014-Z80 ( https://groups.google.com/g/rc2014-z80 ) Retro Computing ( https://groups.google.com/g/retro-comp ) Small Computer Central ( https://smallcomputercentral.com/ ) A complete list of the currently supported platforms is found in RomWBW Hardware . Description Primary Features By design, RomWBW isolates all of the hardware specific functions in the ROM chip itself. The ROM provides a hardware abstraction layer such that all of the operating systems and applications on a disk will run on any RomWBW-based system. To put it simply, you can take a disk (or CF/SD/USB Card) and move it between systems transparently. Supported hardware features of RomWBW include: Z80 Family CPUs including Z80, Z180, and Z280 Banked memory services for several banking designs Disk drivers for RAM, ROM, Floppy, IDE ATA/ATAPI, CF, SD, USB, Zip, Iomega Serial drivers including UART (16550-like), ASCI, ACIA, SIO Video drivers including TMS9918, SY6545, MOS8563, HD6445, Xosera Keyboard (PS/2) drivers via VT8242 or PPI interfaces Real time clock drivers including DS1302, BQ4845 Support for CP/NET networking using Wiznet, MT011 or Serial Built-in VT-100 terminal emulation support A dynamic disk drive letter assignment mechanism allows mapping operating system drive letters to any available disk media. Additionally, mass storage devices (IDE Disk, CF Card, SD Card, etc.) support the use of multiple slices (up to 256 per device). Each slice contains a complete CP/M filesystem and can be mapped independently to any drive letter. This overcomes the inherent size limitations in legacy OSes and allows up to 2GB of addressable storage on a single device, with up to 128MB accessible at any one time. Included Software Multiple disk images are provided in the distribution. Most disk images contain a complete, bootable, ready-to-run implementation of a specific operating system. A \u201ccombo\u201d disk image contains multiple slices, each with a full operating system implementation. If you use this disk image, you can easily pick whichever operating system you want to boot without changing media. Some of the included software: Operating Systems (CP/M 2.2, ZSDOS, NZ-COM, CP/M 3, ZPM3, Z3PLUS, QPM ) Support for other operating systems, p-System, FreeRTOS, and FUZIX. Programming Tools (Z80ASM, Turbo Pascal, Forth, Cowgol) C Compiler\u2019s including Aztec-C, and HI-TECH C Microsoft Basic Compiler, Microsoft Fortran, and Microsoft COBOL Some games such as Colossal Cave, Zork, etc Wordstar Word processing software Some of the provided software can be launched directly from the ROM firmware itself: System Monitor Operating Systems (CP/M 2.2, ZSDOS) ROM BASIC (Nascom BASIC and Tasty BASIC) ROM Forth A tool is provided that allows you to access a FAT-12/16/32 filesystem. The FAT filesystem may be coresident on the same disk media as RomWBW slices or on stand-alone media. This makes exchanging files with modern OSes such as Windows, MacOS, and Linux very easy. ROM Distribution The RomWBW Repository ( https://github.com/wwarthen/RomWBW ) on GitHub is the official distribution location for all project source and documentation. RomWBW is distributed as both source code and pre-built ROM and disk images. The pre-built ROM images distributed with RomWBW are based on the default system configurations as determined by the hardware provider/designer. The pre-built ROM firmware images are generally suitable for most users. The fully-built distribution releases are available on the RomWBW Releases Page ( https://github.com/wwarthen/RomWBW/releases ) of the repository. On this page, you will normally see a Development Snapshot as well as recent stable releases. Unless you have a specific reason, I suggest you stick to the most recent stable release. The asset named RomWBW-vX.X.X-Package.zip includes all pre-built ROM and Disk images as well as full source code. The other assets contain only source code and do not have the pre-built ROM or disk images. Distribution Directory Layout The RomWBW distribution is a compressed zip archive file organized in a set of directories. Each of these directories has its own ReadMe.txt file describing the contents in detail. In summary, these directories are: Directory Description Binary The final output files of the build process are placed here. Most importantly, the ROM images with the file names ending in \u201c.rom\u201d and disk images ending in .img. Doc Contains various detailed documentation, both RomWBW specifically as well as the operating systems and applications. Source Contains the source code files used to build the software and ROM images. Tools Contains the programs that are used by the build process or that may be useful in setting up your system. Building from Source It is also very easy to modify and build custom ROM images that fully tailor the firmware to your specific preferences. All tools required to build custom ROM firmware under Windows are included \u2013 no need to install assemblers, etc. The firmware can also be built using Linux or MacOS after confirming a few standard tools have been installed. Installation & Operation In general, installation of RomWBW on your platform is very simple. You just need to program your ROM with the correct ROM image from the RomWBW distribution. Subsequently, you can write disk images on your disk drives (IDE disk, CF Card, SD Card, etc.) which then provides even more functionality. Complete instructions for installation and operation of RomWBW are found in the RomWBW User Guide . It is also a good idea to review the Release Notes for helpful release-specific information. Documentation There are several documents that form the core of the RomWBW documentation: RomWBW User Guide is the main user guide for RomWBW, it covers the major topics of how to install, manage and use RomWBW, and includes additional guidance to the use of some of the operating systems supported by RomWBW RomWBW Hardware contains a description of all the hardware platforms, and devices supported by RomWBW. RomWBW Applications is a reference for the ROM-hosted and OS-hosted applications created or customized to enhance the operation of RomWBW. RomWBW Disk Catalog is a reference for the contents of the disk images provided with RomWBW, with a description of many of the files on each image RomWBW System Guide discusses much of the internal design and construction of RomWBW. It includes a reference for the RomWBW HBIOS API functions. An online HTML version of this documentation is hosted at https://wwarthen.github.io/RomWBW . Each of the operating systems and ROM applications included with RomWBW are sophisticated tools in their own right. It is not reasonable to fully document their usage. However, you will find complete manuals in PDF format in the Doc directory of the distribution. The intention of this documentation is to describe the operation of RomWBW and the ways in which it enhances the operation of the included applications and operating systems. Since RomWBW is purely a software product for many different platforms, the documentation does not cover hardware construction, configuration, or troubleshooting \u2013 please see your hardware provider for this information. Support Getting Assistance The best way to get assistance with RomWBW or any aspect of the RetroBrew Computers projects is via one of the community forums: RetroBrew Computers Forum RC2014 Google Group retro-comp Google Group Submission of issues and bugs are welcome at the RomWBW GitHub Repository . Also feel free to email Wayne Warthen at wwarthen@gmail.com . I am happy to provide support adapting RomWBW to new or modified systems Contributions All source code and distributions are maintained on GitHub. Contributions of all kinds to RomWBW are very welcome. Acknowledgments I want to acknowledge that a great deal of the code and inspiration for RomWBW has been provided by or derived from the work of others in the RetroBrew Computers Community. I sincerely appreciate all of their contributions. The list below is probably missing many names \u2013 please let me know if I missed you! Andrew Lynch started it all when he created the N8VEM Z80 SBC which became the first platform RomWBW supported. Some of his original code can still be found in RomWBW. Dan Werner wrote much of the code from which RomWBW was originally derived and he has always been a great source of knowledge and advice. Douglas Goodall contributed code, time, testing, and advice in \u201cthe early days\u201d. He created an entire suite of application programs to enhance the use of RomWBW. Unfortunately, they have become unusable due to internal changes within RomWBW. As of RomWBW 2.6, these applications are no longer provided. Sergey Kiselev created several hardware platforms for RomWBW including the very popular Zeta. David Giles created support for the Z180 CSIO which is now included SD Card driver. Phil Summers contributed the Forth and BASIC adaptations in ROM, the AY-3-8910 sound driver, DMA support, and a long list of general code and documentation enhancements. Ed Brindley contributed some of the code that supports the RCBus platform. Spencer Owen created the RC2014 series of hobbyist kit computers which has exponentially increased RomWBW usage. Some of his kits include RomWBW. Stephen Cousins has likewise created a series of hobbyist kit computers at Small Computer Central and is distributing RomWBW with many of them. Alan Cox has contributed some driver code and has provided a great deal of advice. The CP/NET client files were developed by Douglas Miller. Phillip Stevens contributed support for FreeRTOS. Curt Mayer contributed the original Linux / MacOS build process. UNA BIOS and FDISK80 are the products of John Coffman. FLASH4 is a product of Will Sowerbutts. CLRDIR is a product of Max Scane. Tasty Basic is a product of Dimitri Theulings. Dean Netherton contributed multiple components: eZ80 CPU support Sound driver infrastructure SN76489 sound driver Native USB driver (keyboard, floppy, mass storage) The RomWBW Disk Catalog document was produced by Mykl Orders. Rob Prouse has created many of the supplemental disk images including Aztec C, HiTech C, SLR Z80ASM, Turbo Pascal, Microsoft BASIC Compiler, Microsoft Fortran Compiler, and a Games compendium. Martin R has provided substantial help reviewing and improving the User Guide and Applications documents. Mark Pruden has made a wide variety of contributions including: significant content in the Disk Catalog and User Guide creation of the Introduction and Hardware documents Z3PLUS operating system disk image Infocom text adventure game disk image COPYSL, and SLABEL utilities Display of bootable slices via \u201cS\u201d command during startup Optimisations of HBIOS and CBIOS to reduce overall code size a feature for RomWBW configuration by NVRAM the /B bulk mode of disk assignment to the ASSIGN utility Jacques Pelletier has contributed the DS1501 RTC driver code. Jose Collado has contributed enhancements to the TMS driver including compatibility with standard TMS register configuration. Kevin Boone has contributed a generic HBIOS date/time utility (WDATE). Matt Carroll has contributed a fix to XM.COM that corrects the port specification when doing a send. Dean Jenkins enhanced the build process to accommodate the Raspberry Pi 4. Tom Plano has contributed a new utility (HTALK) to allow talking directly to HBIOS COM ports. Lars Nelson has contributed several generic utilities such as a universal (OS agnostic) UNARC application. Dylan Hall added support for specifying a secondary console. Bill Shen has contributed boot loaders for several of his systems. Laszlo Szolnoki has contributed an EF9345 video display controller driver. Ladislau Szilagyi has contributed an enhanced version of CP/M Cowgol that leverages RomWBW memory banking. Les Bird has contributed support for the NABU w/ Option Board Rob Gowin created an online documentation site via MkDocs, and contributed a driver for the Xosera FPGA-based video controller. J\u00f6rg Linder has contributed disassembled and nicely commented source for ZSDOS2 and the BPBIOS utilities. Marshall Gates has contriubed sample program source files for all of the language disk images. Randy Merkel provided the ZSDOS Programmer\u2019s Manual as translated by Wayne Hortensius. Henk Berends added support for the MSX platform. Related Projects Outside of the hardware platforms adapted to RomWBW, there are a variety of projects that either target RomWBW specifically or provide a RomWBW-specific variation. These efforts are greatly appreciated and are listed below. Please contact the author if there are any other such projects that are not listed. Z88DK Z88DK is a software powerful development kit for Z80 computers supporting both C and assembly language. This kit now provides specific library support for RomWBW HBIOS. The Z88DK project is hosted at https://github.com/z88dk/z88dk . Paleo Editor Steve Garcia has created a Windows-hosted IDE that is tailored to development of RomWBW. The project can be found at https://github.com/alloidian/PaleoEditor . Z80 fig-FORTH Dimitri Theulings\u2019 implementation of fig-FORTH for the Z80 has a RomWBW-specific variant. The project is hosted at https://github.com/dimitrit/figforth . Assembly Language Programming for the RC2014 Zed Bruce Hall has written a very nice document that describes how to develop assembly language applications on RomWBW. It begins with the setup and configuration of a new RC2014 Zed system running RomWBW. It describes not only generic CP/M application development, but also RomWBW HBIOS programming and bare metal programming. The latest copy of this document is hosted at http://w8bh.net/Assembly for RC2014Z.pdf . Licensing License Terms RomWBW is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. RomWBW is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with RomWBW. If not, see https://www.gnu.org/licenses/ . Portions of RomWBW were created by, contributed by, or derived from the work of others. It is believed that these works are being used in accordance with the intentions and/or licensing of their creators. If anyone feels their work is being used outside of its intended licensing, please notify: Wayne Warthen wwarthen@gmail.com RomWBW is an aggregate work. It is composed of many individual, standalone programs that are distributed as a whole to function as a cohesive system. Each program may have its own licensing which may be different from other programs within the aggregate. In some cases, a single program (e.g., CP/M Operating System) is composed of multiple components with different licenses. It is believed that in all such cases the licenses are compatible with GPL version 3. RomWBW encourages code contributions from others. Contributors may assert their own copyright in their contributions by annotating the contributed source code appropriately. Contributors are further encouraged to submit their contributions via the RomWBW source code control system to ensure their contributions are clearly documented. All contributions to RomWBW are subject to this license.","title":"Home"},{"location":"#overview","text":"RomWBW software provides a complete, commercial quality implementation of CP/M (and work-alike) operating systems and applications for modern Z80/180/280 retro-computing hardware systems. A wide variety of platforms are supported including those produced by these developer communities: RetroBrew Computers ( https://www.retrobrewcomputers.org ) RC2014 ( https://rc2014.co.uk ), RC2014-Z80 ( https://groups.google.com/g/rc2014-z80 ) Retro Computing ( https://groups.google.com/g/retro-comp ) Small Computer Central ( https://smallcomputercentral.com/ ) A complete list of the currently supported platforms is found in RomWBW Hardware .","title":"Overview"},{"location":"#description","text":"","title":"Description"},{"location":"#primary-features","text":"By design, RomWBW isolates all of the hardware specific functions in the ROM chip itself. The ROM provides a hardware abstraction layer such that all of the operating systems and applications on a disk will run on any RomWBW-based system. To put it simply, you can take a disk (or CF/SD/USB Card) and move it between systems transparently. Supported hardware features of RomWBW include: Z80 Family CPUs including Z80, Z180, and Z280 Banked memory services for several banking designs Disk drivers for RAM, ROM, Floppy, IDE ATA/ATAPI, CF, SD, USB, Zip, Iomega Serial drivers including UART (16550-like), ASCI, ACIA, SIO Video drivers including TMS9918, SY6545, MOS8563, HD6445, Xosera Keyboard (PS/2) drivers via VT8242 or PPI interfaces Real time clock drivers including DS1302, BQ4845 Support for CP/NET networking using Wiznet, MT011 or Serial Built-in VT-100 terminal emulation support A dynamic disk drive letter assignment mechanism allows mapping operating system drive letters to any available disk media. Additionally, mass storage devices (IDE Disk, CF Card, SD Card, etc.) support the use of multiple slices (up to 256 per device). Each slice contains a complete CP/M filesystem and can be mapped independently to any drive letter. This overcomes the inherent size limitations in legacy OSes and allows up to 2GB of addressable storage on a single device, with up to 128MB accessible at any one time.","title":"Primary Features"},{"location":"#included-software","text":"Multiple disk images are provided in the distribution. Most disk images contain a complete, bootable, ready-to-run implementation of a specific operating system. A \u201ccombo\u201d disk image contains multiple slices, each with a full operating system implementation. If you use this disk image, you can easily pick whichever operating system you want to boot without changing media. Some of the included software: Operating Systems (CP/M 2.2, ZSDOS, NZ-COM, CP/M 3, ZPM3, Z3PLUS, QPM ) Support for other operating systems, p-System, FreeRTOS, and FUZIX. Programming Tools (Z80ASM, Turbo Pascal, Forth, Cowgol) C Compiler\u2019s including Aztec-C, and HI-TECH C Microsoft Basic Compiler, Microsoft Fortran, and Microsoft COBOL Some games such as Colossal Cave, Zork, etc Wordstar Word processing software Some of the provided software can be launched directly from the ROM firmware itself: System Monitor Operating Systems (CP/M 2.2, ZSDOS) ROM BASIC (Nascom BASIC and Tasty BASIC) ROM Forth A tool is provided that allows you to access a FAT-12/16/32 filesystem. The FAT filesystem may be coresident on the same disk media as RomWBW slices or on stand-alone media. This makes exchanging files with modern OSes such as Windows, MacOS, and Linux very easy.","title":"Included Software"},{"location":"#rom-distribution","text":"The RomWBW Repository ( https://github.com/wwarthen/RomWBW ) on GitHub is the official distribution location for all project source and documentation. RomWBW is distributed as both source code and pre-built ROM and disk images. The pre-built ROM images distributed with RomWBW are based on the default system configurations as determined by the hardware provider/designer. The pre-built ROM firmware images are generally suitable for most users. The fully-built distribution releases are available on the RomWBW Releases Page ( https://github.com/wwarthen/RomWBW/releases ) of the repository. On this page, you will normally see a Development Snapshot as well as recent stable releases. Unless you have a specific reason, I suggest you stick to the most recent stable release. The asset named RomWBW-vX.X.X-Package.zip includes all pre-built ROM and Disk images as well as full source code. The other assets contain only source code and do not have the pre-built ROM or disk images.","title":"ROM Distribution"},{"location":"#distribution-directory-layout","text":"The RomWBW distribution is a compressed zip archive file organized in a set of directories. Each of these directories has its own ReadMe.txt file describing the contents in detail. In summary, these directories are: Directory Description Binary The final output files of the build process are placed here. Most importantly, the ROM images with the file names ending in \u201c.rom\u201d and disk images ending in .img. Doc Contains various detailed documentation, both RomWBW specifically as well as the operating systems and applications. Source Contains the source code files used to build the software and ROM images. Tools Contains the programs that are used by the build process or that may be useful in setting up your system.","title":"Distribution Directory Layout"},{"location":"#building-from-source","text":"It is also very easy to modify and build custom ROM images that fully tailor the firmware to your specific preferences. All tools required to build custom ROM firmware under Windows are included \u2013 no need to install assemblers, etc. The firmware can also be built using Linux or MacOS after confirming a few standard tools have been installed.","title":"Building from Source"},{"location":"#installation-operation","text":"In general, installation of RomWBW on your platform is very simple. You just need to program your ROM with the correct ROM image from the RomWBW distribution. Subsequently, you can write disk images on your disk drives (IDE disk, CF Card, SD Card, etc.) which then provides even more functionality. Complete instructions for installation and operation of RomWBW are found in the RomWBW User Guide . It is also a good idea to review the Release Notes for helpful release-specific information.","title":"Installation & Operation"},{"location":"#documentation","text":"There are several documents that form the core of the RomWBW documentation: RomWBW User Guide is the main user guide for RomWBW, it covers the major topics of how to install, manage and use RomWBW, and includes additional guidance to the use of some of the operating systems supported by RomWBW RomWBW Hardware contains a description of all the hardware platforms, and devices supported by RomWBW. RomWBW Applications is a reference for the ROM-hosted and OS-hosted applications created or customized to enhance the operation of RomWBW. RomWBW Disk Catalog is a reference for the contents of the disk images provided with RomWBW, with a description of many of the files on each image RomWBW System Guide discusses much of the internal design and construction of RomWBW. It includes a reference for the RomWBW HBIOS API functions. An online HTML version of this documentation is hosted at https://wwarthen.github.io/RomWBW . Each of the operating systems and ROM applications included with RomWBW are sophisticated tools in their own right. It is not reasonable to fully document their usage. However, you will find complete manuals in PDF format in the Doc directory of the distribution. The intention of this documentation is to describe the operation of RomWBW and the ways in which it enhances the operation of the included applications and operating systems. Since RomWBW is purely a software product for many different platforms, the documentation does not cover hardware construction, configuration, or troubleshooting \u2013 please see your hardware provider for this information.","title":"Documentation"},{"location":"#support","text":"","title":"Support"},{"location":"#getting-assistance","text":"The best way to get assistance with RomWBW or any aspect of the RetroBrew Computers projects is via one of the community forums: RetroBrew Computers Forum RC2014 Google Group retro-comp Google Group Submission of issues and bugs are welcome at the RomWBW GitHub Repository . Also feel free to email Wayne Warthen at wwarthen@gmail.com . I am happy to provide support adapting RomWBW to new or modified systems","title":"Getting Assistance"},{"location":"#contributions","text":"All source code and distributions are maintained on GitHub. Contributions of all kinds to RomWBW are very welcome.","title":"Contributions"},{"location":"#acknowledgments","text":"I want to acknowledge that a great deal of the code and inspiration for RomWBW has been provided by or derived from the work of others in the RetroBrew Computers Community. I sincerely appreciate all of their contributions. The list below is probably missing many names \u2013 please let me know if I missed you! Andrew Lynch started it all when he created the N8VEM Z80 SBC which became the first platform RomWBW supported. Some of his original code can still be found in RomWBW. Dan Werner wrote much of the code from which RomWBW was originally derived and he has always been a great source of knowledge and advice. Douglas Goodall contributed code, time, testing, and advice in \u201cthe early days\u201d. He created an entire suite of application programs to enhance the use of RomWBW. Unfortunately, they have become unusable due to internal changes within RomWBW. As of RomWBW 2.6, these applications are no longer provided. Sergey Kiselev created several hardware platforms for RomWBW including the very popular Zeta. David Giles created support for the Z180 CSIO which is now included SD Card driver. Phil Summers contributed the Forth and BASIC adaptations in ROM, the AY-3-8910 sound driver, DMA support, and a long list of general code and documentation enhancements. Ed Brindley contributed some of the code that supports the RCBus platform. Spencer Owen created the RC2014 series of hobbyist kit computers which has exponentially increased RomWBW usage. Some of his kits include RomWBW. Stephen Cousins has likewise created a series of hobbyist kit computers at Small Computer Central and is distributing RomWBW with many of them. Alan Cox has contributed some driver code and has provided a great deal of advice. The CP/NET client files were developed by Douglas Miller. Phillip Stevens contributed support for FreeRTOS. Curt Mayer contributed the original Linux / MacOS build process. UNA BIOS and FDISK80 are the products of John Coffman. FLASH4 is a product of Will Sowerbutts. CLRDIR is a product of Max Scane. Tasty Basic is a product of Dimitri Theulings. Dean Netherton contributed multiple components: eZ80 CPU support Sound driver infrastructure SN76489 sound driver Native USB driver (keyboard, floppy, mass storage) The RomWBW Disk Catalog document was produced by Mykl Orders. Rob Prouse has created many of the supplemental disk images including Aztec C, HiTech C, SLR Z80ASM, Turbo Pascal, Microsoft BASIC Compiler, Microsoft Fortran Compiler, and a Games compendium. Martin R has provided substantial help reviewing and improving the User Guide and Applications documents. Mark Pruden has made a wide variety of contributions including: significant content in the Disk Catalog and User Guide creation of the Introduction and Hardware documents Z3PLUS operating system disk image Infocom text adventure game disk image COPYSL, and SLABEL utilities Display of bootable slices via \u201cS\u201d command during startup Optimisations of HBIOS and CBIOS to reduce overall code size a feature for RomWBW configuration by NVRAM the /B bulk mode of disk assignment to the ASSIGN utility Jacques Pelletier has contributed the DS1501 RTC driver code. Jose Collado has contributed enhancements to the TMS driver including compatibility with standard TMS register configuration. Kevin Boone has contributed a generic HBIOS date/time utility (WDATE). Matt Carroll has contributed a fix to XM.COM that corrects the port specification when doing a send. Dean Jenkins enhanced the build process to accommodate the Raspberry Pi 4. Tom Plano has contributed a new utility (HTALK) to allow talking directly to HBIOS COM ports. Lars Nelson has contributed several generic utilities such as a universal (OS agnostic) UNARC application. Dylan Hall added support for specifying a secondary console. Bill Shen has contributed boot loaders for several of his systems. Laszlo Szolnoki has contributed an EF9345 video display controller driver. Ladislau Szilagyi has contributed an enhanced version of CP/M Cowgol that leverages RomWBW memory banking. Les Bird has contributed support for the NABU w/ Option Board Rob Gowin created an online documentation site via MkDocs, and contributed a driver for the Xosera FPGA-based video controller. J\u00f6rg Linder has contributed disassembled and nicely commented source for ZSDOS2 and the BPBIOS utilities. Marshall Gates has contriubed sample program source files for all of the language disk images. Randy Merkel provided the ZSDOS Programmer\u2019s Manual as translated by Wayne Hortensius. Henk Berends added support for the MSX platform.","title":"Acknowledgments"},{"location":"#related-projects","text":"Outside of the hardware platforms adapted to RomWBW, there are a variety of projects that either target RomWBW specifically or provide a RomWBW-specific variation. These efforts are greatly appreciated and are listed below. Please contact the author if there are any other such projects that are not listed.","title":"Related Projects"},{"location":"#z88dk","text":"Z88DK is a software powerful development kit for Z80 computers supporting both C and assembly language. This kit now provides specific library support for RomWBW HBIOS. The Z88DK project is hosted at https://github.com/z88dk/z88dk .","title":"Z88DK"},{"location":"#paleo-editor","text":"Steve Garcia has created a Windows-hosted IDE that is tailored to development of RomWBW. The project can be found at https://github.com/alloidian/PaleoEditor .","title":"Paleo Editor"},{"location":"#z80-fig-forth","text":"Dimitri Theulings\u2019 implementation of fig-FORTH for the Z80 has a RomWBW-specific variant. The project is hosted at https://github.com/dimitrit/figforth .","title":"Z80 fig-FORTH"},{"location":"#assembly-language-programming-for-the-rc2014-zed","text":"Bruce Hall has written a very nice document that describes how to develop assembly language applications on RomWBW. It begins with the setup and configuration of a new RC2014 Zed system running RomWBW. It describes not only generic CP/M application development, but also RomWBW HBIOS programming and bare metal programming. The latest copy of this document is hosted at http://w8bh.net/Assembly for RC2014Z.pdf .","title":"Assembly Language Programming for the RC2014 Zed"},{"location":"#licensing","text":"","title":"Licensing"},{"location":"#license-terms","text":"RomWBW is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. RomWBW is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with RomWBW. If not, see https://www.gnu.org/licenses/ . Portions of RomWBW were created by, contributed by, or derived from the work of others. It is believed that these works are being used in accordance with the intentions and/or licensing of their creators. If anyone feels their work is being used outside of its intended licensing, please notify: Wayne Warthen wwarthen@gmail.com RomWBW is an aggregate work. It is composed of many individual, standalone programs that are distributed as a whole to function as a cohesive system. Each program may have its own licensing which may be different from other programs within the aggregate. In some cases, a single program (e.g., CP/M Operating System) is composed of multiple components with different licenses. It is believed that in all such cases the licenses are compatible with GPL version 3. RomWBW encourages code contributions from others. Contributors may assert their own copyright in their contributions by annotating the contributed source code appropriately. Contributors are further encouraged to submit their contributions via the RomWBW source code control system to ensure their contributions are clearly documented. All contributions to RomWBW are subject to this license.","title":"License Terms"},{"location":"Applications/","text":"RomWBW Applications Guide \\ Version 3.6 \\ MartinR \\& Phillip Summers ( ) \\ 25 Nov 2025 Summary RomWBW is supplied with a suite of software applications that enhance the use of the system. Some of these applications have been written entirely from scratch for RomWBW. Others are pre-existing software that has been customized for the RomWBW environment. This document serves as a reference for these RomWBW-specific applications. The primary usage documentation for RomWBW is the RomWBW User Guide . It is assumed that the reader is generally familiar with this document. RomWBW also includes many generic software applications that have not been modified for RomWBW (e.g., MSBASIC). These generic applications are not documented here. Please refer to the application specific documentation for these generic applications. The documentation for some of these generic applications is included in the Doc folder of the RomWBW distribution. The applications described in this document fall into two general categories. ROM Applications are software applications that are loaded from the the ROM memory of your RomWBW system. CP/M Applications are software applications that are loaded from disk using a previously loaded CP/M (or CP/M like) operating system using its command line. Note that some applications are available in both forms. For example, Microsoft BASIC is available as a ROM application and as an application that runs under CP/M. Only the ROM variant is documented here because the CP/M variant is not RomWBW-specific. You will see that two of the RomWBW operating systems are included here as ROM Applications. Although operating systems are normally loaded from disk, RomWBW does include a way to launch CP/M 2.2 and Z-System directly from ROM. Most RomWBW systems include a ROM disk. A running operating system can load applications from the ROM disk just like a floppy or hard disk. Applications loaded from the ROM disk by CP/M are considered to be CP/M applications, not ROM applications. Boot Menu The system start-up process is described in some detail in the RomWBW User Guide, and for the sake of completeness there is some overlap here. When a RomWBW system is started the user is presented with a sign-on message at the default console detailing the RomWBW version and build date. The system follows this with the list of hardware that it has discovered, a list of devices and the system units assigned to them. If autoboot is configured then the message (below) will count down and once 0 is reached the system will automatically boot with the configured options AutoBoot in 3 Seconds ( aborts, now)... Pressing esc - will bypass the auto boot process going immediately to the Boot prompt, or pressing enter - will proceed with autoboot immediately. Auto boot is configured using the W boot menu option. If autoboot is bypassed (or not configured) the user is asked to select a boot device with the prompt: Boot [H=Help]: At this point, the user may specify a unit, optionally with a slice, to boot from. Note that it is not possible to boot from from the serial (ASCI) or memory disk (MD) devices. Alternatively the user may select one of the built-in Boot Loader commands. A menu of which may be displayed by pressing the H or ? keys (for Help). Furthermore, a ROM application may also be started from this prompt. This start-up process is described in some detailed in the RomWBW User Guide, and there is some overlap here. Help After pressing H or ? at the boot prompt the user will be presented with the following list of available commands: Boot [H=Help]: H L - List ROM Applications D - Device Inventory S - Slice Inventory R - Reboot System W - RomWBW Configure I [] - Set Console Interface/Baud code V [] - View/Set HBIOS Diagnostic Verbosity N - Network Boot [.] - Boot Disk Unit/Slice The function performed by each command is described below: L: Lists the applications and operating systems that are built into the RomWBW ROM - e.g., low-level monitor utility, CP/M, or BASIC. D: Displays the list of system devices that was first displayed when the system was started. S: Displays the list of disk Slices that contain a label indicating that they may be bootable. See SLABEL (Slice Label) for more details about labels. R: Will restart the system. Note that this does not reset hardware devices in the same way that power-on or pressing the reset button would. W: Runs the SYSCONF (System Configuration) utility allowing RomWBW configuration stored in Non Volatile memory to be changed. I: Allows the user to select the interface connected to the console, and optionally the Baud rate. This could be used to allow the system to be operated from a second console. V: Enables the display of invalid RomWBW HBIOS API calls. This option is very unlikely to be used by a user and is used for development purposes. N: Boot into CP/M via an RCBus Wiznet MT011 network module if configured. Section 10 of the RomWBW User Guide provides complete instructions for setting up a CP/NET based network under RomWBW including network booting. And, finally, the system may be booted by specifying the unit number, and optional slice, separated by a period(\u2018.\u2019), of where the disk operating system software is located - eg 2, 4.1, 5.3 Alternatively, a RomWBW ROM application may be started by pressing the appropriate key from the applications menu, shown in the following section. List ROM Applications If the user presses the L key at the Boot Loader prompt then the system will display the list of ROM applications that are built into RomWBW. If a command letter is known, then it may be entered directly at the prompt rather than first displaying the menu. The ROM applications available from the boot prompt are: Boot [H=Help]: L ROM Applications: M: Monitor Z: Z-System C: CP/M 2.2 F: Forth B: BASIC T: Tasty BASIC P: Play a Game X: XModem Flash Updater U: User App Each of these will now be described in greater detail. ROM Applications Monitor The Monitor program is a low-level utility that can be used for testing and programming. It allows programs to be entered, memory to be examined and modified, and input/output devices to be read or written to. It\u2019s key advantage is that is available at boot up. Its key disadvantages are that code cannot be entered in assembly language and there is no ability to save to persistent storage (disks). The available memory area for programming is 0100h-EDFFh . The following areas are reserved: Memory Area Function 0000-00FFh Jump and restart (RST) vectors EE00-FDFFh Monitor FE00-FFFFh HBIOS proxy The monitor uses a prompt in the format of xx> where xx is the RomWBW bank id number. For example, the prompt may look like this and means that Bank Id 0x8E is currently mapped into the low 32K of processor memory. 8E> Please refer to Section 4 of the \\$doc_sys# for a description of the RomWBW Bank Id and how it relates to the physical bank of memory being mapped to the lower 32K of the processor. The method of assigning banks for specific RomWBW functions is also described. Commands can be entered at the command prompt. Automatic case conversion takes place on command entry and all numeric arguments are expected to be in hex format. The Monitor allows access to all memory locations but ROM and Flash memory cannot be written to. At startup, the Monitor will select the default \u201cUser\u201d bank. The S command is provided to allow selecting alternate banks. There now follows a more detailed guide to using the RomWBW Monitor program: Monitor Commands ? - Will display a summary of the available commands. Monitor Commands (all values in hex): B - Boot system D xxxx [yyyy] - Dump memory from xxxx to yyyy F xxxx yyyy zz - Fill memory from xxxx to yyyy with zz H - Halt system I xxxx - Input from port xxxx K - Keyboard echo L - Load Intel hex data M xxxx yyyy zzzz - Move memory block xxxx-yyyy to zzzz O xxxx yy - Output value yy to port xxxx P xxxx - Program RAM at address xxxx R xxxx [[yy] [zzzz]] - Run code at address xxxx Pass yy and zzzz to register A and BC S xx - Set bank to xx U - Set bank to previous bank T xxxx - X-modem transfer to memory location xxxx X - Exit monitor Cold Boot B - Performs a cold boot of the RomWBW system. A complete re-initialization of the system is performed and the system returns to the Boot Loader prompt. Dump Memory D xxxx [yyyy] - Dump memory from hex location xxxx to yyyy on the screen as lines of 16 hexadecimal bytes with their ASCII equivalents (if within a set range, else a \u2018.\u2019 is printed). If the end address is omitted then 256 bytes are displayed. A good tool to see where code is located, check for version id, obtain details for chip configurations and execution paths. Example: D 100 1FF 0100: 10 0B 01 5A 33 45 4E 56 01 00 00 2A 06 00 F9 11 ...Z3ENV...*..\u00f9. 0110: DE 38 37 ED 52 4D 44 0B 6B 62 13 36 00 ED B0 21 \u00de87\u00edRMD.kb.6.\u00ed\u00b0! 0120: 7D 32 E5 21 80 00 4E 23 06 00 09 36 00 21 81 00 }2\u00e5!..N#...6.!.. 0130: E5 CD 6C 1F C1 C1 E5 2A C9 8C E5 CD 45 05 E5 CD \u00e5\u00cdl.\u00c1\u00c1\u00e5*\u00c9.\u00e5\u00cdE.\u00e5\u00cd 0140: 59 1F C3 00 00 C3 AE 01 C3 51 04 C3 4C 02 C3 57 Y.\u00c3..\u00ee.\u00c3Q.\u00c3L.\u00c3W 0150: 02 C3 64 02 C3 75 02 C3 88 02 C3 B2 03 C3 0D 04 .\u00c3d.\u00c3u.\u00c3..\u00f2.\u00c3.. 0160: C3 19 04 C3 22 04 C3 2A 04 C3 35 04 C3 40 04 C3 \u00c3..\u00c3\".\u00c3*.\u00c35.\u00c3@.\u00c3 0170: 48 04 C3 50 04 C3 50 04 C3 50 04 C3 8F 02 C3 93 H.\u00c3P.\u00c3P.\u00c3P.\u00c3..\u00c3. 0180: 02 C3 94 02 C3 95 02 C3 85 04 C3 C7 04 C3 D1 01 .\u00c3..\u00c3..\u00c3..\u00c3\u00c7.\u00c3\u00d1. 0190: C3 48 02 C3 E7 04 C3 56 03 C3 D0 01 C3 D0 01 C3 \u00c3H.\u00c3\u00e7.\u00c3V.\u00c3\u00d0.\u00c3\u00d0.\u00c3 01A0: D0 01 C3 D0 01 C3 D0 01 C3 D0 01 01 02 01 CD 6B \u00d0.\u00c3\u00d0.\u00c3\u00d0.\u00c3\u00d0....\u00cdk 01B0: 04 54 68 69 73 20 66 75 6E 63 74 69 6F 6E 20 6E .This function n 01C0: 6F 74 20 73 75 70 70 6F 72 74 65 64 2E 0D 0A 00 ot supported.... 01D0: C9 3E FF 32 3C 00 3A 5D 00 FE 20 28 14 D6 30 32 \u00c9>\u00ff2<.:].\u00fe (.\u00d602 01E0: AB 01 32 AD 01 3A 5E 00 FE 20 28 05 D6 30 32 AC \u00ab.2\u00ad.:^.\u00fe (.\u00d602\u00ac 01F0: 01 C5 01 F0 F8 CF E5 26 00 0E 0A CD 39 02 7D 3C .\u00c5.\u00f0\u00f8\u00cf\u00e5&...\u00cd9.}< Fill Memory F xxxx yyyy zz - Fill memory from hex xxxx to yyyy with a single value of zz over the full range. The Dump command can be used to confirm that the fill completed as expected. A good way to zero out memory areas before writing machine data for debug purposes. Halt System H - Halt system. A Z80 HALT instruction is executed. The system remains in the halt state until the system is physically rebooted. Interrupts will not restart the system. On systems that support a HALT status LED, the LED will be illuminated. Input from Port I xxxx - Input data from port xxxx and display to the screen. This command is used to read values from hardware I/O ports and display the contents in hexadecimal. Keyboard Echo K - Echo any key-presses from the terminal. Press \u2018ESC\u2019 key to quit. This facility provides that any key stroke sent to the computer will be echoed back to the terminal. File downloads will be echoed as well while this facility is \u2018on\u2019. Load Hex L - Load a Intel Hex data via the terminal program. The load address is defined in the hex file of the assembled code. The terminal emulator program should be configured to give a delay at the end of each line to allow the monitor enough time to parse the line and move the data to memory. Keep in mind that this will be transient unless the system supports battery backed memory. Saving to memory drive is not supported. Move Memory M xxxx yyyy zzzz - Move hex memory block xxxx to yyyy to memory starting at hex location zzzz. Care should be taken to insure that there is enough memory at the destination so that code does not get over-written or memory wrapped around. Output to Port O xxxx yy - Output data byte xx to port xxxx. This command is used to send hexadecimal values to hardware I/O ports to verify their operation and is the companion to the I operation. Use clip leaded LEDs to confirm the data written. Program Memory P xxxx - Program memory location xxxx. This routine will allow you to program a hexadecimal value into memory starting at location xxxx. Press \u2018Enter\u2019 on a blank line to return to the Monitor prompt. The limitation around programming memory is that it must be entered in hexadecimal. An alternative is to use the L command to load a program that has been assembled to a hex file on the remote computer. An excellent online resource for looking up opcodes for entry can be found here: https://clrhome.org/table . Run Program R xxxx [[yy] [zzzz]] - Run program at location xxxx. If optional arguments yy and zzzz are entered they are loaded into the A and BC register respectively. The return address of the Monitor is saved on the stack so the program can return to the monitor. On return to the monitor, the contents of the A, HL, DE and BC registers are displayed. Set Bank S xx - Set the physical memory bank to the RomWBW Bank Id indicated by xx. Memory addresses 0x0000-0x7FFF (i.e. bottom 32k) are affected. Because the interrupt vectors are stored in the bottom page of this range, this function is disabled when interrupt mode 1 is being used (IM1). Interrupt mode 2 is not affected as the associated jump vectors are stored in high memory. Changing the bank also impacts the restart vectors (RST), so executing code that calls the HBIOS using the RST 08 assembly code will not work. The monitor stack resides in high memory and is not affected but any code that changes the stack to low memory will be affected. The U command may be used to undo the change and return the selected memory bank back to the previously selected one. Section 4 of the RomWBW System Guide provides detail on how Bank Ids map to the physical memory of the system and also how specific banks are utilized by RomWBW. Undo Bank U - Change the bank in memory back to the previously selected bank. This command should be used in conjunction with the S command. X-Modem Transfer T xxxx - Receive an X-modem file transfer and load it into memory starting at location xxxx. 128 byte blocks and checksum mode is the only supported protocol. Exit Monitor X - Exit the monitor program back to the main boot menu. CP/M 2.2 This option will boot the CP/M 2.2 disk operating system from an image contained within the ROM. Please refer to the CPM User Manual in the Doc/CPM folder of the distribution for CP/M usage. There are also many online resources. During the build process the system will create a ROM disk containing a number of curated CP/M applications, and also a RAM drive. The capacity of each will depend upon the size of the ROM and RAM available to the system. A more complete set of utilities are provided within the disk image files provided as part of RomWBW. A number of the applications provided are generic to CP/M, while others rely on particular hardware or aspects of RomWBW itself. Those that are written specific to RomWBW include: ASSIGN, CPUSPD, FDU, FORMAT, FLASH, FDISK80, MODE, REBOOT, RTC, SYSCOPY, TALK, TIMER, XM, and COPYSL. The CP/M utilities supplied with RomWBW warrant more detailed descriptions, and so are described in some detail in their own section of this user guide. In summary they provide the initial capability to manage and update your RomWBW system, to create other bootable media (hardware dependent) and to write/debug code using assembler and BASIC. Z-System Z-System is a complete alternative, but entirely compatible, disk operating system to CP/M. Z-System is comprised of ZSDOS 1.1 which is a replacement for CP/M\u2019s Basic Disk Operating System (BDOS), and ZCPR which is a replacement for the Console Command Processor (CCP). Either or both may be used, although using both together will allow ZCPR to make use of specific ZSDOS features. Documentation for Z-System may be found in the Doc/CPM folder of the RomWBW distribution and the reader is referred to those. BASIC For those who are not familiar with BASIC, it stands for Beginners All Purpose Symbolic Instruction Code. RomWBW contains two versions of ROM BASIC, a full implementation and a \u201ctiny\u201d BASIC. The full implementation is a version of Microsoft BASIC from the NASCOM Computer. A comprehensive instruction manual is available in the Doc/Contrib directory. RomWBW specific features Sound Graphics Terminal Support RomWBW unsupported features Cassette loading Cassette saving TastyBASIC TastyBASIC offers a minimal implementation of BASIC that is only 2304 bytes in size. It originates from Li-Chen Wang\u2019s Palo Alto Tiny BASIC from around 1976. It\u2019s small size suited the tiny memory capacities of the time. This implementation is by Dimitri Theulings and his original source can be found at https://github.com/dimitrit/tastybasic . Features / Limitations Integer arithmetic, numbers -32767 to 32767 Single letter variables A-Z 1-dimensional array support Strings are not supported Direct Commands LIST , RUN , NEW , CLEAR , BYE Statements LET , IF , GOTO , GOSUB RETURN , REM , FOR TO NEXT STEP , INPUT , PRINT , POKE , END Functions PEEK , RND , ABS , USR , SIZE Operators >= , # , > , = , <= , < Operator precedence is supported. Type BYE to return to the boot menu. FORTH CamelForth is the version of Forth included as part of the boot ROM in RomWBW. It has been converted from the Z80 CP/M version published at https://www.camelforth.com/page.php?5 . The author is Brad Rodriguez who is a prolific Forth enthusiast, whose work can be found here: https://www.bradrodriguez.com/papers . For those are who are not familiar with Forth, I recommend the wikipedia article https://en.wikipedia.org/wiki/Forth_(programming_language) and the Forth Interest Group website https://www.forth.org/ . Important things to know Forth is case sensitive. To exit back to the boot loader type bye To get a list of available words type WORDS To reset Forth to its initial state type COLD Most of the code you find on the internet will not run unless modified or additional Forth words are added to the dictionary. This implementation does not support loading or saving of programs. All programs need to be typed in. Additionally, screen editing and code blocks are not supported. A CP/M version is not provided with RomWBW, this is only a ROM application. If you need to run it under CP/M you would need to download it from the camelforth web site, the link is above. Structure of Forth source files File Description camel80.azm Code Primitives camel80d.azm CPU Dependencies camel80h.azm High Level words camel80r.azm RomWBW additions glosshi.txt Glossary of high level words glosslo.txt Glossary of low level words glossr.txt Glossary of RomWBW additions RomWBW Additions Extensions and changes to this implementation compared to the original distribution are: The source code has been converted from Z80mr assembler to Hector Peraza\u2019s zsm. An additional file camel80r.azm has been added for including additional words to the dictionary at build time. However, as currently configured there is very little space allocated for addition words. Exceeding the allocated ROM space will generate an error message when building. James Bowman\u2019s double precision words have been added from his RC2014 version: https://github.com/jamesbowman/camelforth-z80 . Word Syntax Description D+ d1 d2 \u2013 d1+d2 Add double numbers 2>R d \u2013 2 to R 2R> d \u2013 fetch 2 from R M*/ d1 n2 u3 \u2013 d=(d1*n2)/u3 double precision mult. div SVC hl de bc n \u2013 hl de bc af Execute a RomWBW function P! n p \u2013 Write a byte to a I/O port P@ p \u2013 n Read a byte from and I/O port Play a Game (2048) 2048 is a puzzle game that can be both mindless and challenging. It appears deceptively simple but failure can creep up on you suddenly. It requires an ANSI/VT-100 compatible colour terminal to play. 2048 is like a sliding puzzle game except the puzzle tiles are numbers instead of pictures. Instead of moving a single tile all tiles are moved simultaneously in the same direction. Where two tiles of the same number collide, they are reduced to one tile with the combined value. After every move a new tile is added with a starting value of 2. The goal is to create a tile of 2048 before all tile locations are occupied. Reaching the highest points score, which is the sum of all the tiles is a secondary goal. The game will automatically end when there are no more possible moves. Play consists of entering a direction to move. Directions can be entered using any of three different keyboard direction sets. Direction | Keys ----------|---------- Up | w ^E 8 Down | s ^X 2 Left | a ^S 4 Right | d ^D 6 The puzzle board is a 4x4 grid. At start, the grid will be populated with two 2 tiles. An example game sequence is shown below with new tiles to the game shown in brackets. Start Move 1 - Up Move 2 - Left Move 3 - Left +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ | | | |(2)| | | | | 4 | | 4 | | | | | 4 | | | | +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ | | | | | | | | | | | | | |(4)| | 4 | | | | +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ | | | |(2)| | | | | | | | | | | | | | | | +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ | | | | | | | |(2)| | | 2 | | | | | 2 | |(2)| | +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ Move 4 - Left Move 5 - Up Move 6 - Right Move 7 - Up +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ | 4 | | | | | 8 | | | 4 | | | | 8 | 4 | | | | 8 | 8 | +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ | 4 | | |(4)| | 4 | | | | | | | | 4 | | | | | 2 | +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ | | | | | | | | | | | | | | | | | | | | +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ | 4 | | | | |(2)| | | | |(2)| | | 2 | |(2)| | | | +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ +---+---+---+---+ This is how I lost this game: +---+---+---+---+ | 4 | 2 | 16| 4 | +---+---+---+---+ | 32| 64| 8 | 2 | +---+---+---+---+ | 4 | 8 |128| 32| +---+---+---+---+ |(2)| 16| 8 | 4 | +---+---+---+---+ Press Q at any time to bring up the option to Quit or Restart the game. Xmodem Flash Updater The RomWBW Xmodem flash updater provides the capability to update RomWBW from the boot loader using an x-modem file transfer. It offers similar capabilities to Will Sowerbutts FLASH4 utility except that the flashing process occurs during the file transfer. These are the key differences between the two methods are: Xmodem Flash Updater FLASH.COM (aka FLASH4) Available from the boot loader Well proven and tested Xmodem transfer is integrated Wider range of supported chips and hardware Integrated checksum utilities Wider range of supported platforms Capability to copy a ROM image Only reprograms sectors that have changed More convenient one step process Ability save and verify ROM images No intermediate storage required Progress display while flashing . Displays chip identification information . Faster file transfer The major disadvantages of the Updater is that it is new and relatively untested. There is the risk that a failed transfer will result in a partially flashed and unbootable ROM. There are some limitations on serial transfer speeds. The updater utility was initially intended to support the Retrobrew SBC-V2-005 platform using Atmel 39SF040 flash chips but has now been extended to be more generic in operation. Supported flash chips are 39SF040, 29F040, AT49F040, AT29C040, M29F040 , MX29F040, A29010B, A29040B The Atmel 39SF040 chip is recommended as it can erase and write 4Kb sectors. Other chips require the whole chip to be erased. Usage In most cases, completing a ROM update is a simple as: Booting to the boot loader prompt Selecting option X - Xmodem Flash Updater Selecting option U - Update Initiating an X-modem transfer of your ROM image on your console device Selecting option R - Reboot If your console device is not able to transfer a ROM image i.e. your console is a VDU then you will have to use the console options to identify which character-input/output device is to be used as the serial device for transfer. When your console is the serial device used for the transfer, no progress information is displayed as this would disrupt the x-modem file transfer. If you use an alternate character-input/output device as the serial device for the transfer then progress information will be displayed on the console device. Due to different platform processor speeds, serial speeds and flow control capabilities the default console or serial device speed may need to be reduced for a successful transfer and flash to occur. The Set Console Interface/Baud code option at the Boot Loader can be used to change the speed if required. Additionally, the Updater has options to set to and revert from a recommended speed. See the RomWBW Applications guide for additional information on performing upgrades. Console Options Option ( C ) - Set Console Device Option ( S ) - Set Serial Device By default the updater assumes that the current console is a serial device and that the ROM file to be flashed will also be transferred across this device, so the Console and Serial device are both the same. Either device can be can be change to another character-input/output device but the updater will always expect to receive the x-modem transfer on the Serial Device The advantage of transferring on a different device to the console is that progress information can be displayed during the transfer. Option ( > ) - Set Recommended Baud Rate Option ( \\< ) - Revert to Original Baud Rate Programming options Option ( U ) - Begin Update This will begin the update process. The updater will expect to start receiving an x-modem file on the serial device unit. X-modem sends the file in packets of 128 bytes. The updater will cache 32 packets which is 1 flash sector and then write that sector to the flash device. If using separate console, bank and sector progress information will be shown BANK 00 s00 s01 s02 s03 s04 s05 s06 s06 s07 BANK 01 s00 s01 s02 s03 s04 s05 s06 s06 s07 BANK 02 s00 s01 s02 s03 s04 s05 s06 s06 s07 etc The x-modem file transfer protocol does not provide any filename or size information for the transfer so the updater does not perform any checks on the file suitability. The updater expects the file size to be a multiple of 4 kilobytes and will write all data received to the flash device. A system update file (128kb .img) or complete ROM can be received and written (512kb or 1024kb .rom) If the update fails it is recommended that you retry before rebooting or exiting to the Boot loader as your machine may not be bootable. Option ( D ) - Duplicate flash #1 to flash #2 This option will make a copy of flash #1 onto flash #2. The purpose of this is to enable making a backup copy of the current flash. Intended for systems using 2x512Kb Flash devices. Option ( V ) - Toggle Write Verify By default each flash sector will be verified after being written. Slight performance improvements can be gained if turned off and could be used if you are experiencing reliable transfers and flashing. Exit options Option ( R ) - Reboot Execute a cold reboot. This should be done after a successful update. If you perform a cold reboot after a failed update then it is likely that your system will be unusable and removing and reprogramming the flash will be required. Option ( Q ) - Quit to boot loader. The SBC Boot Loader is reloaded from ROM and executed. After a successful update a Reboot should be performed. However, in the case of a failed update this option could be used to attempt to load CP/M and perform the normal x-modem / flash process to recover. CRC Utility options Option ( 1 ) and ( 2 ) - Calculate and display CRC32 of 1st or 2nd 512k ROM. Option ( 3 ) - Calculate and display CRC32 of a 1024k (2x512Kb) ROM. Can be used to verify if a ROM image has been transferred and flashed correctly. Refer to the Tera Term section below for details on configuring the automatic display of a file\u2019s CRC after it has been transferred. In Windows, right clicking on a file should also give you a context menu option CRC SHA which will allow you to select a CRC32 calculation to be done on the selected file. Tera Term macro configuration Macros are a useful tool for automatic common tasks. There are a number of instances where using macros to facilitate the update process could be worthwhile if you are: Following the RomWBW development builds. Doing lots of configuration changes. Doing development on RomWBW drivers Macros can be used to automate sending ROM updates or images and for my own purpose I have set up a separate macro for transferring each of the standard build ROM, my own custom configuration ROM and update ROM. An example macro file to send an *.upd file, using checksum mode and display the crc32 value of the transmitted file: Xmodem send, checksum, display crc32 xmodemsend '\\\\desktop\\users\\phillip\\documents\\github\\romwbw\\binary\\sbc_std_cust.upd' 1 crc32file crc '\\\\desktop\\users\\phillip\\documents\\github\\romwbw\\binary\\sbc_std_cust.rom' sprintf '0x%08x' crc messagebox inputstr 'crc32' Serial speed guidelines As identified in the introduction, there are limitations on serial speed depending on processor speed and flow control settings. Listed below are some of the results identified during testing. Configuration Processor Speed Maximum Serial Speed UART no flow control 2MHz 9600 UART no flow control 4MHz 19200 UART no flow control 5MHz 19200 UART no flow control 8MHz 38400 UART no flow control 10MHz 38400 USB-fifo 2MHz+ n/a ASCI no flow control 18.432MHz 9600 ASCI with flow control 18.432MHz 38400 The Set Recommend Baud Rate option in the Updater menu follows the following guidelines. Processor Speed Baud Rate 1MHz 4800 2-3MHz 9600 4-7MHz 19200 8-20MHz 38400 These can be customized in the updater.asm source code in the CLKTBL table if desired. Feedback to the RomWBW developers on these guidelines would be appreciated. Notes All testing was done with Tera Term x-modem, Forcing checksum mode using macros was found to give the most reliable transfer. Partial writes can be completed with 39SF040 chips. Other chips require entire flash to be erased before being written. An SBC V2-005 MegaFlash or Z80 MBC required for 1mb flash support. The Updater assumes both chips are same type Failure handling has not been tested. Timing broadly calibrated on a Z80 SBC-v2 Unabios not supported User Application RomWBW provides the facility for a user to build, include and execute their own custom application directly from the applications menu at boot-up. All that\u2019s needed is for the user to create their custom code ready for inclusion, recognising that there are certain constraints in doing this. In order to build properly, the build process requires that the file usrrom.asm be found in the /Source/HBIOS folder of the RomWBW tree. This source file needs to assemble using TASM and it must start at (ORG) address 00100H as the RomWBW HBIOS reserves locations 00000H to 000FFH for internal use. Further, the user application must assemble to a maximum of USR-SIZ bytes. During execution, the user application may make use of HBIOS calls as necessary, and at exit it should return to the RomWBW boot loader using the HBIOS warm reset. Note that no disk operating system (eg CP/M) functions will be available as no disk operating system will have been loaded. There is a sample usrrom.asm supplied in Source/HBIOS and it is recommended that, at least initially, users create their own application based on this as a template because it already creates the necessary variables, starts at (ORG) 00100H, and ensures that the assembled file is padded to create a file USR-SIZ in length. Equally, should the the user\u2019s application prove too large for the space available then assembly will be terminated with an error. Users should not remove this check from the templated code. If required, the user application may make use of the Z80 interrupt system but if the user application wishes to rely on HBIOS functionality then it must adhere to the HBIOS framework for managing interupts. Alternatively, if the user application has no need for the HBIOS then it may use its own custom code for handling interrupts. In that case, a hard reset, rather than an HBIOS warm start, would be necessary to return control to RomWBW. CP/M Applications - ROM-Based & Disk-Based There now follows a more detailed guide to using the small suite of custom applications included with RomWBW. In general, these applications are operating system agnostic \u2013 they run under any of the included operating systems. However, they all require RomWBW \u2013 they are not generic CP/M applications. Most of the applications are custom written for RomWBW. However, some are standard CP/M applications that have been adapted to run under RomWBW (e.g. XM/XModem). The applications are generally matched to the version of RomWBW they are distributed with. So, if you upgrade the version of RomWBW in your system ROM, you will want to copy the corresponding applications to any storage devices you are using. Most of the applications are included on the RomWBW ROM disk, so they are easy to access. The applications are also included with all of the operating system disk images provided with RomWBW. So, a simple way to ensure you have matching applications is to write the disk images onto your disk media when upgrading your ROM. Of course, this will destroy any existing data on your disk media, so don\u2019t do this if you are saving any data on the media. Most of the applications are included as source code in the RomWBW distribution and are built during the normal build process. The source code is found in the Source/Apps directory of the distribution. The binary executable applications are found in the Binary/Apps directory. The table below clarifies where each of the applications may be found. It is not an exhaustive list, with further applications existing on both the ROM-based and disk-based versions of CP/M. All of the Applications included within RomWBW may be found within the Binary/Apps directory. Application ROM Disk Boot Disks ASSIGN Yes Yes BBCBASIC No Yes CLRDIR Yes Yes COPYSL No Yes CPUSPD Yes Yes FAT No Yes FDISK80 Yes Yes FDU Yes Yes FLASH Yes Yes FORMAT Yes Yes HTALK Yes Yes MODE Yes Yes REBOOT Yes Yes RTC Yes Yes SURVEY Yes Yes SYSCOPY Yes Yes TALK Yes Yes TBASIC No Yes TIMER Yes Yes TUNE No Yes VGMPLAY No Yes WDATE No Yes XM Yes Yes ZMD No Yes ZMP No Yes All of the CP/M applications may be found in the RomWBW Binary/Apps directory and a user may copy those they need to their own customized disk/slice. Independently of whether the CP/M system was started from ROM or a boot disk, such as a floppy disk or a slice on a CF or uSD memory card, applications may be located on and executed from either the ROM-disk itself or from other media. There are multiple disk images available for CP/M (eg floppy, legacy hard-disk and new hard-disk formats) and they all contain essentially the same set of applications. There are particular advantages for each method of booting into CP/M. ROM-based CP/M: A clean and reliable copy of CP/M with no possibility of corruption No additional hardware required Fast to boot Rolled forward with new releases of RomWBW Disk-based CP/M: Greater capacity allows for a larger number of applications Allows for user-customisation of applications available Allows individual disks to be tailored to a particular purpose, eg word processor For systems starting CP/M from a disk created from an image file, there are a small number of additional applications stored in the USER 2 area of the disk. These applications do not form part of CP/M, but rather are small utilities used for test purposes during development work. They may, or may not, function correctly with any given hardware or software configuration. Documentation for these utilities is very limited, though the source files may be found in the /Source folder. Note that these utiltites are not available when starting CP/M from the ROM image or from a floppy disk. A number of the CP/M applications available are described in more detail in the following sections, each with an indication as to whether that application may be found on the ROM-disk, a boot-disk, or both. ASSIGN ASSIGN ROM-based Yes Disk-based Yes RomWBW includes a flexible mechanism for associating the operating system drive letters (A: - P:) to the physical devices in the system. Drive letter assignments can be changed on a running operating system without rebooting. The ASSIGN command facilitates this by allowing you to display, assign, reassign, or remove the drive letter assignments. Syntax ASSIGN /? ASSIGN /L ASSIGN = ASSIGN ASSIGN [ ],... ASSIGN =[ :[ ]],... ASSIGN = ,... ASSIGN /B='*'