@ -80,7 +85,7 @@ Multiple disk images are provided in the distribution. Most disk images contain
# Installation
# Installation
The latest RomWBW distribution downloads are maintained on GitHub in the [RomWBW Repository](https://github.com/wwarthen/RomWBW). The fully-built distributions are found on the [releases page](https://github.com/wwarthen/RomWBW/releases) of the repository. On this page, you will probably see both pre-releases as well as normal releases. Unless you have a specific reason, I suggest you stick to the most recent normal (not pre-release) 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 called Source Code do not have the pre-built ROM or Disk Images.
The latest RomWBW distribution downloads are maintained on GitHub in the [RomWBW Repository](https://github.com/wwarthen/RomWBW). The fully-built distributions are found on the [releases page](https://github.com/wwarthen/RomWBW/releases) of the repository. On this page, you will probably see both pre-releases as well as normal releases. Unless you have a specific reason, I suggest you stick to the most recent normal release (not pre-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 are Source Code only and do not have the pre-built ROM or disk images.
The pre-built ROM images will automatically detect and support a reasonable range of devices including serial ports, video adapters, on-board disk interfaces, and PropIO/ParPortProp boards without building a custom ROM. The distribution is a .zip archive. After downloading it to a working directory on your modern computer (Windows/Linux/Mac) use any zip tool to extract the contents of the archive.
The pre-built ROM images will automatically detect and support a reasonable range of devices including serial ports, video adapters, on-board disk interfaces, and PropIO/ParPortProp boards without building a custom ROM. The distribution is a .zip archive. After downloading it to a working directory on your modern computer (Windows/Linux/Mac) use any zip tool to extract the contents of the archive.
@ -89,7 +94,7 @@ In general, you will just program your system's ROM chip with the appropriate RO
Looking at the extracted distribution archive, You will see that the distribution is broken up into a few sub-directories. The Binary directory contains the pre-built ROM and disk images. The ROM image files all end in ".rom". Based on the table below, **carefully** pick the appropriate ROM image:
Looking at the extracted distribution archive, You will see that the distribution is broken up into a few sub-directories. The Binary directory contains the pre-built ROM and disk images. The ROM image files all end in ".rom". Based on the table below, **carefully** pick the appropriate ROM image:
\*The RC2014 Z180 requires a separate RAM/ROM memory module. There are two types of these modules and you must pick the ROM for your type of memory module. The "ext" ROM supports Spencer's official 512K RAM/ROM banked memory module. The "nat" ROM supports any of the thrid-party Z180 native memory modules.
\*The RC2014 Z180 requires a separate RAM/ROM memory module. There are two types of these modules and you must pick the ROM for your type of memory module. The "ext" ROM supports Spencer's official 512K RAM/ROM banked memory module. The "nat" ROM supports any of the third-party Z180 native memory modules.
RomWBW will automatically attempt to detect and support typical add-on components for each of the systems supported. More information on the required system configuration and optional supported components for each ROM is found in the file called "RomList.txt" in the Binary directory. All pre-built ROM images are simple 512KB binary images. If your system utilizes a 1MB ROM, you can just program the image into the first 512KB of the ROM.
RomWBW will automatically attempt to detect and support typical add-on components for each of the systems supported. More information on the required system configuration and optional supported components for each ROM is found in the file called "RomList.txt" in the Binary directory. All pre-built ROM images are simple 512KB binary images. If your system utilizes a larger ROM chip, you can just program the image into the first 512KB of the ROM.
Connect a serial terminal or computer with terminal emulation software to the primary serial port of your CPU board. You may need to refer to your hardware provider's documentation for details. A null-modem connection may be required. Set the baud rate as indicated in the table above. Set the line characteristics to 8 data bits, 1 stop bit, no parity, and no flow control. If possible, select VT-100 terminal emulation.
Connect a serial terminal or computer with terminal emulation software to the primary serial port of your CPU board. You may need to refer to your hardware provider's documentation for details. A null-modem connection may be required. Set the baud rate as indicated in the table above. Set the line characteristics to 8 data bits, 1 stop bit, no parity, and no flow control. If possible, select VT-100 terminal emulation.
@ -118,9 +123,9 @@ Initially, you should try the ROM boot options. By selecting either CP/M 2.2 or
Upgrading to a newer release of RomWBW is essentially just a matter of updating the ROM chip in your system. If you have spare ROM chips for your system and a ROM programmer, it is always safest to keep your existing, working ROM chip and program a new one with the new firmware. If the new one fails to boot, you can easily return to the known working ROM.
Upgrading to a newer release of RomWBW is essentially just a matter of updating the ROM chip in your system. If you have spare ROM chips for your system and a ROM programmer, it is always safest to keep your existing, working ROM chip and program a new one with the new firmware. If the new one fails to boot, you can easily return to the known working ROM.
Prior to attempting to reprogram your actual ROM chip, you may wish to "try" the upgrade. With RomWBW, you can upload a new system image and load it from the command line. For each ROM image file (.rom) in the Binary directory, you will also find a corresponding application file (.com). For example, for SBC_std.rom, there is also an SBC_std.com file. You can upload the .com file to your system using XModem, then simply run the .com file. You will see your system go through the normal startup process just like it was started from ROM. However, your ROM has not been updated and the next time you boot your system, it will revert to the system image contained in ROM. You may find that you are unable to load the .com file because it is too large to fit in available application RAM (TPA). Unfortunately, in this case, you will not be able to use the .com file to start your system.
Prior to attempting to reprogram your actual ROM chip, you may wish to "try" the upgrade. With RomWBW, you can upload a new system image and load it from the command line. For each ROM image file (.rom) in the Binary directory, you will also find a corresponding application file (.com). For example, for SBC_std.rom, there is also an SBC_std.com file. You can upload the .com file to your system using XModem, then simply run the .com file. You will see your system go through the normal startup process just like it was started from ROM. However, your ROM has not been updated and the next time you boot your system, it will revert to the system image contained in ROM. You may find that you are unable to load the .com file because it is too large to fit in available application RAM (TPA). Unfortunately, in this case, you will not be able to use the .com file mechanism to start your system.
If you do not have easy access to a ROM programmer, it is entirely possible to reprogram your system ROM using the FLASH utility from Will Sowerbutts. This application called FLASH.COM can be found on the ROM drive of any running system. In this case, you would need to transfer the new ROM image (.rom) over to your system using XModem. The ROM image will be too large to fit on your RAM drive, so you will need to transfer it to a larger storage drive. Once the ROM image is on your system, you can use the FLASH application to update your ROM:
If you do not have easy access to a ROM programmer, it is usually possible to reprogram your system ROM using the FLASH utility from Will Sowerbutts. This application called FLASH.COM can be found on the ROM drive of any running system. In this case, you would need to transfer the new ROM image (.rom) over to your system using XModem (or one of the other mechanisms described in the Transferring Files section below). The ROM image will be too large to fit on your RAM drive, so you will need to transfer it to a larger storage drive. Once the ROM image is on your system, you can use the FLASH application to update your ROM. The following is a typical example of transferring ROM image using XModem and flashing the chip in-situ.
```
```
E>xm r rom.img
E>xm r rom.img
@ -149,7 +154,7 @@ Obviously, there is some risk to this approach since any issues with the program
To confirm your ROM chip has been successfully updated, restart your system and boot an operating system from ROM. Do not boot from a disk device yet. Review the boot messages to see if any issues have occurred.
To confirm your ROM chip has been successfully updated, restart your system and boot an operating system from ROM. Do not boot from a disk device yet. Review the boot messages to see if any issues have occurred.
Once you are satisfied that the ROM is working well, you will need to update the system images and RomWBW custom applications on your disk drives. The system images and custom applications are matched to the RomWBW ROM firmware in use. If you attempt to use a disk or applications that have not been updated to match the current ROM firmware, you are likely to have odd problems.
Once you are satisfied that the ROM is working well, you will need to update the system images and RomWBW custom applications on your disk drives. The system images and custom applications are matched to the RomWBW ROM firmware in use. If you attempt to boot a disk or run applications that have not been updated to match the current ROM firmware, you are likely to have odd problems.
The simplest way to update your disk media is to just use your modern computer to overwrite the entire media with the latest disk image of your choice. This process is described below in the Disk Images section. If you wish to update existing disk media in your system, you need to perform the following steps.
The simplest way to update your disk media is to just use your modern computer to overwrite the entire media with the latest disk image of your choice. This process is described below in the Disk Images section. If you wish to update existing disk media in your system, you need to perform the following steps.
@ -175,7 +180,7 @@ For example: `B>COPY ASSIGN.COM C:`
While the RAM/ROM disks provide a functional system, they are not useful in the long term because you cannot save data across power cycles. They are also constrained by limited space.
While the RAM/ROM disks provide a functional system, they are not useful in the long term because you cannot save data across power cycles. They are also constrained by limited space.
The systems supported by RomWBW all have the ability to use persistent disk media. I am referring to all kinds of disk devices including floppy drives, hard disks, CF Cards, and SD Cards. Some systems have disk interfaces built-in, while others will require add-in cards. You will need to refer to the documentation for your system.
The systems supported by RomWBW all have the ability to use persistent disk media. I am referring to all kinds of disk devices including floppy drives, hard disks, CF Cards, and SD Cards. Some systems have disk interfaces built-in, while others will require add-in cards. You will need to refer to the documentation for your system for your specific options.
In the RomWBW bootup messages, you will see hardware discovery messages. If you have a disk drive interface, you should see messages listing device types like FD:, IDE:, PPIDE:, SD:. Additionally, you will see messages indicating the media that has been found on the interfaces. As an example, here are the messages you might see if you have an IDE interface in your system with a single CF Card inserted in the primary side of the interface:
In the RomWBW bootup messages, you will see hardware discovery messages. If you have a disk drive interface, you should see messages listing device types like FD:, IDE:, PPIDE:, SD:. Additionally, you will see messages indicating the media that has been found on the interfaces. As an example, here are the messages you might see if you have an IDE interface in your system with a single CF Card inserted in the primary side of the interface:
@ -198,27 +203,25 @@ Configuring Drives...
D:=IDE0:1
D:=IDE0:1
```
```
You will probably see mroe drive letters than this. The drive letter assignment process is described in more detail later in this document. Be aware that RomWBW will only assign drive letters to disk interfaces that actually have media in them. If you do not see drive letters assigned as expected, refer to the prior system boot messages to ensure media has been detected in the interface. Actually, there is one exception to this rule: floppy drives will be assigned a drive letter regardless of whether there is any media inserted at boot.
You will probably see more drive letters than this. The drive letter assignment process is described in more detail later in this document. Be aware that RomWBW will only assign drive letters to disk interfaces that actually have media in them. If you do not see drive letters assigned as expected, refer to the prior system boot messages to ensure media has been detected in the interface. Actually, there is one exception to this rule: floppy drives will be assigned a drive letter regardless of whether there is any media inserted at boot.
Notice how each drive letter refers back to a specific disk hardware interface like IDE0. This is important as it is telling you what each drive letter refers to. Also notice that mass storage disks (like IDE) will normally have multiple drive letters assigned. The extra drive letters refer to additional "slices" on the disk. The concept of slices is also explained later in this document.
Notice how each drive letter refers back to a specific disk hardware interface like IDE0. This is important as it is telling you what each drive letter refers to. Also notice that mass storage disks (like IDE) will normally have multiple drive letters assigned. The extra drive letters refer to additional "slices" on the disk. The concept of slices is also explained later in this document.
Once you are seeing drive letters referring to your disk media, you can follow the instructions below to begin using the disk media with the operating system. Your disk media **must** be initialized prior to be used. There are two ways to initialize your media for use.
Once you are seeing drive letters referring to your disk media, you can follow the instructions below to begin using the disk media with the operating system. Your disk media **must** be initialized prior to being used. There are two ways to initialize your media for use.
You can initialize the media in-place using your RomWBW system. This process is described below under Disk Initialization. In this scenario, you will need to subsequently copy any files you want to use onto the newly initialized disk.
You can initialize the media in-place using your RomWBW system. This process is described below under Disk Initialization. In this scenario, you will need to subsequently copy any files you want to use onto the newly initialized disk (see Transferring Files).
Alternatively, you can use your modern Windows, Linux, or Mac computer to copy a disk image onto the disk media. RomWBW comes with a variety of disk images that are ready to use and have a much more complete set of files than you will find on the ROM disk. This process is covered below under Disk Images.
Alternatively, you can use your modern Windows, Linux, or Mac computer to copy a disk image onto the disk media. RomWBW comes with a variety of disk images that are ready to use and have a much more complete set of files than you will find on the ROM disk. This process is covered below under Disk Images.
## Disk Initialization
## Disk Initialization
To use a disk device, you will need to initialize the directory of the filesystem. On RomWBW, the initialization is done using the CLRDIR application. For example if your C: drive has been assigned to a storage device, you would use `CLRDIR C:` to initialize C: and prepare it hold files. Note that CLRDIR will prompt you for confirmation and you must respond with a **capital** 'Y' to confirm. Once CLDIR has completed, you can copy files onto the drive, for example `COPY *.* C:`. Be very careful to pay attention to your drive letter assignments prior to running CLRDIR to avoid accidentally wiping out a filesystem that has data on it.
To use a disk device, you will need to initialize the directory of the filesystem. On RomWBW, the initialization is done using the CLRDIR application. For example if your C: drive has been assigned to a storage device, you would use `CLRDIR C:` to initialize C: and prepare it hold files. Note that CLRDIR will prompt you for confirmation and you must respond with a **capital** 'Y' to confirm. Once `CLDIR` has completed, you can copy files onto the drive, for example `COPY *.* C:`. Be very careful to pay attention to your drive letter assignments prior to running `CLRDIR` to avoid accidentally wiping out a filesystem that has data on it.
Running CLRDIR on a disk device is roughly equivalent to running FORMAT on MS-DOS. Note that unlike MS-DOS you do **not** partition your mass storage device. CP/M knows nothing about disk partitions. You may notice a partitioning application on your ROM disk (FDISK80), but this is strictly for an advanced technique of adding an MS-DOS FAT filesystem to your media in addition to the CP/M area. Do not use FDISK80 unless you are specifically attempting to add an MS-DOS FAT filesystem to your media.
Running `CLRDIR` on a disk device is roughly equivalent to running FORMAT on MS-DOS. Note that unlike MS-DOS you do **not** partition your mass storage device. CP/M knows nothing about disk partitions. You may notice a partitioning application on your ROM disk (FDISK80), but this is strictly for an advanced technique of adding an MS-DOS FAT filesystem to your media in addition to the CP/M area. Do not use FDISK80 unless you are specifically attempting to add an MS-DOS FAT filesystem to your media.
If you are using a floppy drive, you will need to physically format your floppy disk prior to use. This is only required for floppy disks, not hard disk, CF Cards, or SD Cards, etc. To format a floppy drive, you can use the interactive application FDU. FDU is not terribly user friendly, but is generally documented in the file "FDU.txt" found in the Doc directory of the distribution. It is not necessary to run CLRDIR on a floppy disk after physically formatting it -- the directory is cleared as part of the formatting.
## Booting Disks
If you are using a floppy drive, you will need to physically format your floppy disk prior to use. This is only required for floppy disks, not hard disk, CF Cards, or SD Cards, etc. To format a floppy drive, you can use the interactive application `FDU`. FDU is not terribly user friendly, but is generally documented in the file "FDU.txt" found in the Doc directory of the distribution. It is not necessary to run `CLRDIR` on a floppy disk after physically formatting it -- the directory is cleared as part of the formatting.
Once you have initialized a disk device and copied your desired files onto it, you may want to boot directly to this disk device at startup. On CP/M filesystems, you must perform one additional step to make a disk bootable. Specifically, you need to place a copy of the oeoprating system on the system tracks of the disk. This is done using the `SYSCOPY` command. Let's say you have prepared drive C: by initializing it with `CLRDIR` and copied some files onto it. You can now make C: bootable by running the following command:
Once you have initialized a disk device and copied your desired files onto it, you may want to make the disk bootable. On CP/M filesystems, you must perform one additional step to make a disk bootable. Specifically, you need to place a copy of the operating system on the system tracks of the disk. This is done using the `SYSCOPY` command. Let's say you have prepared drive C: by initializing it with `CLRDIR` and copied some files onto it. You can now make C: bootable by running the following command:
`B>SYSCOPY C:=B:ZSYS.SYS`
`B>SYSCOPY C:=B:ZSYS.SYS`
@ -234,37 +237,13 @@ Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y
Reading image... Writing image... Done
Reading image... Writing image... Done
```
```
After successfully putting the operating system on the disk, you can restart your system. When you get to the boot loader, notice the line starting with "Disk:". This line lists the disk devices that you can choose to boot directly.
You will notice that you do not have an option to boot a drive letter here (like C:). This is because the operating system is not yet loaded. When you ran `SYSCOPY` previously, remember that C: was assigned to IDE0:0 which means device IDE0, slice 0. So, to boot the disk that you just setup with SYSCOPY, you would choose option 1. You will then be prompted for the slice on IDE0 that you want to boot. For now, just press enter to choose slice 0. Once you are familiar with slices, you can `SYSCOPY` and boot alternate slices. Here is what you would see when booting to a disk device:
```
MARK IV Boot Loader
ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM
Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1
Boot Selection? 2 Slice(0-9)[0]?
Booting Disk Unit 2, Slice 0...
Reading disk information...
Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive
Loading...
```
Following this, you would see the normal operating system startup messages. However, your operating system prompt will be `A>` and when you look at the drive letter assignments, you should see that A: has been assigned to the disk you selected to boot.
If you receive the error message "Disk not bootable!", you have either failed to properly run `SYSCOPY` on the target disk or you have selected the wrong disk/slice.
Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed in the Disk boot line, they are not currently "bootable" disks because they have no system tracks on them. Attempting to boot to one of them, will fail with a "Disk not bootable!" error message and return to the loader prompt.
Once this process succeeds, you will be able to boot directly to the disk from the boot loader prompt. See the instructions in Booting Disks for details on this.
## Disk Images
## Disk Images
As mentioned previously, RomWBW includes a variety of disk images that contain a full set of applications for the operating systems supported. It is generally easier to use these disk images instead of copying all the files over using XModem. You use your modern computer (Windows, Linux, MacOS) to place the disk image onto the disk media, then just move the media over to your system. In this scenario you **do not** run `CLRDIR` or `SYSCOPY` on the drive(s). The directory prepared and the disk is already bootable, if it is an operating system.
As mentioned previously, RomWBW includes a variety of disk images that contain a full set of applications for the operating systems supported. It is generally easier to use these disk images instead of copying all the files over using XModem. You use your modern computer (Windows, Linux, MacOS) to place the disk image onto the disk media, then just move the media over to your system. In this scenario you **do not** run `CLRDIR` or `SYSCOPY` on the drive(s). The directory is prepared and the disk is already bootable, if it is an operating system boot disk image.
To copy the disk image files onto your actual media (floppy disk, CF Card, SD Card, etc.), you need to use an image writing utility on your modern computer. Your modern computer will need to have an appropriate interface or slot that accepts the media. To actually copy the image, you can use the `dd` command on Linux or MacOS. On Windows, in the "Tools" directory of the distribution there are two tools you can use. For floppy media, you can use RawWriteWin and for hard disk media, you can use Win32DiskImager. In all cases, the image file should be written to the media starting at the very first block or sector of the media. This will destroy any other data on the media.
To copy the disk image files onto your actual media (floppy disk, CF Card, SD Card, etc.), you need to use an image writing utility on your modern computer. Your modern computer will need to have an appropriate interface or slot that accepts the media. To actually copy the image, you can use the `dd` command on Linux or MacOS. On Windows, in the "Tools" directory of the distribution there are two tools you can use. For floppy media, you can use RawWriteWin and for hard disk media, you can use Win32DiskImager. In all cases, the image file should be written to the media starting at the very first block or sector of the media. This will **destroy** any other data on the media.
The disk image files are found in the Binary directory of the distribution. Floppy disk images are prefixed with "fd_" and hard disk images are prefixed with "hd_". The floppy images are specifically for 1.44M floppy media only. Each disk image has the complete set of normal applications and tools distributed with the associated operating system or application suite.
The disk image files are found in the Binary directory of the distribution. Floppy disk images are prefixed with "fd_" and hard disk images are prefixed with "hd_". The floppy images are specifically for 1.44M floppy media only. Each disk image has the complete set of normal applications and tools distributed with the associated operating system or application suite.
@ -272,11 +251,11 @@ The following table shows the disk image files available. Note that the images
| fd_zsdos.img | hd_zsdos.img | ZSDOS 1.1 boot disk |
| fd_nzcom.img | hd_nzcom.img | NZCOM boot disk |
| fd_cpm3 | hd_cpm3.img | DRI CP/M 3 boot disk |
| fd_zpm3 | hd_zpm3.img | ZPM3 boot disk |
| fd_ws4 | hd_ws4.img | WordStar v4 application disk |
| fd_ws4 | hd_ws4.img | WordStar v4 application disk |
In addition to the disk images above, there is also a special hard disk image called hd_combo.img. This image contains all of the images above, but in a single image with 6 slices (see below for information on disk slices). At the boot loader prompt, you can choose a disk with the combo image, then select the specific slice you want. This allows a single disk to have all of the possible operating system options.
In addition to the disk images above, there is also a special hard disk image called hd_combo.img. This image contains all of the images above, but in a single image with 6 slices (see below for information on disk slices). At the boot loader prompt, you can choose a disk with the combo image, then select the specific slice you want. This allows a single disk to have all of the possible operating system options.
@ -296,13 +275,41 @@ Note that unlike the ROM firmware, you do **not** need to choose a disk image sp
All of the disk images that indicate they are bootable (boot disk) will boot from disk as is. You do not need to run `SYSCOPY` on them to make them bootable. However, if you upgrade your ROM, you should use `SYSCOPY` to update the system tracks.
All of the disk images that indicate they are bootable (boot disk) will boot from disk as is. You do not need to run `SYSCOPY` on them to make them bootable. However, if you upgrade your ROM, you should use `SYSCOPY` to update the system tracks.
## Booting Disks
When starting your system, following the hardware initialization, you will see the Boot Loader prompt. In addition, to the ROM boot options, you will see another line listing the Disk boot options. This line lists the disk devices that you can choose to boot directly.
You will notice that you do not have an option to boot a drive letter here (like C:). This is because the operating system is not yet loaded. When you ran `SYSCOPY` previously, remember that C: was assigned to IDE0:0 which means device IDE0, slice 0. So, to boot the disk that you just setup with `SYSCOPY`, you would choose option 1. You will then be prompted for the slice on IDE0 that you want to boot. For now, just press enter to choose slice 0. Once you are familiar with slices, you can `SYSCOPY` and boot alternate slices. Here is what you would see when booting to a disk device:
```
MARK IV Boot Loader
ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM
Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1
Boot Selection? 2 Slice(0-9)[0]?
Booting Disk Unit 2, Slice 0...
Reading disk information...
Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive
Loading...
```
Following this, you would see the normal operating system startup messages. However, your operating system prompt will be `A>` and when you look at the drive letter assignments, you should see that A: has been assigned to the disk you selected to boot.
If you receive the error message "Disk not bootable!", you have either failed to properly run `SYSCOPY` on the target disk or you have selected the wrong disk/slice.
Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed in the Disk boot line, they are not "bootable" disks because they have no system tracks on them. Attempting to boot to one of them, will fail with a "Disk not bootable!" error message and return to the loader prompt.
# General Usage
# General Usage
Each of the operating systems and ROM applications included with RomWBW are sophisticated tools in their own right. It is not reasonable to document their usage here. However, you will find complete manuals in PDF format in the Doc directory of the distribution. The intention of this section is to document the RomWBW specific enhancements to these OSes.
Each of the operating systems and ROM applications included with RomWBW are sophisticated tools in their own right. It is not reasonable to document their usage here. However, you will find complete manuals in PDF format in the Doc directory of the distribution. The intention of this section is to document the RomWBW specific enhancements to these operating systems.
## ROM Disk
## ROM Disk
In addition to the ROM-based operating systems and applications, the ROM also contains a ROM disk with a small CP/M filesystem. The contents have been optimized to provide a core set of tools and applications that are helpful for either CP/M 2.2 and ZSDOS. Since ZSDOS is CP/M 2.2 compatible, this works fairly well. However, you will find some files on the ROM disk that will work with ZSDOS, but will not work on CP/M 2.2. For example, `LDDS`, which loads the ZSDOS date/time stamper will only run on ZSDOS.
In addition to the ROM-based operating systems and applications, the ROM also contains a ROM disk with a small CP/M filesystem. The contents of the ROM disk have been chosen to provide a core set of tools and applications that are helpful for either CP/M 2.2 or ZSDOS. Since ZSDOS is CP/M 2.2 compatible, this works fairly well. However, you will find some files on the ROM disk that will work with ZSDOS, but will not work on CP/M 2.2. For example, `LDDS`, which loads the ZSDOS date/time stamper will only run on ZSDOS.
## Drive Letter Assignment
## Drive Letter Assignment
@ -318,25 +325,25 @@ When performing a ROM boot of an operating system, note that A: will be your RAM
The vintage operating systems included with RomWBW were produced at a time when mass storage devices were quite small. CP/M 2.2 could only handle filesystems up to 8MB. In order to achieve compatibility across all of the operating systems supported by RomWBW, the hard disk filesystem format used is 8MB. This ensures any filesystem will be accessible to any of the operating systems.
The vintage operating systems included with RomWBW were produced at a time when mass storage devices were quite small. CP/M 2.2 could only handle filesystems up to 8MB. In order to achieve compatibility across all of the operating systems supported by RomWBW, the hard disk filesystem format used is 8MB. This ensures any filesystem will be accessible to any of the operating systems.
Since storage devices today are quite large, RomWBW implements a mechanism called slicing to allow up to 256 8MB filesystems on a single large storage device. This allows up to 2GB of useable space on a single media. You can think of slices as a way to refer to the first 256 8MB chunks of space on a single media.
Since storage devices today are quite large, RomWBW implements a mechanism called slicing to allow up to 256 8MB filesystems on a single large storage device. This allows up to 2GB of useable space on a single media. You can think of slices as a way to refer to any of the first 256 8MB chunks of space on a single media.
Of course, the problem is that CP/M-like operating systems have only 16 drive letters (A:-P:) available. Under the covers, RomWBW allows you to use any drive letter to refer to any slice of any media. The `ASSIGN` command is provided to allow you to view or change the drive letter mappings at any time. At startup, the operating system will automatically allocate a reasonable number of drive letters to the available storage devices. The allocation will depend on the number of large storage devices available at boot. For example, if you have only one hard disk type media, you will see that 8 drive letters are assigned to the first 8 slices of that media. If you have two large storage devices, you will see that each device is allocated four drive letters.
Of course, the problem is that CP/M-like operating systems have only 16 drive letters (A:-P:) available. Under the covers, RomWBW allows you to use any drive letter to refer to any slice of any media. The `ASSIGN` command is provided to allow you to view or change the drive letter mappings at any time. At startup, the operating system will automatically allocate a reasonable number of drive letters to the available storage devices. The allocation will depend on the number of large storage devices available at boot. For example, if you have only one hard disk type media, you will see that 8 drive letters are assigned to the first 8 slices of that media. If you have two large storage devices, you will see that each device is allocated four drive letters.
Referring to slices within a storage device is done by appending a :n where n is the device relative slice number from 0-255. For example, if you have an IDE device, it will show up as IDE0: in the boot message meaning the first IDE device. To refer to the second slice of IDE0, you would type "IDE0:1". So, if I wanted to use drive letter L: to refer to the second slice of IDE0, I could use the command `ASSIGN L:=IDE0:1`.
Referring to slices within a storage device is done by appending a :n where n is the device relative slice number from 0-255. For example, if you have an IDE device, it will show up as IDE0: in the boot messages meaning the first IDE device. To refer to the fourth slice of IDE0, you would type "IDE0:3". So, if I wanted to use drive letter L: to refer to the fourth slice of IDE0, I could use the command `ASSIGN L:=IDE0:3`.
There are a couple of rules to be aware of when assigning drive letters. First, you may only refer to a specific device/slice with one drive letter. Said another way, you cannot have multiple drive letters referring to a single device/slice at the same time. Second, there must always be a drive assigned to A:. Any attempt to violate these rules will be blocked by the `ASSIGN` command.
There are a couple of rules to be aware of when assigning drive letters. First, you may only refer to a specific device/slice with one drive letter. Said another way, you cannot have multiple drive letters referring to a single device/slice at the same time. Second, there must always be a drive assigned to A:. Any attempt to violate these rules will be blocked by the `ASSIGN` command.
Unlike MS-DOS partitions, slices are not allocated -- there is no partitioning of slices. Think of every hard disk type device as having a pre-allocated set of 256 8MB slices at the start of the media. You can refer to any of them simply by assigning a drive letter. RomWBW will not check to see if there is anything else on the hard disk in the slice you are referring to, nor will it verify that the hard disk media is large enough to have a slice at the location you refer to. If you attempt to write past the end of your media, you will get an I/O error displayed, so you will know if you make a mistake. There is no tracking of your use of slices -- you will need to keep track of your use of slices yourself.
Unlike MS-DOS partitions, slices are not allocated -- there is no partitioning of slices. Think of every hard disk type device as having a pre-allocated set of 256 8MB slices at the start of the media. You can refer to any of them simply by assigning a drive letter. RomWBW will not check to see if there is anything else on the hard disk in the slice you are referring to, nor will it verify that the hard disk media is large enough to have a slice at the location you refer to. If you attempt to write past the end of your media, you will get an I/O error displayed, so you will know if you make a mistake. There is no tracking of your use of slices -- you will need to keep track of your use of slices yourself.
Nothing automatically initializes a slice as a file system. You must do that yourself using `CLRDIR`. Since CLRDIR works on drive letters, make absolutely sure you know what media and slice are assigned to that drive letter before using `CLRDIR`.
Nothing automatically initializes a slice as a file system. You must do that yourself using `CLRDIR`. Since `CLRDIR` works on drive letters, make absolutely sure you know what media and slice are assigned to that drive letter before using `CLRDIR`.
While it probably obvious, you cannot use slices on any media less than 8MB in size. Specifically, you cannot slice RAM disk, ROM disk, floppy disks, etc.
While it is probably obvious, you cannot use slices on any media less than 8MB in size. Specifically, you cannot slice RAM disks, ROM disks, floppy disks, etc.
# Inbuilt ROM Applications
# Inbuilt ROM Applications
In addition to CP/M 2.2 and Z-System, there are several additional ROM applications that can be launched directly from ROM. These applications are not hosted by an operating system and so they are unable to save files to disk devices.
In addition to CP/M 2.2 and Z-System, there are several ROM applications that can be launched directly from ROM. These applications are not hosted by an operating system and so they are unable to save files to disk devices.
The following options are available at the boot loader prompt:
The following ROM applications are available at the boot loader prompt:
@ -354,7 +361,7 @@ Space is available in the ROM image for the inclusion of other software. Any inb
The operation of the RomWBW hosted operating systems is enhanced through several custom applications. These applications are functional on all of the OS variants included with RomWBW.
The operation of the RomWBW hosted operating systems is enhanced through several custom applications. These applications are functional on all of the OS variants included with RomWBW.
The following custom applications are found on the RomWBW ROM disk and are, therefore, globally available.
The following custom applications are found on the ROM disk and are, therefore, globally available.
@ -368,7 +375,7 @@ The following custom applications are found on the RomWBW ROM disk and are, ther
| FDISK80 | John Coffman's Z80 hard disk partitioning tool. See documentation in Doc directory. |
| FDISK80 | John Coffman's Z80 hard disk partitioning tool. See documentation in Doc directory. |
| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). |
| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). |
| FLASH | Will Sowerbutts' in-situ ROM programming utility. |
| FLASH | Will Sowerbutts' in-situ ROM programming utility. |
| CLRDIR | Format the directory areas of a CP/M disk. |
| CLRDIR | Initialize the directory area of a CP/M disk (Max Scane). |
Some custom applications do not fit on the ROM disk. They are found on the disk image files or the individual files can be found in the Binary\\Apps directory of the distribution.
Some custom applications do not fit on the ROM disk. They are found on the disk image files or the individual files can be found in the Binary\\Apps directory of the distribution.
@ -383,7 +390,7 @@ There is additional documentation on some of these applications at the [RomWBW A
One of the primary goals of RomWBW is to expose a set of generic hardware functions that make it easy to adapt operating systems to any hardware supported by RomWBW. As a result, there are now 5 operating systems that have been adapted to run under RomWBW. The adaptations are identical for all hardware supported by RomWBW because RomWBW hides all hardware specifics from the operating system.
One of the primary goals of RomWBW is to expose a set of generic hardware functions that make it easy to adapt operating systems to any hardware supported by RomWBW. As a result, there are now 5 operating systems that have been adapted to run under RomWBW. The adaptations are identical for all hardware supported by RomWBW because RomWBW hides all hardware specifics from the operating system.
Note that all of the operating systems included with RomWBW support the same basic filesystem format. As as result, a formatted filesystem will be accessible to any operating system. The only possible issue is that if you turn of date/time stamping using the newer OSes, the older OSes will not understand this. Files will not be corrupted, but the date/time stamps may be lost.
Note that all of the operating systems included with RomWBW support the same basic filesystem format. As a result, a formatted filesystem will be accessible to any operating system. The only possible issue is that if you turn on date/time stamping using the newer OSes, the older OSes will not understand this. Files will not be corrupted, but the date/time stamps may be lost.
The following sections briefly describe the operating system options currently available.
The following sections briefly describe the operating system options currently available.
@ -403,7 +410,7 @@ To use, NZCOM, you must run through a simple configuration process. This is wel
## Digital Research CP/M 3
## Digital Research CP/M 3
This is the Digital Research follow-up product to their very popular CP/M 2.2 operating system. While highly compatible with CP/M 2.2, it features many enhancements. It makes better use of banked memory to increase the user program space (TPA). It also has a new suite of support tools and help system.
This is the Digital Research follow-up product to their very popular CP/M 2.2 operating system. While highly compatible with CP/M 2.2, it features many enhancements. It makes direct use of banked memory to increase the user program space (TPA). It also has a new suite of support tools and help system.
Note that to make a CP/M 3 boot disk, you actually place CPMLDR.SYS on the system tracks of the disk. You do not place CPM3.SYS on the system tracks.
Note that to make a CP/M 3 boot disk, you actually place CPMLDR.SYS on the system tracks of the disk. You do not place CPM3.SYS on the system tracks.
@ -411,11 +418,11 @@ Note that to make a CP/M 3 boot disk, you actually place CPMLDR.SYS on the syste
ZPM3 is an interesting combination of the features of both CP/M 3 and ZCPR 3. Essentially, it has the features of and compatibility with both.
ZPM3 is an interesting combination of the features of both CP/M 3 and ZCPR 3. Essentially, it has the features of and compatibility with both.
Like CP/M 3, to make ZPM3 boot disk, you put CPM3.SYS on the system tracks of the disk.
Like CP/M 3, to make ZPM3 boot disk, you put CPMLDR.SYS on the system tracks of the disk.
## FreeRTOS
## FreeRTOS
Note that Phillip Stevens has also ported FreeRTOS to run under RomWBW. FreeRTOS is not provided in the RomWBW distribution, but is available from Phillip.
Note that Phillip Stevens has also ported FreeRTOS to run under RomWBW. FreeRTOS is not provided in the RomWBW distribution. You can contact Phillip for availability.
# Transferring Files
# Transferring Files
@ -427,9 +434,9 @@ RomWBW provides an serial file transfer program called XModem that has been adap
You can type `XM` by itself to get usage information. In general, you will run `XM` with parameters to indicate you want to send or receive a file on your RomWBW system. Then, you will use your modern computers terminal program to complete the process.
You can type `XM` by itself to get usage information. In general, you will run `XM` with parameters to indicate you want to send or receive a file on your RomWBW system. Then, you will use your modern computers terminal program to complete the process.
The `XM` application generally tries to detect the hardware you are using and adapt to it. However, you must ensure that you have a realiable serial connection. You must also ensure that the speed of the connection is not too fast for XModem to handle. Alternatively, you can ensure that hardware flow control is working properly.
The `XM` application generally tries to detect the hardware you are using and adapt to it. However, you must ensure that you have a reliable serial connection. You must also ensure that the speed of the connection is not too fast for XModem to service. Alternatively, you can ensure that hardware flow control is working properly.
There is an odd interaction between XModem and partner terminal programs that can occur. Essentially, after launching `XM`, you must start the protocol on your modern computer fairly quickly (usually about 20 seconds or so). So, if you do not pick a file on your modern computer quickly enough, you will find that the transfer completes about 16K, then hangs. The interaction that casuses this is beyond the scope of this document.
There is an odd interaction between XModem and partner terminal programs that can occur. Essentially, after launching `XM`, you must start the protocol on your modern computer fairly quickly (usually in about 20 seconds or so). So, if you do not pick a file on your modern computer quickly enough, you will find that the transfer completes about 16K, then hangs. The interaction that causes this is beyond the scope of this document.
## Disk Image Transfers
## Disk Image Transfers
@ -442,17 +449,17 @@ The general process to get files from your modern computer to a RomWBW computer
3. Use a disk imaging tool to copy the RomWBW filesystem image onto the media.
3. Use a disk imaging tool to copy the RomWBW filesystem image onto the media.
4. Move the media back to the RomWBW computer.
4. Move the media back to the RomWBW computer.
This process is a little complicated, but it has the benefit of allowing you to get a lot of files over to your RomWBW system quickly and with little change of corruption.
This process is a little complicated, but it has the benefit of allowing you to get a lot of files over to your RomWBW system quickly and with little chance of corruption.
The process can be run in reverse to get files from your RomWBW computer to a modern computer.
The process can be run in reverse to get files from your RomWBW computer to a modern computer.
The exact use of these tools is a bit too much for this document, but the tools are all included in the RomWBW distribution along with usage documents.
The exact use of these tools is a bit too much for this document, but the tools are all included in the RomWBW distribution along with usage documents.
Note that the build scripts for RomWBW create the default disk images supplied with RomWBW. It is relatively easy to customize the contents of the disk images that are part of RomWBW. This is described in more detail in the Source\\Images driectory of the distribution.
Note that the build scripts for RomWBW create the default disk images supplied with RomWBW. It is relatively easy to customize the contents of the disk images that are part of RomWBW. This is described in more detail in the Source\\Images directory of the distribution.
## FAT Filesystem Transfers
## FAT Filesystem Transfers
RomWBW provides a mechanism that allows it to read and write files on an FAT formatted disk. This means that you can generally use your modern computer to make an SD Card or CF Card with a standard FAT32 filesystem on it, then place that media in your RomWBW computer and read/write the files.
RomWBW provides a mechanism that allows it to read and write files on a FAT formatted disk. This means that you can generally use your modern computer to make an SD Card or CF Card with a standard FAT32 filesystem on it, then place that media in your RomWBW computer and access the files.
When formatting the media on your modern computer, but sure to pick the FAT filesystem. NTFS and other filesystems will not work.
When formatting the media on your modern computer, but sure to pick the FAT filesystem. NTFS and other filesystems will not work.
@ -464,19 +471,19 @@ For advanced users, it is possible to create a hybrid disk that contains CP/M sl
# Startup Command Processing
# Startup Command Processing
Each of the operating system supported by RomWBW provide a mechanism to run commands at boot. This is similar to the AUTOEXEC.BAT files from MS-DOS.
Each of the operating systems supported by RomWBW provide a mechanism to run commands at boot. This is similar to the AUTOEXEC.BAT files from MS-DOS.
With the exception of ZPM3, all operating system will look for a file called `PROFILE.SUB` on the system drive at boot. If it is found, it will be processed as a standard CP/M submit file. You can read about the use of the SUBMIT facility in the CP/M manuals included in the RomWBW distribution.
With the exception of ZPM3, all operating systems will look for a file called `PROFILE.SUB` on the system drive at boot. If it is found, it will be processed as a standard CP/M submit file. You can read about the use of the SUBMIT facility in the CP/M manuals included in the RomWBW distribution. Note that the boot disk must also have a copy of `SUBMIT.EXE`.
In the case of ZPM3, the file called `STARTZPM.COM` will be run at boot. To customize this file, you use the ZCPR ALIAS facility. You will need to refer to ZCPR documentation for more information on the ALIAS facility.
In the case of ZPM3, the file called `STARTZPM.COM` will be run at boot. To customize this file, you use the ZCPR ALIAS facility. You will need to refer to ZCPR documentation for more information on the ALIAS facility.
Note that automatic startup processing generally requires booting to a disk drive. Since the ROM disk is not writable, there is no simple way to add/edit a `PROFILE.SUB` file there. If you want to customize your ROM and add a `PROFILE.SUB` file to the ROM Disk, it will work, but is a lot harder than using a boot disk.
Note that the automatic startup processing generally requires booting to a disk drive. Since the ROM disk is not writable, there is no simple way to add/edit a `PROFILE.SUB` file there. If you want to customize your ROM and add a `PROFILE.SUB` file to the ROM Disk, it will work, but is a lot harder than using a boot disk.
# ROM Customization
# ROM Customization
The pre-built ROM images are configured for the basic capabilities of each platform. Additionally, some of the typical add-on hardware for each platform will be automatically detected and used. If you want to go beyond this, RomWBW provides a very flexible configuration mechanism based on configuration files. Creating a customized ROM requires running a build script, but it is quite easy to do.
The pre-built ROM images are configured for the basic capabilities of each platform. Additionally, some of the typical add-on hardware for each platform will be automatically detected and used. If you want to go beyond this, RomWBW provides a very flexible configuration mechanism based on configuration files. Creating a customized ROM requires running a build script, but it is quite easy to do.
Essentially, the creation of a custom ROM is accomplished by updating a small configuration file, then running a script to compile the software and generate the custom ROM image. There are build scripts for Windows, Linux, and MacOS to accommodate virtually all users. All required build tools (compilers, assemblers, etc.) are included in the distribution, so it is not necessary to setup a build environment on your computer.
Essentially, the creation of a custom ROM is accomplished by updating a small configuration file, then running a script to compile the software and generate the custom ROM and disk images. There are build scripts for Windows, Linux, and MacOS to accommodate virtually all users. All required build tools (compilers, assemblers, etc.) are included in the distribution, so it is not necessary to setup a build environment on your computer.
The process for building a custom ROM is documented in the ReadMe.txt file in the Source directory of the distribution.
The process for building a custom ROM is documented in the ReadMe.txt file in the Source directory of the distribution.
@ -503,6 +510,10 @@ Please refer to the [UNA BIOS Firmware Page](https://www.retrobrewcomputers.org/
# RomWBW Distribution
# RomWBW Distribution
All source code and distributions are maintained on GitHub. Code contributions are very welcome.
The RomWBW distribution is a compressed zip archive file organized in a set of directories. Each of these directories has it's own ReadMe.txt file describing the contents in detail. In summary, these directories are:
The RomWBW distribution is a compressed zip archive file organized in a set of directories. Each of these directories has it's own ReadMe.txt file describing the contents in detail. In summary, these directories are:
@ -514,12 +525,6 @@ The RomWBW distribution is a compressed zip archive file organized in a set of d
| Source | Contains the source code files used to build the software and ROM images. |
| Source | Contains the source code files used to build the software and ROM images. |
| Tools | Contains the MS Windows programs that are used by the build process or that may be useful in setting up your system. |
| Tools | Contains the MS Windows programs that are used by the build process or that may be useful in setting up your system. |
## Source Code Respository
All source code and distributions are maintained on GitHub. Code contributions are very welcome.
While I have heavily modified much of the code, I want to acknowledge that much of the work is derived from the work of others in the RetroBrew Computers Community including Andrew Lynch, Dan Werner, Max Scane, David Giles, John Coffman, and probably many others I am not clearly aware of (let me know if I omitted someone!).
While I have heavily modified much of the code, I want to acknowledge that much of the work is derived from the work of others in the RetroBrew Computers Community including Andrew Lynch, Dan Werner, Max Scane, David Giles, John Coffman, and probably many others I am not clearly aware of (let me know if I omitted someone!).
Wayne Warthen
6 years ago