diff --git a/Binary/ReadMe.txt b/Binary/ReadMe.txt index d25fa002..be0294ce 100644 --- a/Binary/ReadMe.txt +++ b/Binary/ReadMe.txt @@ -6,37 +6,37 @@ *** *** *********************************************************************** -This directory ("Binary") is part of the RomWBW System Software -distribution archive. It contains the completed binary outputs of -the build process. As described below, these files are used to +This directory ("Binary") is part of the RomWBW System Software +distribution archive. It contains the completed binary outputs of +the build process. As described below, these files are used to assemble a working RetroBrew Computers system. -The files in this directory are created by the build process that is -documented in the ReadMe.txt file in the Source directory. When -released the directory is populated with the default output files. -However, the output of custom builds will be placed in this directory +The files in this directory are created by the build process that is +documented in the ReadMe.txt file in the Source directory. When +released the directory is populated with the default output files. +However, the output of custom builds will be placed in this directory as well. -If you only see a few files in this directory, then you downloaded -just the source from GitHub. To retrieve the full release download -package, go to https://github.com/wwarthen/RomWBW. On this page, -look for the text "XX releases" where XX is a number. Click on this -text to go to the releases page. On this page, you will see the -latest releases listed. For each release, you will see a package -file called something like "RomWBW-2.9.0-Package.zip". Click on the +If you only see a few files in this directory, then you downloaded +just the source from GitHub. To retrieve the full release download +package, go to https://github.com/wwarthen/RomWBW. On this page, +look for the text "XX releases" where XX is a number. Click on this +text to go to the releases page. On this page, you will see the +latest releases listed. For each release, you will see a package +file called something like "RomWBW-2.9.0-Package.zip". Click on the package file for the release you want to download. ROM Firmware Images (_.rom) ------------------------------------- -The files with a ".rom" extension are binary images ready to program -into an appropriate PROM. These files are named with the format -_.rom. refers to the primary platform such as Zeta, -N8, Mark IV, etc. refers to the specific configuration. In -general, there will be a standard configuration ("std") for each -platform. So, for example, the file called MK4_std.rom is a ROM -image for the Mark IV with the standard configuration. If a custom -configuration called "custom" is created and built, a new file called +The files with a ".rom" extension are binary images ready to program +into an appropriate PROM. These files are named with the format +_.rom. refers to the primary platform such as Zeta, +N8, Mark IV, etc. refers to the specific configuration. In +general, there will be a standard configuration ("std") for each +platform. So, for example, the file called MK4_std.rom is a ROM +image for the Mark IV with the standard configuration. If a custom +configuration called "custom" is created and built, a new file called MK4_custom.rom will be added to this directory. Documentation of the pre-built ROM Images is contained in @@ -54,52 +54,52 @@ contents. Refer to the RomWBW User Guide for more information. ROM Executable Images (_.com) --------------------------------------- -When a ROM image (".rom") is created, an executable version of the -ROM is also created. These files have the same naming convention as -the ROM Image files, but have the extension ".com". These files can +When a ROM image (".rom") is created, an executable version of the +ROM is also created. These files have the same naming convention as +the ROM Image files, but have the extension ".com". These files can be copied to a working system and run like a normal CP/M application. -When run on the target system, they install in RAM just like they had +When run on the target system, they install in RAM just like they had been loaded from ROM. This allows a new ROM build to be tested without reprogramming the actual ROM. -WARNING: In a few cases the .com file is too big to load. If you get -a message like "Full" or "BAD LOAD" when trying to load one of the -.com files, it is too big. In these cases, you will not be able to +WARNING: In a few cases the .com file is too big to load. If you get +a message like "Full" or "BAD LOAD" when trying to load one of the +.com files, it is too big. In these cases, you will not be able to test the ROM prior to programming it. VDU ROM Image (vdu.rom) ----------------------- -The VDU video board requires a dedicated onboard ROM containing the -font data. The "vdu.rom" file contains the binary data to program +The VDU video board requires a dedicated onboard ROM containing the +font data. The "vdu.rom" file contains the binary data to program onto that chip. -Disk Images (fd_*.img, hd_*.img, psys.img) ------------------------------------------- +Disk Images (fd_*.img, hd_*.img) +-------------------------------- -RomWBW includes a mechanism for generating floppy disk and hard disk -binary images that are ready to copy directly to a floppy, hard disk, -CF Card, or SD Card which will then be ready for use in any +RomWBW includes a mechanism for generating floppy disk and hard disk +binary images that are ready to copy directly to a floppy, hard disk, +CF Card, or SD Card which will then be ready for use in any RomWBW-based system. -Essentially, these files contain prepared floppy and hard disk images -with a large set of programs and related files. By copying the -contents of these files to appropriate media as described below, you +Essentially, these files contain prepared floppy and hard disk images +with a large set of programs and related files. By copying the +contents of these files to appropriate media as described below, you can quickly create ready-to-use media. Win32DiskImager or RawWriteWin can be used to copy images directly to media. These programs are included in the RomWBW Tools directory. -The fd_*.img files are floppy disk images. They are sized for 1.44MB -floppy media and can be copied to actual floppy disks using -RawWriteWin (as long as you have access to a floppy drive on your -Windows computer). The resulting floppy disks will be usable on any +The fd_*.img files are floppy disk images. They are sized for 1.44MB +floppy media and can be copied to actual floppy disks using +RawWriteWin (as long as you have access to a floppy drive on your +Windows computer). The resulting floppy disks will be usable on any RomWBW-based system with floppy drive(s). -Likewise, the hd512_*.img and hd1k_*.img files are hard disk images. -Each file is intended to be copied to the start of any type of hard -disk media (typically a CF Card or SD Card). The resulting media will -be usable on any RomWBW-based system that accepts the corresponding +Likewise, the hd512_*.img and hd1k_*.img files are hard disk images. +Each file is intended to be copied to the start of any type of hard +disk media (typically a CF Card or SD Card). The resulting media will +be usable on any RomWBW-based system that accepts the corresponding media type. NOTE: The hd512_*.img files are equivalent to the hd_*.img @@ -109,34 +109,58 @@ maximum number of CP/M directory entries from 512 to 1024. Refer to the ReadMe.txt in the Source/Images directory for details. -Documentation of the pre-built disk images is contained in the +Documentation of the pre-built disk images is contained in the "RomWBW User Guide" found in the Doc directory. The contents of the disk images is contained in the "RomWBW Disk Catalog", but it is significantly out-of-date. -The contents of the floppy/hard disk images are created by -the BuildImages.cmd script in the Source directory. Additional -information on how to generate custom disk images is found in the +The contents of the floppy/hard disk images are created by +the BuildImages.cmd script in the Source directory. Additional +information on how to generate custom disk images is found in the Source\Images ReadMe.txt file. -The psys.img file contains a full implementation of the UCSD p-System -for the Z80 running under RomWBW. This image file must be placed on -disk media by itself (not appended or concatenated with hd*.img files. -Refer to the Source/pSys/ReadMe.txt file for more information on the +Disk Images (hd512_combo.img, hd1k_combo.img, *_std_hd1k_combo.img) +------------------------------------------------------------------- + +The hd512_combo.img and hd1k_combo.img file are the primary combo +disk image files suitable for most platforms. + +The *_std_hd1k_combo.img files are platform specific combo files +typically used in romless platforms, they also contain RomWBW binary code +that is loaded at boot time into RAM + +Disk Images (hd1k_prefix.dat, *_std_hd1k_prefix.dat) +---------------------------------------------------- + +The hd1k_prefix.dat file is part of the combo disk images and is +applied to hd1k image files as a prefix, it contains the standard +partion table. + +The *_std_hd1k_prefix.dat files are platform specific prefixes +typically used in romless platforms, they also contain RomWBW binary code +that is loaded at boot time into RAM + +Disk Images (psys.img) +---------------------- + +The psys.img file contains a full implementation of the UCSD p-System +for the Z80 running under RomWBW. This image file must be placed on +disk media by itself (not appended or concatenated with hd*.img files. +Refer to the Source/pSys/ReadMe.txt file for more information on the p-System implementation. Propeller ROM Images (*.eeprom) ------------------------------- -The files with and extension of ".eeprom" contain the binary images -to be programmed into the Propeller-based boards. The list below +The files with and extension of ".eeprom" contain the binary images +to be programmed into the Propeller-based boards. The list below indicates which file targets each of the Propeller board variants: ParPortProp ParPortProp.eeprom PropIO V1 PropIO.eeprom PropIO V2 PropIO2.eeprom -Refer to the board documentation of the boards for more information +Refer to the board documentation of the boards for more information on how to program the EEPROMs on these boards. Apps Directory @@ -144,4 +168,4 @@ Apps Directory The Apps subdirectory contains the executable application files that are specific to RomWBW. The source for these applications is found -in the Source\Apps directory of the distribution. \ No newline at end of file +in the Source\Apps directory of the distribution. diff --git a/Doc/RomWBW Applications.pdf b/Doc/RomWBW Applications.pdf index 069e4e6d..06dadd70 100644 Binary files a/Doc/RomWBW Applications.pdf and b/Doc/RomWBW Applications.pdf differ diff --git a/Doc/RomWBW Disk Catalog.pdf b/Doc/RomWBW Disk Catalog.pdf index 83c296a7..a1075823 100644 Binary files a/Doc/RomWBW Disk Catalog.pdf and b/Doc/RomWBW Disk Catalog.pdf differ diff --git a/Doc/RomWBW Errata.pdf b/Doc/RomWBW Errata.pdf index 7023a680..9e9d71d9 100644 Binary files a/Doc/RomWBW Errata.pdf and b/Doc/RomWBW Errata.pdf differ diff --git a/Doc/RomWBW System Guide.pdf b/Doc/RomWBW System Guide.pdf index 74f2d8f7..bc1c1a4a 100644 Binary files a/Doc/RomWBW System Guide.pdf and b/Doc/RomWBW System Guide.pdf differ diff --git a/Doc/RomWBW User Guide.pdf b/Doc/RomWBW User Guide.pdf index ddac18b4..ddc26694 100644 Binary files a/Doc/RomWBW User Guide.pdf and b/Doc/RomWBW User Guide.pdf differ diff --git a/ReadMe.md b/ReadMe.md index 23705247..2e22c320 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -1,293 +1,293 @@ - - -**RomWBW ReadMe** \ -Version 3.5 \ -Wayne Warthen ([wwarthen@gmail.com](mailto:wwarthen@gmail.com)) \ -05 Sep 2024 - -# Overview - -RomWBW software provides a complete, commercial quality implementation -of CP/M (and workalike) 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 the -\[Installation\] section. - -General features 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 -- Keyboard (PS/2) drivers via VT8242 or PPI interfaces -- Real time clock drivers including DS1302, BQ4845 -- OSes: CP/M 2.2, ZSDOS, CP/M 3, NZ-COM, ZPM3, QPM, p-System, and - FreeRTOS -- Built-in VT-100 terminal emulation support - -RomWBW is distributed as both source code and pre-built ROM and disk -images. 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 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 accessible storage on a single device. - -The pre-built ROM firmware images are generally suitable for most users. -However, 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 – 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. - -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 “combo” 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. - -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. - -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. - -# Acquiring RomWBW - -The [RomWBW Repository](https://github.com/wwarthen/RomWBW) -() on GitHub is the official -distribution location for all project source and documentation. 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. Expand the “Assets” drop-down -for the release you want to download, then select the asset named -RomWBW-vX.X.X-Package.zip. The Package asset 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. - -All source code and distributions are maintained on GitHub. Code -contributions are very welcome. - -# 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](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20User%20Guide.pdf). - -## Documentation - -Documentation for RomWBW includes: - -- [RomWBW User - Guide](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20User%20Guide.pdf) -- [RomWBW System - Guide](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20System%20Guide.pdf) -- [RomWBW - Applications](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20Applications.pdf) -- [RomWBW - Errata](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20Errata.pdf) - -# 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 – 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 “the - early days”. 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 the sound driver interface and the SN76489 - sound driver. - -- 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 also contributed a great deal of content to the User - Guide. - -- 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 - -Contributions of all kinds to RomWBW are very welcome. - -# Licensing - -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 . - -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 -> - -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. - -# 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](https://www.retrobrewcomputers.org/forum/) -- [RC2014 Google - Group](https://groups.google.com/forum/#!forum/rc2014-z80) -- [retro-comp Google - Group](https://groups.google.com/forum/#!forum/retro-comp) - -Submission of issues and bugs are welcome at the [RomWBW GitHub -Repository](https://github.com/wwarthen/RomWBW). - -Also feel free to email Wayne Warthen at . + + +**RomWBW ReadMe** \ +Version 3.5 \ +Wayne Warthen ([wwarthen@gmail.com](mailto:wwarthen@gmail.com)) \ +06 Sep 2024 + +# Overview + +RomWBW software provides a complete, commercial quality implementation +of CP/M (and workalike) 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 the +\[Installation\] section. + +General features 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 +- Keyboard (PS/2) drivers via VT8242 or PPI interfaces +- Real time clock drivers including DS1302, BQ4845 +- OSes: CP/M 2.2, ZSDOS, CP/M 3, NZ-COM, ZPM3, QPM, p-System, and + FreeRTOS +- Built-in VT-100 terminal emulation support + +RomWBW is distributed as both source code and pre-built ROM and disk +images. 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 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 accessible storage on a single device. + +The pre-built ROM firmware images are generally suitable for most users. +However, 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 – 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. + +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 “combo” 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. + +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. + +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. + +# Acquiring RomWBW + +The [RomWBW Repository](https://github.com/wwarthen/RomWBW) +() on GitHub is the official +distribution location for all project source and documentation. 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. Expand the “Assets” drop-down +for the release you want to download, then select the asset named +RomWBW-vX.X.X-Package.zip. The Package asset 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. + +All source code and distributions are maintained on GitHub. Code +contributions are very welcome. + +# 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](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20User%20Guide.pdf). + +## Documentation + +Documentation for RomWBW includes: + +- [RomWBW User + Guide](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20User%20Guide.pdf) +- [RomWBW System + Guide](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20System%20Guide.pdf) +- [RomWBW + Applications](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20Applications.pdf) +- [RomWBW + Errata](https://github.com/wwarthen/RomWBW/raw/master/Doc/RomWBW%20Errata.pdf) + +# 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 – 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 “the + early days”. 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 the sound driver interface and the SN76489 + sound driver. + +- 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 also contributed a great deal of content to the User + Guide. + +- 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 + +Contributions of all kinds to RomWBW are very welcome. + +# Licensing + +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 . + +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 +> + +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. + +# 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](https://www.retrobrewcomputers.org/forum/) +- [RC2014 Google + Group](https://groups.google.com/forum/#!forum/rc2014-z80) +- [retro-comp Google + Group](https://groups.google.com/forum/#!forum/retro-comp) + +Submission of issues and bugs are welcome at the [RomWBW GitHub +Repository](https://github.com/wwarthen/RomWBW). + +Also feel free to email Wayne Warthen at . diff --git a/ReadMe.txt b/ReadMe.txt index c24532d9..1df615a9 100644 --- a/ReadMe.txt +++ b/ReadMe.txt @@ -1,299 +1,299 @@ -RomWBW ReadMe -Wayne Warthen (wwarthen@gmail.com) -05 Sep 2024 - - - -OVERVIEW - - -RomWBW software provides a complete, commercial quality implementation -of CP/M (and workalike) 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 the -[Installation] section. - -General features 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 -- Keyboard (PS/2) drivers via VT8242 or PPI interfaces -- Real time clock drivers including DS1302, BQ4845 -- OSes: CP/M 2.2, ZSDOS, CP/M 3, NZ-COM, ZPM3, QPM, p-System, and - FreeRTOS -- Built-in VT-100 terminal emulation support - -RomWBW is distributed as both source code and pre-built ROM and disk -images. 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 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 accessible storage on a single device. - -The pre-built ROM firmware images are generally suitable for most users. -However, 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 – 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. - -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 “combo” 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. - -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. - -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. - - - -ACQUIRING ROMWBW - - -The RomWBW Repository (https://github.com/wwarthen/RomWBW) on GitHub is -the official distribution location for all project source and -documentation. 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. Expand -the “Assets” drop-down for the release you want to download, then select -the asset named RomWBW-vX.X.X-Package.zip. The Package asset 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. - -All source code and distributions are maintained on GitHub. Code -contributions are very welcome. - - - -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. - - -Documentation - -Documentation for RomWBW includes: - -- RomWBW User Guide -- RomWBW System Guide -- RomWBW Applications -- RomWBW Errata - - - -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 – 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 “the - early days”. 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 the sound driver interface and the - SN76489 sound driver. - -- 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 also contributed a great deal of content to the User - Guide. - -- 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 - -Contributions of all kinds to RomWBW are very welcome. - - - -LICENSING - - -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. - - - -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. +RomWBW ReadMe +Wayne Warthen (wwarthen@gmail.com) +06 Sep 2024 + + + +OVERVIEW + + +RomWBW software provides a complete, commercial quality implementation +of CP/M (and workalike) 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 the +[Installation] section. + +General features 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 +- Keyboard (PS/2) drivers via VT8242 or PPI interfaces +- Real time clock drivers including DS1302, BQ4845 +- OSes: CP/M 2.2, ZSDOS, CP/M 3, NZ-COM, ZPM3, QPM, p-System, and + FreeRTOS +- Built-in VT-100 terminal emulation support + +RomWBW is distributed as both source code and pre-built ROM and disk +images. 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 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 accessible storage on a single device. + +The pre-built ROM firmware images are generally suitable for most users. +However, 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 – 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. + +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 “combo” 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. + +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. + +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. + + + +ACQUIRING ROMWBW + + +The RomWBW Repository (https://github.com/wwarthen/RomWBW) on GitHub is +the official distribution location for all project source and +documentation. 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. Expand +the “Assets” drop-down for the release you want to download, then select +the asset named RomWBW-vX.X.X-Package.zip. The Package asset 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. + +All source code and distributions are maintained on GitHub. Code +contributions are very welcome. + + + +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. + + +Documentation + +Documentation for RomWBW includes: + +- RomWBW User Guide +- RomWBW System Guide +- RomWBW Applications +- RomWBW Errata + + + +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 – 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 “the + early days”. 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 the sound driver interface and the + SN76489 sound driver. + +- 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 also contributed a great deal of content to the User + Guide. + +- 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 + +Contributions of all kinds to RomWBW are very welcome. + + + +LICENSING + + +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. + + + +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. diff --git a/Source/Doc/UserGuide.md b/Source/Doc/UserGuide.md index 8b2d75fb..91dced48 100644 --- a/Source/Doc/UserGuide.md +++ b/Source/Doc/UserGuide.md @@ -1072,6 +1072,18 @@ The concept of slices is described in detail in the section The mapping of a hardware disk (and slice) to a Drive letter in an operating system. A Drive has a file system installed on it +#### Disk Image + +A disk image is a predefined image of a complete CP/M filesystem, +or filesystem(s), including any partition tables (for hard disk images). +Each disk image has the complete set of normal applications and tools +distributed with the associated operating system or application suite. + +This comes in for form of a file which is suitable for copying directly +onto target media, using a modern computer. It is generally easier to +use these disk images than transferring files over individually. +See the section [Disk Images] for further details. + ## Startup Hardware Discovery During startup RomWBW performs detection for hardware supported by your @@ -1241,16 +1253,17 @@ With some understanding of how RomWBW presents disk space to the operating systems, we need to go over the options for actually setting up your disk(s) with content. -### Preparing Media for first use +### Preparing Media for First Use You can initialize the media in-place using your RomWBW system. Essentially, this means you are creating a set of blank directories on your disk so that files can be saved there. -This is somewhat analogous to partitioning partitioning of a hard disk +This is somewhat analogous to partitioning of a hard disk or doing a low level format of a floppy disk. Initilizing a Floppy disk is covered in the section [Floppy Disk Formatting], -or for a Hard disk the section [Hard Disk Preparation] +or for a Hard disk the section [Hard Disk Preparation] covers the steps to +manually setup a hard disk for first use. ### Clearing (Formatting) Drives @@ -1298,30 +1311,6 @@ Directory cleared. B> ``` -### Making Bootable Media - -If you want to make a disk bootable, you will need to use `SYSCOPY` to -setup the system track(s) of the slice. -The use of `SYSCOPY` depends on the operating system and is -described in the [Operating Systems] chapter of this document. - -As an example, let's assume you want to setup C: as a bootable Z-System disk. -To setup the system track you would use: - -``` -B>SYSCOPY C:=B:ZSYS.SYS - -SYSCOPY v2.0 for RomWBW CP/M, 17-Feb-2020 (CP/M 2 Mode) -Copyright 2020, Wayne Warthen, GNU GPL v3 - -Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y -Reading image... Writing image... Done -``` - -Once this process succeeds, you will be able to boot directly to the -disk slice from the boot loader prompt. See the instructions in -[Starting Operating Systems from Disk] for details on this. - ### Checking Disk Layout If you are not sure which disk layout is used for your existing @@ -1643,10 +1632,7 @@ There are two approaches to preparing disks for use by RomWBW. including files to a disk. This section of the document describes the manual process of preparing -empty disks that are ready for use by an operating system. You will -need to refer to [Transferring Files] for more information on getting -files onto the disks. You will also need to follow the instructions -in [Operating Systems] to make disks bootable. +empty disks that are ready for use by an operating system. Alternatively, you can use the pre-built RomWBW disk images to quickly create disk media that already has a large selection of files and @@ -1760,7 +1746,7 @@ First you need to understand * The disk layout approach (either hd1k or the legacy hd512). See [Hard Disk Layouts] section if you are not sure. - HD1K should be the preferred layout. + hd1k should be the preferred layout. * The number of 8MB slices that you want to allocate, preferred is 64 slices. At least 1 slice of 8MB is required * If you want to leave space for a FAT partition. See [FAT Filesystem Preparation] @@ -1787,9 +1773,9 @@ The disk unit number was assigned at boot See [Device Unit Assignments] Refer to $doc_apps$ for more information on use of the `FDISK80` utility. -If you want to use the legacy hd512 layout skip down to the [Legacy (HD512)] section +If you want to use the legacy hd512 layout skip down to the [Legacy (hd512)] section -#### Modern (HD1K) +#### Modern (hd1k) At this point, use the `I` command to initialize (reset) the partition table to an empty state. @@ -1849,7 +1835,7 @@ At this point, it is best to restart your system to make sure that the operating system is aware of the partition table updates. Start CP/M 2.2 or Z-System from ROM again. -#### Legacy (HD512) +#### Legacy (hd512) At this point, use the `I` command to initialize (reset) the partition table to an empty state. @@ -1862,6 +1848,12 @@ At this point, it is best to restart your system to make sure that the operating system is aware of the partition table updates. Start CP/M 2.2 or Z-System from ROM again. +#### FAT Partition + +At this point you may want to consider creating a FAT partition +Please see the section [FAT Filesystem Preparation] for detils on how +to setup the FAT partition. + ### Slice Initialization You need to initialize each slice for CP/M to use it. @@ -1880,6 +1872,43 @@ using the same process. You may need to reassign drive letters to access some slices that are beyond the ones automatically assigned. You can use the `ASSIGN` command to handle this. +## Post Disk Preparation + +Once a disk (either floppy or hard disk) has been initialised and +formattted you may optionally; +* Make the disk bootable +* Copy system (or other) files to the disk + +### Making a Disk Bootable + +To make a disk bootable you will need to follow the specific instructions +in [Operating Systems], as each operating system will be different. + +Generally you will need to use `SYSCOPY` to setup the system track(s) +of the disk.As an example, If you wanted to setup C: as a bootable +Z-System disk you would use: + +``` +B>SYSCOPY C:=B:ZSYS.SYS + +SYSCOPY v2.0 for RomWBW CP/M, 17-Feb-2020 (CP/M 2 Mode) +Copyright 2020, Wayne Warthen, GNU GPL v3 + +Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y +Reading image... Writing image... Done +``` + +Once this process succeeds, you will be able to boot directly to the +disk slice from the boot loader prompt. See the instructions in +[Starting Operating Systems from Disk] for details on this. + +### Copying System Files + +As well as making the disk bootable, you may need to transfer other +system and application files to your disks. +Refer to [Transferring Files] for more information on getting +files onto your disks. + # Disk Images Since it would be quite a bit of work to transfer over all the files you @@ -2072,13 +2101,19 @@ positions indicated: | Slice 5 | WordStar v4 & ZDE Applications | | Slice 6-63 | _blank unformatted_ | -There are actually 2 combo disk images in the +There are actually 2 primary combo disk images in the distribution. One for an hd512 disk layout (hd512_combo.img) and one for an hd1k disk layout (hd1k_combo.img). Simply use the image file that corresponds to your desired hard disk layout. Review the information in [Hard Disk Layouts] if you need more information of the disk layout options. +> **Note**: Apart from the hd512 and hd1k combo disk images (mentioned above) +> there are actaully a number of other `hd1k_*_combo.img` files. These +> additional combo files are platform (generally romless) specific, +> and should be ignored unless you are on one of these platforms. +> If you are on one of these platforms you must use the correct combo file + The combo disk image actaully only contains the initial partition table, and the first 6 slices (Slice 0 to 5), this is approximately 49MB in size. While the partition table reserves space to store 64 CP/M filesystem @@ -2175,6 +2210,12 @@ Linux/MacOS: `cat hd1k_prefix.dat hd1k_cpm22.img hd1k_cpm3.img hd1k_ws >hd.img` +> **Note**: Apart from the hd1k_prefix.dat file (mentioned above) +> there are actaully a number of other `hd1k_*_prefix.dat` files. These +> additional prefix files are platform (generally romless) specific, +> and should be ignored unless you are on one of these platforms. +> If you are on one of these platforms you must use the correct prefix file + In all of the examples above, the resulting file (hd.img) would now be written to your hard disk media and would be ready to use in a RomWBW system. @@ -2963,195 +3004,6 @@ floppy disk and hard disk images. | TUNE | Play .PT2, .PT3, .MYM audio files. | | INTTEST | Test interrupt vector hooking. | -# FAT Filesystem - -The FAT filesystem format that originated with MS-DOS is almost -ubiquitous across modern computers. Virtually all operating systems -now support reading and writing files to a FAT filesystem. For this -reason, RomWBW now has the ability to read and write files on FAT -filesystems. - -This is accomplished by running a RomWBW custom application called `FAT`. -This application understands both FAT filesystems as well as CP/M filesystems. - -* Files can be copied between a FAT filesystem and a CP/M filesystem, - but you cannot execute files directly from a FAT filesystem. -* FAT12, FAT16, and FAT32 formats are supported. -* Long filenames are not supported. Files with long filenames will - show up with their names truncated into the older 8.3 convention. -* A FAT filesystem can be located on floppy or hard disk media. For - hard disk media, a valid FAT Filesystem partition must exist. -* Note that CP/M (and compatible) OSes do not support all of the - filename characters that a modern computer does. The following - characters are **not permitted** in a CP/M filename: - - `< > . , ; : = ? * [ ] _ % | ( ) / \` - - The FAT application does not auto-rename files when it encounters - invalid filenames. It will just issue an error and quit. - Additionally, the error message is not very clear about the problem. - -## FAT Filesystem Preparation - -In general, you can create media formatted with a FAT filesystem on -your RomWBW computer or on your modern computer. We will only be -discussing the RomWBW-based approach here. - -In the case of a floppy disk, you can use the `FAT` application to -format the floppy disk. The floppy disk must already be physically -formatted using RomWBW FDU or equivalent. If your floppy disk is on -RomWBW disk unit 2, you could use `FAT FORMAT 2:`. This will overwrite -the floppy with a FAT filesystem and all previous contents will be lost. -Once formatted this way, the floppy disk can be used in a floppy drive -attached to a modern computer or it can be used on RomWBW using the -other `FAT` tool commands. - -In the case of hard disk media, it is necessary to have a FAT -partition. If you prepared your RomWBW hard disk media using the -disk image process, then this partition will already be defined and -you do not need to recreate it. This default FAT partition is located -at approximately 512MB from the start of your disk and it is 384MB in -size. So, your hard disk media must be 1GB or greater to use this -default FAT partition. - -You can confirm the existence of the FAT partition with `FDISK80` by -using the 'P' command to show the current partition table. Here is an -example of a partition table listing from `FDISK80` that includes the -FAT partition (labelled "FAT16"): - -``` -Capacity of disk 4: ( 4G) 7813120 Geom 77381010 -Nr ---Type- A -- Start End LBA start LBA count Size - 1 RomWBW 2e 8:0:1 1023:15:16 2048 1048576 512M - 2 FAT16 06 1023:0:1 1023:15:16 1050624 786432 384M - 3 00 *** empty *** - 4 00 *** empty *** -``` - -If your hard disk media does not have a FAT partition already defined, -you will need to define one using FDISK80 by using the 'N' command. -Ensure that the location and size of the FAT partition does not -overlap any of the CP/M slice area and that it fits within the size -of your media. - -Once the partition is defined, you will still need to format it. Just -as with a floppy disk, you use the `FAT` tool to do this. If your -hard disk media is on RomWBW disk unit 4, you would use `FAT FORMAT 4:`. -This will look something like this: - -``` -E>fat format 4: - -About to format FAT Filesystem on Disk Unit #4. -All existing FAT partition data will be destroyed!!! - -Continue (y/n)? - -Formatting... Done -``` - -Your FAT filesystem is now ready to use. - -If your RomWBW system has multiple disk drives/slots, you can also just -create a disk with your modern computer that is a dedicated FAT -filesystem disk. You can use your modern computer to format the disk -(floppy, CF Card, SD Card, etc.), then insert the disk in your RomWBW -computer and access it using `FAT` based on its RomWBW unit number. - -**WARNING**: Microsoft Windows will sometimes suggest reformatting -partitions that it does not recognize. If you are prompted to format a -partition of your SD/CF/USB Media when inserting the card into a Windows -computer, you probably want to select Cancel. - -## FAT Application Usage - -Complete instructions for the `FAT` application are found in $doc_apps$. -Here, we will just provide a couple of simple examples. Note that the -FAT application is not on the ROM disk because it is too large to -include there. - -The most important thing to understand about the `FAT` application is -how it refers to FAT filesystems vs. CP/M filesystems. It infers this -based on the file specification provided. If you use a specification -like `C:SAMPLE.TXT`, it will use the C: drive of your CP/M operating -system. If you use a specification like `4:SAMPLE.TXT`, it will use -the FAT filesystem on the disk in RomWBW disk unit 4. Basically, if -you start your file or directory specification with a number followed -by a colon, it means FAT filesystem. Anything else will mean CP/M -filesystem. - -Here are a few examples. This first example shows how to get a FAT -directory listing from RomWBW disk unit 4: - -``` -E>fat dir 4: - -Directory of 4: - - -E> -``` - -As you can see, there are currently no files there. Now let's copy -a file from CP/M to the FAT directory: - -``` -E>fat copy sample.txt 4: - -Copying... - -SAMPLE.TXT ==> 4:/SAMPLE.TXT ... [OK] - - 1 File(s) Copied -``` - -If we list the FAT directory again, you will see the file: - -``` -E>fat dir 4: - -Directory of 4: - -01/30/2023 17:50:14 29952 ---A SAMPLE.TXT - -``` - -Now let's copy the file from the FAT filesystem back to CP/M. This -time we will get a warning about overwriting the file. For this -example, we don't want to do that, so we abort and reissue the -command specifying a new filename to use: - -``` -E>fat copy 4:sample.txt e: - -Copying... - -4:/SAMPLE.TXT ==> E:SAMPLE.TXT Overwrite? (Y/N) [Skipped] - - 0 File(s) Copied - -E>fat copy 4:sample.txt e:sample2.txt - -Copying... - -4:/SAMPLE.TXT ==> E:SAMPLE2.TXT ... [OK] - - 1 File(s) Copied -``` - -Finally, let's try using wildcards: - -``` -E>fat copy sample*.* 4: - -Copying... - -SAMPLE.TXT ==> 4:/SAMPLE.TXT Overwrite? (Y/N) ... [OK] -SAMPLE2.TXT ==> 4:/SAMPLE2.TXT ... [OK] - - 2 File(s) Copied -``` - # Real Time Clock RomWBW supports a variety of real time clock hardware. If your @@ -3928,35 +3780,222 @@ detail in the Source/Images directory of the distribution. ## FAT Filesystem Transfers -The ability to interact with FAT filesystems was covered in -[FAT Filesystem]. This capability means that you can generally use your - modern computer to make an SD Card, CF Card, or USB Drive with a -standard FAT32 filesystem on it, then place that media in your RomWBW -computer and access the files. +The FAT filesystem format that originated with MS-DOS is almost +ubiquitous across modern computers. Virtually all operating systems +now support reading and writing files to a FAT filesystem. For this +reason, RomWBW now has the ability to read and write files on FAT +filesystems. + +This capability means that you can generally use your modern computer +to make an SD Card, CF Card, or USB Drive with a standard FAT filesystem +on it, then place that media in your RomWBW computer and access the files. + +* Files can be copied between a FAT filesystem and a CP/M filesystem, + but you cannot execute files directly from a FAT filesystem. + +* FAT12, FAT16, and FAT32 formats are supported. + +* Long filenames are not supported. Files with long filenames will + show up with their names truncated into the older 8.3 convention. + If you have files on your modern computer with long filenames, + it is usually easiest to rename them on the modern computer. + +* A FAT filesystem can be located on floppy or hard disk media. For + hard disk media, a valid FAT Filesystem partition must exist. + +Some additional **Notes** and **WARNINGS** Things to be careful about + +* CP/M (and compatible) OSes do not support all of the + filename characters that a modern computer does. The following + characters are **not permitted** in a CP/M filename: + + `< > . , ; : = ? * [ ] _ % | ( ) / \` + + The FAT application does not auto-rename files when it encounters + invalid filenames. It will just issue an error and quit. + Additionally, the error message is not very clear about the problem. -When formatting the media on your modern computer, be sure to pick the -FAT filesystem. NTFS and other filesystems will not work. As previously -mentioned, the `FAT` application does not understand long filenames, -only the traditional 8.3 filenames. If you have files on your modern -computer with long filenames, it is usually easiest to rename them on -the modern computer. +* Microsoft Windows will sometimes suggest **reformatting** + partitions that it does not recognize (e.g. RomWBW). + If you are using media that contains both a FAT partition + and a RomWBW partition you may prompted to format a partition of your + SD/CF/USB Media when inserting the card into a Windows computer, + you probably want to select Cancel. + +### FAT Filesystem Preparation + +In general, you can create media formatted with a FAT filesystem on +your RomWBW computer or on your modern computer. We will only be +discussing the RomWBW-based approach here. + +#### Floppy Disk + +In the case of a floppy disk, you can use the `FAT` application to +format the floppy disk. The floppy disk must already be physically +formatted using RomWBW FDU or equivalent. If your floppy disk is on +RomWBW disk unit 2, you could use `FAT FORMAT 2:`. This will overwrite +the floppy with a FAT filesystem and all previous contents will be lost. +Once formatted this way, the floppy disk can be used in a floppy drive +attached to a modern computer or it can be used on RomWBW using the +other `FAT` tool commands. + +#### Hard Disk + +In the case of hard disk media, it is necessary to have a FAT +partition. If you prepared your RomWBW hard disk media using the +disk image process, then this partition will already be defined and +you do not need to recreate it. This default FAT partition is located +at approximately 512MB from the start of your disk and it is 384MB in +size. So, your hard disk media must be 1GB or greater to use this +default FAT partition. + +You can confirm the existence of the FAT partition with `FDISK80` by +using the 'P' command to show the current partition table. Here is an +example of a partition table listing from `FDISK80` that includes the +FAT partition (labelled "FAT16"): + +``` +Capacity of disk 4: ( 4G) 7813120 Geom 77381010 +Nr ---Type- A -- Start End LBA start LBA count Size + 1 RomWBW 2e 8:0:1 1023:15:16 2048 1048576 512M + 2 FAT16 06 1023:0:1 1023:15:16 1050624 786432 384M + 3 00 *** empty *** + 4 00 *** empty *** +``` + +If your hard disk media does not have a FAT partition already defined, +you will need to define one using FDISK80 by using the 'N' command. +Ensure that the location and size of the FAT partition does not +overlap any of the CP/M slice area and that it fits within the size +of your media. + +Once the partition is defined, you will still need to format it. Just +as with a floppy disk, you use the `FAT` tool to do this. If your +hard disk media is on RomWBW disk unit 4, you would use `FAT FORMAT 4:`. +This will look something like this: + +``` +E>fat format 4: + +About to format FAT Filesystem on Disk Unit #4. +All existing FAT partition data will be destroyed!!! + +Continue (y/n)? + +Formatting... Done +``` + +Your FAT filesystem is now ready to use. + +If your RomWBW system has multiple disk drives/slots, you can also just +create a disk with your modern computer that is a dedicated FAT +filesystem disk. You can use your modern computer to format the disk +(floppy, CF Card, SD Card, etc.), then insert the disk in your RomWBW +computer and access it using `FAT` based on its RomWBW unit number. + +### FAT Application Usage + +Transferring files is accomplished by running a RomWBW custom application +called `FAT`. This application understands both FAT filesystems as well +as CP/M filesystems. To copy files from your modern computer to your RomWBW computer, start by putting the disk media with the FAT filesystem in your modern computer. The modern computer should recognize it. Then copy the files you want to get to your RomWBW computer onto this media. Once done, remove the media from your modern computer and insert it in the RomWBW -computer. Finally, use the `FAT` tool to copy the files onto a CP/M -drive. +computer. -This process works just fine in reverse if you want to copy files from a +Finally, use the `FAT` tool to copy the files onto a CP/M +drive. This process works just fine in reverse if you want to copy files from a CP/M filesystem to your modern computer. -**WARNING**: If you are using media that contains both a FAT partition -and a RomWBW partition, your modern computer may be confused by the -RomWBW partition. In some cases, it will prompt you to format the -RomWBW partition because it doesn't know what it is. You will be -prompted before it does this -- just be careful not to allow it. +Complete instructions for the `FAT` application are found in $doc_apps$. +Here, we will just provide a couple of simple examples. Note that the +FAT application is not on the ROM disk because it is too large to +include there. + +The most important thing to understand about the `FAT` application is +how it refers to FAT filesystems vs. CP/M filesystems. It infers this +based on the file specification provided. If you use a specification +like `C:SAMPLE.TXT`, it will use the C: drive of your CP/M operating +system. If you use a specification like `4:SAMPLE.TXT`, it will use +the FAT filesystem on the disk in RomWBW disk unit 4. Basically, if +you start your file or directory specification with a number followed +by a colon, it means FAT filesystem. Anything else will mean CP/M +filesystem. + +Here are a few examples. This first example shows how to get a FAT +directory listing from RomWBW disk unit 4: + +``` +E>fat dir 4: + +Directory of 4: + + +E> +``` + +As you can see, there are currently no files there. Now let's copy +a file from CP/M to the FAT directory: + +``` +E>fat copy sample.txt 4: + +Copying... + +SAMPLE.TXT ==> 4:/SAMPLE.TXT ... [OK] + + 1 File(s) Copied +``` + +If we list the FAT directory again, you will see the file: + +``` +E>fat dir 4: + +Directory of 4: + +01/30/2023 17:50:14 29952 ---A SAMPLE.TXT + +``` + +Now let's copy the file from the FAT filesystem back to CP/M. This +time we will get a warning about overwriting the file. For this +example, we don't want to do that, so we abort and reissue the +command specifying a new filename to use: + +``` +E>fat copy 4:sample.txt e: + +Copying... + +4:/SAMPLE.TXT ==> E:SAMPLE.TXT Overwrite? (Y/N) [Skipped] + + 0 File(s) Copied + +E>fat copy 4:sample.txt e:sample2.txt + +Copying... + +4:/SAMPLE.TXT ==> E:SAMPLE2.TXT ... [OK] + + 1 File(s) Copied +``` + +Finally, let's try using wildcards: + +``` +E>fat copy sample*.* 4: + +Copying... + +SAMPLE.TXT ==> 4:/SAMPLE.TXT Overwrite? (Y/N) ... [OK] +SAMPLE2.TXT ==> 4:/SAMPLE2.TXT ... [OK] + + 2 File(s) Copied +``` # Customizing RomWBW