# 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/`](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](docs/INSTALL.md)):

```bash
# 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](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 (100 iters);
dadd 1157, ddiv 1261, dmul 1033 cyc/iter (10 iters);
particles 2253 (3 iters — 32-particle physics tick);
mandelbrot 11570 (1 iter — 4×4 fixed-point tile).

See [STATUS.md](STATUS.md) for full language and runtime feature
coverage, and [LLVM_65816_DESIGN.md](LLVM_65816_DESIGN.md) for
backend internals.

## Documentation

- [docs/INSTALL.md](docs/INSTALL.md) — system requirements and install
  steps
- [docs/USAGE.md](docs/USAGE.md) — compile, link, run, debug
- [STATUS.md](STATUS.md) — current language/runtime support matrix
- [LLVM_65816_DESIGN.md](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.