Documenation changes for the NVRAM changes

Doc/ChangeLog.txt

@@ -47,7 +47,7 @@ Version 3.5
 - MAP: Significant improvement in Disk Catalog document
 - MAP: Added Disk Image for the Z3PLUS (Z-System for CP/M-Plus) os.
 - H?H: Fix XModem 12.3 WRERR to put CAN char in proper register to send.
-- MAP: Initial NVRAM configuration infrastructure
+- MAP: Initial NVRAM configuration infrastructure, and boot device selection.
 
 Version 3.4
 -----------

ReadMe.md

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

ReadMe.txt

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

Source/CBIOS/cbios.asm

@@ -78,7 +78,7 @@ MEMTOP		.EQU	$10000
 #INCLUDE "../UBIOS/ubios.inc"
 #ENDIF
 ;
-	.ORG	CBIOS_LOC		; DEFINED IN STD.ASM
+	.ORG	CBIOS_LOC		; DEFINED IN LAYOUT.INC
 ;
 STACK	.EQU	CBIOS_END		; USE SLACK SPACE FOR STACK AS NEEDED
 ;

Source/Doc/Applications.md

@@ -384,6 +384,109 @@ protocol.
 
 **`X`** - Exit the monitor program back to the main boot menu.
 
+## RomWBW System Configuration
+
+System Configuration (`SYSCONF`) is a utility that allows system configuration to 
+be set, dynamically and stored in NVRAM provided by an RTC chip.
+
+(`SYSCONF`) is both a ROM application ('W' Menu option), and a CP/M utility.
+Noting however the CP/M utility is not included on an disk image, it is found in
+the `Binary/Applications` folder of the RomWBW distribution
+
+### Basic Operation
+
+The application is an interactive application it does not have command line syntax.
+Instead commands are executed from within the application in a command line structure
+
+When you first start the (`SYSCONF`) utility it will display the current switches
+followed by a command listing.
+
+When you first run the (`SYSCONF`) utility the NVRAM will be uninitialised, and can 
+be initialised using the (R)eset command, which write default values to NVRAM.
+
+Updates are done immediately to NVRAM as you enter them, i.e. there is no confirm
+changes step. If you make an incorrect changes you simply need to enter a new
+command to set the Switch value correctly
+
+Once a change has been made it is available, however may not take effect until
+the next system reboot. This is dependant on the Switch itself
+
+If no NVRAM is provided by your hardware then running this application will just
+report the missing hardware and exit immediately.
+
+To exit from the application use the (Q)uit command
+
+### Commands and Syntax
+
+The following are the accepted commands, unless otherwise specified a "Space" 
+character is used to delimit parameters in the command 
+
+| Command    | Argument(s)      | Description                                   | 
+|------------|------------------|-----------------------------------------------| 
+| (P)rint    | -none-           | Display a list of the current switch value(s) | 
+| (S)et      | {SW} {val},...   | Sets an Switch {SW} with specific values(s)   | 
+| (R)eset    | -none-           | Reset all setting to default                  | 
+| (H)elp     | {SW}             | Provides help on the syntax (values)          | 
+| (Q)uit     | -none-           | Exit the application                          | 
+
+**Where**
+
+| Argument  | Description                                                          |
+|-----------|----------------------------------------------------------------------|
+| {SW}      | Switch ID, typically this is 2 character name to identify the switch |
+| {val},... | a "Comma" separated list of values to set into the switch            |
+
+### Switch Options
+
+#### Auto Boot (AB)
+
+This switch will define if the system will perform auto boot at the RomWBW boot prompt. 
+Enabling this will not prevent a user from typing a boot command, so long as the timeout is not
+exceeded. When configured this replaces the (`BOOT_DEFAULT`) variable
+defined in build configuration.
+
+Making changes to auto boot has no affect until the next reboot.
+
+**Arguments**
+
+| Type     | Arguments  | Description                                            | 
+|----------|------------|--------------------------------------------------------| 
+| Enable   | 'E'        | Auto Boot. eg. "E,10" will auto boot, after 10 seconds | 
+|          | Timout     | Timeout in seconds in the range 0-15, 0 = immediate    | 
+| Disabled | 'D'        | No Auto Boot. e.g. "D" will disable autoboot           | 
+
+**Examples**
+
+| Command               | Description                                       | 
+|-----------------------|---------------------------------------------------| 
+| S AB E,10             | Enable Auto Boot with 10 second delay             | 
+| S AB D                | Disable Auto Boot                                 | 
+
+#### Default Boot (DB)
+
+This switch will define the default boot command to be executed when pressing enter
+at the RomWBW boot prompt. When configured this replaces the (`BOOT_TIMEOUT`) variable
+defined in build configuration.
+
+Making changes to auto boot has no affect until the next reboot.
+
+**Arguments**
+
+| Type | Arguments        | Description                                              | 
+|------|------------------|----------------------------------------------------------| 
+| Disk | 'D'              | Disk Boot. eg. "D,2,14" will boot, disk unit 2, slice 14 | 
+|      | Disk Unit Number | Unit number in the range 0-127                           | 
+|      | Disk Slice       | Slice in the range 0-255, use 0 for floppy boot          | 
+| ROM  | 'R'              | ROM App. e.g. "R,M" will boot the Monitor App            | 
+|      | Rom App Name     | single character used on the Menu to identify the app    | 
+
+**Examples**
+
+| Command     | Description                                              | 
+|-------------|----------------------------------------------------------| 
+| S DB D,2,14 | Set the default boot from Disk; Unit 2, Slice 14         | 
+| S DB R,M    | Set the default boot to be the (M)onitor Rom Application | 
+
 ## CP/M 2.2
 
 This option will boot the CP/M 2.2 disk operating system 

Source/Doc/ReadMe.md

@@ -191,7 +191,8 @@ please let me know if I missed you!
   
 * Mark Pruden has also contributed a great deal of content to the
   Disk Catalog, User Guide as well as contributing the disk image
-  for the Z3PLUS operating system, and the COPYSL utility.
+  for the Z3PLUS operating system, the COPYSL utility, and also
+  implemented feature for RomWBW configuration by NVRAM.
 
 * Jacques Pelletier has contributed the DS1501 RTC driver code.
 

Source/Doc/SystemGuide.md

@@ -499,6 +499,77 @@ The startup then proceeds very much like the Application Boot
 process described above.  HBIOS is installed in its operating bank
 and control is passed to the Boot Loader.
 
+# Configuration
+
+## RomWBW NVRAM Configuration
+
+On systems with RTC devices (that have Non-Volitile RAM), RomWBW supports storing
+some limited configuration option options inside this RAM
+
+Several configuration options are currently supported, these are known as Switches
+The following switch ID's are defined, and described in sections below
+
+| Switch Number | Name         | Description                                   |      
+|---------------|--------------|-----------------------------------------------|      
+| 0x00          | -reserved-   | Reserved                                      |      
+| 0x01          | Default Boot | Default boot, either a Rom App or Disk Boot   |      
+| 0x02          | -n/a-        | -n/a- high order byte of previous switch      |      
+| 0x03          | Auto Boot    | Automatically boot enabled without user input |
+| 0x04 - 0xFE   | -future-     | Future general usage                          |
+| 0xFF          | Status Reset | Get Status or Reset Switches to Default       |     
+
+RomWBW uses bytes located at the start of RTC NVRAM, and includes a Parity check of
+the bytes in NVRAM to check for authenticity before using the configuration.
+
+| NVRAM Byte  | Name         | Description                       |      
+|-------------|--------------|-----------------------------------|      
+| 0x00        | Header Byte  | Header Signature Byte 'W'         |      
+| 0x01 - 0x03 | Switch Data  | Actual Switch Data                |      
+| 0x04        | Parity Check | Parity byte to check authenticity |    
+
+The above data is copied into HBIOS Configuration Block (HCB) at startup at 
+the loacation starting at CB_SWITCHES
+
+### Default Boot (NVSW_DEFBOOT) 
+
+16 bit Switch defining the default Rom application or Disk device to boot. 
+
+| Bit 15      | Bits 14-8         | Bits 7-0           |      
+|-------------|-------------------|--------------------|      
+| 1 = Rom App | -undefined-       | App to Boot (Char) |      
+| 0 = Disk    | Disk Unit (0-127) | Disk Slice (0-255) |      
+
+### Auto Boot (NVSW_AUTOBOOT)
+
+8 bit Switch defining if the system should auto boot at startup
+
+| Bits 7-6 | Bit 5                  | Bit 4    | Bits 3-0                             |     
+|----------|------------------------|----------|--------------------------------------|     
+| -unused- | 1 = Auto Boot Enabled  | -unused- | 0 = Immediate Boot with no delay     |     
+| -unused- | 1 = Auto Boot Enabled  | -unused- | (1-15) Timeout (seconds) before boot |     
+| -unused- | 0 = Auto Boot Disabled | -unused- | -undefined-                          |     
+
+### Status Reset (0xFF)
+
+The Status Reset switch is not a general purpose switch, it is a control mechanism
+to allow the global status of all switches to be determined. The meaning of the switch
+is different for Read (Get Status) and Write (Reset NVRAM)
+
+#### GET (Get Status)
+
+The read Get Status of switches. This returns very specific values from the function call.
+
+| Status                                       | A Register | Z / NZ Flag  |
+|----------------------------------------------|------------|--------------|
+| NVRAM does not exist                         | A=0        | NZ flag set  |
+| NVRAM exists, but has not been initialised   | A=1        | NZ flag set  |
+| NVRAM exists, and has been fully initialised | A='W'      | Z flag set   |
+
+#### SET (Reset NVRAM)
+
+Reset NVRAM to default values. This will wipe any existing data and set default
+values into NVRAM.
+
 # Driver Model
 
 The framework code for bank switching also allows hardware drivers to be
@@ -2611,6 +2682,27 @@ the caller can use interbank calls directly to the function in the
 driver which bypasses the overhead of the normal function invocation
 lookup.
 
+#### SYSGET Subfunction 0xC0 -- Get Switches (SWITCH)
+
+| **Entry Parameters** | **Returned Values** |
+|----------------------|---------------------|
+| B: 0xF8              | A: Status           |
+| C: 0xC0              | HL: Switch Value    |
+| D: Switch Key        |                     |
+
+This function will return the current value (HL) of the switch (D) from NVRAM. 
+
+Switches may be returned as a 16 bit (HL) or 8 bit (L) value. It is up to the caller 
+to process the returned value correctly. Note for Switch 0xFF (status) the returned value
+is primarily in the Status (A) register.
+
+Errors are signalled in the return by setting the NZ flag. When set the
+(A) register may contain an error code, but this code does not conform to RomWBW standard
+
+Success is indicated by setting the Z flag
+
+For a description of switches please see [RomWBW NVRAM Configuration]
+
 #### SYSGET Subfunction 0xD0 -- Get Timer Tick Count (TIMER)
 
 | **Entry Parameters**                   | **Returned Values**                    |
@@ -2783,6 +2875,27 @@ sub-function value. The following lists the subfunctions available along
 with the registers/information utilized.  The Status (A) is a standard 
 HBIOS result code.
 
+#### SYSSET Subfunction 0xC0 -- Set Switches (SWITCH)
+
+| **Entry Parameters** | **Returned Values** |
+|----------------------|---------------------|
+| B: 0xF9              | A: Status           |
+| C: 0xC0              |                     |
+| D: Switch Key        |                     |
+| HL: Switch Value     |                     |
+
+This function will set the value (HL) into the switch (D) and store it into NVRAM.
+
+Switches may be passed as a 16 bit (HL) or 8 bit (L) value. It is up to the caller
+to send the value correctly. Note for Switch 0xFF (reset) the value (HL) is ignored
+
+Errors are signalled in the return by setting the NZ flag. When set the
+(A) register may contain an error code, but this code does not conform to RomWBW standard
+
+Success is indicated by setting the Z flag
+
+For a description of switches please see [RomWBW NVRAM Configuration]
+
 #### SYSSET Subfunction 0xD0 -- Set Timer Tick Count (TIMER)
 
 | **Entry Parameters**                   | **Returned Values**                    |

Source/Doc/UserGuide.md

@@ -897,6 +897,50 @@ Boot [H=Help]: r
 Restarting System...
 ```
 
+### Setting NVRAM Options
+
+On systems with RTC devices (that have Non-Volatile RAM), RomWBW supports storing
+some limited configuration option options inside this NVRAM
+
+Several configuration options are currently supported, these are known as Switches
+
+* Specify Automatic boot at startup, after an optional delay (AB)
+* Define the Default Disk or ROM App to be booted at startup (DB)
+
+RomWBW uses bytes located at the start of RTC NVRAM, and includes a Parity check of 
+the bytes in NVRAM to check for authenticity before using the configuration.
+
+Initially NVRAM has to be reset (with default values), before it can be used.
+As well as setting defaults, it also writes the correct parity, and allows the
+NVRAM to be accessed and to store RomWBW config.
+
+This is an explicit step that must be done, as any existing data stored is overitten.
+If you are using NVRAM for other purposes then you can continue to do so
+so long as you do NOT perform this Reset step.
+
+NVRAM may also need to be reset in these circumstances
+
+* When there has been a loss of power to the NVRAM
+* When upgrading to a new RomWBW version, or a RomWBW version that has new switches
+* If the NVRAM has been overitten by another application.
+
+If you want to continue to use NVRAM in your applications you may want to consider storing
+your data above the RomWBW Switch data.
+
+The WIZNET class of Network devices also contain NVRAM, currently RomWBW does not support
+writing configuration to these devices.
+
+To configure these options an inbuilt ROM application is provided which can be accessed
+by the command "`W`" from the RomWBW boot menu.
+
+This application is also built as a CP/M utility, but is not included on an disk image, 
+it is found in the `Binary/Applications` folder of the RomWBW distribution
+
+For further guidance on using this application please see the section 
+"RomWBW System Configuration" in the RomWBW Applications document
+
+[RomWBW Applications]($doc_root$/RomWBW Applications.pdf)
+
 ### Changing Console and Console speed
 
 Your system can support a number of devices for the console. They may
@@ -4237,6 +4281,11 @@ ALIAS facility.
 p-System has its own startup command processing mechanism that is
 covered in the p-System documentation.
 
+## NVRAM Configuration
+
+See section [Setting NVRAM Options] for information about how to
+apply NVRAM configuration.
+
 ## ROM Customization
 
 The pre-built ROM images are configured for the basic capabilities of
@@ -4269,6 +4318,14 @@ Note that the ROM customization process does not apply to UNA. All
 UNA customization is performed within the ROM setup script that is
 built into the ROM.
 
+## ROM User Application
+
+The User App is provided as a way to access a custom written
+ROM application.  In the pre-built ROMs, selecting User App will just
+return to the Boot Loader menu.  If you are interested in creating a
+custom application to run instead, review the "usrrom.asm" file in the
+Source/HBIOS folder of the distribution.
+
 # UNA Hardware BIOS
 
 John Coffman has produced a new generation of hardware BIOS called
@@ -4678,7 +4735,8 @@ please let me know if I missed you!
   
 * Mark Pruden has also contributed a great deal of content to the
   Disk Catalog, User Guide as well as contributing the disk image
-  for the Z3PLUS operating system, and the COPYSL utility.
+  for the Z3PLUS operating system, the COPYSL utility, and also
+  implemented feature for RomWBW configuration by NVRAM.  
 
 * Jacques Pelletier has contributed the DS1501 RTC driver code.
 

Source/HBIOS/romldr.asm

@@ -2504,8 +2504,8 @@ ra_ent		.equ	12
 #defcont	.dw	p8
 ;
 ; Note: The formatting of the following is critical. TASM does not pass
-; macro arguments well. Ensure std.asm holds the definitions for *_LOC,
-; *_SIZ *_END and any code generated which does not include std.asm is
+; macro arguments well. Ensure LAYOUT.INC holds the definitions for *_LOC,
+; *_SIZ *_END and any code generated which does not include LAYOUT.INC is
 ; synced.
 ;
 ; Note: The loadable ROM images are placed in ROM banks BID_IMG0 and

Source/HBIOS/usrrom.asm

@@ -45,7 +45,7 @@ COLS	.EQU	8		; NUMBER OF PIXEL COLUMNS PER CHARACTER
 ;
 ; APPLICATION WILL WILL BE LOADED AT USR_LOC.  THEREFORE, THE CODE
 ; MUST "ORG" AT THIS ADDRESS.  TO CHANGE THE LOAD LOCATION OF THIS
-; CODE, YOU CAN UPDATE USR_LOC IN STD.ASM.
+; CODE, YOU CAN UPDATE USR_LOC IN LAYOUT.INC
 ;
 	.ORG	USR_LOC
 ;

Source/TastyBasic/src/romwbwio.asm

@@ -31,7 +31,7 @@ BF_SYSRES_WARM			.equ 01h			; warm start
 
 ;*************************************************************
 ;
-; THE FOLLOWING NEED MUST BE SYNCED WITH STD.ASM SO ROMLDR
+; THE FOLLOWING NEED MUST BE SYNCED WITH LAYOUT.INC SO ROMLDR
 ; KNOWS WHERE THIS EXECUTES AT
 ;
 ;*************************************************************