TinyComputers.io (Posts about Retrocomputing, Compilers)

SectorZ: A C Compiler in 733 Bytes of Z80 Assembly

A.C. Jokela — Sun, 08 Feb 2026 02:00:00 GMT

A friend recently brought to my attention a project called SectorC and it demonstrated something remarkable: a C compiler that fits in a 512-byte x86-16 boot sector. It compiles a substantial subset of C (variables, functions, if/while, 14 binary operators, pointer dereference, inline assembly) in less space than most error messages.

I wanted to see if the same idea could work on the Z80.

The Z80 is a fundamentally different machine from x86-16. It has no memory-to-memory move instructions, no string operations like stosw, no segment registers that double as a free 64K hash table. It's an 8-bit processor pretending to be 16-bit through register pairs. Every operation that x86 does in one instruction tends to take two or three on Z80. So the question wasn't whether a Z80 version would be bigger (it obviously would) but whether it could stay small enough to be interesting.

The answer is 733 bytes.

What It Compiles

SectorZ implements the same "Barely C" language as SectorC. All tokens must be separated by spaces, which eliminates the need for a real tokenizer. You write C, but with mandatory whitespace:

int c ;
int x ;

void putch ( ) {
  asm ( 58 98 209 ) ;
  asm ( 211 129 ) ;
}

void main ( ) {
  x = 72 ;
  c = x ;
  putch ( ) ;
}

The supported feature set:

Global variable declarations (int name ;)
Function definitions (void name ( ) { ... })
Assignment (x = expr ;)
Function calls (func ( ) ;)
If statements (if ( expr ) { ... })
While loops (while ( expr ) { ... })
14 binary operators: + - * & | ^ << >> == != < > <= >=
Pointer dereference for read (* expr) and write (* expr = expr ;)
Address-of operator (& var)
Inline machine code (asm ( byte byte ... ) ;)
Parenthesized subexpressions

No function arguments, no local variables, no return values, no preprocessor, no error checking. The programmer is trusted completely, in the grand tradition of 1970s C.

The Architecture Tax

SectorC fits in 512 bytes partly because x86-16 is dense. The stosw instruction stores AX to [ES:DI] and increments DI, all in a single byte. On the Z80, the equivalent operation (store a 16-bit value and advance the pointer) takes three bytes at minimum. SectorC uses segment registers to create a free 64K lookup table for variable and function hashing. The Z80 has no segments.

This is the fundamental challenge: the Z80 instruction set is more orthogonal and regular than x86, but it pays for that regularity with verbosity. A simple "emit a 3-byte instruction" helper that writes an opcode and a 16-bit address costs 7 bytes. SectorC does the same thing with stosw and a single mov, effectively 4 bytes.

The result is that SectorZ is larger than its x86 counterpart. But 733 bytes for a self-contained C compiler on an 8-bit processor from 1976 still feels pretty good.

Memory Layout

The compiler loads at address $0000 and uses the upper portion of the Z80's 64K address space for its data structures:

Address	Size	Purpose
`$0000`	733 bytes	Compiler code
`$D000`	256 bytes	Function trampoline table (64 entries x 4 bytes)
`$D100`	256 bytes	Variable storage (128 entries x 2 bytes)
`$D200`	3 bytes	Tokenizer state (semicolon buffer, number flag, EOF flag)
`$D300+`	~11.5K	Generated code output

The compiler reads source code character by character from the MC6850 ACIA serial port, compiles it to Z80 machine code starting at $D300, and then calls main() through the trampoline table. The entire process (read, compile, execute) happens without ever touching a disk.

Key Design Decisions

HL as the Code Pointer

The most important register allocation decision in the whole compiler is using HL as the output pointer. Z80's LD (HL), n instruction stores an immediate byte to the address in HL in just 2 bytes. The alternative, using DE with LD A, n / LD (DE), A, costs 3 bytes per emit site. Since the compiler emits bytes constantly, this saves roughly 25 bytes across all the emit sequences. It does mean HL is permanently occupied, so the tokenizer has to push/pop HL around every call, but the trade-off is clearly worth it.

The `atoi` Hash Trick

This is borrowed directly from SectorC, and it's the single cleverest idea in the whole design. The tokenizer hashes every identifier using the same algorithm as atoi: hash = hash * 10 + char. For numeric tokens, it subtracts '0' from each character first, so the hash is the actual integer value. For identifiers, the raw ASCII values are accumulated.

The key insight is that the hash doubles as a lookup key. Variable names hash to 16-bit values; the low byte (masked to even alignment) indexes into the variable table at $D100. Function names hash similarly, with the low byte (masked to 4-byte alignment) indexing into the trampoline table at $D000. Keywords like if, while, and void hash to fixed values that the compiler checks directly.

No symbol table. No string comparison. Just arithmetic.

The `cp_de_imm` Trick

Comparing a 16-bit register pair against a constant is expensive on Z80. The naive approach (LD A, E / CP low / JR NZ, skip / LD A, D / CP high) costs 7 bytes, and the compiler does this check constantly (for every keyword and punctuation token). SectorZ uses an inline-constant trick instead:

cp_de_imm:
    ex   (sp), hl       ; Swap HL with return address on stack
    ld   a, (hl)        ; Load low byte of constant
    inc  hl
    cp   e              ; Compare with E
    jr   nz, cp_de_ne
    ld   a, (hl)        ; Load high byte of constant
    cp   d              ; Compare with D
cp_de_ne:
    inc  hl             ; Skip past constant regardless
    ex   (sp), hl       ; Restore HL, fix return address
    ret

The 16-bit constant is embedded directly after the CALL, as a DW:

    call  cp_de_imm
    dw    tok_if        ; The constant to compare against
    jr    z, do_if      ; Branch if DE == tok_if

The function reads the constant from the return address, advances the return address past it, and restores everything. Each comparison site costs just 5 bytes (3 for the call, 2 for the constant) instead of 7. With 15+ comparison sites in the compiler, this saves around 30 bytes.

The EX (SP), HL instruction is the hero here. It atomically swaps HL with the top of the stack, which is exactly what we need: get the return address into HL for reading, then put the updated address back. This instruction doesn't exist on x86 (SectorC uses lodsw with a different approach), and it's one of the few places where Z80 is genuinely more elegant.

Runtime Helpers for Binary Operations

SectorC generates inline code for binary operators. The x86 ADD AX, BX is just 2 bytes, so inlining is cheap. On Z80, a 16-bit add is ADD HL, DE (1 byte), but subtraction requires OR A / SBC HL, DE (3 bytes), and multiplication doesn't exist as a single instruction at all.

SectorZ moves all binary operations into runtime helper functions. The generated code for any binary expression follows the same pattern: push left operand, evaluate right operand, pop left into DE, swap, call helper. This costs 6 bytes per operator use in the generated code (1 push + 1 pop + 1 ex + 3 call), but the compiler only needs to emit a uniform sequence, which keeps the compiler itself small.

The 14 runtime helpers add 109 bytes to the compiler. The shift and comparison helpers alone would be prohibitively large to inline (the multiply routine is 25 bytes). By centralizing them, the compiler trades generated code density for compiler code density, which is the right call when you're trying to minimize the compiler.

Function Trampolines

Functions are called through a trampoline table at $D000. When the compiler encounters a function definition, it writes a 3-byte JP actual_address instruction into the trampoline slot. When generated code calls a function, it calls the trampoline, which jumps to the real code.

This eliminates forward-reference problems entirely. Functions can be called before they're defined (as long as the caller executes after the definition has been compiled). The trampoline table has 64 entries, which means the low 8 bits of a function name's hash, masked to 4-byte alignment, must be unique across all functions in a program. For typical small programs, this works fine.

The Semicolon Hack

One of the trickier parsing problems in Barely C is the semicolon. Consider x = 3 + 4 ;. The expression parser reads tokens until it hits something that isn't an operator. When it reads ;, it doesn't match any operator, so it returns. But it has already consumed the semicolon. The statement parser needs that semicolon to know the statement is complete.

SectorC's solution, which SectorZ copies, is a one-character pushback buffer. The tokenizer treats semicolons specially: if it encounters a ; while accumulating a token, it saves a flag and returns the current token. The next call to tok_next checks the flag first and returns a synthetic semicolon token without reading any input.

This is 15 bytes of code that prevents the need for a much more complex token lookahead mechanism.

A Real Program: Prime Sieve

Hello World with asm() blocks is a legitimate test, but it doesn't really exercise the compiler. Here's a Sieve of Eratosthenes that finds all primes below 100:

int c ;
int x ;
int d ;
int i ;
int j ;
int p ;
int n ;
int s ;
int f ;

void putch ( ) {
  asm ( 58 98 209 ) ;
  asm ( 211 129 ) ;
}

void printnum ( ) {
  f = 0 ;
  d = 0 ;
  while ( x >= 100 ) {
    x = x - 100 ;
    d = d + 1 ;
  }
  if ( d ) {
    c = d + 48 ;
    putch ( ) ;
    f = 1 ;
  }
  d = 0 ;
  while ( x >= 10 ) {
    x = x - 10 ;
    d = d + 1 ;
  }
  if ( d + f ) {
    c = d + 48 ;
    putch ( ) ;
  }
  c = x + 48 ;
  putch ( ) ;
}

void main ( ) {
  s = 57344 ;
  n = 100 ;
  i = 2 ;
  while ( i < n ) {
    * ( s + i + i ) = 1 ;
    i = i + 1 ;
  }
  p = 2 ;
  while ( p * p < n ) {
    if ( * ( s + p + p ) ) {
      j = p + p ;
      while ( j < n ) {
        * ( s + j + j ) = 0 ;
        j = j + p ;
      }
    }
    p = p + 1 ;
  }
  i = 2 ;
  while ( i < n ) {
    if ( * ( s + i + i ) ) {
      x = i ;
      printnum ( ) ;
      c = 32 ;
      putch ( ) ;
    }
    i = i + 1 ;
  }
  c = 10 ;
  putch ( ) ;
}

This program demonstrates several things that aren't obvious from the language description.

Pointer arithmetic as arrays. Barely C has no array type, but * ( s + i + i ) reads a 16-bit value from address s + 2*i, effectively treating a block of memory as an integer array. The sieve stores its flags at address 57344 ($E000), well above both the compiler and the generated code.

Decimal output without division. The language has no division or modulo operators, so printnum extracts digits via repeated subtraction. The f flag tracks whether a hundreds digit was printed, ensuring proper formatting of numbers like 2 (just "2") vs 103 ("103", not "13").

The putch function. This is the I/O bridge between Barely C and the hardware. The asm statement emits raw Z80 opcodes: 58 98 209 is LD A, ($D162) (load the low byte of variable c), and 211 129 is OUT ($81), A (send it to the ACIA serial port). The programmer has to compute the variable's memory address from its hash (c hashes to 99, masked to even alignment gives 98, at offset $D162), which is admittedly inconvenient but functional.

Running it through the emulator:

$ (cat primes.bc; printf '\x1a') | retroshield sectorz.bin
2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 89 97

All 25 primes below 100, computed and printed by 733 bytes of compiler generating Z80 machine code on the fly.

Size Breakdown

Where do the 733 bytes go?

Component	Bytes	%
Entry point	13	1.8%
Top-level parser (`compile`)	60	8.2%
Statement dispatch (`compile_stmts`)	51	7.0%
Assignment and calls	30	4.1%
`asm` statement	23	3.1%
Control flow (`if`, `while`)	63	8.6%
Deref assign	27	3.7%
Expression parser	59	8.0%
Unary expressions	73	10.0%
Helpers (`emit_var`, `emit3`, `func_addr`, `emit_test`)	32	4.4%
`cp_de_imm`	11	1.5%
Tokenizer	98	13.4%
`getch` (serial I/O)	26	3.5%
Operator table	58	7.9%
Runtime helpers	109	14.9%

The runtime helpers are the largest single component at 15% of the binary. The multiply routine alone is 25 bytes. If the Z80 had a hardware multiply instruction, the compiler would be noticeably smaller. The tokenizer at 13% is the next largest piece, driven primarily by the multiply-by-10 hash accumulation loop, which requires several register shuffles because the Z80 has no 16-bit multiply.

The operator table is pure data: 14 entries of 4 bytes each (token hash + helper address) plus a 2-byte sentinel. It's an unavoidable cost of supporting 14 operators, but the table-driven approach keeps the expression parser compact at 59 bytes.

SectorC vs. SectorZ

	SectorC (x86-16)	SectorZ (Z80)
Size	512 bytes	733 bytes
Target	x86-16 real mode	Z80 bare metal
I/O	VGA memory, INT 16h	MC6850 ACIA serial
Variables	64K segment	256-byte table
Functions	Direct call	JP trampoline table
Binary ops	Inline generated code	CALL to runtime helpers
Code emit	`stosw` (1 byte)	`LD (HL),n / INC HL` (3 bytes)
Token compare	`lodsw / cmp`	`EX (SP),HL` inline trick

The 221-byte difference comes down to instruction set density. The x86 has a rich CISC heritage (string instructions, memory-to-register operations, implicit operand encoding) that makes tiny programs disproportionately easy. The Z80 is capable but verbose. Every extra byte in the instruction encoding cascades across every emit site, every comparison, every helper function.

That said, the Z80 has a few tricks of its own. EX (SP), HL is a single-byte instruction that enables the inline constant comparison technique. The ADD HL, DE instruction does 16-bit addition in one byte. And EX DE, HL swaps two register pairs in one byte, which is essential for getting operands into the right positions cheaply.

Running It

SectorZ runs on the retro-z80-emulator, a Rust-based Z80 emulator that connects stdin/stdout to an emulated MC6850 ACIA serial port. It also runs on real hardware via the RetroShield Z80. The compiler loads at address $0000, reads source from serial, compiles and executes.

$ z80asm -o sectorz.bin sectorz.asm
$ (cat examples/primes.bc; printf '\x1a') | retroshield sectorz.bin

The \x1a (Ctrl-Z) at the end signals EOF to the compiler. The emulator's serial implementation silently drops null bytes, so the traditional CP/M EOF marker of $00 doesn't work. A minor debugging adventure that reinforced the value of reading the emulator source code before assuming how it handles edge cases.

What's Missing

Quite a lot, obviously. No function arguments means all communication happens through global variables. No local scope means recursive functions can't maintain independent state. No else clause. No for loop. No return statement (functions run to the closing brace and always return). No character or string literals. No preprocessor.

But these are the same limitations as SectorC. The point was never to build a production compiler. It's a demonstration that a meaningful C compiler can exist in a space that most programmers would consider insufficient for anything useful. Seven hundred thirty-three bytes is less than a single TCP packet. It's smaller than most compiler error messages. And yet it reads C source code, performs lexical analysis, parses expressions with arbitrary nesting, generates native machine code with forward-patched control flow, and executes the result, all on a processor designed in 1976.

The source code is available on GitHub.

If you're interested in Z80 development, Design a Z80 Computer is a great hands-on guide, and Learn Multiplatform Assembly Programming with ChibiAkumas covers Z80 assembly alongside other architectures.

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.

Rust on Z80: From LLVM Backend to Hello World

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

In my previous post, I documented building an LLVM backend for the Z80 processor. The backend worked; simple LLVM IR compiled to valid Z80 assembly. But that post ended with a sobering admission: Rust's core library remained out of reach, its abstractions overwhelming the constraints of 1976 hardware.

This post picks up where that one left off. The question nagging at me was simple: can we actually compile real Rust code into Z80 assembly? Not just hand-crafted LLVM IR, but genuine Rust source files with functions and variables and all the conveniences we expect from a modern language?

The answer is yes. But getting there required more RAM than any Z80 system ever had, a creative workaround that sidesteps Rust's build system entirely, and a willingness to accept that sometimes the elegant solution isn't the one that works.

The Hardware Reality Check

Before diving into the technical details, I need to address something that caught me off guard: the sheer computational resources required to compile code for an 8-bit processor.

My first attempt was on my M3 Max MacBook Pro. The machine is no slouch: 64GB of unified memory, fast SSD, Apple's impressive silicon. Building LLVM with the Z80 backend worked fine. Building stage 1 of the Rust compiler worked, albeit slowly. But when I tried to build Rust's core library for the Z80 target, the process crawled. After watching it churn for hours with no end in sight, I gave up.

The next attempt used a Linux workstation with 32GB of RAM. This seemed reasonable. Surely 32GB is enough to compile code for a processor with a 64KB address space? It wasn't. The build process hit out-of-memory errors during the compilation of compiler_builtins, a Rust crate that provides low-level runtime functions.

To understand why, you need to know what compiler_builtins actually does. When you write code like let x: u64 = a * b;, and your target processor doesn't have native 64-bit multiplication (the Z80 doesn't even have 8-bit multiplication), something has to implement that operation in software. That something is compiler_builtins. It contains hundreds of functions: software implementations of multiplication, division, floating-point operations, and various other primitives that high-level languages take for granted. Each of these functions gets compiled, optimized, and linked into your final binary.

For the Z80, every one of these functions presents a challenge. 64-bit division on an 8-bit processor expands into an enormous sequence of instructions. The LLVM optimizer works hard to improve this code, and that optimization process consumes memory, lots of it.

The machine that finally worked was a dedicated build server:

OS: Ubuntu 24.04.3 LTS x86_64
Host: Gigabyte G250-G51 Server
CPU: Intel Xeon E5-2697A v4 (64 cores) @ 3.600GHz
Memory: 252GB DDR4
GPU: 4x NVIDIA Tesla P40 (unused for compilation)

With 252GB of RAM and 64 cores, the build finally had room to breathe. LLVM with Z80 support built in about 45 minutes. The Rust stage 1 compiler built in 11 minutes. And when we attempted to build compiler_builtins for Z80, memory usage peaked at 169GB.

Let that sink in: compiling runtime support code for a processor with 64KB of addressable memory required 169GB of RAM. The ratio is absurd: we needed 2.6 million times more memory to compile the code than the target system could ever access. This is what happens when modern software toolchains, designed for 64-bit systems with gigabytes of RAM, encounter hardware from an era when 16KB was a luxury.

The Naive Approach and Why It Fails

With our beefy build server ready, the obvious approach was to build Rust's core library for the Z80 target. The core library is Rust's foundation: it provides basic types like Option and Result, fundamental traits like Copy and Clone, and essential operations like memory manipulation and panicking. Unlike std, which requires an operating system, core is designed for bare-metal embedded systems. If anything could work on a Z80, surely core could.

The first obstacle was unexpected. Rust's build system uses a crate called cc to compile C code and detect target properties. When we ran the build, it immediately failed:

error occurred in cc-rs: target `z80-unknown-none-elf` had an unknown architecture

The cc crate maintains a list of known CPU architectures, and Z80 wasn't on it. The fix was simple (a one-line patch to add "z80" => "z80" to the architecture matching code), but we had to apply it to every version of cc in the cargo registry cache. Not elegant, but effective.

With that patched, the build progressed further before hitting a more fundamental problem:

rustc-LLVM ERROR: unable to legalize instruction: %35:_(s16) = nneg G_UITOFP %10:_(s64)

This error comes from LLVM's GlobalISel pipeline, specifically the Legalizer. To understand it, I need to explain how LLVM actually turns high-level code into machine instructions.

What is GlobalISel and Why Does It Matter?

When you compile code with LLVM, there's a critical step called "instruction selection": the process of converting LLVM's abstract intermediate representation (IR) into concrete machine instructions for your target CPU. This is harder than it sounds. LLVM IR might say "add these two 32-bit integers," but your CPU might only have 8-bit addition, or it might have three different add instructions depending on whether the operands are in registers or memory.

Historically, LLVM used a framework called SelectionDAG for this task. SelectionDAG works, but it operates on individual basic blocks (straight-line code between branches) and makes decisions that are hard to undo later. For well-established targets like x86 and ARM, SelectionDAG is mature and produces excellent code. But for new or unusual targets, it's difficult to work with.

GlobalISel (Global Instruction Selection) is LLVM's modern replacement. The "Global" in the name refers to its ability to see across basic block boundaries, making better optimization decisions. More importantly for our purposes, GlobalISel breaks instruction selection into distinct, understandable phases:

IRTranslator: Converts LLVM IR into generic machine instructions. These instructions have names like G_ADD (generic add), G_LOAD (generic load), and G_UITOFP (generic unsigned integer to floating-point conversion). At this stage, the code is still target-independent. G_ADD doesn't know if it'll become an x86 ADD, an ARM add, or a Z80 ADD A,B.
Legalizer: This is where target constraints enter the picture. The Legalizer transforms operations that the target can't handle into sequences it can. If your target doesn't support 64-bit addition directly, the Legalizer breaks it into multiple 32-bit or 16-bit additions. If your target lacks a multiply instruction (hello, Z80), the Legalizer replaces multiplication with a function call to a software implementation.
RegBankSelect: Assigns each value to a register bank. For the Z80, this means deciding whether something lives in 8-bit registers (A, B, C, D, E, H, L) or 16-bit register pairs (BC, DE, HL). This phase is crucial for the Z80 because using the wrong register bank means extra move instructions.
InstructionSelector: Finally converts the now-legal, register-bank-assigned generic instructions into actual target-specific instructions. G_ADD becomes ADD A,B or ADD HL,DE depending on the operand types.

For the Z80 backend, GlobalISel was the right choice. It gave us fine-grained control over how operations get lowered on extremely constrained hardware. The downside is that every operation needs explicit handling; if the Legalizer doesn't know how to transform a particular instruction for Z80, compilation fails.

The error we hit was in the Legalizer. The G_UITOFP instruction converts an unsigned integer to floating-point. In this case, it was trying to convert a 64-bit integer to a 16-bit half-precision float. This operation appears deep in Rust's core library, in the decimal number parsing code used for floating-point literals.

The Z80 has no floating-point hardware whatsoever. It can't even do integer multiplication in a single instruction. Teaching LLVM to "legalize" 64-bit-to-float conversions on such constrained hardware would require implementing software floating-point operations, a significant undertaking that would generate hundreds of Z80 instructions for a single high-level operation.

Even setting aside the floating-point issue, we encountered another class of failures: LLVM assertion errors in the GlobalISel pipeline when handling complex operations. These manifested as crashes with messages about register operand sizes not matching expectations. The Z80 backend is experimental, and its GlobalISel support doesn't cover every edge case that Rust's core library exercises.

The fundamental problem became clear: Rust's core library, while designed for embedded systems, assumes a level of hardware capability that the Z80 simply doesn't have. It assumes 32-bit integers work efficiently. It assumes floating-point parsing is reasonable. It assumes the register allocator can handle moderately complex control flow.

The Workaround: Cross-Compile and Retarget

When the direct path is blocked, you find another way around.

The key insight is that LLVM IR (Intermediate Representation) is largely target-agnostic. When Rust compiles your code, it first generates LLVM IR, and then LLVM transforms that IR into target-specific assembly. The IR describes your program's logic (additions, function calls, memory accesses) without committing to a specific instruction set.

This suggests a workaround: compile Rust code to LLVM IR using a different target that Rust fully supports, then manually retarget that IR to Z80 and run it through our Z80 LLVM backend.

For the donor target, I chose thumbv6m-none-eabi, the ARM Cortex-M0, a 32-bit embedded processor. This target is well-supported in Rust's ecosystem, and crucially, it's a no_std target designed for resource-constrained embedded systems. The generated IR would be reasonably close to what we'd want for Z80, minus the data layout differences.

The workflow looks like this:

Write Rust code with #![no_std] and #![no_main]
Compile for ARM: cargo +nightly build --target thumbv6m-none-eabi -Zbuild-std=core
Extract the LLVM IR from the build artifacts (the .ll files)
Modify the IR's target triple and data layout for Z80
Compile to Z80 assembly: llc -march=z80 -O2 input.ll -o output.s

The data layout change is important. ARM uses 32-bit pointers; Z80 uses 16-bit pointers. The Z80 data layout string is:

e-m:e-p:16:8-i16:8-i32:8-i64:8-n8:16

This tells LLVM: little-endian, ELF mangling, 16-bit pointers with 8-bit alignment, native types are 8-bit and 16-bit. When we retarget the IR, we need to update this layout and the target triple to z80-unknown-unknown.

Is this elegant? No. It's a hack that bypasses Rust's proper build system. But it works, and sometimes working beats elegant.

Hello Z80 World

Let's put this into practice with the classic first program.

Here's the Rust source code:

#![no_std]
#![no_main]

use core::panic::PanicInfo;

// Memory-mapped serial output at address 0x8000
const SERIAL_OUT: *mut u8 = 0x8000 as *mut u8;

#[inline(never)]
#[no_mangle]
pub extern "C" fn putchar(c: u8) {
    unsafe {
        core::ptr::write_volatile(SERIAL_OUT, c);
    }
}

#[no_mangle]
pub extern "C" fn hello_z80() {
    putchar(b'H'); putchar(b'e'); putchar(b'l'); putchar(b'l'); putchar(b'o');
    putchar(b' '); putchar(b'Z'); putchar(b'8'); putchar(b'0'); putchar(b'!');
    putchar(b'\r'); putchar(b'\n');
}

#[panic_handler]
fn panic(_: &PanicInfo) -> ! { loop {} }

This is genuine Rust code. We're using core::ptr::write_volatile for memory-mapped I/O, the extern "C" calling convention for predictable symbol names, and #[no_mangle] to preserve function names in the output. The #[inline(never)] on putchar ensures it remains a separate function rather than being inlined into the caller.

After compiling to ARM IR and retargeting to Z80, we run it through llc. The output is real Z80 assembly:

    .globl  putchar
putchar:
    ld   de,32768        ; Load address 0x8000
    push de
    pop  hl              ; DE -> HL (address now in HL)
    ld   (hl),a          ; Store A register to memory
    ret

    .globl  hello_z80
hello_z80:
    push ix              ; Save frame pointer
    ld   ix,0
    add  ix,sp           ; Set up stack frame
    dec  sp              ; Allocate 1 byte on stack
    ld   a,72            ; 'H'
    call putchar
    ld   a,101           ; 'e'
    call putchar
    ld   a,108           ; 'l'
    ld   (ix+-1),a       ; Save 'l' to stack (optimization!)
    call putchar
    ld   a,(ix+-1)       ; Reload 'l' for second use
    call putchar
    ld   a,111           ; 'o'
    call putchar
    ld   a,32            ; ' '
    call putchar
    ld   a,90            ; 'Z'
    call putchar
    ld   a,56            ; '8'
    call putchar
    ld   a,48            ; '0'
    call putchar
    ld   a,33            ; '!'
    call putchar
    ld   a,13            ; '\r'
    call putchar
    ld   a,10            ; '\n'
    call putchar
    ld   sp,ix           ; Restore stack
    pop  ix              ; Restore frame pointer
    ret

This is valid Z80 assembly that would run on real hardware. The putchar function loads the serial port address into the HL register pair and stores the character from the A register. The hello_z80 function calls putchar twelve times, once for each character in "Hello Z80!\r\n".

Notice something interesting: the compiler optimized the duplicate 'l' character. Instead of loading 108 into the A register twice, it saves the value to the stack after the first use and reloads it for the second. This is LLVM's register allocator at work, recognizing that reusing a value from the stack is cheaper than reloading an immediate. The Z80 backend is generating genuinely optimized code.

Running on (Emulated) Hardware

Generating assembly is satisfying, but seeing it actually execute closes the loop. I have a Rust-based Z80 emulator that I use for testing RetroShield firmware. It emulates the Z80 CPU along with common peripheral chips, including the MC6850 ACIA serial chip that my physical hardware uses.

To run our Hello World, we need to adapt the memory-mapped I/O to use the ACIA's port-based I/O instead. The MC6850 uses port $80 for status and port $81 for data. A proper implementation waits for the Transmit Data Register Empty (TDRE) bit before sending each character:

; Hello Z80 World - Compiled from Rust via LLVM
; Adapted for MC6850 ACIA serial output

ACIA_STATUS:    equ     $80
ACIA_DATA:      equ     $81

        org     $0000

_start:
        ld      hl, MESSAGE
        ld      b, MESSAGE_END - MESSAGE

print_loop:
wait_ready:
        in      a, (ACIA_STATUS)
        and     $02                ; Check TDRE bit
        jr      z, wait_ready

        ld      a, (hl)
        out     (ACIA_DATA), a
        inc     hl
        djnz    print_loop

halt_loop:
        halt
        jr      halt_loop

MESSAGE:
        defb    "Hello, Z80 World!", $0D, $0A
MESSAGE_END:

This is the essence of what our Rust code does, translated to the actual hardware interface. The infinite loop at the end mirrors Rust's loop {}. On bare metal, there's nowhere to return to.

Assembling with z80asm produces a 39-byte binary. Running it in the emulator:

$ ./retroshield -d -c 10000 hello_rust.bin
Loaded 39 bytes from hello_rust.bin
Starting Z80 emulation...
Hello, Z80 World!

CPU halted at PC=0011 after 1194 cycles

The program executes in 1,194 Z80 cycles, roughly 300 microseconds at the original 4MHz clock speed. The complete pipeline works:

Rust source code → compiled to LLVM IR via rustc
LLVM IR → retargeted to Z80 and compiled to assembly
Z80 assembly → assembled to binary with z80asm
Binary → executed in the Z80 emulator

The 39-byte binary breaks down to about 20 bytes of executable code and 19 bytes for the message string. This is exactly what bare-metal #![no_std] Rust should produce: tight, efficient code with zero runtime overhead.

What Works and What Doesn't

Through experimentation, we've mapped out the boundaries of what the Z80 backend handles well.

Works reliably:

8-bit arithmetic: addition, subtraction, bitwise operations. These map directly to Z80 instructions like ADD A,B and AND B.
16-bit arithmetic: addition and subtraction use the Z80's 16-bit register pairs (HL, DE, BC) efficiently.
Memory operations: loads and stores generate clean LD (HL),A and LD A,(HL) sequences.
Function calls: the calling convention uses registers efficiently, avoiding unnecessary stack operations for simple cases.
Simple control flow: conditional branches and unconditional jumps work as expected.

Works but generates bulky code:

32-bit arithmetic: every 32-bit operation expands into multiple 16-bit operations with careful carry flag handling. A 32-bit addition becomes a sequence that would make a Z80 programmer wince.
Multiplication: even 8-bit multiplication requires a library call to __mulhi3 since the Z80 lacks a multiply instruction.

Breaks the register allocator:

Loops with phi nodes: in LLVM IR, loops use phi nodes to represent values that differ depending on which path entered the loop. Complex phi nodes exhaust the Z80's seven registers, causing "ran out of registers" errors.
Functions with many live variables: if you need more than a handful of values alive simultaneously, the backend can't handle it.

Not supported:

Floating-point operations: no legalization rules exist for converting the Z80's lack of FPU into software equivalents.
Complex core library features: iterators, formatters, and most of the standard library infrastructure trigger unsupported operations.

The Calling Convention

Through testing, we've empirically determined how our Z80 backend passes arguments and returns values:

Type	First Argument	Second Argument	Return Value
`u8` / `i8`	A register	L register	A register
`u16` / `i16`	HL register pair	DE register pair	HL register pair

Additional arguments go on the stack. The stack frame uses the IX register as a frame pointer when needed. This convention minimizes register shuffling for common cases. A function taking two 16-bit arguments and returning one uses HL and DE for input and HL for output, requiring no setup at all.

This differs from traditional Z80 calling conventions used by C compilers, which typically pass all arguments on the stack. Our approach is more register-heavy, which suits the short functions typical of embedded code.

Practical Implications

Let me be clear about what we've achieved and what remains out of reach.

What you can realistically build:

Simple embedded routines: LED patterns, sensor reading, basic I/O handling
Mathematical functions: integer arithmetic, lookup tables, state machines
Protocol handlers: parsing simple data formats, generating responses
Anything that would fit in a few kilobytes of hand-written assembly

What you cannot build:

Anything requiring heap allocation: no Vec, no String, no dynamic data structures
Code using iterators or closures: these generate complex LLVM IR that overwhelms the register allocator
Formatted output: Rust's write! macro and formatting infrastructure are far too heavy
Floating-point calculations: not without significant backend work

The path to making this more capable is visible but non-trivial. A custom minimal core implementation that avoids floating-point entirely would help. Improving the register allocator's handling of phi nodes would enable loops. Adding software floating-point legalization would unlock numerical code. Each of these is a substantial project.

Reflections

Building a compiler backend for a 50-year-old processor using a 21st-century language toolchain is an exercise in contrasts. Modern software assumes abundant resources. The Z80 was designed when resources were precious. Making them meet requires translation across decades of computing evolution.

The fact that we needed 252GB of RAM to compile code for a processor with a 64KB address space is almost poetic. It captures something essential about how far computing has come and how much we've traded simplicity for capability.

But here's what satisfies me: the generated Z80 code is good. It's not bloated or obviously inefficient. When we compile a simple function, we get a simple result. The LLVM optimization passes do their job, and our backend translates the result into idiomatic Z80 assembly. The 'l' character optimization in our Hello World example isn't something I would have thought to do by hand, but the compiler found it automatically.

Rust on Z80 isn't practical for production use. The core library is too heavy, the workarounds are too fragile, and the resulting code size would exceed most Z80 systems' capacity. But as a demonstration that modern toolchains can target ancient hardware? As an exploration of what compilers actually do? As an answer to "I wonder if this is possible?"

Yes. It's possible. And the journey to get here taught me more about LLVM, register allocation, and instruction selection than any tutorial ever could.

What's Next

With emulation working, the obvious next step is running this code on actual hardware. My RetroShield Z80 sits waiting on my workbench, ready to execute whatever binary we load into it. The emulator uses the same ACIA interface as the physical hardware, so the transition should be straightforward: load the binary, connect a terminal, and watch "Hello, Z80 World!" appear on genuine 8-bit silicon.

Beyond hardware validation, the Z80 backend needs work on loop handling. Phi nodes are the enemy. There may be ways to lower them earlier in the pipeline, before they reach the register-hungry instruction selector. That's a project for another day, another blog post, and probably another round of pair programming with Claude.

The projects are available on GitHub for anyone curious enough to try them:

LLVM with Z80 backend: github.com/ajokela/llvm-z80
Rust with Z80 target: github.com/ajokela/rust-z80 (see the z80-backend branch)
Z80 Emulator: github.com/ajokela/retro-z80-emulator

Be warned: you'll need more RAM than seems reasonable. But if you've read this far, you probably already suspected that.

Resources

If you want to dive deeper into any of the topics covered here, these resources might help:

Books:

Programming the Z80 by Rodnay Zaks: The definitive Z80 reference, covering every instruction and addressing mode in detail
The Rust Programming Language by Klabnik and Nichols: The official Rust book, essential for understanding no_std embedded development
Engineering a Compiler by Cooper and Torczon: Comprehensive compiler textbook covering instruction selection, register allocation, and code generation
Crafting Interpreters by Robert Nystrom: Excellent practical guide to building language implementations

Hardware:

Z80 CPU chips: Original Zilog Z80 processors, still available new and vintage
RetroShield Z80: Arduino shield that lets you run a real Z80 with modern conveniences
USB to Serial adapters: Essential for connecting to vintage hardware
Logic Analyzer: Invaluable for debugging Z80 bus timing and signals

Rust on Z80: An LLVM Backend Odyssey

A.C. Jokela — Thu, 25 Dec 2025 18:00:00 GMT

This is the story of attempting something probably inadvisable: compiling Rust for the Zilog Z80, an 8-bit processor from 1976. It's also a story about using AI as a genuine collaborator on deep systems programming work, and what happens when modern software abstractions collide with hardware constraints from an era when 64 kilobytes was considered generous.

Transparency: Claude Code as Collaborator

I want to be upfront about something: significant portions of this compiler backend were developed in collaboration with Claude Code, Anthropic's AI coding assistant. This isn't a case of "AI wrote the code and I took credit"; it's more nuanced than that. Claude served as an unusually patient pair programmer who happens to have read every LLVM tutorial ever written.

Here's what that collaboration actually looked like:

I would describe a problem: "The instruction selector is failing with cannot select: G_SADDO for signed addition with overflow detection." Claude would analyze the GlobalISel pipeline, identify that the Z80's ADC instruction sets the P/V flag for signed overflow, and propose an implementation. I would review, test, discover edge cases, and we'd iterate.

The debugging sessions were particularly valuable. When compilation hung for seven hours on what should have been a two-minute build, Claude helped trace the issue to an accidental infinite recursion: a replace_all refactoring had changed RBI.constrainGenericRegister(...) to constrainOrSetRegClass(...) inside the constrainOrSetRegClass helper function itself. The function was calling itself forever. Finding that bug manually would have taken hours of printf debugging; with Claude analyzing the code structure, we found it in minutes.

This is what AI-assisted development actually looks like in 2025: not magic code generation, but accelerated iteration with a collaborator who never gets frustrated when you ask "wait, explain register allocation to me again."

Why Z80? Why Rust?

The Z80 powered the TRS-80, ZX Spectrum, MSX computers, and countless embedded systems. It's still manufactured today; you can buy new Z80 chips. I actually did just that, I bought a handful of vintage ceramic Z80 chips off of eBay. There's something appealing about running modern language constructs on hardware designed when ABBA topped the charts.

More practically, I've been building Z80-based projects on the RetroShield platform, which lets you run vintage processors on Arduino-compatible hardware. Having a modern compiler toolchain opens possibilities that hand-written assembly doesn't.

But Rust specifically? Rust's ownership model and zero-cost abstractions are theoretically perfect for resource-constrained systems. The language was designed for systems programming. The question is whether "systems" can stretch back 50 years.

Building LLVM for the Z80

The first step was getting LLVM itself to build with Z80 support. This meant:

Adding Z80 to the list of supported targets in the build system
Creating the target description files (registers, instruction formats, calling conventions)
Implementing the GlobalISel pipeline components
Wiring everything together so llc -mtriple=z80-unknown-unknown actually works

The target description files alone span thousands of lines. Here's what defining just the basic registers looks like:

def A : Z80Reg<0, "a">;
def B : Z80Reg<1, "b">;
def C : Z80Reg<2, "c">;
def D : Z80Reg<3, "d">;
def E : Z80Reg<4, "e">;
def H : Z80Reg<5, "h">;
def L : Z80Reg<6, "l">;

// 16-bit register pairs
def BC : Z80RegWithSub<7, "bc", [B, C]>;
def DE : Z80RegWithSub<8, "de", [D, E]>;
def HL : Z80RegWithSub<9, "hl", [H, L]>;

Every instruction needs similar treatment. The Z80 has over 700 documented instruction variants when you count all the addressing modes. Not all are needed for a basic backend, but getting basic arithmetic, loads, stores, branches, and calls working required implementing dozens of instruction patterns.

The build process itself was surprisingly manageable. LLVM's build system is well-designed. A complete build with the Z80 target takes about 20 minutes on modern hardware. The iteration cycle during development was typically: change a few files, rebuild (30 seconds to 2 minutes depending on what changed), test with llc, fix, repeat.

The LLVM Approach

LLVM provides a framework for building compiler backends. You describe your target's registers, instruction set, and calling conventions; LLVM handles optimization, instruction selection, and register allocation. In theory, adding a new target is "just" filling in these descriptions.

In practice, LLVM assumes certain things about targets. It assumes you have a reasonable number of general-purpose registers. It assumes arithmetic operations work on values that fit in registers. It assumes function calls follow conventions that modern ABIs have standardized.

The Z80 violates all of these assumptions.

The Register Poverty Problem

The Z80 has seven 8-bit registers: A, B, C, D, E, H, and L. Some can be paired into 16-bit registers: BC, DE, HL. That's it. Modern architectures have 16 or 32 general-purpose registers; the Z80 has seven that aren't even all general-purpose. A is the accumulator with special arithmetic privileges, HL is the primary memory pointer.

LLVM's register allocator expects to juggle many virtual registers across many physical registers. When you have more virtual registers than physical registers, it spills values to memory. On the Z80, you're spilling constantly. Every 32-bit operation requires careful choreography of the few registers available.

Here's what a simple 16-bit addition looks like in our backend:

define i16 @add16(i16 %a, i16 %b) {
  %result = add i16 %a, %b
  ret i16 %result
}

This compiles to:

add16:
    add hl,de
    ret

That's clean because we designed the calling convention to pass arguments in HL and DE. The backend recognizes that the inputs are already where they need to be and emits just the ADD instruction.

But 32-bit addition? That becomes a multi-instruction sequence juggling values through the stack because we can't hold four 16-bit values in registers simultaneously.

The Width Problem

The Z80 is fundamentally an 8-bit processor with 16-bit addressing. Rust's standard library uses usize for indexing, which on most platforms is 32 or 64 bits. The Z80 cannot directly perform 32-bit arithmetic. Every u32 operation expands into multiple 8-bit or 16-bit operations.

Consider multiplication. The Z80 has no multiply instruction at all. To multiply two 16-bit numbers, we emit a call to a runtime library function (__mulhi3) that implements multiplication through shifts and adds. 32-bit multiplication requires calling a function that orchestrates four 16-bit multiplications with proper carry handling.

Division is worse. Iterative division algorithms on 8-bit hardware are slow. Floating-point arithmetic doesn't exist in hardware; every floating-point operation becomes a library call to software implementations.

GlobalISel: The Modern Approach

We're using LLVM's GlobalISel framework rather than the older SelectionDAG. GlobalISel provides finer control over instruction selection through explicit lowering steps:

IRTranslator: Converts LLVM IR to generic machine instructions (G_ADD, G_LOAD, etc.)
Legalizer: Transforms operations the target can't handle into sequences it can
RegBankSelect: Assigns register banks (8-bit vs 16-bit on Z80)
InstructionSelector: Converts generic instructions to target-specific instructions

Each step presented challenges. The Legalizer needed custom rules to break 32-bit operations into 16-bit pieces. RegBankSelect needed to understand that some Z80 instructions only work with specific register pairs. The InstructionSelector needed patterns for every Z80 instruction variant.

One particularly tricky issue: LLVM's overflow-detecting arithmetic. Instructions like G_SADDO (signed add with overflow) return both a result and an overflow flag. The Z80's ADC instruction sets the P/V flag on signed overflow, but capturing that flag to a register requires careful instruction sequencing; you can't just read the flag register arbitrarily.

The Bug That Cost Seven Hours

During development, we hit a bug that perfectly illustrates the challenges of compiler work. After implementing a helper function to handle register class assignment, compilation started hanging. Not crashing, hanging. A simple three-function test file that should compile in milliseconds ran for over seven hours before I killed it.

The issue? During a refactoring pass, we used a global search-and-replace to change all calls from RBI.constrainGenericRegister(...) to our new constrainOrSetRegClass(...) helper. But the helper function itself contained a call to RBI.constrainGenericRegister() as its fallback case. The replace-all changed that too:

// Before (correct):
bool constrainOrSetRegClass(Register Reg, ...) {
  if (!MRI.getRegClassOrNull(Reg)) {
    MRI.setRegClass(Reg, &RC);
    return true;
  }
  return RBI.constrainGenericRegister(Reg, RC, MRI);  // Fallback
}

// After (infinite recursion):
bool constrainOrSetRegClass(Register Reg, ...) {
  if (!MRI.getRegClassOrNull(Reg)) {
    MRI.setRegClass(Reg, &RC);
    return true;
  }
  return constrainOrSetRegClass(Reg, RC, MRI);  // Calls itself forever!
}

The function was calling itself instead of the underlying LLVM function. Every attempt to compile anything would recurse until the stack overflowed or the heat death of the universe, whichever came first.

This is the kind of bug that's obvious in hindsight but insidious during development. There were no compiler errors, no warnings, no crashes with helpful stack traces. Just silence as the process spun forever.

Finding it required adding debug output at each step of the instruction selector, rebuilding, and watching where the output stopped. Claude helped immensely here, recognizing the pattern of "output stops here" and immediately checking what that code path did.

The Calling Convention

We designed a Z80-specific calling convention optimized for the hardware's constraints:

First 16-bit argument: HL register pair
Second 16-bit argument: DE register pair
Return value: HL register pair
Additional arguments: Stack
Caller-saved: All registers (callee can clobber anything)
Callee-saved: None

This convention minimizes register shuffling for simple functions. A function taking two 16-bit values and returning one doesn't need any register setup at all; the arguments arrive exactly where the ADD instruction expects them.

For 8-bit arguments, values arrive in the low byte of HL (L register) or DE (E register). This wastes the high byte but simplifies the calling convention.

This is radically different from typical calling conventions. Modern ABIs specify precise preservation rules, stack alignment requirements, and argument passing in specific registers. On the Z80, with so few registers, we had to make pragmatic choices. Every function saves and restores what it needs; there's no concept of "preserved across calls."

A Working Example

Here's LLVM IR that our backend compiles successfully:

target datalayout = "e-m:e-p:16:8-i16:8-i32:8-i64:8-n8:16"
target triple = "z80-unknown-unknown"

define i16 @add16(i16 %a, i16 %b) {
  %result = add i16 %a, %b
  ret i16 %result
}

define i16 @sub16(i16 %a, i16 %b) {
  %result = sub i16 %a, %b
  ret i16 %result
}

define i8 @add8(i8 %a, i8 %b) {
  %result = add i8 %a, %b
  ret i8 %result
}

Compiled output:

    .text
    .globl  add16
add16:
    add hl,de
    ret

    .globl  sub16
sub16:
    and a           ; clear carry
    sbc hl,de
    ret

    .globl  add8
add8:
    ld  c,l
    ld  b,c
    add a,b
    ret

The 16-bit operations are efficient. The 8-bit addition shows the register shuffling required when values aren't in the accumulator, so we have to move values through available registers to get them where the ADD instruction expects.

Compilation time for these three functions: 0.01 seconds. The backend works.

Where We Are Now

The backend compiles simple LLVM IR to working Z80 assembly. Integer arithmetic, control flow, function calls, memory access: the fundamentals work. We've implemented handlers for dozens of generic machine instructions and their various edge cases.

Attempting to compile Rust's core library has been... educational. The core library is massive. It includes:

All the formatting infrastructure (Display, Debug, write! macros)
Iterator implementations and adaptors
Option, Result, and their many combinator methods
Slice operations, sorting algorithms
Panic handling infrastructure
Unicode handling

Each of these generates significant code. The formatting system alone probably exceeds the entire memory capacity of a typical Z80 system.

Current status: compilation of core starts, processes thousands of functions, but eventually hits edge cases we haven't handled yet. The most recent error involves register class assignment in the floating-point decimal formatting code, ironic since the Z80 has no floating-point hardware.

Connecting Rust to the Z80 Backend

Getting Rust to use our LLVM backend required modifying the Rust compiler itself. This involved:

Adding a target specification: Defining z80-unknown-none-elf in Rust's target database with the appropriate data layout, pointer width, and feature flags.
Pointing Rust at our LLVM: Rust can use an external LLVM rather than its bundled version. We configured the build to use our Z80-enabled LLVM.
Disabling C compiler-builtins: Rust's standard library includes some C code from compiler-rt for low-level operations. There's no Z80 C compiler readily available, so we had to disable these and rely on pure Rust implementations.
Setting panic=abort: The Z80 can't reasonably support stack unwinding for panic handling.

The Rust target specification looks like this:

Target {
    arch: Arch::Z80,
    data_layout: "e-m:e-p:16:8-i16:8-i32:8-i64:8-n8:16".into(),
    llvm_target: "z80-unknown-unknown".into(),
    pointer_width: 16,
    options: TargetOptions {
        c_int_width: 16,
        panic_strategy: PanicStrategy::Abort,
        max_atomic_width: Some(0),  // No atomics
        atomic_cas: false,
        singlethread: true,
        no_builtins: true,  // No C runtime
        ..TargetOptions::default()
    },
}

The pointer_width: 16 is crucial: this is a 16-bit architecture. The max_atomic_width: Some(0) tells Rust that atomic operations aren't available at all, since the Z80 has no atomic instructions.

When Rust tries to compile core, it invokes rustc, which invokes LLVM, which invokes our Z80 backend. Each function in core goes through this pipeline. The sheer volume is staggering; core contains thousands of generic functions that get monomorphized for every type they're used with.

The Honest Assessment

Will Rust's standard library ever practically run on a Z80? Almost certainly not. The core library alone, compiled for Z80, would likely exceed a megabyte, far beyond the 64KB address space. Even if you could page-swap the code, the runtime overhead of software floating-point, 32-bit arithmetic emulation, and iterator abstractions would make execution glacially slow.

What might actually work:

#![no_std] #![no_core] programs: Bare-metal Rust with a tiny custom runtime, no standard library, hand-optimized for the hardware. A few kilobytes of carefully written Rust that compiles to tight Z80 assembly.
Code generation experiments: Using the LLVM backend to study how modern language constructs map to constrained hardware, even if the results aren't practical to run.
Educational purposes: Understanding compiler internals by working with hardware simple enough to reason about completely.

The value isn't in running production Rust on Z80s. It's in the journey: understanding LLVM's internals, grappling with register allocation on a machine that predates the concept (and myself albeit by only a few years), and seeing how far modern tooling can stretch.

Conclusion

Compiling Rust for the Z80 is somewhere between ambitious and absurd. The hardware constraints are genuinely incompatible with modern language expectations. But the attempt has been valuable: understanding LLVM deeply, exploring what "resource-constrained" really means, and discovering that AI collaboration can work effectively on low-level systems programming.

The Z80 was designed for a world where programmers counted bytes. Rust was designed for a world where programmers trust the compiler to manage complexity. Making them meet is an exercise in translation across decades of computing evolution.

TinyComputers.io (Posts about Retrocomputing, Compilers)

SectorZ: A C Compiler in 733 Bytes of Z80 Assembly

What It Compiles

The Architecture Tax

Memory Layout

Key Design Decisions

HL as the Code Pointer

The atoi Hash Trick

The cp_de_imm Trick

Runtime Helpers for Binary Operations

Function Trampolines

The Semicolon Hack

A Real Program: Prime Sieve

Size Breakdown

SectorC vs. SectorZ

Running It

What's Missing

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

Rust on Z80: From LLVM Backend to Hello World

The Hardware Reality Check

The Naive Approach and Why It Fails

What is GlobalISel and Why Does It Matter?

The Workaround: Cross-Compile and Retarget

Hello Z80 World

Running on (Emulated) Hardware

What Works and What Doesn't

The Calling Convention

Practical Implications

Reflections

What's Next

Resources

Rust on Z80: An LLVM Backend Odyssey

Transparency: Claude Code as Collaborator

Why Z80? Why Rust?

Building LLVM for the Z80

The LLVM Approach

The Register Poverty Problem

The Width Problem

GlobalISel: The Modern Approach

The Bug That Cost Seven Hours

The Calling Convention

A Working Example

Where We Are Now

Connecting Rust to the Z80 Backend

The Honest Assessment

Conclusion

The `atoi` Hash Trick

The `cp_de_imm` Trick

Path 3: Manual `no_std` with FFI to C