MirrorRepos/RomWBW
1
0
Fork 1
mirror of https://github.com/wwarthen/RomWBW.git synced 2026-02-06 14:11:48 -06:00
Code Issues Projects Releases Wiki Activity

Documenation changes for the NVRAM changes

Browse Source
This commit is contained in:
Mark Pruden
2024-11-29 09:06:51 +11:00
parent f6ef90fe14
commit 9713ca445c
14 changed files with 879 additions and 602 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Source/CBIOS/cbios.asm
View File

@@ -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
;

103
Source/Doc/Applications.md
View File

@@ -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

3
Source/Doc/ReadMe.md
View File

@@ -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.

113
Source/Doc/SystemGuide.md
View File

@@ -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** |

60
Source/Doc/UserGuide.md
View File

@@ -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.

4
Source/HBIOS/romldr.asm
View File

@@ -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

2
Source/HBIOS/usrrom.asm
View File

@@ -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
;

2
Source/TastyBasic/src/romwbwio.asm
View File

@@ -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
;
;*************************************************************