llvm816

LLVM/Clang C compiler for the WDC 65816 / Apple IIgs.

Compiles C (and a minimal subset of C++) to native 65816 machine code, links to a relocatable OMF binary, and runs under MAME's apple2gs. Speed-tuned: matches or beats hand-written 65816 assembly on the tight loops in benchmarks like sumOfSquares, popcount, and strcpy.

What you get

• clang --target=w65816 — full C99 + parts of C11, optimized at -O2 by default. Soft-float and soft-double included.
• C standard library subset — stdio.h, stdlib.h, string.h, math.h, time.h, setjmp.h, etc. See runtime/include/ for the complete list.
• link816 — relocating linker producing GS/OS-loadable OMF binaries (single- or multi-segment).
• MAME integration scripts — compile, link, and run a program under MAME's apple2gs with one command.
• Apple IIgs Toolbox bindings — <iigs/toolbox_full.h> exposes ~1300 toolbox routines from 35 tool sets.

Quick start

After installation (see docs/INSTALL.md):

# Compile a C file
cat > hello.c <<'EOF'
__attribute__((noinline)) void switchToBank2(void) {
    __asm__ volatile ("sep #0x20\n.byte 0xa9,0x02\npha\nplb\nrep #0x20\n");
}
int main(void) {
    unsigned short x = 0;
    for (int i = 1; i <= 10; i++) x += i;        // x = 55
    switchToBank2();
    *(volatile unsigned short *)0x5000 = x;
    while (1) {}
}
EOF

# Build + run under MAME (writes 0x0037 to $025000, MAME displays it)
./tools/llvm-mos-build/bin/clang --target=w65816 -O2 -c hello.c -o hello.o
./tools/link816 -o hello.bin --text-base 0x1000 \
    runtime/crt0.o runtime/libc.o runtime/libgcc.o hello.o
bash scripts/runInMame.sh hello.bin --check 0x025000=0037

See docs/USAGE.md for a full walkthrough including multi-segment builds and the Apple IIgs Toolbox.

Project layout

runtime/         C standard library + crt0 startup
  src/           sources (C and .s)
  include/       headers
  *.o            built object files
src/             our LLVM/Clang sources (W65816 target backend)
  clang/         clang patches
  llvm/          LLVM patches + W65816 target
  link816/       relocating linker
patches/         patches against vanilla llvm-mos
scripts/         install scripts, MAME runners, benchmarks
tools/           installed compilers, MAME, ROMs, Calypsi (reference)
benchmarks/      cycle-count and instruction-count benchmarks
compare/         side-by-side asm vs Calypsi
docs/            this directory — INSTALL.md, USAGE.md, design notes

Status

Stable enough to build real programs. Static instruction-count ratio against commercial Calypsi 5.16 (lower is better):

Benchmark	Ours (inst)	Calypsi (inst)	Ratio
sumSquares	26	31	0.84× ✓
evalAt	472	254	1.86×
mul16to32	1	4	0.25× ✓

Per-iteration cycle measurements (via MAME's HBL counter, 2026-05-20): bsearch 127, dotProduct 144, fib 97, memcmp 113, popcount 93, strcpy 91, sumOfSquares 126 (cyc/iter at 100 iters); dadd 1157, ddiv 1261, dmul 1033 (cyc/iter at 10 iters — FP calls are ~1000+ cyc each).

See STATUS.md for full language and runtime feature coverage, and LLVM_65816_DESIGN.md for backend internals.

Documentation

• docs/INSTALL.md — system requirements and install steps
• docs/USAGE.md — compile, link, run, debug
• STATUS.md — current language/runtime support matrix
• LLVM_65816_DESIGN.md — backend design notes

License

Apache 2.0 (matching the LLVM project's license). See tools/llvm-mos/LICENSE.TXT after install.