Updating, building, and flashing RomWBW on an SC130 CP/M system
This article is one of my series
Adventures with RC2014, Z80, and CP/M.
It describes how to update, rebuild, and install the RomWBW firmware
in the EEPROM on an SC130 board -- using Linux as the build platform.
The process should be similar for other boards that use RomWBW,
particularly if -- like the SC130 -- they use a software-flashable
EEPROM. It's also similar on Windows and (I guess) other supported
platforms, but I'm only describing Linux. I don't have a hardware
EEPROM programmer, so I can't describe flashing the EEPROM that
way. I'll be using the CP/M flash utility that is
part of RomWBW.
RomWBW is the platform firmware for a number of Z80-based retro-style computers. It contains not only the CP/M BIOS, but also images of CP/M itself (and other operating systems), and a disk image containing system utilities. In most cases, RomWBW is used with 512 kB EEPROMs.
Note:
CAUTION getting any part of this process wrong could leave you with a brick. There are various tests that can be carried out to reduce the likelihood, but it cannot be entirely excluded. Before proceeding, I advise ensuring that you have a way to obtain a functioning replacement EEPROM.
Why do this?
A common reason to rebuild RomWBW is to change the contents of the system disk image -- to add new utilities, for example, or remove unused ones. In this example, I will be changing the floppy disk controller, which I will do by creating a new configuration file based on the standard one for the SC130.
Note:
Before making modifications to the ROM, it's perhaps worth running the build with an unmodified configuration, just to verify that the build and install processes are themselves working.
Obtaining the source
First obtain the RomWBW source. You can download and unpack it or, more easily, clone the repository on GitHub:
$ git clone https://github.com/wwarthen/RomWBW.git $ cd RomWBW
Using git this way is useful (if you understand
git) because you can record and, perhaps, back out
changes that you make to the source.
Modifying the configuration
During the build, you'll be prompted for platform information.
The prompts refer to configuration files in the directory
Source/HBIOS/CONFIG. My board is supported by
configuration files whose names begin SCZ180. I think
'SC' here is Stephen Cousins, the designer of the board, and Z180
is the CPU.
In the directory are files for specific boards of the same class:
SCZ180_sc130.asm, SCZ180_sc126.asm, etc.
For the SC130 board, I will make a copy of the file
SCZ180_sc130.asm, and call it SCZ180_sc130_kb.asm.
The name is not arbitrary -- it must begin with SCZ180_,
or the build process won't see it.
My configuration change amounts to setting the floppy disk driver in my newly-created configuration file, like this:
FDMODE .SET FDMODE_EPFDC
Of course, the specifics of the change are not important here.
Running the build
On Linux, I just do:
$ make clean; make
It takes a little while before we get to this prompt:
Enter platform [ DYNO MBC MK4 N8 RCZ180 RCZ280 RCZ80 RPH SBC SCZ180 UNA ZETA ZETA2 ] : SCZ180 Enter config for [ sc126 sc130 sc131 sc140 sc503 sc130_kb ] : sc130_kb
Note that one of the choices in the list corresponds to the new configuration file I created -- this is why the naming convention is important.
Testing the build
The outputs of the build process I am interested in are these two files:
$ ls -l Binary/*kb* -rw-rw-r--. 1 kevin kevin 40487 Jun 13 08:04 Binary/SCZ180_sc130_kb.com -rw-rw-r--. 1 kevin kevin 524288 Jun 13 08:04 Binary/SCZ180_sc130_kb.rom ...
The .rom file contains the new contents of the EEPROM. It is
exactly 512kB in size (this applies to nearly all the platforms that
RomWBW supports). The .com file is a CP/M program that
contains the executable part of the BIOS -- not the filesystem image and
platforms. The .com file is important because it allows
us to sanity-check the build before flashing the EEPROM.
To run the test, use whatever method you favour to copy the .com
file to the CP/M system. You'll have to choose a new, shorter name, because
CP/M uses 8.3 file naming. So I have copied the file to drive F, name
test.com.
B> f: F> test
This test runs the HBIOS ROM, but as if it were a CP/M program. It looks
as if the machine has rebooted, but you'll find that none of the
commands to run operating systems work (because they are not part
of the .com file). If the system actually has
rebooted, then that indicates a problem. So it helps if the change
you're making is one that is quite obvious.
In my case, I've changed the floppy disk driver to EPFDC, and I'm looking for confirmation of this in the 'boot' messages.
RomWBW HBIOS v3.2.1, 2023-06-13 ... MD: UNITS=2 ROMDISK=384KB RAMDISK=256KB FD: MODE=EPFDC IO=0x48 NOT PRESENT ...
So there is the change (and, in fact, the disk hardware is not installed at this point, so NOT PRESENT is expected). At this point we can have some confidence that the build succeeded, so now we can flash the EEPROM.
Flashing the ROM
The SC130 has a software-flashable EEPROM, supported by the
RomWBW flash utility. I understand that most boards that
support RomWBW are software-flashable.
Note:
The SC130, and some other boards, have hardware write-protect jumpers that might need to be adjusted.
Copy the .rom file from the build to a suitable (real or
simulated) hard disk on the CP/M system. Again, you'll have to
shorten the name. I have called it test.rom, on drive F.
Now simply use the flash utility to update the EEPROM:
f> b:flash write test.rom
This process takes a few minutes. Reset the system, and check the new BIOS.
Closing remarks
Building and flashing RomWBW is surprisingly straightforward on my
Linux system. It's worth keeping in mind, however, that it
could potentially break something. The flash utility
runs under CP/M so, as a minimum, the modified ROM has to be able
to boot CP/M, and have access to the flash utility
itself. I would not undertake the process without ensuring that you
have a way to recover, if it all goes horribly wrong.
