diff --git a/Doc/RomWBW Applications.pdf b/Doc/RomWBW Applications.pdf index 6e3218f9..089bf13e 100644 Binary files a/Doc/RomWBW Applications.pdf and b/Doc/RomWBW Applications.pdf differ diff --git a/Doc/RomWBW Architecture.pdf b/Doc/RomWBW Architecture.pdf index 20519073..bf265d6f 100644 Binary files a/Doc/RomWBW Architecture.pdf and b/Doc/RomWBW Architecture.pdf differ diff --git a/Doc/RomWBW Getting Started.pdf b/Doc/RomWBW Getting Started.pdf index fe58443a..af4b1e8e 100644 Binary files a/Doc/RomWBW Getting Started.pdf and b/Doc/RomWBW Getting Started.pdf differ diff --git a/ReadMe.md b/ReadMe.md index 84ccad26..896b2148 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -45,8 +45,8 @@ 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) + - System Monitor + - Operating Systems (CP/M 2.2, ZSDOS) - ROM BASIC (Nascom BASIC and Tasty BASIC) - ROM Forth @@ -55,8 +55,8 @@ operating system drive letters to any available disk media. Additionally, mass media devices (IDE Disk, CF Card, SD Card) 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 -providing up to 2GB of accessible storage on a single device. +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 optimal for most users. However, it is also very easy to modify and build custom ROM images that @@ -109,7 +109,7 @@ 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 appropriate ROM image for your hardware. | Platform | ROM Image File | Baud | Description | | ------------- | --------------- | -----: | ----------------------------------------------- | @@ -156,9 +156,9 @@ choose a ROM-based operating system, system monitor, application, or boot from a disk device. Initially, you should try the ROM boot options. By selecting either CP/M -2.2 or Z-System, the operating system will be loaded from ROM and you -will see the a `B>` disk prompt. In this scenario, A: will be an empty -RAM disk and B: will refer to your ROM disk containing some typical +2.2 or Z-System, the selected operating system will be loaded from ROM +and you will see the a `B>` disk prompt. In this scenario, A: will be an +empty RAM disk and B: will refer to your ROM disk containing some common applications. This provides a simple environment for learning to use your system. Be aware that files saved to the RAM disk (A:) will disappear at the next power on (RAM is generally not persistent). Also @@ -169,33 +169,34 @@ ROM is not writable. 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 +your system and a ROM programmer, it is always safest to retain 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 mechanism to start your system. +“try” the upgrade. With RomWBW, you can upload a new system image +executable 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 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 +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 +ROM image is 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. @@ -242,7 +243,7 @@ If you wish to update existing disk media in your system, you need to perform the following steps. If the disk is bootable, you need to update the system tracks of the -disk. This is done using a SYSCOPY command such as `SYSCOPY +disk.This is done using a SYSCOPY command such as `SYSCOPY C:=B:ZSYS.SYS`. For a ZSDOS boot disk, use ZSYS.SYS. For a CP/M 2.2 disk, use CPM.SYS. For a CP/M 3 or ZPM3 disk, use CPMLDR.SYS. CPMLDR.SYS is not provided on the ROM disk, so you would need to upload it from the @@ -254,33 +255,299 @@ following applications are found on your ROM disk. Use COPY to copy them over any older versions of the app on your disk: - ASSIGN.COM - - FORMAT.COM - - OSLDR.COM - SYSCOPY.COM - - TALK.COM + - MODE.COM - FDU.COM (was FDTST.COM) + - OSLDR.COM + - FORMAT.COM - XM.COM - - MODE.COM + - FLASH.COM + - FDISK80.COM + - TALK.COM - RTC.COM - TIMER.COM - INTTEST.COM For example: `B>COPY ASSIGN.COM C:` +Some RomWBW custom applications are too large to fit on the ROM disk. If +you are using any of these you will need to transfer them to your system +and then update all copies. These applications are found in the +Binary\\Apps directory of the distribution and in all of the disk +images. + + - FAT.COM + - TUNE.COM + +# 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 +operating systems. + +## Inbuilt ROM Applications + +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 ROM applications are available at the boot loader prompt: + +| Application | | +| ----------- | ------------------------------------------------------ | +| Monitor | Z80 system debug monitor w/ Intel Hex loader | +| Forth | Brad Rodriguez’s ANSI compatible Forth language | +| Basic | Nascom 8K BASIC language | +| Tasty BASIC | Dimitri Theuling’s Tiny BASIC implementation | +| Play | A simple video game (requires ANSI terminal emulation) | + +In general, the command to exit these applications and restart the +system is `BYE`. The exceptions are the Monitor which uses `B` and Play +which uses `Q`. + +Space is available in the ROM image for the inclusion of other software. +Any inbuilt application can be set up to launch automatically at +startup. + +## Devices and Units + +In order to support a wide variety of hardware, RomWBW HBIOS uses a +modular approach to implementing device drivers and presenting devices +to the operating system. In general, all devices are classified as one +of the following: + + - Disk (Hard Disk, CF Card, SD Card, RAM/ROM Disk, etc.) + - Character (Serial Ports, Parallel Ports, etc.) + - Video (Video Display/Keyboard Interfaces) + - RTC/NVRAM (Real Time Clock, Non-volatile RAM) + +HBIOS uses the concept of unit numbers to present a complex set of +hardware devices to the operating system. As an example, a typical +system might have a ROM Disk, RAM Disk, Floppy Drives, and Disk Drives. +All of these are considered Disk devices and are presented to the +operating system as generic block devices. This means that the operating +system does not need to understand the difference between a floppy drive +and a ROM disk. + +As RomWBW boots, it assigns a unit number to each device. This unit +number is used by the operating system to refer to the device. It is, +therefore, important to know the unit number assigned to each device. +This information is displayed in the unit summary table at startup. Here +is an example: + + Unit Device Type Capacity/Mode + ---------- ---------- ---------------- -------------------- + Char 0 UART0: RS-232 38400,8,N,1 + Char 1 UART1: RS-232 38400,8,N,1 + Disk 0 MD1: RAM Disk 384KB,LBA + Disk 1 MD0: ROM Disk 384KB,LBA + Disk 2 FD0: Floppy Disk 3.5",DS/HD,CHS + Disk 3 FD1: Floppy Disk 3.5",DS/HD,CHS + Disk 4 IDE0: CompactFlash 3815MB,LBA + Disk 5 IDE1: Hard Disk -- + Disk 6 PRPSD0: SD Card 1886MB,LBA + Video 0 CVDU0: CRT Text,80x25 + +In this example, you can see that the system has a total of 7 Disk Units +numbered 0-6. There are also 2 Character Units and 1 Video Unit. The +table shows the unit numbers assigned to each of the devices. Notice how +the unit numbers are assigned sequentially regardless of the specific +device. + +There may or may not be media in the disk devices listed. For example, +the floppy disk devices (Disk Units 2 & 3) may not have a floppy in the +drive. Also note that Disk Unit 4 shows a disk capacity, but Disk Unit 5 +does not. This is because the PPIDE interface of the system supports up +to two drives, but there is only one actual drive attached. A unit +number is assigned to all possible devices regardless of whether they +have actual media installed at boot time. + +Note that Character Unit 0 is **always** the initial system console by +definition. + +If your system has an RTC/NVRAM device, it will not be listed in the +unit summary table. Since only a single RTC/NVRAM device can exist in +one system, unit numbers are not required nor used for this type of +device. + +## Drive Letter Assignment + +In legacy CP/M-type operating systems, drive letters were generally +mapped to disk drives in a completely fixed way. For example, drive A: +would **always** refer to the first floppy drive. Since RomWBW supports +a wide variety of hardware configurations, it implements a much more +flexible drive letter assignment mechanism so that any drive letter can +be assigned to any disk device. + +At boot, you will notice that RomWBW automatically assigns drive letters +to the available disk devices. These assignments are displayed during +the startup of the selected operating system. Additionally, you can +review the current drive assignments at any time using the `ASSIGN` +command. CP/M 3 and ZPM3 do not automatically display the assignments at +startup, but you can use `ASSIGN` do display them. + +The drive letter assignments **do not** change during an OS session +unless you use the `ASSIGN` command yourself to do it. Additionally, the +assignments at boot will stay the same on each boot as long as you do +not make changes to your hardware configuration. Note that the +assignments **are** dependent on the media currently inserted in hard +disk drives. So, notice that if you insert or remove an SD Card or CF +Card, the drive assignments will change. Since drive letter assignments +can change, you must be careful when doing destructive things like using +`CLRDIR` to make sure the drive letter you use is referring to the +desired media. + +When performing a ROM boot of an operating system, note that A: will be +your RAM disk and B: will be your ROM disk. When performing a disk boot, +the disk you are booting from will be assigned to A: and the rest of the +drive letters will be offset to accommodate this. This is done because +most legacy operating systems expect that A: will be the boot drive. + +## Slices + +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 usable 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 allows 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 : +** where ** 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”. Here are some examples: + +| | | +| -------- | ---------------------------- | +| `IDE0:0` | First slice of disk in IDE0 | +| `IDE0:` | First slice of disk in IDE0 | +| `IDE0:3` | Fourth slice of disk in IDE0 | + +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. + +Unlike MS-DOS partitions, slices are not allocated – there is no +partitioning for 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`. + +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. + +# RomWBW Custom Applications + +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 ROM disk and are, +therefore, globally available. + +| Application | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| ASSIGN | Add, change, and delete drive letter assignments. Use ASSIGN /? for usage instructions. | +| SYSCOPY | Copy system image to a device to make it bootable. Use SYSCOPY with no parms for usage instructions. | +| FDU | Format and test floppy disks. Menu driven interface. | +| OSLDR | Load a new OS on the fly. For example, you can switch to Z-System when running CP/M. Use OSLDR with no parms for usage instructions. | +| FORMAT | Will someday be a command line tool to format floppy disks. Currently does nothing\! | +| MODE | Reconfigures serial ports dynamically. | +| XM | XModem file transfer program adapted to hardware. Automatically uses primary serial port on system. | +| 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). | +| FLASH | Will Sowerbutts’ in-situ ROM programming utility. | +| 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. + +| Application | Description | +| ----------- | ----------------------------------------------------------- | +| TUNE | Play .PT2, .PT3, .MYM audio files. | +| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). | + +There is additional documentation on some of these applications at the +[RomWBW Applications +Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps). + # Using Disks +## ROM & RAM Disks + +RomWBW utilizes a portion of the ROM and RAM memory in your system to +implement small memory-based disks. + +The RAM disk provides a small CP/M filesystem that you can use for the +temporary storage of files. Unless your system has a battery backed +mechanism for persisting your RAM contents, the RAM disk contents will +be lost at each power-off. However, the RAM disk is an excellent choice +for storing temporary files because it is very fast. + +Like the RAM disk, the ROM disk also provides a small CP/M filesystem, +but it’s contents are static – they are part of the ROM. As such, you +cannot save files to the ROM disk. Any attempt to do this will result in +a disk I/O error. 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. + +## Disk Devices + 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 for your specific -options. +disk media. A wide variety of disk devices are supported 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. +In the RomWBW boot 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 @@ -311,11 +578,11 @@ an example of this: D:=IDE0:1 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 +assignment process is described above in the Drive Letter Assignment +section. 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. @@ -324,17 +591,17 @@ 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. +is described above in the Slices section. 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 (see Transferring Files). +One option is to 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 @@ -447,10 +714,10 @@ well as real spinning hard disks. 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. +but in a single image with 6 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. This is the layout of the hd\_combo disk image: @@ -487,7 +754,7 @@ 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 +just setup with `SYSCOPY`, you would choose option 2. 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 @@ -522,181 +789,6 @@ 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 - -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 - -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 - -In legacy CP/M-type operating systems, drive letters were generally -mapped to disk drives in a completely fixed way. For example, drive A: -would **always** refer to the first floppy drive. Since RomWBW supports -a wide variety of hardware configurations, it implements a much more -flexible drive letter assignment mechanism so that any drive letter can -be assigned to any disk device. - -At boot, you will notice that RomWBW automatically assigns drive letters -to the available disk devices. These assignments are displayed during -the startup of the selected operating system. Additionally, you can -review the current drive assignments at any time using the `ASSIGN` -command. CP/M 3 and ZPM3 do not automatically display the assignments at -startup, but you can use `ASSIGN` do display them. - -The drive letter assignments **do not** change during an OS session -unless you use the `ASSIGN` command yourself to do it. Additionally, the -assignments at boot will stay the same on each boot as long as you do -not make changes to your hardware configuration. Note that the -assignments **are** dependent on the media currently inserted in hard -disk drives. So, notice that if you insert or remove an SD Card or CF -Card, the drive assignments will change. Since drive letter assignments -can change, you must be careful when doing destructive things like using -`CLRDIR` to make sure the drive letter you use is referring to the -desired media. - -When performing a ROM boot of an operating system, note that A: will be -your RAM disk and B: will be your ROM disk. When performing a disk boot, -the disk you are booting from will be assigned to A: and the rest of the -drive letters will be offset to accommodate this. This is done because -most legacy operating systems expect that A: will be the boot drive. - -## Slices - -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 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. - -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. - -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`. - -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 - -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 ROM applications are available at the boot loader prompt: - -| Application | | -| ----------- | ------------------------------------------------------ | -| Monitor | Z80 system debug monitor w/ Intel Hex loader | -| Forth | Brad Rodriguez’s ANSI compatible Forth language | -| Basic | Nascom 8K BASIC language | -| Tasty BASIC | Dimitri Theuling’s Tiny BASIC implementation | -| Play | A simple video game (requires ANSI terminal emulation) | - -In general, the command to exit these applications and restart the -system is `BYE`. The exceptions are the Monitor which uses `B` and Play -which uses `Q`. - -Space is available in the ROM image for the inclusion of other software. -Any inbuilt application can be set up to launch automatically at -startup. - -# RomWBW Custom Applications - -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 ROM disk and are, -therefore, globally available. - -| Application | Description | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| ASSIGN | Add, change, and delete drive letter assignments. Use ASSIGN /? for usage instructions. | -| SYSCOPY | Copy system image to a device to make it bootable. Use SYSCOPY with no parms for usage instructions. | -| FDU | Format and test floppy disks. Menu driven interface. | -| OSLDR | Load a new OS on the fly. For example, you can switch to Z-System when running CP/M. Use OSLDR with no parms for usage instructions. | -| FORMAT | Will someday be a command line tool to format floppy disks. Currently does nothing\! | -| MODE | Reconfigures serial ports dynamically. | -| XM | XModem file transfer program adapted to hardware. Automatically uses primary serial port on system. | -| 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). | -| FLASH | Will Sowerbutts’ in-situ ROM programming utility. | -| 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. - -| Application | Description | -| ----------- | ----------------------------------------------------------- | -| TUNE | Play .PT2, .PT3, .MYM audio files. | -| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). | - -There is additional documentation on some of these applications at the -[RomWBW Applications -Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps). - # Operating Systems One of the primary goals of RomWBW is to expose a set of generic @@ -833,10 +925,13 @@ computer is: 1. Use `cpmtools` on your modern computer to create a RomWBW CP/M filesystem image. + 2. Insert your RomWBW media (CF Card, SD Card, or floppy disk) in your modern computer. + 3. Use a disk imaging tool to copy the RomWBW filesystem image onto the media. + 4. Move the media back to the RomWBW computer. This process is a little complicated, but it has the benefit of allowing @@ -863,7 +958,7 @@ 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 +When formatting the media on your modern computer, be sure to pick the FAT filesystem. NTFS and other filesystems will not work. On your RomWBW computer you can use the `FAT` application to access the @@ -1014,7 +1109,8 @@ applications are no longer provided. list of general code enhancements. - Phillip Stevens contributed support for FreeRTOS. - Curt Mayer contributed the Linux / MacOS build process. - - UNA BIOS is a product of John Coffman. + - UNA BIOS and FDISK80 is a product of John Coffman. + - FLASH4 is a product of Will Sowerbutts. Contributions of all kinds to RomWBW are very welcome. diff --git a/ReadMe.txt b/ReadMe.txt index 160add5e..d0f9a7d7 100644 --- a/ReadMe.txt +++ b/ReadMe.txt @@ -41,8 +41,8 @@ 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) +- System Monitor +- Operating Systems (CP/M 2.2, ZSDOS) - ROM BASIC (Nascom BASIC and Tasty BASIC) - ROM Forth @@ -51,8 +51,8 @@ operating system drive letters to any available disk media. Additionally, mass media devices (IDE Disk, CF Card, SD Card) 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 -providing up to 2GB of accessible storage on a single device. +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 optimal for most users. However, it is also very easy to modify and build custom ROM images that @@ -103,7 +103,7 @@ 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: +appropriate ROM image for your hardware. -------------------------------------------------------------------------- Platform ROM Image File Baud Description @@ -169,9 +169,9 @@ choose a ROM-based operating system, system monitor, application, or boot from a disk device. Initially, you should try the ROM boot options. By selecting either CP/M -2.2 or Z-System, the operating system will be loaded from ROM and you -will see the a B> disk prompt. In this scenario, A: will be an empty RAM -disk and B: will refer to your ROM disk containing some typical +2.2 or Z-System, the selected operating system will be loaded from ROM +and you will see the a B> disk prompt. In this scenario, A: will be an +empty RAM disk and B: will refer to your ROM disk containing some common applications. This provides a simple environment for learning to use your system. Be aware that files saved to the RAM disk (A:) will disappear at the next power on (RAM is generally not persistent). Also @@ -182,33 +182,34 @@ Upgrading 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 +your system and a ROM programmer, it is always safest to retain 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 mechanism to start your system. +“try” the upgrade. With RomWBW, you can upload a new system image +executable 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 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 +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 +ROM image is 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. @@ -255,11 +256,10 @@ If you wish to update existing disk media in your system, you need to perform the following steps. If the disk is bootable, you need to update the system tracks of the -disk. This is done using a SYSCOPY command such as -SYSCOPY C:=B:ZSYS.SYS. For a ZSDOS boot disk, use ZSYS.SYS. For a CP/M -2.2 disk, use CPM.SYS. For a CP/M 3 or ZPM3 disk, use CPMLDR.SYS. -CPMLDR.SYS is not provided on the ROM disk, so you would need to upload -it from the distribution. +disk.This is done using a SYSCOPY command such as SYSCOPY C:=B:ZSYS.SYS. +For a ZSDOS boot disk, use ZSYS.SYS. For a CP/M 2.2 disk, use CPM.SYS. +For a CP/M 3 or ZPM3 disk, use CPMLDR.SYS. CPMLDR.SYS is not provided on +the ROM disk, so you would need to upload it from the distribution. Finally, if you have copies of any of the RomWBW custom applications on your hard disk, you need to update them with the latest copies. The @@ -267,33 +267,316 @@ following applications are found on your ROM disk. Use COPY to copy them over any older versions of the app on your disk: - ASSIGN.COM -- FORMAT.COM -- OSLDR.COM - SYSCOPY.COM -- TALK.COM +- MODE.COM - FDU.COM (was FDTST.COM) +- OSLDR.COM +- FORMAT.COM - XM.COM -- MODE.COM +- FLASH.COM +- FDISK80.COM +- TALK.COM - RTC.COM - TIMER.COM - INTTEST.COM For example: B>COPY ASSIGN.COM C: +Some RomWBW custom applications are too large to fit on the ROM disk. If +you are using any of these you will need to transfer them to your system +and then update all copies. These applications are found in the +Binary\Apps directory of the distribution and in all of the disk images. + +- FAT.COM +- TUNE.COM + +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 +operating systems. + +Inbuilt ROM Applications + +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 ROM applications are available at the boot loader prompt: + + Application + ------------- -------------------------------------------------------- + Monitor Z80 system debug monitor w/ Intel Hex loader + Forth Brad Rodriguez’s ANSI compatible Forth language + Basic Nascom 8K BASIC language + Tasty BASIC Dimitri Theuling’s Tiny BASIC implementation + Play A simple video game (requires ANSI terminal emulation) + +In general, the command to exit these applications and restart the +system is BYE. The exceptions are the Monitor which uses B and Play +which uses Q. + +Space is available in the ROM image for the inclusion of other software. +Any inbuilt application can be set up to launch automatically at +startup. + +Devices and Units + +In order to support a wide variety of hardware, RomWBW HBIOS uses a +modular approach to implementing device drivers and presenting devices +to the operating system. In general, all devices are classified as one +of the following: + +- Disk (Hard Disk, CF Card, SD Card, RAM/ROM Disk, etc.) +- Character (Serial Ports, Parallel Ports, etc.) +- Video (Video Display/Keyboard Interfaces) +- RTC/NVRAM (Real Time Clock, Non-volatile RAM) + +HBIOS uses the concept of unit numbers to present a complex set of +hardware devices to the operating system. As an example, a typical +system might have a ROM Disk, RAM Disk, Floppy Drives, and Disk Drives. +All of these are considered Disk devices and are presented to the +operating system as generic block devices. This means that the operating +system does not need to understand the difference between a floppy drive +and a ROM disk. + +As RomWBW boots, it assigns a unit number to each device. This unit +number is used by the operating system to refer to the device. It is, +therefore, important to know the unit number assigned to each device. +This information is displayed in the unit summary table at startup. Here +is an example: + + Unit Device Type Capacity/Mode + ---------- ---------- ---------------- -------------------- + Char 0 UART0: RS-232 38400,8,N,1 + Char 1 UART1: RS-232 38400,8,N,1 + Disk 0 MD1: RAM Disk 384KB,LBA + Disk 1 MD0: ROM Disk 384KB,LBA + Disk 2 FD0: Floppy Disk 3.5",DS/HD,CHS + Disk 3 FD1: Floppy Disk 3.5",DS/HD,CHS + Disk 4 IDE0: CompactFlash 3815MB,LBA + Disk 5 IDE1: Hard Disk -- + Disk 6 PRPSD0: SD Card 1886MB,LBA + Video 0 CVDU0: CRT Text,80x25 + +In this example, you can see that the system has a total of 7 Disk Units +numbered 0-6. There are also 2 Character Units and 1 Video Unit. The +table shows the unit numbers assigned to each of the devices. Notice how +the unit numbers are assigned sequentially regardless of the specific +device. + +There may or may not be media in the disk devices listed. For example, +the floppy disk devices (Disk Units 2 & 3) may not have a floppy in the +drive. Also note that Disk Unit 4 shows a disk capacity, but Disk Unit 5 +does not. This is because the PPIDE interface of the system supports up +to two drives, but there is only one actual drive attached. A unit +number is assigned to all possible devices regardless of whether they +have actual media installed at boot time. + +Note that Character Unit 0 is always the initial system console by +definition. + +If your system has an RTC/NVRAM device, it will not be listed in the +unit summary table. Since only a single RTC/NVRAM device can exist in +one system, unit numbers are not required nor used for this type of +device. + +Drive Letter Assignment + +In legacy CP/M-type operating systems, drive letters were generally +mapped to disk drives in a completely fixed way. For example, drive A: +would always refer to the first floppy drive. Since RomWBW supports a +wide variety of hardware configurations, it implements a much more +flexible drive letter assignment mechanism so that any drive letter can +be assigned to any disk device. + +At boot, you will notice that RomWBW automatically assigns drive letters +to the available disk devices. These assignments are displayed during +the startup of the selected operating system. Additionally, you can +review the current drive assignments at any time using the ASSIGN +command. CP/M 3 and ZPM3 do not automatically display the assignments at +startup, but you can use ASSIGN do display them. + +The drive letter assignments do not change during an OS session unless +you use the ASSIGN command yourself to do it. Additionally, the +assignments at boot will stay the same on each boot as long as you do +not make changes to your hardware configuration. Note that the +assignments are dependent on the media currently inserted in hard disk +drives. So, notice that if you insert or remove an SD Card or CF Card, +the drive assignments will change. Since drive letter assignments can +change, you must be careful when doing destructive things like using +CLRDIR to make sure the drive letter you use is referring to the desired +media. + +When performing a ROM boot of an operating system, note that A: will be +your RAM disk and B: will be your ROM disk. When performing a disk boot, +the disk you are booting from will be assigned to A: and the rest of the +drive letters will be offset to accommodate this. This is done because +most legacy operating systems expect that A: will be the boot drive. + +Slices + +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 usable 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 allows 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 : +where 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”. Here are some examples: + + -------- ------------------------------ + IDE0:0 First slice of disk in IDE0 + IDE0: First slice of disk in IDE0 + IDE0:3 Fourth slice of disk in IDE0 + -------- ------------------------------ + +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. + +Unlike MS-DOS partitions, slices are not allocated – there is no +partitioning for 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. + +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. + +RomWBW Custom Applications + +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 ROM disk and are, +therefore, globally available. + + -------------------------------------------------------------------------- + Application Description + ------------- ------------------------------------------------------------ + ASSIGN Add, change, and delete drive letter assignments. Use ASSIGN + /? for usage instructions. + + SYSCOPY Copy system image to a device to make it bootable. Use + SYSCOPY with no parms for usage instructions. + + FDU Format and test floppy disks. Menu driven interface. + + OSLDR Load a new OS on the fly. For example, you can switch to + Z-System when running CP/M. Use OSLDR with no parms for + usage instructions. + + FORMAT Will someday be a command line tool to format floppy disks. + Currently does nothing! + + MODE Reconfigures serial ports dynamically. + + XM XModem file transfer program adapted to hardware. + Automatically uses primary serial port on system. + + 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). + + FLASH Will Sowerbutts’ in-situ ROM programming utility. + + 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. + + Application Description + ------------- ------------------------------------------------------------- + TUNE Play .PT2, .PT3, .MYM audio files. + FAT Access MS-DOS FAT filesystems from RomWBW (based on FatFs). + +There is additional documentation on some of these applications at the +RomWBW Applications Page. + Using Disks +ROM & RAM Disks + +RomWBW utilizes a portion of the ROM and RAM memory in your system to +implement small memory-based disks. + +The RAM disk provides a small CP/M filesystem that you can use for the +temporary storage of files. Unless your system has a battery backed +mechanism for persisting your RAM contents, the RAM disk contents will +be lost at each power-off. However, the RAM disk is an excellent choice +for storing temporary files because it is very fast. + +Like the RAM disk, the ROM disk also provides a small CP/M filesystem, +but it’s contents are static – they are part of the ROM. As such, you +cannot save files to the ROM disk. Any attempt to do this will result in +a disk I/O error. 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. + +Disk Devices + 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 for your specific -options. +disk media. A wide variety of disk devices are supported 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. +In the RomWBW boot 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 @@ -324,11 +607,11 @@ an example of this: D:=IDE0:1 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 +assignment process is described above in the Drive Letter Assignment +section. 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. @@ -337,17 +620,17 @@ 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. +is described above in the Slices section. 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 (see Transferring Files). +One option is to 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 @@ -459,10 +742,10 @@ well as real spinning hard disks. 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. +but in a single image with 6 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. This is the layout of the hd_combo disk image: @@ -499,7 +782,7 @@ 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 +setup with SYSCOPY, you would choose option 2. 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 @@ -534,199 +817,6 @@ 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 - -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 - -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 - -In legacy CP/M-type operating systems, drive letters were generally -mapped to disk drives in a completely fixed way. For example, drive A: -would always refer to the first floppy drive. Since RomWBW supports a -wide variety of hardware configurations, it implements a much more -flexible drive letter assignment mechanism so that any drive letter can -be assigned to any disk device. - -At boot, you will notice that RomWBW automatically assigns drive letters -to the available disk devices. These assignments are displayed during -the startup of the selected operating system. Additionally, you can -review the current drive assignments at any time using the ASSIGN -command. CP/M 3 and ZPM3 do not automatically display the assignments at -startup, but you can use ASSIGN do display them. - -The drive letter assignments do not change during an OS session unless -you use the ASSIGN command yourself to do it. Additionally, the -assignments at boot will stay the same on each boot as long as you do -not make changes to your hardware configuration. Note that the -assignments are dependent on the media currently inserted in hard disk -drives. So, notice that if you insert or remove an SD Card or CF Card, -the drive assignments will change. Since drive letter assignments can -change, you must be careful when doing destructive things like using -CLRDIR to make sure the drive letter you use is referring to the desired -media. - -When performing a ROM boot of an operating system, note that A: will be -your RAM disk and B: will be your ROM disk. When performing a disk boot, -the disk you are booting from will be assigned to A: and the rest of the -drive letters will be offset to accommodate this. This is done because -most legacy operating systems expect that A: will be the boot drive. - -Slices - -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 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. - -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. - -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. - -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 - -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 ROM applications are available at the boot loader prompt: - - Application - ------------- -------------------------------------------------------- - Monitor Z80 system debug monitor w/ Intel Hex loader - Forth Brad Rodriguez’s ANSI compatible Forth language - Basic Nascom 8K BASIC language - Tasty BASIC Dimitri Theuling’s Tiny BASIC implementation - Play A simple video game (requires ANSI terminal emulation) - -In general, the command to exit these applications and restart the -system is BYE. The exceptions are the Monitor which uses B and Play -which uses Q. - -Space is available in the ROM image for the inclusion of other software. -Any inbuilt application can be set up to launch automatically at -startup. - -RomWBW Custom Applications - -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 ROM disk and are, -therefore, globally available. - - -------------------------------------------------------------------------- - Application Description - ------------- ------------------------------------------------------------ - ASSIGN Add, change, and delete drive letter assignments. Use ASSIGN - /? for usage instructions. - - SYSCOPY Copy system image to a device to make it bootable. Use - SYSCOPY with no parms for usage instructions. - - FDU Format and test floppy disks. Menu driven interface. - - OSLDR Load a new OS on the fly. For example, you can switch to - Z-System when running CP/M. Use OSLDR with no parms for - usage instructions. - - FORMAT Will someday be a command line tool to format floppy disks. - Currently does nothing! - - MODE Reconfigures serial ports dynamically. - - XM XModem file transfer program adapted to hardware. - Automatically uses primary serial port on system. - - 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). - - FLASH Will Sowerbutts’ in-situ ROM programming utility. - - 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. - - Application Description - ------------- ------------------------------------------------------------- - TUNE Play .PT2, .PT3, .MYM audio files. - FAT Access MS-DOS FAT filesystems from RomWBW (based on FatFs). - -There is additional documentation on some of these applications at the -RomWBW Applications Page. - Operating Systems One of the primary goals of RomWBW is to expose a set of generic @@ -860,10 +950,13 @@ computer is: 1. Use cpmtools on your modern computer to create a RomWBW CP/M filesystem image. + 2. Insert your RomWBW media (CF Card, SD Card, or floppy disk) in your modern computer. + 3. Use a disk imaging tool to copy the RomWBW filesystem image onto the media. + 4. Move the media back to the RomWBW computer. This process is a little complicated, but it has the benefit of allowing @@ -890,7 +983,7 @@ 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 +When formatting the media on your modern computer, be sure to pick the FAT filesystem. NTFS and other filesystems will not work. On your RomWBW computer you can use the FAT application to access the @@ -1048,7 +1141,8 @@ applications are no longer provided. list of general code enhancements. - Phillip Stevens contributed support for FreeRTOS. - Curt Mayer contributed the Linux / MacOS build process. -- UNA BIOS is a product of John Coffman. +- UNA BIOS and FDISK80 is a product of John Coffman. +- FLASH4 is a product of Will Sowerbutts. Contributions of all kinds to RomWBW are very welcome. diff --git a/Source/Doc/Applications.md b/Source/Doc/Applications.md index ed866aab..55c155a1 100644 --- a/Source/Doc/Applications.md +++ b/Source/Doc/Applications.md @@ -1,10 +1,7 @@ !include(Common.inc) !def(document)(Applications) --- -title: | - | !product - | - | !document +title: !product !document author: !author (mailto:!authmail) date: !date institution: !orgname @@ -35,17 +32,36 @@ header-includes: # Summary -RomWBW includes a small suite of custom applications to maximize the features available. In general, these applications are operating system agnostic -- they run under any of the included operating systems. However, they all require RomWBW -- they are not generic CP/M applications. - -Most of the applications are custom written for RomWBW. However, some are standard CP/M applications that have been adapted to run under RomWBW (e.g., XModem). The applications are generally matched to the version of RomWBW they are distributed with. So, if you upgrade the version of RomWBW in your system ROM, you will want to copy the corresponding applications to any storage devices you are using. - -Most of the applications are included on the RomWBW ROM disk, so they are easy to access. - -The applications are also included with all of the operating system disk images provided with RomWBW. So, a simple way to ensure you have matching applications is to write the disk images onto your disk media when upgrading your ROM. Of course, this will destroy any existing data on your disk media, so don't do this if you are saving any data on the media. - -Most of the applications are included as source code in the RomWBW distribution and are built in the normal build process. The source code is found in the Source\\Apps directory of the distribution. The binary executable applications are found in the Binary\\Apps directory. - -The following table clarifies where each of the applications can be found: +RomWBW includes a small suite of custom applications to maximize the +features available. In general, these applications are operating +system agnostic -- they run under any of the included operating +systems. However, they all require RomWBW -- they are not generic CP/M +applications. + +Most of the applications are custom written for RomWBW. However, some +are standard CP/M applications that have been adapted to run under +RomWBW (e.g., XModem). The applications are generally matched to the +version of RomWBW they are distributed with. So, if you upgrade the +version of RomWBW in your system ROM, you will want to copy the +corresponding applications to any storage devices you are using. + +Most of the applications are included on the RomWBW ROM disk, so they +are easy to access. + +The applications are also included with all of the operating system +disk images provided with RomWBW. So, a simple way to ensure you have +matching applications is to write the disk images onto your disk media +when upgrading your ROM. Of course, this will destroy any existing +data on your disk media, so don't do this if you are saving any data +on the media. + +Most of the applications are included as source code in the RomWBW +distribution and are built in the normal build process. The source +code is found in the Source\\Apps directory of the distribution. The +binary executable applications are found in the Binary\\Apps directory. + +The following table clarifies where each of the applications can be +found: | Application | ROM Disk | Boot Disks | Apps Dir | | ----------- | -------- | ---------- | -------- | @@ -58,6 +74,10 @@ The following table clarifies where each of the applications can be found: | XM | Yes | Yes | Yes | | FLASH | Yes | Yes | Yes | | FDISK80 | Yes | Yes | Yes | +| TALK | Yes | Yes | Yes | +| RTC | Yes | Yes | Yes | +| TIMER | Yes | Yes | Yes | +| INTTEST | Yes | Yes | Yes | | FAT | No | Yes | Yes | | TUNE | No | Yes | Yes | @@ -68,9 +88,8 @@ The following table clarifies where each of the applications can be found: RomWBW includes a flexible mechanism for associating the operating system drive letters (A: - P:) to the physical devices in the system. Drive letter assignments can be changed on a running operating system -without rebooting. The ASSIGN command facilitates this by allowing -allows you to display, assign, reassign, or remove the drive -letter assignments. +without rebooting. The ASSIGN command facilitates this by allowing you +to display, assign, reassign, or remove the drive letter assignments. ## Syntax @@ -84,92 +103,99 @@ letter assignments. `ASSIGN /?` will display brief command usage and version information. -`ASSIGN /L` will display a list of all the devices available to be used -in drive assignments in the running system. The devices listed may or may -not contain media. Although some device types support the use of slices, -the list does not indicate this. +`ASSIGN /L` will display a list of all the devices available to be +used in drive assignments in the running system. The devices listed +may or may not contain media. Although some device types support the +use of slices, the list does not indicate this. -`ASSIGN` with no parameters will list all of the current drive assignments. +`ASSIGN` with no parameters will list all of the current drive +assignments. -`ASSIGN `*``* will display the assignment for the specific drive For example, -`ASSIGN C:` will display the assignment for drive C:. +`ASSIGN `*``* will display the assignment for the specific drive +For example, `ASSIGN C:` will display the assignment for drive C:. -`ASSIGN `*``*`=`*``*`[:`*``*`]` will assign (or reassign) a drive -letter to a new device and (optionally) slice. If no slice is specified, then -slice 0 is assumed. For example, `ASSIGN C:=IDE0` will assign drive letter C: -to device IDE0, slice 0. `ASSIGN D:=IDE0:3` will assign drive letter D: to -device IDE0 slice 3. +`ASSIGN `*``*`=`*``*`[:`*``*`]` will assign (or +reassign) a drive letter to a new device and (optionally) slice. If no +slice is specified, then slice 0 is assumed. For example, `ASSIGN +C:=IDE0` will assign drive letter C: to device IDE0, slice 0. `ASSIGN +D:=IDE0:3` will assign drive letter D: to device IDE0 slice 3. -`ASSIGN `*``*`=` can be used to remove the assignment from a drive letter. So, -`ASSIGN E:=` will remove the association of drive letter E: from any previous -device. +`ASSIGN `*``*`=` can be used to remove the assignment from a +drive letter. So, `ASSIGN E:=` will remove the association of drive +letter E: from any previous device. -`ASSIGN `*``*`=`*``*`` is used to swap the assignments of two drive letters. -For example, `ASSIGN C:=D:` will swap the device assignments of C: and D:. +`ASSIGN `*``*`=`*``* is used to swap the assignments +of two drive letters. For example, `ASSIGN C:=D:` will swap the device +assignments of C: and D:. -The `ASSIGN` command supports "stacking" of instructions. For example, -`ASSIGN C:=IDE0:0,D:=IDE0:1,E:=` will assign C: and D: to the first two slices -of IDE 0 and will unassign E:. +The `ASSIGN` command supports "stacking" of instructions. For example, +`ASSIGN C:=IDE0:0,D:=IDE0:1,E:=` will assign C: and D: to the first +two slices of IDE 0 and will unassign E:. -When the command runs it will echo the resultant assignments to the console to -confirm it's actions. +When the command runs it will echo the resultant assignments to the +console to confirm it's actions. It will also display the remaining +space available in disk buffers. ## Notes -If the `ASSIGN` command encounters any rule violations or errors, it will -abort with an error and **none** of the drive assignments will be -implemented. In other words, the command is atomic and will either +If the `ASSIGN` command encounters any rule violations or errors, it +will abort with an error and **none** of the drive assignments will be +implemented. In other words, the command is atomic and will either completely succeed or completely fail. All assigned drives utilize disk buffer space from a limited pool. The -ASSIGN command will display the amount of buffer space remaining after -an assign command is executed. Buffer space is freed if a drive is -unassigned. If the total assignments exceed the available disk buffer -space available, the command will abort with an error message. - -The `ASSIGN` command does not check to see if the device and slice being assigned -actually contains readable media. If the assigned device has no media, you will -receive an I/O error when you attempt to use the drive letter. - -The `ASSIGN` command will not allow you to specify a slice (other than zero) for -devices that do not support slices (such as floppy drives or RAM/ROM disks). - -The `ASSIGN` command does not check that the media is large enough to support the -slice you specify. In other words, you could potentially assign a drive letter to -a slice that is beyond the end of the media in a device. In this case, subsequent -attempts to use that drive letter will result in an I/O error. - -Additionally, the `ASSIGN` command does not check to see if the slice specified -refers to an area on your media that is occupied by other data (such as a FAT -filesystem). - -You will not be allowed to assign multiple drive letters to a single device and -slice. In other words, only one drive letter may refer to a single filesystem -at a time. - -Drive letter A: must always be assigned to a device and slice. The `ASSIGN` command -will enforce this. - -The changes made by this command are not permanent. The assignments will -persist through a warm start, but when you reboot your system, all drive -letters will return to their default assignments. A SUBMIT batch file -can be used to setup desired drive assignments automatically at boot. - -Floppy disk drives and RAM/ROM drives do not have slices. A slice should -only be specified for hard disk devices (SD, IDE, PPIDE). - -Only one drive letter may be assigned to a specific device/unit/slice at -a time. Attempts to assign a duplicate drive letter will fail and +ASSIGN command will display the amount of buffer space remaining +after an assign command is executed. Buffer space is freed if a drive +is unassigned. If the total assignments exceed the available disk +buffer space available, the command will abort with an error message. + +The `ASSIGN` command does not check to see if the device and slice +being assigned actually contains readable media. If the assigned +device has no media, you will receive an I/O error when you attempt to +use the drive letter. + +The `ASSIGN` command will not allow you to specify a slice (other than +zero) for devices that do not support slices (such as floppy drives +or RAM/ROM disks). + +The `ASSIGN` command does not check that the media is large enough to +support the slice you specify. In other words, you could potentially +assign a drive letter to a slice that is beyond the end of the media +in a device. In this case, subsequent attempts to use that drive +letter will result in an I/O error. + +Additionally, the `ASSIGN` command does not check to see if the slice +specified refers to an area on your media that is occupied by other +data (such as a FAT filesystem). + +You will not be allowed to assign multiple drive letters to a single +device and slice. In other words, only one drive letter may refer to a +single filesystem at a time. + +Drive letter A: must always be assigned to a device and slice. The +`ASSIGN` command will enforce this. + +The changes made by this command are not permanent. The assignments +will persist through a warm start, but when you reboot your system, +all drive letters will return to their default assignments. A SUBMIT +batch file can be used to setup desired drive assignments +automatically at boot. + +Floppy disk drives and RAM/ROM drives do not have slices. A slice +should only be specified for hard disk devices (SD, IDE, PPIDE). + +Only one drive letter may be assigned to a specific device/unit/slice +at a time. Attempts to assign a duplicate drive letter will fail and display an error. If you wish to assign a different drive letter to a device/unit/slice, unassign the the existing drive letter first. Be aware that this command will allow you to reassign or remove the -assignment of your system drive letter. This can cause your operating +assignment of your system drive letter. This can cause your operating system to fail and force you to reboot. -This command is particularly sensitive to being matched to the appropriate -version of the RomWBW ROM you are using. Be very careful to keep all copies -of `ASSIGN.COM` up to date with your ROM. +This command is particularly sensitive to being matched to the +appropriate version of the RomWBW ROM you are using. Be very careful +to keep all copies of `ASSIGN.COM` up to date with your ROM. ## Etymology @@ -180,9 +206,9 @@ provided in the RomWBW distribution. # SYSCOPY -To make disk media bootable, you must write a system boot image onto the system tracks -of the of the media. The `SYSCOPY` allows you to read or write the system boot image -of disk media. +To make disk media bootable, you must write a system boot image onto +the system tracks of the of the media. The `SYSCOPY` allows you to +read or write the system boot image of disk media. ## Syntax @@ -192,15 +218,15 @@ of disk media. alternatively a filename to save the operating system image *``* is the drive containing an operating system image or -alternatively a filename containing the system image to be placed -on the destination +alternatively a filename containing the system image to be placed on +the destination ## Usage -Both *``* and *``* can refer to either a drive letter or -a file. If a drive letter is specified, the system boot image will -be read or written to the system tracks of the drive. If a filename -is specified, the system boot image will be read or written to the +Both *``* and *``* can refer to either a drive letter or a +file. If a drive letter is specified, the system boot image will be +read or written to the system tracks of the drive. If a filename is +specified, the system boot image will be read or written to the specified filename. `SYSCOPY C:=ZSYS.SYS` will read a system boot image from the file @@ -209,65 +235,62 @@ ZSYS.SYS and write it onto the system tracks of drive C:. `SYSCOPY A:OS.SYS=C:` will capture the system boot image from the system tracks of drive C: and store it in the file A:OS.SYS. -`SYSCOPY D:=C:` will copy the system tracks from drive C: onto -the system tracks of drive D: +`SYSCOPY D:=C:` will copy the system tracks from drive C: onto the +system tracks of drive D:. ## Notes The RomWBW ROM disk contains files with the system boot image for -Z-System and CP/M 2.2. These files are called CPM.SYS and ZSYS.SYS -respectively. These files can be used as the source of a `SYSCOPY` +Z-System and CP/M 2.2. These files are called CPM.SYS and ZSYS.SYS +respectively. These files can be used as the source of a `SYSCOPY` command to make a disk bootable with the corresponding operating system. -CP/M 3 uses a two phase boot process. To make a CP/M 3 drive -bootable, you need to put "CPMLDR.SYS" on the boot tracks of the -disk and be sure that the drive also contains the "CPM.SYS" file. -The "CPMLDR.SYS" file is not included on the ROM disk, but is found -on the CP/M 3 disk image. - -ZPM3 is similar to CP/M 3. You also put "CPMLDR.SYS" on the system -tracks of the drive to make it bootable. The ZPM3 operating system -is in the file called "CPM3.SYS" on the ZPM3 disk image. It may -seem confusing that ZPM3 is in the file called CPM3.SYS, but it is -normal for ZPM3. - -For the purposes of booting an operating system, each disk slice -is considered it's own operating system. Each slice can be made -bootable with it's own system tracks. - -`SYSCOPY` uses drive letters to specify where to read/write the -system boot images. However, at startup, the boot loaded will -require you to enter the actual disk device and slice to boot from. -So, you need to be careful to pay attention to the device and slice -that is assigned to a drive letter so you will know what to enter -at the boot loader prompt. By way of explanation, the boot loader -does not know about drive letters because the operating system is -not loaded yet. - -If you want to put a a boot system image on a device and slice -that is not currently assigned to a drive letter, you will need -to assign a drive letter first. - -Not all disk formats include space for system tracks. Such disk -formats cannot contains a system boot image and, therefore, cannot -be made bootable. The best example of such disk formats are the -ROM and RAM disks. To maximize useable file space on these drives, -they do not have system tracks. Obviously, ROM operating system -is supported by choosing a ROM operating system at the boot loader -prompt. Any attempt to write a system boot image to disk media -with no system tracks will cause SYSCOPY to fail with an error -message. - -The system boot images are paired with the ROM version in your -system. So, you must take care to update the system tracks of -any bootable disk when you upgrade your ROM firmware. +CP/M 3 uses a two phase boot process. To make a CP/M 3 drive bootable, +you need to put "CPMLDR.SYS" on the boot tracks of the disk and be +sure that the drive also contains the "CPM.SYS" file. The "CPMLDR.SYS" +file is not included on the ROM disk, but is found on the CP/M 3 disk +image. + +ZPM3 is similar to CP/M 3. You also put "CPMLDR.SYS" on the system +tracks of the drive to make it bootable. The ZPM3 operating system is +in the file called "CPM3.SYS" on the ZPM3 disk image. It may seem +confusing that ZPM3 is in the file called CPM3.SYS, but it is normal +for ZPM3. + +For the purposes of booting an operating system, each disk slice is +considered it's own operating system. Each slice can be made bootable +with it's own system tracks. + +`SYSCOPY` uses drive letters to specify where to read/write the system +boot images. However, at startup, the boot loaded will require you to +enter the actual disk device and slice to boot from. So, you need to +be careful to pay attention to the device and slice that is assigned +to a drive letter so you will know what to enter at the boot loader +prompt. By way of explanation, the boot loader does not know about +drive letters because the operating system is not loaded yet. + +If you want to put a a boot system image on a device and slice that is +not currently assigned to a drive letter, you will need to assign a +drive letter first. + +Not all disk formats include space for system tracks. Such disk +formats cannot contains a system boot image and, therefore, cannot be +made bootable. The best example of such disk formats are the ROM and +RAM disks. To maximize usable file space on these drives, they do not +have system tracks. Obviously, ROM operating system is supported by +choosing a ROM operating system at the boot loader prompt. Any attempt +to write a system boot image to disk media with no system tracks will +cause SYSCOPY to fail with an error message. + +The system boot images are paired with the ROM version in your system. +So, you must take care to update the system tracks of any bootable +disk when you upgrade your ROM firmware. The system boot images are **not** tied to specific hardware -configurations. System boot images and operating systems -provided with RomWBW will work with any supported RomWBW -platform or hardware as long as they are the same version as -the RomWBW firmware. +configurations. System boot images and operating systems provided with +RomWBW will work with any supported RomWBW platform or hardware as +long as they are the same version as the RomWBW firmware. ## Etymology @@ -279,13 +302,13 @@ provided in the RomWBW distribution. # MODE The MODE command allows you to adjust the operating characteristics -such as baud rate, data bits, stop bits, and parity bits of -serial ports dynamically. +such as baud rate, data bits, stop bits, and parity bits of serial +ports dynamically. ## Syntax `MODE /?` -`MODE COM`*``*`: [`*``*`[,`*``*`[,`*``*`[,`*``*`]]]] [/P]` +`MODE COM`*``*`: [`*``*`[,`*``*`[,`*``*`[,`*``*`]]]] [/P]` `/?` displays command usage and version information @@ -311,12 +334,12 @@ configuration. `MODE <`*n*`>` will display the current configuration of the specified character device unit. -`MODE COM`*``*`: [`*``*`[,`*``*`[,`*``*`[,`*``*`]]]] [/P]` -requests that the specified configuration be set on the character -device unit. You can use commas with no values to leave some values -unchanged. As an example, `MODE COM0: 9600,,,2` will setup -character device unit 0 for 9600 baud and 2 stop bits while leaving -data bits and stop bits as is. +`MODE COM`*``*`: [`*``*`[,`*``*`[,`*``*`[,` +*``*`]]]] [/P]` requests that the specified configuration +be set on the character device unit. You can use commas with no values +to leave some values unchanged. As an example, `MODE COM0: 9600,,,2` +will setup character device unit 0 for 9600 baud and 2 stop bits while +leaving data bits and stop bits as is. Appending `/P` in a command specifying a new configuration will cause the terminal output to pause and wait for the user to press a key. @@ -331,10 +354,10 @@ serial unit. Any parameters not specified will remain unchanged. Changes are not persisted and will revert to system defaults at next system boot. -Not all character devices support all `MODE` options. Some devices -(notably ASCI devices) have limited baud rate divisors. An attempt -to set a baud rate that the device cannot support will fail with -an error message. +Not all character devices support all `MODE` options. Some devices +(notably ASCI devices) have limited baud rate divisors. An attempt to +set a baud rate that the device cannot support will fail with an error +message. ## Etymology @@ -354,23 +377,23 @@ to format and test floppy disk media. ## Usage -This application has an interactive user interface. At startup, you -will be prompted to select the floppy interface hardware in your system. -Following this, you will see the main menu of the program with many -functions to manage floppy disk drives. +This application has an interactive user interface. At startup, you +will be prompted to select the floppy interface hardware in your +system. Following this, you will see the main menu of the program with +many functions to manage floppy disk drives. The primary documentation for this application is in a file called -"FDU.txt" in the Doc directory of the RomWBW distribution. Please +"FDU.txt" in the Doc directory of the RomWBW distribution. Please consult this file for usage information. ## Notes This application interfaces directly to the floppy hardware in your -system. It does not use the RomWBW HBIOS. This means that even if -your system is not configured for floppy drives, you can still use -`FDU` to test your floppy drives and format floppy media. This also -means it is critical that you choose the correct hardware interface -from the initial selection when starting the application. +system. It does not use the RomWBW HBIOS. This means that even if your +system is not configured for floppy drives, you can still use `FDU` +to test your floppy drives and format floppy media. This also means it +is critical that you choose the correct hardware interface from the +initial selection when starting the application. ## Etymology @@ -381,9 +404,9 @@ provided in the RomWBW distribution. # OSLDR -RomWBW supports loading new operating systems on-the-fly. For example, +RomWBW supports loading new operating systems on-the-fly. For example, if CP/M 2.2 is currently running, you can load and run Z-System from -the command line. The `OSLDR` application provides this functionality. +the command line. The `OSLDR` application provides this functionality. ## Syntax @@ -397,37 +420,37 @@ the command line. The `OSLDR` application provides this functionality. ## Usage -`OSLDR `*``* will read the specified file, confirm it is an operating system image file, -then load it as though it was being booted. For example, `OSLDR ZSYS.SYS` -would load the Z-System operating system. +`OSLDR `*``* will read the specified file, confirm it is an +operating system image file, then load it as though it was being +booted. For example, `OSLDR ZSYS.SYS` would load the Z-System +operating system. -`OSLDR `*``* *``* will first read and load the specified -*``* file as a new HBIOS image and then read and load -the specified *``* file. HBIOS image can be produced by the -RomWBW build process, but they are not produced by default. You +`OSLDR `*``* *``* will first read and load the +specified *``* file as a new HBIOS image and then read and +load the specified *``* file. HBIOS image can be produced by +the RomWBW build process, but they are not produced by default. You are encouraged to contact Wayne Warthen for more information on this capability. ## Notes -The primary function of `OSLDR` is to allow switching to a new operating -system while the system if running without a full reboot. +The primary function of `OSLDR` is to allow switching to a new +operating system while the system if running without a full reboot. `OSLDR` is considered generally reliable for when used simply to load -a new operating system (one parameter). However, using it to load -an HBIOS image is considered experimental and should not be -relied upon. +a new operating system (one parameter). However, using it to load an +HBIOS image is considered experimental and should not be relied upon. `OSLDR` can also be used to load "test" versions of operating systems -from files transferred to your system. This is especially useful in -when loading both an operating system and HBIOS image because you -can essentially simulate starting your system with new firmware -without reprogramming your ROM. +from files transferred to your system. This is especially useful in +when loading both an operating system and HBIOS image because you can +essentially simulate starting your system with new firmware without +reprogramming your ROM. -`OSLDR` attempts to check the file(s) specified for correctness -before loading them, but it is far from perfect. This application -should be used with caution and may not work in some cases that -are hard to define. +`OSLDR` attempts to check the file(s) specified for correctness before +loading them, but it is far from perfect. This application should be +used with caution and may not work in some cases that are hard to +define. ## Etymology @@ -438,8 +461,8 @@ provided in the RomWBW distribution. # FORMAT -This application is just a placeholder for a future version that -will make it simpler to format media including floppy disks. +This application is just a placeholder for a future version that will +make it simpler to format media including floppy disks. ## Syntax @@ -448,8 +471,8 @@ will make it simpler to format media including floppy disks. ## Notes This application currently just displays a few lines of information -briefly instructing a user how to format media. It performs no -actual function beyond this display currently. +briefly instructing a user how to format media. It performs no actual +function beyond this display currently. ## Etymology @@ -460,7 +483,8 @@ provided in the RomWBW distribution. # XM -An adaptation of Ward Christensen's X-Modem protocol for transferring files between systems using a serial port. +An adaptation of Ward Christensen's X-Modem protocol for transferring +files between systems using a serial port. ## Syntax @@ -477,54 +501,61 @@ An adaptation of Ward Christensen's X-Modem protocol for transferring files betw *``* is the name of a file to send or receive -*``* is the name of a library (.lbr) to extract -a file to send from +*``* is the name of a library (.lbr) to extract a file to send ## Usage -To transfer a file from your host computer to your RomWBW -computer, do the following: +To transfer a file from your host computer to your RomWBW computer, do +the following: + +1. Enter one of the `XM` receive commands specifying the name you want +to give to the received file. + +2. On your host computer select a file to send and initiate the XModem +send operation. -1. Enter one of the `XM` receive commands specifying the name you want to give to the received file. -2. On your host computer select a file to send and initiate the XModem send operation. +To transfer a file from your RomWBW computer to your host computer, do +the following: -To transfer a file from your RomWBW computer to your host computer, do the following: +1. Enter one of the `XM` send commands specifying the name of the file +to be sent. -1. Enter one of the `XM` send commands specifying the name of the file to be sent. -2. On your host computer, specify the name to assign to the received file and initiate and XModem receive operation. +2. On your host computer, specify the name to assign to the received +file and initiate and XModem receive operation. -Please refer to the documentation of your host computer's terminal emulation -software for specific instructions on how to use XModem. +Please refer to the documentation of your host computer's terminal +emulation software for specific instructions on how to use XModem. ## Notes -The XModem adaptation that comes with RomWBW will automatically use the -primary character device unit (character device unit 0) for the file transfer. +The XModem adaptation that comes with RomWBW will automatically use +the primary character device unit (character device unit 0) for the +file transfer. -`XM` attempts to determine the best way to drive the serial port based on your -hardware configuration. When possible, it will bypass the HBIOS for -faster operation. However, in many cases, it will use HBIOS so that flow -control can be used. +`XM` attempts to determine the best way to drive the serial port based +on your hardware configuration. When possible, it will bypass the +HBIOS for faster operation. However, in many cases, it will use HBIOS +so that flow control can be used. -`XM` is dependent on a reliable communications channel. -You must ensure that the serial port can be serviced fast enough by either -using a baud rate that is low enough or ensuring that hardware flow control -is fully functional (end to end). +`XM` is dependent on a reliable communications channel. You must +ensure that the serial port can be serviced fast enough by either +using a baud rate that is low enough or ensuring that hardware flow +control is fully functional (end to end). ## Etymology -The `XM` application provided in RomWBW is an adaptation of a pre-existing -XModem application. Based on the source code comments, it was originally -adapted from Ward Christensen's MODEM2 by Keith Petersen and is -labeled version 12.5. +The `XM` application provided in RomWBW is an adaptation of a +pre-existing XModem application. Based on the source code comments, it +was originally adapted from Ward Christensen's MODEM2 by Keith +Petersen and is labeled version 12.5. -The original source of the application was found in the -Walnut Creek CD-ROM and is called XMDM125.ARK dated 7/15/86. +The original source of the application was found in the Walnut Creek +CD-ROM and is called XMDM125.ARK dated 7/15/86. The actual application is virtually untouched in the RomWBW -adaptation. The majority of the work was in the modem driver -which was enhanced to detect the hardware being used and -dynamically choose the appropriate driver. +adaptation. The majority of the work was in the modem driver which was +enhanced to detect the hardware being used and dynamically choose the +appropriate driver. The source code is provided in the RomWBW distribution. @@ -532,14 +563,13 @@ The source code is provided in the RomWBW distribution. # FLASH -Most of the hardware platforms that run RomWBW support the -use of EEPROMs -- Electronically Erasable Programmable ROMs. -The `FLASH` application can be used to reprogram such ROMS -in-situ (in-place), thus making it possible to upgrade ROMs -without a programmer or even removing the ROM from your -system. +Most of the hardware platforms that run RomWBW support the use of +EEPROMs -- Electronically Erasable Programmable ROMs. The `FLASH` +application can be used to reprogram such ROMS in-situ (in-place), +thus making it possible to upgrade ROMs without a programmer or even +removing the ROM from your system. -This application was produced by Will Sowerbutts. +This application is provided by Will Sowerbutts. ## Syntax @@ -562,100 +592,272 @@ Options: (access method is auto-detected by default) ## Usage To program your EEPROM ROM chip, first transfer the file to your -RomWBW system. Then use the command `FLASH WRITE *``*. -The application will auto-detect the type of EEPROM chip you have -and will program and verify it. +RomWBW system. Then use the command `FLASH WRITE *``*. The +application will auto-detect the type of EEPROM chip you have, +program it, and verify it. -You can use the "READ" variant of the command to read the ROM -image from your system into a file. This is useful if you want -to save a copy of your current ROM before reprogramming it. +You can use the `FLASH READ` form of the command to read the ROM image +from your system into a file. This is useful if you want to save a +copy of your current ROM before reprogramming it. -Although the "WRITE" variant automatically performs a verification, -you can manually perform a verification function with the "VERIFY" -variant of the command. +Although `FLASH WRITE` automatically performs a verification, you can +manually perform a verification function with the `FLASH VERIFY` form +of the command. -The author's documentation for the application is found in the -RomWBW distribution in the Doc\\Contrib directory. +The author's documentation for the application is found in the RomWBW +distribution in the Doc\\Contrib directory. ## Notes -The application supports a significant number of EEPROM parts. It -should automatically detect your part. If it does not recognize -your chip, make sure that you do not have a write protect jumper -set -- this jumper will cause the ROM chip type to be unrecognized. +The application supports a significant number of EEPROM parts. It +should automatically detect your part. If it does not recognize your +chip, make sure that you do not have a write protect jumper set -- +this jumper will cause the ROM chip type to be unrecognized. -Reprogramming a ROM chip in-place is inherently dangerous. If anything -goes wrong, you will be left with a non-functional system and no ability -to run the `FLASH` application again. Use this application with -caution and be prepared to use a hardware ROM programmer to restore -your system if needed. +Reprogramming a ROM chip in-place is inherently dangerous. If anything +goes wrong, you will be left with a non-functional system and no +ability to run the `FLASH` application again. Use this application +with caution and be prepared to use a hardware ROM programmer to +restore your system if needed. ## Etymology -This application was written and provided by Will Sowerbutts. He +This application was written and provided by Will Sowerbutts. He provides it in binary format and is included in the RomWBW distribution as a binary file. -The source code for this application can be found at the [FLASH4 GitHub -repository](https://github.com/willsowerbutts/flash4). +The source code for this application can be found at the [FLASH4 +GitHub repository](https://github.com/willsowerbutts/flash4). `\clearpage`{=latex} # FDISK80 -RomWBW supports disk media with MS-DOS FAT filesystems (see FAT -application). If you wish to put a FAT filesystem on your media, the -FDISK80 application can be used to partition your media which is +RomWBW supports disk media with MS-DOS FAT filesystems (see FAT +application). If you wish to put a FAT filesystem on your media, the +FDISK80 application can be used to partition your media which is required in order to add a FAT filesystem. -This application was produced by John Coffman. +This application is provided by John Coffman. ## Usage -`FDISK80` is an interactive application. At startup it will ask -you for the disk unit that you want to partition. When your -RomWBW system boots, it will display a table with the disk unit -numbers. Use the disk unit numbers from that table to enter the -desired disk unit to partition. +`FDISK80` is an interactive application. At startup it will ask you +for the disk unit that you want to partition. When your RomWBW system +boots, it will display a table with the disk unit numbers. Use the +disk unit numbers from that table to enter the desired disk unit to +partition. `FDISK80` operates very much like other FDISK disk partitioning -applications. Please refer to the file called "FDisk Manual.pdf" -in the Doc directory of the RomWBW distribution for further -instructions. +applications. Please refer to the file called "FDisk Manual.pdf" in +the Doc directory of the RomWBW distribution for further instructions. -There is also more information on using FAT partitions with RomWBW -in the "RomWBW Getting Started.pdf" document in the Doc directory of the distribution. +There is also more information on using FAT partitions with RomWBW in +the "RomWBW Getting Started.pdf" document in the Doc directory of the +distribution. ## Notes -Partitioning of RomWBW media is **only** required if you want to add -a FAT filesystem to the media. Do not partition your media if you are -simply using it for RomWBW. To be clear, RomWBW slices do not require +Partitioning of RomWBW media is **only** required if you want to add a +FAT filesystem to your media. Do not partition your media if you are +simply using it for RomWBW. To be clear, RomWBW slices do not require partitioning. As described in "RomWBW Getting Started.pdf", you should be careful -when adding a FAT partition to your media that the partition does -not overlap with the area of the media being used for RomWBW slices. -The "(R)eserve" function in `FDISK80` can help prevent this. +when adding a FAT partition to your media that the partition does not +overlap with the area of the media being used for RomWBW slices. The +"(R)eserve" function in `FDISK80` can help prevent this. ## Etymology The source for this application was provided directly by John Coffman. It is a C program and requires a build environment that includes the -SDCC compiler. As such, it is not included in the RomWBW build process, -only the binary executable is included. +SDCC compiler. As such, it is not included in the RomWBW build +process, only the binary executable is included. Please contact John Coffman if you would like a copy of the source. `\clearpage`{=latex} +# TALK + +It is sometimes useful to direct your console input/output to a +designated serial port. For example, if you were to connect a modem +to your second serial port, you might want to connect directly to it +and have everything you type sent to it and everything it sends be +shown on your console. The `TALK` application does this. + +## Syntax + +`TALK [TTY:|CRT:|BAT:UC1:]` + +## Usage + +`TALK` operates at the operating system level (not HBIOS). + +The parameter to `TALK` refers to logical CP/M serial devices. Upon +execution all characters types at the console will be sent to the +device specified and all characters received by the specified device +will be echoes on the console. + +Press Control+Z on the console to terminate the application. + +## Notes + +This application is designed for CP/M 2.2 or Z-System. Use on later +operating systems such as CP/M 3 is not supported. + +## Etymology + +The `TALK` command is an original product and the source code is +provided in the RomWBW distribution. + +`\clearpage`{=latex} + +# RTC + +Many RomWBW systems provide real time clock hardware. The RTC +application is a simple, interactive program allowing you to display +and set the time and registers of the RTC. + +## Syntax + +`RTC` + +## Usage + +After startup, the application provides the following options: + +| Option | Function | +| ----------- | ------------------------------------------------------ | +| `E)xit` | will terminate the application. | +| `T)ime` | will display the time as read from the RTC hardware. | +| `st(A)rt` | will restart the clock running if it is stopped. | +| `S)et` | will program the RTC clock with the date/time previously entered using the I)nit option. | +| `R)aw` | will read the minute/second of the RTC clock iteratively every time the space key is pressed. Press enter to end. | +| `L)oop` | will read the full date/time of the RTC clock iteratively every time the space key is pressed. Press enter to end. | +| `C)harge` | will enable the battery charging function of the RTC. | +| `N)ocharge` | will disable the battery charging functino of the RTC. | +| `D)elay` | allows you to test the built-in timing delay in the program. It is not unusual for it to be wrong. | +| `I)nit` | allows you to enter a date/time value for subsequent programming of the RTC using the S)et option. | +| `G)et` | allows you to read the value of a non-volatile register in the RTC. | +| `P)ut` | allows you to write the value of a non-volatile register in the RTC. | +| `B)oot` | will reboot your system. | +| `H)elp` | displays brief help. | + +## Notes + +When using Get and Put options, the register number to read/write is +entered in hex. The non-volatile ram register numbers are 0x20-0x3F. + +When entering values, you must enter exactly two hex characters. The +backspace key is not supported. You do not use enter after entering +the two hex characters. Yes, this should be improved. + +The `RTC` application interacts directly with the RTC hardware +bypassing HBIOS. + +## Etymology + +The `RTC` application was originally written by Andrew Lync as part of +the original ECB SBC board development. It has since been modified to +support most of the hardware variations included with RomWBW. + +`\clearpage`{=latex} + +# TIMER + +Most RomWBW systems have a 50Hz periodic system timer. A counter is +incremented every time a timer tick occurs. The `TIMER` application +displays the value of the counter. + +## Syntax + +`TIMER` +`TIMER /?` +`TIMER /C` + +## Usage + +Use `TIMER` to display the current value of the counter. + +Use `TIMER /C` to display the value of the counter continuously. + +The display of the counter will be something like this: + +`00045444 Ticks, 0000162A.10 Seconds` + +The first number is the total number of ticks since system startup. +The second number is the total number of seconds since system startup. + +## Notes + +The seconds value is displayed with a fractional value which is not a +an actual fraction, but rather the number of ticks past the seconds +rollover. All values are in hex. + +The primary use of the `TIMER` application is to test the system +timer functionality of your system. + +In theory, you could capture the value before and after some process +you want to time. + +## Etymology + +The `TIMER` command is an original product and the source code is +provided in the RomWBW distribution. + +`\clearpage`{=latex} + +# INTTEST + +RomWBW includes an API allowing applications to "hook" interrupts. +The `INTTEST` application allows you to test this functionality. + +## Syntax + +`INTTEST` + +## Usage + +`INTTEST` is an interactive application. At startup, it will display +a list of the interrupt vector slots in your system along with the +current vector address for each of them. + +It then prompts you to enter the slot number (in hex) of a vector to +hook. After entering this, the application will watch the hooked +vector and countdown from 0xFF to 0x00 as interrupts are noted. + +When the counter reaches 0x00, the interrupt is unhooked and the +application terminates. The application can also be terminated by +pressing . + +## Notes + +If your system is running without interrupts active, the application +will terminate immediately. + +All slots have vectors even if the corresponding interrupt is not +doing anything. In this case, the vector is pointing to the "bad +interrupt" handler. + +If you hook a vector that is not receiving any interrupts, the +downcounter will not do anything. + +## Etymology + +The `INTTEST` command is an original product and the source code is +provided in the RomWBW distribution. + +`\clearpage`{=latex} + # FAT The operating systems included with RomWBW do not have any native -ability to access MS-DOS FAT filesystems. The FAT application can -be used overcome this. It will allow you to transfer files between -CP/M and FAT filesystems (wildcards supported). It can also -erase files, format, and list directories of FAT filesystems. +ability to access MS-DOS FAT filesystems. The FAT application can be +used overcome this. It will allow you to transfer files between CP/M +and FAT filesystems (wildcards supported). It can also erase files, +format, and list directories of FAT filesystems. ## Syntax @@ -674,144 +876,146 @@ erase files, format, and list directories of FAT filesystems. | *``* is a RomWBW disk unit number | CP/M filespec: *``*`:FILENAME.EXT` (*``* is CP/M drive letter A-P) -| FAT filespec: *``*`:/DIR/FILENAME.EXT` (*``* is RomWBW disk unit #) +| FAT filespec: *``*`:/DIR/FILENAME.EXT` (*``* is RomWBW disk unit #) ## Usage -The `FAT` application determines whether you are referring to a -CP/M filesystem or a FAT filesystem based on the way you specify -the file or path. If the file or path is prefixed with a number (n:), -then it is assumed this is a FAT filesystem reference and is referring -to the FAT filesystem on RomWBW disk unit 'n'. Otherwise, the -file specification is assumed to be a normal CP/M file specification. +The `FAT` application determines whether you are referring to a CP/M +filesystem or a FAT filesystem based on the way you specify the file +or path. If the file or path is prefixed with a number (n:), then it +is assumed this is a FAT filesystem reference and is referring to the +FAT filesystem on RomWBW disk unit 'n'. Otherwise, the file +specification is assumed to be a normal CP/M file specification. If you wanted to list the directory of the FAT filesystem on RomWBW -disk unit 2, you would use `FAT DIR 2:`. If you only wanted to -see the ".TXT" files, you would use `FAT DIR 2:*.TXT` +disk unit 2, you would use `FAT DIR 2:`. If you only wanted to see the +".TXT" files, you would use `FAT DIR 2:*.TXT`. -If you wanted to copy all of the files on CP/M drive B: to the -FAT filesystem on RomWBW disk unit 4, you would use the command -`FAT COPY B:*.* 4:` If you wanted to copy the files to the "FOO" -directory, then you would use `FAT COPY B:*.* 4:\FOO`. To copy -files in the opposite direction, you just reverse the parameters. +If you wanted to copy all of the files on CP/M drive B: to the FAT +filesystem on RomWBW disk unit 4, you would use the command `FAT COPY +B:*.* 4:` If you wanted to copy the files to the "FOO" directory, then +you would use `FAT COPY B:*.* 4:\FOO`. To copy files in the opposite +direction, you just reverse the parameters. -To rename the file "XXX.DAT" to "YYY.DAT" on a FAT filesystem, -you could use a command like "FAT REN 2:XXX.DAT 2:YYY.DAT". +To rename the file "XXX.DAT" to "YYY.DAT" on a FAT filesystem, you +could use a command like "FAT REN 2:XXX.DAT 2:YYY.DAT". -To delete a file "XXX.DAT" on a FAT filesystem in directory "FOO", -you would use a command like `FAT DEL 2:\FOO\XXX.DAT`. +To delete a file "XXX.DAT" on a FAT filesystem in directory "FOO", you +would use a command like `FAT DEL 2:\FOO\XXX.DAT`. -To make a directory called "FOO2" on a FAT filesystem, you would -use a command line `FAT MD 2:\FOO2`. +To make a directory called "FOO2" on a FAT filesystem, you would use a +command line `FAT MD 2:\FOO2`. To format the filesystem on a FAT partition, you would use a command -like `FAT FORMAT 2:`. Use this with caution because it will destroy +like `FAT FORMAT 2:`. Use this with caution because it will destroy all data on any pre-existing FAT filesystem on disk unit 2. ## Notes -Partitioned or non-partitioned media is handled automatically. -A floppy drive is a good example of a non-partitioned FAT -filesystem and will be recognized. Larger media will typically -have a partition table which will be recognized by the -application to find the FAT filesystem. +Partitioned or non-partitioned media is handled automatically. A +floppy drive is a good example of a non-partitioned FAT filesystem and +will be recognized. Larger media will typically have a partition +table which will be recognized by the application to find the FAT +filesystem. Although RomWBW-style CP/M media does not know anything about -partition tables, it is entirely possible to have media that -has both CP/M and FAT file systems on it. This is accomplished -by creating a FAT filesystem on the media that starts on a track -beyond the last track used by CP/M. Each CP/M slice on a -media will occupy a little over 8MB. So, make sure to start -your FAT partition beyond (slice count) * 8MB. - -The application infers whether you are attempting to reference -a FAT or CP/M filesystem via the drive specifier (char before ':'). -A numeric drive character specifies the HBIOS disk unit number -for FAT access. An alpha (A-P) character indicates a CP/M -file system access targeting the specified drive letter. If there -is no drive character specified, the current CP/M filesystem and -current CP/M drive is assumed. For example: - -"2:README.TXT" refers to FAT file README.TXT on disk unit #2 -"C:README.TXT" refers to CP/M file README.TXT on CP/M drive C -"README.TXT" refers to CP/M file README.TXT on the current CP/M drive - -Files with SYS, HIDDEN, or R/O only attributes are not given -any special treatment. Such files are found and processed -like any other file. However, any attempt to write to a -read-only file will fail and the application will abort. - -It is not currently possible to reference CP/M user areas other -than the current user. To copy files to alternate user areas, -you must switch to the desired user number first or use an -additional step to copy the file to the desired user area. - -Accessing FAT filesystems on a floppy requires the use of -RomWBW HBIOS v2.9.1-pre.13 or greater. +partition tables, it is entirely possible to have media that has both +CP/M and FAT file systems on it. This is accomplished by creating a +FAT filesystem on the media that starts on a track beyond the last +track used by CP/M. Each CP/M slice on a media will occupy 8,320K +(16,640 sectors). So, make sure to start your FAT partition beyond (< +slice count> * 8,320K) or (`* -*``* is the name of a sound file ending in .PT2, .PT3, or .MYM +*``* is the name of a sound file ending in .PT2, .PT3, or +.MYM ## Usage -The TUNE application supports PT and YM sound file formats. It -determines the format of the file from the extension of the file, -so your tune filenames should end in .PT2, .PT3, or .MYM. +The TUNE application supports PT and YM sound file formats. It +determines the format of the file from the extension of the file, so +your tune filenames should end in .PT2, .PT3, or .MYM. To play a sound file, just use the command and specify the file to -play after the command. So, for example, `TUNE ATTACK.PT2` will +play after the command. So, for example, `TUNE ATTACK.PT2` will immediately begin playing the PT sound file "ATTACK.PT2". ## Notes -The `TUNE` application automatically probes for compatible hardware -at well known port addresses at startup. It will auto-configure -itself for the hardware found. If no hardware is detected, it will -abort with an error message. +The `TUNE` application automatically probes for compatible hardware at +well known port addresses at startup. It will auto-configure itself +for the hardware found. If no hardware is detected, it will abort with +an error message. On Z180 systems, I/O wait states are added when writing to the sound -chip to avoid exceeding it's speed limitations. +chip to avoid exceeding it's speed limitations. On Z80 systems, you +will need to ensure that the CPU clock speed of your system does not +exceed the timing limitations of your sound chip. The application probes for an active system timer and uses it to -accurately pace the sound file output. If no system timer is -available, a delay loop is calculated instead. The delay loop will -not be as accurate as the system timer. +accurately pace the sound file output. If no system timer is +available, a delay loop is calculated instead. The delay loop will not +be as accurate as the system timer. All RomWBW operating system boot disks include a selection of sound files in user area 3. ## Etymology -The `TUNE` application was custom written for RomWBW. All of the -hardware interface code is specific to RomWBW. The sound file -decoding software was adapted and embedded from pre-existing -sources. The YM player code is from MYMPLAY 0.4 by Lieves!Tuore -and the PT player code is (c)2004-2007 S.V.Bulba - +The `TUNE` application was custom written for RomWBW. All of the +hardware interface code is specific to RomWBW. The sound file decoding +software was adapted and embedded from pre-existing sources. The YM +player code is from MYMPLAY 0.4 by Lieves!Tuore and the PT player code +is (c)2004-2007 S.V.Bulba . -The source code is provided in the RomWBW distribution. +The source code is provided in the RomWBW distribution. \ No newline at end of file diff --git a/Source/Doc/Architecture.md b/Source/Doc/Architecture.md index 6968f2dd..2d545893 100644 --- a/Source/Doc/Architecture.md +++ b/Source/Doc/Architecture.md @@ -16,7 +16,7 @@ toc-depth: 1 numbersections: true secnumdepth: 1 papersize: letter -geometry: +geometry: - top=1in - bottom=1in - left=1in @@ -94,17 +94,17 @@ ROM. RomWBW firmware includes: -- System startup code (bootstrap) +* System startup code (bootstrap) -- A basic system/debug monitor +* A basic system/debug monitor -- HBIOS (Hardware BIOS) providing support for the vast majority of - RetroBrew Computers I/O components +* HBIOS (Hardware BIOS) providing support for the vast majority of +RetroBrew Computers I/O components -- A complete operating system (either CP/M 2.2 or ZSDOS 1.1) +* A complete operating system (either CP/M 2.2 or ZSDOS 1.1) -- A built-in CP/M filesystem containing the basic applications and - utilities for the operating system and hardware being used +* A built-in CP/M filesystem containing the basic applications and +utilities for the operating system and hardware being used It is appropriate to note that much of the code and components that make up a complete RomWBW package are derived from pre-existing work. Most @@ -297,12 +297,12 @@ a ROM Boot. Notes ----- -1. Size of ROM disk and RAM disk will be decreased as needed to - accommodate RAM and ROM memory bank usage for the banked BIOS. +1. Size of ROM disk and RAM disk will be decreased as needed to +accommodate RAM and ROM memory bank usage for the banked BIOS. -2. There is no support for interrupt driven drivers at this time. Such - support should be possible in a variety of ways, but none are yet - implemented. +2. There is no support for interrupt driven drivers at this time. Such +support should be possible in a variety of ways, but none are yet +implemented. Driver Model ============ @@ -375,22 +375,51 @@ HBIOS Reference Invocation ---------- -HBIOS functions are invoked by placing the required parameters in CPU registers and executing an RST 08 instruction. Note that HBIOS does not preserve register values that are unused. However, it will not modify the Z80 alternate registers or IX/IY (these registers may be used within HBIOS, but will be saved and restored internally). - -Normally, applications will not call HBIOS functions directly. It is intended that the operating system makes all HBIOS function calls. Applications that are considered system utilities may use HBIOS, but must be careful not to modify the operating environment in any way that the operating system does not expect. - -In general, the desired function is placed in the B register. Register C is frequently used to specify a subfunction or a target device unit number. Additional registers are used as defined by the specific function. Register A should be used to return function result information. A=0 should indicate success, other values are function specific. - -The character, disk, and video device functions all refer to target devices using a logical device unit number that is passed in the C register. Keep in mind that these unit numbers are assigned dynamically at HBIOS initialization during the device discovery process. The assigned unit numbers are displayed on the consoled at the conclusion of device initialization. The unit assignments will never change after HBIOS initialization. However, they can change at the next boot if there have been hardware or BIOS customization changes. Code using HBIOS functions should not assume fixed unit assignments. - -Some functions utilize pointers to memory buffers. Unless otherwise stated, such buffers can be located anywhere in the Z80 CPU 64K address space. However, performance sensitive buffers (primarily disk I/O buffers) will require double-buffering if the caller’s buffer is in the lower 32K of CPU address space. For optimal performance, such buffers should be placed in the upper 32K of CPU address space. - -\newpage +HBIOS functions are invoked by placing the required parameters in CPU +registers and executing an RST 08 instruction. Note that HBIOS does not +preserve register values that are unused. However, it will not modify the +Z80 alternate registers or IX/IY (these registers may be used within HBIOS, +but will be saved and restored internally). + +Normally, applications will not call HBIOS functions directly. It is +intended that the operating system makes all HBIOS function calls. +Applications that are considered system utilities may use HBIOS, but must +be careful not to modify the operating environment in any way that the +operating system does not expect. + +In general, the desired function is placed in the B register. Register C is +frequently used to specify a subfunction or a target device unit number. +Additional registers are used as defined by the specific function. Register +A should be used to return function result information. A=0 should +indicate success, other values are function specific. + +The character, disk, and video device functions all refer to target devices +using a logical device unit number that is passed in the C register. Keep +in mind that these unit numbers are assigned dynamically at HBIOS +initialization during the device discovery process. The assigned unit +numbers are displayed on the consoled at the conclusion of device +initialization. The unit assignments will never change after HBIOS +initialization. However, they can change at the next boot if there have +been hardware or BIOS customization changes. Code using HBIOS functions +should not assume fixed unit assignments. + +Some functions utilize pointers to memory buffers. Unless otherwise stated, +such buffers can be located anywhere in the Z80 CPU 64K address space. +However, performance sensitive buffers (primarily disk I/O buffers) will +require double-buffering if the caller’s buffer is in the lower 32K of CPU +address space. For optimal performance, such buffers should be placed in +the upper 32K of CPU address space. + +`\clearpage`{=latex} Character Input/Output (CIO) ---------------------------- -Character input/output functions require that a Character Unit be specified in the C register. This is the logical device unit number assigned during the boot process that identifies all character I/O devices uniquely. A special value of 0x80 can be used for Unit to refer to the current console device. +Character input/output functions require that a Character Unit be specified +in the C register. This is the logical device unit number assigned during +the boot process that identifies all character I/O devices uniquely. A +special value of 0x80 can be used for Unit to refer to the current console +device. Character devices can usually be configured with line characteristics such as speed, framing, etc. A word value (16 bit) is used to describe @@ -420,8 +449,9 @@ bits are defined as YXXXX. | A: Status (0=OK, else error) | E: Character Received -Read a character from the device unit specified in register C and return the character -value in E. If no character(s) are available, this function will wait indefinitely. +Read a character from the device unit specified in register C and return +the character value in E. If no character(s) are available, this function +will wait indefinitely. ### Function 0x01 -- Character Output (CIOOUT) @@ -433,8 +463,8 @@ value in E. If no character(s) are available, this function will wait indefinite | _Exit Results_ | A: Status (0=OK, else error) -Send character value in register E to device specified in register C. If device is -not ready to send, function will wait indefinitely. +Send character value in register E to device specified in register C. If +device is not ready to send, function will wait indefinitely. ### Function 0x02 -- Character Input Status (CIOIST) @@ -445,10 +475,10 @@ not ready to send, function will wait indefinitely. | _Exit Results_ | A: Bytes Pending -Return the number of characters available to read in the input buffer of the unit -specified. If the device has no input buffer, it is acceptable to return simply 0 or -1 where 0 means there is no character available to read and 1 means there is at -least one character available to read. +Return the number of characters available to read in the input buffer of +the unit specified. If the device has no input buffer, it is acceptable to +return simply 0 or 1 where 0 means there is no character available to read +and 1 means there is at least one character available to read. ### Function 0x03 -- Character Output Status (CIOOST) @@ -459,11 +489,12 @@ least one character available to read. | _Exit Results_ | A: Output Buffer Bytes Available -Return the space available in the output buffer expressed as a character count. If a -16 byte output buffer contained 6 characters waiting to be sent, this function would -return 10, the number of positions available in the output buffer. If the port has -no output buffer, it is acceptable to return simply 0 or 1 where 0 means the port is -busy and 1 means the port is ready to output a character. +Return the space available in the output buffer expressed as a character +count. If a 16 byte output buffer contained 6 characters waiting to be +sent, this function would return 10, the number of positions available in +the output buffer. If the port has no output buffer, it is acceptable to +return simply 0 or 1 where 0 means the port is busy and 1 means the port is +ready to output a character. ### Function 0x04 -- Character IO Initialization (CIOINIT) @@ -475,10 +506,11 @@ busy and 1 means the port is ready to output a character. | _Exit Results_ | A: Status (0=OK, else error) -Setup line characteristics (baudrate, framing, etc.) of the specified unit. Register -pair DE specifies line characteristics. If DE contains -1 (0xFFFF), then the device -will be reinitialized with the last line characteristics used. Result of function -is returned in A with zero indicating success. +Setup line characteristics (baudrate, framing, etc.) of the specified unit. +Register pair DE specifies line characteristics. If DE contains -1 +(0xFFFF), then the device will be reinitialized with the last line +characteristics used. Result of function is returned in A with zero +indicating success. ### Function 0x05 -- Character IO Query (CIOQUERY) @@ -490,8 +522,8 @@ is returned in A with zero indicating success. | A: Status (0=OK, else error) | DE: Line Characteristics -Reports the line characteristics (baudrate, framing, etc.) of the specified unit. -Register pair DE contains the line characteristics upon return. +Reports the line characteristics (baudrate, framing, etc.) of the specified +unit. Register pair DE contains the line characteristics upon return. ### Function 0x06 -- Character IO Device (CIODEVICE) @@ -505,11 +537,14 @@ Register pair DE contains the line characteristics upon return. | D: Serial Device Type | E: Serial Device Number -Reports information about the character device unit specified. Register C indicates -the device attributes: 0=RS-232 and 1=Terminal. Register D indicates the device type -(driver) and register E indicates the physical device number assigned by the driver. +Reports information about the character device unit specified. Register C +indicates the device attributes: 0=RS-232 and 1=Terminal. Register D +indicates the device type (driver) and register E indicates the physical +device number assigned by the driver. -Each character device is handled by an appropriate driver (UART, ASCI, etc.). The driver can be identified by the Device Type. The assigned Device Types are listed below. +Each character device is handled by an appropriate driver (UART, ASCI, +etc.). The driver can be identified by the Device Type. The assigned Device +Types are listed below. _Id_ | _Device Type / Driver_ ---- | ---------------------- @@ -523,17 +558,18 @@ _Id_ | _Device Type / Driver_ 0x70 | PIO 0x80 | UF -\newpage +`\clearpage`{=latex} Disk Input/Output (DIO) ----------------------- -Character input/output functions require that a character unit be -specified in the C register. This is the logical disk unit number -assigned during the boot process that identifies all disk i/o devices -uniquely. +Character input/output functions require that a character unit be specified +in the C register. This is the logical disk unit number assigned during +the boot process that identifies all disk i/o devices uniquely. -A fixed set of media types are defined. The currently defined media types are listed below. Each driver will support a subset of the defined media types. +A fixed set of media types are defined. The currently defined media types +are listed below. Each driver will support a subset of the defined media +types. **Media ID** | **Value** | **Format** ------------ | --------- | ---------- @@ -565,9 +601,9 @@ MID\_FD111 | 9 | 8" 1.11M Floppy | _Exit Results_ | A: Status (0=OK, else error) -Reset the physical interface associated with the specified unit. Flag -all units associated with the interface for unit initialization at next -I/O call. Clear media identified unless locked. Reset result code of all +Reset the physical interface associated with the specified unit. Flag +all units associated with the interface for unit initialization at next +I/O call. Clear media identified unless locked. Reset result code of all associated units of the physical interface. ### Function 0x12 -- Disk Seek (DIOSEEK) @@ -588,9 +624,8 @@ associated units of the physical interface. | _Exit Results_ | A: Status (0=OK, else error) -Update target CHS or LBA for next I/O request on designated unit. -Physical seek is typically deferred until subsequent I/O -operation. +Update target CHS or LBA for next I/O request on designated unit. Physical +seek is typically deferred until subsequent I/O operation. Bit 7 of D indicates whether the disk seek address is specified as cylinder/head/sector (CHS) or Logical Block Address (LBA). If D:7=1, then @@ -613,17 +648,18 @@ determine if the device supports LBA addressing. | _Exit Results_ | A: Status (0=OK, else error) -| E: Blocks Reaad +| E: Blocks Read Read Block Count sectors to buffer address starting at current target -sector. Current sector must be established by prior seek function; -however, multiple read/write/verify function calls can be made after a -seek function. Current sector is incremented after each sector -successfully read. On error, current sector is sector is sector where -error occurred. Blocks read indicates number of sectors successfully read. +sector. Current sector must be established by prior seek function; however, +multiple read/write/verify function calls can be made after a seek +function. Current sector is incremented after each sector successfully +read. On error, current sector is sector is sector where error occurred. +Blocks read indicates number of sectors successfully read. -Caller must ensure: 1) buffer address is large enough to contain data for all -sectors requested, and 2) entire buffer area resides in upper 32K of memory. +Caller must ensure: 1) buffer address is large enough to contain data for +all sectors requested, and 2) entire buffer area resides in upper 32K of +memory. ### Function 0x14 -- Disk Write (DIOWRITE) @@ -638,15 +674,15 @@ sectors requested, and 2) entire buffer area resides in upper 32K of memory. | E: Blocks Written Write Block Count sectors to buffer address starting at current target -sector. Current sector must be established by prior seek function; -however, multiple read/write/verify function calls can be made after a -seek function. Current sector is incremented after each sector -successfully written. On error, current sector is sector is sector where -error occurred. Blocks written indicates number of sectors successfully -written. +sector. Current sector must be established by prior seek function; however, +multiple read/write/verify function calls can be made after a seek +function. Current sector is incremented after each sector successfully +written. On error, current sector is sector is sector where error occurred. +Blocks written indicates number of sectors successfully written. -Caller must ensure: 1) buffer address is large enough to contain data for all -sectors being written, and 2) entire buffer area resides in upper 32K of memory. +Caller must ensure: 1) buffer address is large enough to contain data for +all sectors being written, and 2) entire buffer area resides in upper 32K +of memory. ### Function 0x15 -- Disk Verify (DIOVERIFY) @@ -782,7 +818,7 @@ block size. If media is unknown, an error will be returned. Report current media geometry information. If media is unknown, return error (no media). -\newpage +`\clearpage`{=latex} Real Time Clock (RTC) --------------------- @@ -836,8 +872,8 @@ pointed to by HL. | A: Status (0=OK, else error) | E: Value -Read a single byte value from the Non-Volatile RAM at the index -specified by C. The value is returned in register E. +Read a single byte value from the Non-Volatile RAM at the index specified +by C. The value is returned in register E. ### Function 0x23 -- RTC Set NVRAM Byte (RTCSETBYT) @@ -849,8 +885,8 @@ specified by C. The value is returned in register E. | A: Status (0=OK, else error) | E: Value -Write a single byte value into the Non-Volatile RAM at the index -specified by C. The value to be written is specified in E. +Write a single byte value into the Non-Volatile RAM at the index specified +by C. The value to be written is specified in E. ### Function 0x24 -- RTC Get NVRAM Block (RTCGETBLK) @@ -873,9 +909,10 @@ to by HL. HL must point to a location in the top 32K of CPU address space. | _Exit Results_ | A: Status (0=OK, else error) -Write the entire contents of the Non-Volatile RAM from the buffer -pointed to by HL. HL must point to a location in the top 32K of CPU -address space. +Write the entire contents of the Non-Volatile RAM from the buffer pointed +to by HL. HL must point to a location in the top 32K of CPU address space. + +`\clearpage`{=latex} Video Display Adapter (VDA) --------------------------- @@ -889,11 +926,10 @@ attributes may or may not be supported. If the hardware does not support these capabilities, they will be ignored. Color byte values are constructed using typical RGBI -(Red/Green/Blue/Intensity) bits. The high four bits of the value -determine the background color and the low four bits determine the -foreground color. This results in 16 unique color values for both -foreground and background. The following table illustrates the color -byte value construction: +(Red/Green/Blue/Intensity) bits. The high four bits of the value determine +the background color and the low four bits determine the foreground color. +This results in 16 unique color values for both foreground and background. +The following table illustrates the color byte value construction:   | **Bit** | **Color** ---------- | ------- | --------- @@ -1254,6 +1290,8 @@ Keycodes are generally returned as appropriate ASCII values, if possible. Special keys, like function keys, are returned as reserved codes as described at the start of this section. +`\clearpage`{=latex} + System (SYS) ------------ @@ -1364,10 +1402,10 @@ change. WARNINGS: * This function is inherently dangerous and does not prevent you from - corrupting critical areas of memory. Use with **extreme** caution. +corrupting critical areas of memory. Use with **extreme** caution. * Overlapping source and destination memory ranges are not supported and - will result in undetermined behavior. +will result in undetermined behavior. * Copying of byte ranges that cross bank boundaries is undefined. @@ -1409,7 +1447,7 @@ allocated memory. | A: Status (0=OK, else error) This function will report various system information based on the -sub-function value. The following lists the subfunctions +sub-function value. The following lists the subfunctions available along with the registers/information returned. #### SYSGET Subfunction 0x00 -- Get Serial Device Unit Count (CIOCNT) @@ -1581,50 +1619,59 @@ The bank specified is not range checked. | _Returned Values_ | A: Status (0=OK, else error) -This function allows the caller to query information about the interrupt configuration of -the running system and allows adding or hooking interrupt handlers dynamically. Register C -is used to specify a subfunction. Additional input and output registers may be used as -defined by the sub-function. +This function allows the caller to query information about the interrupt +configuration of the running system and allows adding or hooking interrupt +handlers dynamically. Register C is used to specify a subfunction. +Additional input and output registers may be used as defined by the +sub-function. -Note that during interrupt processing, the lower 32K of CPU address space will contain the -RomWBW HBIOS code bank, not the lower 32K of application TPA. As such, a dynamically -installed interrupt handler does not have access to the lower 32K of TPA and must be -careful to avoid modifying the contents of the lower 32K of memory. Invoking RomWBW HBIOS -functions within an interrupt handler is not supported. +Note that during interrupt processing, the lower 32K of CPU address space +will contain the RomWBW HBIOS code bank, not the lower 32K of application +TPA. As such, a dynamically installed interrupt handler does not have +access to the lower 32K of TPA and must be careful to avoid modifying the +contents of the lower 32K of memory. Invoking RomWBW HBIOS functions +within an interrupt handler is not supported. Interrupt handlers are different for IM1 or IM2. For IM1: -> The new interrupt handler is responsible for chaining (JP) to the previous vector if the - interrupt is not handled. If the interrupt is handled, the new handler may simply return - (RET). When chaining to the previous interrupt handler, ZF must be set if interrupt is - handled and ZF cleared if not handled. The interrupt management framework takes care of - saving and restoring AF, BC, DE, HL, and IY. Any other registers modified must be saved - and restored by the interrupt handler. +> The new interrupt handler is responsible for chaining (JP) to the +previous vector if the interrupt is not handled. If the interrupt is +handled, the new handler may simply return (RET). When chaining to the +previous interrupt handler, ZF must be set if interrupt is handled and +ZF cleared if not handled. The interrupt management framework takes care +of saving and restoring AF, BC, DE, HL, and IY. Any other registers +modified must be saved and restored by the interrupt handler. For IM2: -> The new interrupt handler may either replace or hook the previous interrupt handler. To - replace the previous interrupt handler, the new handler just returns (RET) when done. To - hook the previous handler, the new handler can chain (JP) to the previous vector. Note - that initially all IM2 interrupt vectors are set to be handled as “BAD” meaning that the - interrupt is unexpected. In most cases, you do not want to chain to the previous vector - because it will cause the interrupt to display a “BAD INT” system panic message. - - The interrupt framework will take care of issuing an EI and RETI instruction. Do not put - these instructions in your new handler. Additionally, interrupt management framework takes care of saving and restoring AF, BC, DE, HL, and IY. Any other registers modified must be saved and restored by the interrupt handler. - - -If the caller is transient, then the caller must remove the new interrupt handler and -restore the original one prior to termination. This is accomplished by calling this -function with the Interrupt Vector set to the Previous Vector returned in the original call. - -The caller is responsible for disabling interrupts prior to making an INTSET call and -enabling them afterwards. The caller is responsible for ensuring that a valid interrupt -handler is installed prior to enabling any hardware interrupts associated with the handler. -Also, if the handler is transient, the caller must disable the hardware interrupt(s) -associated with the handler prior to uninstalling it. +> The new interrupt handler may either replace or hook the previous +interrupt handler. To replace the previous interrupt handler, the new +handler just returns (RET) when done. To hook the previous handler, the +new handler can chain (JP) to the previous vector. Note that initially +all IM2 interrupt vectors are set to be handled as “BAD” meaning that the +interrupt is unexpected. In most cases, you do not want to chain to the +previous vector because it will cause the interrupt to display a “BAD +INT” system panic message. + +The interrupt framework will take care of issuing an EI and RETI +instruction. Do not put these instructions in your new handler. +Additionally, interrupt management framework takes care of saving and +restoring AF, BC, DE, HL, and IY. Any other registers modified must be +saved and restored by the interrupt handler. + +If the caller is transient, then the caller must remove the new interrupt +handler and restore the original one prior to termination. This is +accomplished by calling this function with the Interrupt Vector set to the +Previous Vector returned in the original call. + +The caller is responsible for disabling interrupts prior to making an +INTSET call and enabling them afterwards. The caller is responsible for +ensuring that a valid interrupt handler is installed prior to enabling any +hardware interrupts associated with the handler. Also, if the handler is +transient, the caller must disable the hardware interrupt(s) associated +with the handler prior to uninstalling it. #### SYSINT Subfunction 0x00 -- Interrupt Info (INTINF) @@ -1636,9 +1683,9 @@ associated with the handler prior to uninstalling it. | D: Interrupt Mode | E: Size (# entries) of Interrupt Vector Table -Return interrupt mode in D and size of interrupt vector table in E. For -IM1, the size of the table is the number of vectors chained together. -For IM2, the size of the table is the number of slots in the vector +Return interrupt mode in D and size of interrupt vector table in E. For +IM1, the size of the table is the number of vectors chained together. +For IM2, the size of the table is the number of slots in the vector table. #### SYSINT Subfunction 0x10) -- Get Interrupt (INTGET) @@ -1651,8 +1698,8 @@ table. | A: Status (0=OK, else error) | HL: Current Interrupt Vector Address -On entry, register E must contain an index into the interrupt vector -table. On return, HL will contain the address of the current interrupt +On entry, register E must contain an index into the interrupt vector +table. On return, HL will contain the address of the current interrupt vector at the specified index. #### SYSINT Subfunction 0x20) -- Set Interrupt (INTSET) @@ -1667,6 +1714,7 @@ vector at the specified index. | HL: Previous Interrupt Vector Address | DE: Interrupt Routing Engine Address (IM2) -On entry, register E must contain an index into the interrupt vector table and register HL -must contain the address of the new interrupt vector to be inserted in the table at the -index. On return, HL will contain the previous address in the table at the index. +On entry, register E must contain an index into the interrupt vector table +and register HL must contain the address of the new interrupt vector to +be inserted in the table at the index. On return, HL will contain the +previous address in the table at the index. diff --git a/Source/Doc/GettingStarted.md b/Source/Doc/GettingStarted.md index ff32af7c..fa4c5337 100644 --- a/Source/Doc/GettingStarted.md +++ b/Source/Doc/GettingStarted.md @@ -44,54 +44,103 @@ header-includes: ### Download - * [RomWBW Distribution Package](https://github.com/wwarthen/RomWBW/releases) +* [RomWBW Distribution Package](https://github.com/wwarthen/RomWBW/releases) ### Related Pages - * [RomWBW Architecture Document](https://www.retrobrewcomputers.org/lib/exe/fetch.php?media=software:firmwareos:romwbw:romwbw_architecture.pdf) - * [RomWBW Applications](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps) - * [RomWBW Errata](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:errata) +* [RomWBW Architecture Document](https://www.retrobrewcomputers.org/lib/exe/fetch.php?media=software:firmwareos:romwbw:romwbw_architecture.pdf) +* [RomWBW Applications](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps) +* [RomWBW Errata](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:errata) # Overview -RomWBW provides a complete software system for a wide variety of hobbyist Z80/Z180 CPU-based systems produced by these developer communities: +RomWBW provides a complete software system for a wide variety of hobbyist +Z80/Z180 CPU-based systems produced by these developer communities: - * [RetroBrew Computers](https://www.retrobrewcomputers.org) - * [RC2014](https://rc2014.co.uk) - * [retro-comp](https://groups.google.com/forum/#!forum/retro-comp) +* [RetroBrew Computers](https://www.retrobrewcomputers.org) +* [RC2014](https://rc2014.co.uk) +* [retro-comp](https://groups.google.com/forum/#!forum/retro-comp) General features include: - * Banked memory services for several banking designs - * Disk drivers for RAM, ROM, Floppy, IDE, CF, and SD - * Serial drivers including UART (16550-like), ASCI, ACIA, SIO - * Video drivers including TMS9918, SY6545, MOS8563, HD6445 - * Real time clock drivers including DS1322, BQ4845 - * Multiple OS support including CP/M 2.2, ZSDOS, CP/M 3, ZPM3 - * 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 media devices (IDE Disk, CF Card, SD Card) 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 providing up to 2GB of accessible storage on a single device. - -The pre-built ROM firmware images are generally optimal 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 are included -- no need to install assemblers, etc. Any modern computer running Windows, Linux, or MacOS can be used. - -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. +* Banked memory services for several banking designs +* Disk drivers for RAM, ROM, Floppy, IDE, CF, and SD +* Serial drivers including UART (16550-like), ASCI, ACIA, SIO +* Video drivers including TMS9918, SY6545, MOS8563, HD6445 +* Real time clock drivers including DS1322, BQ4845 +* Multiple OS support including CP/M 2.2, ZSDOS, CP/M 3, ZPM3 +* 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 media devices (IDE Disk, CF Card, SD Card) 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 optimal 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 are included -- no +need to install assemblers, etc. Any modern computer running Windows, +Linux, or MacOS can be used. + +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. # 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 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. - -In general, you will just program your system's ROM chip with the appropriate ROM image from the RomWBW distribution. Depending on how you got your system, you may have already been provided with a pre-programmed ROM chip. If so, use that initially. Otherwise, you will need to use a ROM programmer to initially program your ROM chip. Please refer to the documentation that came with your ROM programmer for more information. Once you have a running RomWBW system, you can generally update your ROM to a newer version in-situ with an included ROM Flashing tool (Will Sowerbutts' FLASH application) as described in the Upgrading section below. - -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 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. + +In general, you will just program your system's ROM chip with the +appropriate ROM image from the RomWBW distribution. Depending on how +you got your system, you may have already been provided with a +pre-programmed ROM chip. If so, use that initially. Otherwise, you +will need to use a ROM programmer to initially program your ROM chip. +Please refer to the documentation that came with your ROM programmer +for more information. Once you have a running RomWBW system, you can +generally update your ROM to a newer version in-situ with an included +ROM Flashing tool (Will Sowerbutts' FLASH application) as described in +the Upgrading section below. + +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 for your hardware. | Platform | ROM Image File | Baud | Description | | --------------| --------------------- | --------: | ------------------------------------------------ | @@ -109,23 +158,79 @@ Looking at the extracted distribution archive, You will see that the distributio | SC131 | SCZ180_131.rom | 115200 | Stephen Cousin's SC131 Z180 | | Dyno | DYNO_std.rom | 38400 | Steve Garcia's Z180 Dyno Computer | -\*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 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. - -Upon power-up, your terminal should display a sign-on banner within 2 seconds followed by hardware inventory and discovery information. When hardware initialization is completed, a boot loader prompt allows you to choose a ROM-based operating system, system monitor, application, or boot from a disk device. - -Initially, you should try the ROM boot options. By selecting either CP/M 2.2 or Z-System, the operating system will be loaded from ROM and you will see the a `B>` disk prompt. In this scenario, A: will be an empty RAM disk and B: will refer to your ROM disk containing some typical applications. This provides a simple environment for learning to use your system. Be aware that files saved to the RAM disk (A:) will disappear at the next power on (RAM is generally not persistent). Also note that attempts to save files to the ROM disk (B:) will fail because ROM is not writable. +\*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 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. + +Upon power-up, your terminal should display a sign-on banner within 2 +seconds followed by hardware inventory and discovery information. When +hardware initialization is completed, a boot loader prompt allows you to +choose a ROM-based operating system, system monitor, application, or boot +from a disk device. + +Initially, you should try the ROM boot options. By selecting either +CP/M 2.2 or Z-System, the selected operating system will be loaded +from ROM and you will see the a `B>` disk prompt. In this scenario, A: +will be an empty RAM disk and B: will refer to your ROM disk +containing some common applications. This provides a simple +environment for learning to use your system. Be aware that files saved +to the RAM disk (A:) will disappear at the next power on (RAM is +generally not persistent). Also note that attempts to save files to +the ROM disk (B:) will fail because ROM is not writable. # Upgrading -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 mechanism to start your system. - -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. +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 retain 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 +executable 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 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 is 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 @@ -150,39 +255,345 @@ Write complete: Reprogrammed 2/128 sectors. Verify (128 sectors) complete: OK! ``` -Obviously, there is some risk to this approach since any issues with the programming or ROM image could result in a non-functional system. +Obviously, there is some risk to this approach since any issues with the +programming or ROM image could result in a non-functional system. + +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 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. + +If the disk is bootable, you need to update the system tracks of the +disk.This is done using a SYSCOPY command such as `SYSCOPY +C:=B:ZSYS.SYS`. For a ZSDOS boot disk, use ZSYS.SYS. For a CP/M 2.2 +disk, use CPM.SYS. For a CP/M 3 or ZPM3 disk, use CPMLDR.SYS. +CPMLDR.SYS is not provided on the ROM disk, so you would need to +upload it from the distribution. + +Finally, if you have copies of any of the RomWBW custom applications +on your hard disk, you need to update them with the latest copies. The +following applications are found on your ROM disk. Use COPY to copy +them over any older versions of the app on your disk: + +* ASSIGN.COM +* SYSCOPY.COM +* MODE.COM +* FDU.COM (was FDTST.COM) +* OSLDR.COM +* FORMAT.COM +* XM.COM +* FLASH.COM +* FDISK80.COM +* TALK.COM +* RTC.COM +* TIMER.COM +* INTTEST.COM + +For example: `B>COPY ASSIGN.COM C:` + +Some RomWBW custom applications are too large to fit on the ROM disk. +If you are using any of these you will need to transfer them to your +system and then update all copies. These applications are found in +the Binary\\Apps directory of the distribution and in all of the disk +images. + +* FAT.COM +* TUNE.COM + +# 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 operating systems. + +## Inbuilt ROM Applications + +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. -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. +The following ROM applications are available at the boot loader prompt: + +| Application | | +| ----------- | -------------------------------------------------------------- | +| Monitor | Z80 system debug monitor w/ Intel Hex loader | +| Forth | Brad Rodriguez's ANSI compatible Forth language | +| Basic | Nascom 8K BASIC language | +| Tasty BASIC | Dimitri Theuling's Tiny BASIC implementation | +| Play | A simple video game (requires ANSI terminal emulation) | -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. +In general, the command to exit these applications and restart the +system is `BYE`. The exceptions are the Monitor which uses `B` and +Play which uses `Q`. -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. +Space is available in the ROM image for the inclusion of other +software. Any inbuilt application can be set up to launch +automatically at startup. -If the disk is bootable, you need to update the system tracks of the disk. This is done using a SYSCOPY command such as `SYSCOPY C:=B:ZSYS.SYS`. For a ZSDOS boot disk, use ZSYS.SYS. For a CP/M 2.2 disk, use CPM.SYS. For a CP/M 3 or ZPM3 disk, use CPMLDR.SYS. CPMLDR.SYS is not provided on the ROM disk, so you would need to upload it from the distribution. +## Devices and Units -Finally, if you have copies of any of the RomWBW custom applications on your hard disk, you need to update them with the latest copies. The following applications are found on your ROM disk. Use COPY to copy them over any older versions of the app on your disk: +In order to support a wide variety of hardware, RomWBW HBIOS uses a +modular approach to implementing device drivers and presenting devices +to the operating system. In general, all devices are classified as +one of the following: - * ASSIGN.COM - * FORMAT.COM - * OSLDR.COM - * SYSCOPY.COM - * TALK.COM - * FDU.COM (was FDTST.COM) - * XM.COM - * MODE.COM - * RTC.COM - * TIMER.COM - * INTTEST.COM +* Disk (Hard Disk, CF Card, SD Card, RAM/ROM Disk, etc.) +* Character (Serial Ports, Parallel Ports, etc.) +* Video (Video Display/Keyboard Interfaces) +* RTC/NVRAM (Real Time Clock, Non-volatile RAM) -For example: `B>COPY ASSIGN.COM C:` +HBIOS uses the concept of unit numbers to present a complex set of +hardware devices to the operating system. As an example, a typical +system might have a ROM Disk, RAM Disk, Floppy Drives, and Disk +Drives. All of these are considered Disk devices and are presented +to the operating system as generic block devices. This means that +the operating system does not need to understand the difference between +a floppy drive and a ROM disk. -# Using Disks +As RomWBW boots, it assigns a unit number to each device. This unit +number is used by the operating system to refer to the device. It is, +therefore, important to know the unit number assigned to each device. +This information is displayed in the unit summary table at startup. +Here is an example: + +``` +Unit Device Type Capacity/Mode +---------- ---------- ---------------- -------------------- +Char 0 UART0: RS-232 38400,8,N,1 +Char 1 UART1: RS-232 38400,8,N,1 +Disk 0 MD1: RAM Disk 384KB,LBA +Disk 1 MD0: ROM Disk 384KB,LBA +Disk 2 FD0: Floppy Disk 3.5",DS/HD,CHS +Disk 3 FD1: Floppy Disk 3.5",DS/HD,CHS +Disk 4 IDE0: CompactFlash 3815MB,LBA +Disk 5 IDE1: Hard Disk -- +Disk 6 PRPSD0: SD Card 1886MB,LBA +Video 0 CVDU0: CRT Text,80x25 +``` + +In this example, you can see that the system has a total of 7 Disk +Units numbered 0-6. There are also 2 Character Units and 1 Video +Unit. The table shows the unit numbers assigned to each of the +devices. Notice how the unit numbers are assigned sequentially +regardless of the specific device. + +There may or may not be media in the disk devices listed. For example, +the floppy disk devices (Disk Units 2 & 3) may not have a floppy in +the drive. Also note that Disk Unit 4 shows a disk capacity, but +Disk Unit 5 does not. This is because the PPIDE interface of the +system supports up to two drives, but there is only one actual drive +attached. A unit number is assigned to all possible devices +regardless of whether they have actual media installed at boot time. + +Note that Character Unit 0 is **always** the initial system console +by definition. + +If your system has an RTC/NVRAM device, it will not be listed in the +unit summary table. Since only a single RTC/NVRAM device can exist in +one system, unit numbers are not required nor used for this type of +device. + +## Drive Letter Assignment -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. +In legacy CP/M-type operating systems, drive letters were generally +mapped to disk drives in a completely fixed way. For example, drive A: +would **always** refer to the first floppy drive. Since RomWBW +supports a wide variety of hardware configurations, it implements a +much more flexible drive letter assignment mechanism so that any drive +letter can be assigned to any disk device. + +At boot, you will notice that RomWBW automatically assigns drive +letters to the available disk devices. These assignments are +displayed during the startup of the selected operating system. +Additionally, you can review the current drive assignments at any +time using the `ASSIGN` command. CP/M 3 and ZPM3 do not automatically +display the assignments at startup, but you can use `ASSIGN` do +display them. + +The drive letter assignments **do not** change during an OS session +unless you use the `ASSIGN` command yourself to do it. Additionally, +the assignments at boot will stay the same on each boot as long as you +do not make changes to your hardware configuration. Note that the +assignments **are** dependent on the media currently inserted in hard +disk drives. So, notice that if you insert or remove an SD Card or CF +Card, the drive assignments will change. Since drive letter +assignments can change, you must be careful when doing destructive +things like using `CLRDIR` to make sure the drive letter you use is +referring to the desired media. + +When performing a ROM boot of an operating system, note that A: will +be your RAM disk and B: will be your ROM disk. When performing a disk +boot, the disk you are booting from will be assigned to A: and the +rest of the drive letters will be offset to accommodate this. This is +done because most legacy operating systems expect that A: will be the +boot drive. -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. +## Slices + +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 usable 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 allows 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 : +** where ** 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". Here are some examples: + +| | | +| -------- | ---------------------------- | +| `IDE0:0` | First slice of disk in IDE0 | +| `IDE0:` | First slice of disk in IDE0 | +| `IDE0:3` | Fourth slice of disk in IDE0 | + +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. + +Unlike MS-DOS partitions, slices are not allocated -- there is no +partitioning for 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`. + +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. + +# RomWBW Custom Applications + +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 ROM disk and are, +therefore, globally available. + +| Application | Description | +| ----------- | -------------------------------------------------------------- | +| ASSIGN | Add, change, and delete drive letter assignments. Use ASSIGN /? for usage instructions. | +| SYSCOPY | Copy system image to a device to make it bootable. Use SYSCOPY with no parms for usage instructions. | +| FDU | Format and test floppy disks. Menu driven interface. | +| OSLDR | Load a new OS on the fly. For example, you can switch to Z-System when running CP/M. Use OSLDR with no parms for usage instructions. | +| FORMAT | Will someday be a command line tool to format floppy disks. Currently does nothing! | +| MODE | Reconfigures serial ports dynamically. | +| XM | XModem file transfer program adapted to hardware. Automatically uses primary serial port on system. | +| 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). | +| FLASH | Will Sowerbutts' in-situ ROM programming utility. | +| 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. + +| Application | Description | +| ----------- | -------------------------------------------------------------- | +| TUNE | Play .PT2, .PT3, .MYM audio files. | +| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). | + +There is additional documentation on some of these applications at the +[RomWBW Applications Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps). + +# Using Disks -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: +## ROM & RAM Disks + +RomWBW utilizes a portion of the ROM and RAM memory in your system to +implement small memory-based disks. + +The RAM disk provides a small CP/M filesystem that you can use for the +temporary storage of files. Unless your system has a battery backed +mechanism for persisting your RAM contents, the RAM disk contents will +be lost at each power-off. However, the RAM disk is an excellent +choice for storing temporary files because it is very fast. + +Like the RAM disk, the ROM disk also provides a small CP/M +filesystem, but it's contents are static -- they are part of the +ROM. As such, you cannot save files to the ROM disk. Any attempt to +do this will result in a disk I/O error. 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. + +## Disk Devices + +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. A wide variety of disk devices are supported 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 boot 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: ``` IDE: IO=0x80 MODE=MK4 @@ -190,9 +601,16 @@ IDE0: 8-BIT LBA BLOCKS=0x00773800 SIZE=3815MB IDE1: NO MEDIA ``` -The messages you see will vary depending on your hardware and the media you have installed. But, they will all have the same general format as the example above. +The messages you see will vary depending on your hardware and the +media you have installed. But, they will all have the same general +format as the example above. -Once your your system has working disk devices, you can boot an operating system and the operating system will have access to the media. At the boot loader prompt, select either either CP/M 2.2 or Z-System to boot from ROM. As the operating system starts up, you should see a list of drive letters assigned to the disk media you have installed. Here is an example of this: +Once your your system has working disk devices, you can boot an +operating system and the operating system will have access to the +media. At the boot loader prompt, select either either CP/M 2.2 or +Z-System to boot from ROM. As the operating system starts up, you +should see a list of drive letters assigned to the disk media you have +installed. Here is an example of this: ``` Configuring Drives... @@ -203,29 +621,86 @@ Configuring Drives... D:=IDE0:1 ``` -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. - -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 (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. +You will probably see more drive letters than this. The drive letter +assignment process is described above in the Drive Letter Assignment +section. 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 described above in the Slices section. + +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. + +One option is to 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. ## 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. - -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. - -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: +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. + +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 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` -This command means: copy the Z-System operating system onto the system tracks of drive C:. In this example, it is assumed that you have booted from ROM, so B: is the ROM disk drive. Additionally, this example assumes you want the Z-System operating system to be booted from C:. If you want CP/M 2.2 instead, you would replace `B:ZSYS.SYS` with `B:CPM.SYS`. Here is a full example of this process. +This command means: copy the Z-System operating system onto the +system tracks of drive C:. In this example, it is assumed that you +have booted from ROM, so B: is the ROM disk drive. Additionally, this +example assumes you want the Z-System operating system to be booted +from C:. If you want CP/M 2.2 instead, you would replace `B:ZSYS.SYS` +with `B:CPM.SYS`. Here is a full example of this process. ``` B>SYSCOPY C:=B:ZSYS.SYS @@ -237,17 +712,44 @@ Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y Reading image... Writing image... Done ``` -Once this process succeeds, you will be able to boot directly to the disk from the boot loader prompt. See the instructions in Booting Disks for details on this. +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 -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. - -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 following table shows the disk image files available. Note that the images in the "Hard" column are fine for use on CF Cards, SD Cards, as well as real spinning hard disks. +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. + +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 following table shows the disk image files available. Note that +the images in the "Hard" column are fine for use on CF Cards, SD +Cards, as well as real spinning hard disks. | Floppy | Hard | Description | | --------------- | --------------- | -------------------------------------- | @@ -258,7 +760,12 @@ The following table shows the disk image files available. Note that the images | fd_zpm3 | hd_zpm3.img | ZPM3 boot 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. 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. This is the layout of the hd_combo disk image: @@ -271,15 +778,35 @@ This is the layout of the hd_combo disk image: | Slice 4 | ZPM3 boot disk | | Slice 5 | WordStar v4 application disk | -Note that unlike the ROM firmware, you do **not** need to choose a disk image specific to your hardware. Because the RomWBW firmware provides a hardware abstraction layer, all hard disk images will work on all hardware variations. Yes, this means you can remove an SD Card from one system and put it in a different system. The only constraint is that the applications on the disk media must be up to date with the firmware on the system being used. +Note that unlike the ROM firmware, you do **not** need to choose a +disk image specific to your hardware. Because the RomWBW firmware +provides a hardware abstraction layer, all hard disk images will work +on all hardware variations. Yes, this means you can remove an SD Card +from one system and put it in a different system. The only constraint +is that the applications on the disk media must be up to date with +the firmware on the system being used. -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: +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 2. +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 @@ -297,233 +824,314 @@ 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 - -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 - -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 - -In legacy CP/M-type operating systems, drive letters were generally mapped to disk drives in a completely fixed way. For example, drive A: would **always** refer to the first floppy drive. Since RomWBW supports a wide variety of hardware configurations, it implements a much more flexible drive letter assignment mechanism so that any drive letter can be assigned to any disk device. - -At boot, you will notice that RomWBW automatically assigns drive letters to the available disk devices. These assignments are displayed during the startup of the selected operating system. Additionally, you can review the current drive assignments at any time using the `ASSIGN` command. CP/M 3 and ZPM3 do not automatically display the assignments at startup, but you can use `ASSIGN` do display them. - -The drive letter assignments **do not** change during an OS session unless you use the `ASSIGN` command yourself to do it. Additionally, the assignments at boot will stay the same on each boot as long as you do not make changes to your hardware configuration. Note that the assignments **are** dependent on the media currently inserted in hard disk drives. So, notice that if you insert or remove an SD Card or CF Card, the drive assignments will change. Since drive letter assignments can change, you must be careful when doing destructive things like using `CLRDIR` to make sure the drive letter you use is referring to the desired media. - -When performing a ROM boot of an operating system, note that A: will be your RAM disk and B: will be your ROM disk. When performing a disk boot, the disk you are booting from will be assigned to A: and the rest of the drive letters will be offset to accommodate this. This is done because most legacy operating systems expect that A: will be the boot drive. - -## Slices - -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 any of the first 256 8MB chunks of space on a single media. +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. -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. +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. -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. - -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`. - -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 - -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 ROM applications are available at the boot loader prompt: - -| Application | | -| ----------- | -------------------------------------------------------------- | -| Monitor | Z80 system debug monitor w/ Intel Hex loader | -| Forth | Brad Rodriguez's ANSI compatible Forth language | -| Basic | Nascom 8K BASIC language | -| Tasty BASIC | Dimitri Theuling's Tiny BASIC implementation | -| Play | A simple video game (requires ANSI terminal emulation) | - -In general, the command to exit these applications and restart the system is `BYE`. The exceptions are the Monitor which uses `B` and Play which uses `Q`. - -Space is available in the ROM image for the inclusion of other software. Any inbuilt application can be set up to launch automatically at startup. - -# RomWBW Custom Applications - -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 ROM disk and are, therefore, globally available. - -| Application | Description | -| ----------- | -------------------------------------------------------------- | -| ASSIGN | Add, change, and delete drive letter assignments. Use ASSIGN /? for usage instructions. | -| SYSCOPY | Copy system image to a device to make it bootable. Use SYSCOPY with no parms for usage instructions. | -| FDU | Format and test floppy disks. Menu driven interface. | -| OSLDR | Load a new OS on the fly. For example, you can switch to Z-System when running CP/M. Use OSLDR with no parms for usage instructions. | -| FORMAT | Will someday be a command line tool to format floppy disks. Currently does nothing! | -| MODE | Reconfigures serial ports dynamically. | -| XM | XModem file transfer program adapted to hardware. Automatically uses primary serial port on system. | -| 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). | -| FLASH | Will Sowerbutts' in-situ ROM programming utility. | -| 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. - -| Application | Description | -| ----------- | -------------------------------------------------------------- | -| TUNE | Play .PT2, .PT3, .MYM audio files. | -| FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). | - -There is additional documentation on some of these applications at the [RomWBW Applications Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:apps). +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. # Operating Systems -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 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. +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. ## Digital Research CP/M 2.2 -This is the most widely used variant of the Digital Research operating system. It has the most basic feature set, but is essentially the compatibility metric for all other CP/M-like operating systems including all of those listed below. The Doc directory contains a manual for CP/M usage ("CPM Manual.pdf"). If you are new to the CP/M world, I would recommend using this CP/M variant to start with simply because it is the most stable and you are less likely to encounter problems. +This is the most widely used variant of the Digital Research +operating system. It has the most basic feature set, but is +essentially the compatibility metric for all other CP/M-like +operating systems including all of those listed below. The Doc +directory contains a manual for CP/M usage ("CPM Manual.pdf"). If you +are new to the CP/M world, I would recommend using this CP/M variant +to start with simply because it is the most stable and you are less +likely to encounter problems. ## ZSDOS 1.1 -ZSDOS is the most popular non-DRI CP/M "clone" which is generally referred to as Z-System. Z-System is intended to be an enhanced version of CP/M and should run all CP/M 2.2 applications. It is optimized for the Z80 CPU (as opposed to 8080 for CP/M) and has some significant improvements such as date/time stamping of files. For further information on the RomWBW implementation of Z-System, see the wiki page [Z-System Notes](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:zsystem). Additionally, the official documentation for Z-System is included in the RomWBW distribution Doc directory ("ZSDOS Manual.pdf" and "ZCPR Manual.pdf"). +ZSDOS is the most popular non-DRI CP/M "clone" which is generally +referred to as Z-System. Z-System is intended to be an enhanced +version of CP/M and should run all CP/M 2.2 applications. It is +optimized for the Z80 CPU (as opposed to 8080 for CP/M) and has some +significant improvements such as date/time stamping of files. For +further information on the RomWBW implementation of Z-System, see the +wiki page +[Z-System Notes](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:romwbw:zsystem). +Additionally, the official documentation for Z-System is included in +the RomWBW distribution Doc directory ("ZSDOS Manual.pdf" and "ZCPR +Manual.pdf"). ## NZCOM Automatic Z-System -NZCOM is a much further refined version of Z-System (ZCPR 3.4). NZCOM was sold as an enhancement for existing users of CP/M 2.2 or ZSDOS. For this reason, (by design) NZCOM does not provide a way to boot directly from disk. Rather, it is loaded after the system boots into a host OS. On the RomWBW NZCOM disk images, the boot OS is ZSDOS 1.1. After you configure NZCOM, you can add a `PROFILE.SUB` file to automatically launch NZCOM at boot. +NZCOM is a much further refined version of Z-System (ZCPR 3.4). NZCOM +was sold as an enhancement for existing users of CP/M 2.2 or ZSDOS. +For this reason, (by design) NZCOM does not provide a way to boot +directly from disk. Rather, it is loaded after the system boots into +a host OS. On the RomWBW NZCOM disk images, the boot OS is ZSDOS 1.1. +After you configure NZCOM, you can add a `PROFILE.SUB` file to +automatically launch NZCOM at boot. -To use, NZCOM, you must run through a simple configuration process. This is well documented in the NZCOM manual in the "NZCOM Users Manual.pdf" file in the RomWBW Doc directory. Additionally, there are instructions for automatically launching NZCOM when the disk is booted under the host OS via an auto command submission process. +To use, NZCOM, you must run through a simple configuration process. +This is well documented in the NZCOM manual in the "NZCOM Users +Manual.pdf" file in the RomWBW Doc directory. Additionally, there are +instructions for automatically launching NZCOM when the disk is +booted under the host OS via an auto command submission process. ## 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 direct 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. ## Simeon Cran's ZPM3 -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 CPMLDR.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 -Note that Phillip Stevens has also ported FreeRTOS to run under RomWBW. -FreeRTOS is not provided in the RomWBW distribution. FreeRTOS is available -under the [MIT licence](https://www.freertos.org/a00114.html) -and further general information is available at +Note that Phillip Stevens has also ported FreeRTOS to run under +RomWBW. FreeRTOS is not provided in the RomWBW distribution. FreeRTOS +is available under the +[MIT licence](https://www.freertos.org/a00114.html) and further general +information is available at [FreeRTOS](https://www.freertos.org/RTOS.html). You can also contact Phillip for detailed information on the Z180 -implementation of FreeRTOS for RomWBW. [@feilipu](https://github.com/feilipu) +implementation of FreeRTOS for RomWBW. +[@feilipu](https://github.com/feilipu) # Transferring Files -Transferring files between your modern computer and your RomWBW system can be achieved in a variety of ways. The most common of these are described below. All of these have a certain degree of complexity and I encourage new users to use the available community forums to seek assistance as needed. +Transferring files between your modern computer and your RomWBW +system can be achieved in a variety of ways. The most common of these +are described below. All of these have a certain degree of complexity +and I encourage new users to use the available community forums to +seek assistance as needed. ## Serial Port Transfers -RomWBW provides an serial file transfer program called XModem that has been adapted to run under RomWBW hardware. The program is called `XM` and is on your ROM disk as well as all of the pre-built disk images. +RomWBW provides an serial file transfer program called XModem that +has been adapted to run under RomWBW hardware. The program is called +`XM` and is on your ROM disk as well as all of the pre-built disk +images. + +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 +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 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. -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. +## Disk Image Transfers -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. +It is possible to pass disk images between your RomWBW system and +your modern computer. This assumes you have an appropriate media slot +on your modern computer for the media you want to use (CF Card, SD +Card, or floppy drive). -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. +The general process to get files from your modern computer to a RomWBW +computer is: -## Disk Image Transfers +1. Use `cpmtools` on your modern computer to create a RomWBW CP/M +filesystem image. -It is possible to pass disk images between your RomWBW system and your modern computer. This assumes you have an appropriate media slot on your modern computer for the media you want to use (CF Card, SD Card, or floppy drive). +2. Insert your RomWBW media (CF Card, SD Card, or floppy disk) in your +modern computer. -The general process to get files from your modern computer to a RomWBW computer is: +3. Use a disk imaging tool to copy the RomWBW filesystem image onto the +media. -1. Use `cpmtools` on your modern computer to create a RomWBW CP/M filesystem image. -2. Insert your RomWBW media (CF Card, SD Card, or floppy disk) in your modern computer. -3. Use a disk imaging tool to copy the RomWBW filesystem image onto the media. 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 chance 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 directory 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 -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. - -On your RomWBW computer you can use the `FAT` application to access the FAT media. The `FAT` application allows you to read files, write files, list a directory, and erase files on the FAT media. It can handle subdirectories as well. It will only see 8.3 character filenames however. Longer filenames will show up as a truncated version. - -The `FAT` application is not on your ROM disk because it is too large to fit. You will find it on all of the pre-built disk images as well as in the Binary\\Apps directory of the distribution. - -For advanced users, it is possible to create a hybrid disk that contains CP/M slices at the beginning and a FAT filesystem after. Such a hybrid disk can be used to boot an operating system and still have access to FAT files on the FAT portion of the disk. David Reese has prepared a document describing how to do this. It is called "SC126_How-To_No_2_Preparing_an_SD_Card_for_Use_with_SC126_Rev_1-5.pdf" and can be found in the Doc\\Contrib directory of the distribution. +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, be sure to pick +the FAT filesystem. NTFS and other filesystems will not work. + +On your RomWBW computer you can use the `FAT` application to access +the FAT media. The `FAT` application allows you to read files, write +files, list a directory, and erase files on the FAT media. It can +handle subdirectories as well. It will only see 8.3 character +filenames however. Longer filenames will show up as a truncated +version. + +The `FAT` application is not on your ROM disk because it is too large +to fit. You will find it on all of the pre-built disk images as well +as in the Binary\\Apps directory of the distribution. + +For advanced users, it is possible to create a hybrid disk that +contains CP/M slices at the beginning and a FAT filesystem after. +Such a hybrid disk can be used to boot an operating system and still +have access to FAT files on the FAT portion of the disk. David Reese +has prepared a document describing how to do this. It is called +"SC126_How-To_No_2_Preparing_an_SD_Card_for_Use_with_SC126_Rev_1-5.pdf" +and can be found in the Doc\\Contrib directory of the distribution. # Startup Command Processing -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. +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 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`. +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 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. +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 -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 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. +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. -For those who are interested in more than basic system customization, note that all source code is provided (including the operating systems). Modification of the source code is considered an expert level task and is left to the reader to pursue. +For those who are interested in more than basic system customization, +note that all source code is provided (including the operating +systems). Modification of the source code is considered an expert +level task and is left to the reader to pursue. -Note that the ROM customization process does not apply to UNA. All UNA customization is performed within the ROM setup script. +Note that the ROM customization process does not apply to UNA. All +UNA customization is performed within the ROM setup script. # UNA Hardware BIOS -John Coffman has produced a new generation of hardware BIOS called UNA. The standard RomWBW distribution includes it's own hardware BIOS. However, RomWBW can alternatively be constructed with UNA as the hardware BIOS portion of the ROM. If you wish to use the UNA variant of RomWBW, then just program your ROM with the ROM image called "UNA_std.rom" in the Binary directory. This one image is suitable on **all** of the platforms and hardware UNA supports. - -UNA is customized dynamically using a ROM based setup routine and the setup is persisted in the system NVRAM of the RTC chip. This means that the single UNA-based ROM image can be used on most of the RetroBrew platforms and is easily customized. UNA also supports FAT file system access that can be used for in-situ ROM programming and loading system images. - -While John is likely to enhance UNA over time, there are currently a few things that UNA does not support: - - * Floppy Drives - * Terminal Emulation - * Zeta 1, N8, RC2014, Easy Z80, and Dyno Systems - * Some older support boards - -The UNA version embedded in RomWBW is the latest production release of UNA. RomWBW will be updated with John's upcoming UNA release with support for VGA3 as soon as it reaches production status. - -Please refer to the [UNA BIOS Firmware Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:una:start) for more information on UNA. +John Coffman has produced a new generation of hardware BIOS called +UNA. The standard RomWBW distribution includes it's own hardware +BIOS. However, RomWBW can alternatively be constructed with UNA as +the hardware BIOS portion of the ROM. If you wish to use the UNA +variant of RomWBW, then just program your ROM with the ROM image +called "UNA_std.rom" in the Binary directory. This one image is +suitable on **all** of the platforms and hardware UNA supports. + +UNA is customized dynamically using a ROM based setup routine and the +setup is persisted in the system NVRAM of the RTC chip. This means +that the single UNA-based ROM image can be used on most of the +RetroBrew platforms and is easily customized. UNA also supports FAT +file system access that can be used for in-situ ROM programming and +loading system images. + +While John is likely to enhance UNA over time, there are currently a +few things that UNA does not support: + +* Floppy Drives +* Terminal Emulation +* Zeta 1, N8, RC2014, Easy Z80, and Dyno Systems +* Some older support boards + +The UNA version embedded in RomWBW is the latest production release +of UNA. RomWBW will be updated with John's upcoming UNA release with +support for VGA3 as soon as it reaches production status. + +Please refer to the +[UNA BIOS Firmware Page](https://www.retrobrewcomputers.org/doku.php?id=software:firmwareos:una:start) +for more information on UNA. # RomWBW Distribution -All source code and distributions are maintained on GitHub. Code contributions are very welcome. +All source code and distributions are maintained on GitHub. Code +contributions are very welcome. [RomWBW GitHub Repository](https://github.com/wwarthen/RomWBW|https://github.com/wwarthen/RomWBW) ## Distribution Directory Layout -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: | Application | Description | | ----------- | -------------------------------------------------------------- | @@ -534,27 +1142,41 @@ The RomWBW distribution is a compressed zip archive file organized in a set of d # Acknowledgments -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!). - -I especially want to credit Douglas Goodall for contributing code, time, testing, and advice. He created an entire suite of application programs to enhance the use of RomWBW. However, he is looking for someone to continue the maintenance of these applications and they have become unusable due to changes within RomWBW. As of RomWBW 2.6, these applications are no longer provided. - - * David Giles contributed support for the CSIO support in the SD Card driver. - * Ed Brindley contributed some of the code that supports the RC2014 platform. - * Phil Summers contributed Forth and BASIC in ROM as well as a long list of general code enhancements. - * Phillip Stevens contributed support for FreeRTOS. - * Curt Mayer contributed the Linux / MacOS build process. - * UNA BIOS is a product of John Coffman. +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!). + +I especially want to credit Douglas Goodall for contributing code, +time, testing, and advice. He created an entire suite of application +programs to enhance the use of RomWBW. However, he is looking for +someone to continue the maintenance of these applications and they +have become unusable due to changes within RomWBW. As of RomWBW 2.6, +these applications are no longer provided. + +* David Giles contributed support for the CSIO support in the SD Card +driver. +* Ed Brindley contributed some of the code that supports the RC2014 +platform. +* Phil Summers contributed Forth and BASIC in ROM as well as a long +list of general code enhancements. +* Phillip Stevens contributed support for FreeRTOS. +* Curt Mayer contributed the Linux / MacOS build process. +* UNA BIOS and FDISK80 is a product of John Coffman. +* FLASH4 is a product of Will Sowerbutts. Contributions of all kinds to RomWBW are very welcome. # Getting Assistance -The best way to get assistance with RomWBW or any aspect of the RetroBrew Computers projects is via the community forums: +The best way to get assistance with RomWBW or any aspect of the +RetroBrew Computers projects is via 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) +* [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 !author at [!authmail](mailto:!authmail). +Also feel free to email !author at [!authmail](mailto:!authmail). \ No newline at end of file