TinyComputers.io (Posts about sampo)

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

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.

Part 3: Building an LLVM Backend for Sampo - Rust Runs on a Custom 16-bit RISC CPU

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

In Part 1, we designed the Sampo 16-bit RISC architecture from scratch. In Part 2, we brought it to life on an FPGA (sort of). Now, in Part 3, we tackle arguably the most ambitious goal of the project: making Rust compile for Sampo.

This isn't just about having a working assembler and emulator. It's about integrating a custom CPU architecture into one of the most sophisticated compiler infrastructures in existence (LLVM) and then building Rust's standard library for a 16-bit target that has never existed before.

The result? A complete toolchain where you can write:

#![no_std]
#![no_main]

extern "C" { fn putc(c: u8); }

#[no_mangle]
pub extern "C" fn _start() {
    unsafe {
        putc(b'H');
        putc(b'i');
        putc(b'!');
    }
    loop {}
}

And it compiles to native Sampo assembly that runs on our emulator:

Sampo Emulator - Loaded 310 bytes
Starting execution at 0x0100

Hi!

CPU halted at 0x0122

This article documents the journey: the architecture of an LLVM backend, the challenges of targeting a 16-bit architecture with modern compiler infrastructure, and how AI-assisted development with Claude Code made this ambitious project achievable.

Why LLVM?

Before diving into implementation details, it's worth asking: why LLVM at all? We already have a working assembler (sasm) written in Rust. Why not just write a simple C compiler that targets that assembler directly?

The answer is leverage. LLVM is used by:

Rust (via rustc)
Clang (C/C++/Objective-C)
Swift
Julia
Zig
And dozens of other languages

By implementing a single LLVM backend, Sampo gains access to all of these languages. More importantly, we get decades of optimization research (constant folding, dead code elimination, loop unrolling, register allocation) for free. A hand-written C compiler would take years to reach the same quality.

The tradeoff is complexity. LLVM is a massive codebase (~30 million lines of C++) with steep learning curves. But with modern AI-assisted development tools, that complexity becomes manageable.

Prior Art: LLVM on the Z80

This isn't our first attempt at bringing LLVM to unconventional hardware. Before Sampo, we tackled an even more constrained target: the Zilog Z80, an 8-bit processor from 1976.

The Z80 project was, in many ways, a proving ground. We learned:

GlobalISel is the right choice for new backends. The older SelectionDAG framework is battle-tested but harder to debug. GlobalISel's modular design made iterative development practical.
Type legalization is where 90% of the work lives. An 8-bit processor running code written for 64-bit assumptions requires extensive transformation rules.
AI-assisted development actually works for compilers. The Z80 backend was our first serious test of using Claude Code for systems programming. The collaboration model we developed there (human direction, AI implementation, iterative refinement) carried directly into Sampo.

The Z80 experience also revealed the limits of targeting truly minimal hardware. With only 64KB of address space, no hardware multiply, and registers measured in single bytes, many Rust abstractions simply couldn't fit. The full write-up documents both the successes and the fundamental constraints we hit.

Sampo, as a 16-bit architecture with hardware multiply/divide and a cleaner register file, sidesteps many of those limitations. The Z80 taught us how to build LLVM backends; Sampo let us build one that actually works well.

The Role of Claude Code

This project would not have been feasible without extensive use of Claude Code, Anthropic's AI-powered coding assistant. I want to be explicit about this: implementing an LLVM backend is traditionally a multi-month effort requiring deep expertise in compiler internals. With Claude Code, the core implementation was completed in intensive sessions over a few days.

Here's how Claude Code contributed:

1. Scaffolding the Backend Structure

LLVM backends follow a specific structure with dozens of interrelated files: SampoTargetMachine.cpp, SampoInstrInfo.td, SampoRegisterInfo.td, SampoCallingConv.td, and many more. Claude Code generated the initial scaffolding based on patterns from existing backends (RISC-V, MSP430, AVR), then systematically customized each file for Sampo's specific requirements.

2. Debugging Cryptic LLVM Errors

LLVM's error messages can be... opaque. Messages like "unable to legalize instruction: G_TRUNC s12 = G_TRUNC s32" or "SmallVector capacity overflow" don't immediately point to solutions. Claude Code could analyze stack traces, cross-reference them with LLVM's source code, and identify the root causes, often obscure interactions between type legalization rules.

3. Iterative Refinement

The development process was highly iterative. We'd attempt to compile a test case, hit an error, fix it, and discover the next issue. Claude Code maintained context across hundreds of these iterations, remembering what had been tried, what worked, and what the current state of each file was.

4. Understanding LLVM Internals

LLVM has two instruction selection frameworks: SelectionDAG (legacy) and GlobalISel (newer, recommended for new backends). Claude Code explained the tradeoffs, recommended GlobalISel for Sampo, and then implemented the required components: SampoLegalizerInfo, SampoRegisterBankInfo, and SampoInstructionSelector.

This isn't to diminish the human element; architectural decisions, design philosophy, and validation all required human judgment. But the mechanical work of writing hundreds of lines of boilerplate C++, TableGen definitions, and CMake configurations was dramatically accelerated.

LLVM Backend Architecture

An LLVM backend transforms LLVM Intermediate Representation (IR) into target-specific machine code. For Sampo, this involves several stages:

Rust Source Code
       ↓
   rustc frontend
       ↓
    LLVM IR
       ↓
  Instruction Selection (GlobalISel)
       ↓
  Register Allocation
       ↓
  Prologue/Epilogue Insertion
       ↓
  MC Layer (Machine Code)
       ↓
  Sampo Assembly (.s file)
       ↓
  sasm Assembler
       ↓
  Binary (.bin file)
       ↓
  semu Emulator

Let's examine the key components we implemented.

File Structure

A complete LLVM backend requires approximately 25-30 files. Here's the structure for Sampo:

llvm/lib/Target/Sampo/
├── CMakeLists.txt
├── Sampo.h
├── Sampo.td                    # Top-level TableGen
├── SampoAsmPrinter.cpp         # Assembly generation
├── SampoCallingConv.td         # Calling convention
├── SampoFrameLowering.cpp      # Stack frame handling
├── SampoFrameLowering.h
├── SampoInstrFormats.td        # Instruction encoding
├── SampoInstrInfo.cpp          # Instruction utilities
├── SampoInstrInfo.h
├── SampoInstrInfo.td           # Instruction definitions
├── SampoISelLowering.cpp       # DAG lowering (minimal)
├── SampoISelLowering.h
├── SampoMCInstLower.cpp        # MachineInstr → MCInst
├── SampoMCInstLower.h
├── SampoRegisterInfo.cpp       # Register handling
├── SampoRegisterInfo.h
├── SampoRegisterInfo.td        # Register definitions
├── SampoSubtarget.cpp          # Target features
├── SampoSubtarget.h
├── SampoTargetMachine.cpp      # Entry point
├── SampoTargetMachine.h
├── GISel/
│   ├── SampoCallLowering.cpp   # GlobalISel calls
│   ├── SampoCallLowering.h
│   ├── SampoInstructionSelector.cpp
│   ├── SampoLegalizerInfo.cpp  # Type legalization
│   ├── SampoLegalizerInfo.h
│   ├── SampoRegisterBankInfo.cpp
│   └── SampoRegisterBankInfo.h
├── MCTargetDesc/
│   ├── SampoAsmBackend.cpp     # Object file generation
│   ├── SampoELFObjectWriter.cpp
│   ├── SampoInstPrinter.cpp    # Assembly printing
│   ├── SampoMCAsmInfo.cpp
│   ├── SampoMCCodeEmitter.cpp
│   └── SampoMCTargetDesc.cpp
└── TargetInfo/
    └── SampoTargetInfo.cpp     # Target registration

Each file has a specific role. The TableGen files (.td) are processed at build time to generate C++ code for instruction encoding, assembly printing, and more. The GISel/ directory contains GlobalISel-specific components; this is where most of the interesting logic lives.

Target Description (TableGen)

LLVM uses TableGen, a domain-specific language, to describe target architectures declaratively. For Sampo, we defined:

Registers (SampoRegisterInfo.td):

def R0  : SampoReg<0,  "R0">;   // Zero register
def R1  : SampoReg<1,  "R1">;   // Return address
def R2  : SampoReg<2,  "R2">;   // Stack pointer
// ... R3-R15

def GPR : RegisterClass<"Sampo", [i16], 16, (sequence "R%u", 0, 15)>;

Instructions (SampoInstrInfo.td):

def ADD : FormatR<0x0, 0x0, (outs GPR:$rd), (ins GPR:$rs1, GPR:$rs2),
                  "ADD\t$rd, $rs1, $rs2",
                  [(set GPR:$rd, (add GPR:$rs1, GPR:$rs2))]>;

def LIX : FormatXNoRs<0x8, (outs GPR:$rd), (ins imm16:$imm),
                      "LIX\t$rd, $imm",
                      [(set GPR:$rd, imm16:$imm)]>;

Calling Convention (SampoCallingConv.td):

def CC_Sampo : CallingConv<[
  // First 4 arguments in R4-R7
  CCIfType<[i16], CCAssignToReg<[R4, R5, R6, R7]>>,
  // Additional arguments on stack
  CCIfType<[i16], CCAssignToStack<2, 2>>
]>;

These declarative definitions generate thousands of lines of C++ code automatically.

GlobalISel: The Modern Instruction Selector

GlobalISel is LLVM's newer instruction selection framework, designed to be more modular and easier to target than the legacy SelectionDAG approach. It works in phases:

IRTranslator: Converts LLVM IR to Generic Machine IR (GMIR)
Legalizer: Transforms illegal operations into legal ones
RegBankSelect: Assigns operands to register banks
InstructionSelect: Maps GMIR to target instructions

For a 16-bit architecture like Sampo, the Legalizer is where most complexity lives. LLVM IR freely uses types like i32, i64, and even i128. Sampo's ALU only operates on 16-bit values. The legalizer must transform these:

// In SampoLegalizerInfo.cpp
getActionDefinitionsBuilder(G_ADD)
    .legalFor({s16})           // i16 add is native
    .clampScalar(0, s16, s16)  // Clamp to 16-bit
    .widenScalarToNextPow2(0); // Widen smaller types

getActionDefinitionsBuilder({G_SDIV, G_UDIV})
    .legalFor({s16})
    .libcallFor({s32, s64})    // Use libcalls for larger types
    .clampScalar(0, s16, s64);

This tells LLVM: "16-bit addition is a single instruction. 32-bit addition needs to be broken into multiple 16-bit operations. 64-bit division should call a library function."

Debugging the Legalizer: A Case Study

One particularly memorable debugging session illustrates the challenges of LLVM development. When first attempting to compile Rust's libcore, the compiler crashed with:

Assertion failed: (idx < size()), function operator[], file SmallVector.h, line 301

This cryptic error (a SmallVector bounds overflow deep in LLVM's internals) gave no indication of what was wrong. The stack trace pointed to SampoInstPrinter::printOperand, which prints assembly operands.

Working with Claude Code, we traced the issue through multiple layers:

The crash occurred when printing a JALR (indirect call) instruction
JALR is defined in TableGen as JALR $rd, $rs1 (two operands)
Our call lowering code was only providing one operand (the target register)
The printer tried to access operand index 1, which didn't exist

The fix was a single line change, adding the return address destination register:

// Before (broken):
MIRBuilder.buildInstr(Sampo::JALR)
    .addReg(Info.Callee.getReg());

// After (fixed):
MIRBuilder.buildInstr(Sampo::JALR)
    .addDef(Sampo::R1)  // Return address destination
    .addReg(Info.Callee.getReg());

This pattern repeated throughout development: an opaque error, careful tracing through LLVM's layers, and ultimately a small fix. Without Claude Code's ability to quickly navigate LLVM's massive codebase and maintain context across debugging sessions, each of these issues could have taken days to resolve.

The 16-bit Challenge: Type Legalization

The most significant technical challenge was handling non-16-bit types. Consider what happens when Rust code uses a u32:

let x: u32 = 0x12345678;
let y: u32 = x + 1;

Sampo has no 32-bit registers. LLVM must:

Split the 32-bit value across two 16-bit registers (R4:R5)
Implement addition with carry propagation
Track both halves through register allocation

The legalizer handles this through "narrowing" actions:

getActionDefinitionsBuilder(G_ADD)
    .legalFor({s16})
    .narrowScalarFor({{s32, s16}},  // Narrow s32 to s16 pairs
                     [](const LegalityQuery &Query) {
                       return std::make_pair(0, LLT::scalar(16));
                     });

We also encountered issues with unusual type sizes. LLVM's intermediate stages sometimes create types like s12 or s24 (12-bit and 24-bit integers). These aren't power-of-two sizes, which caused crashes in the type legalization framework:

LLVM ERROR: unable to legalize instruction: %1:_(s12) = G_TRUNC %0:_(s32)

The fix required careful specification of widening rules:

getActionDefinitionsBuilder(G_TRUNC)
    .widenScalarIf(
        [](const LegalityQuery &Query) {
          unsigned Size = Query.Types[1].getSizeInBits();
          return !llvm::isPowerOf2_32(Size);  // Non-power-of-2?
        },
        [](const LegalityQuery &Query) {
          unsigned Size = Query.Types[1].getSizeInBits();
          unsigned NewSize = llvm::PowerOf2Ceil(Size);
          return std::make_pair(1, LLT::scalar(NewSize));
        })
    .legalIf([](const LegalityQuery &Query) {
      return Query.Types[0].getSizeInBits() <=
             Query.Types[1].getSizeInBits();
    });

This tells LLVM: "If you see a non-power-of-2 type, round it up to the next power of 2 first, then proceed with normal legalization."

Multi-Word Arithmetic

When Rust code uses 32-bit or 64-bit integers, Sampo must synthesize these operations from 16-bit primitives. Consider a simple 32-bit addition:

let a: u32 = 0x12340000;
let b: u32 = 0x00005678;
let c = a + b;  // 0x12345678

This compiles to a sequence that:

Adds the low 16-bit halves
Adds the high 16-bit halves with carry propagation
Manages results across register pairs

The generated assembly looks like:

; R4:R5 = first operand (low:high)
; R6:R7 = second operand (low:high)
ADD   R8, R4, R6      ; Add low halves
LIX   R9, 0           ; Prepare carry
; (carry detection logic)
ADD   R10, R5, R7     ; Add high halves
ADD   R10, R10, R9    ; Add carry
; Result in R8:R10

LLVM's legalizer generates this multi-instruction sequence automatically through "narrowing" rules. We didn't write this expansion manually; we just told LLVM that 32-bit operations should be narrowed to 16-bit pairs.

Function Calling Convention

Getting function calls right was crucial. Sampo uses:

R4-R7: First four arguments (caller-saved)
R1: Return address
R2: Stack pointer
R8-R11: Temporaries (caller-saved)
R12-R15: Saved registers (callee-saved)

The SampoCallLowering.cpp file implements this:

bool SampoCallLowering::lowerCall(MachineIRBuilder &MIRBuilder,
                                   CallLoweringInfo &Info) const {
  // Copy arguments to their designated registers
  static const MCPhysReg ArgRegs[] = {Sampo::R4, Sampo::R5,
                                       Sampo::R6, Sampo::R7};

  for (unsigned i = 0; i < Info.OrigArgs.size(); i++) {
    if (i < 4) {
      MIRBuilder.buildCopy(Register(ArgRegs[i]), Info.OrigArgs[i].Regs[0]);
    } else {
      // Spill to stack
    }
  }

  // Build the call instruction
  if (Info.Callee.isReg()) {
    // Indirect call: JALR R1, Rs  (save return addr to R1, jump to Rs)
    MIRBuilder.buildInstr(Sampo::JALR)
        .addDef(Sampo::R1)
        .addReg(Info.Callee.getReg());
  } else {
    // Direct call: JALX symbol
    MIRBuilder.buildInstr(Sampo::JALX)
        .add(Info.Callee);
  }

  // Mark caller-saved registers as clobbered
  // ... implicit defs for R4-R11
}

One subtle bug took hours to track down: the JALR instruction (indirect call) expects two operands: the destination register for the return address (R1) and the source register containing the jump target. Initially, we only provided one operand, causing a crash deep in the assembly printer when it tried to access the non-existent second operand. The error message was simply "SmallVector capacity overflow," not exactly illuminating without context.

The Assembly Printer Layer

The final stage of code generation converts LLVM's internal machine instructions to textual assembly. This involves two components:

MCInstLower converts MachineInstr (high-level) to MCInst (low-level):

void SampoMCInstLower::Lower(const MachineInstr *MI, MCInst &OutMI) const {
  OutMI.setOpcode(MI->getOpcode());

  for (const MachineOperand &MO : MI->operands()) {
    MCOperand MCOp = LowerOperand(MO);
    if (MCOp.isValid())  // Skip implicit operands
      OutMI.addOperand(MCOp);
  }
}

InstPrinter converts MCInst to assembly text:

void SampoInstPrinter::printOperand(const MCInst *MI, unsigned OpNo,
                                    raw_ostream &O) {
  const MCOperand &Op = MI->getOperand(OpNo);
  if (Op.isReg())
    printRegName(O, Op.getReg());
  else if (Op.isImm())
    O << Op.getImm();
  else if (Op.isExpr())
    MAI.printExpr(O, *Op.getExpr());
}

TableGen generates most of the printer code automatically from instruction definitions. The pattern "ADD\t$rd, $rs1, $rs2" in the TableGen file directly produces the assembly format.

Building Rust's Standard Library

With the LLVM backend working, the next step was teaching Rust about Sampo. This required:

1. Adding the Target Triple

In Rust's rustc_target crate, we added sampo-unknown-none:

// compiler/rustc_target/src/spec/targets/sampo_unknown_none.rs
pub(crate) fn target() -> Target {
    Target {
        data_layout: "e-m:e-p:16:16-i8:8-i16:16-i32:16-n16-S16".into(),
        llvm_target: "sampo-unknown-none".into(),
        pointer_width: 16,
        arch: Arch::Sampo,
        options: TargetOptions {
            panic_strategy: PanicStrategy::Abort,
            atomic_cas: false,
            max_atomic_width: Some(0),
            c_int_width: 16,
            ..Default::default()
        },
    }
}

The data_layout string is critical; it tells LLVM that pointers are 16 bits, alignment requirements, and native integer sizes. Getting this wrong causes subtle miscompilations.

2. Registering the Target in Rust

Rust's build system needs to know about new targets in multiple places:

// compiler/rustc_target/src/spec/mod.rs
supported_targets! {
    // ... existing targets ...
    ("sampo-unknown-none", sampo_unknown_none),
}

// compiler/rustc_span/src/symbol.rs
Symbols {
    // ... existing symbols ...
    sampo,
}

The Arch enum in rustc_target also needed a new variant. These changes propagate through Rust's bootstrap system, eventually producing a compiler that recognizes --target sampo-unknown-none.

3. Building Core Libraries

Rust's #![no_std] programs still need libcore (the dependency-free foundation) and compiler_builtins (intrinsics for operations the hardware doesn't support natively). Building these required:

# Point Rust at our custom LLVM
export LLVM_CONFIG=/path/to/llvm-sampo/build/bin/llvm-config

# Build stage 1 compiler
./x.py build --stage 1

# Build libraries for Sampo
./x.py build --stage 1 library --target sampo-unknown-none

This compiles approximately 50,000 lines of Rust into Sampo assembly, a significant stress test of the backend. The resulting libraries:

libcore: 1.1 MB (Rust's core library)
liballoc: 211 KB (heap allocation)
libcompiler_builtins: 2.3 MB (soft-float, 64-bit arithmetic, etc.)

3. Handling Missing Features

A 16-bit CPU without atomic operations or floating-point hardware needs careful configuration:

atomic_cas: false: No compare-and-swap
max_atomic_width: Some(0): No atomic operations at all
panic_strategy: PanicStrategy::Abort: No unwinding

Rust's type system handles these gracefully. Code that requires atomics simply won't compile for Sampo, with clear error messages.

The Complete Pipeline

Let's trace through what happens when compiling our "Hi!" program:

Stage 1: Rust to LLVM IR

putc(b'H');

Becomes:

call void @putc(i8 zeroext 72)

Stage 2: LLVM IR to Generic Machine IR

%0:gpr = G_CONSTANT i16 72
$r4 = COPY %0
JALX @putc, implicit $r4, implicit-def $r1, ...

Stage 3: Instruction Selection

%0:gpr = LIX 72
$r4 = COPY %0
JALX @putc, ...

Stage 4: Register Allocation

$r4 = LIX 72
JALX @putc

Stage 5: Assembly Output

LIX  R4, 72
JALX putc

Stage 6: Binary

Our sasm assembler produces the final binary, which runs on semu.

The Development Process: Iterating with AI

Traditional compiler development follows a deliberate pace: study the codebase for weeks, implement a small feature, spend days debugging, repeat. With Claude Code, this cycle compressed dramatically.

A typical session looked like:

Describe the goal: "I need to implement call lowering for indirect function calls"
Receive implementation: Claude Code generates SampoCallLowering.cpp with appropriate patterns
Test: Compile a test case, observe failure
Debug together: Share the error, get analysis and fixes
Iterate: Sometimes 10-20 cycles for a single feature

The key insight is that Claude Code doesn't just generate code; it explains why that code is correct (or incorrect). When the call lowering crashed, Claude Code walked through:

How MachineInstrs represent instructions
The difference between explicit and implicit operands
Why the TableGen definition expected two operands
What the MCInstLower layer does with each operand type

This contextual understanding accelerates learning far beyond copy-paste coding.

Code Quality Considerations

AI-generated code requires the same scrutiny as human-written code. During this project, we found:

Things Claude Code did well:

Boilerplate that follows established patterns
TableGen definitions (highly formulaic)
Explaining LLVM concepts and architecture
Debugging from error messages and stack traces

Things requiring human judgment:

Architectural decisions (GlobalISel vs SelectionDAG)
Performance tradeoffs in instruction selection
Edge cases in type legalization
Testing strategy and coverage

The final codebase reflects this collaboration. Claude Code generated perhaps 80% of the initial code, but human review and iteration refined it into something production-quality.

Lessons Learned

1. Start with GlobalISel

For new backends, GlobalISel is significantly easier to work with than SelectionDAG. The modular design means you can implement and test each phase independently.

2. Type Legalization is the Hard Part

For non-standard word sizes (16-bit, 8-bit), most complexity lives in the legalizer. Plan to spend 60%+ of your effort here.

3. Test Early and Often

We maintained a suite of LLVM IR test files that exercised specific features:

; test_call.ll - Function calling
define void @_start() {
  call void @putc(i8 72)  ; 'H'
  ret void
}

Each bug fix was validated against this suite before proceeding.

4. AI-Assisted Development Changes Everything

Traditional LLVM backend development requires months of ramp-up time just to understand the codebase. Claude Code's ability to explain concepts, generate boilerplate, and debug issues compressed this dramatically. The key is knowing what questions to ask and validating the outputs.

5. LLVM's Abstractions Are Worth It

Despite the complexity, LLVM's abstractions pay dividends. Register allocation, instruction scheduling, and numerous optimizations come for free. A hand-written code generator would take years to match this quality.

What's Next

With Rust compiling for Sampo, several exciting possibilities open up:

Operating System Development: Sampo now has enough tooling to write a simple operating system. A minimal kernel with task switching, memory management, and device drivers becomes feasible. Rust's ownership model could make this a particularly safe OS, even on a minimal 16-bit platform.

Language Ports: Since we implemented an LLVM backend (not just Rust support), Clang should work with minimal additional effort. C and C++ for Sampo would enable porting existing retrocomputing software. Imagine CP/M utilities or classic games recompiled for modern Sampo hardware.

Hardware Verification: Running Rust-generated code on the FPGA implementation will provide end-to-end validation of both the hardware and software toolchains. Any discrepancy between the emulator and hardware would become immediately visible.

Educational Materials: A complete, working compiler toolchain for a simple CPU is valuable for teaching. Students can trace code from high-level Rust through every compilation stage to final execution. The relative simplicity of a 16-bit architecture makes the concepts accessible.

Performance Optimization: The current backend generates correct code, but there's room for improvement. Instruction scheduling, better register allocation hints, and peephole optimizations could improve code density and speed.

Conclusion

Building an LLVM backend for a custom CPU is one of those projects that sounds impossible until you're in the middle of it, then sounds impossible again when you hit your third cryptic linker error at 2 AM. But it's achievable, especially with modern AI-assisted development tools.

The Sampo project now spans:

Architecture design: A clean 16-bit RISC with Z80-inspired features
Hardware implementation: Verilog RTL running on an ECP5 FPGA (need to order hardware first!)
Assembler and emulator: Written in Rust, fully functional
LLVM backend: Complete GlobalISel-based code generator
Rust support: libcore, liballoc, and compiler_builtins for sampo-unknown-none

From Finnish mythology, the Sampo was a magical mill that produced endless riches. Our Sampo is more modest; it just produces machine code. But there's something magical about typing cargo build --target sampo-unknown-none and watching a high-level language compile down to instructions for a CPU that didn't exist a few months ago.

The complete source code is available on GitHub:

llvm-sampo - The LLVM backend and Rust target specification
sampo - CPU architecture, assembler, emulator, and FPGA RTL

Whether you're interested in compiler development, CPU design, or just want to see how deep the rabbit hole goes, I hope this series has been illuminating.

Recommended Books

If you're interested in learning more about LLVM, Rust, or computer architecture, these books are excellent resources:

LLVM & Compiler Development

Learn LLVM 17 by Kai Nacke - Comprehensive guide to LLVM internals, including backend development
LLVM Techniques, Tips, and Best Practices by Min-Yih Hsu - Practical patterns for working with LLVM
LLVM Code Generation - Focused coverage of code generation, instruction selection, and register allocation

Rust Programming

The Rust Programming Language, 3rd Edition by Steve Klabnik & Carol Nichols - The definitive Rust guide, updated for 2024
Programming Rust, 2nd Edition by Jim Blandy et al. - Deep dive into Rust's systems programming capabilities

Computer Architecture

Computer Architecture: A Quantitative Approach by Hennessy & Patterson - The classic text on CPU design
Digital Design and Computer Architecture by Harris & Harris - From gates to processors, excellent for CPU design
The RISC-V Reader - Modern RISC architecture principles (many Sampo design decisions were informed by RISC-V)

Source Code

All code is available under open source licenses:

github.com/ajokela/llvm-sampo - LLVM backend (Apache 2.0 + LLVM Exception)
github.com/ajokela/sampo - Assembler, emulator, FPGA RTL

Acknowledgments

This project wouldn't have been possible without the LLVM community's extensive documentation and the examples provided by existing backends. The MSP430, AVR, and RISC-V backends were particularly useful references for handling small word sizes.

Claude Code, developed by Anthropic, was instrumental in navigating LLVM's complexity. While AI-assisted development is sometimes viewed skeptically, this project demonstrates its potential for tackling genuinely difficult engineering challenges. The key is treating AI as a collaborator rather than a replacement; it accelerates the mechanical aspects while humans provide direction and judgment.

This is Part 3 of the Sampo series. Part 1 covers the architecture design, and Part 2 covers the FPGA implementation.

Part 2: Implementing Sampo on the ULX3S FPGA

A.C. Jokela — Mon, 02 Feb 2026 18:00:00 GMT

After designing the Sampo RISC architecture on paper (complete with a working assembler and emulator) it's time to bring it to life in silicon. Or at least, in programmable logic. This post documents the hardware selection and implementation planning for synthesizing Sampo on an FPGA.

The Story So Far

If you haven't read Part 1 of this series, here's the quick version: Sampo is a 16-bit RISC CPU designed to bridge the gap between clean RISC design principles and Z80-friendly features. It has 16 general-purpose registers, ~66 instructions, port-based I/O, block operations (LDIR, LDDR), alternate registers for fast interrupt handling, and hardware multiply/divide.

The project already includes working tools written in Rust:

sasm - A full assembler
semu - An emulator with TUI debugger (step, breakpoints, memory inspection)

And for hardware implementation, we now have two complete RTL implementations:

Amaranth HDL (/rtl/):

cpu.py, alu.py, decode.py, regfile.py, soc.py
Python-based, excellent for rapid iteration
Generates Verilog for synthesis

AI Assisted Hand-written Verilog (/verilog/rtl/):

cpu.v, alu.v, decode.v, regfile.v, shifter.v, uart.v, ram.v, soc.v
Readable, portable, works with any toolchain
Includes testbenches for Icarus Verilog and Verilator

Now it's time to synthesize it to real hardware.

Choosing an FPGA Platform

The FPGA world is split between proprietary toolchains (Xilinx Vivado, Intel Quartus) and the growing open source ecosystem. For a project like Sampo, where understanding every layer of the stack matters, open source tooling is the clear choice.

Open Source FPGA Options

FPGA Family	Capacity	Toolchain	Maturity
Gowin GW1N/GW2A	1K-55K LUTs	Project Apicula	Good
Lattice iCE40	1K-8K LUTs	Project IceStorm	Excellent
Lattice ECP5	12K-85K LUTs	Project Trellis	Excellent
Xilinx 7-series	10K-200K+ LUTs	Project X-Ray (partial)	Experimental

For Sampo, which estimates at ~1,500-2,500 LUTs for the basic CPU, even the smaller FPGAs have more than enough capacity. But if we want room to grow (adding caches, more peripherals, maybe even multi-core experiments) a larger device makes sense.

The ULX3S Board

The ULX3S is an open hardware development board built around the ECP5 FPGA. It's designed by Radiona.org and has become the de facto standard for open source FPGA development.

Specifications

Component	Specification
FPGA	Lattice ECP5 (LFE5U-85F/45F/12F-6BG381C)
LUTs	12K / 44K / 84K (depending on variant)
USB	FTDI FT231XS (500 kbit JTAG, 3 Mbit serial)
GPIO	56 pins (28 differential pairs), PMOD-compatible
RAM	32 MB SDRAM @ 166 MHz
Flash	4-16 MB Quad-SPI
Storage	microSD slot
LEDs	11 total (8 user, 2 USB, 1 WiFi)
Buttons	7 (4 direction, 2 fire, 1 power)
Audio	3.5mm jack (stereo + digital/composite)
Video	GPDI (HDMI-compatible) with level shifter
Display	Header for 0.96" SPI OLED (SSD1331)
Wireless	ESP32-WROOM-32 (WiFi/Bluetooth, standalone JTAG)
ADC	8 channels, 12-bit, 1 MS/s (MAX11125)
Clock	25 MHz onboard, differential input available
Power	3 switching regulators (1.1V, 2.5V, 3.3V)
Sleep	5 µA standby, RTC wake-up with battery backup
Dimensions	94mm × 51mm

Why ULX3S for Sampo

The ULX3S isn't just an FPGA breakout board; it's a complete system:

32MB SDRAM: Real memory, not just block RAM. Essential for running actual programs.
HDMI output: Video terminal without external hardware.
microSD slot: Load programs, implement a filesystem.
ESP32 co-processor: WiFi-based JTAG debugging from any device.
Buttons and LEDs: Instant I/O for testing without wiring anything.
Audio output: Even supports composite video through the audio jack.

Budget Alternative: Tang Nano 9K

Before we dive into the ULX3S, it's worth mentioning a much cheaper option. The Tang Nano 9K (~$15 on AliExpress) uses a Gowin GW1NR-9 FPGA with 8,640 LUTs, more than enough for Sampo:

8,640 LUTs
64Mbit PSRAM (can serve as the full 64KB address space and then some)
HDMI output for a video terminal
USB-C programming
Fully supported by open-source toolchain (Yosys + nextpnr-gowin)

For initial development and testing, the Tang Nano 9K is hard to beat on price. But the ULX3S offers more I/O, more RAM, and a richer peripheral set, making it the better choice for a more complete Sampo system.

LUT Budget Planning

The Sampo RTL implementation is designed to be compact. Here's the resource breakdown:

Component	Estimated LUTs
16 × 16-bit registers	~256 FFs
ALU (16-bit)	200 - 400
Control logic	500 - 1,000
Instruction decode	300 - 500
Sampo CPU core	~1,500 - 2,500
UART (115200 baud)	200 - 300
SPI controller (SD card)	300 - 500
GPIO controller	200 - 400
Basic system	~2,500 - 4,000
SDRAM controller	500 - 1,000
Instruction cache	1,000 - 2,000
Data cache	1,000 - 2,000
Full system	~6,000 - 10,000

These estimates are based on typical RISC CPU implementations. The actual numbers will depend on optimization choices and synthesis settings.

Variant Recommendations

12K LUTs (ULX3S-12F): Plenty for basic Sampo + peripherals, tight for caches.
45K LUTs (ULX3S-45F): Comfortable. Full CPU with cache, room for experiments.
85K LUTs (ULX3S-85F): Luxurious. Multi-core experiments, extensive peripherals.

Toolchain Setup

The ECP5 toolchain is fully open source:

# macOS (Homebrew)
brew install yosys nextpnr-ecp5 ecpprog fujprog

# Ubuntu/Debian
apt install yosys nextpnr-ecp5 ecpprog

# Amaranth HDL (for our existing RTL)
pip install amaranth amaranth-boards

# Or build FPGA tools from source for latest features
git clone https://github.com/YosysHQ/yosys
git clone https://github.com/YosysHQ/nextpnr
git clone https://github.com/YosysHQ/prjtrellis

Tool Roles

Tool	Purpose
Amaranth	Python-based HDL (generates Verilog)
Yosys	Verilog synthesis (RTL → netlist)
nextpnr-ecp5	Place and route (netlist → bitstream)
Project Trellis	ECP5 bitstream documentation
ecpprog/fujprog	Upload bitstream to board

Amaranth Build Flow

Since Sampo's RTL is written in Amaranth, the build flow starts with Python:

# Generate Verilog from Amaranth
cd rtl/
python -m amaranth generate soc.py > sampo.v

# Then synthesize with standard tools
yosys -p "synth_ecp5 -top sampo_soc -json sampo.json" sampo.v
nextpnr-ecp5 --85k --package CABGA381 \
    --lpf ulx3s.lpf --json sampo.json --textcfg sampo.config
ecppack sampo.config sampo.bit

# Program the board
fujprog sampo.bit

Hand-Written Verilog Implementation

In addition to the Amaranth RTL, we now have a complete ai-assisted hand-written Verilog implementation at /verilog/. While Amaranth can generate Verilog, the auto-generated output isn't particularly readable. The hand-written version is designed for clarity and portability:

verilog/
├── rtl/
│   ├── sampo_pkg.vh   # Opcodes, constants, state definitions
│   ├── alu.v          # 16-bit ALU with all operations
│   ├── shifter.v      # Barrel shifter (1/4/8-bit shifts, rotates)
│   ├── regfile.v      # 16 registers + alternate set (EXX)
│   ├── decode.v       # Instruction decoder
│   ├── cpu.v          # FSM-based CPU core (8 states)
│   ├── ram.v          # 64KB synchronous RAM
│   ├── uart.v         # Simple UART for serial I/O
│   └── soc.v          # Top-level SoC integration
├── tb/
│   ├── alu_tb.v       # ALU unit tests
│   ├── regfile_tb.v   # Register file tests
│   └── sampo_tb.v     # Full system testbench
├── programs/
│   └── hello.hex      # Test program in Verilog hex format
├── Makefile           # Build automation
└── bin2hex.py         # Convert sasm output to Verilog $readmemh format

The Verilog implementation uses an 8-state FSM for the CPU: RESET → FETCH → FETCH_EXT → DECODE → EXECUTE → MEMORY → WRITEBACK → HALTED. This makes timing predictable and debugging straightforward.

Simulation with Icarus Verilog

The Verilog implementation includes a complete Makefile for testing:

cd verilog/

# Run the main simulation (hello world)
make test

# Run ALU unit tests
make test-alu

# Run register file tests
make test-regfile

# Build with Verilator (faster simulation)
make verilate

# View waveforms in GTKWave
make wave

Sample output from make test:

=== Sampo CPU Testbench ===
RAM init file: ../programs/hello.hex

CPU started at PC=0x0100
UART output:
----------------------------------------
Hello, Sampo!
----------------------------------------

Simulation complete:
  Final PC:    0x011E
  Cycles:      847
  UART chars:  14
  Status:      HALTED

The Verilog version is portable to any FPGA toolchain (Xilinx, Intel, Lattice, Gowin) without requiring Amaranth or Python in the build chain.

Implementation Roadmap

With both Amaranth and Verilog implementations complete and tested in simulation, the roadmap is now about bringing them up on hardware.

Phase 1: Core Bring-up ✓ (Complete)

✓ Instruction fetch and decode
✓ ALU operations (all 16 operations)
✓ Barrel shifter (1/4/8-bit shifts, rotates, RCL/RCR)
✓ Register file with alternate set (EXX)
✓ FSM-based CPU core (8 states)
✓ RAM interface (64KB)
✓ UART for serial I/O
✓ SoC integration
✓ Testbenches passing (ALU, regfile, full system)
✓ Hello World runs in simulation

Phase 1.5: FPGA Bring-up (Current)

○ ULX3S pin constraints (.lpf file)
○ Clock setup (PLL from 25MHz)
○ Map UART to FTDI
○ LED heartbeat / debug outputs

Phase 2: Memory System

SDRAM controller for 32MB RAM
Instruction cache (optional but helps timing)
Basic interrupt handling

Phase 3: Peripherals

SPI controller for SD card boot
GPIO controller (buttons, LEDs)
Timer/counter module

Phase 4: Advanced Features

Data cache
MMU for memory protection
HDMI text console (VGA timing → GPDI)
ESP32 WiFi integration for wireless debugging

Recommended Tools & Books

Hardware

Tang Nano 9K FPGA - Budget-friendly FPGA board (~$25 on Amazon, ~$15 on AliExpress)
USB Logic Analyzer - Essential for debugging signals (24MHz, 8 channels)

Books

If you're new to Verilog or FPGA development, these are excellent starting points:

Getting Started with FPGAs by Russell Merrick - Beginner-friendly with Verilog and VHDL examples
Programming FPGAs: Getting Started with Verilog by Simon Monk - Practical hands-on guide
Verilog by Example by Blaine Readler - Concise reference for working engineers

Resources

Sampo on GitHub - Full source including assembler, emulator, and RTL
ULX3S GitHub - Schematics, examples, documentation
Project Trellis - ECP5 bitstream documentation
Amaranth HDL - Python-based hardware description
nextpnr - Place and route tool
Yosys - Verilog synthesis

Where to Buy

ULX3S: - AliExpress - ~$100-150 depending on variant - Mouser - Official distribution - CrowdSupply - Original campaign page

Tang Nano 9K (budget alternative): - Amazon - ~$25, faster shipping - AliExpress - ~$15, slower shipping

Next up: Getting our first instructions executing on real hardware. Both the Amaranth and Verilog implementations are ready and tested; Hello World runs in simulation and the testbenches pass. Now it's a matter of pin constraints, clock domains, and debugging the inevitable timing issues.

Sampo: Designing a 16-bit RISC CPU from Scratch - Part 1: Theory and Architecture

A.C. Jokela — Tue, 30 Dec 2025 15:00:00 GMT

In Finnish mythology, the Sampo is a magical artifact from the epic poem Kalevala, compiled by Elias Lönnrot in 1835. According to legend, the Sampo was forged by Ilmarinen, a legendary blacksmith and sky god, from a swan's feather, a grain of barley, a ball of wool, a drop of milk, and a shaft of a distaff. The resulting creation took the form of a magical mill that could produce flour, salt, and gold endlessly, bringing riches and good fortune to its holder.

The exact nature of the Sampo has been debated by scholars since 1818, with over 30 theories proposed, ranging from a world pillar to an astrolabe to a decorated shield. This mystery makes it a fitting namesake for a CPU architecture: something that transforms simple inputs into useful outputs, whose inner workings invite exploration and understanding.

This is the first part of a two-part series exploring the Sampo CPU architecture. In this article, we'll dive deep into the theory, design philosophy, and architectural decisions that shaped Sampo. In Part 2, we'll get our hands dirty with an actual FPGA implementation using Amaranth HDL, bringing this processor to life on real silicon.

The Problem Space: Why Another CPU?

Before diving into Sampo's architecture, it's worth asking: why design a new CPU at all? The retrocomputing community has no shortage of classic processors to explore (the Z80, 6502, 68000) and modern RISC architectures like RISC-V offer clean, well-documented designs for educational purposes.

The answer lies in a specific niche that existing architectures don't quite fill. Consider the typical workloads of classic 8-bit systems: interpreters for languages like BASIC and Forth, operating systems like CP/M, text editors, and simple games. These workloads have distinct characteristics:

Heavy use of memory operations: Block copies, string manipulation, memory fills
Port-based I/O: Serial terminals, disk controllers, sound chips accessed via dedicated I/O instructions
Context switching: Interrupt handlers that need to save and restore register state quickly
BCD arithmetic: Calculator applications, financial software

The Z80 excels at these tasks through specialized instructions (LDIR, LDDR, IN, OUT) and its alternate register set. But the Z80 is an 8-bit CISC processor with irregular encoding, complex addressing modes, and over 300 instruction variants. This makes it challenging to implement efficiently in modern hardware or to target with optimizing compilers.

Modern RISC architectures like RISC-V take the opposite approach: clean, orthogonal instruction sets optimized for pipelining and compiler code generation. But they typically use memory-mapped I/O (no dedicated I/O instructions), lack block operations, and provide no alternate register sets for fast context switching.

Sampo occupies the middle ground, a "Z80 programmer's RISC" that combines the regularity and simplicity of RISC design with the specialized capabilities that made the Z80 so effective for its target workloads.

Design Goals

Sampo was designed with five primary goals:

RISC-inspired instruction set: Clean, orthogonal design with predictable encoding
16-bit native word size: Registers, ALU, and memory addressing all 16-bit
Efficient for interpreters and compilers: Stack operations, indirect addressing, hardware multiply/divide
Simple to implement: Suitable for FPGA synthesis or software emulation
Z80-workload compatible: Port-based I/O, BCD support, block operations, alternate registers

These goals create natural tensions. RISC purity would eliminate block operations and port-based I/O. Maximum Z80 compatibility would preserve its irregular encoding. Sampo resolves these tensions by borrowing selectively from multiple architectural traditions.

Architectural Lineage

Sampo's design draws from four distinct sources, each contributing specific elements:

From RISC-V

RISC-V's influence is most visible in Sampo's register conventions:

Zero register (R0): A register that always reads as zero and ignores writes. This eliminates the need for separate "clear" or "load zero" instructions: ADD R4, R0, R0 clears R4, ADD R4, R5, R0 copies R5 to R4.
Register naming conventions: Return address (RA), stack pointer (SP), global pointer (GP), argument registers (A0-A3), temporaries (T0-T3), and saved registers (S0-S3).
Load/store architecture: Only load and store instructions access memory; all computation occurs between registers.

From MIPS

MIPS contributed Sampo's approach to instruction encoding:

Simple, orthogonal formats: A small number of instruction formats (R, I, S, B, J) with consistent field positions
4-bit primary opcode: Sixteen instruction categories, each with function codes for variants
PC-relative branching: Branch targets specified as signed offsets from the program counter

From ARM Thumb/Thumb-2

ARM's Thumb instruction set inspired Sampo's hybrid encoding strategy:

16-bit base instruction width: Most common operations fit in 16 bits for improved code density
32-bit extended forms: Operations requiring larger immediates use a two-word format
Prefix-based extension: The 0xF opcode prefix indicates a 32-bit instruction, simplifying decode

From the Z80

The Z80 provides Sampo's "personality": the features that make it feel familiar to retrocomputing enthusiasts:

Port-based I/O: IN and OUT instructions with 8-bit port addresses, separate from the memory address space
Alternate register set: The EXX instruction swaps working registers with shadow copies for fast interrupt handling
Block operations: LDIR, LDDR, FILL, and CPIR for efficient memory manipulation
BCD support: The DAA (Decimal Adjust Accumulator) instruction for binary-coded decimal arithmetic
64KB address space: 16-bit addresses, matching the Z80's memory model

The Register File

Sampo provides 16 general-purpose 16-bit registers, organized with RISC-V-style conventions:

Register	Alias	Convention
R0	ZERO	Always reads as 0, writes ignored
R1	RA	Return address (saved by caller)
R2	SP	Stack pointer
R3	GP	Global pointer (optional)
R4-R7	A0-A3	Arguments / Return values
R8-R11	T0-T3	Temporaries (caller-saved)
R12-R15	S0-S3	Saved registers (callee-saved)

The zero register deserves special attention. Having a register that always contains zero eliminates entire classes of instructions found in other architectures:

MOV Rd, Rs becomes ADD Rd, Rs, R0
CLR Rd becomes ADD Rd, R0, R0
NEG Rd, Rs can use R0 as the implicit minuend
CMP Rs, #0 becomes SUB R0, Rs, R0 (result discarded, flags set)

This technique, pioneered by MIPS and refined by RISC-V, dramatically simplifies the instruction set while maintaining expressiveness.

Alternate Registers

Unlike the Z80, which swaps all main registers with EXX, Sampo is selective. Only registers R4-R11 (the arguments and temporaries) have shadow copies. The critical system registers (R0 (zero), R1 (return address), R2 (stack pointer), R3 (global pointer), and R12-R15 (saved registers)) are never swapped.

This design decision serves interrupt handling. When an interrupt occurs, the handler can execute EXX to gain a fresh set of working registers without corrupting the interrupted code's arguments or temporaries. The stack pointer remains valid (no need to establish a new stack), and the return address register can be used to save the interrupted PC.

irq_handler:
    EXX                     ; Swap to alternate R4-R11
    ; ... handle interrupt using R4'-R11' ...
    ; Primary registers preserved automatically
    EXX                     ; Swap back
    RETI                    ; Return from interrupt

The Flags Register

Sampo uses an 8-bit flags register with six defined flags:

Bit	Flag	Name	Description
7	N	Negative	Sign bit of result (bit 15)
6	Z	Zero	Result is zero
5	C	Carry	Unsigned overflow / borrow
4	V	Overflow	Signed overflow
3	H	Half-carry	Carry from bit 3 to 4 (for BCD)
2	I	Interrupt	Interrupt enable

The N, Z, C, and V flags follow standard conventions and support the full range of conditional branches. The H (half-carry) flag exists specifically for the DAA instruction, enabling correct BCD arithmetic. The I flag controls interrupt recognition.

Notably, Sampo provides explicit GETF and SETF instructions to read and write the flags register, unlike many RISC architectures that treat flags as implicit state. This supports context switching and debugging.

Memory Model

Sampo uses a straightforward memory model:

Address space: 64KB (16-bit addresses)
Byte-addressable: Individual bytes can be loaded and stored
Little-endian: Multi-byte values stored with LSB at lower address
Word alignment: 16-bit words should be aligned on even addresses (optional enforcement)

A suggested memory map divides the 64KB space:

0x0000-0x00FF   Interrupt vectors / Reset
0x0100-0x7FFF   Program ROM (~32KB)
0x8000-0xFEFF   RAM (~32KB)
0xFF00-0xFFFF   Memory-mapped I/O (256 bytes)

This layout provides a clean separation between code, data, and I/O while leaving room for customization. The interrupt vector area at the bottom of memory follows Z80 conventions, with the reset vector at 0x0000 and interrupt vector at 0x0004.

Port-Based I/O

In addition to memory, Sampo provides a separate 256-port I/O address space accessed via IN and OUT instructions. This design directly mirrors the Z80 and enables straightforward porting of code that interacts with serial ports, disk controllers, sound chips, and other peripherals.

The I/O instructions come in two forms:

INI  R4, 0x80       ; Read from port 0x80 (immediate port number)
IN   R4, (R5)       ; Read from port specified in R5
OUTI 0x81, R4       ; Write R4 to port 0x81 (immediate)
OUT  (R5), R4       ; Write R4 to port specified in R5

Extended 32-bit forms (INX, OUTX) allow the full 8-bit port range to be specified in immediate form.

Instruction Encoding

Sampo uses a clean, regular encoding scheme with 16-bit base instructions and 32-bit extended forms. The 4-bit primary opcode in bits 15:12 determines the instruction category:

Opcode	Category	Description
0x0	ADD	Register addition
0x1	SUB	Register subtraction
0x2	AND	Bitwise AND
0x3	OR	Bitwise OR
0x4	XOR	Bitwise XOR
0x5	ADDI	Add immediate
0x6	LOAD	Load from memory
0x7	STORE	Store to memory
0x8	BRANCH	Conditional branch
0x9	JUMP	Unconditional jump/call
0xA	SHIFT	Shift and rotate
0xB	MULDIV	Multiply/divide/BCD
0xC	MISC	Stack, block ops, compare
0xD	I/O	Port input/output
0xE	SYSTEM	NOP, HALT, interrupts
0xF	EXTENDED	32-bit instructions

Instruction Formats

Six formats cover all instruction types:

Format R (Register-Register):

15       12 11     8 7      4 3      0
+----------+--------+--------+--------+
|  opcode  |   Rd   |  Rs1   |  Rs2   |
+----------+--------+--------+--------+

Used for three-register operations like ADD R4, R5, R6.

Format I (Immediate):

15       12 11     8 7                0
+----------+--------+------------------+
|  opcode  |   Rd   |      imm8        |
+----------+--------+------------------+

Used for operations with 8-bit immediates like ADDI R4, 42.

Format S (Store):

15       12 11     8 7      4 3      0
+----------+--------+--------+--------+
|  opcode  |  imm4  |  Rs1   |  Rs2   |
+----------+--------+--------+--------+

Used for stores where the destination register field holds an offset.

Format B (Branch):

15       12 11     8 7                0
+----------+--------+------------------+
|  opcode  |  cond  |     offset8      |
+----------+--------+------------------+

Used for conditional branches with PC-relative offsets.

Format J (Jump):

15       12 11                       0
+----------+--------------------------+
|  opcode  |        offset12          |
+----------+--------------------------+

Used for unconditional jumps with 12-bit PC-relative offsets.

Format X (Extended):

Word 0:
15       12 11     8 7      4 3      0
+----------+--------+--------+--------+
|   0xF    |   Rd   |  Rs1   |  sub   |
+----------+--------+--------+--------+

Word 1:
15                                   0
+-------------------------------------+
|              imm16                  |
+-------------------------------------+

Used for operations requiring 16-bit immediates or absolute addresses.

Encoding Examples

To illustrate the encoding scheme, let's examine several instructions:

ADD R4, R5, R6 (R4 = R5 + R6):

Opcode = 0x0, Rd = 4, Rs1 = 5, Rs2 = 6
Binary: 0000 0100 0101 0110 = 0x0456

ADDI R4, 10 (R4 = R4 + 10):

Opcode = 0x5, Rd = 4, imm8 = 10
Binary: 0101 0100 0000 1010 = 0x540A

BEQ +8 (branch forward 8 bytes if equal):

Opcode = 0x8, cond = 0 (BEQ), offset = 4 words
Binary: 1000 0000 0000 0100 = 0x8004

LIX R4, 0x1234 (load 16-bit immediate):

Word 0: 0xF (extended), Rd = 4, Rs = 0, sub = 7 (LIX)
Word 1: 0x1234
Binary: 1111 0100 0000 0111 0001 0010 0011 0100 = 0xF407 0x1234

The regularity of this encoding makes instruction decode straightforward: the first nibble determines the instruction category, and subsequent fields are in consistent positions across formats.

The Instruction Set

Sampo provides approximately 66 distinct instructions, organized into ten categories.

Arithmetic (15 instructions)

The arithmetic category includes standard operations (ADD, SUB, ADDI) plus multiply/divide support:

MUL: 16×16 multiplication, low 16 bits of result
MULH/MULHU: High 16 bits of 32-bit product (signed/unsigned)
DIV/DIVU: Integer division (signed/unsigned)
REM/REMU: Remainder (signed/unsigned)
DAA: Decimal adjust for BCD arithmetic
NEG: Two's complement negation
CMP: Compare (subtract without storing result)

Hardware multiply and divide are essential for interpreter performance; dividing a 32-bit value by 10 for number formatting would be prohibitively slow without hardware support.

Logic (6 instructions)

Standard bitwise operations: AND, OR, XOR, NOT, plus immediate forms ANDI and ORI.

Shift and Rotate (16 variants)

Sampo provides an unusually rich set of shift operations:

SLL/SRL/SRA: Shift left/right logical/arithmetic
ROL/ROR: Rotate left/right
RCL/RCR: Rotate through carry (17-bit rotation)
SWAP: Swap high and low bytes

Each shift type comes in three shift amounts: 1, 4, and 8 bits. The 4-bit shift is particularly useful for hexadecimal digit extraction and insertion. Variable shifts use the extended format with the shift amount in the second register or immediate field.

Load/Store (6 instructions)

Memory access instructions include word and byte loads (with sign or zero extension), word and byte stores, and LUI (Load Upper Immediate) for constructing 16-bit constants:

LUI  R4, 0x12       ; R4 = 0x1200
ORI  R4, R4, 0x34   ; R4 = 0x1234

Branch (16 conditions)

Sampo supports a comprehensive set of branch conditions:

BEQ/BNE: Equal/not equal
BLT/BGE/BGT/BLE: Signed comparisons
BLTU/BGEU/BHI/BLS: Unsigned comparisons
BMI/BPL: Negative/positive
BVS/BVC: Overflow set/clear
BCS/BCC: Carry set/clear

This covers all reasonable comparison outcomes for both signed and unsigned arithmetic.

Jump/Call (4 instructions)

J: PC-relative unconditional jump
JAL: Jump and link (save return address in RA)
JR: Jump to address in register
JALR: Jump and link to register address

Block Operations (6 instructions)

The block operations use a fixed register convention (R4=count, R5=source, R6=destination):

LDI/LDD: Load single byte, increment/decrement pointers and count
LDIR/LDDR: Repeat until count reaches zero
FILL: Fill memory region with value
CPIR: Compare and search forward

These instructions are decidedly un-RISC; they're multi-cycle operations that modify multiple registers. But they're implemented with predictable behavior (always the same registers, always the same algorithm) and provide enormous speedups for common memory operations.

Stack (4 instructions)

PUSH/POP: Single register push/pop
PUSHM/POPM: Push/pop multiple registers (via bitmask)

I/O (4 instructions)

INI/OUTI: Immediate port address
IN/OUT: Register port address

System (9 instructions)

NOP: No operation
HALT: Stop processor
DI/EI: Disable/enable interrupts
EXX: Exchange alternate registers
RETI: Return from interrupt
SWI: Software interrupt
SCF/CCF: Set/complement carry flag
GETF/SETF: Read/write flags register

Comparison with Other Architectures

To put Sampo in context, consider how it compares with related processors:

Aspect	Z80	MIPS	RISC-V	Sampo
Word size	8-bit	32-bit	32/64-bit	16-bit
Instruction width	1-4 bytes	4 bytes	2/4 bytes	2/4 bytes
Registers	8 + alternates	32	32	16 + alternates
Zero register	No	$zero	x0	R0
I/O model	Port-based	Memory-mapped	Memory-mapped	Port-based
Block operations	Yes	No	No	Yes
Instruction count	~300+	~60	~50 base	~66

Sampo sits in an interesting position: more regular than the Z80 but with Z80-friendly features, smaller and simpler than 32-bit RISC but still cleanly orthogonal.

Code Examples

To demonstrate how Sampo assembly looks in practice, here's a "Hello World" program that outputs text via a serial port:

        .org 0x0100

.equ    ACIA_STATUS 0x80
.equ    ACIA_DATA   0x81
.equ    TX_READY    0x02

start:
        LIX  R4, message        ; Load address of string

loop:
        LBU  R5, (R4)           ; Load byte from string
        CMP  R5, R0             ; Compare with zero
        BEQ  done               ; If null terminator, done

wait_tx:
        INI  R6, ACIA_STATUS    ; Read serial status port
        ANDI R6, R6, TX_READY   ; Check transmit ready bit
        BEQ  wait_tx            ; Wait if not ready

        OUTI ACIA_DATA, R5      ; Write character to data port
        ADDI R4, 1              ; Next character
        J    loop
done:
        HALT

message:
        .asciz "Hello, Sampo!\n"

And here's a Fibonacci function demonstrating the calling convention:

; fib(n) - compute nth Fibonacci number
; Input: R4 (A0) = n
; Output: R4 (A0) = fib(n)

fib:
        ADDI R5, R0, 0      ; a = 0
        ADDI R6, R0, 1      ; b = 1
        CMP  R4, R0
        BEQ  fib_done

fib_loop:
        ADD  R7, R5, R6     ; temp = a + b
        ADD  R5, R6, R0     ; a = b
        ADD  R6, R7, R0     ; b = temp
        ADDI R4, R4, -1     ; n--
        BNE  fib_loop

fib_done:
        ADD  R4, R5, R0     ; return a
        JR   RA

The code reads naturally to anyone familiar with RISC assembly, while the I/O instructions and register conventions provide the Z80-like feel that makes porting classic software straightforward.

Looking Ahead: FPGA Implementation

With the architecture defined, the next step is implementation. In Part 2 of this series, we'll build a working Sampo processor using Amaranth HDL, a modern Python-based hardware description language. We'll cover:

The ALU module: Implementing all arithmetic and logic operations
The register file: Including the alternate register set and zero register
The instruction decoder: Parsing the various instruction formats
The control unit: Managing the fetch-decode-execute cycle
The memory interface: Connecting to block RAM
The I/O subsystem: Implementing the port-based I/O model
Integration: Putting it all together into a working system-on-chip

We'll synthesize the design for an affordable FPGA board and run actual Sampo programs, demonstrating that this architecture isn't just a paper exercise but a real, working processor.

The Sampo project on GitHub includes a complete Rust-based assembler (sasm) and emulator (semu) with a TUI debugger, so you can start writing and testing Sampo programs today. The FPGA implementation will let you run those same programs on real hardware, completing the journey from mythological artifact to silicon reality.

Stay tuned for Part 2, where we'll forge our own Sampo, not from swan feathers and barley, but from lookup tables and flip-flops.

TinyComputers.io (Posts about sampo)

Part 4: 132 Tests, Zero Failures - Verifying the Sampo CPU on Real Hardware

The Test Strategy

The Test Framework

Test Coverage

Finding a Real Bug: The Pipeline Hazard

Taking It to the FPGA

The Delay Loop Patch

The Address Shift Bug

The Fix

The Testbench: Trusting but Verifying

Running All Tests on the FPGA

What This Means

Lessons Learned

What's Next

Recommended Resources

Source Code

Three Paths to Rust on Custom Hardware

Path 1: The Full LLVM Backend

Path 2: Rust → C via Eurydice → Existing C Compiler

What Is Eurydice?

Why This Matters for Retro/Custom Hardware

The Real-World Use Case

Limitations

Path 3: Manual no_std with FFI to C

Walkthrough: Rust → C → Z80

Prerequisites

Step 1: Write a Rust Program

Step 2: Extract MIR with Charon

Step 3: Transpile to C with Eurydice

Step 4: Adapt for Bare-Metal Z80

Step 5: Compile with SDCC

What the Z80 Assembly Looks Like

What Just Happened

Comparing the Three Paths

The Elephant in the Room

Where This Leaves Us

Part 3: Building an LLVM Backend for Sampo - Rust Runs on a Custom 16-bit RISC CPU

Why LLVM?

Prior Art: LLVM on the Z80

The Role of Claude Code

1. Scaffolding the Backend Structure

2. Debugging Cryptic LLVM Errors

3. Iterative Refinement

4. Understanding LLVM Internals

LLVM Backend Architecture

File Structure

Target Description (TableGen)

GlobalISel: The Modern Instruction Selector

Debugging the Legalizer: A Case Study

The 16-bit Challenge: Type Legalization

Multi-Word Arithmetic

Function Calling Convention

The Assembly Printer Layer

Building Rust's Standard Library

1. Adding the Target Triple

2. Registering the Target in Rust

3. Building Core Libraries

3. Handling Missing Features

The Complete Pipeline

Stage 1: Rust to LLVM IR

Stage 2: LLVM IR to Generic Machine IR

Stage 3: Instruction Selection

Stage 4: Register Allocation

Stage 5: Assembly Output

Stage 6: Binary

The Development Process: Iterating with AI

Code Quality Considerations

Lessons Learned

1. Start with GlobalISel

2. Type Legalization is the Hard Part

3. Test Early and Often

4. AI-Assisted Development Changes Everything

5. LLVM's Abstractions Are Worth It

What's Next

Conclusion

Recommended Books

LLVM & Compiler Development

Rust Programming

Computer Architecture

Path 3: Manual `no_std` with FFI to C