TinyComputers.io (Posts about wifi)

Playing Zork on a Real Z80: From CP/M Boot to the Great Underground Empire

A.C. Jokela — Sun, 15 Feb 2026 12:00:00 GMT

This is the third post in a series about running CP/M 2.2 on a real Z80 processor connected to an Arduino Giga R1 WiFi. The first post covered getting the custom level converter shield designed and manufactured. The second post documented the hardware stack, the catastrophic TXB0108 level converter failures, the shadow register workaround, and the Rust sector server that provides disk I/O over WiFi. That post ended with a promise: CP/M was close to booting, and all the pieces were in place.

This post is about keeping that promise. It covers the final debugging push from "almost boots" to a fully interactive game of Zork I running on real Z80 hardware, and the performance crisis that nearly made the whole thing unusable.

The Story So Far

The hardware is straightforward: a RetroShield Z80 (a real Zilog Z80 CPU on a shield board) plugged into an Arduino Giga R1 WiFi through a custom level converter PCB. The Giga's STM32H747 (480MHz Cortex-M7) provides 64KB of Z80 RAM as a byte array in its internal SRAM, clocks the Z80, and serves memory read/write requests. Disk I/O goes over WiFi to a Rust TCP sector server instead of an SD card.

The level converter uses nine TXB0108 bidirectional level shifters to bridge the Giga's 3.3V logic and the RetroShield's 5V. And those TXB0108s are the source of almost every interesting engineering decision in the project. Their auto-direction sensing fails for several Z80 bus signals: IORQ_N and RD_N are permanently stuck, WR_N only works during memory cycles, and the data bus is invisible from Z80-to-Arduino during I/O operations. The address bus works but lags by 1-3 clock ticks through the converter.

These failures forced a fundamentally different approach to interfacing with the Z80. Instead of passively watching bus signals, the Arduino actively decodes the Z80's instruction stream and maintains software copies of the CPU's internal state:

Guard-only M1 detection: a timing table (tStates[256]) tells us how many clock cycles each instruction takes; the next memory read after the guard expires is the next opcode fetch
Software PC (softPC): a software copy of the Z80's program counter, immune to address bus lag
Shadow registers: software copies of A, B, C, D, E, H, L, F, and SP, updated by decoding each opcode from z80RAM[softPC]
Pre-writes: memory store instructions write their values directly to z80RAM at opcode detection time, using shadow register values and softPC-derived addresses, because the Z80's physical bus writes go to wrong addresses due to the propagation delay
Deferred writes: for read-modify-write instructions like INC (HL), where pre-writing would cause the Z80 to read an already-modified value and double-apply the operation

The full technical details of this architecture are in the previous post. What matters here is where that post left off: the shadow register system was working, the sector server was serving disk images over WiFi, and partial serial output confirmed that the Z80 was executing real code. What remained was completeness testing, making sure every instruction the Z80 actually executed was tracked correctly in the shadows.

CP/M Boots

The first milestone came faster than expected. After expanding the shadow register switch statement to cover more of the Z80 instruction set (POP instructions, ADD HL with register pairs, DAA (decimal adjust), EX (SP),HL), CP/M booted.

The boot loader loaded all 53 sectors of CPM.SYS from the sector server over WiFi. The BIOS cold boot initialized correctly. And the console printed:

RetroShield CP/M 2.2
56K TPA

a>

A real Z80, running real CP/M 2.2, with 56KB of Transient Program Area, booting from a disk image served over WiFi from a Rust TCP server. The DIR command worked and showed the contents of drive A:

a>dir
A: ZORK1    COM : ZORK1    DAT : ZORK2    COM : ZORK2    DAT

Zork was right there, waiting.

The "Bad Load" Bug

Running ZORK1.COM produced a single line of output and then nothing:

a>zork1
Bad load

"Bad load" is a CP/M CCP (Console Command Processor) error. It means the CCP tried to load the .COM file into the TPA and something went wrong: either a disk read failed, or the CCP's internal logic decided the load was corrupt.

Finding the Root Cause

The CCP loads .COM files by repeatedly calling BDOS function 20 (Read Sequential), advancing the DMA address by 128 bytes after each successful sector read, until the file is fully loaded. The load loop lives in the CCP code at address 0xE6DE. After each BDOS call, it checks whether the DMA address has exceeded the TPA boundary at 0xE000:

E6F5: LD E,A         ; save BDOS return code
E6F6: LD A,H         ; get current DMA high byte
E6F7: SUB E           ; compare against...
E6F8: LD A,H          ; (for SBC below)
E6F9: SBC A,D         ; ...TPA boundary
E6FB: JP NC,E771      ; if past TPA, stop loading

The SBC A,D instruction at E6F9 (opcode 0x9A) subtracts the D register and the carry flag from A. This is a 16-bit comparison implemented as a high-byte subtract-with-borrow after the low-byte subtract at E6F7.

The problem: opcode 0x9A was not in the shadow register tracking. The switch statement had SBC A,A (0x9F), SBC A,B (0x98), and SBC A,C (0x99), but not SBC A,D.

Without tracking, the SBC A,D instruction didn't update shadowF. The carry flag in the shadow still reflected the preceding SUB E instruction, which had set carry=0 (no borrow, since 0x80 - 0x00 = 0x80). But the real Z80 computed SBC A,D with the actual register values and got carry=1 (borrow). When the JP NC,E771 branch came, our shadow said NC=true (carry clear, branch taken) while the Z80 said NC=false (carry set, branch not taken).

SoftPC jumped to the "Bad load" error handler. The real Z80 continued the load loop. From that point on, softPC and the Z80's actual program counter were desynchronized; every subsequent opcode decode was wrong, and the system was effectively running blind.

The Fix

Add the missing instructions. All of them:

// SBC A,r — subtract with carry
case 0x98: { uint16_t r = shadowA - shadowB - (shadowF & FLAG_C ? 1 : 0);
             shadowF = flagsSub8(shadowA, shadowB, r, true);
             shadowA = r & 0xFF; break; }
case 0x99: { /* SBC A,C */ ... }
case 0x9A: { /* SBC A,D */ ... }
case 0x9B: { /* SBC A,E */ ... }
case 0x9C: { /* SBC A,H */ ... }
case 0x9D: { /* SBC A,L */ ... }
case 0x9E: { /* SBC A,(HL) */ ... }

// ADC A,r — add with carry (same gap)
case 0x8A: { /* ADC A,D */ ... }
case 0x8B: { /* ADC A,E */ ... }
case 0x8C: { /* ADC A,H */ ... }
case 0x8D: { /* ADC A,L */ ... }
case 0x8E: { /* ADC A,(HL) */ ... }

After this fix, ZORK1.COM loaded all 68 sectors successfully: 8,704 bytes from DMA address 0x0100 to 0x2300, with every BDOS read returning success.

Zork Starts, Barely

With the load fixed, Zork launched. It read its .DAT file from disk. The copyright text appeared:

ZORK I: The Great Underground Empire
Copyright (c) 1981, 1982, 1983 Infocom, Inc. All rights
reserved.
ZORK is a registered trademark of Infocom, Inc.
Revision 88 / Serial number 840726

And then... nothing. Or rather, something, but at glacial speed. At approximately 18,000 Z80 clock cycles per second, the text took minutes to render. The game was technically running but practically frozen. Typing a command and waiting for a response meant staring at a blank terminal for an eternity.

On a 480MHz Cortex-M7, 18,000 Z80 cycles per second means the Arduino was spending roughly 26,000 of its own CPU cycles on every single Z80 clock tick. Something was catastrophically wrong with the hot loop.

The Performance Crisis

I added a performance counter that measured actual Z80 cycles per second. The numbers were dire: 9,000–18,000 cycles/sec depending on what the Z80 was doing. A real Z80 runs at 2.5–8 MHz. We were three orders of magnitude too slow.

Five bottlenecks were hiding in the hot loop, each one multiplying the others.

Bottleneck 1: A Two-Millisecond Nap on Every Tick

Every clock tick included delayMicroseconds(2), a 2,000-nanosecond delay to let signals settle through the TXB0108 after toggling the clock. The TXB0108's actual propagation delay is about 4–12 nanoseconds. This was a 200x safety margin I'd added early in debugging and never removed.

Fix: Replace with 24 inline NOP instructions. At 480MHz, each NOP is ~2ns, giving roughly 50ns of settle time, still 4x more than the TXB0108 needs, but 40x faster than the delay.

inline void __attribute__((always_inline)) busSettle() {
    __asm volatile("nop\nnop\nnop\nnop\nnop\nnop\nnop\nnop\n"
                   "nop\nnop\nnop\nnop\nnop\nnop\nnop\nnop\n"
                   "nop\nnop\nnop\nnop\nnop\nnop\nnop\nnop\n");
}

Bottleneck 2: Flipping 8 Pins on Every Single Tick

This was the real killer. At the end of every cpu_tick() call, setDataBusInput() was called to tri-state the data bus pins, switching all 8 data lines from output to input mode. Then at the start of the next memory read, setDataBusOutput() switched them all back. Each direction change went through the Arduino HAL pinMode() function 8 times.

On the STM32H747 with the mbed-based Arduino core, each pinMode() call involves HAL abstraction layers, pin table lookups, and clock configuration checks. Eight calls took approximately 16–32 microseconds. This was happening on every single clock tick, both directions, 16 pinMode() calls per tick.

The irony: this direction switching was completely unnecessary. Since all Z80 bus writes are suppressed (pre-writes handle memory stores in software), the data bus never needs to read anything from the Z80 during normal operation. The bus can stay in output mode permanently.

Fix: Remove the per-tick setDataBusInput() call entirely. For the rare cases where direction changes are still needed (certain IO operations), replace pinMode() with direct GPIO MODER register writes:

#define GPIO_SET_OUTPUT(port, pin) \
    ((port)->MODER = ((port)->MODER & ~(3U << ((pin)*2))) \
                     | (1U << ((pin)*2)))
#define GPIO_SET_INPUT(port, pin) \
    ((port)->MODER = ((port)->MODER & ~(3U << ((pin)*2))))

One register write per pin instead of a full HAL function call.

Bottleneck 3: Arduino HAL in the Hot Loop

The Arduino digitalRead() and digitalWrite() functions are convenient abstractions, but on the STM32H747 they carry significant overhead: pin number lookups, port mapping tables, multiple function calls per operation. The original RetroShield code for the Mega 2560 used direct AVR port registers (PORTA, PORTL) for fast parallel I/O. On the Giga, the pins are scattered across GPIO ports B, E, G, H, I, J, and K (no single-register solution), but direct register access is still orders of magnitude faster than the HAL.

Fix: Map every Arduino pin to its STM32H747 GPIO port and pin number, then replace all hot-path I/O with direct register access.

The clock signal (toggled every tick) went from ~200ns per call through HAL to ~4ns via the BSRR (Bit Set/Reset Register):

// Before
#define CLK_HIGH  digitalWrite(uP_CLK, HIGH)

// After — single atomic register write
#define CLK_HIGH  (GPIOK->BSRR = (1U << 2))    // PK2
#define CLK_LOW   (GPIOK->BSRR = (1U << 18))   // PK2 reset

The BSRR register is an elegant STM32 feature: bits [15:0] set outputs high, bits [31:16] set outputs low, and the entire operation is atomic, so no read-modify-write cycle is needed.

For the address bus (16 pins read every memory cycle), three GPIO IDR (Input Data Register) reads replace sixteen individual digitalRead() calls:

inline uint16_t readAddress() {
    uint32_t jIDR = GPIOJ->IDR;
    uint32_t kIDR = GPIOK->IDR;
    uint32_t gIDR = GPIOG->IDR;

    uint16_t addr = 0;
    if (jIDR & (1U << 12)) addr |= (1 << 0);   // A0 = PJ12
    if (gIDR & (1U << 13)) addr |= (1 << 1);   // A1 = PG13
    // ... 14 more bit extractions
    return addr;
}

For the data bus (8 pins written every memory read cycle), pins sharing the same GPIO port are combined into a single BSRR write. Port I has three data bus pins, so they get folded into one register operation:

inline void writeDataBus(byte val) {
    GPIOE->BSRR = (val & 0x01) ? (1U << 4) : (1U << 20);
    GPIOK->BSRR = (val & 0x02) ? (1U << 0) : (1U << 16);
    GPIOB->BSRR = (val & 0x04) ? (1U << 2) : (1U << 18);
    GPIOH->BSRR = (val & 0x08) ? (1U << 15) : (1U << 31);

    // Port I: combine 3 data bus pins into one write
    uint32_t iBSRR = 0;
    iBSRR |= (val & 0x10) ? (1U << 13) : (1U << 29);  // PI13
    iBSRR |= (val & 0x40) ? (1U << 10) : (1U << 26);  // PI10
    iBSRR |= (val & 0x80) ? (1U << 15) : (1U << 31);  // PI15
    GPIOI->BSRR = iBSRR;

    GPIOG->BSRR = (val & 0x20) ? (1U << 10) : (1U << 26);
}

Bottleneck 4: USB Serial Polling Every Tick

The MC6850 ACIA emulation checked Serial.available() on every clock tick to detect incoming keystrokes. On the Giga, USB CDC serial operations are expensive; each call may involve USB stack processing. At 700K ticks/sec, checking every tick means 700,000 USB stack queries per second.

Fix: Check every 256 ticks. That's still a 2,700 Hz polling rate, more than fast enough for interactive typing, and it eliminates 99.6% of the USB overhead.

if ((clock_cycle_count & 0xFF) == 0) {
    if (!CONTROL_RTS_STATE && Serial.available()) {
        reg6850_STATUS |= 0b00000001;   // RDRF set
        if (CONTROL_RX_INT_ENABLE) { INT_N_LOW; }
    }
}

Bottleneck 5: I-Cache Thrashing from Forced Inlining

The cpu_tick() function is around 1,200 lines of code, dominated by the shadow register tracking switch statement with hundreds of cases. It was marked inline __attribute__((always_inline)), which forces the compiler to inline the entire function body into loop().

The STM32H747's instruction cache is 16KB. Inlining a 1,200-line function creates a binary blob that doesn't fit, causing constant cache misses. Every iteration of the main loop refills the I-cache from flash.

Fix: Change to __attribute__((noinline)). The function call overhead (a few nanoseconds for the branch and return) is negligible compared to the cache thrashing cost. This change also reduced the compiled binary by ~9KB, from 284KB to 276KB.

void __attribute__((noinline)) cpu_tick() {
    // ... 1,200 lines of bus interface and shadow tracking
}

The Result

Metric	Before	After
Z80 cycles/sec	~9,000	~690,000
Effective Z80 clock	~0.009 MHz	~0.69 MHz
Binary size	284 KB	276 KB
Time per Z80 tick	~111 µs	~1.4 µs

A 75x speedup. The system went from roughly 50,000 Cortex-M7 cycles per Z80 tick down to about 700. Enough for Zork to be fully interactive.

Network Reconnection

With the performance problem solved, a new issue appeared: the TCP connection to the sector server dropped during long idle periods. Zork is a text adventure; the player types a command, the game responds, and then nothing happens until the next command. During that idle time (which could be minutes while you think about whether to go north or east), the WiFi TCP socket would quietly die. The next disk operation would fail with "Bad Sector."

The fix was automatic reconnection logic. Before each disk operation, ensureServerConnection() checks if the TCP socket is still alive. If not, it reconnects to the sector server, re-opens the disk image file that was previously open, and re-seeks to the last position, all transparently, so the Z80 never knows the connection dropped.

bool ensureServerConnection() {
    if (server.connected()) return true;

    Serial.println("[NET] Connection lost, reconnecting...");
    server.stop();

    for (int attempt = 0; attempt < 3; attempt++) {
        if (server.connect(SERVER_IP, SERVER_PORT)) {
            Serial.println("[NET] Reconnected to server");
            if (diskFileOpen && diskActiveFile.length() > 0) {
                netSendFileCommand(DISK_CMD_OPEN_RW, diskActiveFile);
                uint8_t status = netReadStatus();
                if (status != 0) { diskFileOpen = false; return false; }
                // Re-seek to last known position
                uint8_t seekCmd[4];
                seekCmd[0] = DISK_CMD_SEEK;
                seekCmd[1] = diskSeekPos & 0xFF;
                seekCmd[2] = (diskSeekPos >> 8) & 0xFF;
                seekCmd[3] = (diskSeekPos >> 16) & 0xFF;
                server.write(seekCmd, 4);
                netReadStatus();
            }
            return true;
        }
        delay(500);
    }
    return false;
}

Your browser does not support the video tag.

Playing Zork

With all the pieces in place (shadow registers covering every instruction CP/M and Zork use, GPIO registers replacing Arduino HAL calls, network reconnection handling idle timeouts), it was time to play.

Here's a complete boot-to-gameplay session, captured from the serial terminal:

OK (192.168.0.75)
Server:     OK (192.168.0.248:9000)
Boot:       OK (512 bytes loaded)

Starting Z80...

RetroShield Z80 Boot Loader
Copyright (c) 2025 Alex Jokela, tinycomputers.io

Loading CPM.SYS.....................................................
Boot complete.

RetroShield CP/M 2.2
56K TPA

a>zork1
ZORK I: The Great Underground Empire
Copyright (c) 1981, 1982, 1983 Infocom, Inc. All rights
reserved.
ZORK is a registered trademark of Infocom, Inc.
Revision 88 / Serial number 840726

West of House
You are standing in an open field west of a white house, with
a boarded front door.
There is a small mailbox here.

>open mailbox
Opening the small mailbox reveals a leaflet.

>take leaflet
Taken.

>go south
South of House
You are facing the south side of a white house. There is no
door here, and all the windows are boarded.

>go east
Behind House
You are behind the white house. A path leads into the forest
to the east. In one corner of the house there is a small
window which is slightly ajar.

>open window
With great effort, you open the window far enough to allow
entry.

>enter
Kitchen
You are in the kitchen of the white house. A table seems to
have been used recently for the preparation of food. A passage
leads to the west and a dark staircase can be seen leading
upward. A dark chimney leads down and to the east is a small
window which is open.
On the table is an elongated brown sack, smelling of hot
peppers.
A bottle is sitting on the table.
The glass bottle contains:
  A quantity of water

Every command produces the correct response, at interactive speed. The text appears as fast as you'd expect from a terminal session, with no perceptible delay between pressing Enter and seeing the game's response.

How It All Fits Together

Here's what happens when you type open mailbox at the Zork prompt, end to end:

Each keystroke arrives over USB serial. Every 256 Z80 clock ticks, the Arduino checks Serial.available(), finds a character, and sets the MC6850 ACIA status register's RDRF bit.
The Z80 is spinning in the BIOS console input loop, repeatedly executing IN A,(0x80) to check the ACIA status register. Our shadow register system detects each IN instruction at M1 time, calls handle_io_read(0x80), and drives the status byte onto the data bus during the IO cycle.
When RDRF is set, the Z80 executes IN A,(0x81) to read the character. We return the byte from Serial.read(), and shadowA gets updated to match.
The BIOS echoes the character by executing OUT (0x81),A. We detect this at M1 time, use shadowA for the data value, and call Serial.write().
When the user presses Enter, the CCP passes the command to Zork. Zork parses it and starts executing game logic, hundreds of thousands of Z80 instructions manipulating its internal data structures.
When Zork needs to read from its .DAT file, the BIOS executes a sequence of OUT instructions to set up the disk operation: filename characters to port 0x13, seek position to ports 0x14/0x15/0x19, DMA address to ports 0x16/0x17, and a block read command to port 0x18. Each OUT is intercepted by the shadow register system and forwarded to the sector server over WiFi.
The sector server reads 128 bytes from the disk image file, sends them back over TCP. The Arduino writes them directly into z80RAM at the DMA address.
Zork processes the data, generates response text, and prints it character by character through the ACIA, each character going through the same OUT (0x81),A → shadowA → Serial.write() path.

Every single one of these operations relies on the shadow register system. The Z80 has no idea the Arduino can't see half its bus signals. It thinks it's talking to normal memory and I/O ports. The Arduino, meanwhile, is running a parallel simulation of the Z80's register state, intercepting every instruction, and making the illusion seamless.

The Full Architecture

For reference, here's the complete technical stack:

Hardware: - Arduino Giga R1 WiFi (STM32H747, 480MHz Cortex-M7, 1MB SRAM, WiFi) - RetroShield Z80 (real Zilog Z80 CPU, 5V logic) - Custom level converter PCB (nine TXB0108PW, design details here)

Z80 Memory: - 64KB byte array in Giga's internal SRAM (uint8_t z80RAM[65536])

Bus Interface (direct STM32 GPIO registers): - Clock: GPIOK pin 2 (BSRR for set/clear) - Address: 3 IDR reads (GPIOJ, GPIOK, GPIOG) → 16-bit extraction - Data: 6 BSRR writes (GPIOE, GPIOK, GPIOB, GPIOH, GPIOI combined, GPIOG) - Control: MREQ via GPIOK pin 7, WR via GPIOE pin 6

Software Architecture: - Guard-only M1 detection with tStates[256] timing table - Software PC tracking (softPC) for all branch types including conditional - Shadow registers (A, B, C, D, E, H, L, F, SP) with full ALU flag computation - Pre-writes for all memory store instructions - Deferred writes for read-modify-write instructions (INC/DEC (HL), CB prefix on (HL)) - IO handling at M1 time using shadow register values

Disk I/O: - Rust TCP sector server on local network (192.168.0.248:9000) - 128-byte CP/M sector transfers over WiFi - Automatic reconnection with file re-open and seek restore

Console I/O: - Emulated MC6850 ACIA on ports 0x80/0x81 - USB CDC serial at 115200 baud - Interrupt-driven receive with throttled polling (every 256 ticks)

Pin Mapping Reference

For anyone attempting a similar project, here's the complete mapping from Arduino digital pins to STM32H747 GPIO ports. This is essential for the direct register access that makes the performance optimization possible:

Function	Arduino Pin	STM32 Port/Pin
CLK	D52	PK2
MREQ_N	D41	PK7
WR_N	D40	PE6
IORQ_N	D39	PI14
INT_N	D50	PI11
RESET_N	D38	PJ7
Data bit 0	D49	PE4
Data bit 1	D48	PK0
Data bit 2	D47	PB2
Data bit 3	D46	PH15
Data bit 4	D45	PI13
Data bit 5	D44	PG10
Data bit 6	D43	PI10
Data bit 7	D42	PI15
Addr A0	D22	PJ12
Addr A1	D23	PG13
Addr A2	D24	PG12
Addr A3	D25	PJ0
Addr A4	D26	PJ14
Addr A5	D27	PJ1
Addr A6	D28	PJ15
Addr A7	D29	PJ2
Addr A8	D37	PJ6
Addr A9	D36	PK6
Addr A10	D35	PJ5
Addr A11	D34	PK5
Addr A12	D33	PJ4
Addr A13	D32	PK4
Addr A14	D31	PJ3
Addr A15	D30	PK3

The address bus pins are spread across three GPIO ports (J, G, K), so a 16-bit address read requires three IDR register reads and individual bit extraction. Not ideal, but still orders of magnitude faster than sixteen digitalRead() calls.

What's Next

The immediate win would be using the Giga's 8MB SDRAM as a disk cache. Download entire disk images over WiFi at boot, then serve all disk I/O from memory. No network latency, no TCP overhead, no reconnection logic needed. CP/M running at SRAM speed on a RAM disk, faster than any physical media the Z80 ever had access to.

There's also the question of the TXB0108 itself. The level converter PCB works, but three of its nine ICs are essentially decorative; the signals they're supposed to translate (IORQ_N, RD_N, and data bus Z80→Arduino during IO) are broken, and the software works around them. A v0.2 of the board replaces 5 of the 9 TXB0108s with purpose-matched ICs that don't rely on auto-direction sensing:

74LVC541 (U1–U3): Unidirectional buffers for the address bus and control inputs (MREQ_N, IORQ_N, RD_N, WR_N). VCC at 3.3V with 5V-tolerant inputs. They simply translate 5V→3.3V with no direction ambiguity. This eliminates the stuck-HIGH failures on IORQ_N and RD_N entirely.
74AHCT541 (U4): Unidirectional buffer for control outputs (CLK, RESET_N, INT_N, NMI_N). VCC at 5V with TTL-compatible inputs that accept 3.3V drive levels, providing clean 3.3V→5V translation.
SN74LVC4245A (U5): Bidirectional transceiver for the data bus, with an explicit DIR pin controlled by a Giga GPIO. No more auto-sensing guesswork; the firmware tells the chip which side is driving, so Z80→Arduino data is visible during IO writes for the first time.
TXB0108 (U6–U9): Retained for the remaining 40 channels of pass-through GPIO, where auto-direction sensing works fine.

The firmware payoff is substantial: the entire shadow register architecture (roughly 1,300 lines of opcode tracking, softPC maintenance, pre-writes, and deferred write logic) could be replaced by a single digitalWrite() to flip the data bus direction pin. That's a lot of complexity removed for one additional GPIO wire.

But there's something satisfying about the current approach. The shadow register system transforms a passive bus controller into something that understands the Z80's instruction stream at a semantic level. The Arduino doesn't just shuttle bytes; it knows what the Z80 is thinking. And if the goal is to play Zork in the Great Underground Empire on real 1980s hardware controlled by a modern microcontroller over WiFi, well, we're there.

A note on tooling: this project would have taken considerably longer without Claude Code. The debugging cycle for a project like this (where you're staring at Z80 opcode tables, cross-referencing flag behavior across hundreds of instructions, and hunting for one wrong carry bit in a 2,600-line Arduino sketch) is brutal. Claude Code served as a tireless pair programmer throughout the process, helping trace through instruction semantics, spotting missing opcodes in the shadow register implementation, working through the GPIO register mappings for the STM32H747, and iterating on performance optimizations. The feedback loop that would normally stretch across days of manual datasheet cross-referencing compressed into hours.

Source Code

All source code, firmware, and hardware design files for this project are open source:

retroshield-z80-cpm-giga: Arduino Giga R1 firmware, CP/M system files, and disk image (BSD 3-Clause)
retroshield-sector-server: Rust TCP sector server for WiFi-based disk I/O (BSD 3-Clause)
retroshield-level-shifter-pcb: KiCad design files, Gerber files, BOM, and schematic for the level converter shield (CC BY-SA 4.0)

This is the third post in the Arduino Giga R1 + RetroShield Z80 series:

My Experience Using Fiverr for Custom PCB Design: A $468 Arduino Giga Shield, designing the level converter
Porting CP/M to the Arduino Giga R1: When Level Converters Fight Back, the hardware stack, TXB0108 failures, shadow registers, and sector server
Playing Zork on a Real Z80 (this post), getting CP/M to boot, the "Bad load" bug, 75x performance optimization, and interactive Zork gameplay

Porting CP/M to the Arduino Giga R1: When Level Converters Fight Back

A.C. Jokela — Sat, 14 Feb 2026 21:00:00 GMT

My previous CP/M build runs great. A real Z80 on a RetroShield, DRAM shield for 64KB, SD card for disk images, all sitting on an Arduino Mega 2560. It boots CP/M, runs Zork, the works. So naturally I decided to make my life harder.

The Arduino Giga R1 WiFi is a significantly more powerful board: a dual-core STM32H747 running at 480MHz, 1MB of internal SRAM, 8MB of SDRAM, and built-in WiFi. Where the Mega's 16MHz AVR crawled through bus cycles, the Giga could theoretically fly. And all that internal RAM means we can ditch the KDRAM2560 DRAM shield entirely, leaving just a 64KB byte array in SRAM.

There was just one problem. The Giga runs at 3.3V logic. The Z80 runs at 5V. And as I'd learn the hard way, bridging that gap would consume more debugging hours than everything else combined.

This post documents the port: the hardware stack, the architectural pivot to WiFi-based disk I/O, the level converter nightmare, the shadow register workaround that saved the project, and the Rust sector server that ties it all together. If you want the backstory on the custom level converter PCB, designed by Elijah on Fiverr, that's a separate post.

The Hardware Stack

The upgraded system has fewer physical components than the Mega version, but more going on under the hood.

Component	Mega Version	Giga Version
Processor	ATmega2560, 16MHz	STM32H747, 480MHz Cortex-M7
Logic Level	5V native	3.3V (needs level converter)
Z80 RAM	KDRAM2560 DRAM shield	64KB byte array in SRAM
Bus I/O	AVR port registers (parallel)	digitalRead/Write (per-pin)
Disk Storage	SD card (software SPI)	WiFi to sector server
Extra Hardware	DRAM shield + SD adapter	Level converter board only

The RetroShield Z80 plugs in the same way; it uses the same physical pin positions. The level converter board sits between the Giga and the RetroShield, translating all bus signals between 3.3V and 5V. The board uses TXB0108 bidirectional level converters, which sense the drive direction automatically.

At least, that's what they're supposed to do.

CP/M Memory Map

The Z80 sees the same 64KB address space as on the Mega:

0000-00FF   Page Zero (jump vectors, FCBs, command buffer)
0100-DFFF   TPA (Transient Program Area) — 56KB
E000-E7FF   CCP (Console Command Processor)
E800-F5FF   BDOS (Basic Disk Operating System)
F600-FFFF   BIOS (Basic I/O System)

On the Mega, this lived in the KDRAM2560's dynamic RAM with its complex refresh timing. On the Giga, it's just:

byte z80RAM[65536];

One line. The Giga's 1MB of internal SRAM makes the entire DRAM shield unnecessary.

WiFi Instead of SD

The original plan was to keep the SD card. The Mega version used software SPI on pins 4-7 since the RetroShield claims the hardware SPI pins. On the Giga, the RetroShield still claims all 76 digital pins, but this time there are no spare analog pins conveniently routed for software SPI either.

The initial idea was to wire a MicroSD adapter to the analog pins. But that meant more custom wiring on top of the already-custom level converter board. And anyone trying to replicate this project would need to solder yet another adapter.

Then it hit me: the Giga has WiFi built in. Why not serve disk images over the network?

The more I thought about it, the more sense it made:

No additional hardware. WiFi is built into the Giga. Zero extra wiring.
Better reproducibility. The project already requires a custom level converter. Adding another custom wiring job makes it harder for others to build.
The sector server is just software. Anyone can download and run a binary. Compare that to soldering an SD adapter to analog pins.
It plays to the Giga's strengths. If you're upgrading from a Mega, you might as well use what makes the Giga special: WiFi and RAM.
Future potential. The 8MB SDRAM could cache entire disk images downloaded over WiFi at boot. CP/M on a RAM disk, faster than any physical media the Z80 ever had access to.

The tradeoff is that the system is no longer self-contained. It needs a WiFi network and a computer running the sector server. For a project that already requires a custom level converter PCB, this felt acceptable.

The Level Converter Problem

This is where the project nearly died.

The TXB0108 is a popular bidirectional level converter. It uses auto-direction sensing: whichever side drives a signal stronger "wins," and the converter translates accordingly. This works well for simple I2C and SPI signals where direction is clear.

It does not work well for a Z80 bus.

Signal-by-Signal Breakdown

I built a pin diagnostic sketch to test each signal through the level converter. Here's what I found:

Signal	Pin	Expected	Actual	Status
MREQ_N	41	Toggles on memory access	Toggles correctly	Working
WR_N	40	Toggles on writes	Memory writes only	Partial
RD_N	53	Toggles on reads	Stuck HIGH always	Broken
IORQ_N	39	Toggles on I/O access	Stuck HIGH always	Broken
Address Bus	22-37	16-bit address	All bits correct	Working
Data Bus (A→Z80)	42-49	Arduino drives data	Works	Working
Data Bus (Z80→A)	42-49	Z80 drives data	Memory writes only	Partial

Two signals completely stuck. Two signals working only half the time. The auto-direction sensing that makes the TXB0108 convenient is exactly what makes it unreliable here; the Z80's bus signals have complex timing relationships where drive strength varies throughout the cycle.

RD_N: Permanently Stuck

RD_N on pin 53 never toggles. It reads HIGH regardless of what the Z80 is doing. Pin 53 is the hardware SPI SCK pin on the Mega, and may have internal pull-ups or other conflicts on the Giga's STM32. Combined with the TXB0108's direction sensing, the signal simply can't get through.

The fix is trivial once you realize it: during any bus cycle, the Z80 is either reading or writing. They're mutually exclusive. So:

#define STATE_RD_N (!STATE_WR_N)

If WR_N isn't asserted, it must be a read. This works for all standard Z80 bus operations.

IORQ_N: The Big One

IORQ_N on pin 39 is also stuck HIGH. This is the signal that tells us the Z80 wants to talk to a peripheral: console I/O, disk I/O, everything. Without it, we have no way to detect I/O operations through the bus.

But we have something the bus doesn't know about: we control the Z80's memory. Every byte the Z80 fetches comes from z80RAM[], which we serve. We can read the opcode stream and know exactly what instruction the Z80 is executing, including OUT (n), A (opcode 0xD3) and IN A, (n) (opcode 0xDB).

So instead of watching for IORQ_N to go low, we watch for the Z80 to fetch an I/O instruction from memory.

Data Bus: Invisible During I/O OUT

This was the subtlest failure. During OUT (n), A, the Z80 puts the A register value on the data bus. We should be able to read it. But we can't.

The TXB0108 latches the last strongly-driven value. Since the Arduino drives the data bus during memory reads (pushing 3.3V through the converter to the Z80's 5V side), the converter's direction gets stuck. When the Z80 tries to drive data back during an I/O write, its 5V output can't overcome the converter's latched direction.

I confirmed this by sampling the data bus at every clock tick during an OUT cycle. It showed 0x80 (the last value the Arduino had driven, a port number) at every single tick. Zero variation. The Z80's output was completely invisible.

WR_N: Only Works Sometimes

WR_N toggles correctly during memory write cycles but never during I/O write cycles. The timing or drive strength during I/O is just different enough that the converter can't track it.

This meant we couldn't use WR_N to detect when an I/O write was complete either. Every signal we'd normally use for I/O detection was either stuck or unreliable.

Shadow Register Tracking

The solution to the data bus problem is to never read the data bus during I/O at all. Instead, we maintain a shadow copy of the Z80's A register by watching the opcode stream.

Since we serve every byte the Z80 reads from z80RAM[], we can decode the instruction stream in real time. When we see LD A, 0x03 (opcode 0x3E 0x03), we set shadowA = 0x03. When we later see OUT (0x10), A (opcode 0xD3 0x10), we already know A contains 0x03, so there's no need to read the bus.

M1 Detection

The first challenge is knowing when the Z80 is fetching an opcode (M1 cycle) versus reading data. We detect M1 by watching for the first MREQ-active read after a MREQ-inactive cycle, the rising-to-falling edge of MREQ activity:

bool mreq_active = !digitalRead(uP_MREQ_N);

if (mreq_active && !prevMREQ_active && opcodeSkip == 0) {
    uint8_t opcode = z80RAM[uP_ADDR];
    // This is an M1 fetch — decode the instruction
}

The opcodeSkip Counter

After M1, the Z80 runs a refresh cycle (which reuses the address bus; when the I register is 0 after reset, refresh addresses overlap with boot code at 0x0000+). If we mistook a refresh cycle for another M1, we'd corrupt the shadow registers by "decoding" whatever data happened to be at the refresh address.

The fix is a 256-entry lookup table that tells us how many MREQ-active read cycles to skip after each opcode:

static const uint8_t skipCount[256] = {
    // 0x00-0x0F: NOP=1, LD BC,nn=3, ...
    1, 3, 1, 1, 1, 1, 2, 1, 1, 1, 2, 1, 1, 1, 2, 1,
    // ... 256 entries covering every Z80 opcode
};

A 1-byte instruction like NOP gets skip=1 (refresh only). A 3-byte instruction like LD HL, nn gets skip=3 (refresh + 2 operand reads). I/O instructions get skip=0 because their skipping is handled by the I/O state machine. After each M1, we set opcodeSkip = skipCount[opcode] and decrement it on each subsequent MREQ-active read cycle.

Register Tracking

We don't need to track every Z80 register, just enough to know what value A holds when an OUT happens. The BIOS uses a relatively small set of instructions to load registers before I/O:

switch (opcode) {
    // === IO Instructions ===
    case 0xD3: {  // OUT (n), A
        uint8_t port = z80RAM[uP_ADDR + 1];
        handle_io_write(port, shadowA);
        break;
    }
    case 0xDB: {  // IN A, (n)
        uint8_t port = z80RAM[uP_ADDR + 1];
        ioResponse = handle_io_read(port);
        shadowA = ioResponse;  // IN updates A
        break;
    }

    // === A register tracking ===
    case 0x3E: shadowA = z80RAM[uP_ADDR + 1]; break; // LD A, n
    case 0xAF: shadowA = 0; break;                     // XOR A
    case 0x79: shadowA = shadowC; break;                // LD A, C
    case 0x78: shadowA = shadowB; break;                // LD A, B
    case 0x7C: shadowA = shadowH; break;                // LD A, H
    case 0x7D: shadowA = shadowL; break;                // LD A, L
    case 0x7E: shadowA = z80RAM[(shadowH << 8) | shadowL]; break;
    case 0xE6: shadowA &= z80RAM[uP_ADDR + 1]; break;  // AND n
    case 0xF6: shadowA |= z80RAM[uP_ADDR + 1]; break;  // OR n
    case 0x2F: shadowA = ~shadowA; break;                // CPL
    case 0x3C: shadowA++; break;                         // INC A
    case 0x3D: shadowA--; break;                         // DEC A

    // === B, C, H, L tracking (needed because A loads from them) ===
    case 0x06: shadowB = z80RAM[uP_ADDR + 1]; break;  // LD B, n
    case 0x0E: shadowC = z80RAM[uP_ADDR + 1]; break;  // LD C, n
    case 0x21: {  // LD HL, nn
        shadowL = z80RAM[uP_ADDR + 1];
        shadowH = z80RAM[uP_ADDR + 2];
        break;
    }
    // ... plus INC/DEC HL, LD between registers, etc.
}

This isn't a full Z80 emulator; it's just enough to track register flow from loads to I/O instructions. If the BIOS uses an instruction we don't track, shadowA will be wrong and the I/O operation will get bad data. But the CP/M BIOS is a known codebase, so we can enumerate exactly which instructions it uses and make sure they're covered.

IO State Machine

For OUT, we handle the write immediately when we detect 0xD3 at M1, since we already know the port (from RAM) and the data (from shadowA). Then we let the skip counter consume the remaining machine cycles.

For IN, it's trickier because the Z80 needs to actually read our response off the data bus. We use a small state machine:

IO_IDLE → detect 0xDB → IO_IN_PENDING (call handle_io_read, get response)
IO_IN_PENDING → opcodeSkip reaches 0 → IO_IN_DRIVING (drive response on data bus)
IO_IN_DRIVING → next MREQ goes active → IO_IDLE (release bus, resume normal)

During IO_IN_DRIVING, we keep the response byte on the data bus and ignore other processing until the Z80's next M1 fetch (signaled by MREQ going active again).

The Sector Server

With the Arduino side handling bus-level I/O through shadow registers, the disk I/O ports translate to network messages. The Z80 BIOS writes a filename character-by-character to port 0x13, writes seek bytes to ports 0x14/0x15/0x19, sets the DMA address via ports 0x16/0x17, then triggers a block read/write on port 0x18. The Arduino accumulates this state, then forwards the operation to the sector server over TCP.

Protocol

The server speaks a simple binary protocol that mirrors the BIOS port commands:

Command	Byte	Payload	Response
OPEN_READ	0x01	filename\0	status
CREATE	0x02	filename\0	status
OPEN_APPEND	0x03	filename\0	status
SEEK_START	0x04	(none)	status
CLOSE	0x05	(none)	status
DIR	0x06	(none)	status + listing\0
OPEN_RW	0x07	filename\0	status
SEEK	0x08	3 bytes LE offset	status
READ_BLOCK	0x10	(none)	status + 128 bytes
WRITE_BLOCK	0x11	128 bytes	status

Status is a single byte: 0x00 for OK, 0x01 for error. Block size is 128 bytes, a CP/M sector.

Implementation

The server is written in Rust with minimal dependencies (just socket2 for SO_REUSEADDR). It started single-threaded, which worked fine until the Giga crashed and rebooted. The old TCP connection would hang in the server's blocking read_exact(), and the Giga's new connection attempt would queue indefinitely. Classic deadlock.

The fix was threaded connections with timeouts:

for stream in listener.incoming() {
    match stream {
        Ok(stream) => {
            let base_dir = Arc::clone(&base_dir);
            thread::spawn(move || {
                handle_client(stream, &base_dir);
            });
        }
        Err(e) => eprintln!("[!] Accept error: {}", e),
    }
}

Each client gets its own thread. The accept loop never blocks. Read timeouts (30s mid-command, 300s idle) automatically drop dead connections. SO_REUSEADDR lets the server restart instantly without port conflicts.

The server also sanitizes filenames (rejecting path traversal and special characters) and tracks session metrics:

Session Summary
---------------
Duration:        00:00:00
Commands:        11
Files opened:    2
Seeks:           1
Sectors read:    5
Sectors written: 1
Bytes read:      640 (640 B)
Bytes written:   128 (128 B)
Errors:          0

Running It

# Build
cd sector_server && cargo build --release

# Serve CP/M files on port 9000
./sector_server/target/release/sector_server ./kz80_cpm 9000

The directory needs boot.bin, CPM.SYS, and the disk images (A.DSK, B.DSK, etc.).

Proof of Concept

Before wiring up the full shadow register machinery, I wrote a minimal POC sketch that tests just the WiFi + sector server communication. It connects, opens files, reads blocks, seeks, and closes, verifying the network layer end-to-end without any Z80 involvement.

All 8 tests passed:

=== Sector Server POC ===

WiFi: connecting to TP-Link_A8A8 ... OK (192.168.0.75)
Server: connecting to 192.168.0.248:9000 ... OK

--- Test 1: OPEN_READ boot.bin ---
  Status: OK
--- Test 2: READ_BLOCK (128 bytes) ---
  Status: OK
  Data:
F3 31 00 04 3E 03 D3 80 3E 15 D3 80 21 83 00 CD
7B 00 21 43 01 CD 70 00 3E 01 D3 10 DB 11 E6 02
--- Test 3: READ_BLOCK (next 128 bytes) ---
  Status: OK
  Data:
23 18 F8 0D 0A 52 65 74 72 6F 53 68 69 65 6C 64
20 5A 38 30 20 42 6F 6F 74 20 4C 6F 61 64 65 72
--- Test 4: CLOSE ---
  Status: OK
--- Test 5: OPEN_RW A.DSK ---
  Status: OK
--- Test 6: SEEK offset=6656 ---
  Status: OK
--- Test 7: READ_BLOCK (directory sector) ---
  Status: OK
  Data:
00 5A 4F 52 4B 31 20 20 20 43 4F 4D 00 00 00 44
--- Test 8: CLOSE ---
  Status: OK

=== All tests complete ===

Some things to note: the first bytes of boot.bin are F3 31 00 04, which disassembles to DI; LD SP, 0x0400, the boot loader's first instructions, correct. The second block contains the ASCII string "RetroShield Z80 Boot Loader." And the directory sector from A.DSK shows ZORK1 COM. Zork is on the disk, waiting.

Boot Sequence

When the full sketch runs, the expected boot sequence is:

======================================
RetroShield Z80 CP/M 2.2
Arduino Giga R1 WiFi
======================================

Z80 RAM:    OK (64KB in SRAM)
WiFi:       OK (192.168.0.75)
Server:     OK (192.168.0.248:9000)
Boot:       OK (384 bytes loaded)

Starting Z80...

After "Starting Z80...", the Z80 boot loader runs. It opens CPM.SYS via the sector server, loads the CCP and BDOS into memory at 0xE000, jumps to the BIOS cold boot at 0xF600, and if everything works, prints a banner and the A> prompt.

What's Next

The WiFi communication works. The shadow register tracking mechanism works; I've confirmed partial serial output from the Z80 (the ACIA console I/O goes through the same shadow register path). The instruction skip counter prevents refresh cycle confusion. All the pieces are in place.

What remains is completeness testing. The shadow register tracking needs to cover every instruction the BIOS and CCP actually use. If the Z80 executes an instruction that modifies A through a path we don't track (say, a POP AF or EX AF, AF'), the shadow will be wrong and the next OUT will send garbage. The fix is straightforward (add more cases to the switch statement) but requires methodical testing.

There's also the 8MB SDRAM sitting unused on the Giga. Once CP/M boots reliably, the obvious next step is downloading entire disk images into SDRAM over WiFi at startup. At that point, all disk I/O becomes memory-mapped, with no network latency and no TCP overhead. CP/M running at memory speed on a RAM disk, served from a real Z80 that thinks it's talking to a floppy drive.

Once the project is stable and CP/M boots reliably, I plan to open-source the full KiCad PCB design files for the level converter shield, along with the Arduino sketch and sector server. The level converter board uses nine TXB0108PW ICs in TSSOP-20 packages to translate all 72 signals between the Giga's 3.3V and the RetroShield's 5V. It's a straightforward two-layer design that anyone could get fabricated.

The debugging journey from "IORQ_N is stuck" to "let's just decode the entire instruction stream in software" was not the path I expected to take. But it turned a level converter limitation into something arguably more interesting: a system where the Arduino doesn't just babysit the Z80's bus signals, but understands what the Z80 is thinking.