Miscellaneous

- Added "Character Device Mapping" sub-section to each of the Operating System sections of the User Guide.  This attempts to clarify how character devices will appear within the different operating system environments.
- Generate a disk image "catalog" file for each disk image generated during build.  This simply helps confirm what files wound up on each disk image and the space used/free.
- Make the CP/M 2.2 files added to NZCOM and ZSDOS consistent.

ReadMe.md

@@ -3,7 +3,7 @@
 **RomWBW ReadMe** \
 Version 3.5 \
 Wayne Warthen  ([wwarthen@gmail.com](mailto:wwarthen@gmail.com)) \
-25 Oct 2024
+27 Oct 2024
 
 # Overview
 
@@ -199,7 +199,8 @@ let me know if I missed you!
   User Guide and Applications documents.
 
 - Mark Pruden has also contributed a great deal of content to the Disk
-  Catalog, User Guide as well as the COPYSL utility.
+  Catalog, User Guide as well as contributing the disk image for the
+  Z3PLUS operating system, and the COPYSL utility.
 
 - Jacques Pelletier has contributed the DS1501 RTC driver code.
 

ReadMe.txt

@@ -1,6 +1,6 @@
 RomWBW ReadMe
 Wayne Warthen (wwarthen@gmail.com)
-25 Oct 2024
+27 Oct 2024
 
 
 
@@ -200,7 +200,8 @@ let me know if I missed you!
     User Guide and Applications documents.
 
 -   Mark Pruden has also contributed a great deal of content to the Disk
-    Catalog, User Guide as well as the COPYSL utility.
+    Catalog, User Guide as well as contributing the disk image for the
+    Z3PLUS operating system, and the COPYSL utility.
 
 -   Jacques Pelletier has contributed the DS1501 RTC driver code.
 

Source/Doc/Catalog.md

@@ -122,21 +122,21 @@ The following files appear in User Area 0
 | **File**        | **Description**                  | **Also Found In** |
 |-----------------|----------------------------------|-------------------|
 | `ASM.COM`       | 8080 assembler                   | NZCOM, QPM, ZSDOS |
-| `DDT.COM`       | 8080 dunamic debugger            | QPM               |
-| `DUMP.COM`      | type contents of file in hex     | QPM               |
-| `ED.COM`        | line editor                      | QPM               |
-| `HELP.COM`      | CP/M 3 Derived HELP display      | QPM               |
-| `HELP.HLP`      | CP/M 3 Derived HELP data file    | QPM               |
+| `DDT.COM`       | 8080 dynamic debugger            | NZCOM, QPM, ZSDOS |
+| `DUMP.COM`      | type contents of file in hex     | NZCOM, QPM, ZSDOS |
+| `ED.COM`        | line editor                      | NZCOM, QPM, ZSDOS |
+| `HELP.COM`      | CP/M 3 Derived HELP display      | NZCOM, QPM, ZSDOS |
+| `HELP.HLP`      | CP/M 3 Derived HELP data file    | NZCOM, QPM, ZSDOS |
 | `LIB.COM`       | object file library manager      | NZCOM, QPM, ZSDOS |
 | `LINK.COM`      | object file linker               | NZCOM, QPM, ZSDOS |
 | `LOAD.COM`      | loader for Intel hex files       | NZCOM, QPM, ZSDOS |
 | `MAC.COM`       | 8080 macro assembler             | NZCOM, QPM, ZSDOS |
-| `PIP.COM`       | file transfer program            | QPM               |
-| `RMAC.COM`      | 8080 macro assembler             | NZCOM, QPM, ZSDOS |
+| `PIP.COM`       | file transfer program            | NZCOM, QPM, ZSDOS |
+| `RMAC.COM`      | 8080 relocating macro assembler  | NZCOM, QPM, ZSDOS |
 | `STAT.COM`      | file/disk/device info & config   | NZCOM, QPM, ZSDOS |
 | `SUBMIT.COM`    | batch file submission tool       | NZCOM, QPM, ZSDOS |
 | `XSUB.COM`      | batch file resident extension    | NZCOM, QPM, ZSDOS |
-| `ZSID.COM`      | Z80 symbolic debugger            | QPM               |
+| `ZSID.COM`      | Z80 symbolic debugger            | NZCOM, QPM, ZSDOS |
 
 As noted above several of the above files are also present in other 
 disk images besides CP/M 2.2

Source/Doc/UserGuide.md

@@ -2418,6 +2418,88 @@ call "CPM.SYS".  For example:
 
 `SYSCOPY C:=B:CPM.SYS`
 
+#### Character Device Mapping
+
+Character device mapping under CP/M 2.2 has 3 layers:
+
+CP/M Logical Device --> CP/M Physical Device --> RomWBW HBIOS Device
+
+The CP/M Logical Devices are:
+
+| Device | Description                                                              |
+|--------|--------------------------------------------------------------------------|
+| `CON:` | System console device, used by CCP for communication with the operator   |
+| `RDR:` | Paper tape reader device                                                 |
+| `PUN:` | Paper tape punch device                                                  |
+| `LST:` | Output list device                                                       |
+
+The CP/M Physical Devices are:
+
+| Device | Description                                                              |
+|--------|--------------------------------------------------------------------------|
+| `TTY:` | Teletype device (slow speed console)                                     |
+| `CRT:` | Cathode ray tube device (high speed console)                             |
+| `BAT:` | Batch processing (input from `RDR:`, output to `LST:`)                   |
+| `UC1:` | User-defined console                                                     |
+| `PTR:` | Paper tape reader (high speed reader)                                    |
+| `UR1:` | User-defined reader #1                                                   |
+| `UR2:` | User-defined reader #2                                                   |
+| `PTP:` | Paper tape punch (high speed punch)                                      |
+| `UP1:` | User-defined punch #1                                                    |
+| `UP2:` | User-defined punch #2                                                    |
+| `LPT:` | Line printer                                                             |
+| `UL1:` | User-defined list device #1                                              |
+
+CP/M Logical Devices are mapped to CP/M Physical Devices via the
+IOBYTE at 0x0003 as shown below.
+
++----------------+----------+----------+----------+----------+
+| Logical Device | `LST:`   | `PUN:`   | `RDR:`   | `CON:`   |
++----------------+----------+----------+----------+----------+
+| IOBYTE Bits    | 7 6      | 5 4      | 3 2      | 1 0      |
++================+==========+==========+==========+==========+
+| 0 (0b00)       | `TTY:`   | `TTY:`   | `TTY:`   | `TTY:`   |
++----------------+----------+----------+----------+----------+
+| 1 (0b01)       | `CRT:`   | `PTP:`   | `PTR:`   | `CRT:`   |
++----------------+----------+----------+----------+----------+
+| 2 (0b10)       | `LPT:`   | `UP1:`   | `UR1:`   | `BAT:`   |
++----------------+----------+----------+----------+----------+
+| 3 (0b11)       | `UL1:`   | `UP2:`   | `UR2:`   | `UC1:`   |
++----------------+----------+----------+----------+----------+
+
+The mappings above can be managed using the `STAT` command.  This
+command essentially just modifies the IOBYTE value.
+
+CP/M Physical Devices are mapped to RomWBW HBIOS devices during
+the boot process depending on the number of HBIOS Char devices
+in the system.
+
+All CP/M Physical Devices are initially mapped to HBIOS Char 0.
+If additional HBIOS Char devices are available in the system, they will
+be mapped as below:
+
+| CP/M   | RomWBW HBIOS     |
+|--------|------------------|
+| `TTY:` | Char 0           |
+| `CRT:` | CRT              |
+| `BAT:` | CP/M RDR/LST     |
+| `UC1:` | Char 1           |
+| `PTR:` | Char 1           |
+| `UR1:` | Char 2           |
+| `UR2:` | Char 3           |
+| `PTP:` | Char 1           |
+| `UP1:` | Char 2           |
+| `UP2:` | Char 3           |
+| `LPT:` | Char 1           |
+| `UL1:` | Char 2           |
+
+Normally, the HBIOS Console device (Loader prompt) is on HBIOS Device
+Char 0.  If it has been reassigned to a different HBIOS character
+device before launching CP/M, then the above mapping will be modified.
+TTY: will be assigned to the current HBIOS console Char device.  The
+remaining assignments will be filled in with the other Char devices
+as available.
+
 #### Notes
 
 * You can change media, but it must be done while at the OS
@@ -2466,6 +2548,12 @@ call "ZSYS.SYS".  For example:
 
 `SYSCOPY C:=B:ZSYS.SYS`
 
+#### Character Device Mapping
+
+Mapping of character devices to RomWBW HBIOS Character devices
+operates exactly the same as described in [Digital Research CP/M 2.2].
+The CP/M 2.2 `STAT` command is used to manipulate the device mappings.
+
 #### Notes
 
 * Although most CP/M 2.2 applications will run under Z-System, some
@@ -2537,6 +2625,18 @@ Since NZ-COM boots via Z-System, you can make a bootable
 NZ-COM disk using `ZSYS.SYS` as described in [Z-System] above.  You
 will need to add a `PROFILE.SUB` file to auto-start NZ-COM itself.
 
+#### Character Device Mapping
+
+Mapping of character devices to RomWBW HBIOS Character devices
+operates exactly the same as described in [Digital Research CP/M 2.2].
+However, it is **not** possible to manipulate the CP/M Logical to
+Physical device mapping using the `STAT` command.  The mapping is
+static.
+
+Note: A custom ZCPR IOP module could theoretically be used to manage
+the character device mappings.  RomWBW does not provide this module
+and writing an IOP module is beyond the scope of this document.
+
 #### Notes
 
 * All of the notes for [Z-System] above generally apply to NZCOM.
@@ -2607,6 +2707,36 @@ COPY A:CCP.COM F:
 Note in the example above that `CPM3BNK.SYS` is renamed to `CPM3.SYS`
 in the copy command.
 
+#### Character Device Mapping
+
+Character device mapping under CP/M 3 has 3 layers:
+
+CP/M Logical Device --> CP/M Physical Device --> RomWBW HBIOS Device
+
+The primary CP/M Logical Devices are:
+
+| Device | Description                                                              |
+|--------|--------------------------------------------------------------------------|
+| `CON:` | Console input or output device                                           |
+| `AUX:` | Auxiliary Input or Output Device                                         |
+| `LST:` | List output device, usually the printer                                  |
+
+There are various aliases for these devices.  Please refer to the CP/M 3
+Users Guide for more information.
+
+The mapping of CP/M 3 Logical Devices to Physical Devices is performed
+using the `DEVICE` command.
+
+CP/M 3 refers to Physical Character Devices using the `COM` device 
+label.  These `COM` devices are mapped directly to the RomWBW HBIOS Char
+devices as described below:
+
+|       `COM0:` --> HBIOS Char 0
+|       `COM1:` --> HBIOS Char 1
+|       `COM2:` --> HBIOS Char 2
+|       . . .
+|       `COMn:` --> HBIOS Char n
+
 #### Notes
 
 - The `COPYSYS` command described in the DRI CP/M 3 documentation is
@@ -2662,6 +2792,12 @@ section above.
 
 You will need to add a `PROFILE.SUB` file to auto-start Z3PLUS itself.
 
+#### Character Device Mapping
+
+Mapping of character devices to RomWBW HBIOS Character devices
+operates exactly the same as described in [Digital Research CP/M 3].
+The CP/M 3 `DEVICE` command is used to manipulate the device mappings.
+
 #### Notes
 
 * All of the notes for [Digital Research CP/M 3] above generally 
@@ -2739,6 +2875,12 @@ COPY A:ZINSTAL.ZPM F:
 COPY A:STARTZPM.COM F:
 ```
 
+#### Character Device Mapping
+
+Mapping of character devices to RomWBW HBIOS Character devices
+operates exactly the same as described in [Digital Research CP/M 3].
+The CP/M 3 `DEVICE` command is used to manipulate the device mappings.
+
 #### Notes
 
 - The ZPM3 operating system is contained in the file called CPM3.SYS 
@@ -2762,7 +2904,6 @@ regarding the RomWBW adaptation and customizations.
 
 #### Boot Disk
 
-
 To create or update a bootable QP/M Z-System disk, a special process
 is required.  QP/M is not provided in source format.  You are expected
 to install QP/M over an existing CP/M installation using the
@@ -2793,6 +2934,14 @@ pre-built RomWBW QP/M disk image includes a couple of specific
 non-default settings to optimize use with RomWBW.  Please review the
 notes in the ReadMe.txt file in Source/Images/d_qpm.
 
+#### Character Device Mapping
+
+Mapping of character devices to RomWBW HBIOS Character devices operates 
+exactly the same as described in [Digital Research CP/M 2.2]. The 
+mappings can be viewed or modified using the QP/M `QSTAT` command which 
+is analogous to the CP/M 2.2 `STAT` command.  Do **not** use the CP/M 
+2.2 `STAT` command under QP/M.
+
 #### Notes
 
 - QPM is not available as source.  This implementation was based
@@ -2856,6 +3005,13 @@ scratch under RomWBW.  This has already been done as part of the
 porting process.  You must use the provided p-System hard disk image
 file which is bootable.
 
+#### Character Device Mapping
+
+RomWBW Character Devices are automatically assigned to p-System devices 
+at startup.  The current HBIOS Console device is assigned to CONSOLE:.  
+The next available HBIOS Char device is assigned to REMIN:/REMOUT:.  The
+next available HBIOS Char devices is assigned to PRINTER:
+
 #### Notes
 
 * There is no floppy support at this time.

Source/Images/BuildDisk.ps1

@@ -25,6 +25,7 @@ switch ($Format)
 		# 1.44MB Floppy Disk
 		$Desc = "1.44MB Floppy Disk"
 		$ImgFile = "fd144_${Disk}.img"
+		$CatFile = "fd144_${Disk}.cat"
 		$MediaID = 6
 		$Size = 1440KB
 	}
@@ -34,6 +35,7 @@ switch ($Format)
 		# 512 Directory Entry Hard Disk Format
 		$Desc = "Hard Disk (512 directory entry format)"
 		$ImgFile = "hd512_${Disk}.img"
+		$CatFile = "hd512_${Disk}.cat"
 		$MediaID = 4
 		$Size = 8MB + 128KB
 	}
@@ -43,6 +45,7 @@ switch ($Format)
 		# 1024 Directory Entry Hard Disk Format
 		$Desc = "Hard Disk (1024 directory entry format)"
 		$ImgFile = "hd1k_${Disk}.img"
+		$CatFile = "hd1k_${Disk}.cat"
 		$MediaID = 10
 		$Size = 8MB
 	}
@@ -96,6 +99,10 @@ if (Test-Path("${Type}_${Disk}.txt"))
 	}
 }
 
+$Cmd = "cpmls -f $Format -D $ImgFile"
+$Cmd
+Invoke-Expression $Cmd > $CatFile
+
 "Moving image $ImgFile into output directory..."
 
 Move-Item $ImgFile -Destination "..\..\Binary\" -Force

Source/Images/Clean.cmd

@@ -4,3 +4,4 @@ setlocal
 if exist *.tmp del *.tmp
 if exist *.img del *.img
 if exist *.sys del *.sys
+if exist *.cat del *.cat

Source/Images/Makefile

@@ -34,7 +34,7 @@ OBJECTS = $(FDIMGS)
 OBJECTS += $(HD512IMGS) $(HD512XIMGS) hd512_combo.img $(HD512PREFIX)
 OBJECTS += $(HD1KIMGS) $(HD1KXIMGS) hd1k_combo.img $(HD1KPREFIX)
 
-OTHERS = blank144 blankhd512 blankhd1k
+OTHERS = blank144 blankhd512 blankhd1k *.cat
 
 NODELETE = $(HD512PREFIX) $(HD1KPREFIX)
 
@@ -131,7 +131,7 @@ blankhd1k:
 			fi ; \
 		done ; \
 	fi ; \
-
+	$(CPMLS) -f $$fmt -D $@ > $(@:.img=.cat)
 
 clean::
 	@rm -f *.ls

Source/Images/fd_nzcom.txt

@@ -3,12 +3,9 @@
 #
 d_nzcom/ReadMe.txt 0:
 #
-# Include selected CP/M 2.2 files
+# Include CP/M 2.2 files
 #
-d_cpm22/u0/PIP.COM 15:
-d_cpm22/u0/STAT.COM 15:
-d_cpm22/u0/SUBMIT.COM 0:
-d_cpm22/u0/XSUB.COM 15:
+d_cpm22/u0/*.* 0:
 #
 # Add RomWBW utilities
 #

Source/Images/fd_zsdos.txt

@@ -3,18 +3,9 @@
 #
 d_zsdos/ReadMe.txt 0:
 #
-# Include selected CP/M 2.2 files
-#
-d_cpm22/u0/ASM.COM 0:
-d_cpm22/u0/LIB.COM 0:
-d_cpm22/u0/LINK.COM 0:
-d_cpm22/u0/LOAD.COM 0:
-d_cpm22/u0/MAC.COM 0:
-d_cpm22/u0/PIP.COM 0:
-d_cpm22/u0/RMAC.COM 0:
-d_cpm22/u0/STAT.COM 0:
-d_cpm22/u0/SUBMIT.COM 0:
-d_cpm22/u0/XSUB.COM 0:
+# Include CP/M 2.2 files
+#
+d_cpm22/u0/*.* 0:
 #
 # Add RomWBW utilities
 #

Source/Images/hd_nzcom.txt

@@ -3,18 +3,9 @@
 #
 d_nzcom/ReadMe.txt 0:
 #
-# Include selected CP/M 2.2 files
-#
-d_cpm22/u0/ASM.COM 15:
-d_cpm22/u0/LIB.COM 15:
-d_cpm22/u0/LINK.COM 15:
-d_cpm22/u0/LOAD.COM 15:
-d_cpm22/u0/MAC.COM 15:
-d_cpm22/u0/PIP.COM 15:
-d_cpm22/u0/RMAC.COM 15:
-d_cpm22/u0/STAT.COM 15:
-d_cpm22/u0/SUBMIT.COM 0:
-d_cpm22/u0/XSUB.COM 15:
+# Include CP/M 2.2 files
+#
+d_cpm22/u0/*.* 0:
 #
 # Include ZSDOS files
 #

Source/Images/hd_zsdos.txt

@@ -3,18 +3,9 @@
 #
 d_zsdos/ReadMe.txt 0:
 #
-# Include selected CP/M 2.2 files
+# Include CP/M 2.2 files
 #
-d_cpm22/u0/ASM.COM 0:
-d_cpm22/u0/LIB.COM 0:
-d_cpm22/u0/LINK.COM 0:
-d_cpm22/u0/LOAD.COM 0:
-d_cpm22/u0/MAC.COM 0:
-d_cpm22/u0/PIP.COM 0:
-d_cpm22/u0/RMAC.COM 0:
-d_cpm22/u0/STAT.COM 0:
-d_cpm22/u0/SUBMIT.COM 0:
-d_cpm22/u0/XSUB.COM 0:
+d_cpm22/u0/*.* 0:
 #
 # Add RomWBW utilities
 #