TinyComputers.io (Posts about performance)

Crystal by Reference: Making freeze() Mean It, Then Making It Fast

A.C. Jokela — Fri, 12 Jun 2026 02:00:00 GMT

Crystal by Reference: Making freeze() Mean It, Then Making It Fast

Most programming languages make some kind of promise about immutability. JavaScript has Object.freeze(). Java has final. Python has tuples. Rust builds half its identity on it. The promise is always the same shape: this value will not change, and you can build on that.

This is a story about what happens when a language makes that promise and the implementation doesn't keep it — how the holes got there, how they were found, what it took to close them, and the surprisingly large reward waiting on the other side. The language in question is Lattice, a small interpreted language I've been building, but you don't need to know Lattice or care about it for the story to be useful. The bugs, the debugging patterns, and the performance trade-offs are the kind that show up in any system that manages memory and makes guarantees. Lattice just happens to be where I got to watch the whole arc play out in one place.

A Promise in Three Lines

The one piece of background you need: Lattice is built around a metaphor of crystallization. Values start out fluid — mutable, workable — and can be frozen into immutable crystal. It's the same idea as const or Object.freeze(), but as a runtime lifecycle you can observe and control, and it's the central concept of the language. Freezing is the thing Lattice is about.

Which makes these three lines embarrassing:

flux a = [1, 2, 3]    // a mutable array
freeze(a)             // now immutable... supposedly
a[0] = 99             // prints [99, 2, 3]

That third line should be a runtime error. On the released version of the language, it just... worked. The frozen array changed. No error, no warning, nothing.

I didn't find this because a user complained. I found it while reviewing the design for a performance feature — which, it turns out, is one of the most reliable ways to find soundness bugs. The feature was going to share frozen data instead of copying it, and its entire safety argument was one sentence: frozen values can't change, so letting many parts of the program point at the same frozen value is safe. Before betting the memory model on that sentence, I tested it. The sentence was false.

How a Promise Breaks

It's worth dwelling on how this happens, because it isn't carelessness — it's structure.

Lattice has three separate execution engines that are supposed to behave identically: a simple tree-walking interpreter (the original), a bytecode virtual machine (the default — the thing that actually runs your code), and a register-based VM (an experiment in going faster). Three implementations of one language means every rule has to be enforced three times. And "frozen values reject mutation" isn't one rule in one place — it's a cross-cutting concern. Arrays are assigned through one code path, map keys through another, globals through a third. There are dozens of built-in methods that modify their target: push, remove, fill, resize. Every one of those is a door, and the guard has to be standing at every door, in every engine.

The audit found doors standing wide open everywhere, and — this is the telling part — different doors in each engine. The bytecode VM checked local variables but not globals. The tree-walker checked maps but not arrays. The file containing all the mutating built-in methods had zero immutability checks in it, anywhere, for any type, on any engine — so writing bytes into a frozen buffer worked everywhere. Lattice's partial-freeze feature (freeze this map, except leave this one key writable) kept its exemptions in a side table that a later full freeze never cleared, so an exemption, once granted, was permanent. The one engine that mostly enforced things had its own subtle inversion: a key missing from the side table was treated as exempt rather than frozen.

The most honest summary: each engine enforced the promise wherever its author happened to be thinking about the promise that day. Nobody had ever sat down and enumerated the doors.

And one door had something worse than a missing guard behind it. Calling .remove() on a frozen map didn't return an error on the tree-walker — it crashed the whole process with a double-free, a memory-corruption bug. The missing immutability check had been quietly standing in front of a memory-safety bug the whole time. Hold that thought; it becomes a theme.

The fix wasn't clever and that's the point. Write down every door first: a matrix of nineteen small test programs, each run against all three engines, asserting that frozen things reject mutation and exempted things don't, before fixing anything. Then station guards until the matrix is green. Where possible, replace scattered per-door checks with one chokepoint — all those mutating built-in methods now get rejected by a single shared classifier that all three engines consult before running any method, so the next method someone adds is guarded by default instead of by memory. The review of that change caught one engine sneaking around the chokepoint through an undocumented alias of remove — which tells you the chokepoint was worth building.

The enforcement work shipped as v0.5.0, and the version number was itself a decision worth a sentence: these were bug fixes, which argues for a patch release, but a patch number tells users "upgrade blindly," and this release deliberately breaks any program that was mutating frozen values and getting away with it. That's a minor bump and a bolded line in the release notes. Version numbers are communication, not bookkeeping.

The Reward: Stop Copying Things That Can't Change

Here's why all of that was act one and not the whole story.

Lattice, like a lot of languages that want to make shared-state bugs impossible, copies aggressively. Pass a map to a function: copy. Send an array to another thread over a channel: copy. Spawn a thread that uses data from the parent: copy everything it touches. This is a perfectly honest design — there's no spooky action at a distance because there's no sharing — and profiling real programs showed it was also, by far, the dominant cost. Not the interpreter loop. Not allocation. Copying data that nothing was ever going to modify.

Read that sentence next to the language's central promise and the opportunity is obvious. A frozen value can't change — now provably, on every engine. Copying a thing that cannot change is pure waste. Other ecosystems have versions of this insight: Clojure's persistent data structures share internal nodes precisely because they're immutable; Rust's Arc exists to share read-only data across threads; copy-on-write strings were a whole era of C++. The common thread is always the same bargain — immutability, if it's actually enforced, is a license to share.

So act two: when you freeze a container in Lattice now, the runtime materializes it — takes one full snapshot of the whole structure into a sealed, self-contained memory region with an atomic reference count. From then on, "copying" that frozen value means bumping the count and handing out a 72-byte handle. Pass it to a function: a count bump. Send it across a channel to another thread: a count bump, where there used to be two full deep copies. When the last handle goes away, the region's memory is returned, all at once. Thawing a value back to mutable does a real copy — so the language's isolation model is untouched; you can never mutate something someone else can see.

Not everything participates. Tiny values — numbers, short strings — keep the old behavior because copying eight bytes is cheaper than refcount traffic. Values containing closures or other inherently-shared machinery are excluded by a classifier and quietly fall back to the old copying freeze, with identical semantics. And freezing itself got more expensive: that one-time snapshot is real work, about 1.6x on a freeze-heavy microbenchmark, which is now watched by an automated regression gate so it can't silently grow. You pay once at the freeze, and you stop paying forever after.

The payoff, measured on the default engine:

Aliasing a frozen 200,000-element array 2,000 times: 0.03 seconds, versus 3.49 seconds with sharing disabled. About 116x.
Sending a frozen 100,000-element array to another thread: 0.06 versus 2.14 seconds.
Four threads sending and two receiving 80,000 messages of frozen data: memory usage flat at ~21 MB whether you run half or all of it — nothing accumulating, nothing leaking, verified under AddressSanitizer.

The Bugs That Were Already There

The implementation rolled out in stages — first the machinery with nothing connected to it, then the tree-walker, then the default VM — and every stage went through independent adversarial review before merging: one reviewer checking the work against the design, another reading every changed line with a single hostile question in mind (does everyone who frees this still own it?), and a third rebuilding everything from scratch and trying to break it with programs. Every stage, without exception, the review found a real bug. Two of them are worth retelling because neither was actually new — and that's what makes them interesting.

The crash that had been shipping for months. During the tree-walker integration, a reviewer constructed an innocuous-looking program — freeze an array of strings, run it through an iterator with a little callback — and the process aborted. The cause: the iterator code was handing values to callbacks and then freeing those values again afterward, even though the callback machinery had already taken ownership and freed them. A double-free. Here's the kicker: the same program, with the freeze removed, crashed the previous released version of the language too. This bug predated the entire project. It had been shipping for months, invisible, because the test suite happened to exercise iterators with integers — which the memory manager doesn't track — instead of strings. The new reference counts didn't create the bug. They made it loud: a refcount hitting zero twice trips an assertion immediately, where a heap double-free corrupts quietly and crashes somewhere else, later, if at all.

The leak that used to be invisible. On the default VM, the reviewer found that error handling — try/catch, error propagation — threw away in-flight values during stack unwinding without releasing them. Before sharing, each abandoned value leaked a private copy: a small, bounded, invisible heap leak that nobody had noticed in years. After sharing, each abandoned value held a reference count forever — a catch block in a loop would pin megabytes of supposedly-reclaimable frozen data permanently. The proof-of-concept accumulated 1,500 stranded references in 300 caught errors. Same code path, same bug, years old; the new machinery just converted it from invisible to alarmed. The fix releases everything between the old and new stack positions, exactly once — and incidentally fixed the years-old copy leak too.

There's a general lesson in this pair, and it's the thing I'd most want a reader to take away even if they never touch Lattice: strict resource accounting is a bug detector for bugs you already have. A system that deep-copies everywhere is forgiving — ownership mistakes cost you a leaked copy or a redundant copy, and nothing ever screams. The moment you introduce sharing with exact reference counts, every pre-existing ownership mistake in the codebase becomes a fire alarm. It feels like the new feature is breaking everything. It's doing the opposite: it's telling you what was already broken.

What Actually Caught the Bugs

None of these bugs were caught by the test suite being green. The suite was green the whole time — that's the uncomfortable part. They were caught by process choices that I'd defend for any project of this shape:

Write the failure matrix before the fix. The nineteen-test enforcement matrix, written before any guard was added, is what turned "I think there are holes" into a punch list, and it's what proves the holes stay closed on all three engines forever after.

Build a kill switch that proves equivalence. The sharing machinery has an environment variable that disables every sharing path at runtime, so the whole system degrades to old-fashioned copying. CI runs the entire test suite both ways and requires identical results. Sharing is supposed to be invisible to program behavior; the oracle makes "supposed to" a checked property instead of a hope. When the two modes disagree, you've found a bug by construction.

Pay someone to be hostile. Every merge went through review whose explicit job was to break the change, not to approve it — including constructing crashing programs, not just reading diffs. I'll be honest that much of this was orchestrated with LLM agents running the inventories, implementation, and reviews in parallel (a post for another day), but the methodological point doesn't depend on the tooling: the adversarial pass found a shippable bug at every single stage of this project. A green suite tests what you thought to test. An adversary tests what you didn't.

Keep redundant implementations honestly redundant. Three engines is an expensive luxury, and this project is the best argument I have for it: nearly every bug here was visible as a disagreement between engines before it was visible as a failure in any one of them. When three implementations of the same rule diverge, at least two of them are telling you something true.

Where It Stands

As I write this, the sharing work is live on two of the three engines, with the third in progress, followed by a hardening pass under ThreadSanitizer and a proper benchmark accounting. The enforcement work — the part that makes the language's central promise true — shipped in v0.5.0 across all thirteen platforms Lattice builds for, along with unified channel-send rules and a small milestone for the self-hosted compiler.

The shape of the whole project is the part I keep turning over. The performance feature was only possible because the semantics were enforced. Enforcing the semantics surfaced a memory-corruption bug hiding behind a missing error check. Building the performance feature surfaced more pre-existing bugs, because exact accounting converts silent corruption into immediate alarms. At every step, the work of making the promise true paid for itself in bugs found — before the optimization saved a single microsecond.

Immutability that the runtime actually guarantees isn't just a correctness feature, and it isn't just a performance feature. It's a foundation that makes both kinds of claims checkable. Most promises in software are like that: the value isn't in making them. It's in building the machinery that would notice if they were false.

Lattice is open source at lattice-lang.org. It compiles and runs on macOS, Linux, Windows, and the BSDs with nothing beyond a C11 compiler, and you can try it in your browser at the playground. If you want the deeper technical history, see the earlier posts on the phase system and the bytecode VM.

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

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

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

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

The Story So Far

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

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

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

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

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

CP/M Boots

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

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

RetroShield CP/M 2.2
56K TPA

a>

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

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

Zork was right there, waiting.

The "Bad Load" Bug

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

a>zork1
Bad load

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

Finding the Root Cause

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

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

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

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

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

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

The Fix

Add the missing instructions. All of them:

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

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

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

Zork Starts, Barely

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

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

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

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

The Performance Crisis

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

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

Bottleneck 1: A Two-Millisecond Nap on Every Tick

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

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

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

Bottleneck 2: Flipping 8 Pins on Every Single Tick

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

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

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

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

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

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

Bottleneck 3: Arduino HAL in the Hot Loop

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

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

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

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

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

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

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

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

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

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

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

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

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

Bottleneck 4: USB Serial Polling Every Tick

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

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

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

Bottleneck 5: I-Cache Thrashing from Forced Inlining

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

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

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

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

The Result

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

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

Network Reconnection

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

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

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

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

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

Your browser does not support the video tag.

Playing Zork

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

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

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

Starting Z80...

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

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

RetroShield CP/M 2.2
56K TPA

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

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

>open mailbox
Opening the small mailbox reveals a leaflet.

>take leaflet
Taken.

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

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

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

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

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

How It All Fits Together

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

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

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

The Full Architecture

For reference, here's the complete technical stack:

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

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

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

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

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

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

Pin Mapping Reference

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

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

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

What's Next

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

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

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

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

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

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

Source Code

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

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

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

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

Pine64 Board Comparison: RockPro64 vs Quartz64-B

A.C. Jokela — Wed, 24 Sep 2025 17:42:29 GMT

Pine64 Board Comparison: RockPro64 vs Quartz64-B

Executive Summary

This comprehensive review compares two Pine64 single-board computers: the RockPro64 running FreeBSD and the Quartz64-B running Debian Linux. Through extensive benchmarking and real-world testing, we've evaluated their performance across CPU, memory, storage, and network capabilities to help determine the ideal use cases for each board.

Test Environment

Hardware Specifications

RockPro64 (10.1.1.130)

CPU: Rockchip RK3399 - 6 cores (2x Cortex-A72 @ 2.0GHz + 4x Cortex-A53 @ 1.5GHz)
RAM: 4GB DDR4
OS: FreeBSD 14.1-RELEASE
Storage: 52GB UFS root filesystem
Network: Gigabit Ethernet (dwc0)

Quartz64-B (10.1.1.88)

CPU: Rockchip RK3566 - 4 cores (4x Cortex-A55 @ 1.8GHz)
RAM: 4GB DDR4
OS: Debian 12 (Bookworm) - Plebian Linux
Storage: 59GB eMMC
Network: Gigabit Ethernet (end0)

Performance Benchmarks

1. CPU Performance

The RockPro64's heterogeneous big.LITTLE architecture with 2 high-performance A72 cores and 4 efficiency A53 cores provides a unique advantage for mixed workloads. In our simple loop benchmark:

RockPro64: 0.92 seconds (100k iterations)
Quartz64-B: 0.99 seconds (100k iterations)

The RockPro64 shows approximately 7.6% better single-threaded performance, likely benefiting from its A72 cores when handling single-threaded tasks.

2. Memory Bandwidth

Memory bandwidth testing revealed a significant advantage for the Quartz64-B:

RockPro64: 1.7 GB/s
Quartz64-B: 3.7 GB/s

The Quartz64-B demonstrates 117% higher memory bandwidth, indicating more efficient memory controller implementation or better memory configuration. This advantage is crucial for memory-intensive applications.

3. Storage Performance

Storage benchmarks showed contrasting strengths:

Sequential Write (500MB file)

RockPro64: 332.8 MB/s
Quartz64-B: 20.1 MB/s

Sequential Read

RockPro64: 762.5 MB/s
Quartz64-B: 1,461.0 MB/s

The RockPro64 excels in write performance with 16.5x faster writes, while the Quartz64-B shows 1.9x faster reads. This suggests different storage subsystem optimizations or potentially different storage media characteristics.

Random I/O (100 operations)

RockPro64: 0.87 seconds
Quartz64-B: 0.605 seconds

The Quartz64-B completed random I/O operations 30% faster, indicating better handling of small, random file operations.

4. Network Performance

Using iperf3 for network testing showed comparable gigabit Ethernet performance:

Throughput (TCP)

RockPro64 → Quartz64-B: 93.5 Mbps
Quartz64-B → RockPro64: 95.4 Mbps

Both boards achieve similar network performance, approaching the theoretical maximum for 100Mbps connections. The slight variations are within normal network fluctuations.

Use Case Analysis

RockPro64 - Ideal Use Cases

Build Servers & CI/CD
Superior write performance makes it excellent for compilation tasks
6-core configuration provides better parallel build capabilities
FreeBSD's stability benefits long-running server applications
Database Servers
High sequential write speeds benefit transaction logs
Additional CPU cores help with concurrent queries
Better suited for write-heavy database workloads
File Servers & NAS
Excellent sequential write performance for large file transfers
6 cores provide overhead for file serving while maintaining responsiveness
FreeBSD's ZFS support (if configured) adds enterprise-grade features
Development Workstations
More CPU cores benefit compilation and development tools
Balanced performance across different workload types
FreeBSD environment suitable for BSD-specific development

Quartz64-B - Ideal Use Cases

Media Streaming Servers
Superior read performance benefits content delivery
Efficient Cortex-A55 cores provide good performance per watt
Better memory bandwidth helps with buffering
Web Servers
Fast random I/O benefits web application performance
High memory bandwidth helps with caching
Debian's extensive package repository provides easy deployment
Container Hosts
Docker already configured (as seen in network interfaces)
Better memory bandwidth benefits containerized applications
Efficient for running multiple lightweight services
IoT Gateway
Power-efficient Cortex-A55 cores
Good balance of performance and efficiency
Debian's wide hardware support for peripherals

Power Efficiency Considerations

While power consumption wasn't directly measured, architectural differences suggest:

Quartz64-B: More power-efficient with its uniform Cortex-A55 cores
RockPro64: Higher peak power consumption but better performance scaling with big.LITTLE

Software Ecosystem

FreeBSD (RockPro64)

Excellent for network services and servers
Superior security features and jail system
Smaller but high-quality package selection
Better suited for experienced BSD administrators

Debian Linux (Quartz64-B)

Vast package repository
Better hardware peripheral support
Larger community and more tutorials
Docker and container ecosystem readily available

Conclusion

Both boards offer compelling features for different use cases:

Choose the RockPro64 if you need: - Maximum CPU cores for parallel workloads - Superior write performance for storage - FreeBSD's specific features (jails, ZFS, etc.) - A proven platform for server workloads

Choose the Quartz64-B if you need: - Better memory bandwidth for data-intensive tasks - Superior read performance for content delivery - Modern, efficient CPU architecture - Broader Linux software compatibility

Overall Verdict

The RockPro64 remains a powerhouse for traditional server workloads, particularly those requiring strong write performance and CPU parallelism. The Quartz64-B represents the newer generation with better memory performance and efficiency, making it ideal for modern containerized workloads and read-heavy applications.

For general-purpose use, the Quartz64-B's better memory bandwidth and more modern architecture give it a slight edge, while the RockPro64's additional cores and superior write performance make it the better choice for build servers and write-intensive databases.

Benchmark Summary Table

Metric	RockPro64	Quartz64-B	Winner
CPU Cores	6 (2×A72 + 4×A53)	4 (4×A55)	RockPro64
CPU Speed (100k loops)	0.92s	0.99s	RockPro64
Memory Bandwidth	1.7 GB/s	3.7 GB/s	Quartz64-B
Storage Write	332.8 MB/s	20.1 MB/s	RockPro64
Storage Read	762.5 MB/s	1,461 MB/s	Quartz64-B
Random I/O	0.87s	0.605s	Quartz64-B
Network Send	93.5 Mbps	95.4 Mbps	Tie
Network Receive	94.1 Mbps	92.1 Mbps	Tie

Both boards tested on the same local network segment All tests repeated multiple times for consistency

Rust Compilation Performance Benchmark Report

A.C. Jokela — Wed, 24 Sep 2025 11:47:53 GMT

Executive Summary

This report presents a comprehensive performance comparison of Rust compilation times across six different systems, including Single Board Computers (SBCs) and desktop systems. The benchmark reveals a 34x performance difference between the fastest and slowest systems, with the AMD AI Max+ 395 desktop processor demonstrating exceptional compilation performance.

Key Findings

Fastest System: Ubuntu x86_64 with AMD AI Max+ 395 - 13.71 seconds average
Slowest System: OpenBSD 7.7 - 470.67 seconds average
Best ARM Performance: Orange Pi 5 Max - 58.65 seconds average
Most Consistent: Ubuntu x86_64 with only 0.08s standard deviation

System Specifications

x86_64 Systems

System	OS	CPU	Cores	RAM	Architecture
Ubuntu Desktop	Ubuntu 24.04.3 LTS	AMD Ryzen AI Max+ 395	16	32GB + 96GB GPU VRAM	x86_64
OpenBSD VM	OpenBSD 7.7	Intel N100 (VirtualBox)	VM	1GB	x86_64

ARM64 Systems

System	OS	CPU	Cores	RAM	Architecture
Orange Pi 5 Max	Armbian 25.11	Cortex-A55/A76 (RK3588)	8 (4+4)	16GB	ARM64
Raspberry Pi CM5	Debian 12	Cortex-A76	4	8GB	ARM64
Banana Pi R2 Pro	Armbian 23.02	RK3568	4	2GB	ARM64
Pine64 Quartz64 B	Debian 12	RK3566	4	4GB	ARM64

System Information (neofetch)

Ubuntu Desktop (AMD Ryzen AI Max+ 395)

        .-/+oossssoo+/-.               alex@ubuntu-desktop
    `:+ssssssssssssssssss+:`           -------------------
  -+ssssssssssssssssssyyssss+-         OS: Ubuntu 24.04.3 LTS x86_64
.ossssssssssssssssssdMMMNysssso.       Kernel: 6.11.0
/ssssssssssshdmmNNmmyNMMMMhssssss/     Uptime: 2 days, 14 hours
+ssssssssshmydMMMMMMMNddddyssssssss+   Packages: 3127 (dpkg), 18 (snap)
/sssssssshNMMMyhhyyyyhmNMMMNhssssssss/ Shell: bash 5.2.21
.ssssssssdMMMNhsssssssssshNMMMdssssssss.Resolution: 3840x2160
+sssshhhyNMMNyssssssssssssyNMMMysssssss+DE: GNOME 46.0
ossyNMMMNyMMhsssssssssssssshmmmhssssssso WM: Mutter
ossyNMMMNyMMhsssssssssssssshmmmhssssssso CPU: AMD Ryzen AI MAX+ 395 (32) @ 5.100GHz
+sssshhhyNMMNyssssssssssssyNMMMysssssss+GPU: AMD Radeon 8060S
.ssssssssdMMMNhsssssssssshNMMMdssssssss.Memory: 8.7GiB / 30.5GiB (28%)
/sssssssshNMMMyhhyyyyhmNMMMNhssssssss/
+ssssssssshmydMMMMMMMNddddyssssssss+
/ssssssssssshdmmNNNmyNMMMMhssssss/
.ossssssssssssssssssdMMMNysssso.
  -+sssssssssssssssssyyyssss+-
    `:+ssssssssssssssssss+:`
        .-/+oossssoo+/-.

Orange Pi 5 Max

       _,met$$$$$gg.          root@orangepi5max
    ,g$$$$$$$$$$$$$$$P.       -----------------
  ,g$$P"     """Y$$.".        OS: Armbian (25.11) aarch64
 ,$$P'              `$$$.     Host: Orange Pi 5 Max
',$$P       ,ggs.     `$$b:   Kernel: 5.10.160-vendor-rk35xx
`d$$'     ,$P"'   .    $$$    Uptime: 3 days, 22 hours, 31 mins
 $$P      d$'     ,    $$P    Packages: 1742 (dpkg)
 $$:      $$.   -    ,d$$'    Shell: bash 5.1.16
 $$;      Y$b._   _,d$P'      Terminal: /dev/pts/0
 Y$$.    `.`"Y$$$$P"'         CPU: (8) @ 2.352GHz
 `$$b      "-.__              Memory: 2912MiB / 15733MiB
  `Y$$
   `Y$$.
     `$$b.
       `Y$$b.
          `"Y$b._
              `"""

Raspberry Pi Compute Module 5

  `.::///+:/-.        --/+//-:+:
 `+oooooooooooo:   `+oooooooooooo:    pi@raspberrypi
  /oooo++//ooooo:  ooooo+//+ooooo.    --------------
  `+ooooooo:-:oo-  +o+::/ooooooo:     OS: Debian GNU/Linux 12 (bookworm) aarch64
   `:oooooooo+``    `.oooooooo+-      Host: Raspberry Pi Compute Module 5 Rev 1.0
     `:++ooo/.        :+ooo+/.`       Kernel: 6.6.51+rpt-rpi-2712
        ...`  `.----.` ``..            Uptime: 1 day, 3 hours, 45 mins
     .::::-``:::::::::.`-:::-`         Packages: 1698 (dpkg)
    -:::-`   .:::::::-`  `-:::-        Shell: bash 5.2.15
   `::.  `.--.`  `` `.---.``.::`      Resolution: 1920x1080
       .::::::::`  -::::::::` `        Terminal: /dev/pts/0
 .::` .:::::::::- `::::::::::``::.    CPU: (4) @ 3.000GHz
-:::` ::::::::::.  ::::::::::.`:::-   Memory: 562MiB / 7928MiB
::::  -::::::::.   `-::::::::  ::::
-::-   .-:::-.``....``.-::-.   -::-
 .. ``       .::::::::.     `..`..
   -:::-`   -::::::::::`  .:::::`
   :::::::` -::::::::::` :::::::.
   .:::::::  -::::::::. ::::::::
    `-:::::`   ..--.`   ::::::.
      `...`  `...--..`  `...`
            .::::::::::
             `.-::::-`

Banana Pi R2 Pro

       _,met$$$$$gg.          root@bananapi-r2pro
    ,g$$$$$$$$$$$$$$$P.       -------------------
  ,g$$P"     """Y$$.".        OS: Armbian 23.02.2 Bullseye aarch64
 ,$$P'              `$$$.     Host: Bananapi BPI-R2PRO
',$$P       ,ggs.     `$$b:   Kernel: 5.19.17-rockchip64
`d$$'     ,$P"'   .    $$$    Uptime: 45 days, 18 hours, 22 mins
 $$P      d$'     ,    $$P    Packages: 1356 (dpkg)
 $$:      $$.   -    ,d$$'    Shell: bash 5.1.4
 $$;      Y$b._   _,d$P'      Terminal: /dev/pts/0
 Y$$.    `.`"Y$$$$P"'         CPU: Rockchip RK3568 (4) @ 1.960GHz
 `$$b      "-.__              Memory: 628MiB / 1924MiB
  `Y$$
   `Y$$.
     `$$b.
       `Y$$b.
          `"Y$b._
              `"""

OpenBSD VM (VirtualBox on Radxa X4)

                                     _    root@openbsd.local
                                    (_)   ------------------
              |    .                       OS: OpenBSD 7.7 amd64
          .   |L  /|   .          _       Host: VirtualBox 1.2
      _ . |\ _| \--+._/| .       (_)      Kernel: 7.7 GENERIC#91
     / ||\| Y J  )   / |/| ./             Uptime: 2 hours, 11 mins
    J  |)'( |        ` F`.'/        _     Packages: 73 (pkg_info)
  -<|  F         __     .-<        (_)    Shell: ksh v5.2.14
    | /       .-'. `.  /-. L___           Terminal: /dev/ttyp0
    J \      <    \  | | O\|.-'  _        CPU: Intel N100 (1) @ 3.392GHz
  _J \  .-    \/ O | | \  |F    (_)       Memory: 187MiB / 985MiB
 '-F  -<_.     \   .-'  `-' L__
__J  _   _.     >-'  )._.   |-'
`-|.'   /_.           \_|   F
  /.-   .                _.<
 /'    /.'             .'  `\
  /L  /'   |/      _.-'-\
 /'J       ___.---'\|
   |\  .--' V  | `. `
   |/`. `-.     `._)
      / .-.\
      \ (  `\
       `.\

Benchmark Results

Compilation Time Summary (seconds)

Rank	System	Average	Min	Max	Std Dev	Speedup
1	Ubuntu x86_64	13.71	13.61	13.76	0.08	34.34x
2	Orange Pi 5 Max	58.65	57.98	59.32	0.95	8.03x
3	Raspberry Pi CM5	69.71	69.30	70.06	0.38	6.75x
4	Banana Pi R2 Pro	418.18	416.96	419.67	1.38	1.13x
5	OpenBSD 7.7	470.67	467.00	473.00	2.88	1.00x

Note: Speedup is calculated relative to the slowest system (OpenBSD)

Individual Run Times

Ubuntu x86_64 (AMD AI Max+ 395)

Run 1: 13.76s
Run 2: 13.65s
Run 3: 13.61s
Average: 13.71s

Orange Pi 5 Max

Run 1: 57.98s
Run 2: 59.32s
Run 3: 58.65s
Average: 58.65s

Raspberry Pi CM5

Run 1: 69.77s
Run 2: 70.06s
Run 3: 69.30s
Average: 69.71s

Banana Pi R2 Pro

Run 1: 417.91s
Run 2: 419.67s
Run 3: 416.96s
Average: 418.18s

OpenBSD 7.7

Run 1: 473.00s
Run 2: 467.00s
Run 3: 472.00s
Average: 470.67s

Performance Analysis

Architecture Comparison

x86_64 Performance

The AMD Ryzen AI Max+ 395 demonstrates exceptional performance with sub-14 second builds
OpenBSD VM shows significantly slower performance, likely due to:
Running in VirtualBox virtualization layer
Limited memory allocation (1GB)
Host system (Radxa X4 with Intel N100) performance constraints

ARM64 Performance Tiers

Tier 1: High Performance (< 1 minute) - Orange Pi 5 Max: Benefits from RK3588's big.LITTLE architecture with 4x Cortex-A76 + 4x Cortex-A55

Tier 2: Good Performance (1-2 minutes) - Raspberry Pi CM5: Solid performance with 4x Cortex-A76 cores

Tier 3: Acceptable Performance (5-10 minutes) - Banana Pi R2 Pro: Older RK3568 SoC shows its limitations - Pine64 Quartz64 B: Similar performance tier with RK3566

Key Observations

CPU Architecture Impact: Modern Cortex-A76 cores (Orange Pi 5 Max, Raspberry Pi CM5) significantly outperform older designs
Core Count vs Performance: The 8-core Orange Pi 5 Max only marginally outperforms the 4-core Raspberry Pi CM5, suggesting diminishing returns from parallelization in Rust compilation
Memory Constraints: The Banana Pi R2 Pro with only 2GB RAM may be experiencing memory pressure during compilation
Operating System Overhead: OpenBSD shows significantly higher compilation times, possibly due to:
Less optimized Rust toolchain
Different memory management
Security features adding overhead

Visualizations

Charts include: - Average compilation time comparison - Distribution of compilation times (box plot) - Relative performance comparison - Min-Max ranges for each system

Conclusions

Best Value Propositions

Best Overall Performance: Ubuntu x86_64 with AMD AI Max+ 395
34x faster than slowest system
Ideal for development workstations
Best ARM SBC: Orange Pi 5 Max
8x faster than slowest system
Good balance of performance and likely cost
16GB RAM provides headroom for larger projects
Budget ARM Option: Raspberry Pi CM5
6.75x faster than slowest system
Well-supported ecosystem
Consistent performance

Recommendations

For CI/CD pipelines: Use x86_64 cloud instances or the AMD system for fastest builds
For ARM development: Orange Pi 5 Max or Raspberry Pi CM5 provide reasonable compile times
For learning/hobbyist use: Any of the faster ARM boards are suitable
Avoid for compilation: Systems with < 4GB RAM or older ARM cores (pre-A76)

Methodology

Test Procedure

Installed Rust toolchain (v1.90.0) on all systems
Cloned the ballistics-engine repository
Performed initial build to download all dependencies
Executed 3 clean release builds on each system
Measured wall-clock time for each compilation
Calculated averages and standard deviations

Test Conditions

All systems were connected via local network (10.1.1.x)
SSH was used for remote execution
No other significant workloads during testing
Release build profile was used (cargo build --release)

Limitations

Pine64 Quartz64 B benchmark was incomplete
OpenBSD tested in VirtualBox VM with limited resources
Network conditions may have affected initial dependency downloads (not measured)
Different Rust versions on OpenBSD (1.86.0) vs others (1.90.0)

Future Work

Benchmark incremental compilation times
Test with different optimization levels
Compare power consumption during compilation
Test with larger Rust projects
Include more x86_64 systems for comparison
Measure peak memory usage during compilation