diff --git a/Doc/RomWBW Architecture.pdf b/Doc/RomWBW Architecture.pdf index 9cc8f576..0c2782cc 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 50732c83..fa0f8640 100644 Binary files a/Doc/RomWBW Getting Started.pdf and b/Doc/RomWBW Getting Started.pdf differ diff --git a/Doc/ZCPR Manual.pdf b/Doc/ZCPR Manual.pdf index ce5f80b8..50668527 100644 Binary files a/Doc/ZCPR Manual.pdf and b/Doc/ZCPR Manual.pdf differ diff --git a/ReadMe.md b/ReadMe.md index 0899e120..0b5dcde6 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -2,7 +2,8 @@ ## Z80/Z180 System Software -Version 2.9.2 of March 18, 2020 +Version 2.9.2 +Friday 20 March 2020 Wayne Warthen @@ -26,7 +27,7 @@ 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) + - [RetroBrew Computers](https://www.retrobrewcomputers.org) - [RC2014](https://rc2014.co.uk) - [retro-comp](https://groups.google.com/forum/#!forum/retro-comp) @@ -79,11 +80,12 @@ distributions are found on the [releases page](https://github.com/wwarthen/RomWBW/releases) of the repository. On this page, you will probably see both pre-releases as well as normal releases. Unless you have a specific reason, I suggest you stick to the -most recent normal (not pre-release) release. Expand the “Assets” +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 called Source Code do not have the pre-built ROM or Disk Images. +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, @@ -109,13 +111,13 @@ 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: -| Platform | ROM Image File | Baud | Description | -| ------------- | --------------- | ------ | ----------------------------------------------- | -| SBC V1/V2 | SBC\_std.rom | 38400 | RetroBrew SBC v1 or v2 ECB Z80 | -| Zeta V1 | ZETA\_std.rom | 38400 | RetroBrew Zeta V1 Z80, ParPortProp (optional) | -| Zeta V2 | ZETA2\_std.rom | 38400 | RetroBrew Zeta V2 Z80, ParPortProp (optional) | -| N8 | N8\_std.rom | 38400 | RetroBrew N8 Z180, date code \>= 2312 | -| Mark IV | MK4\_std.rom | 38400 | RetroBrew Mark IV ECB Z180 | +| Platform | ROM Image File | Baud | Description | +| ------------- | --------------- | -----: | ----------------------------------------------- | +| SBC V1/V2 | SBC\_std.rom | 38400 | RetroBrew SBC v1 or v2 ECB Z80 | +| Zeta V1 | ZETA\_std.rom | 38400 | RetroBrew Zeta V1 Z80, ParPortProp (optional) | +| Zeta V2 | ZETA2\_std.rom | 38400 | RetroBrew Zeta V2 Z80, ParPortProp (optional) | +| N8 | N8\_std.rom | 38400 | RetroBrew N8 Z180, date code \>= 2312 | +| Mark IV | MK4\_std.rom | 38400 | RetroBrew Mark IV ECB Z180 | | RC2014 Z80 | RCZ80\_std.rom | 115200 | RC2014 w/ Z80 CPU, requires 512K RAM/ROM module | | RC2014 Z180\* | RCZ180\_ext.rom | 115200 | RC2014 w/ Z180 CPU & 512K banked RAM/ROM module | | RC2014 Z180\* | RCZ180\_nat.rom | 115200 | RC2014 w/ Z180 CPU & 512K native RAM/ROM module | @@ -123,12 +125,12 @@ the appropriate ROM image: | SC126 | SCZ180\_126.rom | 115200 | Stephen Cousin’s SC126 Z180 | | SC130 | SCZ180\_130.rom | 115200 | Stephen Cousin’s SC130 Z180 | | SC131 | SCZ180\_131.rom | 115200 | Stephen Cousin’s SC131 Z180 | -| Dyno | DYNO\_std.rom | 38400 | Steve Garcia’s Z180 Dyno Computer | +| 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 thrid-party Z180 +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 @@ -136,8 +138,8 @@ components for each of the systems supported. More information on the required system configuration and optional supported components for each ROM is found in the file called “RomList.txt” in the Binary directory. All pre-built ROM images are simple 512KB binary images. If your system -utilizes a 1MB ROM, you can just program the image into the first 512KB -of the ROM. +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 @@ -184,16 +186,19 @@ not been updated and the next time you boot your system, it will revert to the system image contained in ROM. You may find that you are unable to load the .com file because it is too large to fit in available application RAM (TPA). Unfortunately, in this case, you will not be able -to use the .com file to start your system. +to use the .com file mechanism to start your system. -If you do not have easy access to a ROM programmer, it is entirely +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. 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 new ROM image (.rom) over to your system using XModem (or one of the +other mechanisms described in the Transferring Files section below). The +ROM image will be too large to fit on your RAM drive, so you will need +to transfer it to a larger storage drive. Once the ROM image is on your +system, you can use the FLASH application to update your ROM. The +following is a typical example of transferring ROM image using XModem +and flashing the chip in-situ. E>xm r rom.img @@ -226,9 +231,9 @@ device yet. Review the boot messages to see if any issues have occurred. Once you are satisfied that the ROM is working well, you will need to update the system images and RomWBW custom applications on your disk drives. The system images and custom applications are matched to the -RomWBW ROM firmware in use. If you attempt to use a disk or applications -that have not been updated to match the current ROM firmware, you are -likely to have odd problems. +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 @@ -272,7 +277,8 @@ 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. +need to refer to the documentation for your system for your specific +options. In the RomWBW bootup messages, you will see hardware discovery messages. If you have a disk drive interface, you should see messages listing @@ -304,7 +310,7 @@ an example of this: C:=IDE0:0 D:=IDE0:1 -You will probably see mroe drive letters than this. The drive letter +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 @@ -322,13 +328,13 @@ is also explained later in this document. Once you are seeing drive letters referring to your disk media, you can follow the instructions below to begin using the disk media with the -operating system. Your disk media **must** be initialized prior to be +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. +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 @@ -343,40 +349,38 @@ 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 +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 +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 +Running `CLRDIR` on a disk device is roughly equivalent to running +FORMAT on MS-DOS. Note that unlike MS-DOS you do **not** partition your +mass storage device. CP/M knows nothing about disk partitions. You may +notice a partitioning application on your ROM disk (FDISK80), but this +is strictly for an advanced technique of adding an MS-DOS FAT filesystem +to your media in addition to the CP/M area. Do not use FDISK80 unless +you are specifically attempting to add an MS-DOS FAT filesystem to your media. If you are using a floppy drive, you will need to physically format your floppy disk prior to use. This is only required for floppy disks, not hard disk, CF Cards, or SD Cards, etc. To format a floppy drive, you can -use the interactive application FDU. FDU is not terribly user friendly, -but is generally documented in the file “FDU.txt” found in the Doc -directory of the distribution. It is not necessary to run CLRDIR on a -floppy disk after physically formatting it – the directory is cleared as -part of the formatting. - -## Booting Disks +use the interactive application `FDU`. FDU is not terribly user +friendly, but is generally documented in the file “FDU.txt” found in the +Doc directory of the distribution. It is not necessary to run `CLRDIR` +on a floppy disk after physically formatting it – the directory is +cleared as part of the formatting. Once you have initialized a disk device and copied your desired files -onto it, you may want to boot directly to this disk device at startup. -On CP/M filesystems, you must perform one additional step to make a disk -bootable. Specifically, you need to place a copy of the oeoprating -system on the system tracks of the disk. This is done using the -`SYSCOPY` command. Let’s say you have prepared drive C: by initializing -it with `CLRDIR` and copied some files onto it. You can now make C: -bootable by running the following command: +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` @@ -395,49 +399,9 @@ you want CP/M 2.2 instead, you would replace `B:ZSYS.SYS` with Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y Reading image... Writing image... Done -After successfully putting the operating system on the disk, you can -restart your system. When you get to the boot loader, notice the line -starting with “Disk:”. This line lists the disk devices that you can -choose to boot directly. - -You will notice that you do not have an option to boot a drive letter -here (like C:). This is because the operating system is not yet loaded. -When you ran `SYSCOPY` previously, remember that C: was assigned to -IDE0:0 which means device IDE0, slice 0. So, to boot the disk that you -just setup with SYSCOPY, you would choose option 1. You will then be -prompted for the slice on IDE0 that you want to boot. For now, just -press enter to choose slice 0. Once you are familiar with slices, you -can `SYSCOPY` and boot alternate slices. Here is what you would see when -booting to a disk device: - - MARK IV Boot Loader - - ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM - Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1 - - Boot Selection? 2 Slice(0-9)[0]? - - Booting Disk Unit 2, Slice 0... - - Reading disk information... - Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive - - Loading... - -Following this, you would see the normal operating system startup -messages. However, your operating system prompt will be `A>` and when -you look at the drive letter assignments, you should see that A: has -been assigned to the disk you selected to boot. - -If you receive the error message “Disk not bootable\!”, you have either -failed to properly run `SYSCOPY` on the target disk or you have selected -the wrong disk/slice. - -Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed -in the Disk boot line, they are not currently “bootable” disks because -they have no system tracks on them. Attempting to boot to one of them, -will fail with a “Disk not bootable\!” error message and return to the -loader prompt. +Once this process succeeds, you will be able to boot directly to the +disk from the boot loader prompt. See the instructions in Booting Disks +for details on this. ## Disk Images @@ -447,8 +411,8 @@ It is generally easier to use these disk images instead of copying all the files over using XModem. You use your modern computer (Windows, Linux, MacOS) to place the disk image onto the disk media, then just move the media over to your system. In this scenario you **do not** run -`CLRDIR` or `SYSCOPY` on the drive(s). The directory prepared and the -disk is already bootable, if it is an operating system. +`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 @@ -459,7 +423,7 @@ you can use the `dd` command on Linux or MacOS. On Windows, in the 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. +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 @@ -474,11 +438,11 @@ well as real spinning hard disks. | Floppy | Hard | Description | | ------------- | ------------- | ---------------------------- | -| fd\_cpm22.img | hd\_cpm22.img | DRI CP/M 2.2 bootable disk | -| fd\_zsdos.img | hd\_zsdos.img | ZSDOS 1.1 bootable disk | -| fd\_nzcom.img | hd\_nzcom.img | NZCOM bootable disk | -| fd\_cpm3 | hd\_cpm3.img | DRI CP/M 3 bootable disk | -| fd\_zpm3 | hd\_zpm3.img | ZPM3 bootable disk | +| fd\_cpm22.img | hd\_cpm22.img | DRI CP/M 2.2 boot disk | +| fd\_zsdos.img | hd\_zsdos.img | ZSDOS 1.1 boot disk | +| fd\_nzcom.img | hd\_nzcom.img | NZCOM boot disk | +| fd\_cpm3 | hd\_cpm3.img | DRI CP/M 3 boot disk | +| fd\_zpm3 | hd\_zpm3.img | ZPM3 boot disk | | fd\_ws4 | hd\_ws4.img | WordStar v4 application disk | In addition to the disk images above, there is also a special hard disk @@ -512,6 +476,52 @@ boot from disk as is. You do not need to run `SYSCOPY` on them to make them bootable. However, if you upgrade your ROM, you should use `SYSCOPY` to update the system tracks. +## Booting Disks + +When starting your system, following the hardware initialization, you +will see the Boot Loader prompt. In addition, to the ROM boot options, +you will see another line listing the Disk boot options. This line lists +the disk devices that you can choose to boot directly. + +You will notice that you do not have an option to boot a drive letter +here (like C:). This is because the operating system is not yet loaded. +When you ran `SYSCOPY` previously, remember that C: was assigned to +IDE0:0 which means device IDE0, slice 0. So, to boot the disk that you +just setup with `SYSCOPY`, you would choose option 1. You will then be +prompted for the slice on IDE0 that you want to boot. For now, just +press enter to choose slice 0. Once you are familiar with slices, you +can `SYSCOPY` and boot alternate slices. Here is what you would see when +booting to a disk device: + + MARK IV Boot Loader + + ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM + Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1 + + Boot Selection? 2 Slice(0-9)[0]? + + Booting Disk Unit 2, Slice 0... + + Reading disk information... + Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive + + Loading... + +Following this, you would see the normal operating system startup +messages. However, your operating system prompt will be `A>` and when +you look at the drive letter assignments, you should see that A: has +been assigned to the disk you selected to boot. + +If you receive the error message “Disk not bootable\!”, you have either +failed to properly run `SYSCOPY` on the target disk or you have selected +the wrong disk/slice. + +Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed +in the Disk boot line, they are not “bootable” disks because they have +no system tracks on them. Attempting to boot to one of them, will fail +with a “Disk not bootable\!” error message and return to the loader +prompt. + # General Usage Each of the operating systems and ROM applications included with RomWBW @@ -519,18 +529,18 @@ are sophisticated tools in their own right. It is not reasonable to document their usage here. However, you will find complete manuals in PDF format in the Doc directory of the distribution. The intention of this section is to document the RomWBW specific enhancements to these -OSes. +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 have -been optimized to provide a core set of tools and applications that are -helpful for either CP/M 2.2 and ZSDOS. Since ZSDOS is CP/M 2.2 -compatible, this works fairly well. However, you will find some files on -the ROM disk that will work with ZSDOS, but will not work on CP/M 2.2. -For example, `LDDS`, which loads the ZSDOS date/time stamper will only -run on ZSDOS. +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 @@ -577,8 +587,8 @@ accessible to any of the operating systems. Since storage devices today are quite large, RomWBW implements a mechanism called slicing to allow up to 256 8MB filesystems on a single large storage device. This allows up to 2GB of useable space on a single -media. You can think of slices as a way to refer to the first 256 8MB -chunks of space on a single media. +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 @@ -594,10 +604,10 @@ devices, you will see that each device is allocated four drive letters. Referring to slices within a storage device is done by appending a :n where n is the device relative slice number from 0-255. For example, if -you have an IDE device, it will show up as IDE0: in the boot message -meaning the first IDE device. To refer to the second slice of IDE0, you -would type “IDE0:1”. So, if I wanted to use drive letter L: to refer to -the second slice of IDE0, I could use the command `ASSIGN L:=IDE0:1`. +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 @@ -618,22 +628,22 @@ 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`. +that yourself using `CLRDIR`. Since `CLRDIR` works on drive letters, +make absolutely sure you know what media and slice are assigned to that +drive letter before using `CLRDIR`. -While it probably obvious, you cannot use slices on any media less than -8MB in size. Specifically, you cannot slice RAM disk, ROM disk, floppy -disks, etc. +While it is probably obvious, you cannot use slices on any media less +than 8MB in size. Specifically, you cannot slice RAM disks, ROM disks, +floppy disks, etc. # Inbuilt ROM Applications -In addition to CP/M 2.2 and Z-System, there are several additional ROM -applications that can be launched directly from ROM. These applications -are not hosted by an operating system and so they are unable to save -files to disk devices. +In addition to CP/M 2.2 and Z-System, there are several ROM applications +that can be launched directly from ROM. These applications are not +hosted by an operating system and so they are unable to save files to +disk devices. -The following options are available at the boot loader prompt: +The following ROM applications are available at the boot loader prompt: | Application | | | ----------- | ------------------------------------------------------ | @@ -657,8 +667,8 @@ The operation of the RomWBW hosted operating systems is enhanced through several custom applications. These applications are functional on all of the OS variants included with RomWBW. -The following custom applications are found on the RomWBW ROM disk and -are, therefore, globally available. +The following custom applications are found on the ROM disk and are, +therefore, globally available. | Application | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | @@ -672,7 +682,7 @@ are, therefore, globally available. | 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 | Format the directory areas of a CP/M disk. | +| CLRDIR | Initialize the directory area of a CP/M disk (Max Scane). | Some custom applications do not fit on the ROM disk. They are found on the disk image files or the individual files can be found in the @@ -697,9 +707,9 @@ identical for all hardware supported by RomWBW because RomWBW hides all hardware specifics from the operating system. Note that all of the operating systems included with RomWBW support the -same basic filesystem format. As as result, a formatted filesystem will +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 of date/time stamping using the newer OSes, the older OSes +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. @@ -748,7 +758,7 @@ OS via an auto command submission process. This is the Digital Research follow-up product to their very popular CP/M 2.2 operating system. While highly compatible with CP/M 2.2, it -features many enhancements. It makes better use of banked memory to +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. @@ -761,14 +771,14 @@ tracks. ZPM3 is an interesting combination of the features of both CP/M 3 and ZCPR 3. Essentially, it has the features of and compatibility with both. -Like CP/M 3, to make ZPM3 boot disk, you put CPM3.SYS on the system +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, but is available -from Phillip. +FreeRTOS is not provided in the RomWBW distribution. You can contact +Phillip for availability. # Transferring Files @@ -790,18 +800,18 @@ file on your RomWBW system. Then, you will use your modern computers terminal program to complete the process. The `XM` application generally tries to detect the hardware you are -using and adapt to it. However, you must ensure that you have a -realiable serial connection. You must also ensure that the speed of the -connection is not too fast for XModem to handle. Alternatively, you can -ensure that hardware flow control is working properly. +using and adapt to it. However, you must ensure that you have a reliable +serial connection. You must also ensure that the speed of the connection +is not too fast for XModem to service. Alternatively, you can ensure +that hardware flow control is working properly. There is an odd interaction between XModem and partner terminal programs that can occur. Essentially, after launching `XM`, you must start the -protocol on your modern computer fairly quickly (usually about 20 +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 casuses this is beyond the scope of -this document. +then hangs. The interaction that causes this is beyond the scope of this +document. ## Disk Image Transfers @@ -823,7 +833,7 @@ computer is: This process is a little complicated, but it has the benefit of allowing you to get a lot of files over to your RomWBW system quickly and with -little change of corruption. +little chance of corruption. The process can be run in reverse to get files from your RomWBW computer to a modern computer. @@ -835,14 +845,14 @@ documents. Note that the build scripts for RomWBW create the default disk images supplied with RomWBW. It is relatively easy to customize the contents of the disk images that are part of RomWBW. This is described in more -detail in the Source\\Images driectory of the distribution. +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 an +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 read/write the +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 @@ -868,23 +878,24 @@ and can be found in the Doc\\Contrib directory of the distribution. # Startup Command Processing -Each of the operating system supported by RomWBW provide a mechanism to +Each of the operating systems supported by RomWBW provide a mechanism to run commands at boot. This is similar to the AUTOEXEC.BAT files from MS-DOS. -With the exception of ZPM3, all operating system will look for a file +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. +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. -Note that automatic startup processing generally requires booting to a -disk drive. Since the ROM disk is not writable, there is no simple way +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. @@ -900,10 +911,11 @@ a build script, but it is quite easy to do. Essentially, the creation of a custom ROM is accomplished by updating a small configuration file, then running a script to compile the software -and generate the custom ROM image. There are build scripts for Windows, -Linux, and MacOS to accommodate virtually all users. All required build -tools (compilers, assemblers, etc.) are included in the distribution, so -it is not necessary to setup a build environment on your computer. +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. @@ -951,6 +963,12 @@ for more information on UNA. # RomWBW Distribution +All source code and distributions are maintained on GitHub. Code +contributions are very welcome. + +[RomWBW GitHub +Repository](https://github.com/wwarthen/RomWBW%7Chttps://github.com/wwarthen/RomWBW) + ## Distribution Directory Layout The RomWBW distribution is a compressed zip archive file organized in a @@ -965,14 +983,6 @@ are: | Source | Contains the source code files used to build the software and ROM images. | | Tools | Contains the MS Windows programs that are used by the build process or that may be useful in setting up your system. | -## Source Code Respository - -All source code and distributions are maintained on GitHub. Code -contributions are very welcome. - -[RomWBW GitHub -Repository](https://github.com/wwarthen/RomWBW%7Chttps://github.com/wwarthen/RomWBW) - # Acknowledgements While I have heavily modified much of the code, I want to acknowledge diff --git a/ReadMe.txt b/ReadMe.txt index ff28b03f..e7bd9d64 100644 --- a/ReadMe.txt +++ b/ReadMe.txt @@ -2,7 +2,8 @@ RomWBW Z80/Z180 System Software -Version 2.9.2 of March 18, 2020 +Version 2.9.2 +Friday 20 March 2020 Wayne Warthen wwarthen@gmail.com @@ -22,7 +23,7 @@ RomWBW provides a complete software system for a wide variety of hobbyist Z80/Z180 CPU-based systems produced by these developer communities: -- Retrobrew Computers +- RetroBrew Computers - RC2014 - retro-comp @@ -73,12 +74,12 @@ The latest RomWBW distribution downloads are maintained on GitHub in the RomWBW Repository. The fully-built distributions are found on the releases page of the repository. On this page, you will probably see both pre-releases as well as normal releases. Unless you have a specific -reason, I suggest you stick to the most recent normal (not pre-release) -release. Expand the “Assets” drop-down for the release you want to +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 called Source Code do not have the -pre-built ROM or Disk Images. +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, @@ -105,44 +106,44 @@ files all end in “.rom”. Based on the table below, carefully pick the appropriate ROM image: -------------------------------------------------------------------------- - Platform ROM Image File Baud Description + Platform ROM Image File Baud Description ---------- ---------------- -------- ------------------------------------- - SBC V1/V2 SBC_std.rom 38400 RetroBrew SBC v1 or v2 ECB Z80 + SBC V1/V2 SBC_std.rom 38400 RetroBrew SBC v1 or v2 ECB Z80 - Zeta V1 ZETA_std.rom 38400 RetroBrew Zeta V1 Z80, ParPortProp + Zeta V1 ZETA_std.rom 38400 RetroBrew Zeta V1 Z80, ParPortProp (optional) - Zeta V2 ZETA2_std.rom 38400 RetroBrew Zeta V2 Z80, ParPortProp + Zeta V2 ZETA2_std.rom 38400 RetroBrew Zeta V2 Z80, ParPortProp (optional) - N8 N8_std.rom 38400 RetroBrew N8 Z180, date code >= 2312 + N8 N8_std.rom 38400 RetroBrew N8 Z180, date code >= 2312 - Mark IV MK4_std.rom 38400 RetroBrew Mark IV ECB Z180 + Mark IV MK4_std.rom 38400 RetroBrew Mark IV ECB Z180 - RC2014 Z80 RCZ80_std.rom 115200 RC2014 w/ Z80 CPU, requires 512K + RC2014 Z80 RCZ80_std.rom 115200 RC2014 w/ Z80 CPU, requires 512K RAM/ROM module - RC2014 RCZ180_ext.rom 115200 RC2014 w/ Z180 CPU & 512K banked + RC2014 RCZ180_ext.rom 115200 RC2014 w/ Z180 CPU & 512K banked Z180* RAM/ROM module - RC2014 RCZ180_nat.rom 115200 RC2014 w/ Z180 CPU & 512K native + RC2014 RCZ180_nat.rom 115200 RC2014 w/ Z180 CPU & 512K native Z180* RAM/ROM module - Easy Z80 EZZ80_std.rom 115200 Sergey Kiselev’s Easy Z80 + Easy Z80 EZZ80_std.rom 115200 Sergey Kiselev’s Easy Z80 - SC126 SCZ180_126.rom 115200 Stephen Cousin’s SC126 Z180 + SC126 SCZ180_126.rom 115200 Stephen Cousin’s SC126 Z180 - SC130 SCZ180_130.rom 115200 Stephen Cousin’s SC130 Z180 + SC130 SCZ180_130.rom 115200 Stephen Cousin’s SC130 Z180 - SC131 SCZ180_131.rom 115200 Stephen Cousin’s SC131 Z180 + SC131 SCZ180_131.rom 115200 Stephen Cousin’s SC131 Z180 - Dyno DYNO_std.rom 38400 Steve Garcia’s Z180 Dyno Computer + 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 thrid-party Z180 +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 @@ -150,8 +151,8 @@ components for each of the systems supported. More information on the required system configuration and optional supported components for each ROM is found in the file called “RomList.txt” in the Binary directory. All pre-built ROM images are simple 512KB binary images. If your system -utilizes a 1MB ROM, you can just program the image into the first 512KB -of the ROM. +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 @@ -198,16 +199,19 @@ not been updated and the next time you boot your system, it will revert to the system image contained in ROM. You may find that you are unable to load the .com file because it is too large to fit in available application RAM (TPA). Unfortunately, in this case, you will not be able -to use the .com file to start your system. +to use the .com file mechanism to start your system. -If you do not have easy access to a ROM programmer, it is entirely +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. 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 new ROM image (.rom) over to your system using XModem (or one of the +other mechanisms described in the Transferring Files section below). The +ROM image will be too large to fit on your RAM drive, so you will need +to transfer it to a larger storage drive. Once the ROM image is on your +system, you can use the FLASH application to update your ROM. The +following is a typical example of transferring ROM image using XModem +and flashing the chip in-situ. E>xm r rom.img @@ -240,9 +244,9 @@ device yet. Review the boot messages to see if any issues have occurred. Once you are satisfied that the ROM is working well, you will need to update the system images and RomWBW custom applications on your disk drives. The system images and custom applications are matched to the -RomWBW ROM firmware in use. If you attempt to use a disk or applications -that have not been updated to match the current ROM firmware, you are -likely to have odd problems. +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 @@ -286,7 +290,8 @@ 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. +need to refer to the documentation for your system for your specific +options. In the RomWBW bootup messages, you will see hardware discovery messages. If you have a disk drive interface, you should see messages listing @@ -318,7 +323,7 @@ an example of this: C:=IDE0:0 D:=IDE0:1 -You will probably see mroe drive letters than this. The drive letter +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 @@ -336,13 +341,13 @@ is also explained later in this document. Once you are seeing drive letters referring to your disk media, you can follow the instructions below to begin using the disk media with the -operating system. Your disk media must be initialized prior to be used. -There are two ways to initialize your media for use. +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. +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 @@ -380,16 +385,14 @@ directory of the distribution. It is not necessary to run CLRDIR on a floppy disk after physically formatting it – the directory is cleared as part of the formatting. -Booting Disks - Once you have initialized a disk device and copied your desired files -onto it, you may want to boot directly to this disk device at startup. -On CP/M filesystems, you must perform one additional step to make a disk -bootable. Specifically, you need to place a copy of the oeoprating -system on the system tracks of the disk. This is done using the SYSCOPY -command. Let’s say you have prepared drive C: by initializing it with -CLRDIR and copied some files onto it. You can now make C: bootable by -running the following command: +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 @@ -408,49 +411,9 @@ Here is a full example of this process. Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y Reading image... Writing image... Done -After successfully putting the operating system on the disk, you can -restart your system. When you get to the boot loader, notice the line -starting with “Disk:”. This line lists the disk devices that you can -choose to boot directly. - -You will notice that you do not have an option to boot a drive letter -here (like C:). This is because the operating system is not yet loaded. -When you ran SYSCOPY previously, remember that C: was assigned to IDE0:0 -which means device IDE0, slice 0. So, to boot the disk that you just -setup with SYSCOPY, you would choose option 1. You will then be prompted -for the slice on IDE0 that you want to boot. For now, just press enter -to choose slice 0. Once you are familiar with slices, you can SYSCOPY -and boot alternate slices. Here is what you would see when booting to a -disk device: - - MARK IV Boot Loader - - ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM - Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1 - - Boot Selection? 2 Slice(0-9)[0]? - - Booting Disk Unit 2, Slice 0... - - Reading disk information... - Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive - - Loading... - -Following this, you would see the normal operating system startup -messages. However, your operating system prompt will be A> and when you -look at the drive letter assignments, you should see that A: has been -assigned to the disk you selected to boot. - -If you receive the error message “Disk not bootable!”, you have either -failed to properly run SYSCOPY on the target disk or you have selected -the wrong disk/slice. - -Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed -in the Disk boot line, they are not currently “bootable” disks because -they have no system tracks on them. Attempting to boot to one of them, -will fail with a “Disk not bootable!” error message and return to the -loader prompt. +Once this process succeeds, you will be able to boot directly to the +disk from the boot loader prompt. See the instructions in Booting Disks +for details on this. Disk Images @@ -460,8 +423,8 @@ It is generally easier to use these disk images instead of copying all the files over using XModem. You use your modern computer (Windows, Linux, MacOS) to place the disk image onto the disk media, then just move the media over to your system. In this scenario you do not run -CLRDIR or SYSCOPY on the drive(s). The directory prepared and the disk -is already bootable, if it is an operating system. +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 @@ -487,11 +450,11 @@ well as real spinning hard disks. Floppy Hard Description -------------- -------------- ------------------------------ - fd_cpm22.img hd_cpm22.img DRI CP/M 2.2 bootable disk - fd_zsdos.img hd_zsdos.img ZSDOS 1.1 bootable disk - fd_nzcom.img hd_nzcom.img NZCOM bootable disk - fd_cpm3 hd_cpm3.img DRI CP/M 3 bootable disk - fd_zpm3 hd_zpm3.img ZPM3 bootable disk + fd_cpm22.img hd_cpm22.img DRI CP/M 2.2 boot disk + fd_zsdos.img hd_zsdos.img ZSDOS 1.1 boot disk + fd_nzcom.img hd_nzcom.img NZCOM boot disk + fd_cpm3 hd_cpm3.img DRI CP/M 3 boot disk + fd_zpm3 hd_zpm3.img ZPM3 boot disk fd_ws4 hd_ws4.img WordStar v4 application disk In addition to the disk images above, there is also a special hard disk @@ -525,6 +488,52 @@ boot from disk as is. You do not need to run SYSCOPY on them to make them bootable. However, if you upgrade your ROM, you should use SYSCOPY to update the system tracks. +Booting Disks + +When starting your system, following the hardware initialization, you +will see the Boot Loader prompt. In addition, to the ROM boot options, +you will see another line listing the Disk boot options. This line lists +the disk devices that you can choose to boot directly. + +You will notice that you do not have an option to boot a drive letter +here (like C:). This is because the operating system is not yet loaded. +When you ran SYSCOPY previously, remember that C: was assigned to IDE0:0 +which means device IDE0, slice 0. So, to boot the disk that you just +setup with SYSCOPY, you would choose option 1. You will then be prompted +for the slice on IDE0 that you want to boot. For now, just press enter +to choose slice 0. Once you are familiar with slices, you can SYSCOPY +and boot alternate slices. Here is what you would see when booting to a +disk device: + + MARK IV Boot Loader + + ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM + Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1 + + Boot Selection? 2 Slice(0-9)[0]? + + Booting Disk Unit 2, Slice 0... + + Reading disk information... + Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive + + Loading... + +Following this, you would see the normal operating system startup +messages. However, your operating system prompt will be A> and when you +look at the drive letter assignments, you should see that A: has been +assigned to the disk you selected to boot. + +If you receive the error message “Disk not bootable!”, you have either +failed to properly run SYSCOPY on the target disk or you have selected +the wrong disk/slice. + +Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed +in the Disk boot line, they are not “bootable” disks because they have +no system tracks on them. Attempting to boot to one of them, will fail +with a “Disk not bootable!” error message and return to the loader +prompt. + General Usage Each of the operating systems and ROM applications included with RomWBW @@ -532,18 +541,18 @@ are sophisticated tools in their own right. It is not reasonable to document their usage here. However, you will find complete manuals in PDF format in the Doc directory of the distribution. The intention of this section is to document the RomWBW specific enhancements to these -OSes. +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 have -been optimized to provide a core set of tools and applications that are -helpful for either CP/M 2.2 and ZSDOS. Since ZSDOS is CP/M 2.2 -compatible, this works fairly well. However, you will find some files on -the ROM disk that will work with ZSDOS, but will not work on CP/M 2.2. -For example, LDDS, which loads the ZSDOS date/time stamper will only run -on ZSDOS. +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 @@ -590,8 +599,8 @@ accessible to any of the operating systems. Since storage devices today are quite large, RomWBW implements a mechanism called slicing to allow up to 256 8MB filesystems on a single large storage device. This allows up to 2GB of useable space on a single -media. You can think of slices as a way to refer to the first 256 8MB -chunks of space on a single media. +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 @@ -607,10 +616,10 @@ devices, you will see that each device is allocated four drive letters. Referring to slices within a storage device is done by appending a :n where n is the device relative slice number from 0-255. For example, if -you have an IDE device, it will show up as IDE0: in the boot message -meaning the first IDE device. To refer to the second slice of IDE0, you -would type “IDE0:1”. So, if I wanted to use drive letter L: to refer to -the second slice of IDE0, I could use the command ASSIGN L:=IDE0:1. +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 @@ -635,18 +644,18 @@ that yourself using CLRDIR. Since CLRDIR works on drive letters, make absolutely sure you know what media and slice are assigned to that drive letter before using CLRDIR. -While it probably obvious, you cannot use slices on any media less than -8MB in size. Specifically, you cannot slice RAM disk, ROM disk, floppy -disks, etc. +While it is probably obvious, you cannot use slices on any media less +than 8MB in size. Specifically, you cannot slice RAM disks, ROM disks, +floppy disks, etc. Inbuilt ROM Applications -In addition to CP/M 2.2 and Z-System, there are several additional ROM -applications that can be launched directly from ROM. These applications -are not hosted by an operating system and so they are unable to save -files to disk devices. +In addition to CP/M 2.2 and Z-System, there are several ROM applications +that can be launched directly from ROM. These applications are not +hosted by an operating system and so they are unable to save files to +disk devices. -The following options are available at the boot loader prompt: +The following ROM applications are available at the boot loader prompt: Application ------------- -------------------------------------------------------- @@ -670,8 +679,8 @@ The operation of the RomWBW hosted operating systems is enhanced through several custom applications. These applications are functional on all of the OS variants included with RomWBW. -The following custom applications are found on the RomWBW ROM disk and -are, therefore, globally available. +The following custom applications are found on the ROM disk and are, +therefore, globally available. -------------------------------------------------------------------------- Application Description @@ -703,7 +712,7 @@ are, therefore, globally available. FLASH Will Sowerbutts’ in-situ ROM programming utility. - CLRDIR Format the directory areas of a CP/M disk. + CLRDIR Initialize the directory area of a CP/M disk (Max Scane). -------------------------------------------------------------------------- Some custom applications do not fit on the ROM disk. They are found on @@ -728,9 +737,9 @@ identical for all hardware supported by RomWBW because RomWBW hides all hardware specifics from the operating system. Note that all of the operating systems included with RomWBW support the -same basic filesystem format. As as result, a formatted filesystem will +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 of date/time stamping using the newer OSes, the older OSes +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. @@ -777,7 +786,7 @@ Digital Research CP/M 3 This is the Digital Research follow-up product to their very popular CP/M 2.2 operating system. While highly compatible with CP/M 2.2, it -features many enhancements. It makes better use of banked memory to +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. @@ -790,14 +799,14 @@ 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. -Like CP/M 3, to make ZPM3 boot disk, you put CPM3.SYS on the system +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, but is available -from Phillip. +FreeRTOS is not provided in the RomWBW distribution. You can contact +Phillip for availability. Transferring Files @@ -819,18 +828,18 @@ your RomWBW system. Then, you will use your modern computers terminal program to complete the process. The XM application generally tries to detect the hardware you are using -and adapt to it. However, you must ensure that you have a realiable +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 handle. Alternatively, you can ensure that -hardware flow control is working properly. +is not too fast for XModem to service. Alternatively, you can ensure +that hardware flow control is working properly. There is an odd interaction between XModem and partner terminal programs that can occur. Essentially, after launching XM, you must start the -protocol on your modern computer fairly quickly (usually about 20 +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 casuses this is beyond the scope of -this document. +then hangs. The interaction that causes this is beyond the scope of this +document. Disk Image Transfers @@ -852,7 +861,7 @@ computer is: This process is a little complicated, but it has the benefit of allowing you to get a lot of files over to your RomWBW system quickly and with -little change of corruption. +little chance of corruption. The process can be run in reverse to get files from your RomWBW computer to a modern computer. @@ -864,14 +873,14 @@ documents. Note that the build scripts for RomWBW create the default disk images supplied with RomWBW. It is relatively easy to customize the contents of the disk images that are part of RomWBW. This is described in more -detail in the Source\Images driectory of the distribution. +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 an +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 read/write the +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 @@ -897,23 +906,24 @@ and can be found in the Doc\Contrib directory of the distribution. Startup Command Processing -Each of the operating system supported by RomWBW provide a mechanism to +Each of the operating systems supported by RomWBW provide a mechanism to run commands at boot. This is similar to the AUTOEXEC.BAT files from MS-DOS. -With the exception of ZPM3, all operating system will look for a file +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. +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. -Note that automatic startup processing generally requires booting to a -disk drive. Since the ROM disk is not writable, there is no simple way +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. @@ -929,10 +939,11 @@ a build script, but it is quite easy to do. Essentially, the creation of a custom ROM is accomplished by updating a small configuration file, then running a script to compile the software -and generate the custom ROM image. There are build scripts for Windows, -Linux, and MacOS to accommodate virtually all users. All required build -tools (compilers, assemblers, etc.) are included in the distribution, so -it is not necessary to setup a build environment on your computer. +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. @@ -978,6 +989,11 @@ Please refer to the UNA BIOS Firmware Page for more information on UNA. RomWBW Distribution +All source code and distributions are maintained on GitHub. Code +contributions are very welcome. + +RomWBW GitHub Repository + Distribution Directory Layout The RomWBW distribution is a compressed zip archive file organized in a @@ -1002,13 +1018,6 @@ are: process or that may be useful in setting up your system. -------------------------------------------------------------------------- -Source Code Respository - -All source code and distributions are maintained on GitHub. Code -contributions are very welcome. - -RomWBW GitHub Repository - Acknowledgements While I have heavily modified much of the code, I want to acknowledge diff --git a/Source/Clean.cmd b/Source/Clean.cmd index a4420787..b097dc88 100644 --- a/Source/Clean.cmd +++ b/Source/Clean.cmd @@ -13,6 +13,5 @@ setlocal & cd Forth && call Clean.cmd & endlocal setlocal & cd Fonts && call Clean.cmd & endlocal setlocal & cd BPBIOS && call Clean.cmd & endlocal setlocal & cd HBIOS && call Clean.cmd & endlocal -setlocal & cd Doc && call Clean.cmd & endlocal setlocal & cd Images && call Clean & endlocal setlocal & cd Prop && call Clean & endlocal diff --git a/Source/Doc/Architecture.md b/Source/Doc/Architecture.md index d9c0e426..9a73a4cd 100644 --- a/Source/Doc/Architecture.md +++ b/Source/Doc/Architecture.md @@ -1,22 +1,21 @@ !include(Common.inc) -!def(name)(Architecture) +!def(document)(Architecture) --- -title: RomWBW !name +title: | + | !product + | + | !document author: !author (mailto:!authmail) date: !date institution: !orgname documentclass: book +classoption: +- oneside toc: true toc-depth: 1 numbersections: true secnumdepth: 1 -classoption: -- oneside papersize: letter -fontsize: 12pt -graphics: yes -fontfamily: helvet -# fontfamilyoptions: scaled geometry: - top=1in - bottom=1in @@ -26,7 +25,8 @@ geometry: # - pass linestretch: 1.25 colorlinks: true -#pagestyle: empty +fontfamily: helvet +fontsize: 12pt header-includes: - \setlength{\headheight}{15pt} - | @@ -35,8 +35,6 @@ header-includes: \usepackage{xcolor} \usepackage{xhfill} \renewcommand*{\familydefault}{\sfdefault} - \renewcommand{\bfdefault}{b} - \renewcommand{\contentsname}{Table of Contents} \renewcommand{\maketitle}{ \begin{titlepage} \centering @@ -45,8 +43,8 @@ header-includes: \includegraphics[width=\paperwidth]{Graphics/Logo.pdf} \par \vfill \raggedleft - {\scshape \bfseries \fontsize{48pt}{56pt} \selectfont RomWBW \par} - {\bfseries \fontsize{32pt}{36pt} \selectfont !name \par} + {\scshape \bfseries \fontsize{48pt}{56pt} \selectfont !product \par} + {\bfseries \fontsize{32pt}{36pt} \selectfont !document \par} \vspace{24pt} {\huge Version !ver \\ !date \par} \vspace{24pt} @@ -71,7 +69,7 @@ include-before: ```{=latex} \clearpage \pagenumbering{arabic} -\lhead{\fancyplain{}{\nouppercase{\footnotesize \bfseries \leftmark \hfill RomWBW !name}}} +\lhead{\fancyplain{}{\nouppercase{\footnotesize \bfseries \leftmark \hfill !product !document}}} ``` Overview @@ -419,7 +417,7 @@ bits are defined as YXXXX. | C: Serial Device Unit Number | _Exit Results_ -| A: Status +| A: Status (0=OK, else error) | E: Character Received Read a character from the device unit specified in register C and return the character @@ -433,7 +431,7 @@ value in E. If no character(s) are available, this function will wait indefinite | E: Character to Send | _Exit Results_ -| A: Status +| 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. @@ -445,7 +443,7 @@ not ready to send, function will wait indefinitely. | C: Serial Device Unit Number | _Exit Results_ -| A: Status +| 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 @@ -459,7 +457,7 @@ least one character available to read. | C: Serial Device Unit Number | _Exit Results_ -| A: Status +| 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 @@ -475,7 +473,7 @@ busy and 1 means the port is ready to output a character. | DE: Line Characteristics | _Exit Results_ -| A: Status +| 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 @@ -489,7 +487,7 @@ is returned in A with zero indicating success. | C: Serial Device Unit Number | _Exit Results_ -| A: Status +| A: Status (0=OK, else error) | DE: Line Characteristics Reports the line characteristics (baudrate, framing, etc.) of the specified unit. @@ -502,7 +500,7 @@ Register pair DE contains the line characteristics upon return. | C: Serial Device Unit Number | _Exit Results_ -| A: Status +| A: Status (0=OK, else error) | C: Serial Device Attributes | D: Serial Device Type | E: Serial Device Number @@ -556,7 +554,7 @@ MID\_FD111 | 9 | 8" 1.11M Floppy | B: 0x10 | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) ### Function 0x11 -- Disk Status (DIORESET) @@ -565,7 +563,7 @@ MID\_FD111 | 9 | 8" 1.11M Floppy | C: Disk Device Unit ID | _Exit Results_ -| A: Status (0=OK, 1=Error) +| 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 @@ -588,7 +586,7 @@ associated units of the physical interface. | DE:HL: Block Address | _Exit Results_ -| A: Status (0=OK, 1=Error) +| 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 @@ -614,7 +612,7 @@ determine if the device supports LBA addressing. | HL: Buffer Address | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) | E: Blocks Reaad Read Block Count sectors to buffer address starting at current target @@ -636,7 +634,7 @@ sectors requested, and 2) entire buffer area resides in upper 32K of memory. | HL: Buffer Address | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) | E: Blocks Written Write Block Count sectors to buffer address starting at current target @@ -659,7 +657,7 @@ sectors being written, and 2) entire buffer area resides in upper 32K of memory. | E: Block Count | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) | E: Blocks Verified \*\*\*Not Implemented\*\*\* @@ -674,7 +672,7 @@ sectors being written, and 2) entire buffer area resides in upper 32K of memory. | HL: Cylinder | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) \*\*\*Not Implemented\*\*\* @@ -685,7 +683,7 @@ sectors being written, and 2) entire buffer area resides in upper 32K of memory. | C: Disk Device Unit ID | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) | C: Attributes | D: Device Type | E: Device Number @@ -734,12 +732,12 @@ etc.) which is identified by a device type id from the table below. | E0: Enable Media Discovery | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) | E: Media ID Report the media definition for media in specified unit. If bit 0 of E is set, then perform media discovery or verification. If no media in device, -return no media error. +function will return an error status. ### Function 0x19 -- Disk Define Media (DIODEFMED) @@ -749,7 +747,7 @@ return no media error. | E: Media ID | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) \*\*\* Not implemented \*\*\* @@ -761,7 +759,7 @@ return no media error. | HL: Buffer Address | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) | DE:HL: Blocks on Device | BC: Block Size @@ -776,7 +774,7 @@ block size. If media is unknown, an error will be returned. | C: Disk Device Unit ID | _Exit Results_ -| A: Status (0=OK, 1=Error) +| A: Status (0=OK, else error) | HL: Cylinders | D7: LBA Capability | BC: Block Size @@ -1199,7 +1197,7 @@ contains a negative number, then reverse scroll should be performed. | C: Video Device Unit ID | _Exit Results_ -| A: Status (# Key Codes in Keyboard Buffer) +| A:Count of Key Codes in Keyboard Buffer Return a count of the number of key codes in the keyboard buffer. If it is not possible to determine the actual number in the buffer, it is diff --git a/Source/Doc/Common.inc b/Source/Doc/Common.inc index 0358de0e..e5f87bed 100644 --- a/Source/Doc/Common.inc +++ b/Source/Doc/Common.inc @@ -1,6 +1,6 @@ !def(ver)(2.9.2) -!def(date)(March 18, 2020) -!def(name)(RomWBW) +!def(date)(!mdate) +!def(product)(RomWBW) !def(author)(Wayne Warthen) !def(authmail)(wwarthen@gmail.com) !def(orgname)(RetroBrew Computers Group) diff --git a/Source/Doc/GettingStarted.md b/Source/Doc/GettingStarted.md index 20c3112c..6815ea60 100644 --- a/Source/Doc/GettingStarted.md +++ b/Source/Doc/GettingStarted.md @@ -1,14 +1,17 @@ !include(Common.inc) -!def(name)(Getting Started) +!def(document)(Getting Started) --- -title: RomWBW !name +title: | + | !product + | + | !document author: !author (mailto:!authmail) date: !date institution: !orgname documentclass: article -toc: true classoption: - oneside +toc: true papersize: letter geometry: - top=1in @@ -24,16 +27,18 @@ header-includes: - | ```{=latex} \renewcommand*{\familydefault}{\sfdefault} + \setstretch{1.25} % for TOC ``` --- -`\clearpage`{=latex} +`\clearpage % new page after TOC`{=latex} # RomWBW ## Z80/Z180 System Software -Version !ver of !date +| Version !ver +| !date !author() [!authmail](mailto:!authmail) @@ -51,7 +56,7 @@ Version !ver of !date 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) + * [RetroBrew Computers](https://www.retrobrewcomputers.org) * [RC2014](https://rc2014.co.uk) * [retro-comp](https://groups.google.com/forum/#!forum/retro-comp) @@ -80,7 +85,7 @@ Multiple disk images are provided in the distribution. Most disk images contain # Installation -The latest RomWBW distribution downloads are maintained on GitHub in the [RomWBW Repository](https://github.com/wwarthen/RomWBW). The fully-built distributions are found on the [releases page](https://github.com/wwarthen/RomWBW/releases) of the repository. On this page, you will probably see both pre-releases as well as normal releases. Unless you have a specific reason, I suggest you stick to the most recent normal (not pre-release) release. Expand the "Assets" drop-down for the release you want to download, then select the asset named RomWBW-vX.X.X-Package.zip. The Package asset includes all pre-built ROM and Disk images as well as full source code. The other assets called Source Code do not have the pre-built ROM or Disk Images. +The latest RomWBW distribution downloads are maintained on GitHub in the [RomWBW Repository](https://github.com/wwarthen/RomWBW). The fully-built distributions are found on the [releases page](https://github.com/wwarthen/RomWBW/releases) of the repository. On this page, you will probably see both pre-releases as well as normal releases. Unless you have a specific reason, I suggest you stick to the most recent normal release (not pre-release). Expand the "Assets" drop-down for the release you want to download, then select the asset named RomWBW-vX.X.X-Package.zip. The Package asset includes all pre-built ROM and Disk images as well as full source code. The other assets are Source Code only and do not have the pre-built ROM or disk images. The pre-built ROM images will automatically detect and support a reasonable range of devices including serial ports, video adapters, on-board disk interfaces, and PropIO/ParPortProp boards without building a custom ROM. The distribution is a .zip archive. After downloading it to a working directory on your modern computer (Windows/Linux/Mac) use any zip tool to extract the contents of the archive. @@ -89,7 +94,7 @@ In general, you will just program your system's ROM chip with the appropriate RO Looking at the extracted distribution archive, You will see that the distribution is broken up into a few sub-directories. The Binary directory contains the pre-built ROM and disk images. The ROM image files all end in ".rom". Based on the table below, **carefully** pick the appropriate ROM image: | Platform | ROM Image File | Baud | Description | -| --------------| --------------------- | --------- | ------------------------------------------------ | +| --------------| --------------------- | --------: | ------------------------------------------------ | | SBC V1/V2 | SBC_std.rom | 38400 | RetroBrew SBC v1 or v2 ECB Z80 | | Zeta V1 | ZETA_std.rom | 38400 | RetroBrew Zeta V1 Z80, ParPortProp (optional) | | Zeta V2 | ZETA2_std.rom | 38400 | RetroBrew Zeta V2 Z80, ParPortProp (optional) | @@ -104,9 +109,9 @@ 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 thrid-party Z180 native memory modules. +\*The RC2014 Z180 requires a separate RAM/ROM memory module. There are two types of these modules and you must pick the ROM for your type of memory module. The "ext" ROM supports Spencer's official 512K RAM/ROM banked memory module. The "nat" ROM supports any of the third-party Z180 native memory modules. -RomWBW will automatically attempt to detect and support typical add-on components for each of the systems supported. More information on the required system configuration and optional supported components for each ROM is found in the file called "RomList.txt" in the Binary directory. All pre-built ROM images are simple 512KB binary images. If your system utilizes a 1MB ROM, you can just program the image into the first 512KB of the ROM. +RomWBW will automatically attempt to detect and support typical add-on components for each of the systems supported. More information on the required system configuration and optional supported components for each ROM is found in the file called "RomList.txt" in the Binary directory. All pre-built ROM images are simple 512KB binary images. If your system utilizes a larger ROM chip, you can just program the image into the first 512KB of the ROM. Connect a serial terminal or computer with terminal emulation software to the primary serial port of your CPU board. You may need to refer to your hardware provider's documentation for details. A null-modem connection may be required. Set the baud rate as indicated in the table above. Set the line characteristics to 8 data bits, 1 stop bit, no parity, and no flow control. If possible, select VT-100 terminal emulation. @@ -118,9 +123,9 @@ Initially, you should try the ROM boot options. By selecting either CP/M 2.2 or Upgrading to a newer release of RomWBW is essentially just a matter of updating the ROM chip in your system. If you have spare ROM chips for your system and a ROM programmer, it is always safest to keep your existing, working ROM chip and program a new one with the new firmware. If the new one fails to boot, you can easily return to the known working ROM. -Prior to attempting to reprogram your actual ROM chip, you may wish to "try" the upgrade. With RomWBW, you can upload a new system image and load it from the command line. For each ROM image file (.rom) in the Binary directory, you will also find a corresponding application file (.com). For example, for SBC_std.rom, there is also an SBC_std.com file. You can upload the .com file to your system using XModem, then simply run the .com file. You will see your system go through the normal startup process just like it was started from ROM. However, your ROM has not been updated and the next time you boot your system, it will revert to the system image contained in ROM. You may find that you are unable to load the .com file because it is too large to fit in available application RAM (TPA). Unfortunately, in this case, you will not be able to use the .com file to start your system. +Prior to attempting to reprogram your actual ROM chip, you may wish to "try" the upgrade. With RomWBW, you can upload a new system image and load it from the command line. For each ROM image file (.rom) in the Binary directory, you will also find a corresponding application file (.com). For example, for SBC_std.rom, there is also an SBC_std.com file. You can upload the .com file to your system using XModem, then simply run the .com file. You will see your system go through the normal startup process just like it was started from ROM. However, your ROM has not been updated and the next time you boot your system, it will revert to the system image contained in ROM. You may find that you are unable to load the .com file because it is too large to fit in available application RAM (TPA). Unfortunately, in this case, you will not be able to use the .com file mechanism to start your system. -If you do not have easy access to a ROM programmer, it is entirely possible to reprogram your system ROM using the FLASH utility from Will Sowerbutts. This application called FLASH.COM can be found on the ROM drive of any running system. In this case, you would need to transfer the new ROM image (.rom) over to your system using XModem. The ROM image will be too large to fit on your RAM drive, so you will need to transfer it to a larger storage drive. Once the ROM image is on your system, you can use the FLASH application to update your ROM: +If you do not have easy access to a ROM programmer, it is usually possible to reprogram your system ROM using the FLASH utility from Will Sowerbutts. This application called FLASH.COM can be found on the ROM drive of any running system. In this case, you would need to transfer the new ROM image (.rom) over to your system using XModem (or one of the other mechanisms described in the Transferring Files section below). The ROM image will be too large to fit on your RAM drive, so you will need to transfer it to a larger storage drive. Once the ROM image is on your system, you can use the FLASH application to update your ROM. The following is a typical example of transferring ROM image using XModem and flashing the chip in-situ. ``` E>xm r rom.img @@ -149,7 +154,7 @@ Obviously, there is some risk to this approach since any issues with the program To confirm your ROM chip has been successfully updated, restart your system and boot an operating system from ROM. Do not boot from a disk device yet. Review the boot messages to see if any issues have occurred. -Once you are satisfied that the ROM is working well, you will need to update the system images and RomWBW custom applications on your disk drives. The system images and custom applications are matched to the RomWBW ROM firmware in use. If you attempt to use a disk or applications that have not been updated to match the current ROM firmware, you are likely to have odd problems. +Once you are satisfied that the ROM is working well, you will need to update the system images and RomWBW custom applications on your disk drives. The system images and custom applications are matched to the RomWBW ROM firmware in use. If you attempt to boot a disk or run applications that have not been updated to match the current ROM firmware, you are likely to have odd problems. The simplest way to update your disk media is to just use your modern computer to overwrite the entire media with the latest disk image of your choice. This process is described below in the Disk Images section. If you wish to update existing disk media in your system, you need to perform the following steps. @@ -175,7 +180,7 @@ For example: `B>COPY ASSIGN.COM C:` While the RAM/ROM disks provide a functional system, they are not useful in the long term because you cannot save data across power cycles. They are also constrained by limited space. -The systems supported by RomWBW all have the ability to use persistent disk media. I am referring to all kinds of disk devices including floppy drives, hard disks, CF Cards, and SD Cards. Some systems have disk interfaces built-in, while others will require add-in cards. You will need to refer to the documentation for your system. +The systems supported by RomWBW all have the ability to use persistent disk media. I am referring to all kinds of disk devices including floppy drives, hard disks, CF Cards, and SD Cards. Some systems have disk interfaces built-in, while others will require add-in cards. You will need to refer to the documentation for your system for your specific options. In the RomWBW bootup messages, you will see hardware discovery messages. If you have a disk drive interface, you should see messages listing device types like FD:, IDE:, PPIDE:, SD:. Additionally, you will see messages indicating the media that has been found on the interfaces. As an example, here are the messages you might see if you have an IDE interface in your system with a single CF Card inserted in the primary side of the interface: @@ -198,27 +203,25 @@ Configuring Drives... D:=IDE0:1 ``` -You will probably see mroe drive letters than this. The drive letter assignment process is described in more detail later in this document. Be aware that RomWBW will only assign drive letters to disk interfaces that actually have media in them. If you do not see drive letters assigned as expected, refer to the prior system boot messages to ensure media has been detected in the interface. Actually, there is one exception to this rule: floppy drives will be assigned a drive letter regardless of whether there is any media inserted at boot. +You will probably see more drive letters than this. The drive letter assignment process is described in more detail later in this document. Be aware that RomWBW will only assign drive letters to disk interfaces that actually have media in them. If you do not see drive letters assigned as expected, refer to the prior system boot messages to ensure media has been detected in the interface. Actually, there is one exception to this rule: floppy drives will be assigned a drive letter regardless of whether there is any media inserted at boot. Notice how each drive letter refers back to a specific disk hardware interface like IDE0. This is important as it is telling you what each drive letter refers to. Also notice that mass storage disks (like IDE) will normally have multiple drive letters assigned. The extra drive letters refer to additional "slices" on the disk. The concept of slices is also explained later in this document. -Once you are seeing drive letters referring to your disk media, you can follow the instructions below to begin using the disk media with the operating system. Your disk media **must** be initialized prior to be used. There are two ways to initialize your media for use. +Once you are seeing drive letters referring to your disk media, you can follow the instructions below to begin using the disk media with the operating system. Your disk media **must** be initialized prior to being used. There are two ways to initialize your media for use. -You can initialize the media in-place using your RomWBW system. This process is described below under Disk Initialization. In this scenario, you will need to subsequently copy any files you want to use onto the newly initialized disk. +You can initialize the media in-place using your RomWBW system. This process is described below under Disk Initialization. In this scenario, you will need to subsequently copy any files you want to use onto the newly initialized disk (see Transferring Files). Alternatively, you can use your modern Windows, Linux, or Mac computer to copy a disk image onto the disk media. RomWBW comes with a variety of disk images that are ready to use and have a much more complete set of files than you will find on the ROM disk. This process is covered below under Disk Images. ## Disk Initialization -To use a disk device, you will need to initialize the directory of the filesystem. On RomWBW, the initialization is done using the CLRDIR application. For example if your C: drive has been assigned to a storage device, you would use `CLRDIR C:` to initialize C: and prepare it hold files. Note that CLRDIR will prompt you for confirmation and you must respond with a **capital** 'Y' to confirm. Once CLDIR has completed, you can copy files onto the drive, for example `COPY *.* C:`. Be very careful to pay attention to your drive letter assignments prior to running CLRDIR to avoid accidentally wiping out a filesystem that has data on it. +To use a disk device, you will need to initialize the directory of the filesystem. On RomWBW, the initialization is done using the CLRDIR application. For example if your C: drive has been assigned to a storage device, you would use `CLRDIR C:` to initialize C: and prepare it hold files. Note that CLRDIR will prompt you for confirmation and you must respond with a **capital** 'Y' to confirm. Once `CLDIR` has completed, you can copy files onto the drive, for example `COPY *.* C:`. Be very careful to pay attention to your drive letter assignments prior to running `CLRDIR` to avoid accidentally wiping out a filesystem that has data on it. -Running CLRDIR on a disk device is roughly equivalent to running FORMAT on MS-DOS. Note that unlike MS-DOS you do **not** partition your mass storage device. CP/M knows nothing about disk partitions. You may notice a partitioning application on your ROM disk (FDISK80), but this is strictly for an advanced technique of adding an MS-DOS FAT filesystem to your media in addition to the CP/M area. Do not use FDISK80 unless you are specifically attempting to add an MS-DOS FAT filesystem to your media. +Running `CLRDIR` on a disk device is roughly equivalent to running FORMAT on MS-DOS. Note that unlike MS-DOS you do **not** partition your mass storage device. CP/M knows nothing about disk partitions. You may notice a partitioning application on your ROM disk (FDISK80), but this is strictly for an advanced technique of adding an MS-DOS FAT filesystem to your media in addition to the CP/M area. Do not use FDISK80 unless you are specifically attempting to add an MS-DOS FAT filesystem to your media. -If you are using a floppy drive, you will need to physically format your floppy disk prior to use. This is only required for floppy disks, not hard disk, CF Cards, or SD Cards, etc. To format a floppy drive, you can use the interactive application FDU. FDU is not terribly user friendly, but is generally documented in the file "FDU.txt" found in the Doc directory of the distribution. It is not necessary to run CLRDIR on a floppy disk after physically formatting it -- the directory is cleared as part of the formatting. - -## Booting Disks +If you are using a floppy drive, you will need to physically format your floppy disk prior to use. This is only required for floppy disks, not hard disk, CF Cards, or SD Cards, etc. To format a floppy drive, you can use the interactive application `FDU`. FDU is not terribly user friendly, but is generally documented in the file "FDU.txt" found in the Doc directory of the distribution. It is not necessary to run `CLRDIR` on a floppy disk after physically formatting it -- the directory is cleared as part of the formatting. -Once you have initialized a disk device and copied your desired files onto it, you may want to boot directly to this disk device at startup. On CP/M filesystems, you must perform one additional step to make a disk bootable. Specifically, you need to place a copy of the oeoprating system on the system tracks of the disk. This is done using the `SYSCOPY` command. Let's say you have prepared drive C: by initializing it with `CLRDIR` and copied some files onto it. You can now make C: bootable by running the following command: +Once you have initialized a disk device and copied your desired files onto it, you may want to make the disk bootable. On CP/M filesystems, you must perform one additional step to make a disk bootable. Specifically, you need to place a copy of the operating system on the system tracks of the disk. This is done using the `SYSCOPY` command. Let's say you have prepared drive C: by initializing it with `CLRDIR` and copied some files onto it. You can now make C: bootable by running the following command: `B>SYSCOPY C:=B:ZSYS.SYS` @@ -234,37 +237,13 @@ Transfer system image from B:ZSYS.SYS to C: (Y/N)? Y Reading image... Writing image... Done ``` -After successfully putting the operating system on the disk, you can restart your system. When you get to the boot loader, notice the line starting with "Disk:". This line lists the disk devices that you can choose to boot directly. - -You will notice that you do not have an option to boot a drive letter here (like C:). This is because the operating system is not yet loaded. When you ran `SYSCOPY` previously, remember that C: was assigned to IDE0:0 which means device IDE0, slice 0. So, to boot the disk that you just setup with SYSCOPY, you would choose option 1. You will then be prompted for the slice on IDE0 that you want to boot. For now, just press enter to choose slice 0. Once you are familiar with slices, you can `SYSCOPY` and boot alternate slices. Here is what you would see when booting to a disk device: - -``` -MARK IV Boot Loader - -ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM -Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1 - -Boot Selection? 2 Slice(0-9)[0]? - -Booting Disk Unit 2, Slice 0... - -Reading disk information... -Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive - -Loading... -``` - -Following this, you would see the normal operating system startup messages. However, your operating system prompt will be `A>` and when you look at the drive letter assignments, you should see that A: has been assigned to the disk you selected to boot. - -If you receive the error message "Disk not bootable!", you have either failed to properly run `SYSCOPY` on the target disk or you have selected the wrong disk/slice. - -Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed in the Disk boot line, they are not currently "bootable" disks because they have no system tracks on them. Attempting to boot to one of them, will fail with a "Disk not bootable!" error message and return to the loader prompt. +Once this process succeeds, you will be able to boot directly to the disk from the boot loader prompt. See the instructions in Booting Disks for details on this. ## Disk Images -As mentioned previously, RomWBW includes a variety of disk images that contain a full set of applications for the operating systems supported. It is generally easier to use these disk images instead of copying all the files over using XModem. You use your modern computer (Windows, Linux, MacOS) to place the disk image onto the disk media, then just move the media over to your system. In this scenario you **do not** run `CLRDIR` or `SYSCOPY` on the drive(s). The directory prepared and the disk is already bootable, if it is an operating system. +As mentioned previously, RomWBW includes a variety of disk images that contain a full set of applications for the operating systems supported. It is generally easier to use these disk images instead of copying all the files over using XModem. You use your modern computer (Windows, Linux, MacOS) to place the disk image onto the disk media, then just move the media over to your system. In this scenario you **do not** run `CLRDIR` or `SYSCOPY` on the drive(s). The directory is prepared and the disk is already bootable, if it is an operating system boot disk image. -To copy the disk image files onto your actual media (floppy disk, CF Card, SD Card, etc.), you need to use an image writing utility on your modern computer. Your modern computer will need to have an appropriate interface or slot that accepts the media. To actually copy the image, you can use the `dd` command on Linux or MacOS. On Windows, in the "Tools" directory of the distribution there are two tools you can use. For floppy media, you can use RawWriteWin and for hard disk media, you can use Win32DiskImager. In all cases, the image file should be written to the media starting at the very first block or sector of the media. This will destroy any other data on the media. +To copy the disk image files onto your actual media (floppy disk, CF Card, SD Card, etc.), you need to use an image writing utility on your modern computer. Your modern computer will need to have an appropriate interface or slot that accepts the media. To actually copy the image, you can use the `dd` command on Linux or MacOS. On Windows, in the "Tools" directory of the distribution there are two tools you can use. For floppy media, you can use RawWriteWin and for hard disk media, you can use Win32DiskImager. In all cases, the image file should be written to the media starting at the very first block or sector of the media. This will **destroy** any other data on the media. The disk image files are found in the Binary directory of the distribution. Floppy disk images are prefixed with "fd_" and hard disk images are prefixed with "hd_". The floppy images are specifically for 1.44M floppy media only. Each disk image has the complete set of normal applications and tools distributed with the associated operating system or application suite. @@ -272,11 +251,11 @@ The following table shows the disk image files available. Note that the images | Floppy | Hard | Description | | --------------- | --------------- | -------------------------------------- | -| fd_cpm22.img | hd_cpm22.img | DRI CP/M 2.2 bootable disk | -| fd_zsdos.img | hd_zsdos.img | ZSDOS 1.1 bootable disk | -| fd_nzcom.img | hd_nzcom.img | NZCOM bootable disk | -| fd_cpm3 | hd_cpm3.img | DRI CP/M 3 bootable disk | -| fd_zpm3 | hd_zpm3.img | ZPM3 bootable disk | +| fd_cpm22.img | hd_cpm22.img | DRI CP/M 2.2 boot disk | +| fd_zsdos.img | hd_zsdos.img | ZSDOS 1.1 boot disk | +| fd_nzcom.img | hd_nzcom.img | NZCOM boot disk | +| fd_cpm3 | hd_cpm3.img | DRI CP/M 3 boot disk | +| fd_zpm3 | hd_zpm3.img | ZPM3 boot disk | | fd_ws4 | hd_ws4.img | WordStar v4 application disk | In addition to the disk images above, there is also a special hard disk image called hd_combo.img. This image contains all of the images above, but in a single image with 6 slices (see below for information on disk slices). At the boot loader prompt, you can choose a disk with the combo image, then select the specific slice you want. This allows a single disk to have all of the possible operating system options. @@ -296,13 +275,41 @@ Note that unlike the ROM firmware, you do **not** need to choose a disk image sp All of the disk images that indicate they are bootable (boot disk) will boot from disk as is. You do not need to run `SYSCOPY` on them to make them bootable. However, if you upgrade your ROM, you should use `SYSCOPY` to update the system tracks. +## Booting Disks + +When starting your system, following the hardware initialization, you will see the Boot Loader prompt. In addition, to the ROM boot options, you will see another line listing the Disk boot options. This line lists the disk devices that you can choose to boot directly. + +You will notice that you do not have an option to boot a drive letter here (like C:). This is because the operating system is not yet loaded. When you ran `SYSCOPY` previously, remember that C: was assigned to IDE0:0 which means device IDE0, slice 0. So, to boot the disk that you just setup with `SYSCOPY`, you would choose option 1. You will then be prompted for the slice on IDE0 that you want to boot. For now, just press enter to choose slice 0. Once you are familiar with slices, you can `SYSCOPY` and boot alternate slices. Here is what you would see when booting to a disk device: + +``` +MARK IV Boot Loader + +ROM: (M)onitor (C)P/M (Z)-System (F)orth (B)ASIC (T)-BASIC (P)LAY (U)SER ROM +Disk: (0)MD1 (1)MD0 (2)IDE0 (3)IDE1 + +Boot Selection? 2 Slice(0-9)[0]? + +Booting Disk Unit 2, Slice 0... + +Reading disk information... +Loc=D000 End=FE00 Ent=E600 Label=Unlabeled Drive + +Loading... +``` + +Following this, you would see the normal operating system startup messages. However, your operating system prompt will be `A>` and when you look at the drive letter assignments, you should see that A: has been assigned to the disk you selected to boot. + +If you receive the error message "Disk not bootable!", you have either failed to properly run `SYSCOPY` on the target disk or you have selected the wrong disk/slice. + +Note that although MD1 (RAM disk) and MD0 (ROM disk) drives are listed in the Disk boot line, they are not "bootable" disks because they have no system tracks on them. Attempting to boot to one of them, will fail with a "Disk not bootable!" error message and return to the loader prompt. + # General Usage -Each of the operating systems and ROM applications included with RomWBW are sophisticated tools in their own right. It is not reasonable to document their usage here. However, you will find complete manuals in PDF format in the Doc directory of the distribution. The intention of this section is to document the RomWBW specific enhancements to these OSes. +Each of the operating systems and ROM applications included with RomWBW are sophisticated tools in their own right. It is not reasonable to document their usage here. However, you will find complete manuals in PDF format in the Doc directory of the distribution. The intention of this section is to document the RomWBW specific enhancements to these operating systems. ## ROM Disk -In addition to the ROM-based operating systems and applications, the ROM also contains a ROM disk with a small CP/M filesystem. The contents have been optimized to provide a core set of tools and applications that are helpful for either CP/M 2.2 and ZSDOS. Since ZSDOS is CP/M 2.2 compatible, this works fairly well. However, you will find some files on the ROM disk that will work with ZSDOS, but will not work on CP/M 2.2. For example, `LDDS`, which loads the ZSDOS date/time stamper will only run on ZSDOS. +In addition to the ROM-based operating systems and applications, the ROM also contains a ROM disk with a small CP/M filesystem. The contents of the ROM disk have been chosen to provide a core set of tools and applications that are helpful for either CP/M 2.2 or ZSDOS. Since ZSDOS is CP/M 2.2 compatible, this works fairly well. However, you will find some files on the ROM disk that will work with ZSDOS, but will not work on CP/M 2.2. For example, `LDDS`, which loads the ZSDOS date/time stamper will only run on ZSDOS. ## Drive Letter Assignment @@ -318,25 +325,25 @@ When performing a ROM boot of an operating system, note that A: will be your RAM The vintage operating systems included with RomWBW were produced at a time when mass storage devices were quite small. CP/M 2.2 could only handle filesystems up to 8MB. In order to achieve compatibility across all of the operating systems supported by RomWBW, the hard disk filesystem format used is 8MB. This ensures any filesystem will be accessible to any of the operating systems. -Since storage devices today are quite large, RomWBW implements a mechanism called slicing to allow up to 256 8MB filesystems on a single large storage device. This allows up to 2GB of useable space on a single media. You can think of slices as a way to refer to the first 256 8MB chunks of space on a single media. +Since storage devices today are quite large, RomWBW implements a mechanism called slicing to allow up to 256 8MB filesystems on a single large storage device. This allows up to 2GB of useable space on a single media. You can think of slices as a way to refer to any of the first 256 8MB chunks of space on a single media. Of course, the problem is that CP/M-like operating systems have only 16 drive letters (A:-P:) available. Under the covers, RomWBW allows you to use any drive letter to refer to any slice of any media. The `ASSIGN` command is provided to allow you to view or change the drive letter mappings at any time. At startup, the operating system will automatically allocate a reasonable number of drive letters to the available storage devices. The allocation will depend on the number of large storage devices available at boot. For example, if you have only one hard disk type media, you will see that 8 drive letters are assigned to the first 8 slices of that media. If you have two large storage devices, you will see that each device is allocated four drive letters. -Referring to slices within a storage device is done by appending a :n where n is the device relative slice number from 0-255. For example, if you have an IDE device, it will show up as IDE0: in the boot message meaning the first IDE device. To refer to the second slice of IDE0, you would type "IDE0:1". So, if I wanted to use drive letter L: to refer to the second slice of IDE0, I could use the command `ASSIGN L:=IDE0:1`. +Referring to slices within a storage device is done by appending a :n where n is the device relative slice number from 0-255. For example, if you have an IDE device, it will show up as IDE0: in the boot messages meaning the first IDE device. To refer to the fourth slice of IDE0, you would type "IDE0:3". So, if I wanted to use drive letter L: to refer to the fourth slice of IDE0, I could use the command `ASSIGN L:=IDE0:3`. There are a couple of rules to be aware of when assigning drive letters. First, you may only refer to a specific device/slice with one drive letter. Said another way, you cannot have multiple drive letters referring to a single device/slice at the same time. Second, there must always be a drive assigned to A:. Any attempt to violate these rules will be blocked by the `ASSIGN` command. Unlike MS-DOS partitions, slices are not allocated -- there is no partitioning of slices. Think of every hard disk type device as having a pre-allocated set of 256 8MB slices at the start of the media. You can refer to any of them simply by assigning a drive letter. RomWBW will not check to see if there is anything else on the hard disk in the slice you are referring to, nor will it verify that the hard disk media is large enough to have a slice at the location you refer to. If you attempt to write past the end of your media, you will get an I/O error displayed, so you will know if you make a mistake. There is no tracking of your use of slices -- you will need to keep track of your use of slices yourself. -Nothing automatically initializes a slice as a file system. You must do that yourself using `CLRDIR`. Since CLRDIR works on drive letters, make absolutely sure you know what media and slice are assigned to that drive letter before using `CLRDIR`. +Nothing automatically initializes a slice as a file system. You must do that yourself using `CLRDIR`. Since `CLRDIR` works on drive letters, make absolutely sure you know what media and slice are assigned to that drive letter before using `CLRDIR`. -While it probably obvious, you cannot use slices on any media less than 8MB in size. Specifically, you cannot slice RAM disk, ROM disk, floppy disks, etc. +While it is probably obvious, you cannot use slices on any media less than 8MB in size. Specifically, you cannot slice RAM disks, ROM disks, floppy disks, etc. # Inbuilt ROM Applications -In addition to CP/M 2.2 and Z-System, there are several additional ROM applications that can be launched directly from ROM. These applications are not hosted by an operating system and so they are unable to save files to disk devices. +In addition to CP/M 2.2 and Z-System, there are several ROM applications that can be launched directly from ROM. These applications are not hosted by an operating system and so they are unable to save files to disk devices. -The following options are available at the boot loader prompt: +The following ROM applications are available at the boot loader prompt: | Application | | | ----------- | -------------------------------------------------------------- | @@ -354,7 +361,7 @@ Space is available in the ROM image for the inclusion of other software. Any inb The operation of the RomWBW hosted operating systems is enhanced through several custom applications. These applications are functional on all of the OS variants included with RomWBW. -The following custom applications are found on the RomWBW ROM disk and are, therefore, globally available. +The following custom applications are found on the ROM disk and are, therefore, globally available. | Application | Description | | ----------- | -------------------------------------------------------------- | @@ -368,7 +375,7 @@ The following custom applications are found on the RomWBW ROM disk and are, ther | FDISK80 | John Coffman's Z80 hard disk partitioning tool. See documentation in Doc directory. | | FAT | Access MS-DOS FAT filesystems from RomWBW (based on FatFs). | | FLASH | Will Sowerbutts' in-situ ROM programming utility. | -| CLRDIR | Format the directory areas of a CP/M disk. | +| CLRDIR | Initialize the directory area of a CP/M disk (Max Scane). | Some custom applications do not fit on the ROM disk. They are found on the disk image files or the individual files can be found in the Binary\\Apps directory of the distribution. @@ -383,7 +390,7 @@ There is additional documentation on some of these applications at the [RomWBW A One of the primary goals of RomWBW is to expose a set of generic hardware functions that make it easy to adapt operating systems to any hardware supported by RomWBW. As a result, there are now 5 operating systems that have been adapted to run under RomWBW. The adaptations are identical for all hardware supported by RomWBW because RomWBW hides all hardware specifics from the operating system. -Note that all of the operating systems included with RomWBW support the same basic filesystem format. As as result, a formatted filesystem will be accessible to any operating system. The only possible issue is that if you turn of date/time stamping using the newer OSes, the older OSes will not understand this. Files will not be corrupted, but the date/time stamps may be lost. +Note that all of the operating systems included with RomWBW support the same basic filesystem format. As a result, a formatted filesystem will be accessible to any operating system. The only possible issue is that if you turn on date/time stamping using the newer OSes, the older OSes will not understand this. Files will not be corrupted, but the date/time stamps may be lost. The following sections briefly describe the operating system options currently available. @@ -403,7 +410,7 @@ To use, NZCOM, you must run through a simple configuration process. This is wel ## Digital Research CP/M 3 -This is the Digital Research follow-up product to their very popular CP/M 2.2 operating system. While highly compatible with CP/M 2.2, it features many enhancements. It makes better use of banked memory to increase the user program space (TPA). It also has a new suite of support tools and help system. +This is the Digital Research follow-up product to their very popular CP/M 2.2 operating system. While highly compatible with CP/M 2.2, it features many enhancements. It makes direct use of banked memory to increase the user program space (TPA). It also has a new suite of support tools and help system. Note that to make a CP/M 3 boot disk, you actually place CPMLDR.SYS on the system tracks of the disk. You do not place CPM3.SYS on the system tracks. @@ -411,11 +418,11 @@ Note that to make a CP/M 3 boot disk, you actually place CPMLDR.SYS on the syste ZPM3 is an interesting combination of the features of both CP/M 3 and ZCPR 3. Essentially, it has the features of and compatibility with both. -Like CP/M 3, to make ZPM3 boot disk, you put CPM3.SYS on the system tracks of the disk. +Like CP/M 3, to make ZPM3 boot disk, you put CPMLDR.SYS on the system tracks of the disk. ## FreeRTOS -Note that Phillip Stevens has also ported FreeRTOS to run under RomWBW. FreeRTOS is not provided in the RomWBW distribution, but is available from Phillip. +Note that Phillip Stevens has also ported FreeRTOS to run under RomWBW. FreeRTOS is not provided in the RomWBW distribution. You can contact Phillip for availability. # Transferring Files @@ -427,9 +434,9 @@ RomWBW provides an serial file transfer program called XModem that has been adap You can type `XM` by itself to get usage information. In general, you will run `XM` with parameters to indicate you want to send or receive a file on your RomWBW system. Then, you will use your modern computers terminal program to complete the process. -The `XM` application generally tries to detect the hardware you are using and adapt to it. However, you must ensure that you have a realiable serial connection. You must also ensure that the speed of the connection is not too fast for XModem to handle. Alternatively, you can ensure that hardware flow control is working properly. +The `XM` application generally tries to detect the hardware you are using and adapt to it. However, you must ensure that you have a reliable serial connection. You must also ensure that the speed of the connection is not too fast for XModem to service. Alternatively, you can ensure that hardware flow control is working properly. -There is an odd interaction between XModem and partner terminal programs that can occur. Essentially, after launching `XM`, you must start the protocol on your modern computer fairly quickly (usually about 20 seconds or so). So, if you do not pick a file on your modern computer quickly enough, you will find that the transfer completes about 16K, then hangs. The interaction that casuses this is beyond the scope of this document. +There is an odd interaction between XModem and partner terminal programs that can occur. Essentially, after launching `XM`, you must start the protocol on your modern computer fairly quickly (usually in about 20 seconds or so). So, if you do not pick a file on your modern computer quickly enough, you will find that the transfer completes about 16K, then hangs. The interaction that causes this is beyond the scope of this document. ## Disk Image Transfers @@ -442,17 +449,17 @@ The general process to get files from your modern computer to a RomWBW computer 3. Use a disk imaging tool to copy the RomWBW filesystem image onto the media. 4. Move the media back to the RomWBW computer. -This process is a little complicated, but it has the benefit of allowing you to get a lot of files over to your RomWBW system quickly and with little change of corruption. +This process is a little complicated, but it has the benefit of allowing you to get a lot of files over to your RomWBW system quickly and with little chance of corruption. The process can be run in reverse to get files from your RomWBW computer to a modern computer. The exact use of these tools is a bit too much for this document, but the tools are all included in the RomWBW distribution along with usage documents. -Note that the build scripts for RomWBW create the default disk images supplied with RomWBW. It is relatively easy to customize the contents of the disk images that are part of RomWBW. This is described in more detail in the Source\\Images driectory of the distribution. +Note that the build scripts for RomWBW create the default disk images supplied with RomWBW. It is relatively easy to customize the contents of the disk images that are part of RomWBW. This is described in more detail in the Source\\Images directory of the distribution. ## FAT Filesystem Transfers -RomWBW provides a mechanism that allows it to read and write files on an FAT formatted disk. This means that you can generally use your modern computer to make an SD Card or CF Card with a standard FAT32 filesystem on it, then place that media in your RomWBW computer and read/write the files. +RomWBW provides a mechanism that allows it to read and write files on a FAT formatted disk. This means that you can generally use your modern computer to make an SD Card or CF Card with a standard FAT32 filesystem on it, then place that media in your RomWBW computer and access the files. When formatting the media on your modern computer, but sure to pick the FAT filesystem. NTFS and other filesystems will not work. @@ -464,19 +471,19 @@ For advanced users, it is possible to create a hybrid disk that contains CP/M sl # Startup Command Processing -Each of the operating system supported by RomWBW provide a mechanism to run commands at boot. This is similar to the AUTOEXEC.BAT files from MS-DOS. +Each of the operating systems supported by RomWBW provide a mechanism to run commands at boot. This is similar to the AUTOEXEC.BAT files from MS-DOS. -With the exception of ZPM3, all operating system will look for a file called `PROFILE.SUB` on the system drive at boot. If it is found, it will be processed as a standard CP/M submit file. You can read about the use of the SUBMIT facility in the CP/M manuals included in the RomWBW distribution. +With the exception of ZPM3, all operating systems will look for a file called `PROFILE.SUB` on the system drive at boot. If it is found, it will be processed as a standard CP/M submit file. You can read about the use of the SUBMIT facility in the CP/M manuals included in the RomWBW distribution. Note that the boot disk must also have a copy of `SUBMIT.EXE`. In the case of ZPM3, the file called `STARTZPM.COM` will be run at boot. To customize this file, you use the ZCPR ALIAS facility. You will need to refer to ZCPR documentation for more information on the ALIAS facility. -Note that automatic startup processing generally requires booting to a disk drive. Since the ROM disk is not writable, there is no simple way to add/edit a `PROFILE.SUB` file there. If you want to customize your ROM and add a `PROFILE.SUB` file to the ROM Disk, it will work, but is a lot harder than using a boot disk. +Note that the automatic startup processing generally requires booting to a disk drive. Since the ROM disk is not writable, there is no simple way to add/edit a `PROFILE.SUB` file there. If you want to customize your ROM and add a `PROFILE.SUB` file to the ROM Disk, it will work, but is a lot harder than using a boot disk. # ROM Customization The pre-built ROM images are configured for the basic capabilities of each platform. Additionally, some of the typical add-on hardware for each platform will be automatically detected and used. If you want to go beyond this, RomWBW provides a very flexible configuration mechanism based on configuration files. Creating a customized ROM requires running a build script, but it is quite easy to do. -Essentially, the creation of a custom ROM is accomplished by updating a small configuration file, then running a script to compile the software and generate the custom ROM image. There are build scripts for Windows, Linux, and MacOS to accommodate virtually all users. All required build tools (compilers, assemblers, etc.) are included in the distribution, so it is not necessary to setup a build environment on your computer. +Essentially, the creation of a custom ROM is accomplished by updating a small configuration file, then running a script to compile the software and generate the custom ROM and disk images. There are build scripts for Windows, Linux, and MacOS to accommodate virtually all users. All required build tools (compilers, assemblers, etc.) are included in the distribution, so it is not necessary to setup a build environment on your computer. The process for building a custom ROM is documented in the ReadMe.txt file in the Source directory of the distribution. @@ -503,6 +510,10 @@ Please refer to the [UNA BIOS Firmware Page](https://www.retrobrewcomputers.org/ # RomWBW Distribution +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: @@ -514,12 +525,6 @@ The RomWBW distribution is a compressed zip archive file organized in a set of d | Source | Contains the source code files used to build the software and ROM images. | | Tools | Contains the MS Windows programs that are used by the build process or that may be useful in setting up your system. | -## Source Code Respository - -All source code and distributions are maintained on GitHub. Code contributions are very welcome. - -[RomWBW GitHub Repository](https://github.com/wwarthen/RomWBW|https://github.com/wwarthen/RomWBW) - # Acknowledgements 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!). diff --git a/Source/Doc/ZCPR Manual/Main.ltx b/Source/Doc/ZCPR Manual/Main.ltx deleted file mode 100644 index 2cc18498..00000000 --- a/Source/Doc/ZCPR Manual/Main.ltx +++ /dev/null @@ -1,25 +0,0 @@ -\documentclass[letterpaper,10pt,oneside]{book} -\usepackage[T1]{fontenc} -%\usepackage[defaultmono]{droidmono} -\usepackage[scaled]{beramono} -\usepackage{fancyvrb} -\usepackage{geometry} -\usepackage{pdflscape} -%\usepackage{showframe} % Diagnostic - -% Suppress headers and footers completely -\pagestyle{empty} - -% 66 lines per page, portrait -\geometry{top=0.0in, bottom=0.0in, left=1.5in, right=1.5in} - -\RecustomVerbatimCommand{\VerbatimInput}{VerbatimInput} -{ - commandchars=\\\{\} -} - -\begin{document} - -\VerbatimInput{zcpr.ltx} - -\end{document} \ No newline at end of file diff --git a/Source/Doc/ZCPR Manual/zcpr.ltx b/Source/Doc/ZCPR Manual/zcpr.ltx deleted file mode 100644 index 732f43a7..00000000 --- a/Source/Doc/ZCPR Manual/zcpr.ltx +++ /dev/null @@ -1,1384 +0,0 @@ - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - - - \textbf{Documentation on ZCPR - A Z80 Replacement for the CP/M CCP} - - - - - ZCPR is a Group Project By the CCP-GROUP: - RLC - Richard Conn FJW - Frank Wancho - KBP - Keith Peterson RGF - Ron Fowler - - - ZCPR Documentation By RLC - - - - - - - - Table of Contents - ----- -- -------- - - Introduction 2 - - Part A: Installation Instructions 4 - ZCPR Integration Example 5 - Setting the ZCPR Inline Options 8 - REL, BASE, CPRLOC, RAS, SUBA, CLEVEL3 8 - Customization Symbols 8 - NLINES, WIDE, PGDFLT 8 - PGDFLG, MAXUSR, SYSFLG, SOFLG, SUPRES, - DEFUSR, SPRMPT, CPRMPT, NUMBASE, 9 - SECTFLG, FENCE 10 - Patching SUBMIT.COM 10 - - Part B: Usage Instructions and Explanation of - Commands 11 - The ZCPR Command Hierarchy Search 11 - The ZCPR-Resident Commands 14 - DIR, ERA 14 - LIST, TYPE, SAVE 15 - REN, USER, DFU 16 - JUMP, GO, GET 17 - ZCPR Error Messages 18 - - Part C: ZCPR Command Levels and How to Use Them 19 - - - - - - - - - Page 1 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - \textbf{Documentation on ZCPR - A Z80 Replacement for the CP/M CCP} - - - - - ZCPR is a replacement for the CP/M Console Command Processor - (CCP) which is designed to run as part of CP/M on Z80-based - microcomputers. In most cases it is upward-compatible with the - original CP/M Version 2.2 CCP. - - ZCPR, however, provides many extensions to the CP/M CCP. - Included in these extensions are the following features: - - . The TYPE function can be made to page or not page its - output at the user's discretion - - . A LIST function is available which sends its output - to the CP/M LST: Device and does NOT page - - . The DIR command has been extended to allow the dis- - play of the system files or all files - - . The ERA command now prints out the names of the files - it is erasing - - . The current user number may be included as part of - the command prompt; if the user is under a number other than 0, - the prompt is of the form 'du>' (like 'A2>' or 'B10>'), and, if - the user is under 0, the prompt may be 'd>' or 'd0>' as per his - choice - - . The SUBMIT facility has been changed in two basic - ways: - - the prompt changes to 'du$' or 'd$' when the - SUBMIT command is printed - - the $$$.SUB is executed from drive A: (note that - the original SUBMIT problem now exists, but the new SUB.COM - facility corrects it); the CCP-GROUP definition of an Indirect - Command File now applies, and this definition is that any - sequence of commands which may be issued from the console is also - a valid sequence of commands for execution from an Indirect - Command File; hence, the sequence: - - DIR - B: - DIR - A: - - may be issued from either the console or an Indirect Command - File, and the results of the execution of this sequence are the - same. Basically, this says that Indirect Command Files are - upward-compatible to the console input (but not necessarily that - the contents of an Indirect Command File may be issued at the - console without modification). - - - Page 2 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - . A command-search hierarchy is now implemented which - is executed roughly as follows: - - the user's command is checked against the CPR- - resident commands and executed immediately if a match is found - - failing that, the current user number on the - current disk is scanned for the COM file; the COM file is loaded - and executed if found - - failing that, a default user number (initially 0 - but can be reset with the DFU CPR-resident command) on the cur- - rent disk is scanned for the COM file; the COM file is loaded and - executed if found - - finally, failing that, the default user number - on disk A: is scanned for the COM file; the COM file is loaded - and executed if found or an error message (COMMAND?, when COMMAND - was the user's command name) is printed - - . The numeric argument for the SAVE command can be - specified in hexadecimal so that the user may employ the values - presented by tools such as DDT exactly as they are given - - . A GET command which loads a file at a specified - memory address and a JUMP command which "calls" the subroutine at - a specified memory address have been added; a GO command which - "calls" the subroutine at 100H (subset of the JUMP capability) - has also been added - - - This document provides the user of ZCPR with the following - information: - - Part A: Installation Instructions - Part B: Usage Instructions and Explanation of Commands - Part C: ZCPR Command Levels and How to Use Them - - - - - - - - - - - - - - - - - - - - - - - - Page 3 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Part A - Installation Instructions - - In order to install ZCPR on a target microcomputer (must be - currently running CP/M 2.2), the user must know two basic things: - - 1) Where his CCP is currently running in memory - 2) Where his CCP is located in the SYSGEN image, or, - for systems which don't support SYSGEN (such as P&T CP/M 2.2 for - the TRS-80 Model II), where his CCP is located on disk and how to - place the new ZCPR on top of it - - The first question is answered relatively easily. A pro- - gram, known as either BDOSLOC or BDLOC (for BDOS Locator), is - provided with ZCPR. You should assemble this program for your - particular computer (change the base ORG if you are running non- - ORG-0 CP/M) and execute it. Upon execution, it will provide you - with the base address of (1) the BDOS and (2) the CCP for your - particular system. BDOSLOC has worked correctly for all systems - tested so far, but there is always a chance that it may NOT work - for some non-tested system. For the time being, assume that it - works correctly and record the starting base page address of your - CCP. - - The second question is not answered nearly so easily. If - you have the ability to SYSGEN your system, it is much easier - (commonly) than if you do not. You must, after assembling the - ZCPR properly, integrate it into the sysgen (or disk) image of - CP/M. This can be done by obtaining a SYSGEN image of your - system, scanning it via a debugger such as DDT to find the offset - for the CCP, reading the new CPR in on top of the old one, and - finally running SYSGEN again to place the resultant system on - disk. If you DO NOT have SYSGEN capability, a Disk Utility - program is required to locate the CCP on disk and then write the - new ZCPR on top of the old one. The net result of this - integration is the placement of the new ZCPR onto disk in the - proper place so that it will be loaded with the rest of CP/M on - cold boot and executed properly. - - To find the original CCP, you typically have to locate it by - its appearance. It is probably stored contiguously on disk, so, - once it is found, a sequential overwrite is all that is required. - Probability is extremely high that it is stored contiguously in - the SYSGEN image. The CCP starts with two (2) and ONLY TWO jump - instructions followed by a buffer area (possibly containing an - initial command and/or the Digital Research copyright notice). - The Digital Research manuals show the CCP to reside at address - 980H in the SYSGEN image, but this may vary with system. To - find this image, use DDT or some other such debugger, load the - SYSGEN image you can get via SYSGEN, and examine memory starting - at around 900H for the two (and ONLY two) jumps described above. - If you find an area with more than two jumps (a group of them), - you are probably looking at the BIOS and should go lower for the - CCP. The CCP will probably start on an even page or half-page - address (like 900H, 980H, 1100H, etc). - - Page 4 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Now that the location of the CCP has been found, record this - address for later. You are now ready for the integration of ZCPR - into your system. To do this, perform the following steps using - the information of the page address of the CCP (obtained from - BDOSLOC and called CPRLOC within ZCPR) and the SYSGEN image - address of the CCP (called IMAGE for reference in this document). - - 1. Edit ZCPR and set the CPRLOC equate to the value - obtained from above. Also set any flags and values as you desire - (see the section on ZCPR Customization below). When satisfied, - end the edit session. - - 2. Assemble ZCPR with MAC (or equivalent). This - assembler is required because of the MACROs used. Only the - resultant HEX file is required. - - 3. Assuming that you can use SYSGEN, obtain a SYSGEN - image of your current CP/M system and save it on disk. - - 4. Load the SYSGEN image into memory with DDT (or - equivalent). Once loaded, verify that the original CCP is at the - IMAGE address found above and compute the integration offset - using the DDT H command: - H, - The second number displayed gives you the OFFSET value required - for step 5. - - 5. Integrate ZCPR into your SYSGEN image via DDT's I - and ROFFSET commands. Use IZCPR.HEX (or the name of your version - of ZCPR) to load the FCB and ROFFSET (where OFFSET was computed - in step 4) to load the ZCPR.HEX file into memory at the proper - location. Check to see that ZCPR is indeed properly loaded by - examining the SYSGEN IMAGE area. - - 6. Place the new system on disk by running SYSGEN and - NOT loading the system from disk (use the memory image). - - For further clarification of the above process, the - following is a sample terminal session which outlines the steps - taken. - - ZCPR Integration Example - - - B>; Sample terminal session for integrating ZCPR - B>sysgen - SYSGEN VER 2.2 - SOURCE DRIVE NAME (OR RETURN TO SKIP)b - SOURCE ON B, THEN TYPE RETURN <-- I hit the RETURN key here - FUNCTION COMPLETE / - DESTINATION DRIVE NAME (OR RETURN TO REBOOT) <-- and here - B>save 44 cpm56.com <-- We now have a SYSGEN image of CP/M - to work with - - - - Page 5 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - B>xdir - XDIR Version 2.6 User Number: 0, Double Density - File Attributes: Non-System - - Filename.Typ Size K Filename.Typ Size K Filename.Typ Size K - -------- --- ------ -------- --- ------ -------- --- ------ - !TEXTWRK.-12 0 CPR .DOC 8 EE687 .TXT 4 - CPR .AQM 34 TFS .HLP 6 EE687PRE.TXT 4 - CPR .ASM 50 CONTENTS.T01 6 SW1 .TXT 10 - CPR .BAK 4 CONTENTS.T02 4 SW2 .TXT 2 - CPM56 .COM 12 CONTENTS.T03 4 - B: 30 Entries & 22 Files -- 338K Bytes Remaining - File Data: 14 Files -- 154K Bytes Displayed - B>bdosloc <-- Now to locate the CCP's address - The Base Page Address of this system's BDOS is C5 - The Base Page Address of this system's CCP is BD <-- This is it - B>ddt cpm56.com <-- Now to find the CCP in the SYSGEN image - DDT VERS 2.0 - NEXT PC - 2D00 0100 - -d900,90f <-- Start looking around here - 0900 31 80 E7 3E 06 3C 3C FE 1B CA 00 C2 DA 11 E7 D6 1..>.<<......... - -da00,a0f - 0A00 31 00 01 01 01 0C C5 CD 0F E4 21 00 BE 11 00 04 1.........!..... - -db00,b0f - 0B00 31 00 01 01 01 11 C5 CD 0F E4 21 00 C0 11 00 02 1.........!..... - -db80,b8f - 0B80 31 00 01 01 09 01 CD A8 00 21 00 D2 11 00 C2 0E 1........!...... - -- Detail Left Out -- - -d1100 <-- I found it at 1100H; note the 2 JMP's - 1100 C3 FF BD C3 FB BD 50 10 20 20 20 20 20 20 20 20 ......P. - 1110 20 20 20 20 20 20 20 20 00 00 00 00 00 00 00 00 ........ - 1120 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ - -- Detail Left Out -- - -^C <-- Return to CP/M; I know that CPRLOC will be - BD00H and the IMAGE offset is 1100H - - B>ed cpr.asm \{edit ZCPR here and place CPRLOC=BD00H\}# - -- Detail Left Out -- - - B>mac cpr $pz sz <-- Now to assemble the CPR - CP/M MACRO ASSEM 2.0 - C4F0 <-- Note that CPR MUST end before BDOS - begins! - 014H USE FACTOR - END OF ASSEMBLY - - - - - - - - - - - - Page 6 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - B>ddt cpm56.com <-- Now to integrate! - DDT VERS 2.0 - NEXT PC - 2D00 0100 - -h1100,bd00 <-- Compute offset for new CPR - CE00 5400 <-- Offset is 5400H - -icpr.hex <-- Init FCB - -r5400 <-- Read in new CPR with offset - NEXT PC - 2D00 0000 - -^C <-- Done! - B>sysgen <-- Now to SYSGEN onto disk - SYSGEN VER 2.2 - SOURCE DRIVE NAME (OR RETURN TO SKIP) <-- Use memory image - DESTINATION DRIVE NAME (OR RETURN TO REBOOT)b <-- onto B: - DESTINATION ON B, THEN TYPE RETURN - FUNCTION COMPLETE - DESTINATION DRIVE NAME (OR RETURN TO REBOOT) <-- Done for now - - B> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Page 7 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Setting the ZCPR Inline Options - - The following are the four basic options available to the - user under ZCPR for customization of his package. - - Option Name Function - - REL Configures CPRLOC (CPRLOC equ 0) for integration - via MOVCPM rather than the DDT/SYSGEN technique - outlined above; set to TRUE for MOVCPM integra- - tion or FALSE for DDT/SYSGEN integration - - BASE Base address of your CP/M system; standard CP/M - has a base of 0, but some CP/M systems (such as - for the TRS-80 Model I and Heath/Zenith H89/Z89) - start physical RAM memory at a higher address; - equate BASE to the starting RAM memory address of - your system - - CPRLOC This is the starting address of ZCPR; set the - second CPRLOC equate to the address you obtain - from BDOSLOC - - RAS This is an equate which masks out selected ZCPR - command functions for security purposes on - Remote Access Systems such as Bulletin Boards; - the masked out functions currently include - SAVE, ERA, REN, JUMP, GO, and GET; set RAS to TRUE - to mask these out or FALSE to leave them in - - SUBA This is an equate which determines the drive - onto which ZCPR will look for an executing - Indirect Command File. If the basic philosophy - of the Indirect Command File described above is - to be maintained, this symbol should be set to - TRUE (look on drive A: for the $$$.SUB file); if - not, this symbol should be set to FALSE (look on - the default drive from the $$$.SUB file). To - review, the basic philosophy of the Indirect - Command File is that any sequence of commands - which may be issued from the console (within - reason, which means NOT to erase a $$$.SUB file) - may also be issued from within an Indirect - Command File, and the resultant execution should - be identical (same functions performed). - - CLEVEL3 This equate enables or disables extended Command - Level 3 Processing. If set to TRUE, extended - Command Level 3 Processing is enabled and the user - command line is automatically capitalized, the - terminating zero is placed at the end of the - buffer, and the internal CIBPTR is set correctly - (see later for more information). - - - - Page 8 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - Customization Symbols - - The following symbols are provided for further customization - of ZCPR to a user's particular tastes and hardware facilities. - - Option Name Function - - NLINES Number of lines on the user's CRT for paging - - WIDE This equate is used to select a narrow or wide - display under the DIR command; if WIDE is equated - to TRUE, each file name is separated by two - spaces, a FENCE, and two more spaces; if WIDE is - equated to FALSE, each file name is separated by - one space, a FENCE, and one more space - - PGDFLT This is the Paging Default flag for the TYPE - command; if PGDFLT is set to TRUE, the TYPE - command will page its output by default and - the P option on the TYPE command (see below) - will prohibit paging; if PGDFLT is set to FALSE, - the TYPE command will NOT page its output by - default and the P option will enable paging - - PGDFLG This sets the option character in the command - line for the TYPE command (the 'P' mentioned - above); if the user wishes to change this option - character, he need only change this equate - - MAXUSR This is the largest user number recognized by - the USER command; if the user wishes to protect - the higher user areas, he may set this symbol - to the highest area normally accessable; 15 is - the largest permitted value for MAXUSR - - SYSFLG This is the option character for the DIR command - line which is used to specify that DIR search - All Files (both $SYS and $DIR) for its display; - the distributed default for this is 'A' - - SOFLG This is the option character for the DIR command - line which is used to specify that DIR search - ONLY the $SYS files for its display; the distri- - buted default for this is 'S' - - SUPRES Set SUPRES to TRUE to suppress printing the user - number when the user is under User Number 0 or - set SUPRES to FALSE to ALWAYS display the User - Number with the CPR prompt; with SUPRES set to - TRUE, a user on B: in user 0 sees 'B>' as the - prompt, but with SUPRES set to FALSE, a user on - B: in user 0 sees 'B0>' as the prompt - - - - Page 9 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - DEFUSR This is the CPR-default user number which is - searched in the command hierarchy for the COM - files (distributed as 0); the DFU changes this - temporarily until a Warm Boot or Cold Boot is - done, at which time the search reverts to this - value - - SPRMPT This is the CPR prompt character which indicates - that a SUBMIT file is in execution; by default - it is set to '$', so prompts like 'A$' appear - during SUBMIT file execution - - CPRMPT This is the CPR prompt character which indicates - that the CPR is awaiting a user console command; - by default it is set to '>', so prompts like - 'A>' appear during user input to the CPR - - NUMBASE This is the escape character used by those - commands which require a DECIMAL number as - an argument; placing this character after - the number argument switches the base to - HEXADECIMAL; for example, 'SAVE 15 MYFILE' can be - expressed as 'SAVE FH MYFILE' if NUMBASE is - set to 'H' (the default) - - SECTFLG This character constant is the suffix option for - the SAVE command which specifies that sectors, - as opposed to pages, are to be saved; the default - value is 'S' - - FENCE This is the character printed to separate entries - in a directory listing; it's default value is '|' - - - Patching SUBMIT.COM - - SUBMIT.COM may be patched to run with ZCPR by the following - procedure (this is recommended if the user does not have - SUB.COM). This patch simply makes it always place the $$$.SUB - file on Drive A:. Illustrative terminal session follows: - - A>ddt b:submit.com - DDT VERS 2.0 - NEXT PC - 0600 0100 - -s5bb <-- Patch is at 5BB Hex - 05BB 00 1 <-- Change 0 (default drive) to 1 (drive A:) - 05BC 24 . <-- That's it! - -d5b0 5cf <-- See change - 05B0 00 00 00 00 00 00 30 30 31 20 24 01 24 24 24 20 ......001 $.$$$ - 05C0 20 20 20 20 53 55 42 00 00 00 1A 1A 1A 1A 1A 1A SUB......... - -^C <-- Done - A>save 5 newsubmt.com <-- Save new SUBMIT.COM file - - - - Page 10 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Part B - Usage Instructions and Explanation of Commands - - - The following instructions are written with the assumption - that the reader is quite familiar with how to use CP/M 2.2 and - its CCP. ZCPR is written as a logical extension of the CP/M 2.2 - CCP philosophy and should be addressed as such. - - - - The ZCPR Command Hierarchy Search - - The first, and most basic thing, to learn about ZCPR is the - order in which is searches for a COM file for execution or a file - specified by the GET command. Under the CP/M 2.2 CCP, if the - specified COM file command was not found on the current drive in - the current user area, the CCP aborted with an error message. - ZCPR, however, continues searching from this point a maximum of - two more levels. This command hierarchy search was outlined - above and is described here in further detail. - - 1. If the command is of the form 'COMMAND' and NOT - 'd:COMMAND', the CPR-resident command list is searched for a - match. If the match is found, the CPR-resident command is - immediately processed. If the match is not found or the command - is of the form 'd:COMMAND', the next step is taken. Note that - the 'd:COMMAND' form is good for executing a command COM file - which has the same name as a CPR-resident command (such as SAVE - or DIR). - - 2. If the command is of the form 'd:COMMAND', disk - drive 'd:' is temporarily logged in for the purpose of the - command search. Otherwise, the currently logged-in drive is - used. - - 3. Now the file named COMMAND.COM is searched for. If - found, it is loaded into memory starting at 100H and executed. - If not, proceed to step 4. - - 4. Now that the first search for COMMAND.COM has - failed, the CPR checks to see if the user is under the current - Default User Number. The Default User Number may be that set by - the DEFUSR equate in the CPR or that set by the user via the DFU - command. DEFUSR is in effect if DFU has not been issued since - the last Warm or Cold Boot, and DFU is in effect if it was issued - since the last Warm or Cold Boot. If the user is NOT under the - current Default User Number, ZCPR temporarily logs him into it - and searches the directory. If COMMAND.COM is found, it is - loaded as described above and executed. If not, ZCPR proceeds to - the next step. - - - - - - Page 11 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - 5. The user is now in the Default User Number, and at - this point, ZCPR checks to see if the user is on disk drive A:. - If not, it temporarily logs into A: and searches the default user - number of A: for COMMAND.COM. If found, it is loaded as - described above and executed. If not, ZCPR prints the command - name as an error message and returns to command input mode, - aborting the SUBMIT file if COMMAND came from it. - - In all cases of the search above, if COMMAND.COM is found, - after it is loaded into memory, ZCPR resets the user to his - original disk drive and user number. Hence, the files referenced - by the user by default are obtained from this environment. - - To illustrate this command hierarchy search, consider the - following examples: - - Example 1: DEFUSR equ 0 \{default user number is 0\} - - B10> <-- User is on Drive B:, User Number 10 - B10>ASM TEST.BBZ <-- User wishes to assemble TEST.ASM in - Drive B:, User 10 - <-- At this point, ZCPR looks on B:/10 for ASM.COM, fails, - looks on B:/0, fails, and finally looks on A:/0; it - finds ASM.COM here and goes back to B:/10 for the file - - - Example 2: DEFUSR equ 0 and DFU issued - - B10> <-- User is on Drive B:, User Number 10 - B10>DFU 5 <-- User Selects User 5 as default - B10>ASM TEST.BBZ <-- As above - <-- At this point, ZCPR looks on B:/10 for ASM.COM, fails, - look on B:/5, fails, and finally looks on A:/5; it - fails here also and prints ASM? as an error message - - Example 3: DEFUSR equ 0 - - B> <-- User is on Drive B:, User Number 0 - B>ASM TEST.BBZ <-- As above - <-- At this point, ZCPR looks on B:/0 for ASM.COM, fails, - looks on A:/0, fails, and prints error message - - Example 4: DEFUSR equ 0 - - A10> <-- User is on Drive A:, User Number 10 - A10>ASM TEST.AAZ <-- As above, but file on A: - <-- At this point, ZCPR looks on A:/10 for ASM.COM, fails, - looks on A:/0, fails, and prints error message - - - - - - - - - Page 12 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - Another Example: - - For example, if the user is logged into Drive B: in - User Area 10, the Default User Number is 0, and the following COM - files are present as indicated -- - - WM.COM on Drive A: in User 0 - MBASIC.COM on Drive A: in User 0 and on - Drive B: in User 0 - TEST.COM on Drive B: in User 10 and Drive B: - in User 0 - - then the following happens when the following commands are - issued from the console (or Indirect Command File): - - B10>WM TEST2.TXT - ^ ^ ^-------- File to be edited - | +----------- Invoke the WM.COM file (Word Master editor) - +--------------- User is on Drive B: in User Area 10 - - Results: - ZCPR searches B: User 10, B: User 0, and A: User 0 for - WM.COM; it finds WM.COM in A: User 0, loads it, logs the user - back into B: User 10, and executes it. - - B10>MBASIC - ^ ^----- Invoke the MBASIC.COM file (MBASIC Interpreter) - +--------- User is on Drive B: in User Area 10 - - Results: - ZCPR searches B: User 10 and B: User 0 for MBASIC.COM; - it finds MBASIC.COM in B: User 0, so it doesn't bother to look on - A: User 0. MBASIC.COM is then loaded and executed as described - in the previous example. - - B10>TEST - ^ ^--- Invoke the TEST.COM file (TEST program) - +------- User is on Drive B: in User Area 10 - - Results: - ZCPR searches B: User 10 for TEST.COM; it finds - TEST.COM in B: User 0, so it doesn't bother to look further (if - it had, it would have found TEST.COM in B: User 0). TEST.COM is - then loaded and executed as described above. - - B10>TEST2 - | +--- Invoke the TEST2.COM file (TEST2 program) - +------- User is on Drive B: in User Area 10 - - Results: - ZCPR searches B: User 10, B: User 0, and A: User 0 for - TEST2.COM; it doesn't find it, so it issues the error message - 'TEST2?', which says it couldn't find TEST2.COM. - - - - Page 13 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - - The ZCPR-Resident Commands - - The following pages describe the ZCPR-Resident Commands. - These are commands located within ZCPR itself which are executed - from within ZCPR. The phrases and refer to ambiguous - file name and unambigous file name as per the CP/M convention. - - Command: DIR - Function: To Display a listing of the names of the files on disk - Forms: - DIR <-- Displays $DIR files - DIR S <-- Displays $SYS files - DIR A <-- Displays both $DIR and $SYS files - Customization Variables: - WIDE SYSFLG SOFLG FENCE - Examples: - DIR *.ASM <-- All $DIR .ASM files - DIR *.COM S <-- All $SYS .COM files - DIR *.COM A <-- All .COM files - Notes: - If a file is scanned for and no such name exists on disk, - the 'No Files' message will appear. However, if a file is - scanned for and the name exists as a $SYS file and $DIR files are - being scanned for, no file name is displayed but the 'No Files' - message does NOT appear. For example, if TEST.COM is a $SYS file - and 'DIR TEST.COM' is issued, no message appears. If 'DIR - TEXT.COM' is issued and TEXT.COM does not exist on disk, the 'No - Files' message is displayed. - - - Command: ERA - Function: To Erase the specified $R/W files from disk - Forms: - ERA <-- Erase both $DIR and $SYS files - Customization Variables: - WIDE FENCE - Examples: - ERA *.ASM <-- Erase all .ASM files - ERA *.* <-- Erase all files - Notes: - If a $R/O file is encountered, a BDOS error message will be - displayed and the procedure is stopped. The user is unsure at - this time as to which files have been erased and which have not - and should check. Sorry for this problem! The ERASE command (to - be given to SIG/M by RLC in the near future) is a solution to - this problem. - - - - - - - - - Page 14 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - Command: LIST - Function: To Print the specified file on the CP/M LST: device - Forms: - LIST <-- Print the file (no paging) - Customization Variables: - -None- - Examples: - LIST TEST.TXT <-- Print TEST.TXT on LST: - Notes: - If the file has a $SYS attribute, it will be found as well - as those with $DIR attributes. - - - Command: TYPE - Function: To Print the specified file on the CP/M CON: device - Forms: - TYPE <-- Print the file with the paging deflt - TYPE P <-- Print the file with the paging deflt - negated - Customization Variables: - NLINES PGDFLT PGDFLG - Examples: - TYPE TEST.TXT - TYPE TEST.TXT P - Notes: - When the display pauses during paging, type any char to - continue or ^C to abort. ^S also works. - - - Command: SAVE - Function: To Copy the TPA starting at 100H to disk - Forms: - SAVE <-- in DEC - SAVE H <-- in HEX - SAVE S <-- Number of sectors - SAVE H S <-- Number of sectors - Customization Variables: - NUMBASE RAS - Examples: - SAVE 15 MYFILE.TXT <-- 15 pages saved - SAVE FH MYFILE.TXT <-- 15 pages saved - SAVE 10H MYFILE.TXT S <-- 16 sectors (8 pages) saved - Notes: - If the file name to be saved already exists, then SAVE will - exit with the message 'Delete File?'; if the user REALLY wants to - save under this name, he may then type Y or y and the current - file will be deleted and then recreated containing the specified - part of the TPA. - - - - - - - - Page 15 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - - Command: REN - Function: To Change the name of a disk file - Forms: - REN = - Customization Variables: - RAS - Examples: - REN NEWFILE.TXT=OLDFILE.TXT - Notes: - If already exists, the message 'Delete File?' will - be printed and the user may respond with Y or y to delete the - current and then rename to . - - Command: USER - Function: To Change the current user number - Forms: - USER <-- in DEC - USER H <-- in HEX - Customization Variables: - -None- - Examples: - USER 15 USER FH USER 0 - USER <-- Same as USER 0 - Notes: - -None- - - - Command: DFU - Function: To Temporarily Change the default user number for the - command hierarchy search - Forms: - DFU <-- in DEC - DFU H <-- in HEX - Customization Variables: - -None- - Examples: - DFU 15 DFU FH DFU 0 - DFU <-- Same as DFU 0 - Notes: - See above for explanation. - - - - - - - - - - - - - - - Page 16 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - - Command: JUMP - Function: To "call" the subroutine at the specified page address - Forms: - JUMP
<--
in HEX - Customization Variables: - NUMBASE RAS - Examples: - JUMP E000 or JUMP E000H <-- Jump to E000H - JUMP <-- Jump to 000H - JUMP 0 <-- Jump to 000H - Notes: - JUMP performs a subroutine "call", so the called routine may - return to the ZCPR by either a RET or a Warm Boot. - - - Command: GO - Function: To "call" the subroutine starting at 100H - Forms: - GO <-- Execute reentrant at 100H - Customization Variables: - RAS - Examples: - GO *.ASM <-- Assuming XDIR is loaded, - gives directory of *.ASM - Notes: - This command is identical in function to JUMP 100H; JUMP, - however, leaves the address as the first entry in CP/M BASE + 80H - (the input line buffer), while GO has no such address. - - - Command: GET - Function: To load a file from disk into memory starting at the - specified page - Forms: - GET
<--
in HEX - Customization Variables: - NUMBASE RAS - Examples: - GET 8000 TEST.80 <-- Load TEST.80 starting at 8000H - GET 100 TEST.80 or GET 100H TEST.80 <-- Load TEST.80 - starting at 100H - GET 0 TEST.80 <-- Load TEST.80 starting at 000H - Notes: - GET searches for the specified file according to the same - command hierarchy search employed by the ZCPR command scanner. - Hence, if the user is on B:/10 and the file is on A:/0 with the - current default user number at 0, GET will search from B:/10 to - B:/0 to A:/0 in looking for the file. - - - - - - - Page 17 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - ZCPR Error Messages - - The following are the error messages issued by ZCPR and - their meanings. - - Message Meaning - - ? Printed after a command or an argument means that such - was invalid - - No File From DIR, this means that DIR did not locate any files - Also from ERA with the same meaning - - All? Issued in response ERA *.*, asks the user is he really - wants to erase all the files. Unlike under the - original CP/M 2.2 CCP, single character input is - required (Y or y for yes and anything else for no) - with NO to end the line - - Full From SAVE, means that there is not enough space on - disk - From GET or command load by CPR, means that there - is not enough space in memory - - Delete File? - From REN or SAVE, means that the file specified already - exists on disk and the user may type Y or y to delete - it and proceed with the REN or SAVE function - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Page 18 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - Part C - ZCPR Command Levels and How to Use Them - - - ZCPR Version 1.0 and beyond supports three distinct command - levels in its implementation. Each level constitutes a different - way to issue a command for ZCPR to process. - - Command Levels 1 and 2 are common to all implementations of - CP/M and CP/ZM from CP/M Version 1.4. Command Level 1 is that - command level in which the command is issued by the user from his - console terminal. The prompt 'd>' or 'du>' appears on the - terminal, and the user is allowed to enter the command with - editing from the terminal. Command Level 2 is that command level - in which the command is entered from an executing $$$.SUB file. - - In both cases, the command is stored in the internal ZCPR - buffer called CIBUFF (Command Input BUFFer). Under both Command - Levels 1 and 2, the command is placed into this buffer, the - characters of the command line are capitalized, a character count - which indicates the number of characters in the command line is - stored in CBUFF (the byte before CIBUFF), an ending binary 0 is - placed after the last character in the command line, and the - internal pointer CIBPTR (Command Input Buffer PoinTeR) is set to - point to CIBUFF (the first character of the command line). - - Command Level 3 is an extended concept to Command Levels 1 - and 2 which is specifically supported by ZCPR Version 1.0 and - beyond. This command level allows a transient program to place a - command line into CIBUFF and the character count into CBUFF and - have this command line executed by ZCPR. Once control is trans- - ferred to ZCPR to execute the command line, the transient program - which placed the command line loses control and the command is - executed exactly as though it had been typed by the user at his - console terminal. - - In order for a transient program to utilize the Command - Level 3 facility, this program MUST do the following: - - 1. Locate the ZCPR. Since the ZCPR is ALWAYS 2K bytes - in size and located directly under the BDOS, the transient can - locate the ZCPR by examining the BDOS entry page address at - location 7 and subtracting 8 from this number (8 pages = 2K - bytes). The resulting number is the base page address of ZCPR. - - 2. Store the command line in CIBUFF and the character - count in CBUFF. Knowing the base page address of ZCPR, the - following information is useful in doing this: - - - - - - - - Page 19 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - ORG CPRLOC ;Base Address of ZCPR - JMP CPR ;Enter ZCPR and Execute Default Cmd - JMP CPR1 ;Enter ZCPR and Don't Execute - MBUFF: DB BUFLEN ;Size of CIBUFF in bytes - CBUFF: DS 1 ;Number of Bytes in Command Line - CIBUFF: DS BUFLEN ;Buffer for Command Line - DS 1 ;Buffer for Ending 0 (set by ZCPR) - CIBPTR: DS 2 ;Address of CIBUFF (set by ZCPR) - - - 3. Obtain the User/Disk Flag. Location 4 contains - this number, but the user may select a flag of his choice. This - flag is one byte long, and the high-order nybble (4 bits) - contains the user number and the low-order nybble contains the - disk number to process the command from. The User/Disk Flag is - to be passed to ZCPR in the C Register. - - 4. When ready, transfer control to ZCPR to process the - command by JMPing to the base address of ZCPR. The first JMP in - the JMP Table given above is at this address. At this time, ZCPR - will log in the user and disk in the User/Disk Flag and process - the Command Level 3 Command Line. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Page 20 - - - - - - ZCPR - A Z80 Replacement for the CP/M CCP - - - - - The following is a sample program which illustrates the - steps outlined above: - - ; - ; Demonstration of Command Level 3 Facility by RLC - ; - udflag equ 4 ;Address of User/Disk Flag - bdos equ 5 ;Address of BDOS Entry Point - - org 100h - - lxi d,prmpt ;Print User Prompt - mvi c,9 ;PRINT function - call bdos - - lhld bdos+1 ;Get address of BDOS - mov a,h ;High-Order Address in A - sui 8 ;A=High-Order Address of CPR - mov h,a ;HL=Address of CPR - mvi l,0 - shld cpr ;Save address in buffer - - lxi d,6 ;Point to command line buffer - dad d ;HL points to command line buffer - xchg ;DE points to command line buffer - mvi c,10 ;READLN into this buffer - call bdos - - lhld cpr ;Get Address of CPR - lda udflag ;Get User/Disk Flag - mov c,a ; ... in C - pchl ;Run Command Line - - cpr: ds 2 ;CPR Address buffer - prmpt: db 'User Command? $' - - - - - - - Enjoy using ZCPR! - -- RLC - - - - - - - - - - - - - Page 21 \ No newline at end of file diff --git a/Source/Makefile b/Source/Makefile index 1204b022..166bb4c1 100644 --- a/Source/Makefile +++ b/Source/Makefile @@ -1,7 +1,6 @@ # # order is actually important, because of build dependencies # -NOTDONE = Doc SUBDIRS = Prop SUBDIRS += Apps SUBDIRS += CBIOS