RFS/README.md

# RFS

**Website:** [engineers@work](https://eaw.app) | **Repository:** [git.eaw.app/eaw/RFS](https://git.eaw.app/eaw/RFS)

---

## <font style="color: yellow;" size="6">Overview</font>

<div style="text-align: justify">
The Rom Filing System (RFS) is a Z80 assembly language firmware package that provides an interactive monitor with mass-storage filing system, application launch, memory utilities and debugging tools for the Sharp MZ-80A and compatible hardware.
<div style="padding-top: 0.8em;"></div>

RFS replaces the Monitor ROM and User ROM of the host machine via socket lifters connected to the expansion board. It presents itself to the user as an enhanced version of the original SA-1510 monitor program with the same familiar <code>* </code> prompt, all original commands intact and a comprehensive set of new commands for SD card and ROM filing, CP/M boot, BASIC load and much more.
<div style="padding-top: 0.8em;"></div>

The firmware supports four hardware platforms, each selected at compile time via a flag in <code>rfs_definitions.asm</code>:
<ul>
  <li><b>RomDisk card</b> — the original target. Up to 4&times;512&nbsp;KB Flash RAMs, 512&nbsp;KB Static RAM and an SDXC card reader. Monitor and User ROMs are bank-switched across the Flash RAM.</li>
  <li><b>SFD-700</b> — the Sharp Floppy Disk Interface board. RFS occupies the CPLD/ROM space of the SFD-700 and provides monitor, BASIC load, floppy boot and a built-in Z80 assembler/disassembler.</li>
  <li><b>tranZPUter FusionX</b> — the FPGA-based Z80 enhancement board. RFS runs within its Flash ROM space.</li>
  <li><b>picoZ80</b> — the Raspberry Pi Pico based Z80 replacement/emulator board.</li>
</ul>
</div>

--------------------------------------------------------------------------------------------------------

## <font style="color: yellow;" size="6">RFS Monitor</font>

<div style="text-align: justify">
On boot the familiar SA-1510 sign-on banner appears, appended with "<code>+ RFS</code>" when the filing system has initialised successfully. The original SA-1510 command set is fully available alongside a set of extended commands. Some extended commands (SD card operations, drive selection) are only present in the RomDisk / picoZ80 build; the SFD700 build instead adds the inline assembler and disassembler.
<div style="padding-top: 0.8em;"></div>

The full command set is listed below. Commands marked <b>(R)</b> are present only in the RomDisk / picoZ80 build; commands marked <b>(S)</b> are present only in the SFD700 build.
</div>

| Command | Parameters | Description |
|---------|------------|-------------|
| 0 .. 9 **(R)** | — | Select the active RFS SD card drive (0–9). |
| 40 **(R)** | — | Switch to 40‑column display mode (requires Kuma 40/80 upgrade or Video Module). |
| 80 **(R)** | — | Switch to 80‑column display mode (requires Kuma 40/80 upgrade or Video Module). |
| ASM **(S)** | \<address\> | Interactive Z80 assembler. Enter assembly mnemonics directly into memory starting at the given address. |
| B | — | Toggle the keyboard bell. |
| BASIC | — | Locate BASIC SA-5510 on the active SD drive or ROM, load and execute it. |
| C | \[\<8‑bit value\>\] | Clear (initialise) memory from 0x1200 to top of RAM with 0x00 or the supplied byte value. |
| CP | \<src\> \<dst\> \<size\> | Copy a block of memory. All three arguments are 4‑digit hex: source address, destination address, byte count. |
| CPM | — | Locate CP/M 2.2 on the active SD drive or ROM, load and boot it. |
| D | \<addr\> \[\<addr2\>\] | Dump memory from \<addr\> to \<addr2\> (or 20 lines) in hex and ASCII. Output pauses at each screenful; press a key to continue, 'U' to page up, 'X' to exit. Repeating 'D' without an address continues from the last displayed location. |
| DASM **(S)** | \<addr\> \[\<addr2\>\] | Disassemble Z80 machine code from \<addr\> to \<addr2\>. |
| EC **(R)** | \<name\> or \<file no.\> | Erase a file from the active SD card drive by name or file number. |
| F | \[\<drive\>\] | Boot from the specified floppy drive. If omitted, you are prompted to enter a drive number. |
| f | — | Execute the original floppy AFI boot code at 0xF000. |
| H | — | Display the command help screen (paginated, press Space to continue). |
| IC **(R)** | — | Paged directory listing of files on the active SD card drive. Each entry shows a hex file number and filename. |
| IR | — | Paged directory listing of programs stored in the Flash ROM drives. |
| J | \<address\> | Jump to (execute from) the given address. |
| L \| LT | \[\<filename\>\] | Load a file from tape (CMT) and execute it. |
| LTNX | \[\<filename\>\] | Load a file from tape (CMT) without executing. |
| LR | \<name\> or \<file no.\> | Load a program from ROM by name or file number and execute it. |
| LRNX | \<name\> or \<file no.\> | Load a program from ROM by name or file number without executing. |
| LC **(R)** | \<name\> or \<file no.\> | Load a program from the SD card and execute it. |
| LCNX **(R)** | \<name\> or \<file no.\> | Load a program from the SD card without executing. |
| M | \<address\> | Interactive memory editor starting at \<address\>. |
| P | — | Run a test on the connected printer. |
| R | — | Run a DRAM memory test. |
| S \| ST | \<start\> \<end\> \<exec\> | Save a memory range to tape (CMT). You are prompted for a filename. Example: `S120020001203` saves from 0x1200 to 0x2000 with execution at 0x1203. |
| SC **(R)** | \<start\> \<end\> \<exec\> | Save a memory range to the active SD card drive. You are prompted for a filename. |
| SD2T **(R)** | \<name\> or \<file no.\> | Copy a file from the SD card to tape in the CMT. |
| T | — | Test the 8253 timer. |
| T2SD **(R)** | — | Load a program from tape and write it to the active SD card drive. |
| V | — | Verify a tape save against the data currently in memory. |
| X **(R)** | — | Exchange to the hi‑load ROM variant so DRAM spans 0x0000–0xCFFF. |


If the Kuma 40/80 column upgrade or the Video Module is installed, typing `4` switches to 40‑column display and `8` switches to 80‑column display. In 80‑column mode the directory listing commands (IC / IR) display four columns.

--------------------------------------------------------------------------------------------------------

## <font style="color: yellow;" size="6">Upgraded Applications</font>

<div style="text-align: justify">
The Sharp MZ series are known as "clean machines" — almost no software lives permanently in ROM; everything is loaded from tape or floppy. The applications that existed therefore had no knowledge of the enhanced storage that RFS provides, other than being able to load them rapidly from the RFS monitor.
<div style="padding-top: 0.8em;"></div>

To make the machines more usable, key applications have been updated to use RFS natively and the Microsoft BASIC interpreter has been ported to the platform. CP/M 2.2 has also been brought up via a custom CBIOS that uses RFS facilities.
</div>

### <font style="color: yellow;" size="5">Sharp BASIC SA-5510</font>

<div style="text-align: justify">
The original Sharp SA-5510 BASIC has been disassembled and extended with RFS-aware LOAD, SAVE and DIR commands. The byte layout of the interpreter is preserved so that programs that rely on known fixed addresses continue to work. Extensions are applied outside the main interpreter image.
<div style="padding-top: 0.8em;"></div>

The extended version is named <b>SA-5510RFS</b> on the ROM drive and SD drive. On boot it uses the active SD drive (drives 0–9) for all file operations. The standard LOAD and SAVE syntax is unchanged; the drive qualifier prefix is the only addition.
</div>

| Command | Parameter | Description |
|---------|-----------|-------------|
| LOAD | `"TEST"` | Search the active drive for a program named TEST, load and run it. |
| LOAD | | Load the next sequential file from the active drive. If file 5 was last loaded, this loads file 6. |
| LOAD | `"3:TEST"` | Load TEST from RFS drive 3, making drive 3 active. |
| LOAD | `"C:TEST"` | Load TEST from the internal cassette (CMT), making CMT the active drive. |
| SAVE | `"TEST"` | Overwrite an existing file named TEST on the active drive, or create it if absent. On CMT, writes immediately at the current tape position. |
| SAVE | | Save the current program under an auto-generated name `DEFAULT<n>`, where `<n>` is the current sequence number. |
| SAVE | `"3:TEST"` | Save/create TEST on RFS drive 3 and make drive 3 active. |
| SAVE | `"C:TEST"` | Save to CMT with the name TEST and make CMT active. |
| DIR | | List the SD card directory for the active drive in RFS format (file number + filename). |
| DIR | `"3:"` | List the directory on drive 3 and make drive 3 active. |

See [SD Card Organisation](#sd-card-organisation) below for the default drive layout.

### <font style="color: yellow;" size="5">Microsoft BASIC</font>

<div style="text-align: justify">
While most MZ-80A BASIC interpreters are available only as binaries, Microsoft BASIC (NASCOM 4.7b) has freely available source code and a large library of existing programs. RFS includes a ported and extended version that supports native RFS storage across three configurations matching the target hardware:
</div>

  * **MS-BASIC(MZ-80A)** — for original MZ-80A hardware, cassette storage only.
  * **MS-BASIC(RFS40)** — RFS with 40‑column display; adds SD card, CLOAD, CSAVE, DIR.
  * **MS-BASIC(RFS80)** — RFS with 80‑column display; adds SD card, CLOAD, CSAVE, DIR.

Each variant appears on the RFS ROM drive and SD drive. Consult the [NASCOM Basic Manual](../docs/Nascom_Basic_Manual.pdf) for the full standard command set. The table below lists the extensions added for RFS.

| Command | Parameters | Version | Description |
|---------|------------|---------|-------------|
| CLOAD | `"<filename>"` | MZ-80A | Load a tokenised BASIC program from cassette. |
| CSAVE | `"<filename>"` | MZ-80A | Save the current BASIC program to cassette in tokenised format. |
| CLOAD | `"[<drive>:]<filename>"` | RFS40, RFS80 | Load from tape or SD card. `<drive>` is 0–9; `<filename>` is a 17-character MZ name or 2-digit RFS hex number. Example: `CLOAD "8:13"` or `CLOAD "8:othello"`. |
| CSAVE | `"[<drive>:]<filename>"` | RFS40, RFS80 | Save to tape or SD card with optional drive qualifier. |
| DIR | `"[<drive>:]"` | RFS40, RFS80 | Display the active or specified RFS drive contents. |
| ANSITERM | `0` = Off, `1` = On | All | Enable or disable (default on) the built-in ANSI terminal processor. This translates ANSI escape sequences into screen actions, allowing portable BASIC programs to run unchanged. (The Star Trek V2 BASIC program uses ANSI escape sequences.) |

##### <font style="color: yellow;" size="4">NASCOM Cassette Image Converter</font>

<div style="text-align: justify">
NASCOM BASIC programs are commonly distributed as cassette image files containing tape-framing data wrapped around tokenised BASIC. The bundled <code>nasconv</code> tool strips the tape framing and rebuilds the BASIC code in a format loadable on the MZ-80A under RFS. It also remaps token values automatically, since the RFS MS-BASIC extension adds new tokens that shift the table.
</div>

```bash
nasconv v1.0

Required:
  -i | --image  <file>   Cassette image file to convert.
  -o | --output <file>   Output file for converted BASIC data.

Options:
  -l | --loadaddr <addr> MZ-80A BASIC start address.
  -n | --nasaddr  <addr> Original NASCOM BASIC start address.
  -h | --help            Show this help.
  -v | --verbose         Verbose output.

Example:
  nasconv --image 3dnc.cas --output 3dnc.bas \
          --nasaddr 0x10fa --loadaddr 0x4341
```

--------------------------------------------------------------------------------------------------------

## <font style="color: yellow;" size="6">Software Architecture</font>

<div style="text-align: justify">
The User ROM space at 0xE800 is divided into 2&nbsp;KB banks, each containing a copy of the bank-switching stub so that any bank can call code in any other bank without disturbing execution flow. The Monitor ROM space at 0xC000 / 0xF000 is divided into 4&nbsp;KB banks. Together the RFS and CP/M CBIOS banks give almost 16&nbsp;KB of effective ROM program space without consuming any RAM.
<div style="padding-top: 0.8em;"></div>

The following table lists every source module, its target ROM, bank and function:
</div>

| Module | Target ROM | Size | Bank | Description |
|--------|-----------|------|------|-------------|
| rfs.asm | User | 2 KB | 0 | Primary RFS entry point, command dispatcher and command table. Contains the bank-switching infrastructure shared by all banks. |
| rfs_bank1.asm | User | 2 KB | 1 | Floppy disk controller (FDC) functions. Handles drive selection and boot. |
| rfs_bank2.asm | User | 2 KB | 2 | SD card controller. SPI driver, SD card initialisation, SDCFS directory and file read/write. |
| rfs_bank3.asm | User | 2 KB | 3 | Monitor memory utilities: hex dump, memory edit, memory copy, tape↔SD copy (T2SD / SD2T). |
| rfs_bank4.asm | User | 2 KB | 4 | CMT (cassette) controller: tape load, save and verify. |
| rfs_bank5.asm | User | 2 KB | 5 | General utility functions: formatted print, string routines and shared helper code. |
| rfs_bank6.asm | User | 2 KB | 6 | Help screen, message strings, ASCII↔Sharp character set conversion table. |
| rfs_bank7.asm | User | 2 KB | 7 | Full Z80 interactive assembler, Z80 disassembler, DRAM memory test and 8253 timer test. |
| cbios_bank1.asm | User | 2 KB | 8 | CP/M CBIOS: audio functions and low-level utilities. |
| cbios_bank2.asm | User | 2 KB | 9 | CP/M CBIOS: screen driver and ANSI terminal emulation. |
| cbios_bank3.asm | User | 2 KB | 10 | CP/M CBIOS: SD card driver (provides CP/M drive A:–G:). |
| cbios_bank4.asm | User | 2 KB | 11 | CP/M CBIOS: floppy disk controller. |
| monitor_sa1510.asm | Monitor | 4 KB | 0 | Original SA-1510 monitor ROM (40-column). |
| monitor_80c_sa1510.asm | Monitor | 4 KB | 1 | SA-1510 monitor patched for 80-column display. |
| cbios.asm | Monitor | 4 KB | 2 | CP/M 2.2 CBIOS kernel (loaded to 0xC000–0xCFFF). |
| rfs_mrom.asm | Monitor | 4 KB | 3 | RFS Monitor ROM utilities. Because code executing from the User ROM cannot page itself out to scan the remaining ROM, these routines run from Monitor ROM bank 3 to scan and load MZF files stored in the User ROM Flash RAM. |
| monitor_1z-013a.asm | Monitor | 4 KB | 4 | MZ-1Z-013A monitor ROM (MZ-700 / MZ-1200 variant). |
| monitor_80c_1z-013a.asm | Monitor | 4 KB | 5 | MZ-1Z-013A monitor patched for 80-column display. |
| ipl.asm | Monitor | 4 KB | 6 | Initial Program Loader. |

<div style="text-align: justify">
<br>
CP/M 2.2 is supported with 47&nbsp;KB of usable program RAM. Only the CCP and BDOS reside in RAM (and can be overwritten by applications); the CBIOS itself lives in Monitor ROM bank 2 and User ROM banks 8–11, consuming no program RAM at all.
<br><br>

The Monitor ROM also provides several variant monitor images built at the same time: a standard SA-1510, an 80-column SA-1510, a Kuma-80 version (selected via the <code>KUMA80_ENA</code> flag in <code>rfs_definitions.asm</code>), and hi-load variants of both SA-1510 and 80-column SA-1510 used when DRAM needs to fill the full 0x0000–0xCFFF range.
</div>

--------------------------------------------------------------------------------------------------------

## <font style="color: yellow;" size="6">Build System</font>

<div style="text-align: justify">
All development is done under Linux (Debian / Ubuntu). Building RFS involves assembling the Z80 source, packaging the ROM images and creating SD card images. The toolchain is almost entirely self-contained within the repository.
</div>

### <font style="color: yellow;" size="5">Prerequisites</font>

| Tool | Notes |
|------|-------|
| **Java** (JRE 8+) | Required to run the GLASS Z80 assembler. `java` must be on `PATH`. |
| **bash** | All build scripts are bash. |
| **perl** | Required by `mzftool.pl`. |
| **gcc / make** | Required to compile `cpmtools` from source (done automatically on first build). |
| **dd, cat, stat** | Standard Linux utilities used by the packaging scripts. |

The GLASS Z80 assembler (`glass.jar`) is bundled in the `tools/` directory — no separate installation is needed.

### <font style="color: yellow;" size="5">Build Targets</font>

The build target is selected by editing `asm/include/rfs_definitions.asm` and setting exactly one of the following flags to `1` (all others must be `0`):

| Flag | Target | Description |
|------|--------|-------------|
| `BUILD_ROMDISK` | RomDisk card | MZ-80A with 4×512 KB Flash RAM + SDXC card expansion. |
| `BUILD_SFD700` | SFD-700 | Sharp floppy disk interface board. No SD card; adds ASM/DASM. |
| `BUILD_PICOZ80` | picoZ80 | Raspberry Pi Pico based Z80 replacement board. |

Additional optional flags in the same file:

| Flag | Default | Description |
|------|---------|-------------|
| `KUMA80_ENA` | 0 | Set to 1 if the Kuma 40/80 column upgrade is installed. |
| `VIDEOMODULE_ENA` | 0 | Set to 1 if the 40/80 column colour Video Module is installed. |
| `FUSIONX_ENA` | 0 | Set to 1 when running RFS on the tranZPUter FusionX board. |
| `HW_SPI_ENA` | 1 | Hardware SPI (RomDisk v2+ PCB). Leave at 1 for all current boards. |
| `ENADEBUG` | 0 | Enable assembly-time debug logging. |

### <font style="color: yellow;" size="5">Building</font>

Clone the repository and run the top-level build script:

```bash
git clone https://git.eaw.app/eaw/RFS.git
cd RFS

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

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

`build.sh` performs the following steps in order:

1. Compiles `cpmtools` from source (first run only) and adds the result to `PATH`.
2. **`tools/assemble_rfs.sh`** — assembles `rfs.asm` and `rfs_mrom.asm` into `roms/rfs.rom` and `roms/rfs_mrom.rom`.
3. **`tools/assemble_cpm.sh`** — assembles the CP/M 2.2 CBIOS (`cbios.asm`, `cbios_bank1–4.asm`, `cpm22.asm`) into `roms/*.rom`.
4. **`tools/assemble_roms.sh`** — assembles all monitor variants (SA-1510, 80c SA-1510, 1Z-013A, hi-load variants, Kuma version, IPL) and MZF application files (SA-5510, MS-BASIC variants, etc.) into `roms/` and `MZB/`.
5. **`tools/make_roms.sh`** — packages the assembled ROMs and MZF applications into Flash ROM images (see Output Files below).
6. **`tools/make_cpmdisks.sh`** — builds CP/M disk images in RAW and CPC Extended Disk Format for each of the pre-populated CP/M drive sets.
7. **`tools/make_sdcard.sh`** — assembles the final SD card image combining 10 RFS drive images and 7 CP/M disk images.

The individual scripts can also be run directly from within the `tools/` directory for partial rebuilds.

### <font style="color: yellow;" size="5">Output Files</font>

After a successful build the `roms/` directory contains:

| File | Flash chip | Description |
|------|-----------|-------------|
| `MROM_ROMDISK_256.bin` | SST39SF040 (Monitor ROM) | Monitor ROM image for the RomDisk build. Contains SA-1510, 80c SA-1510, CP/M CBIOS, RFS mrom utilities, 1Z-013A monitors and IPL across 8×4 KB banks. |
| `MROM_PICOZ80_256.bin` | SST39SF040 (Monitor ROM) | Monitor ROM image for the picoZ80 build (bank order differs from ROMDISK). |
| `USER_ROM_256.bin` | SST39SF040 (User ROM 1) | User ROM 1: RFS banks 0–7, CP/M CBIOS banks 8–11, CP/M 2.2 image and a packed set of MZF applications. |
| `USER_ROM_II_256.bin` | SST39SF040 (User ROM 2) | User ROM 2: additional MZF applications. |
| `USER_ROM_III_256.bin` | SST39SF040 (User ROM 3) | User ROM 3: additional MZF applications. |
| `SFD700_256.bin` | SST39SF040 | SFD-700 ROM: MZ-80A AFI floppy ROM (0x00000–0x00FFF), MZ-700 floppy ROM (0x01000–0x01FFF), RFS firmware (0x02000–0x0BFFF), then ROM file system. |
| `SHARP_MZ80A_RFS_IMAGE_0–9.img` | SD card | Ten RFS drive images (one per `0–9` drive). |
| `SHARP_MZ80A_RFS_CPM_IMAGE_1.img` | SD card | Combined SD card image: 10 RFS drives followed by 7 CP/M disk images. Copy this directly to an SD card. |

### <font style="color: yellow;" size="5">Programming the Flash ROMs</font>

The ROM images are written to SST39SF040 (512 KB) Flash RAM chips using a TL866 or compatible programmer:

```bash
# Monitor ROM (RomDisk build):
minipro --infoic /path/to/minipro/infoic.xml -p SST39SF040 -s -w roms/MROM_ROMDISK_256.bin

# User ROM 1:
minipro --infoic /path/to/minipro/infoic.xml -p SST39SF040 -s -w roms/USER_ROM_256.bin

# SFD-700:
minipro --infoic /path/to/minipro/infoic.xml -p SST39SF040 -s -w roms/SFD700_256.bin
```

### <font style="color: yellow;" size="5">Writing the SD Card Image</font>

Write the combined SD card image directly to the SD card using `dd`:

```bash
# Replace /dev/sdX with your SD card device:
dd if=roms/SHARP_MZ80A_RFS_CPM_IMAGE_1.img of=/dev/sdX bs=512
sync
```

No partitioning is required. The SDCFS image begins at sector 0. Insert the SD card into the reader on the RomDisk board.

### <font style="color: yellow;" size="5">Adding Applications to the ROM Drives</font>

Applications stored in the Flash ROM drives must first be converted from MZF format into sector-padded binary images. Place the MZF files in the appropriate subdirectory under `MZF/` and run:

```bash
tools/processMZFfiles.sh
```

This converts all MZF files into 128-byte and 256-byte sector-padded images stored in `MZB/`. They are then picked up automatically by `make_roms.sh`.

To choose which applications appear in each ROM drive, edit `tools/make_roms.sh` and adjust the `addMZFToROMImageList` calls. Each call takes four flags (include in ROMDISK build, include in SFD700 build, include in picoZ80 build, reserved) and the path to the sectored binary:

```bash
# Format:
#   addMZFToROMImageList  <ROMDISK>  <SFD700>  <picoZ80>  <reserved>  "<MZB path>"
#
# Example — include in all builds:
addMZFToROMImageList 1 1 1 0 "${MZB_PATH}/Common/sa-5510_rfs.${SECTORSIZE}.bin"

# Example — RomDisk and picoZ80 only:
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 applications you always want available at the top of the list.

### <font style="color: yellow;" size="5">Build Tools Reference</font>

| Script / Tool | Description |
|--------------|-------------|
| `build.sh` | Top-level build script. Runs all steps below in order. Pass `-m` to also reprocess MZF application files. |
| `tools/assemble_rfs.sh` | Assembles `rfs.asm` and `rfs_mrom.asm` → `roms/rfs.rom`, `roms/rfs_mrom.rom`. |
| `tools/assemble_cpm.sh` | Assembles the CP/M 2.2 CBIOS and kernel → `roms/*.rom`. |
| `tools/assemble_roms.sh` | Assembles all monitor ROM variants and MZF application binaries. Handles the four MS-BASIC build variants via a `BUILD_VERSION` EQU written to `include/msbasic_buildversion.asm` before each pass. |
| `tools/make_roms.sh` | Packages ROM and MZF binaries into Flash ROM images for ROMDISK, SFD700 and picoZ80 targets. |
| `tools/make_cpmdisks.sh` | Creates CP/M disk images in RAW format (for SD card) and CPC Extended Disk Format (for floppy emulators or physical copying). |
| `tools/make_sdcard.sh` | Combines RFS drive images and CP/M disk images into a single SD card image. |
| `tools/processMZFfiles.sh` | Converts MZF application files into 128-byte and 256-byte sector-padded images in `MZB/`. |
| `tools/mzftool.pl` | Perl script to create, extract and inspect MZF format images. |
| `tools/sdtool` | Binary tool that builds the RFS SD card directory structure and populates it with MZF / binary applications. |
| `tools/nasconv` | Converts NASCOM cassette image files to MZ-80A loadable format, remapping MS-BASIC token values as needed. |
| `tools/glass.jar` | Bundled GLASS Z80 assembler (Java). Used by all three assembly scripts. |
| `cpmtools/` | cpmtools source (cpmcp, cpmls, cpmrm, etc.). Compiled automatically on first build and installed into `tools/`. |

--------------------------------------------------------------------------------------------------------

## <font style="color: yellow;" size="6">SD Card Filing System</font>

<div style="text-align: justify">
Rather than implementing a FAT file system (which would be too large for the 2 KB and 4 KB ROM banks), RFS uses a purpose-built simple filing system called the SD Card Filing System (SDCFS). Initial v1 boards used a software bit-bang SPI interface; the v2.0 PCB added hardware SPI, giving ROM-level access speeds.
</div>

### <font style="color: yellow;" size="5">SDCFS Structure</font>

<div style="text-align: justify">
Each SDCFS image contains a 32-byte-per-entry directory for up to 256 files followed by 256 fixed-size file blocks. Ten SDCFS images (drives 0–9) are stored at the start of the SD card. The remainder of the SD card holds CP/M disk images.
<div style="padding-top: 0.8em;"></div>

Each directory entry is based on the standard MZF header:
</div>

| FLAG1 | FLAG2 | FILE NAME | START SECTOR | SIZE | LOAD ADDR | EXEC ADDR | RESERVED |
|-------|-------|-----------|--------------|------|-----------|-----------|----------|
| 1 Byte | 1 Byte | 17 Bytes | 4 Bytes | 2 Bytes | 2 Bytes | 2 Bytes | 3 Bytes |

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

Each file block is a fixed 64 KB, matching the maximum CMT (tape) block size. This keeps the layout simple and allows files to be read or written exactly as if they were on tape, enabling transparent SD↔CMT copy operations.

### <font style="color: yellow;" size="5">SD Card Layout</font>

```
ADDRESS    SECTOR   CONTENT
00000000   00000  ┌─────────────────────────────────────────────────────────────┐
                  │  RFS DRIVE 0                                                │
00000000   00000  │  Directory entry 000 (32 bytes)                             │
                  │  ...                                                        │
00001FE0   0000F  │  Directory entry 255 (32 bytes)                             │
00002000   00010  │  File block 0     (64 KB)                                   │
                  │  ...                                                        │
00FF2000   7FF90  │  File block 255   (64 KB)                                   │
01001FFF   8000F  └─────────────────────────────────────────────────────────────┘
                  ...  (RFS drives 1–8 follow the same pattern)
09012000   48090  ┌─────────────────────────────────────────────────────────────┐
                  │  RFS DRIVE 9                                                │
0A013FFF   5009F  └─────────────────────────────────────────────────────────────┘
                  ... padding to 256 MB boundary ...
10000000   80000  ┌─────────────────────────────────────────────────────────────┐
                  │  CP/M DISK IMAGE 0   (16 MB, 32 sectors × 1024 tracks)     │
11000000   88000  ├─────────────────────────────────────────────────────────────┤
                  │  CP/M DISK IMAGE 1                                          │
                  │  ...                                                        │
XX000000          │  CP/M DISK IMAGE n                                          │
                  └─────────────────────────────────────────────────────────────┘
```

### <font style="color: yellow;" size="5">SD Card Organisation</font>

The SD card image built by the repository tools is pre-populated as follows:

| RFS Drive | Contents |
|-----------|----------|
| 0 | Common and MZ-80A machine code programs. |
| 1 | MZ-80K machine code programs. |
| 2 | MZ-700 machine code programs. |
| 3 | MZ-800 / MZ-1500 machine code programs. |
| 4 | MZ-80B / MZ-2000 machine code programs. |
| 5 | BASIC programs, type 2 (MZ-80A). |
| 6 | BASIC programs, type 2 (MZ-80K). |
| 7 | BASIC programs, type 5 (MZ-700 / MZ-800). |
| 8 | Other / miscellaneous programs. |
| 9 | Other / miscellaneous programs. |

| CP/M Drive | User# | Disk image | Contents |
|-----------|-------|-----------|---------|
| 0 | 0 | CPM00_SYSTEM | CP/M system programs |
| | 1 | CPM01_TURBOP | Turbo Pascal |
| | 2 | CPM02_HI_C | Hi-Soft C |
| | 3 | CPM03_FORTRAN80 | Fortran 80 |
| | 4 | CPM04_MBASIC | Microsoft BASIC 80/85 |
| | 5–7 | CPM05–07_COBOL80 | Cobol v1.3, v2.0, Cobol 80 |
| | 8 | CPM08_Z80FORTH | Z80 Forth |
| | 9 | CPM09_CPMTEX | CP/M TeX |
| | 10 | CPM10_DISKUTILFUNC5 | Disk utilities |
| | 11 | CPM11_MAC80 | Macro Assembler 80 |
| | 12 | CPM29_ZSID_v14 | ZSID Debugger |
| | 13–14 | CPM32–33_ZCPR3 | ZCPR3 CCP enhancement |
| 1 | 0 | CPM12_PASCALMTP_v561 | Pascal v5.61 |
| | 1 | CPM26_TPASCAL_v300a | Turbo Pascal v3.00a |
| | 2–11 | CPM13–22_MTPUG_01–10 | Pascal User Group Disks 01–10 |
| 2 | 0–2 | CPM23–25_PLI / PLI80 | PLI Compiler, PLI 80 v1.3, v1.4 |
| | 3 | CPM28_PLM80 | PLM 80 |
| | 4–6 | CPM27,30,31_WORDSTAR | WordStar v3.0, v3.3, v4.0 |
| 3–6 | 0–9 | CPM_MC_C0–F9 | Grant Searle CP/M collection disks C0–F9 |

--------------------------------------------------------------------------------------------------------

## <font style="color: yellow;" size="6">Manuals</font>

<div style="text-align: justify">
Detailed documentation for the Rom Filing System is available in three separate manuals:
</div>
<div style="padding-top: 0.8em;"></div>

| Manual | Description |
|--------|-------------|
| [User Manual](/sharpmz-upgrades-rfs-usermanual/) | Getting RFS, monitor command reference, using SD drives, BASIC, CP/M, and troubleshooting |
| [Technical Guide](/sharpmz-upgrades-rfs-technicalguide/) | Hardware platforms, memory architecture, bank switching, SDCFS design, CP/M CBIOS, and full build system reference |
| [Developer's Guide](/sharpmz-upgrades-rfs-developersguide/) | Z80 assembly primer, full source module walkthroughs (including bank-switching internals), and guides for adding new commands and hardware targets |

--------------------------------------------------------------------------------------------------------

## <font style="color: yellow;" size="6">Credits</font>

<div style="text-align: justify">
Where any component is based on or derived from a third-party design, the original author's copyright notice is included in the relevant source file header. All third-party software is, to the best of knowledge, open source and freely usable. If any component is found to carry licensing restrictions it will be removed and a suitable link provided instead.
</div>

--------------------------------------------------------------------------------------------------------

## <font style="color: yellow;" size="6">Licenses</font>

<div style="text-align: justify">
This design, hardware and software, is licensed under the GNU Public Licence v3.
<br><br>
No commercial use to be made of this design or any hardware/firmware component without express permission from the author. This condition overrides any rights afforded by the GNU GPL 3 license.
</div>

### <font style="color: yellow;" size="5">The Gnu Public License v3</font>

<div style="text-align: justify">
 The source and binary files in this project marked as GPL v3 are free software: you can redistribute them and-or modify them under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
<br><br>

 The source files are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
<br><br>

 You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
</div>