TinyComputers.io (Posts about llvm)

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.

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 llvm)

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

Source Code

Acknowledgments

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

Path 3: Manual `no_std` with FFI to C