TinyComputers.io (Posts about retrocomputing)

Designing a Dual Z80 RetroShield: Ground Planes, Ghost Shorts, and the Fix (Part 2)

A.C. Jokela — Mon, 06 Apr 2026 22:00:00 GMT

The assembled dual Z80 RetroShield on the bench. Two Z80 CPUs socketed, jumper wires from J2 to the Arduino Mega's free pins, ready for testing.

In Part 1, I designed a dual-Z80 RetroShield PCB entirely from the command line: two Z80 CPUs sharing an address and data bus, with independent control signals on a supplementary header. The Gerber files went to PCBWay. The boards arrived. I soldered everything up, plugged the shield into an Arduino Mega, wired jumpers from the J2 control header to the Mega's free pins, loaded a test sketch, and...

Nothing. Both Z80s appeared to be alive (the diagnostic showed bus activity after reset), but they couldn't execute a single instruction. The data bus was completely unresponsive. The SMP kernel I'd written—a 52-byte symmetric multiprocessing demo where both CPUs boot the same code, pull tasks from a shared scheduler, and sum arrays in parallel—hit its cycle limit and returned zeroes.

What followed was a multi-day debugging session that taught me more about PCB design than the entire design phase did. The root cause turned out to be a subtle interaction between pcb-rnd's ground fill polygon and its Gerber exporter. This is the story of finding it.

The Hardware

The boards came back from PCBWay with the usual four week turn around time. Clean fabrication, good silkscreen, no obvious defects on visual inspection. I soldered DIP-40 sockets for both Z80s, the 2×18 J1 bus header, the 2×6 J2 control header, and the bus activity LED. The Z80 chips dropped into their sockets with satisfying precision.

The J2 header needed jumper wires to the Arduino Mega's free pins (D0–D21). I chose a deliberate mapping based on the pin functions: D9 for CPU2's clock (Timer1 OC1A, which can generate a hardware PWM signal for a stable 4 MHz clock), D4 for RESET, D5–D6 for INT/NMI, D7–D8 for MREQ/IORQ, D10–D11 for RD/WR, and D12–D13 for BUSRQ/BUSAK. Twelve jumper wires total, plus +5V and GND.

The plan was to run a five-test validation suite: each Z80 solo (write a signature byte to a known address), shared RAM persistence (both CPUs write to different locations, verify both persist), a relay test (CPU1 computes a value, CPU2 picks it up and continues), and a loop counter (DJNZ loop to verify branch instructions work). After that, the SMP kernel.

None of it worked.

Routing traces with Freerouting.

First Contact: The Diagnostic Sketch

I backed off to a simpler diagnostic sketch to test each connection individually. It checked four things: idle state of control pins, bus activity after releasing reset, address bus bit toggling, and the BUSRQ/BUSAK handshake on CPU2.

The results were a mix of encouraging and confusing:

=== Test 1: Control Pin Idle State ===
  [FAIL] U1 MREQ (D41) idle HIGH
  [FAIL] U1 IORQ (D39) idle HIGH
  [FAIL] U1 RD   (D53) idle HIGH
  [FAIL] U1 WR   (D40) idle HIGH

=== U1: Bus Activity ===
  [PASS] MREQ went LOW (Z80 is alive)
  [PASS] RD went LOW (Z80 fetching)
  [PASS] Address bus active — first fetch address = 0x0000

Both Z80s were "alive" in the sense that they responded to clock pulses and attempted to fetch from address 0x0000 after reset. But every control signal (MREQ, IORQ, RD, WR) read LOW regardless of what the Z80 was doing. They should have been toggling between HIGH and LOW during bus cycles. LOW all the time meant either the Z80 wasn't actually driving these pins, or something else was pulling them down.

I filed this under "weird but not fatal" and pushed ahead to the SMP test. That's when things got serious.

The Bus Trace That Went Nowhere

The SMP kernel loaded into emulated memory at address 0x0000. After releasing reset, the Z80 should have fetched its first instruction (0xDB, the opcode for IN A, (n)), executed it, and proceeded through the scheduler loop. Instead, a 150-cycle bus trace showed this:

Cyc  MREQ IORQ RD WR  Addr    Data  Action
  0  LOW   LOW   L  L  0x0000  0xDB  MEM RD
  1  LOW   LOW   L  L  0x0000  0xDB  MEM RD
  2  LOW   LOW   L  L  0x0000  0xDB  MEM RD
  ...
149  LOW   LOW   L  L  0x0000  0xDB  MEM RD

Every single cycle: same address, same data, same control signals. The Z80 was stuck at its reset vector, endlessly attempting to fetch the first byte and never advancing. MREQ and IORQ were LOW simultaneously on every cycle, which should never happen during normal Z80 operation—they're mutually exclusive signals.

The Z80 was putting 0x0000 on the address bus (correct for a reset vector fetch), and I was driving 0xDB on the data bus (the correct opcode). But the Z80 wasn't reading it. Or rather, it was reading something else.

The Data Bus Loopback Test

I added a simple test: with the Z80 held in reset (outputs tri-stated), drive patterns on the data bus and read them back. If the Arduino writes 0xFF to PORTL and reads back 0xFF from PINL, the data bus is clean. If it reads back something else, there's a short or broken trace.

--- Data Bus Drive Test ---
  bit0(D49)  wrote 0x01 read 0x01 OK
  bit1(D48)  wrote 0x02 read 0x02 OK
  bit2(D47)  wrote 0x04 read 0x04 OK
  bit3(D46)  wrote 0x08 read 0x08 OK
  bit4(D45)  wrote 0x10 read 0x10 OK
  bit5(D44)  wrote 0x20 read 0x00 FAIL
  bit6(D43)  wrote 0x40 read 0x00 FAIL
  bit7(D42)  wrote 0x80 read 0x80 OK

Bits 5 and 6 were stuck LOW. The Arduino's GPIO pins couldn't drive them HIGH—something on the board was pulling those lines to ground with enough strength to overpower the Mega's output drivers.

This explained why the Z80 couldn't execute. When I drove 0xDB (IN A, (n)) on the data bus, the Z80 actually saw 0x9B (bits 5 and 6 forced low), which decodes as SBC A, E—a completely different instruction. The Z80 was faithfully executing garbage.

Isolating the Short

Systematic isolation. First question: is it the Arduino or the board?

I pulled the RetroShield off the Mega and ran the same loopback test with the shield disconnected. Every bit passed perfectly. The Arduino's PORTL pins (D42–D49) could drive any pattern and read it back correctly. The problem was definitively on the board.

Second question: is it CPU1 or CPU2? The two Z80s share the address and data bus, so a fault on either side would affect both. I disconnected J2's +5V jumper to deprive CPU2 of power, leaving its outputs floating. Same result—bits 5 and 6 still stuck LOW. So CPU2 wasn't the culprit. The short was in CPU1's territory.

Third question: is it the Z80 chip or the PCB? I pulled U1 from its socket. Bits 5 and 6 still stuck. Pulled U2 as well (since it shares the bus traces even without power). Both chips out, empty sockets, and the shorts persisted.

Then I ran a comprehensive pin test with both Z80 chips removed—just the bare PCB with sockets:

--- Data Bus (PORTL) ---
  [SHORT] D0/bit0 (D49/PL0)
  [SHORT] D1/bit1 (D48/PL1)
  [SHORT] D2/bit2 (D47/PL2)
  [SHORT] D3/bit3 (D46/PL3)
  [SHORT] D4/bit4 (D45/PL4)
  [SHORT] D5/bit5 (D44/PL5)
  [SHORT] D6/bit6 (D43/PL6)
  [SHORT] D7/bit7 (D42/PL7)

--- Address Bus ---
  [SHORT] A0 through A15 — all 16 lines

--- U1 Control Pins ---
  [OK] MREQ, IORQ, RD, WR, RESET, INT, NMI, CLK — all 8 fine

Every single data line. Every single address line. All 24 shorted to ground. But all 8 control signals were clean.

This wasn't random solder bridges. The pattern was too systematic: every line that belonged to the shared bus (connected to both U1 and U2) was shorted, while every line that connected to only one Z80 was fine. Something structural was wrong with the PCB.

The Ground Fill

I went back to the PCB design files. The original RetroShield design included a copper fill polygon on the bottom layer—a ground plane covering roughly the left half of the board (x = 0.3mm to 55.6mm, y = 0.3mm to 53.1mm). This is standard practice: ground planes reduce noise, improve signal integrity, and provide a low-impedance return path for high-frequency signals.

The polygon had a clearpoly flag, which tells pcb-rnd to maintain clearance around pins that aren't connected to the fill. Each Z80 through-hole pin specified 0.762mm clearance. The fill should have maintained that gap around every signal pin, connecting only to GND pins (via thermal relief pads) and leaving all data and address pins isolated.

I also found some design-level flag errors. U1 pin 1 (A11, an address line) had a thermal(0X) flag—explicitly telling pcb-rnd to connect this signal pin to a copper fill on the top layer. Several +5V pins had connected flags. These were wrong, though in pcb-rnd's net-aware polygon system, they turned out to be harmless (a connected flag only connects a pin to a fill on the same net, so +5V pins wouldn't connect to a GND fill). I fixed them anyway.

But fixing the flags didn't solve the short. The 24 bus lines were still shorted to ground with both chips removed. The problem was deeper.

The Gerber Analysis

I dug into the actual Gerber output for the bottom copper layer. In Gerber format, ground fill clearances are typically achieved either through layer polarity commands (%LPC*% to switch to "clear" mode and punch out holes) or by drawing the fill as a region with the clearance areas built into its outline.

pcb-rnd uses the region approach. The fill polygon gets exported as a complex region (G36/G37 block) whose boundary weaves around each pin, creating clearance cutouts. Or at least, that's what it's supposed to do.

I wrote a script to analyze the region vertices near U1's pins. For pin 9 (D5, a signal pin that should have full clearance), this is what the Gerber contained:

# U1-9(D5) SIGNAL at Gerber(120000,120000)
# Region 20: 5 vertices within 2.54mm
#   (120000,116587) dist=0.87mm angle=-90°
#   (121413,128587) dist=2.21mm angle=81°

Five vertices. Two distinct positions. A proper circular clearance cutout around a through-hole pin needs 8 to 16 vertices distributed at various angles to approximate the circle. This had vertices at just two angles: -90° and 81°. The polygon boundary was making a shallow notch past the pin, not encircling it.

Even worse: the closest vertex was only 0.87mm from the pin center. The pad edge is at 0.762mm (half of the 1.524mm pad diameter). That left 0.108mm of clearance—about 4.3 mil—on the side where the boundary came closest. Manufacturing tolerance at PCBWay is typically 4-6 mil. The clearance was right at the edge, and on other sides of the pin, there was no clearance at all because the polygon boundary didn't go around.

For comparison, U1 pin 29 (GND, which should connect to the fill) had a vertex at exactly 0.00mm distance. The fill went right through it. Correct.

The Root Cause

pcb-rnd's Gerber exporter was generating incomplete clearance cutouts in the ground fill polygon around through-hole pins. Instead of tracing a complete circle around each pin (maintaining the specified 0.762mm clearance on all sides), it was generating partial notches that only cleared the pin on one or two sides. On the remaining sides, the ground fill copper made direct contact with the pin pad.

This affected every through-hole pin inside the polygon's boundary: all of U1's pins, all of J1's pins, and most of the vias. The pattern now made sense. The ground fill polygon covered x = 0.3mm to 55.6mm—the left side of the board. U1 (at x = 30.48mm) was squarely inside. U2 (at x = 66.0mm) was outside. All 24 bus lines pass through U1's footprint. All 8 control lines connect only to one Z80 and route through traces, not through-hole pads, in the fill area.

The reason the initial diagnostic showed control signals as "OK" while bus lines were "SHORT" was purely geometric: the control signal traces exited the fill area quickly and reached the Arduino pins via the top copper layer, while the bus lines had through-hole pads sitting directly in the fill.

It's worth noting that this bug is specific to the combination of pcb-rnd's polygon fill, through-hole pins, and Gerber export. SMD pads weren't affected (no SMD components were inside the fill area). The clearance math in pcb-rnd's internal representation appeared correct, but the translation to Gerber region vertices lost fidelity, producing polygon outlines that didn't fully encircle the pins.

The Fix

I removed the ground fill polygon entirely.

# Find and remove the Polygon block in Layer 2 (bottom)
# Strategy: parse through the file, skip everything
# between 'Polygon("clearpoly")' and its closing ')'

The board's GND connectivity doesn't depend on the fill. The autorouter (Freerouting) had already placed explicit copper traces connecting all GND pins. The fill was adding copper density and potentially improving signal integrity, but neither matters for a board running Z80s at 4 MHz. At these speeds, the electrical benefit of a ground plane is negligible, and the manufacturing risk (as we discovered) is real.

I also cleaned up the erroneous flags while I was in there:

Removed thermal(0X) from U1 pin 1 (A11 should not connect to any fill)
Removed connected from all +5V pins (J1-1, J1-36, U1-11, U1-24, U1-25, U2-11, U2-24, U2-25)
Removed thermal/connected from all 11 vias (signal vias should get clearance, not connection)
Left thermal flags only on GND pins: J1-18, J1-19, and U1-29

The bottom copper Gerber went from 46KB (fill + traces) to 16KB (traces only). The region block count dropped from 26 to 5. Regenerated the Excellon drill file, rebuilt the production zip with BOM and centroid, and pushed everything to the repository.

Was This Always Broken?

A natural question: is this a flaw in the original RetroShield Z80 design, or something we introduced? The ground fill polygon, the thermal(0X) flag on U1 pin 1, and all the connected flags exist in Erturk Kocalar's upstream design — identical to our initial commit. We didn't add any of them. So why does the original RetroShield work?

To find out, I ran the original, unmodified kz80.pcb through the same pcb-rnd Gerber exporter and performed the same vertex analysis on the output. The results were revealing:

Pin	Our Board (re-routed)	Original Board (original traces)
U1-9 (D5, signal)	5 vertices, closest 0.87mm from center	75 vertices, closest 1.14mm from center
U1-10 (D6, signal)	similar	169 vertices, closest 1.14mm
U1-29 (GND)	vertex at 0.00mm (correct)	vertices at 0.76mm (thermal spokes, correct)

The original board, exported through the same pcb-rnd Gerber exporter, gets proper circular clearance cutouts with 75+ vertices distributed around each signal pin at a safe 1.14mm from center (0.38mm clearance from pad edge). Our re-routed board gets 5 vertices at only 0.87mm from center (0.11mm clearance — below manufacturing tolerance).

The difference is the trace geometry. The original RetroShield's traces were routed with classic gEDA/pcb. When we added the second Z80, we stripped all traces and autorouted from scratch with Freerouting. The new trace layout changed how pcb-rnd's polygon fill algorithm tessellated the clearance boundaries. With different traces running through the fill area, the polygon's outline took different paths around the pins — and those paths didn't maintain adequate clearance.

So the design flaw (wrong flags, a ground fill with tight clearance margins) was always latent in the original design. But it only manifested as physical shorts when the trace geometry changed. The original routing happened to produce geometry that pcb-rnd's exporter handled gracefully. Our autorouted traces didn't. It's the kind of bug that lies dormant until you touch something seemingly unrelated.

This is why removing the polygon entirely was the right fix. It doesn't matter how the traces are routed if there's no fill to create clearance problems against. The GND connectivity is fully handled by explicit routed traces.

Verification

To confirm the fix, I verified the new Gerber output:

No layer polarity commands (no fill, no clearance needed)
No large region blocks (no polygon fill)
Only trace geometry and pad flashes remain on the bottom copper layer
Bottom copper file size reduced by 65% (46KB → 16KB)

The new production files have been submitted to PCBWay for a second fabrication run. The fix is structural: without the fill polygon, there's nothing to short to. Every GND connection is an explicit routed trace, visible in the Gerber, and verifiable by inspection.

The corrected Rev C board: 553 traces, 25 vias, no ground fill polygon. Clean explicit routing for all 48 nets.

What I Learned

Ground fills aren't free. They improve signal integrity on high-speed boards, but on a 4 MHz Z80, the benefit is marginal. The cost is an additional failure mode: if the clearance generation is buggy, incomplete, or at the edge of manufacturing tolerance, the fill becomes a liability. For simple retro computing boards, explicit GND traces are more predictable.

Autorouting can break things you didn't touch. The ground fill polygon wasn't something we modified. But by re-routing the traces (which we had to do after adding the second Z80), we changed the geometry that the polygon fill algorithm used to compute clearances. A latent design flaw became an active one. When you re-route a board with copper fills, you need to re-verify the fills, not just the traces.

Test the bare PCB before populating it. If I'd run a continuity test between the Z80 socket pads and GND before soldering anything, I'd have caught this immediately. Instead, I spent time debugging firmware, suspecting timing issues, and questioning my understanding of Z80 bus cycles. The problem was never software.

The Gerber is the contract. The PCB design tool's internal representation doesn't matter; only the Gerber output does. Even if pcb-rnd's polygon clearance looks correct on screen, the Gerber export is what the fab house uses. Verify the Gerber, not the design file. A Gerber viewer would have shown the incomplete clearances immediately.

Diagnostic sketches are invaluable. Writing targeted Arduino sketches that tested individual pins, drove patterns, and reported results over serial turned a "nothing works" situation into a systematic narrowing process. The data bus loopback test (drive a byte, read it back, compare) is trivially simple and would have caught this on day one.

AI-assisted debugging works the same way AI-assisted design works. I brought the domain knowledge (how Z80 bus signals work, what the control signal timing should look like, what "stuck LOW" means electrically) and the AI handled the tedious parts: writing diagnostic firmware, parsing Gerber files, analyzing polygon vertices, checking coordinate math. The same division of labor that made the design possible also made the debugging possible.

Solder bridges are a red herring when the pattern is systematic. Early on, I found and fixed a solder bridge between two adjacent pins. It didn't help. When two pins are bridged, you get two bad signals. When 24 pins are all shorted to the same rail, the cause is structural, not incidental. I should have recognized the pattern sooner and stopped looking at individual joints.

Open-source hardware needs open-source verification. The entire reason I could diagnose this was that every file in the chain—PCB source, Gerber output, Excellon drill files—was text-based, parseable, and inspectable. I wrote Python scripts to analyze the Gerber's region vertices and measure distances to pin centers. Try doing that with a proprietary board file. The text-based EDA workflow that made the design possible also made the debugging possible.

What's Next

The corrected boards are in fabrication. When they arrive, Part 3 will cover what this project was always about: bringing up the SMP kernel, watching two Z80 processors boot the same code, identify themselves, and divide work across a shared memory bus. The kernel is 52 bytes. The scheduler is in the Arduino. The demo sums an array split across both CPUs and measures the speedup.

Both Z80s are confirmed alive. They just need a board that doesn't short their bus to ground.

The complete source—PCB files, Gerber production package, diagnostic sketches, SMP kernel, and wiring guide—is on GitHub.

Why Some Chips Last 40+ Years: Z80, 68k, 6502, and the Secret to Processor Longevity

A.C. Jokela — Sun, 08 Mar 2026 16:00:00 GMT

There's a Zilog Z80 in a graphing calculator sitting in a high school classroom right now. The student using it was born around 2008. The Z80 was designed in 1976. That processor is older than the student's parents.

This isn't a quirky footnote. It's a pattern. The Z80, the Motorola 68000, the MOS Technology 6502, the Intel 8051: these processors have been in continuous production and active deployment for forty years or more. The Z80 is closing in on fifty. Meanwhile, processors that were objectively superior by nearly every technical measure (the Zilog Z8000, the National Semiconductor 32016, the Motorola 88000, the Intel i960) are footnotes in Wikipedia articles that nobody reads.

What determines whether a processor lives for decades or dies in five years? I've spent the last two years building Z80 emulators, writing compilers for the Z80, running CP/M on physical RetroShield hardware, and exploring the Motorola 68000 through TI calculators. I've read William Barden's 1978 handbook that was still being reprinted in 1985, and Steve Ciarcia's build-your-own guide that assumed you'd wire up a computer from discrete chips. The deeper I've gone into this world, the more convinced I've become that processor longevity isn't really about the processor. It's about everything around it.

The Survivors

Four processors stand out for their extraordinary longevity. Each was introduced in the mid-to-late 1970s. Each is still manufactured or cloned today.

The Zilog Z80 (1976) was designed by Federico Faggin and Masatoshi Shima, both of whom had worked on the Intel 4004 and 8080. The Z80 was explicitly designed as a better 8080, backward-compatible with the 8080's instruction set but adding indexed addressing, a second register bank, a built-in DRAM refresh counter, and a single 5V power supply (the 8080 needed three voltage rails). It became the heart of CP/M machines, arcade cabinets, and eventually TI graphing calculators. Zilog's CMOS variant, the Z84C00, was manufactured continuously until April 2024, when Littelfuse (Zilog's current owner) finally announced end-of-life after 48 years. The eZ80, a backward-compatible enhanced variant, continues in production, and third-party clones remain available. The Z80 instruction set isn't going anywhere even if the original silicon is.

The MOS Technology 6502 (1975) was designed by Chuck Peddle and Bill Mensch after they left Motorola. At \$25 when competing processors cost \$150-\$300, the 6502 was a revolution in affordability. It powered the Apple II, the Commodore 64, the Atari 2600, and the NES. Bill Mensch's Western Design Center still manufactures the W65C02S and W65C816S today, fifty years after the original design.

The Motorola 68000 (1979) was the 32-bit processor that arrived a generation early. With a linear 24-bit address space and an orthogonal instruction set that programmers genuinely enjoyed using, it became the foundation for the original Macintosh, the Amiga, the Atari ST, the Sega Genesis, and Sun's first workstations. Its descendants (the 68020, 68030, 68040, ColdFire, and now NXP's modern variants) kept the architecture alive in embedded systems, automotive controllers, and Texas Instruments calculators well into the 2020s.

The Intel 8051 (1980) is perhaps the most quietly ubiquitous processor ever made. Designed as a microcontroller (a processor with RAM, ROM, timers, and I/O ports integrated on a single chip), the 8051 found its way into everything from washing machines to automotive engine controllers to industrial PLCs. Over two dozen companies have manufactured 8051 variants. If you've used an appliance, driven a car, or walked through a building with an elevator in the last forty years, you've interacted with an 8051 derivative.

The 8051 is also a case study in Jevons Paradox applied to silicon. As more manufacturers licensed and produced the 8051, unit costs fell. As unit costs fell, engineers designed it into applications that would never have justified a microcontroller at the original price: a toaster, a thermostat, a toy. Each new application expanded the market, which attracted more manufacturers, which drove costs lower still. The cycle fed itself for decades. Technically superior alternatives existed at every point along this curve, but they couldn't compete with an architecture whose ecosystem was compounding while their price-per-unit was still on the wrong side of the volume curve.

The Fallen

For every processor that lasted decades, dozens vanished. Some of these were technically impressive, arguably more capable than the survivors.

The Zilog Z8000 (1979), designed as the Z80's successor, offered a 16-bit architecture with segmented memory addressing. It was more powerful than the Z80 in every measurable way. It lasted roughly five years in the market before fading into obscurity. The segmented memory model (the same curse that plagued Intel's 8086/286) made programming painful. And critically, it wasn't backward-compatible with the Z80. Every Z80 program, every CP/M application, every line of existing code was useless on the Z8000. Zilog was asking customers to abandon their entire software investment.

The Motorola 88000 (1988) was Motorola's clean-sheet RISC design, intended to eventually replace the 68k family. It was technically excellent: pipelined, superscalar-capable, and well-designed. Motorola couldn't sell it. Customers had millions of lines of 68k code, working products, trained engineers, and proven toolchains. The 88000 offered better performance but required abandoning everything. Motorola eventually surrendered and joined IBM and Apple to create the PowerPC, which at least had the marketing muscle of three companies behind it.

The National Semiconductor 32016 (1982) was a full 32-bit processor at a time when the PC world was still on 16-bit. It was used in the Acorn Cambridge Workstation and a few other systems. It had bugs. The early silicon had errata that made reliable system design difficult. By the time National got the bugs out, the market had moved on.

The pattern is consistent: technical superiority alone doesn't determine survival.

Five Factors That Determine Processor Longevity

After spending years in this world, I've identified five factors that separate the survivors from the fallen. They're listed roughly in order of importance, which is not the order most engineers would expect.

1. Second-Sourcing and Licensing

This is the single most important factor, and it's the one that engineers consistently underrate because it's a business decision, not a technical one.

The Z80 was second-sourced by Mostek, SGS-Thomson, Sharp, NEC, Toshiba, Samsung, and others. When Littelfuse, the current owner of Zilog, finally discontinued the standalone Z84C00 in 2024, the instruction set didn't die, because it was never dependent on a single manufacturer. This is exactly what second-sourcing was designed to protect against. It mattered enormously to design engineers in the 1980s and 1990s, because committing a product design to a single-source processor was career-threatening. If your sole supplier had a fab fire, or went out of business, or simply decided to discontinue the chip, your product was dead.

The 6502 was licensed to multiple manufacturers: Rockwell, Synertek, GTE, and later CMD and the Western Design Center. The 8051 took this to its logical extreme: Intel actively encouraged licensing, and the architecture was eventually manufactured by Atmel, Philips/NXP, Silicon Labs, Dallas/Maxim, Infineon, and dozens more. The 8051 became less a product and more a standard, an instruction set architecture that any competent semiconductor company could implement. It was, in hindsight, a preview of the model that ARM and RISC-V would later formalize: sell the design, not the chip, and let the ecosystem do the rest.

The 68000 family was produced by Motorola, Hitachi, Signetics, Mostek, and Toshiba. Later, the ColdFire and subsequent architectures maintained enough compatibility to keep the ecosystem alive under Freescale and then NXP.

The x86 architecture tells the same story at a larger scale. IBM refused to use Intel's 8088 in the original PC without a second source. That requirement forced Intel to license the design to AMD, a decision Intel spent the next four decades regretting and litigating. But the resulting duopoly is a major reason x86 survived the RISC revolution of the 1990s. When Sun, SGI, and DEC were pushing SPARC, MIPS, and Alpha, customers considering a switch to RISC had to weigh superior performance against the uncomfortable fact that each RISC architecture had exactly one supplier. x86 had two. That mattered more than clock speeds.

Contrast all of this with the Z8000, which was essentially Zilog-only. Or the 88000, which was Motorola-only. Single-source processors carry existential risk for every product that uses them. Purchasing managers know this even when engineers don't.

2. Ecosystem and Toolchain Maturity

A processor without a mature toolchain is a science project. A processor with assemblers, compilers, debuggers, reference designs, application notes, textbooks, and a community of experienced engineers is an ecosystem.

The Z80 ecosystem by the mid-1980s was staggering. There were books (Rodnay Zaks' Programming the Z80, Barden's handbook, Ciarcia's build guide, Coffron's applications manual) available at any technical bookstore. There were assemblers, C compilers, BASIC interpreters, and Forth systems. There were thousands of CP/M applications. There were magazines publishing Z80 projects monthly. There were university courses teaching Z80 assembly. Every year, this ecosystem grew, and every year, the cost of switching to a different processor increased.

The 6502 had a similar ecosystem, driven heavily by the Apple II and Commodore 64 communities. The 8051 accumulated the largest ecosystem of any microcontroller family, with Keil (now ARM), IAR, SDCC, and many other toolchains providing development environments across every host platform.

When I wrote about how we learned hardware in 1983, I was documenting a snapshot of this ecosystem at its peak. Those books, those reference designs, those shared conventions: they weren't just educational resources. They were infrastructure. And infrastructure, once built, resists replacement.

3. ISA Simplicity and Predictability

There's a counterintuitive truth about instruction set architecture: the "best" ISA often isn't the one that survives. The one that survives is the one that's simple enough to implement cheaply, predictable enough to verify thoroughly, and small enough to teach in a semester.

The Z80's instruction set is large by 8-bit standards, with 158 base instructions and variants pushing toward 700 when you count all the addressing modes. But the fundamental execution model is simple: fetch an instruction, decode it, execute it. No pipeline. No branch prediction. No speculative execution. No out-of-order dispatch. The behavior is deterministic. If you clock the Z80 at 4 MHz, you can calculate exactly how many T-states each instruction takes and predict your program's execution time down to the microsecond.

This determinism is extraordinarily valuable in embedded systems. When you're designing an engine controller or a medical device, you need to know (not estimate, know) that your interrupt handler will complete within a specific time window. Pipelined processors with branch prediction make this analysis much harder. Simple processors make it trivial.

The 6502 takes this even further. With only 56 instructions and 13 addressing modes, the entire ISA fits on a single reference card. You can hold the complete instruction set in your head. This isn't a limitation; it's a feature. Engineers who can reason about every instruction their processor executes build more reliable systems than engineers who rely on abstractions they don't fully understand.

The 8051 instruction set is similarly compact: 111 instructions, most executing in one or two machine cycles. The architecture includes bit-addressable memory, a feature that seems quirky until you're writing firmware for a device with dozens of individual control signals, at which point it becomes indispensable.

4. Power, Size, and Cost

The survivors share a common economic profile: they're cheap to manufacture, cheap to buy, and cheap to power.

A Z84C00 in CMOS draws microwatts in standby. A W65C02S runs on a coin cell battery for years. An 8051 derivative can be manufactured on mature process nodes that have been paid for decades ago, with die sizes so small that the packaging costs more than the silicon. When your processor costs \$0.50 in volume and runs on the leakage current of a lithium cell, the engineering case for replacing it with something faster but more expensive becomes very hard to make.

This is where processor longevity intersects with the economics I've written about in the Jevons Paradox series. The relevant cost isn't just the chip; it's the total cost of the design: the processor, the toolchain, the engineering time, the qualification testing, the regulatory certification, and the opportunity cost of a redesign. A \$0.50 Z80 clone in a proven design with ten years of field data is almost impossible to displace, even if a \$0.30 ARM Cortex-M0 is technically superior, because the redesign and requalification costs dwarf the per-unit savings.

5. Inertia and Institutional Knowledge

The final factor is the hardest to quantify and the most powerful: institutional inertia.

Somewhere in Germany, there's a factory running a production line controlled by Z80-based PLCs installed in 1988. The line produces automotive components. It runs 24/7. It works. The engineer who designed the control system retired fifteen years ago. The firmware was written in Z80 assembly and documented in a binder that lives in a filing cabinet near the line.

Replacing this system would require: reverse-engineering the existing firmware (the original source code may or may not still exist), designing a new control system, writing new firmware, testing it against every production scenario the old system handles, qualifying the new system for automotive safety standards, scheduling downtime for installation, and training operators on the new system. The cost runs into hundreds of thousands of dollars. The risk is non-trivial; any bug could halt production.

So they order more Z80s. And the Z80 stays in production for another year.

Multiply this scenario by thousands of factories, millions of installed devices, and billions of lines of proven firmware, and you begin to understand why some processors simply cannot die. The cost of replacing them exceeds the cost of maintaining them, indefinitely.

This is also why the TI-84+ still uses a Z80. Texas Instruments has decades of TI-BASIC software, decades of teacher training materials, decades of standardized test approvals, and a user base that expects backward compatibility with programs written in 2004. The Z80 isn't the best processor for a modern calculator. But replacing it would require replacing everything else, and "everything else" is where the real value lives.

The Newcomen Pattern

There's a historical analogy I keep returning to. Thomas Newcomen built his atmospheric steam engine in 1712. It was inefficient, converting roughly 1% of the heat energy in coal into useful work. James Watt's improved design, introduced in the 1760s, was dramatically better: separate condenser, double-acting cylinder, and eventually five times the thermal efficiency. By any rational engineering measure, the Newcomen engine should have vanished overnight.

It didn't. Newcomen engines continued to be built and operated for decades after Watt's design was available. In some mining operations, they remained in service into the 19th century. The reasons were the same ones that keep Z80s in factories today: the existing engines worked, the operators knew how to maintain them, the replacement cost was high, and the performance of the old engine was adequate for the task.

"Adequate for the task" is the phrase that explains processor longevity better than any technical specification. The Z80 is adequate for a graphing calculator. The 6502 is adequate for a simple embedded controller. The 8051 is adequate for a washing machine. And "adequate" plus "proven" plus "cheap" plus "available from multiple sources" is a combination that "superior but new and unfamiliar" almost never beats.

The Numbers Tell the Story

It's worth pausing to appreciate the sheer scale of the survivors' deployment.

The 8051 family has been manufactured in quantities estimated at over 10 billion units. That's not a typo. Ten billion. More 8051 derivatives have been produced than any other processor architecture in history, including x86. They're in your car; a modern automobile contains dozens of microcontrollers, many of them 8051 variants, handling everything from window controls to tire pressure monitoring. They're in your thermostat, your microwave, your garage door opener.

The Z80 and its clones have shipped in quantities that are harder to pin down precisely, but conservative estimates exceed a billion units across all manufacturers and derivatives. The 6502 family, counting all variants from the original through the 65C816 that powered the Apple IIGS and the Super Nintendo, is in a similar range.

The 68000 family took a different path: fewer total units but higher-value applications. Where the 8051 went wide and cheap, the 68k went deep and capable. It dominated the workstation market before RISC architectures displaced it, then settled into a long career in automotive and industrial control. NXP's ColdFire and subsequent QorIQ Layerscape processors carry DNA that traces back to the original 68000. The architecture didn't die; it evolved.

What's remarkable about these numbers is that they continue to grow. These aren't static installed bases slowly decaying as old equipment is retired. New products are still being designed with 8051 cores. New Z80-compatible processors are still being fabricated; even after Littelfuse discontinued the original Z84C00 in 2024, third-party clones and the eZ80 keep the instruction set alive. When I built a dual Z80 RetroShield, I ordered Z84C0020PEC chips that were still in stock from the final production runs. A 1976 design, manufactured nearly half a century later. And the fact that Zilog's discontinuation made international headlines tells you everything about how deeply embedded these chips remain. You don't mourn a processor nobody uses.

What This Means for Modern Processors

The ARM Cortex-M0, introduced in 2009, is arguably the first modern processor that has a plausible shot at matching the longevity of the 8-bit survivors. It's licensable (like the 8051), simple (like the 6502), power-efficient (like the Z84C00), and backed by an ecosystem that's growing rapidly. ARM's licensing model (selling the design, not the chip) mirrors the model that made the 8051 ubiquitous.

RISC-V, as an open ISA, goes even further. No licensing fees, no single company that can discontinue the architecture, no vendor lock-in. I've reviewed RISC-V boards and watched the ecosystem grow. If any modern ISA is positioned to last fifty years, it's RISC-V, not because it's the best architecture, but because it's the hardest to kill.

But here's the uncomfortable truth for anyone designing a new processor architecture: the window for establishing a forty-year processor is probably closed. The Z80, 6502, 68000, and 8051 all emerged during a period when the microprocessor market was being established. There were no entrenched incumbents. Every design win was greenfield. Every new application (calculators, arcade cabinets, industrial controllers, medical devices) was being designed for the first time with microprocessors.

That era is over. Every new design now competes against an installed base. Every new ISA competes against ARM's ecosystem. The switching costs that keep forty-year-old processors alive are the same switching costs that prevent new architectures from gaining traction. The moat works in both directions.

The Lesson

The processors that last aren't the ones that push the performance envelope. They're the ones that solve a problem well enough, cheaply enough, reliably enough, and from enough sources that replacing them is never worth the trouble. Technical excellence is necessary but not sufficient. What matters more is the web of dependencies (the toolchains, the trained engineers, the certified designs, the proven firmware, the institutional knowledge) that accumulates around a processor over decades.

The Z80 will outlive many of the engineers reading this, not because it's a great processor, but because it's woven into the fabric of systems that nobody has a compelling reason to redesign. The 8051 will outlive the Z80, because it's woven into even more systems. And somewhere in a high school classroom, a student is pressing buttons on a TI-84+ that runs on a fifty-year-old instruction set, completely unaware that the chip executing their quadratic formula has been doing this job since before their grandparents started dating.

That's longevity. Not the kind you engineer. The kind that happens when everything around the chip conspires to keep it in place.

Image credits: Hitachi HD68000 and Intel P8051 photographs by Konstantin Lanzet, via Wikimedia Commons. Licensed under GFDL and CC BY-SA 3.0 respectively.

Designing a Dual Z80 RetroShield: Two CPUs, One Bus, Zero GUI (Part 1)

A.C. Jokela — Fri, 06 Mar 2026 14:00:00 GMT

The RetroShield Z80 by Erturk Kocalar at 8bitforce.com is one of my favorite pieces of hardware. A real Zilog Z80 CPU on a shield that plugs into an Arduino Mega. The Arduino emulates memory and I/O while the Z80 executes real instructions on real silicon. I've used it to boot CP/M, play Zork over WiFi, port it to the Arduino Giga R1, and even commission a custom level-converter shield to bridge the voltage gap.

But a single Z80 is, well, a single Z80. Real multi-processor Z80 systems existed in the 1980s. Machines like the Cromemco System Three and some S-100 configurations ran multiple Z80s on a shared bus, with bus arbitration mediating access. The question that kept nagging at me: could I fit a second Z80 onto the RetroShield?

I should be honest about something: PCB design is one of my least knowledgeable areas of computing. I'm comfortable with firmware, with compilers, with operating systems, but the physical layer, the world of copper traces and drill files and design rule checks, is territory I've mostly avoided. I can read a schematic, but I've never designed a board from scratch. What I wanted to find out was whether modern AI tools could bridge that gap, whether I could use AI to help me understand, alter, and extend Erturk Kocalar's existing RetroShield design into something new without becoming a PCB design expert first.

This is part one of a two-part series. This piece covers the design: architecture decisions, schematic work, PCB layout, autorouting, and Gerber generation. Part two will cover the physical boards arriving from the fab, assembly, bring-up, and the firmware that makes two Z80s cooperate.

One more thing worth mentioning up front: every step of this design was done without a GUI. That was intentional. I wanted to see how far I could get with just a terminal, command-line EDA tools, AI assistance, and Python scripts that modify PCB files directly. Partly because I think text-based workflows compose better with AI; it's much easier for an AI to generate a Python script that manipulates a text-based PCB file than to drive a graphical EDA tool. And partly because I wanted the entire process to be reproducible and scriptable, not trapped in a series of mouse clicks I'd never remember.

The Original Design

The stock RetroShield Z80 is a clean, simple board. A 55.88mm × 53.34mm two-layer PCB carrying:

U1: A Z80 CPU in a DIP-40 package
J1: A 2×18 pin header (36 pins) that plugs into Arduino Mega 2560 pins 22–53
A handful of passives: decoupling caps (C1, C2), a clock cap (C3), a clock series resistor (R1), an LED current-limiting resistor (R3), and a bus activity LED

The J1 header carries everything the Z80 needs: 16 address lines (A0–A15), 8 data lines (D0–D7), and control signals (CLK, RESET, INT, NMI, MREQ, IORQ, RD, WR). The Arduino drives the clock, provides the data when the Z80 reads, captures the data when the Z80 writes, and emulates whatever memory and I/O map you define in firmware. It's elegant in its simplicity; the Z80 thinks it's talking to a real computer, and in a sense, it is.

The schematic and PCB files use the gEDA format, text-based files that are human-readable and, crucially, scriptable. The schematic (.sch) defines the logical connections. The PCB (.pcb) defines the physical layout: component footprints, copper traces, vias, and board outline. Both are just text. This matters a lot for what comes next.

Why Two Z80s?

The honest answer is that I wanted to see if it could be done. But there are genuinely interesting things you can do with two processors sharing a bus:

Asymmetric multiprocessing. One Z80 runs CP/M as the primary CPU. The second handles I/O (serial communication, disk access, network operations), freeing the primary CPU from waiting on slow peripherals. This mirrors how some S-100 systems used coprocessor boards.

Cooperative multitasking. Both CPUs execute independent programs, taking turns on the shared bus. The Arduino arbitrates access using the Z80's built-in BUSRQ/BUSACK mechanism, a hardware handshake designed exactly for this purpose. One CPU gets the bus, executes for a while, then yields so the other can run.

Debugging and instrumentation. The second CPU can monitor the first. Watch the address bus to trace execution. Compare outputs. Run the same code on both CPUs and verify they produce identical results, which is useful for testing Z80 clones or FPGA implementations against real silicon.

The Z80 was designed for multiprocessor operation. As Rodnay Zaks details in Programming the Z80, it has dedicated bus request (BUSRQ) and bus acknowledge (BUSAK) pins specifically for multi-master bus sharing. Steve Ciarcia's Build Your Own Z80 Computer covers the hardware side of these signals in practical detail. Most hobbyist projects never use them. This one does.

Architecture: Shared Bus with Independent Control

The first design I considered (and quickly rejected) gave each Z80 its own independent header. Two 36-pin headers, two complete sets of address, data, and control lines. This would have worked electrically, but it was wrong for several reasons. It would have required either two Arduino Megas or consumed all the I/O on one Mega with nothing left for bus arbitration. The board would have been enormous. And it wouldn't have reflected how real multi-processor Z80 systems actually worked.

The right approach is a shared bus. Both Z80s connect to the same address and data lines through J1. They take turns driving the bus, just like in a real S-100 system. What each CPU needs independently is its own set of control signals: its own clock, its own reset, its own interrupt lines, and its own bus request/acknowledge pair.

I checked the Arduino Mega's pin budget. J1 uses pins 22–53 (32 I/O pins). The Mega still has pins 2–21 (20 pins) plus analog pins A0–A15 (16 more, usable as digital I/O), leaving 36 pins sitting idle. A second CPU's control signals only need about 10 pins. There was plenty of room.

The solution: a small supplementary 2×6 header (J2, 12 pins) carrying CPU2's independent control signals to the Arduino's remaining pins:

Pin 1:  +5V         Pin 2:  GND
Pin 3:  CLK_2       Pin 4:  RESET_2
Pin 5:  INT_2       Pin 6:  NMI_2
Pin 7:  MREQ_2      Pin 8:  IORQ_2
Pin 9:  RD_2        Pin 10: WR_2
Pin 11: BUSRQ_2     Pin 12: BUSAK_2

BUSRQ and BUSAK are the key pins. The Arduino firmware pulls BUSRQ low on whichever CPU should yield the bus. That CPU finishes its current machine cycle, tristates its outputs, and asserts BUSAK to signal it's off the bus. The other CPU can then drive the bus freely. It's the same mechanism Zilog designed in 1976; I'm just finally using it.

Building the Schematic, Without a Schematic Editor

The original project used classic gEDA tools (gschem, pcb), which are no longer packaged for Ubuntu 24.04. The modern replacement is lepton-eda, a maintained fork that reads the same file formats. But since the whole point was to avoid a GUI, even lepton-schematic's graphical mode was off the table.

This is where AI earned its keep. I don't have the gEDA file format memorized; I've never needed to. But AI can work through the format specification and generate correct output. I described what I wanted (a second Z80 sharing the existing bus, with independent control signals on a new header), and the AI helped me produce the schematic files, the symbol definitions, and eventually the PCB modifications. I still had to understand the architecture and make the design decisions, but the AI handled the translation from intent to file format.

gEDA schematic files are text. A component placement looks like this:

C 44300 47700 1 0 0 z80-1.sym
{
T 44400 59000 5 10 1 1 0 0 1
refdes=U2
}

That's a Z80 symbol placed at coordinates (44300, 47700), with reference designator U2. Net connections are similarly textual. N entries define wire segments, U entries define bus rippers. You can write an entire schematic in a text editor if you understand the coordinate system.

I created a new schematic page, kz80_cpu2.sch, for the second CPU. In gEDA's multi-page scheme, nets with the same name on different pages are automatically connected. So CPU2's address pins connect to nets named A0, A1, ..., A15 (the same net names used on page 1), and the netlister merges them into shared nets. The shared bus happens at the netlist level without any explicit cross-page wiring.

The one component that didn't exist yet was the 2×6 control header. I wrote a new gEDA symbol file (ctrlhdr2x6-1.sym) from scratch, a rectangular body with 12 pins, labeled with the control signal names, specifying the HEADER12_1 footprint. It's about 30 lines of text, all hand-written.

CPU2's schematic connections break down cleanly:

Shared with CPU1 (same net names, auto-merged): A0–A15, D0–D7, +5V, GND

Independent to CPU2 (new nets with _2 suffix): CLK_2, RESET_2, INT_2, NMI_2, MREQ_2, IORQ_2, RD_2, WR_2, BUSRQ_2, BUSAK_2

The total net count went from 37 to 48, only 11 new nets for an entirely new processor. That's the elegance of the shared-bus approach.

Modifying the PCB With Python

Here's where the CLI-only constraint got interesting. The normal workflow would be: run lepton-sch2pcb to update the PCB with new components from the schematic, then open the PCB in a graphical editor to place and route them. But lepton-sch2pcb had trouble finding footprints in pcb-rnd's library paths, and I didn't have a graphical editor anyway.

So I had AI write a Python script (add_cpu2_shared.py) to modify the PCB file directly. The pcb-rnd file format is text-based, with clearly delimited blocks for each component (Element), each copper trace (Line), each via (Via), and the netlist (NetList). The script:

Widened the board from 55.88mm to 86.36mm, an extra 30.48mm to accommodate the second Z80 and control header, placed on the right half of the board.

Inserted five new Element blocks: U2 (Z80, DIP-40), J2 (2×6 header), C4 and C5 (decoupling and clock caps), and R2 (clock series resistor). Each Element block is essentially a footprint definition: pin positions, pad dimensions, drill sizes, silkscreen outlines. I copied the dimensional parameters from the existing components to maintain consistency.

Updated the netlist in two ways. For shared nets (A0–A15, D0–D7, +5V, GND), the script found each existing net block and appended Connect("U2-xx") entries. For CPU2's independent control signals, it created 11 entirely new net blocks. The +5V net picked up four new connections: U2's VCC pin, U2's WAIT pin (tied high, since WAIT is active low, so high means "not waiting"), C4, and J2.

The result was a valid PCB file with all components placed and all nets defined, but no copper traces connecting anything.

Autorouting: Let the Machine Do the Tedious Part

With components placed and nets defined, the board needed routing: actual copper traces connecting all those pins. Doing this by hand over SSH would have been masochistic. This is exactly what autorouters exist for.

The workflow: export the PCB to Specctra DSN format (an industry-standard interchange format for autorouters), run Freerouting, then import the results back.

First Attempt (Failed)

The first attempt exported the PCB with the original CPU1 traces still in place, hoping Freerouting would preserve them and only route the new nets. Instead, Freerouting spent 50+ seconds per pass trying to work around traces it couldn't associate with its own net encoding. After 48 passes and 40 minutes, it was still failing to route several nets.

Second Attempt (Clean Slate)

Another AI-generated Python script (strip_traces.py) removed all existing copper traces from the PCB file. This was a careful operation. The script had to remove Line[...] entries inside Layer blocks (copper traces) while preserving ElementLine[...] entries (component silkscreen outlines that look syntactically similar).

With a clean board, Freerouting ran in headless mode:

java -jar /tmp/freerouting.jar -de kz80.dsn -do kz80.ses -mp 20

It completed the initial routing in 10 passes, then spent another 49 passes optimizing trace length, converging at pass 59 with the message: "There were only 10.60 track length increase in the last 5 passes, so it's very likely that autorouter can't improve the result further."

Total routing time: about three minutes. The result: 191 wires decomposed into 897 individual trace segments, plus 82 vias for layer transitions. Every net connected. Every design rule satisfied.

Importing Routes Back

One more headless problem: pcb-rnd's SES import requires the GUI. I tried xvfb-run with action commands, but it hung waiting for GTK widget interactions that couldn't happen without a display.

The solution was yet another AI-generated Python script (ses_to_pcb.py) that parsed the Freerouting SES output and injected the routes directly into the PCB file as copper Line entries. The main complication was coordinate system conversion: the SES file uses a bottom-left origin (y increases upward) while pcb-rnd uses a top-left origin (y increases downward). The script also handled via translation, mapping Freerouting's via definitions to pcb-rnd's format with appropriate pad sizes, drill diameters, and clearances.

897 trace segments and 82 vias injected. The PCB was fully routed.

The top copper layer after Freerouting: 897 trace segments connecting 48 nets across both Z80s, the J1 bus header, and the J2 control header. Every trace was placed by the autorouter; none were drawn by hand.

Generating Production Files

The final step was generating Gerber files, the industry-standard format that PCB fabrication houses use to manufacture boards. pcb-rnd's command-line exporter handled this cleanly:

pcb-rnd -x gerber --all-layers kz80.pcb

This produced 11 files covering top and bottom copper, solder mask, silkscreen, paste stencil, board outline, and drill locations. pcb-rnd uses verbose filenames (kz80.top.copper.none.3.gbr), so a renaming script converted them to the standard extensions (.gtl, .gbl, .gts, etc.) that fabrication houses expect.

I also added tinycomputers.io to the top silkscreen layer, placed directly below the existing www.8bitforce.com text, a small nod to both projects.

The final Gerber package: 35KB zipped, ready for fabrication.

The Final Board

The top silkscreen: U1 (left) and U2 (right) with the J1 bus header on the far left and the J2 control header between the two CPUs. The silkscreen includes the original 8bitforce.com credit alongside tinycomputers.io.

Here's what changed from the original RetroShield to the dual-CPU version:

Parameter	Original	Dual CPU
Board dimensions	55.88 × 53.34mm	86.36 × 53.34mm
Layers	2	2
Z80 CPUs	1	2
Headers	J1 (36 pins)	J1 (36) + J2 (12) = 48 pins
Nets	37	48
Through-hole components	2	4
SMD components	6	9
Trace segments	-	897
Vias	-	82

The board is wider but not taller. The second Z80 sits to the right of the first, with the J2 control header between them. Both CPUs share the J1 bus connection, and the Arduino firmware will manage who drives the bus at any given moment.

The Toolchain Nobody Uses

It's worth stepping back to note what just happened. An entire PCB was designed (schematic capture, component placement, autorouting, Gerber generation) without opening a single graphical application. Every step was either a command-line tool invocation or an AI-generated Python script manipulating text files. And it was done by someone who, at the start of the project, couldn't have told you the difference between a Gerber file and a drill file.

That was the whole point. I chose to avoid a GUI specifically because I wanted to test a hypothesis: that AI-assisted, text-based workflows could let someone with domain knowledge in adjacent areas (firmware, systems programming) operate effectively in an unfamiliar domain (PCB design). The text-based EDA formats made this possible; they gave the AI something it could read, reason about, and generate. A graphical tool would have put me back to square one, clicking through menus I didn't understand.

I'm not claiming this is better than using KiCad or Altium with a mouse. For complex boards with hundreds of components, graphical tools and experienced designers are indispensable. But for a modification like this (adding a known set of components to an existing, well-documented open-source design), AI plus text-based tools was surprisingly effective. I brought the architectural understanding (how Z80 bus arbitration works, which signals need to be shared versus independent) and the AI handled the translation into file formats I'd never touched before. Most of the time was spent understanding the design, not fighting tools.

What's Next

The Gerber files are at the fab now. In part two, I'll cover what happens when the physical boards arrive: inspection, assembly, first power-on, and the Arduino firmware that orchestrates two Z80s on a shared bus. The firmware is where the real complexity lives: bus arbitration timing, memory mapping for two independent address spaces, and the question of what to actually run on a dual-Z80 system in 2026.

Here's a preview of what the bus arbitration core looks like. The Arduino manages which CPU owns the shared bus at any given moment using the Z80's hardware BUSRQ/BUSAK handshake:

// --- Pin definitions (active low) ---
// CPU1 control (directly from J1 via existing RetroShield mapping)
#define CPU1_CLK      A5
#define CPU1_BUSRQ    A4    // directly from Arduino to CPU1 BUSRQ pin
#define CPU1_BUSAK    A3    // directly from CPU1 BUSAK pin to Arduino

// CPU2 control (directly from J2 header)
#define CPU2_CLK      2
#define CPU2_BUSRQ    3
#define CPU2_BUSAK    4

// Bus state
volatile uint8_t active_cpu = 1;

void setup() {
  // BUSRQ is output (Arduino tells CPU to release bus)
  pinMode(CPU1_BUSRQ, OUTPUT);
  pinMode(CPU2_BUSRQ, OUTPUT);

  // BUSAK is input (CPU tells Arduino it released bus)
  pinMode(CPU1_BUSAK, INPUT_PULLUP);
  pinMode(CPU2_BUSAK, INPUT_PULLUP);

  // Start with CPU1 active, CPU2 off the bus
  digitalWrite(CPU1_BUSRQ, HIGH);   // HIGH = don't request bus release
  digitalWrite(CPU2_BUSRQ, LOW);    // LOW  = request CPU2 to release bus
  active_cpu = 1;

  // Wait for CPU2 to acknowledge it's off the bus
  while (digitalRead(CPU2_BUSAK) == HIGH);
}

bool switch_to_cpu(uint8_t cpu) {
  if (cpu == active_cpu) return true;

  uint8_t old_busrq = (active_cpu == 1) ? CPU1_BUSRQ : CPU2_BUSRQ;
  uint8_t old_busak = (active_cpu == 1) ? CPU1_BUSAK : CPU2_BUSAK;
  uint8_t new_busrq = (cpu == 1) ? CPU1_BUSRQ : CPU2_BUSRQ;

  // Ask the active CPU to release the bus
  digitalWrite(old_busrq, LOW);

  // Wait for acknowledgment (CPU finishes current machine cycle first)
  unsigned long timeout = micros() + 1000;
  while (digitalRead(old_busak) == HIGH) {
    if (micros() > timeout) return false;   // hung CPU — shouldn't happen
  }

  // Bus is free. Release the new CPU onto it.
  digitalWrite(new_busrq, HIGH);
  active_cpu = cpu;
  return true;
}

The critical detail is timing. When the Arduino pulls BUSRQ low, the Z80 doesn't stop immediately; it finishes its current machine cycle, which can take 3–6 clock periods depending on the instruction. Only then does it tristate its address, data, and control outputs and assert BUSAK. The while loop waits for that handshake to complete. During the transition, neither CPU is driving the bus, and the Arduino must not attempt any bus operations.

This is a simplified version. The full firmware in part two will handle clock generation for both CPUs, memory mapping, I/O dispatch, and the arbitration policy (round-robin, priority-based, or cooperative yield). But the handshake above is the foundation everything else builds on. It's the same protocol that made multi-Z80 S-100 systems work in the early 1980s.

The hardware design is the easy part. Making two 50-year-old processors cooperate is the challenge.

Source Files

All schematics, PCB files, Gerber outputs, and helper scripts for this project are open source:

dual-z80: KiCad/gEDA source files, Gerber package, Python scripts for PCB manipulation, and build log

This is part one of a two-part series. Part two will cover board assembly, bring-up, and dual-CPU firmware.

Previous RetroShield posts: CP/M on the RetroShield · Fiverr PCB Design · CP/M on the Giga R1 · Zork on the Giga

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.

The Z-80 Microcomputer Handbook: A 1978 Reference That Outlived Its Era

A.C. Jokela — Thu, 05 Feb 2026 21:00:00 GMT

In 1978, William Barden, Jr. set out to write a book with a threefold purpose: to acquaint the reader with the hardware of the Z80, to discuss its "almost overwhelming" software instruction set, and to describe the microcomputer systems being built around it. The result was The Z-80 Microcomputer Handbook, published by Howard W. Sams & Co., one of the most prolific technical publishers of the era. At just over 300 pages, Barden delivered on all three promises, producing a reference that served as both tutorial and encyclopedia for what was arguably the most important microprocessor of the late 1970s.

The copy I have is the eighth printing from 1985. Eight printings. The book was first published in 1978, and Howard W. Sams was still running the presses seven years later. I'll confess I hadn't fully appreciated that the Z80's popularity carried that kind of momentum into the mid-1980s, by which point Intel's 80286 had been on the market for three years and IBM's AT was already sitting on desks in corporate offices across America. Yet here was a book about an 8-bit processor from 1976, still selling briskly enough to justify another print run. That tells you something about the Z80's staying power, and something about the quality of Barden's handbook.

The Author and the Publisher

William Barden, Jr. was a prolific technical author who wrote extensively about microprocessors and microcomputers throughout the late 1970s and 1980s. His writing style sits in a comfortable middle ground between the dry precision of a Zilog datasheet and the conversational approachability of a hobbyist magazine column. He assumes the reader has some technical foundation but doesn't demand an electrical engineering degree. The prose is clear, methodical, and, when the subject matter allows, occasionally wry.

Howard W. Sams & Co., a subsidiary of Macmillan, was headquartered in Indianapolis and had built a reputation as one of the go-to publishers for electronics and computing references. Their catalog included the famous Photofact service manuals and a long list of titles covering everything from transistor theory to amateur radio. A Sams book on your shelf carried a certain implicit endorsement: this was going to be technically sound, well-organized, and useful.

Three Sections, One Processor

Barden organized the book into three distinct sections, each approaching the Z80 from a different angle. Section I covers Z80 hardware: the architecture, interface signals and timing, addressing modes, instruction set, flags and arithmetic operations, interrupt sequences, and interfacing memory and I/O devices. Section II shifts to Z80 software, beginning with the assembly process itself and then working through the major instruction groups: data movement, arithmetic and logical operations, shifting and bit manipulation, list and table operations, subroutine calls, I/O and interrupt operations, and commonly used subroutines. Section III surveys five commercial microcomputer systems built around the Z80.

This three-part structure gives the book a completeness that many competing references lacked. Readers who wanted to understand the Z80 at the silicon level could camp out in Section I. Programmers who needed to write assembly code had a thorough software reference in Section II. And anyone trying to decide which Z80 system to buy, or trying to understand what made these systems different from one another, could turn to Section III for a comparative tour.

The Hardware Foundation

Section I opens with a concise but thorough treatment of the Z80's internal architecture. Barden walks the reader through the processor's register set: fourteen general-purpose 8-bit registers organized in two banks (A through L, and their primed counterparts A' through L'), plus the special-purpose registers: two index registers (IX and IY), the stack pointer, program counter, interrupt vector register, and memory refresh counter.

The dual register bank architecture receives careful attention, and rightly so. The ability to swap between two complete register sets with a single EXX instruction was one of the Z80's most distinctive features. Barden explains not just the mechanics but the motivation: fast interrupt handling without the overhead of pushing and popping registers to the stack. For real-time applications (process control, data acquisition, communications) this was a significant advantage over the Intel 8080A, which required explicit save-and-restore sequences.

The flag register documentation is similarly thorough. Each of the six testable flags (Sign, Zero, Half-carry, Parity/Overflow, Subtract, and Carry) gets individual treatment, with clear diagrams showing bit positions and the conditions under which each flag is set or cleared. Barden's flag register diagram on page 19 is the kind of figure you'd photocopy and tape to the wall above your workbench.

Chapter 3 dives into the Z80's interface signals and timing with a level of detail that borders on the exhaustive. Every control signal is documented: MREQ, IORQ, RD, WR, RFSH, HALT, WAIT, INT, NMI, BUSRQ, BUSAK, and the rest. The timing diagrams for M1 cycles, memory read and write cycles, I/O cycles, interrupt acknowledge sequences, and bus request/acknowledge handshakes are presented with the precision needed for hardware designers wiring up actual systems. This is reference material, not light reading, but it's the kind of reference material you desperately need when your homebrew system isn't behaving and you're staring at an oscilloscope trace trying to figure out why.

Chapter 4's treatment of addressing modes deserves special mention. The Z80 supported ten addressing modes: implied, immediate, extended immediate, register, register indirect, extended, modified page zero, relative, indexed, and bit addressing. Barden documents each with examples showing the instruction encoding at the bit level. The indexed addressing mode, using IX or IY plus a displacement byte, was a Z80 innovation that made structured data access far more practical than on the 8080A. Barden's diagrams showing multi-byte instruction formats, with op-codes, displacement values, and immediate data laid out byte by byte, are models of technical illustration.

The instruction set itself, covered in Chapter 5, is presented in tabular form with every detail a programmer needs: mnemonic, symbolic operation, flag effects, op-code encoding in binary, byte count, machine cycle count, and T-state count. These tables span dozens of pages and represent the kind of painstaking documentation that made the book worth keeping within arm's reach during coding sessions. The eleven instruction groups (from 8-bit loads through block transfers, arithmetic operations, rotates and shifts, bit manipulation, jumps, calls, and I/O) are each given systematic treatment.

Chapter 8 rounds out the hardware section with a practical discussion of interfacing memory and I/O devices to the Z80. The treatment of the Z80 PIO (Parallel Input/Output) chip is particularly detailed, covering all four operating modes with programming examples. Barden walks through the initialization sequences for each mode, the interrupt vector configuration, and the handshaking protocols, exactly the kind of information you'd struggle to extract from Zilog's own documentation without considerable effort.

The Software Perspective

Section II opens with what might be the most pedagogically effective chapter in the book: Chapter 9, the Z80 Assembler. Rather than jumping straight into assembly language syntax, Barden starts with raw machine language. He presents a trivial program (adding the numbers one through ten) first as a series of mnemonics, then as hand-assembled machine code with each op-code and operand byte spelled out in hexadecimal. He then shows the same program rewritten with a loop, and walks through the manual assembly process step by step: calculating instruction lengths, assigning memory addresses, resolving label references, filling in the binary encoding of each instruction.

This is brilliant pedagogy. By forcing the reader through the pain of manual assembly (calculating that a JP NZ,LOOP instruction at address 0105H needs to encode the target address 0103H as bytes 03H and 01H in little-endian order) Barden ensures they understand exactly what an assembler does before they start using one. The transition from manual assembly to symbolic assembly language feels earned rather than arbitrary. When Barden introduces labels, pseudo-operations, expression evaluation, and the two-pass assembly process, the reader understands why these features exist, not just how to use them.

Chapters 10 through 15 systematically work through the instruction groups from a programmer's perspective. Each chapter takes a logical group (data movement, arithmetic and logic, shifting and bit manipulation, list and table operations, subroutines, I/O and CPU control) and provides detailed examples showing how the instructions are used in practice. The block transfer instructions (LDI, LDIR, LDD, LDDR) and block search instructions (CPI, CPIR) receive particularly good coverage, as these were among the Z80's most powerful features and had no equivalent in the 8080A instruction set.

Chapter 16, covering commonly used subroutines, is where the book transitions from reference to practical cookbook. Barden provides complete, tested subroutine implementations for comparison, timing loops, multiply, divide, multiple-precision arithmetic, ASCII-to-binary conversion, base conversion, memory fill, string comparison, and table search. Each subroutine is documented with its entry conditions, exit conditions, and register usage, the kind of disciplined documentation that professional assembly programmers live by. The table search routine, using IX as a base pointer with entry size in DE, is a clean example of the Z80's indexed addressing mode earning its keep.

A Snapshot of the Ecosystem

Section III is where the book transforms from a processor reference into a historical document. In two chapters, Barden surveys five companies manufacturing Z80-based microcomputer systems: Zilog itself, Technical Design Labs (TDL), Cromemco, The Digital Group, and Radio Shack.

The Zilog chapter covers the Z80 MCB (Microcomputer Board), a complete single-board computer measuring 7.7 by 7.75 inches. With 4K of dynamic RAM, up to 4K of EPROM or PROM, a PIO for parallel I/O, a USART for serial communication, and a CTC for timing, the MCB was a capable development platform. Barden documents the memory map, I/O port addressing, interrupt configuration, and the 1K monitor program with its eight commands for examining memory, setting breakpoints, and controlling program execution. The minimum MCB system (the board itself, a 5-volt power supply, and a Teletype ASR-33) was a complete development environment, albeit a spartan one.

The Cromemco coverage reveals a more ambitious ecosystem. Their Z-1 and Z-2 systems were built around the S-100 bus, with the Z-2 offering a chassis with 21 card slots, a 30-amp power supply, and room for serious expansion. Cromemco's peripheral lineup included a TV DAZZLER for color graphics, a Digital Interface Board with analog-to-digital and digital-to-analog converters, and their BYTESAVER EPROM programmer board. Their CONTROL BASIC (a specialized BASIC interpreter designed for process control and automated testing) hints at the industrial applications that were already finding the Z80.

The Digital Group section reveals a company taking a different approach: offering CPU boards for multiple processor families (Motorola 6800, MOS Technology 6502, Intel 8080A, and Z80) all interchangeable at the board level. Their Phi-Deck cassette storage system, with 800 bytes per second transfer rates and CRC error checking, was a notably sophisticated approach to the cassette storage problem.

And then there's Radio Shack. Barden's description of the TRS-80 stands out because of what it represented: a completely integrated, turnkey system that a consumer could purchase, take home, plug in, and immediately begin programming in BASIC. While the other systems in this chapter required varying degrees of assembly, configuration, and technical knowledge, the TRS-80 was designed for people who wanted to use a computer, not build one. With its 53-key keyboard, 12-inch monitor, cassette storage, and 4K of ROM containing a BASIC interpreter, it was a vision of the microcomputer's commercial future, even if its 64-character-by-16-line display and 4K of RAM seem quaint today.

Reading these system descriptions in sequence, you can see the microcomputer market stratifying in real time. At one end, boards like Zilog's MCB served engineers and serious hobbyists who wanted maximum flexibility. In the middle, S-100 systems from Cromemco and others offered expandability with some degree of standardization. And at the consumer end, Radio Shack was proving that microcomputers could be mass-market products. All of them ran on the Z80.

The Intel Shadow

What makes the 1985 printing date so remarkable is the context in which someone would have been buying this book. By 1985, the microcomputer landscape had shifted dramatically from the world Barden documented in 1978.

Intel had introduced the 8086 in 1978 (the same year this book was published) and its cost-reduced sibling, the 8088, in 1979. When IBM chose the 8088 for its Personal Computer in 1981, the x86 architecture gained a gravitational pull that would reshape the entire industry. The Intel 80286, launched in 1982, brought protected mode, a 16-megabyte address space, and hardware memory management. When IBM built the 80286 into the PC/AT in August 1984, it created what would become the standard business computer platform for years to come. The AT was fast, expandable, and, critically, backward compatible with the enormous library of software already written for the original PC.

By 1985, the trajectory was clear. The x86 architecture was the future of personal computing. CP/M, which had been the dominant operating system for Z80 machines, was fading in the face of MS-DOS. The TRS-80 line was winding down. Cromemco had pivoted to 68000-based systems. The Z80's reign as the king of personal computing was effectively over.

And yet the eighth printing rolled off the presses.

The Z80 endured because personal computing was never the whole story. The processor had found its way into embedded systems, industrial controllers, point-of-sale terminals, scientific instruments, and countless other applications where its simplicity, low cost, and well-understood behavior were more valuable than raw performance. The Z80 didn't need a 16-megabyte address space to control a factory floor. It didn't need protected mode to run a cash register. It needed to be cheap, reliable, and thoroughly documented, and books like Barden's were part of that documentation ecosystem.

There's also the educational angle. In 1985, the Z80 was still one of the best processors for learning computer architecture. Its instruction set was complex enough to illustrate real-world design tradeoffs (accumulator-based operations, register pairs for 16-bit addressing, multiple addressing modes, condition flags) without being so complex as to overwhelm a student. Many universities and technical colleges were still teaching microprocessor courses using the Z80 well into the late 1980s. For those students and their instructors, Barden's handbook was still entirely relevant.

The Book as Reference

Evaluating The Z-80 Microcomputer Handbook as a technical reference, it holds up remarkably well within its domain. The instruction set tables in Chapter 5 are comprehensive and clearly formatted, with every detail needed for hand-coding or verifying assembler output. The appendices (covering electrical specifications, an 8080-to-Z80 instruction cross-reference, a complete instruction summary, binary and hexadecimal tables, and ASCII codes) round out the reference material.

The 8080/Z80 comparison in Appendix B is particularly useful for readers coming from the Intel side. Since the Z80 included the entire 8080A instruction set as a subset (using Zilog's own mnemonics rather than Intel's), this cross-reference served as a Rosetta Stone for programmers transitioning between the two architectures. Many Z80 systems needed to run software originally written for the 8080A, and understanding the mapping between Intel and Zilog mnemonics was a practical necessity.

Where the book shows its age most clearly is in Section III. The specific microcomputer systems described (the Zilog MCB, the TDL ZPUTM and Xitan, the Cromemco Z-1 and Z-2, the Digital Group systems, and the TRS-80) are all long discontinued. But this is precisely what makes Section III valuable today: it's a primary source document of a hardware ecosystem that existed for a brief, vibrant moment and then vanished. You won't find this level of detail about the Digital Group's Phi-Deck cassette system or TDL's System Monitor Board in Wikipedia.

A Companion Piece

Readers of this site may notice a natural pairing with Steve Ciarcia's Build Your Own Z80 Computer (Amazon), which we reviewed previously. Where Ciarcia's book is a construction manual (guiding the reader through building a complete Z80 system from power supply to CRT terminal) while Barden's handbook is a reference and survey. Ciarcia teaches you to build; Barden teaches you to understand. The two books complement each other almost perfectly, and it's easy to imagine a 1978-era hobbyist keeping both within reach: Barden's for looking up instruction encodings and timing specifications, Ciarcia's for wiring up the hardware to run them on.

The difference in approach also reflects the different publishers. BYTE Books, which published Ciarcia, was rooted in the hobbyist magazine world and emphasized hands-on projects. Howard W. Sams had a longer tradition of comprehensive technical references. Each publisher played to its strengths.

Final Thoughts

The Z-80 Microcomputer Handbook is not a book that will teach you to build a computer, nor is it one that will dazzle you with narrative flair. It is, instead, something arguably more valuable: a thorough, well-organized, clearly written reference to a processor and its ecosystem, produced at the moment when that ecosystem was at its peak. Barden's systematic approach (hardware first, then software, then systems) gives the reader a complete understanding of the Z80 world from silicon to finished product.

That the book was still being printed in 1985, with the IBM AT already on the market and the 80386 just a year away, is a testament to both the Z80's remarkable longevity and the quality of Barden's work. Eight printings don't happen by accident. They happen because engineers, students, hobbyists, and embedded systems designers kept walking into bookstores and electronics shops and deciding that yes, they still needed this book.

Nearly five decades after its original publication, The Z-80 Microcomputer Handbook remains a worthwhile read for anyone interested in the foundations of microcomputing. Paired with Rodnay Zaks' Programming the Z80 for software depth and J.S. Walker's Design a Z80 Computer for a modern practical build guide, it forms part of an essential Z80 library. The architecture it documents influenced a generation of processor designs. The assembly language techniques it teaches remain relevant for anyone working close to the metal. And the ecosystem it surveys (that brief, fertile period when a handful of small companies were inventing the personal computer industry in real time) deserves to be remembered in the detail that Barden provided.

How We Learned Hardware in 1983

A.C. Jokela — Sat, 31 Jan 2026 16:00:00 GMT

I recently spent an afternoon with a scanned PDF of Z80 Applications by James W. Coffron, published by SYBEX in 1983. It's a 306-page guide to building microprocessor systems from discrete components. Reading it felt like archaeology, not because the technology is obsolete (the Z80 is still manufactured today), but because the way it teaches is so foreign to how we learn hardware now.

The book assumes you want to build a computer from chips. Not program one. Not configure one. Build one, with a soldering iron, from a CPU, some RAM, some ROM, and a handful of 74LS-series logic gates. The gap between this and a modern "Getting Started with Arduino" tutorial is so vast it's almost difficult to articulate. But I'll try.

The Starting Point: What You're Expected to Know

Coffron's introduction sets the tone:

"Have you ever imagined a new application for a microprocessor-controlled system, only to have the idea vanish under a torrent of technical details found in the data sheets? If so, you're not alone."

This is a book for people who have already read the datasheets and gotten lost. The assumed baseline is that you understand what a microprocessor is, what buses are, what memory addressing means. The book's job is to bridge the gap between "I understand the theory" and "I have a working system on my bench."

Compare this to the Arduino "Blink" tutorial, which assumes you know how to plug in a USB cable. The entire hardware abstraction layer (the thing that makes digitalWrite(13, HIGH) turn on an LED) is invisible. You don't need to know that pin 13 maps to PORTB bit 5 on the ATmega328P, or that setting that bit high puts 5V on the physical pin, or that there's a 220-ohm current-limiting resistor already on the board. You just call a function.

Chapter 1: Connecting a CPU to ROM

The first real chapter of Coffron's book is titled "Using the Z80 with ROM." Not programming the Z80. Not using an existing Z80 system. Literally: how do you wire a Z80 CPU chip to a 2716 EPROM so that the CPU can fetch instructions?

Figure 1.9 from the book: A complete schematic showing the connection between a 2716 EPROM and the Z80 microprocessor, including the logic used for enabling the memory device according to the memory map.

This single diagram requires understanding:

Address buses: The Z80 has 16 address lines (A0-A15). The 2716 EPROM has 11 address inputs. How do you connect them? Which lines go where?
Data buses: The Z80 has 8 data lines. The 2716 has 8 data outputs. These connect directly, but only when the chip is selected.
Chip select logic: The 74LS138 is a 3-to-8 decoder. The book explains how to use the upper address lines (A11-A15) to generate chip select signals, so that different memory chips respond to different address ranges. This is memory mapping, implemented in hardware.
Control signal generation: The Z80 outputs MREQ (memory request) and RD (read). These must be combined with OR gates to generate MEMR, which enables the ROM's output buffers at the correct moment.

The timing diagram that accompanies this schematic shows exactly when each signal transitions:

Figure 1.10: A timing diagram showing the important signal relationships. Address lines stabilize, MREQ goes low, RD goes low, data becomes valid, then everything releases.

This is page 12 of the book. We haven't written a single line of code yet. We're just trying to make the CPU able to read instructions from a ROM chip.

The Modern Equivalent: There Isn't One

On a Raspberry Pi, you don't connect the CPU to RAM. The RAM is soldered to the board. On an Arduino, the flash memory that holds your program is inside the microcontroller chip. There's no schematic to draw because there's no external connection to make.

When a modern tutorial says "upload your sketch," it's hiding:

The USB-to-serial converter that talks to the bootloader
The bootloader that receives bytes and writes them to flash
The flash memory controller that handles page erasure and programming
The reset circuit that starts execution at the right address

All of this exists. It's just not something you're expected to understand, or even know about, to get started.

Dynamic RAM: Where It Gets Serious

Chapter 4 of Coffron's book covers dynamic RAM. This is where the real complexity lives.

Static RAM is simple: you put an address on the bus, assert the chip select, and the data appears. Dynamic RAM is different. It stores bits in tiny capacitors that leak charge, so you have to refresh them periodically. It uses multiplexed addressing to reduce pin count. You send the row address, strobe RAS (Row Address Strobe), then send the column address and strobe CAS (Column Address Strobe).

The book dedicates an entire chapter to building a 16K x 8-bit dynamic RAM system using 4116 chips. This involves:

Address multiplexing hardware: You need logic to switch between presenting the low address bits and the high address bits to the RAM chips at the right times.
RAS/CAS timing generation: The sequence of RAS and CAS signals must meet strict timing requirements. Too fast and the chips don't respond. Too slow and you waste cycles.
Refresh logic: The Z80 has a built-in refresh counter (one of its innovations over the 8080), but you still need to understand when refresh cycles occur and how they interleave with normal memory access.

Figure 2.6: A partial data sheet and block diagram for the 2114, a 1K x 4 static RAM. The book walks through every pin and its function.

Here's the key insight: in 1983, if you wanted more than a few kilobytes of RAM, you had to use dynamic RAM. Static RAM was expensive. The 4116 gave you 16K bits for the same cost as 1K bits of static RAM. But you paid for it in complexity.

Today? The Raspberry Pi 5 has 8 gigabytes of DDR4 RAM. The timing controller, refresh logic, and address multiplexing are all handled by a dedicated memory controller inside the Broadcom SoC. You don't configure it. You don't even see it. It just works.

Interrupts: Where Software Meets Hardware

Chapter 5 covers interrupts, and this is where Coffron's book becomes genuinely fascinating. The Z80 has three interrupt modes, and the book explains not just what they do, but how to wire the hardware to use them.

The book explains the electrical characteristics of the INT input, how to mask interrupts in software, and the three interrupt modes.

Mode 2 interrupts are particularly elegant. When an interrupt occurs:

The interrupting device places a byte on the data bus
The CPU reads this byte and combines it with the I register to form a 16-bit pointer
This pointer addresses a table in memory containing the actual interrupt service routine address
The CPU jumps to that address

This means you can have up to 128 different interrupt vectors, each pointing to a different handler, with the interrupting device choosing which one. The book shows how to set up the vector table in memory and how to wire multiple devices in a "daisy chain" priority scheme.

In Arduino-land, you write attachInterrupt(digitalPinToInterrupt(2), myFunction, RISING) and you're done. The hardware abstraction layer handles vector table management, priority, and dispatch. This is convenient. But you have no idea why pin 2 can trigger an interrupt and pin 4 can't (on an Uno), or what happens inside the CPU when an interrupt fires.

The Peripheral Chips: A Complete Ecosystem

The Z80 wasn't just a CPU; it was the center of a chip family. Zilog made matching peripheral chips designed to work together:

Z80 PIO: Parallel I/O controller with handshaking
Z80 CTC: Counter/Timer circuit for generating timing or counting events
Z80 SIO: Serial I/O for RS-232 communication
Z80 DMA: Direct Memory Access controller for fast block transfers

Coffron's book covers all of these, plus Intel's 8255 PIO and 8253 timer (which work with the Z80 despite being designed for the 8080).

Figure 11.12: A Z80 program for initializing the Z80-SIO in an interrupt application. Every register must be programmed in the correct sequence.

Look at that initialization code. To set up a serial port, you have to:

Write to the control port to select which internal register you want to access
Write the actual configuration byte
Repeat for each register (WR0 through WR7)
Set up the interrupt vector
Enable the receiver and transmitter separately

The SIO has eight write registers and three read registers per channel, each with specific bit-level meanings. The book includes an appendix that's just register descriptions, twelve pages of bit definitions.

Compare this to Arduino: Serial.begin(9600). One line. Done.

The Static Stimulus Tester: Debugging from First Principles

Chapter 12 is unlike anything you'll find in a modern tutorial. It describes building a "Static Stimulus Tester," a tool for debugging Z80 hardware by manually single-stepping the CPU.

The idea is simple but radical: disconnect the crystal oscillator and replace it with a push-button. Each press advances the CPU by one clock cycle. Add LED displays for the address bus, data bus, and control signals. Now you can literally watch the CPU execute, one clock tick at a time.

The book includes assembly language examples throughout, always tied to specific hardware configurations.

This is how engineers debugged hardware in 1983. No logic analyzer (those cost more than cars). No JTAG. No printf debugging. You built a tool that let you see electricity moving through your circuit, and you traced the problem by hand.

Modern development boards have LEDs. They blink to show activity. But they're diagnostic indicators, not debugging tools. If your Arduino doesn't work, you use the serial monitor to print messages. If that doesn't work, you post on Stack Overflow. The idea of building a hardware tool to watch your CPU execute instruction-by-instruction is genuinely alien to modern practice.

The Economics of Learning

It's worth considering what it actually cost to learn hardware in 1983.

The book itself was probably \$15-20. But to actually use it, you needed:

A Z80 CPU: about \$10-15 in 1983 dollars
2716 EPROMs: \$5-10 each, and you'd need several
2114 static RAM chips: \$3-5 each, eight for a basic system
74LS-series logic chips: \$0.50-2 each, dozens needed
Sockets, capacitors, resistors, wire: another \$20-30
A prototype board or wirewrap supplies: \$10-50
An EPROM programmer: \$100-300 for a basic unit
An oscilloscope: \$300-1000 for something usable
A power supply: \$30-50

A minimal setup to follow along with Coffron's book would run \$200-400 in 1983 dollars, roughly \$600-1200 in 2026 money. A serious hobbyist setup with a decent scope and programmer could easily hit \$1000-2000 (1983), or \$3000-6000 adjusted.

Compare that to an Arduino Uno: \$25. A Raspberry Pi: \$35-75. A USB cable you probably already own. Free software. Free tutorials. Free community support on forums and Discord.

The democratization isn't just about abstraction; it's about cost. In 1983, learning hardware was expensive enough that it filtered for a certain kind of person: someone with disposable income, access to electronics suppliers, and enough space for a workbench. Today, a teenager with a part-time job can afford to experiment.

This matters. The people who learned hardware in 1983 were a self-selected group. The people who learn today are everyone.

What We Gained and What We Lost

I want to be clear: I'm not arguing that the 1983 approach is better. The barriers to entry were enormous. Building a working Z80 system from Coffron's book required:

Understanding digital logic (AND, OR, NAND gates)
Reading timing diagrams
Calculating address decoding logic
Soldering dozens of chips onto a board
Having access to an EPROM programmer
Writing assembly language

This took months of study and significant equipment investment. The number of people who could do it was small.

Today, a complete beginner can have an LED blinking on an Arduino within an hour of opening the box. They can connect sensors, motors, and displays without understanding the underlying protocols. They can build genuinely useful things (home automation, art installations, scientific instruments) without ever reading a timing diagram.

This democratization is valuable. More people building more things is good.

But something is lost.

The modern approach creates a gap between "user" and "understander." You can use an Arduino without understanding it. You can use a Raspberry Pi as a Linux computer without knowing it has GPIO pins. You can run machine learning models without understanding matrix multiplication.

In 1983, there was no such gap. If you were using a microprocessor, you understood microprocessors. You had to. The abstraction layers didn't exist yet.

The Pedagogical Difference

Coffron's book teaches hardware by building it. Each chapter adds another subsystem: ROM, then RAM, then I/O ports, then interrupts, then timers, then serial communication. By the end, you understand how all the pieces connect because you connected them yourself.

Modern tutorials teach by doing. "Make this LED blink. Now make it blink faster. Now add a button. Now read a temperature sensor." The complexity is hidden, revealed only when you hit the limits of the abstraction.

Both approaches work. But they produce different kinds of understanding.

Someone who learned from Coffron's book can troubleshoot hardware. They can look at an oscilloscope trace and identify a timing problem. They can read a datasheet for a new chip and understand how to integrate it. They have a mental model of what the electricity is doing.

Someone who learned from Arduino tutorials can build things. They can iterate quickly, trying different sensors and actuators until something works. They can find libraries that solve their problems and examples they can modify. They have a mental model of what the software is doing.

Neither is wrong. But they're not the same thing.

What Would 1983 Make of 2026?

If you dropped a Raspberry Pi 5 on James Coffron's desk in 1983, what would he see?

A computer with four 64-bit CPU cores running at 2.4 GHz. Eight gigabytes of RAM. Gigabit Ethernet. Bluetooth. WiFi. USB. HDMI. A GPU capable of 4K video. Storage measured in terabytes.

And no way to understand any of it from first principles.

The SoC at the heart of a Raspberry Pi contains billions of transistors. The memory controller alone is more complex than every computer that existed in 1983 combined. The protocols (USB 3.0, HDMI 2.0, PCIe) are specified in documents thousands of pages long.

You can't build a Raspberry Pi from discrete components. You can't even build the chips that go into it without a billion-dollar fab. The abstraction isn't just convenient; it's necessary. The complexity has exceeded human ability to hold it in one head.

This is progress. But it's also a kind of loss.

Closing Thoughts

I keep Coffron's book on my shelf not because I'm going to build a Z80 system (though I might, someday), but because it represents a way of thinking about computers that's worth preserving.

The Z80 is comprehensible. One person can understand all of it: every instruction, every pin, every timing requirement. The peripheral chips are comprehensible too. A moderately determined person can read the datasheets and know exactly what the hardware is doing.

Modern computers are not comprehensible in this way. They're usable, powerful, and democratized. But they're also opaque, their complexity hidden behind layers of abstraction that most users will never penetrate.

Both things can be true. We can celebrate Arduino for making electronics accessible while acknowledging that something is different (not worse, but different) about a world where understanding and using have become separate activities.

If you want to experience what hardware education was like in 1983, find a copy of Coffron's book. It's out of print, but scanned PDFs exist. Read chapter 1. Draw the schematic on paper. Trace the signals with your finger. Try to understand not just what the circuit does, but why it works.

Then open the Arduino IDE and type digitalWrite(13, HIGH).

Both are valid. But they're not the same thing.

Resources

The Books

Z80 Applications by James W. Coffron: The 1983 SYBEX book discussed in this article. Used copies occasionally appear.
Build Your Own Z80 Computer by Steve Ciarcia: Another classic from 1981, showing how to construct a complete Z80 system from scratch.
The Best of Ciarcia's Circuit Cellar: A collection of Steve Ciarcia's legendary BYTE magazine projects.

The Modern Approach

Arduino Uno R3: The official board. Plug it in, upload a sketch, blink an LED.
ELEGOO UNO R3 Most Complete Starter Kit: 200+ components with tutorials. Everything you need to get started.
Raspberry Pi 5 (8GB): The computer that would have seemed like science fiction in 1983.

The 1983 Toolkit

Hakko FX888D Soldering Station: A quality soldering station for building hardware the old-fashioned way.
Rigol DS1054Z Oscilloscope: A 4-channel 50MHz scope. In 1983, this capability would have cost thousands.
T48 Universal Programmer: Programs EPROMs, EEPROMs, and microcontrollers. Supports the vintage 27Cxxx series with high-voltage programming.

Build Your Own Z80 Computer: A Classic Guide to DIY Microcomputing

A.C. Jokela — Mon, 19 Jan 2026 14:00:00 GMT

In 1981, Steve Ciarcia published what would become one of the most influential books in the homebrew computing movement: Build Your Own Z80 Computer: Design Guidelines and Application Notes. Published by BYTE Books, this comprehensive guide took readers on a journey from understanding basic power supply design all the way through constructing a fully functional microcomputer called ZAP (Z80 Applications Processor). More than four decades later, the book remains a fascinating window into an era when building your own computer wasn't just possible, it was expected.

The Author and His Mission

Steve Ciarcia was already well-known to readers of BYTE magazine through his popular "Ciarcia's Circuit Cellar" column, where he regularly presented do-it-yourself hardware projects. His columns had generated substantial reader interest, revealing that despite the growing availability of assembled personal computers, there remained a dedicated community of technically-minded individuals who wanted to understand what was inside their machines, and build them themselves.

Ciarcia wrote in the introduction: "Build Your Own Z80 Computer is a book written for technically minded individuals who are interested in knowing what is inside a microcomputer. It is for persons who, already possessing a basic understanding of electronics, want to build rather than purchase a computer."

This wasn't a book for beginners who had never held a soldering iron, nor was it an engineering textbook filled with impenetrable mathematics. Ciarcia positioned it squarely in the middle: practical enough for the determined hobbyist, technical enough to provide genuine understanding.

The book also reflected Ciarcia's pragmatic philosophy about engineering design. He shared an anecdote about having lunch with the designer of a major personal computer system, expecting to hear about months of careful optimization and instruction set analysis. Instead, he learned the designer had simply been given two months to produce something manufacturable, and had built the system around the microprocessor he happened to already own. "So much for textbook engineering design," Ciarcia noted wryly, while acknowledging that hobbyists doing hand-wiring needed to be more deliberate in their choices.

Why the Z80?

The choice of the Z80 microprocessor as the heart of the ZAP computer wasn't arbitrary. Ciarcia explained that when building a microcomputer from scratch, several criteria must be carefully considered: circuit complexity, cost, and software compatibility.

The Z80 (also available in 5-packs), introduced by Zilog in 1976, offered a compelling combination of features. It executed the complete instruction set of the Intel 8080A while adding significant enhancements of its own. Where the 8080A required multiple support chips (the 8224 clock driver and 8228 bus controller) to function, the Z80 integrated much of this functionality on-chip. This meant fewer components, simpler wiring, and reduced opportunities for errors, all critical considerations for hand-wired projects.

The Z80's architecture included 158 instructions (compared to the 8080A's 78), dual register sets for rapid context switching, index registers for sophisticated addressing modes, and a built-in memory refresh counter for dynamic RAM. The processor came in a standard 40-pin dual inline package, with clearly defined buses: a 16-bit address bus capable of addressing 64K bytes of memory, an 8-bit bidirectional data bus, and a comprehensive control bus.

Ciarcia also noted the practical reality of the personal computer market: "The fact that so many personal computers are in use has established de facto standardization of central processor choice." The Z80 was already powering popular systems like the TRS-80, Sinclair ZX80, and numerous CP/M machines, which meant abundant software and documentation were available.

The Z80 compared favorably to its contemporaries. While the Motorola 6800 and MOS Technology 6502 were capable processors, Ciarcia's analysis considered three key factors: circuit complexity (keeping components to a minimum to reduce wiring errors), cost (finding the sweet spot between cheap discrete logic and expensive LSI), and software compatibility (ensuring the user could benefit from existing programs and development tools). The Z80 struck an optimal balance across all three dimensions for the hand-wired builder.

Starting With the Power Supply

In a decision that reveals much about Ciarcia's pedagogical approach, the book begins not with the glamorous central processor but with the humble power supply. His reasoning was both practical and psychological: "This is a good way to test ability and provide immediate positive reinforcement from successful construction."

The ZAP computer required three DC voltage rails: +5V at 5 amps for the digital logic, and ±12V at 1 amp each for peripheral interfaces and analog circuits. Ciarcia devoted an entire chapter to power supply design, explaining transformer selection, full-wave bridge rectification, filter capacitor sizing, and three-terminal voltage regulators.

The technical depth here is remarkable. Readers learned about ripple voltage calculations, the relationship between peak voltage and steady-state voltage, and why a 25% ripple factor was recommended for the filter capacitor. The explanation of three-terminal regulators like the μA78H05 covered not just their use but their internal operation: bandgap references, error amplifiers, and thermal protection circuits.

Perhaps most valuably, Ciarcia addressed overvoltage protection. Recognizing that a regulator failure could send dangerous voltage spikes to sensitive logic circuits, he included detailed designs for SCR-based "crowbar" circuits that would short the output to ground and blow a fuse before damage could occur. This wasn't theoretical paranoia; it was the kind of practical wisdom that came from experience with real-world failures.

The chapter also tackled thermal management, a subject often glossed over in hobbyist literature. Ciarcia explained heat sink calculations, thermal resistance from junction to ambient, and the importance of forced air cooling for high-current regulators. His advice was characteristically practical: "I hate red-hot power supplies." Rather than agonize over precise thermal calculations, he recommended adequate heat sinking combined with a fan. The additional cost of robust cooling was, he noted, far less than the cost of replacing fried computer components.

Layout considerations received equal attention. Ciarcia explained how improper placement of filter capacitors could induce ripple on the output voltage, and how resistance in power distribution wiring could create different voltage levels at different points in the circuit. His solution (heavy gauge wire, single-point grounding, and dedicated bus strips) reflected the kind of hard-won practical knowledge that separates reliable designs from troublesome ones.

Understanding the Z80's Internal Architecture

Chapter 3 provides what amounts to a complete Z80 programmer's reference. Ciarcia walked through every aspect of the processor's architecture: the accumulator and flag registers, general-purpose register pairs (BC, DE, HL), special-purpose registers (program counter, stack pointer, index registers IX and IY), and the interrupt and refresh registers.

The dual register set architecture received particular attention. The Z80 contained two complete sets of general-purpose registers (main and alternate) that could be swapped with single exchange instructions. This feature enabled rapid interrupt handling and context switching, capabilities that made the Z80 attractive for real-time applications.

The instruction set documentation is exhaustive, rivaling dedicated references like Rodnay Zaks' Programming the Z80 (PDF) and Ramesh Gaonkar's The Z80 Microprocessor: Architecture, Interfacing, Programming and Design. Every instruction is described with its mnemonic, operation, affected flags, byte encoding, cycle count, and timing states. Load and exchange instructions, arithmetic and logical operations, block transfer and search commands, rotate and shift operations, bit manipulation, jumps, calls, returns, and I/O instructions. All are covered with the detail needed for hand assembly of machine code.

Ciarcia also explained the hardware interface: the meaning of every pin on the Z80's 40-pin package. Control signals like MREQ (memory request), IORQ (I/O request), RD (read), WR (write), and RFSH (refresh) are described in terms of their logical function and timing relationships. The interrupt system, with its three modes and maskable/non-maskable hierarchy, receives thorough treatment.

Building the Basic Computer

Chapter 4, "Build Your Own Computer: Start With the Basics," transitions from theory to practice. The approach is methodical: construct the minimum viable system first, verify its operation, then expand.

The basic ZAP configuration included the Z80 processor, 1K of EPROM containing the monitor program, 2K of static RAM for user programs and stack, address decoding logic, and a hexadecimal display with keyboard for interaction. Ciarcia deliberately avoided elaborate peripherals in the initial build, focusing instead on achieving a working foundation.

Memory architecture was a central concern. Ciarcia explained memory mapping, the allocation of the Z80's 64K address space among ROM, RAM, and I/O devices. For ZAP, the memory map placed the 1K monitor EPROM at addresses 0000-03FF (where the Z80 begins execution after reset), with RAM starting at address 2000 hex.

The discussion of memory devices compared available options. The 2716 EPROM (2K × 8) and 2114 static RAM (1K × 4) were recommended for their balance of capacity, availability, and ease of use. Ciarcia explained why static RAM was preferred over dynamic RAM for this application: dynamic RAM required refresh logic that, while supported by the Z80, added complexity inappropriate for a learning project.

Address decoding used simple 74LS138 three-to-eight decoders, with higher address lines selecting among memory banks and lower lines addressing within each device. This straightforward approach traded some address space efficiency for wiring simplicity.

The Peripheral Ecosystem

With the basic computer operational, Chapter 5 expanded the system with practical peripherals. The hexadecimal display and keyboard provided the most basic human interface, allowing users to examine and modify memory contents, run programs, and debug code.

The RS-232C serial interface opened connections to terminals and other equipment. Ciarcia used the COM2017 UART (Universal Asynchronous Receiver/Transmitter) to handle serial data formatting, baud rate generation, and handshaking. The interface supported standard rates from 110 to 9600 baud, making ZAP compatible with widely available terminals.

For mass storage, the book included a cassette interface design. In 1981, audio cassettes were the affordable mass storage medium for personal computers. Ciarcia's design used the Kansas City Standard (300 baud), encoding data as audio tones that could be recorded on any audio cassette recorder. While primitive by modern standards, this approach made program storage accessible without expensive disk drives.

The ZAP Monitor Software

Chapter 6 revealed the software that breathed life into the hardware. The ZAP monitor was a 1K program stored in EPROM that coordinated system operations and provided a command interface for the user.

The monitor's capabilities included: - Memory examination and modification - Program execution from specified addresses - Register display and modification - Block memory operations (move, fill, compare) - Cassette load and save operations - Breakpoint debugging support

Ciarcia presented the complete source code with detailed annotations. The listings served dual purposes: they documented the specific monitor implementation, and they provided extensive examples of Z80 assembly language programming. Readers learned about interrupt handling, I/O programming, data structure manipulation, and subroutine organization, not from abstract examples but from working, useful code.

The flow diagrams accompanying the source code illustrated program logic visually, a documentation technique that helped readers understand the relationships between code sections before diving into instruction-level details.

Programming an EPROM

Chapter 7 addressed a critical practical concern: how to get the monitor program into the EPROM in the first place. This chicken-and-egg problem (needing a programmed EPROM to have a working computer, but needing a working computer to program an EPROM) was solved through a dedicated EPROM programmer built as part of the ZAP system.

Ciarcia's EPROM programmer design could program 2708, 2716, and similar devices. The programming process required specific voltage sequences and timing, all explained in sufficient detail for readers to understand the underlying physics of EPROM operation. For those who preferred to avoid this bootstrap problem, Ciarcia noted that programmed EPROMs were available by mail order.

Connecting ZAP to the Real World

Chapter 8, "Connecting ZAP to the Real World," transformed the computer from an abstract digital machine into a practical tool for measurement and control. This chapter covered analog-to-digital and digital-to-analog conversion, enabling ZAP to interact with continuous physical quantities.

The A/D converter design used the ADC0804, an 8-bit successive approximation converter that could digitize analog signals for processing. Applications ranged from simple voltage measurement to data logging systems that could record environmental parameters over time.

On the output side, D/A conversion allowed ZAP to generate analog signals for control applications. Ciarcia included a particularly interesting application: digital speech synthesis using the SC-01 speech synthesizer chip. By sending phoneme codes from the Z80 to the speech chip, ZAP could produce intelligible spoken output, a capability that seemed almost magical in 1981.

Building a CRT Terminal

The final major project, Chapter 9, was arguably the most ambitious: a complete CRT terminal. Rather than connecting ZAP to an expensive commercial terminal, readers could build their own using the CRT5027 video timer/controller and CRT8002 video attributes controller.

The terminal design supported an 80-column by 24-row display, the standard format that would dominate computing for decades. Character generation used a ROM-based approach, with dot-matrix patterns for the full ASCII character set. The design included cursor control, scrolling, and basic display attributes.

This project integrated many skills developed earlier in the book: power supply design, digital logic, memory interfacing, and RS-232 communication. The completed terminal could serve not only ZAP but any computer with a serial port, making it a genuinely useful piece of equipment.

The terminal design included detailed worksheets for calculating timing parameters: horizontal and vertical sync widths, blanking intervals, and character clock rates. These calculations showed readers how video timing worked at a fundamental level, demystifying what seemed like magic to many hobbyists. The result was not just a working terminal but genuine understanding of raster-scan display technology.

The Appendices: Reference Material

The appendices transformed the book from a tutorial into a reference. Appendix A covered construction techniques: wire-wrapping, soldering, and printed circuit board fabrication. Appendix B provided ASCII code tables. Appendix C collected manufacturers' specification sheets for key components, eliminating the need to track down separate datasheets.

Appendix D contained the complete ZAP operating system listing, while Appendix E provided Z80 CPU technical specifications including electrical characteristics, timing diagrams, and the complete instruction set summary. The glossary and index made the book's wealth of information accessible for quick reference.

The Historical Context

To fully appreciate Build Your Own Z80 Computer, one must understand the computing landscape of 1981. The MITS Altair 8800 had kicked off the personal computer revolution just six years earlier. The Apple II was four years old. The Commodore PET and TRS-80 were both recent arrivals. Computing was still new enough that the question "Should I build or buy?" was legitimate.

Commercial computers were expensive (often thousands of dollars) while components were relatively cheap. A skilled hobbyist with time could build substantial systems for a fraction of the commercial cost. More importantly, building your own computer meant you understood it completely. When something broke, you could fix it. When you wanted to expand it, you knew how. This self-reliance was both necessity and philosophy in the early hobbyist community.

The book also appeared during the golden age of electronics magazines. BYTE, Radio Electronics, Popular Electronics, and others featured monthly construction articles. Readers expected detailed schematics, parts lists, and construction notes. Ciarcia's book was, in many ways, an extended version of the magazine articles that had made him famous, but comprehensive enough to guide a reader through an entire computer system rather than a single peripheral.

The Book's Lasting Significance

Build Your Own Z80 Computer appeared at a transitional moment in computing history. The homebrew era of the mid-1970s, when building your own computer was often the only affordable option, was giving way to an era of mass-produced personal computers. The IBM PC would debut later in 1981, accelerating the shift toward standardized, commercially manufactured systems.

Yet Ciarcia's book served a purpose beyond mere necessity. It educated a generation of engineers and enthusiasts in the fundamentals of digital design. Readers who worked through ZAP gained deep understanding of computer architecture, not just how to use a computer, but how computers actually work at the hardware level. Many professional engineers who came of age in the 1980s cite this book (or Ciarcia's magazine columns) as formative influences on their careers.

The book also demonstrated that complex systems could be understood through systematic decomposition. By building each subsystem separately, testing it in isolation, and then integrating the pieces, even ambitious projects became manageable. This approach to complexity management remains relevant today, whether one is building embedded systems, designing software architectures, or troubleshooting network infrastructure.

The pedagogical approach Ciarcia employed (theory interspersed with practice, abstract concepts grounded in concrete examples) anticipated modern project-based learning. Readers weren't just told how a regulator worked; they built one and measured its performance. They weren't just taught about memory addressing; they wired decode logic and watched the computer access specific memory locations. This hands-on approach created understanding that mere reading could never provide.

For the retrocomputing enthusiast, Build Your Own Z80 Computer offers both historical insight and practical guidance. The Z80 remains available, its instruction set unchanged from 1976. Modern implementations on FPGAs and emulators keep the architecture accessible. Projects like the RC2014 and other Z80-based single-board computers carry forward the tradition of building your own system. For those inspired to design their own Z80 system from scratch, J.S. Walker's Design a Z80 Computer provides a modern practical guide to discrete-logic computer design. And Ciarcia's thorough documentation makes it possible to understand, and even construct, systems that defined the early personal computer era.

Steve Ciarcia went on to found Circuit Cellar magazine and continued contributing to the hobbyist electronics community for decades. But Build Your Own Z80 Computer remains perhaps his most complete and influential work, a comprehensive guide that took readers from bare components to working computer, explaining every step along the way.

The book stands as a testament to an era when understanding technology meant building it yourself, one wire at a time. In an age of sealed devices and cloud computing, there's something deeply satisfying about returning to first principles, about understanding that a computer is ultimately just silicon responding to voltages, executing instructions one cycle at a time, exactly as Steve Ciarcia explained over four decades ago.

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.

Building Language Compilers for the Z80: An Anthology of Retrocomputing Languages

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

Over the past year, I have been building a collection of programming language compilers and interpreters targeting the venerable Zilog Z80 microprocessor. What started as an experiment in retrocomputing has grown into a comprehensive suite of tools spanning multiple programming paradigms: from the functional elegance of LISP to the object-oriented messaging of Smalltalk, from the structured programming of Pascal and Fortran to the low-level control of C. This anthology documents the common architectural patterns, the unique challenges of targeting an 8-bit processor, and the unexpected joys of bringing modern language implementations to 1970s hardware.

My fascination with the Z80 began in the mid-1990s when I got my first TI-85 graphing calculator. That unassuming device, marketed for algebra and calculus homework, contained a Z80 running at 6 MHz with 28KB of RAM. Discovering that I could write programs in Z80 assembly and run them on this pocket computer was revelatory. I accumulated a small library of Z80 assembly books and spent countless hours learning the instruction set, writing simple games, and understanding how software meets hardware at the most fundamental level. Three decades later, this project represents a return to that formative obsession, now armed with modern tools and a deeper understanding of language implementation.

The RetroShield Platform

The RetroShield is a family of hardware adapters that bridge vintage microprocessors to modern Arduino development boards. The product line covers a remarkable range of classic CPUs: the MOS 6502 (powering the Apple II and Commodore 64), the Motorola 6809 (used in the TRS-80 Color Computer), the Intel 8085, the SC/MP, and the Zilog Z80. Each variant allows the original processor to execute real machine code while the Arduino emulates memory, peripherals, and I/O.

For this project, I focused exclusively on the RetroShield Z80. The Z80's rich instruction set, hardware BCD support via the DAA instruction, and historical significance as the CPU behind CP/M made it an ideal target for language implementation experiments. The RetroShield Z80 connects the actual Z80 chip to an Arduino Mega (or Teensy adapter for projects requiring more RAM), which emulates the memory and peripheral chips. This arrangement provides the authenticity of running on actual Z80 silicon while offering the convenience of modern development workflows.

The standard memory map provides 8KB of ROM at addresses 0x0000-0x1FFF and 6KB of RAM at 0x2000-0x37FF, though the Teensy adapter expands this significantly to 256KB. Serial I/O is handled through an emulated MC6850 ACIA chip at ports 0x80 and 0x81, providing the familiar RS-232 interface that connects these vintage programs to modern terminals.

It needs to be mentioned that if you do have a Z80 RetroShield and you want to run the binaries produced by the compilers collections on actual hardware, you will need a couple things: 1) bin2c, this is a program that will take a Z80 binary and turn it into a PROGMEM statement that you can put into an Arduino sketch. 2) Look at this sketch - there is code in there for emulating the MC6850 ACIA.

Common Compiler Architecture: Lexer, Parser, AST, Codegen

Every compiler in this collection follows a similar multi-stage architecture, a pattern that has proven itself across decades of compiler construction. Understanding this common structure reveals how the same fundamental approach can target vastly different source languages while producing efficient Z80 machine code.

The Lexer: Breaking Text into Tokens

The lexer (or tokenizer) is the first stage of compilation, responsible for transforming raw source code into a stream of tokens. Each language has its own lexical grammar: LISP recognizes parentheses and symbols, C identifies keywords and operators, Smalltalk distinguishes between message selectors and literals. Despite these differences, every lexer performs the same fundamental task of categorizing input characters into meaningful units.

In our Rust implementations, the lexer typically maintains a position in the source string and provides a next_token() method that advances through the input. This produces tokens like Token::Integer(42), Token::Plus, or Token::Identifier("factorial"). The lexer handles the tedious work of skipping whitespace, recognizing multi-character operators, and converting digit sequences into numbers.

The Parser: Building the Abstract Syntax Tree

The parser consumes the token stream and constructs an Abstract Syntax Tree (AST) that represents the hierarchical structure of the program. Most of our compilers use recursive descent parsing, a technique where each grammar rule becomes a function that may call other rule functions. This approach is intuitive, produces readable code, and handles the grammars of most programming languages effectively.

For example, parsing an arithmetic expression like 3 + 4 * 5 requires understanding operator precedence. The parser might have functions like parse_expression(), parse_term(), and parse_factor(), each handling operators at different precedence levels. The result is an AST where the multiplication is grouped as a subtree, correctly representing that it should be evaluated before the addition.

Code Generation: Emitting Z80 Machine Code

The code generator walks the AST and emits Z80 machine code. This is where the rubber meets the road: abstract operations like "add two numbers" become concrete sequences of Z80 instructions like LD A,(HL), ADD A,E, and LD (DE),A.

Most of our compilers generate code directly into a byte buffer, manually encoding each instruction's opcode and operands. This approach, while requiring intimate knowledge of the Z80 instruction set, gives us precise control over the generated code and avoids the complexity of an intermediate representation or separate assembler pass.

The DAA Instruction and BCD Arithmetic

One of the most fascinating aspects of Z80 programming is the DAA (Decimal Adjust Accumulator) instruction, opcode 0x27. This single instruction makes the Z80 surprisingly capable at decimal arithmetic, which proves essential for implementing numeric types on an 8-bit processor.

What is BCD?

Binary Coded Decimal (BCD) is a numeric representation where each decimal digit is stored in 4 bits (a nibble). Rather than storing the number 42 as binary 00101010 (its true binary representation), BCD stores it as 0100 0010, with the first nibble representing 4 and the second representing 2. This "packed BCD" format stores two decimal digits per byte.

While BCD is less space-efficient than pure binary (you can only represent 0-99 in a byte rather than 0-255), it has a crucial advantage: decimal arithmetic produces exact decimal results without rounding errors. This is why BCD was the standard for financial calculations on mainframes and why pocket calculators (including the famous TI series) used BCD internally.

How DAA Works

When you perform binary addition on two BCD digits, the result may not be valid BCD. Adding 0x09 and 0x01 gives 0x0A, but 0x0A is not a valid BCD digit. The DAA instruction corrects this: it examines the result and the half-carry flag (which indicates a carry from bit 3 to bit 4, i.e., from the low nibble to the high nibble) and adds 0x06 to any nibble that exceeds 9. After DAA, that 0x0A becomes 0x10, correctly representing decimal 10 in BCD.

This process works for both addition (after ADD or ADC instructions) and subtraction (after SUB or SBC instructions, where DAA subtracts 0x06 instead of adding it). The Z80 remembers whether the previous operation was addition or subtraction through its N flag.

BCD in Our Compilers

Several of our compilers use 4-byte packed BCD integers, supporting numbers up to 99,999,999 (8 decimal digits). The addition routine loads bytes from both operands starting from the least significant byte, adds them with ADC (add with carry) to propagate carries between bytes, applies DAA to correct each byte, and stores the result. The entire operation takes perhaps 20 bytes of code but provides exact decimal arithmetic on an 8-bit processor.

Here is a simplified version of our BCD addition loop:

bcd_add: LD B, 4 ; 4 bytes to process OR A ; Clear carry flag bcd_add_loop: LD A, (DE) ; Load byte from first operand ADC A, (HL) ; Add byte from second operand with carry DAA ; Decimal adjust LD (DE), A ; Store result DEC HL ; Move to next byte DEC DE DJNZ bcd_add_loop RET

This pattern appears in kz80_c, kz80_fortran, kz80_smalltalk, and kz80_lisp, demonstrating how a hardware feature designed in 1976 still provides practical benefits for language implementation.

The Evolution: From Assembly to C to Rust

The journey of implementing these compilers taught us valuable lessons about choosing the right tool for the job, and our approach evolved significantly over time.

First Attempt: Pascal in Z80 Assembly

Our first language implementation was kz80_pascal, a Pascal interpreter written entirely in Z80 assembly language. This approach seemed natural: if you are targeting the Z80, why not write directly in its native language?

The reality proved challenging. Z80 assembly, while powerful, is unforgiving. Building a recursive descent parser in assembly requires manually managing the call stack, carefully preserving registers across function calls, and debugging through hex dumps of memory. The resulting interpreter works and provides an interactive REPL for Pascal expressions, but extending it requires significant effort. Every new feature means more assembly, more potential for subtle bugs, and more time spent on implementation details rather than language design.

Second Attempt: Fortran 77 in C with SDCC

For kz80_fortran, we tried a different approach: writing the interpreter in C and cross-compiling with SDCC (Small Device C Compiler). This was dramatically more productive. C provided structured control flow, automatic stack management, and the ability to organize code into manageable modules.

The result is a comprehensive Fortran 77 subset with floating-point arithmetic (via BCD), subroutines and functions, arrays, and block IF statements. The C source compiles to approximately 19KB of Z80 code, fitting comfortably in ROM with room for program storage in RAM.

However, this approach has limitations. SDCC produces functional but not always optimal code, and debugging requires understanding both the C source and the generated assembly. The interpreter also requires the Teensy adapter with 256KB RAM, as the Arduino Mega's 4KB is insufficient for the runtime data structures.

The Rust Workbench: Our Final Form

Our breakthrough came with the realization that we did not need the compiler itself to run on the Z80, only the generated code. This insight led to what we call the "Rust workbench" approach: write the compiler in Rust, running on a modern development machine, and have it emit Z80 binary images.

This architecture provides enormous advantages:

Modern tooling: Cargo manages dependencies and builds, rustc catches bugs at compile time, and we have access to the entire Rust ecosystem for testing and development.

Fast iteration: Compiling a Rust program takes seconds; testing the generated Z80 code in our emulator takes milliseconds. Compare this to the multi-minute flash cycles required when the compiler runs on the target.

Comprehensive testing: Each compiler includes both Rust unit tests (testing the lexer, parser, and code generator individually) and integration tests that compile source programs and verify their output in the emulator.

Zero-dependency output: Despite being written in Rust, the generated Z80 binaries have no runtime dependencies. They are pure machine code that runs directly on the hardware.

This approach now powers kz80_lisp, kz80_c, kz80_lua, kz80_smalltalk, kz80_chip8, and retrolang. Each is a standalone Rust binary that reads source code and produces a 32KB ROM image.

The Z80 Emulator

None of this would be practical without a way to test generated code quickly. Our RetroShield Z80 Emulator provides exactly this: a cycle-accurate Z80 emulation with the same memory map and I/O ports as the real hardware.

The emulator comes in two versions: a simple passthrough mode (retroshield) that connects stdin/stdout directly to the emulated serial port, and a full TUI debugger (retroshield_nc) with register displays, disassembly views, memory inspection, and single-step execution. The passthrough mode enables scripted testing, piping test inputs through the emulator and comparing outputs against expected results. The TUI debugger proves invaluable when tracking down code generation bugs.

The emulator uses the superzazu/z80 library for CPU emulation, which provides accurate flag behavior and correct cycle counts. Combined with our MC6850 ACIA emulation, it provides a faithful recreation of the RetroShield environment without requiring physical hardware.

Self-Hosting Compilers: LISP and C

Two of our compilers achieve something remarkable: they can compile themselves and run on the target hardware. This property, called "self-hosting," is a significant milestone in compiler development.

What Does Self-Hosting Mean?

A self-hosting compiler is one written in the language it compiles. The classic example is the C compiler: most C compilers are themselves written in C. But this creates a chicken-and-egg problem: how do you compile a C compiler if you need a C compiler to compile it?

The solution is bootstrapping. You start with a minimal compiler written in some other language (or in machine code), use it to compile a slightly better compiler written in the target language, and iterate until you have a full-featured compiler that can compile its own source code. Once bootstrapped, the compiler becomes self-sustaining: future versions compile themselves.

kz80_lisp: A Self-Hosted LISP Compiler

kz80_lisp (crates.io) includes a LISP-to-Z80 compiler written in LISP itself. The compiler.lisp file defines functions that traverse LISP expressions and emit Z80 machine code bytes directly into memory. When you call (COMPILE '(+ 1 2)), it generates the actual Z80 instructions to load 1 and 2 and add them.

The self-hosted compiler supports arithmetic expressions, nested function calls, and can generate code that interfaces with the runtime's I/O primitives. While not a full replacement for the Rust-based code generator, it demonstrates that LISP is expressive enough to describe its own compilation to machine code.

kz80_c: A Self-Hosted C Compiler

kz80_c (crates.io) goes further: its self/cc.c file is a complete C compiler written in the C subset it compiles. This compiler reads C source from stdin and outputs Z80 binary to stdout, making it usable in shell pipelines:

# printf 'int main() { puts("Hello!"); return 0; }\x00' | \ retroshield self/cc.bin > hello.bin # retroshield hello.bin Hello!

The self-hosted C compiler supports all arithmetic operators, pointers, arrays, global variables, control flow statements, and recursive functions. Its main limitation is memory: the compiler source is approximately 66KB, exceeding the 8KB input buffer available on the Z80. This is a fundamental hardware constraint, not a compiler bug. In theory, a "stage 0" minimal compiler could bootstrap larger compilers.

Why Self-Hosting Matters

Self-hosting is more than a technical achievement; it validates the language implementation. If the compiler can compile itself correctly, it demonstrates that the language is expressive enough for real programs and that the code generator produces working code under complex conditions. For our Z80 compilers, self-hosting also connects us to the history of computing: the original Small-C compiler by Ron Cain in 1980 was similarly self-hosted on Z80/CP-M systems.

The Language Implementations

kz80_lisp

A minimal LISP interpreter and compiler featuring the full suite of list operations (CAR, CDR, CONS), special forms (QUOTE, IF, COND, LAMBDA, DEFINE), and recursive function support. The implementation includes a pure-LISP floating-point library and the self-hosted compiler mentioned above.

kz80_lisp v0.1 > (+ 21 21) 42 > (DEFINE (SQUARE X) (* X X)) SQUARE > (SQUARE 7) 49

GitHub: https://github.com/ajokela/kz80_lisp
Crates.io: https://crates.io/crates/kz80_lisp

kz80_c

A C compiler supporting char (8-bit), int (16-bit), float (BCD), pointers, arrays, structs, and a preprocessor with #define and #include. The runtime library provides serial I/O and comprehensive BCD arithmetic functions. The self-hosted variant can compile and run C programs entirely on the Z80.

# cat fibonacci.c int fib(int n) { if (n <= 1) return n; return fib(n-1) + fib(n-2); } int main() { puts("Fibonacci:"); for (int i = 0; i < 10; i = i + 1) print_num(fib(i)); return 0; } # kz80_c fibonacci.c -o fib.bin # retroshield -l fib.bin Fibonacci: 0 1 1 2 3 5 8 13 21 34

GitHub: https://github.com/ajokela/kz80_c
Crates.io: https://crates.io/crates/kz80_c

kz80_smalltalk

A Smalltalk subset compiler implementing the language's distinctive message-passing syntax with left-to-right operator evaluation. Expressions like 1 + 2 * 3 evaluate to 9 (not 7), matching Smalltalk's uniform treatment of binary messages. All arithmetic uses BCD with the DAA instruction.

# echo "6 * 7" | kz80_smalltalk /dev/stdin -o answer.bin # retroshield -l answer.bin Tiny Smalltalk on Z80 42

GitHub: https://github.com/ajokela/kz80_smalltalk
Crates.io: https://crates.io/crates/kz80_smalltalk

kz80_lua

A Lua compiler producing standalone ROM images with an embedded virtual machine. Supports tables (Lua's associative arrays), first-class functions, closures, and familiar control structures. The generated VM interprets Lua bytecode, with frequently-used operations implemented in native Z80 code for performance.

# cat factorial.lua function factorial(n) if n <= 1 then return 1 end return n * factorial(n - 1) end print("5! =", factorial(5)) # kz80_lua factorial.lua -o fact.bin # retroshield -l fact.bin Tiny Lua v0.1 5! = 120

GitHub: https://github.com/ajokela/kz80_lua
Crates.io: https://crates.io/crates/kz80_lua

kz80_fortran

A Fortran 77 interpreter with free-format input, REAL numbers via BCD floating point, block IF/THEN/ELSE/ENDIF, DO loops, subroutines, and functions. Requires the Teensy adapter for sufficient RAM. Written in C and cross-compiled with SDCC.

FORTRAN-77 Interpreter v0.3 RetroShield Z80 Ready. > INTEGER X, Y > X = 7 > Y = X * 6 > WRITE(*,*) 'Answer:', Y Answer: 42

GitHub: https://github.com/ajokela/kz80_fortran

kz80_pascal

A Pascal interpreter implemented in pure Z80 assembly. Provides an interactive REPL for expression evaluation with integer arithmetic, boolean operations, and comparison operators. A testament to the challenges of assembly language programming.

Tiny Pascal v0.1 For RetroShield Z80 (Expression Eval Mode) > 2 + 3 * 4 = 00014 > TRUE AND (5 > 3) = TRUE

GitHub: https://github.com/ajokela/kz80_pascal

retrolang

A custom systems programming language with Pascal/C-like syntax, featuring 16-bit integers, 8-bit bytes, pointers, arrays, inline assembly, and full function support with recursion. Compiles to readable Z80 assembly before assembling to binary.

# cat squares.rl proc main() var i: int; print("Squares: "); for i := 1 to 5 do printi(i * i); printc(32); end; println(); end; # retrolang squares.rl --binary -o squares.bin # retroshield -l squares.bin Squares: 1 4 9 16 25

GitHub: https://github.com/ajokela/retrolang
Crates.io: https://crates.io/crates/retrolang

kz80_chip8

A static recompiler that transforms CHIP-8 programs into native Z80 code. Rather than interpreting CHIP-8 bytecode at runtime, the compiler analyzes each instruction and generates equivalent Z80 sequences. Classic games like Space Invaders and Tetris run directly on the hardware.

# kz80_chip8 -d ibm_logo.ch8 200: 00E0 CLS 202: A22A LD I, 22A 204: 600C LD V0, 0C 206: 6108 LD V1, 08 208: D01F DRW V0, V1, 15 20A: 7009 ADD V0, 09 20C: A239 LD I, 239 20E: D01F DRW V0, V1, 15 ... # kz80_chip8 ibm_logo.ch8 -o ibm.bin # retroshield -l ibm.bin CHIP-8 on Z80 [displays IBM logo]

GitHub: https://github.com/ajokela/kz80_chip8
Crates.io: https://crates.io/crates/kz80_chip8

Why Rust for Compiler Development?

The choice of Rust for our compiler workbench was not accidental. Several features make it exceptionally well-suited for this work.

Strong typing catches bugs early. When you're generating machine code, off-by-one errors or type mismatches can produce binaries that crash or compute wrong results. Rust's type system prevents many such errors at compile time.

Pattern matching excels at AST manipulation. Walking a syntax tree involves matching on node types and recursively processing children. Rust's match expressions with destructuring make this natural and exhaustive (the compiler warns if you forget a case).

Zero-cost abstractions. We can use high-level constructs like iterators, enums with data, and trait objects without runtime overhead. The generated compiler code is as efficient as hand-written C.

Excellent tooling. Cargo's test framework made it easy to build comprehensive test suites. Each compiler has dozens to hundreds of tests that run in seconds, providing confidence when making changes.

Memory safety without garbage collection. This matters less for the compilers themselves (which are desktop tools) but more for our mental model: thinking about ownership and lifetimes transfers naturally to thinking about Z80 register allocation and stack management.

Conclusion

Building these compilers has been a journey through computing history, from the Z80's 1976 architecture to modern Rust tooling, from the fundamentals of lexing and parsing to the intricacies of self-hosting. The BCD arithmetic that seemed like a curiosity became a practical necessity; the emulator that started as a debugging aid became essential infrastructure; the Rust workbench that felt like an optimization became the key to productivity.

The Z80 remains a remarkable teaching platform. Its simple instruction set is comprehensible in an afternoon, yet implementing real languages for it requires genuine compiler engineering. Every language in this collection forced us to think carefully about representation, evaluation, and code generation in ways that higher-level targets often obscure.

All of these projects are open source under BSD-3-Clause licenses. The compilers are available on both GitHub and crates.io, ready to install with cargo install. Whether you are interested in retrocomputing, compiler construction, or just curious how programming languages work at the metal level, I hope these tools and their source code prove useful.

The Z80 may be nearly 50 years old, but it still has lessons to teach.