TinyComputers.io

Redesigning a PCB with Claude Code and Open-Source EDA Tools (Part 1)

A.C. Jokela — Fri, 13 Mar 2026 16:00:00 GMT

In January, I spent $468 on Fiverr to have a professional design an Arduino Giga R1 shield with level shifters. It was a good design. Nine TXB0108PW bidirectional level translators, 72 channels of 3.3V-to-5V shifting, a clean two-layer board ready for fabrication. And then I started testing it with the RetroShield Z80, and the auto-sensing level shifters fell apart.

The TXB0108 is a clever chip. It detects signal direction automatically, so you don't need to tell it whether a pin is input or output. For most applications, that's a feature. For a Z80 bus interface, it's a fatal flaw. During bus cycles, the Z80 tri-states its address and data lines. The outputs go high-impedance. They're not driving high or low, they're floating. The TXB0108 can't determine drive direction from a floating signal. It guesses wrong, or it doesn't drive at all, and the Arduino on the other side sees garbage. The board was blind to half of what the Z80 was doing.

The fix was clear: replace the TXB0108s with SN74LVC8T245PW driven level shifters. The SN74LVC8T245 has an explicit DIR pin: you tell it which direction to translate, and it does exactly that, regardless of whether the signals are being actively driven. No guessing, no ambiguity, deterministic behavior during tri-state periods. The trade-off is that you need a direction control signal for each shifter IC, but that's a small price for reliability.

What wasn't clear was how to execute the redesign. I could go back to Fiverr for another $400-500. I could spend weeks learning KiCad properly. Or I could try something that had worked surprisingly well on a previous project: use AI and open-source command-line EDA tools to design the board from a terminal, without ever opening a graphical PCB editor.

This is part one of a two-part series. This piece covers the design and toolchain: how I used Claude Code, the gEDA ecosystem, pcb-rnd, and Freerouting to go from a failed design to production-ready Gerber files. Part two will cover the physical boards, assembly, and testing against the Z80.

The Toolchain Problem

The original Fiverr design was done in KiCad 9.0. My first instinct was to modify it directly: swap the TXB0108 footprints for SN74LVC8T245, update the pin mappings, add the DIR control header, and re-route. But there was a problem. My preferred command-line PCB tool, pcb-rnd, is version 3.1.4 on Ubuntu. KiCad 9.0 uses a file format version (20241229) that pcb-rnd's io_kicad plugin doesn't support. When I tried to open the KiCad PCB:

unexpected layout version number (perhaps too new)

Hard stop. No conversion path exists from KiCad 9.0 to pcb-rnd. The formats aren't just different versions. KiCad's S-expression format and pcb-rnd's text-based format are fundamentally different syntaxes.

I could have started KiCad and used its GUI. But I'd already proven to myself with the dual Z80 RetroShield project that text-based, AI-assisted PCB workflows are not only possible but sometimes preferable. The gEDA/pcb-rnd file format is human-readable. AI can parse it, reason about it, and generate it. A Python script can manipulate it. You can diff two boards and see exactly what changed. None of that is true for a graphical-only workflow.

So the plan became: extract everything useful from the KiCad source files, then rebuild the board from scratch in pcb-rnd's native format using Python. Sound insane? It kind of is. But it worked.

Extracting the DNA

Even though pcb-rnd couldn't read the KiCad files directly, the KiCad files contained all the design intelligence I needed. Component positions, net assignments, pin mappings, board dimensions. It was all there, just in a format I couldn't import.

KiCad's CLI tools (kicad-cli) could export what I needed:

# Component positions (X, Y, rotation for each part)
kicad-cli pcb export pos AlexJ_bz_ArduinoGigaShield.kicad_pcb -o giga_pos.csv

# Netlist connectivity
kicad-cli pcb export ipc2581 AlexJ_bz_ArduinoGigaShield.kicad_pcb -o giga_netlist.d356

The schematic file (AlexJ_bz_ArduinoGigaShield.kicad_sch) was an S-expression text file I could parse to extract the signal mappings: which Giga pin connects to which 5V header pin through which level shifter channel. This was the most critical piece: getting the net assignments wrong would mean the board physically connects but logically doesn't work.

This is where Claude Code earned its keep. I described the KiCad schematic structure and asked it to help me parse out the signal mappings. The KiCad schematic uses hierarchical sheets with positional net connections, which isn't the simplest format to work with manually, but straightforward for an AI that can read S-expressions and track net names across sheets. Within an hour, I had a complete mapping of all 72 signal channels across the 9 shifter ICs.

Generating the Board with Python

With positions and nets extracted, I wrote build_giga_shield.py, a single Python script that generates the entire pcb-rnd board from scratch. No GUI involved. Every component footprint, every pin, every net connection is defined programmatically.

The script is structured around four generator functions:

tssop24_element() generates the SN74LVC8T245PW footprint. TSSOP-24 is a precise geometry: 0.65mm pin pitch, 6.4mm pad-to-pad span, 24 pins. The function calculates pad positions mathematically: 12 pins on the left, 12 on the right, with pin 1 marked as square per convention. Getting the pin numbering right was critical. The SN74LVC8T245's datasheet shows pins 1-12 on the left (DIR, A1-A4, GND, A5-A8, OE#, GND) and pins 13-24 on the right counting bottom-to-top (B8-B5, VCCB, B4-B1, VCCA, VCCA, VCCB).

pin_header_element() handles through-hole pin headers with rotation support. The Arduino Giga R1 has an unusual form factor: the long pin headers run along the board edges horizontally, not vertically. In the original KiCad design, these were placed with 90-degree or -90-degree rotation. Without matching that rotation, a 26-pin header at y=84mm would extend 63.5mm downward to y=148mm, well past the 90mm board edge. The rotation transform was simple once identified:

def rotate(px, py):
    if rot == 90:
        return (py, -px)
    elif rot == -90:
        return (-py, px)
    return (px, py)

smd_0603_element() creates the 0603 footprint shared by all 27 decoupling capacitors and 9 pull-down resistors. Small SMD parts, simple geometry.

mounting_hole_element() places the four 3.2mm mounting holes that align with the Arduino Giga's standoff positions.

The coordinate system was the trickiest part. KiCad uses an arbitrary origin; in this design, x=106mm, y=30.5mm. pcb-rnd uses (0,0). Every KiCad coordinate had to be translated:

KX, KY = 106.0, 30.5
def kpos(kx, ky):
    return (mm(kx - KX), mm(ky - KY))

The build_pcb() function ties everything together: place components, assign nets, build the symbol table, generate the layer stack, and write out a valid pcb-rnd .pcb file. Running the script produces a complete, unrouted board: components placed, netlist defined, silkscreen text positioned, board outline drawn. Ready for routing.

$ python3 build_giga_shield.py
Generated giga_shield.pcb
Board: 155mm x 90mm
9x SN74LVC8T245PW (TSSOP-24) level shifters
DIR control via J11 (1x10 header)

The Format Wars

Getting pcb-rnd to actually accept the generated file was its own adventure. pcb-rnd's parser is strict about things that look optional in the documentation, and its error messages are sometimes misleading. An error in an Element definition might be reported as a syntax error in the Layer section fifty lines later.

Three format issues bit me hardest:

The "smd" flag. I initially generated elements with Element["smd" "TSSOP24" "U1" ...], which seemed logical for surface-mount parts. pcb-rnd rejected it with "Unknown flag: smd ignored," which cascaded into a complete parse failure. The fix: use an empty string Element["" "TSSOP24" "U1" ...]. The SMD-ness is implicit from using Pad[] entries instead of Pin[] entries.

Bare zeros. pcb-rnd is inconsistent about whether 0 and 0nm are interchangeable. In some contexts, bare 0 works fine. In others, it causes a silent parse error that manifests as a syntax error dozens of lines later. The defensive fix: always use 0nm, never bare 0, everywhere.

Missing flags on Layer lines. The Line[] entry inside Layer blocks needs 7 fields, not 6. The seventh is a flags string like "clearline". My generator omitted it, producing Line[x1 y1 x2 y2 thickness clearance]. The parser's error message: syntax error, unexpected ']', expecting INTEGER or STRING, reported at the layer definition, not at the malformed line.

I found these bugs using a binary search approach, truncating the file with head -N and testing each truncation point until I isolated which section introduced the failure. It's crude but effective when error reporting is unhelpful. Claude Code helped enormously here. I'd paste the error and the surrounding file content, and it would spot the structural issue faster than I could.

The pcb-rnd Ecosystem

For anyone unfamiliar with the tools involved, a brief orientation.

gEDA (GNU Electronic Design Automation) is a suite of open-source tools for electronic design. The original project dates to the late 1990s and includes gschem (schematic capture), pcb (PCB layout), and various utilities. The file formats are text-based and human-readable, a deliberate design choice that makes them scriptable and version-control-friendly. The original pcb program is now deprecated.

pcb-rnd is the actively maintained successor to gEDA's pcb program. It reads and writes the same text-based PCB format, but adds modern features: more export formats, better plugin support, and critically for this project, command-line export of Gerber files, PNG renderings, and Specctra DSN files. It runs on Linux (packaged for Ubuntu) but not macOS, which is why I ran it over SSH on a remote machine throughout this project.

Freerouting is a Java-based autorouter that speaks the Specctra DSN/SES interchange format. You feed it a board definition with components and nets but no traces, and it computes the copper routing, finding paths for every net while respecting design rules for trace width, clearance, and via placement. It's the open-source standard for PCB autorouting and has been used in production for decades.

The workflow chains these tools together:

build_giga_shield.py → giga_shield.pcb
                            ↓
                    [pcb-rnd DSN export]
                            ↓
                     giga_shield.dsn
                            ↓
                   [Freerouting autorouter]
                            ↓
                     giga_shield.ses
                            ↓
              [pcb-rnd SES import + Gerber export]
                            ↓
                    Production files

Every step is a command-line operation. Every intermediate file is text. Every transformation is reproducible. Change a component position in the Python script, re-run the pipeline, get new Gerber files. This is the power of text-based EDA: the entire design is version-controlled, diffable, and automatable.

Autorouting: The Machine Does the Tedious Part

With the board generated and validated in pcb-rnd, the next step was routing: connecting all 308 nets with actual copper traces across a two-layer board. This is where Freerouting comes in.

The pipeline starts with exporting the unrouted board to Specctra DSN format. pcb-rnd handles this in batch mode on the remote Linux machine:

pcb-rnd -x dsn giga_shield.pcb

The DSN file contains the board geometry, component placements, pad definitions, and netlist, everything the autorouter needs to compute a routing solution. One subtlety I learned the hard way: the DSN's (structure) section needs explicit (rule) and (via) definitions. pcb-rnd's DSN exporter puts the design rules inside the net class section, but Freerouting also expects them in the structure section. Without them, the router can see the nets but can't figure out what trace widths and via sizes are legal, and it silently fails to route most connections. A two-line addition fixed this:

(via pstk_1)
(rule
  (width 0.254)
  (clearance 0.254)
)

Freerouting itself is a Java application with both GUI and command-line modes. On my machine, I'm running a custom build from source. The current main branch had a few issues I had to fix (a missing static on the main method, a null pointer on maxThreads in the GUI initialization, and a Gradle build compatibility issue). The v1.9 codepath was more reliable for headless routing:

java -jar freerouting-1.9.0-executable.jar \
  -de giga_shield.dsn \
  -do giga_shield.ses

The autorouter loaded the 308-net board, ran through its passes, and produced a Specctra Session file containing 2911 wire segments and 172 vias. Every net connected. Every design rule satisfied. The routing took about 10 seconds for initial placement followed by optimization passes.

Importing the routes back into pcb-rnd was the final step. pcb-rnd can import SES files through its batch mode:

pcb-rnd --gui hid_batch giga_shield.pcb <<EOF
ImportSes(giga_shield.ses)
SaveTo(LayoutAs, giga_shield_routed.pcb)
EOF

The result: a fully routed PCB with 2911 traces and 172 vias, ready for Gerber export.

Running pcb-rnd Over SSH

One of the more unusual aspects of this project is that all pcb-rnd operations happened on a remote Ubuntu 24.04 machine accessed over SSH. pcb-rnd isn't available on macOS via Homebrew (I tried; there's a deprecated pcb package but no pcb-rnd), and building from source on macOS looked like a rabbit hole I didn't want to enter.

The remote workflow was straightforward:

# Upload the PCB
scp giga_shield.pcb alex@10.1.1.27:/tmp/

# Export DSN for routing
ssh alex@10.1.1.27 "pcb-rnd -x dsn /tmp/giga_shield.pcb"

# Import SES and export gerbers
ssh alex@10.1.1.27 'pcb-rnd --gui hid_batch /tmp/giga_shield.pcb <<EOF
ImportSes(/tmp/giga_shield.ses)
SaveTo(LayoutAs, /tmp/giga_shield_routed.pcb)
EOF'

# Export production files
ssh alex@10.1.1.27 "pcb-rnd -x gerber --gerberfile /tmp/giga_shield /tmp/giga_shield_routed.pcb"
ssh alex@10.1.1.27 "pcb-rnd -x png --dpi 600 --photo-mode --outfile /tmp/top.png /tmp/giga_shield_routed.pcb"

# Download results
scp alex@10.1.1.27:/tmp/giga_shield.*.gbr .
scp alex@10.1.1.27:/tmp/top.png giga_shield_top.png

It's more keystrokes than clicking Export in a GUI. But it's scriptable, repeatable, and fits into the same terminal where Claude Code is running. When I needed to iterate (move a component, re-route, re-export) I could do it in a single pipeline without switching contexts.

Claude Code as a Hardware Design Partner

I should be explicit about what Claude Code did and didn't do in this project, because the AI angle is the part people will either find most interesting or most suspicious.

What Claude Code did:

Parsed the KiCad schematic to extract the 72-channel signal mapping across 9 level shifter ICs
Wrote the initial build_giga_shield.py generator script, including all four footprint generators and the net assignment logic
Debugged pcb-rnd format issues by analyzing error messages and file structure
Managed the remote SSH workflow: uploading files, running pcb-rnd commands, downloading results
Fixed bugs in the Freerouting build (the static main issue, the null maxThreads, the Gradle fileMode API change)
Handled iterative changes: "move tinycomputers.io down by a millimeter" became an edit to the Python script, a regeneration, a re-import, and a re-export, all executed as a single flow

What Claude Code didn't do:

Make architectural decisions. The choice to use SN74LVC8T245 over TXB0108, the DIR control header design, the decision to use pull-down resistors defaulting to A-to-B direction. Those were my decisions based on understanding the Z80 bus protocol; it is also on me for selecting the TXB0108 in the first place
Verify electrical correctness. I checked the SN74LVC8T245 datasheet pin mapping myself. I verified that OE# tied to GND means always-enabled. I confirmed the 10K pull-down value was appropriate for the DIR pin
Replace domain knowledge. I knew why the TXB0108 failed during tri-state periods because I understand Z80 bus cycles. Claude Code could have looked up the TXB0108 datasheet, but it couldn't have diagnosed the real-world failure mode from first principles

The pattern that emerged was: I made design decisions, Claude Code implemented them. I said "the DIR pins need pull-down resistors to default A-to-B direction," Claude Code generated the pcb-rnd Element entries with the correct footprint, position, and net assignments. I said "export gerbers at 600 DPI with photo mode," Claude Code ran the right pcb-rnd command on the remote machine.

This is the same division of labor I described in the dual Z80 post: I bring the domain knowledge, the AI handles the format translation. The text-based nature of gEDA files makes this work. If the design lived in a binary format or required mouse interactions, the AI would have been far less useful.

The New Design

Here's what the redesigned board looks like:

Parameter	v0.1 (Fiverr/TXB0108)	v0.2 (Claude Code/SN74LVC8T245)
Level Shifter IC	TXB0108PW (TSSOP-20)	SN74LVC8T245PW (TSSOP-24)
Direction Control	Auto-sensing	Explicit DIR pin
Channels	72	72
Shifter ICs	9	9
Decoupling Caps	27	27
Pull-down Resistors	9 (OE)	9 (DIR)
DIR Control Header	None	J11 (1x10)
Board Dimensions	155mm x 90mm	155mm x 90mm
Layers	2	2
Design Tool	KiCad 9.0 (GUI)	Python + pcb-rnd (CLI)
Design Cost	$468.63	$0 (open source tools)
Design Time	~10 days (outsourced)	~2 days (with AI)

The J11 header is the key addition. It's a 1x10 pin header with 9 direction control pins (one per shifter IC) and a ground reference. Each DIR pin has a 10K pull-down resistor that defaults the direction to A-to-B (3.3V to 5V). To reverse a shifter's direction (for example, when the Arduino needs to read from the Z80's data bus) you drive the corresponding J11 pin high. The Arduino firmware manages this dynamically during bus cycles.

The board carries "tinycomputers.io" and "v0.2" on the silkscreen, placed near the bottom edge. Version tracking on the physical board, a lesson learned from the Fiverr experience, where I had to pay $57 for a revision just to add version text to the silkscreen.

Generating Production Files

With the routed board in hand, the final step was generating files suitable for manufacturing. pcb-rnd handles this with command-line exporters:

# Gerber files (9 layers: top/bottom copper, mask, silk, paste, outline, drill, fab)
pcb-rnd -x gerber --gerberfile giga_shield giga_shield_routed.pcb

# Photo-realistic renderings
pcb-rnd -x png --dpi 600 --photo-mode --outfile top.png giga_shield_routed.pcb
pcb-rnd -x png --dpi 600 --photo-mode --photo-flip-x --outfile bottom.png giga_shield_routed.pcb

The Gerber output includes everything a fab house needs: top and bottom copper, solder mask, silkscreen, paste stencil, board outline, and drill locations. The photo-realistic PNG renderings use pcb-rnd's built-in renderer: green solder mask, gold-plated pads, white silkscreen text. They're useful for documentation and for sanity-checking the layout before sending it to fabrication.

The BOM and centroid files were generated separately from the Python script's component data. The centroid file lists every SMD component's X/Y position and rotation, which is essential if you're having the boards assembled by a service rather than hand-soldering.

What's Different About This Approach

The standard way to design a PCB in 2026 is: open KiCad or Altium, draw a schematic, assign footprints, lay out the board, route traces (manually or with the built-in autorouter), and export Gerbers. It's a visual, interactive process that works well for most people and most projects.

What I did is different in a few ways that I think are worth noting, even if they're not universally applicable:

The entire design is a Python script. build_giga_shield.py is the single source of truth. Want to move a component? Change a coordinate in the script. Want to add a net? Add it to the dictionary. Want to change every decoupling cap from 0.1uF to 0.22uF? Change a string. Then re-run the pipeline. There's no "did I save the layout?" ambiguity, no undo history to worry about, no risk of accidentally moving something with a stray mouse click.

Every intermediate file is text. The .pcb file, the .dsn file, the .ses file. All text, all diffable, all version-controllable. When I moved a component and re-routed, I could git diff the PCB file and see exactly what changed. Try that with a binary PCB format.

AI can participate meaningfully. Because the files are text, Claude Code could read them, modify them, and verify them. It could grep for a component reference in the PCB file, find its coordinates, suggest a new position, and make the edit. It could read the Freerouting log and diagnose why routing failed. This level of AI participation simply isn't possible with graphical-only workflows.

The workflow is reproducible. I can hand someone the Python script and the Freerouting JAR and they can regenerate the entire board from scratch, on any machine with Python and Java. No KiCad version compatibility issues, no plugin dependencies, no "works on my machine" problems.

The trade-off is obvious: this approach requires understanding file formats at a level that graphical tools abstract away. If pcb-rnd's parser rejects your file with a misleading error message, you need to debug the file format, not just re-click a button. It's a power-user workflow. But for someone comfortable with text editors and command lines (which describes most of the audience reading a blog called tinycomputers.io), it's a viable alternative.

What's Next

The Gerber files are ready for fabrication. In part two, I'll cover ordering the boards from PCBWay, sourcing the SN74LVC8T245PW and passive components, and the moment of truth: plugging the RetroShield Z80 into the new shield and seeing if the Arduino can finally see the Z80's bus cycles clearly.

I'll also compare the v0.2 board side-by-side with the original Fiverr v0.1 board: the TXB0108 auto-sensing design versus the SN74LVC8T245 driven design. Same board dimensions, same connector layout, fundamentally different level-shifting approach. The comparison should be instructive for anyone choosing between auto-sensing and driven level translators for bus interfaces.

The Python build script, pcb-rnd source files, Gerber outputs, and all helper scripts are open source:

giga-shield — Complete design files, build pipeline, and production outputs

This is part one of a two-part series. Part two will cover fabrication, assembly, and testing.

Previous posts in this series: Fiverr PCB Design ($468) · Dual Z80 RetroShield · CP/M on the Giga R1 · Zork on the Giga

The Real Cost of Running Qwen TTS Locally — Three Machines Compared

A.C. Jokela — Thu, 12 Mar 2026 14:00:00 GMT

Every post on this site has an audio version. A small player at the top, a few minutes of narration, generated entirely on local hardware. No cloud API, no per-character fees, no data leaving the network. I wrote about setting up the pipeline on AMD Strix Halo earlier this year, and the system has been running in production since — generating narrations for new posts, regenerating old ones when I revise them, and occasionally processing long-form content that would cost real money through Google Cloud TTS or ElevenLabs.

But I now have three machines capable of running Qwen3-TTS, and they could not be more different from each other. An Apple M3 Max laptop. An AMD Ryzen AI MAX+ 395 mini desktop with integrated Radeon graphics. And a four-GPU Tesla P40 server built from decade-old enterprise hardware bought on eBay. Three different silicon vendors, three different compute backends — MPS, ROCm, and CUDA — running the same model on the same text.

The question I wanted to answer is simple: how do they actually compare? Not on paper. Not in theoretical FLOPS. In wall-clock time, generating real audio from a real blog post.

The answer turned out to be more interesting than I expected, because the numbers tell a story about hardware architecture that raw specifications completely miss.

The Setup

The model is Qwen3-TTS-12Hz-1.7B-CustomVoice, a 1.7 billion parameter autoregressive text-to-speech model from Alibaba's Qwen team. It generates natural-sounding speech with multiple speaker voices. I use the Eric voice for all blog narrations — clear, professional, well-paced for technical content.

The three machines:

Apple M3 Max — a MacBook Pro with Apple's M3 Max chip. 14 CPU cores, 30 GPU cores, 64GB unified memory. The GPU runs through PyTorch's MPS (Metal Performance Shaders) backend. This is my daily driver laptop, and it generates TTS when I am writing and editing posts.

AMD Radeon 8060S — a Bosgame M5 mini desktop running AMD's Ryzen AI MAX+ 395. This is a Strix Halo APU with integrated RDNA 3.5 graphics — not a discrete GPU. It shares 128GB of DDR5 system memory with the CPU, with roughly 96GB addressable as VRAM. The GPU runs through ROCm 7.2 with PyTorch 2.9.1. The gfx1151 architecture requires specific PyTorch wheels from AMD's pre-release index and several environment variable overrides to function. I wrote a full setup guide for this machine.

NVIDIA Tesla P40 — a 2U rack-mount server with four Tesla P40 GPUs, each with 24GB of GDDR5X. Pascal architecture from 2016. Compute capability 6.1. No Tensor Cores, no native bfloat16 support. The benchmark uses a single P40, since Qwen TTS runs on one GPU. This machine lives in an unheated shop building in Minnesota and screams through the winter when the BMC misinterprets sub-zero ambient temperatures as a hardware malfunction.

All three machines run the same model checkpoint, the same text input, and the same speaker voice. The only differences are the silicon and the compute backend.

The Benchmark

I used a standardized 2,411-character passage — five paragraphs on the Jevons Paradox, dense enough to exercise the model's prosody and pacing on real written content. Each machine ran three consecutive generations from the same loaded model, producing roughly three minutes of audio per run. The first run includes kernel compilation and cache warmup; subsequent runs reflect steady-state performance.

The metric that matters is Real-Time Factor (RTF): how many seconds of wall-clock time it takes to generate one second of audio. An RTF of 1.0 means the model generates audio at exactly real-time speed. Below 1.0 is faster than real-time. Above 1.0 means you are waiting.

Individual Runs

Apple M3 Max (MPS)

Run	Generation Time	Audio Length	RTF
1	698.5s	197.7s	3.53
2	533.1s	184.2s	2.89
3	447.8s	179.2s	2.50
Average	559.8s	187.0s	2.97

AMD Radeon 8060S (ROCm)

Run	Generation Time	Audio Length	RTF
1	729.2s	173.6s	4.20
2	460.0s	204.8s	2.25
3	548.2s	214.2s	2.56
Average	579.1s	197.5s	3.00

NVIDIA Tesla P40 (CUDA)

Run	Generation Time	Audio Length	RTF
1	1511.4s	204.1s	7.41
2	1225.7s	171.6s	7.14
3	1537.2s	206.7s	7.44
Average	1424.8s	194.1s	7.33

Summary

Machine	GPU	Avg RTF	Best RTF	Avg Gen Time
MacBook Pro	M3 Max (MPS)	2.97	2.50	559.8s
Bosgame M5	Radeon 8060S (ROCm)	3.00	2.25	579.1s
Penguin 2U	Tesla P40 (CUDA)	7.33	7.14	1424.8s

What the Numbers Mean

The headline result is that the M3 Max and Radeon 8060S are essentially tied, and the Tesla P40 is roughly 2.4 times slower than both. But that summary hides the interesting details.

The Warmup Effect Is Massive

On both the M3 Max and the Radeon 8060S, the first run is dramatically slower than subsequent runs. The M3 Max goes from RTF 3.53 on run 1 to RTF 2.50 on run 3 — a 29% improvement. The AMD shows an even larger swing: RTF 4.20 on run 1 dropping to RTF 2.25 on run 2, a 46% improvement.

This is kernel compilation. Both MPS and ROCm compile GPU kernels on first use and cache them for subsequent calls. The Qwen TTS model hits a wide variety of kernel shapes during autoregressive generation — different sequence lengths, different attention patterns — and each new shape triggers a compilation on the first encounter. By run 2, most of the common shapes are cached, and performance stabilizes.

The P40 shows almost no warmup effect. RTF 7.41 on run 1, 7.14 on run 2, 7.44 on run 3. CUDA's kernel compilation is faster and more mature, so the overhead is absorbed within the first few seconds rather than spread across the entire run. But this maturity does not translate into faster inference — CUDA compiles faster, but the P40's hardware is fundamentally slower at the operations this model requires.

This has a practical implication that matters: short benchmarks on MPS and ROCm are misleading. I initially ran a quick 276-character test on all three machines before doing the full benchmark. The short test showed the AMD at RTF 9.20 — almost identical to the P40's RTF 10.01, and far behind the M3 Max's RTF 2.84. That result nearly led me to conclude the AMD was performing as poorly as decade-old hardware. The longer benchmark, with its warmup effect amortized across more generation, revealed the truth: the AMD is just as fast as the M3 Max once the kernels are cached. If I had stopped at the short test, I would have drawn exactly the wrong conclusion.

Why the P40 Is So Slow

The Tesla P40 is a Pascal-generation GPU from 2016. It has 3,840 CUDA cores and 24GB of GDDR5X memory. On paper, it should be competitive — 12 TFLOPS of FP32 compute is not trivial. And for LLM inference through Ollama, the P40 performs remarkably well, outperforming quad T4 instances on models up to 8B parameters.

TTS is a different workload. Qwen3-TTS is an autoregressive transformer that generates audio tokens one at a time, each conditioned on all previous tokens. This means the inference is heavily memory-bandwidth bound during the decoding phase, and compute-bound during the attention and feedforward passes. The model is distributed in bfloat16 precision, which the P40 cannot compute natively — Pascal predates bfloat16 support entirely. PyTorch silently promotes bf16 operations to fp32 on the P40, roughly doubling the computation per operation and halving the effective throughput.

The P40 also lacks the SDPA (Scaled Dot-Product Attention) hardware acceleration that newer architectures provide. On the M3 Max, MPS routes attention through Metal's optimized primitives. On the AMD, ROCm's AOTriton provides experimental flash attention support. On the P40, attention runs through standard CUDA kernels without any of these accelerations. For a model that generates thousands of autoregressive steps per audio clip, each involving a full attention pass over the growing sequence, this compounds dramatically.

The P40 is not bad hardware. It is excellent hardware for the workloads it was designed for — batch inference on quantized LLMs where its 24GB of VRAM per card creates a memory advantage. But autoregressive TTS in bfloat16 hits every one of its architectural weaknesses simultaneously.

Unified Memory Wins This Workload

Both the M3 Max and the Radeon 8060S use unified memory architectures — the CPU and GPU share the same physical memory pool. The M3 Max has 64GB of unified LPDDR5. The Radeon 8060S shares 128GB of DDR5 with the CPU, with roughly 96GB addressable as VRAM.

For a 1.7B parameter model in bf16, the weights occupy roughly 3.4GB. The model fits comfortably on all three machines. But the autoregressive generation pattern creates a stream of intermediate activations — KV cache entries, attention scores, feedforward intermediates — that grow with the sequence length. On a unified memory architecture, these intermediates exist in the same memory space as the model weights, avoiding any PCIe transfer overhead. On the P40, every interaction between CPU and GPU crosses a PCIe 3.0 bus.

For LLM inference, where the bottleneck is token generation throughput and the KV cache fits in VRAM, the P40's discrete memory is fine. For TTS, where the model generates hundreds of audio tokens per second of speech and the attention window grows continuously, the memory access pattern favors unified architectures.

This is not a universal statement about unified versus discrete memory. A modern discrete GPU with HBM2e or GDDR6X and PCIe 4.0 or 5.0 would likely outperform both the M3 Max and the Radeon 8060S on this workload. The P40's problem is not that its memory is discrete — it is that its memory is slow and its bus is narrow by 2026 standards.

The Model Architecture Question

While benchmarking Qwen TTS, I also ran a quick comparison with F5-TTS on the AMD machine to sanity-check the results. F5-TTS is a flow-matching model — fundamentally different from Qwen's autoregressive approach. Where Qwen generates audio tokens sequentially, each conditioned on all previous tokens, F5 generates audio in parallel through an iterative refinement process.

The difference is stark. On the same Radeon 8060S, the same text, the same hardware:

Model	Generation Time	Audio Length	RTF
Qwen3-TTS	579.1s (avg)	197.5s	3.00
F5-TTS	17.4s	27.2s	0.64

F5-TTS is faster than real-time. Qwen3-TTS takes three times longer than the audio it produces. On normalized terms, F5 is roughly five times faster than Qwen at steady-state — and the gap widens on shorter content where Qwen's warmup overhead is proportionally larger.

This is not an apples-to-apples quality comparison. Qwen3-TTS generally produces more natural prosody, better handling of complex sentence structures, and more consistent speaker identity across long passages. F5-TTS is excellent but can occasionally drift in voice character or pacing on very long content. For blog narration, both are well above the threshold of "good enough," and the quality difference is smaller than you might expect given the architectural gap.

The point is that hardware is only half the story. The choice of model architecture can matter more than the choice of GPU. A flow-matching model on integrated AMD graphics outperforms an autoregressive model on Apple's best laptop silicon by a wide margin. If generation speed is the constraint, switching models gains more than switching hardware.

What This Costs in Practice

The abstract benchmark numbers translate into concrete time and electricity costs when you are generating audio for a library of blog posts.

A typical TinyComputers post runs 3,000 to 5,000 words, producing 15 to 25 minutes of narrated audio. At steady-state RTF:

Machine	15 min audio	25 min audio	System Power
M3 Max	~38 min	~63 min	~50W
Radeon 8060S	~38 min	~63 min	~100W
Tesla P40	~110 min	~183 min	~400W

The M3 Max and Radeon 8060S are tied on generation time, but the M3 Max draws roughly half the system power. For a single post, the electricity cost difference is negligible — a fraction of a cent. For batch processing a backlog of thirty posts, the M3 Max costs about \$0.18 in electricity versus \$0.36 for the AMD and \$3.50 for the P40.

None of these numbers are alarming. Even the P40, at nearly two and a half hours per post and 400 watts from the wall, costs under fifteen cents in electricity per narration at Minnesota residential rates. The equivalent Google Cloud TTS job would cost \$4 to \$16 per post depending on the voice quality tier.

To put cloud costs in perspective: I recently ran a fiction novel through Google's Chirp3-HD voice — 82,000 words, roughly 500,000 characters of text plus SSML markup. The bill came to \$17.25 at Google's rate of \$30 per million characters. That is not unreasonable for a one-off project, but it adds up quickly if you are generating audio regularly. The entire library of TinyComputers narrations — dozens of posts, hours of audio — has cost me nothing beyond the electricity to run the machines I already own. The economics of local TTS are favorable on every machine in the comparison.

The real cost is time. If I am generating audio for a single new post, I start it on whichever machine is idle and check back in an hour. If I am regenerating audio for twenty posts after changing the speaker voice or updating the pipeline, the M3 Max or AMD will finish overnight. The P40 would take most of a weekend.

The Right Machine for the Job

After running these benchmarks, my workflow has shifted. The M3 Max is the default for new post narration — it is fast, quiet, and I am usually sitting in front of it when I finish writing. The AMD handles batch jobs and overnight processing, where its slightly higher power draw does not matter and its equivalent speed makes it interchangeable with the Mac. The P40 server is reserved for what it does best: running large language models through Ollama, where its 96GB of aggregate VRAM gives it an advantage that neither the Mac nor the AMD can match.

The P40 can still generate TTS in a pinch, and it does — when both other machines are occupied, I will queue a job on the P40 and accept the longer wait. But for a workload that is inherently autoregressive, memory-bandwidth sensitive, and dependent on bf16 precision, a ten-year-old Pascal GPU is the wrong tool.

What surprised me most is how well the AMD performs. The Radeon 8060S is an integrated GPU sharing system memory with the CPU. It has no HBM, no dedicated VRAM, no NVLink. Its ROCm software stack requires environment variable hacks, pre-release PyTorch wheels, and a GFX version override to function at all. And yet, once the kernels warm up, it matches Apple's best laptop silicon stride for stride. The raw hardware is there — 40 RDNA 3.5 compute units with access to a deep pool of DDR5 memory. The software just needs to get out of the way, and on run 2 and beyond, it does.

Lessons

Three takeaways from this exercise that generalize beyond TTS:

Short benchmarks lie. Kernel compilation overhead on MPS and ROCm is large enough to dominate a short test. If you are evaluating a new model on non-CUDA hardware, run it at least twice before drawing conclusions. The first run is measuring the software stack, not the hardware.

Architecture matters more than clock speed. The P40 has more raw FLOPS than the Radeon 8060S. It does not matter. The P40 lacks native bf16, lacks efficient attention primitives, and sits behind a PCIe 3.0 bus. The Radeon has all three — and ties a chip designed by Apple's custom silicon team. For autoregressive models, the architectural fit between model and hardware dominates everything else.

Model choice can outweigh hardware choice. F5-TTS running on the weakest GPU in this comparison is five times faster than Qwen3-TTS running on the strongest. If your constraint is generation speed and you can accept a modest quality trade-off, switching to a flow-matching architecture gains more than any hardware upgrade short of a data center GPU.

The audio player at the top of each post on this site represents a few minutes of machine time on one of these three machines. Which machine generated it depends on the day, the workload, and what else is running. The listener cannot tell the difference. The audio sounds the same regardless of whether it was generated on a laptop, a mini desktop, or a rack-mount server in a cold Minnesota shop. That is the real benchmark — not which machine is fastest, but that all three are fast enough.

Repurposing Enterprise GPUs: The Tesla P40 Home Lab Story

A.C. Jokela — Wed, 11 Mar 2026 14:00:00 GMT

There is a window, maybe eighteen months wide, where enterprise hardware hits a pricing sweet spot. The first-generation buyers — the hyperscalers, the research labs, the Fortune 500 AI teams — have moved on to the next generation. The second-hand market floods. Prices crater. And if you know what you're looking for, you can build something genuinely capable for less than a month of cloud compute.

I built a four-GPU inference server for about twenty-five hundred dollars. This is the story of how, why, and whether you should do the same.

The Buy

The acquisition strategy is straightforward: eBay, patience, and knowing what to look for.

Tesla P40s started appearing in volume on the secondary market around 2023, when cloud providers and enterprise data centers began cycling them out in favor of A100s and H100s. A card that sold for over five thousand dollars new was suddenly available for three hundred, then two hundred and fifty, then — if you watched listings carefully and were willing to buy from decommissioned lot sellers — sometimes less. I picked up four cards over the course of about two months, averaging two hundred and fifty dollars each.

The chassis was a Penguin Computing 2U rack-mount server, also from eBay. These show up when government labs and research institutions liquidate equipment. The Penguin Computing systems are well-built — proper server-grade construction with redundant power supplies and engineered airflow. Mine takes the Xeon E5-2697A v4 and two were purchased from eBay: eighteen Broadwell cores, more than enough CPU to keep four GPUs fed. The chassis cost around six hundred dollars.

Memory was the lucky purchase. I bought 252GB of DDR4 ECC RAM before the memory price spike that hit in late 2024 when every company on Earth decided they needed AI infrastructure simultaneously. What I paid around two hundred and fifty dollars for would cost significantly more today. Total build: roughly twenty-five hundred dollars.

The Hardware

The Tesla P40 is a 2016-era data center GPU. NVIDIA designed it for the Pascal generation, targeting inference workloads in enterprise environments. The specifications, for something you can buy on eBay for two hundred and fifty dollars, are remarkable:

24GB GDDR5X per card — more memory than an RTX 4090
3,840 CUDA cores — Pascal architecture, compute capability 6.1
12 TFLOPS FP32 — respectable even by 2026 standards for inference
250W TDP — this is a data center card and it draws power like one

Multiply by four and you get 96GB of VRAM for a thousand dollars. That is an extraordinary amount of GPU memory for the price. For context, a single NVIDIA A100 80GB still sells for north of five thousand dollars on the secondary market. Four P40s give you more total VRAM for a fraction of the cost.

What You Give Up

There is no free lunch in computing, and the P40 makes you pay for its low price in specific, sometimes painful ways.

No Tensor Cores. The P40 predates NVIDIA's Tensor Core architecture, which arrived with Volta in 2017. Tensor Cores accelerate matrix multiplication — the fundamental operation in neural network inference — by factors of 4x to 16x depending on precision. The P40 does everything with its CUDA cores, the old-fashioned way. This matters less than you might think for inference at moderate batch sizes, but it means you will never match the throughput of a V100 or newer card, clock for clock.

No native BF16 or FP16. This is the real gotcha. BF16 (bfloat16) has become the default precision for large language models. It is what most model weights are distributed in. The P40 cannot compute in BF16 natively — it emulates it through FP32 operations, which is roughly 21% slower than native support. In practice, this means you are running quantized models (Q4, Q5, Q8) through llama.cpp or similar frameworks, which handle the precision conversion for you. It works. It is not optimal.

Passive cooling designed for server airflow. The P40 is a blower-style card designed for 1U and 2U server chassis with front-to-back forced airflow. In a proper server, this is fine. In anything else, you need to solve cooling yourself. I put mine in a Penguin Computing 2U rack-mount chassis, which has the right airflow characteristics, but this is not a card you drop into a desktop tower.

PCIe 3.0 x16. The P40 connects via PCIe 3.0, which provides about 16 GB/s of bandwidth per direction. When you are running a model that spans four GPUs, the inter-GPU communication goes over PCIe, not NVLink. This creates a bottleneck for models that require heavy cross-GPU communication. For inference, where the communication pattern is more predictable than training, this is manageable. For training, it would be a serious constraint.

The Minnesota Problem

My server lives in an unheated shop building in northern Minnesota. This has created an issue that no hardware review will prepare you for.

When ambient temperatures drop below freezing — which, in Minnesota, means roughly October through April — the onboard temperature sensors report values that the baseboard management controller interprets as a malfunction. The BMC's response is to spin every fan to maximum RPM as a protective measure.

The result is a machine that, on quiet winter nights, is audible from the house. The house is a hundred and fifty feet away.

I have not solved this problem. I have learned to live with it. You can override BMC fan curves on some platforms, but the Penguin Computing firmware is locked down in ways that make this nontrivial, and frankly, a server that runs its fans at full speed because it thinks it is dying is doing exactly what it should be doing. The firmware's assumptions are just wrong for the environment.

The server runs 24/7 regardless of the season, and the cold air actually keeps the GPUs well within thermal limits — the irony is that the machine has never been cooler or louder than when it is twenty below zero outside. If you are considering a similar setup in a garage, basement, or outbuilding, factor in noise. A 2U server with four 250W GPUs is not quiet under any circumstances, and server-grade fans at full RPM are genuinely loud.

Setting Up the Software Stack

The driver situation for the P40 in 2026 is straightforward, though it was not always. NVIDIA's nvidia-driver-570-server package works cleanly on Ubuntu, and the DKMS module rebuilds automatically on kernel updates — most of the time. I have had exactly two occasions where a kernel update broke the NVIDIA module and required manual intervention. This is fewer than I expected.

For inference, I run Ollama, which wraps llama.cpp and provides a simple API for model management and inference. Ollama handles multi-GPU sharding automatically — when you load a model, it distributes layers across GPUs based on available memory and model size. A 65GB model like gpt-oss:120b fits across three of the four P40s, leaving one free. Smaller models may only need one or two cards. The allocation is generally sensible, though you have less control over placement than you would with raw llama.cpp.

The alternative stack — vLLM, TGI, or raw llama.cpp — offers more control over GPU assignment but requires more configuration. With llama.cpp directly, you can pin specific GPU layers to specific devices, which lets you optimize for the P40's memory topology. vLLM provides better batching and continuous batching for serving multiple concurrent requests. For a home lab where the primary use case is running various models for experimentation and development rather than serving production traffic, Ollama's simplicity wins.

One thing worth noting: the P40 is well-supported by the GGUF ecosystem that llama.cpp (and therefore Ollama) uses. GGUF quantized models — Q4_K_M, Q5_K_M, Q8_0 — run without issues on Pascal hardware. The quantization handles the BF16 problem for you: model weights are stored in 4-bit or 8-bit integer formats and dequantized to FP32 at runtime, which the P40 handles natively. You are not fighting the hardware; you are working with it.

The Benchmarks

Theory is cheap. Benchmarks are what matter. I ran the same inference workload across three configurations: my four P40 home lab, a single AWS Tesla T4 instance, and a quad T4 instance on AWS. The T4 is the closest cloud comparison — it is the workhorse inference GPU in AWS's fleet, one generation newer than the P40 (Turing architecture, 2018), with 16GB of GDDR6 and actual Tensor Cores.

All benchmarks used Ollama with the same prompt, measuring tokens per second during the evaluation phase (excluding model load time).

Dense Models

Model	Parameters	4x P40 (Home Lab)	1x T4 (AWS \$0.53/hr)	4x T4 (AWS \$3.91/hr)
Llama 3.2	3B	94.3 tok/s	81.5 tok/s	101.5 tok/s
Qwen 2.5	7B	52.7 tok/s	36.9 tok/s	40.3 tok/s
Llama 3.1	8B	47.8 tok/s	35.7 tok/s	29.2 tok/s

The P40 wins on the 7B and 8B models by substantial margins — 31% and 64% respectively over the quad T4 configuration. The only model where the T4 edges ahead is the 3B, which is small enough to fit entirely on a single GPU. Here, the T4's higher clock speeds and faster GDDR6 memory give it an advantage because there is no multi-GPU overhead to penalize it.

The 8B result is particularly interesting. The quad T4 actually performs worse than a single T4 on this model (29.2 vs 35.7 tok/s). Ollama shards the model across all four GPUs even though it fits on one, and the PCIe communication overhead between four T4s costs more than it gains. The P40, with its larger 24GB per-card memory, likely fits more of the model per GPU, reducing cross-GPU transfers.

The MoE Advantage

The most compelling benchmark comes from OpenAI's gpt-oss — a 120-billion parameter mixture-of-experts model with only 5.1 billion active parameters per token. The MoE architecture means the model's total weight is large (it needs the memory), but the computation per token is modest (only a fraction of the parameters fire for any given input).

Model	Architecture	4x P40	4x T4 (AWS \$3.91/hr)
gpt-oss	120B MoE (5.1B active)	28.1 tok/s	20.6 tok/s

The P40 runs OpenAI's 120B model at 28.1 tokens per second — 36% faster than the cloud instance, and fast enough for comfortable interactive use. This is a state-of-the-art model running on decade-old GPUs at a speed that would have been impressive on much newer hardware a year ago.

The reason is memory. The gpt-oss model uses MXFP4 quantization on its MoE weights, bringing the total model size to about 65GB. Four P40s offer 96GB of VRAM — enough to hold the entire model in GPU memory. Four T4s offer only 64GB, which means some of the model likely spills to system RAM, adding latency on every token.

This is the P40's superpower: 24GB per card was overkill in 2016, and it is exactly right in 2026. Models have grown to fill the memory, and the P40 has more of it per dollar than almost anything else on the market.

Where It Falls Apart

Dense 70B models are a different story. Llama 3.1 70B at Q4_0 quantization (39GB) fits across 96GB of P40 VRAM, but the inference speed is essentially unusable: 0.033 tokens per second. One token every thirty seconds. Answering "What is 2+2?" took six and a half minutes. The combination of no Tensor Cores, PCIe 3.0 interconnect, and the sheer volume of cross-GPU data transfers for a dense 70B model pushes the per-token latency beyond any practical threshold.

The quad T4 on AWS managed 2.0 tokens per second on the same model — sixty times faster. Slow, but functional. The T4's Tensor Cores make the difference here — at this scale, the P40's raw CUDA cores simply cannot keep up with the matrix math.

The lesson: MoE models and quantized models up to about 8B parameters are the P40's sweet spot. Dense models above 13B start hitting diminishing returns. Dense 70B is a wall.

The Cost Argument

Here is the math that justifies the project.

A g4dn.12xlarge on AWS — four Tesla T4s, 48 vCPUs, 192GB RAM — costs \$3.91 per hour. My home lab outperforms it on every model except the smallest. If I run inference for just four hours a day, the cloud cost would be:

Daily: \$15.64
Monthly: \$469
Yearly: \$5,694

My server cost \$2,500 to build. It pays for itself in roughly five months of equivalent cloud usage. After that, the only ongoing cost is electricity. At Minnesota residential rates (roughly \$0.12/kWh) and an average draw of 800W under load, that is about \$70 per month. Less than a single day of the equivalent cloud instance.

Even if you factor in the P40's lower performance on some workloads and assume you only get 70% of the cloud equivalent's utility, the break-even point is still well under a year. For a home lab that runs 24/7 for development, experimentation, and text-to-speech generation, the economics are overwhelming.

What I Actually Use It For

The server runs several workloads:

Local LLM inference. This is the primary use case. Having a local inference server with 96GB of VRAM means I can run frontier-class open-weight models without sending data to a cloud API. For development work — where I might make hundreds of inference calls while iterating on a project — the zero marginal cost changes how I work. I experiment more freely when each query costs nothing.

Text-to-speech. I run Qwen TTS on the P40s to generate audio narration for blog posts. The model fits comfortably in the P40's memory, and the generation speed is acceptable for batch processing. The narration you hear on posts across this site was generated on these GPUs.

Development and testing. When I am building projects like Sampo or Lattice, having local GPU compute available for testing AI-assisted workflows means I do not need to worry about API rate limits or costs during intensive development sessions.

The server sits on my local network at a static IP, accessible from any machine in the house. It is always on, always available, and always free to use. That availability changes your relationship with AI inference in ways that are hard to appreciate until you have lived with it. There is a psychological difference between "this costs two cents per query" and "this costs nothing per query." The first makes you think about whether the query is worth it. The second lets you experiment without friction — and that friction reduction, compounded across hundreds of daily interactions, fundamentally changes how you work.

This is, incidentally, a small-scale example of the Jevons Paradox I have been writing about in this blog's economics series. Making inference cheaper did not cause me to run the same number of queries and pocket the savings. It caused me to run dramatically more queries, on more models, for more projects, consuming more total compute than I ever would have purchased from a cloud provider. The efficiency created demand.

Should You Build One?

The honest answer is: it depends on what you value.

Build one if: - You run local inference regularly and the cloud costs are adding up - You want 96GB of VRAM for under a thousand dollars in GPU costs - You have the physical space, electrical capacity, and noise tolerance for a rack-mount server - You enjoy the process of building and configuring systems — this is not a plug-and-play experience

Do not build one if: - You need the latest model performance (Tensor Cores, FP8, NVLink) - You are training models, not running inference - You need reliability guarantees — this is a home lab, not a production environment - You are not comfortable with Linux system administration, driver debugging, and occasional hardware troubleshooting

The P40 window will not last forever. As newer GPUs age out of data centers — the V100, the A100 — the P40 will eventually lose its price-to-performance advantage. The V100, with its first-generation Tensor Cores and 32GB of HBM2, is already starting to appear at attractive secondary market prices. Within a year, it may be the new sweet spot. But right now, in early 2026, four P40s on eBay represent one of the best deals in GPU computing. Ninety-six gigabytes of VRAM, proven CUDA compatibility, and a decade of driver maturity, for the price of a weekend trip.

The server in my shop building will keep running. The fans will keep screaming through the Minnesota winter. And I will keep running models on hardware that a hyperscaler discarded three years ago, at speeds that would have been remarkable on any hardware five years ago. That is the beauty of the secondary market — someone else paid for the R&D, someone else paid for the depreciation, and you get the compute.

JokelaOS: Writing a Bare-Metal x86 Kernel from Scratch

A.C. Jokela — Tue, 10 Mar 2026 15:00:00 GMT

There's a moment early in any OS project where the serial port prints its first character and you realize that nothing you've written has a safety net. No libc. No kernel underneath. No syscall to fall back on. If the byte appears on the terminal, it's because you programmed the UART (Universal Asynchronous Receiver-Transmitter) divisor latch, polled the line status register, and wrote to the data port. If it doesn't appear, you stare at register dumps until you find the mistake. There's no debugger — you haven't written one yet.

The closest thing I can compare it to is the first time I got a RetroShield Z80 talking over serial — that moment where a processor you wired up yourself pushes a character out of an emulated ACIA and it appears on your screen. The Z80 version involves physical hardware and solder. The x86 version is virtual — QEMU, a cross-compiler, and a Multiboot header — but the feeling is the same. You built the entire path from CPU to character. Nothing was given to you.

JokelaOS started there: a Multiboot header, a stack, and a call kmain. Everything that followed — GDT (Global Descriptor Table), IDT (Interrupt Descriptor Table), memory management, a network stack, preemptive multitasking, paging, user mode, a shell — was built one subsystem at a time, tested after every change, with no external code. No forks of existing kernels. No libc. No shortcuts.

To be clear about what this is: JokelaOS is a toy. It's a learning project. The memory allocator is a linear scan. The scheduler has no concept of priority. The file system can't delete files. The user authentication stores passwords in plaintext in a static array. Nothing here is production-grade, and none of it is intended to be. The value is in the building — understanding what each subsystem actually does by writing it from scratch, making the mistakes, and fixing them with nothing between you and the hardware.

This is the story of what it takes to go from twenty lines of NASM to a kernel that boots, manages memory, runs user programs in Ring 3, handles syscalls, responds to pings, and gives you a command prompt.

The Target

JokelaOS targets 32-bit x86 (i686) and runs under QEMU. The toolchain is a cross-compiler (i686-elf-gcc, i686-elf-ld) with NASM (Netwide Assembler) for the assembly files. The C standard is gnu11 — GNU extensions are required for inline assembly. There are no external libraries whatsoever, not even a freestanding string.h. Every memcpy, every memset, every printf-like function is written from scratch.

The only console is the serial port. COM1 at 0x3F8, 115200 baud, 8N1 (8 data bits, no parity, 1 stop bit). All kernel output goes through serial_printf(). This is a deliberate choice: serial is simpler than VGA text mode, works perfectly with QEMU's -serial stdio, and means the kernel's output appears directly in the host terminal. No framebuffer driver needed, no font rendering, no cursor management. Just bytes on a wire.

$ make run
qemu-system-i386 -kernel build/jokelaos.bin -serial stdio \
    -display none -device rtl8139,netdev=net0 \
    -netdev user,id=net0 -no-reboot

Kernel Architecture: Where JokelaOS Fits

Before getting into implementation, it's worth understanding the design space. Not all kernels are structured the same way, and the choice of architecture has consequences that ripple through every subsystem.

A monolithic kernel puts everything — memory management, scheduling, file systems, device drivers, the network stack — into a single binary running in Ring 0. All kernel code shares one address space. A function call from the scheduler into the memory manager is just that: a function call. No context switches, no message serialization, no copying buffers between address spaces. Linux is monolithic. So are the BSDs. So is JokelaOS.

The advantage is performance and simplicity. When the network stack needs to allocate a page, it calls pmm_alloc_frame() directly. When the shell wants to load a program, it calls the loader, which calls the PMM (Physical Memory Manager), which calls the paging subsystem — all in the same address space, all with the same privilege level, all at the cost of a function call. There's no overhead beyond what the work itself requires.

The disadvantage is that every driver, every subsystem, every line of kernel code has full access to every other line of kernel code's memory. A bug in the RTL8139 driver can corrupt the process table. A buffer overrun in the serial port handler can overwrite page tables. In a production monolithic kernel like Linux, this is mitigated by code review, testing, and an enormous community of contributors. In a toy kernel written by one person, it means bugs are spectacular.

A microkernel takes the opposite approach. Only the absolute minimum runs in Ring 0: the scheduler, IPC (Inter-Process Communication) message passing, and basic memory management. Everything else — file systems, device drivers, the network stack — runs as separate user-space processes (called "servers") that communicate through message passing. Mach, developed at Carnegie Mellon in the 1980s, is the canonical example. MINIX 3 is a modern realization of the idea, designed by Andrew Tanenbaum specifically to demonstrate microkernel reliability. L4 and its descendants (seL4, which has a formal mathematical proof of correctness) represent the performance-optimized end of the microkernel spectrum.

The advantage is isolation. If the network driver crashes, it crashes in its own address space. The kernel restarts it. The file system never noticed. This matters enormously for reliability and security — seL4 is used in military and aviation systems where "the driver crashed and took the kernel with it" is not acceptable.

The disadvantage is IPC overhead. Every interaction between subsystems that would be a function call in a monolithic kernel becomes a message: marshal the arguments, trap into the kernel, copy the message to the destination server's address space, schedule that server, let it process the request, marshal the reply, trap back. Mach's original implementation was notoriously slow — sometimes 50-70% slower than monolithic equivalents for system-call-heavy workloads. L4 demonstrated that much of this overhead was implementation quality rather than an inherent property of the architecture, but the fundamental cost of crossing address space boundaries doesn't disappear.

A hybrid kernel tries to split the difference. Windows NT is the most commercially successful example: it has a microkernel-like separation of concerns in its architecture, but runs most of the subsystems that a pure microkernel would put in user space (the window manager, parts of the file system, device drivers) in kernel mode for performance. macOS runs XNU, which is a Mach microkernel fused with a BSD monolithic kernel — Mach handles the low-level primitives (memory management, IPC, scheduling), while the BSD layer provides the POSIX API, the file system, and networking, all running in Ring 0. It's a microkernel by lineage but monolithic in practice.

There are more exotic designs. Exokernels, researched at MIT in the 1990s, eliminate almost all kernel abstractions and let applications manage hardware resources directly, with the kernel only enforcing protection. Unikernels (MirageOS, IncludeOS) compile the application and a minimal OS library into a single binary that runs directly on the hypervisor — no ring separation at all, because there's only one program and it's trusted by definition.

JokelaOS is monolithic, and deliberately so. It's the simplest architecture to implement, it's the easiest to debug (everything is in one address space, so a serial_printf() anywhere can see anything), and it's what you build when you're trying to understand how each subsystem works in isolation before worrying about how to decouple them. A microkernel JokelaOS would be a more interesting engineering artifact, but it would also be three times as much code before you could print a single character — you'd need working IPC before the serial driver could talk to anything.

Booting: The First 33 Lines

The entire boot sequence fits in boot.asm. Multiboot v1 requires a magic number (0x1BADB002), flags, and a checksum in a specific header format. GRUB or QEMU's -kernel loader scans for this header, loads the binary, and jumps to _start in protected mode with paging disabled.

section .multiboot
align 4
    dd 0x1BADB002                           ; Multiboot magic
    dd 0x00000003                           ; Flags: page-align + memory map
    dd -(0x1BADB002 + 0x00000003)           ; Checksum

section .text
global _start
extern kmain

_start:
    mov esp, stack_top
    push 0
    popf                    ; Clear EFLAGS
    push ebx                ; Multiboot info struct pointer
    push eax                ; Multiboot magic number
    call kmain
    cli
.hang:
    hlt
    jmp .hang

That's it. Set up a stack, clear the flags register, push the two values the Multiboot spec guarantees (magic number in EAX, info struct pointer in EBX), and call C. If kmain ever returns, disable interrupts and halt forever.

The 16 KB stack is allocated in the BSS (Block Started by Symbol) section — the region where uninitialized global data lives, zeroed at load time. The linker script places the kernel at 1 MB (the standard x86 protected-mode load address), with .multiboot first so the bootloader can find the header within the first 8 KB of the binary.

Protection Rings: Hardware-Enforced Privilege

x86 protected mode provides four privilege levels, numbered 0 through 3, called rings. Ring 0 is the most privileged — the kernel runs here. Ring 3 is the least privileged — user programs run here. Rings 1 and 2 exist in the hardware but almost nobody uses them. Linux doesn't. Windows doesn't. JokelaOS doesn't. The practical x86 privilege model is two rings: kernel and user.

The ring system isn't a software convention. It's enforced by the CPU itself, in silicon. The processor tracks the Current Privilege Level (CPL) — the ring the currently executing code belongs to — and checks it against every sensitive operation. A Ring 3 process that executes cli (disable interrupts), hlt (halt the CPU), lgdt (load a new GDT), or mov cr3 (change the page directory) triggers a General Protection Fault. The CPU literally refuses to execute the instruction. A Ring 3 process can't touch I/O ports unless the kernel has explicitly granted access through the I/O Permission Bitmap in the TSS. It can't modify its own segment registers to escalate privilege, because the CPU validates every segment load against the descriptor's DPL (Descriptor Privilege Level).

The only way for Ring 3 code to enter Ring 0 is through a gate — an interrupt gate, a trap gate, or a call gate. Gates are entries in the IDT or GDT that the kernel sets up in advance. They define the exact entry points where Ring 3 code can cross into Ring 0, what the new code and stack segments will be, and what privilege level is required to use them. There's no way for user code to jump to an arbitrary kernel address. It can only enter the kernel through the doors the kernel has built.

This is what makes an operating system an operating system rather than a library. Without ring separation, a buggy user program can corrupt kernel memory, disable interrupts, reprogram the PIC, or overwrite the page tables. With ring separation, the worst it can do is crash itself.

The mechanism that implements all of this is the Global Descriptor Table.

The GDT: Defining the World

The GDT defines memory segments — their base addresses, sizes, privilege levels, and whether they hold code or data. Each segment descriptor is an 8-byte structure with fields packed into non-obvious bit positions (a consequence of backward compatibility with the 286, which had a different descriptor format that the 386 had to extend without breaking).

JokelaOS uses a flat memory model: every segment covers the full 4 GB address space with base 0 and limit 0xFFFFFFFF. The segmentation hardware is effectively nullified, which is what you want on modern x86 where paging handles memory protection. But the GDT is still mandatory — the CPU requires it for the ring system to function. Even with flat segments, the DPL field in each descriptor is what tells the CPU "code using this segment is Ring 0" or "code using this segment is Ring 3."

The GDT has six entries:

Index	Selector	Purpose
0	0x00	Null descriptor (required by x86)
1	0x08	Kernel code (Ring 0, execute/read)
2	0x10	Kernel data (Ring 0, read/write)
3	0x18	User code (Ring 3, execute/read)
4	0x20	User data (Ring 3, read/write)
5	0x28	Task State Segment

Entries 1 and 2 are identical to entries 3 and 4 in every way except the DPL field — two bits in the access byte that say 00 (Ring 0) versus 11 (Ring 3). That two-bit difference is the entire kernel/user boundary.

When a user process runs, the CPU's CS register is loaded with 0x1B — that's selector 0x18 (pointing to GDT entry 3, the user code segment) OR'd with RPL 3 (Requested Privilege Level, the bottom two bits of the selector). The data segment registers get 0x23 (GDT entry 4, user data, RPL 3). The CPU sets CPL to match, and from that point on, every instruction is checked against Ring 3 privileges. The kernel runs with CS=0x08 (GDT entry 1, RPL 0) and DS=0x10 (GDT entry 2, RPL 0).

The TSS (Task State Segment) is the bridge between rings. When the CPU takes an interrupt while running Ring 3 code, it needs to switch to a Ring 0 stack — you can't trust the user's stack pointer to be valid, and you certainly can't run kernel interrupt handlers on a user-controlled stack. The TSS holds the Ring 0 stack pointer (esp0). Every context switch updates the TSS with the current process's kernel stack, so the CPU always knows where to land when transitioning from user mode to kernel mode.

void gdt_init(void) {
    gdt_set_entry(0, 0, 0, 0, 0);                     // Null
    gdt_set_entry(1, 0, 0xFFFFFFFF, 0x9A, 0xCF);      // Kernel code
    gdt_set_entry(2, 0, 0xFFFFFFFF, 0x92, 0xCF);      // Kernel data
    gdt_set_entry(3, 0, 0xFFFFFFFF, 0xFA, 0xCF);      // User code
    gdt_set_entry(4, 0, 0xFFFFFFFF, 0xF2, 0xCF);      // User data
    // TSS entry built separately
    ...
}

The access byte 0x9A means: present, Ring 0, code segment, executable, readable. 0xFA means the same thing but Ring 3. These magic numbers come straight from the Intel manuals and they're the kind of thing you get wrong three times before you get right once.

Interrupts: Exceptions, IRQs, and the PIC

The IDT (Interrupt Descriptor Table) maps interrupt vectors to handler functions. JokelaOS sets up 256 entries: CPU exceptions (0-31), hardware IRQs (32-47), and the syscall gate (0x80).

The x86 PIC (Programmable Interrupt Controller) needs remapping. By default, the master PIC maps IRQs 0-7 to interrupt vectors 8-15, which collide with CPU exceptions (double fault is vector 8, for instance). The standard fix is to remap the master PIC to vectors 32-39 and the slave to 40-47. This requires sending four Initialization Command Words to each PIC in the correct sequence — the kind of hardware protocol that hasn't changed since the IBM PC/AT in 1984.

ISR (Interrupt Service Routine) stubs are written in NASM. Each one pushes an error code (or a dummy zero for exceptions that don't push one), pushes the interrupt number, saves all general-purpose registers, calls the C handler, restores registers, and does an iret. The stubs are generated with macros:

%macro ISR_NOERRCODE 1
global isr%1
isr%1:
    push dword 0        ; dummy error code
    push dword %1       ; interrupt number
    jmp isr_common
%endmacro

The C-side dispatcher checks the interrupt number. For exceptions (0-31), it prints the register state and halts — there's no recovery from a page fault when you don't have a page fault handler yet. For IRQs (32-47), it calls the registered handler function and sends an EOI (End of Interrupt) command to the PIC. For interrupt 0x80, it dispatches to the syscall handler.

One critical detail: interrupt 0x80 is set as a trap gate with DPL 3, not an interrupt gate. This means Ring 3 code can trigger it with int 0x80. All other interrupt gates are DPL 0 — a user program that tries to execute int 0x00 gets a General Protection Fault instead. This is the mechanism that makes syscalls work while keeping everything else protected.

Memory: Three Allocators

JokelaOS has three layers of memory management, each built on top of the previous one.

The Bump Allocator

The simplest possible allocator. A pointer starts at the first page boundary after the kernel image (_kernel_end from the linker script) and only moves forward. kmalloc(size) aligns the pointer to 16 bytes, returns it, and advances by size. There is no kfree(). Memory allocated with the bump allocator is permanent.

This sounds primitive, and it is. But it's also exactly right for kernel initialization. The GDT, IDT, page tables, file system metadata, user table — these are allocated once and never freed. The bump allocator handles all of them with zero fragmentation and zero overhead.

The Physical Memory Manager

Once the kernel needs to allocate and free pages dynamically (for process stacks, program code, page tables), it needs a real allocator. The PMM uses a bitmap: one bit per 4 KB physical frame, supporting up to 256 MB of RAM (65,536 frames, 8 KB bitmap).

Initialization parses the Multiboot memory map to find usable RAM regions, then marks everything from frame 0 through the end of the bump heap as reserved. This protects the IVT (Interrupt Vector Table), BIOS data area, kernel image, and all bump-allocated structures from being handed out as free pages.

uint32_t pmm_alloc_frame(void) {
    for (uint32_t i = 0; i < total_frames; i++) {
        if (!(bitmap[i / 8] & (1 << (i % 8)))) {
            bitmap[i / 8] |= (1 << (i % 8));
            free_count--;
            return i * PAGE_SIZE;
        }
    }
    return 0;  // out of memory
}

Linear scan, no free lists, no buddy system. It's O(n) per allocation, which is fine when n is measured in thousands and allocations are infrequent. A production kernel would use something smarter. This kernel allocates a few dozen pages total.

Paging

With physical frames available, the kernel can enable paging. paging_init() builds a page directory and 32 page tables, identity-mapping the first 128 MB of physical memory (virtual address = physical address). The page directory goes into CR3, and setting the PG bit in CR0 turns the MMU (Memory Management Unit) on.

Identity mapping means the kernel doesn't need to worry about virtual-to-physical translation for its own code and data. Kernel pointers just work. When user processes need memory, the loader allocates physical frames and maps them into the process's address space with the PG_USER flag set, allowing Ring 3 access.

void paging_map_page(uint32_t virt, uint32_t phys, uint32_t flags) {
    uint32_t dir_idx = virt >> 22;
    uint32_t tbl_idx = (virt >> 12) & 0x3FF;

    if (!(page_directory[dir_idx] & PG_PRESENT)) {
        uint32_t tbl_frame = pmm_alloc_frame();
        memset((void *)tbl_frame, 0, PAGE_SIZE);
        page_directory[dir_idx] = tbl_frame | PG_PRESENT | PG_WRITE | flags;
    }

    uint32_t *table = (uint32_t *)(page_directory[dir_idx] & 0xFFFFF000);
    table[tbl_idx] = (phys & 0xFFFFF000) | flags;

    asm volatile("invlpg (%0)" : : "r"(virt) : "memory");
}

The invlpg instruction flushes the TLB (Translation Lookaside Buffer) entry for the mapped virtual address, which is critical — without it, the CPU might use a stale translation from its cache and access the wrong physical page.

The Network Stack

JokelaOS has a working network stack — the one subsystem where "toy" undersells it slightly. It resolves ARP (Address Resolution Protocol), constructs IPv4 (Internet Protocol version 4) packets with correct checksums, and handles ICMP (Internet Control Message Protocol) echo request/reply with measured round-trip times. There's no TCP (Transmission Control Protocol), no UDP (User Datagram Protocol), no sockets. But the packets that leave this kernel are real packets that traverse real networks.

The NIC (Network Interface Controller) is an emulated RTL8139, the simplest PCI (Peripheral Component Interconnect) Ethernet controller that QEMU supports. The driver initializes the chip by writing to its configuration registers: reset, enable transmitter and receiver, set up a receive ring buffer, configure the interrupt mask, and unmask IRQ 11. Packet transmission uses a four-descriptor TX ring; reception is interrupt-driven through the RTL8139's ring buffer.

PCI enumeration scans the configuration space to find the RTL8139 by vendor/device ID (0x10EC:0x8139), reads the I/O base address from BAR0 (Base Address Register 0), and enables bus mastering. This is the only driver in the system — there's no USB, no disk, no display. One NIC, one network.

The stack is layered:

Layer	Module	Purpose
Link	`ethernet.c`	Frame demux by EtherType
ARP	`arp.c`	Table + request/reply
Network	`ipv4.c`	Routing, header checksum
Transport	`icmp.c`	Echo reply + outgoing ping

On boot, the kernel sends an ARP request for the gateway (10.0.2.2, QEMU's default) and waits for the reply. Once the gateway's MAC (Media Access Control) address is resolved, the kernel can ping arbitrary hosts through QEMU's SLIRP (Session-Level IP Redirect Protocol) NAT (Network Address Translation). A ping 10.1.1.1 from the shell constructs an ICMP echo request, wraps it in an IPv4 packet, wraps that in an Ethernet frame, and pushes it out through the RTL8139's TX ring. When the reply comes back, the receive ISR fires, the Ethernet layer demuxes by EtherType, the IP layer validates the checksum, and the ICMP handler matches the echo reply to the outstanding request and computes the RTT (round-trip time).

root$ ping 10.1.1.1
[ping] Pinging 10.1.1.1...
  64 bytes from 10.1.1.1: seq=1 time=4 ms
  64 bytes from 10.1.1.1: seq=2 time=2 ms
  64 bytes from 10.1.1.1: seq=3 time=3 ms
  64 bytes from 10.1.1.1: seq=4 time=2 ms

Getting here required writing every byte-order conversion (htons, htonl), every checksum computation (the IP header checksum is a one's complement sum of 16-bit words), every packet layout (Ethernet header is 14 bytes, IP header is 20, ICMP is 8 plus payload). None of this is hard individually. Together, it's a thousand places to put a byte in the wrong order.

Processes and Preemptive Multitasking

The process subsystem manages up to 16 processes in a static table. Each process has a state (UNUSED, READY, RUNNING, DEAD), a kernel stack pointer, and a user-mode entry point and stack.

Process creation doesn't follow the UNIX fork()/exec() model. There's no cloning of address spaces, no copy-on-write, no replacing the current process image. Instead, the loader allocates fresh physical frames for the program's code and stack, copies the flat binary into the code pages, and calls proc_create(), which allocates a 4 KB kernel stack and builds a fake stack frame on it. This stack frame is what context_switch() will "return" into on the process's first schedule — it contains saved registers and a return address pointing to proc_entry_user().

proc_entry_user() is a small assembly sequence that performs the Ring 0 to Ring 3 transition. It sets the data segment registers to the user data selector (0x23), pushes a fake interrupt frame (SS, ESP, EFLAGS with IF=1, CS, EIP), and executes iret. The CPU pops the frame, switches to Ring 3, and starts executing the user program. From the hardware's perspective, this looks identical to returning from an interrupt that happened to interrupt a user-mode program — which is exactly the trick.

static void proc_entry_user(void) {
    process_t *p = proc_current();
    asm volatile(
        "mov $0x23, %%ax \n"
        "mov %%ax, %%ds  \n"
        "mov %%ax, %%es  \n"
        "mov %%ax, %%fs  \n"
        "mov %%ax, %%gs  \n"
        "push $0x23      \n"   // SS
        "push %0         \n"   // ESP
        "pushf           \n"
        "pop %%eax       \n"
        "or $0x200, %%eax\n"   // Set IF
        "push %%eax      \n"   // EFLAGS
        "push $0x1B      \n"   // CS (user code)
        "push %1         \n"   // EIP
        "iret"
        : : "r"(p->user_esp), "r"(p->user_eip)
        : "eax", "memory"
    );
}

Context switching uses a simple assembly stub in switch.asm. It saves the callee-saved registers (EBP, EBX, ESI, EDI), stores ESP into the old process's slot, loads the new process's ESP, restores registers, and returns. The ret instruction pops the return address from the new stack and resumes where that process left off.

Scheduling is preemptive round-robin. The PIT (Programmable Interval Timer) fires at 1000 Hz. Every 10 ticks (10 ms), the IRQ handler calls proc_schedule(), which finds the next READY process and switches to it. If no user processes are ready, control stays with PID 0 (the kernel/shell). This is the minimum viable scheduler — no priorities, no time slices, no fairness guarantees. But it works: two user programs printing characters to serial run concurrently, interleaved by the timer.

Syscalls

User programs communicate with the kernel through int 0x80. The mechanism — a software interrupt that transitions from Ring 3 to Ring 0 — is the same one Linux used on i386 before sysenter replaced it. The register convention is borrowed too: syscall number in EAX, arguments in EBX/ECX/EDX/ESI/EDI, return value in EAX. But that's where the resemblance ends.

JokelaOS is not a UNIX. The syscall numbers are custom — exit is 0, write is 1, getpid is 2, read is 3 — not Linux's i386 table (where exit is 1, read is 3, write is 4, getpid is 20). There's no fork(), no exec(), no open(), no close(), no signals, no pipes. File descriptors 0 and 1 exist as concepts (stdin maps to the keyboard buffer, stdout maps to the serial port) but there's no file descriptor table behind them. The syscall handler just checks if (fd == 1) and calls serial_putchar(). The process model isn't UNIX either — there's no parent/child relationship, no wait(), no process groups. Processes are created by the loader and scheduled round-robin until they exit. It's closer to a microcontroller RTOS (Real-Time Operating System) than to anything in the UNIX lineage.

Four syscalls are implemented:

Number	Name	Arguments	Description
0	SYS_EXIT	ebx=status	Terminate process
1	SYS_WRITE	ebx=fd, ecx=buf, edx=len	Write to serial (fd=1)
2	SYS_GETPID	—	Return current PID
3	SYS_READ	ebx=fd, ecx=buf, edx=len	Read from keyboard (fd=0)

This is enough to write programs that print output, read input, identify themselves, and exit cleanly. The syscall dispatcher validates file descriptors (only 0 and 1 are legal) and bounds-checks lengths. SYS_WRITE sends bytes to the serial port; SYS_READ drains the keyboard buffer non-blocking.

User programs are flat binaries — raw machine code with no headers, no relocations, no ELF (Executable and Linkable Format) parsing. The loader copies the binary to freshly allocated pages and jumps to byte zero. Programs that need to reference their own data use position-independent tricks:

call next       ; push EIP
next:
pop ebp         ; EBP = address of this instruction
lea ecx, [ebp + offset_to_data]

This is the same technique used by shellcode and position-independent code on x86. It works because call pushes the address of the next instruction, which gives you a known reference point relative to the code's actual load address.

The Shell

With all the subsystems in place, the shell ties them together into something interactive. shell_run() is the kernel's main loop after initialization — it presents a login prompt, authenticates against the user table, and drops into a command interpreter.

==============================
  JokelaOS v0.1
==============================

[ok] GDT loaded (ring 0 + ring 3 + TSS)
[ok] IDT loaded, PIC remapped
[ok] Multiboot confirmed
[ok] Multiboot info at 0x9500
[ok] Bump allocator ready

PCI 00:03.0 — vendor 10EC device 8139 (RTL8139)
[ok] RTL8139 ready, MAC=52:54:00:12:34:56, IRQ=11

[ok] ramfs: 2 files
[ok] Users: root, guest
[ok] PMM: 31269 free frames (122 MB)
[ok] Paging enabled (128 MB identity-mapped)
[ok] PIT timer @ 1000 Hz
[ok] Keyboard + serial input ready

JokelaOS is alive.

login: root
password: ****
root$

The shell supports: help, ls, run <program>, ps, mem, ping <ip>, uptime, whoami, and logout. The line editor handles backspace. Password input echoes asterisks. The run command loads a flat binary from ramfs, creates a process, and the scheduler picks it up on the next timer tick.

ps shows the process table:

root$ ps
  PID  STATE
    0  RUNNING
    1  READY
    2  DEAD

mem shows memory usage:

root$ mem
Heap used: 8832 bytes
PMM free:  31267 frames (122 MB)

The keyboard input path is worth noting. The PS/2 keyboard controller fires IRQ 1. The handler reads the scancode from port 0x60, converts it to ASCII using a US QWERTY lookup table (with shift modifier tracking), and drops it into a 256-byte circular buffer. Serial input takes the same path — the UART's receive interrupt (IRQ 4) reads the incoming byte and injects it into the keyboard buffer. This means the shell works identically whether you're typing on a PS/2 keyboard or through the QEMU serial console.

The RAM File System

User programs need to live somewhere. With no disk driver, the file system is purely in-memory. ramfs stores up to 32 files, each with a name (28 bytes), a data pointer, and a size. ramfs_create() allocates space with the bump allocator and copies the binary in. ramfs_find() does a linear search by name.

During boot, two test programs are embedded directly in kmain.c as byte arrays of hand-assembled x86 machine code. One prints the character '1' ten times; the other prints '2' ten times. Both use SYS_WRITE to output through the serial port and SYS_EXIT to terminate cleanly. They're loaded into ramfs, and run print1 from the shell executes them in user mode.

This is about as minimal as a file system gets. No directories, no permissions, no deletion. But it demonstrates the complete path from "bytes in kernel memory" to "user-mode process executing with its own address space."

What I Learned

Writing a kernel from scratch teaches you things that no amount of reading about kernels will teach you. Some of these are technical. Most are about the nature of systems programming itself.

The boot process is the hardest part. Not because the code is complex — boot.asm is 33 lines — but because when something goes wrong, you have zero diagnostic capability. The serial port isn't initialized yet. The IDT isn't loaded. If your Multiboot header checksum is wrong by one bit, QEMU silently fails. You're debugging with QEMU's -d int flag and reading hex dumps of interrupt frames.

x86 protected mode is an archaeology project. The PIC remapping sequence dates from the IBM PC/AT (1984). The GDT access bytes encode information in bit patterns designed for hardware that predates flat memory models. The TSS exists because Intel's original vision for the 286 involved hardware task switching that nobody ended up using. You're programming against forty years of backward compatibility, and every one of those layers is still there, still mandatory, still silently breaking things if you get it wrong.

The gap between "works in Ring 0" and "works in Ring 3" is enormous. A kernel that runs entirely in supervisor mode can be surprisingly simple. The moment you add user mode, you need: the TSS (so the CPU knows where the kernel stack is), Ring 3 GDT segments, trap gates for syscalls, a mechanism to build fake interrupt frames for the initial iret into user mode, and careful validation of every pointer that crosses the kernel boundary. Each of these is individually straightforward. Getting them all correct simultaneously is where the real difficulty lies.

Preemptive scheduling is simpler than it sounds. The concept — save state, pick next process, restore state — translates almost directly into code. The context switch is twelve instructions of assembly. The scheduler is a for loop. What makes it tricky is the interaction with everything else: the TSS must be updated, the interrupt must send EOI before switching, the process's kernel stack must be set up so that restoring registers and returning lands in the right place. The scheduler itself is trivial. The invariants it depends on are not.

Writing a network stack is an exercise in byte ordering. Ethernet is big-endian. x86 is little-endian. IP addresses, port numbers, checksums, packet lengths — every multi-byte field requires explicit conversion. Miss one htons() and your packets are valid-looking garbage. The RTL8139 driver, the ARP implementation, the IP checksum — each is maybe fifty lines. The debugging when a byte is swapped is hours.

The Numbers

JokelaOS in its current form:

Component	Files	Approximate LOC
Boot (ASM)	3	~120
Kernel core	16	~1,200
Drivers	2	~250
Network stack	5	~450
Total	26	~2,000

Two thousand lines for a kernel that boots, manages memory with paging, runs preemptive multitasking with Ring 3 isolation, handles interrupts, implements syscalls, has a working network stack, and provides an interactive shell. No line is borrowed from another project. Every byte is accounted for.

The entire thing builds in under a second and the binary is around 40 KB. make run goes from source to a running kernel in QEMU in about two seconds. This fast iteration cycle is what made the project possible — every subsystem was tested immediately after being written, and bugs were caught before they could compound.

What's Next

JokelaOS is a foundation, not a finished product. The obvious next steps are a proper virtual memory manager (per-process page directories instead of a shared identity map), a real file system (even a simple FAT12 (File Allocation Table, 12-bit) would be a significant step up from ramfs), and ELF binary loading. Beyond that: a disk driver would unlock persistence, TCP would make the network stack actually useful, and a proper fork()/exec() would make the process model complete.

But the point of JokelaOS was never to build a production operating system. The point was to understand what an operating system actually does — not in the abstract, not from a textbook diagram, but in the specific, concrete sense of "these bytes go into these ports in this order and then the hardware does this thing." Every subsystem in JokelaOS exists because I wanted to understand it, and the only way to truly understand a piece of systems software is to write it yourself.

The source code is on GitHub.

The Cathedral and the Bazaar, Nearly 30 Years Later

A.C. Jokela — Mon, 09 Mar 2026 16:00:00 GMT

In 1997, Eric S. Raymond presented a paper at the Linux Kongress in Bavaria that would reshape how an entire industry thought about building software. "The Cathedral and the Bazaar" drew a sharp line between two models of development. The cathedral: careful, centralized, release-when-ready. The bazaar: open, decentralized, release-early-and-often. Raymond argued, with considerable evidence from the Linux kernel and his own fetchmail project, that the bazaar would win.

Nearly three decades later, we can evaluate the claim. And the answer is more interesting than a simple yes or no.

What Raymond Actually Argued

The essay's core thesis was that certain software problems — particularly large, complex ones — were better solved by decentralized communities than by centralized teams. Raymond distilled this into several principles, the most famous being Linus's Law: "Given enough eyeballs, all bugs are shallow." With enough contributors examining source code, every bug would be obvious to someone.

He identified several supporting dynamics. Release early and often. Treat your users as co-developers. If you treat beta testers as your most valuable resource, they'll respond by becoming your most valuable resource. Keep the architecture modular enough that contributors can work on pieces independently.

The implicit assumption was ideological as much as technical. Open-source development would succeed because it aligned individual motivation (scratching a personal itch, building reputation, the intellectual satisfaction of solving problems) with collective benefit. No corporate hierarchy required. No cathedral architects directing the work from above.

It was, in its way, a profoundly optimistic vision of human coordination.

Here's what makes the timing remarkable: when Raymond presented his paper in 1997, the term "open source" didn't exist. He was writing about "free software" and the Linux development model. The phrase was coined months later, in February 1998, at a strategy session in Palo Alto — partly catalyzed by the essay's success and Netscape's decision to release the Navigator source code (a decision Raymond's essay directly influenced). The Open Source Initiative followed weeks after that, co-founded by Raymond and Bruce Perens.

The movement Raymond was describing was young. The GNU Project was fourteen years old. The Free Software Foundation was twelve. The GPL was eight. Linux itself was only six. BSD had been circulating since the late 1970s, but the legal battles that nearly killed it were barely resolved. There was no GitHub, no SourceForge, no standardized workflow for distributed contribution. The bazaar Raymond championed was a handful of mailing lists, FTP servers, and the sheer force of Linus Torvalds's integrative judgment.

The essay didn't just describe a revolution. It named one that hadn't named itself yet.

The Bazaar Won

By any quantitative measure, Raymond was right. Linux runs the cloud. Android runs the phone. Firefox and then Chromium reshaped the browser. Apache and then Nginx served the web. PostgreSQL and MySQL handled the data. Python, Ruby, Node.js, Rust, Go — the languages that define modern development are overwhelmingly open-source.

The numbers are staggering. GitHub hosts over 400 million repositories. The Linux kernel has received contributions from over 20,000 individual developers. Every major cloud provider — Amazon, Microsoft, Google — runs on open-source infrastructure. Even Microsoft, which once called Linux a "cancer," now contributes to it, acquired GitHub, and ships a Linux kernel inside Windows.

If you'd told someone in 1997 that the world's most valuable companies would run their businesses on software they didn't own and couldn't fully control, they would have questioned your judgment. Raymond's prediction wasn't just right. It was conservative.

The Cathedral Came Back Wearing Bazaar Clothes

Here's where Raymond's vision diverges from what actually happened. The bazaar won, but the cathedrals adapted.

Meta open-sources PyTorch and Llama. Google open-sources TensorFlow, Kubernetes, Android, and Chromium. Microsoft open-sources VS Code, TypeScript, and .NET. Amazon builds its most profitable business on top of open-source databases, then offers them as managed services. These are not acts of ideological commitment. They are strategic decisions made by organizations with cathedral-scale resources and cathedral-scale ambitions.

The pattern is consistent: open-source the layer you want to commoditize, then capture value at the layer above. Google open-sources Android to commoditize mobile operating systems, then captures value through the Play Store and advertising. Meta open-sources PyTorch to commoditize the AI framework layer, then captures value through the models and services built on top. Amazon doesn't need to own the database — it needs to own the infrastructure the database runs on.

This is what Raymond didn't anticipate. The bazaar model wasn't just adopted by idealists scratching personal itches. It was weaponized by the most powerful corporations in history as a competitive strategy. The BSD licensing disputes that shaped early open-source history look almost quaint compared to the strategic licensing wars that followed.

There's a personal irony here too. Raymond himself wasn't immune to the cathedral's gravitational pull. He received 150,000 pre-IPO shares of VA Linux, briefly making him worth approximately \$36 million. He wrote an essay called "Surprised by Wealth" about the experience, pledging that the money wouldn't change him. By April 2002, the shares were worth \$195,000 — he'd held through the entire collapse without selling. The bazaar's chief evangelist got rich, briefly, through the most cathedral-scale financial mechanism in capitalism: Wall Street pre-IPO allocations. The wealth came and went through institutions the bazaar model was supposed to make irrelevant.

Joel Spolsky described this dynamic in 2002 as "commoditize your complements." Open-source your competitors' profit center, and your own products become more valuable. But even Spolsky didn't fully see how far it would go. In 2026, the bazaar is less a revolutionary alternative to the cathedral than a resource the cathedral harvests.

The Efficiency That Created More, Not Less

Raymond's essay focused on the development model — how code gets written, reviewed, and shipped. What he didn't explore was the economic consequence of making infrastructure-quality software free.

When the bazaar model succeeded, it didn't just change how software was built. It changed how much software existed. By making operating systems, web servers, databases, programming languages, and frameworks available at zero marginal cost, the bazaar removed the floor from the cost of building new things. A startup in 2005 could do what a well-funded company in 1995 could not, because the entire stack was free.

The result wasn't less total development effort. It was dramatically more. Linux didn't consolidate the operating system landscape into one efficient platform — it spawned hundreds of distributions, each with its own community, its own design philosophy, its own ecosystem. Free databases didn't mean fewer databases. It meant PostgreSQL, MySQL, MariaDB, SQLite, MongoDB, Redis, CockroachDB, and dozens more, each serving demand that wouldn't have existed if everyone had to pay Oracle prices.

This pattern — efficiency gains leading to expanded consumption rather than reduced effort — has a name in economics, and it shows up everywhere technology reduces the cost of a critical input. The bazaar made software infrastructure cheap, and the world responded by building more software than anyone in 1997 could have imagined.

There's a second-order effect too. By making infrastructure free, the bazaar lowered the cost of building on top of that infrastructure. Entire industries — SaaS, cloud computing, the modern startup ecosystem — simply wouldn't have been viable if everyone had to pay cathedral-model prices for their stack. The VisiCalc pattern repeated itself: a tool that was supposed to eliminate work created new categories of work that dwarfed the original.

And Raymond's own principle — treat users as co-developers — is itself a demand-expanding dynamic. Converting consumers of software into producers means the resource (developer attention) gets deployed more broadly, not more efficiently. More people write code because more people can write code, because the tools are free, the examples are public, and the barrier to participation is a GitHub account.

What Raymond Got Wrong

The essay's blind spots have become painfully clear.

Maintainer burnout. Raymond assumed that contributor motivation was self-sustaining — people would keep showing up because the work was interesting. He didn't account for the dynamics that emerge when a hobby project becomes critical infrastructure. The OpenSSL library, maintained for years by a handful of volunteers, secured the majority of encrypted web traffic until the Heartbleed vulnerability in 2014 revealed how thin the maintenance layer really was. The left-pad incident, the core-js crisis, the Log4j vulnerability — each demonstrated that the bazaar's supply of labor is not inexhaustible. It concentrates on the exciting work and neglects the essential work.

Free-riding at scale. The essay assumed a rough symmetry between use and contribution. The reality is asymmetric: billions of dollars in commercial value extracted from projects maintained by unpaid or underpaid developers. Amazon took Elasticsearch and offered it as a managed service. When Elastic changed their license to prevent this, the open-source community split. MongoDB, Redis, and HashiCorp followed similar paths — companies that built open-source projects, watched cloud providers commoditize them, and responded by restricting their licenses.

Security supply chains. A bazaar has no gatekeepers, which Raymond saw as a feature. It's also a vulnerability. The SolarWinds attack, dependency confusion attacks, typosquatting on npm — these exploit the trust model that makes the bazaar work. When anyone can contribute, anyone includes adversaries.

Governance. Raymond wrote about the bazaar as if the only governance question was technical: who decides which patches get merged? The real governance questions turned out to be social and economic: who funds maintenance? Who decides licensing changes? Who gets to use the work commercially? These questions have no bazaar-native answers. They require institutions — foundations, companies, legal frameworks — which is to say, they require cathedrals.

The Licensing Wars

The clearest evidence that Raymond's framework was incomplete is the licensing landscape of 2026.

The GPL, which Richard Stallman designed to ensure that modified software remained free, worked well in a world where software was distributed as binaries. The cloud broke that model. If you run GPL software as a service, you never "distribute" it — users interact with the output, not the code. The software is free in theory and proprietary in practice.

The response was a proliferation of new licenses. The AGPL closed the cloud loophole by requiring source availability for network services. The Business Source License (BSL) made code available to read but restricted commercial use until a time-delayed release to open source. The Server Side Public License (SSPL) required that anyone offering the software as a service must open-source their entire stack.

Each of these represents a partial retreat from the bazaar model. Not back to the cathedral — the code is still visible, forkable, auditable — but to something Raymond didn't envision: a commons with fences. The ideological purity of "free as in freedom" collided with the economic reality that freedom without reciprocity becomes exploitation.

The BSD licensing story foreshadowed this. The permissive BSD license allowed commercial forks without contribution back. This wasn't a problem when the commercial ecosystem was small. When the commercial ecosystem became the entire cloud computing industry, the lack of reciprocity became untenable for projects that couldn't attract cathedral-scale corporate sponsorship.

What Raymond Got Right

Despite these blind spots, the essay's core insight has proven durable: for certain classes of problems, decentralized coordination outperforms centralized planning.

This isn't because decentralized systems are morally superior. It's because they solve the information problem differently. A cathedral architect must understand the entire system well enough to direct work from above. A bazaar participant only needs to understand their local patch well enough to improve it. As systems grow in complexity, the information burden on the cathedral architect grows faster than the burden on any individual bazaar participant.

The Linux kernel is the proof. No single person understands the entire Linux kernel. It's too large, too complex, spanning too many hardware architectures and subsystems. But the kernel works — and works remarkably well — because the development model doesn't require any single person to understand it all. Subsystem maintainers understand their domains. Linus Torvalds understands the integration points. Contributors understand the specific problems they're solving. The architecture of the development process mirrors the architecture of the software.

This insight extends beyond software. Wikipedia works on bazaar principles. Citizen science projects like Galaxy Zoo and Foldit leverage distributed human attention. Even hardware design is slowly moving in this direction, though the marginal cost of atoms versus bits creates structural barriers that software doesn't face. The concept of second-sourcing — multiple manufacturers producing compatible chips — is, in a sense, the hardware world's version of the bazaar. The Z80 survived for nearly fifty years partly because Zilog couldn't monopolize it.

Raymond also got the motivational model roughly right, even if the details were off. People do contribute to open-source projects for intrinsic reasons — intellectual satisfaction, reputation, the desire to solve problems that matter to them personally. The mistake was assuming these motivations were sufficient at industrial scale, without institutional support.

The Bazaar in 2026

The open-source landscape of 2026 bears little resemblance to what Raymond described in 1997, but the dynamics he identified are still operating.

The bazaar model made software infrastructure so cheap that it created more demand for software than any cathedral could have supplied. It enabled the cloud, the startup ecosystem, the AI revolution — all built on free foundations. The efficiency didn't reduce consumption. It unlocked latent demand that dwarfed the original market.

At the same time, the cathedral never disappeared. It adapted. The most sophisticated cathedrals now build bazaars strategically — open-sourcing frameworks and tools that make their own proprietary services more valuable. Meta's contribution to PyTorch isn't charity. Google's contribution to Kubernetes isn't ideology. They're infrastructure investments that make the entire ecosystem dependent on capabilities only cathedral-scale organizations can provide.

The result is a layered system more nuanced than Raymond's binary. At the bottom: genuine bazaar-model projects maintained by communities (the Linux kernel, PostgreSQL, countless libraries). In the middle: corporate-sponsored projects that look like bazaars but serve cathedral strategies (Kubernetes, Chromium, Llama). At the top: proprietary services built on open foundations (AWS, Google Cloud, OpenAI's API).

Each layer depends on the ones below it. Each layer captures value differently. And the whole structure is held together by a web of licenses, foundations, corporate agreements, and social norms that Raymond's 1997 essay couldn't have anticipated.

What's strangest about this arrangement is its circularity. Corporations adopted open source because it was free and good. Volunteer maintainers couldn't scale to meet corporate demand — Heartbleed and Log4j proved that. So corporations began funding open-source projects to keep their own infrastructure stable. But funding brought governance influence. The top Linux kernel contributors aren't hobbyists scratching personal itches. They're engineers employed by Google, Microsoft, Red Hat, Intel, and Huawei, steering the roadmap toward their employers' needs. Kubernetes evolves in ways that benefit Google Cloud. PyTorch evolves in ways that benefit Meta's AI stack.

The projects became dependent on corporate funding. But the corporations became equally dependent on the projects. If Google pulled out of Kubernetes, the project would struggle. If Kubernetes collapsed, Google Cloud would struggle. So Google funds it more, which deepens the entanglement, which makes withdrawal more costly, which demands more funding. The snake eats its own tail.

Google and Amazon compete ferociously in cloud computing, but they cooperate on the same open-source infrastructure that both their businesses require. They're rivals building on shared foundations that neither can afford to let fail and neither fully controls. The commons isn't independent anymore — but neither are the corporations.

Raymond imagined the bazaar as freedom from institutional dependency. What emerged is mutual capture. The cathedral could fire its architects. The bazaar's corporate sponsors can't walk away from the bazaar, and the bazaar can't survive without them. Independence became entanglement — and the entanglement, paradoxically, is what makes the system work.

The Essay Worth Rereading

Raymond saw something real about how coordination works in networks. He was right that the bazaar model could produce software of extraordinary quality and scale. He was right that decentralized development could solve problems that centralized approaches couldn't. He was right that open-source would reshape the industry.

He was wrong about the institutional vacuum. The bazaar didn't eliminate the need for cathedrals — it changed what cathedrals do. They no longer build the infrastructure. They build on top of it, around it, and through it. The most powerful technology companies in the world are cathedral organizations that have learned to cultivate bazaars for strategic advantage.

"The Cathedral and the Bazaar" is worth rereading in 2026 not because it predicted the future correctly — no essay could, across three decades — but because it identified dynamics that, once set in motion, produced outcomes no one predicted. The bazaar made software free, and free software made more software. The cathedrals adapted, and their adaptation made the bazaar more important, not less. Raymond's binary became a symbiosis that neither model, alone, could have produced.

The essay ends with Raymond quoting Robert Browning: "A man's reach should exceed his grasp, or what's a heaven for?" The reach exceeded. The grasp caught something different than expected. That's not a failure of vision. That's how ideas work when they meet reality.

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 — 158 base instructions with 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 — 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) — 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 — 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

Investing in the Jevons Expansion

A.C. Jokela — Thu, 05 Mar 2026 14:00:00 GMT

This is the sixth piece in a series applying the Jevons Paradox framework to AI economics. The prior five built the theoretical case:

The Paradox of Cheap Compute established the historical pattern — every time the cost of compute fell by an order of magnitude, total consumption expanded far beyond the efficiency gain.
The Jevons Counter-Thesis argued that AI displacement models systematically undercount the demand expansion that follows when cognitive labor gets cheaper.
Moore's Law for Intelligence mapped the inference cost curve and showed it mirrors early Moore's Law.
Something Big Is Happening — And Something Big Is Missing applied the framework to a specific displacement scenario and showed where the analysis breaks down.
The AI Vampire Is Jevons Paradox identified the binding constraint: human judgment doesn't scale the way compute does.

This piece asks the practical question: if you believe the framework, what follows?

I should be clear about what this is and what it isn't. This is not financial advice. I'm not recommending specific trades, allocations, or timing. What I'm doing is mapping a structural argument — Jevons-style demand expansion in AI — onto the physical and economic layers that expansion must pass through. The goal is to identify where expansion creates bottlenecks, because bottlenecks are where pricing power concentrates.

The key insight is that you don't need to pick which AI company wins. You don't need to know whether OpenAI, Anthropic, Google, or some company that doesn't exist yet captures the application layer. What you need to identify are the fixed-supply inputs that every AI company needs regardless of who wins. The expansion has to flow through certain physical chokepoints, and those chokepoints are investable.

The Framework in One Paragraph

For readers coming to this series fresh: Jevons Paradox describes what happens when a critical input gets dramatically cheaper. The intuitive expectation is that total spending on that input falls. The historical reality is the opposite — demand expands beyond the efficiency gain, and total consumption increases. Coal in the 19th century — as Jevons himself documented in The Coal Question — transistors in the 20th, bandwidth in the 21st. The prior pieces in this series argue that AI inference costs are following the same curve, with the same structural conditions that produced Jevons outcomes in every prior case. If that argument holds, then what matters isn't whether AI gets more efficient — it's where the resulting demand expansion hits physical constraints.

The Objection That Isn't

The most common pushback I get on this series is some version of: "GPUs are hitting diminishing returns, capex is already enormous, and there's a natural ceiling on how far the expansion can go." Variations appear in coverage from Northeastern and illuminem, often framed as a correction to the Jevons thesis.

It's a reasonable-sounding objection. It's also wrong — and understanding why it's wrong actually strengthens the Jevons case.

The objection treats a technology-specific constraint as an input-level constraint. GPUs hitting diminishing returns doesn't mean inference is hitting diminishing returns. It means GPUs are reaching the end of their particular S-curve. But GPUs aren't the only way to run inference. Custom ASICs, TPUs, NPUs, and novel architectures are opening entirely new cost curves below the GPU curve. The GPU plateau isn't a ceiling — it's a handoff.

The numbers are already visible. Broadcom controls roughly 70% of the custom AI ASIC market, reporting \$5.2 billion in AI semiconductor revenue in Q3 alone, with five major hyperscaler customers driving demand. Marvell's custom XPU pipeline spans AWS, Google, Meta, and Microsoft, with AI revenue reaching \$2.6 billion in FY2026. Google's TPU transition from v6 to v7 delivered a roughly 70% cost-per-token reduction. Taalas, a startup building hardwired inference chips, claims 1000x performance per watt versus general-purpose GPUs. Custom ASICs handle an estimated 20% of inference workloads today and are projected to reach 70–75% by 2028, with custom ASIC shipments growing at 44.6% annually versus 16.1% for GPUs.

Every prior Jevons cycle worked exactly this way. Newcomen's engine didn't just get incrementally better — it was replaced by Watt's engine, then Corliss, then turbines. Each new technology started a fresh S-curve before the previous one fully flattened. Moore's Law didn't ride a single technology either — as Chris Miller chronicles in Chip War, bipolar gave way to NMOS, then CMOS, then FinFET, now gate-all-around. The pattern is always multiple overlapping S-curves, each beginning before the last one peaks.

The data supports the mechanism: every 50% reduction in inference cost has been associated with a 200–300% increase in deployment. That's textbook Jevons elasticity.

"Diminishing returns on GPUs" isn't a ceiling on inference. It's the moment the next technology takes over. That's the mechanism of Jevons Paradox, not a counterpoint to it.

The Investment Layers

If Jevons-style expansion is real, it has to flow through physical infrastructure. I think about this in four layers, ordered from deepest (most expansion-certain) to shallowest (most speculative).

Layer 1: Energy and Power

Energy is the binding constraint. If AI demand expands at anything close to Jevons rates, someone has to generate the electricity. Data center electricity demand is on track to double this year, with the sector's total consumption surpassing Canada's national usage.

The structural problem is deeper than just demand growth. As Vaclav Smil details in Energy and Civilization, energy transitions are slow precisely because the physical infrastructure is massive and long-lived. Roughly 70% of the U.S. electrical grid was built between the 1950s and 1970s. Much of it is approaching end-of-life at the exact moment AI is driving the largest incremental demand increase in decades. This isn't a problem that resolves quickly. Power plants take years to permit and build. Grid transmission upgrades take longer.

Nuclear is where the smart money is moving. Constellation Energy's merger with Calpine creates a fleet of 21 nuclear reactors plus 50 natural gas plants — essentially a baseload power platform positioned for AI demand. Amazon signed a 1.92 GW power purchase agreement at Susquehanna and committed \$500 million to small modular reactor development. These aren't speculative bets on future demand — they're capacity commitments predicated on demand that's already contractually visible.

Hyperscaler capital expenditure tells the same story: \$602 billion planned for 2026, roughly 75% tied to AI infrastructure. Goldman Sachs estimates cumulative AI infrastructure spending of \$1.15 trillion between 2025 and 2027. That capital has to buy electricity, and the electricity has to come from somewhere.

Layer 2: Physical Infrastructure

Between the power plant and the GPU sits an enormous amount of physical equipment: transformers, switchgear, power distribution units, cooling systems, racks, cabling. This is the picks-and-shovels layer — it benefits regardless of which AI stack wins.

Eaton reported data center orders up 70% year-over-year. Transformers have become a bottleneck, with lead times stretching to 18+ months for large power transformers. Vertiv, which makes power management and thermal systems, is sitting on a \$9.5 billion backlog. Liquid cooling, once a niche technology, is becoming standard for high-density AI compute racks.

Grid transmission and distribution may be the most underappreciated bottleneck. You can build a data center in 18 months. Getting grid interconnection can take three to five years. The physical infrastructure required to move power from generation to consumption is the constraint that's hardest to accelerate — and it benefits from AI expansion regardless of which models, chips, or cloud providers ultimately dominate.

Layer 3: Custom Silicon

The GPU-to-ASIC transition described above isn't just evidence that the Jevons expansion continues — it's itself a Jevons trigger. Each new silicon architecture that enters production at lower cost-per-token reopens the demand curve.

Broadcom's AI semiconductor revenue is doubling year-over-year to roughly \$8.2 billion in Q1 FY2026. Marvell's custom XPU pipeline is expanding across all major hyperscalers. Both companies are positioned on the ASIC side of the GPU-to-ASIC transition — the side that's growing at 44.6% versus 16.1%.

Nvidia still dominates training workloads, and Blackwell delivers a 10x cost-per-token reduction for open-source inference models — which is itself a massive Jevons input. But inference is bifurcating. Training demands flexibility and programmability (Nvidia's strength). Inference at scale demands efficiency and cost optimization (where ASICs excel). The market is splitting, and both sides drive expansion.

Layer 4: The Application Tier

This is where it gets speculative. Cloud providers and hyperscalers function as toll booths — they collect revenue proportional to total compute consumed, making them natural beneficiaries of demand expansion. But the application tier above them is where you're picking winners, not betting on expansion itself.

AI-native companies become viable only at cheaper inference price points. The legal tech startup that can offer document review at one-tenth the cost of a junior associate doesn't exist at \$20 per million tokens. It might exist at \$2. It definitely exists at \$0.20. Each step down the cost curve unlocks a new tier of applications.

The contrarian opportunity in this layer is latent demand — the markets that don't exist yet because the service was too expensive for most people. Roughly 80% of Americans who need a lawyer can't afford one. Most small businesses can't afford financial planning. Most students can't afford tutoring. If inference costs follow a Jevons trajectory, these aren't aspirational markets — they're inevitable markets. But investing in them means picking which company captures each one, which is a fundamentally different bet than investing in the infrastructure that serves all of them.

Who Else Is Making This Bet

This framework isn't contrarian anymore. Satya Nadella tweeted "Jevons paradox strikes again!" when DeepSeek demonstrated cheaper inference without reducing demand. Microsoft's AI revenue hit \$13 billion, up 175% year-over-year. Fortune noted that Nadella's optimism was explicitly grounded in the paradox — cheaper AI means more AI, not less.

Andreessen Horowitz made the economic case directly: cheaper tokens unlock more demand than efficiency saves. Their thesis is that foundation model economics follow the same curve as prior compute economics — falling costs expand the addressable market faster than they reduce per-unit revenue.

NPR's Planet Money covered the thesis in mainstream terms, bringing Jevons Paradox from an obscure 19th-century economic observation to a household framework for understanding AI economics. Nathan Witkin's analysis showed that employment in software development, translation, and radiology increased after GPT-3 — exactly the demand expansion the model predicts. Markman Capital called the "flawed consensus" of GPU diminishing returns "one of the most dangerous misreadings of the current market."

Deloitte, McKinsey, and Bain are all projecting massive infrastructure buildout. McKinsey's \$7 trillion estimate for data center scaling reflects the same underlying logic: if demand expands as costs fall, the physical infrastructure to support it is the bottleneck.

Jevons went from an obscure economics reference to a mainstream investment framework in roughly twelve months. That's not because it's trendy — it's because the data keeps confirming the pattern.

Where the Thesis Could Be Wrong

Intellectual honesty requires mapping the failure modes.

Demand elasticity might be lower than historical precedent. Every prior Jevons cycle involved inputs with massive latent demand — coal for industrial heat, transistors for consumer electronics, bandwidth for media. AI inference might not have the same depth of latent demand. If the tasks AI performs well are narrower than the tasks coal or transistors enabled, the expansion could stall earlier than the model predicts.

Regulatory intervention could cap the expansion. Energy policy, AI regulation, data center permitting restrictions — any of these could artificially constrain the physical infrastructure that the expansion requires. Jevons Paradox describes an economic dynamic, not a law of physics. It can be overridden by policy.

The biological ceiling is real. As I argued in The AI Vampire Is Jevons Paradox, human judgment is the input that doesn't scale. If every Jevons expansion in AI ultimately concentrates demand on human decision-making, and human decision-making has genuine cognitive limits, the expansion hits a different kind of constraint — one that can't be solved with more silicon or more power.

Timing risk is the most likely failure mode. The direction of the thesis could be correct while the timeline is wrong. Infrastructure bottlenecks might resolve more slowly than demand builds, creating periods of overinvestment followed by correction. The historical base rate favors Jevons, but base rates describe probabilities, not certainties. Plenty of investors have been right about the direction and still lost money because they were wrong about the timing.

The Physical Footprint of Expansion

The deepest layers — energy and physical infrastructure — are the safest Jevons bets. They benefit from AI demand expansion regardless of which models, chips, or companies win. You don't need to know whether GPT-7 or Claude 6 is the better model to know that both of them will need electricity, transformers, cooling, and grid capacity.

The further up the stack you go, the more you're picking winners rather than betting on expansion. Custom silicon is a strong middle ground — the GPU-to-ASIC transition is structural, and the companies positioned on the right side of it have visible demand. But the application tier is where the uncertainty concentrates, and that's where most retail investors focus their attention.

The expansion has a physical footprint. Every token generated requires electricity. Every data center requires grid interconnection. Every custom ASIC requires a fab slot. Every cooling system requires water. The Jevons expansion, if it plays out as the framework predicts, will be visible not in stock prices or earnings calls but in the physical world — in power generation capacity, in transformer lead times, in grid interconnection queues, in cooling system orders.

Jevons won't announce itself. It never does. It shows up in electricity bills, in transformer backorders, in cooling system lead times, in the quiet scramble to secure power purchase agreements years in advance. The signal isn't in what people say about AI. It's in what they're building to support it.

Generating Technical Handbooks with AI: Parallel Agents, Source Code, and 2,400 Pages

A.C. Jokela — Wed, 04 Mar 2026 17:00:00 GMT

Over the past few weeks I've generated three technical handbooks using Claude Code with Opus 4.6 and the Claude Agent SDK. The Ballistics Engine Handbook — 641 pages across 66 chapters covering computational exterior ballistics. The Lattice Handbook — 868 pages across 84 chapters documenting an entire programming language. The Sampo CPU Handbook — 871 pages across 82 chapters walking through the design, programming, and hardware implementation of a 16-bit RISC CPU.

That's roughly 2,400 pages and 232 chapters of deeply technical content, generated from real codebases by AI agents that read actual source files before writing about them.

These aren't ChatGPT summaries. They aren't the kind of vaguely plausible prose you get from asking an LLM to "write a book about X." Each handbook was produced by a framework that launches 10-12 Claude agents in parallel, each assigned a Part of the book, each with access to the real project source code, each writing LaTeX chapters grounded in actual implementation. The result is documentation that references real functions, real CLI flags, real instruction encodings — because the agents read the code before writing about it.

Why Handbooks?

Developer documentation is chronically underwritten. Most projects ship with a README, maybe some auto-generated API docs, and a handful of examples. If you're lucky, there's a tutorial. The gap between "reference documentation" and "understanding how to actually use this thing" is enormous, and it's the gap where handbooks live.

A good handbook explains not just what the API surface looks like but why the design decisions were made, how the pieces fit together, what the edge cases are, and how to use the tool effectively in real-world scenarios. Writing one for a complex project is a multi-month effort. For a solo developer maintaining a project in their spare time, it's effectively impossible — the opportunity cost is too high.

AI changes the math. If you can point agents at source code and get a coherent, accurate, 600-page handbook, the cost drops from months to hours. The output isn't a finished book — it's a first draft that needs review, editing, and correction. But it's a dramatically better starting point than a blank page.

The Source-Aware Approach

What makes this different from asking a model to "write a book about ballistics" or "write a book about CPU design" is that the agents have access to the actual codebase.

Each agent runs with its working directory set to the real project — the ballistics-engine Rust crate, the Lattice C compiler, or the Sampo CPU's Verilog and assembly. The agents have Read, Glob, and Grep access. They can open source files, search for function signatures, trace data structures, and understand the actual implementation before writing about it.

The chapter definitions in the generation script include explicit source file references:

sourceReferences: ["src/atmosphere.rs", "src/drag.rs", "src/drag_model.rs"]

When an agent starts writing a chapter on atmosphere modeling, the prompt tells it: read src/atmosphere.rs first. The agent opens the file, sees the ICAO standard atmosphere implementation, finds the actual function signatures and constants, and writes a chapter grounded in what the code actually does — not what a language model thinks atmosphere modeling might look like.

For the Ballistics Engine Handbook, this means chapters that reference real Rust functions, real CLI flags from src/cli_api.rs, and real numerical methods from the solver. For the Sampo CPU Handbook, it means chapters that include actual Verilog module definitions, actual ISA encodings from the architecture spec, and actual assembler passes from the Rust toolchain. The agent reads ENCODING.md and writes about instruction formats using the real bit layouts, not invented ones.

This source-awareness is the difference between documentation that happens to sound plausible and documentation that is grounded in implementation. It doesn't eliminate hallucination — I'll get to that — but it dramatically reduces it.

The Parallel Agent Framework

The core of the system is a TypeScript file called generate.mts that orchestrates parallel Claude Agent SDK sessions. Each handbook has its own version, but the architecture is the same.

The book structure is defined as TypeScript data:

interface Chapter {
  number: number;
  title: string;
  filename: string;
  description: string;
  pages: number;
  sections: Section[];
  sourceReferences: string[];
}

interface Part {
  number: number;
  title: string;
  description: string;
  pageTarget: number;
  chapters: Chapter[];
}

Each Part contains its chapters, each chapter lists its sections, page target, and which source files the agent should read. The Ballistics Engine Handbook has 9 Parts. The Lattice Handbook has 11. The Sampo Handbook has 11 plus appendices.

When you run npx tsx generate.mts, every Part launches as a separate Claude agent simultaneously:

const promises = [
  ...BOOK_STRUCTURE.map((part) => runPartAgent(part)),
  runAppendixAgent(),
];
const settled = await Promise.allSettled(promises);

For the Sampo Handbook, that's 12 agents running in parallel. Each one receives a detailed prompt containing:

The full table of contents (so it knows what other Parts cover — cross-reference awareness)
Its specific chapters, sections, descriptions, and page targets
Source file references to read before writing
A style guide (more on this below)
LaTeX formatting conventions, custom environments, and commands

Each agent calls the Claude Agent SDK's query() function with Opus 4.6, running in the source project's directory:

for await (const message of query({
  prompt,
  options: {
    cwd: "/Users/alexjokela/projects/ballistics-engine",
    allowedTools: ["Read", "Glob", "Grep", "Write", "Bash"],
    permissionMode: "bypassPermissions",
    maxTurns: 30 + part.chapters.length * 8,
    model: "claude-opus-4-6",
  },
})) { ... }

The agents write LaTeX .tex chapter files to a chapters/ directory, which are \include{}'d by the main book.tex. Each agent logs its progress to a per-part log file. When all agents finish, the script reports results — duration, success/failure status, and file sizes for each generated chapter.

Promise.allSettled() is important here. If one Part fails — the agent hits a turn limit, encounters an error, or produces incomplete output — the other nine or ten agents keep running. You can rerun a single failed Part with --part=N without regenerating the entire book.

The parallelism is the key performance insight. A single agent writing all 82 chapters of the Sampo Handbook sequentially would take many hours. Twelve agents writing in parallel, each handling 7-8 chapters, complete the entire book in roughly 45 minutes to an hour of wall-clock time. The agents don't share state or coordinate — they work independently, which is what makes parallelism straightforward.

The Style Guide Problem

Each handbook has a distinct voice, defined in a CLAUDE.md file that the agent reads before starting:

The Ballistics Engine Handbook: "Technical, authoritative, and practical. Inspired by O'Reilly's Definitive Guide series." Use real cartridge data in every example. Show the physics. Include safety warnings for anything involving pressure or load data.

The Lattice Handbook: "Conversational, precise, and playful. Inspired by Why's (Poignant) Guide to Ruby and Eloquent Ruby." Use chemistry and materials science metaphors for the phase system — values are materials that can be fluid or crystallized, freezing is literally crystallization.

The Sampo CPU Handbook: "Technical, authoritative, and hands-on. Think of it as a lab notebook that became a textbook." Show both hex and binary for instruction encodings. Use real code from the project — never invent hypothetical assembly or Verilog.

Maintaining consistent voice across 10-12 agents writing simultaneously is a genuine challenge. Each agent reads the same style guide, but interpretation varies. What works: detailed, specific instructions with concrete examples of what to do and what not to do. All three guides include an explicit list of banned words — "simple," "easy," "trivial," "obviously," "just" — because those words make struggling readers feel bad and they're the first thing an LLM reaches for when transitioning between concepts.

What doesn't work: vague instructions like "be conversational" or "keep it engaging." Every agent interprets those differently. The Lattice Handbook's metaphor system — where the phase-based type system is described using chemistry analogies — required explicit instructions: "Values are materials. Freezing is crystallization. Thawing is melting. Arenas are regions where crystals are stored." Without that specificity, some agents would use the metaphors and others wouldn't, and the book would feel like it had multiple authors — which, in a sense, it does.

The "no AI self-reference" rule is also critical. The style guide explicitly states: "Book content must read as if written entirely by the author — no references to AI assistance." Without this, agents occasionally produce meta-commentary about their own generation process, which breaks immersion.

What Goes Wrong

An honest assessment of failure modes:

Hallucinated APIs. Despite source-awareness, agents sometimes invent function signatures, CLI flags, or configuration options that don't exist. This is the most dangerous failure mode because it reads authoritatively. The mitigation — explicit source file references — reduces but doesn't eliminate it. Every chapter needs a review pass where someone checks that the referenced functions and flags actually exist.

Uneven depth. Some chapters come out thin — hitting the minimum viable content but lacking the depth a handbook reader expects. Others balloon beyond their page target with redundant examples. Page targets in the chapter definitions help, but agents treat them as loose guidelines.

Cross-reference gaps. Agent writing Part III doesn't know exactly what Agent writing Part VIII said. Each agent gets the full table of contents for awareness, but not the actual content of other Parts. This means cross-references are sometimes vague ("as we'll see in Chapter 25") or occasionally contradictory. The LaTeX \cref{} system helps — agents insert labels and cross-references that at least compile correctly — but semantic consistency across Parts requires a human review pass.

LaTeX formatting inconsistencies. Different agents make different choices about when to use \begin{notebox} vs. \begin{tipbox}, how to format code listings, whether to put output inline or in a separate listing. The style guide constrains this, but the variation is noticeable.

The confident-but-wrong problem. AI writes with unwavering authority about implementation details it misread. An agent might open a Rust file, misinterpret a match arm, and write a paragraph confidently explaining behavior that the code doesn't actually produce. This is the hardest failure to catch because the prose sounds correct and references real source files — you have to actually trace the logic to find the error.

The regeneration workflow handles most of these: rerun a single Part with --part=N, review the output, iterate. A full regeneration of one Part takes about five minutes — fast enough to make iterative refinement practical.

Results and Numbers

Across the three handbooks:

	Ballistics Engine	Lattice	Sampo CPU
Pages	641	868	871
Chapters	66	84	82
Parts	9 + Appendices	11	11 + Appendices
Parallel Agents	10	11	12
Source Language	Rust	C	Verilog/Rust/Assembly
Style	O'Reilly Guide	Why's Poignant	Lab Notebook

The model for all three is Claude Opus 4.6. Total generation time per handbook is roughly 45-60 minutes wall-clock with parallel agents — compared to what would be 8+ hours running sequentially.

What This Costs

All of this work was done on a Claude Max subscription at \$200/month. At that tier, you get access to Opus 4.6 through Claude Code with what Anthropic describes as "significantly higher" usage limits than the \$20 Pro plan. How much higher? That's where things get vague.

Anthropic doesn't publish concrete token limits or rate caps for Max. The pricing page says you get "9x more usage" than Pro — but 9x of what? The Pro plan's limits are themselves unstated. You get a usage meter in the interface that fills up and eventually throttles you, but there's no documentation of what the meter measures, how it maps to tokens, or what the actual ceiling is. When you hit the limit, you're told to wait or upgrade. The \$100/month tier exists between Pro and Max, and Anthropic is equally vague about how it differs from either.

In practice, the Max subscription was sufficient to generate all three handbooks — 2,400 pages of content produced by dozens of parallel agent sessions running Opus 4.6 — within a single billing cycle, without hitting much throttling that would have blocked the work. Whether that's representative of the limit or I happened to stay under it, I genuinely don't know. Anthropic's refusal to publish concrete limits makes it impossible to do the math in advance. You can't calculate cost-per-page or tokens-per-dollar because the denominator is secret.

This is a strange posture for a company selling a product. The \$200/month price point positions Max as a professional tool — something you'd expense to a business or justify as a productivity investment. Professional tools come with specs. You know how many build minutes your CI plan includes. You know how many API calls your database tier supports. You know how many seats your Slack plan covers. Anthropic is asking for \$200/month and answering the question "what do I get for that?" with essentially "a lot — trust us."

For what it's worth, the alternative would have been the API, where pricing is transparent: Opus 4.6 runs roughly \$15 per million input tokens and \$75 per million output tokens. Back-of-envelope math suggests that generating a single 800-page handbook through the API — with all the source file reading, prompt construction, and chapter output — would consume something in the range of several hundred dollars of tokens. Three handbooks would plausibly run \$500-1,000+ through direct API billing. If that estimate is in the right ballpark, the Max subscription is a genuine bargain for this kind of heavy-generation workload — you just have to take it on faith because Anthropic won't show you the numbers.

For comparison against the alternative: a professional technical writer producing this volume of deeply technical content — requiring them to understand exterior ballistics physics, or compiler internals, or CPU microarchitecture — would represent months of full-time work at rates that would make the API costs look trivial. The AI-generated output is a first draft, not a finished product. But it's a first draft that covers the full scope, references real source code, and provides a structure that would take weeks to produce manually.

What This Means for Documentation

This connects to a theme I've been writing about in the Jevons Paradox series: documentation is a classic example of latent demand suppressed by cost.

Most open-source projects have mediocre documentation because good documentation is expensive to produce. A solo maintainer choosing between implementing features and writing a 600-page handbook will choose features every time. The handbook doesn't get written — not because it wouldn't be valuable, but because the cost of producing it exceeds the maintainer's available time.

If handbook generation becomes cheap enough, every serious project gets one. The total volume of technical documentation doesn't decrease — it explodes. And the human role shifts from production to curation. The expensive work isn't writing 600 pages anymore. It's defining the structure — deciding what the book should cover, in what order, at what depth. It's reviewing the output for accuracy — catching hallucinated APIs, verifying that code examples actually run, ensuring cross-references are coherent. It's editing for voice — making sure the playful tone of the Lattice Handbook doesn't lapse into the authoritative register of the Ballistics Handbook.

This is Jevons in miniature. Cheaper documentation doesn't mean less documentation work. It means more documentation exists, and humans focus on the higher-judgment parts: structure, accuracy, and editorial voice.

The Framework Is the Product

The generate.mts pattern is reusable. The same architecture — define a book structure in TypeScript, launch parallel agents with source code access, collect LaTeX output — applies to any project with a codebase and a desired handbook.

The bottleneck isn't the AI's ability to write. It's the human's ability to define what the handbook should contain and whether the output is correct. Defining the structure for the Sampo Handbook — 11 Parts, 82 chapters, hundreds of sections, source file references for each — took longer than running the generation. Reviewing and correcting the output takes longer than generating it.

That bottleneck is itself a Jevons observation. When the cost of producing prose drops to near zero, the scarce input becomes human judgment about what the prose should say and whether it's right. The generation is the cheap part. The thinking is the expensive part. As it always has been.

The AI Vampire Is Jevons Paradox

A.C. Jokela — Wed, 04 Mar 2026 14:00:00 GMT

Steve Yegge's "The AI Vampire" has been circulating among developers and managers for the past few weeks, and it's striking a nerve. The core argument: AI makes you dramatically more productive — Yegge estimates 10x or more — but companies capture the entire surplus. You don't get a shorter workday. You get 10x the output at the same hours, with the cognitive load compressed into pure decision-making. The result is burnout on a scale the industry hasn't seen before. His prescription is blunt: calculate your \$/hr, work three to four hours a day, and refuse to let the vampire drain you dry.

It's a compelling piece, written with Yegge's characteristic directness and self-awareness. And it describes something real. But as I read it, I kept seeing something he doesn't name — a pattern I've been writing about for months.

This is the fourth piece in what has become a series on Jevons Paradox and AI economics. The first traced the paradox through the semiconductor industry. The second argued that AI displacement scenarios systematically undercount demand expansion. The third explored what happens when the cost of intelligence follows a Moore's Law trajectory. Along the way, I responded to Matt Shumer's displacement argument with the same framework.

Those pieces all looked at the macro picture — markets expanding, new industries forming, total economic activity growing. Yegge is describing the micro picture. What it actually feels like to be a human worker inside a Jevons expansion. And what he's describing, whether he uses the term or not, is Jevons Paradox operating on human attention.

The Jevons Pattern, One More Time

The pattern is simple enough to state in a sentence: when a critical input gets cheaper, demand expands beyond the efficiency gain. Total consumption of the input rises, not falls.

Coal got cheaper per unit of useful work. Total coal consumption surged as new applications became viable. Transistors got cheaper per unit of compute. Total compute spending grew by orders of magnitude. Bandwidth got cheaper per unit of data. Total data consumption exploded. The per-unit savings are overwhelmed by the explosion in total units demanded.

In my previous pieces, I applied this at the macro level. Cognitive output gets cheaper through AI. New industries emerge. Demand for cognitive work expands. The economy restructures around abundant, cheap intelligence. That argument is about markets, GDP, and employment categories — the aerial view.

But Jevons has always had a micro counterpart. When coal got cheaper, individual mines didn't shut down early — they ran harder, longer, extracting more because the economics now justified it. When compute got cheaper, individual developers didn't write less code — they wrote vastly more, because the constraints that had limited what was practical evaporated. The expansion creates pressure at every level of the system, not just at the top.

The macro story is about new markets forming. The micro story is about what happens to the people at the point of production — the ones whose labor is the input that just got cheaper.

What Yegge Is Actually Describing

Yegge's framework centers on a value-capture trap. He presents two scenarios:

Scenario A: AI makes you 10x more productive. Your company captures the surplus. You now produce 10x the output at the same salary and hours. The company benefits. You burn out.

Scenario B: You recognize the \$/hr math. If you were worth \$150/hr before AI and now produce 10x the output, your effective rate should be \$1,500/hr — or equivalently, you should work one-tenth the hours for the same salary. You work three to four hours a day, produce what used to take a full day, and keep your sanity.

He frames this as a choice between being exploited and being strategic. And he's honest about the difficulty of Scenario B — most people can't negotiate a three-hour workday, most companies won't accept it, and the competitive dynamics push relentlessly toward Scenario A.

Yegge's most vivid metaphor is that "AI has turned us all into Jeff Bezos." At Amazon, Bezos sat atop a machine that handled volume — logistics, warehousing, customer service, shipping — while he focused exclusively on high-leverage decisions. AI does the same thing for individual workers. It absorbs the volume work — the boilerplate code, the routine analysis, the standard responses — and leaves you with a residue of pure judgment calls. Every decision is consequential. Every hour is cognitively expensive.

He also has an important moment of self-awareness. Yegge acknowledges that his own experience — forty years of engineering, unlimited AI tokens, deep familiarity with the tools — represents "unrealistic beauty standards" for the average developer. He's the equivalent of the fitness influencer whose workout routine is their full-time job. Most people don't have his context, his autonomy, or his leverage to negotiate Scenario B.

And he identifies a crucial accelerant: the startup gold rush. AI has made it cheap enough to launch a company that "a million founders are chasing the same six ideas." This intensifies competition, which intensifies the pressure to push the output dial higher, which feeds the vampire.

The Jevons Connection

Here's what Yegge is describing in Jevons terms.

AI makes cognitive output dramatically cheaper. Jevons predicts that demand won't fall in response — it will increase. That's exactly what happens. Companies don't say "same output, fewer hours." They say "10x the output, same hours." The efficiency gain doesn't reduce consumption of the input. It increases consumption. This is the paradox, and it is playing out precisely as the model predicts.

But there's something different about this Jevons cycle — something that doesn't have a precedent in the historical cases.

Coal doesn't get tired. Transistors don't burn out. Bandwidth doesn't need a nap. Every prior Jevons cycle involved an inert input. You could mine more coal, fabricate more chips, lay more fiber. When demand expanded, supply expanded to meet it, and the system found a new equilibrium at higher volume. The input didn't resist. It didn't have a biological ceiling.

Human attention does.

AI creates a concentration effect that Yegge describes precisely: it absorbs high-volume, routine work and leaves humans with a residue of pure judgment. The judgment work is, by definition, the most cognitively expensive kind of work — the kind that requires deep focus, contextual understanding, and the willingness to be wrong. And demand for this judgment work expands Jevons-style as AI makes the overall process cheaper. More projects get launched. More code gets written. More decisions need to be made. The volume of judgment calls scales with the volume of output, even as AI handles everything else.

The problem is that the biological supply of deep, focused judgment is fixed. The deep work literature — Cal Newport and others have documented this extensively — converges on roughly three to four hours per day as the upper bound for sustained, cognitively demanding work. This isn't a cultural preference or a lifestyle choice. It's a constraint imposed by neurobiology. Attention is a depletable resource that recovers on a fixed biological schedule.

This is the first Jevons cycle where expanding demand hits a hard biological ceiling on the input.

Yegge's startup observation is also a Jevons phenomenon. AI made starting a company cheaper, so the number of startups exploded. More startups means more competition. More competition means more pressure to maximize output per person. The expansion creates its own acceleration — a feedback loop where cheaper cognitive output produces more ventures, which produce more demand for cognitive output, which increases the pressure on the humans in the loop.

And the "unrealistic beauty standards" problem has a Jevons name too: it's the efficiency benchmark effect. In every Jevons cycle, the most efficient user of the cheaper input sets the competitive pace for everyone else. The factory that adopted steam power first forced every competitor to adopt it or die. The company that adopted AI first forces every competitor to match its output-per-employee or lose. Yegge, with his forty years and unlimited tokens, is the equivalent of the first factory with a Watt engine. His output level becomes the standard against which everyone is measured — even though most people can't replicate his efficiency.

Where the Ceiling Matters

In every prior Jevons cycle, the resolution was supply expansion. Coal demand surged — mine more coal. Compute demand surged — fabricate more chips. Bandwidth demand surged — lay more fiber. The system found equilibrium at higher volume because the input could scale.

Human cognitive capacity doesn't scale. You can't mine more judgment. You can't fabricate more attention. The three-to-four-hour ceiling on deep work isn't going to move because a company's OKRs demand it.

This means a Jevons expansion in demand for human judgment has to resolve differently than prior cycles. There are really only three paths:

Better tooling that reduces the judgment burden. AI gets good enough to handle more decisions autonomously, pushing the human-in-the-loop threshold higher. The frontier of what requires human judgment retreats as AI capability advances. This is already happening — the boundary between "AI can handle this" and "a human needs to decide" is moving rapidly. But it's not moving fast enough to outpace the demand expansion, which is why Yegge's burnout observation is accurate right now even if the long-term trajectory favors less human involvement.

Organizational restructuring. More people, fewer high-stakes decisions each. Instead of one developer making judgment calls on 10x the output, you have three developers each handling a manageable portion. This is the "hire more" response, and it pushes back against the cost-reduction motive that drives Scenario A. Companies that pursue this path may produce better outcomes but at higher cost, which competitive dynamics tend to punish.

Cultural pushback. Yegge's \$/hr formula. Workers internalize the fixed-supply economics of their own attention, price it accordingly, and refuse to let demand expansion drain it below sustainable levels. This is individually rational but collectively difficult — it requires either enough leverage to negotiate, or enough cultural shift to change expectations.

Yegge's \$/hr formula is, in Jevons terms, an attempt to set equilibrium for a fixed-supply resource. It is the cognitive equivalent of OPEC production quotas — an effort to prevent the price of a scarce input from being driven to zero by unconstrained demand. And like OPEC quotas, it works only if enough participants enforce it.

What This Means for the Macro Picture

I want to be honest about what Yegge's observation adds to the framework I've been building.

My previous pieces argued that when cognitive output gets cheaper, demand expansion will create new economic activity that exceeds the displacement. I stand by that argument. But I underweighted the human-in-the-loop constraint. The demand expansion is real — new markets form, new companies launch, total economic activity grows. But every unit of that expanded activity still requires some quantum of human judgment, and that judgment runs on biological hardware with a fixed daily capacity.

This doesn't invalidate the macro Jevons argument. Demand will expand. New industries will form. Total employment will restructure, not collapse. But the human attention constraint acts as a speed governor on the expansion. The economy can't scale cognitive output infinitely by just pushing the existing workforce harder, because the existing workforce has a biological ceiling on the input that matters most.

This argues for Yegge's three-to-four-hour workday not as a lifestyle aspiration but as something closer to an economic inevitability — the natural equilibrium point for a Jevons cycle operating on a fixed-supply input. When demand for an input exceeds the maximum sustainable rate of supply, the system must either find a substitute (AI handling more decisions autonomously), expand the supplier base (more workers, shorter hours each), or accept a constrained equilibrium (the three-hour workday). Some combination of all three is likely.

The interesting implication is that the Jevons expansion and the burnout crisis are not contradictory phenomena. They're the same phenomenon viewed from different vantage points. The macro analyst sees demand expanding and new economic activity forming. The individual worker sees an unsustainable cognitive load. Both are correct. They're describing different aspects of the same system adjusting to a radically cheaper input.

The Vampire and the Paradox

Matt Shumer worries about displacement — losing your job to AI. Steve Yegge worries about what happens to the people who aren't displaced — who keep their jobs but get vampired. Both are describing real phenomena. Neither is the whole picture.

The Jevons framework encompasses both. Demand expansion creates new work, answering Shumer's displacement concern — the economy doesn't contract, it restructures. But the expansion concentrates cognitive load on the humans who remain in the loop, confirming Yegge's burnout observation — because the one input AI can't replace is the one input that can't scale.

Shumer's error is modeling only the displacement side. Yegge's error is modeling only the extraction side. The full picture includes both: an economy producing vastly more cognitive output, creating genuinely new economic activity, while simultaneously pushing the humans at the center of it toward a biological wall.

The vampire is real. It's also, like every Jevons cycle, a signal that something genuinely new is being created — that demand is expanding into territory that didn't exist before. The burnout isn't incidental to the expansion. It's a symptom of it. And like every prior Jevons cycle, the system will find an equilibrium — not because anyone plans it, but because a fixed-supply input eventually forces one. The question is how much damage the vampire does before we get there.

Something Big Is Happening — And Something Big Is Missing

A.C. Jokela — Sun, 01 Mar 2026 14:00:00 GMT

Matt Shumer's "Something Big Is Happening" has been making the rounds — forwarded by founders, reposted by VCs, shared by worried parents and recent graduates. If you haven't read it, the core argument is straightforward: AI capabilities are advancing at an unprecedented pace, the public doesn't appreciate how fast things are moving, and roughly half of entry-level white-collar jobs will be displaced within one to five years. He frames this as a personal warning to the non-technical people in his life, drawing an explicit parallel to February 2020 — the moment before COVID when the warnings were there but most people weren't listening.

It is a well-written, earnest piece, and it resonated for a reason. The capability gains are real. The perception gap is real. The practical advice is genuinely useful. Shumer deserves credit for engaging seriously with a question that most people in his position — CEO of an AI company — have financial incentives to either hype or deflect.

But the piece has a hole in the center of it, and it's the same hole that appears in nearly every AI displacement argument I've encountered. I've written about this through the lens of Jevons Paradox, explored it as a direct counter-thesis to displacement scenarios, and examined what happens when you apply Moore's Law to the cost of intelligence itself. The pattern is consistent, and Shumer's piece reproduces the analytical error at its core: it models what AI replaces without modeling what AI creates.

The Steelman

Before critiquing the piece, I want to present its strongest version in good faith — because Shumer gets several important things right, and dismissing the argument wholesale would be intellectually lazy.

The capability curve is real. METR benchmarks show AI task completion doubling roughly every seven months, possibly accelerating. Shumer cites this data, and it's legitimate. I've experienced the curve firsthand. Over the past year and a half, I've built a high-performance Rust-based ballistics engine and Lattice, an entire programming language with a novel phase-based type system — working across GPT-4, GPT-4o, Claude Haiku, Opus, and most recently Opus 4.6 with Claude Code. The progression itself is the data point. Early models could help with fragments. Today's frontier models reason across thousands of lines of interconnected code — tracking type systems, managing compiler passes, understanding how changes in one module ripple through the rest. These aren't toy demos. They're production-quality projects where the AI operated at the architectural level. The capability gap between late 2024 and early 2026 is genuinely striking.

The perception gap is real too. Shumer makes a point that doesn't get enough attention: most people's experience with AI is limited to free-tier models that lag frontier capabilities by twelve months or more. Someone who tried ChatGPT once in 2024 and found it mediocre is extrapolating from hardware that's already obsolete. The gap between the free experience and the paid frontier experience is larger than most people realize, and Shumer is right to flag it.

The self-improvement feedback loops are real. OpenAI has stated that GPT-5.3 Codex was "instrumental in creating itself." Anthropic's training pipeline uses prior Claude models to evaluate training examples. Dario Amodei predicts AI autonomously building next-generation versions within one to two years. These aren't speculative claims — they're descriptions of current practice, and they compress the improvement timeline.

Shumer's practical advice is sound: use paid tools, select the best available models, spend an hour a day experimenting, build financial resilience, develop adaptability as a core skill. This is good counsel regardless of how the macro picture unfolds.

And the urgency is not manufactured. Whatever you think the economic consequences will be, the pace of capability improvement is unprecedented in the history of technology. Shumer is right that most people are not paying attention. Where he goes wrong is in what he concludes from that observation.

The Substitution Fallacy

Here is Shumer's core analytical error — and the one that most critiques of his piece also miss.

He treats "AI can do X" as equivalent to "AI will replace all humans doing X." His piece moves through a list of job categories — legal work, financial analysis, software engineering, medical analysis, customer service — and for each one, the logic is: AI can now perform this work at a level that rivals human professionals, therefore the humans performing this work are at risk. Implicit in this framing is the assumption that the economy stays roughly the same size, with machines doing work that humans used to do. The number of legal analyses needed stays constant. The number of financial models stays constant. The amount of software stays constant. AI just does it cheaper.

This is the substitution frame, and it has been wrong by orders of magnitude at every prior technological inflection point.

I explored this in detail in my Jevons counter-thesis. The mechanism is straightforward: when a critical input becomes dramatically cheaper, the addressable market for everything that uses that input expands. New use cases emerge that were previously uneconomical. Existing use cases scale to populations that were previously priced out. Total consumption of the now-cheaper input rises even as the per-unit cost falls.

The numbers on latent demand are not speculative. Roughly 80% of Americans who need legal help cannot afford it. Personalized tutoring is a luxury good — \$50 to \$100 per hour puts it out of reach for the average family. Custom software development, at \$50,000 or more per engagement, is inaccessible to most small businesses. Personalized financial planning is available only to households with six-figure investable assets. These aren't hypothetical markets. They are documented, unmet demand suppressed by the cost of the human intelligence required to serve them.

When Shumer writes that his lawyer friend finds AI "rivals junior associates" for contract review and legal research, the Jevons question is: what happens when legal analysis costs one-hundredth what it costs today? The answer isn't "lawyers lose their jobs." It's "hundreds of millions of people who currently have zero legal representation suddenly have access to it." The total volume of legal analysis performed doesn't shrink. It explodes. Whether that explosion employs as many human lawyers as today is a genuine question — but it's a very different question from "AI replaces lawyers," and Shumer's piece never asks it.

The same logic applies to every category on his list. If financial modeling becomes 100x cheaper, every small business gets CFO-grade analysis — a market expansion of orders of magnitude relative to the current financial services industry. If software development becomes 100x cheaper, the barrier between "person with an idea" and "working application" functionally disappears, and the total volume of software produced doesn't shrink — it expands to include millions of applications that nobody would build at current costs.

The Pandemic Analogy Problem

"Think back to February 2020." It's an emotionally effective opening, and it does exactly what Shumer intends — it activates the memory of a time when the warnings were there but most people didn't act until it was too late. As a rhetorical device, it works. As an analytical framework, it's misleading.

COVID was a pure externality. It destroyed without creating. A virus doesn't generate new economic activity as it spreads. It imposes costs, disrupts supply chains, and kills people. The appropriate response was defensive: stockpile supplies, get vaccinated, stay home. The framing of individual survival — how do I get through this — was correct for a pandemic because a pandemic doesn't create opportunity. It just destroys.

Technology transitions are categorically different. They create as they destroy, and historically, the creation overwhelms the destruction. The better analogy — the one Shumer doesn't use — is the semiconductor revolution. Computing destroyed millions of clerical, typist, switchboard operator, and filing clerk jobs. It also created the software industry, the internet economy, the mobile ecosystem, social media, cloud computing, e-commerce logistics, and millions of roles that had no conceptual precursor in the prior economy. Total employment didn't shrink. It restructured and grew.

The pandemic analogy does something else that's analytically costly: it frames the correct response as individual survival. How do I prepare? How do I stay ahead? This is the right question for a virus. It is the wrong question for a technology transition, where the correct frame is not "how do I survive displacement" but "what new things become possible?" Shumer's advice — use the tools, build adaptability, experiment daily — is good advice. But it's embedded in a survivalist frame that misses the larger economic picture. The person who learned to build websites in 1995 wasn't surviving the death of typesetting. They were participating in the creation of something that would be orders of magnitude larger than the industry it disrupted.

A Founder's Experience Is Not the Economy

"I describe what I want built, in plain English, and it just appears."

I believe him. I've had similar experiences. When I built the ballistics engine and Lattice, there were moments where the workflow felt qualitatively different from anything I'd experienced in over three decades of writing software. The capability is real and it's striking.

But Shumer is generalizing from the thinnest part of the adoption curve. A startup founder building prototypes with frontier AI tools is the absolute highest-leverage, lowest-friction use case for current technology. There are no compliance departments. No regulatory review. No integration with legacy systems built on COBOL. No liability frameworks that require a human signature. No union contracts. No procurement cycles measured in fiscal years.

The gap between "a founder can build a prototype in an afternoon" and "a hospital deploys AI-driven diagnostics at scale" is measured in years, not months. Regulatory friction, institutional inertia, liability requirements, and cultural resistance are real. The FDA doesn't move at startup speed. Neither do insurance companies, government agencies, or school districts. These aren't trivial obstacles — they're the mechanisms through which society manages risk, and they exist for reasons.

I don't want to overweight this argument. Institutional friction can be overstated, and appeals to regulation can become a way of avoiding engagement with the underlying capability shift. The important point is narrower: Shumer extrapolates from his personal productivity gain to "nothing done on a computer is safe," and that's an extrapolation error. A founder experiencing sudden personal leverage and projecting that curve onto civilization is a recognizable pattern in tech commentary. It's usually too bullish on the timeline and too narrow on the mechanism.

What Gets Created

This is the biggest gap in Shumer's piece — and the biggest gap in most commentary on AI and employment. He spends thousands of words on what AI can replace. He spends zero words on what AI makes possible for the first time.

I examined this through the Moore's Law for Intelligence framework — the 10x / 100x / 1,000x staircase of what becomes viable as the cost per unit of machine intelligence drops. The historical pattern from semiconductors is unambiguous: each order-of-magnitude cost reduction didn't just make existing applications cheaper. It created entirely new categories of economic activity that were literally unimaginable at the prior price point.

Nobody in 1975 predicted Instagram, Uber, or Spotify. Not because they required new physics — they required compute cheap enough to fit in a pocket. The applications were latent, waiting for the cost curve to reach them.

The same is true for intelligence. We can identify the structural conditions for demand expansion even if we can't predict the specific applications:

Small businesses with CFO-grade financial analysts — not because they hire CFOs, but because AI makes that analysis accessible at \$50 per month instead of \$200,000 per year. Personalized tutoring for every student — not an incremental improvement on existing education, but a qualitative shift in how learning works for the 95% of families who can't afford human tutors. Legal help for the 80% of Americans currently priced out. Preventive medicine embedded in every checkup, where an AI has read every relevant paper published in the last decade and cross-referenced it against the patient's complete history.

And the nature of software engineering itself is changing — not replacing engineers but redefining the skill. The workflow is already shifting from "write code line by line" to "describe architecture, direct implementation, review output." At 100x cheaper inference, small teams build products that previously required departments. At 1,000x cheaper, the barrier between having an idea and having working software effectively disappears. That's not displacement of engineers — it's an explosion in the total volume of software that gets built, and it requires people who know what to build and why.

We can't predict the Instagram of cheap cognition. But we can observe that the structural conditions — massive latent demand, rapidly falling costs, intense competition distributing gains to consumers — are identical to the conditions that preceded every prior wave of demand-driven economic expansion.

The Speed Question — Where Shumer Is Strongest

The legitimate uncertainty in Shumer's argument isn't whether displacement will happen. It will. The question is whether it happens faster than demand expansion can absorb.

Prior Jevons cycles unfolded over decades. Agricultural mechanization displaced 90% of farm workers over a century. Computerization restructured white-collar work over roughly forty years. If AI compresses displacement into two to three years, the question of whether demand expansion keeps pace becomes genuinely urgent. This is where Shumer's urgency has teeth, and it's the argument I take most seriously.

I was honest about this in both the counter-thesis and the Moore's Law piece: the speed of this transition is unprecedented, and historical analogy doesn't fully resolve the timing question. The transitional pain for people whose livelihoods depend on cognitive labor that AI can replicate is real and potentially severe.

But notice the asymmetry in Shumer's framing. Disruption happens at AI speed — step-function capability jumps, immediate adoption, rapid displacement. Demand expansion, on the other hand, is treated as essentially static or non-existent. The economy absorbs the shock and contracts. End of story.

This asymmetry isn't supported by the evidence. The smartphone created a trillion-dollar app economy in under five years. Cloud computing spawned tens of thousands of SaaS companies within a decade. When a critical input becomes 100x cheaper, entrepreneurs move fast — because the profit opportunity is enormous. Shumer's own experience is evidence of this: he's a founder building products at unprecedented speed using AI tools. Scale that behavior across millions of entrepreneurs who suddenly have access to capabilities that were previously reserved for well-funded teams, and the demand side moves faster than any prior technology transition.

The honest answer is that we don't know whether demand expansion will keep pace with displacement. That's a genuine uncertainty. But Shumer presents it as a foregone conclusion in one direction — displacement wins, full stop — and that's not an evidence-based position. It's a bet against the strongest empirical pattern in economic history.

What to Take from This

Shumer's practical advice to individuals is sound even if his macro analysis is incomplete. Use the tools. Build adaptability. Experiment daily. Don't ignore the capability curve — it's real, it's fast, and it will restructure how cognitive work gets done.

But don't mistake a substitution-only model for the full picture. The most consistent empirical pattern in economic history is that when a critical input gets dramatically cheaper, total consumption increases and the economy restructures around the cheaper input. Coal. Transistors. Bandwidth. Lighting. Every time, the predictions that efficiency would destroy demand were wrong — not because displacement didn't happen, but because demand expansion overwhelmed it. Betting that this pattern has finally broken requires an extraordinary burden of proof that Shumer's piece — eloquent, urgent, and emotionally resonant as it is — does not meet.

Something big is happening. What's missing from the conversation is the other half of it.

Moore's Law for Intelligence: What Happens When Thinking Gets Cheap

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

I have written about Jevons Paradox twice now — once through the history of the semiconductor industry, and once as a broader examination of what happens when the cost of a critical economic input collapses. The pattern is consistent: demand expands to overwhelm the savings. Coal. Transistors. Bandwidth. Lighting.

Those pieces looked at the pattern itself. This one is different. I want to run a thought experiment forward, not backward.

I've also spent a lot of time on this site looking backward at computing history — watching Stewart Cheifet walk viewers through the early personal computer revolution on The Computer Chronicles, examining how word processing went from a curiosity to a necessity in a single decade, tracing George Morrow's role in making personal computing real, and following CP/M's arc from operating system of the future to historical footnote. I've run CP/M on physical RetroShield hardware, explored the Motorola 68000 that powered a generation of machines, and dug into how Infocom turned text adventures into a business at a time when 64K of RAM was generous. That immersion in where computing came from is exactly what makes the forward question so vivid — because at every stage, the people living through the transition couldn't see what was coming next. The engineers building CP/M didn't anticipate DOS. The engineers building DOS didn't anticipate the web. The engineers building the web didn't anticipate the iPhone. The pattern is always the same: cheaper compute enables things that were unimaginable at the prior cost.

The question isn't "will AI destroy jobs?" or "is the doom scenario wrong?" The question is: what becomes possible when thinking gets cheap?

Because AI compute is following a cost curve that looks remarkably like the early decades of Moore's Law. And if that continues — if the cost per unit of machine intelligence drops by an order of magnitude every few years — the consequences extend far beyond making today's chatbots cheaper to run.

The Cost Curve

Moore's Law, in its original formulation, described the doubling of transistors per integrated circuit roughly every two years. But the economic consequence that mattered wasn't transistor density — it was cost per unit of compute. From the 1960s through the 2010s, the cost per FLOP declined at a compound rate that delivered roughly a 10x improvement every four to five years. A computation that cost \$1 million in 1975 cost \$1 by 2010. That decline didn't just make existing applications cheaper. It created entirely new categories of computing that were inconceivable at the prior cost structure.

AI inference costs are now following a similar trajectory, but faster. OpenAI's text-davinci-003, released in late 2022, cost \$20 per million tokens. GPT-4o mini, released in mid-2024, delivers substantially better performance at \$0.15 per million input tokens — a 99% cost reduction in under two years. Claude, Gemini, and open-source models have followed similar curves. DeepSeek entered the market in early 2025 with pricing that undercut Western frontier models by roughly 90%, compressing the timeline further through competitive pressure.

The GPU hardware underneath these models is on its own Moore's Law trajectory. GPU price-performance in FLOP/s per dollar doubles approximately every 2.5 years for ML-class hardware. Architectural improvements in transformers, mixture-of-experts routing, quantization, speculative decoding, and distillation compound on top of the hardware gains. The result is a cost curve where the effective price of a unit of machine reasoning is falling faster than the price of a transistor did during the semiconductor industry's most explosive growth phase.

This matters because we know, empirically, what happens when the cost of a foundational input follows an exponential decline. We have sixty years of data on it. The compute industry went from a few thousand mainframes serving governments and large corporations to billions of devices in every pocket, every appliance, every traffic light. Total spending on computing didn't shrink as costs fell — it expanded by orders of magnitude, because each 10x cost reduction unlocked categories of use that didn't exist at the prior price point.

The thought experiment is straightforward: apply that pattern to intelligence itself.

Today's Price Points Create Today's Use Cases

At current pricing — roughly \$3 per million input tokens for a frontier model like Claude Sonnet — AI is economically viable for a specific class of applications. Customer support automation. Code assistance. Document summarization. Marketing copy. Translation. These are the use cases where the value generated per token comfortably exceeds the cost per token, and where the interaction pattern involves relatively short exchanges.

But there are vast categories of potential use where current pricing makes the math uncomfortable or impossible. Consider:

Continuous monitoring and analysis. A financial analyst who wants an AI to continuously watch SEC filings, earnings calls, patent applications, and news feeds across 500 companies — analyzing each document in full, cross-referencing against historical patterns, and generating alerts — would consume billions of tokens per month. At current prices, this costs tens of thousands of dollars monthly. At 100x cheaper, it costs the price of a SaaS subscription.

Full-codebase reasoning. This one is already arriving. Anthropic's Claude Opus 4.6, working through Claude Code, can operate at the repository level — reading files, understanding architecture, running tests, and making changes across an entire codebase in a single session. I've used it to build a high-performance Rust-based ballistics engine and to develop Lattice, an entire programming language with a bytecode VM compiler — projects where the AI wasn't autocompleting fragments but reasoning across thousands of lines of interconnected code, tracking type systems, managing compiler passes, and understanding how changes in one module ripple through the rest. The constraint today isn't capability — it's cost. These sessions consume large volumes of tokens, which means they're viable for serious engineering work but not yet cheap enough to run continuously on every commit, every pull request, every deployment. At 100x cheaper, that changes. At 1,000x cheaper, every codebase has an always-on collaborator that has read everything and forgets nothing.

Personalized education at scale. A truly personalized AI tutor that adapts to a student's learning style, tracks their understanding across subjects, reviews their homework in detail, explains mistakes with patience, and adjusts its teaching strategy over months — this requires sustained, high-volume token consumption per student. Multiply by millions of students and the current cost structure breaks. At 100x cheaper, it's viable for a school district. At 1,000x cheaper, it's viable for an individual family.

Preventive medicine. Analyzing a patient's complete medical history, genetic data, lifestyle information, lab results, and the current research literature to generate genuinely personalized health recommendations — not the generic advice a five-minute doctor's visit produces, but the kind of comprehensive analysis that currently only concierge medicine patients paying \$10,000+ per year receive. At current token prices, this is prohibitively expensive for routine use. At 100x cheaper, it could be embedded in every annual checkup.

Ambient intelligence. The concept of AI that runs continuously in the background of your life — understanding your calendar, email, documents, and goals, proactively surfacing relevant information, drafting responses, scheduling meetings, flagging conflicts — requires sustained inference at volumes that would cost hundreds of dollars per day at current prices. At 1,000x cheaper, it costs less than your phone bill.

These aren't science fiction scenarios. They're applications of current model capabilities at price points that don't yet exist. The models can already do most of this work. The cost curve is the bottleneck.

The 10x / 100x / 1,000x Framework

Moore's Law didn't deliver its benefits in a smooth, continuous flow. It came in thresholds — price points at which qualitatively new applications became viable. The pattern with AI compute is likely to follow the same staircase function.

At 10x cheaper (plausible within 1-2 years): AI becomes viable for tasks that are currently "almost worth it." Small businesses that can't justify \$500/month for AI tooling find it worthwhile at \$50/month. Individual professionals — accountants, lawyers, doctors, engineers — integrate AI into their daily workflow not as an occasional tool but as a constant companion. The volume of AI-mediated work increases dramatically, but the character of work doesn't fundamentally change. This is the equivalent of the minicomputer era — the same kind of computing, available to more people.

At 100x cheaper (plausible within 3-5 years): The applications listed above become economically viable. Continuous analysis, full-codebase reasoning, personalized education, preventive medicine at scale. At this price point, AI stops being a tool you use and starts being infrastructure you run on. Every document you write gets reviewed. Every decision you make gets a second opinion. Every student gets a tutor. Every patient gets a diagnostician. The total volume of inference consumed per capita increases by far more than 100x, because new use cases emerge that weren't contemplated at the prior price. This is the personal computer moment — qualitatively new categories of use.

At 1,000x cheaper (plausible within 5-8 years): Intelligence becomes ambient and disposable. You don't think about whether to use AI for a task any more than you think about whether to use electricity for a task. Every appliance, every vehicle, every building, every piece of infrastructure has embedded reasoning running continuously. Your home understands your patterns and adapts. Your car negotiates traffic in real time not just with sensors but with models that predict the behavior of every other vehicle. Agricultural equipment analyzes soil conditions at the individual plant level. Supply chains optimize in real time across thousands of variables. This is the smartphone moment — computing so cheap and pervasive that it becomes invisible.

The Compounding Effect

There's a dynamic in AI cost reduction that didn't exist with traditional Moore's Law: cheaper inference enables better models, which enables even cheaper inference.

When inference is expensive, researchers are constrained in how they can train and evaluate models. Each experiment costs real money. Each architecture search consumes significant compute budgets. When inference costs drop, researchers can run more experiments, evaluate more architectures, and discover more efficient approaches — which further reduces costs. Distillation (training a smaller model to mimic a larger one) becomes more practical when the larger model is cheaper to run at scale. Synthetic data generation (using AI to create training data for other AI) becomes more economical. The cost reduction compounds on itself.

This is already happening. GPT-4 was used to generate synthetic training data for GPT-4o. Claude's training pipeline uses prior Claude models to evaluate and filter training examples. Google's Gemini models help design the next generation of TPU chips that will run future Gemini models. The AI equivalent of "using computers to design better computers" arrived in year three of the current wave, decades earlier in the relative timeline than it took the semiconductor industry to reach the same recursive dynamic.

The implication is that the cost curve isn't just declining — it's declining at an accelerating rate because each improvement enables the next one. The semiconductor industry saw this acceleration plateau after about fifty years as it approached physical limits of silicon. AI has no equivalent physical constraint on the horizon. The limits are architectural and algorithmic, and those limits have been falling faster than hardware limits ever did.

What the Semiconductor Analogy Actually Predicts

In 1975, a Cray-1 supercomputer delivered about 160 MFLOPS and cost \$8 million. In 2025, an iPhone delivers roughly 2 TFLOPS of neural engine performance and costs \$800. That's a 12,500x performance increase at a 10,000x cost decrease — a net improvement of roughly 100 million times in price-performance over fifty years.

Nobody in 1975 predicted Instagram, Uber, Google Maps, or Spotify. Not because these applications required fundamentally new physics — they just required compute that was cheap enough to run in a device that fit in your pocket. The applications were latent, waiting for the cost curve to reach them.

The history is instructive at each threshold. When a capable computer crossed below \$20,000 in the early 1980s, it unlocked small business accounting — the same work mainframes did, just for smaller organizations. When it crossed below \$2,000 in the mid-1990s, it unlocked home computing, and with it the web browser, email, and e-commerce. When capable compute crossed below \$200 in the smartphone era, it unlocked ride-sharing, mobile payments, and social media — none of which had any conceptual precursor at the \$20,000 price point. Each 10x reduction didn't just expand the existing market. It created a market that was literally unimaginable at the prior price.

The same principle applies to intelligence. We are in the mainframe era of AI. The applications we see today — chatbots, code assistants, image generators — are the equivalent of payroll processing and scientific computation on 1960s mainframes. They are real and valuable, but they represent a tiny fraction of what becomes possible when the cost drops by five or six orders of magnitude.

What are the Instagram and Uber equivalents of cheap intelligence? By definition, we can't fully predict them. But we can identify the structural conditions that will enable them:

When intelligence costs less than attention, delegation becomes default. Today, the cognitive cost of formulating a good prompt, evaluating the output, and iterating often exceeds the cost of just doing the task yourself. As models get cheaper, faster, and better at understanding context, the threshold shifts. Eventually, not delegating a cognitive task to AI becomes the irrational choice, the way not using a calculator for arithmetic became irrational.

When intelligence costs less than data storage, everything gets analyzed. Today, most data that organizations collect is never analyzed. It's stored, archived, and forgotten — because the cost of human analysis exceeds the expected value of the insights. When AI analysis is effectively free, every dataset gets examined. Every log file gets reviewed. Every customer interaction gets analyzed for patterns. The volume of insight generated from existing data increases by orders of magnitude.

When intelligence costs less than communication overhead, organizations restructure. This is already starting. A significant fraction of white-collar work is coordination — meetings, emails, status updates, project management. These exist because humans need to synchronize their mental models of shared projects. AI tools are already compressing this layer: meeting summaries that eliminate the need for half the attendees, project dashboards that maintain themselves, codebases where an AI agent tracks the state of every open issue so developers don't have to sit through standup. When AI can maintain a comprehensive, always-current model of a project's state, much of the coordination overhead that justifies entire job categories — project managers, program managers, business analysts, internal consultants — begins to evaporate. An organization that currently needs 50 people to coordinate a complex project might need 10, with AI handling the information synthesis that previously required human intermediaries. That's a genuine productivity gain. It's also 40 people who need to find something else to do — and the honest answer is that we don't yet know how fast the demand side creates new roles to absorb them.

The Demand Expansion Is the Story

The instinct when hearing "AI gets 1,000x cheaper" is to think about cost savings. That's the substitution frame — doing the same things for less money. And yes, that will happen. But the semiconductor analogy tells us that cost savings are the boring part of the story.

When compute got 1,000x cheaper between 1980 and 2000, the interesting story wasn't that scientific simulations got cheaper to run. It was that entirely new industries — PC software, internet services, mobile apps, social media, cloud computing — emerged to consume orders of magnitude more compute than the entire prior industry had used. The efficiency gain on existing applications was dwarfed by the demand expansion from new applications.

The same will likely be true for intelligence. Consider bandwidth as a parallel case. In 1995, a 28.8 kbps modem made email and basic web pages viable. Nobody was streaming video — it was physically impossible at that bandwidth, not merely expensive. By 2005, broadband had made streaming music viable. By 2015, streaming 4K video was routine. By 2025, cloud gaming and real-time video conferencing were infrastructure-level assumptions. Total bandwidth consumption didn't decline as it got cheaper. It increased by roughly a million times, because each generation of cost reduction enabled applications that consumed orders of magnitude more bandwidth than the previous generation's entire output.

The interesting story isn't that customer support gets cheaper. It's the applications that are currently impossible — not difficult, not expensive, but literally impossible at current price points — that become not just possible but routine.

A world where every small business has a CFO-grade financial analyst. Where every patient has a diagnostician who has read every relevant paper published in the last decade. Where every student has a tutor who knows exactly where they're struggling and why. Where every local government has the analytical capacity currently reserved for federal agencies.

And the nature of building software itself is changing in ways that go beyond "engineers with better tools." For most of computing history, writing code meant a human translating intent into syntax — line by line, function by function. AI assistance started as autocomplete: suggesting the next line, filling in boilerplate. But that phase is already ending. Today, with tools like Claude Code, the workflow has inverted. The human describes what they want — an architecture, a feature, a behavior — and the AI writes the implementation across files, runs the tests, and iterates on failures. The engineer's role shifts from writing code to directing and reviewing it, from syntax to judgment. At 10x cheaper, this is how professional developers work. At 100x cheaper, it's how small teams build products that previously required departments. At 1,000x cheaper, the barrier between "person with an idea" and "working software" functionally disappears. The entire concept of what it means to be a software engineer is being rewritten in real time — not by replacing engineers, but by redefining the skill from "can you write this code?" to "do you know what to build and why?"

These aren't efficiency improvements on existing systems. They're new capabilities that create new categories of economic activity, new forms of organization, and new kinds of products and services that don't have current analogs — just as social media, ride-sharing, and cloud computing had no analogs in the mainframe era.

The Question That Matters

I should be honest about what I don't know. The displacement scenarios for white-collar labor are not fantasy. AI is already capable enough to handle work that was solidly middle-class professional territory two years ago — document review, financial analysis, code generation, customer support, content production. The scenarios where this accelerates faster than the economy can absorb are plausible, and anyone who dismisses them outright isn't paying attention. When a technology can replicate cognitive labor at a fraction of the cost, the transitional pain for the people whose livelihoods depend on that labor is real and potentially severe. The speed matters: prior technology transitions unfolded over decades, and AI compression of that timeline into years is a genuine uncertainty that historical analogy doesn't fully resolve.

But there is a question that displacement scenarios consistently underweight, and it's the one I explored in my Jevons counter-thesis: what happens on the demand side? Every model that projects mass unemployment from cheap AI is implicitly assuming that the economy remains roughly the same size, with machines doing the work humans used to do. That's the substitution frame. And the substitution frame has been wrong at every prior technological inflection point — not slightly wrong, but wrong by orders of magnitude.

The semiconductor industry's answer, delivered over sixty years of data, is unambiguous. Every order-of-magnitude cost reduction generated more economic activity, more employment, and more total compute consumption than the one before it. The economy didn't shrink as compute got cheaper. It restructured around cheap compute and grew. Roughly 80% of Americans who need legal help can't afford it today. Personalized tutoring is a luxury good. Custom software is out of reach for most small businesses. These aren't speculative markets — they're documented unmet demand suppressed by the cost of human intelligence. When that cost collapses, the demand doesn't stay static.

The honest answer is that both things will happen simultaneously. Jobs will be displaced — some permanently. And new categories of economic activity will emerge that are currently inconceivable, just as social media and cloud computing were inconceivable in the mainframe era. The question is which force dominates, and how fast the transition occurs. I think the historical pattern favors demand expansion, but I hold that view with the humility of someone who knows the speed of this particular transition is unprecedented.

AI inference costs are following the same curve as semiconductors, possibly faster. The tokens-per-dollar ratio will improve by orders of magnitude. And when it does, the applications that emerge will make today's AI use cases look as quaint as running payroll on a room-sized mainframe.

The thought experiment ends where all Jevons stories end: with more consumption, not less. More intelligence deployed, not less. More economic activity built on cheap cognition, not less. The cost curve is the enabling condition. What gets built on top of it is the part we can't fully predict — and historically, that's always been the most interesting part.

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.

The Jevons Counter-Thesis: Why AI Displacement Scenarios Underweight Demand Expansion

A.C. Jokela — Tue, 24 Feb 2026 14:00:00 GMT

Citrini Research recently published a piece called "The 2028 Global Intelligence Crisis" — a thought experiment modeling a scenario in which AI-driven white-collar displacement triggers a cascading economic crisis. In their telling, AI replaces workers, spending drops, firms invest more in AI to protect margins, AI improves, and the cycle repeats. They call it the "Intelligence Displacement Spiral" and project a 57% peak-to-trough drawdown in the S&P 500. No natural brake. No soft landing.

It is a well-constructed stress test, and worth reading on its own terms. But the scenario achieves its conclusion by modeling only the displacement side of an efficiency revolution while treating the demand-expansion side as essentially zero. This is the core analytical gap, and it is precisely the gap that Jevons Paradox addresses.

I have written about Jevons Paradox before in the context of the semiconductor industry — how improvements in energy efficiency from the transistor through GPUs have consistently driven more total energy consumption, not less, by making computing cheap enough to permeate every corner of the economy. The same framework applies to AI and cognitive labor, and the Citrini piece is a useful foil for exploring why.

What Jevons Paradox Actually Says

In 1865, the English economist William Stanley Jevons observed something counterintuitive about coal consumption in Britain. James Watt's steam engine had made coal use dramatically more efficient — you could extract far more useful work per ton of coal than before. The intuitive expectation was that Britain would use less coal. The opposite happened. Total coal consumption surged, because the efficiency gains made coal-powered activities so much cheaper that entirely new applications emerged. Factories that couldn't justify coal-powered machinery at the old efficiency levels now could. Industries that had never used steam power adopted it. The per-unit savings were overwhelmed by the explosion in total units demanded.

This pattern has recurred across nearly every major input cost reduction in economic history. Semiconductor efficiency improved by roughly a trillionfold over six decades, and total spending on computing did not decline — it expanded from a niche military and scientific expenditure to a multi-trillion-dollar global industry. Bandwidth costs collapsed through the 1990s and 2000s, and total bandwidth consumption didn't decrease — it increased by orders of magnitude as streaming video, social media, cloud computing, and mobile internet emerged. LED lighting is roughly 90% more efficient than incandescent bulbs, and total global illumination has increased, not decreased, as cheap lighting enabled new architectural designs, 24-hour commercial operations, and decorative applications that were uneconomical before.

The mechanism is straightforward: when a critical input becomes dramatically cheaper, the addressable market for everything that uses that input expands. New use cases emerge that were previously uneconomical. Existing use cases scale to populations that were previously priced out. The total consumption of the now-cheaper input rises even as the per-unit cost falls.

The Citrini piece implicitly models AI as a substitution technology — it replaces human cognitive labor, and that's the end of the transaction. Jevons Paradox suggests AI is simultaneously, and perhaps primarily, an expansion technology — it makes cognitive services so cheap that demand for them can grow faster than the displacement effect.

Latent Demand Is Enormous and Unmeasured

The Citrini scenario treats the economy as having a fixed quantity of cognitive work. AI absorbs that work, the workers who performed it lose their income, and aggregate demand collapses. But the reason cognitive work costs what it does is that human intelligence has been scarce and expensive. This scarcity has suppressed enormous categories of demand that simply don't show up in current GDP accounting because they've never been economically feasible.

Consider education. The average American family cannot afford personalized tutoring. A human tutor at \$50-100 per hour is a luxury good. If AI reduces the cost of competent, personalized educational support to near zero, the addressable market isn't the current tutoring market — it's every student in the country. That is a market expansion of potentially 50x or more relative to the existing tutoring industry. The humans who previously worked as tutors are displaced, yes, but the economic activity generated by tens of millions of students receiving personalized education — and the downstream productivity gains from a better-educated workforce — is a new demand category that didn't exist before.

The same logic applies across dozens of sectors. Legal services: roughly 80% of Americans who need legal help cannot afford it. Personalized financial planning: currently available only to households with six-figure investable assets. Preventive health analysis: limited by the number of available clinicians. Custom software for small businesses: a \$50,000 engagement is out of reach for a business generating \$300,000 in annual revenue. Architecture and design services for middle-income homeowners. Personalized nutrition and fitness programming. Translation and localization for businesses that currently operate only in one language.

These are not speculative categories. They are documented, unmet needs constrained by the cost of the human intelligence required to serve them. When AI collapses those costs, the question is whether the demand expansion across all of these categories — and others we haven't imagined — can offset the displacement in existing roles. The Citrini piece assumes the answer is no without modeling the question. Jevons Paradox, and the historical base rate, suggests the answer is more likely yes.

The Citrini Piece's Own Evidence Supports Jevons

The piece acknowledges two canonical examples of technological displacement that didn't produce net job losses: ATMs (bank teller employment rose for 20 years after their introduction, because cheaper branch operations led to more branches) and the internet (travel agencies, the Yellow Pages, and brick-and-mortar retail were disrupted, but entirely new industries emerged in their place). It then dismisses both by asserting that "AI is different because it improves at the very tasks humans would redeploy to."

But this is precisely what critics said at every prior inflection point. When mechanized looms were introduced in the early 19th century, displaced textile workers could not "redeploy" to weaving — the machines did the very thing they were trained for. What actually happened was that radically cheaper cloth created demand for fashion, retail distribution, global trade logistics, cotton cultivation, and marketing — categories that scarcely existed at the prior cost structure. The weavers didn't get their old jobs back. They moved into an economy that had been restructured around abundant, cheap textiles, and that economy was far larger than the one it replaced.

The Citrini piece's own scenario contains evidence of Jevons-style expansion that it frames exclusively as destruction. The section on agentic commerce describes consumers using AI agents that eliminate friction — price-matching across platforms, renegotiating subscriptions, rebooking travel. The article frames this as the death of intermediation moats. But it is equally a story of market expansion. When an AI agent assembles a complete travel itinerary faster and cheaper than Expedia, the result isn't just that Expedia loses revenue. It's that people who previously found trip planning too cumbersome or too expensive now take trips. Total travel volume can increase even as per-trip intermediation costs fall.

The DoorDash example is even more explicit. The article describes vibe-coded competitors passing 90-95% of delivery fees to drivers, and AI agents shopping across twenty platforms for the best deal. Delivery becomes cheaper for consumers and more remunerative for drivers. The article frames this as destruction of DoorDash's moat. From a Jevons perspective, it's a textbook demand expansion setup: cheaper delivery means more people order delivery, more restaurants offer delivery, and total delivery volume grows.

The Feedback Loop Has a Natural Brake

The article's most powerful rhetorical device is the claim that the Intelligence Displacement Spiral has "no natural brake." This is the critical assertion on which the entire doom scenario depends, and it is the assertion most directly challenged by Jevons Paradox.

The natural brake is price-driven demand expansion. As AI makes cognitive services cheaper, consumers gain access to goods and services they couldn't previously afford. This is true even for displaced workers operating at lower income levels. A former product manager earning \$45,000 as an Uber driver cannot afford a human financial advisor, but can access AI-driven financial planning for near zero cost. They cannot afford a human tutor for their children, but can access AI tutoring. They cannot afford custom software to start a small business, but can build an application using AI tools. The consumption basket shifts — less spending on expensive human-mediated services, more consumption of cheap AI-mediated services that were previously unattainable.

This doesn't make the individual worse off on net — it partially offsets the income decline through dramatically lower cost of living for intelligence-intensive services. The article's "Ghost GDP" concept — output that shows up in national accounts but doesn't circulate through the real economy — assumes that the efficiency gains accrue entirely to capital owners. But the article itself documents intense competition. Dozens of vibe-coded delivery startups competing for share. Agentic shoppers forcing prices down across every category. Stablecoin payment rails bypassing card interchange fees. In competitive markets, efficiency gains don't stay with producers — they flow to consumers through lower prices. That flow is the transmission mechanism through which Jevons effects operate, and the article describes it vividly while somehow not recognizing it as a countervailing force.

The OpEx Substitution Framing Conceals the Demand Side

The article makes an astute observation that AI investment increased even as the economy contracted, because companies were substituting AI OpEx for labor OpEx. A company spending \$100M on employees and \$5M on AI shifts to \$70M on employees and \$20M on AI — total spending falls while AI spending rises. This explains why the AI infrastructure complex continued performing even as the broader economy deteriorated.

This is a credible supply-side analysis. But it omits the demand-side consequence. If a company produces the same output with fewer workers at lower total cost, competitive pressure pushes the price of that output down. Falling prices expand the addressable market. A SaaS product that cost \$500,000 annually and was affordable only to the Fortune 500 now costs \$50,000 and is accessible to mid-market companies. A consulting engagement that cost \$2 million and was reserved for large enterprises now costs \$200,000 and is available to growth-stage companies. The total number of transactions can grow even as per-transaction revenue falls.

The article models a world where output stays constant, prices stay constant, costs drop, and the entire surplus accrues to shareholders. In practice, the intense competition the article itself describes — incumbents in knife-fights with each other and with upstart challengers — is precisely the mechanism that prevents this. Competition distributes efficiency gains through lower prices, and lower prices expand markets.

The Intelligence Premium Unwind Is Also a Jevons Story

The article's most compelling framing is that human intelligence has been the scarce input in the economy for all of modern history, and AI is unwinding that premium. Every institution — the labor market, mortgage underwriting, the tax code — was designed for a world where human cognition was expensive and irreplaceable. As AI makes intelligence abundant, these institutions crack.

Jevons Paradox applied to this framing produces a different conclusion. When intelligence becomes abundant and cheap, the economy doesn't just produce the same cognitive output more efficiently — it restructures around consuming vastly more intelligence. We don't merely replicate the existing quantity of analysis, decisions, creative output, and coordination at lower cost. We produce orders of magnitude more of it.

The article's own data point supports this: by March 2027 in their scenario, the median American was consuming 400,000 tokens per day, a 10x increase from the end of 2026. The article cites this as evidence of disruption, but it is fundamentally a Jevons data point. People are consuming more intelligence, not less. That consumption drives economic activity — someone is building the products and services that consume those tokens, maintaining the infrastructure, curating quality, arbitrating edge cases, and inventing new applications.

The question is whether that new economic activity employs enough people at high enough wages to offset the displacement. The article assumes it doesn't. History suggests it tends to, though the transition period can be painful and the new employment categories often look nothing like the old ones.

The GDP Composition Argument Cuts Both Ways

The article makes much of the fact that 70% of US GDP is consumer spending, and that white-collar workers drive a disproportionate share of that spending. When those workers lose income, the consumption base collapses, and GDP follows. This is mechanically sound as far as it goes.

But Jevons Paradox suggests that the composition of GDP shifts during efficiency revolutions, not just the level. When agricultural mechanization displaced 90% of farm workers over the course of a century, it did not produce a permanent 90% unemployment rate. GDP restructured around manufacturing and services — categories that were economically marginal when most human labor was occupied with food production. The displaced agricultural workers didn't return to farming. They moved into an economy where cheap food freed up income and labor for other activities.

The analogous question for AI is: when cognitive labor becomes cheap, what does the economy restructure around? The Citrini piece doesn't attempt to answer this, which is understandable — predicting the specific industries of the future is a fool's errand. But the pattern is well-established. Cheap food led to a manufacturing economy. Cheap manufacturing led to a services economy. Cheap cognitive services leads to something else. The article's scenario assumes the chain terminates with "cheap cognitive services leads to nothing," which is historically unprecedented.

One plausible direction: the economy shifts toward activities where physical presence, human trust, and embodied experience carry a premium precisely because cognitive tasks are commoditized. Healthcare delivery (not diagnosis, but care), skilled trades, experiential services, community-oriented businesses, and creative work that is valued specifically for its human origin. These are not futuristic speculations — they are existing sectors where human presence is intrinsic to the value proposition. As AI deflates the cost of cognitive services, the relative value of irreducibly human activities increases, and spending may shift toward them.

Another direction, potentially larger: entirely new categories of economic activity that we cannot yet name, because they only become viable when intelligence is cheap and abundant. The internet didn't just make existing activities more efficient — it created social media, the gig economy, e-commerce logistics, content creation as a profession, and cloud computing as an industry. None of these were predicted in advance. The equivalent AI-native industries may already be emerging in nascent form, invisible to a GDP accounting framework built for the prior economic structure.

Where the Speed Concern Is Legitimate

The strongest element of the Citrini scenario is the speed argument. Prior Jevons cycles unfolded over decades — long enough for institutions, education systems, and labor markets to adapt. The article's timeline compresses displacement into roughly 18-24 months, far faster than the demand-expansion side can respond.

This is a legitimate concern, and it's where the Jevons counter-argument is weakest. If displacement is fast and demand expansion is slow, the interim period can be genuinely severe — even if the long-run equilibrium is positive. Policy response, education, and institutional adaptation all operate on timescales measured in years, not quarters.

However, the article makes an asymmetric assumption on this point. It models disruption happening at AI speed — step-function capability jumps, immediate corporate adoption, rapid layoff cycles. But it models demand expansion as essentially static, only emerging when government intervention eventually arrives. This ignores that entrepreneurial response to dramatically cheaper inputs has historically been fast. The smartphone created a trillion-dollar app economy in under five years. Cloud computing spawned tens of thousands of SaaS companies within a decade. When a critical input becomes 100x cheaper, entrepreneurs move quickly to build products that exploit the new cost structure, because the profit opportunity is enormous.

The article's scenario includes dozens of vibe-coded delivery startups appearing rapidly, which is itself evidence of fast entrepreneurial response to cheaper intelligence. It just doesn't extend that observation to other sectors.

Where the Counter-Argument Must Be Honest

Jevons Paradox is not a universal law. It describes a tendency — a strong historical pattern — not an iron guarantee. The Citrini piece's most potent rebuttal is that prior Jevons cycles involved specific resource inputs (coal, compute, bandwidth, lighting), while AI targets the general-purpose input of intelligence itself. If AI can perform not only existing cognitive tasks but also the new tasks that would emerge from demand expansion, then the rebound effect could be muted or eliminated entirely. A coal-fired loom couldn't design fashion or run a retail chain. But an AI that can code, analyze, write, plan, and reason might well be capable of staffing the very industries that Jevons expansion would create.

This is a genuine uncertainty, and intellectual honesty requires acknowledging it. The question reduces to whether human judgment, taste, coordination, creativity, physical presence, and social trust constitute a durable residual demand — activities where humans remain preferred or necessary even when AI is technically capable — or whether those too get absorbed over time. The honest answer is that we don't know.

What we do know is that the historical base rate strongly favors Jevons over the doom loop. Every prior prediction that a general-purpose technology would produce permanent mass unemployment — mechanized agriculture, factory automation, computerization, the internet — has been wrong, and wrong for the same reason: the predictions modeled displacement without modeling demand expansion. The Citrini piece, for all its sophistication, repeats that analytical pattern.

The Bottom Line

The Citrini piece is worth reading as a risk scenario. The transitional pain it describes is plausible, and portfolio construction should account for it. But as a base case for the future of the economy, it requires assuming that the most consistent empirical pattern in economic history — that radically cheaper inputs generate demand that exceeds displacement — has finally broken. That's a bet against a very long track record.

For more on the mechanics of Jevons Paradox and how it has played out across the semiconductor industry from vacuum tubes to modern AI accelerators, see my earlier piece: Jevons Paradox and the Semiconductor Industry.

A Stack-Based Bytecode VM for Lattice: 100 Opcodes, Serialization, and a Self-Hosted Compiler

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

When I first wrote about Lattice's move from a tree-walking interpreter to a bytecode VM, the instruction set had 62 opcodes, concurrency primitives still delegated to the tree-walker, and programs couldn't be serialized. The VM was a foundation — correct and complete enough to become the default, but clearly a starting point.

That was ten versions ago. The bytecode VM now has 100 opcodes, compiles concurrency primitives into standalone sub-chunks with zero AST dependency at runtime, ships a binary serialization format for ahead-of-time compilation, includes an ephemeral bump arena for short-lived string temporaries, and — perhaps most satisfyingly — has a self-hosted compiler written entirely in Lattice that produces the same .latc bytecode files as the C implementation.

This post walks through what changed and why. The full technical treatment is available as a research paper; this is the practitioner's version.

Why Keep Going

The original bytecode VM solved the immediate problems: it eliminated recursive AST dispatch overhead and gave Lattice a single execution path for file execution, the REPL, and the WASM playground. But three issues remained.

First, OP_SCOPE and OP_SELECT — Lattice's structured concurrency opcodes — still stored AST node pointers in the constant pool and dropped into the tree-walking evaluator at runtime. This meant the AST had to stay alive during concurrent execution, which defeated one of the main motivations for having a bytecode VM in the first place.

Second, the AST dependency made serialization impossible. You can serialize bytecode to a file, but you can't easily serialize an arbitrary C pointer to an AST node. Programs had to be parsed and compiled on every run.

Third, the dispatch loop used a plain switch statement. Not a crisis, but computed goto dispatch is a well-known improvement for bytecode interpreters, and leaving it on the table felt unnecessary.

All three problems are solved now. Let me start with the instruction set, since everything else builds on it.

100 Opcodes

The instruction set grew from 62 to 100 opcodes, organized into 16 functional categories:

Category	Representative opcodes	Count
Stack manipulation	`CONSTANT`, `NIL`, `TRUE`, `FALSE`, `UNIT`, `POP`, `DUP`, `SWAP`	8
Arithmetic/logical	`ADD`, `SUB`, `MUL`, `DIV`, `MOD`, `NEG`, `NOT`	7
Bitwise	`BIT_AND`, `BIT_OR`, `BIT_XOR`, `BIT_NOT`, `LSHIFT`, `RSHIFT`	6
Comparison	`EQ`, `NEQ`, `LT`, `GT`, `LTEQ`, `GTEQ`	6
String	`CONCAT`	1
Variables	`GET/SET_LOCAL`, `GET/SET/DEFINE_GLOBAL`, `GET/SET_UPVALUE`, `CLOSE_UPVALUE`	8
Control flow	`JUMP`, `JUMP_IF_FALSE`, `JUMP_IF_TRUE`, `JUMP_IF_NOT_NIL`, `LOOP`	5
Functions	`CALL`, `CLOSURE`, `RETURN`	3
Iterators	`ITER_INIT`, `ITER_NEXT`	2
Data structures	`BUILD_ARRAY`, `INDEX`, `SET_INDEX`, `GET_FIELD`, `INVOKE`, etc.	15
Exceptions/defer	`PUSH_EXCEPTION_HANDLER`, `THROW`, `DEFER_PUSH`, `DEFER_RUN`, etc.	6
Phase system	`FREEZE`, `THAW`, `CLONE`, `MARK_FLUID`, `REACT`, `BOND`, `SEED`, etc.	14
Builtins/modules	`PRINT`, `IMPORT`	2
Concurrency	`SCOPE`, `SELECT`	2
Integer fast paths	`INC_LOCAL`, `DEC_LOCAL`, `ADD_INT`, `SUB_INT`, `LOAD_INT8`, etc.	8
Wide variants	`CONSTANT_16`, `GET_GLOBAL_16`, `SET_GLOBAL_16`, `DEFINE_GLOBAL_16`, `CLOSURE_16`	5
Special	`RESET_EPHEMERAL`, `HALT`	2
Total		100

The growth came from three directions: the integer fast-path opcodes (8 new), the wide constant variants (5 new), and the concurrency/arena opcodes. Let me explain each.

Integer Fast Paths

Tight loops like for i in 0..1000 spend most of their time incrementing a counter and comparing it to a bound. The generic OP_ADD has to check whether its operands are integers, floats, or strings (for concatenation), which adds branching overhead on every iteration.

The integer fast-path opcodes — OP_ADD_INT, OP_SUB_INT, OP_MUL_INT, OP_LT_INT, OP_LTEQ_INT — skip the type check entirely and operate directly on int64_t values. OP_INC_LOCAL and OP_DEC_LOCAL handle the i += 1 and i -= 1 patterns as single-byte instructions that modify the stack slot in place, no push or pop required.

OP_LOAD_INT8 encodes a signed byte directly in the instruction stream. The integer 42 becomes two bytes (OP_LOAD_INT8, 0x2A) instead of a three-byte OP_CONSTANT plus an eight-byte constant pool entry. Any integer in [-128, 127] gets this treatment.

Wide Constant Variants

The original instruction set used a single byte for constant pool indices, limiting each chunk to 256 constants. This is fine for most functions, but the self-hosted compiler — a 2,000-line Lattice program compiled as a single top-level script — blows past that limit easily.

OP_CONSTANT_16, OP_GET_GLOBAL_16, OP_SET_GLOBAL_16, OP_DEFINE_GLOBAL_16, and OP_CLOSURE_16 use two-byte big-endian indices, supporting up to 65,536 constants per chunk. The compiler automatically switches to wide variants when an index exceeds 255.

The Compiler

The bytecode compiler performs a single-pass walk over the AST. It maintains a chain of Compiler structs linked via enclosing pointers — one per function being compiled. Variable references resolve through three tiers: local (scan the current compiler's locals array), upvalue (recursively check enclosing compilers), and global (fall through to OP_GET_GLOBAL).

Three compilation modes handle different use cases. compile() is the standard file mode — it compiles all declarations and emits an implicit call to main() if one is defined. compile_module() is for imports — identical to compile() but skips the auto-call. compile_repl() preserves the last expression on the stack as the iteration's return value (displayed with => prefix) and keeps the known-enum table alive across REPL iterations so enum declarations persist.

The compiler implements several optimizations during code generation. Binary operations on literal operands are folded at compile time — 3 + 4 emits a single OP_LOAD_INT8 7 rather than two loads and an OP_ADD. The pattern x += 1 is detected and emitted as the single-byte OP_INC_LOCAL, which modifies the stack slot in place. And every statement is wrapped by compile_stmt_reset(), which appends OP_RESET_EPHEMERAL to trigger the ephemeral arena cleanup.

Computed Goto Dispatch

The dispatch loop now uses GCC/Clang's labels-as-values extension for computed goto:

#ifdef VM_USE_COMPUTED_GOTO
  static void *dispatch_table[] = {
    [OP_CONSTANT] = &&lbl_OP_CONSTANT,
    [OP_NIL]      = &&lbl_OP_NIL,
    // ... all 100 entries
  };
#endif

for (;;) {
    uint8_t op = READ_BYTE();
#ifdef VM_USE_COMPUTED_GOTO
    goto *dispatch_table[op];
#endif
    switch (op) {
        // ...
    }
}

Each opcode handler ends with a goto *dispatch_table[READ_BYTE()] rather than breaking back to the top of the loop. This eliminates the switch statement's bounds check and branch table indirection, replacing it with a single indirect jump. The CPU's branch predictor sees different jump sites for different opcodes, which improves prediction accuracy compared to a single switch that all opcodes funnel through.

On platforms without the extension, it falls back to a standard switch. The VM works correctly either way.

Pre-Compiled Concurrency

This is the change I'm most pleased with, because it solves the problem cleanly.

Lattice has three concurrency primitives: scope defines a concurrent region, spawn launches a task within that region, and select multiplexes over channels. In the tree-walker, these work by passing AST node pointers to spawned threads, which then evaluate the subtrees independently. The bytecode VM's original implementation did the same thing — OP_SCOPE stored an Expr* pointer in the constant pool and called the tree-walking evaluator at runtime.

The solution is to compile each concurrent body into a standalone Chunk at compile time. The compiler provides two helpers: compile_sub_body() for statement blocks and compile_sub_expr() for expressions. Each creates a fresh Compiler, compiles the code into a new chunk, emits OP_HALT, and stores the resulting chunk in the parent's constant pool as a VAL_CLOSURE constant.

OP_SCOPE uses variable-length encoding: a spawn count, a sync body chunk index, and one chunk index per spawn body. At runtime, the VM:

Exports locals to the global environment using the local_names debug table, so sub-chunks can access parent variables via OP_GET_GLOBAL
Runs the sync body (if present) via a recursive vm_run() call
Spawns threads for each spawn body, each running on a cloned VM
Joins all threads and propagates errors

OP_SELECT similarly encodes per-arm metadata: flags, channel expression chunk index, body chunk index, and binding name index. The VM evaluates channel expressions, polls for readiness, and executes the winning arm.

The key insight is that sub-chunks run as FUNC_SCRIPT without lexical access to the parent's locals. Since they can't use upvalues to reach into the parent frame, the VM exports the parent's live locals into the global environment before running any sub-chunk, using a pushed scope that gets popped after all sub-chunks complete. This is slightly more expensive than true lexical capture, but it keeps the sub-chunks completely self-contained — no AST, no parent frame dependency, fully serializable.

Bytecode Serialization

With AST dependency eliminated, serialization becomes straightforward. The .latc binary format starts with an 8-byte header:

[4C 41 54 43]  magic: "LATC"
[01 00]        format version: 1
[00 00]        reserved

The rest is a recursive chunk encoding: code length + bytecode bytes, line numbers for source mapping, typed constants (with a one-byte type tag for each), and local name debug info. Constants use seven type tags:

Tag	Type	Encoding
0	Int	8-byte signed LE
1	Float	8-byte IEEE 754
2	Bool	1 byte
3	String	length-prefixed (u32 + bytes)
4	Nil	no payload
5	Unit	no payload
6	Closure	param count + variadic flag + recursive sub-chunk

The Closure tag is what makes this recursive: a function constant contains its parameter metadata followed by a complete serialized sub-chunk. Nested functions serialize naturally to arbitrary depth.

The CLI integrates this cleanly:

# Compile to .latc
clat compile input.lat -o output.latc

# Run pre-compiled bytecode (auto-detects .latc suffix)
clat output.latc

# Or compile and run in one step (the default)
clat input.lat

Loading validates magic bytes, checks the format version, and uses a bounds-checking ByteReader that produces descriptive error messages for truncated or malformed inputs.

The Ephemeral Bump Arena

String concatenation is a common source of short-lived allocations. An expression like "hello " + name + "!" creates intermediate strings that are immediately consumed and discarded. In a language with deep-clone-on-read semantics, these temporaries add up.

The ephemeral bump arena is a simple optimization: string concatenation in OP_ADD and OP_CONCAT allocates into a bump arena (vm->ephemeral) instead of the general-purpose heap. These allocations are tagged with REGION_EPHEMERAL, and OP_RESET_EPHEMERAL — emitted by the compiler at every statement boundary — resets the arena in O(1), reclaiming all temporary strings at once.

The tricky part is escape analysis. If a temporary string gets assigned to a global variable, stored in an array, or passed to a compiled closure, it needs to be promoted out of the ephemeral arena before the arena is reset. The VM handles this at specific escape points: OP_DEFINE_GLOBAL, OP_CALL (for compiled closures), array.push, and OP_SET_INDEX_LOCAL. Each of these calls vm_promote_value(), which deep-clones the string to the regular heap if its region is ephemeral.

The arena uses a page-based allocator with 4 KB pages. Resetting doesn't free pages — it just moves the bump pointer back to zero, so subsequent allocations reuse the same memory without any malloc/free overhead. The full design and safety proof are covered in a companion paper.

Closures and the Storage Hack

The upvalue system hasn't changed architecturally since the first VM post — it's still the Lua-inspired open/closed model where ObjUpvalue structs start pointing into the stack and get closed (deep-cloned to the heap) when variables go out of scope. But the encoding grew to accommodate the wider instruction set.

OP_CLOSURE uses variable-length encoding: a constant pool index for the function's compiled chunk, an upvalue count, and then [is_local, index] byte pairs for each captured variable. OP_CLOSURE_16 uses a two-byte big-endian function index for chunks with more than 256 constants.

The storage hack — repurposing closure.body (NULL), closure.native_fn (Chunk pointer), closure.captured_env (ObjUpvalue** cast), and region_id (upvalue count) — remains unchanged. A sentinel value VM_NATIVE_MARKER distinguishes C-native functions from compiled closures:

#define VM_NATIVE_MARKER ((struct Expr **)(uintptr_t)0x1)

A closure with body == NULL and native_fn != NULL is either a C native (if default_values == VM_NATIVE_MARKER) or a compiled bytecode function (otherwise). This avoids adding VM-specific fields to the LatValue union, which matters when values are deep-cloned frequently.

The Self-Hosted Compiler

The file compiler/latc.lat is a bytecode compiler written entirely in Lattice — approximately 2,060 lines that read .lat source, produce bytecode, and write .latc files using the same binary format as the C implementation:

# Use the self-hosted compiler
clat compiler/latc.lat input.lat output.latc

# Run the result
clat output.latc

The architecture mirrors the C compiler: lexing via the built-in tokenize() function, a recursive-descent parser, single-pass code emission, and scope management with upvalue resolution. But Lattice's value semantics required some creative workarounds.

The biggest constraint is that structs and maps are pass-by-value. In C, the compiler uses a Compiler struct with mutable fields — local arrays, scope depth, a chunk pointer. In Lattice, passing a struct to a function creates a copy, so mutations in the callee don't propagate back. The self-hosted compiler works around this with parallel global arrays: code, constants, c_lines, local_names, local_depths, local_captured. Since array mutations via .push() and index assignment are in-place (via resolve_lvalue), global arrays work where structs don't.

Nested function compilation uses explicit save_compiler() / restore_compiler() functions that copy all global arrays to local temporaries and back. It's verbose but correct. The Buffer type (used for serialization output) is also pass-by-value, so a global ser_buf accumulates serialized bytes across function calls.

Other language constraints: no else if (requires else { if ... } or match), mandatory type annotations on function parameters (fn foo(a: any)), and test is a keyword so you can't use it as an identifier.

The self-hosted compiler currently handles expressions, variables, functions with closures, control flow (if/else, while, loop, for, break, continue, match), structs, enums, exceptions, defer, string interpolation, and imports. Not yet implemented: concurrency primitives and advanced phase operations (react, bond, seed). The bootstrapping chain is:

latc.lat → [C VM interprets] → output.latc → [C VM executes]

Full self-hosting — where latc.lat compiles itself — requires adding concurrency support and closing the remaining feature gaps.

The VM Execution Engine

The VM maintains a 4,096-slot value stack, a 256-frame call stack, an exception handler stack (64 entries), a defer stack (256 entries), a global environment, the open upvalue linked list, the ephemeral arena, and a module cache. A pre-allocated fast_args[16] buffer avoids heap allocation for most native function calls.

The OP_CALL instruction discriminates three callee types. Native C functions (marked with VM_NATIVE_MARKER) get the fast path — arguments are popped into fast_args, the C function pointer is invoked, and the return value is pushed. No call frame allocated. Compiled closures get the full treatment: the VM promotes ephemeral values in the current frame (so the callee's OP_RESET_EPHEMERAL doesn't invalidate the caller's temporaries), then pushes a new CallFrame with the instruction pointer at byte 0 of the callee's chunk. Callable structs look up a constructor-named field and dispatch accordingly.

Exception handling uses a handler stack. OP_PUSH_EXCEPTION_HANDLER records the current IP, chunk, call frame index, and stack top. When OP_THROW executes, the nearest handler is popped, the call frame and value stacks are unwound, the error value is pushed, and execution resumes at the handler's saved IP. Deferred blocks interact correctly — OP_DEFER_RUN executes all defer entries registered at or above the current frame before the frame is popped by OP_RETURN.

Iterators avoid closure allocation entirely. OP_ITER_INIT converts a range or array into an internal iterator occupying two stack slots (collection + cursor index). OP_ITER_NEXT advances the cursor, pushes the next element, or jumps to a specified offset when exhausted. The tree-walker used closure-based iterators for for loops — the bytecode version is simpler and avoids the allocation.

Ref<T>: The Escape Hatch from Value Semantics

Everything described so far operates in a world where values are deep-cloned on every read. Maps are pass-by-value. Structs are pass-by-value. Pass a collection to a function and the function gets its own copy — mutations don't propagate back. This is correct and eliminates aliasing bugs, but it creates a real problem: how do you share mutable state when you actually need to?

Ref<T> is the answer. It's a reference-counted shared mutable wrapper — the one type in Lattice that deliberately breaks value semantics:

struct LatRef {
    LatValue value;      // the wrapped inner value
    size_t   refcount;   // reference count
};

When a Ref is cloned (which happens on every variable read, like everything else), the VM bumps the refcount and copies the pointer. It does not deep-clone the inner value. Multiple copies of a Ref share the same underlying LatRef, so mutations through one are visible through all others. This is the explicit opt-in to reference semantics that the rest of the language avoids.

let r = Ref::new([1, 2, 3])
let r2 = r              // shallow copy — same LatRef
r.push(4)
print(r2.get())          // [1, 2, 3, 4] — shared state

The VM provides transparent proxying: OP_INDEX, OP_SET_INDEX, and OP_INVOKE all check for VAL_REF and delegate to the inner value. Indexing into a Ref<Array> indexes the inner array. Calling .push() on a Ref<Array> mutates the inner array directly. At the language level, a Ref mostly behaves like the value it wraps — you just get shared mutation instead of isolated copies.

Ref has its own methods — get()/deref() to clone the inner value out, set(v) to replace it, inner_type() to inspect the wrapped type — plus proxied methods for whatever the inner value supports (map set/get/keys, array push/pop, etc.).

The phase system applies to Refs too. Freezing a Ref blocks all mutation: set(), push(), index assignment all check obj->phase == VTAG_CRYSTAL and error with "cannot set on a frozen Ref." This makes frozen Refs safe to share across concurrent boundaries — they're immutable handles to immutable data.

This introduces a third memory management strategy alongside the dual-heap (mark-and-sweep for fluid values, arenas for crystal values) and the ephemeral bump arena. Refs use reference counting: ref_retain() on clone, ref_release() on free, with the inner value freed when the count hits zero. It's a deliberate trade-off — reference counting is simple and deterministic, and since Refs are the uncommon case (most Lattice code uses value semantics), the lack of cycle collection hasn't been an issue in practice.

Validation

The VM is validated by 815 tests covering every feature: arithmetic, closures, upvalues, phase transitions, exception handling, defer, iterators, data structures, concurrency, modules, bytecode serialization, and the self-hosted compiler.

All 815 tests pass under both normal compilation and AddressSanitizer builds (make asan), which dynamically checks for heap buffer overflows, use-after-free, stack buffer overflows, and memory leaks. For a VM with manual memory management, upvalue lifetime tracking, and an ephemeral arena that reclaims memory at statement boundaries, ASan validation is essential.

Both execution modes — bytecode VM (default) and tree-walker (--tree-walk) — share the same test suite and produce identical results:

make test                # bytecode VM: 815 passed
make test TREE_WALK=1    # tree-walker: 815 passed

Feature parity is complete:

Feature	Tree-walker	Bytecode VM
Phase system (freeze/thaw/clone/forge)	✓	✓
Closures with upvalues	✓	✓
Exception handling (try/catch/throw)	✓	✓
Defer blocks	✓	✓
Pattern matching	✓	✓
Structs with methods	✓	✓
Enums with payloads	✓	✓
Arrays, maps, tuples, sets, buffers	✓	✓
Iterators (for-in, ranges)	✓	✓
Module imports	✓	✓
Concurrency (scope/spawn/select)	✓	✓
Channels	✓	✓
Phase reactions/bonds/seeds	✓	✓
Contracts (require/ensure)	✓	✓
Variable tracking (history)	✓	✓
Bytecode serialization (.latc)	---	✓
Computed goto dispatch	---	✓
Ephemeral bump arena	---	✓
Specialized integer ops	---	✓

The last four rows are VM-only features that have no tree-walker equivalent.

What's Next

The VM is feature-complete but not performance-optimized. The obvious next steps are register allocation to reduce stack traffic, type-specialized dispatch paths guided by runtime profiling, tail call optimization for recursive patterns, and constant pool deduplication across compilation units. Further out, the bytecode provides a natural intermediate representation for JIT compilation.

On the self-hosting front, adding concurrency primitives to latc.lat would close the gap to full self-compilation — where the Lattice compiler compiles itself, producing a .latc file that can then compile other programs without the C implementation in the loop.

The full technical details — including encoding diagrams, the complete opcode listing, compilation walkthroughs, and references to related work in Lua, CPython, YARV, and WebAssembly — are in the research paper.

The source code is at github.com/ajokela/lattice, and the project site is at lattice-lang.org.

git clone https://github.com/ajokela/lattice.git
cd lattice && make
./clat

Rue: Steve Klabnik's AI-Assisted Experiment in Memory Safety Without the Pain

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

The Pitch

Every few years, a new programming language appears that promises to fix what its predecessors got wrong. Most quietly vanish. A handful become infrastructure. What makes Rue interesting is not that it promises to replace Rust—its creator explicitly says it won't—but that the person making it is one of the most qualified people alive to attempt the experiment.

Steve Klabnik spent thirteen years in the Rust ecosystem. He co-authored The Rust Programming Language, the official book that has introduced more people to Rust than any other resource. He served on the Rust core team, led its documentation team, and worked at Mozilla during Rust's formative years. He later joined Oxide Computer Company, where he contributed to a scratch-built operating system written in Rust. Before all of that, he was a prolific contributor to Ruby on Rails and authored Rust for Rubyists, one of the earliest attempts to bridge the Ruby and Rust communities.

If anyone has earned the right to look at Rust and say "I think we can do this differently," it's Klabnik. And that's exactly what Rue is: a research project asking whether memory safety without garbage collection can be achieved with less cognitive overhead than Rust demands.

But Rue is also something else entirely—an experiment in whether a single person, assisted by an AI, can build a programming language from scratch without funding, without a team, and without a multi-year timeline. The compiler is written in Rust, designed by Klabnik, and implemented primarily by Claude, Anthropic's AI assistant. The project went from nothing to a working compiler in roughly two weeks, producing approximately 100,000 lines of Rust code across 700+ commits.

The Person Behind It

Understanding Rue requires understanding Klabnik's trajectory through programming language communities. He entered professional programming through Ruby, becoming one of the most prolific open-source contributors to the Rails ecosystem in the early 2010s. His final commits to Rails landed in late 2013, around the time he discovered Rust 0.5 during a Christmas visit to his parents' house in rural Pennsylvania.

What followed was a thirteen-year involvement with Rust that few can match. Beyond the official book (now in its second edition, co-authored with Carol Nichols and published by No Starch Press), Klabnik shaped how the Rust community communicates, documents, and teaches. His work on Rust's documentation established patterns that other language communities later adopted. At Mozilla, he helped shepherd Rust through its 1.0 release. At Oxide, he worked on systems software at the lowest levels the language supports.

Klabnik describes himself as having been an AI skeptic until 2025, when he found that large language models had crossed a threshold of genuine usefulness for programming. The shift was dramatic enough that he now writes most of his code with AI assistance. Rue is the product of that conversion—not just a language experiment but a methodology experiment, testing what happens when a deeply experienced language designer directs an AI to implement his vision.

The name follows a deliberate pattern from his career: Ruby, Rust, Rue. He notes three associations—"rue the day" (the negative connotation, a nod to the skepticism any new language faces), the rue plant (paralleling Rust's fungal connotation), and brevity.

What Rue Is Today

Let's be direct about the current state: Rue is a version 0.1.0 research project. The website prominently warns that it is "not ready for real use" and to "expect bugs, missing features, and breaking changes." Klabnik himself has described the language as "still very janky" and cautions against reading too deeply into current implementation details. The GitHub README puts it plainly: "Not everything in here is good, or accurate, or anything: I'm just messing around."

With that caveat firmly in place, here's what exists.

Rue compiles to native machine code targeting x86-64 and ARM64. There is no virtual machine, no interpreter, and no garbage collector. The compiler is written in Rust (95.8% of the repository) and produces binaries directly. It builds using Buck2, Meta's build system, and the project includes a specification, a ten-chapter tutorial, a blog, and a benchmark dashboard that tracks compilation time, memory usage, and binary size across Linux and macOS.

The language itself is statically typed with type inference. Variables are declared with let (immutable by default) or let mut (mutable), following Rust's convention. The type system includes signed and unsigned integers (i8 through i64, u8 through u64), booleans, fixed-size arrays, structs, and enums. There are no strings. There is no standard library. There are no traits, no closures, no iterators, no modules, no error handling beyond panics, and no heap allocation. Generics exist behind a --preview comptime flag—more on that below—but they are not yet part of the stable language.

Read that list of absences again. It is long. And it is honest.

The Type System and Memory Model

Rue's central technical bet is that affine types with mutable value semantics can deliver memory safety more intuitively than Rust's borrow checker and lifetime annotations.

In practice, this means values in Rue are moved by default. When you assign a struct to a new variable or pass it to a function, the original becomes invalid—the compiler enforces single ownership at the type level. This is Rust's move semantics without the escape hatches that references and borrowing provide. If you want a type to be copied instead of moved, you annotate the struct definition with @copy, which enables value duplication.

Where Rust provides shared references (&T) and mutable references (&mut T) governed by the borrow checker's aliasing rules, Rue provides two simpler mechanisms: borrow and inout.

A borrow parameter grants read-only access to a value without copying it. An inout parameter grants temporary mutable access—the function can modify the value, and changes persist after the function returns. Critically, both are marked at the call site, not just in the function signature. When reading Rue code, you can immediately see which arguments a function will modify:

sort(inout values, borrow config);

The tutorial makes the design motivation explicit: "When you read code, you want to understand what it does without tracing through every function." In Go or Python, a function receiving a slice or object might mutate it invisibly. In Rue, mutation is always syntactically visible where the function is called.

This is genuinely appealing. One of Rust's persistent pain points is that understanding what a function does to its arguments requires reading the signature carefully—and even then, interior mutability patterns like RefCell can make the signature misleading. Rue's approach trades expressiveness for legibility.

The trade-off, however, is severe. Without general references, you cannot build self-referential data structures. Linked lists, trees, and graphs—the bread and butter of systems programming data structures—have no obvious implementation path in current Rue. The Hacker News discussion around the language's announcement surfaced this concern immediately: without references that can be stored in data structures, you cannot implement iterators that borrow from containers. This is not a missing feature that will be added later; it is a fundamental consequence of the design choice.

Klabnik has acknowledged this directly: "There is going to inherently be some expressiveness loss. There is no silver bullet." The question Rue poses is whether the expressiveness that remains is sufficient for a useful class of programs. The answer today is: we don't know yet.

What the Tutorial Reveals

The ten-chapter tutorial walks from installation through a capstone quicksort implementation. It covers variables, types, functions, control flow, arrays, structs, enums, and the borrow/inout system. The final chapter implements partitioning and recursive sorting, demonstrating how the language's features compose.

Working through it reveals a language that feels like a simplified Rust with the hard parts surgically removed. Pattern matching on enums is exhaustive, as in Rust. Structs have named fields and move semantics. Arrays are fixed-size with runtime bounds checking that panics on out-of-bounds access. Integers overflow-check by default.

The syntax is deliberately familiar to anyone who has written Rust, Go, or C. Function signatures look like Rust without lifetimes:

fn partition(arr: inout [i32; 5], low: u64, high: u64) -> u64

Control flow uses if/else and while without parentheses around conditions. There is no for loop—iteration requires manual index management with while, which feels like a notable omission even for an early-stage language.

What's conspicuously absent from the tutorial is any program that does something useful beyond computation. There is no file I/O, no string handling, no network access, no memory allocation. The only output mechanism is @dbg(), a built-in debug print. The actual hello.rue in the examples directory is revealing: it is fn main() -> i32 { 42 }. There are no strings, so there is no "Hello, World." The fizzbuzz example is equally telling—it returns integers (1 for Fizz, 2 for Buzz, 3 for FizzBuzz) because it cannot print the words. The specification explicitly excludes coverage of a standard library "when one exists."

The AI Development Story

The most widely discussed aspect of Rue is not its type system but how it was built. Klabnik's blog posts describe a process where he provided architectural direction and design decisions while Claude wrote the vast majority of the implementation code. The project's blog posts are co-credited to both Klabnik and Claude, with some posts authored solely by the AI.

The timeline is striking. The first commit landed on December 15, 2025. By December 22—one week later—the compiler could handle basic types, structs, control flow, and had accumulated 130 commits. By early January 2026, the project had 777 specification tests across two platforms and the compiler had grown to handle enums, pattern matching, arrays, and the borrow/inout system.

The repository now contains over 700 commits from 4 contributors, with 1,100+ GitHub stars. For a personal hobby project by a well-known developer, this represents meaningful interest—though not the kind of momentum that suggests organic community adoption.

This development model raises legitimate questions. When Claude writes the compiler and Claude writes the blog posts, what does it mean for a human to have "designed" the language? Klabnik's answer is that he makes all architectural and design decisions—what features to include, how the type system works, what trade-offs to accept—while the AI handles implementation. He compares it to an architect and a construction crew: the architect doesn't lay bricks, but the building reflects the architect's vision.

The analogy is imperfect. A construction crew doesn't suggest design changes mid-build based on patterns learned from every other building ever constructed. But the broader point—that directing implementation is itself a form of authorship—is reasonable, and Klabnik's thirteen years of language implementation experience give him credibility that a less experienced designer directing an AI would lack.

What the Source Code Reveals

The documentation and tutorial tell one story. The GitHub repository tells a more nuanced one. Digging into the examples directory and compiler crates reveals features in various stages of development that the official tutorial has not yet caught up with.

Most notably, generics exist as a preview feature. The examples/generics.rue file demonstrates Zig-style comptime type parameters:

fn max(comptime T: type, a: T, b: T) -> T {
    if a > b { a } else { b }
}

let bigger = max(i32, 10, 20);

The comptime T: type syntax tells the compiler to monomorphize—creating specialized versions (max__i32, max__bool, etc.) for each concrete type used at call sites. This is a meaningful step beyond what the tutorial covers, and it follows the Zig model rather than Rust's trait-bounded generics. Whether this approach will scale to real-world code—and whether it can support the kind of type-level abstraction that traits and interfaces provide—remains to be seen. You must compile with rue --preview comptime to access this feature, signaling that it is experimental even by Rue's standards.

The compiler architecture itself is surprisingly mature for a project of this age. The repository contains 18 separate crates: a lexer, parser, intermediate representation (rue-rir), an abstract intermediate representation (rue-air), control flow graph analysis (rue-cfg), code generation, linking, a fuzzer, a spec test runner, and a VS Code extension. This is not a toy single-file compiler—it is a modular pipeline that reflects real compiler engineering, even if the language it compiles remains minimal.

Beyond generics, the gaps are still significant. There are no traits or interfaces, so there is no polymorphism beyond what enums and comptime monomorphization provide. There are no closures or first-class functions. There is no error handling mechanism—functions can panic, but there is no Result type or equivalent. There are no modules or visibility controls. There are no methods on types. There is no string type.

The unchecked keyword provides an escape hatch similar to Rust's unsafe, allowing low-level memory operations while keeping such code "visibly separate from normal safe code." The specification includes chapters on unchecked code syntax and unchecked intrinsics, suggesting that Klabnik recognizes the eventual need for the kind of low-level access that Rust provides through its unsafe system.

The performance page tracks compilation metrics—time, memory, binary size—across x86-64 and ARM64 on both Linux and macOS, but provides no runtime benchmarks comparing Rue's generated code to C, Rust, or Go. This is understandable for a research project, but it means we cannot evaluate whether Rue's native compilation delivers competitive performance.

The Fundamental Question

Every new systems language must answer the same question: what programs can I write in this language that I couldn't write (or couldn't write as well) in an existing one?

For Rust, the answer was clear from early on: memory-safe systems programs without garbage collection pauses. For Go, it was concurrent network services with fast compilation. For Zig, it was a C replacement with better defaults and comptime.

Rue's answer, as it stands today, is: nothing. Not yet. You cannot write a program in Rue that you couldn't write more easily in any mainstream language, because Rue cannot perform I/O, allocate memory, manipulate strings, or interact with the operating system.

This is not a criticism so much as a statement of development stage. The interesting question is what Rue's answer could become if development continues. The borrow/inout model is genuinely simpler than Rust's borrow checker for the cases it handles. Generics are already emerging through the comptime preview. If Rue can stabilize them, grow a heap allocator, a string type, and enough standard library to write real programs—without reintroducing the complexity it was designed to avoid—it could serve programmers who find Rust's learning curve prohibitive but need more safety than C or Go provide.

That is a big "if." History is littered with languages that simplified an existing language's hard parts and then discovered that the hard parts existed for good reasons. Rust's borrow checker is complex because the problems it solves are complex. Removing it and replacing it with a simpler system necessarily means either accepting less expressiveness or finding a genuinely novel solution that the Rust team somehow missed in over a decade of research.

Klabnik is explicit that he doesn't claim to have found such a solution. Rue is a research project exploring a design space, not a product claiming to have mapped it.

Who Should Pay Attention

If you're looking for a language to write software in today, Rue is not it. The project's own documentation says so clearly and repeatedly.

If you're interested in programming language design, Rue is worth following for two reasons. First, the borrow/inout model is a clean articulation of an alternative to Rust's reference system, and watching it encounter real-world requirements will be educational regardless of whether it succeeds. Second, the AI-assisted development methodology is itself a data point in the ongoing question of what role AI can play in building complex software systems.

If you're a Rust programmer who has ever thought "there must be a simpler way to express this," Rue represents one concrete exploration of what "simpler" might look like—and what it costs. The language makes the trade-offs visible in a way that abstract arguments about borrow checker complexity do not.

And if you're Steve Klabnik, messing around with a hobby project after thirteen years of working on someone else's language, Rue looks like exactly the kind of thing a deeply experienced language person should be doing with their evenings and weekends.

Conclusion

Rue is best understood as three things simultaneously: a technical experiment in memory safety ergonomics, a methodological experiment in AI-assisted language development, and a personal project by someone with unusually deep expertise in the problem space. As a technical experiment, it has articulated a clean alternative to Rust's borrow checker that is worth studying even if it proves too restrictive for general use. As a methodological experiment, the speed of development—700+ commits and a working multi-platform compiler in weeks—is genuinely remarkable, though the long-term maintainability of AI-generated compiler code remains unproven. As a personal project, it is honest about its limitations in a way that many language announcements are not.

The language cannot do anything useful yet. It may never be able to. But the questions it asks—can memory safety be simpler? can one person with an AI build a compiler? what happens when you remove the borrow checker and try something else?—are worth asking. And the person asking them has spent over a decade earning the credibility to make the attempt interesting rather than naive.

Watch the GitHub repository. Read the specification. Try the tutorial if you're curious about what a post-Rust systems language might feel like. Just don't write anything important in it yet.

Review of "Crafting Interpreters" by Robert Nystrom

A.C. Jokela — Thu, 19 Feb 2026 16:30:00 GMT

Introduction

There is a particular category of programming book that transcends its subject matter, becoming not just a reference but an experience. "Crafting Interpreters" by Robert Nystrom belongs firmly in this category. Originally published in 2021 after six years of development, the book tackles what many programmers consider one of the most intimidating topics in computer science—building a programming language from scratch—and makes it not just accessible but genuinely enjoyable.

Nystrom is no stranger to technical writing that connects with practitioners. His earlier book "Game Programming Patterns" demonstrated a talent for explaining complex software concepts through clear prose and practical examples. With "Crafting Interpreters," he applies that same skill to language implementation, a domain traditionally guarded by dense academic texts and formal notation that sends most working programmers running.

The book's central premise is both ambitious and elegant: build the same programming language twice. First as a tree-walk interpreter in Java (called jlox), then as a bytecode virtual machine in C (called clox). This dual implementation strategy isn't just a structural gimmick. It serves a deep pedagogical purpose, allowing readers to first grasp the conceptual architecture of language processing in a high-level language before rebuilding everything from raw memory and pointer arithmetic. The result is a book that manages to teach compiler theory, language design, software architecture, and low-level systems programming simultaneously.

The entire text is freely available at craftinginterpreters.com, which speaks to Nystrom's commitment to making this knowledge widely accessible. The physical edition, published with care and featuring hand-drawn illustrations throughout, is worth owning for anyone who works through the material.

The Language: Lox

Before diving into implementation, Nystrom introduces Lox, the language both interpreters will execute. Lox is a dynamically typed, garbage-collected language with C-family syntax that supports first-class functions, closures, and class-based object orientation with single inheritance. It is deliberately modest in scope—no arrays, no module system, no standard library to speak of—but this restraint is precisely the point.

Every feature in Lox exists because it teaches something important about language implementation. Dynamic typing means building a runtime type system. Garbage collection means understanding memory management at the deepest level. Closures require wrestling with variable capture and lifetime semantics. Classes and inheritance demand method resolution and the vtable-like dispatch mechanisms that underpin most object-oriented languages. Lox is small enough to implement in a book but complex enough that implementing it forces the reader to confront every major challenge in language design.

The choice of a custom language rather than a subset of an existing one is significant. It frees Nystrom from having to explain why certain features are omitted or work differently than readers might expect. Lox is exactly what it needs to be, nothing more.

Part II: The Tree-Walk Interpreter (`jlox`)

The first implementation spans thirteen chapters and builds a complete interpreter in Java. Nystrom begins where every language implementation must—with scanning. The scanner chapter walks through converting raw source text into tokens, handling string literals, numbers, keywords, and the inevitable edge cases that make lexical analysis more interesting than it first appears.

From there, the book moves into parsing, where Nystrom introduces recursive descent parsing with a clarity that makes the technique feel almost obvious in hindsight. Rather than reaching for parser generators like YACC or ANTLR, every line of the parser is written by hand. This decision is characteristic of the book's philosophy: no black boxes, no magic, no dependencies. The reader understands every piece because the reader built every piece.

The chapters on expression evaluation and statement execution establish the runtime model, but the book truly hits its stride in the chapters on scope and environments. Nystrom's explanation of lexical scoping—using a chain of environment objects that form what he calls a "cactus stack"—is one of the clearest treatments of this topic in any programming text. The hand-drawn illustration of nested environments, with their parent pointers threading back through enclosing scopes, communicates in a single image what paragraphs of formal specification struggle to convey.

Functions and closures represent the first major conceptual challenge, and Nystrom handles them with characteristic patience. The problem of captured variables—where a closure must hold onto variables from an enclosing scope that may have already returned—is presented as a puzzle to be solved rather than a rule to be memorized. The resolver pass that performs static analysis to determine variable binding is introduced as a natural response to a concrete bug, not as an abstract compiler phase.

The object-oriented chapters add classes, methods, constructors, inheritance, and super expressions. By the time jlox is complete, the reader has built a language implementation capable of running recursive algorithms, managing object hierarchies, and handling the scoping rules that trip up even experienced programmers in production languages.

What makes this section exceptional is Nystrom's willingness to show the design process, not just the final design. When a naive approach creates a bug or performance problem, the reader sees it happen and participates in fixing it. This iterative development style mirrors how real software is built and teaches debugging intuition alongside language implementation.

Part III: The Bytecode Virtual Machine (`clox`)

If Part II is the approachable on-ramp, Part III is where the book reveals its true ambition. Across seventeen chapters, Nystrom rebuilds everything in C, this time compiling Lox to bytecode and executing it on a stack-based virtual machine. The motivation is made concrete early: jlox takes 72 seconds to compute the 40th Fibonacci number recursively, while C can do it in half a second. The bytecode VM will close that gap dramatically.

The transition from Java to C is itself educational. Readers who have grown comfortable with Java's automatic memory management, dynamic arrays, and hash maps must now implement all of these from scratch. Nystrom builds a dynamic array type, a hash table, and ultimately a mark-sweep garbage collector, all in service of the language implementation. These data structures are not taught in isolation—they emerge because the VM needs them.

The chunk and instruction design chapters teach the reader to think about data representation at the byte level. Each bytecode instruction is a single byte, followed by operands that encode constants, variable slots, or jump offsets. The disassembler that Nystrom builds alongside the VM is a thoughtful touch, providing a debugging tool that makes the otherwise invisible bytecode tangible.

The single-pass compiler that replaces jlox's separate parsing and resolution phases is a masterclass in practical compiler construction. Nystrom uses Pratt parsing for expressions—a technique he explains with such clarity that this chapter alone has become a widely referenced resource for anyone implementing expression parsers. The Pratt parser's elegant handling of precedence and associativity through a simple table of parsing functions is one of those ideas that, once understood, feels like it should have been obvious all along.

The chapters on closures in clox deserve special mention. Where jlox could lean on Java's garbage collector and object references to capture variables, clox must solve the "upvalue" problem explicitly. Nystrom introduces the concept of upvalues—runtime objects that represent captured variables—and walks through the mechanism by which stack-allocated locals are "closed over" and moved to the heap when their enclosing function returns. The complexity of this implementation, managed through careful incremental development, demonstrates why closures are considered one of the hardest features to implement correctly in a bytecode VM.

The garbage collection chapter is the book's peak of systems programming depth. Nystrom implements a mark-sweep collector, explaining reachability, root sets, and the tricolor abstraction. The treatment is practical rather than theoretical—the reader sees exactly when collection triggers, how objects are traced, and why the collector must handle the subtle case of the VM itself allocating memory during collection (which could invalidate pointers being traced). The self-adjusting heap threshold that balances collection frequency against memory usage is a detail that separates a textbook GC from one that works in practice.

Writing Style and Presentation

Nystrom's prose is the book's secret weapon. Technical writing about compilers tends toward one of two failure modes: impenetrable formalism or hand-waving oversimplification. Nystrom avoids both. His writing is conversational without being sloppy, precise without being dry. Footnotes contain genuine wit. Asides acknowledge the reader's likely confusion at exactly the moments when confusion is most natural.

The hand-drawn illustrations scattered throughout the book serve a purpose beyond aesthetics. They signal that this is a personal, crafted work rather than a mass-produced textbook. The diagrams of memory layouts, parse trees, and stack states during execution are clearer than their machine-generated equivalents in most compiler texts, partly because they include exactly the detail needed and nothing more.

The "Design Note" sections that appear between chapters are mini-essays on language design philosophy—why dynamic typing exists, what makes a feature "elegant," how language designers balance expressiveness against implementation complexity. These sections transform the book from a pure implementation guide into something closer to a meditation on programming language design as a creative discipline.

Strengths

The book's greatest achievement is making compiler construction feel like a natural extension of everyday programming rather than a specialized academic pursuit. By avoiding formal grammars, automata theory, and the mathematical notation that dominates traditional compiler texts, Nystrom demonstrates that you don't need a PhD to build a working language implementation.

The dual-implementation approach pays dividends throughout. Concepts that are murky in one implementation become clear in the other. The tree-walk interpreter makes the abstract concepts tangible; the bytecode VM reveals the performance and engineering considerations that production language implementations face. Together, they provide a stereoscopic view of language implementation that neither could achieve alone.

The no-dependency philosophy deserves praise. There is no lexer generator, no parser generator, no framework, no library. Every line of code in both implementations is written in the book and understood by the reader. This means that upon completion, the reader owns their understanding completely—there is no mysterious tool doing critical work behind the scenes.

The incremental development style produces a book that is remarkably difficult to get lost in. Each chapter begins with working code and ends with working code. The reader is never more than a few pages from being able to compile and run something. For a topic as complex as language implementation, this steady cadence of progress is essential for maintaining motivation.

Limitations

The book is not without its shortcomings. The choice of dynamic typing for Lox means that static type systems—one of the most active and important areas of modern language design—receive no coverage. Type inference, generics, algebraic data types, and pattern matching are absent. A reader completing both implementations still would not know how to add a type checker, which is arguably the most practically relevant compiler phase for working programmers today.

Optimization is largely unexplored. The clox VM is faster than jlox by virtue of being a bytecode interpreter written in C, but Nystrom does not cover constant folding, dead code elimination, register allocation, or any of the optimization passes that distinguish a teaching compiler from a production one. JIT compilation, increasingly the standard for high-performance language runtimes, is mentioned only in passing.

The error handling and recovery throughout both implementations is minimal. Production parsers need sophisticated error recovery to provide useful diagnostics. Nystrom acknowledges this gap but does not address it, leaving readers who want to build user-facing tools with significant work ahead of them.

Lox's deliberate simplicity means that several common language features—arrays, iterators, modules, pattern matching, exception handling—are left as exercises. While this keeps the book focused, it means that readers must figure out on their own how to implement the features that most real languages require. The gap between Lox and a practical language is significant.

Who Should Read This Book

"Crafting Interpreters" is ideal for working programmers who have always been curious about how languages work but have been intimidated by the traditional compiler literature. Comfortable familiarity with Java and C is assumed—this is not a book for learning either language. But the reader need not have any prior knowledge of compilers, formal languages, or automata theory.

Computer science students will find it an excellent companion to a formal compilers course, providing the practical intuition that textbooks like Aho's "Dragon Book" deliberately omit. Conversely, self-taught programmers who never took a compilers course will find this book fills a significant gap in their education.

Language enthusiasts who have tinkered with toy interpreters but never built anything with closures, classes, or garbage collection will find exactly the guidance they need to level up. And anyone who simply enjoys beautifully crafted technical writing will find the book rewarding even as a pure reading experience.

Conclusion

"Crafting Interpreters" is one of the best programming books published in recent years. It takes a subject that most programmers consider forbiddingly complex and renders it not just comprehensible but engaging. Nystrom's combination of clear writing, thoughtful pedagogy, practical focus, and genuine craft produces a book that teaches far more than its nominal subject. Beyond scanning, parsing, and code generation, the reader learns how to approach complex software design, how to build systems incrementally, and how to think about the tools they use every day at a deeper level.

The book will not make you a compiler engineer. It will not teach you how to build a production language runtime, optimize generated code, or implement a sophisticated type system. What it will do is demystify the machinery that powers every programming language you have ever used, and give you the confidence and foundation to explore further. For most programmers, that is more than enough. It is, in fact, exactly what was needed.

Upgrading ROCm 7.0 to 7.2 on AMD Strix Halo (gfx1151)

A.C. Jokela — Wed, 18 Feb 2026 16:00:00 GMT

Introduction

If you're running AMD's Strix Halo hardware -- specifically the Ryzen AI MAX+ 395 with its integrated Radeon 8060S GPU -- you already know the software ecosystem is a moving target. The gfx1151 architecture sits in an awkward spot: powerful hardware that isn't officially listed on AMD's ROCm support matrix, yet functional enough to run real workloads with the right driver stack. When ROCm 7.2 landed in early 2026, upgrading from 7.0.2 was a priority. The newer stack brings an updated HSA runtime, a refreshed amdgpu kernel module, and broader compatibility improvements that matter on bleeding-edge silicon.

This post documents the complete upgrade procedure from ROCm 7.0.2 to 7.2 on a production Ubuntu 24.04 system. It's not a theoretical exercise -- this was performed on a live server running QEMU virtual machines and network services, with the expectation that everything would come back online after a single reboot.

AMD's official documentation states that in-place ROCm upgrades are not supported. The recommended path is a full uninstall followed by a clean reinstall. That's exactly what we did, and the entire process took about 20 minutes of wall-clock time (excluding the reboot).

System Overview

The target system is a Bosgame mini PC running the Ryzen AI MAX+ 395 APU. If you've read the earlier review of this hardware, you'll be familiar with the specs. For context on this upgrade, here's what matters:

Hardware

CPU: AMD Ryzen AI MAX+ 395, 16 cores / 32 threads, Zen 5
GPU: Integrated Radeon 8060S, 40 Compute Units, RDNA 3.5 (gfx1151)
Memory: 32 GB DDR5, unified architecture with 96 GB allocatable to GPU
Peak GPU Clock: 2,900 MHz

Software (Pre-Upgrade)

OS: Ubuntu 24.04.3 LTS (Noble Numbat)
Kernel: 6.14.0-37-generic (HWE, pinned)
ROCm: 7.0.2
amdgpu-dkms: 6.14.14 (from repo.radeon.com/amdgpu/30.10.2)
ROCk Module: 6.14.14

Running Services

The system was actively serving several roles during the upgrade:

Five QEMU virtual machines (three x86, two aarch64)
A PXE boot server (dnsmasq) for the local network
Docker daemon with various containers

None of these services are tied to the GPU driver stack, so the plan was to perform the upgrade and reboot without shutting them down first. The VMs and network services would come back automatically after the reboot.

Why Upgrade

ROCm 7.0.2 worked on this hardware. Models loaded, inference ran, rocminfo detected the GPU. So why bother upgrading?

Three reasons:

Driver maturity for gfx1151: The amdgpu kernel module jumped from 6.14.14 to 6.16.13 between the two releases. That's not a minor revision -- it represents months of kernel driver development. On hardware that isn't officially supported, newer drivers tend to bring meaningful stability improvements as AMD's internal teams encounter and fix issues on adjacent architectures.
HSA Runtime improvements: ROCm 7.2 ships HSA Runtime Extension version 1.15, up from 1.11 in ROCm 7.0.2. The HSA (Heterogeneous System Architecture) runtime is the lowest layer of the ROCm software stack -- it handles device discovery, memory management, and kernel dispatch. Improvements here affect everything built on top of it.
Ecosystem alignment: PyTorch wheels, Ollama builds, and other ROCm-dependent tools increasingly target 7.2 as the baseline. Running 7.0.2 was becoming an exercise in version pinning and compatibility workarounds.

The Kernel Hold: Why It Matters

Before diving into the procedure, a note on kernel management. This system runs the Ubuntu HWE (Hardware Enablement) kernel, which provides newer kernel versions on LTS releases. At the time of this upgrade, the HWE kernel was 6.14.0-37-generic. The upstream kernel had already moved to 6.17, but we didn't want the ROCm upgrade to pull in a kernel that AMD's DKMS module might not build against.

The solution is apt-mark hold:

sudo apt-mark hold linux-generic-hwe-24.04 linux-headers-generic-hwe-24.04 linux-image-generic-hwe-24.04

This prevents apt from upgrading the kernel meta-packages, effectively pinning the system to 6.14.0-37-generic. The hold was already in place before the upgrade and remained untouched throughout. After the upgrade, we confirmed it was still active:

apt-mark showhold

linux-generic-hwe-24.04
linux-headers-generic-hwe-24.04
linux-image-generic-hwe-24.04

If you're running Strix Halo or any other hardware where kernel compatibility with amdgpu-dkms is uncertain, kernel holds are essential. A kernel upgrade that breaks the DKMS build means no GPU driver after reboot.

Upgrade Procedure

Step 1: Uninstall the Current ROCm Stack

AMD provides the amdgpu-uninstall script for exactly this purpose. It removes all ROCm userspace packages and the amdgpu-dkms kernel module in a single operation:

sudo amdgpu-uninstall -y

This command removed approximately 120 packages, including the full HIP runtime, rocBLAS, MIOpen, MIGraphX, ROCm SMI, the LLVM-based compiler toolchain, and the Mesa graphics drivers that ship with ROCm. The DKMS module was purged, which means the amdgpu kernel module was removed from the 6.14.0-37-generic kernel's module tree.

After the ROCm stack was removed, we purged the amdgpu-install meta-package itself:

sudo apt purge -y amdgpu-install

This also cleaned up the APT repository entries that amdgpu-install had configured in /etc/apt/sources.list.d/. The old repos -- repo.radeon.com/amdgpu/30.10.2, repo.radeon.com/rocm/apt/7.0.2, and repo.radeon.com/graphics/7.0.2 -- were all removed automatically.

Step 2: Clean Up Leftover Files

The package removal was thorough but not perfect. A few leftover directories remained in /opt/:

ls /opt/ | grep rocm

rocm-7.0.0
rocm-7.0.2
rocm-7.9.0

The rocm-7.0.0 directory was from a previous installation attempt. The rocm-7.9.0 was from an earlier experiment with a release candidate build. The rocm-7.0.2 directory contained a single orphaned shared library (libamdhip64.so.6) that dpkg couldn't remove because the directory wasn't empty. All three were cleaned up manually:

sudo rm -rf /opt/rocm-7.0.0 /opt/rocm-7.0.2 /opt/rocm-7.9.0

It's worth checking for stale ROCm directories after any uninstall. They consume negligible disk space but can confuse build systems and scripts that scan /opt/rocm* for active installations.

Step 3: Install the ROCm 7.2 Installer

AMD distributes ROCm through a meta-package called amdgpu-install. Each ROCm release has its own version of this package, which configures the appropriate APT repositories. The 7.2 installer was downloaded directly from AMD's repository:

cd /tmp
wget https://repo.radeon.com/amdgpu-install/7.2/ubuntu/noble/amdgpu-install_7.2.70200-1_all.deb
sudo apt install -y ./amdgpu-install_7.2.70200-1_all.deb
sudo apt update

After installation and apt update, three new repositories were active:

https://repo.radeon.com/amdgpu/30.30/ubuntu noble -- the kernel driver and Mesa components
https://repo.radeon.com/rocm/apt/7.2 noble -- the ROCm userspace stack
https://repo.radeon.com/graphics/7.2/ubuntu noble -- graphics libraries

The version numbering can be confusing. The amdgpu-install package version is 30.30.0.0.30300000-2278356.24.04, which maps to the amdgpu driver release 30.30. The ROCm version is 7.2.0. These are different version tracks that AMD maintains in parallel.

Step 4: Install ROCm 7.2

With the repositories configured, the actual installation was a single command:

sudo amdgpu-install -y --usecase=graphics,rocm

The --usecase=graphics,rocm flag tells the installer to include both the Mesa graphics drivers and the full ROCm compute stack. This is the right choice for a system that needs both display output and GPU compute capabilities.

The installation took approximately 10 minutes and included:

amdgpu-dkms 6.16.13: The kernel module, compiled via DKMS against the running kernel
Full ROCm 7.2 stack: HIP runtime, hipcc compiler, rocBLAS, rocFFT, MIOpen, MIGraphX, RCCL, ROCm SMI, ROCProfiler, and dozens of other libraries
Mesa graphics: Updated EGL, OpenGL, and Vulkan drivers from the amdgpu Mesa fork
ROCm LLVM toolchain: The LLVM-based compiler infrastructure that HIP uses for kernel compilation

The DKMS build is the critical step. During installation, DKMS compiled the amdgpu module against the kernel headers for 6.14.0-37-generic. The output confirmed a successful build:

depmod...
update-initramfs: Generating /boot/initrd.img-6.14.0-37-generic

The initramfs was regenerated to include the new module, ensuring it would be loaded at boot.

Step 5: Verify DKMS

Before rebooting, we confirmed the DKMS status:

dkms status

amdgpu/6.16.13-2278356.24.04, 6.14.0-37-generic, x86_64: installed
virtualbox/7.0.16, 6.14.0-36-generic, x86_64: installed
virtualbox/7.0.16, 6.14.0-37-generic, x86_64: installed
virtualbox/7.0.16, 6.8.0-100-generic, x86_64: installed

The new amdgpu module (6.16.13) was built and installed for 6.14.0-37-generic. Note that it only built for the currently running kernel, unlike VirtualBox which had modules built for older kernels as well. This is expected -- DKMS builds against available kernel headers, and the old kernel headers for 6.14.0-36 and 6.8.0-100 were still present from earlier installations.

Step 6: Reboot

sudo reboot

The server came back online in approximately 50 seconds.

Post-Reboot Verification

rocminfo

The first check after reboot was rocminfo, which queries the HSA runtime for available agents:

rocminfo

ROCk module version 6.16.13 is loaded
=====================
HSA System Attributes
=====================
Runtime Version:         1.18
Runtime Ext Version:     1.15
...
==========
HSA Agents
==========
Agent 1: AMD RYZEN AI MAX+ 395 w/ Radeon 8060S (CPU)
Agent 2: gfx1151 (GPU)
  Marketing Name:          AMD Radeon Graphics
  Compute Unit:            40
  Max Clock Freq. (MHz):   2900
  Memory Properties:       APU
  ISA 1: amdgcn-amd-amdhsa--gfx1151
  ISA 2: amdgcn-amd-amdhsa--gfx11-generic

Key observations:

ROCk module 6.16.13: The new kernel module loaded successfully.
Runtime Ext Version 1.15: Upgraded from 1.11 in ROCm 7.0.2.
gfx1151 detected: The GPU was recognized with its correct ISA identifier.
gfx11-generic ISA: ROCm 7.2 also exposes a generic gfx11 ISA, which allows software compiled for the broader RDNA 3 family to run on this device without gfx1151-specific builds.
APU memory: The memory properties correctly identify this as an APU with unified memory.

ROCm SMI

rocm-smi

Device  Node  Temp    Power     SCLK  MCLK     Fan  Perf  VRAM%  GPU%
0       1     33.0C   9.087W    N/A   1000Mhz  0%   auto  0%     0%

The GPU was visible and reporting telemetry. The 0% VRAM reading is expected on an APU -- rocm-smi reports dedicated VRAM usage, but on a unified memory architecture, GPU memory allocations come from system RAM and aren't reflected in this counter.

ROCm Version

cat /opt/rocm/.info/version

7.2.0

DKMS

dkms status

Confirmed amdgpu/6.16.13 remained installed for 6.14.0-37-generic after reboot.

PyTorch Validation

With the driver stack verified, the next step was confirming that PyTorch could see and use the GPU. ROCm 7.2 ships with prebuilt PyTorch wheels on AMD's repository.

Installing PyTorch for ROCm 7.2

We set up a Python virtual environment and installed the ROCm-specific wheels:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

The PyTorch wheel for ROCm 7.2 requires a matching ROCm-specific build of Triton. Both are available from AMD's manylinux repository. The order matters -- Triton must be installed first, since the PyTorch wheel declares it as a dependency with a specific version that doesn't exist on PyPI:

pip install https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/triton-3.5.1%2Brocm7.2.0.gita272dfa8-cp312-cp312-linux_x86_64.whl
pip install https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torch-2.9.1%2Brocm7.2.0.lw.git7e1940d4-cp312-cp312-linux_x86_64.whl
pip install https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torchvision-0.24.0%2Brocm7.2.0.gitb919bd0c-cp312-cp312-linux_x86_64.whl

These are the ROCm 7.2 builds for Python 3.12. AMD also provides wheels for Python 3.10, 3.11, and 3.13.

Smoke Test

import torch
print("PyTorch:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())
print("Device:", torch.cuda.get_device_name(0))
print("VRAM:", round(torch.cuda.get_device_properties(0).total_memory / 1e9, 1), "GB")

PyTorch: 2.9.1+rocm7.2.0.git7e1940d4
CUDA available: True
Device: AMD Radeon Graphics
VRAM: 103.1 GB

PyTorch detected the GPU through ROCm's HIP-to-CUDA translation layer. The 103.1 GB figure represents the total addressable memory on this unified-memory APU, which includes both the 96 GB GPU allocation and additional system memory accessible through the HSA runtime.

Note the use of torch.cuda despite this being an AMD GPU. ROCm's HIP runtime presents itself through PyTorch's CUDA interface, so all CUDA API calls in PyTorch (device selection, memory management, kernel launches) work transparently with AMD hardware.

Before and After Summary

Component	ROCm 7.0.2	ROCm 7.2.0
ROCm Version	7.0.2	7.2.0
amdgpu-dkms	6.14.14	6.16.13
ROCk Module	6.14.14	6.16.13
HSA Runtime Ext	1.11	1.15
amdgpu Repo	30.10.2	30.30
PyTorch	N/A	2.9.1+rocm7.2.0
Triton	N/A	3.5.1+rocm7.2.0
Kernel	6.14.0-37-generic	6.14.0-37-generic
Kernel Holds	In place	In place

Notes on gfx1151 Support

It's worth being explicit about the support situation. As of February 2026, gfx1151 (Strix Halo) is not listed on AMD's official ROCm support matrix. The supported RDNA 3 targets are gfx1100 (Navi 31, RX 7900 XTX) and gfx1101 (Navi 32). Strix Halo's gfx1151 is an RDNA 3.5 derivative that shares much of the ISA with gfx1100 but has architectural differences in the memory subsystem and compute unit layout.

In practice, ROCm 7.2 works on gfx1151. The kernel driver loads, rocminfo detects the GPU, and PyTorch can allocate tensors and dispatch compute kernels. The gfx11-generic ISA target in ROCm 7.2 is particularly helpful -- it provides a compatibility path for software that hasn't been explicitly compiled for gfx1151.

However, "works" and "fully supported" are different things. There are known quirks:

rocm-smi VRAM reporting: Always shows 0% on the APU since it only tracks discrete VRAM
No official PyTorch gfx1151 builds: The ROCm PyTorch wheels target gfx1100. They run on gfx1151 through ISA compatibility, but performance may not be optimal
Large model loading latency: Moving large models to the GPU device can be slow on the unified memory architecture, as the HSA runtime handles page migration differently than discrete GPU DMA transfers

If you're considering this hardware for production AI workloads, treat ROCm support as "functional but experimental." It works well enough for development, testing, and moderate inference workloads. For production training or latency-sensitive deployment, stick with hardware on AMD's official support list.

Rollback Plan

If the upgrade fails -- the DKMS module doesn't build, the GPU isn't detected after reboot, or something else goes wrong -- the rollback path is straightforward:

Uninstall ROCm 7.2:

sudo amdgpu-uninstall -y
sudo apt purge -y amdgpu-install

Reinstall ROCm 7.0.2:

wget https://repo.radeon.com/amdgpu-install/30.10.2/ubuntu/noble/amdgpu-install_30.10.2.0.30100200-2226257.24.04_all.deb
sudo apt install -y ./amdgpu-install_30.10.2.0.30100200-2226257.24.04_all.deb
sudo apt update
sudo amdgpu-install -y --usecase=graphics,rocm
sudo reboot

The entire rollback takes about 15 minutes. Keep the old amdgpu-install deb URL handy -- it's not linked from AMD's current download pages once a newer version is published.

Conclusion

Upgrading ROCm on hardware that isn't officially supported always carries some risk, but this upgrade from 7.0.2 to 7.2 on gfx1151 was uneventful. The procedure follows AMD's documented uninstall-reinstall approach with no deviations. The kernel hold strategy kept the kernel stable, the DKMS module built cleanly against 6.14.0-37-generic, and all post-reboot checks passed.

The improvements in ROCm 7.2 -- particularly the HSA runtime bump to 1.15 and the introduction of the gfx11-generic ISA target -- represent meaningful progress for Strix Halo users. The ecosystem is slowly catching up to the hardware. It's not there yet, but each release closes the gap.

For anyone running a Ryzen AI MAX+ 395 or similar Strix Halo hardware on Ubuntu 24.04, this upgrade is worth doing. The procedure is well-defined, the rollback path is clear, and the newer driver stack brings tangible benefits. Just remember to hold your kernel first.

Recommended Resources

Hardware

Bosgame M5 AI Mini PC (Ryzen AI MAX+ 395) - The system used in this post
GMKtec EVO X2 (Ryzen AI MAX+ 395) - Another Strix Halo mini PC option on Amazon

Books

Deep Learning with PyTorch by Stevens, Antiga, Huang, Viehmann - Comprehensive guide to building, training, and tuning neural networks with PyTorch
Programming PyTorch for Deep Learning by Ian Pointer - Practical guide to creating and deploying deep learning applications
Understanding Deep Learning by Simon Prince - Modern treatment of deep learning fundamentals

From Tree-Walker to Bytecode VM: Compiling Lattice

A.C. Jokela — Tue, 17 Feb 2026 18:00:00 GMT

Lattice is a programming language built around a crystallization-based phase system — values start as mutable "flux" and can be frozen into immutable "fix," with the runtime enforcing the transition and providing reactions, bonds, contracts, and temporal tracking around it. It's implemented in C with no external dependencies.

When I started building Lattice, a tree-walking interpreter was the obvious first move. You parse source into an AST, walk the nodes recursively, and evaluate as you go. It's straightforward, easy to debug, and lets you iterate on language semantics quickly without worrying about a second representation. Crafting Interpreters calls this approach "the simplest way to build an interpreter," and it's right.

But tree-walkers have well-known limitations. Every expression evaluation descends through function calls — eval_expr calling eval_binary calling eval_expr twice more. The overhead compounds. You're chasing pointers through heap-allocated AST nodes with poor cache locality. And the call stack of the host language (C, in Lattice's case) becomes tangled with the call stack of the guest language, making it harder to implement features like error recovery and coroutines cleanly.

Lattice v0.3.0 shipped a bytecode compiler and stack-based virtual machine alongside the tree-walker. In v0.3.1, the bytecode VM became the default for file execution, the interactive REPL, and the browser-based playground. The tree-walker is still available via --tree-walk, but the VM now handles everything. This post walks through the architecture of that VM, some design decisions that turned out to matter, and a mutation bug that only surfaces when you combine deep-clone-on-read semantics with in-place method dispatch.

Architecture Overview

The bytecode pipeline has three stages: lexing and parsing (shared with the tree-walker), compilation from AST to bytecode chunks, and execution on a stack-based VM. The compiler and VM together add about 8,200 lines of C to the codebase, bringing the total to around 33,000 lines.

A Chunk is the compilation unit — a dynamic array of bytecode instructions, a constant pool, and debug metadata mapping instructions back to source line numbers. The compiler walks the AST and emits bytes into a chunk. The VM reads bytes from the chunk and executes them against a value stack.

typedef struct {
    uint8_t  *code;          // bytecode array
    size_t    len, cap;
    LatValue *constants;     // constant pool
    size_t    const_len, const_cap;
    int      *lines;         // source line per instruction
    char    **local_names;   // slot → variable name (debug)
    size_t    local_name_cap;
} Chunk;

The VM itself is a for(;;) loop with a switch on the current opcode byte — the textbook approach. No computed gotos, no threaded dispatch, no JIT. Just a switch. On modern hardware with branch prediction, a well-organized switch over 62 opcodes is fast enough that the overhead is negligible compared to the cost of actual operations (string allocation, hash table lookups, deep cloning).

for (;;) {
    uint8_t op = READ_BYTE();
    switch (op) {
        case OP_CONSTANT: { ... }
        case OP_ADD:      { ... }
        case OP_CALL:     { ... }
        // 59 more cases
    }
}

The value stack holds 4,096 slots. The call frame stack holds 256 frames. Each CallFrame tracks its own instruction pointer, a base pointer into the value stack for its local variables, and an array of captured upvalues for closures. When you call a function, the VM pushes a new frame pointing at the callee's chunk. When the function returns, the frame pops and execution resumes in the caller.

The Instruction Set

Lattice's instruction set has 62 opcodes. Some are standard — OP_ADD, OP_JUMP_IF_FALSE, OP_RETURN. Others exist because of Lattice-specific semantics.

The phase system needs dedicated opcodes. OP_FREEZE pops a value, deep-clones it into a crystal region with VTAG_CRYSTAL tags, and pushes the frozen result. OP_THAW does the reverse. OP_MARK_FLUID sets the phase tag to VTAG_FLUID — this is what flux bindings emit after their initializer. OP_FREEZE_VAR and OP_THAW_VAR handle the case where freeze(x) targets a named variable and needs to write back the result, carrying extra operands to identify the variable's location (local slot, upvalue, or global name).

Phase reactions and bonds each have their own opcodes: OP_REACT, OP_UNREACT, OP_BOND, OP_UNBOND, OP_SEED, OP_UNSEED. These could theoretically be implemented as native function calls, but making them opcodes lets the compiler emit the variable name as a constant operand — the VM needs the name to look up the correct reaction/bond registration in its tracking tables, and encoding it in the bytecode avoids a runtime string lookup.

Structured concurrency uses an interesting hybrid. OP_SCOPE and OP_SELECT each carry a constant-pool index that stores a pointer to the original AST Expr* node. When the VM hits one of these opcodes, it invokes the tree-walking evaluator on that subtree. This is a deliberate design choice — the concurrency primitives involve spawning threads and managing channels, which requires the evaluator's full environment machinery. Rather than reimplement all of that in the VM, the bytecode compiler punts to the tree-walker for these specific constructs. The rest of the program runs on the VM; only scope and select blocks briefly drop into interpretation.

Closures and Upvalues

Closures are where bytecode VMs get interesting, and Lattice follows the upvalue model that Lua pioneered and Crafting Interpreters popularized.

When a function is defined inside another function and references variables from the enclosing scope, those variables need to outlive their original stack frame. The solution is upvalues — indirection objects that start pointing into the stack and get "closed over" when the variable goes out of scope.

typedef struct ObjUpvalue {
    LatValue *location;        // points to stack slot or &closed
    LatValue  closed;          // holds value after scope exit
    struct ObjUpvalue *next;   // linked list for open upvalues
} ObjUpvalue;

While the enclosing function is still executing, location points directly at the stack slot. When the enclosing function returns, OP_CLOSE_UPVALUE copies the stack value into the closed field and repoints location to &closed. The closure doesn't know or care about the switch — it always dereferences location. This is why upvalues work: they're a level of indirection that transparently survives stack frame destruction.

The compiler resolves variable references in three stages: first it checks local scope (resolve_local), then upvalues (resolve_upvalue, which walks the compiler chain recursively), then falls back to globals via OP_GET_GLOBAL. The OP_CLOSURE instruction is followed by a series of (is_local, index) byte pairs, one per upvalue, telling the VM whether to capture from the current frame's stack or from the parent frame's upvalue array.

A concrete example makes this clearer. Consider a counter factory:

fn make_counter() {
    flux count = 0
    return |n| { count += n; count }
}

let c = make_counter()
print(c(5))   // 5
print(c(3))   // 8

When make_counter returns, its stack frame is destroyed — but count needs to survive, because the returned closure references it. During compilation, the compiler sees that the closure's body references count, which is local to the enclosing make_counter. It emits an (is_local=true, index=1) upvalue descriptor. At runtime, OP_CLOSURE calls capture_upvalue(), which either reuses an existing ObjUpvalue pointing at that stack slot or creates a new one. When make_counter returns, OP_CLOSE_UPVALUE copies the stack value of count into the upvalue's closed field and repoints location. The closure keeps working, oblivious to the frame being gone.

One implementation detail worth noting: Lattice stores the upvalue array by repurposing the closure's captured_env field (normally an Env* in the tree-walker) and the upvalue count in the region_id field. This avoids adding new fields to the LatValue union, which matters when values are deep-cloned frequently — every field adds to the clone cost.

Compiling for the REPL

A REPL that runs on a bytecode VM needs different compilation from file execution. The difference is small but important.

In file mode, compile_module() compiles a complete program and terminates with OP_UNIT; OP_RETURN — the module returns unit, and any expression results along the way are discarded with OP_POP. This is the right behavior for scripts: you don't want every intermediate expression to accumulate on the stack.

In REPL mode, compile_repl() needs the opposite behavior for the last expression. When you type 42 at the REPL prompt, you want to see => 42. So if the last item in the compiled chunk is a bare expression statement, compile_repl() compiles the expression but skips the OP_POP, leaving the value on the stack. Then it emits OP_RETURN, and the VM receives the value as the chunk's return value.

bool last_is_expr = (prog->item_count > 0 &&
    prog->items[prog->item_count - 1].tag == ITEM_STMT &&
    prog->items[prog->item_count - 1].as.stmt->tag == STMT_EXPR);

if (last_is_expr)
    emit_byte(OP_RETURN, 0);       // value already on stack
else {
    emit_byte(OP_UNIT, 0);         // no expression — return unit
    emit_byte(OP_RETURN, 0);
}

For function definitions, struct declarations, and enum definitions, the result is unit, and the REPL silently suppresses the => output. This matches user expectations — defining a function shouldn't print anything. The effect in practice:

lattice> 42
=> 42
lattice> "hello" + " world"
=> "hello world"
lattice> flux x = 10
lattice> x * 2
=> 20
lattice> fn square(n: Int) -> Int { n * n }
lattice> square(7)
=> 49

Each line is independently compiled and executed on the persistent VM. Globals defined in one line (flux x = 10) are visible in subsequent lines because they're stored in the VM's environment, which persists across iterations. The Chunk for each line is freed after execution — constants that matter (like global variable values) have already been deep-cloned into the environment.

The other critical difference is enum persistence. compile_module() frees its known-enum registry after compilation, because the compiler is done. compile_repl() must not, because enums defined in REPL iteration N need to be visible in iteration N+1. The REPL calls compiler_free_known_enums() only on exit. The same lifetime concern applies to parsed programs — struct and function declarations store Expr* pointers that compiled chunks reference at runtime. The REPL accumulates all parsed programs in a dynamic array and frees them only when the session ends.

The Global Mutation Bug

This is the story I find most instructive, because it reveals a subtle interaction between two independently reasonable design decisions.

Lattice has deep-clone-on-read semantics. When you access a variable, the environment doesn't hand you a reference to the stored value — it hands you a fresh deep clone. This eliminates aliasing entirely: two variables never share underlying memory, passing a map to a function gives the function its own copy, and there's no way to create spooky action at a distance through shared mutable state.

bool env_get(const Env *env, const char *name, LatValue *out) {
    for (size_t i = env->count; i > 0; i--) {
        LatValue *v = lat_map_get(&env->scopes[i-1], name);
        if (v) {
            *out = value_deep_clone(v);  // always a fresh copy
            return true;
        }
    }
    return false;
}

This is expensive but correct. It gives Lattice pure value semantics without needing a borrow checker or persistent data structures.

The tree-walking evaluator handles in-place mutation (like array.push()) with a separate resolve_lvalue() mechanism that obtains a direct mutable pointer into the environment's storage, bypassing the deep clone. Push, pop, index assignment — these all go through resolve_lvalue and mutate the stored value directly.

The bytecode VM needed the same distinction. For local variables, this is straightforward: locals live on the value stack, and the VM has a direct pointer to them via frame->slots[slot]. I added OP_INVOKE_LOCAL, which takes a stack slot index as an operand and passes a pointer to vm_invoke_builtin():

case OP_INVOKE_LOCAL: {
    uint8_t slot = READ_BYTE();
    uint8_t method_idx = READ_BYTE();
    uint8_t arg_count = READ_BYTE();
    const char *method_name = frame->chunk->constants[method_idx].as.str_val;
    LatValue *obj = &frame->slots[slot];  // direct pointer

    if (vm_invoke_builtin(vm, obj, method_name, arg_count, local_var_name)) {
        // builtin mutated obj in-place — mutation persists
        break;
    }
    // ... fall through to closure/method dispatch
}

When .push() grows the array by reallocating obj->as.array.elems and incrementing obj->as.array.len, it's directly modifying the stack slot. The mutation persists because obj is the variable.

For globals, the situation is different. Globals live in the environment (a scope-chain of hash maps), and env_get() deep-clones. The generic OP_INVOKE opcode works by evaluating the receiver expression onto the stack — which, for a global variable, means emitting OP_GET_GLOBAL, which calls env_get(), which deep-clones — and then dispatching the method on the cloned value. After the builtin mutates the clone, OP_INVOKE pops and frees it. The mutation vanishes.

flux nums = [1, 2, 3]
nums.push(4)
print(nums)  // still [1, 2, 3] — the push mutated a clone

This is the kind of bug that's obvious in retrospect but invisible when you're implementing things one piece at a time. env_get() deep-cloning is correct. OP_INVOKE popping the receiver after dispatch is correct. Each piece behaves correctly in isolation. The bug emerges from their composition.

The fix is OP_INVOKE_GLOBAL — a new opcode that knows the receiver is a global variable and writes back after mutation:

case OP_INVOKE_GLOBAL: {
    uint8_t name_idx = READ_BYTE();
    uint8_t method_idx = READ_BYTE();
    uint8_t arg_count = READ_BYTE();
    const char *global_name = frame->chunk->constants[name_idx].as.str_val;
    const char *method_name = frame->chunk->constants[method_idx].as.str_val;

    LatValue obj_val;
    if (!env_get(vm->env, global_name, &obj_val)) {
        VM_ERROR("undefined variable '%s'", global_name); break;
    }

    if (vm_invoke_builtin(vm, &obj_val, method_name, arg_count, global_name)) {
        if (vm->error) { /* handle error */ }
        // Write back the mutated clone to the environment
        env_set(vm->env, global_name, obj_val);
        break;
    }
    // ... fall through for non-builtin methods
}

The compiler emits OP_INVOKE_GLOBAL when it sees a method call on an identifier that isn't a local variable or an upvalue:

case EXPR_METHOD_CALL: {
    if (e->as.method_call.object->tag == EXPR_IDENT) {
        int slot = resolve_local(current, e->as.method_call.object->as.str_val);
        if (slot >= 0) {
            // ... emit OP_INVOKE_LOCAL
        }
        int upvalue = resolve_upvalue(current, e->as.method_call.object->as.str_val);
        if (upvalue < 0) {
            // Not local, not upvalue — must be global
            // ... emit OP_INVOKE_GLOBAL
        }
    }
    // ... fall through to generic OP_INVOKE
}

This gives us three tiers of method dispatch: OP_INVOKE_LOCAL for locals (direct pointer, no clone), OP_INVOKE_GLOBAL for globals (clone + write-back), and OP_INVOKE for everything else (computed receivers like get_array().push(x), where there's nothing to write back to). With the fix:

flux nums = [1, 2, 3]
nums.push(4)
nums.push(5)
print(nums)  // [1, 2, 3, 4, 5] — mutations persist

All mutating builtins — push, pop, set, remove, insert, remove_at — now work correctly on global variables. The same pattern applies to maps, sets, and any other type with in-place methods.

The broader lesson is that deep-clone-on-read semantics create an impedance mismatch with in-place mutation. In a reference-based language, obj.push(x) just works — obj is a reference, and the mutation happens wherever the reference points. In a value-based language, you need to explicitly handle the write-back for every level of variable storage. The tree-walker's resolve_lvalue is one solution. The VM's tiered invoke opcodes are another. Both exist because of the same underlying tension.

The WASM Playground

Lattice's browser-based playground compiles the entire VM to WebAssembly via Emscripten. The WASM API exposes four functions: lat_init(), lat_run_line(), lat_is_complete(), and lat_destroy().

The playground runs the same bytecode VM as the native binary. Each line of input goes through the same pipeline: lex, parse, compile_repl(), vm_run(). The lat_is_complete() function checks bracket depth to determine whether the user is mid-expression, enabling multi-line input by waiting for balanced braces before compiling.

Previously the playground used the tree-walking evaluator, which meant code could behave differently in the browser than on the command line. Switching the WASM build to the bytecode VM eliminates that inconsistency — the playground, the REPL, and file execution all use the same compilation and execution path.

What Didn't Change

It's worth noting what the bytecode VM doesn't change about Lattice.

The value representation is identical. A LatValue is still a tagged union with a type tag, phase tag, and payload. Phase transitions still deep-clone data across heap regions. The dual-heap architecture — mark-and-sweep for fluid data, arena-based regions for crystal data — is unchanged. Global variables still live in a scope-chain environment.

The parser and AST are completely shared. The compiler reads the same Program structure that the tree-walker reads. A single set of test programs validates both execution paths — all 771 tests pass on both.

The phase system compiles one-to-one. freeze() becomes OP_FREEZE. thaw() becomes OP_THAW. Bonds, reactions, seeds, pressure constraints — each has a corresponding opcode that does exactly what the tree-walker's evaluator function did, just driven by bytecode dispatch instead of recursive AST traversal.

Performance

I haven't done rigorous benchmarking, and I'm deliberately not making performance claims. The motivation for the bytecode VM wasn't speed — it was consistency (one execution path everywhere) and architectural cleanliness (the VM is easier to extend than the tree-walker's deeply nested switch statements).

That said, bytecode VMs are generally faster than tree-walkers for the structural reasons mentioned earlier: better cache locality (sequential byte array vs. pointer-chasing through AST nodes), less call overhead (one switch dispatch vs. recursive function calls), and a compact representation that fits more of the program in cache. Whether this matters for Lattice programs depends on the workload. For a language whose core runtime cost is dominated by deep cloning, the dispatch overhead is rarely the bottleneck.

Looking Forward

The VM is feature-complete but not optimized. There's no constant folding, no dead code elimination, no register allocation (it's a pure stack machine). The OP_SCOPE and OP_SELECT concurrency opcodes still delegate to the tree-walker. The dispatch loop is a plain switch rather than computed gotos.

These are all well-understood optimizations with clear implementation paths. The point of v0.3.1 is that the bytecode VM is now the default, passes all tests, and handles the full language surface including the phase system. Optimization is a separate project.

The source code is at github.com/ajokela/lattice, and you can try it in the browser at lattice-lang.web.app. The bytecode VM, compiler, REPL, and all 62 opcodes are in four files: compiler.c, vm.c, chunk.c, and opcode.c.

git clone https://github.com/ajokela/lattice.git
cd lattice && make
./clat

Recommended Resources

Crafting Interpreters by Robert Nystrom - The definitive guide to building interpreters and bytecode VMs, and a major influence on Lattice's upvalue implementation
Writing A Compiler In Go by Thorsten Ball - Practical companion covering bytecode compilation and stack-based VMs
Engineering a Compiler by Cooper & Torczon - Comprehensive treatment of compiler internals from front-end to optimization
Compilers: Principles, Techniques, and Tools by Aho, Lam, Sethi, Ullman - The classic Dragon Book covering parsing, code generation, and optimization theory

Image Editing on 10-Year-Old GPUs: NVIDIA P40 vs AMD Strix Halo

A.C. Jokela — Tue, 17 Feb 2026 18:00:00 GMT

Introduction

There's a certain satisfaction in making old hardware do new tricks. When NVIDIA released the Tesla P40 in 2016, deep learning was still finding its footing. ImageNet classification was the benchmark everyone cared about, GANs were generating blurry faces, and the idea of a 57-billion-parameter image editing model would have seemed like science fiction.

Around the middle of 2017, when the P40 would have been seeing peak adoption in datacenters, I found myself in an advanced pattern recognition course, my final credits needed for a masters in computer science — the name hadn't been updated to reflect more contemporary terminology like "machine learning," let alone "deep learning." The textbook was Bishop's Pattern Recognition and Machine Learning, a book that managed to make Bayesian inference feel both rigorous and approachable. We spent the last two weeks of the course looking at deep learning using TensorFlow, but we didn't even have GPU infrastructure available. Everything ran on CPU. It would have been great to have experienced the P40 in its prime, when 24 GB of VRAM and 3,840 CUDA cores made it one of the most capable inference GPUs money could buy. Instead, I'm getting acquainted with it a decade later, asking it to do things its designers never imagined.

Fast forward to 2026, and here I am, running a 57-billion-parameter model on four of these decade-old GPUs — and comparing the results against AMD's latest Strix Halo APU, a chip that didn't exist until 2025.

The model in question is FireRed-Image-Edit-1.0 from FireRedTeam, a 57.7GB diffusion model built on the QwenImageEditPlusPipeline architecture. It takes an input image and a text prompt, then produces an edited version. The kind of thing that would have required a massive cloud GPU a couple of years ago.

This post documents the full journey: the precision pitfalls of running modern diffusion models on Pascal-era GPUs, the quantization trade-offs that make or break image quality, and the head-to-head performance comparison that produced some genuinely surprising results. All of the inference scripts and output images are available on GitHub.

The Hardware

NVIDIA Tesla P40 (2016)

The P40 was NVIDIA's inference-focused datacenter GPU from the Pascal generation. The key specs for our purposes:

Architecture: Pascal (sm_6.1)
CUDA Cores: 3,840
Memory: 24 GB GDDR5X
Memory Bandwidth: 346 GB/s
FP32 Performance: 12 TFLOPS
FP16 Performance: Limited — no native FP16 tensor cores
BF16 Support: None
Price today: ~$100-200 per card on the secondary market

I have four of these cards in a server, giving me 96 GB of total VRAM — but spread across four separate memory spaces, which introduces its own challenges.

AMD Ryzen AI MAX+ 395 / Strix Halo (2025)

AMD's Strix Halo is a different beast entirely. It's an APU — CPU and GPU on the same die, sharing the same memory pool:

GPU Architecture: RDNA 3.5 (gfx1151)
Compute Units: 40 CUs
Memory: 128 GB unified LPDDR5X (32 GB for CPU, 96 GB for VRAM)
Memory Bandwidth: ~256 GB/s (shared)
BF16 Support: Yes
FP16 Support: Yes (Fast F16 Operation)
ROCm: 7.9.0
Price: ~$2,000+ for the complete system

The unified memory architecture means all 96 GB is accessible to the GPU without any PCIe transfer overhead, and the entire model can live in a single memory space.

The Model: FireRed-Image-Edit-1.0

FireRed-Image-Edit is a diffusion-based image editing model with three major components:

Component	Size	Description
Transformer	40.9 GB	QwenImageTransformer2DModel, 60 layers
Text Encoder	16.6 GB	Qwen2.5-VL 7B vision-language model
VAE	~0.3 GB	AutoencoderKL for encoding/decoding images

Total: 57.7 GB of model weights. The scheduler is FlowMatchEulerDiscreteScheduler, and the pipeline uses true classifier-free guidance (CFG), which roughly doubles the memory needed during inference since it runs both conditional and unconditional passes.

The test task: take this input image and apply the prompt "Add a red hat on the cat" — the model draws a cat wearing a red hat onto the book cover, rendered in the style of the O'Reilly animal illustrations.

The P40 Challenge: When FP16 Breaks Everything

The Precision Problem

The first — and biggest — challenge with the P40s is numerical precision. Modern diffusion models are designed for BF16 (bfloat16), which has the same exponent range as FP32 (8 exponent bits, range ±3.4×10³⁸) but with reduced mantissa precision. The P40, being a Pascal-era GPU, supports neither BF16 nor proper FP16 tensor operations.

FP16 has only 5 exponent bits, giving it a range of ±65,504. This might seem sufficient, but the diffusion scheduler's internal sigma values and the VAE's convolution operations routinely produce intermediate values that overflow this range. The FlowMatchEulerDiscreteScheduler, in particular, works with sigma schedules that can produce large intermediate values during the noise prediction and scaling steps. When these overflow FP16's limited range, they become NaN or Inf, and these corrupt values propagate through every subsequent operation — matrix multiplications, attention computations, residual connections — until the entire tensor is garbage.

The result: NaN propagation that silently corrupts the entire pipeline, producing an all-black output image.

This was the most time-consuming discovery in the entire project. The model would load, the progress bar would advance through all 40 denoising steps without any indication of trouble, and then the output would be perfectly black — mean=0.0, min=0, max=0. No error messages. No warnings. No NaN detection exceptions. Just silent numerical corruption that only becomes visible when you look at the final image.

The debugging process was particularly frustrating because the corruption happens gradually. Partial NaN contamination in early steps doesn't crash anything — the attention mechanisms and residual connections continue to produce tensor outputs of the expected shapes. The model appears to be working normally right up until the final image is decoded from all-zero latents.

The FP32 Solution (and a Speed Surprise)

The fix was to run the entire pipeline in FP32 — scheduler, VAE, and all non-quantized transformer layers. The quantized weights themselves stay compressed (INT8 or NF4), but every arithmetic operation uses full 32-bit precision.

It wasn't enough to just set the quantization compute dtype to FP32 — that only fixes the dequantized matmul operations inside the quantized layers. The scheduler's sigma arithmetic, the VAE's convolution operations, and the non-quantized components (layer norms, biases, attention scaling) all needed FP32 as well. Similarly, loading the pipeline with torch_dtype=torch.float32 but leaving the transformer's non-quantized layers in FP16 caused a dtype mismatch in the attention mechanism — PyTorch's scaled dot-product attention requires query, key, and value tensors to share the same dtype. Every component in the computational chain needed to be FP32.

The one exception is the text encoder, which runs once before the denoising loop begins. It stays in FP16 on its own GPU, and its output embeddings are upcast to FP32 when transferred to the main device. This is safe because the text encoder doesn't participate in the iterative process where precision errors compound.

Here's where things got interesting: FP32 was actually faster than FP16 on the P40. The first attempts with FP16 ran at approximately 9 minutes per denoising step. After switching to FP32, the same operations completed in about 2.4 minutes per step with NF4, and 1.5 minutes per step with INT8. The P40's FP32 throughput is its native strength — it was designed for FP32 datacenter inference, after all. FP16 on Pascal is handled through slower pathways that add overhead rather than saving it.

Multi-GPU Device Orchestration

With 57.7 GB of model weights and only 24 GB per GPU, some form of model sharding or quantization is mandatory. After extensive testing, the optimal configuration for the P40s turned out to be:

GPU 0: INT8-quantized transformer (~22 GB)
GPU 1: Text encoder in FP16 (~16.6 GB)
GPU 2: VAE in FP32 (~6.6 GB including decode workspace)
GPU 3: Unused

This layout requires significant monkey-patching of the diffusers pipeline. The _execution_device property must be overridden to ensure latents are created on the correct GPU. The encode_prompt method needs patching to route inputs to the text encoder's GPU and move the resulting embeddings back. And for the INT8 configuration, the VAE's encode and decode methods need wrappers to handle cross-device tensor transfers.

The text encoder stays in FP16 because it fits on a single GPU and its outputs are immediately upcast to FP32 when moved to the main device. This is safe because the text encoder runs once at the beginning — it doesn't participate in the iterative denoising loop where precision matters most.

Quantization Quality: INT8 vs NF4

With the FP32 pipeline in place, I tested both INT8 (8-bit) and NF4 (4-bit) quantization for the transformer:

NF4 (4-bit quantization): The NF4 approach uses bitsandbytes' normalized float 4-bit quantization with double quantization enabled. The transformer compresses from 40.9 GB to roughly 10 GB, easily fitting on a single P40 alongside the VAE. However, the output quality was significantly degraded — heavy noise and grain throughout the image, even at the full 40 denoising steps. Each denoising step introduces small numerical errors from the 4-bit weight approximations, and these errors compound across 40 iterations.

INT8 (8-bit quantization): INT8 produced dramatically better results. The output was clean and sharp, visually comparable to what you'd expect from full-precision inference on a modern GPU. The 8-bit precision preserves enough information in the weights that the per-step errors don't accumulate into visible artifacts.

The trade-off is memory: the INT8 transformer occupies ~22 GB, nearly filling an entire P40. This is why the VAE had to move to a third GPU — there wasn't enough headroom on GPU 0 for the VAE's convolution workspace during the decode phase. An early attempt that kept the VAE on GPU 0 ran all 40 denoising steps successfully, only to crash with an out-of-memory error at the very last operation.

The Strix Halo Experience: Simplicity Wins

BF16 Full Precision

Running the same model on the Strix Halo was refreshingly simple. With 96 GB of unified VRAM and native BF16 support, the entire pipeline loads in a few lines:

pipe = QwenImageEditPlusPipeline.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda:0")

No quantization. No multi-GPU patching. No device transfer hooks. No FP32 workarounds. The model loads in BF16 and runs natively.

During inference, the pipeline consumed approximately 75 GB of VRAM (the true CFG doubles the workspace requirements), well within the 96 GB budget.

The first run did take about 35 minutes of JIT kernel compilation before producing any inference steps — ROCm compiles HIP kernels for the gfx1151 architecture on first use. During this phase, the GPU sits at 100% utilization with no visible progress, which can be alarming if you're not expecting it. The GPU temperature climbed from 31°C idle to 69°C, and power draw went from 9W to 119W as the compiler worked through the hundreds of unique kernel configurations needed by a 60-layer transformer. These compiled kernels are cached, so subsequent runs skip this overhead entirely.

Quantization on Strix Halo: Does It Help?

Given the surprising performance parity between the two systems at full precision, I tested whether quantization could speed up the Strix Halo by reducing memory traffic. The theory was that if the workload is memory-bandwidth-limited, smaller model weights should mean faster inference.

The results were definitive:

Configuration	Per-Step Time	40-Step Estimate	VRAM Used
BF16 (full precision)	82.6s	55 min	~75 GB
NF4 (4-bit)	83.5s	56 min	~30 GB
INT8 (8-bit)	94.9s	63 min	~44 GB

NF4 quantization produced virtually identical speed to full BF16. The model shrank from 75 GB to 30 GB of VRAM usage, but inference time didn't improve at all. INT8 was actually slower — the bitsandbytes INT8 matmul path adds dequantization overhead that more than offsets any memory bandwidth savings.

This tells us something important about the Strix Halo's performance profile for this workload: it's compute-bound, not memory-bound. The RDNA 3.5 GPU's 40 compute units are the bottleneck, not the LPDDR5X memory bandwidth. Reducing the model size doesn't help because the GPU is already busy with arithmetic, not waiting on memory.

This contrasts with LLM inference workloads (text generation), where the Strix Halo's large memory pool is a genuine advantage — LLM token generation is almost entirely memory-bound, making quantization directly translate to speed improvements. Each token generation pass reads the entire model's weights but performs relatively little computation per weight. Diffusion models are the opposite: each denoising step runs a full forward pass through 60 transformer layers with dense matrix multiplications, attention computations, and residual connections. The arithmetic intensity is much higher, putting the pressure squarely on the GPU's compute units rather than its memory subsystem.

Head-to-Head: The Numbers

Here's the complete performance comparison across all tested configurations:

System	Configuration	Per-Step	40 Steps	Image Quality
Strix Halo	BF16 full precision	82.6s	55 min	Clean, sharp
Strix Halo	NF4 (4-bit)	83.5s	56 min	Clean (10-step test)
Strix Halo	INT8 (8-bit)	94.9s	63 min	Clean (10-step test)
4× P40	INT8 + FP32 pipeline	87.5s	58 min	Clean, sharp
4× P40	NF4 + FP32 pipeline	145.9s	97 min	Heavy noise/grain

The headline result: a single AMD Strix Halo APU from 2025 is about 6% faster per step than four NVIDIA P40s from 2016 running INT8-quantized inference. That's not exactly the generational leap you might expect from a decade of GPU evolution.

To be fair, the comparison isn't entirely apples-to-apples. The P40 is running an 8-bit quantized model (less computation per step but with dequantization overhead), while the Strix Halo runs the full BF16 model. The P40's dedicated GDDR5X provides 346 GB/s of bandwidth to a single GPU, while the Strix Halo's LPDDR5X shares its ~256 GB/s between the CPU and GPU. And the P40 setup requires three GPUs working in concert, while the Strix Halo uses a single unified memory space.

Lessons Learned

Old GPUs Are Surprisingly Capable

Four P40s at ~$500 total produce inference quality and speed that's competitive with a $2,000+ modern APU system. The P40's 346 GB/s memory bandwidth per card and strong FP32 throughput remain relevant even for models that were designed for hardware two generations newer. The main challenge is software engineering — working around the precision limitations and multi-GPU complexity takes significant effort.

Precision Matters More Than Speed

The single most impactful discovery in this project was that FP16 silently corrupts diffusion model outputs on Pascal GPUs. There are no error messages, no NaN warnings during inference — just a black image at the end. The fix (using FP32 everywhere) actually improved performance, which was counterintuitive. The lesson: when dealing with older hardware, always validate your numerical precision assumptions before optimizing for speed.

Quantization Is Not Free

On the P40s, INT8 quantization was essential (the model simply wouldn't fit otherwise) and produced excellent results. NF4 was too aggressive — the 4-bit precision degraded output quality visibly.

On the Strix Halo, quantization was unnecessary and even counterproductive. INT8 added overhead without any speed benefit, and NF4 didn't save time despite dramatically reducing memory usage. The takeaway: quantization's value depends entirely on your bottleneck. If you're compute-bound, smaller weights don't help.

Unified Memory Is Underrated

The Strix Halo's greatest advantage wasn't raw performance — it was simplicity. Loading a 57.7 GB model into a single 96 GB memory space eliminates an entire category of engineering problems: no device placement, no cross-GPU tensor transfers, no monkey-patching encode/decode methods, no VAE OOM surprises at the decode step. The inference script for the Strix Halo is about 50 lines. The P40 version is over 150, most of it careful device orchestration code.

For anyone who values development velocity and code maintainability over squeezing the last dollar of cost-efficiency out of used datacenter hardware, unified memory APUs have a compelling argument even when they don't win on raw throughput.

What About Newer NVIDIA GPUs?

It's worth putting these numbers in context. An NVIDIA RTX 4090 with 24 GB of VRAM and native BF16/FP16 tensor core support would likely run this model (with INT8 quantization) at roughly 10-15 seconds per step — 5-8x faster than either system tested here. An A100 with 80 GB could run it unquantized in BF16 at similar or better speeds. The P40 and Strix Halo are both firmly in the "budget/accessible" tier of AI hardware.

The more interesting comparison is cost-per-step. Four P40s from eBay cost about $500 total (plus a server that can host them). The Strix Halo system runs about $2,000+. Both produce essentially the same result at the same speed. The P40 route demands more engineering knowledge; the Strix Halo route demands more money.

Conclusion

Both systems successfully ran a 57.7 GB diffusion model that would have been considered impossibly large for consumer hardware just a few years ago. The P40s did it through clever quantization and multi-GPU orchestration. The Strix Halo did it by brute force — 96 GB of memory and native BF16 support.

The performance story is more nuanced than "newer is always better." For diffusion model inference, the NVIDIA P40 — a card you can buy for $100 on eBay — remains remarkably competitive when properly configured. It requires more engineering effort, and you need to know the precision pitfalls, but the results speak for themselves.

The Strix Halo's strength lies not in raw speed but in its unified memory architecture and modern instruction set support. It eliminates the multi-GPU complexity entirely, runs native BF16 without precision hacks, and provides a development experience that's orders of magnitude simpler. For iterating on models, testing new architectures, or just avoiding the headaches of cross-device tensor management, that simplicity has real value.

If you're considering hardware for running large diffusion models locally, the choice comes down to how you value your time versus your budget. Four P40s and a weekend of debugging will get you to roughly the same place as a Strix Halo system that just works out of the box. Both paths lead to a cat in a red hat.

Recommended Resources

Hardware

NVIDIA Tesla P40 24GB - The GPU used in this post. Available on eBay for a fraction of the original price. You'll need a server with PCIe x16 slots and adequate cooling.
GMKtec EVO-X2 (AMD Ryzen AI MAX+ 395) - A compact Strix Halo mini PC with 128GB unified LPDDR5X 8000MHz, WiFi 7, and USB4. A representative platform for running large models on Strix Halo.

Books

Pattern Recognition and Machine Learning by Christopher M. Bishop - The classic that introduced many to Bayesian methods and kernel machines. Still one of the best foundations for understanding the statistical principles behind modern ML.
Hands-On Generative AI with Transformers and Diffusion Models by Omar Sanseviero, Pedro Cuenca, Apolinário Passos, and Jonathan Whitaker - A practical guide to building and fine-tuning diffusion models using the Hugging Face ecosystem, including the diffusers library used in this post.
Understanding Deep Learning by Simon J.D. Prince - A thorough modern treatment of deep learning fundamentals through diffusion models, with excellent visualizations and mathematical rigor.

Part 4: 132 Tests, Zero Failures - Verifying the Sampo CPU on Real Hardware

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

In Part 1, we designed the Sampo 16-bit RISC architecture. In Part 2, we synthesized it to an ECP5 FPGA on the ULX3S board. In Part 3, we built an LLVM backend so Rust could compile for it. But there was a glaring gap in the project: we'd never systematically verified that the hardware actually implements the ISA correctly.

The "Hello, Sampo!" demo program exercises maybe 10 of the CPU's 66 instructions. The LLVM backend generates code that assumes the hardware matches the spec. If a single instruction is subtly wrong - a carry flag not set, a branch offset miscalculated, a byte load sign-extending when it shouldn't - the entire toolchain is built on sand.

This post documents the process of building a comprehensive test suite, running it in simulation, finding a real pipeline hazard bug in the CPU, and then the surprisingly treacherous journey of getting those tests running on real FPGA hardware.

The Test Strategy

The approach is straightforward: write assembly programs that exercise every instruction in the ISA, compare results against known-good values, and report PASS or FAIL over UART. The testbench monitors the serial output, and if it sees "FAIL" anywhere, the test run fails.

Each test follows the same pattern:

; Load known inputs
LIX  R8, 0x1234
LIX  R9, 0x5678

; Execute the instruction under test
ADD  R10, R8, R9

; Check the result
MOV  R4, R10          ; actual value
LIX  R5, 0x68AC       ; expected value
JALX check_eq         ; prints PASS or FAIL

The check_eq subroutine compares R4 (actual) against R5 (expected) and prints the result over the UART. This makes the test output human-readable and machine-parseable:

=== ALU Tests ===
ADD basic: PASS
ADD zero: PASS
ADD carry out: PASS
ADD overflow: PASS
SUB basic: PASS
...
Done.

The Test Framework

Every test program begins with a block of helper subroutines that handle UART communication and result reporting. The core is a busy-wait loop that polls the MC6850-compatible UART status register:

.equ ACIA_STATUS 0x80
.equ ACIA_DATA   0x81

print_char:
    ; R5 = character to output
.wait:
    INI  R6, ACIA_STATUS    ; Read status register
    AND  R7, R6, R6         ; Copy to R7
    ADDI R7, -2             ; Check if TX ready (bit 1)
    BNE  .wait              ; Loop until ready
    OUTI ACIA_DATA, R5      ; Send character
    JR   RA                 ; Return

The check_eq helper prints "PASS" or "FAIL" based on a register comparison, and the print_str helper walks a null-terminated string byte by byte. These routines are duplicated in each test file rather than linked - there's no linker in this toolchain, just a single-file assembler.

Test Coverage

We organized the tests into 10 programs, each targeting a specific area of the instruction set:

Test Program	Instructions Tested	Test Count
test_alu	ADD, SUB, AND, OR, XOR, NEG + flags	20
test_addi	ADDI with signed immediates + flags	10
test_shift	SLL, SRL, SRA, ROL, ROR, SWAP (1/4/8-bit variants)	17
test_muldiv	MUL, MULH, DIV, DIVU, REM, REMU	12
test_loadstore	LW, LB, LBU, SW, SB + offset variants	11
test_branch	All 16 branch conditions (taken + not taken)	24
test_jump	J, JR, JALR, JX, JALX	6
test_stack	PUSH, POP, CMP, TEST, MOV	12
test_misc	EXX, GETF, SETF, SCF, CCF, NOP	9
test_extended	ADDIX, SUBIX, ANDIX, ORIX, XORIX, SLLX, SRLX, SRAX	11
Total		132

The branch tests are particularly thorough - each of the 16 conditions (BEQ, BNE, BLT, BGE, BLTU, BGEU, BMI, BPL, BVS, BVC, BCS, BCC, BGT, BLE, BHI, BLS) gets tested both for the taken and not-taken case. We set up flags with arithmetic, then verify the branch goes the right way.

Finding a Real Bug: The Pipeline Hazard

The first time we ran the full test suite in simulation, 130 of 132 tests passed. Two tests in test_loadstore were failing: the multi-word store/load test and a load with offset test.

The failing pattern was consistent: any test that performed a store followed immediately by a load from a different address would read stale data. The load would return the value from the previous memory operation instead of the current one.

The root cause was a pipeline hazard between the MEMORY and FETCH states. Here's what was happening:

Cycle N:   MEMORY state - store completes, mem_ready asserts
Cycle N+1: FETCH state  - new instruction fetch begins

The problem: mem_ready is a one-cycle delayed version of mem_valid (because the RAM is synchronous). When the CPU transitions from MEMORY to WRITEBACK to FETCH, the mem_ready signal from the store was still asserted during the first cycle of the next FETCH. The CPU latched the stale mem_rdata from the previous store operation as if it were the new instruction.

The fix was to add a WRITEBACK state after every MEMORY operation - not just loads, but stores too. This gives mem_ready a cycle to deassert before the next FETCH begins:

Before: MEMORY → FETCH          (mem_ready still high from store)
After:  MEMORY → WRITEBACK → FETCH  (mem_ready deasserts during WRITEBACK)

A one-line change to the next-state logic:

`ST_MEMORY: begin
    if (mem_ready) begin
        // Always go through WRITEBACK after MEMORY.
        // For stores: allows mem_ready to deassert before
        // next FETCH (prevents stale rdata latch).
        next_state = `ST_WRITEBACK;
    end
end

This is exactly the kind of bug that simulation catches and manual inspection misses. The instruction executes correctly in isolation - it's only the interaction between consecutive memory operations that triggers the hazard. After the fix, all 132 tests passed in simulation.

Taking It to the FPGA

With simulation clean, the next step was running the tests on real hardware. The ULX3S board has an FTDI FT231X USB-serial chip connected to the FPGA, so UART output appears on a serial port at 115200 baud.

There was an immediate practical problem: the test programs run fast. At 12.5 MHz, the entire 20-test ALU suite completes in about 30 milliseconds. By the time openFPGALoader finishes programming the FPGA and releases the USB port, the test output is long gone. The FTDI chip has a small receive buffer, but 364 characters of test output overflows it before you can open the serial port.

The solution: patch the hex files to loop instead of halting. Replace the HALT instruction with a delay loop followed by a jump back to the reset vector. The test runs, outputs its results, waits about half a second, and starts over. You can open the serial port at any time and catch a complete iteration.

The Delay Loop Patch

The hex_loop_patch.py script performs binary patching on the assembled hex files. It finds the HALT instruction (encoded as 0xE100) and replaces it with a delay loop:

; Delay ~0.38 seconds at 12.5 MHz
    LIX  R8, 0x0008       ; outer counter
outer:
    LIX  R9, 0xFFFF       ; inner counter = 65535
inner:
    ADDI R9, -1
    BNE  inner
    ADDI R8, -1
    BNE  outer
    JX   0x0100            ; jump back to reset vector

The first version of this script inserted these 10 words at the HALT position. This seemed obviously correct. The tests ran on FPGA. Characters appeared on the serial port.

They were the wrong characters.

The Address Shift Bug

The FPGA output for the "Hello, Sampo!" test program was \x08\x08\x08\x08 - four backspace characters, repeating forever. The ALU test suite showed truncated output with roughly 45% of characters missing. Same pattern at 12.5 MHz and 6.25 MHz, ruling out timing violations. Simulation with realistic UART timing (1,080 cycles per byte, matching the hardware baud rate) passed perfectly.

I spent considerable time investigating the wrong theories. Was the UART transmitter dropping bytes? Was there a clock domain crossing issue? Was $readmemh in Yosys interpreting the hex file differently from Icarus Verilog? None of these panned out.

The breakthrough came from staring at \x08. That's the byte value 8. Where would 8 come from? The "Hello, Sampo!" program loads its message pointer with LIX R4, message where message is the label for the string data. In the assembled hex, message resolves to address 0x011E - the byte immediately after the HALT instruction.

And there it was. Look at the assembly structure:

done:
    HALT                    ; address 0x011C
message:
    .asciz "Hello, Sampo!\n" ; address 0x011E

The string data lives immediately after HALT. When hex_loop_patch.py inserts 10 words of delay loop code at the HALT position, it pushes the string data down by 20 bytes. But the LIX R4, 0x011E instruction still points to the original address. At 0x011E there's now the second word of LIX R8, 0x0008 - which contains the value 0x0008. The low byte is 0x08.

The CPU faithfully reads byte 0x08 from the patched address, outputs it via UART, advances the pointer to 0x011F where the high byte is 0x00 (the null terminator), and stops. One \x08 per iteration, four iterations captured. Mystery solved.

This same address shift corrupted every test program. The test strings ("ADD basic: ", "PASS\n", etc.) all live after HALT and all got displaced. The CPU was reading from locations that now contained delay loop machine code instead of ASCII text. Some fragments of text survived because adjacent strings partially overlapped with their shifted locations, producing the truncated output we saw.

The Fix

The correct approach: don't shift any data. Place the delay loop at address 0x0000 - the 256 bytes of unused memory before the 0x0100 reset vector - and replace the single-word HALT with a single-word relative J (jump) instruction that jumps backward to the loop code. One word replaces one word. No data moves.

# Place delay loop at address 0x0000 (unused space)
for i, w in enumerate(LOOP_PATCH):
    words[loop_base + i] = w

# Replace HALT with J instruction to address 0x0000
# J encoding: opcode 0x9, 12-bit signed offset
# target = PC + 2 + (sign_extend(offset) << 1)
offset = (target_addr - halt_addr - 2) // 2
j_word = 0x9000 | (offset & 0xFFF)
words[halt_idx] = j_word

There's a subtle complication: the J instruction shares opcode 0x9 with JR (register indirect jump) and JALR (jump and link register). The decoder distinguishes them by specific bit patterns in the offset field. If the calculated offset happens to have bits[3:0] == 0x1 and bits[11:8] != 0xF, the decoder interprets it as JALR instead of J. The script tries successive target addresses (0x0000, 0x0002, 0x0004, ...) until it finds one that doesn't collide with the JR/JALR encoding space.

After the fix, the patched hex files have exactly the same number of words as the originals. The only changes are the delay loop code written to the zero page and the HALT word replaced with a backward jump.

With the corrected patcher, the "Hello, Sampo!" program finally works on the FPGA - looping cleanly with zero character loss:

The Testbench: Trusting but Verifying

One important discovery during this process: the simulation testbench had tx_ready = 1 permanently. The simulated UART never pushed back on the CPU - it accepted every byte instantly. This meant the CPU's busy-wait loop (INI R6, ACIA_STATUS / ADDI R7, -2 / BNE wait) was never actually tested in simulation. The status register always returned "ready," so the loop body executed zero times.

On real hardware, the UART transmitter takes about 87 microseconds per byte at 115200 baud. The busy-wait loop runs hundreds of times per character, exercising the INI instruction, the AND/ADDI flag-setting sequence, and the BNE branch in a tight loop. If any of those instructions had a subtle bug, it would only manifest on hardware.

We added realistic UART timing to the testbench:

parameter TX_BYTE_CYCLES = 108 * 10;  // ~1080 cycles per byte
reg [15:0] tx_delay_cnt;

always @(posedge clk) begin
    if (tx_valid && tx_ready) begin
        tx_ready <= 0;
        tx_delay_cnt <= TX_BYTE_CYCLES;
    end else if (tx_delay_cnt > 0) begin
        tx_delay_cnt <= tx_delay_cnt - 1;
        if (tx_delay_cnt == 1)
            tx_ready <= 1;
    end
end

With this change, simulation exercises the same code paths as the hardware. All 132 tests still pass - the UART flow control logic was correct all along, it just wasn't being tested.

Running All Tests on the FPGA

Your browser does not support the video tag.

With the patch bug fixed, we ran the complete suite. Each test requires a separate FPGA build (Yosys synthesis, nextpnr place-and-route, ecppack bitstream generation), programming via JTAG, and serial capture. The Makefile automates the entire pipeline:

fpga-%: $(BUILD_DIR)/sampo_%.bit
    openFPGALoader -b ulx3s $<
    sleep 1
    python3 fpga_capture.py $(SERIAL_PORT) $(SERIAL_BAUD) 5

The fpga_capture.py script opens the serial port, discards the first partial iteration (we might join mid-stream), waits for the === ... === header line that starts each test, captures everything until the header repeats, and outputs one clean iteration.

The results:

========================================
=== FPGA: test_alu ===
========================================
=== ALU Tests ===
ADD basic: PASS
ADD zero: PASS
ADD carry out: PASS
...
AND clr C/V: PASS
All tests passed!

========================================
=== FPGA: test_addi ===
========================================
...
All tests passed!

...

========================================
FPGA Test Summary: 10 passed, 0 failed
========================================

All 10 test suites pass. All 132 individual tests pass. Zero failures on real hardware.

Test Suite	Tests	FPGA Result
ALU (ADD, SUB, AND, OR, XOR)	20	All PASS
ADDI (immediate arithmetic)	10	All PASS
Shift (SLL, SRL, SRA, ROL, SWAP)	17	All PASS
MulDiv (MUL, DIV, REM variants)	12	All PASS
Load/Store (LW, LB, LBU, SW, SB)	11	All PASS
Branch (all 16 conditions)	24	All PASS
Jump (J, JR, JALR, JX, JALX)	6	All PASS
Stack (PUSH, POP, CMP, TEST, MOV)	12	All PASS
Misc (EXX, GETF, SETF, SCF, CCF, NOP)	9	All PASS
Extended (ADDIX, SUBIX, SLLX, etc.)	11	All PASS
Total	132	All PASS

What This Means

Having all 132 ISA tests pass on hardware is a significant milestone for the project. It means:

The Verilog RTL is correct. Every instruction in the Sampo ISA produces the right result, sets the right flags, and handles edge cases (zero, overflow, carry, sign extension) correctly. Not just in behavioral simulation, but in synthesized logic on a real FPGA running at 12.5 MHz.

The assembler is correct. All 66 instructions encode properly. Branch offsets calculate correctly. Extended instructions (LIX, JALX, OUTX) with their 32-bit encoding work. The sasm Rust assembler and the Verilog decoder agree on every instruction format.

The LLVM backend has a solid foundation. When the Rust compiler generates a ADD or BNE or JALX, the hardware will execute it correctly. The test suite doesn't exercise every possible code generation pattern, but it validates every primitive instruction that the compiler builds upon.

The UART subsystem works end-to-end. Status register polling, TX busy-wait, byte transmission, baud rate generation - all verified on hardware. The MC6850-compatible interface works exactly as specified.

Lessons Learned

Test your assumptions. The testbench had tx_ready = 1. It went unnoticed because simulation "worked." The real hardware exercises code paths that simulation shortcuts. Add realistic peripheral timing to your testbenches from day one.

Binary patching is fragile. Inserting bytes into a binary without updating references is a classic relocation bug - the same class of problem that linkers exist to solve. If your patch changes the size of anything, every address reference past the patch point is wrong. The fix - placing the patch in unused address space and using a same-size replacement instruction - avoids the problem entirely.

Simulation is necessary but not sufficient. The pipeline hazard bug was caught by simulation. The address shift bug was invisible to simulation (both used the same patching script, and the original programs - without patching - worked fine). You need both simulation and hardware testing, exercising different code paths and different failure modes.

Systematic testing finds bugs that demos don't. "Hello, Sampo!" worked on the FPGA from day one. It exercises LIX, LBU, CMP, BEQ, INI, OUTI, ADDI, and J - about 8 instructions. The pipeline hazard only manifested when a store was followed by a load to a different address, a pattern that doesn't occur in a simple print loop. You need tests specifically designed to exercise corner cases.

What's Next

The entire Sampo project - assembler, emulator, Verilog RTL, FPGA build scripts, test suite, and LLVM backend - is open source on GitHub. With hardware verification complete, the next steps might be:

Running Rust-compiled code on the FPGA. The LLVM backend generates assembly, the assembler produces hex files, and we now know the hardware executes them correctly. Closing this loop - cargo build to blinking LEDs - is the obvious next milestone.
Adding more peripherals. The ULX3S has 32MB of SDRAM, an HDMI output, a microSD slot, and an ESP32 co-processor. Each of these opens up interesting possibilities for a working 16-bit computer.
Performance optimization. The CPU currently runs at 12.5 MHz with a multi-cycle FSM (5-8 cycles per instruction). Pipelining could push this significantly higher on the ECP5.

But first: 132 tests, zero failures. The Sampo CPU works.

This is Part 4 of the Sampo series. Part 1 covers architecture design, Part 2 covers FPGA implementation, and Part 3 covers the LLVM backend.

Recommended Resources

OrangeCrab ECP5 FPGA Board - A compact Lattice ECP5 board with DDR3 and USB-C, available on Amazon
ECP5 FPGA Development Boards - Other ECP5 boards available on Amazon
Getting Started with FPGAs by Russell Merrick - Beginner-friendly introduction with Verilog and VHDL examples
FTDI USB Serial Adapters - Useful for UART debugging with FPGAs
USB Logic Analyzers - Essential for debugging digital signals

Source Code

github.com/ajokela/sampo - CPU architecture, assembler, emulator, Verilog RTL, test suite, and FPGA build scripts
github.com/ajokela/llvm-sampo - LLVM backend and Rust target specification

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 — no read-modify-write cycle 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 — 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 — 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

Mutability as a First-Class Concept: The Lattice Phase System

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

Mutability as a First-Class Concept: The Lattice Phase System

Most programming languages treat mutability as a binary annotation. You write const or let, final or var, and the compiler enforces it statically. Rust goes further with its borrow checker, enforcing exclusive mutable access at compile time. JavaScript offers Object.freeze(), a runtime operation that's shallow by default and provides no mechanism for observation or validation. These are all useful tools, but they share a common limitation: mutability is something you declare, not something you work with.

In Lattice, I've been building something different. Mutability — what Lattice calls phase — is a first-class runtime property that can be queried, constrained, validated, coordinated across variables, observed reactively, and even tracked historically. Over the last several releases (v0.2.3 through v0.2.6), this system has grown from simple freeze/thaw semantics into a full lifecycle framework. This post walks through that progression and the design decisions behind it.

The Metaphor: Crystallization

Lattice is built around the metaphor of crystallization. Values begin in a fluid state (mutable) and can be frozen into a crystal state (immutable). The thaw() operation creates a mutable copy of a crystal value, and clone() performs a deep copy regardless of phase. This vocabulary isn't just cosmetic — it shapes how you think about data lifecycle in a Lattice program.

flux temperature = 72.5       // fluid: mutable
temperature = 68.0             // allowed

freeze(temperature)            // now crystal: immutable
// temperature = 70.0          // ERROR: cannot mutate crystal value

flux copy = thaw(temperature)  // new fluid copy
copy = 70.0                    // allowed

The flux keyword declares a fluid (mutable) binding. The fix keyword declares a crystal (immutable) binding. And let infers phase from context — fluid if the value is fluid, crystal if crystal. This alone isn't novel. What makes Lattice's approach interesting is everything that builds on top of it.

Phase Constraints: Mutability in Your Type Signatures

The first major addition (v0.2.3) was phase constraints on function parameters. In most languages, a function that receives data has no way to express whether it expects mutable or immutable input. You might document it, or rely on convention, but the language doesn't help. In Lattice, you can annotate parameters with their expected phase:

fn mutate(data: flux Map) {
    data.set("modified", true)
}

fn inspect(data: fix Map) {
    print(data.get("name"))
}

The runtime checks phase at call time. Pass a crystal value to mutate() and you get an error. Pass a fluid value to inspect() and it works fine — fluid is compatible with fix because it can be read. The constraint is about what the function needs, not what the caller has.

The shorthand syntax uses ~ for flux and * for fix:

fn process(data: ~Map) { ... }  // needs mutable
fn display(data: *Map) { ... }  // needs immutable

Phase-Dependent Dispatch

Phase constraints enable something more powerful: dispatch based on runtime phase. You can define multiple implementations of the same function with different phase signatures, and the runtime selects the best match:

fn serialize(data: ~Map) {
    // mutable path: can add metadata before serializing
    data.set("serialized_at", time_now())
    print(json_stringify(data))
}

fn serialize(data: *Map) {
    // immutable path: serialize directly, no side effects
    print(json_stringify(data))
}

flux config = Map::new()
config["host"] = "localhost"
serialize(config)      // calls flux overload, adds timestamp

freeze(config)
serialize(config)      // calls fix overload, no mutation

The overload resolution uses a scoring system. An exact phase match (fluid argument to flux parameter) scores highest. A compatible match (fluid to unphased) scores lower. An incompatible match (crystal to flux) is rejected entirely. When multiple overloads exist, the best-scoring one wins.

This is genuinely useful in practice. A caching layer might have one implementation that updates a cache (requires mutable data) and another that reads through (works with immutable data). A serialization function might add metadata to mutable structures but serialize immutable ones directly. The caller doesn't need to know — the runtime dispatches based on what the data actually is.

Crystallization Contracts: Validation at the Phase Boundary

The next question was: when data freezes, how do you ensure it's in a valid state? In real systems, immutable data often represents finalized configuration, committed transactions, or published records. You want to validate before that transition happens.

Version 0.2.5 introduced crystallization contracts — validation closures attached to freeze() with the where keyword:

flux config = Map::new()
config["host"] = "localhost"
config["port"] = 8080
config["workers"] = 4

freeze(config) where |v| {
    if !v.has("host") { throw("config missing 'host'") }
    if !v.has("port") { throw("config missing 'port'") }
    if v["workers"] < 1 { throw("need at least 1 worker") }
}

The contract receives a deep clone of the value (so the validation can't accidentally mutate the original), runs the closure, and if the closure throws, the freeze is aborted and the value remains fluid. If validation passes, the value transitions to crystal.

This maps cleanly to real-world patterns. Database ORMs validate before persisting. Configuration systems validate before applying. Form submissions validate before accepting. The difference is that in Lattice, this validation is attached to the phase transition itself, not to a separate method you have to remember to call.

Contracts compose naturally with the rest of the phase system. You can use them with phase bonds (discussed next) or with phase-dependent dispatch. A function that accepts fix Map knows its argument passed whatever contract was attached at freeze time.

Phase Bonds: Coordinated Freezing

Individual freeze/thaw operations work well for isolated values, but real programs have related data that should transition together. A web request's headers, body, and metadata should probably all be immutable before you send it. A transaction's debit and credit entries should freeze atomically.

Phase bonds (also v0.2.5) let you declare these relationships:

flux header = Map::new()
flux body = Map::new()
flux footer = Map::new()

header["content-type"] = "text/html"
body["content"] = "<h1>Hello</h1>"
footer["timestamp"] = time_now()

bond(header, body, footer)

freeze(header)              // cascades to body AND footer
print(phase_of(body))       // "crystal"
print(phase_of(footer))     // "crystal"

The bond(target, ...deps) call links dependencies to a target. When the target freezes, all its dependencies freeze too. Bonds are also transitive — if A is bonded to B and B is bonded to C, freezing A cascades through B to C.

flux a = 1
flux b = 2
flux c = 3

bond(a, b)    // b depends on a
bond(b, c)    // c depends on b

freeze(a)     // freezes a → b → c
print(phase_of(c))  // "crystal"

You can remove bonds with unbond() before the freeze happens:

bond(header, body, footer)
unbond(header, footer)    // footer no longer cascades

freeze(header)            // freezes header and body, NOT footer
print(phase_of(footer))   // "fluid"

Bonds solve a coordination problem that most languages leave to discipline. In a typical codebase, you'd need to remember to freeze all related values, or wrap them in a container and freeze that. Bonds make the relationship explicit and enforced.

Phase Reactions: Observing State Transitions

With constraints, contracts, and bonds, you can control how and when phase transitions happen. But sometimes you also need to know that they happened. Logging, cache invalidation, UI updates, audit trails — these are all responses to state changes.

Version 0.2.6 adds phase reactions: callbacks that fire automatically when a variable's phase changes.

flux data = [1, 2, 3]

react(data, |phase, val| {
    print("data is now " + phase + ": " + to_string(val))
})

freeze(data)   // prints: "data is now crystal: [1, 2, 3]"
thaw(data)     // prints: "data is now fluid: [1, 2, 3]"

The callback receives two arguments: the new phase name (as a string — "crystal", "fluid") and a deep clone of the current value. Multiple callbacks can be registered on the same variable, and they fire in registration order:

flux counter = 0

react(counter, |phase, val| {
    print("logger: counter is now " + phase)
})

react(counter, |phase, val| {
    if phase == "crystal" {
        print("audit: counter finalized at " + to_string(val))
    }
})

counter = 42
freeze(counter)
// prints:
//   logger: counter is now crystal
//   audit: counter finalized at 42

Reactions also fire during bond cascades. If variable B is bonded to A and has a reaction registered, freezing A will cascade to B and trigger B's reaction:

flux primary = Map::new()
flux replica = Map::new()

bond(primary, replica)

react(replica, |phase, val| {
    print("replica transitioned to " + phase)
})

freeze(primary)
// prints: "replica transitioned to crystal"

This is a powerful combination. Bonds handle the coordination of transitions, and reactions handle the observation. Together they let you build systems where phase changes propagate and trigger side effects in a predictable, declarative way.

Use unreact() to remove all reactions from a variable:

react(data, |phase, val| { print("fired") })
unreact(data)
freeze(data)  // no output — reaction was removed

If a reaction callback throws an error, it propagates as a reaction error, giving you a clean way to handle failures in the observation chain.

Temporal Values: Phase History and Time Travel

The last piece of the phase system (also v0.2.5) is temporal values — the ability to track a variable's phase transitions and value changes over time.

flux counter = 0
track("counter")

counter = 10
counter = 20
freeze(counter)

let history = phases("counter")
// [{phase: "fluid", value: 0},
//  {phase: "fluid", value: 10},
//  {phase: "fluid", value: 20},
//  {phase: "crystal", value: 20}]

The track() function enables recording for a named variable. Every assignment and phase transition creates a snapshot. The phases() function returns the full history as an array of maps, and rewind() lets you retrieve past values by offset:

flux x = 100
track("x")
x = 200
x = 300

print(rewind("x", 0))  // 300 (current)
print(rewind("x", 1))  // 200 (one step back)
print(rewind("x", 2))  // 100 (two steps back)

Temporal values serve primarily as a debugging and auditing tool. When something goes wrong with a frozen value, you can inspect its history to see what mutations happened before the freeze. When testing phase-dependent dispatch, you can verify that the right transitions occurred. In production systems, you can use temporal tracking for audit logs or undo functionality.

The Bigger Picture: Why This Matters

Most programming languages treat mutability as a compiler concern — something to check at build time and forget about. Lattice treats it as a runtime property with the same richness as types or values. This opens up patterns that are difficult or impossible in other languages:

Gradual freezing. Data starts fluid, accumulates state through a pipeline, and freezes when it's complete. Contracts validate at the boundary. Bonds ensure related data transitions together. This maps naturally to request processing, form building, transaction assembly, and configuration loading.

Observable state transitions. Reactions let you attach behavior to phase changes without coupling the code that freezes with the code that responds. A module can register a reaction on shared data without knowing who or when the freeze will happen.

Phase-aware APIs. Functions can express their mutability requirements in their signatures and dispatch based on the caller's data. Libraries can offer mutable and immutable code paths transparently.

Auditability. Temporal tracking provides a built-in mechanism for understanding how data evolved, without external logging infrastructure.

None of these features require abandoning the simple mental model. At its core, Lattice still has fluid and crystal — mutable and immutable. Everything else is opt-in machinery for programs that need more control.

Comparison with Other Approaches

It's worth comparing this to how other languages handle mutability:

Feature	Rust	JavaScript	Lattice
Mutability declaration	`let` / `let mut`	`const` / `let`	`fix` / `flux` / `let`
Enforcement	Compile-time	Runtime (shallow)	Runtime (deep)
Phase transitions	N/A	`Object.freeze()`	`freeze()` / `thaw()` / `clone()`
Validation on freeze	N/A	N/A	Crystallization contracts
Coordinated freezing	N/A	N/A	Phase bonds
Transition observation	N/A	N/A	Phase reactions
Phase-dependent dispatch	N/A	N/A	Overload resolution by phase
History tracking	N/A	N/A	Temporal values

Rust's borrow checker is more powerful for preventing data races at compile time — Lattice doesn't attempt that. JavaScript's Object.freeze() is more pragmatic but also more limited — it's shallow, provides no observation, and offers no coordination. Lattice occupies a different point in the design space: mutability as a domain concept rather than a compiler constraint.

Implementation Notes

The phase system is implemented in C as part of Lattice's tree-walking interpreter. Phase tags are stored directly on values (VTAG_FLUID, VTAG_CRYSTAL, VTAG_UNPHASED), so phase checks are single comparisons. Bonds are stored as a dynamic array of BondEntry structs on the evaluator, each mapping a target variable name to its dependencies. Reactions use a similar structure — ReactionEntry maps a variable name to an array of callback closures. Temporal tracking stores HistorySnapshot arrays containing phase names and deep-cloned values.

The deep cloning is important throughout. Contract validation receives a clone so it can't mutate the original. Reaction callbacks receive clones so observers can't interfere with each other. Temporal snapshots are clones so history is independent of current state. This means the phase system has allocation costs proportional to value size, but it also means the invariants are strong — no spooky action at a distance.

Freeze cascading through bonds is recursive, and reactions fire during cascading, so a single freeze() call can trigger an arbitrary chain of transitions and callbacks. Error propagation is straightforward: if any reaction throws, the error surfaces immediately with context about which reaction failed.

What's Next

The phase system is reaching a natural plateau in terms of core features. There are a few directions I'm considering:

Partial freezing already exists in a basic form — you can freeze individual struct fields or map keys while leaving the container mutable. Expanding this to support more granular control (freeze all fields matching a pattern, freeze a subtree) could be useful for large data structures.

Phase-aware pattern matching lets you match on phase in match expressions using ~ and * qualifiers. This is already implemented but could be extended with more complex phase patterns.

Compile-time phase inference is a longer-term goal. If the interpreter can prove that a value is always crystal by a certain point, it could skip runtime checks. This would bring some of Rust's static guarantees to Lattice without requiring explicit lifetime annotations.

For now, the phase system provides a cohesive set of tools for working with mutability as a first-class concept. Whether you're building a configuration loader that validates before committing, a pipeline that coordinates related state transitions, or a reactive system that responds to phase changes, Lattice gives you the vocabulary and the enforcement to do it declaratively.

Lattice is open source and available at lattice-lang.org. The language compiles and runs on macOS and Linux with no dependencies beyond a C11 compiler. You can try it in your browser via the playground, or clone the repo and run make && ./clat to start the REPL.

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 — 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 — 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 — 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 — no network latency, 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.

Milk-V Mars Review: SiFive's RISC-V Enters the SBC Arena

A.C. Jokela — Fri, 13 Feb 2026 21:30:00 GMT

Introduction

The Milk-V Mars is a compact RISC-V single board computer built around StarFive's JH7110 system-on-chip, featuring four SiFive U74-MC application cores and 8GB of LPDDR4 RAM. Priced affordably and shipping in a Raspberry Pi-like form factor, the Mars targets developers and enthusiasts who want to explore the RISC-V ecosystem on real hardware without investing in high-end development boards.

This review arrives at an interesting moment for RISC-V single board computers. We've already benchmarked the Orange Pi RV2 with its 8-core Ky(R) X1 processor, and the Milk-V Mars gives us a second data point in the RISC-V SBC landscape - this time with SiFive's cores, the company widely regarded as the pioneer of commercial RISC-V silicon. How does a board built on SiFive's mature U74 core design compare to the newer Ky X1, and where does it land against the ARM and x86 competition? The answers are illuminating, if not entirely encouraging.

Hardware Architecture: SiFive U74-MC on StarFive JH7110

At the heart of the Milk-V Mars sits the StarFive JH7110, a 28nm SoC that pairs four SiFive U74-MC application cores with a single SiFive S7 monitor core. The U74 is SiFive's 64-bit application processor core implementing the RV64GC instruction set (rv64imafdc) - the standard RISC-V profile with integer multiplication, atomic operations, single and double-precision floating point, and compressed instructions. The cores feature an in-order, dual-issue, 8-stage pipeline with separate L1 instruction and data caches, backed by a shared 2MB L2 cache. For readers wanting to understand the ISA itself, The RISC-V Reader is an excellent and concise introduction to the architecture and its design rationale.

The SiFive U74 has an important place in RISC-V history. As one of the first commercially available application-class RISC-V cores, it powered the HiFive Unmatched development board that many early RISC-V adopters used to explore the architecture. The U74-MC variant in the JH7110 is a cost-optimized version without the memory management features of the full U74, targeting embedded and SBC applications rather than server or workstation use.

However, the U74's in-order pipeline design places it at a fundamental architectural disadvantage compared to modern out-of-order ARM cores. While the Cortex-A76 in a Raspberry Pi 5 can speculatively execute instructions, reorder them for optimal throughput, and predict branches with sophisticated algorithms refined over years of iteration, the U74 executes instructions strictly in program order. This simplicity reduces silicon area and power consumption but significantly limits single-threaded performance - the metric that matters most for many real-world workloads.

The JH7110 is fabricated on TSMC's 28nm process, which is two to three generations behind the 8nm and 6nm processes used in contemporary ARM SoCs like the Rockchip RK3588. This older process node limits clock speeds, increases power consumption per transistor, and constrains the amount of logic that can be economically integrated into the die.

Board Specifications

Our test unit came configured with:

SoC: StarFive JH7110 (28nm process)
CPU: 4x SiFive U74-MC @ 1.5 GHz (RV64GC)
Monitor Core: 1x SiFive S7
RAM: 8GB LPDDR4
Storage: microSD card (29GB card installed, expandable)
Networking: Gigabit Ethernet
OS: Debian GNU/Linux Bookworm (kernel 5.15.0)
USB: USB 3.0 and USB 2.0 ports
Video: HDMI output
GPIO: 40-pin header (Raspberry Pi compatible layout)

The 8GB of RAM is generous for a board in this class - more than many ARM SBCs ship with by default - and proved more than adequate for our Rust compilation benchmarks. The microSD card storage is adequate but not exceptional; the board does support eMMC modules for better storage performance, though our test unit used a standard SD card.

One notable issue we encountered during setup: the factory image shipped with a root partition of only 3.8GB on a 29GB SD card. This is common with SBC images but particularly problematic here because installing the Rust toolchain and build dependencies requires significant disk space. We expanded the partition using parted and resize2fs before proceeding - a standard operation, but one that new users might find daunting.

Software Environment

The Milk-V Mars runs Debian Bookworm with a Linux 5.15.0 kernel, a relatively old kernel version compared to the 6.x kernels shipping on more recent ARM and RISC-V boards. The kernel includes StarFive-specific patches for JH7110 hardware support, but the older base means newer kernel features and optimizations aren't available.

The software experience is functional but bare. The system ships as a minimal Debian installation - no build tools, no git, no development packages preinstalled. Setting up the board for development required installing build-essential, git, curl, and bc via apt before we could proceed with Rust installation. The Debian repositories worked without issues, and rustup installed cleanly for the riscv64gc-unknown-linux-gnu target, delivering Rust 1.93.1 - the latest stable release at the time of testing.

This is actually a positive sign for the RISC-V ecosystem. Rust's official support for RISC-V has matured to the point where rustup "just works" on riscv64gc targets. Compare this to just a few years ago when RISC-V Rust development required building the compiler from source. The toolchain infrastructure has come a long way, even if the hardware performance hasn't yet caught up to ARM. If you're new to Rust and want to understand the language driving these benchmarks, The Rust Programming Language by Klabnik and Nichols is the definitive starting point.

Performance Testing: Rust Compilation Benchmarks

To assess the Milk-V Mars's CPU performance, we ran our standard benchmark: compiling the ballistics-engine Rust project in release mode, three times from a clean build state. This workload exercises all CPU cores through parallel compilation units, stresses the memory subsystem with large intermediate data structures, and measures real-world compiler and linker performance - the kind of task a developer would encounter daily.

Milk-V Mars Compilation Times

Run 1: 939.13 seconds (15 minutes 38 seconds)
Run 2: 933.45 seconds (15 minutes 33 seconds)
Run 3: 935.96 seconds (15 minutes 35 seconds)
Average: 936.18 seconds (15 minutes 36 seconds)
Standard Deviation: 2.85 seconds (0.30%)

The first thing that stands out is the remarkable consistency. A standard deviation of just 2.85 seconds across three 15-minute runs indicates stable thermal behavior and no throttling - the board maintained consistent performance throughout the entire test sequence. This suggests good power delivery and adequate thermal management, even without active cooling.

The second thing that stands out is the absolute time: over 15 minutes per compilation. This is the slowest result in our entire benchmark fleet.

Comparative Analysis

Here's how the Milk-V Mars stacks up against every board we've benchmarked:

Rank	System	Architecture	CPU	Cores	Average Time	vs. Mars
1	Orange Pi 5 Max	ARM64	Cortex-A55/A76	8 (4+4)	62.31s	15.0x faster
2	Raspberry Pi CM5	ARM64	Cortex-A76	4	71.04s	13.2x faster
3	LattePanda IOTA	x86_64	Intel N150	4	72.21s	13.0x faster
4	Raspberry Pi 5	ARM64	Cortex-A76	4	76.65s	12.2x faster
5	Banana Pi CM5-Pro	ARM64	Cortex-A53/A72	8 (4+4)	167.15s	5.6x faster
6	Horizon X3 CM	ARM64	Cortex-A53	4	378.81s	2.5x faster
7	Orange Pi RV2	RISC-V	Ky(R) X1	8	650.60s	1.4x faster
8	Milk-V Mars	RISC-V	SiFive U74-MC	4	936.18s	baseline

The Milk-V Mars is 15x slower than the fastest board in our fleet (Orange Pi 5 Max) and 12.2x slower than the ubiquitous Raspberry Pi 5. Even the much-maligned Horizon X3 CM with its ancient Cortex-A53 cores is 2.5x faster.

Understanding the Performance Gap

The 15x gap between the Milk-V Mars and the Orange Pi 5 Max isn't surprising when you understand the architectural differences at play:

In-order vs. out-of-order execution. The U74's in-order pipeline means the CPU stalls whenever it encounters a cache miss, branch misprediction, or data dependency. Modern out-of-order cores like the Cortex-A76 can continue executing independent instructions while waiting for stalled operations to complete. For a workload like Rust compilation, which involves complex data structures, frequent branching, and irregular memory access patterns, out-of-order execution provides enormous benefits. Hennessy and Patterson's Computer Architecture: A Quantitative Approach covers the engineering trade-offs between in-order and out-of-order pipelines in detail.

Clock speed. The U74 runs at 1.5 GHz compared to 2.4 GHz for the Cortex-A76 cores in the Pi 5 and Orange Pi 5 Max. This 1.6x frequency disadvantage compounds with the architectural differences to create a much larger effective performance gap.

Process technology. The JH7110's 28nm fabrication limits the transistor budget available for performance-enhancing features like larger caches, more complex branch predictors, and wider execution units. Modern ARM SoCs on 8nm or smaller processes can pack significantly more logic into the same power envelope.

Compiler maturity. While LLVM's RISC-V backend has improved substantially, it still lacks many of the target-specific optimizations that the ARM backend has accumulated over years of development. Code generation for RISC-V may not always exploit the microarchitecture as effectively as ARM code generation exploits Cortex-A76 features.

Core count. The Mars has four cores versus eight on the Orange Pi 5 Max. For parallel compilation workloads, more cores translate directly to faster builds, all else being equal.

RISC-V vs. RISC-V: Mars vs. Orange Pi RV2

Perhaps the most interesting comparison is between the two RISC-V boards in our fleet. The Orange Pi RV2 with its 8-core Ky(R) X1 processor compiled our benchmark in 650.60 seconds - 1.44x faster than the Milk-V Mars's 936.18 seconds.

This 44% performance advantage for the Orange Pi RV2 can be attributed to two factors:

Double the cores. The Ky X1 has eight cores versus the U74's four. For parallel compilation, this provides a near-linear speedup for the parallel portions of the build, though Amdahl's Law limits the overall benefit due to serial bottlenecks in linking and code generation.

Newer core design. The Ky X1 represents a more recent RISC-V core design than the U74, likely incorporating microarchitectural improvements that boost instructions-per-clock (IPC). While details about the Ky X1's pipeline are scarce, its performance-per-core appears to be modestly better than the U74's.

However, both RISC-V boards exist in the same performance tier - dramatically slower than ARM and x86 alternatives. The 286-second gap between the Mars and the RV2 is notable but pales in comparison to the 874-second gap between the Mars and the Orange Pi 5 Max. Both RISC-V platforms are firmly in "pioneer hardware" territory, demonstrating architectural viability rather than competitive performance.

The SiFive Legacy: Historical Context

It's worth acknowledging what the SiFive U74 represents historically. SiFive, founded in 2015 by the creators of the RISC-V instruction set at UC Berkeley, was the first company to offer commercial RISC-V cores. The U74 was their first serious application-class core, designed at a time when RISC-V was still primarily an academic project.

The HiFive Unmatched, which used the same JH7110-predecessor (the FU740), was one of the first RISC-V boards capable of running a full Linux desktop. It proved that RISC-V could work for general-purpose computing. The Milk-V Mars, using the JH7110 with U74-MC cores, is essentially a cost-reduced descendant of that pioneering effort.

In this light, the U74's performance is less a failure and more a measure of how far the RISC-V ecosystem has come - and how far it still needs to go. The U74 was designed for correctness and compatibility, not performance leadership. Newer SiFive cores like the P670 and P870 incorporate out-of-order execution, branch prediction, and other modern features that should dramatically close the gap with ARM. We haven't yet seen these cores in affordable SBC form factors, but when they arrive, the comparison should be far more competitive.

Practical Considerations

Who Should Buy the Milk-V Mars?

RISC-V learners and enthusiasts. If you want to understand RISC-V at a hardware level - boot Linux, explore the ISA, compile software, and experiment with the architecture - the Mars is a low-cost entry point. The 8GB of RAM is generous, and the Debian software environment is functional enough for exploration.

Embedded RISC-V developers. If you're developing software that will eventually run on RISC-V embedded systems, the Mars provides a Linux-capable development and testing platform. Cross-compilation workflows (develop on x86, test on RISC-V) are viable, and native compilation works - it just takes patience.

SBC collectors and architecture enthusiasts. The Mars represents an important moment in RISC-V history. As SiFive's application-class cores in an affordable SBC, it has both practical and historical value for anyone tracking the evolution of processor architectures.

Who Should Look Elsewhere?

Anyone needing competitive performance. If compilation speed, application responsiveness, or computational throughput matter for your use case, the Raspberry Pi 5 delivers 12x better performance at a similar price point. There is no workload where the Mars outperforms modern ARM alternatives.

Production deployments. The combination of slow CPU performance, older kernel, and limited software ecosystem makes the Mars unsuitable for production use cases. Even RISC-V-specific production deployments would benefit from waiting for next-generation hardware.

AI and machine learning. The Mars lacks any AI acceleration hardware, and its CPU performance makes even lightweight inference workloads impractical. Our experience running TinyLlama on the Orange Pi RV2 at 0.44 tokens per second suggests the Mars would be even slower given its lower core count and comparable per-core performance.

The Bigger Picture: RISC-V's Two-Board Story

Having now benchmarked two RISC-V single board computers, a pattern emerges. Both the Milk-V Mars (SiFive U74, 4 cores, 936s) and the Orange Pi RV2 (Ky X1, 8 cores, 651s) occupy a performance tier roughly 10-15x slower than mainstream ARM platforms. This isn't a coincidence - it reflects the current state of RISC-V application processor development.

The good news is that this gap isn't architectural. Nothing about the RISC-V instruction set prevents high-performance implementations. SiFive's P-series cores, Ventana's Veyron, and Alibaba's Xuantie C920 all promise ARM-competitive performance. The gap exists because the affordable SBC market is currently served by first-generation cores on older process nodes with immature compiler support.

The bad news is that closing this gap requires simultaneous progress on multiple fronts: newer core designs with out-of-order execution, migration to modern process nodes (7nm and below), compiler optimizations specific to new microarchitectures, and operating system tuning for RISC-V hardware features. This is years of work, and it's unclear whether the SBC market generates enough volume to justify the investment.

For now, RISC-V single board computers remain in the "interesting to explore, impractical to deploy" category. The Milk-V Mars embodies this perfectly: a board that works, runs real software, and delivers real results - just not quickly enough to compete with the ARM and x86 boards sitting next to it on the shelf.

Conclusion

The Milk-V Mars is a functional, stable, and affordable RISC-V single board computer that delivers on its basic promise: a Linux-capable platform built on SiFive's pioneering U74 cores. Its 8GB of RAM, Gigabit Ethernet, and standard Debian environment make it a reasonable development platform for RISC-V exploration.

Its performance, however, tells the honest story of where RISC-V stands in early 2026. At 936 seconds average for our Rust compilation benchmark, the Mars is the slowest board we've tested - 15x slower than the Orange Pi 5 Max, 12.2x slower than the Raspberry Pi 5, and 1.4x slower than the Orange Pi RV2. These numbers reflect the U74's in-order pipeline, 1.5 GHz clock speed, and 28nm process node, compounded by RISC-V's still-maturing compiler toolchain.

The remarkable consistency across benchmark runs (0.3% standard deviation) shows that the hardware is well-behaved and thermally stable - it's simply not fast. The board does exactly what it's supposed to do; it just does it slowly by modern standards.

For RISC-V enthusiasts, the Milk-V Mars offers an affordable window into the architecture that may eventually reshape computing. For everyone else, the Raspberry Pi 5 remains the obvious choice for general-purpose single board computing. The Mars is a board for the curious and the patient - those willing to trade performance today for a front-row seat to an architectural revolution that's still finding its footing.

The question isn't whether RISC-V will eventually match ARM and x86 performance in affordable SBCs. It will. The question is when, and whether boards like the Milk-V Mars will be remembered as charming relics of the early days or as stepping stones that helped build the ecosystem that made RISC-V competitive. Either way, they deserve a place in the story.

Specifications Summary

Processor:

StarFive JH7110 (28nm process)
4x SiFive U74-MC @ 1.5 GHz (RV64GC: rv64imafdc)
1x SiFive S7 monitor core
MMU: Sv39

Memory & Storage:

8GB LPDDR4 RAM (2GB and 4GB options also available)
microSD card slot
eMMC module support

Video:

HDMI output
Hardware video decoding support

Connectivity:

Gigabit Ethernet
USB 3.0 and USB 2.0 ports
40-pin GPIO header (Raspberry Pi compatible)
I2C, SPI, UART

Physical:

Compact SBC form factor
Passive cooling adequate for sustained workloads

Benchmark Performance:

Rust compilation: 936.18 seconds average
15.0x slower than Orange Pi 5 Max (ARM64, RK3588)
12.2x slower than Raspberry Pi 5 (ARM64, BCM2712)
5.6x slower than Banana Pi CM5-Pro (ARM64, RK3576)
2.5x slower than Horizon X3 CM (ARM64, Sunrise X3)
1.4x slower than Orange Pi RV2 (RISC-V, Ky X1)
Standard deviation: 2.85 seconds (0.30% - excellent consistency)

Software:

Debian GNU/Linux Bookworm
Linux kernel 5.15.0 (StarFive patches)
Rust 1.93.1 (official rustup support for riscv64gc)

Recommendation: Suitable for RISC-V exploration and development; not competitive with ARM or x86 alternatives for performance-sensitive workloads.

Introducing Lattice: A Crystallization-Based Programming Language

A.C. Jokela — Tue, 10 Feb 2026 18:00:00 GMT

Most programming languages treat mutability as a binary property. A variable is either mutable or it's not. You declare it one way, and that's the end of the story. Rust adds nuance with its ownership and borrowing model, and functional languages sidestep the question by making everything immutable by default, but the fundamental framing remains the same: mutability is a static attribute decided at declaration time.

Lattice takes a different approach. In Lattice, mutability is a phase — a state that a value passes through over its lifetime, like matter transitioning between liquid and solid. A value starts as mutable flux, and when you're done shaping it, you freeze it into immutable fix. Need to modify it again? Thaw it back to flux. Want to build something complex and immutable in one shot? Use a forge block — a controlled mutation zone whose output automatically crystallizes.

This isn't just a metaphor. The phase system is woven through Lattice's entire runtime, from its type representation to its memory management architecture. This post is a deep dive into what that means, how it works at the implementation level, and why it represents a genuinely different way of thinking about the relationship between mutability and memory.

The Problem Lattice Solves

Every language designer eventually confronts the same tension: programmers need mutability to build things, but mutability is the source of most bugs. Shared mutable state causes race conditions. Unexpected mutation causes aliasing bugs. Mutable references that outlive their owners cause use-after-free errors.

Different languages resolve this tension in different ways, and each approach carries trade-offs.

Garbage-collected languages (Java, Python, Go, JavaScript) let you mutate freely and use a garbage collector to clean up. This is convenient but pushes the cost to runtime — GC pauses, unpredictable memory usage, and no compile-time guarantees about who can modify what. You gain ease of use but lose control.

Rust's ownership model provides compile-time guarantees through a sophisticated borrow checker. You can have either one mutable reference or many immutable references, but not both. This eliminates data races at compile time, but the cost is complexity — the borrow checker is notoriously difficult for newcomers, lifetime annotations add syntactic weight, and certain patterns (like self-referential structs or graph structures) require unsafe escape hatches.

Functional languages (Haskell, Erlang, Clojure) default to immutability and model mutation through controlled mechanisms like monads, processes, or atoms. This produces correct programs but can feel unnatural for inherently stateful problems, and persistent data structures carry performance overhead.

C and C++ give you full manual control and zero overhead, at the cost of memory safety. const in C is advisory at best — you can cast it away, and the compiler won't stop you from freeing memory that someone else is still using.

Lattice's phase system is an attempt to find a different point in this design space. The core insight is that in most programs, values have a natural lifecycle: they're constructed (requiring mutation), then used (requiring stability), and occasionally reconstructed (requiring mutation again). The phase system makes this lifecycle explicit and enforceable.

The Phase Model

Lattice has three binding keywords that correspond to mutability phases:

flux declares a mutable binding. A flux variable can be reassigned, and its contents can be modified in place. This is where you do your work — building arrays, populating maps, incrementing counters.

flux counter = 0
counter += 1
counter += 1

fix declares an immutable binding. A fix variable cannot be reassigned, and its contents cannot be modified. Attempting to mutate a fix binding is an error.

fix pi = freeze(3.14159)
// pi = 2.0  -- error: cannot assign to crystal binding

let is the inferred form (available in casual mode). It doesn't enforce a phase — the value keeps whatever phase tag it already has.

The transitions between phases are explicit function calls:

freeze(value) transitions a value from fluid to crystal. In strict mode, this is a consuming operation — the original binding is removed from the environment. You can't accidentally keep a mutable reference to something you've declared immutable.
thaw(value) creates a mutable deep clone of a crystal value. The original remains frozen; you get a completely independent mutable copy.
clone(value) creates a deep copy without changing phase.

And then there's the forge block, which is perhaps the most interesting construct:

fix config = forge {
    flux temp = Map::new()
    temp.set("host", "localhost")
    temp.set("port", "8080")
    temp.set("debug", "true")
    freeze(temp)
}

A forge block is a scoped computation whose result is automatically frozen. Inside the forge, you can use flux variables and mutate freely. But whatever value the block produces comes out crystallized. The temporary mutable state is gone — only the finished, immutable result survives.

This addresses a real pain point. In functional languages, building a complex immutable data structure often requires awkward chains of constructor calls or builder patterns. In Lattice, you just... build it, mutably, in a forge block, and it comes out frozen. The forge acknowledges that construction is inherently a mutable process, while insisting that the result of construction should be stable.

Under the Hood: How the Phase System Maps to Memory

Lattice is implemented as a tree-walking interpreter in C — roughly 6,000 lines across the lexer, parser, phase checker, and evaluator. The implementation reveals some interesting design decisions about how phase semantics interact with memory management.

Value Representation

Every runtime value in Lattice is a LatValue struct — a tagged union carrying a type tag, a phase tag, and the value payload:

struct LatValue {
    ValueType type;   // VAL_INT, VAL_STR, VAL_ARRAY, VAL_MAP, ...
    PhaseTag  phase;  // VTAG_FLUID, VTAG_CRYSTAL, VTAG_UNPHASED
    union { ... } as;
};

Primitive values (integers, floats, booleans) live inline in the union — no heap allocation. Compound values (strings, arrays, structs, maps, closures) own heap-allocated payloads. A string holds a heap-allocated character buffer. An array holds a malloc'd element buffer. A map holds a pointer to an open-addressing hash table.

Deep-Clone-on-Read: Value Semantics Without a Compiler

The most consequential design decision in Lattice's runtime is that every variable read produces a deep clone. When you access a variable, the environment doesn't hand you a reference to the stored value — it hands you a complete, independent copy.

bool env_get(const Env *env, const char *name, LatValue *out) {
    for (size_t i = env->count; i > 0; i--) {
        LatValue *v = lat_map_get(&env->scopes[i-1], name);
        if (v) {
            *out = value_deep_clone(v);  // always a fresh copy
            return true;
        }
    }
    return false;
}

This is expensive. Every array access clones the entire array. Every map read clones every key-value pair. But it eliminates an entire class of bugs. There is no aliasing in Lattice. Two variables never point to the same underlying memory. When you pass a map to a function, the function gets its own copy — mutations inside the function don't leak back to the caller. When you assign an array to a new variable, you get two independent arrays.

This is the implementation strategy that makes Lattice's maps value types. In most languages, objects and collections are reference types — assigning them to a new variable creates a new reference to the same data. In Lattice, assignment means duplication. This is closer to how values work in mathematics than how they work in most programming languages.

For in-place mutation within a scope (like array.push() or map.set()), Lattice uses a separate resolve_lvalue() mechanism that obtains a direct mutable pointer into the environment's storage, bypassing the deep clone. This means local mutations are efficient — it's only cross-scope communication that pays the cloning cost.

The Dual Heap Architecture

Lattice's memory subsystem uses what the implementation calls a DualHeap — two separate allocation regions with different management strategies:

The FluidHeap manages mutable data using a mark-and-sweep garbage collector. It maintains a linked list of all heap allocations, with a mark bit on each. When memory pressure crosses a threshold (1 MB by default), the GC walks all reachable values from the environment and a shadow root stack, marks what's alive, and sweeps everything else.

The RegionManager manages immutable data using arena-based regions. Each freeze creates a new region backed by a page-based arena — a linked list of 4 KB pages with bump allocation. When a value is frozen, it is deep-cloned entirely into the region's arena, giving crystal data cache locality and enabling O(1) bulk deallocation when the region becomes unreachable. Regions are collected during GC cycles based on reachability analysis.

The key insight here is that immutable and mutable data have different lifecycle characteristics and benefit from different management strategies. Mutable data changes frequently and has unpredictable lifetimes — mark-and-sweep handles this well. Immutable data, once created, never changes and tends to be long-lived — arena-based region allocation is more efficient for this pattern, as it enables bulk deallocation and better cache locality.

This is conceptually similar to generational garbage collection (where young objects are collected differently from old objects), but the split is based on mutability rather than age. Lattice's phase tags provide the runtime with information that generational GCs have to infer statistically.

The following chart shows how this plays out in practice across several benchmark programs. Fluid peak memory represents the high-water mark of the GC-managed heap, while crystal arena data shows how much data has been frozen into arena-backed regions:

Freeze and Thaw at the Memory Level

When you call freeze() on a value, the runtime creates a new crystal region with a fresh arena, deep-clones the entire value tree into it, sets the phase field to VTAG_CRYSTAL on every node, and frees the original fluid heap pointers. The data physically migrates from the fluid heap into arena pages — freeze is a move operation, not just a metadata flip. This gives frozen data cache locality within contiguous arena pages and completely separates it from the garbage-collected fluid heap.

But in strict mode, freeze() is also a consuming operation. It removes the original binding from the environment and returns the frozen value. This is effectively a move — after freeze(x), there is no x anymore. You can bind the result to a new name (fix y = freeze(x)), but the mutable original is gone. This prevents a common bug pattern where you freeze a value but accidentally keep mutating the original through a still-live reference.

thaw() is more expensive: it performs a complete deep clone of the crystal value and then recursively sets all phase tags to VTAG_FLUID. The original crystal value is untouched — you get a completely independent mutable copy. This is consistent with the principle that crystal values are permanent. Thawing doesn't melt the original; it creates a new fluid copy.

In practice, both operations are fast. Across the benchmark suite, freeze and thaw costs stay well under a millisecond even for complex data structures:

The number and type of phase transitions varies by workload. Some benchmarks are freeze-heavy (building immutable snapshots), others are thaw-heavy (repeatedly modifying frozen state), and some use deep clones for full value duplication:

How This Compares to Existing Systems

vs. Rust's Ownership and Borrowing

Rust solves the mutability problem at compile time through static analysis. The borrow checker ensures that mutable references are unique and that immutable references don't coexist with mutable ones. This gives Rust zero-runtime-cost safety guarantees that Lattice can't match.

But Rust's approach operates at the reference level — it tracks who has access to data, not the data's intrinsic state. You can have an &mut to data that is conceptually "done being built," or an & to data that you wish you could modify. The permission model and the data lifecycle are orthogonal.

Lattice's phase system operates on the data itself. A frozen value is immutable — not because the type system prevents you from obtaining a mutable reference, but because the value has transitioned to a state where mutation doesn't apply. This is a simpler mental model at the cost of runtime enforcement rather than compile-time proof.

The consuming freeze() in strict mode is reminiscent of Rust's move semantics, where using a value after moving it is a compile error. Lattice achieves a similar effect at runtime — freeze consumes the binding, preventing further mutable access. It's not as strong a guarantee (runtime vs. compile time), but it's the same intuition: once you've declared something immutable, the mutable version shouldn't exist anymore.

vs. Garbage Collection

Traditional garbage collectors (Java, Go, Python) are phase-agnostic. They track reachability, not mutability. A final field in Java prevents reassignment but doesn't inform the GC. An immutable object in Python is collected the same way as a mutable one.

Lattice's dual-heap architecture uses phase information to make better allocation decisions. Crystal values go into arena-managed memory with reachability-based collection. Fluid values go into a mark-and-sweep heap. The GC can reason about immutable data more efficiently because it knows the data won't change — it doesn't need to re-scan crystal regions for updated references.

This is a form of phase-informed memory management that, to my knowledge, doesn't have a direct precedent in mainstream languages. The closest analogy might be Clojure's persistent data structures, which are structurally shared and immutable, but Clojure doesn't use this information to drive its garbage collection strategy differently.

vs. Functional Immutability

Haskell and other pure functional languages are immutable by default, with mutation confined to monads (IORef, STRef) or similar controlled mechanisms. This is elegant but can be awkward for imperative algorithms where you need to build something up step by step.

Lattice's forge blocks address this directly. Instead of threading a builder through a chain of pure function calls, you write imperative mutation inside a forge and get an immutable result. This acknowledges that construction and consumption are different activities that benefit from different mutability guarantees.

The philosophical difference is that functional languages treat immutability as the default and mutation as the exception. Lattice treats mutability as a phase that values pass through — both flux and fix are natural, expected states, and the language provides explicit tools for transitioning between them.

vs. C/C++ Manual Memory Management

C gives you malloc and free and wishes you the best. C++ adds RAII, smart pointers, and const correctness, but const in both languages is fundamentally a compiler hint — it can be cast away, and the runtime has no awareness of it. A const pointer in C doesn't prevent someone else from modifying the data through a non-const pointer to the same memory. The const is a property of the reference, not the data.

Lattice's phase tags live on the data itself. When a value is crystal, it's crystal regardless of how you access it. There's no way to "cast away" a freeze — the only path back to mutability is thaw(), which creates a new independent copy. This is a stronger guarantee than const provides, because it operates on values rather than references.

C++ move semantics share DNA with Lattice's consuming freeze() in strict mode. A std::move in C++ transfers ownership of resources, leaving the source in a valid-but-unspecified state. Lattice's strict freeze does something similar — it removes the binding entirely, ensuring the mutable version ceases to exist. But where C++ moves are primarily about avoiding copies for performance, Lattice's consuming freeze is about semantic correctness — ensuring that the transition from mutable to immutable is clean and total. Scott Meyers' Effective Modern C++ remains the best guide to understanding these move semantics and other modern C++ patterns that Lattice's design draws from.

The Static Phase Checker

It's worth noting that Lattice doesn't rely solely on runtime enforcement. Before any code executes, a static phase checker walks the AST and catches phase violations at analysis time. This checker maintains its own scope stack mapping variable names to their declared phases and rejects programs that attempt to reassign crystal bindings, freeze already-frozen values, thaw already-fluid values, or use let in strict mode where an explicit phase declaration is required.

The static checker also enforces spawn boundaries — if Lattice's concurrency model (spawn) is used, fluid bindings from the enclosing scope cannot be captured across the spawn point. Only crystal values can be shared into spawned computations. This is checked before evaluation begins, catching potential data races at parse time rather than at runtime.

This two-layer approach — static checking before evaluation, runtime enforcement during — provides confidence without requiring a full type system or borrow checker. It catches the obvious mistakes early and enforces the subtle invariants at runtime. For the theoretical foundations behind this kind of phase-based type analysis, Benjamin Pierce's Types and Programming Languages is the standard reference.

The Language Beyond Phases

While the phase system is Lattice's defining feature, the language has other characteristics worth noting.

Structs in Lattice can hold closures as fields, enabling object-like patterns without a class system. A struct with function fields and a self parameter in each closure behaves much like an object with methods — but the data flow is explicit, and there's no hidden this pointer or vtable dispatch. When a closure captures self, it receives a deep clone, ensuring that method calls don't produce spooky action at a distance.

Control flow is expression-based — if/else blocks, match expressions, and bare blocks all return values. This reduces the need for temporary variables and makes code more compositional. Error handling uses try/catch blocks with explicit error values rather than exception hierarchies.

The self-hosted REPL is particularly notable. Written entirely in Lattice, it demonstrates that the language is expressive enough to implement its own interactive environment — parsing multi-line input, evaluating expressions, and managing session state. Running ./clat without arguments drops into this REPL, while ./clat file.lat executes a program directly.

Lattice is implemented in C with no external dependencies. The entire codebase — roughly 6,000 lines across the lexer, parser, phase checker, evaluator, and data structures — compiles with a single make invocation. This is a deliberate choice. The language is meant to be small, understandable, and self-contained. You can read the entire implementation in an afternoon. If you're interested in this kind of work, Robert Nystrom's Crafting Interpreters is the best practical guide to building language implementations from scratch — it covers both tree-walking interpreters and bytecode VMs, and Lattice's architecture shares several design decisions with Nystrom's Lox language. For the C implementation side, Kernighan and Ritchie's The C Programming Language remains the definitive reference for writing the kind of clean, minimal C that Lattice targets.

Runtime Characteristics

To understand how the dual-heap architecture behaves in practice, Lattice includes a benchmark suite that exercises different memory patterns — allocation churn, closure-heavy computation, event sourcing, freeze/thaw cycles, game state rollback, long-lived crystal data, persistent tree construction, and undo/redo stacks.

The overview below shows peak RSS (resident set size) alongside the number of live crystal regions at program exit. Benchmarks that use the phase system heavily (like freeze/thaw cycles and persistent trees) maintain more live regions, while purely fluid workloads like allocation churn and closure-heavy computation have none:

The memory churn ratio — total bytes allocated divided by peak live bytes — reveals how aggressively each benchmark recycles memory. A high ratio means the program allocates and discards data rapidly, relying on the GC to keep the working set small. Benchmarks using crystal regions (shown in purple) tend to have lower churn because frozen data is long-lived by design:

Research Papers

For readers interested in the formal foundations and empirical analysis, two companion papers are available:

The Lattice Phase System: First-Class Immutability with Dual-Heap Memory Management — The full research paper covering the language design, formal operational semantics, six proved safety properties (phase monotonicity, value isolation, consuming freeze, forge soundness, heap separation, and thaw independence), implementation details of the dual-heap architecture, and empirical evaluation across eight benchmarks.
Formal Semantics of the Lattice Phase System — A standalone formal treatment containing the complete semantic domains, static phase-checking rules, big-step operational semantics, memory model, and full proofs of all six safety theorems.

Looking Forward

Lattice is at version 0.1.3, which means it's early. The dual-heap architecture is fully wired into the evaluator — freeze operations physically migrate data into arena-backed crystal regions, providing cache locality and O(1) bulk deallocation for immutable data. The mark-and-sweep GC handles fluid values, while crystal regions are collected through reachability analysis during GC cycles.

The deep-clone-on-read strategy is correct but expensive. Future versions may introduce structural sharing for crystal values (since they can't be modified, sharing is safe) or copy-on-write semantics for fluid values that haven't actually been mutated. The phase tags provide the runtime with exactly the information needed to make these optimizations — which values can be shared safely, and which might change.

There's also the question of concurrency. The phase system provides a natural foundation for safe concurrent programming: crystal values can be freely shared across threads (they're immutable), while fluid values are confined to their owning scope. The spawn keyword exists in the parser and phase checker, with static analysis already preventing fluid bindings from crossing spawn boundaries — though concurrent execution isn't yet implemented.

The source code is available on GitHub under the BSD 3-Clause license, and the project site is at lattice-lang.org. If you're interested in language design, memory management, or just want to play with a language that treats mutability as a physical process rather than a type annotation, it's worth a look.

git clone https://github.com/ajokela/lattice.git
cd lattice && make
./clat

SectorZ: A C Compiler in 733 Bytes of Z80 Assembly

A.C. Jokela — Sun, 08 Feb 2026 02:00:00 GMT

A friend recently brought to my attention a project called SectorC and it demonstrated something remarkable: a C compiler that fits in a 512-byte x86-16 boot sector. It compiles a substantial subset of C (variables, functions, if/while, 14 binary operators, pointer dereference, inline assembly) in less space than most error messages.

I wanted to see if the same idea could work on the Z80.

The Z80 is a fundamentally different machine from x86-16. It has no memory-to-memory move instructions, no string operations like stosw, no segment registers that double as a free 64K hash table. It's an 8-bit processor pretending to be 16-bit through register pairs. Every operation that x86 does in one instruction tends to take two or three on Z80. So the question wasn't whether a Z80 version would be bigger (it obviously would) but whether it could stay small enough to be interesting.

The answer is 733 bytes.

What It Compiles

SectorZ implements the same "Barely C" language as SectorC. All tokens must be separated by spaces, which eliminates the need for a real tokenizer. You write C, but with mandatory whitespace:

int c ;
int x ;

void putch ( ) {
  asm ( 58 98 209 ) ;
  asm ( 211 129 ) ;
}

void main ( ) {
  x = 72 ;
  c = x ;
  putch ( ) ;
}

The supported feature set:

Global variable declarations (int name ;)
Function definitions (void name ( ) { ... })
Assignment (x = expr ;)
Function calls (func ( ) ;)
If statements (if ( expr ) { ... })
While loops (while ( expr ) { ... })
14 binary operators: + - * & | ^ << >> == != < > <= >=
Pointer dereference for read (* expr) and write (* expr = expr ;)
Address-of operator (& var)
Inline machine code (asm ( byte byte ... ) ;)
Parenthesized subexpressions

No function arguments, no local variables, no return values, no preprocessor, no error checking. The programmer is trusted completely, in the grand tradition of 1970s C.

The Architecture Tax

SectorC fits in 512 bytes partly because x86-16 is dense. The stosw instruction stores AX to [ES:DI] and increments DI, all in a single byte. On the Z80, the equivalent operation (store a 16-bit value and advance the pointer) takes three bytes at minimum. SectorC uses segment registers to create a free 64K lookup table for variable and function hashing. The Z80 has no segments.

This is the fundamental challenge: the Z80 instruction set is more orthogonal and regular than x86, but it pays for that regularity with verbosity. A simple "emit a 3-byte instruction" helper that writes an opcode and a 16-bit address costs 7 bytes. SectorC does the same thing with stosw and a single mov, effectively 4 bytes.

The result is that SectorZ is larger than its x86 counterpart. But 733 bytes for a self-contained C compiler on an 8-bit processor from 1976 still feels pretty good.

Memory Layout

The compiler loads at address $0000 and uses the upper portion of the Z80's 64K address space for its data structures:

Address	Size	Purpose
`$0000`	733 bytes	Compiler code
`$D000`	256 bytes	Function trampoline table (64 entries x 4 bytes)
`$D100`	256 bytes	Variable storage (128 entries x 2 bytes)
`$D200`	3 bytes	Tokenizer state (semicolon buffer, number flag, EOF flag)
`$D300+`	~11.5K	Generated code output

The compiler reads source code character by character from the MC6850 ACIA serial port, compiles it to Z80 machine code starting at $D300, and then calls main() through the trampoline table. The entire process (read, compile, execute) happens without ever touching a disk.

Key Design Decisions

HL as the Code Pointer

The most important register allocation decision in the whole compiler is using HL as the output pointer. Z80's LD (HL), n instruction stores an immediate byte to the address in HL in just 2 bytes. The alternative, using DE with LD A, n / LD (DE), A, costs 3 bytes per emit site. Since the compiler emits bytes constantly, this saves roughly 25 bytes across all the emit sequences. It does mean HL is permanently occupied, so the tokenizer has to push/pop HL around every call, but the trade-off is clearly worth it.

The `atoi` Hash Trick

This is borrowed directly from SectorC, and it's the single cleverest idea in the whole design. The tokenizer hashes every identifier using the same algorithm as atoi: hash = hash * 10 + char. For numeric tokens, it subtracts '0' from each character first, so the hash is the actual integer value. For identifiers, the raw ASCII values are accumulated.

The key insight is that the hash doubles as a lookup key. Variable names hash to 16-bit values; the low byte (masked to even alignment) indexes into the variable table at $D100. Function names hash similarly, with the low byte (masked to 4-byte alignment) indexing into the trampoline table at $D000. Keywords like if, while, and void hash to fixed values that the compiler checks directly.

No symbol table. No string comparison. Just arithmetic.

The `cp_de_imm` Trick

Comparing a 16-bit register pair against a constant is expensive on Z80. The naive approach (LD A, E / CP low / JR NZ, skip / LD A, D / CP high) costs 7 bytes, and the compiler does this check constantly (for every keyword and punctuation token). SectorZ uses an inline-constant trick instead:

cp_de_imm:
    ex   (sp), hl       ; Swap HL with return address on stack
    ld   a, (hl)        ; Load low byte of constant
    inc  hl
    cp   e              ; Compare with E
    jr   nz, cp_de_ne
    ld   a, (hl)        ; Load high byte of constant
    cp   d              ; Compare with D
cp_de_ne:
    inc  hl             ; Skip past constant regardless
    ex   (sp), hl       ; Restore HL, fix return address
    ret

The 16-bit constant is embedded directly after the CALL, as a DW:

    call  cp_de_imm
    dw    tok_if        ; The constant to compare against
    jr    z, do_if      ; Branch if DE == tok_if

The function reads the constant from the return address, advances the return address past it, and restores everything. Each comparison site costs just 5 bytes (3 for the call, 2 for the constant) instead of 7. With 15+ comparison sites in the compiler, this saves around 30 bytes.

The EX (SP), HL instruction is the hero here. It atomically swaps HL with the top of the stack, which is exactly what we need: get the return address into HL for reading, then put the updated address back. This instruction doesn't exist on x86 (SectorC uses lodsw with a different approach), and it's one of the few places where Z80 is genuinely more elegant.

Runtime Helpers for Binary Operations

SectorC generates inline code for binary operators. The x86 ADD AX, BX is just 2 bytes, so inlining is cheap. On Z80, a 16-bit add is ADD HL, DE (1 byte), but subtraction requires OR A / SBC HL, DE (3 bytes), and multiplication doesn't exist as a single instruction at all.

SectorZ moves all binary operations into runtime helper functions. The generated code for any binary expression follows the same pattern: push left operand, evaluate right operand, pop left into DE, swap, call helper. This costs 6 bytes per operator use in the generated code (1 push + 1 pop + 1 ex + 3 call), but the compiler only needs to emit a uniform sequence, which keeps the compiler itself small.

The 14 runtime helpers add 109 bytes to the compiler. The shift and comparison helpers alone would be prohibitively large to inline (the multiply routine is 25 bytes). By centralizing them, the compiler trades generated code density for compiler code density, which is the right call when you're trying to minimize the compiler.

Function Trampolines

Functions are called through a trampoline table at $D000. When the compiler encounters a function definition, it writes a 3-byte JP actual_address instruction into the trampoline slot. When generated code calls a function, it calls the trampoline, which jumps to the real code.

This eliminates forward-reference problems entirely. Functions can be called before they're defined (as long as the caller executes after the definition has been compiled). The trampoline table has 64 entries, which means the low 8 bits of a function name's hash, masked to 4-byte alignment, must be unique across all functions in a program. For typical small programs, this works fine.

The Semicolon Hack

One of the trickier parsing problems in Barely C is the semicolon. Consider x = 3 + 4 ;. The expression parser reads tokens until it hits something that isn't an operator. When it reads ;, it doesn't match any operator, so it returns. But it has already consumed the semicolon. The statement parser needs that semicolon to know the statement is complete.

SectorC's solution, which SectorZ copies, is a one-character pushback buffer. The tokenizer treats semicolons specially: if it encounters a ; while accumulating a token, it saves a flag and returns the current token. The next call to tok_next checks the flag first and returns a synthetic semicolon token without reading any input.

This is 15 bytes of code that prevents the need for a much more complex token lookahead mechanism.

A Real Program: Prime Sieve

Hello World with asm() blocks is a legitimate test, but it doesn't really exercise the compiler. Here's a Sieve of Eratosthenes that finds all primes below 100:

int c ;
int x ;
int d ;
int i ;
int j ;
int p ;
int n ;
int s ;
int f ;

void putch ( ) {
  asm ( 58 98 209 ) ;
  asm ( 211 129 ) ;
}

void printnum ( ) {
  f = 0 ;
  d = 0 ;
  while ( x >= 100 ) {
    x = x - 100 ;
    d = d + 1 ;
  }
  if ( d ) {
    c = d + 48 ;
    putch ( ) ;
    f = 1 ;
  }
  d = 0 ;
  while ( x >= 10 ) {
    x = x - 10 ;
    d = d + 1 ;
  }
  if ( d + f ) {
    c = d + 48 ;
    putch ( ) ;
  }
  c = x + 48 ;
  putch ( ) ;
}

void main ( ) {
  s = 57344 ;
  n = 100 ;
  i = 2 ;
  while ( i < n ) {
    * ( s + i + i ) = 1 ;
    i = i + 1 ;
  }
  p = 2 ;
  while ( p * p < n ) {
    if ( * ( s + p + p ) ) {
      j = p + p ;
      while ( j < n ) {
        * ( s + j + j ) = 0 ;
        j = j + p ;
      }
    }
    p = p + 1 ;
  }
  i = 2 ;
  while ( i < n ) {
    if ( * ( s + i + i ) ) {
      x = i ;
      printnum ( ) ;
      c = 32 ;
      putch ( ) ;
    }
    i = i + 1 ;
  }
  c = 10 ;
  putch ( ) ;
}

This program demonstrates several things that aren't obvious from the language description.

Pointer arithmetic as arrays. Barely C has no array type, but * ( s + i + i ) reads a 16-bit value from address s + 2*i, effectively treating a block of memory as an integer array. The sieve stores its flags at address 57344 ($E000), well above both the compiler and the generated code.

Decimal output without division. The language has no division or modulo operators, so printnum extracts digits via repeated subtraction. The f flag tracks whether a hundreds digit was printed, ensuring proper formatting of numbers like 2 (just "2") vs 103 ("103", not "13").

The putch function. This is the I/O bridge between Barely C and the hardware. The asm statement emits raw Z80 opcodes: 58 98 209 is LD A, ($D162) (load the low byte of variable c), and 211 129 is OUT ($81), A (send it to the ACIA serial port). The programmer has to compute the variable's memory address from its hash (c hashes to 99, masked to even alignment gives 98, at offset $D162), which is admittedly inconvenient but functional.

Running it through the emulator:

$ (cat primes.bc; printf '\x1a') | retroshield sectorz.bin
2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 89 97

All 25 primes below 100, computed and printed by 733 bytes of compiler generating Z80 machine code on the fly.

Size Breakdown

Where do the 733 bytes go?

Component	Bytes	%
Entry point	13	1.8%
Top-level parser (`compile`)	60	8.2%
Statement dispatch (`compile_stmts`)	51	7.0%
Assignment and calls	30	4.1%
`asm` statement	23	3.1%
Control flow (`if`, `while`)	63	8.6%
Deref assign	27	3.7%
Expression parser	59	8.0%
Unary expressions	73	10.0%
Helpers (`emit_var`, `emit3`, `func_addr`, `emit_test`)	32	4.4%
`cp_de_imm`	11	1.5%
Tokenizer	98	13.4%
`getch` (serial I/O)	26	3.5%
Operator table	58	7.9%
Runtime helpers	109	14.9%

The runtime helpers are the largest single component at 15% of the binary. The multiply routine alone is 25 bytes. If the Z80 had a hardware multiply instruction, the compiler would be noticeably smaller. The tokenizer at 13% is the next largest piece, driven primarily by the multiply-by-10 hash accumulation loop, which requires several register shuffles because the Z80 has no 16-bit multiply.

The operator table is pure data: 14 entries of 4 bytes each (token hash + helper address) plus a 2-byte sentinel. It's an unavoidable cost of supporting 14 operators, but the table-driven approach keeps the expression parser compact at 59 bytes.

SectorC vs. SectorZ

	SectorC (x86-16)	SectorZ (Z80)
Size	512 bytes	733 bytes
Target	x86-16 real mode	Z80 bare metal
I/O	VGA memory, INT 16h	MC6850 ACIA serial
Variables	64K segment	256-byte table
Functions	Direct call	JP trampoline table
Binary ops	Inline generated code	CALL to runtime helpers
Code emit	`stosw` (1 byte)	`LD (HL),n / INC HL` (3 bytes)
Token compare	`lodsw / cmp`	`EX (SP),HL` inline trick

The 221-byte difference comes down to instruction set density. The x86 has a rich CISC heritage (string instructions, memory-to-register operations, implicit operand encoding) that makes tiny programs disproportionately easy. The Z80 is capable but verbose. Every extra byte in the instruction encoding cascades across every emit site, every comparison, every helper function.

That said, the Z80 has a few tricks of its own. EX (SP), HL is a single-byte instruction that enables the inline constant comparison technique. The ADD HL, DE instruction does 16-bit addition in one byte. And EX DE, HL swaps two register pairs in one byte, which is essential for getting operands into the right positions cheaply.

Running It

SectorZ runs on the retro-z80-emulator, a Rust-based Z80 emulator that connects stdin/stdout to an emulated MC6850 ACIA serial port. It also runs on real hardware via the RetroShield Z80. The compiler loads at address $0000, reads source from serial, compiles and executes.

$ z80asm -o sectorz.bin sectorz.asm
$ (cat examples/primes.bc; printf '\x1a') | retroshield sectorz.bin

The \x1a (Ctrl-Z) at the end signals EOF to the compiler. The emulator's serial implementation silently drops null bytes, so the traditional CP/M EOF marker of $00 doesn't work. A minor debugging adventure that reinforced the value of reading the emulator source code before assuming how it handles edge cases.

What's Missing

Quite a lot, obviously. No function arguments means all communication happens through global variables. No local scope means recursive functions can't maintain independent state. No else clause. No for loop. No return statement (functions run to the closing brace and always return). No character or string literals. No preprocessor.

But these are the same limitations as SectorC. The point was never to build a production compiler. It's a demonstration that a meaningful C compiler can exist in a space that most programmers would consider insufficient for anything useful. Seven hundred thirty-three bytes is less than a single TCP packet. It's smaller than most compiler error messages. And yet it reads C source code, performs lexical analysis, parses expressions with arbitrary nesting, generates native machine code with forward-patched control flow, and executes the result, all on a processor designed in 1976.

The source code is available on GitHub.

If you're interested in Z80 development, Design a Z80 Computer is a great hands-on guide, and Learn Multiplatform Assembly Programming with ChibiAkumas covers Z80 assembly alongside other architectures.

Review of "Getting Started with FPGAs" by Russell Merrick

A.C. Jokela — Sat, 07 Feb 2026 14:13:49 GMT

Introduction and Overview

Field programmable gate arrays occupy a fascinating position in the landscape of digital electronics: immensely powerful, endlessly flexible, and yet stubbornly inaccessible to newcomers. Unlike microcontrollers, which have benefited from decades of beginner-friendly ecosystems like Arduino and Raspberry Pi, FPGAs have long remained the province of electrical engineering graduates and industry professionals. The learning curve is steep, the toolchains are complex, and the fundamental paradigm shift from sequential software thinking to parallel hardware description is enough to discourage many aspiring digital designers before they write their first line of HDL. Russell Merrick's Getting Started with FPGAs: Digital Circuit Design, Verilog, and VHDL for Beginners, published by No Starch Press in 2024, makes a deliberate and largely successful attempt to change that.

Merrick brings a distinctive combination of credentials to this task. A University of Massachusetts electrical engineering graduate with a master's degree in the same field, he has worked in defense at BAE Systems and L-3 Communications, in aerospace at satellite propulsion startup Accion Systems, and in commercial electronics at fitness wearable company WHOOP. More importantly for a book of this nature, he has been creating FPGA educational content at nandland.com and its accompanying YouTube channel since 2014, even designing his own FPGA development board, the Nandland Go Board. This decade of answering beginner questions on Stack Overflow and producing tutorial content informs every page of the book. Merrick knows exactly where newcomers get stuck, because he has been watching them get stuck for years.

The book spans 11 chapters plus two appendices across roughly 280 pages, targeting the Lattice iCE40 family of FPGAs. This choice of hardware is itself a pedagogical decision: iCE40 devices are inexpensive, the toolchain (iCEcube2 and Diamond Programmer) is lightweight, and the open source community has embraced Lattice parts for low-level hacking. More expensive FPGAs from AMD (Xilinx) or Intel (Altera) come with sophisticated but overwhelming development environments that can intimidate beginners. By choosing the simpler end of the market, Merrick keeps the focus on understanding FPGA fundamentals rather than wrestling with tool complexity.

The Dual-Language Approach

Perhaps the most distinctive pedagogical choice in the book is Merrick's decision to present every code example in both Verilog and VHDL, side by side. This is no small commitment for an author. It effectively doubles the code content of the book and requires careful attention to ensure that both versions are correct, idiomatic, and illustrative of the same concepts. The payoff, however, is substantial: readers can follow along with whichever language suits their situation without needing to purchase a second book or mentally translate between the two.

Merrick provides a thoughtful comparison of the two languages in Chapter 1 that avoids the partisan flame wars common in FPGA circles. He notes that VHDL, born from the U.S. Department of Defense and inheriting Ada's strong typing, requires more verbose code but catches errors at compile time. Verilog, syntactically closer to C and weakly typed, is more concise but will happily let you write incorrect code without complaint. He even includes a Google Trends analysis showing regional preferences: Verilog dominates in the United States, China, and South Korea, while VHDL is preferred in Germany and France. His practical advice is refreshingly simple: learn whichever language your school or employer uses.

The dual-language presentation also serves as an implicit lesson in the differences between the two HDLs. Readers can observe firsthand how VHDL's strong typing forces explicit resize() calls and type conversions that Verilog handles automatically, or how VHDL's process blocks map to Verilog's always blocks. These side-by-side comparisons provide a deeper understanding of both languages than either one alone could offer.

Building Foundations: Logic, Memory, and Time

The book's first four chapters establish the fundamental building blocks of FPGA design with admirable clarity. Chapter 1, "Meet the FPGA," provides historical context starting from the Xilinx XC2064 in 1985 and surveys the modern FPGA landscape, including the AMD acquisition of Xilinx for $35 billion and Intel's earlier purchase of Altera for $16.7 billion. The chapter's comparison of FPGAs versus microcontrollers versus ASICs across dimensions of cost, speed, power, flexibility, and ease of use is presented in a clean table that serves as a useful reference throughout the reader's career. Merrick is honest about where FPGAs fall short: they are more expensive than microcontrollers at scale, consume more power, and are harder to use. But when you need raw bandwidth, parallel computation, or hardware flexibility, nothing else will do.

Chapter 2 walks through hardware and tool setup, getting readers to their first working FPGA project: wiring switches to LEDs. This "hello world" equivalent may seem trivial, but it introduces the full development workflow: writing HDL code, creating a project, adding pin constraints, running the build, connecting the board, and programming the FPGA. Each step is a potential stumbling block for beginners, and Merrick guides through them methodically.

Chapter 3 on Boolean algebra and the look-up table is where the book begins to reveal its deeper ambitions. Rather than treating logic gates as abstract mathematical curiosities, Merrick connects them directly to the physical reality inside an FPGA. The key insight, clearly articulated, is that discrete logic gates do not actually exist inside modern FPGAs. Instead, all Boolean operations are implemented through look-up tables, programmable devices that can represent any truth table you can imagine. A single three-input LUT can replace an AND gate, an OR gate, an XOR gate, or any combination thereof. This understanding, that LUTs and flip-flops are the two fundamental building blocks from which all FPGA designs are constructed, is the conceptual foundation upon which the entire book rests.

Chapter 4 introduces the flip-flop and with it the concept of state. Where LUTs handle combinational logic, flip-flops provide sequential logic, giving the FPGA memory of what happened previously. The chapter carefully distinguishes between combinational and sequential logic, explains the clock signal and its role in synchronizing operations, and warns about the dangers of latches, an accidental design pattern that causes unpredictable timing behavior. Merrick's years of answering beginner questions are evident here; the latch warning, including the specific synthesis warning message readers should watch for, addresses one of the most common FPGA beginner mistakes.

Simulation, Testing, and the Black Box Problem

Chapter 5, on simulation, contains some of the book's most valuable practical wisdom. Merrick frames the motivation perfectly: your FPGA is essentially a black box. You can change the inputs and observe the outputs, but you cannot see what is happening inside. Simulation cracks open that black box, letting you examine every internal signal, register, and wire as your design executes.

He drives this point home with an anecdote from his professional experience: a coworker spent weeks debugging an FPGA design using oscilloscopes and logic analyzers, trying to find a data corruption issue on the physical hardware. Merrick checked the code out, built a simulation testbench, and found the bug within hours. The lesson is clear: simulation is not an optional nicety but an essential part of the FPGA development process that will save you enormous amounts of time.

The chapter introduces EDA Playground, a free web-based simulator, as the primary tool. This is a pragmatic choice that eliminates the barrier of downloading and configuring multi-gigabyte vendor tools. Readers learn to write testbenches, the HDL code that exercises a design by providing inputs and monitoring outputs. The first testbench, for the AND gate project from Chapter 3, walks through every detail: declaring signals, instantiating the unit under test, driving stimulus with delay statements, and generating waveform output for visual analysis. The progression to more sophisticated testing, including self-checking testbenches that automatically verify correctness and a discussion of formal verification, shows that Merrick understands the professional importance of testing even as he keeps the material accessible.

Common Modules and the Building-Block Philosophy

Chapter 6, "Common FPGA Modules," represents a turning point in the book's complexity. Having established the primitive components, LUTs and flip-flops, Merrick now shows how to combine them into reusable building blocks: multiplexers, demultiplexers, shift registers, RAM, and FIFOs. Each module is explained conceptually, implemented in both Verilog and VHDL, and connected to practical applications.

The FIFO (First In, First Out) implementation is particularly well done. Merrick walks through the complete design including read and write address management, element counting, full and empty flags, and "almost full" and "almost empty" threshold flags. The code is production-quality, handling edge cases like simultaneous read and write operations and providing anticipatory flags that let higher-level modules stop writing before the FIFO actually overflows. This is not a toy example; it is a genuinely useful piece of infrastructure that readers can adapt for their own projects.

The Linear Feedback Shift Register (LFSR) implementation showcases a more specialized application: generating pseudo-random sequences using nothing more than shift registers and XOR gates. Merrick explains why this matters in practice, as LFSRs are used in everything from encryption to test pattern generation, and provides the implementation alongside a conceptual explanation of why specific feedback tap positions produce maximum-length sequences.

The Build Process Demystified

Chapter 7 tackles synthesis, place and route, and crossing clock domains, subjects that many beginner texts either skip or relegate to appendices. Merrick treats them as essential knowledge, and rightly so. Understanding what happens when you press the "Build FPGA" button is critical for writing efficient, correct designs.

The synthesis discussion is particularly strong. Merrick explains logic optimization, the tool's process of minimizing the resources your design consumes, and connects it to the utilization report that tells you how many LUTs, flip-flops, and block RAMs your design uses. He provides practical guidance on what to do when your design does not fit: switch to a larger FPGA, rewrite resource-intensive modules, or remove functionality. His anecdote about a division operation that forced a million-dollar hardware upgrade to a larger FPGA family illustrates the real-world consequences of resource-intensive code.

The section on non-synthesizable code addresses a source of deep confusion for beginners transitioning from software: not all valid Verilog or VHDL code can be translated into physical hardware. Time delays, print statements, file operations, and certain loop constructs exist solely for simulation and will be silently ignored or flagged during synthesis. Merrick's treatment of synthesizable versus non-synthesizable for loops is especially valuable. In software, a for loop iterates sequentially over time. In synthesizable FPGA code, a for loop unrolls into replicated hardware that executes simultaneously in a single clock cycle. Beginners who expect a 10-iteration loop to take 10 clock cycles will be baffled when it completes in one. Merrick shows both the pitfall and the correct pattern for implementing sequential iteration using counters and if statements.

The clock domain crossing section covers a topic that trips up even experienced FPGA designers. When signals pass between parts of a design running at different clock frequencies, metastability can cause unpredictable behavior. Merrick explains the problem and presents standard solutions: double-flop synchronizers for single-bit signals and FIFOs for multi-bit data transfers.

State Machines and the Memory Game

Chapter 8, "The State Machine," brings together all the preceding material in the book's most ambitious project: an interactive memory game using a seven-segment display. State machines are the standard way to implement sequential behavior in FPGAs, a series of states connected by transitions triggered by events. Merrick presents two implementation styles (two-process and one-process blocks), discusses best practices, and then launches into a full project that requires planning the state machine, organizing the design across multiple modules, interfacing with a seven-segment display, and writing comprehensive testbenches.

The memory game project is a strong capstone for the book's middle section. It requires the reader to synthesize knowledge of flip-flops, multiplexers, RAM, state machines, and physical I/O constraints into a working interactive system. The project is complex enough to feel like genuine FPGA engineering but simple enough to complete without despair.

FPGA Primitives and the Hardware Reality

Chapter 9 examines the specialized hardware blocks that differentiate FPGAs from simple arrays of LUTs and flip-flops. Block RAM provides dedicated memory resources that are faster and more efficient than flip-flop-based storage. The Digital Signal Processing (DSP) block offers hardened multiply-accumulate units that are essential for math-intensive applications like filtering and signal processing. The Phase-Locked Loop (PLL) generates new clock frequencies from an input clock, enabling designs that need multiple clock domains.

Merrick explains both the capabilities and the creation process for each primitive, covering both instantiation (directly connecting to the hardware block in your code) and the GUI approach (using vendor tools to configure the block graphically). This dual treatment acknowledges that different workflows suit different situations and different engineers.

Numbers, Math, and the Rules of Binary Arithmetic

Chapter 10, "Numbers and Math," is arguably the most technically dense chapter in the book, and it may also be the most practically valuable. Performing mathematical operations inside an FPGA is fraught with subtle pitfalls that can produce silently incorrect results. Merrick distills years of hard-won experience into six clear rules that, if followed, will prevent the most common binary math errors.

The chapter progresses methodically through addition, subtraction, multiplication, and division, showing both correct and incorrect implementations at each step. The emphasis on showing code that produces wrong answers is a particularly effective teaching strategy. When Merrick demonstrates that adding two 4-bit unsigned numbers (9 + 11) and storing the result in a 4-bit output gives 4 instead of 20, the reader understands viscerally why Rule #1 (the result should be at least 1 bit bigger than the biggest input) matters. The discussion of sign extension, the process of increasing a binary number's bit width while preserving its sign and value, is handled with exceptional clarity.

The treatment of division is refreshingly honest. Merrick states plainly that division is resource-intensive and should be avoided when possible inside an FPGA. He presents three alternatives: restricting divisors to powers of 2 (implemented as simple shift-right operations), using precalculated lookup tables stored in block RAM, and spreading the operation across multiple clock cycles using iterative subtraction. His anecdote about "the million-dollar divide," where a single division operation forced an upgrade to a more expensive FPGA family at a cost exceeding $1 million in hardware changes, makes the point memorably.

The fixed-point arithmetic section that closes the chapter is an excellent primer on representing decimal values in hardware without the complexity and resource cost of floating-point. Merrick introduces the UX.Y and SX.Y notation for unsigned and signed fixed-point formats, explains the conversion between formats, and works through addition and multiplication examples that demonstrate the rules for matching decimal widths and sizing outputs.

I/O, SerDes, and the Edge of the Chip

The final technical chapter covers getting data in and out of the FPGA, where the digital logic meets the physical world. Merrick covers GPIO pin configuration including I/O buffers, output enable signals, and bidirectional communication. He explains operating voltage standards (LVCMOS33, TTL, LVCMOS25), drive strength in milliamps, and slew rate, the speed at which a signal transitions between high and low. The discussion of single-ended versus differential signaling provides useful background for understanding high-speed interfaces.

The SerDes (serializer/deserializer) section introduces the concept of converting parallel data to serial for high-speed transmission and back again at the receiver. While the iCE40 FPGAs used in the book's projects do not include SerDes blocks, Merrick covers the topic at a conceptual level to prepare readers who may eventually work with more capable devices. This forward-looking coverage, explaining concepts that exceed the current hardware's capabilities, is a sensible choice that increases the book's long-term value.

The Appendices: Beyond the Technical

Appendix A surveys three development boards compatible with the book's projects: the Nandland Go Board, the Lattice iCEstick, and the Alchitry Cu. The Nandland Go Board, designed by Merrick himself, is naturally the most fully supported option, but the inclusion of alternatives from other vendors demonstrates good faith.

Appendix B, "Tips for a Career in FPGA Engineering," is an unusual and welcome addition to a technical book. Merrick covers resume construction, interview preparation, and job offer negotiation with the practical specificity of someone who has been on both sides of the hiring table. He advises listing HDL projects prominently on resumes, preparing for whiteboard coding exercises in Verilog or VHDL, and understanding that FPGA engineering positions often command premium salaries due to the specialized skill set. For readers considering FPGA development as a career rather than a hobby, this appendix alone could be worth the price of the book.

Strengths and Unique Value

The book's greatest strength is its accessibility. Merrick has an uncommon talent for explaining hardware concepts in software-friendly terms without being condescending or imprecise. His comparison of low-level FPGA programming to building with individual LEGO bricks while high-level microcontroller programming is like working with preconstructed LEGO sets captures the essential difference in a way that immediately resonates. The parallel-versus-serial thinking distinction, hammered home from the first chapter, is the single most important conceptual hurdle for software developers entering FPGA territory, and Merrick addresses it directly and repeatedly.

The hands-on projects embedded throughout the book, from wiring switches to LEDs through blinking an LED, debouncing a switch, selectively blinking LEDs, and building a memory game, provide a satisfying progression of complexity. Each project builds on concepts from previous chapters and results in something that works on real hardware, providing the tangible feedback that keeps learners motivated.

The dual Verilog/VHDL presentation is a genuine differentiator. Most FPGA books choose one language and leave readers of the other to fend for themselves. Merrick's commitment to both languages, while surely doubling his authorial workload, produces a reference that serves a broader audience and provides implicit comparative education that deepens understanding of both languages.

The inclusion of professional engineering wisdom, from the million-dollar divide anecdote to the latch warnings to the career advice appendix, gives the book a practical grounding that purely academic treatments lack. Merrick writes as someone who has shipped FPGA designs in defense, aerospace, and consumer electronics, and that experience informs his choices about what to emphasize and what to warn against.

Limitations and Missed Opportunities

The book's commitment to the iCE40 platform, while pedagogically sound, does impose limitations. These are small, inexpensive FPGAs with limited resources, no hard processor cores, and minimal specialized IP blocks. Readers who complete the book and want to tackle more ambitious projects, say, implementing a RISC-V soft processor or building a video processing pipeline, will need to transition to AMD or Intel FPGA platforms with significantly different (and more complex) toolchains. The book provides a conceptual foundation for that transition but no practical guidance through it.

The Windows-centric tooling requirement is a notable friction point. Merrick acknowledges that the iCE40 tools work best on Windows and recommends a virtual machine for Mac and Linux users. In an era when open source FPGA tools like Yosys and nextpnr have matured significantly, especially for iCE40 targets, the absence of any mention of the open source toolchain feels like a missed opportunity. For Linux users in particular, the Yosys/nextpnr/IceStorm flow provides a native, arguably simpler development experience than running Windows tools in a VM.

The book could benefit from more substantial treatment of debugging workflows. While simulation is covered well, on-FPGA debugging receives only brief mention. Topics like using integrated logic analyzers, reading back internal signals through JTAG, or structured approaches to narrowing down hardware bugs would strengthen the book's practical value for readers who move beyond simulation into real hardware deployment.

Some readers may find the book's pace in early chapters slow if they already have digital logic background from university courses. The extensive coverage of Boolean algebra, truth tables, and logic gates in Chapter 3, while valuable for true beginners, may feel redundant for readers with prior exposure. Conversely, the later chapters on clock domain crossing, SerDes, and fixed-point arithmetic accelerate considerably and could benefit from additional worked examples.

Who Should Read This Book

The book is best suited for three audiences. First, software developers who are curious about hardware and want to understand what happens below the abstraction layer of their programming languages. The explicit comparisons between software concepts (sequential execution, for loops, variables) and their FPGA counterparts (parallel execution, hardware replication, signals and registers) make this a natural bridge text. Second, electronics hobbyists and makers who have experience with microcontrollers like Arduino or Raspberry Pi and want to explore the next level of hardware control. Third, university students encountering FPGAs in coursework who need a more approachable companion text to supplement dense academic material.

Experienced FPGA engineers will find little new technical content here, though the book's explanations may provide useful language for mentoring junior colleagues. Readers looking for advanced topics like high-level synthesis, SystemVerilog verification methodology, or FPGA-based machine learning acceleration will need to look elsewhere.

Conclusion

Getting Started with FPGAs succeeds at its stated goal: building a solid foundation for anyone interested in the world of FPGA design. Russell Merrick has distilled a decade of educational content creation into a coherent, well-structured text that respects the reader's intelligence while acknowledging the genuine difficulty of the subject matter. The dual-language approach, the hands-on projects, the honest treatment of where FPGAs excel and where they fall short, and the professional engineering perspective all contribute to a book that fills a genuine gap in the FPGA literature.

The book does not attempt to be comprehensive. It will not teach you everything about Verilog or VHDL, will not prepare you to design a production FPGA system from scratch, and will not cover the full depth of any single topic it addresses. What it will do is give you a clear mental model of how FPGAs work at a fundamental level, equip you with enough Verilog and VHDL to write and simulate basic designs, and provide the conceptual vocabulary to continue learning independently. For a subject as intimidating as FPGA development, that is no small achievement.

In the broader context of No Starch Press's catalog of accessible technical books, Getting Started with FPGAs fits naturally alongside titles that demystify complex subjects without dumbing them down. It occupies a niche that has been surprisingly underserved: the true beginner FPGA book that takes the reader seriously. For anyone who has stared at an FPGA development board with a mixture of curiosity and trepidation, wondering how to bridge the gap between software thinking and hardware reality, this book provides a clear and well-lit path forward.

Three Paths to Rust on Custom Hardware

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

If you want to run Rust on hardware that Rust was never designed for—a Z80 from 1976, a custom 16-bit RISC CPU, a Game Boy—you have a problem. The Rust compiler targets LLVM, and LLVM doesn't know your CPU exists.

I've spent some time solving this problem in different ways. I built LLVM backends for both the Z80 and my own Sampo 16-bit RISC architecture. That's the "correct" solution—and it works—but it's also countless amounts of time wrestling with TableGen definitions and GlobalISel pipelines, though agentic coding tools help immensely.

There's a recent project that offers a different path entirely: Eurydice, a Rust-to-C transpiler developed by researchers at Inria and Microsoft. The premise is simple. If your target already has a C compiler, you can skip LLVM entirely:

Rust → Eurydice → C → existing C compiler → your target

For the Z80, that existing C compiler is SDCC, the Small Device C Compiler. It's mature, well-tested, and has supported the Z80 for decades.

This article explores three distinct paths to getting Rust on custom hardware, and includes a hands-on walkthrough of the Eurydice approach—transpiling Rust to readable C, then compiling that C for the Z80 with SDCC.

Path 1: The Full LLVM Backend

This is what I did for both the Z80 and Sampo. You fork LLVM, implement a complete backend—register descriptions, instruction selection, calling conventions, type legalization, assembly printing—and teach the Rust compiler about your new target triple.

The pipeline looks like this:

Rust source → rustc frontend → LLVM IR → Your Backend → Assembly → Binary

What you get:

Full Rust language support (within hardware constraints)
Access to LLVM's optimization passes—constant folding, dead code elimination, register allocation
A single backend that works for Rust, C (via Clang), and any other LLVM frontend
Native code quality that improves as LLVM improves

What it costs:

LLVM is roughly 30 million lines of C++. The learning curve is vertical.
A minimal backend requires 25-30 files of TableGen, C++, and CMake configuration
Type legalization—teaching LLVM that your 8-bit CPU can't natively handle 64-bit integers—is where 60% of the effort lives
Keeping your fork synchronized with upstream LLVM is ongoing maintenance

For the Z80, the register poverty problem alone was really the bane of the efforts. The Z80 has seven 8-bit registers, some of which can pair into 16-bit values. LLVM's register allocator expects 16 or 32 general-purpose registers. Every function call, every 16-bit addition, every pointer dereference requires careful choreography of a register file designed when RAM was measured in kilobytes. If you follow this blog and have read about my efforts to get LLVM and Rust working for the Z80, you will recall that I needed hundreds of gigabytes of RAM on the build server just to allow full expansion of all the 8-bit registers to the 64-bit and 128-bit types in Rust.

For Sampo, the experience was smoother—a 16-bit RISC with 16 registers is closer to what LLVM expects. But "smoother" is relative. The Sampo LLVM backend still involved implementing GlobalISel pipelines, debugging opaque errors like "SmallVector capacity overflow," and building Rust's libcore for a target that had never existed.

The full LLVM approach gives you the best results. It's also the hardest path by a wide margin.

Path 2: Rust → C via Eurydice → Existing C Compiler

This is the path that caught my attention. Eurydice takes a fundamentally different approach: instead of teaching LLVM about your hardware, you transpile Rust to readable C and let an existing C compiler handle the target. This is the path other niche languages, like nim use to make portable code.

What Is Eurydice?

Eurydice grew out of the Aeneas formal verification project. Its predecessor, KaRaMeL, compiled F* (a dependently typed functional language used for cryptographic proofs) to C. Eurydice adapts this infrastructure for Rust.

The pipeline has two stages:

Charon extracts rustc's Medium-level Intermediate Representation (MIR) and dumps it as a JSON .llbc file
Eurydice reads the .llbc, applies roughly 30 optimization passes to lower Rust semantics to C, and emits .c and .h files

The generated C is genuinely readable—not the kind of machine-generated nightmare you'd expect. Rust structs become C structs. Functions keep their names (with module prefixes). Control flow is preserved. The goal is C code a human could maintain, not just C code that compiles.

Why This Matters for Retro/Custom Hardware

Here's the insight that matters for this audience: many obscure targets already have a C compiler but will never get an LLVM backend. The Z80 has SDCC. The 6502 has cc65. The 68000 has multiple mature C compilers. The Game Boy has GBDK.

If Eurydice can produce C that these compilers accept, you get Rust on all of these platforms without touching LLVM at all.

The Real-World Use Case

This isn't just theoretical. Eurydice's flagship use case is post-quantum cryptography. The ML-KEM (Kyber) key encapsulation algorithm was written and verified in Rust via the libcrux library, then transpiled to C via Eurydice for integration into:

Mozilla's NSS (Network Security Services)
Microsoft's SymCrypt
Google's BoringSSL

These organizations need verified cryptographic implementations but can't take a dependency on the Rust toolchain in their C/C++ codebases. Eurydice bridges that gap.

Limitations

Eurydice is honest about what it can and can't do:

No dyn traits — dynamic dispatch isn't yet supported (vtable generation is planned)
Const generics can cause Charon's MIR extraction to fail
Iterators get compiled to while loops with runtime state management—functional but potentially less efficient than hand-written C loops
Monomorphization is required for generics, producing separate C functions for each type instantiation
Strict aliasing — the generated code's handling of dynamically sized types violates C's strict-aliasing rules, requiring -fno-strict-aliasing
Panic-free code only — Eurydice doesn't replicate Rust's panic semantics for integer overflow or bounds checking

For retro targets, some of these limitations are actually advantages. no_std embedded Rust code tends to avoid dyn traits and complex iterators. The code that runs well on a Z80—small functions, fixed-size arrays, simple control flow—is exactly the subset Eurydice handles best.

Path 3: Manual `no_std` with FFI to C

The minimal approach. You write your core logic in Rust targeting a supported architecture, then manually bridge to C via FFI for anything target-specific.

#![no_std]
#![no_main]

extern "C" {
    fn z80_out(port: u8, value: u8);
}

#[no_mangle]
pub extern "C" fn compute_trajectory() -> u16 {
    // Pure Rust computation here
    let result = some_math(42);
    unsafe { z80_out(0x03, result as u8); }
    result
}

You compile the Rust portion for a supported target (like thumbv6m-none-eabi for ARM Cortex-M0, the smallest Rust target), extract the algorithm logic, and rewrite the hardware interface in C or assembly.

What you get:

Rust's type safety and ownership model for algorithm development
No toolchain modifications required
Works today with stable Rust

What it costs:

You're not actually running Rust on your target—you're using Rust as a development language and manually porting
No automated pipeline; changes to the Rust code require manual re-porting
You lose Rust's guarantees at the FFI boundary
Testing requires maintaining parallel implementations

This is really a development methodology, not a compilation strategy. It's useful for prototyping algorithms in Rust before implementing them in C for a constrained target, but it doesn't give you "Rust on Z80" in any meaningful sense.

Walkthrough: Rust → C → Z80

Let's do something concrete. We'll take a simple Rust program, transpile it to C with Eurydice, and compile the C for the Z80 with SDCC. I tested every step of this on my machine—what follows is real output, not approximations.

Prerequisites

You'll need:

Nix (recommended) or OCaml + OPAM for building Eurydice
SDCC for Z80 compilation
Rust (Eurydice pins its own nightly via Charon)

On macOS:

# Install SDCC
brew install sdcc

# Install Nix (if you don't have it)
curl -L https://nixos.org/nix/install | sh

Nix is the path of least resistance here. Eurydice depends on specific versions of OCaml, Charon, and KaRaMeL, and the Nix flake pins all of them. You can build everything manually with OPAM, but you'll be chasing version mismatches for an afternoon.

Step 1: Write a Rust Program

Create a small Rust project. The key constraint: it needs to stay within the subset Eurydice handles well. No dyn traits, no complex iterators, no standard library I/O.

cargo init --name z80demo
cd z80demo

Replace src/main.rs with something appropriate for a Z80:

/// Simple GCD computation — the kind of algorithm
/// you'd actually want on constrained hardware.
pub fn gcd(mut a: u16, mut b: u16) -> u16 {
    while b != 0 {
        let t = b;
        b = a % t;
        a = t;
    }
    a
}

/// Compute LCM using GCD
pub fn lcm(a: u16, b: u16) -> u16 {
    if a == 0 || b == 0 {
        return 0;
    }
    (a / gcd(a, b)) * b
}

/// A lookup table — common pattern in embedded code
static FIBONACCI: [u16; 12] = [
    0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89
];

pub fn fib_lookup(n: u8) -> u16 {
    if (n as usize) < FIBONACCI.len() {
        FIBONACCI[n as usize]
    } else {
        0
    }
}

fn main() {
    let result = gcd(252, 105);
    assert_eq!(result, 21);

    let l = lcm(12, 18);
    assert_eq!(l, 36);

    let f = fib_lookup(10);
    assert_eq!(f, 55);
}

This is deliberately simple: u16 arithmetic (native to the Z80's 16-bit register pairs), no heap allocation, no traits, no closures. It's the kind of code that will transpile cleanly.

Step 2: Extract MIR with Charon

Charon hooks into the Rust compiler to extract its Medium-level Intermediate Representation (MIR). The critical detail I missed on my first attempt: Eurydice requires Charon to be invoked with --preset=eurydice. Without it, Eurydice will reject the output with a cryptic error.

Using Nix, you can run Charon directly without cloning or building anything:

nix --extra-experimental-features "nix-command flakes" \
    run 'github:aeneasverif/eurydice#charon' -- cargo --preset=eurydice

The first run takes a while as Nix fetches and builds Charon's Rust toolchain. Subsequent runs complete in seconds:

   Compiling z80demo v0.1.0 (/Users/alexjokela/projects/eurydice/z80demo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.25s

This produces z80demo.llbc—a 107KB JSON file containing the type declarations, function bodies, and trait implementations in Charon's intermediate format.

If Charon fails, the error usually points to an unsupported Rust feature. The fix is almost always to simplify the Rust code—replace iterators with explicit loops, avoid const generics, use concrete types instead of generics where possible.

Step 3: Transpile to C with Eurydice

nix --extra-experimental-features "nix-command flakes" \
    run 'github:aeneasverif/eurydice' -- z80demo.llbc

Eurydice processes the LLBC through roughly 30 optimization passes and emits two files:

1️⃣ LLBC ➡️  AST
2️⃣ Cleanup
3️⃣ Monomorphization, datatypes
✅ Done

Here's the actual generated z80demo.c (comments and headers trimmed for clarity):

#include "z80demo.h"

const
Eurydice_arr_f5
z80demo_FIBONACCI = { .data = { 0U, 1U, 1U, 2U, 3U, 5U, 8U, 13U, 21U, 34U, 55U, 89U } };

uint16_t z80demo_fib_lookup(uint8_t n)
{
  uint16_t uu____0;
  if ((size_t)n < (size_t)12U)
  {
    uu____0 = z80demo_FIBONACCI.data[(size_t)n];
  }
  else
  {
    uu____0 = 0U;
  }
  return uu____0;
}

/**
 Simple GCD computation — the kind of algorithm
 you'd actually want on constrained hardware.
*/
uint16_t z80demo_gcd(uint16_t a, uint16_t b)
{
  while (b != 0U)
  {
    uint16_t t = b;
    b = (uint32_t)a % (uint32_t)t;
    a = t;
  }
  return a;
}

/**
 Compute LCM using GCD
*/
uint16_t z80demo_lcm(uint16_t a, uint16_t b)
{
  if (!(a == 0U))
  {
    if (!(b == 0U))
    {
      uint16_t uu____0 = a;
      return (uint32_t)uu____0 / (uint32_t)z80demo_gcd(a, b) * (uint32_t)b;
    }
  }
  return 0U;
}

And the generated z80demo.h:

#include "eurydice_glue.h"

typedef struct Eurydice_arr_f5_s { uint16_t data[12U]; } Eurydice_arr_f5;

extern const Eurydice_arr_f5 z80demo_FIBONACCI;

uint16_t z80demo_fib_lookup(uint8_t n);
uint16_t z80demo_gcd(uint16_t a, uint16_t b);
uint16_t z80demo_lcm(uint16_t a, uint16_t b);
void z80demo_main(void);

A few things to notice:

Rust doc comments are preserved as C comments. That's a nice touch.
Arrays are wrapped in structs (Eurydice_arr_f5). This gives C arrays value semantics—you can return and assign them, matching Rust's behavior. The tradeoff is that array access goes through .data[n] instead of [n].
Arithmetic is widened to uint32_t. Eurydice promotes u16 % u16 to uint32_t to avoid C's integer promotion pitfalls. On a Z80, this means 32-bit math library calls—SDCC handles this, but it's heavier than necessary. A hand-tuned version would keep the modulo at 16 bits.
assert_eq! becomes EURYDICE_ASSERT with a pair struct. The generated main() (which I'm omitting here) creates const_uint16_t__x2 structs to hold the two comparison operands. It works, but it's verbose compared to a simple ==.
Control flow is preserved. The if/else in fib_lookup, the while loop in gcd—they're structurally identical to the Rust original.

Step 4: Adapt for Bare-Metal Z80

Here's where things get practical. Eurydice's eurydice_glue.h includes <stdio.h>, <stdlib.h>, <string.h>, and KaRaMeL headers—none of which exist on a bare-metal Z80. We need a minimal replacement that provides only what the generated code actually uses.

Create eurydice_glue.h in the project directory:

/*
 * Minimal eurydice_glue.h for bare-metal Z80 via SDCC.
 * Replaces the full Eurydice glue header with only what z80demo needs.
 */
#ifndef EURYDICE_GLUE_H
#define EURYDICE_GLUE_H

#include <stdint.h>

/* SDCC Z80: size_t is 16-bit */
#ifndef _SIZE_T_DEFINED
typedef unsigned int size_t;
#define _SIZE_T_DEFINED
#endif

/* On bare metal, assertions just halt the CPU */
#define EURYDICE_ASSERT(test, msg)  \
  do {                              \
    if (!(test)) {                  \
      __asm                         \
        halt                        \
      __endasm;                     \
    }                               \
  } while (0)

#endif /* EURYDICE_GLUE_H */

This is the key insight for using Eurydice on constrained targets: the glue header is a compatibility layer, not a fundamental dependency. For any specific program, you can replace it with a minimal shim that provides only what that program's generated code actually references.

Now create z80_main.c—our bare-metal wrapper with serial I/O:

#include <stdint.h>

/* Import Eurydice-generated functions */
extern uint16_t z80demo_gcd(uint16_t a, uint16_t b);
extern uint16_t z80demo_lcm(uint16_t a, uint16_t b);
extern uint16_t z80demo_fib_lookup(uint8_t n);

/* Z80 serial output via port 0x01 (e.g., MC6850 ACIA) */
__sfr __at 0x01 serial_data;

void putchar_z80(char c) {
    serial_data = c;
}

void print(const char *s) {
    while (*s) {
        putchar_z80(*s++);
    }
}

void print_u16(uint16_t val) {
    char buf[6];
    uint8_t i = 5;
    buf[i] = '\0';
    if (val == 0) {
        putchar_z80('0');
        return;
    }
    while (val > 0 && i > 0) {
        buf[--i] = '0' + (val % 10);
        val /= 10;
    }
    while (buf[i]) {
        putchar_z80(buf[i++]);
    }
}

void main(void) {
    uint16_t g = z80demo_gcd(252, 105);
    print("GCD(252,105) = ");
    print_u16(g);
    print("\r\n");

    uint16_t l = z80demo_lcm(12, 18);
    print("LCM(12,18) = ");
    print_u16(l);
    print("\r\n");

    uint16_t f = z80demo_fib_lookup(10);
    print("Fib(10) = ");
    print_u16(f);
    print("\r\n");

    __asm
        halt
    __endasm;
}

Step 5: Compile with SDCC

# Compile the Eurydice-generated code
sdcc -mz80 -c --std-c11 -I. z80demo.c

# Compile our Z80 wrapper
sdcc -mz80 -c --std-c11 z80_main.c

# Link — code at 0x0000, data at 0x8000
sdcc -mz80 --code-loc 0x0000 --data-loc 0x8000 \
     -o z80demo.ihx z80_main.rel z80demo.rel

# Convert to raw binary
makebin -s 32768 z80demo.ihx z80demo.bin

Both compilation steps complete with zero warnings. The linker produces a 32KB ROM image. According to the memory map, the _CODE segment is 717 bytes—our Rust-originated logic plus I/O wrappers and SDCC's runtime support for 32-bit division.

What the Z80 Assembly Looks Like

Here's the GCD function as SDCC compiled it, straight from the Eurydice-generated C:

_z80demo_gcd::
    ; while (b != 0U)
00101$:
    ld    a, d
    or    a, e
    jr    Z, 00103$
    ; b = (uint32_t)a % (uint32_t)t;
    push  de
    call  __modsint
    ; a = t;
    pop   hl
    jr    00101$
00103$:
    ; return a;
    ex    de, hl
    ret

SDCC's register-based calling convention (sdcccall 1) passes the first 16-bit argument in HL and the second in DE, returning results in DE. The GCD loop is tight—test for zero, call the modulo library routine, swap, repeat. The __modsint call is where the uint32_t widening lands; SDCC promotes to 32-bit for the modulo, which adds overhead but ensures correctness.

The Fibonacci lookup is even cleaner:

_z80demo_fib_lookup::
    ; if ((size_t)n < (size_t)12U)
    ld    c, a
    ld    b, #0x00
    ld    a, c
    sub   a, #0x0c
    jr    NC, 00102$
    ; return z80demo_FIBONACCI.data[(size_t)n]
    ld    de, #_z80demo_FIBONACCI+0
    ld    l, c
    ld    h, b
    add   hl, hl        ; n * 2 (16-bit entries)
    add   hl, de        ; base + offset
    ld    e, (hl)
    inc   hl
    ld    d, (hl)
    ret
00102$:
    ; return 0
    ld    de, #0x0000
    ret

The bounds check compiles to a single SUB/JR NC pair. The array lookup uses ADD HL,HL to compute the 16-bit element offset—exactly what you'd write by hand.

What Just Happened

We took Rust source code, ran two commands (Charon, then Eurydice), got readable C, wrote a 25-line glue header, and compiled for the Z80 with SDCC. Total code size: 717 bytes. No LLVM fork. No TableGen. No hours or days of debugging register allocation.

The entire Eurydice pipeline—from Rust to C—preserves the structure of the original code. The SDCC step is standard Z80 C compilation, unchanged from what you'd do with hand-written C. The main adaptation work is replacing the glue header, which took about five minutes once I understood what the generated code actually referenced.

Comparing the Three Paths

	LLVM Backend	Eurydice → C	Manual FFI
Rust coverage	Full `no_std`	Subset (no `dyn`, limited generics)	None (development aid only)
Code quality	Native optimized	Depends on C compiler	N/A
Maintenance	Track LLVM upstream	Track Eurydice + Charon	Manual sync
Automation	Full pipeline	Full pipeline	Manual porting
Prerequisites	LLVM expertise	Nix or OCaml	Basic C/Rust
Target reuse	All LLVM frontends	C-only output	None

The right choice depends on your timeline and ambitions. If you're building a serious toolchain for a custom CPU—something you'll maintain for years—the LLVM backend is worth the investment. If you need Rust on a platform that already has a C compiler and you're working with a constrained subset of the language, Eurydice is a compelling shortcut.

The Elephant in the Room

Eurydice works best for small, self-contained programs that avoid complex Rust features. Its primary limitation is Charon, the MIR extractor, which is "routinely foiled by more recent Rust features" according to the LWN article that prompted this exploration. Const generics, complex trait bounds, and advanced pattern matching can all cause extraction failures.

For embedded and retro targets, this might actually be fine. The Rust code you'd write for a Z80—no_std, no allocator, fixed-size buffers, simple arithmetic—is exactly the subset that Eurydice handles well. You're not going to impl Iterator your way through 64KB of address space.

But if your Rust code is complex enough to genuinely benefit from Rust's type system—generics, trait objects, complex lifetime management—you've probably outgrown what Eurydice can transpile. At that point, you need an LLVM backend.

The Eurydice team is actively working on expanding coverage. Dynamic dispatch via vtables is the next major feature. Broader standard library support is an ambitious goal for 2026. The project is dual-licensed under Apache 2.0 and MIT, and accepts outside contributions.

Where This Leaves Us

For my own projects, the LLVM backends for Z80 and Sampo remain the right choice—they support the full no_std Rust language and produce optimized native code. But if someone asked me "how do I get started running Rust on my retro hardware this weekend," I'd point them at Eurydice and SDCC. The barrier to entry dropped from "understand GlobalISel" to "install Nix and run two commands."

That's genuine progress. The path from Rust to weird hardware just got shorter.

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—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.