709 lines
35 KiB
Markdown
709 lines
35 KiB
Markdown
# Session Resume — llvm816 project
|
||
|
||
Drop this into a new Claude Code session and say "read SESSION_STATE.md and
|
||
continue where we left off." Pairs with `LLVM_65816_DESIGN.md` (the design
|
||
doc — read that second).
|
||
|
||
---
|
||
|
||
## 1. Project in one sentence
|
||
|
||
Build an open-source LLVM/Clang backend for the WDC 65816 (Apple IIgs) that
|
||
matches or exceeds Calypsi's output quality, forked from llvm-mos but
|
||
maintained as our own separate W65816 target. User is Scott; expert C dev,
|
||
doesn't want hand-holding on LLVM or 65816 basics.
|
||
|
||
## 2. Where we are in the plan
|
||
|
||
Design doc section 7 lists a 12-step implementation order. We are at:
|
||
|
||
- [x] **Setup toolchain** (prior session)
|
||
- [x] **Architectural decision: separate W65816 target** (design doc §2.5)
|
||
- [x] **Repo-layout decision:** `src/` holds our authored files, `patches/`
|
||
holds modifications to upstream llvm-mos files, `tools/llvm-mos/` is
|
||
ephemeral and gitignored. `scripts/applyBackend.sh` stitches src +
|
||
patches into the clone.
|
||
- [x] **Step 1 — scaffold W65816 target directory.** 41 files under
|
||
`src/llvm/lib/Target/W65816/` + 2 files under
|
||
`src/clang/lib/Basic/Targets/`. 4 upstream patches under `patches/`.
|
||
- [x] **Step 2 — verify the skeleton fully compiles and links.** All 8
|
||
tablegen generators run clean, three static libs
|
||
(LLVMW65816Info/Desc/CodeGen) build, llc links with the target
|
||
registered, zero warnings in the W65816-local build.
|
||
`./bin/llc -march=w65816 -filetype=null /dev/null` → exit 0.
|
||
- [x] **Step 2a — real MC-layer instructions.** `W65816InstrInfo.td` now
|
||
holds ~90 real 65816 opcodes (LDA/STA/LDX/LDY/STX/STY across
|
||
immediate/DP/abs/DPX/AbsX/AbsY/long where applicable; ADC/SBC/CMP/
|
||
AND/ORA/EOR/BIT; INC/DEC/ASL/LSR/ROL/ROR; all transfers; stack
|
||
push/pull; REP/SEP/CLC/SEC/XCE/XBA; branches; JMP/JML/JSR/JSL;
|
||
RTS/RTL/RTI; MVN/MVP). Instructions whose size depends on M or X
|
||
bits exist as `_Imm8`/`_Imm16` pairs carrying the appropriate
|
||
TSFlag bits (MLow/MHigh/XLow/XHigh) for the future REP/SEP pass.
|
||
- [x] **Step 2b — wire MCCodeEmitter.** Tablegen `-gen-emitter` runs
|
||
cleanly; `W65816MCCodeEmitter.cpp` calls the tablegen-provided
|
||
`getBinaryCodeForInstr` and emits Size bytes little-endian.
|
||
- [x] **Step 2c — symbolic fixups.** Each operand class (imm8/imm16/
|
||
addrDP/addrAbs/addrLong/pcrel8/pcrel16) has its own
|
||
`EncoderMethod` that emits a `W65816::fixup_*` at the correct
|
||
byte offset for expression operands. `W65816AsmBackend::applyFixup`
|
||
patches the data bytes little-endian for resolved fixups and
|
||
defers to `maybeAddReloc` for unresolved ones.
|
||
`W65816ELFObjectWriter::getRelocType` returns placeholder
|
||
relocation numbers 1-5 (swap for canonical R_W65816_* names once
|
||
the ELF `EM_` is decided — §7 item 1).
|
||
- [x] **Step 2d — patch 0005 eliminates data-layout warning.** The
|
||
data-layout string for `Triple::w65816` lives in
|
||
`llvm/lib/TargetParser/TargetDataLayout.cpp`; `W65816TargetMachine`
|
||
now calls `TT.computeDataLayout()`. Zero warnings in the W65816
|
||
build.
|
||
- [x] **Step 2e — AsmParser scaffold.** 441-line
|
||
`AsmParser/W65816AsmParser.cpp` ported from MSP430, stripped of
|
||
register-operand handling (65816 has no MC register operands),
|
||
with width-narrowing predicates on each operand class so the
|
||
matcher picks the narrowest instruction variant the value fits
|
||
(e.g. `sta $10` → STA_DP, `sta $1000` → STA_Abs, `sta $10000` →
|
||
STA_Long). `#` is emitted as a literal token to match the AsmString
|
||
tokenisation. Block-move (MVN/MVP) uses `addrDP` for both bank
|
||
bytes so `mvn $01, $02` parses.
|
||
- [x] **Step 2f — operand bit-field wiring.** Every `Inst*` class in
|
||
`W65816InstrFormats.td` now assigns named bitfields into
|
||
`Inst{N-8}` (e.g. `let Inst{15-8} = imm;`). Without this
|
||
tablegen emits an encoder that writes the opcode but leaves the
|
||
operand bytes as zero — we had that bug for an iteration.
|
||
- [x] **Step 2g — smoke-test script.** `scripts/smokeTest.sh` checks
|
||
llc registration, empty-module codegen, and llvm-mc encoding of
|
||
a representative instruction mix. Run with `--build` to rebuild
|
||
first.
|
||
- [x] **Step 2h — end-to-end ELF object.** `llvm-mc -filetype=obj`
|
||
produces a valid ELF with relocations at correct byte offsets.
|
||
Relocations are placeholder numbers 1-5 (§7 item 1 — decide
|
||
EM_/R_* mapping).
|
||
- [x] **Step 2i — Disassembler.** 190-line
|
||
`Disassembler/W65816Disassembler.cpp` tries 1/2/3/4-byte decode
|
||
tables in ascending size order. Custom decoder callbacks for
|
||
imm/addr/pcrel operands wrap raw bits into MCOperands. Mode-
|
||
ambiguous opcodes (LDA/LDX/LDY/ADC/SBC/CMP/AND/ORA/EOR/BIT/CPX/
|
||
CPY immediate forms) are parked in separate
|
||
DecoderTableW65816{MHigh,XHigh}16 tables and the scaffold only
|
||
reads the default tables — so those opcodes always disassemble
|
||
as 3-byte 16-bit-immediate forms until a mode-aware decoder
|
||
lands (alongside REP/SEP).
|
||
- [x] **Step 2j — register operands in the AsmParser.** Key fix found
|
||
via round-trip test: tablegen treats `a`, `x`, `y` in AsmStrings
|
||
(e.g. `"inc a"`, `"lda\t$addr, x"`) as references to the real
|
||
register records, so the matcher expects register operands, not
|
||
literal tokens. AsmParser now produces `k_Reg` operands for
|
||
these identifiers. Verified: `inc a` → 0x1A, `lda $1000, x` →
|
||
0xBD,0x00,0x10, full ELF round-trip passes.
|
||
- [x] **Step 2k — smoke test covers disassembly.** The smoke test
|
||
now feeds raw bytes through `llvm-mc --disassemble` and checks
|
||
for expected mnemonics, so encoder/decoder asymmetries surface
|
||
immediately.
|
||
- [x] **Step 3a — first DAG patterns.** Type-as-mode model (approved).
|
||
`LDAi16imm` pseudo for i16 constants; `RTL` for retglue;
|
||
`emitPrologue` emits canonical `REP #$30`. Mode-dependent
|
||
`_Imm8` variants are `isCodeGenOnly` so the asm matcher never
|
||
picks them.
|
||
- [x] **Step 3c — single-arg function calls.** `LowerFormalArguments`
|
||
receives arg 0 in A; `LowerCall` passes arg 0 in A and JSL's
|
||
via a JSL pseudo to bridge the i16 symbol operand to the MC
|
||
`JSL_Long`'s 24-bit operand class. Result is back in A.
|
||
Multi-arg call lowering still wants a `PUSHA` SDNode + SP unwind
|
||
sequence — caller side currently fatals on >1 args.
|
||
- [x] **Step 3d — multi-arg via stack (callee side).**
|
||
`LowerFormalArguments` now reads arg 1+ from stack via
|
||
FrameIndex + load. `eliminateFrameIndex` translates LDAfi /
|
||
STAfi / ADCfi / SBCfi / ANDfi / ORAfi / EORfi / CMPfi pseudos
|
||
to their `LDA d,S` etc. counterparts with the offset baked in.
|
||
Stack-relative MC instructions are in place; AsmParser
|
||
recognises the `,s` suffix. Callee-side fully working: a
|
||
`define i16 @sum3(i16 %a, i16 %b, i16 %c)` compiles to
|
||
`clc; adc 4,s; clc; adc 6,s; rtl`.
|
||
- [x] **Step 3e — frame-index spill plumbing.** `storeRegToStackSlot`
|
||
and `loadRegFromStackSlot` emit STAfi / LDAfi pseudos so the
|
||
register allocator can spill Acc16 values when needed.
|
||
- [x] **Step 3f — multiplications via shifts.** Multiply by power-of-2
|
||
constants inherits the `shl` patterns (1/2/3/4 bits unrolled to
|
||
`asl a` sequences). Multiply by arbitrary constants and
|
||
runtime values fail at ISel pending library functions.
|
||
- [x] **Step 3h — clang front end builds.** Real C → 65816 machine
|
||
code via the full `clang -target w65816 -c` pipeline. Bumped
|
||
clang's `IntAlign`/`LongAlign`/`PointerAlign`/`SuitableAlign`
|
||
from 8 to 16; also overrode `allowsMisalignedMemoryAccesses` to
|
||
return true. `scripts/cDemo.sh` shows the full front-end
|
||
pipeline on a built-in 7-function demo. Additional patterns:
|
||
`INC_Abs`/`DEC_Abs` for `*p = *p + 1`; `ASRA16` (PHA;ASL;PLA;ROR
|
||
sequence) for signed shift-right by 1.
|
||
- [x] **Step 3i — frame reservation + epilogue.** `emitPrologue`
|
||
now emits `TSC; SEC; SBC #N; TCS` to reserve N bytes for locals
|
||
and spills, then `emitEpilogue` reverses with `TSC; CLC; ADC #N;
|
||
TCS` before the RTL. `eliminateFrameIndex` translates
|
||
FrameIndex operands into stack-relative offsets via
|
||
`disp = FrameOffset + StackSize`. `hasFPImpl` returns false
|
||
(no native FP — direct page would be the logical home). This
|
||
unblocks `clang -O0 -c` for pure-arithmetic functions (each
|
||
arg gets spilled to its own stack slot). Stack-relative
|
||
addressing modes for ADC/SBC/AND/ORA/EOR/CMP let the codegen
|
||
fold loads from frame indices into the carry-arithmetic ops.
|
||
- [x] **Step 3g — basic i8 codegen.** Acc8 patterns now cover:
|
||
`LDAi8imm` (constants), `INA_PSEUDO8` / `DEA_PSEUDO8` (inc/dec),
|
||
`ADCi8imm` / `SBCi8imm` (add/sub immediate), `ANDi8imm` /
|
||
`ORAi8imm` / `EORi8imm` (bitwise immediate), `LDA8abs` /
|
||
`STA8abs` (load/store via global), `ASLA8` / `LSRA8` (1-bit
|
||
shifts), `CMPi8imm` (compare against immediate, with BR_CC i8
|
||
lowering). Frame lowering scans the function IR for any i8
|
||
type usage (return, args, instruction values, operands) and
|
||
picks `REP #$10; SEP #$20` prologue when found, else
|
||
`REP #$30`. AsmPrinter masks i8 immediates to 8 bits before
|
||
printing so `i8 -16` shows `0xf0` rather than `0xfff0`.
|
||
Limitations: i8 mode is per-function only — mixed-mode
|
||
functions get the i8 prologue (8-bit A) and i16 ops fail.
|
||
Asm round-trip for i8 still loses M-mode info (the parser
|
||
can't disambiguate `lda #imm` between Imm8 and Imm16); use
|
||
`-filetype=obj` directly from llc to get the right encoding.
|
||
- [x] **Step 3b — globals, loads, stores, arithmetic, branches,
|
||
bitwise.** `LowerOperation` custom-lowers `GlobalAddress` and
|
||
`ExternalSymbol` to `W65816Wrapper(target...)`. Pseudo +
|
||
AsmPrinter-expansion family covers:
|
||
|
||
- `LDAi16imm`, `LDAabs`, `STAabs` (load/store/materialise via
|
||
Wrapper of global)
|
||
- `ADCi16imm`, `ADCabs`, `SBCi16imm`, `SBCabs` (add/sub with the
|
||
required CLC/SEC carry prefix)
|
||
- `ANDi16imm`, `ORAi16imm`, `EORi16imm` and their `*abs`
|
||
memory-fold variants
|
||
- `CMPi16imm`, `CMPabs` plus `W65816ISD::CMP` / `W65816ISD::BR_CC`
|
||
SDNodes; `LowerBR_CC` swaps constant-on-LHS forms and rewrites
|
||
SETULE/SETUGT/SETLE/SETGT to SETULT/SETUGE/SETLT/SETGE+1 so
|
||
the canonicalised DAG hits our patterns; condition-code map
|
||
covers BEQ/BNE/BCS/BCC plus signed BMI/BPL.
|
||
- `BRA` for unconditional `br`.
|
||
- `INA_PSEUDO` / `DEA_PSEUDO` for `add x, ±1` → `inc a` / `dec a`
|
||
- `ASLA16` / `LSRA16` for `shl x, 1` and `lshr x, 1` → `asl a` /
|
||
`lsr a`
|
||
- `NEGA16` for `0 - x` → `eor #$ffff; inc a`
|
||
- `(xor x, -1)` → `eor #$ffff` (bitwise NOT)
|
||
- Zero-extending byte load: `lda addr; and #$ff`
|
||
|
||
The end-to-end pipeline can now compile and assemble functions
|
||
that read/write globals, do arithmetic on them, and branch
|
||
conditionally — all with optimal-looking 65816 idioms (e.g.
|
||
`lda x ; clc ; adc y` for `*x + *y`).
|
||
- [ ] **Step 3i — open codegen gaps:**
|
||
|
||
1. **Multi-arg call lowering** (caller side). Callee side works;
|
||
caller still bails on >1 arg. Needs PUSHA SDNode + SP-unwind
|
||
in ADJCALLSTACKUP.
|
||
2. **Frame-reserved scratch space.** Prologue doesn't reserve
|
||
stack space for locals/spills, so any alloca'd value or
|
||
allocator-spilled value lands at a negative SP offset and
|
||
eliminateFrameIndex bails. Blocks: -O0 compilation of
|
||
functions with parameters; loops with PHIs that need to
|
||
compare two computed values; two-Acc16 binary ops in
|
||
general. Fix: emit `TSC; CLC; ADC #-N; TCS` (or PHA-loop)
|
||
in emitPrologue and the inverse in emitEpilogue, where N
|
||
is the function's frame size.
|
||
3. **Mixed-mode i8/i16.** Per-function mode only — the prologue
|
||
picks one mode; the other type's ops fail. REP/SEP scheduling
|
||
pass needed.
|
||
4. **Signed `(a - b)` overflow handling.** BMI/BPL based signed
|
||
comparisons are correct only when the subtraction can't
|
||
overflow; pathological values give wrong results.
|
||
5. **`sub imm, var`** and **`mul var, var`** (or non-power-of-2
|
||
constants). Need libcall support.
|
||
6. **SETCC and SELECT_CC i16.** Boolean conversions like
|
||
`(int)(cond != 0)` and `(cond) ? a : b` aren't selectable.
|
||
Custom lowering needed.
|
||
7. **Library functions.** `__mulhi3`, etc. — no runtime yet.
|
||
- [ ] **Step 4 — real frame lowering, calling convention, REP/SEP
|
||
scheduling pass.** The prologue `REP #$30` is unconditional;
|
||
the REP/SEP pass will remove it when redundant.
|
||
|
||
### Where we actually got to (current state, 2026-04-27)
|
||
|
||
The "open codegen gaps" list above is mostly resolved. Status of the
|
||
seven sub-items at line 192:
|
||
|
||
1. **Multi-arg call lowering (caller side)** — done. `LowerCall`
|
||
pushes args 1..N-1 right-to-left via `W65816ISD::PUSH`,
|
||
`ADJCALLSTACKUP` unwinds with `tsc;clc;adc #N;tcs`.
|
||
2. **Frame-reserved scratch space** — done. `emitPrologue` /
|
||
`emitEpilogue` use `tsc;sec;sbc #N;tcs` and the inverse.
|
||
3. **Mixed-mode i8/i16** — partial. Per-function mode based on IR
|
||
scan; full REP/SEP scheduling pass still TODO (Step 4).
|
||
4. **Signed `(a - b)` overflow in compares** — handled for i8/i16
|
||
via the signed-CC promote-to-i16 path. Still has the BMI/BPL
|
||
correctness caveat at INT16_MIN/MAX boundaries.
|
||
5. **`mul var, var` and friends** — done via libcalls; runtime stubs
|
||
live in `runtime/src/libgcc.s` (__mulhi3, __mulsi3, __ashlhi3,
|
||
__ashrhi3, __lshrhi3, __ashlsi3, __ashrsi3, __lshrsi3, __udivhi3,
|
||
__divhi3, __umodhi3, __modhi3, __udivsi3, __divsi3, __umodsi3,
|
||
__modsi3).
|
||
6. **SETCC and SELECT_CC i16** — done via custom inserter and the
|
||
`W65816cmp + W65816selectcc` SDNode pair.
|
||
7. **Library functions** — done; see #5 above.
|
||
|
||
### i32 (long) support — landed (2026-04-26..28)
|
||
|
||
- Type legalization splits i32 into two i16 halves.
|
||
- ABI: i32 first-arg lives in A:X (lo:hi), matching the return
|
||
ABI; subsequent i32 args go on stack 2 bytes per half.
|
||
`RetCC_W65816` assigns `[A, X]` for two i16 returns so
|
||
`__mulsi3` / `__divsi3` libcall returns work.
|
||
- ADD/SUB use the native ADC carry chain via ISD::ADDC/ADDE/SUBC/
|
||
SUBE Legal: `ADCi16imm` etc. mark `Defs = [P]` and pattern-match
|
||
`addc`; new `ADCEi16imm` / `ADCEabs` / `ADCEfi` (and SBC/E
|
||
variants) mark `Uses = [P], Defs = [P]` for `adde`/`sube`.
|
||
`ADDE_RR` / `SUBE_RR` have the inserter equivalent for two-Acc16
|
||
chains (e.g. fib32's loop). Net: an i32 add went from ~25 insns
|
||
(manual UADDO + SETCC + add-of-bool) to ~17 incl. prologue/epilogue,
|
||
with the core 8 being the optimal `clc;adc;sta;lda;adc;tax;lda;rtl`.
|
||
- NEGC16 / NEGE16 lower `(subc/sube 0, x)` for i32 negate via the
|
||
ADD chain (`EOR #$FFFF; CLC; ADC #1` lo, `EOR #$FFFF; ADC #0` hi).
|
||
- MUL/DIV/MOD/SHL/SHR/USHR all libcalled; preferredShiftLegalization
|
||
Strategy returns `LowerToLibcall` for i32 to keep LLVM from emitting
|
||
SHL_PARTS we'd have no pattern for.
|
||
- `BuildSDIVPow2` / `BuildSREMPow2` overrides return SDValue() to
|
||
block the magic-constant pow2 expansion that emits unsupported
|
||
BUILD_VECTOR.
|
||
|
||
### Other recent work
|
||
|
||
- `i1` `sext_inreg` lowered as `(sub 0, (and x, 1))`.
|
||
- `i8` `sext_inreg` and `sextload-i8` go through the existing
|
||
branchless `((x & 0xFF) ^ 0x80) - 0x80` sequence (SEXTLOAD i8 set
|
||
to Expand, sext_inreg pattern added).
|
||
- `extloadi8` from an `Acc16` register pointer maps to `LDAptr` (16-
|
||
bit load; consumer ignores high byte).
|
||
- Bare `ISD::FrameIndex` selected as `ADDframe (FI, 0)` for
|
||
alloca'd-array address-of; `eliminateFrameIndex` expands ADDframe
|
||
into `tsc;clc;adc #disp` (LEA equivalent).
|
||
- **Indirect calls** (function pointers): `LowerCall` redirects
|
||
through `__jsl_indir` in `runtime/src/libgcc.s` — caller stores
|
||
the dynamic target to global `__indirTarget` then JSLs the
|
||
trampoline, which does `JMP (__indirTarget)`. Target's RTL pops
|
||
the original JSL frame and returns directly to the caller.
|
||
Single-bank only (JMP indirect is bank-local).
|
||
- **Code-quality cleanup pass** (`W65816StackSlotCleanup`,
|
||
addPostRegAlloc):
|
||
- Removes redundant `LDAfi slot` after `STAfi reg, slot` when the
|
||
LDA's destination matches and nothing in between clobbers
|
||
either reg or slot. Catches the regalloc spill+reload cycle
|
||
around COPY $a → vreg.
|
||
- Removes dead `STAfi reg, slot` when a subsequent `STAfi`
|
||
overwrites the same slot before any read, OR when the function
|
||
returns without reading the slot (catches result-spill-before-
|
||
return that the libcall return ABI makes redundant).
|
||
- Combined with `isReMaterializable` on LDAfi from fixed FIs, the
|
||
i32 add went from 17 → 11 instructions.
|
||
- **i32 shift-by-1 inline** (task #59). The type-legalizer's
|
||
SHL_PARTS / SRL_PARTS expansion of `i32 << 1` / `>> 1` emits a
|
||
`(srl x, 15)` or `(shl x, 15)` for the carry-cross-halves slot.
|
||
Previously routed through __lshrhi3 / __ashlhi3 libcalls. Added
|
||
SRL15A pseudo (`ASL A; LDA #0; ROL A`, 3 bytes) and SHL15A
|
||
(`LSR A; LDA #0; ROR A`). i32 shl-by-1 went 33 → 26 insns;
|
||
shr-by-1 29 → 23.
|
||
- **i16 shift-by-8 inline** (task #60). Same idea for `(srl x, 8)`
|
||
and `(shl x, 8)` — used by i32 shift-by-8 type-legalization.
|
||
XBA swaps the two bytes of A in 16-bit M; AND clears the half
|
||
we don't want. 4 bytes per shift. i32 shl/shr-by-8 went
|
||
39/35 → 27/24 insns.
|
||
- **PUSH16X for direct X-push** (task #61). When LowerCall sees
|
||
an outgoing arg whose SDValue is `CopyFromReg` of a vreg that's
|
||
live-in from $x (i.e. the i32-first-arg-in-A:X hi half), emit
|
||
`phx` directly instead of `txa; pha` (which also requires
|
||
spilling $a to preserve it). mul32 went 19 → 13 insns.
|
||
- **Dead frame-slot trimming** (task #62). Extended W65816Stack
|
||
SlotCleanup to scan MIR for unreferenced (post-cleanup) local
|
||
frame indices and zero-size them so PrologueEpilogue trims the
|
||
prologue PHA/TSC reservation. Combined with the spill cleanup,
|
||
shrinks frames in many functions by 2-4 bytes (one fewer
|
||
PHA + PLY pair).
|
||
- **i32 first-arg in A:X (task #50)**. When the first original
|
||
argument is i32 (LowerFormalArguments / LowerCall detect via
|
||
`Outs[0..1].OrigArgIndex == 0` on i16 halves), pass it lo:hi in
|
||
A:X — matching the i32 return ABI. Saves one stack slot per
|
||
i32 arg. Required updating libgcc.s helpers (`__mulsi3`,
|
||
`__udivsi3`, `__umodsi3`, `__divsi3`, `__modsi3`, `__ashlsi3`,
|
||
`__lshrsi3`, `__ashrsi3`, `__divmodsi_setup`) to read arg0_hi
|
||
from X (and shifted arg1 offsets).
|
||
- **Implicit Defs/Uses on stack-rel MC instructions**: was a
|
||
pre-existing latent bug — `eliminateFrameIndex` strips the
|
||
implicit A/P def/use info when it converts ADCfi/STAfi/etc. to
|
||
the MC form (ADC d,S, STA d,S etc.). Machine Copy Propagation
|
||
then sees stale dataflow and elides necessary TAX/TXA copies.
|
||
Fixed by re-attaching `RegState::Implicit` operands on each
|
||
expanded MC instruction in W65816RegisterInfo::eliminateFrame
|
||
Index. Without this, the i32-A:X ABI miscompiles return values
|
||
(TAX gets elided, X retains arg0_hi instead of result_hi).
|
||
The fix also benefits the existing single-A path; before it,
|
||
certain Machine Copy Propagation choices were unsafe but
|
||
happened not to trigger. Now they're also safe.
|
||
|
||
### Currently still pending
|
||
|
||
- **REP/SEP scheduling pass** (Step 4) — per-function mode only;
|
||
mixed-mode functions don't work.
|
||
- **Vararg functions** — `LowerFormalArguments` reports a fatal
|
||
error.
|
||
- **i32 comparison** — uses SETCC+ADD-of-bool instead of a CMP+SBC
|
||
chain (analogous to the ADC chain we landed for add/sub).
|
||
- **Regalloc** (#56) — heapify-style functions with 4+ live i16
|
||
values run out of A.
|
||
|
||
### Smoke-test coverage (31 checks as of 2026-04-28)
|
||
|
||
`scripts/smokeTest.sh` covers: target registration, llvm-mc encode/
|
||
disassemble, end-to-end IR→ELF, multi-pattern function, single-arg
|
||
call, 3-arg stack reads, pure-i8 SEP prologue, multi-branch SETCC,
|
||
SELECT_CC, two-Acc16 spill, libcall emission (__mulhi3/__ashlhi3),
|
||
pointer load/store, runtime/build.sh, real-world program,
|
||
libcall-symbol coverage, signed/eq i8 compare, -O2 tiny C, i32 add
|
||
end-to-end, i32 carry-chain shape (1 clc + 2 adc + 0 bcc), i32
|
||
A:X first-arg ABI (1 txa), 32-bit fib loop (ADDE_RR inserter),
|
||
__mulsi3 libcall, alloca'd-array LEA, signed-byte strcmp
|
||
(sextload + sext_inreg + extload-via-ptr), indirect call via
|
||
__jsl_indir trampoline, i32 shift-by-1 inline (no hi3 libcall).
|
||
|
||
## 3. What is installed and where
|
||
|
||
All under `/home/scott/claude/llvm816/tools/`:
|
||
|
||
| Tool | Path | Notes |
|
||
|---|---|---|
|
||
| llvm-mos source | `tools/llvm-mos/` | shallow clone. Backend files are symlinked in from `src/`; patches applied on top. Reset cleanly via `scripts/updateLlvmMos.sh`. |
|
||
| llvm-mos build dir | `tools/llvm-mos-build/` | cmake-generated, ephemeral |
|
||
| llvm-mos-sdk | `tools/llvm-mos-sdk/` | prebuilt toolchain |
|
||
| MAME 0.264 | `/usr/games/mame` (apt) | supports `-console` (Lua) |
|
||
| Apple IIgs ROMs | `tools/mame/roms/apple2gs.zip`, `apple2gsr1.zip` | from archive.org |
|
||
| Calypsi 5.16 | `tools/calypsi/` | extracted .deb |
|
||
| ORCA/C source | `tools/orca-c/` | reference only |
|
||
|
||
`./setup.sh --verify-only` passed all checks as of the prior session.
|
||
|
||
## 4. Repo layout (current)
|
||
|
||
```
|
||
llvm816/ # git repo, branch main
|
||
├── LLVM_65816_DESIGN.md # tracked
|
||
├── SESSION_STATE.md # this file
|
||
├── setup.sh # tracked
|
||
├── scripts/ # tracked
|
||
│ ├── common.sh
|
||
│ ├── installDeps.sh installCalypsi.sh installOrcaC.sh
|
||
│ ├── installLlvmMos.sh # non-destructive (see §8)
|
||
│ ├── installMame.sh verify.sh
|
||
│ ├── applyBackend.sh # src/ + patches/ -> tools/llvm-mos/
|
||
│ └── updateLlvmMos.sh # reset clone, re-apply backend
|
||
├── src/ # authored files, tracked
|
||
│ ├── llvm/lib/Target/W65816/ # 41 files
|
||
│ │ ├── MCTargetDesc/ (10 files)
|
||
│ │ ├── TargetInfo/ (3 files)
|
||
│ │ └── (28 top-level files)
|
||
│ └── clang/lib/Basic/Targets/
|
||
│ ├── W65816.h
|
||
│ └── W65816.cpp
|
||
├── patches/ # unified diffs, tracked
|
||
│ ├── 0001-triple-add-w65816-arch.patch
|
||
│ ├── 0002-triple-cpp-add-w65816-cases.patch
|
||
│ ├── 0003-clang-basic-dispatch-w65816.patch
|
||
│ └── 0004-cmake-add-w65816-experimental.patch
|
||
├── tools/ # gitignored, ephemeral
|
||
└── .gitignore # excludes tools/, .cache/
|
||
```
|
||
|
||
## 5. Key architectural decisions
|
||
|
||
### 5.1 Separate target, not MOS subtarget feature
|
||
|
||
llvm-mos has `FeatureW65816` declared in `MOSDevices.td` but codegen
|
||
unimplemented (issue #321). We are NOT extending MOS. Reasons:
|
||
- We cannot upstream an AI-assisted backend to llvm-mos anyway.
|
||
- Clean register model: `Acc8`/`Acc16`/`Idx8`/`Idx16` as separate classes.
|
||
- Independent evolution.
|
||
|
||
Recorded in design doc §2.5.
|
||
|
||
### 5.2 Symlinks + patches, not a fork
|
||
|
||
`applyBackend.sh` symlinks every file under `src/` into the corresponding
|
||
path under `tools/llvm-mos/`, then applies each `patches/*.patch` with
|
||
`git apply`. Idempotent: skips already-current symlinks and
|
||
already-applied patches (detected via `git apply --reverse --check`).
|
||
|
||
`updateLlvmMos.sh` is the ONLY script allowed to destructively reset the
|
||
clone. It reverses all patches, removes our symlinks, `git reset --hard
|
||
FETCH_HEAD`, then re-runs `applyBackend.sh`.
|
||
|
||
`installLlvmMos.sh` refuses to touch the clone if it is dirty or off
|
||
main — this is deliberate to protect applied patches.
|
||
|
||
## 6. Concrete next actions (in order)
|
||
|
||
### 6.1 Function arguments
|
||
|
||
`LowerFormalArguments` and `LowerCall` still fatal-error. Without
|
||
arguments, every function we test has to use globals as inputs. The
|
||
plan: pass i8/i16 args via the stack (push right-to-left, caller
|
||
cleans), with the first 1-2 args optionally going in A or X for
|
||
register-passing. Calypsi output is the reference for ABI choices.
|
||
|
||
### 6.2 i8 codegen
|
||
|
||
Currently every function gets `REP #$30` (16-bit mode). For i8 ops
|
||
we need either:
|
||
|
||
- A scan-and-prepend approach: if the function has any i8 op, emit
|
||
`SEP #$20` after the REP for whichever mode dominates, plus
|
||
toggle pseudos around the off-mode regions.
|
||
- Or commit to widening all i8 to i16 pre-ISel (simpler, but uses 2x
|
||
the cycles for byte-heavy code).
|
||
|
||
This is the natural lead-in to the REP/SEP scheduling pass (§6.4).
|
||
|
||
### 6.3 Frame indices, stack locals
|
||
|
||
Add `eliminateFrameIndex` and frame-pointer pseudos so we can spill
|
||
to the stack. Today `W65816RegisterInfo::eliminateFrameIndex` is
|
||
`llvm_unreachable`. Stack accesses on 65816 are `,s` and `(,s),y`
|
||
indirect — needs new operand classes.
|
||
|
||
### 6.4 REP/SEP scheduling pass
|
||
|
||
The core algorithmic work. TSFlag bits on every mode-dependent
|
||
instruction are already in place; the pass walks MIR, dataflows the
|
||
required mode per region, and inserts/removes REP/SEP transitions to
|
||
minimise total mode switches. Design doc §3.3.
|
||
|
||
### 6.2 Wire frame lowering + calling convention (real)
|
||
|
||
`W65816FrameLowering.cpp` is still `llvm_unreachable`. The simplest
|
||
working version: establish an i16 stack pointer-based frame using the
|
||
native SP, locals accessed via stack-relative indirect via Y. Calypsi
|
||
output for a trivial function is a good model.
|
||
|
||
`W65816CallingConv.td` covers i8/i16 return in A but nothing for
|
||
arguments. Start with stack-based (push right-to-left, caller cleans)
|
||
per design doc §3.5.
|
||
|
||
### 6.3 Disassembler mode-aware decoding (deferred)
|
||
|
||
The scaffold disassembler always decodes LDA/LDX/LDY/ADC/SBC/CMP/AND/
|
||
ORA/EOR/BIT/CPX/CPY immediate forms as 3-byte 16-bit-immediate
|
||
variants. A real decoder should track the M/X bits across the stream
|
||
(consuming REP/SEP, XCE transitions) and choose between
|
||
`DecoderTableW65816` (default) and `DecoderTableW65816{MHigh,XHigh}16`
|
||
per instruction. Naturally pairs with the REP/SEP codegen pass since
|
||
both need the same M/X tracking model.
|
||
|
||
### 6.4 REP/SEP scheduling pass
|
||
|
||
The core algorithmic work (design doc §3.3). Every real instruction
|
||
now carries TSFlag bits indicating which M/X mode it requires. The
|
||
pass reads those, does the width-inference / coalescing / transition
|
||
insertion dataflow, and emits REP/SEP instructions at block
|
||
boundaries. Plan to spend multiple sessions.
|
||
|
||
### 6.5 Tidy-ups (can happen in any order)
|
||
|
||
- Decide ELF `EM_` value (§7 item 1). Currently `EM_NONE`, with
|
||
placeholder relocation numbers 1-5 in `W65816ELFObjectWriter`.
|
||
Swap for canonical `R_W65816_*` names once chosen.
|
||
- Replace ASCII-art mnemonics (`inc a`, `dec a`, `asl a`, etc.) with
|
||
proper InstAliases so both `INA` and `INC A` assemble to the same
|
||
opcode. Requires AsmParser (§6.3).
|
||
|
||
## 7. Open design questions flagged by the scaffold
|
||
|
||
1. **ELF `EM_` machine number.** `W65816ELFObjectWriter.cpp` uses
|
||
`ELF::EM_NONE` as a placeholder. llvm-mos uses `EM_MOS = 0x1966` for
|
||
the 6502 family. Decide: share `EM_MOS`, or pick a new value?
|
||
2. **Data layout string** is hardcoded in
|
||
`W65816TargetMachine.cpp` rather than routing through
|
||
`Triple::computeDataLayout()`. That is OK for now — when we're
|
||
ready to consolidate, add a case in `TargetDataLayout.cpp` and
|
||
switch to `TT.computeDataLayout()`.
|
||
3. **i32 return convention** — does i32 return in A:X or via a hidden
|
||
pointer? Currently `W65816CallingConv.td` only handles i8/i16. Design
|
||
doc §3.5 says "A:X for 32-bit" but this isn't modelled yet.
|
||
4. **Register aliasing for mode-dependent widths.** `Acc8` and `Acc16`
|
||
both contain physical register `A`. LLVM's allocator will not cope
|
||
with this correctly. The REP/SEP management pass (§3.3) is required.
|
||
Flagged per the design doc.
|
||
5. **Open questions from design doc §8** (GS/OS DP reservation, bank
|
||
memory model, interrupt ABI, ORCA/C ABI compat, width-contract
|
||
attribute, MAME cycle accuracy) — still unresolved. Punt until after
|
||
we have a working instruction set.
|
||
|
||
## 8. Gotchas + hard-won knowledge
|
||
|
||
- **`installLlvmMos.sh` is non-destructive now.** It refuses to reset
|
||
the clone if it is dirty or off main. Use `scripts/updateLlvmMos.sh`
|
||
to refresh (the only script allowed to reset).
|
||
- **MAME `-console` flag** is listed by `-showusage`, NOT `-help`.
|
||
- **`log()` in `common.sh` writes to stderr.** Don't change it.
|
||
- **llvm-mos has `FeatureW65816` but not working codegen** (issue #321).
|
||
- **`RemapAllTargetPseudoPointerOperands<PtrRegs>` is required** in
|
||
`W65816.td` or tablegen fails with 8 "missing target override for
|
||
pseudoinstruction using PointerLikeRegClass" errors. Don't remove it.
|
||
- **`Triple::w65816` placement in Triple.h:** inserted right after
|
||
`mos,` to keep the 65xx family clustered. See patch 0001.
|
||
- **Added to `LLVM_ALL_EXPERIMENTAL_TARGETS`** in `llvm/CMakeLists.txt`
|
||
so `-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=all` picks up W65816. Not
|
||
strictly required — passing the name explicitly also works.
|
||
- **Operand `OperandType` field wants LLVM's enum spelling**, not
|
||
shortened. Use `OPERAND_IMMEDIATE`, `OPERAND_MEMORY`, `OPERAND_PCREL`
|
||
(see `llvm/include/llvm/MC/MCInstrDesc.h` MCOI::OperandType).
|
||
`OPERAND_IMM` / `OPERAND_IMM8` / `OPERAND_IMM16` are NOT valid.
|
||
- **`PrintMethod` signature for PC-rel operands takes `Address`.**
|
||
Tablegen generates `printPCRel8(MI, Address, OpNo, O)` — 4 args, not
|
||
3. Non-PC-rel PrintMethods use the 3-arg form `(MI, OpNo, O)`.
|
||
- **Several `.cpp` files needed explicit `#include`s beyond what MSP430
|
||
ships with** because the tablegen-generated `.inc` references full
|
||
types: `W65816RegisterInfo.cpp` needs `W65816Subtarget.h` and
|
||
`W65816FrameLowering.h` (for `GET_REGINFO_TARGET_DESC`);
|
||
`W65816InstPrinter.cpp` needs `llvm/MC/MCAsmInfo.h` (for
|
||
`MAI.printExpr`).
|
||
- **Marker classes can't override mayLoad/mayStore via `let`.**
|
||
TableGen's multi-inheritance doesn't let unrelated sibling classes
|
||
touch fields from the base `Instruction`. Use `let isReturn = 1, ...
|
||
in { ... }` blocks at def sites instead (idiomatic LLVM style).
|
||
- **Data layout is hardcoded** in `W65816TargetMachine.cpp` rather than
|
||
computed from `TT.computeDataLayout()`, because `TargetDataLayout.cpp`
|
||
doesn't have a case for `w65816` yet. This produces one `-Wswitch`
|
||
warning in the llvm-mos build. §6.5 notes adding a 5th patch to
|
||
silence it.
|
||
|
||
## 9. Disk space recovery
|
||
|
||
If space is tight before resume:
|
||
|
||
```
|
||
# safe to delete — regenerable from setup.sh + applyBackend.sh:
|
||
rm -rf /home/scott/claude/llvm816/tools/
|
||
rm -rf /home/scott/claude/llvm816/.cache/
|
||
```
|
||
|
||
Regenerate with `./setup.sh` then `./scripts/applyBackend.sh`.
|
||
|
||
The `tools/llvm-mos-build/` directory alone is ~2 GB after a full
|
||
configure+tablegen. A full ninja build will be much more.
|
||
|
||
## 10. Quick verification commands for resume
|
||
|
||
```
|
||
# Verify the scaffold is in place:
|
||
ls src/llvm/lib/Target/W65816/ | wc -l # expect ~20 top-level files
|
||
ls patches/ # expect 4 .patch files
|
||
|
||
# Verify apply is clean:
|
||
./scripts/applyBackend.sh # expect 0 new, 44 current symlinks; 0 new, 4 applied patches
|
||
|
||
# Verify cmake configures:
|
||
cmake -S tools/llvm-mos/llvm -B tools/llvm-mos-build -G Ninja \
|
||
-DCMAKE_BUILD_TYPE=Release \
|
||
-DLLVM_TARGETS_TO_BUILD="" \
|
||
-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD="MOS;W65816" \
|
||
-DLLVM_ENABLE_PROJECTS="clang" \
|
||
-DLLVM_INCLUDE_TESTS=OFF -DLLVM_INCLUDE_EXAMPLES=OFF \
|
||
-DLLVM_INCLUDE_BENCHMARKS=OFF
|
||
|
||
# Verify full build + llc registration (slow first time, cached after):
|
||
( cd tools/llvm-mos-build && ninja LLVMW65816Info LLVMW65816Desc LLVMW65816CodeGen llc )
|
||
./tools/llvm-mos-build/bin/llc --version | grep w65816
|
||
./tools/llvm-mos-build/bin/llc -march=w65816 -filetype=null /dev/null ; echo $?
|
||
# Expect: grep matches; llc exits 0.
|
||
```
|
||
|
||
## 11. Files changed this session (not yet committed by user)
|
||
|
||
```
|
||
scripts/applyBackend.sh # idempotent src+patches apply
|
||
scripts/updateLlvmMos.sh # safe reset+reapply
|
||
scripts/installLlvmMos.sh # no longer destructively resets
|
||
scripts/smokeTest.sh # regression smoke test
|
||
src/llvm/lib/Target/W65816/ # full MC layer + first codegen:
|
||
# CodeGen scaffolds (~40 files)
|
||
# AsmParser/ (2 files)
|
||
# Disassembler/ (2 files)
|
||
# MCTargetDesc/ (11 files)
|
||
# TargetInfo/ (3 files)
|
||
# ~90 real instruction defs
|
||
# ~25 codegen pseudos +
|
||
# AsmPrinter expansion
|
||
src/clang/lib/Basic/Targets/W65816.{h,cpp}
|
||
patches/0001..0005.patch # upstream llvm-mos mods
|
||
SESSION_STATE.md # this file
|
||
```
|
||
|
||
The tools/ tree is all ephemeral (gitignored).
|
||
|
||
### What now works end-to-end
|
||
|
||
Try it yourself:
|
||
|
||
```
|
||
./scripts/cDemo.sh # built-in demo
|
||
./scripts/cDemo.sh path/to/your.c
|
||
```
|
||
|
||
Sample output for the built-in demo (real C → real 65816):
|
||
|
||
```
|
||
get_counter: lda counter ; rtl
|
||
set_counter: sta counter ; rtl
|
||
sum_with_target: clc ; adc target ; rtl
|
||
doubler: asl a ; rtl
|
||
half: lsr a ; rtl
|
||
reset: lda #0 ; sta counter ; rtl
|
||
answer: lda #42 ; rtl
|
||
```
|
||
|
||
### Detail: command-line invocations
|
||
|
||
```
|
||
# Round-trip asm -> bytes -> asm:
|
||
echo ' lda #0x1234' | ./bin/llvm-mc -arch=w65816 -show-encoding
|
||
# -> lda #0x1234 ; encoding: [0xa9,0x34,0x12]
|
||
|
||
echo '0xea 0xa9 0x34 0x12 0x6b' | ./bin/llvm-mc --disassemble --triple=w65816
|
||
# -> nop ; lda #0x1234 ; rtl
|
||
|
||
# Full asm -> ELF -> disasm:
|
||
./bin/llvm-mc -arch=w65816 -filetype=obj foo.s -o foo.o
|
||
./bin/llvm-objdump --triple=w65816 -d foo.o
|
||
|
||
# Real codegen. This .ll compiles cleanly:
|
||
@x = global i16 0
|
||
@y = global i16 0
|
||
define i16 @fib_step() {
|
||
%a = load i16, ptr @x
|
||
%b = load i16, ptr @y
|
||
%s = add i16 %a, %b
|
||
store i16 %a, ptr @y
|
||
store i16 %s, ptr @x
|
||
ret i16 %s
|
||
}
|
||
# llc emits idiomatic 65816:
|
||
# rep #0x30
|
||
# lda x; clc; adc y ; A = a + b
|
||
# sta x ; x = a + b
|
||
# ...
|
||
```
|
||
|
||
### What doesn't work yet
|
||
|
||
- **Multi-arg calls** (caller side). Callee accepts stack-passed
|
||
args; the matching push side is unimplemented. Functions with
|
||
more than one arg can be defined and compile correctly, but
|
||
cannot be called from another function.
|
||
- **Two-Acc16 cmp.** Loops with PHIs that need to compare two
|
||
computed values fail at ISel — only one A.
|
||
- **i8 ops** (always 16-bit mode for now).
|
||
- **Signed overflow** in CMP-based branches: BMI/BPL test the N flag
|
||
of the subtraction, which is incorrect when the subtract overflows.
|
||
- **`mul var, var`** (or by non-power-of-2 constants). Needs library
|
||
functions (`__mulhi3` etc.).
|
||
- **`sub imm, var`** (only `sub var, imm` works).
|
||
|
||
See §6.1-§6.4 for the next steps.
|