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.