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

Some other errors and ommission in Documentation.

Browse Source
This commit is contained in:
Mark Pruden
2025-02-13 11:03:51 +11:00
parent 858d680371
commit 30866ccbae
2 changed files with 132 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
Source/Doc/UserGuide.md
View File

@@ -1772,6 +1772,7 @@ The following table shows the disk images available.
| xxx_qpm.img | QPM Operating System | Yes |
| xxx_tpascal.img | Borland Turbo Pascal Compiler | No |
| xxx_ws4.img | WordStar v4 & ZDE Applications | No |
| xxx_z3plus.img | Z3 PLUS ZCPR 3.4 Operating System | Yes |
| xxx_z80asm.img | Relocating macro assembler for CP/M | No |
| xxx_zpm3.img | ZPM3 Operating System | Yes |
| xxx_zsdos.img | ZCPR-DJ & ZSDOS 1.1 Operating System | Yes |
@@ -2277,6 +2278,10 @@ call "CPM.SYS". For example:
`SYSCOPY C:=B:CPM.SYS`
Note: While the CP/M manual refers to the use of SYSGEN under RomWBW, it
is recommended that you use SYSCOPY as it is more flexible. SYSGEN is
included for completeness.
#### Character Device Mapping
Character device mapping under CP/M 2.2 has 3 layers:
@@ -2378,6 +2383,11 @@ as available.
* Z-System applications will not run under CP/M 2.2. For example,
the `LDDS` date stamper will not work.
* CP/M 2.2 was not distributed with a help system. Douglas Miller
has adapted the CP/M 3 help system for CP/M 2.2 and is included.
The HELP.HLP data file must be found on the current default drive
and user area when HELP.COM is run.
## Z-System
Z-System is the most popular non-DRI CP/M workalike "clone" which is generally
@@ -2478,6 +2488,9 @@ Manual.pdf" document in order to use this operating system effectively.
* [Z-System Users Guide]($doc_root$/CPM/Z-System Users Guide.pdf)
* [ZCPR3.3 User Guide]($doc_root$/CPM/ZCPR3.3 User Guide.pdf)
* Additionally, please review the file called RELEASE.NOT (U14) on the
disk which contains a variety of updates regarding the NZ-COM distribution.
#### Boot Disk
Since NZ-COM boots via Z-System, you can make a bootable
@@ -2641,6 +2654,9 @@ document in order to use this operating system effectively.
* [Z-System Users Guide]($doc_root$/CPM/Z-System Users Guide.pdf)
* [ZCPR3.3 User Guide]($doc_root$/CPM/ZCPR3.3 User Guide.pdf)
* Additionally, please review the file called RELEASE.NOT (U14) on the
disk which contains a variety of updates regarding the Z3PLUS distribution.
#### Boot Disk
Since Z3PLUS boots via CP/M 3, you first must make the disk CP/M 3
@@ -2663,7 +2679,7 @@ The CP/M 3 `DEVICE` command is used to manipulate the device mappings.
apply to Z3PLUS.
* Some applications in the Z3PLUS distribution have been upgraded
with newer versions. This is done with in
with newer versions.
## ZPM3
@@ -3021,6 +3037,32 @@ To boot into Fuzix:
You may now use Fuzix as desired. The general operation and use of
Fuzix is outside of the scope of this document.
## DOS 65
This disk is one of several ready-to-run disks provided with RomWBW.
It contains the files to start and run DOS/65 on an MBC system that
contains Dan Werner's 6502 processor. The contents of this disk are
purely a redistribution of the work of Dan Werner
WARNING: This is a work in progress. Use of this disk image requires
specific hardware and configuration. You should contact Dan Werner
before attempting to use this disk image.
### Usage ###
- The disk is configured to boot under ZSDOS 1.1 (via primary Z80
CPU). Once booted, you can launch DOS/65 on a secondary 6502
CPU using the "DOS65" command.
### Notes ###
- DOS/65 is generally compatible with the CP/M 2.2 filesystem. Once
launched, you will have access to the fielsystem of the boot disk.
- DOS/65 does not utilize any of the RomWBW framework or drivers, so
it will only support devices built into DOS/65 itself. Once
launched DOS/65 takes over the hardware completely.
# Custom Applications
The operation of the RomWBW hosted operating systems is enhanced through

175
Source/ReadMe.txt
View File

@@ -8,12 +8,12 @@
This directory is the root directory of the source tree for RomWBW.
This document describes the process to build a customized version
of the RomWBW firmware. RomWBW was explicitly organized in a way
This document describes the process to build a customized version
of the RomWBW firmware. RomWBW was explicitly organized in a way
that makes it very easy to rebuild the firmware.
Significant customization can be achieved with a custom built
firmware using simple option configuration files. You can
Significant customization can be achieved with a custom built
firmware using simple option configuration files. You can
customize your firmware to:
- Include support for add-on support boards such as
@@ -21,12 +21,12 @@ customize your firmware to:
- Modify operational parameters such as serial port
speed or wait state insertion.
- Add or remove programs or files contained on the disk images.
Virtually all source code is provided including the operating
systems themselves, so advanced users can easily modify any of
the software.
A cross-platform approach is used to build the RomWBW firmware.
A cross-platform approach is used to build the RomWBW firmware.
The software is built using a modern Windows, Linux, or Mac
computer, then the resulting firmware image is programmed into
the ROM of your RetroBrew Computer CPU board.
@@ -36,26 +36,26 @@ Windows Build System Requirements
For Microsoft Windows computers, all that is required to build the
firmware is the RomWBW distribution zip archive file. The zip
archive package includes all of the required source code
(including the operating systems) and the programs required to run
archive package includes all of the required source code
(including the operating systems) and the programs required to run
the build.
The build process is run via some simple scripts that automate the
process. These scripts utilize both batch command files as well as
Windows PowerShell. Windows 7 or greater is recommended. If you want
to use Windows Vista or XP, you will need to first install PowerShell
which available for free from Microsoft. Either 32 or 64 bit versions
of Microsoft Windows are fine. No additional programs need to be
The build process is run via some simple scripts that automate the
process. These scripts utilize both batch command files as well as
Windows PowerShell. Windows 7 or greater is recommended. If you want
to use Windows Vista or XP, you will need to first install PowerShell
which available for free from Microsoft. Either 32 or 64 bit versions
of Microsoft Windows are fine. No additional programs need to be
installed to run the build.
You may find that you get messages such as this during the Windows
build process:
Security warning
Run only scripts that you trust. While scripts from the internet can be
useful, this script can potentially harm your computer. If you trust
this script, use the Unblock-File cmdlet to allow the script to run
without this warning message. Do you want to run
Run only scripts that you trust. While scripts from the internet can be
useful, this script can potentially harm your computer. If you trust
this script, use the Unblock-File cmdlet to allow the script to run
without this warning message. Do you want to run
C:\Temp\RomWBW-v3.5.0-dev.67-Package\Source\Images\BuildDisk.ps1?
[D] Do not run [R] Run once [S] Suspend [?] Help (default is "D"):
@@ -75,7 +75,7 @@ before removing the file block protection.
Linux Build System Requirements
-------------------------------
You must have some standard system tools and libraries
You must have some standard system tools and libraries
installed, specifically: gcc, gnu make, libncurses, and srecord.
Typically, something like this will take care of adding all
required packages in Linux:
@@ -94,9 +94,9 @@ build process:
brew install srecord
You may encounter a failure reading or writing files. This is caused by
protection features in MacOS (at least, in Catalina) that prevent
programs built on your local system (unsigned) from running. To
You may encounter a failure reading or writing files. This is caused by
protection features in MacOS (at least, in Catalina) that prevent
programs built on your local system (unsigned) from running. To
disable this feature:
1) Make sure you exit System Preferences.
@@ -126,12 +126,12 @@ The basic steps to create a custom ROM are:
4) Program the resultant ROM image and/or write thedisk images.
Note that steps 1 and 2 are performed to customize your ROM as
desired. If you want to simply build a standard configuration, it is
*not* necessary to perform steps 1 or 2 before running a build. In
fact, I strongly recommend that you skip steps 1 and 2 initially and
just perform perform steps 3 and 4 using the standard configuration to
make sure that you have no issues building and programming a ROM that
Note that steps 1 and 2 are performed to customize your ROM as
desired. If you want to simply build a standard configuration, it is
*not* necessary to perform steps 1 or 2 before running a build. In
fact, I strongly recommend that you skip steps 1 and 2 initially and
just perform perform steps 3 and 4 using the standard configuration to
make sure that you have no issues building and programming a ROM that
works the same as a pre-built ROM.
Each of the 4 steps above is described in more detail below.
@@ -139,7 +139,7 @@ Each of the 4 steps above is described in more detail below.
1. Create/Update Configuration File
-----------------------------------
The options for a build are primarily controlled by a configuration
The options for a build are primarily controlled by a configuration
file that is included in the build process.
RomWBW uses cascading configuration files as indicated below:
@@ -157,11 +157,11 @@ configuration settings. Each file below the master configuration file
inherits the cumulative settings of the files above it and may
override these settings as desired.
Other than the top master file, each file must "#INCLUDE" its parent
file. The top two files should not be modified. To customize your
build settings you should modify the default build settings
(config/<platform>_std.asm) or preferably create an optional custom
user settings file that includes the default build settings file (see
Other than the top master file, each file must "#INCLUDE" its parent
file. The top two files should not be modified. To customize your
build settings you should modify the default build settings
(config/<platform>_std.asm) or preferably create an optional custom
user settings file that includes the default build settings file (see
example Config/SBC_user.asm).
By creating a custom user settings file, you are less likely to be
@@ -174,7 +174,7 @@ systems supported. Configuration refers to the settings that
customize the build. The configuration is modifies the platform
defaults as desired.
The platform names are predefined. Refer to the following table
The platform names are predefined. Refer to the following table
to determine the <plt> component of the configuration filename:
SBC Z80 SBC (v1 or v2) w/ ECB interface
@@ -201,17 +201,17 @@ to determine the <plt> component of the configuration filename:
NABU NABU w/ Les Bird's RomWBW Option Board
FZ80 S100 Computers FPGA Z80
Configuration files are found in the Source\HBIOS\Config
directory. If you look in the this directory, you will see a
Configuration files are found in the Source\HBIOS\Config
directory. If you look in the this directory, you will see a
series of files named <plt>_<cfg>.asm. By convention, all
configuration files start with the platform identifier followed
by an underscore. You will see later that the build process does
require this naming convention and it allows you to easily see which
configuration files apply to each of the platforms supported.
Each of the possible platforms has at least one configuration file. In
many cases, there will be a standard ("std") configuration for the
platform. For example, there is a file called MK4_std.asm. This is
Each of the possible platforms has at least one configuration file. In
many cases, there will be a standard ("std") configuration for the
platform. For example, there is a file called MK4_std.asm. This is
the standard ("std") configuration for a Mark IV CPU board.
The <cfg> portion of the filename can be anything desired. To create
@@ -248,8 +248,8 @@ This is because ".EQU" defines the initial value for a variable and
".SET" modifies a pre-existing value. You *must* use ".EQU" and ".SET"
correctly or the assembler will complain very loudly.
In our example, let's say you have added a DiskIO V3 board to your
Mark IV system and want to include floppy support. You will see a
In our example, let's say you have added a DiskIO V3 board to your
Mark IV system and want to include floppy support. You will see a
couple lines similar to these in the config file:
FDENABLE .SET TRUE ; FD: ENABLE FLOPPY DISK DRIVER (FD.ASM)
@@ -261,18 +261,18 @@ just modify the line to read:
FDMODE .SET FDMODE_DIO3 ; FD: DRIVER MODE: FDMODE_[DIO|ZETA|ZETA2|DIDE|N8|DIO3|RCSMC|RCWDC|DYNO|EPWDC]
You are now probably wondering where to find detailed instructions for
each of the configuration settings. Sadly, this is an area where
RomWBW is very deficient. The changes to hardware support happen so
fast that is have been virtually impossible to create such a document.
If it is not obvious what you need to do when looking at the build
configuration file, I recommend that you look at the platform
configuration file in the parent directory. It will contain all of the
possible settings and their default values as well as a brief comment.
In many cases this is enough information to figure out what to do. If
not, you will need to either look at the HBIOS source code or request
help in any of the RomWBW support communities (people are typically
very helpful). You can also post questions or issues on the GitHub
You are now probably wondering where to find detailed instructions for
each of the configuration settings. Sadly, this is an area where
RomWBW is very deficient. The changes to hardware support happen so
fast that is have been virtually impossible to create such a document.
If it is not obvious what you need to do when looking at the build
configuration file, I recommend that you look at the platform
configuration file in the parent directory. It will contain all of the
possible settings and their default values as well as a brief comment.
In many cases this is enough information to figure out what to do. If
not, you will need to either look at the HBIOS source code or request
help in any of the RomWBW support communities (people are typically
very helpful). You can also post questions or issues on the GitHub
repository.
2. Update/Add/Delete Disk Files
@@ -281,29 +281,32 @@ repository.
A major part of the RomWBW build process is the creation of the
ROM disk contents and the floppy/hard disk image files.
The files that are included on the ROM Disk of your ROM are copied
from a set of directories during the build process. This allows
you to have complete flexibility over the files you want included
The files that are included on the ROM Disk of your ROM are copied
from a set of directories during the build process. This allows
you to have complete flexibility over the files you want included
in your ROM.
The ROM disk process starts in the Source/RomDsk directory. Within
that directory, there are subdirectories for each of the different
possible ROM sizes that can be created. The vast majority of all
ROMs are 512KB, so you will probably be interested primarily in the
ROM_512KB subdirectory.
possible ROM disk sizes that can be created.
These subdirectories are already populated in the distribution. You do
not need to do anything unless you want to change the files that are
A ROM disk will occupy 128KB less than the physical size of ROM chip
itself, as 128KB is used for the ROMWBW firmware, software,
and boot images. Since the vast majority of all ROMs are 512KB, you will
probably be interested primarily in the ROM_384KB subdirectory.
These subdirectories are already populated in the distribution. You do
not need to do anything unless you want to change the files that are
included on your ROM Disk.
In summary, the ROM Disk embedded in the ROM firmware you build,
will include the files from the ROM_512KB directory (or the
ROM_1024KB directory if building a 1024KB firmware, etc.).
In summary, the ROM Disk embedded in the ROM firmware you build,
will include the files from the ROM_384KB directory for a 512KB ROM,
or a different sub directory depending on the size of the actual ROM.
There is a ReadMe.txt document in the \Source\RomDsk directory
There is a ReadMe.txt document in the \Source\RomDsk directory
with a more detailed description of this process.
Note that the standard 512K ROM disk is almost full. So, if
Note that the standard 384KB ROM disk is almost full. So, if
you want to add files to it, you will need to delete other files
to free up some space.
@@ -353,20 +356,20 @@ id:
> cust
Configuration:
Enter one of the configuration options to build a ROM with the
Enter one of the configuration options to build a ROM with the
associated config file.
At this point, the build should continue and you will see output
related to the assembler runs and some utility invocations. Just
review the output for any obvious errors. Normally, all errors
will cause the build to stop immediately and display an error
At this point, the build should continue and you will see output
related to the assembler runs and some utility invocations. Just
review the output for any obvious errors. Normally, all errors
will cause the build to stop immediately and display an error
message in red.
You will see some lines in the output indicating the amount of
space various components have taken. You should check these to
make sure you do not see any negative numbers which would indicate
that you have included too many features/drivers for the available
memory space. Here are examples of the lines showing the space
You will see some lines in the output indicating the amount of
space various components have taken. You should check these to
make sure you do not see any negative numbers which would indicate
that you have included too many features/drivers for the available
memory space. Here are examples of the lines showing the space
used:
HBIOS PROXY STACK space: 38 bytes.
@@ -380,9 +383,9 @@ used:
HBIOS space remaining: 21434 bytes.
At the completion of the build process, you will find the resultant
ROM and disk image files in the Binary directory.
ROM and disk image files in the Binary directory.
There will be many disk image (".img") files created. These are
There will be many disk image (".img") files created. These are
described in the RomWBW User Guide document. Since RomWBW
encapsulates all hardware interface code in the ROM itself, the
disk image files are generic for all ROMs. The only reason they
@@ -392,7 +395,7 @@ made.
4. Deploy the ROM
-----------------
Upon completion of a successful build, you should find the
Upon completion of a successful build, you should find the
resulting firmware in the Binary directory. The ROM file
will be called <plt>_<cfg>.rom matching the platform identifier
and configuration you chose.
@@ -408,17 +411,17 @@ Three output files will be created for a single build:
only the "code" portion of your ROM
and not modify the ROM disk
The actual ROM image is the file ending in .rom. It will normally be
512KB. Simply burn the .rom image to your ROM and install
it in your hardware. The process for programming your ROM depends
on your hardware, but the .rom file is in a pure binary format (it
The actual ROM image is the file ending in .rom. It will normally be
512KB. Simply burn the .rom image to your ROM and install
it in your hardware. The process for programming your ROM depends
on your hardware, but the .rom file is in a pure binary format (it
is not hex encoded).
You can alternatively reprogram your ROM in-situ (most hardware
supports this) using the FLASH application included with RomWBW. This
is described in the "Upgrading" section of the RomWBW User Guide.
Refer to the document ReadMe.txt in the Binary directory for more
Refer to the document ReadMe.txt in the Binary directory for more
information on the other two file extensions created.
Specifying Build Options on Command Line
@@ -437,7 +440,7 @@ Under Linux or MacOS, you can do the same thing like this:
make ROM_PLATFORM=MK4 ROM_CONFIG=cust
In this case, you will not be prompted. This is useful if you wish
In this case, you will not be prompted. This is useful if you wish
to automate your build process.
In the past, the size of the ROM could be specified as the third