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.
350 lines
13 KiB
350 lines
13 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). Additionally, you will need Microsoft PowerShell.
|
|
PowerShell is included in all distributions of Microsoft
|
|
Windows starting with Vista. It is available as a free
|
|
download for Windows XP from Microsoft
|
|
|
|
Other than PowerShell, 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. You must
|
|
configure PowerShell prior to these steps, but this only needs
|
|
to be done once.
|
|
|
|
The basic steps to create a custom ROM are:
|
|
|
|
1) Create/update configuration file
|
|
|
|
2) Update/Add/Delete any files you want incorporated in
|
|
the ROM Disk
|
|
|
|
3) Run the build scripts and
|
|
confirm there are no errors.
|
|
|
|
4) Burn the resultant ROM image and try it.
|
|
|
|
I strongly recommend that you initially SKIP steps
|
|
1 & 2. Just try steps 3 & 4 to make sure you are
|
|
able to build a ROM and test it in your hardware.
|
|
|
|
Each of the 4 steps above is described in more detail
|
|
below.
|
|
|
|
Acquiring the Distribution
|
|
--------------------------
|
|
|
|
Preparing PowerShell
|
|
--------------------
|
|
|
|
|
|
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.
|
|
|
|
Configuration files are found in the Source\BIOS\Config
|
|
directory. If you look in the this directory, you will see
|
|
a series of files named XXXX_yyyy.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 XXXX_yyyy.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 ZETA_std.asm to ZETA_wayne.asm. You MUST
|
|
name your config file as XXXX_yyyy.asm. The XXXX portion
|
|
must match your platform (N8VEM, ZETA, ZETA2, N8, UNA).
|
|
The yyyy portion can be whatever you want.
|
|
|
|
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 ROM_512KB or ROM_1024KB will
|
|
be included depending on on the size of the ROM you
|
|
are building. If you are building a 512KB ROM, then
|
|
all the files from ROM_512KB will be included. If you
|
|
are building a 1MB ROM, then all the files from ROM_1024KB
|
|
will be included. Essentialy, the files in ROM_1204KB are
|
|
a superset of the ones in ROM_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_std" configuration, all files in ZETA_std will
|
|
be added. Note that these files will be in addition
|
|
to the files from the ROM_XXXKB directory.
|
|
|
|
If you created your own config file (like ZETA_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 ZETA_wayne.asm from ZETA_std.asm,
|
|
then you would create a subdirectory in RomDsk called
|
|
ZETA_wayne and copy all the files from ZETA_std to
|
|
ZETA_wayne.
|
|
|
|
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 commands 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.
|
|
|
|
First, you will need to build the components that are
|
|
common to all configurations. These components do not
|
|
require any configuration. To build these, use the
|
|
following command and ensure it completes
|
|
without error:
|
|
|
|
BuildCommon
|
|
|
|
To run the configuration specific 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 "RemoteSigned".
|
|
To do this, you need to right-click on FixPowerShell.cmd and
|
|
choose "Run as Administrator" to make the change. It 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):
|
|
|
|
Platform:
|
|
|
|
Respond with the name of the platform that you are targeting.
|
|
It must be one of N8VEM, ZETA, ZETA2, N8, or UNA.
|
|
|
|
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 building the provided
|
|
ZETA_std configuration, just enter "std". 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 size of the ROM you will ultimately be burning. This is
|
|
dependant on your hardware.
|
|
|
|
At this point, the build should run and you will see output related
|
|
to the assembler runs and some 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 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:
|
|
|
|
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>.com - executable version of the system image that can be
|
|
copied via xmodem to a running system to test
|
|
the build.
|
|
<config>.img - system image that can be written to an SD/CF Card
|
|
and loaded via the UNA FS FAT loader.
|
|
|
|
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 std 512
|
|
|
|
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\Projects\N8VEM\Build\RomWBW>Build.cmd
|
|
Platform [N8VEM|ZETA|N8|UNA|S100]: ZETA
|
|
Configurations available:
|
|
> ppp
|
|
> std
|
|
Configuration: std
|
|
ROM Size [512|1024]: 512
|
|
|
|
Building ZETA_std: 512KB ROM configuration std for Z80...
|
|
|
|
tasm -t80 -g3 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 -g3 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 -g3 syscfg.asm syscfg.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 (STD)
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -g3 -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 (STD)
|
|
INFOLIST occupies 18 bytes.
|
|
UTIL occupies 484 bytes.
|
|
FD_DATA occupies 340 bytes.
|
|
PPIDE_DATA occupies 1116 bytes.
|
|
CBIOS space remaining: 2092 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -g3 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 (STD)
|
|
DBGMON space remaining: 795 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -g3 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 (STD)
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -g3 bootrom.asm bootrom.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 (STD)
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -g3 bootapp.asm bootapp.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 (STD)
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -g3 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 (STD)
|
|
LOADER space remaining: 1205 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -g3 pgzero.asm pgzero.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 -g3 hbios.asm hbios.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 (STD)
|
|
UART occupies 146 bytes.
|
|
FD occupies 2071 bytes.
|
|
PPIDE occupies 809 bytes.
|
|
HBIOS space remaining: 24428 bytes.
|
|
STACK space remaining: 145 bytes.
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -g3 hbfill.asm hbfill.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 (STD)
|
|
tasm: pass 2 complete.
|
|
tasm: Number of errors = 0
|
|
tasm -t80 -g3 romfill.asm romfill.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
|
|
Building ZETA_std output files...
|
|
Building 512KB ZETA_std ROM disk data file...
|
|
|
|
C:\Users\WWarthen\Projects\N8VEM\Build\RomWBW>
|