RetroShield Z80 Emulator (Rust)

A Z80 emulator written in Rust for testing RetroShield Z80 firmware. Includes a simple passthrough emulator, a full-featured TUI debugger, and a WebAssembly build for browser-based emulation.

Features

• Z80 emulation using the rz80 crate
• Dual serial chip emulation:
  • MC6850 ACIA (ports $80/$81) - used by MINT, Firth, Monty, Retro Pascal
  • Intel 8251 USART (ports $00/$01) - used by Grant's BASIC, EFEX
• Three emulator modes:
  • retroshield - Simple passthrough (stdin/stdout)
  • retroshield_tui - Full TUI debugger with registers, disassembly, stack, memory view
  • WebAssembly - Browser-based emulation with JavaScript API

Building

Native (TUI and Passthrough)

cargo build --release

Binaries will be in target/release/.

WebAssembly

To build for the browser, you'll need wasm-pack:

# Install wasm-pack if you don't have it
cargo install wasm-pack

# Build the WASM package
wasm-pack build --target web --out-dir pkg

This produces:

• pkg/retro_z80_emulator.js - JavaScript bindings
• pkg/retro_z80_emulator_bg.wasm - WebAssembly binary

Using in a Web Page

<script type="module">
import init, { Z80Emulator } from './pkg/retro_z80_emulator.js';

async function main() {
    await init();
    const emulator = new Z80Emulator();

    // Load a ROM
    const response = await fetch('rom.bin');
    const data = new Uint8Array(await response.arrayBuffer());
    emulator.load_rom(data);

    // For 8251-based ROMs (like Grant's BASIC)
    // emulator.set_8251_mode(true);

    // Run emulation loop
    function runLoop() {
        emulator.run(50000);  // Run 50000 cycles

        // Get any output from the serial port
        const output = emulator.get_output_string();
        if (output.length > 0) {
            console.log(output);
        }

        requestAnimationFrame(runLoop);
    }
    runLoop();

    // Send keyboard input
    document.addEventListener('keydown', (e) => {
        if (e.key === 'Enter') {
            emulator.send_char(13);
        } else if (e.key.length === 1) {
            emulator.send_char(e.key.charCodeAt(0));
        }
    });
}

main();
</script>

WASM API

Usage

Passthrough Emulator

Simple emulator that connects stdin/stdout directly to the emulated serial port:

./target/release/retroshield [OPTIONS] <rom.bin>

Options:
  -d          Debug mode (prints load info)
  -c <cycles> Run for specified cycles then exit

TUI Debugger

Full-screen debugger with register display, disassembly, stack view, memory view, and terminal:

./target/release/retroshield_tui <rom.bin>

TUI Layout

┌─ Registers ─────────┬─ Disassembly ──────────┬─ Stack ─────────┐
│ PC:0075  SP:FFC2    │ >0075: LD A,($2043)    │>FFC2: 0075      │
│ AF:0042  BC:010D    │  0078: CP $00          │ FFC4: 0120      │
│ DE:215C  HL:20A6    │  007A: JR Z,$0075      │ FFC6: 0000      │
│ IX:0000  IY:0000    │                        ├─ CPU State ─────┤
│ Flags: -Z----N-     │                        │ IM:1 IFF1:1     │
├─ Memory @ $2000 ────┤                        │ HALT:0 I:00 R:7F│
│ 2000: 00 0D 50 52...├────────────────────────┴─────────────────┤
│ 2010: 57 20 57 4F...│ Terminal                                 │
│ ...                 │ Z80 BASIC Ver 4.7b                       │
│                     │ Ok                                       │
│                     │ █                                        │
└─────────────────────┴──────────────────────────────────────────┘
[RUNNING] Z80:31.16MHz CPU:5.8% Mem:8.5MB F5:Run F6:Step F12:Quit

TUI Controls

The TUI starts in paused mode. Press F5 to run or F6 to step.

Status Bar

The status bar shows:

• State - RUNNING, PAUSED, or HALTED
• Z80 MHz - Effective emulated clock speed
• CPU% - Host CPU usage
• Mem MB - Host memory usage
• Cyc - Total Z80 cycles executed

I/O Ports

MC6850 ACIA (ports $80/$81)

Intel 8251 USART (ports $00/$01)

Interrupt Support

• IM 1 - Manually simulated (RST 38H) for 8251-based ROMs
• IM 2 - Supported via rz80 crate

Included ROMs

The roms/ directory contains pre-built ROM binaries for testing:

Examples

# Run MINT
./target/release/retroshield roms/mint.z80.bin

# Run Grant's BASIC with TUI
./target/release/retroshield_tui roms/grantz80_basic_new.bin

# Run Firth Forth
./target/release/retroshield roms/firth.z80.bin

# Run Retro Pascal with TUI
./target/release/retroshield_tui roms/pascal.bin

Dependencies

Native

• rz80 - Z80 CPU emulation
• ratatui - Terminal UI framework
• crossterm - Terminal manipulation
• sysinfo - System metrics
• libc - Non-blocking stdin (Unix)

WebAssembly

• wasm-bindgen - JavaScript interop

License

MIT License - see LICENSE

See Also

• RetroShield Z80 - Hardware platform by 8bitforce
• retroshield-arduino - Arduino sketches for RetroShield
• C Emulator - Original C implementation with notcurses TUI