tranZPUter Filing System — User Manual

TZFS User Manual

The tranZPUter Filing System (TZFS) is a Z80 assembly language firmware package for the tranZPUter family of Z80 enhancement boards. It is a port of the Rom Filing System (RFS) adapted to the tranZPUter's architecture: instead of programming a physical Flash ROM card, TZFS is loaded automatically by the tranZPUter's on-board I/O processor (K64F or ZPU) from SD card into the board's 512 KB RAM at every boot. The result is an expanded monitor that adds SD card filing, CP/M 2.2 boot, a built-in Z80 assembler and disassembler, hardware machine emulation, soft CPU switching, VGA output control, and more than 40 new commands — all while keeping the familiar SA-1510 * prompt and every original command intact.
This manual covers everything needed to get started and use TZFS day-to-day. For hardware architecture and build system details see the Technical Guide. For source code internals and firmware development see the Developer's Guide.

Supported Hardware

TZFS supports five hardware platforms, each selected at compile time via build flags. The resulting firmware image and available feature set differ between targets. Commands marked (T) in the monitor command reference are available only on the tranZPUter SW, SW-700, and Fusion platforms. These commands are absent on FusionX and picoZ80, where the equivalent functionality is handled natively by the FPGA or RP2350.
Platform Build Flag Description Limitations
tranZPUter SW BUILD_MZ700 (default) Original tranZPUter design. The FPGA implements hardware emulation of all Sharp MZ models, the T80 soft-core Z80 CPU, the ZPU Evolution soft CPU, and VGA output. The K64F I/O processor handles SD card access and other soft services. None — full feature set.
tranZPUter SW-700 v1.3 BUILD_MZ700 Current production model. Refined PCB layout of the SW. Same FPGA and K64F capabilities, full feature set. None — full feature set.
tranZPUter Fusion BUILD_MZ700 Combines the tranZPUter board with an FPGA video module. Same FPGA and K64F capabilities, full feature set. None — full feature set.
tranZPUter FusionX BUILD_FUSIONX FPGA-based virtual implementation of the tranZPUter. Hardware emulation, CPU switching, and VGA control are handled natively by the FPGA. Hardware emulation, CPU switching, and VGA commands (T) are not available via TZFS. All file, tape, and memory commands are available.
picoZ80 BUILD_PICOZ80 RP2350-based Z80 replacement board. Same architectural division as FusionX — FPGA/RP2350 handles low-level hardware functions. Same limitations as FusionX: no (T) commands via TZFS. All file, tape, and memory commands are available.
Additional build flags BUILD_MZ80A, BUILD_MZ1500, and BUILD_MZ2000 select the target MZ model when building for non-MZ-700 machines. These affect default tape timing and certain memory map constants but do not change the command set.

Getting TZFS

Pre-built firmware images are available in the releases/ directory of the GitHub repository and can be used directly without any build tools. Unlike RFS, TZFS does not require programming any physical ROM chips — the K64F or ZPU I/O processor loads the TZFS firmware from the SD card into the tranZPUter's 512 KB RAM automatically at every boot.
To install TZFS, copy the pre-built firmware binary and accompanying SD card files onto a FAT-formatted micro SD card and insert it into the tranZPUter board's SD card slot. The I/O processor will detect the firmware at boot and load it transparently before the Z80 is released from reset.
To build from source, clone the repository and run: 
./build.sh
The build script assembles TZFS for the default target (BUILD_MZ700). Pass the appropriate flag to target a different platform: 
./build.sh BUILD_FUSIONX=1      # FusionX build
./build.sh BUILD_PICOZ80=1      # picoZ80 build
./build.sh BUILD_MZ80A=1        # MZ-80A target (SW/SW-700/Fusion)
Once built, copy the output binary to the SD card alongside the SD card file collection. See the Technical Guide — Build System for full details of the build process and output layout.

First Boot

Insert the SD card, connect the tranZPUter board to a compatible Sharp MZ machine, and power on. The K64F or ZPU I/O processor loads the TZFS firmware into the tranZPUter's 512 KB RAM. The Z80 is then released from reset and executes TZFS directly. The familiar SA-1510 sign-on banner appears, appended with "+ TZFS" to confirm that TZFS initialised successfully: 
SHARP MZ-80A
Monitor SA-1510  + TZFS

*
The * is the standard SA-1510 monitor prompt. All original SA-1510 commands work exactly as they did on the unmodified machine. Type H to display a paginated help screen listing all TZFS commands. Press Space to advance through pages.
If the + TZFS text is absent, TZFS did not initialise correctly. The most common causes are a missing or incorrectly prepared SD card, or a firmware binary that does not match the target hardware platform. Check that the SD card is properly inserted and contains the correct TZFS firmware binary for your board variant.

TZFS Monitor Commands

The complete TZFS command set is listed below. Commands marked (T) are available only on the tranZPUter SW, SW-700, and Fusion platforms (those carrying the K64F I/O processor). These commands are absent on FusionX and picoZ80 builds, where the equivalent hardware functions are provided natively.
Command Parameters Description
4 — Switch to 40-column display mode.
8 — Switch to 80-column display mode.
ASM <address> Invoke the built-in Z80 assembler starting at <address>. Enter mnemonics line by line; assembled bytes are written to RAM and the address advances automatically.
B — Enable or disable the key-entry beep.
BASIC — Locate SA-5510 BASIC on the SD card, load and execute it.
CD [<directory>] Change the active SD card directory. With no argument, prints the current path. Supports standard directory navigation.
CP <src> <dst> <size> Copy a block of memory. All arguments are 4-digit hex: source address, destination address, byte count.
CPM — Load CP/M 2.2 from SD card and boot.
D <addr> [<addr2>] Hex and ASCII dump of memory from <addr> to <addr2> (or 20 lines if no end address). Pauses at each screenful; press D to page down, U to page up, X to exit.
DASM <addr> [<addr2>] Disassemble Z80 machine code from <addr> to <addr2>. Displays address, hex bytes, and mnemonic.
DIR [<wildcard>] Paged directory listing of the active SD card directory. Optional wildcard pattern, e.g. DIR *.MZF.
EC <name or file no.> Erase a file from the SD card by name or by number.
EX — Exit TZFS and restart the machine in its original mode (without TZFS).
F [<drive>] Boot from floppy disk. Prompts for a drive number if not supplied.
FILL <start> <end> [,<value>] Fill memory from <start> to <end> with <value> (default 0x00).
FREQ <kHz> Set the CPU frequency in kHz. 0 restores the board default. Uses the K64F service request API.
H — Display the paginated help screen. Press Space to advance.
J <address> Jump to (execute from) the given hex address.
L / LT [<filename>] [,<M>] Load from tape (CMT) and execute. Optional ,M specifies machine model for tape timing (see Tape Operations).
LTNX [<filename>] [,<M>] Load from tape without executing.
LC <name or no.> [,<M>] Load a program from SD card and execute. Optional ,M specifies the target machine model.
LCNX <name or no.> [,<M>] Load from SD card without executing.
M <address> Interactive memory editor. Shows the address and current value; type a hex value to write, press Enter to skip, Ctrl-C to exit.
MZ (T) [<mc>] Activate hardware emulation for machine code mc. If omitted, defaults to MZ-80A. Valid codes: 80K, 80C, 1200, 80A, 700, 800, 80B, 2000.
MZ80K (T) — Activate Sharp MZ-80K hardware emulation.
MZ80C (T) — Activate Sharp MZ-80C hardware emulation.
MZ1200 (T) — Activate Sharp MZ-1200 hardware emulation.
MZ80A (T) — Activate Sharp MZ-80A hardware emulation.
MZ700 (T) — Activate Sharp MZ-700 hardware emulation.
MZ1500 (T) — Activate Sharp MZ-1500 hardware emulation.
MZ800 (T) — Activate Sharp MZ-800 hardware emulation.
MZ80B (T) — Activate Sharp MZ-80B hardware emulation.
MZ2000 (T) — Activate Sharp MZ-2000 hardware emulation.
MZ2200 (T) — Activate Sharp MZ-2200 hardware emulation.
MZ2500 (T) — Activate Sharp MZ-2500 hardware emulation.
P — Run a test on the connected printer.
R — Run a comprehensive DRAM memory test (0x1200–0xCFFF). Reports any failed addresses.
RIO <port> Read an I/O port and print the value. Port is 4-digit hex.
S / ST <start> <end> <exec> [,<M>] Save a memory range to tape (CMT). Prompts for a filename. Optional ,M for machine tape timing.
SC <start> <end> <exec> Save a memory range to SD card. Prompts for a filename.
SD2T <name or no.> [,<M>] Copy a file from SD card to tape (CMT). Optional ,M for machine model tape timing.
T — Test the 8253 timer chip.
T2SD [B] [,<M>] Copy tape to SD card. The B flag loads in Bulk mode (multiple files back-to-back). Optional ,M for machine model.
T80 (T) — Switch from the hardware Z80 to the internal soft T80 CPU core.
TC [-]<value> Set tape delay compensation in steps. Use - prefix to decrease, no prefix to increase. Run with no arguments to show the current value.
V — Verify a file saved to tape against the data currently in memory.
VBORDER (T) <colour> Set the VGA output border colour (0–15).
VGA (T) <mode> Set the VGA output mode (0=off, 1=640×480, 2=800×600).
VMODE (T) <mode> Set the active video mode for the emulated machine.
WIO <port> <value> Write <value> (2-digit hex) to I/O port <port> (4-digit hex). Useful for hardware debugging.
Z80 (T) — Switch from the soft CPU back to the hard (external) Z80.
ZPU (T) — Switch to the ZPU Evolution soft CPU core and boot zOS.

Tape Operations

TZFS retains full CMT (cassette) support alongside the SD card filing system. All original tape commands work as they did on the unmodified SA-1510 monitor. TZFS extends them with machine model timing selection and adds convenience commands for transferring files between tape and SD card.
Loading from Tape
Use L (or its alias LT) to load a program from tape and execute it. Use LTNX to load without executing. An optional filename can be specified — if given, TZFS searches the tape until it finds a matching header. Without a filename, the first file encountered is loaded.
The optional ,M parameter selects the machine model whose tape timing parameters are used for the load. This is needed when reading tapes made on a different MZ model that uses different baud rates or bit-cell widths.
Code Machine model
K Sharp MZ-80K
C Sharp MZ-80C
1 Sharp MZ-1200
A Sharp MZ-80A
7 Sharp MZ-700
8 Sharp MZ-800
B Sharp MZ-80B
2 Sharp MZ-2000 
* L              ; Load next tape file and execute (default timing)
* LT INVADERS    ; Search for INVADERS on tape and execute
* LTNX ,7        ; Load next file using MZ-700 tape timing, no execute
Saving to Tape
Use S (or ST) to save a memory range to tape. Provide start address, end address, and execution address as consecutive 4-digit hex values, then type the filename when prompted. The optional ,M parameter selects the tape timing for the target machine model: 
* S120020001200
FILE NAME? MYPROG
SAVING...
Verifying a Tape Save
Use V immediately after saving to verify that what was written to tape matches the data still in memory. TZFS reads the tape back and compares it byte by byte, reporting any mismatches.
Copying Tape to SD Card
T2SD loads the next file from tape and saves it directly to the active SD card directory. Press Play on the tape deck before running the command. The optional B flag enables Bulk mode, which reads files back-to-back from the tape until the end of the tape is reached or an error occurs — useful for archiving an entire tape side to SD card in one operation. The optional ,M parameter selects tape timing as described above: 
* T2SD          ; Copy next tape file to SD card (default timing)
* T2SD B        ; Bulk copy — read all files from tape to SD card
* T2SD B,7      ; Bulk copy using MZ-700 tape timing
Copying SD Card to Tape
SD2T loads a named file (or file by number) from the active SD card directory and writes it to tape exactly as if performing a tape-to-tape copy. Press Record on the tape deck when prompted. The optional ,M parameter selects the tape timing for the write: 
* SD2T INVADERS      ; Write INVADERS from SD card to tape
* SD2T 04,7          ; Write file 04 to tape using MZ-700 timing
Tape Delay Compensation
Different CMT decks and tape heads have slightly different read/write timing characteristics. The TC command adjusts a compensation value that is applied to all tape timing calculations. Run TC with no arguments to display the current value. Use TC without a prefix to increase compensation, or TC with a - prefix to decrease it. Adjusting by one or two steps at a time is usually sufficient to resolve intermittent load failures caused by tape head speed variations: 
* TC            ; Display current compensation value
* TC 2          ; Increase compensation by 2 steps
* TC -1         ; Decrease compensation by 1 step

SD Card Operations

TZFS uses the tranZPUter's K64F or ZPU I/O processor to access a FAT-formatted SD card via a service request API. Files are stored as standard MZF-format files in a conventional directory structure, making it straightforward to manage the SD card from a PC. All SD card commands operate on the currently active directory, which can be changed with CD.
Listing the Directory
Use DIR to display a paged listing of the active SD card directory. An optional wildcard pattern restricts the listing: 
* DIR               ; List all files in the active directory
* DIR *.MZF         ; List only .MZF files
* DIR INVADERS*     ; List files whose names begin with INVADERS
Each listing entry shows a file number and the filename. The listing pauses at each screenful; press Space to continue.
Changing Directory
Use CD to navigate the SD card directory structure. With no argument, CD displays the current path. Standard directory navigation applies: 
* CD                ; Show current directory path
* CD MZ700          ; Change into subdirectory MZ700
* CD ..             ; Move up one level
Loading Programs
Use LC to load a program from the active SD card directory and execute it. Use LCNX to load without executing. Files can be specified by name or by the number shown in the DIR listing. Loading by number is faster as no string matching is required. The optional ,M parameter specifies the target machine model for programs designed for a different MZ variant: 
* LC INVADERS        ; Load INVADERS from the active directory and execute
* LCNX INVADERS      ; Load without executing (useful for debugging)
* LC 04              ; Load file number 04 and execute
* LC STARTREK,7      ; Load STARTREK targeting MZ-700 memory model
Saving Programs
Use SC to save a memory range to the active SD card directory. The syntax is the same as the tape S command — start address, end address, and execution address as consecutive 4-digit hex values, followed by a filename when prompted: 
* SC120020001200
FILE NAME? MYPROG
SAVED
Erasing Files
Use EC to erase a file from the active SD card directory. The file can be identified by name or by the number shown in the DIR listing: 
* EC OLDPROG         ; Erase file named OLDPROG
* EC 07              ; Erase file number 07

Hardware Emulation

This feature is available on tranZPUter SW, SW-700, and Fusion platforms only (T).
The tranZPUter's FPGA implements hardware-level emulation of the full Sharp MZ family. When a hardware emulation command is issued, the TZFS firmware asks the K64F to load the correct monitor ROM for the target machine from the SD card into SRAM (for example, 1Z-013A for the MZ-700, or SA-1510 for the MZ-80A). Once loaded, the FPGA reconfigures its video and memory mapping logic to match the target machine and the machine restarts in full compatibility mode. From that point, software designed for the target model runs without modification — the host machine is, at the hardware level, the target machine.
The MZ command activates emulation for a named machine code. The individual named commands (MZ80K, MZ700, etc.) are convenience aliases for the most common models: 
* MZ 700         ; Activate MZ-700 hardware emulation
* MZ700          ; Equivalent alias
* MZ             ; Activate MZ-80A emulation (default)
* MZ 2000        ; Activate MZ-2000 hardware emulation
The full list of supported emulation targets is given in the command table above. Note that MZ-2200 and MZ-2500 emulation entries are present but depend on monitor ROM availability on the SD card.
To return to the host machine's native mode after emulation, issue the appropriate MZ command for the host (e.g. MZ80A if the host is an MZ-80A) or power-cycle the machine. Hardware emulation changes persist across soft resets.

CPU Switching

This feature is available on tranZPUter SW, SW-700, and Fusion platforms only (T).
The tranZPUter's FPGA implements two soft CPU cores alongside the hard external Z80: T80 (a soft-core Z80 implementation) and ZPU Evolution (a 32-bit stack CPU). Switching CPUs asks the K64F to load any required firmware before the FPGA activates the requested core. TZFS exposes three commands for this:
Command Description
Z80 Switch back to the hard (external) Z80. This is the default state after boot.
T80 Switch to the T80 soft-core Z80 implemented in the FPGA.
ZPU Switch to the ZPU Evolution soft CPU implemented in the FPGA and boot zOS, the ZPU operating system.
After switching, TZFS firmware continues running on the new CPU without interruption to the user session. The Z80, T80, and ZPU cores share the same 512 KB RAM space, so the memory contents visible before and after a switch are identical. CPU switching is transparent to programs that do not depend on cycle-exact Z80 timing.
The FREQ command allows the CPU clock frequency to be adjusted independently of switching (communicated via the K64F service API): 
* T80            ; Switch to soft T80 core
* Z80            ; Switch back to external Z80
* ZPU            ; Switch to ZPU Evolution core and boot zOS
* FREQ 4000      ; Set CPU frequency to 4 MHz
* FREQ 0         ; Restore board default frequency

Video Control

This feature is available on tranZPUter SW, SW-700, and Fusion platforms only (T).
The tranZPUter FPGA provides VGA video output. Three commands control it:
Command Parameters Description
VGA <mode> Set the VGA output mode. 0 = off, 1 = 640×480, 2 = 800×600.
VBORDER <colour> Set the VGA border colour (0–15). Colour values follow the standard Sharp MZ palette.
VMODE <mode> Set the active video mode for the emulated machine. Mode values depend on the active hardware emulation target. 
* VGA 1          ; Enable VGA output at 640x480
* VGA 2          ; Enable VGA output at 800x600
* VGA 0          ; Disable VGA output
* VBORDER 4      ; Set border colour to 4
* VMODE 2        ; Set video mode 2 for the active emulation target
The 40-column and 80-column display switching commands (4 and 8) are available on all platforms and switch the character cell width independently of VGA output.

Using BASIC

TZFS can locate and load the Sharp SA-5510 BASIC interpreter from the SD card automatically. From the monitor prompt, type: 
* BASIC
TZFS searches the active SD card directory for the SA-5510 BASIC image, loads it into RAM, and executes it. The BASIC prompt appears and the interpreter operates as it would on the original hardware.
BASIC programs stored on the SD card as MZF files can be loaded from within BASIC using the standard tape LOAD command directed at the appropriate file. To return to the TZFS monitor from BASIC, use the BASIC BYE or MON command if available, or reset the machine and TZFS will reload automatically from the SD card.
Because TZFS loads BASIC from SD card rather than ROM, it is straightforward to keep multiple BASIC versions on the SD card and load the one appropriate for the current hardware emulation target. For example, when running under MZ-700 hardware emulation, load the MZ-700 BASIC image rather than the SA-5510.

Running CP/M 2.2

CP/M 2.2 is available on all TZFS platforms. From the monitor prompt: 
* CPM
TZFS will locate the CP/M image on the active SD card directory, load it, and transfer control to the CP/M CCP. The prompt changes to A>.
CP/M access to disk drives is provided through the tranZPUter's K64F or ZPU I/O processor service API, which translates CP/M BIOS calls into SD card file operations. The pre-built SD card image includes a populated CP/M disk area with a selection of CP/M applications and utilities.
To return to the TZFS monitor from CP/M, use a warm boot (Ctrl-C from the CCP) which reloads the CCP. To return fully to TZFS, use the EX command from the monitor prompt after the CP/M session ends, or power-cycle the machine — TZFS will reload automatically from SD card.

Troubleshooting

Monitor boots but "TZFS" is not shown in the banner

  • SD card not inserted or not detected — check the card is fully seated in the tranZPUter board's SD card slot.
  • Wrong firmware binary on SD card — ensure the TZFS binary matches your board variant (SW/SW-700/Fusion, FusionX, or picoZ80). Mixing firmware builds between hardware targets will cause load failures.
  • SD card not FAT-formatted — the K64F/ZPU I/O processor expects a standard FAT-formatted card. Re-format the card and copy the TZFS firmware and SD card files again.
  • I/O processor firmware outdated — ensure the K64F or ZPU I/O processor is running a firmware version that supports the TZFS service request API. Check the GitHub releases page for compatible I/O processor firmware.

Hardware emulation, CPU switching, or VGA commands are not recognised

  • Running on FusionX or picoZ80 — commands marked (T) are not available on these platforms. The equivalent functionality is provided natively by the FPGA or RP2350. This is expected behaviour, not a fault.
  • Wrong build target — verify the TZFS firmware was built with the correct flag for your hardware (e.g. BUILD_FUSIONX=1 for FusionX). A mismatch can result in commands being silently absent.

Tape loads fail or produce errors

  • Tape timing mismatch — if the tape was recorded on a different MZ model, use the ,M parameter to select the appropriate machine model timing (see Tape Operations).
  • Tape head speed variation — use the TC command to adjust tape delay compensation. Increasing or decreasing by one or two steps usually resolves intermittent failures.
  • Tape condition — aged or poorly stored tapes may have drop-outs. Try cleaning the tape head and capstan with isopropyl alcohol before retrying.

CP/M does not boot or shows BIOS errors

  • CP/M image not present on SD card — ensure the SD card contains the CP/M boot image in the directory that was active when CPM was typed. Use DIR to confirm.
  • Wrong active directory — navigate with CD to the directory containing the CP/M image before typing CPM.
  • I/O processor service timeout — if the K64F or ZPU does not respond to a BIOS service request within the expected window, CP/M will stall. Power-cycle the board and retry. If the problem persists, check I/O processor firmware compatibility.

Machine crashes or resets unexpectedly after loading a program

  • Program targets wrong machine model — programs written for a specific MZ model may crash on a different model. Activate the appropriate hardware emulation before loading (e.g. MZ700 before loading MZ-700 software).
  • Program overwrites TZFS workspace — TZFS reserves areas of the tranZPUter's 512 KB RAM for its own use. Programs that use all of the lower 64 KB may corrupt TZFS data structures. Use LCNX rather than LC to load without executing, and inspect the load address with D before running.

Reference Sites

Resource Link
TZFS project page /sharpmz-upgrades-tzfs/
TZFS Technical Guide /sharpmz-upgrades-tzfs-technicalguide/
TZFS Developer’s Guide /sharpmz-upgrades-tzfs-developersguide/
tranZPUter SW project page /tranzputer/
tranZPUter Fusion project page /tranzputerfusion/
picoZ80 (RP2350 Z80 replacement) /picoz80/
RFS User Manual (companion firmware) /sharpmz-upgrades-rfs-usermanual/
Sharp MZ Series technical reference Bundled in repository docs/ directory