TinyComputers.io (Posts about cp/m)

An LLM Clean Room Z80 Emulator: Building from Specifications, Not Source Code

A.C. Jokela — Fri, 27 Feb 2026 00:00:00 GMT

There's a particular kind of satisfaction in building something from specifications rather than from someone else's implementation. When you take timing diagrams and instruction tables and turn them into working code, you're not copying; you're reconstructing. Every decision about how to decode an opcode, how to handle the flag register's undocumented bits, how to sequence a block transfer instruction: these become deliberate choices, informed by the original engineering documents but filtered through genuine understanding of the problem.

This is the story of writing a complete Z80 emulator under clean room constraints, with the twist that the implementer is an LLM. I used Claude Code to write every line of C (the CPU core, the test suite, the system emulator) with a single, non-negotiable rule: no reference to existing Z80 emulator source code. The inputs were the Zilog Z80 CPU User Manual, my architectural plan, and the test ROMs to prove it works.

An important clarification on what "clean room" means here. The constraint was no existing emulator source code, not "only the official Zilog manual." The Z80's undocumented behaviors (the F3/F5 flag bits, IXH/IXL half-index registers, DDCB register copy side effects) aren't in Zilog's official documentation. They come from decades of community reverse-engineering documented in references like Sean Young's "The Undocumented Z80 Documented" and similar technical write-ups. Claude's training data includes this secondary documentation, and the clean room constraint didn't prohibit drawing on that knowledge; it prohibited referencing how other emulators implemented that knowledge. The distinction matters: a specification of behavior is not the same as someone else's code that implements it.

Why an LLM Clean Room?

The term "clean room" comes from the semiconductor and software industries, where it describes a development methodology designed to produce implementations that are legally and intellectually independent of existing ones. In the chip fabrication sense, it's a literal dust-free environment. In the software sense, it means building from specifications and documentation without ever examining existing implementations.

When an LLM writes code, there's always the question: is this implementation derived from the specification I gave it, or is it pattern-matching against emulator source code in its training data? This is the central tension of using AI for systems programming. An LLM has likely seen dozens of Z80 emulators during training. If you just ask it to "write a Z80 emulator," you'll get something that works, but you can't know whether it's an original implementation or a recombination of memorized code.

The clean room constraint changes the experiment. By explicitly instructing Claude that this is a clean room project (that all implementation must be derived solely from specifications and documentation, not from existing emulator source code), you're testing whether the model can work from first principles rather than from pattern recall. Can it read an instruction set specification, understand the semantics of each opcode, and produce correct flag computations without cribbing from someone else's z80.c?

Antirez explored this territory recently with his own Z80 emulator project, using Claude Code to generate a working ZX Spectrum emulator. His experiment demonstrated something important about LLM-assisted development: that providing an agent with proper specifications and documentation, rather than asking it to regurgitate training data, produces implementations that are genuinely novel assemblies of knowledge rather than memorized patterns. The code Claude produced for antirez passed the notoriously thorough ZEXALL test suite, validating every documented Z80 behavior including the undocumented flag bits. Antirez's conclusion was that the LLM wasn't decompressing training data; it was assembling knowledge, the way a human developer would when working from a datasheet.

Reading antirez's write-up was the catalyst for this project. I wanted to see whether the same approach (specifications in, working emulator out, clean room constraints enforced throughout) would hold up when I drove the process myself. The Z80 User Manual is one of the best-documented processor specifications ever written. Everything you need to build a working emulator is in that document. The question is whether an LLM, given that document as its source of truth and told not to reference existing implementations, can produce something correct.

The Process

The workflow looked nothing like "prompt and pray." I started by writing a detailed architectural plan: the CPU state struct layout, the instruction decoding strategy (bit field decomposition), the system emulator's responsibilities, the test coverage targets. This plan became Claude's specification, not just "write a Z80 emulator" but "implement the Z80 CPU using x/y/z/p/q bit field decoding of the opcode byte, with these specific callback interfaces, these T-state timing requirements, and this test structure."

Claude then implemented each component: z80.h first, then the full z80.c CPU core, then the test suite, then the system emulator. I reviewed each piece, ran the tests, identified failures, and fed the errors back. The first compile had a T-state timing issue with DD/FD prefixed instructions; the prefix overhead was being double-counted. One test out of 117 failed. Claude diagnosed the problem (the prefix dispatch was adding 4 T-states on top of instruction timings that already included the prefix cost) and fixed it.

This iterative loop (plan, implement, test, fix) is exactly how a human developer would work. The difference is velocity. The entire CPU core, all 1,300 lines of C covering every official Z80 instruction plus undocumented behaviors, was produced in a single session. A human developer working from the same specification would spend days or weeks reaching the same point. The LLM's advantage isn't that it knows more; it's that it can hold the entire instruction set specification in context and translate it to code without the cognitive overhead of context-switching between the manual and the editor.

The Architecture

What Claude produced is a four-file emulator:

File	Purpose
`z80.h`	CPU state struct, flag constants, public API
`z80.c`	Complete Z80 CPU emulation core
`z80_test.c`	117 unit tests covering all instruction groups
`zxs.c`	Unified emulator binary with ACIA serial and CP/M support

The design philosophy is straightforward: the CPU core knows nothing about the system it's running in. It communicates with the outside world exclusively through four callback functions: memory read, memory write, I/O in, and I/O out. The system emulator (zxs.c) provides these callbacks and implements whatever hardware peripherals the target system requires.

This separation matters. The same CPU core can run a Grant Searle BASIC SBC, an RC2014, or a CP/M program without any changes to z80.c. The system-specific behavior lives entirely in the callbacks.

The CPU State

A Z80 has more programmer-visible state than you might expect if you're used to simpler processors. The main register file includes the accumulator A and flags register F, plus three general-purpose register pairs BC, DE, and HL. But then there's a complete shadow set of all those registers (A', F', BC', DE', HL'), accessible only through the EX AF,AF' and EXX exchange instructions.

Add the two 16-bit index registers IX and IY, the stack pointer SP, the program counter PC, the interrupt vector register I, and the memory refresh counter R, and you've got a substantial amount of state to track. Then there's the interrupt system: two flip-flops IFF1 and IFF2, the interrupt mode register (modes 0, 1, or 2), a halt flag, and a one-instruction delay flag for the EI instruction.

typedef struct {
    /* Main registers */
    uint8_t  A, F;
    uint8_t  B, C, D, E, H, L;

    /* Shadow registers */
    uint8_t  A_, F_, B_, C_, D_, E_, H_, L_;

    /* Index registers */
    uint16_t IX, IY;

    /* Stack pointer and program counter */
    uint16_t SP, PC;

    /* Interrupt and refresh registers */
    uint8_t  I, R;

    /* Interrupt state */
    uint8_t  IFF1, IFF2, IM, halted, ei_delay;

    /* Cycle counter */
    unsigned long t_states;

    /* Memory and I/O callbacks */
    z80_read_fn  mem_read;
    z80_write_fn mem_write;
    z80_in_fn    io_in;
    z80_out_fn   io_out;
    void *ctx;
} z80_t;

I chose to store each register as an individual byte rather than using unions or bitfields to form 16-bit pairs. This makes the code more explicit; when you see cpu->B, you know exactly what's being accessed. Register pairs are assembled and disassembled through inline helper functions like rp_bc() and set_bc(). The compiler optimizes these away completely, so there's no performance cost for the clarity.

Instruction Decoding: The Bit Field Approach

The Z80's instruction encoding has a structure that isn't immediately obvious if you're just looking at an opcode table, but becomes clear once you read the User Manual carefully. Every opcode byte can be decomposed into bit fields:

x = bits 7:6 (the two highest bits)
y = bits 5:3 (the middle three bits)
z = bits 2:0 (the lowest three bits)
p = bits 5:4 (y >> 1)
q = bit 3 (y & 1)

These fields determine the instruction's category and operands. For the unprefixed opcodes:

x=0: Miscellaneous: relative jumps, 16-bit loads, 16-bit arithmetic, INC/DEC, 8-bit loads with immediate data, and the accumulator rotate/DAA/CPL/SCF/CCF group
x=1: Register-to-register loads (LD r, r'), with the special case of LD (HL),(HL) encoding HALT instead
x=2: ALU operations between the accumulator and a register (ADD A,r through CP r)
x=3: Returns, jumps, calls, stack operations, RST vectors, I/O, exchange instructions, interrupt control, and the prefix bytes for extended instruction groups

This structure means you can decode most unprefixed instructions with a three-level switch on x, then z (or y), rather than a 256-entry lookup table. The code reads more like the specification:

switch (x) {
case 1:
    if (y == 6 && z == 6) {
        /* HALT */
        c->halted = 1;
        c->PC--;
    } else {
        /* LD r[y], r[z] */
        set_reg8(c, y, get_reg8(c, z));
    }
    break;

case 2:
    /* ALU A, r[z] */
    do_alu(c, y, get_reg8(c, z));
    break;

The register index mapping (0=B, 1=C, 2=D, 3=E, 4=H, 5=L, 6=(HL), 7=A) is used consistently throughout the instruction set. Index 6 always means the memory byte pointed to by HL, which is why LD (HL),(HL) would be meaningless (load memory from the same memory location) and gets repurposed as HALT.

The Prefix System

The Z80 extends its instruction set through prefix bytes: CB, ED, DD, and FD. Each opens up a different dimension of functionality.

CB prefix: Rotate/shift operations and bit manipulation. The same x/y/z decode applies, but now x=0 is rotate/shift, x=1 is BIT (test), x=2 is RES (reset), and x=3 is SET. This gives you eight different rotate/shift operations on any of the eight register positions, and bit test/set/reset for any of eight bit positions on any register. That's 248 instructions from a single prefix byte.

ED prefix: Extended operations that don't fit the main opcode map. Block transfer and search instructions (LDI, LDIR, LDD, LDDR, CPI, CPIR, and their output counterparts), 16-bit arithmetic with carry (ADC HL,rp and SBC HL,rp), extended I/O (IN r,(C) and OUT (C),r), interrupt mode selection, and a handful of register transfer instructions (LD I,A, LD A,R, etc.).

DD and FD prefixes: These modify the following instruction by replacing HL with IX or IY respectively. Wherever the unprefixed instruction uses HL as a 16-bit register, the prefixed version uses IX or IY. Wherever it accesses (HL) as a memory operand, the prefixed version accesses (IX+d) or (IY+d), where d is a signed displacement byte inserted between the opcode and any immediate data.

This substitution extends to the individual H and L registers in many contexts. LD A,H becomes LD A,IXH with a DD prefix. These "half-index" register operations are technically undocumented but universally supported by real silicon and widely used by software. A clean room implementation needs to handle them.

DDCB and FDCB: The most complex prefix combination. For bit operations on indexed memory (IX+d), the displacement byte comes before the opcode byte, not after:

DD CB d op    →    operation on (IX+d)

This reversed order exists because the Z80's internal pipeline needs the displacement early to begin the memory access while decoding the operation. It's an elegant microarchitectural optimization that reveals itself in the instruction encoding.

There's an additional subtlety: undocumented behavior where DDCB/FDCB rotate and set/reset operations also copy their result into a register specified by the z field of the opcode. RLC (IX+5) with a z field of 0 also loads the result into B. This behavior is consistent across all real Z80 chips and is relied upon by some software.

The ALU

The eight ALU operations (ADD, ADC, SUB, SBC, AND, XOR, OR, CP) share a common pattern in how they affect the flags register. Getting the flags right is the single most important aspect of Z80 emulation, and the area where most subtle bugs hide.

The Z80's flag register contains eight bits, six of which are documented:

Bit	Name	Meaning
7	S	Sign (copy of bit 7 of result)
6	Z	Zero (result is zero)
5	F5	Undocumented (copy of bit 5 of result*)
4	H	Half-carry (carry from bit 3 to bit 4)
3	F3	Undocumented (copy of bit 3 of result*)
2	P/V	Parity (logic ops) or Overflow (arithmetic ops)
1	N	Subtract (set if last operation was subtraction)
0	C	Carry (carry out of bit 7)

The asterisk on F3 and F5 matters. For most operations, bits 3 and 5 come from the result. But for CP (compare), they come from the operand, not the result. This is because CP is internally a subtraction that discards the result and keeps only the flags, but the Z80 designers connected the F3 and F5 flag inputs to the operand bus rather than the internal result bus for this particular instruction. It's the kind of detail that only shows up when you're testing against real hardware behavior.

The overflow flag computation deserves special attention. For addition, overflow occurs when two operands of the same sign produce a result of the opposite sign:

uint8_t v = ((a ^ val ^ 0x80) & (a ^ result)) & 0x80;

For subtraction, overflow occurs when two operands of different signs produce a result whose sign differs from the first operand:

uint8_t v = ((a ^ val) & (a ^ result)) & 0x80;

These one-liners replace what would otherwise be multi-branch conditional logic. They work because XOR detects sign differences, and AND combines the two conditions.

Block Operations

The Z80's block instructions are one of its most powerful features and one of the trickiest to implement correctly. LDIR (Load, Increment, Repeat) copies a block of memory from the address in HL to the address in DE, decrementing BC as a counter, and repeating until BC reaches zero.

The implementation requires careful attention to the repeat mechanism. When BC is not yet zero, LDIR decrements PC by 2 so that the next instruction fetch re-executes the same LDIR opcode. The repeated iteration takes 21 T-states; the final iteration (when BC reaches zero) takes only 16 T-states. This asymmetry matters for cycle-accurate emulation:

case 0: /* LDI/LDD/LDIR/LDDR */
    {
        uint8_t val = rb(c, rp_hl(c));
        wb(c, rp_de(c), val);
        /* Increment or decrement based on instruction */
        if (y == 4 || y == 6) {
            set_hl(c, rp_hl(c) + 1);
            set_de(c, rp_de(c) + 1);
        } else {
            set_hl(c, rp_hl(c) - 1);
            set_de(c, rp_de(c) - 1);
        }
        set_bc(c, rp_bc(c) - 1);
        /* ... flag computation ... */
        if (y >= 6 && rp_bc(c) != 0) {
            c->PC -= 2;
            repeat = 1;
        }
    }
    return repeat ? 21 : 16;

The flag behavior during block operations is another area where the specification requires careful reading. The P/V flag reflects whether BC is non-zero after the decrement, acting as a "more data" indicator. The undocumented F3 and F5 flags come from the sum of the transferred byte and the accumulator, with F5 derived from bit 1 rather than bit 5 of that sum. These details are well-documented in the secondary literature but require careful implementation.

The search variants (CPI, CPIR, etc.) are even more nuanced. They compare the accumulator against memory, set Z if a match is found, and terminate on either a match or BC reaching zero. The flags after a search operation encode both whether a match was found and whether the counter has been exhausted, two independent pieces of information packed into the flag register.

T-State Timing

Every Z80 instruction has a specific T-state (clock cycle) count that's documented in the User Manual. For an emulator driving a simulated UART or polling for terminal input at realistic intervals, accurate timing is essential.

The timing model uses a simple accumulator. Each call to z80_step() returns the number of T-states consumed and adds them to a running total in the CPU state. The system emulator uses this to determine when to poll for input or deliver interrupts:

while (!quit_flag) {
    unsigned long target = cpu.t_states + 7373;
    while (cpu.t_states < target) {
        z80_step(&cpu);
    }
    /* Poll for serial input, deliver interrupts */
}

The value 7373 represents approximately 2 milliseconds at 3.6864 MHz, the crystal frequency used by many Z80 SBC designs. This frequency was chosen historically because it divides cleanly to produce standard baud rates. At 9600 baud with 10 bits per character (start, 8 data, stop), you get approximately 960 characters per second, or about one character every 3,840 clock cycles. Polling at 7373-cycle intervals gives roughly two opportunities to check for input per character time, enough for reliable serial communication without excessive overhead.

Conditional instructions have different cycle counts depending on whether the condition is met. A JR Z,d takes 12 T-states when the jump is taken but only 7 when it falls through. CALL cc,nn takes 17 T-states when taken, 10 when not. These differences reflect the real pipeline behavior of the Z80; a taken branch requires additional cycles to flush the prefetch and load the new address.

The Interrupt System

The Z80 supports three interrupt modes and a non-maskable interrupt. Mode 1 is the simplest and most commonly used in SBC designs: a maskable interrupt causes the CPU to push the current PC and jump to address 0x0038, just like an RST 38h instruction.

Mode 2 is more sophisticated. The interrupting device places a vector byte on the data bus, which is combined with the I register to form a 16-bit address into a vector table in memory. The CPU reads the actual interrupt service routine address from that table location. This provides up to 128 different interrupt vectors, enabling complex multi-device interrupt schemes.

The EI instruction has a subtle but critical behavior: it doesn't enable interrupts immediately. Instead, it sets a one-instruction delay, so the next instruction after EI executes before any pending interrupt can be serviced. This guarantees that EI; RETI (enable interrupts, then return from interrupt) executes atomically; the return completes before any new interrupt can preempt it.

case 7: /* EI */
    c->IFF1 = 1;
    c->IFF2 = 1;
    c->ei_delay = 1;
    break;

And in the interrupt handler:

void z80_interrupt(z80_t *cpu, uint8_t data) {
    if (!cpu->IFF1 || cpu->ei_delay) return;
    /* ... process interrupt ... */
}

DAA: The Most Misunderstood Instruction

DAA (Decimal Adjust Accumulator) is arguably the Z80's most complex single instruction. It adjusts the result of a previous addition or subtraction to produce a valid BCD (Binary-Coded Decimal) result. The adjustment depends on three pieces of state: the current value of the accumulator, the carry flag, and the half-carry flag. It also behaves differently depending on whether the previous operation was addition or subtraction (tracked by the N flag).

The algorithm: if the lower nibble exceeds 9 or the half-carry flag is set, add (or subtract) 0x06. If the upper nibble exceeds 9 or the carry flag is set, add (or subtract) 0x60. Update carry if the upper correction was applied.

static void daa(z80_t *c) {
    uint8_t a = c->A;
    uint8_t correction = 0;
    uint8_t carry = c->F & Z80_CF;

    if ((c->F & Z80_HF) || (a & 0x0F) > 9)
        correction |= 0x06;
    if (carry || a > 0x99) {
        correction |= 0x60;
        carry = Z80_CF;
    }

    if (c->F & Z80_NF)
        c->A -= correction;
    else
        c->A += correction;

    c->F = sz53p(c->A) | carry | (c->F & Z80_NF) |
           ((a ^ c->A) & Z80_HF);
}

BCD arithmetic was important in the era when the Z80 was designed. Financial calculations, display drivers, and industrial controllers all needed decimal precision without floating-point hardware. The Z80's DAA instruction made BCD arithmetic practical on an 8-bit processor by adjusting binary results back into valid decimal digits after each operation.

Testing: 117 Ways to Be Wrong

Writing a test suite for a CPU emulator is an exercise in paranoia. Every instruction has multiple paths through the flag logic, multiple edge cases in operand handling, and multiple interactions with the rest of the CPU state. The test suite covers:

Register loads: 8-bit immediate, register-to-register, 16-bit immediate, indirect through BC/DE/HL, absolute addressing, HL indirect
8-bit ALU: All eight operations with basic values, carry/borrow propagation, overflow detection, half-carry, undocumented flag bits
16-bit arithmetic: ADD HL with carry, SBC HL, ADC HL
INC/DEC: 8-bit with overflow and half-carry edge cases, 16-bit wrapping
Rotates and shifts: RLCA/RRCA/RLA/RRA (accumulator), CB-prefixed RLC/RRC/RL/RR/SLA/SRA/SRL on registers
BIT/SET/RES: Test, set, and reset individual bits
Jumps and branches: JP, JR, DJNZ with taken/not-taken paths
Calls and returns: CALL/RET with condition codes, RST vectors
Stack operations: PUSH/POP for all register pairs including AF
Block operations: LDI/LDIR/LDD, CPI/CPIR, INI/OUTI
Exchange instructions: EX AF, EXX, EX DE,HL, EX (SP),HL
Interrupt system: IM modes, Mode 1 and Mode 2 dispatch, NMI, EI delay
IX/IY indexed: Loads, stores, arithmetic, IXH/IXL access, DDCB bit operations
T-state timing: Verified counts for representative instructions from each group
R register: Increment behavior, bit 7 preservation

Each test sets up a specific CPU state, loads a short instruction sequence into memory, executes it, and verifies the results. The test framework is minimal, just macros for assertions and a runner that reports pass/fail:

Z80 CPU Test Suite
==================
test_nop                                                    PASS
test_ld_reg_imm                                             PASS
...
test_r_bit7_preserved                                       PASS

==================
Results: 117/117 passed

All 117 pass. But passing unit tests isn't the same as passing real software. The real validation comes from booting actual ROMs.

The System Emulator

The zxs binary wraps the CPU core with enough peripheral emulation to run two classes of software: Grant Searle-style BASIC SBCs with ACIA serial I/O, and CP/M .COM programs with a minimal BDOS shim.

ACIA Serial Emulation

The Motorola MC6850 ACIA (Asynchronous Communications Interface Adapter) is the serial chip used in the Grant Searle Z80 SBC design and many similar projects. It presents two registers to the CPU:

Status register (base address): Bit 0 = Receive Data Register Full (RDRF), Bit 1 = Transmit Data Register Empty (TDRE)
Data register (base + 1): Read for received data, write to transmit

The emulation maps these to terminal I/O. TDRE is always set (the "transmitter" is always ready since we're writing directly to stdout). RDRF is set when non-blocking read() has captured a character from stdin. The ACIA's interrupt capability is emulated: when receive interrupts are enabled and data is available, the emulator delivers an RST 38h interrupt to the CPU.

Serial Port Auto-Detection

Rather than hardcoding the ACIA port address, the emulator scans the loaded ROM for IN A,(n) (DB xx) and OUT (n),A (D3 xx) instruction patterns. It collects the referenced port addresses and looks for adjacent pairs (status + data ports) that have both IN and OUT references, the signature of a serial peripheral. For the Grant Searle ROM, this reliably detects port base 0x80. For ROMs that use different port configurations, a --port flag provides a manual override.

CP/M Mode

For .com and .cim files, the emulator switches to CP/M mode: the program is loaded at 0x0100, the stack pointer is set to 0xFFFE with a return address of 0x0000 pushed, and BDOS calls are intercepted at address 0x0005. Only the essential BDOS functions are implemented (console output (function 2) and string output (function 9)), but this is enough to run many CP/M utilities and test programs.

System Auto-Detection

File extension determines the system type: .com and .cim files run in CP/M mode, everything else runs as a BASIC SBC. Intel HEX files are detected and parsed regardless of extension. The --system flag overrides auto-detection when needed.

Booting BASIC

The real test of any emulator is whether it runs real software. Here's what happens when you point zxs at Grant Searle's BASIC ROM:

$ ./zxs basic.rom
Loaded 8192 bytes at 0x0000
BASIC SBC mode, serial port base: 0x80 (Ctrl+] to exit)
Z80 SBC By Grant Searle

Memory top?

That banner, "Z80 SBC By Grant Searle," represents thousands of Z80 instructions executing correctly. The ROM initializes memory, configures the ACIA, sets up the interrupt handler, and enters the BASIC interpreter's command loop. Each of those steps exercises a different subset of the CPU's instruction set. A single incorrectly implemented instruction (a wrong flag bit, a miscounted displacement, a botched stack operation) would cause the ROM to crash or produce garbage output.

The RC2014 BASIC ROM boots as well, though it requires specifying the serial port base since its ROM references multiple I/O addresses:

$ ./zxs --port 0x80 rc2014_56k.hex
Loaded 8154 bytes from HEX file
BASIC SBC mode, serial port base: 0x80 (Ctrl+] to exit)

RC2014 - MS Basic Loader
z88dk - feilipu

Memory top?

Intel HEX file loading is handled transparently. The emulator detects the format by checking for the : record marker and parses the standard Intel HEX record format (data records, EOF records, address fields, checksums).

What I Learned About LLM Clean Room Development

This project taught me as much about working with LLMs as it did about the Z80. Some observations:

Specification quality determines output quality. When I gave Claude a vague instruction like "implement the Z80," the result would have been a generic emulator shaped by whatever training data dominates. When I gave it a detailed architectural plan (bit field decoding, specific callback interfaces, T-state requirements), the result was a coherent, well-structured implementation that reflected the design decisions in the specification. Antirez observed the same thing: the LLM performs dramatically better when you provide documentation and constraints rather than open-ended prompts.

LLMs can work from datasheets, not just from memory. The clean room constraint was the whole point: could Claude produce correct Z80 flag behavior, proper DDCB/FDCB displacement ordering, accurate block operation semantics, all derived from specification knowledge rather than memorized source code? The 117 passing tests and booting ROMs suggest it can. The code doesn't look like any particular existing emulator. The bit field decoder, the ALU structure, the prefix dispatch: these are architecturally reasonable but stylistically original.

The bug pattern was illuminating. The one test failure in the initial implementation was a T-state timing issue: DD/FD prefix overhead was being double-counted. This is exactly the kind of bug a human developer would make when implementing prefix dispatch, a bookkeeping error at the boundary between the prefix handler and the main decoder. It was not the kind of error you'd see from copying existing code, where the timing would already be correct. The bug was original, which paradoxically increases confidence that the implementation is too.

The Z80's instruction encoding is remarkably systematic. Once you express the x/y/z/p/q bit field decomposition in the architectural plan, the entire instruction set becomes a small number of patterns applied consistently across register indices and operation codes. Claude picked up on this structure immediately and produced a decoder that reads like the specification. The elegance of Zilog's encoding is invisible in an opcode table but obvious in a decoder, and an LLM can see that structure when pointed at it.

The DD/FD prefix system is essentially a register renaming mechanism. It doesn't introduce new operations; it modifies existing ones by replacing HL with IX or IY. Expressing this in the plan as "replace HL→IX/IY, H→IXH/IYH, L→IXL/IYL, (HL)→(IX+d)/(IY+d)" gave Claude the conceptual framework to implement DD/FD support as a modifier on the existing decoder rather than duplicating 200+ instruction handlers.

Flag behavior is the specification. Two Z80 emulators can produce identical results for every instruction and still differ in their flag register output. The undocumented F3 and F5 bits, the special CP flag behavior, the block instruction flag computations: these are what distinguish a correct emulator from an approximately correct one. Claude got the CP flag anomaly right (F3/F5 from the operand, not the result), which suggests it was working from specification knowledge about the Z80's internal bus routing rather than just copying a known-good flag computation.

Clean room constraints make LLM output more trustworthy, not less. There's an irony here: by restricting what the LLM can reference, you get more confidence in the result. If Claude had produced code that looked suspiciously like MAME's Z80 core, you'd wonder whether it was simply reciting training data. Instead, it produced an implementation that's structurally sound, stylistically distinct, and correct, the hallmarks of working from specifications rather than from examples.

The Code

The complete source is on GitHub, five files totaling roughly 3,000 lines of C. It builds with make, produces zero warnings with -Wall -Wextra, and runs Grant Searle and RC2014 BASIC ROMs out of the box.

$ make
cc -Wall -Wextra -O2 -o zxs zxs.c z80.c
cc -Wall -Wextra -O2 -o z80_test z80_test.c z80.c

$ ./z80_test
Z80 CPU Test Suite
==================
...
Results: 117/117 passed

$ ./zxs basic.rom
Z80 SBC By Grant Searle
Memory top?

There is more to do. ZEXALL compliance would be the next validation milestone; it tests every instruction against known-good results captured from real Z80 hardware. ZX Spectrum emulation would require adding ULA video, keyboard matrix scanning, and Spectrum-specific memory banking. Cycle-exact timing would enable accurate sound emulation and demo-scene effects.

But for now, the ROM boots, BASIC runs, and every line of the emulator traces back to Z80 specifications and documentation rather than someone else's z80.c. An LLM wrote it, but a human designed it, constrained it, tested it, and validated it against real hardware ROM images. The clean room constraint didn't just produce a trustworthy emulator; it produced a trustworthy process for using LLMs on systems programming tasks. Give the model a specification instead of an open-ended prompt. Enforce constraints that prevent training data regurgitation. Validate against real-world artifacts, not just unit tests.

Antirez asked whether LLMs create original code or decompress training data. This project is one more data point on the side of original creation, but only when you set up the conditions for it. The clean room is what makes the difference.

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.

George Morrow: Pioneer of Personal Computing

A.C. Jokela — Fri, 30 Jan 2026 15:00:00 GMT

In the pantheon of personal computing pioneers, certain names dominate the narrative: Steve Jobs, Steve Wozniak, Bill Gates. Yet the early microcomputer industry was built by dozens of brilliant engineers and entrepreneurs whose contributions, while perhaps less celebrated, were no less significant. Among these figures stands George C. Morrow, a man described by Richard Dalton in the Whole Earth Software Catalog as "one of the microcomputer industry's iconoclasts." His journey from high school dropout to computer industry pioneer to jazz preservationist tells a uniquely American story of reinvention, innovation, and passion.

From Detroit to Stanford: An Unconventional Path

George Morrow was born on January 30, 1934, in Detroit, Michigan. His early life followed an unconventional trajectory that would later inform his maverick approach to business. Morrow dropped out of high school, a decision that might have closed doors for others. But at the age of 28, driven by intellectual curiosity, he made the remarkable decision to return to education.

Morrow earned a bachelor's degree in physics from Stanford University, one of the nation's most prestigious institutions. He followed this with a master's degree in mathematics from the University of Oklahoma. Not content to stop there, he pursued doctoral studies in mathematics at the University of California, Berkeley. It was at Berkeley that Morrow's life took its decisive turn. Working as a programmer in the university's computer lab, he became captivated by the emerging world of computing. The pursuit of a PhD in mathematics gave way to a new passion that would define the rest of his career.

The Homebrew Computer Club and the Birth of an Industry

The year 1975 marked a watershed moment in computing history. The MITS Altair 8800 appeared on the cover of Popular Electronics, igniting the imagination of hobbyists and engineers across the country. In the San Francisco Bay Area, these enthusiasts began gathering at the Homebrew Computer Club, an informal group that would spawn an extraordinary number of future industry leaders.

Morrow became an active member of this legendary collective, documented extensively in Fire in the Valley. Among his fellow members were Steve Wozniak, who would co-found Apple; Harry Garland and Roger Melen of Cromemco; Adam Osborne of Osborne Computer; Lee Felsenstein, designer of the Osborne 1; and Bob Marsh of Processor Technology. The club served as an incubator for ideas, a forum for technical exchange, and a launching pad for commercial ventures.

From Morrow's Microstuff to Thinker Toys

Starting in 1976, Morrow began designing and selling computer parts and accessories. His first venture was Morrow's Microstuff, which sold memory boards for the Altair 8800 via mail order. His initial product was an Intel 8080 board featuring an octal-notation keypad, but it proved unappealing to hobbyists who preferred the binary notation and flip switches of the Altair itself.

Undeterred, Morrow pivoted to what would become his signature contribution: storage solutions. He began selling floppy disk drives for S-100 machines, packaging them as complete systems that included an 8-inch external drive, a controller board, the CP/M operating system, and CBASIC. This bundle proved enormously popular, establishing Morrow as a significant player in the nascent industry.

Morrow rebranded his company as Thinker Toys, a name that captured the playful yet serious nature of the hobbyist computing world. However, the toy company that manufactured Tinkertoys took exception to the similar name and threatened legal action. Morrow was forced to rename his business once more, this time as Morrow Designs, the name by which it would become best known. The company set up operations at 600 McCormick Street in San Leandro, California.

Bringing Mainframe Concepts to Microcomputers

What set Morrow apart from many competitors was his willingness to bring sophisticated engineering concepts from the mainframe world to microcomputers. The Disk Jockey/DMA (DJDMA) floppy disk controller exemplified this philosophy. As the company's technical documentation explained: "The idea of an intelligent I/O channel was first implemented by IBM on their famous 370 mainframes. Now for the first time, this powerful concept has been implemented on the S100 bus."

The DJDMA featured its own Z-80 4MHz microprocessor dedicated to supervising data transfers between disk drives and system memory. This "channel concept," borrowed directly from IBM's mainframe architecture, allowed the controller to operate independently of the main CPU. The documentation boasted: "All in all, there is nothing on the S-100 bus in the way of a floppy disk controller that comes anywhere near the performance and versatility of the DJDMA. For that matter, we here at Morrow Designs know of no other floppy disk controller on any bus that can match the DJDMA in price, power, performance, and flexibility."

This wasn't mere marketing hyperbole. The controller supported both 8-inch and 5¼-inch drives, could accommodate up to eight drives simultaneously, and featured programmable bipolar LSI logic that could read and write media with almost any format. The engineering approach reflected Morrow's belief that microcomputer users deserved the same sophisticated I/O handling that mainframe users enjoyed.

Morrow Designs also ventured into hard disk storage with products like the Discus M26, a complete mass storage subsystem with a 14-inch Winchester-type hard disk offering 26 million bytes of formatted storage, an enormous capacity for the era. The system could be expanded to 104 million bytes with four drives. The company was already planning cassette tape backup systems for 1980, recognizing the data security challenges posed by non-removable media.

The S-100 Bus and IEEE-696: Building Industry Standards

One of Morrow's most enduring contributions to computing was his work on the S-100 bus standard. The S-100 bus (named for its 100-pin connector) had originated with the Altair 8800. While it enabled a thriving ecosystem of compatible boards and peripherals, the lack of formal standardization created compatibility problems as manufacturers interpreted the bus specifications differently.

Morrow recognized that the industry needed rigorous standards to mature. The first symposium on the S-100 bus was held on November 20, 1976, at Diablo Valley College, moderated by Jim Warren with a panel that included Morrow, Harry Garland, and Lee Felsenstein. In July 1979, Morrow joined Kells Elmquist, Howard Fullmer, and David Gustavson in publishing a "Standard Specification for S-100 Bus Interface Devices," extending the data path to 16 bits and the address path to 24 bits.

The IEEE 696 Working Group continued developing the specification, which was approved by the IEEE Computer Society on June 10, 1982, and by ANSI on September 8, 1983 as IEEE Std 696-1983. Morrow was, by many accounts, the person most responsible for the design, specification, and approval of this standard. His DJDMA documentation reflected this commitment to standards: "A great deal of care has been taken in the design of the interface circuitry so it conforms in every detail to this new standard and still allows the controller to work well with existing systems designed before the standardization effort was started."

The Decision 1 and Micro Decision: Computing for Everyone

In 1979, George Morrow and his wife Michiko Jean formally incorporated Morrow Designs. The company's product line expanded to include complete computer systems aimed at making business computing affordable.

The Decision 1 represented the high end of Morrow's offerings. According to the December 1982 price list, the base D1 model sold for \$2,395 and featured an S-100 (IEEE 696) 14-slot motherboard, Z80 CPU, real-time CMOS clock/calendar chip, programmable interrupt controller, three RS232C serial ports, one parallel printer port, and 64K of high-speed static RAM expandable to a full megabyte. The top-of-the-line D3C model, with a 16-megabyte hard disk, commanded \$5,400. The company also offered multi-user upgrade kits with the Micronix operating system, enabling small businesses to share a single computer among multiple terminals.

But it was the Micro Decision line, introduced in 1982, that best exemplified Morrow's commitment to affordability. The MD1 started at just \$1,195 and included a Z80A CPU running at 4MHz, 64K of RAM, two RS232C serial ports, a floppy disk controller supporting up to four drives, and a complete software bundle: CP/M 2.2, Microsoft BASIC 80, the company's own BaZic interpreter (compatible with NorthStar BASIC), WordStar word processor, LogiCalc spreadsheet, and Correct-It spelling checker.

The MD2, with two single-sided drives providing 400K of storage, sold for \$1,545. The MD3, featuring two double-sided drives with 768K total storage plus the Personal Pearl database manager, cost \$1,695. Optional terminals (the MDT20 in beige or MDT50 in black) added \$595. These were remarkable prices for complete, software-bundled systems at a time when competing products often cost significantly more.

Bankruptcy and Beyond

As the IBM PC and its clones came to dominate the market, Morrow Designs faced an existential challenge. The company's CP/M-based systems, however excellent, were increasingly seen as outdated. In 1984, Morrow released the Pivot, an IBM-compatible portable computer, licensing the design to Zenith Electronics Corporation for \$1.2 million.

The Zenith deal, ironically, hastened the company's demise. In 1986, Zenith won a \$27 million contract with the Internal Revenue Service to supply computers based on Morrow's design. But the terms of the licensing agreement and the company's mounting debts proved unsustainable. On March 11, 1986, just weeks after Zenith won the IRS contract, Morrow Designs filed for bankruptcy.

Computer Chronicles and a Second Act

Even as his company struggled, Morrow found a new platform for his expertise. He became a co-host of Computer Chronicles, a public television program that explained computing to general audiences. Morrow appeared in over 40 episodes between 1985 and 1995, sharing his deep knowledge of hardware, software, and industry trends with viewers across the country. His appearances revealed the same qualities that had defined his career: technical depth combined with an ability to communicate complex ideas clearly, and an iconoclastic perspective that questioned industry assumptions.

Following the collapse of Morrow Designs, George Morrow turned to a passion he had nurtured throughout his life: jazz and big band music from the 1920s and 1930s. He assembled one of the largest private collections of 78 RPM records in the country, eventually exceeding 70,000 items, with a particular focus on rare dance and jazz recordings from the pre-war era.

Applying the same engineering mindset that had driven his computer work, he developed a sophisticated system to digitize and restore these fragile shellac recordings. His son John recalled that his father would labor for hours or even days over a single recorded song until satisfied with the restored version. Morrow released these painstakingly restored recordings under his own label, Old Masters, preserving an important piece of American musical heritage for future generations.

Legacy

George Morrow died on May 7, 2003, at his home in San Mateo, California, from complications of aplastic anemia. He was 69 years old. He was survived by his wife Michiko Jean, sons John and William, and daughter Kelly.

Morrow's contributions to computing extend far beyond the products that bore his name. His work on the IEEE-696 standard helped transform a hobbyist ecosystem into a professional industry. His decision to bring mainframe I/O concepts to microcomputers pushed the entire field forward. His commitment to affordable, software-bundled systems anticipated the value-driven approach that would eventually democratize personal computing.

The archive of Morrow Designs documentation (including technical manuals, BIOS source code, price lists, and product literature) survives as a resource for historians and retrocomputing enthusiasts. These documents reveal not just the products themselves but the engineering philosophy behind them: a belief that microcomputer users deserved sophisticated, well-documented systems at fair prices.

Perhaps most importantly, Morrow embodied the spirit of the early microcomputer industry: the conviction that small teams of dedicated engineers could build transformative technologies, that standards and cooperation could coexist with competition, and that computing should be accessible to everyone, not just institutions and corporations.

CP/M 2.2 on Physical Hardware: RetroShield Z80 with 1MB DRAM and SD Card Storage

A.C. Jokela — Wed, 07 Jan 2026 22:00:00 GMT

There's a profound difference between emulation and the real thing. While my previous post covered running CP/M on a software-based Z80 emulator, this post documents the journey of bringing CP/M 2.2 to life on actual Z80 silicon - a real Zilog Z80 CPU executing real machine code, with 1MB of DRAM and SD card storage for disk images.

The result? A fully functional CP/M system running Zork, all on an Arduino Mega 2560 acting as the glue between vintage and modern technology.

The Hardware Stack

Building a working CP/M system requires three essential components: a CPU, memory, and storage. Here's what I used:

The RetroShield Z80

The RetroShield from 8bitforce is a clever piece of engineering. It's a shield that holds a real Z80 CPU and lets an Arduino Mega control it cycle-by-cycle. The Arduino provides the clock, handles bus transactions, and emulates peripherals - but the Z80 is doing the actual computation.

The RetroShield uses nearly every pin on the Arduino Mega:

Function	Arduino Pins
Address Bus (A0-A15)	Pins 22-37
Data Bus (D0-D7)	Pins 42-49
Control Signals	Pins 38-41, 50-53

This pin-hungry design means we need to be creative about adding peripherals.

KDRAM2560: 1MB of Dynamic RAM

The KDRAM2560 is another 8bitforce product - a DRAM shield that provides a full megabyte of memory to the Arduino Mega. It uses the analog pins (A0-A15) for its interface, leaving digital pins available for other uses.

Why DRAM instead of SRAM? Cost and density. A megabyte of SRAM would be expensive and physically large. DRAM is cheap but requires periodic refresh to maintain data integrity. The KDRAM2560 library handles this automatically using one of the Arduino's hardware timers.

For CP/M, we only need 64KB of the available 1MB, but having extra memory opens possibilities for RAM disks or bank switching in future projects.

#define DRAM_REFRESH_USE_TIMER_1
#include <kdram2560.h>

void setup() {
    // Initialize DRAM - this also starts the refresh interrupt
    if (DRAM.begin(&Serial)) {
        Serial.println("KDRAM2560: OK (1MB DRAM)");
    } else {
        Serial.println("KDRAM2560: FAILED!");
        while (1) {}  // Halt
    }
}

The API is beautifully simple:

// Read a byte from any address in the 1MB space
byte data = DRAM.read8(address);

// Write a byte
DRAM.write8(address, data);

Internally, the library handles the complex multiplexed addressing that DRAM requires - splitting the 20-bit address into row and column components, managing RAS/CAS timing, and ensuring refresh cycles happen frequently enough to prevent data loss.

Software SPI SD Card

Here's where things get interesting. The obvious choice for SD card storage would be the Arduino's hardware SPI on pins 50-53. But look back at that pin table - the RetroShield uses pins 50-53 for Z80 control signals!

The solution is software SPI - bit-banging the SPI protocol on different pins. I chose pins 4-7, safely away from both the RetroShield and KDRAM2560:

SD Card Pin	Arduino Pin
MISO	Pin 4
MOSI	Pin 5
SCK	Pin 6
CS	Pin 7

The SdFat library supports software SPI through its SoftSpiDriver template class. One important note: you must set SPI_DRIVER_SELECT to 2 in SdFatConfig.h to enable this:

// In SdFat/src/SdFatConfig.h
#define SPI_DRIVER_SELECT 2  // Enable software SPI

Then in your sketch:

#include "SdFat.h"

const uint8_t SOFT_MISO_PIN = 4;
const uint8_t SOFT_MOSI_PIN = 5;
const uint8_t SOFT_SCK_PIN  = 6;
const uint8_t SD_CS_PIN     = 7;

SoftSpiDriver<SOFT_MISO_PIN, SOFT_MOSI_PIN, SOFT_SCK_PIN> softSpi;
#define SD_CONFIG SdSpiConfig(SD_CS_PIN, DEDICATED_SPI, SD_SCK_MHZ(0), &softSpi)

SdFs sd;

void setup() {
    if (sd.begin(SD_CONFIG)) {
        Serial.println("SD Card: OK (Software SPI)");
    }
}

Software SPI is slower than hardware SPI - roughly 20-50 KB/s compared to 1-2 MB/s. For loading programs at boot and occasional disk access, this is perfectly acceptable. You won't notice the difference playing Zork.

The Complete System Architecture

Here's how all the pieces fit together:

┌─────────────────────────────────────────────────────────────┐
│                      Arduino Mega 2560                      │
├─────────────────────────────────────────────────────────────┤
│  Z80 RetroShield (top layer)                                │
│    Real Zilog Z80 CPU @ ~100kHz                             │
│    Address: pins 22-37 (directly mapped)                    │
│    Data: pins 42-49 (directly mapped)                       │
│    Control: pins 38-41, 50-53                               │
├─────────────────────────────────────────────────────────────┤
│  KDRAM2560 (middle layer)                                   │
│    1MB DRAM via analog pins A0-A15                          │
│    Timer 1 interrupt for automatic refresh                  │
│    Only 64KB used for Z80 address space                     │
├─────────────────────────────────────────────────────────────┤
│  MicroSD Card (external, via jumper wires)                  │
│    Software SPI on pins 4-7                                 │
│    FAT32 formatted, ≤32GB                                   │
│    Contains: boot.bin, CPM.SYS, A.DSK, B.DSK                │
└─────────────────────────────────────────────────────────────┘

Peripheral Emulation: The Arduino's Role

While the Z80 executes code, the Arduino handles peripheral I/O. When the Z80 performs an IN or OUT instruction, the Arduino intercepts it and provides the appropriate response.

MC6850 ACIA (Serial Console)

The console uses a virtual MC6850 ACIA on I/O ports 0x80 (control/status) and 0x81 (data). This connects to the Arduino's Serial interface, which in turn connects to your terminal:

#define ADDR_6850_CONTROL     0x80
#define ADDR_6850_DATA        0x81

// In the I/O read handler:
if (ADDR_L == ADDR_6850_DATA) {
    // Z80 is reading from serial
    prevDATA = Serial.read();
}
else if (ADDR_L == ADDR_6850_CONTROL) {
    // Z80 is checking status
    // Bit 0: Receive data ready
    // Bit 1: Transmit buffer empty
    prevDATA = reg6850_STATUS;
}

// In the I/O write handler:
if (ADDR_L == ADDR_6850_DATA) {
    // Z80 is writing to serial
    Serial.write(DATA_IN);
}

SD Card Interface

The SD card interface uses ports 0x10-0x19, providing commands for file operations and DMA block transfers:

Port	Function
0x10	Command register
0x11	Status register
0x12	Data byte (single-byte I/O)
0x13	Filename character input
0x14-0x15, 0x19	Seek position (24-bit)
0x16-0x17	DMA address (16-bit)
0x18	Block command (0=read, 1=write)

The key innovation is the DMA block transfer. Instead of the Z80 reading 128 bytes one at a time through port 0x12 (which would require 128 IN instructions), it sets a DMA address and issues a single block command. The Arduino then copies 128 bytes directly between the SD card and DRAM:

void sd_do_block_read() {
    uint8_t buffer[128];
    sdFile.read(buffer, 128);

    // Copy directly to DRAM
    for (int i = 0; i < 128; i++) {
        DRAM.write8((unsigned long)(sdDmaAddr + i), buffer[i]);
    }
    sdBlockStatus = 0;  // Success
}

This makes disk operations reasonably fast despite the software SPI limitation.

The Boot Process

When the Arduino powers up, here's what happens:

Arduino Setup
Initialize Serial at 115200 baud
Initialize KDRAM2560 (starts refresh interrupt)
Initialize SD card via software SPI
Load boot.bin from SD card into DRAM at address 0x0000
Release Z80 from reset
Z80 Boot Loader (boot.bin)
Initialize the MC6850 ACIA
Print boot banner
Open CPM.SYS from SD card
Load it into DRAM at 0xE000 (53 sectors = 6,784 bytes)
Jump to BIOS cold start at 0xF600
CP/M BIOS Cold Start
Initialize disk variables
Set up page zero jump vectors
Print the welcome message
Jump to CCP (Console Command Processor)
You see the A> prompt!

The boot loader is about 330 bytes of Z80 assembly:

;========================================================================
; CP/M Boot Loader for RetroShield Z80
;========================================================================

CCP_BASE:       equ     0xE000
BIOS_BASE:      equ     0xF600
LOAD_SIZE:      equ     53              ; Sectors to load

                org     0x0000

BOOT:
                di
                ld      sp, 0x0400

                ; Print boot message
                ld      hl, MSG_BOOT
                call    PRINT_STR

                ; Open CPM.SYS
                ld      hl, FILENAME
                call    SD_SEND_NAME
                ld      a, CMD_OPEN_READ
                out     (SD_CMD), a

                ; Load CP/M system to memory
                ld      hl, CCP_BASE
                ld      b, LOAD_SIZE

LOAD_LOOP:
                push    bc
                push    hl

                ; Set DMA address
                ld      a, l
                out     (SD_DMA_LO), a
                ld      a, h
                out     (SD_DMA_HI), a

                ; Read 128-byte block via DMA
                xor     a
                out     (SD_BLOCK), a

                ; Print progress dot
                ld      a, '.'
                call    PRINT_CHAR

                pop     hl
                ld      de, 128
                add     hl, de
                pop     bc
                djnz    LOAD_LOOP

                ; Jump to BIOS
                jp      BIOS_BASE

CP/M Disk Images

CP/M uses a specific disk format based on the 8-inch floppy standard:

77 tracks
26 sectors per track
128 bytes per sector
256KB total capacity

The first two tracks are reserved for the system (though we load from CPM.SYS instead). The directory starts at track 2, sector 0 (byte offset 6,656 or 0x1A00).

I wrote a Python tool to create and manage these disk images:

# Create an empty disk image
python3 cpm_disk.py create A.DSK

# Add a file
python3 cpm_disk.py add A.DSK ZORK1.COM

# List files
python3 cpm_disk.py list A.DSK

The directory entry format is straightforward - 32 bytes per entry:

Offset	Size	Description
0	1	User number (0xE5 = empty/deleted)
1-8	8	Filename (space-padded)
9-11	3	Extension (space-padded)
12-15	4	Extent info and record count
16-31	16	Block allocation map

One gotcha: empty directory entries must be marked with 0xE5, not 0x00. A disk full of zeros will confuse CP/M into thinking it has files with blank names!

Loading Classic Software: Zork on Real Hardware

With the infrastructure in place, loading classic software is straightforward. I grabbed Zork I, II, and III from the cpm-dist repository:

# Add Zork to the A: drive
python3 cpm_disk.py add A.DSK ZORK1.COM
python3 cpm_disk.py add A.DSK ZORK1.DAT
python3 cpm_disk.py add A.DSK ZORK2.COM
python3 cpm_disk.py add A.DSK ZORK2.DAT

# Hitchhiker's Guide goes on B:
python3 cpm_disk.py add B.DSK HITCH.COM
python3 cpm_disk.py add B.DSK HITCHHIK.DAT

Copy the disk images to the SD card, insert it into the module, and reset the Arduino:

======================================
RetroShield Z80 CP/M 2.2
======================================

KDRAM2560:  OK (1MB DRAM)
SD Card:    OK (Software SPI)
Loading boot.bin...
Loaded 331 bytes to DRAM at 0x0000
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>DIR
A: ZORK1    COM : ZORK1    DAT : ZORK2    COM : ZORK2    DAT
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.

>

There's something deeply satisfying about this. The Z80 CPU running this game is the same architecture that ran it in 1981. The actual opcodes being executed are identical. We've just swapped floppy drives for SD cards and CRT terminals for USB serial.

The CPU Tick Loop: Where It All Comes Together

The heart of the system is the cpu_tick() function - called continuously in loop(), it handles one Z80 clock cycle:

inline __attribute__((always_inline))
void cpu_tick() {
    // Check for serial input
    if (Serial.available()) {
        reg6850_STATUS |= 0x01;  // Set RDRF
    }

    CLK_HIGH;  // Rising clock edge
    uP_ADDR = ADDR;  // Capture address bus

    // Memory access?
    if (!STATE_MREQ_N) {
        if (!STATE_RD_N) {
            // Memory read - get byte from DRAM
            DATA_DIR = DIR_OUT;
            DATA_OUT = DRAM.read8((unsigned long)uP_ADDR);
        }
        else if (!STATE_WR_N) {
            // Memory write - store byte to DRAM
            DRAM.write8((unsigned long)uP_ADDR, DATA_IN);
        }
    }
    // I/O access?
    else if (!STATE_IORQ_N) {
        if (!STATE_RD_N && prevIORQ) {
            // I/O read
            DATA_DIR = DIR_OUT;
            if (sd_handles_port(ADDR_L)) {
                prevDATA = sd_read_port(ADDR_L);
            }
            else if (ADDR_L == ADDR_6850_DATA) {
                prevDATA = Serial.read();
            }
            else if (ADDR_L == ADDR_6850_CONTROL) {
                prevDATA = reg6850_STATUS;
            }
            DATA_OUT = prevDATA;
        }
        else if (!STATE_WR_N && prevIORQ) {
            // I/O write
            DATA_DIR = DIR_IN;
            if (sd_handles_port(ADDR_L)) {
                sd_write_port(ADDR_L, DATA_IN);
            }
            else if (ADDR_L == ADDR_6850_DATA) {
                Serial.write(DATA_IN);
            }
        }
    }

    prevIORQ = STATE_IORQ_N;
    CLK_LOW;  // Falling clock edge
    DATA_DIR = DIR_IN;
}

This runs at roughly 100kHz - slow by modern standards, but plenty fast for interactive programs. The Z80 was designed for clock speeds of 2-4MHz, so we're running at about 3-5% of original speed. Text adventures don't mind.

The BIOS: Hardware Abstraction in 1KB

The CP/M BIOS is where the magic happens. It's the only part of CP/M that needs to be written for each new hardware platform. The BDOS and CCP are universal - they work on any machine with a conforming BIOS.

Our BIOS implements 17 entry points:

                org     BIOS_BASE       ; 0xF600

                jp      BOOT            ; 00 - Cold boot
WBOOTE:         jp      WBOOT           ; 03 - Warm boot
                jp      CONST           ; 06 - Console status
                jp      CONIN           ; 09 - Console input
                jp      CONOUT          ; 0C - Console output
                jp      LIST            ; 0F - List output
                jp      PUNCH           ; 12 - Punch output
                jp      READER          ; 15 - Reader input
                jp      HOME            ; 18 - Home disk
                jp      SELDSK          ; 1B - Select disk
                jp      SETTRK          ; 1E - Set track
                jp      SETSEC          ; 21 - Set sector
                jp      SETDMA          ; 24 - Set DMA address
                jp      READ            ; 27 - Read sector
                jp      WRITE           ; 2A - Write sector
                jp      LISTST          ; 2D - List status
                jp      SECTRAN         ; 30 - Sector translate

The most complex routines are the disk operations. READ and WRITE must calculate the byte offset within the disk image from track and sector numbers:

CALC_OFFSET:
        ; offset = (track * 26 + sector) * 128
        ld      hl, (TRACK)
        ld      de, 26          ; Sectors per track
        call    MULT16          ; HL = track * 26
        ld      de, (SECTOR)
        add     hl, de          ; HL = track * 26 + sector

        ; Multiply by 128 (shift left 7 times)
        xor     a               ; Clear carry byte
        add     hl, hl          ; *2
        adc     a, 0
        add     hl, hl          ; *4
        adc     a, a
        ; ... continue shifting ...

        ld      (SEEKPOS), hl
        ld      (SEEKPOS+2), a  ; 24-bit result
        ret

The Disk Parameter Block (DPB) tells CP/M about our disk geometry:

DPB:
        defw    26              ; SPT - sectors per track
        defb    3               ; BSH - block shift (1K blocks)
        defb    7               ; BLM - block mask
        defb    0               ; EXM - extent mask
        defw    242             ; DSM - total blocks - 1
        defw    63              ; DRM - directory entries - 1
        defb    0xC0            ; AL0 - allocation bitmap
        defb    0x00            ; AL1
        defw    16              ; CKS - checksum size
        defw    2               ; OFF - reserved tracks

These parameters define a standard 256KB 8-inch floppy format - the same format used by countless CP/M machines in the late 1970s.

Understanding CP/M's Memory Model

CP/M's memory layout is elegantly simple. The entire operating system fits in the top 8KB of the 64KB address space:

┌───────────────────────────────────────┐ 0xFFFF
│              BIOS                     │ ~1KB - Hardware abstraction
├───────────────────────────────────────┤ 0xF600
│              BDOS                     │ ~3.5KB - File system, I/O
├───────────────────────────────────────┤ 0xE800
│              CCP                      │ ~2KB - Command processor
├───────────────────────────────────────┤ 0xE000
│                                       │
│                                       │
│              TPA                      │ ~56KB - Your programs!
│     (Transient Program Area)          │
│                                       │
│                                       │
├───────────────────────────────────────┤ 0x0100
│          Page Zero                    │ 256 bytes - System variables
└───────────────────────────────────────┘ 0x0000

Page Zero contains crucial system information:

0x0000-0x0002: Jump to warm boot
0x0005-0x0007: Jump to BDOS entry
0x005C: Default FCB (File Control Block)
0x0080: Default DMA buffer / command tail

When you type ZORK1 at the command prompt, CP/M loads ZORK1.COM at address 0x0100 and jumps there. The program has nearly 56KB to work with - a luxurious amount of memory for 1970s software.

Debugging Tips

Getting CP/M running required extensive debugging. Here are some tips if you're attempting something similar:

Enable Debug Output

Set outputDEBUG to 1 in the Arduino sketch to see every I/O operation:

#define outputDEBUG     1

This prints every port read/write, which is invaluable for tracking down why the BIOS isn't finding files or why sectors are being read from wrong locations.

Check Your Directory Format

The most common issue I encountered was improperly formatted disk images. Use a hex editor to verify:

Directory starts at offset 0x1A00 (6656 bytes)
Empty entries have 0xE5 in byte 0, not 0x00
Filenames are space-padded to 8 characters, extensions to 3

Verify DMA Addresses

If programs load but crash immediately, check that the DMA address is being set correctly. The BIOS must output both low and high bytes:

ld      a, l
out     (SD_DMA_LO), a
ld      a, h
out     (SD_DMA_HI), a

Watch for Register Clobbering

Z80 subroutine calls don't preserve registers by default. If your SELDSK routine returns garbage, check whether the OPENDISK helper is destroying HL before the return.

Performance Considerations

The system runs at approximately 100kHz - about 3% of the Z80's original 4MHz speed. This is limited by:

Arduino loop overhead: Each cpu_tick() call has function call overhead
DRAM access time: Software-controlled DRAM is slower than dedicated hardware
Software SPI: Bit-banging SPI adds latency to disk operations

For interactive programs like text adventures, this is imperceptible. For computation-heavy tasks, you'd notice the slowdown. WordStar feels sluggish but usable; compiling code would test your patience.

Future optimizations could include:

Assembly-optimized cpu_tick() routine
Hardware SPI with a different pin arrangement
Overclocking the Arduino (at your own risk)

Challenges and Solutions

Challenge 1: Pin Conflicts

The RetroShield claims the hardware SPI pins (50-53). Solution: software SPI on alternate pins. The SdFat library's SoftSpiDriver template makes this painless.

Challenge 2: Memory Refresh

DRAM needs refresh every few milliseconds or it loses data. Solution: the KDRAM2560 library uses Timer 1 interrupts to handle this transparently. The refresh happens in the background - you never need to think about it.

Challenge 3: Disk Image Format

CP/M expects 0xE5 (not 0x00) for empty directory entries. A disk image initialized to all zeros will confuse CP/M into displaying phantom files. Solution: the cpm_disk.py tool properly initializes the directory.

Challenge 4: 24-bit Seek Positions

Disk images are 256KB, requiring 18 bits to fully address. My initial 16-bit seek implementation couldn't access sectors past track 51. Solution: added a third seek port (0x19) for bits 16-23.

Challenge 5: SELDSK Return Value Bug

CP/M's BDOS expects SELDSK to return a pointer to the Disk Parameter Header in HL. My initial code calculated this pointer, then called OPENDISK which clobbered HL. Solution: push/pop HL around the OPENDISK call.

Getting Started: Bill of Materials

To build your own CP/M machine, you'll need:

Item	Approximate Cost
Arduino Mega 2560	$15-40
Z80 RetroShield	$35
KDRAM2560	$20
MicroSD Card Module	$5
MicroSD Card (≤32GB FAT32)	$5-10
Jumper wires	$5
Total	~$100-130

Files and Resources

The complete Arduino sketch and supporting files are available on GitHub:

Arduino Sketch: kz80_cpm.ino
Boot Loader Source: boot.asm
BIOS Source: bios.asm
Disk Image Tool: cpm_disk.py

Required libraries: - KDRAM2560 - 1MB DRAM library - SdFat - SD card with software SPI support

Conclusion

Building this system was a journey through computing history. CP/M's clean architecture - the separation of BIOS, BDOS, and CCP - made it possible to port a 45-year-old operating system to completely alien hardware in a matter of days. For a fascinating look at CP/M in its heyday, check out the Computer Chronicles episode on CP/M from 1984.

The Z80 doesn't know it's being fed clock pulses by an Arduino, that its memory is dynamic RAM on a shield, or that its "floppy drives" are files on an SD card. It just executes its opcodes, one after another, exactly as it did in 1978.

And somewhere in that stream of opcodes, a small mailbox waits west of a white house, just as it has for over four and a half decades.

>open mailbox
Opening the small mailbox reveals a leaflet.

>read leaflet
"WELCOME TO ZORK!

ZORK is a game of adventure, danger, and low cunning. In it you will
explore some of the most amazing territory ever seen by mortals..."

Welcome to the underground empire. The password is nostalgia, and the treasure is understanding how elegantly simple these early systems really were.

Running CP/M 2.2 on the RetroShield Z80 Emulator

A.C. Jokela — Wed, 31 Dec 2025 16:00:00 GMT

There's something magical about watching a 45-year-old operating system boot on modern hardware. CP/M 2.2, the operating system that launched a thousand microcomputers and paved the way for MS-DOS, still has lessons to teach us about elegant system design.

This post documents my journey getting CP/M 2.2 running on the RetroShield Z80 emulator, a Rust-based Z80 emulator I've been developing. The result is a fully functional CP/M system that can run classic software like Zork and WordStar.

What is CP/M?

CP/M (Control Program for Microcomputers) was created by Gary Kildall at Digital Research in 1974. It became the dominant operating system for 8-bit microcomputers in the late 1970s and early 1980s, running on machines like the Altair 8800, IMSAI 8080, Osborne 1, and Kaypro.

CP/M's genius was its portability. The system separated into three layers:

CCP (Console Command Processor) - The command line interface
BDOS (Basic Disk Operating System) - File and I/O services
BIOS (Basic Input/Output System) - Hardware abstraction

Only the BIOS needed to be rewritten for each machine. This architecture directly influenced MS-DOS and, by extension, every PC operating system that followed.

The RetroShield Z80 Emulator

The RetroShield is a hardware shield that lets you run vintage CPUs on modern microcontrollers. My emulator takes this concept further by providing a complete software simulation of the Z80 and its peripherals.

The emulator includes:

Full Z80 CPU emulation (via the rz80 crate)
MC6850 ACIA serial port (console I/O)
SD card emulation with DMA block transfers
TUI debugger with memory viewer, disassembly, and single-stepping

The Challenge: Disk I/O

Getting CP/M's console I/O working was straightforward. The real challenge was disk I/O. CP/M expects to read and write 128-byte sectors from floppy disks. I needed to emulate this using files on the host system.

The standard 8" single-sided, single-density floppy format that CP/M uses:

77 tracks
26 sectors per track
128 bytes per sector
256KB total capacity

DMA Block Transfers

Rather than transferring bytes one at a time through I/O ports (which would be painfully slow), I implemented DMA block transfers. The BIOS sets up a DMA address and issues a single command to transfer an entire 128-byte sector:

; Set DMA address
ld      hl, (DMAADR)
ld      a, l
out     (SD_DMA_LO), a
ld      a, h
out     (SD_DMA_HI), a

; Issue block read
xor     a
out     (SD_BLOCK), a

; Check status
in      a, (SD_BLOCK)
ret                     ; A = 0 if OK

On the emulator side, this triggers a direct memory copy from the disk image file into emulated RAM.

The Bug That Almost Defeated Me

After implementing everything, CP/M would boot and print its banner, but then hang or show garbage. The debug output revealed the BDOS was requesting insane track numbers like 0x0083 instead of track 2.

The culprit? A classic use-after-move bug in the BIOS:

SELDSK:
    ; Calculate DPH address in HL
    ld      l, c
    ld      h, 0
    add     hl, hl          ; *16
    add     hl, hl
    add     hl, hl
    add     hl, hl
    ld      de, DPH0
    add     hl, de

    call    OPENDISK        ; BUG: This overwrites HL!
    ret                     ; Returns garbage instead of DPH

The OPENDISK subroutine was using HL internally, destroying the Disk Parameter Header address that SELDSK was supposed to return. The BDOS would then read garbage from the wrong memory location for its disk parameters.

The fix was simple:

    push    hl
    call    OPENDISK
    pop     hl              ; Restore DPH address
    ret

24-bit Seek Positions

Another issue: the disk images are 256KB, but I initially only supported 16-bit seek positions (64KB max). I added an extended seek port for the high byte:

pub const SD_SEEK_LO: u8 = 0x14;    // Bits 0-7
pub const SD_SEEK_HI: u8 = 0x15;    // Bits 8-15
pub const SD_SEEK_EX: u8 = 0x19;    // Bits 16-23

The Memory Map

CP/M's memory layout for a 56KB TPA (Transient Program Area):

0000-00FF   Page Zero (jump vectors, FCB, command buffer)
0100-DFFF   TPA - User programs load here (56KB)
E000-E7FF   CCP - Console Command Processor
E800-F5FF   BDOS - Basic Disk Operating System
F600-FFFF   BIOS - Hardware abstraction layer

The BIOS is only about 1KB of Z80 assembly, handling:

Console I/O via the MC6850 ACIA
Disk I/O via SD card emulation
Drive selection and track/sector positioning

Running Classic Software

With CP/M booting successfully, I could run classic software:

Zork I - Infocom's legendary text adventure runs perfectly:

WordStar 3.3 and SuperCalc also run, though they need terminal escape codes configured properly (the Kaypro version uses ADM-3A codes).

Try It Yourself

The code is available on GitHub:

RetroShield Z80 Emulator - The Rust emulator with SD card DMA support
RetroShield CP/M - BIOS, boot loader, and CP/M system files

To run:

cd emulator/rust
cargo build --release
./target/release/retroshield_tui -s storage path/to/boot.bin

Press F5 to run, then type zork1 at the A> prompt.

Lessons Learned

Building this system reinforced some timeless principles:

Abstraction layers work. CP/M's BIOS/BDOS/CCP split made porting trivial. Only 1KB of code needed to be written for a completely new "hardware" platform.
Debug output is essential. Adding hex dumps of track/sector values immediately revealed the SELDSK bug.
Read the documentation. The CP/M 2.2 System Alteration Guide is remarkably well-written and explained exactly what the BIOS functions needed to do.
Old code still runs. With the right emulation layer, 45-year-old binaries execute flawlessly. The Z80 instruction set is eternal.

There's a certain satisfaction in seeing that A> prompt appear. It's the same prompt that greeted users in 1977, now running on code I wrote in 2025. The machines change, but the software endures.

What VisiCalc Teaches Us About AI: The 45-Year Pattern of "This Time It's Different"

A.C. Jokela — Fri, 26 Dec 2025 18:00:00 GMT

I was born in the back half of 1980, which means I missed the revolution.

By the time I sat down at an Apple IIe in 1986, with its green phosphor glow and chunky 5.25-inch floppies, the war was already over. The Altair 8800 was a museum piece. CP/M was fading into obscurity. The TRS-80 and Commodore PET were yesterday's news. I arrived just in time for the Apple II's twilight years, blissfully unaware that the machine in front of me represented the victory lap of a decade-long transformation.

I never experienced CP/M. I never loaded WordStar from an 8-inch floppy. I never watched VisiCalc recalculate a spreadsheet and felt the shock of a machine doing in seconds what had taken hours by hand. These were foundational moments in computing history, and I missed them entirely.

Now, decades later, I find myself building Z80 emulators and writing compilers for a processor that had already ceded the PC spotlight by the time I could read, though it quietly lived on in the TI graphing calculators that would later get me through high school math, and still powers them today. It's a form of technological archaeology, reconstructing a world I never lived in, trying to understand the texture of an era I only know through documentation and nostalgia. And from this vantage point, watching the current panic over artificial intelligence, I can't help but notice something: we've been here before.

As 2025 quickly fades. ChatGPT writes code. Midjourney creates art. Claude analyzes documents. The headlines scream that knowledge workers are doomed, that white-collar jobs will evaporate, that "this time it's different."

But it's not different. It's never different. And VisiCalc can prove it.

The World Before the Spreadsheet

To understand why VisiCalc mattered, you need to understand what "spreadsheet" meant in 1978. It wasn't software. It was paper.

Accountants, analysts, and financial planners worked with literal sheets of paper, ruled into rows and columns. They called them spreadsheets because the worksheets spread across multiple pages, sometimes taped together into unwieldy grids that covered entire desks. Every number was written by hand. Every calculation was performed with a mechanical adding machine or, if you were modern, an electronic calculator.

Here's what financial planning looked like: You'd spend hours, maybe days, building a projection. Revenue assumptions in one column, cost structures in another, profit margins calculated cell by cell. Then your boss would ask a simple question: "What if we increase prices by 5%?"

And you'd start over.

Not from the pricing cell. From every cell that pricing touched. The cascade of recalculations could take hours. A complex model might require a full day to revise. And if you made an error somewhere in the middle? Good luck finding it in a forest of pencil marks and eraser smudges.

Word processing was no better. Before WordStar and its competitors, documents were produced on typewriters. The IBM Selectric was the gold standard, a marvel of engineering that let you swap font balls and correct single characters with lift-off tape. But if you found a typo on page 47 of a 60-page contract, you had options: live with it, or retype pages 47 through 60.

Typing was a specialized profession. Companies maintained typing pools, rooms full of secretaries whose primary job was converting handwritten drafts and dictation into finished documents. A skilled typist was a valuable employee precisely because the work was so labor-intensive.

And if you needed computing power for serious analysis, you went to the mainframe. You submitted your job to the MIS department, waited in a queue, and paid by the CPU-minute. Time-sharing systems charged hundreds of dollars per hour. Computing was a scarce resource, rationed by bureaucracy.

This was knowledge work in the mid-1970s: manual, slow, expensive, and error-prone.

The Revolution No One Expected

Dan Bricklin was a Harvard MBA student in 1978 when he had the insight that would change everything. Sitting in a classroom, he watched a professor work through a financial model on a blackboard. The professor would write numbers, perform calculations, and fill in cells. Then he'd change an assumption, and the recalculation cascade would begin: erasing, recomputing, rewriting, sometimes running out of blackboard space.

Bricklin's thought was simple: what if the blackboard could recalculate itself?

Working with programmer Bob Frankston, Bricklin built VisiCalc, the "visible calculator." It ran on the Apple II, which was itself a hobbyist curiosity, a machine that enthusiasts bought to tinker with BASIC programs and play primitive games. VisiCalc transformed it into a business tool.

The software shipped in 1979, priced at \$100. Within a year, it was selling 12,000 copies per month. More importantly, it was selling Apple IIs. The \$2,000 computer became justifiable as a business expense because VisiCalc made it productive.

Consider the economics. A financial analyst in 1980 earned perhaps \$25,000 per year. A secretary earned \$12,000 to \$15,000. The Apple II plus VisiCalc cost roughly \$2,500. If the software saved a few weeks of analyst time, or let one analyst do the work that had previously required two, it paid for itself almost immediately.

But the real magic wasn't cost savings; it was capability. Suddenly you could ask "what if?" as many times as you wanted. Change an assumption, watch the spreadsheet ripple with recalculations, and see the answer in seconds. Financial modeling went from a laborious exercise in arithmetic to an exploratory conversation with your data.

WordStar, released a year earlier in 1978, performed the same transformation for documents. Write, edit, revise, move paragraphs, fix typos, all before committing anything to paper. The document existed as a malleable thing, not a fixed artifact produced through irreversible mechanical action.

Together, these applications (and others like dBASE for databases and SuperCalc as a VisiCalc competitor) created the productivity software category. They didn't sell computers to hobbyists; they sold computers to businesses. And they did it by solving mundane problems: arithmetic and typing.

The pundits of the era made predictions. Accountants would become obsolete. Secretaries would be eliminated. The typing pool would vanish. Knowledge work itself was being automated.

What Actually Happened

The predictions were wrong. Or rather, they were right about the transformation but wrong about the outcome.

Typing pools did shrink. The specialized profession of "typist" largely disappeared as word processing became a universal skill. But administrative assistants didn't vanish; their job changed. Instead of spending hours producing documents, they spent hours managing calendars, coordinating logistics, and handling communication. The mechanical work evaporated; the judgment work remained.

Bookkeepers declined as a profession. The person whose job was to maintain ledgers and perform routine calculations found that job automated. But accountants, the people who interpreted the numbers, made recommendations, and exercised judgment, grew in number. The Bureau of Labor Statistics shows steady growth in accounting employment through the 1980s and 1990s, even as the basic arithmetic of accounting was completely automated.

Financial analysts became more valuable, not less. The spreadsheet didn't replace them; it amplified them. An analyst who could build sophisticated models in VisiCalc or Lotus 1-2-3 was worth more than one limited to paper. The ceiling rose.

And here's the crucial point: the total amount of analysis, documentation, and financial modeling exploded. When something becomes cheaper and faster to produce, you produce more of it. Companies that had operated with crude annual budgets started building detailed monthly projections. Reports that had been quarterly became weekly. The volume of knowledge work grew to fill the new capacity.

This pattern (automation making workers more productive, which increases demand for the work, which maintains or increases employment) has a name in economics. It's called the Jevons paradox, originally observed in coal consumption: as steam engines became more efficient, total coal usage increased rather than decreased, because efficiency made steam power economical for more applications.

The same paradox applies to labor. Make an accountant 10x more productive, and you don't need 1/10th as many accountants. You do 10x as much accounting.

The Pattern Repeats

VisiCalc wasn't the first technology to trigger predictions of labor displacement, and it certainly wasn't the last. The pattern repeats with remarkable consistency:

ATMs (1970s-present): Automated Teller Machines were supposed to eliminate bank tellers. The math seemed obvious: why pay a human to dispense cash when a machine could do it? Yet U.S. bank teller employment roughly doubled between 1970 and 2010. The explanation: ATMs made bank branches cheaper to operate, so banks opened more branches, each requiring fewer but still some tellers. And the tellers' jobs shifted from cash handling to sales, complex transactions, and customer relationships.

CAD Software (1980s): Computer-aided design was going to eliminate draftsmen. Instead, it eliminated hand drafting while increasing demand for designers. The ability to iterate quickly, produce more alternatives, and handle more complex designs meant more design work overall.

Desktop Publishing (1980s): PageMaker and QuarkXPress would kill graphic designers by letting anyone create professional documents. Instead, the volume of designed materials exploded, and graphic design became a larger profession. The average quality rose because the floor rose.

Legal Research Databases (1990s): LexisNexis and Westlaw would eliminate paralegals by automating case research. Instead, faster research enabled more litigation, more thorough preparation, and more legal work overall.

Electronic Trading (1990s-2000s): Algorithmic trading would eliminate floor traders and financial professionals. It did eliminate floor traders, but the financial sector's employment grew as new roles emerged: quants, algorithm developers, risk managers, compliance officers.

In every case, the predictions followed the same logic: Technology X automates task Y, therefore workers who do Y are obsolete. And in every case, the predictions missed the second-order effects: automation makes the overall activity more valuable, demand increases, and workers shift to higher-judgment versions of the same work.

The AI Moment

Which brings us to now.

ChatGPT was released in November 2022. Within two months, it had 100 million users. Within a year, AI assistants were embedded in products from Microsoft to Google to Adobe. Large language models could write essays, generate code, summarize documents, answer questions, and produce content that was, on first glance, indistinguishable from human output.

The predictions arrived immediately. Programmers would become obsolete. Writers were doomed. Customer service, legal research, financial analysis, medical diagnosis: all would be automated. Goldman Sachs estimated 300 million jobs would be affected. The World Economic Forum issued reports. Thought leaders proclaimed that "this time it's different."

But is it?

Let's apply the VisiCalc framework. What exactly does AI automate?

First drafts, not final judgment. AI can produce a draft document, a code snippet, an analysis outline. What it cannot do is determine whether that draft serves the actual goal, handles the edge cases that matter, or fits the political context of the organization. The human reviews, revises, and takes responsibility.

Pattern matching, not pattern breaking. Large language models are, at their core, sophisticated pattern matchers trained on existing text. They excel at producing outputs that look like their training data. They struggle with genuine novelty: situations unlike anything in the training corpus, problems that require inventing new approaches rather than recombining old ones.

The middle of the distribution, not the edges. AI handles routine cases well. It struggles with outliers. The customer service bot can resolve common issues; the unusual complaint needs a human. The coding assistant can generate boilerplate; the architectural decision requires judgment.

Production, not accountability. AI can produce outputs, but it cannot be held accountable for them. When the document goes to the client, someone signs it. When the code ships to production, someone owns it. When the decision has consequences, someone faces them. That someone is human, because accountability requires agency, and agency requires humanity.

This is exactly the pattern we saw with spreadsheets. VisiCalc automated arithmetic, not judgment. It automated production, not accountability. It handled the routine middle, not the novel edges. And the humans who learned to use it became more valuable, not less.

The Irreducible Human

Why do humans remain in the loop? Not for sentimental reasons. Not because we want to preserve jobs. But because certain functions cannot be automated, regardless of how sophisticated the technology.

Accountability requires agency. When something goes wrong, someone must be responsible. Legal systems, regulatory frameworks, and social structures all assume a responsible party. AI systems can produce outputs, but they cannot be sued, fired, jailed, or shamed. The human who relies on AI output remains accountable for that output. This isn't a bug; it's a feature of how human society functions.

Context is infinite and local. AI models are trained on general patterns. Your specific situation (your company's politics, your client's unspoken concerns, your industry's unwritten rules) is not in the training data. The model knows what words typically follow other words. It doesn't know that your CFO hates bullet points, that your customer is going through a divorce, or that mentioning the competitor's product is forbidden in this meeting. The human provides context.

Trust requires relationship. Business transactions ultimately rest on trust between humans. You hire the lawyer, not the legal database. You trust your doctor, not the diagnostic algorithm. You buy from salespeople, not recommendation engines. AI can support these relationships, but it cannot replace them, because trust is a human phenomenon.

The feedback loop requires humans. Here's a subtle but critical point: AI systems are trained on human-generated data. If humans stop producing original work, the training data stops improving. The model learns to produce outputs that look like human outputs because it was trained on human outputs. Remove the humans, and you get a system trained on its own outputs, a recursive degradation. We are the curriculum.

Novel situations require genuine understanding. AI excels at interpolation, finding patterns within the space of its training data. It struggles with extrapolation, handling situations outside that space. Genuine novelty, by definition, lies outside the training distribution. The unprecedented situation, the black swan event, the "we've never seen this before" moment: these require human judgment, because no pattern matching can help when there's no pattern to match.

The Reskilling Reality

None of this means AI changes nothing. It changes a lot. The question is what kind of change.

When spreadsheets arrived, certain skills became less valuable. Manual arithmetic, once essential for financial work, became irrelevant. The ability to maintain error-free ledgers through careful penmanship mattered less. Slide rule proficiency joined buggy whip maintenance in the museum of obsolete competencies.

But new skills became essential. Building spreadsheet models, understanding the logic of cell references, knowing how to structure data for analysis: these became core professional competencies. "Computer literacy" emerged as a job requirement. People who learned the new tools thrived; people who refused to adapt struggled.

AI is triggering the same shift. Consider what becomes less valuable:

Writing first drafts from scratch. When AI can produce a competent first draft in seconds, the ability to stare at a blank page and produce prose is less differentiating. The value shifts to editing, directing, and refining.

Routine research and compilation. When AI can summarize documents, extract key points, and synthesize information, the human who only does that work has a problem. The value shifts to evaluating sources, asking the right questions, and interpreting results.

Basic code production. When AI can generate boilerplate, implement standard patterns, and translate requirements into code, the programmer whose main skill is typing syntax is in trouble. The value shifts to architecture, debugging, code review, and understanding what the system should do.

And consider what becomes more valuable:

Judgment and curation. AI produces. Humans evaluate. The ability to look at AI output and quickly determine what's useful, what's wrong, and what's missing becomes essential. This is editing in the broadest sense, not just fixing typos, but directing the creative process.

Domain expertise plus AI fluency. The accountant who understands both accounting and how to leverage AI tools is more valuable than either an accountant who ignores AI or an AI operator who doesn't understand accounting. The combination is the new competency.

Handling exceptions and edge cases. As AI handles the routine middle, humans focus on the exceptions. The unusual customer complaint, the novel legal situation, the unprecedented technical problem: these become the human domain. Expertise in handling weirdness becomes more valuable.

Relationship and trust building. As transactional work becomes automated, relationship work becomes relatively more important. The human who can build trust, navigate politics, and close deals face-to-face has a durable advantage.

This is exactly what happened with spreadsheets. The value shifted from arithmetic to analysis, from production to judgment, from routine to exception. The workers who adapted thrived. The workers who clung to obsolete methods struggled.

The Transition Is Never Painless

I don't want to minimize the disruption. Real people, with real skills, face real challenges when technology shifts beneath them.

The typing pool secretary in 1985 had spent years developing speed and accuracy on the Selectric. She could type 80 words per minute with minimal errors. She knew the quirks of carbon paper, the rhythm of the carriage return, the muscle memory of the key layout. These skills, honed over a decade, became worthless in the span of a few years.

Some of those secretaries learned WordPerfect and became administrative assistants. Some moved into other roles entirely. Some struggled, unable or unwilling to adapt, and found themselves squeezed out of the workforce. The aggregate statistics (employment levels, productivity growth, economic expansion) hide individual stories of dislocation and difficulty.

The same will be true of AI. Some knowledge workers will adapt smoothly, integrating AI tools into their workflow and becoming more productive. Some will resist, clinging to methods that worked in 2020 but feel increasingly obsolete by 2030. Some will find themselves displaced, their particular bundle of skills suddenly less valuable in a market that's moved on.

The historical pattern tells us that the net outcome is positive, that technological transitions create more opportunity than they destroy, that the economy adjusts, that new roles emerge. But history is cold comfort to the individual caught in the transition. The typewriter repairman didn't care that computer technicians were a growing field. He cared that his skills were worthless.

This is why the reskilling conversation matters. Not because AI will eliminate all jobs (it won't) but because the specific jobs, the specific skills, the specific ways of working will change. And navigating that change requires awareness, adaptability, and often institutional support.

The workers who thrived through the spreadsheet revolution weren't necessarily the most skilled at the old methods. They were the ones who recognized the shift and moved with it. The accountant who embraced Lotus 1-2-3, even if she was mediocre at mental arithmetic, outcompeted the brilliant human calculator who refused to touch a keyboard.

The same pattern is emerging now. The programmer who integrates AI assistance, even if she's not the fastest typist, will outcompete the keyboard wizard who insists on writing every character manually. The writer who uses AI for drafts and focuses on editing and judgment will outcompete the prose stylist who spends hours on first drafts. The analyst who lets AI handle data compilation and focuses on interpretation will outcompete the Excel jockey who takes pride in manual formula construction.

Adaptation isn't optional. It wasn't optional in 1980, and it isn't optional now.

The Long View

I spend my weekends building emulators for 50-year-old processors. I write compilers that target the Z80, a chip that was designed when Gerald Ford was president. I run BASIC and FORTH on simulated hardware, watching instructions execute that were first written when disco was young.

From this perspective, the current AI moment looks familiar. Technology extends human capability. It always has. The accountant with VisiCalc wasn't replaced; she was amplified. The writer with WordStar wasn't obsolete; he was leveraged. The analyst with a spreadsheet could do in hours what had taken days, and that made analysis more valuable, not less.

When I run my Z80 emulator (JavaScript interpreting WebAssembly interpreting 1976 machine code) I'm witnessing layers of abstraction that would have seemed like science fiction to the engineers who designed the original chip. But the fundamental relationship remains: humans using tools to extend their capabilities.

The nature of work changes. It always changes. The bookkeeper becomes the accountant. The typist becomes the administrative assistant. The draftsman becomes the designer. The job titles shift, the tools evolve, the skills required transform. But the need for human judgment, human accountability, human creativity, and human relationships remains.

This isn't optimism. It's pattern recognition. The 45-year pattern from VisiCalc to ChatGPT is consistent: technology that automates tasks changes the nature of work without eliminating the need for workers. The "this time it's different" predictions have been wrong every time, not because technology isn't powerful, but because the predictions misunderstand the relationship between automation and human labor.

The spreadsheet didn't eliminate the need for human intelligence. It made human intelligence more valuable by freeing it from arithmetic. AI won't eliminate the need for human judgment. It will make human judgment more valuable by freeing it from production.

We've been here before. And we'll be here again, decades from now, when some new technology triggers the same predictions, and historians look back at our AI panic the way we look back at the VisiCalc panic, as an understandable overreaction that missed the larger pattern.

The work changes. The workers adapt. The need for humans persists.

It's not different this time. It never is.

Z80 CP/M: History and Legacy and Emulation

A.C. Jokela — Sat, 19 Aug 2023 17:23:47 GMT

After reading an article that Adafruit put out on running CP/M on an emulator running on an Arduino, I thought I could expand up the article and add to the story. Enjoy.

In the early years of microcomputers, their processing power was incredibly limited compared to what we are accustomed to today. These devices, which emerged in the 1970s, were designed to be affordable and accessible for individual users, businesses, and small organizations, marking a stark departure from the large and expensive mainframes and minicomputers of the time. However, this accessibility came at a cost: the processing capabilities of these early microcomputers were constrained by the technology of the era, as well as by economic and practical considerations.

One of the initial limitations of early microcomputers was the processor itself. Early models, such as the Altair 8800 and Apple I, relied on 8-bit microprocessors like the Intel 8080 and MOS 6502. These 8-bit processors could typically handle only very simple calculations and operations in comparison to more advanced processors. Clock speeds were also significantly lower; they generally ranged from under 1 MHz to a few MHz. This lack of processing speed constrained the tasks that these computers could perform; complex calculations, large datasets, and intricate simulations were largely beyond their reach.

Memory was another significant limiting factor. Early microcomputers were equipped with a very small amount of RAM, often measured in kilobytes rather than the gigabytes or terabytes commonplace today. The limited RAM constrained the size and complexity of the programs that could be run, as well as the amount of data that could be processed at one time. It was not uncommon for users to constantly manage their memory use meticulously, choosing which programs and data could be loaded into their precious few kilobytes of RAM.

Storage capacity in early microcomputers was also quite constrained. Hard drives were expensive and uncommon in the earliest microcomputers, which often used cassette tapes or floppy disks for data storage. These mediums offered extremely limited storage capacity, often on the order of a few tens or hundreds of kilobytes. This required users to be extremely judicious with how they used and stored data and software, as the total available storage space was minuscule compared to today's standards.

In addition to hardware limitations, the software available for early microcomputers was often rudimentary due to the limited processing power. Graphical interfaces were virtually non-existent in the earliest microcomputers, with users typically interacting with the system through text-based command-line interfaces. Software applications were often basic and focused on simple tasks, such as word processing or basic spreadsheet calculations. Sophisticated applications like advanced graphics editing, video processing, or 3D modeling were well beyond the capabilities of these early systems.

Against this burgeoning backdrop of the microcomputer revolution, a man by the name of Gary Kildall developed the Control Program for Microcomputers (CP/M) system. CP/M was a pre-MS-DOS operating system. Kildall, while working at Intel, developed a high-level language named PL/M (Programming Language for Microcomputers). He needed a way to test and debug programs written in PL/M on the newly developed Intel 8080 microprocessor. This led to the creation of CP/M. Recognizing the imminent proliferation of different hardware systems, Kildall, with his experience at Intel and knowledge of microprocessors, saw a need for a standardized software platform. Many microcomputers were operating on incompatible systems, and Kildall's solution was CP/M, an operating system designed to work across diverse hardware setups.

At the heart of CP/M's design was its modularity, characterized predominantly by the BIOS (Basic Input/Output System). The BIOS acted as an intermediary layer that handled the direct communication with the hardware, such as disk drives, keyboards, and displays. By isolating system-specific hardware instructions within the BIOS, CP/M maintained a core set of generic commands. This modular architecture meant that to make CP/M compatible with a new machine, only the BIOS needed to be tailored to the specific hardware, preserving the integrity of the rest of the operating system. This modularity enabled rapid porting of CP/M across a wide array of early microcomputers without rewriting the entire OS.

Another notable technical feature of CP/M was its file system. CP/M used a disk-oriented file system, which was one of the first to use a hierarchical directory structure. This structure allowed users to organize and manage files efficiently on floppy disks. The operating system employed a simple 8.3 filename convention (up to 8 characters for the filename and 3 for the extension) which, though limited by today's standards, was effective for the time. Files were accessed through File Control Blocks (FCBs), a data structure that provided a consistent interface for file operations, further simplifying application development.

CP/M's command-line interface (CLI) was a hallmark feature, providing users with a means to interact with the system and run applications. The CLI, while rudimentary by today's standards, allowed users to navigate the directory structure, execute programs, and manage files. Coupled with a set of basic utilities bundled with the OS, this interface provided an accessible environment for both end-users and developers. For developers, CP/M provided a BDOS (Basic Disk Operating System) interface, allowing applications to be written without deep knowledge of the underlying hardware, thus fostering a rich ecosystem of software tailored for the CP/M platform.

However, CP/M's technical success didn't guarantee lasting market dominance. As it gained traction, Kildall's company, Digital Research, became a major player in the microcomputer software industry. But a missed business opportunity with IBM led to IBM choosing Microsoft's MS-DOS, which bore similarities to CP/M, for its Personal Computer. The story of early personal computing is interesting, and is depicted nicely in Pirates of Silicon Valley (available on DVD). The IBM + MS-DOS choice tilted the scales in the software market, positioning MS-DOS and its successors as major players, while CP/M gradually faded. Nonetheless, CP/M's role in early personal computing is significant, representing a key step towards standardized operating systems.

I wasn't around for the early days of personal computing when CP/M was a big deal. By the time I started exploring computers in the mid-1980s, the Apple IIe was the choice in education where I was first really exposed to personal computers. The Apple IIe was straightforward and easy to use. When I turned it on, I was met with the AppleSoft BASIC interface. In 1992, as I would soon be a teenager, my family purchased its first personal computer from Gateway 2000. Even though I missed the CP/M phase, the Apple IIe provided a solid introduction to the world of computing for me with the Gateway 2000 being foundational in my ever growing interest in computers.

Let's get back to CP/M.

The primary architecture CP/M was designed for was the Intel 8080 and its compatible successor, the Zilog Z80. However, CP/M was adapted to run on several different architectures over time. Here's a brief overview of some architectures and their technical specs:

Intel 8080:
- 8-bit microprocessor
- Clock speeds typically up to 2 MHz
- 4.5k transistors
- 16-bit address bus, enabling it to access 65,536 memory locations
Zilog Z80:
- 8-bit microprocessor
- Clock speeds of 2.5 MHz to 10 MHz
- Around 8.5k transistors
- 16-bit address bus, 8-bit data bus
- It had enhanced instruction set compared to 8080 and was binary compatible with it.
Intel 8085:
- 8-bit microprocessor
- Clock speeds of up to 5 MHz
- An improved and more power-efficient version of the 8080
- Included new instructions over the 8080
Zilog Z8000 and Intel 8086/8088:
- These were 16-bit processors.
- CP/M-86 was developed for these processors as an extension to the original 8-bit CP/M.
- The 8086 had a 16-bit data bus, and the 8088, used in the original IBM PC, had an 8-bit data bus.
Motorola 68000:
- While not a primary platform for CP/M, there were ports and adaptations made for the 16/32-bit Motorola 68000 series.
- Used in early Apple Macintosh computers, Atari ST, Commodore Amiga, and others.
Interdata 7/32:
- This is a lesser-known 32-bit minicomputer for which CP/M was adapted.

We have already looked at the Z80 (in the context of the TI-84+ graphing calculator) as well as the Motorola 68000 (in the context of the TI-89 graphing calculator). Instead of focusing on a specific architecture, the RC2014, to run CP/M on bare metal, we will be looking at running a CP/M emulator on Adafruit's Grand Central M4 Express. I would love to get of the RC2014 kits and run CP/M on bare metal, but for now, we won't be doing that.

We're concentrating on setting up RunCPM on the Grand Central, so we'll only touch on the Z80 briefly. For additional information on the Z80, visit z80.info. The person behind z80.info also write an in-depth look at Z80 hardware and assembly language in Hackspace Magazine issues 7 & 8. If you're interested in a comprehensive study of the Z80, consider the books: Build your own Z80 computer - design guidelines and application notes by Steve Ciarcia (you can also grab the PDF here or here) and Programming the Z80 by Rodnay Zaks (you can also grab PDFs here, or here or here or here). Both books have out of print for decades and are rather expensive on Amazon.

CP/M

CP/M incorporated wildcard characters in its file naming conventions, a legacy we continue to see in modern systems. Specifically, '?' was used to match any single character, and '*' could match part of or an entire file name or file type.

In terms of commands, many accepted these wildcards, and such a command was labeled as using an ambiguous file reference, abbreviated as "afn". In contrast, commands that required file references to be specific, without the use of wildcards, were termed as using an unambiguous file reference or "ufn". These shorthand terms, "afn" and "ufn", are frequently found in official CP/M documentation and will be adopted for our discussion here.

Builtin Commands:

DIR afn (or simply DIR): Employed to display the names of files that match the specified wildcard pattern.
ERA afn: This command is used to delete one or multiple files.
REN ufn1=ufn2: As the name suggests, this command allows users to rename a specific file.
TYPE ufn: Useful for viewing the contents of an ASCII file..

Standard Programs:

CP/M was equipped with a suite of standard programs, often referred to as Transient Commands. These weren't embedded within the core of CP/M but were accessible to the user as needed. They'd be loaded, run, and then purged from the memory. Several of these commands were fundamental for operations within the CP/M environment. A concise overview of some notable Transient Commands is provided below, though a more exhaustive exploration can be found in the CP/M manual.

STAT: This program offers insights into the current disk's status, specifics about individual files, and device assignment details.
ASM: A tool for program assembly. It takes a source code input and assembles it to produce an executable.
LOAD: Designed for Intel HEX formatted code files, this command loads the code and subsequently converts it into an executable format.
DDT: This is CP/M's built-in debugger, essential for diagnosing and resolving program errors.
ED: CP/M's text editor, enabling users to create and modify text files within the operating system.
SUBMIT: A utility to accept a file containing a list of commands, essentially enabling batch processing.
DUMP: A handy tool for those looking to view a file's contents represented in hexadecimal format.

For those eager to dive deeper into the vast ocean of CP/M's capabilities and legacy, the Tim Olmstead Memorial Digital Research CP/M Library is an invaluable resource, housing a trove of information and code associated with CP/M.

RunCPM is essentially a Z80 emulator that comes packaged with different CP/M versions tailored to function on the emulated Z80. It's a comprehensive toolkit for those interested in delving into Z80 assembly language programming, with the added perk of accessing the Grand Central's IO capabilities. As a bonus, Microsoft Basic is incorporated within the package, and for enthusiasts looking to explore further, various other languages can be sourced online. One such language is Modula-2, which holds significance as Niklaus Wirth's successor to the famed Pascal language).

When it comes to building RunCPM, the approach isn't one-size-fits-all. The build method you opt for is contingent on the target platform. In our case, we're aiming for compatibility with the Grand Central, so the Arduino method is the route we'll take. Begin by launching the RunCPM.ino file within the Arduino IDE (or Visual Code). However, prior to this step, ensure that the IDE is configured to build for the Grand Central. The following are stripped down instructions for RunCPM from its Github repo.

RunCPM - Z80 CP/M emulator

RunCPM is an application which can execute vintage CP/M 8 bits programs on many modern platforms, like Windows, Mac OS X, Linux, FreeBSD, Arduino DUE and variants, like Adafruit Grand Central Station, and the Teensy or ESP32. It can be built both on 32 and 64 bits host environments and should be easily portable to other platforms.

RunCPM is fully written in C and in a modular way, so porting to other platforms should be only a matter of writing an abstraction layer file for it. No modification to the main code modules should be necessary.

If you miss using powerful programs like Wordstar, dBaseII, mBasic and others, then RunCPM is for you. It is very stable and fun to use.

RunCPM emulates CP/M from Digital Research as close as possible, the only difference being that it uses regular folders on the host instead of disk images.

Grand Central M4 (GSM4)

The ATSAMD51 is large with an Arduino Mega shape and pinout.
The front half has the same shape and pinout as Adafruit's Metro's, so it is compatible with all Adafruit shields.
It's got analog pins, and SPI/UART/I2C hardware support in the same spot as the Metro 328 and M0.
It's powered with an ATSAMD51P20, which includes:
- Cortex M4 core running at 120 MHz
- Floating point support with Cortex M4 DSP instructions
- 1MB flash, 256 KB RAM
- 32-bit, 3.3V logic and power
- 70 GPIO pins in total
- Dual 1 MSPS DAC (A0 and A1)
- Dual 1 MSPS ADC (15 analog pins)
- 8 x hardware SERCOM (can be I2C, SPI or UART)
- 22 x PWM outputs
- Stereo I2S input/output with MCK pin
- 12-bit Parallel capture controller (for camera/video in)
- Built-in crypto engines with AES (256 bit), true RNG, Pubkey controller
Power the Grand Central with 6-12V polarity protected DC or the micro USB connector to any 5V USB source.
The 2.1mm DC jack has an on/off switch next to it so you can turn off your setup easily.
The board will automagically switch between USB and DC.
Grand Central has 62 GPIO pins, 16 of which are analog in, and two of which are true analog out.
There's a hardware SPI port, hardware I2C port, and hardware UART.
5 more SERCOMs are available for extra I2C/SPI/UARTs.
Logic level is 3.3V.

The GC M4 comes with native USB support, eliminating the need for a separate hardware USB to Serial converter. When configured to emulate a serial device, this USB interface enables any computer to send and receive data to the GC M4. Moreover, this interface can be used to launch and update code via the bootloader. The board’s USB support extends to functioning as a Human Interface Device (HID), allowing it to act like a keyboard or mouse, which can be a significant feature for various interactive projects.

On the hardware front, the GC M4 features four indicator LEDs and one NeoPixel located on the front edge of the PCB, designed for easy debugging and status indication. The set includes one green power LED, two RX/TX LEDs that indicate data transmission over USB, and a red LED connected to a user-controllable pin. Adjacent to the reset button, there is an RGB NeoPixel. This NeoPixel can be programmed to serve any purpose, such as displaying a status color code, which adds a visually informative aspect to your projects.

Furthermore, the GC M4 includes an 8 MB QSPI (Quad SPI) Flash storage chip on board. This storage can be likened to a miniature hard drive embedded within the microcontroller. In a CircuitPython environment, this 8 MB flash memory serves as the storage space for all your scripts, libraries, and files, effectively acting as the "disk" where your Python code lives. When the GC M4 is used in an Arduino context, this storage allows for read/write operations, much like a small data logger or an SD card. A dedicated helper program is provided to facilitate accessing these files over USB, making it easy to transfer data between the GC M4 and a computer. This built-in storage is a significant feature, as it simplifies the process of logging data and managing code, and it opens up new possibilities for more advanced and storage-intensive projects.

The GC M4 board boasts a built-in Micro SD Card slot, providing a convenient and flexible option for removable storage of any size. This storage is connected to an SPI (Serial Peripheral Interface) SERCOM, providing high-speed data communication. Notably, SDIO (Secure Digital Input Output), a faster interface that is commonly used for SD cards, is not supported on this board. Nevertheless, the availability of a dedicated Micro SD Card slot is a standout feature, as it allows users to easily expand the storage capacity of their projects without any complex setup. This integrated Micro SD Card slot is a substantial advantage when comparing the GC M4 to other boards, such as the Arduino Due. Unlike the GC M4, the Arduino Due does not come with built-in SD card support. For projects that require additional storage or data logging capabilities on the Due, users must purchase and connect an external Micro SD adapter or a shield, which can add to the overall cost and complexity of the setup. The built-in SD Card slot on the GC M4 eliminates the need for such additional components, simplifying project designs and reducing both the cost and the physical footprint of the final build.

This convenient feature underscores the GC M4's design philosophy of providing an integrated, user-friendly experience. By including an SD Card slot directly on the board, the GC M4 encourages broader experimentation with data-intensive applications, such as data logging, file storage, and multimedia processing, which can be essential for a wide range of creative and practical projects.

Comes pre-loaded with the UF2 bootloader, which looks like a USB storage key. Simply drag firmware on to program, no special tools or drivers needed! It can be used to load up CircuitPython or Arduino IDE (it is bossa v1.8 compatible)

With all of these features, it probably seems like cheating for getting CP/M working. And we will be barely exercising these features. If only Gary Kildall could see how computers and technology have evolved.

Grand Central Specific Adaptations for RunCMP

Arduino digital and analog read/write support was added by Krzysztof Kliś via extra non-standard BDOS calls (see the bottom of cpm.h file for details).

LED blink codes: GSM4 user LED will blink fast when RunCPM is waiting for a serial connection and will send two repeating short blinks when RunCPM has exited (CPU halted). Other than that the user LED will indicate disk activity.

RunCPM needs A LOT of RAM and Flash memory by Arduino standards, so you will need to run on Arduinos like the DUE (not the Duemilanove) and similar controllers, like Adafruit's Grand Central. It is theoretically possible to run it on an Arduino which has enough Flash (at least 96K) by adding external RAM to it via some shield, but this is untested, probably slow and would require an entirely different port of RunCPM code. That could be for another day, but if you want to get CP/M running quickly, grab a Grand Central or Due.

You will also need a micro sd ("tf") card.

When using Arduino boards, the serial speed as well as other parameters, may be set by editing the RunCPM.ino sketch. The default serial speed is 9600 for compatibility with vintage terminals.

You will need to clone the RunCPM repository:

git clone https://github.com/MockbaTheBorg/RunCPM.git -v

In RunCPM.ino, you will want to specify the Grand Center header file be included:

#include "hardware/arduino/gc.h"

instead of

#include "hardware/arduino/due_sd_tf.h"

Getting Started

Preparing the RunCPM folder :

To set up the RunCPM environment, create a folder that contains both the RunCPM executable and the CCP (Console Command Processor) binaries for the system. Two types of CCP binaries are provided: one for 64K memory and another for 60K memory. On your micro SD card, you will want to create a directory called A which will need a directory called 0 in it. Place in 0 the contents of A.zip.

The 64K version of the CCPs maximizes the amount of memory available to CP/M applications. However, its memory addressing ranges are not reflective of what a real CP/M computer would have, making it less authentic in terms of emulating a physical CP/M machine.

On the other hand, the 60K version of the CCPs aims to provide a more realistic memory addressing space. It maintains the CCP entry point at the same loading address that it would occupy on a physical CP/M computer, adding to the authenticity of the emulation.

While the 64K and 60K versions are standard, it is possible to use other memory sizes, but this would necessitate rebuilding the CCP binaries. The source code needed to do this is available on disk A.ZIP. The CCP binaries are named to correspond with the amount of memory they are designed to operate with. For example, DRI's CCP designed for a 60K memory environment would be named CCP-DR.60K. RunCPM searches for the appropriate file based on the amount of memory selected when it is built.

It is important to note that starting with version 3.4 of RunCPM, regardless of the amount of memory allocated to the CP/M system, RunCPM will allocate 64K of RAM on the host machine. This ensures that the BIOS always starts at the same position in memory. This design decision facilitates the porting of an even wider range of CCP codes to RunCPM. Starting from version 3.4, it is essential to use new copies of the master disk A.ZIP, as well as the ZCPR2 CCP and ZCPR3 CCP (all of which are provided in the distribution).

Building dependencies

All boards now use the SdFat 2.x library, from here: https://github.com/greiman/SdFat/ All Arduino libraries can be found here: https://www.arduinolibraries.info/

SdFat library change

If you get a 'File' has no member named 'dirEntry' error, then a modification is needed on the SdFat Library SdFatConfig.h file (line 78 as of version 2.0.2) changing:

#define SDFAT_FILE_TYPE 3

#define SDFAT_FILE_TYPE 1

As file type 1 is required for most of the RunCPM ports.

To find your libraries folder, open the Preferences in Arduino IDE and look at the Sketchbook location field.

Changes to Adapt to the Grand Central

Given that the official repository has already integrated the modifications to support the Grand Central, the following changes are primarily to serve educational purposes or as guidance for those intending to adapt the setup for other M4 boards.

All of the following should already be set in RunCPM.ino, but I'll write them out so you can see what changes have been made.

abstraction_arduino.h For the Grand Central, the alteration pertains to the setting of HostOs:

On line 8, the line:

#ifdef ARDUINO_SAM_DUE

Should be transformed to:

#if defined ARDUINO_SAM_DUE || defined ADAFRUIT_GRAND_CENTRAL_M4

RunCPM.ino Aligning with the alteration in abstraction_arduino.h, we also need to integrate Grand Central support in this file. Specifically, configurations relating to the SD card, LED interfaces, and the board's designation need adjustment. Insert a branch to the board configuration #if structure at approximately line 28:

#elif defined ADAFRUIT_GRAND_CENTRAL_M4
  #define USE_SDIO 0
  SdFat SD;
  #define SDINIT SDCARD_SS_PIN
  #define LED 13
  #define LEDinv 0
  #define BOARD "ADAFRUIT GRAND CENTRAL M4"

Due to certain ambiguous factors (perhaps the unique SPI bus configuration for the SD card), initializing the SD card and file system requires a different approach. Thus, following the insertion of the previous snippet, at line 108:

#if defined ADAFRUIT_GRAND_CENTRAL_M4
  if (SD.cardBegin(SDINIT, SD_SCK_MHZ(50))) {
    if (!SD.fsBegin()) {
      _puts("\nFile System initialization failed.\n");
      return;
    }
  }
#else
  if (SD.begin(SDINIT)) {
#endif

This snippet replaces the original:

if (SD.begin(SDINIT)) {

Following these modifications, it's straightforward to get RunCPM functional. For communication, the USB connection acts as the terminal interface. However, take note that not all terminal emulators provide flawless compatibility. Since CP/M anticipates a VT100-style terminal, some features might not behave as expected.

Installing Adafruit SAMD M4 Boards

If you haven't already, you will need to add Adafruit board definitions to Arduino IDE. To do this, copy the URL below and paste into the text field in the dialog box; navigate to File --> Preferences

https://adafruit.github.io/arduino-board-index/package_adafruit_index.json

We will only need to add one URL to the IDE in this example, but you can add multiple URLS by separating them with commas. Copy and paste the link below into the Additional Boards Manager URLs option in the Arduino IDE preferences.

Preparing the CP/M virtual drives :

VERY IMPORTANT NOTE - Starting with RunCPM version 3.7, the use of user areas has become mandatory. The support for disk folders without user areas was dropped between versions 3.5 and 3.6. If you are running a version up to 3.5, it is advisable to consider upgrading to version 3.7 or higher. However, before making this move, it is important to update your disk folder structure to accommodate the newly required support for user areas.

RunCPM emulates the disk drives and user areas of the CP/M operating system by means of subfolders located under the RunCPM executable’s directory. To prepare a folder or SD card for running RunCPM, follow these procedures:

Create subfolders in the location where the RunCPM executable is located. Name these subfolders "A", "B", "C", and so forth, corresponding to each disk drive you intend to use. Each one of these folders represents a separate disk drive in the emulated CP/M environment. Within the "A" folder, create a subfolder named "0". This represents user area 0 of disk A:. Extract the contents of the A.ZIP package into this "0" subfolder. When you switch to another user area within CP/M, RunCPM will automatically create the respective subfolders, named "1", "2", "3", etc., as they are selected. For user areas 10 through 15, subfolders are created with names "A" through "F".

It is crucial to keep all folder and file names in uppercase to avoid potential issues with case-sensitive filesystems. CP/M originally supported only 16 disk drives, labeled A: through P:. Therefore, creating folder names representing drives beyond P: will not function in the emulation, and the same limitation applies to user areas beyond 15 (F).

Available CCPs :

RunCPM can run on its internal CCP or using binary CCPs from real CP/M computers. A few CCPs are provided:

CCP-DR - Is the original CCP from Digital Research.
CCP-CCPZ - Is the Z80 CCP from RLC and others.
CCP-ZCP2 - Is the original ZCPR2 CCP modification.
CCP-ZCP3 - Is the original ZCPR3 CCP modification.
CCP-Z80 - Is the Z80CCP CCP modification, also from RLC and others.

The A.ZIP package includes the source code for the Console Command Processors (CCPs), allowing for native rebuilding if necessary. To facilitate this, SUBMIT (.SUB) files are provided, which are also useful for rebuilding some of the RunCPM utilities.

While the package comes with a set of CCPs, users can adapt additional CCPs to work with RunCPM. If successful in this adaptation, users are encouraged to share their work so it can be potentially added to the package for others to use. By default, RunCPM utilizes an internal CCP. However, if you prefer to use a different CCP, two specific steps must be taken, which are outlined below:

1 - Change the selected CCP in globals.h (in the RunCPM folder). Find the lines that show:

/ Definition of which CCP to use (must define only one) /

#define CCP_INTERNAL // If this is defined, an internal CCP will emulated

//#define CCP_DR

//#define CCP_CCPZ

//#define CCP_ZCPR2

//#define CCP_ZCPR3

//#define CCP_Z80

Comment out the CCP_INTERNAL line by inserting two slashes at the line's beginning. Then remove the two slashes at the start of the line containing the name of the CCP you intend to use. Save the file.

2 - Copy a matching CCP from the CCP folder to the folder that holds your A folder. Each CCP selection will have two external CCP's, one for 60K and another for 64K. If you have already built the executable, you will need to do it again.

Anytime you wish to change the CCP, you must repeat these steps and rebuild.

IMPORTANT NOTE - CCP-Z80 expects the $$$.SUB to be created on the currently logged drive/user, so when using it, use SUBMITD.COM instead of SUBMIT.COM when starting SUBMIT jobs.

Contents of the "master" disk (A.ZIP) :

The "master" disk, labeled as A.ZIP, serves as the foundational environment for CP/M within RunCPM. It includes the source code for the Console Command Processors (CCPs) and features the EXIT program, which terminates RunCPM when executed.

The master disk also houses the FORMAT program, designed to create a new drive folder, simulating the process of formatting a disk. Importantly, the FORMAT program doesn't affect existing drive folders, ensuring its safe use. Despite its ability to create these drive folders, it doesn't have the capability to remove them from within RunCPM. To remove a drive folder created by the FORMAT program, manual deletion is necessary, which involves accessing the RunCPM folder or SD Card via a host machine.

In addition to these utilities, the master disk contains Z80ASM, a potent Z80 assembler that directly produces .COM files, ready for execution. To further enhance the RunCPM experience, the master disk also includes various CP/M applications not originally part of Digital Research Inc.'s (DRI's) official distribution. A detailed list of these additional applications can be found in the 1STREAD.ME file included on the master disk.

Printing

Printing to the PUN: and LST: devices is allowed and will generate files called "PUN.TXT" and "LST.TXT" under user area 0 of disk A:. These files can then be tranferred over to a host computer via XMODEM for real physical printing. These files are created when the first printing occurs, and will be kept open throughout RunCPM usage. They can be erased inside CP/M to trigger the start of a new printing. As of now RunCPM does not support printing to physical devices.

Limitations / Misbehaviors

The objective of RunCPM is not to emulate a Z80 CP/M computer perfectly, but to allow CP/M to be emulated as close as possible while keeping its files on the native (host) filesystem.

This will obviously prevent the accurate physical emulation of disk drives, so applications like MOVCPM and STAT will not be useful.

The master disk, A.ZIP, continues to provide the necessary components to maintain compatibility with Digital Research Inc.'s official CP/M distribution. Currently, only CP/M 2.2 is fully supported, though work is ongoing to bring support for CP/M 3.0.

IN/OUT instructions are designated to facilitate communication between the soft CPU BIOS and BDOS and the equivalent functions within RunCPM, thus these instructions are reserved for this purpose and cannot be used for other tasks. The video monitor in this emulation environment is assumed to be an ANSI/VT100 emulation, which is the standard for DOS/Windows/Linux distributions. This means CP/M applications hard-coded for different terminals may encounter issues with screen rendering.

When using a serial terminal emulator with RunCPM, it is important to configure the emulator to send either a Carriage Return (CR) or a Line Feed (LF) when the Enter key is pressed, but not both (CR+LF). Sending both can disrupt the DIR listing on Digital Research’s Command Control Processor (CCP), consistent with standard CP/M 2.2 behavior.

RunCPM does not support setting files to read-only or applying other CP/M-specific file attributes. All files within the RunCPM environment will be both visible and read/write at all times, necessitating careful file handling. RunCPM does support setting "disks" to read-only, but this read-only status applies only within the context of RunCPM. It does not alter the read/write attributes of the disk’s containing folder on the host system.

Furthermore, some applications, such as Hi-Tech C, may attempt to access user areas numbered higher than 15 to check for a specific CP/M flavor other than 2.2. This action results in the creation of user areas labeled with letters beyond 'F', which is expected behavior and will not be altered in RunCPM.

CP/M Software

CP/M software library here! or here

Having inserted the microSD card and connected the Grand Central appropriately, ensuring both board and port settings are accurate, proceed to build and install onto the Grand Central.

RunCPM provides access to Arduino I/O capabilities through CP/M's BDOS (Basic Disk Operating System) interface. By loading the C register with a function number and a call to address 5, additional functionality that has been added to the system can be accessed.

For these functions, the number of the pin being used is placed in the D register and the value to write (when appropriate) is placed in E. For read functions, the result is returned as noted.

PinMode

LD C, 220
LD D, pin_number
LD E, mode ;(0 = INPUT, 1 = OUTPUT, 2 = INPUT_PULLUP)
CALL 5 

DigitalRead 

LD C, 221
LD D, pin_number
CALL 5 Returns result in A (0 = LOW, 1 = HIGH). 

DigitalWrite 

LD C, 222
LD D, pin_number
LD E, value ;(0 = LOW, 1 = HIGH)
CALL 5 

AnalogRead 

LD C, 223
LD D, pin_number
CALL 5 

Returns result in HL (0 - 1023). 

AnalogWrite (i.e. PWM)

LD C, 224
LD D, pin_number
LD E, value (0-255)
CALL 5
Turning on a LED

Using the provided PinMode and DigitalWrite calls, writing code to control an LED, such as turning it on when connected to pin D8, becomes a straightforward task. To accomplish this, one can use the ED editor to create a file named LED.ASM with the necessary code. This file editing can be done directly on your workstation and saved to the SD card, which is a convenient approach given that ED, the editor, hails from a different era of computing and might feel a bit foreign to modern users accustomed to contemporary text editors.

; Turn on a LED wired to pin 8
org 100h    ;start address
mvi c, 220  ;pinmode
mvi d, 8    ;digital pin number
mvi e, 1    ;value (0 = low, 1 = high)
push d      ;save arguments
call 5      ;call BDOS
pop d       ;restore arguments
mvi c, 222  ;digital write
call 5      ;call BDOS
ret         ;exit to CP/M

Then use the ASM command to assemble it:

A>asm led
CP/M ASSEMBLER - VER 2.0
0111
000H USE FACTOR
END OF ASSEMBLY

RunCPM Version 3.7 (CP/M 2.2 60K)

This produces several files. LED.PRN is a text file containing your assembly language program along with the machine code it assembles to. Each line has 3 columns: address, machine code, and assembly language.

A>type led.prn

0100          org 100h
0100 0EDC     mvi c,220
0102 1608     mvi d,8
0104 1E01     mvi e, 1
0106 D5       push d
0107 CD0500   call 5
010A D1       pop d
010B 0EDE     mvi c, 222
010D CD0500   call 5
0110 C9       ret

There is also now a LED.HEX file. We can use the LOAD command/program to convert it into LED.COM which can be executed.

A> load led

FIRST ADDRESS 0100
LAST ADDRESS  0110
BYTES READ    0011
RECORDS WRITTEN 01

Now it can executed:

A>led

which will turn on the LED connected to pin D8.

So now we can read and write digital and analog I/O from Z80 assembly language code that's running on a Z80 emulated on the Grand Central. That seems pretty round-about.

While that's true, the point is to be able to play around with Z80 assembly language (and CP/M in this case) without having to find or build an actual Z80 system (although that can be its own kind of fun).

Closing Thoughts

One of the most lasting legacies of CP/M is its file system and command-line interface, with its 8-character filename followed by a 3-character file type (e.g., filename.txt), which became a standard that was carried into MS-DOS and later Windows. Its command-line interface, with commands like DIR to list files and REN to rename files, has echoes in the MS-DOS command prompt and persists in modern versions of Windows as the Command Prompt and PowerShell. CP/M was notable for being one of the first operating systems that was largely machine-independent, due to its separation between the operating system and the BIOS (Basic Input/Output System). This made it relatively easy to port CP/M to different computer systems and paved the way for the concept of a software ecosystem that is not tied to a specific set of hardware, a key principle in modern operating system design.

CP/M played a crucial role in the early days of personal computing; before the dominance of MS-DOS and Windows, CP/M was the de facto standard operating system for early microcomputers, fostering the personal computing revolution by making computers more approachable and useful for everyday tasks. When IBM was developing its first personal computer, CP/M was initially considered the operating system of choice, and although IBM ultimately went with MS-DOS (largely due to cost and timing), MS-DOS itself was heavily influenced by CP/M, with many command-line commands being similar and the overall architecture of MS-DOS bearing a strong resemblance to CP/M. This influence extended as MS-DOS evolved into Windows, making CP/M an indirect ancestor of one of the world’s most widely used operating systems. Even after its decline as a primary OS for general-purpose computers, CP/M found a second life in embedded systems and other specialized computing applications due to its lightweight, efficient design, setting the stage for the importance of compact, efficient operating systems in embedded and specialized computing devices, a category that has grown with the proliferation of IoT (Internet of Things) devices. In summary, CP/M stands as an iconic example of how early innovations in computing continue to have ripple effects that extend far into the future.

TinyComputers.io (Posts about cp/m)

An LLM Clean Room Z80 Emulator: Building from Specifications, Not Source Code

Why an LLM Clean Room?

The Process

The Architecture

The CPU State

Instruction Decoding: The Bit Field Approach

The Prefix System

The ALU

Block Operations

T-State Timing

The Interrupt System

DAA: The Most Misunderstood Instruction

Testing: 117 Ways to Be Wrong

The System Emulator

ACIA Serial Emulation

Serial Port Auto-Detection

CP/M Mode

System Auto-Detection

Booting BASIC

What I Learned About LLM Clean Room Development

The Code

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

The Story So Far

CP/M Boots

The "Bad Load" Bug

Finding the Root Cause

The Fix

Zork Starts, Barely

The Performance Crisis

Bottleneck 1: A Two-Millisecond Nap on Every Tick

Bottleneck 2: Flipping 8 Pins on Every Single Tick

Bottleneck 3: Arduino HAL in the Hot Loop

Bottleneck 4: USB Serial Polling Every Tick

Bottleneck 5: I-Cache Thrashing from Forced Inlining

The Result

Network Reconnection

Playing Zork

How It All Fits Together

The Full Architecture

Pin Mapping Reference

What's Next

Source Code

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

The Hardware Stack

CP/M Memory Map

WiFi Instead of SD

The Level Converter Problem

Signal-by-Signal Breakdown

RD_N: Permanently Stuck

IORQ_N: The Big One

Data Bus: Invisible During I/O OUT

WR_N: Only Works Sometimes

Shadow Register Tracking

M1 Detection

The opcodeSkip Counter

Register Tracking

IO State Machine

The Sector Server

Protocol

Implementation

Running It

Proof of Concept

Boot Sequence

What's Next

George Morrow: Pioneer of Personal Computing

From Detroit to Stanford: An Unconventional Path

The Homebrew Computer Club and the Birth of an Industry

From Morrow's Microstuff to Thinker Toys

Bringing Mainframe Concepts to Microcomputers

The S-100 Bus and IEEE-696: Building Industry Standards

The Decision 1 and Micro Decision: Computing for Everyone

Bankruptcy and Beyond

Computer Chronicles and a Second Act

Legacy

Further Reading

CP/M 2.2 on Physical Hardware: RetroShield Z80 with 1MB DRAM and SD Card Storage

The Hardware Stack

The RetroShield Z80

KDRAM2560: 1MB of Dynamic RAM