mirror of https://github.com/wwarthen/RomWBW.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
331 lines
12 KiB
331 lines
12 KiB
Building a Custom ROM
|
|
---------------------
|
|
|
|
At present, the build environment assumes you are running
|
|
a current version of Microsoft Windows (either 32-bit or
|
|
64-bit).
|
|
|
|
If you are using Linux, David Giles has contributed a Linux
|
|
makefile that should work for you. Please read the
|
|
LinuxBuild.txt file for more information.
|
|
|
|
All required tools are included in the distribution. You
|
|
should not need anything other than what comes as part of
|
|
Windows or as part of the distribution.
|
|
|
|
In summary, the process involves the 4 steps below:
|
|
|
|
1) Create/update configuration file
|
|
|
|
2) Update/Add/Delete any files you want incorporated in
|
|
the ROM Disk
|
|
|
|
3) Run the build script (or makefile if you prefer) and
|
|
confirm there are no errors.
|
|
|
|
4) Burn the resultant ROM image and try it.
|
|
|
|
The process is really very simple. In fact, you can
|
|
essentially skip steps 1 & 2 if yoiu want to try simply
|
|
building one of the existing configurations.
|
|
|
|
Each of the 4 steps above is described in more detail
|
|
below.
|
|
|
|
1. Create/Update Configuration File
|
|
-----------------------------------
|
|
|
|
The settings for a build are primarily controled by
|
|
a configuration file that is included in the build
|
|
process. In order to customize your settings, you
|
|
need to modify an existing configuration file or
|
|
create your own.
|
|
|
|
If you look in the Source directory, you will see
|
|
a series of files named config_xxxxxx.asm. Each of
|
|
them corresponds to one of the standard configurations
|
|
listed in the ROMList.txt file.
|
|
|
|
You have two choices. You can simply modify the existing
|
|
configuration file that is closest to your situation, or
|
|
you can copy it to a new config_xxxxx.asm file and modify
|
|
that. I recommend that you copy one to your own name so
|
|
that you will always have the unmodified standard configuration
|
|
files left in place. So, for example, you could just
|
|
copy config_zeta.asm to config_wayne.asm. You MUST
|
|
name your config file as congig_xxxxxx.asm. The xxxx's
|
|
can be whatever you want, but the rest must be exactly
|
|
as indicated.
|
|
|
|
The config files are simply text files with various
|
|
settings. Open your target config file with your
|
|
favorite text editor and modify the settings as desired.
|
|
|
|
Unfortunately, I have not yet documented each of the
|
|
settings in detail; that will be a separate document
|
|
provided in the future. However, there are comments
|
|
in the config file that will probably be sufficient
|
|
for the most part.
|
|
|
|
2. Update/Add/Delete ROM Disk 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 in your
|
|
ROM.
|
|
|
|
If you look at the RomDsk directory, you will see
|
|
a variety of subdirectories. These subdirectories
|
|
contain the files that will be included in the
|
|
ROM disk. The build process will determine
|
|
which subdirectories to include files from based
|
|
on the following rules:
|
|
|
|
First, all files from either std_512 or std_1024 will
|
|
be incuded depending on on the size of the ROM you
|
|
are building. If you are building a 512KB ROM, then
|
|
all the files from std_512KB will be included. If you
|
|
are building a 1MB ROM, then all the files from std_1024KB
|
|
will be included. Essentialy, the files in std_1204KB are
|
|
a superset of the ones in std_512KB because there is more
|
|
space available for the ROM drive.
|
|
|
|
Second, all files from the directory that corresponds to
|
|
your configuration file will be included. If you build
|
|
the "zeta" configuration, all files in cfg_zeta will
|
|
be added. Note that these files will be in addition
|
|
to the files from the std_XXXKB directory.
|
|
|
|
If you created your own config file (like config_wayne.asm
|
|
described above), you MUST create a subdirectory within
|
|
the RomDsk directory and populate it with the files
|
|
you want added. Normally, you would include the
|
|
files from the original standard config. So, if
|
|
you created config_wayne.asm from config_zeta.asm,
|
|
then you would create a subdirectory in RomDsk called
|
|
cfg_wayne and copy all the files from cfg_zeta to
|
|
cfg_wayne.
|
|
|
|
Finally, you will notice another subdirectory called
|
|
RomApps. This is directory is used to place a set of
|
|
RomWBW apps provided by Douglas Goodall. The driectory
|
|
will be populated automatically and the files will be
|
|
included automatically.
|
|
|
|
3. Run the Build Process
|
|
------------------------
|
|
|
|
NOTE: The process described here is the more commonly
|
|
used build script. If you wish to use a makefile
|
|
instead, refer to the comments in the makefile in
|
|
the Source directory as an alternative to the
|
|
process described here.
|
|
|
|
The build involves running a command at the command
|
|
prompt. From a Command Prompt window, you will need
|
|
to change to the high level directory for the build.
|
|
Normally, you would be changing to the RomWBW directory
|
|
unless you renamed it.
|
|
|
|
To run the build and be prompted for required information,
|
|
just enter "Build". You will be prompted for the information
|
|
described below and the build should run. If an error is
|
|
encountered, the build should stop and display an error
|
|
in red text.
|
|
|
|
If you immediately receive the error "the execution of
|
|
scripts is disabled on this system", then you will need to
|
|
change the PowerShell Execution-Polcy to "Unrestricted".
|
|
To do this, you need to right-click on FixPowerShell.cmd and
|
|
choose "Run as Administrator" to make the change. If is
|
|
critical that you right-click and use "Run as Administrator"
|
|
or the change will not work (you will get an error
|
|
indicating "Access to the registry denied" if you fail to
|
|
use "Run as Administrator".
|
|
|
|
The build script will prompt you for the following information
|
|
which you will need to provide (don't worry, it is simple):
|
|
|
|
Configuration:
|
|
|
|
Respond with the name of the configuration you wish to build.
|
|
A list of all available configurations is displayed for your
|
|
convenience. For example, if you are buidling the provided
|
|
zeta configuration, just enter "zeta". If you have created a
|
|
custom configuration as described above, you would enter
|
|
"wayne".
|
|
|
|
ROM Size [512|1024]:
|
|
|
|
Respond with either "512" for a 512KB ROM build or "1024" for a
|
|
1MB ROM build. Only the two choices are possible at this time.
|
|
It is important that you choose a ROM size that is no larger than
|
|
the szie of the ROM you will ultimately be burning. This is
|
|
dependant on your hardware.
|
|
|
|
CPU Type Z[80|180]:
|
|
|
|
Respond with "80" if the ROM is for Z80 hardware such as the
|
|
N8VEM Z80 SBC or for Zeta. Respond with "180" if the ROM is
|
|
for Z180 based hardware such as the N8.
|
|
|
|
System [CPM|ZSYS]:
|
|
|
|
Respond with the type of system you wish to create. If you are
|
|
not sure which you want, you should enter "CPM". Refer to the
|
|
ReadMe.txt file for more informatino on the difference between
|
|
the two system types.
|
|
|
|
At this point the build should run and you will see output related
|
|
to the assembler runs and somem utility invocations. Just review
|
|
the output for any obvioius errors. Normally, all errors will
|
|
cause the build to stop immediately and display an error message
|
|
in red.
|
|
|
|
You will see from lines in the output indicating the amount of
|
|
space variouis 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:
|
|
|
|
DATA space remaining: 39 bytes.
|
|
BOOT LOADER space remaining: 3503 bytes.
|
|
CBIOS space remaining: 161 bytes.
|
|
DBGMON space remaining: 860 bytes.
|
|
ROMX space remaining: 8191 bytes.
|
|
BOOT LOADER space remaining: 3503 bytes.
|
|
|
|
4. Deploy the ROM
|
|
-----------------
|
|
|
|
If you look in the Output directory. You should find the following files:
|
|
|
|
<config>.rom - binary ROM image to burn to EEPROM
|
|
<config>.sys - system image that can be written to the start of a
|
|
disk to enable boot from disk functionality
|
|
<config>.com - executable version of the system image that can be
|
|
copied via xmodem to a running system to test
|
|
the build.
|
|
|
|
The actual ROM image is the file ending in .rom. It should be exactly
|
|
512KB or 1MB depending on the ROM size you chose. Simply burn the .rom
|
|
image to your ROM and install it in your hardware.
|
|
|
|
Specifying Build Options on Command Line
|
|
----------------------------------------
|
|
|
|
If you don't want to be prompted for the options to the "Build"
|
|
command, you can specify the options right on the command line.
|
|
|
|
For example:
|
|
|
|
Build zeta 512 80 CPM
|
|
|
|
In this case, you will not be prompted. This is useful if you
|
|
wish to automate your build process.
|
|
|
|
Example Build Run
|
|
-----------------
|
|
|
|
C:\Users\WWarthen\N8VEM\Build\RomWBW>build
|
|
Configurations available:
|
|
> n8
|
|
> n8vem
|
|
> n8vem_dide
|
|
> n8vem_diskio
|
|
> n8vem_diskio3
|
|
> n8vem_ppide
|
|
> n8vem_vdu
|
|
> n8vem_vdux
|
|
> simh
|
|
> zeta
|
|
Configuration: zeta
|
|
ROM Size [512|1024]: 512
|
|
CPU Type Z[80|180]: 80
|
|
System [CPM|ZSYS]: CPM
|
|
|
|
Building zeta: 512KB ROM configuration zeta for Z80...
|
|
|
|
tasm -t80 -b -g3 -fFF ccpb03.asm cp.bin
|
|
TASM Z80 Assembler. Version 3.2 September, 2001.
|
|
Copyright (C) 2001 Squak Valley Software
|
|
tasm: pass 1 complete.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -b -g3 -fFF bdosb01.asm dos.bin
|
|
TASM Z80 Assembler. Version 3.2 September, 2001.
|
|
Copyright (C) 2001 Squak Valley Software
|
|
tasm: pass 1 complete.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -b -g3 -fFF -dBLD_SYS=SYS_CPM data.asm data.bin
|
|
TASM Z80 Assembler. Version 3.2 September, 2001.
|
|
Copyright (C) 2001 Squak Valley Software
|
|
tasm: pass 1 complete.
|
|
Configuration: ZETA Z80 SBC, FLOPPY (AUTOSIZE), PPIDE
|
|
UTIL_DATA occupies 16 bytes.
|
|
FD_DATA occupies 427 bytes.
|
|
PPIDE_DATA occupies 584 bytes.
|
|
DATA space remaining: 23 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -b -g3 -fFF -dBLD_SYS=SYS_CPM cbios.asm cbios.bin
|
|
TASM Z80 Assembler. Version 3.2 September, 2001.
|
|
Copyright (C) 2001 Squak Valley Software
|
|
tasm: pass 1 complete.
|
|
Configuration: ZETA Z80 SBC, FLOPPY (AUTOSIZE), PPIDE
|
|
CNFGDATA occupies 69 bytes.
|
|
DSKMAP occupies 6 bytes.
|
|
UART occupies 77 bytes.
|
|
FD occupies 1991 bytes.
|
|
PPIDE occupies 832 bytes.
|
|
UTIL occupies 381 bytes.
|
|
CBIOS space remaining: 165 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -b -g3 -fFF dbgmon.asm dbgmon.bin
|
|
TASM Z80 Assembler. Version 3.2 September, 2001.
|
|
Copyright (C) 2001 Squak Valley Software
|
|
tasm: pass 1 complete.
|
|
Configuration: ZETA Z80 SBC, FLOPPY (AUTOSIZE), PPIDE
|
|
DBGMON space remaining: 831 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -b -g3 -fFF bloader.asm bloader.bin
|
|
TASM Z80 Assembler. Version 3.2 September, 2001.
|
|
Copyright (C) 2001 Squak Valley Software
|
|
tasm: pass 1 complete.
|
|
Configuration: ZETA Z80 SBC, FLOPPY (AUTOSIZE), PPIDE
|
|
BOOT LOADER space remaining: 3522 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -b -g3 -fFF romx.asm romx.bin
|
|
TASM Z80 Assembler. Version 3.2 September, 2001.
|
|
Copyright (C) 2001 Squak Valley Software
|
|
tasm: pass 1 complete.
|
|
Configuration: ZETA Z80 SBC, FLOPPY (AUTOSIZE), PPIDE
|
|
ROMX space remaining: 8191 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -b -g3 -fFF prefix.asm prefix.bin
|
|
TASM Z80 Assembler. Version 3.2 September, 2001.
|
|
Copyright (C) 2001 Squak Valley Software
|
|
tasm: pass 1 complete.
|
|
Configuration: ZETA Z80 SBC, FLOPPY (AUTOSIZE), PPIDE
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -b -g3 -fFF loader.asm loader.bin
|
|
TASM Z80 Assembler. Version 3.2 September, 2001.
|
|
Copyright (C) 2001 Squak Valley Software
|
|
tasm: pass 1 complete.
|
|
Configuration: ZETA Z80 SBC, FLOPPY (AUTOSIZE), PPIDE
|
|
BOOT LOADER space remaining: 3522 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
Building zeta output files...
|
|
Building 512KB zeta ROM disk data file...
|
|
|
|
C:\Users\WWarthen\N8VEM\Build\RomWBW>
|