diff --git a/Doc/ChangeLog.txt b/Doc/ChangeLog.txt index 9b31569a..0a5bc2f1 100644 --- a/Doc/ChangeLog.txt +++ b/Doc/ChangeLog.txt @@ -47,7 +47,7 @@ Version 3.5 - MAP: Significant improvement in Disk Catalog document - MAP: Added Disk Image for the Z3PLUS (Z-System for CP/M-Plus) os. - H?H: Fix XModem 12.3 WRERR to put CAN char in proper register to send. -- MAP: Initial NVRAM configuration infrastructure +- MAP: Initial NVRAM configuration infrastructure, and boot device selection. Version 3.4 ----------- diff --git a/Doc/RomWBW Applications.pdf b/Doc/RomWBW Applications.pdf index 6b3ed77d..78871c4a 100644 Binary files a/Doc/RomWBW Applications.pdf and b/Doc/RomWBW Applications.pdf differ diff --git a/Doc/RomWBW System Guide.pdf b/Doc/RomWBW System Guide.pdf index 64c54ef4..b4e76b65 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 b66ef8f7..7d1c3878 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 3d49bb8b..702e62de 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -1,294 +1,295 @@ - - -**RomWBW ReadMe** \ -Version 3.5 \ -Wayne Warthen ([wwarthen@gmail.com](mailto:wwarthen@gmail.com)) \ -08 Nov 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 eZ80 CPU support, 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 Disk - Catalog, User Guide as well as contributing the disk image for the - Z3PLUS operating system, and the COPYSL 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 - -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)) \ +29 Nov 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 eZ80 CPU support, 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 Disk + Catalog, User Guide as well as contributing the disk image for the + Z3PLUS operating system, the COPYSL utility, and also implemented + feature for RomWBW configuration by NVRAM. + +- 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 86e19209..e3f66d92 100644 --- a/ReadMe.txt +++ b/ReadMe.txt @@ -1,300 +1,301 @@ -RomWBW ReadMe -Wayne Warthen (wwarthen@gmail.com) -08 Nov 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 eZ80 CPU support, 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 Disk - Catalog, User Guide as well as contributing the disk image for the - Z3PLUS operating system, and the COPYSL 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 - -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) +29 Nov 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 eZ80 CPU support, 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 Disk + Catalog, User Guide as well as contributing the disk image for the + Z3PLUS operating system, the COPYSL utility, and also implemented + feature for RomWBW configuration by NVRAM. + +- 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/CBIOS/cbios.asm b/Source/CBIOS/cbios.asm index ed29a789..83279de0 100644 --- a/Source/CBIOS/cbios.asm +++ b/Source/CBIOS/cbios.asm @@ -78,7 +78,7 @@ MEMTOP .EQU $10000 #INCLUDE "../UBIOS/ubios.inc" #ENDIF ; - .ORG CBIOS_LOC ; DEFINED IN STD.ASM + .ORG CBIOS_LOC ; DEFINED IN LAYOUT.INC ; STACK .EQU CBIOS_END ; USE SLACK SPACE FOR STACK AS NEEDED ; diff --git a/Source/Doc/Applications.md b/Source/Doc/Applications.md index fbac6e99..4f7cb10e 100644 --- a/Source/Doc/Applications.md +++ b/Source/Doc/Applications.md @@ -384,6 +384,109 @@ protocol. **`X`** - Exit the monitor program back to the main boot menu. +## RomWBW System Configuration + +System Configuration (`SYSCONF`) is a utility that allows system configuration to +be set, dynamically and stored in NVRAM provided by an RTC chip. + +(`SYSCONF`) is both a ROM application ('W' Menu option), and a CP/M utility. +Noting however the CP/M utility is not included on an disk image, it is found in +the `Binary/Applications` folder of the RomWBW distribution + +### Basic Operation + +The application is an interactive application it does not have command line syntax. +Instead commands are executed from within the application in a command line structure + +When you first start the (`SYSCONF`) utility it will display the current switches +followed by a command listing. + +When you first run the (`SYSCONF`) utility the NVRAM will be uninitialised, and can +be initialised using the (R)eset command, which write default values to NVRAM. + +Updates are done immediately to NVRAM as you enter them, i.e. there is no confirm +changes step. If you make an incorrect changes you simply need to enter a new +command to set the Switch value correctly + +Once a change has been made it is available, however may not take effect until +the next system reboot. This is dependant on the Switch itself + +If no NVRAM is provided by your hardware then running this application will just +report the missing hardware and exit immediately. + +To exit from the application use the (Q)uit command + +### Commands and Syntax + +The following are the accepted commands, unless otherwise specified a "Space" +character is used to delimit parameters in the command + +| Command | Argument(s) | Description | +|------------|------------------|-----------------------------------------------| +| (P)rint | -none- | Display a list of the current switch value(s) | +| (S)et | {SW} {val},... | Sets an Switch {SW} with specific values(s) | +| (R)eset | -none- | Reset all setting to default | +| (H)elp | {SW} | Provides help on the syntax (values) | +| (Q)uit | -none- | Exit the application | + +**Where** + +| Argument | Description | +|-----------|----------------------------------------------------------------------| +| {SW} | Switch ID, typically this is 2 character name to identify the switch | +| {val},... | a "Comma" separated list of values to set into the switch | + +### Switch Options + +#### Auto Boot (AB) + +This switch will define if the system will perform auto boot at the RomWBW boot prompt. +Enabling this will not prevent a user from typing a boot command, so long as the timeout is not +exceeded. When configured this replaces the (`BOOT_DEFAULT`) variable +defined in build configuration. + +Making changes to auto boot has no affect until the next reboot. + +**Arguments** + +| Type | Arguments | Description | +|----------|------------|--------------------------------------------------------| +| Enable | 'E' | Auto Boot. eg. "E,10" will auto boot, after 10 seconds | +| | Timout | Timeout in seconds in the range 0-15, 0 = immediate | +| Disabled | 'D' | No Auto Boot. e.g. "D" will disable autoboot | + +**Examples** + +| Command | Description | +|-----------------------|---------------------------------------------------| +| S AB E,10 | Enable Auto Boot with 10 second delay | +| S AB D | Disable Auto Boot | + +#### Default Boot (DB) + +This switch will define the default boot command to be executed when pressing enter +at the RomWBW boot prompt. When configured this replaces the (`BOOT_TIMEOUT`) variable +defined in build configuration. + +Making changes to auto boot has no affect until the next reboot. + +**Arguments** + +| Type | Arguments | Description | +|------|------------------|----------------------------------------------------------| +| Disk | 'D' | Disk Boot. eg. "D,2,14" will boot, disk unit 2, slice 14 | +| | Disk Unit Number | Unit number in the range 0-127 | +| | Disk Slice | Slice in the range 0-255, use 0 for floppy boot | +| ROM | 'R' | ROM App. e.g. "R,M" will boot the Monitor App | +| | Rom App Name | single character used on the Menu to identify the app | + +**Examples** + +| Command | Description | +|-------------|----------------------------------------------------------| +| S DB D,2,14 | Set the default boot from Disk; Unit 2, Slice 14 | +| S DB R,M | Set the default boot to be the (M)onitor Rom Application | + ## CP/M 2.2 This option will boot the CP/M 2.2 disk operating system diff --git a/Source/Doc/ReadMe.md b/Source/Doc/ReadMe.md index bf0c97da..426d4622 100644 --- a/Source/Doc/ReadMe.md +++ b/Source/Doc/ReadMe.md @@ -191,7 +191,8 @@ please let me know if I missed you! * Mark Pruden has also contributed a great deal of content to the Disk Catalog, User Guide as well as contributing the disk image - for the Z3PLUS operating system, and the COPYSL utility. + for the Z3PLUS operating system, the COPYSL utility, and also + implemented feature for RomWBW configuration by NVRAM. * Jacques Pelletier has contributed the DS1501 RTC driver code. diff --git a/Source/Doc/SystemGuide.md b/Source/Doc/SystemGuide.md index 4f995772..94488538 100644 --- a/Source/Doc/SystemGuide.md +++ b/Source/Doc/SystemGuide.md @@ -499,6 +499,77 @@ The startup then proceeds very much like the Application Boot process described above. HBIOS is installed in its operating bank and control is passed to the Boot Loader. +# Configuration + +## RomWBW NVRAM Configuration + +On systems with RTC devices (that have Non-Volitile RAM), RomWBW supports storing +some limited configuration option options inside this RAM + +Several configuration options are currently supported, these are known as Switches +The following switch ID's are defined, and described in sections below + +| Switch Number | Name | Description | +|---------------|--------------|-----------------------------------------------| +| 0x00 | -reserved- | Reserved | +| 0x01 | Default Boot | Default boot, either a Rom App or Disk Boot | +| 0x02 | -n/a- | -n/a- high order byte of previous switch | +| 0x03 | Auto Boot | Automatically boot enabled without user input | +| 0x04 - 0xFE | -future- | Future general usage | +| 0xFF | Status Reset | Get Status or Reset Switches to Default | + +RomWBW uses bytes located at the start of RTC NVRAM, and includes a Parity check of +the bytes in NVRAM to check for authenticity before using the configuration. + +| NVRAM Byte | Name | Description | +|-------------|--------------|-----------------------------------| +| 0x00 | Header Byte | Header Signature Byte 'W' | +| 0x01 - 0x03 | Switch Data | Actual Switch Data | +| 0x04 | Parity Check | Parity byte to check authenticity | + +The above data is copied into HBIOS Configuration Block (HCB) at startup at +the loacation starting at CB_SWITCHES + +### Default Boot (NVSW_DEFBOOT) + +16 bit Switch defining the default Rom application or Disk device to boot. + +| Bit 15 | Bits 14-8 | Bits 7-0 | +|-------------|-------------------|--------------------| +| 1 = Rom App | -undefined- | App to Boot (Char) | +| 0 = Disk | Disk Unit (0-127) | Disk Slice (0-255) | + +### Auto Boot (NVSW_AUTOBOOT) + +8 bit Switch defining if the system should auto boot at startup + +| Bits 7-6 | Bit 5 | Bit 4 | Bits 3-0 | +|----------|------------------------|----------|--------------------------------------| +| -unused- | 1 = Auto Boot Enabled | -unused- | 0 = Immediate Boot with no delay | +| -unused- | 1 = Auto Boot Enabled | -unused- | (1-15) Timeout (seconds) before boot | +| -unused- | 0 = Auto Boot Disabled | -unused- | -undefined- | + +### Status Reset (0xFF) + +The Status Reset switch is not a general purpose switch, it is a control mechanism +to allow the global status of all switches to be determined. The meaning of the switch +is different for Read (Get Status) and Write (Reset NVRAM) + +#### GET (Get Status) + +The read Get Status of switches. This returns very specific values from the function call. + +| Status | A Register | Z / NZ Flag | +|----------------------------------------------|------------|--------------| +| NVRAM does not exist | A=0 | NZ flag set | +| NVRAM exists, but has not been initialised | A=1 | NZ flag set | +| NVRAM exists, and has been fully initialised | A='W' | Z flag set | + +#### SET (Reset NVRAM) + +Reset NVRAM to default values. This will wipe any existing data and set default +values into NVRAM. + # Driver Model The framework code for bank switching also allows hardware drivers to be @@ -2611,6 +2682,27 @@ the caller can use interbank calls directly to the function in the driver which bypasses the overhead of the normal function invocation lookup. +#### SYSGET Subfunction 0xC0 -- Get Switches (SWITCH) + +| **Entry Parameters** | **Returned Values** | +|----------------------|---------------------| +| B: 0xF8 | A: Status | +| C: 0xC0 | HL: Switch Value | +| D: Switch Key | | + +This function will return the current value (HL) of the switch (D) from NVRAM. + +Switches may be returned as a 16 bit (HL) or 8 bit (L) value. It is up to the caller +to process the returned value correctly. Note for Switch 0xFF (status) the returned value +is primarily in the Status (A) register. + +Errors are signalled in the return by setting the NZ flag. When set the +(A) register may contain an error code, but this code does not conform to RomWBW standard + +Success is indicated by setting the Z flag + +For a description of switches please see [RomWBW NVRAM Configuration] + #### SYSGET Subfunction 0xD0 -- Get Timer Tick Count (TIMER) | **Entry Parameters** | **Returned Values** | @@ -2783,6 +2875,27 @@ sub-function value. The following lists the subfunctions available along with the registers/information utilized. The Status (A) is a standard HBIOS result code. +#### SYSSET Subfunction 0xC0 -- Set Switches (SWITCH) + +| **Entry Parameters** | **Returned Values** | +|----------------------|---------------------| +| B: 0xF9 | A: Status | +| C: 0xC0 | | +| D: Switch Key | | +| HL: Switch Value | | + +This function will set the value (HL) into the switch (D) and store it into NVRAM. + +Switches may be passed as a 16 bit (HL) or 8 bit (L) value. It is up to the caller +to send the value correctly. Note for Switch 0xFF (reset) the value (HL) is ignored + +Errors are signalled in the return by setting the NZ flag. When set the +(A) register may contain an error code, but this code does not conform to RomWBW standard + +Success is indicated by setting the Z flag + +For a description of switches please see [RomWBW NVRAM Configuration] + #### SYSSET Subfunction 0xD0 -- Set Timer Tick Count (TIMER) | **Entry Parameters** | **Returned Values** | diff --git a/Source/Doc/UserGuide.md b/Source/Doc/UserGuide.md index c2882d31..d1bd92e5 100644 --- a/Source/Doc/UserGuide.md +++ b/Source/Doc/UserGuide.md @@ -897,6 +897,50 @@ Boot [H=Help]: r Restarting System... ``` +### Setting NVRAM Options + +On systems with RTC devices (that have Non-Volatile RAM), RomWBW supports storing +some limited configuration option options inside this NVRAM + +Several configuration options are currently supported, these are known as Switches + +* Specify Automatic boot at startup, after an optional delay (AB) +* Define the Default Disk or ROM App to be booted at startup (DB) + +RomWBW uses bytes located at the start of RTC NVRAM, and includes a Parity check of +the bytes in NVRAM to check for authenticity before using the configuration. + +Initially NVRAM has to be reset (with default values), before it can be used. +As well as setting defaults, it also writes the correct parity, and allows the +NVRAM to be accessed and to store RomWBW config. + +This is an explicit step that must be done, as any existing data stored is overitten. +If you are using NVRAM for other purposes then you can continue to do so +so long as you do NOT perform this Reset step. + +NVRAM may also need to be reset in these circumstances + +* When there has been a loss of power to the NVRAM +* When upgrading to a new RomWBW version, or a RomWBW version that has new switches +* If the NVRAM has been overitten by another application. + +If you want to continue to use NVRAM in your applications you may want to consider storing +your data above the RomWBW Switch data. + +The WIZNET class of Network devices also contain NVRAM, currently RomWBW does not support +writing configuration to these devices. + +To configure these options an inbuilt ROM application is provided which can be accessed +by the command "`W`" from the RomWBW boot menu. + +This application is also built as a CP/M utility, but is not included on an disk image, +it is found in the `Binary/Applications` folder of the RomWBW distribution + +For further guidance on using this application please see the section +"RomWBW System Configuration" in the RomWBW Applications document + +[RomWBW Applications]($doc_root$/RomWBW Applications.pdf) + ### Changing Console and Console speed Your system can support a number of devices for the console. They may @@ -4237,6 +4281,11 @@ ALIAS facility. p-System has its own startup command processing mechanism that is covered in the p-System documentation. +## NVRAM Configuration + +See section [Setting NVRAM Options] for information about how to +apply NVRAM configuration. + ## ROM Customization The pre-built ROM images are configured for the basic capabilities of @@ -4269,6 +4318,14 @@ Note that the ROM customization process does not apply to UNA. All UNA customization is performed within the ROM setup script that is built into the ROM. +## ROM User Application + +The User App is provided as a way to access a custom written +ROM application. In the pre-built ROMs, selecting User App will just +return to the Boot Loader menu. If you are interested in creating a +custom application to run instead, review the "usrrom.asm" file in the +Source/HBIOS folder of the distribution. + # UNA Hardware BIOS John Coffman has produced a new generation of hardware BIOS called @@ -4678,7 +4735,8 @@ please let me know if I missed you! * Mark Pruden has also contributed a great deal of content to the Disk Catalog, User Guide as well as contributing the disk image - for the Z3PLUS operating system, and the COPYSL utility. + for the Z3PLUS operating system, the COPYSL utility, and also + implemented feature for RomWBW configuration by NVRAM. * Jacques Pelletier has contributed the DS1501 RTC driver code. diff --git a/Source/HBIOS/romldr.asm b/Source/HBIOS/romldr.asm index 01736dc3..ff8cf6df 100644 --- a/Source/HBIOS/romldr.asm +++ b/Source/HBIOS/romldr.asm @@ -2504,8 +2504,8 @@ ra_ent .equ 12 #defcont .dw p8 ; ; Note: The formatting of the following is critical. TASM does not pass -; macro arguments well. Ensure std.asm holds the definitions for *_LOC, -; *_SIZ *_END and any code generated which does not include std.asm is +; macro arguments well. Ensure LAYOUT.INC holds the definitions for *_LOC, +; *_SIZ *_END and any code generated which does not include LAYOUT.INC is ; synced. ; ; Note: The loadable ROM images are placed in ROM banks BID_IMG0 and diff --git a/Source/HBIOS/usrrom.asm b/Source/HBIOS/usrrom.asm index 146d4937..680fbc79 100644 --- a/Source/HBIOS/usrrom.asm +++ b/Source/HBIOS/usrrom.asm @@ -45,7 +45,7 @@ COLS .EQU 8 ; NUMBER OF PIXEL COLUMNS PER CHARACTER ; ; APPLICATION WILL WILL BE LOADED AT USR_LOC. THEREFORE, THE CODE ; MUST "ORG" AT THIS ADDRESS. TO CHANGE THE LOAD LOCATION OF THIS -; CODE, YOU CAN UPDATE USR_LOC IN STD.ASM. +; CODE, YOU CAN UPDATE USR_LOC IN LAYOUT.INC ; .ORG USR_LOC ; diff --git a/Source/TastyBasic/src/romwbwio.asm b/Source/TastyBasic/src/romwbwio.asm index 0f4a5cbd..ed76b7ce 100644 --- a/Source/TastyBasic/src/romwbwio.asm +++ b/Source/TastyBasic/src/romwbwio.asm @@ -31,7 +31,7 @@ BF_SYSRES_WARM .equ 01h ; warm start ;************************************************************* ; -; THE FOLLOWING NEED MUST BE SYNCED WITH STD.ASM SO ROMLDR +; THE FOLLOWING NEED MUST BE SYNCED WITH LAYOUT.INC SO ROMLDR ; KNOWS WHERE THIS EXECUTES AT ; ;*************************************************************