Rom Filing System — Technical Guide

RFS Technical Guide

This guide documents the Rom Filing System hardware integration, memory architecture, software module layout, SD Card Filing System design, CP/M implementation, and the complete build system. It is intended for users who want to understand how RFS works at a system level, port RFS to new hardware, or perform a full build from source.

For day-to-day usage and monitor command reference see the User Manual. For Z80 assembly source code walkthroughs see the Developer's Guide.

Hardware Platforms

RFS targets four hardware platforms. Each is selected at compile time via a flag in asm/include/rfs_definitions.asm. The resulting binary images differ in bank layout, feature set, and the ROM addresses used.

RomDisk Card

The original and most capable RFS target. The RomDisk PCB plugs into the Sharp MZ-80A expansion slot and provides:

Up to 4 × 512 KB SST39SF040 Flash RAMs — replaces the Monitor ROM and provides three User ROM chips, giving up to 2 MB of Flash-based ROM storage.

512 KB Static RAM — available as additional paged workspace (future use).

SDXC card reader with hardware SPI interface (v2+ boards) or software bit-bang SPI (v1 boards, using the printer parallel port).

A coded latch (v2.0+ boards) that protects the bank control registers — the latch only opens after a fixed sequence of reads to the upper 8 bytes of the User ROM address range (0xEFF8–0xEFFF), preventing accidental bank switches during normal operation.

The Monitor ROM chip (at 0x0000–0x0FFF on the MZ-80A) is replaced by a paged Flash RAM socket-adapted to appear as a 4 KB window into the full 512 KB chip. Similarly the User ROM (at 0xE800–0xEFFF) is replaced by a paged 2 KB window.

SFD-700 Floppy Interface

The SFD-700 mkII floppy disk interface card includes a 512 KB Flash ROM. RFS occupies pages of this Flash ROM alongside the floppy AFI boot code:

0x00000–0x00FFF — MZ-80A AFI floppy boot ROM (original, needed for the 2 MHz DRQ trick).

0x01000–0x01FFF — MZ-700 AFI floppy boot ROM.

0x02000–0x0BFFF — RFS firmware (10 × 2 KB User ROM banks, equivalent to User ROM banks 0–4).

0x0C000 onwards — ROM file system (programs stored as MZF images).

On the SFD-700 build, the User ROM code assembles to start at 0xE000 and aligns to 0xE300 (respecting the MZ-700 memory-mapped I/O range). There is no SD card; instead the inline assembler and disassembler (ASM/DASM) replace the SD card commands.

picoZ80

The picoZ80 board (RP2350-based Z80 replacement) emulates the MZ-80A's complete memory map in PSRAM and Flash. RFS runs inside the emulated ROM space, using the same bank addresses as the RomDisk build. The picoZ80 provides its own SPI-connected SD card storage, so the full RomDisk feature set (SD card drives, tape↔SD copy, etc.) is available.

Memory Architecture

The Sharp MZ-80A's Z80 CPU addresses 64 KB of memory. RFS fits its entire firmware into the two ROM windows without consuming any RAM, leaving the full 0x1200–0xCFFF range for user programs.

Z80 Address Space Layout

Address     Size    Contents
─────────────────────────────────────────────────────────────────────
0x0000      4 KB    Monitor ROM (MROM)  — 4 KB window into 512 KB Flash
                    Paged: bank 0 = SA-1510, bank 1 = SA-1510 80c,
                           bank 2 = CP/M CBIOS, bank 3 = RFS mrom utils,
                           bank 4 = 1Z-013A, bank 5 = 1Z-013A 80c,
                           bank 6 = IPL
0x1000      256 B   MZ-80A system variables / stack
0x1200    ~46 KB    User RAM  (main program area)
0xCFFF
0xD000      12 KB   Video RAM + memory-mapped I/O (MZ-80A hardware)
0xE800       2 KB   User ROM (UROM) — 2 KB window into 512 KB Flash
                    Paged: banks 0–7 = RFS modules,
                           banks 8–11 = CP/M CBIOS banks
                    Note: on the SFD-700 build the UROM window starts at
                    0xE300 (0xE000–0xE2FF is MZ-700 memory-mapped I/O).
                    The command table (CMDTABLE2) is placed at 0xE300 and
                    the main bank code remains at 0xE800 as on other builds.
0xEFFF
0xF000       4 KB   Floppy AFI ROM / FDC ROM (SFD-700 MROM location)
─────────────────────────────────────────────────────────────────────

Monitor ROM Banks (4 KB each)

The Monitor ROM window at 0x0000–0x0FFF is bank-switched across 7 banks stored in the Monitor ROM Flash chip:

Bank	Module	Description
0	`monitor_sa1510.asm`	Original SA-1510 monitor ROM — 40-column. The default bank on power-on.
1	`monitor_80c_sa1510.asm`	SA-1510 patched for 80-column display (requires Kuma upgrade).
2	`cbios.asm`	CP/M 2.2 CBIOS kernel — relocated here during CP/M boot.
3	`rfs_mrom.asm`	RFS Monitor ROM utilities. Runs from MROM space to scan and load MZF files stored in the User ROM Flash, since User ROM code cannot page itself out.
4	`monitor_1z-013a.asm`	MZ-1Z-013A monitor (MZ-700 / MZ-1200 variant).
5	`monitor_80c_1z-013a.asm`	1Z-013A monitor patched for 80-column display.
6	`ipl.asm`	Initial Program Loader.

User ROM Banks (2 KB each)

The User ROM window at 0xE800–0xEFFF is bank-switched across 12 banks in the User ROM Flash chips:

Bank	Module	Description
0	`rfs.asm`	Primary RFS entry point, command dispatcher, command table, bank-switch infrastructure shared by all banks.
1	`rfs_bank1.asm`	Floppy disk controller (FDC) functions — drive selection and boot. On the SFD-700 build only FDCK (direct AFI ROM jump) is assembled; the full drive-select boot routine (FLOPPY) is RomDisk / picoZ80 only.
2	`rfs_bank2.asm`	SD card controller — SPI driver, SD card initialisation, SDCFS directory and file read/write. Not assembled on the SFD-700 build (no SD card hardware).
3	`rfs_bank3.asm`	Monitor memory utilities — hex dump (D), memory edit (M), memory copy (CP). Tape↔SD copy (T2SD/SD2T) is included only in RomDisk / picoZ80 builds.
4	`rfs_bank4.asm`	CMT (cassette) controller — tape load, save, and verify.
5	`rfs_bank5.asm`	General utility functions — formatted print, string routines, shared helper code.
6	`rfs_bank6.asm`	Help screen, message strings, ASCII↔Sharp character set conversion table.
7	`rfs_bank7.asm`	Full Z80 interactive assembler, Z80 disassembler, DRAM memory test, 8253 timer test.
8	`cbios_bank1.asm`	CP/M CBIOS — audio functions and low-level utilities.
9	`cbios_bank2.asm`	CP/M CBIOS — screen driver and ANSI terminal emulation.
10	`cbios_bank3.asm`	CP/M CBIOS — SD card driver (provides CP/M drives A:–G:).
11	`cbios_bank4.asm`	CP/M CBIOS — floppy disk controller.

Bank Switching Mechanism

Because the Z80 can only see a 2 KB slice of the User ROM at any one time, every bank contains a copy of the bank-switching stub — a small fixed block of code at a known address within the 2 KB window. When bank 0 needs to call a routine in bank 3, it:

Writes the destination bank number to the hardware bank latch register.

Jumps to the well-known entry point in the newly mapped bank.

Executes the required routine.

Writes bank 0 back to the latch and returns.

This mechanism means all 12 × 2 KB = 24 KB of User ROM code is accessible from any execution context, even though only 2 KB is visible at a time. The bank switching stub occupies the first 32 bytes of each bank (0xE800–0xE81F), and the bank switching table starts at 0xE800 + 0xB0. Critically: no loop instruction must ever span the range 0xEFF8–0xEFFF on v2+ RomDisk boards, as those addresses trigger the coded latch unlock sequence.

Software Architecture

The complete module table — every source file, its target ROM, bank and function:

Module	ROM	Bank	Size	Description
rfs.asm	User	0	2 KB	Command dispatcher, command table, bank-switch infrastructure.
rfs_bank1.asm	User	1	2 KB	Floppy disk controller — drive select and FDC boot (RomDisk/picoZ80); FDCK AFI jump only (SFD-700).
rfs_bank2.asm	User	2	2 KB	SD card controller — SPI, SDCFS directory, file read/write. Not assembled on SFD-700 build.
rfs_bank3.asm	User	3	2 KB	Memory utilities — D, M, CP (all builds); T2SD, SD2T (RomDisk / picoZ80 only).
rfs_bank4.asm	User	4	2 KB	CMT controller — tape load, save, verify.
rfs_bank5.asm	User	5	2 KB	General utilities — print routines, string helpers.
rfs_bank6.asm	User	6	2 KB	Help screen, message strings, character set conversion.
rfs_bank7.asm	User	7	2 KB	Z80 assembler, Z80 disassembler, DRAM test, timer test.
cbios_bank1.asm	User	8	2 KB	CP/M CBIOS — audio, low-level utilities.
cbios_bank2.asm	User	9	2 KB	CP/M CBIOS — screen driver, ANSI terminal emulator.
cbios_bank3.asm	User	10	2 KB	CP/M CBIOS — SD card driver (CP/M drives A:–G:).
cbios_bank4.asm	User	11	2 KB	CP/M CBIOS — floppy disk controller.
monitor_sa1510.asm	Monitor	0	4 KB	Original SA-1510 monitor ROM (40-column).
monitor_80c_sa1510.asm	Monitor	1	4 KB	SA-1510 patched for 80-column display.
cbios.asm	Monitor	2	4 KB	CP/M 2.2 CBIOS kernel (relocated to 0xC000 during CP/M boot).
rfs_mrom.asm	Monitor	3	4 KB	RFS Monitor ROM utilities — ROM scanning, MZF loading.
monitor_1z-013a.asm	Monitor	4	4 KB	MZ-1Z-013A monitor (MZ-700 / MZ-1200 variant).
monitor_80c_1z-013a.asm	Monitor	5	4 KB	1Z-013A patched for 80-column display.
ipl.asm	Monitor	6	4 KB	Initial Program Loader.

CP/M 2.2 delivers 47 KB of usable program RAM. The CCP and BDOS reside in RAM and can be overwritten by large applications (they are reloaded on warm boot). The CBIOS lives entirely in Monitor ROM bank 2 and User ROM banks 8–11, consuming no program RAM.

The Monitor ROM also produces several additional variant images at build time: hi-load variants of SA-1510 and 80c SA-1510 (used when DRAM must span 0x0000–0xCFFF), and Kuma-80 variants (selected via the KUMA80_ENA flag).

SD Card Filing System (SDCFS)

Rather than implementing FAT (which would be too large for the available 2 KB ROM banks), RFS uses a purpose-built filing system called the SD Card Filing System (SDCFS). The design prioritises simplicity and a tight ROM footprint over flexibility.

Directory Structure

Each SDCFS drive image contains a flat directory of up to 256 entries. Each entry is exactly 32 bytes, based on the standard MZF tape header format:

Field	Bytes	Description
FLAG1	1	Bit 7 = 1: valid entry. Bit 7 = 0: inactive / deleted.
FLAG2	1	MZF execution type (0x01 = binary program).
FILE NAME	17	Standard 17-character MZF filename (Sharp character encoding).
START SECTOR	4	First sector within this drive image where the file’s data block begins.
SIZE	2	Actual byte count of the file data.
LOAD ADDR	2	Z80 RAM address to load the file data to.
EXEC ADDR	2	Auto-execution address for binary files (jumped to after load).
RESERVED	3	Not currently used.

The directory occupies the first 8 KB of each drive image (256 entries × 32 bytes). File data immediately follows, starting at the 256th 32-byte boundary. Each file is allocated a fixed 64 KB block — matching the maximum CMT tape block size — which keeps the layout trivially simple and makes SD↔tape copy a direct byte-for-byte transfer.

SD Card Layout

ADDRESS    CONTENT
────────────────────────────────────────────────────────────
0x00000000  RFS DRIVE 0
              0x00000000–0x00001FE0  Directory (256 × 32 B)
              0x00002000–0xFF2000    File blocks (256 × 64 KB)
0x01002000  RFS DRIVE 1  (same structure)
...
0x09012000  RFS DRIVE 9  (same structure)
0x0A014000  (padding to 256 MB boundary)
────────────────────────────────────────────────────────────
0x10000000  CP/M DISK IMAGE 0   (16 MB — 32 sectors × 1024 tracks)
0x11000000  CP/M DISK IMAGE 1
...
0xXX000000  CP/M DISK IMAGE 6
────────────────────────────────────────────────────────────

No partition table is written. The SDCFS image begins at byte 0 of the SD card. CP/M disk images begin at the 256 MB boundary to leave room for all 10 RFS drives regardless of how full they are.

CP/M 2.2 Implementation

Boot Process

CP/M boot on RFS occurs in two phases:

Phase 1 — AFI boot: The original MZ-80A AFI (Auto Floppy Interface) ROM code at 0xF000 reads the first sector of the floppy or the SD card boot block. It checks for the marker bytes 0x02 + "IPLPRO" at byte 0 (the MZ-80A CP/M bootable disk signature). If found, it passes control to the encapsulated second-stage loader in that sector.

Phase 2 — CCP+BDOS+CBIOS load: The second-stage loader reads the CCP, BDOS, and CBIOS from disk into RAM starting at 0x9C00. Once loaded, the CBIOS cold-boot entry point is called. The CBIOS configures the hardware (keyboard, screen, disk drives) and passes control to the CCP at 0x9C00.

CBIOS Architecture

The Custom BIOS (CBIOS) is split across five ROM modules to fit within available bank space:

Module	ROM Location	Contents
`cbios.asm`	MROM bank 2 (0xC000–0xCFFF)	CBIOS entry points (all 17 API vectors), cold/warm boot, interrupt handler, ROM disk controller, disk parameter tables.
`cbios_bank1.asm`	UROM bank 8	Audio (bell, melody), real-time clock routines, keyboard handler with auto-repeat.
`cbios_bank2.asm`	UROM bank 9	Screen driver (character output, scroll, cursor), ANSI terminal emulator (VT52/VT100 subset).
`cbios_bank3.asm`	UROM bank 10	SD card disk driver — reads and writes 128-byte CP/M sectors from SDCFS drive images starting at the 256 MB boundary.
`cbios_bank4.asm`	UROM bank 11	Floppy disk controller — standard 8-inch/5.25-inch drive support for physical CP/M disks.

CBIOS API

The CP/M CBIOS implements all 17 standard CP/M 2.2 API entry points:

Entry Point	Description
BOOT	Cold start — initialises all hardware, sets up the disk parameter tables, calls CCP.
WBOOT	Warm start — restores hardware state, reloads CCP+BDOS from disk, calls CCP.
CONST	Console Status — returns 0xFF if a key is waiting, 0x00 if not.
CONIN	Console Input — waits for a keypress and returns the ASCII code.
CONOUT	Console Output — writes a character to the screen.
LIST	Printer Output — outputs a character to the connected printer.
PUNCH	Punch/Tape Output — outputs to the tape punch device.
READER	Reader Input — reads from the tape reader device.
HOME	Seek to track 0 on the currently selected disk.
SELDSK	Select a disk drive (A:–G:) and return the Disk Parameter Header address.
SETTRK	Set the disk track for the next read or write operation.
SETSEC	Set the disk sector for the next read or write operation.
SETDMA	Set the Disk Memory Address — where data will be read to or written from.
READ	Read one 128-byte sector from the selected disk into the DMA buffer.
WRITE	Write one 128-byte sector from the DMA buffer to the selected disk.
LISTST	Printer Status — returns ready status of the list device.
SECTRN	Sector Translation — maps logical sector numbers to physical positions using the disk’s skew table.

CP/M Drive Configuration

CP/M drives are created dynamically during the cold boot by the CBIOS, depending on which disk controllers are available. The standard drive mapping on a fully equipped RomDisk / picoZ80 system is:

CP/M Drive	Controller	Image
A:	SD card	CPM_SYSTEM — OS programs, Turbo Pascal, Hi-Soft C, Fortran 80, MS-BASIC 80
B:	SD card	Pascal MTP v5.61, Turbo Pascal v3.00a, Pascal User Group disks
C:	SD card	PLI, PLM 80, WordStar v3.0/v3.3/v4.0
D:–G:	SD card	Grant Searle CP/M collection disks C0–F9

Build System

All development is done under Linux (Debian/Ubuntu). The build system is almost entirely self-contained within the repository.

Prerequisites

Tool	Purpose
Java JRE 8+	Runs the GLASS Z80 assembler (`tools/glass.jar`). `java` must be on `PATH`.
bash	All build scripts are bash shell scripts.
perl	Required by `tools/mzftool.pl` for MZF file manipulation.
gcc / make	Compiles `cpmtools` from source on first build (automatic).
dd, cat, stat	Standard Linux utilities used by the packaging scripts.

The GLASS Z80 assembler is bundled in tools/glass.jar — no separate installation is required.

Build Flags

Edit asm/include/rfs_definitions.asm and set exactly one target flag to 1 (all others must be 0):

Flag	Target
`BUILD_ROMDISK EQU 1`	RomDisk card
`BUILD_SFD700 EQU 1`	SFD-700 floppy interface
`BUILD_PICOZ80 EQU 1`	picoZ80 board

Additional optional feature flags:

Flag	Default	Description
`KUMA80_ENA`	0	Set to 1 if the Kuma 40/80 column upgrade is fitted.
`VIDEOMODULE_ENA`	0	Set to 1 if the 40/80 colour Video Module is fitted.
`FUSIONX_ENA`	0	Set to 1 when running on the tranZPUter FusionX board.
`HW_SPI_ENA`	1	Hardware SPI (RomDisk v2+ PCB). Leave at 1 for all current boards.
`SW_SPI_ENA`	0	Software bit-bang SPI (RomDisk v1 via parallel port).
`ENADEBUG`	0	Enable assembly-time debug output.

Build Steps

git clone https://github.com/pdsmart/RFS.git
cd RFS

# Full build — assembles all ROMs, packages images, builds SD card image:
./build.sh

# Full build including reprocessing all MZF application files
# (only needed when files in MZF/ have changed):
./build.sh -m

build.sh runs the following steps in order:

Compiles cpmtools from source (first run only) and adds to PATH.

tools/assemble_rfs.sh — assembles rfs.asm and rfs_mrom.asm into roms/rfs.rom and roms/rfs_mrom.rom.

tools/assemble_cpm.sh — assembles the CP/M 2.2 CBIOS and CCP+BDOS into roms/*.rom.

tools/assemble_roms.sh — assembles all monitor variants and MZF applications. Handles the four MS-BASIC build variants by writing a BUILD_VERSION EQU to include/msbasic_buildversion.asm before each pass.

tools/make_roms.sh — packages ROM and MZF binaries into Flash ROM images for each target.

tools/make_cpmdisks.sh — builds CP/M disk images in RAW format (for SD card) and CPC Extended Disk Format (for floppy emulators).

tools/make_sdcard.sh — combines 10 RFS drive images and 7 CP/M disk images into the final SD card image.

Output Files

After a successful build the roms/ directory contains:

File	Flash Chip	Description
`MROM_ROMDISK_256.bin`	Monitor ROM Flash	Monitor ROM for RomDisk: SA-1510, 80c SA-1510, CP/M CBIOS, RFS mrom utils, 1Z-013A monitors, IPL across 7×4 KB banks.
`MROM_PICOZ80_256.bin`	Monitor ROM Flash	Monitor ROM for picoZ80 (bank order differs from RomDisk).
`USER_ROM_256.bin`	User ROM 1 Flash	RFS banks 0–7, CP/M CBIOS banks 8–11, CP/M 2.2 image, packed MZF applications.
`USER_ROM_II_256.bin`	User ROM 2 Flash	Additional MZF applications.
`USER_ROM_III_256.bin`	User ROM 3 Flash	Additional MZF applications.
`SFD700_256.bin`	SFD-700 Flash	AFI ROMs + RFS firmware + ROM file system.
`SHARP_MZ80A_RFS_IMAGE_0–9.img`	SD card	Individual RFS drive images (one per drive 0–9).
`SHARP_MZ80A_RFS_CPM_IMAGE_1.img`	SD card	Combined image: 10 RFS drives + 7 CP/M disk images. Write this to the SD card.

Adding Applications to the ROM Drives

MZF format application files must be converted to sector-padded binary images before inclusion in the ROM drives. Place MZF files in the appropriate subdirectory under MZF/ then run:

tools/processMZFfiles.sh

This produces 128-byte and 256-byte sector-padded images in MZB/. To choose which applications appear in each ROM drive, edit tools/make_roms.sh and adjust the addMZFToROMImageList calls:

# Format: addMZFToROMImageList <ROMDISK> <SFD700> <picoZ80> <reserved> "<path>"
#
# Include in all builds:
addMZFToROMImageList 1 1 1 0 "${MZB_PATH}/Common/sa-5510_rfs.${SECTORSIZE}.bin"
#
# RomDisk and picoZ80 only (no SFD700 — needs SD card):
addMZFToROMImageList 1 0 1 0 "${MZB_PATH}/MZ-80A/defender.${SECTORSIZE}.bin"

Applications are packed in the order listed, filling User ROM 1 first, then User ROM 2 and 3. Place the most frequently used applications at the top of the list.

Build Tools Reference

Tool	Description
`build.sh`	Top-level build script. Pass `-m` to also reprocess MZF files.
`tools/assemble_rfs.sh`	Assembles RFS core modules.
`tools/assemble_cpm.sh`	Assembles CP/M 2.2 CBIOS and kernel.
`tools/assemble_roms.sh`	Assembles monitor variants and MZF application binaries.
`tools/make_roms.sh`	Packages binaries into Flash ROM images.
`tools/make_cpmdisks.sh`	Creates CP/M disk images.
`tools/make_sdcard.sh`	Combines images into the final SD card image.
`tools/processMZFfiles.sh`	Converts MZF files to sector-padded binaries in `MZB/`.
`tools/mzftool.pl`	Creates, extracts, and inspects MZF format images.
`tools/sdtool`	Builds the RFS SD card directory and populates it with files.
`tools/nasconv`	Converts NASCOM cassette images to MZ-80A loadable format, remapping MS-BASIC tokens.
`tools/glass.jar`	Bundled GLASS Z80 assembler (Java). Used by all assembly scripts.
`cpmtools/`	Source for `cpmcp`, `cpmls`, `cpmrm`, etc. Compiled on first build.

Reference Sites

Resource	Link
RFS project page	/sharpmz-upgrades-rfs/
RFS User Manual	/sharpmz-upgrades-rfs-usermanual/
RFS Developer’s Guide	/sharpmz-upgrades-rfs-developersguide/
RFS Gallery	/sharpmz-upgrades-rfs-gallery/
CP/M on MZ-80A notes	Included in `_pages/MZ80A_RFS_CPM_README.md`
SFD-700 mkII Technical Guide	/sfd700-technicalguide/
picoZ80 Technical Guide	/picoz80-technicalguide/
GLASS Z80 Assembler	Bundled in `tools/glass.jar`