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

Merge branch 'master' into master

Browse Source
This commit is contained in:
Wayne Warthen
2024-12-01 15:26:39 -08:00
committed by GitHub
parent 925b2870eb b032694e01
commit f61d96bf93
36 changed files with 507 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
Source/Doc/Applications.md
View File

@@ -384,6 +384,112 @@ 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.
The $doc_user$ has additional information on the use of NVRAM to set your
system configuration.
### 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 dependent 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

@@ -518,6 +518,77 @@ port IDE interface drivers.
Platforms supporting this option currently are the MBC, Duodyne and
latter version of the SBC.
# Configuration
## RomWBW NVRAM Configuration
On systems with RTC devices (that have Non-Volatile 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 the HBIOS Configuration Block (HCB) at startup at
the location 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
@@ -2630,6 +2701,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** |
@@ -2802,6 +2894,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** |

105
Source/Doc/UserGuide.md
View File

@@ -897,7 +897,56 @@ Boot [H=Help]: r
Restarting System...
```
### Changing Console and Console speed
### 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.
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 $doc_apps$ document.
If your system has both a [Front Panel] as well as NVRAM, be aware that
the Front Panel switches take precedence over the NVRAM configuration
settings.
Note that the WizNet class of Network devices also contain NVRAM which is
entirely separate from the RomWBW configuration NVRAM described here. A
separate utility is used to set the WizNet NVRAM (see [CP/NET Client Setup]).
[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
be VDU type devices or serial devices. If you want to change which
@@ -2288,12 +2337,21 @@ survive re-imaging, you **must** follow these rules:
This section covers techniques to copy partial images onto pre-existing media,
in effect performing a selective slice copy. These techniques currently **only** apply to
hd1k formatted media, which has a convienient 1MB size metric.
However adapting to hd512 is possible.
hd1k formatted media, which has a convenient 1MB size metric.
However adapting to hd512 is possible, but left to the user.
On Linux/MacOS the `dd` command can be used to write data in a controlled manner.
The `dd` command supports options to define precisly souce
and destination offsets and sizes to copy.
Although Windows does not have a native `dd` command, there are multiple
options for installing it including [MSYS2](https://www.msys2.org/),
[CygWin](https://www.cygwin.com/),
and [dd for Windows](http://www.chrysocome.net/dd).
**WARNING**: The `dd` command is a low-level utility that writes
directly to raw disk sectors with almost no safety checks. It is very
easy to corrupt a disk if this tool is used incorrectly.
The `dd` command supports options to define precisely source
and destination offsets and sizes to copy.
From the documentation of `dd` the following options are important.
```
@@ -2365,6 +2423,27 @@ and 1 is the size of the partition table im megabytes.
Thus we are skipping 6 slices (in the combo image)
and writing to the 7th slice.
#### Example 3 : Copy image using partition
In the previous examples, the hard disk is addressed as a raw disk
device and we took steps to calculate the assumed start of the RomWBW
partition. However, as long as the hd1k format is in use, it is
also possible to just point `dd` directly to the partition itself.
To do this, you must first determine the name that your operating
system is using for the desired partition. Frequently, partitions
are named by simply adding a number after the name of the hard disk
device. For example, if the hard disk is /dev/sdg, the first
partition is frequently /dev/sdg1 or /dev/sdgp1.
Taking advantage of this, it is safer and easier to calculate the
offset of a slice within the partition. It is simply the slice
number \* 8MB. Example 2 above, could now be performed as:
```
Binary % sudo dd if=hd1k_games.img of=/dev/sdg1 seek=48 bs=1M
```
# Operating Systems
One of the primary goals of RomWBW is to expose a set of generic
@@ -4237,6 +4316,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 +4353,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 +4770,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.