1
0
Fork 0
mirror of https://github.com/imjasonh/nescript synced 2026-07-08 08:55:38 +00:00

analyzer+codegen: lift the 4-param ceiling via a direct-write calling convention

Follow-up to the silent-drop audit. The old ABI passed every
parameter through four fixed zero-page transport slots `$04-$07`,
imposing a hard 4-param cap (E0506) that didn't compose with
structs/arrays/u16s and fell back to "pack args into a global"
workarounds whenever a function needed five things. The transport
scheme also cost every non-leaf call a 4-LDA/STA spill prologue
(~28 cycles, 16 bytes) to copy args out of ZP before the next
nested `JSR` could clobber them.

Replace it with a hybrid convention keyed on leaf-ness:

- **Leaf callees** (no nested `JSR` in body, ≤4 params):
  unchanged. Caller stages args into `$04-$07`; body reads those
  slots directly for its entire lifetime. No prologue copy.
  Fastest path, 3-cycle ZP stores + 3-cycle ZP loads, preserves
  the SHA-256 leaf-primitive optimisation that motivated the
  original fast path.

- **Non-leaf callees** (body contains a nested `JSR`, OR ≥5
  params): direct-write. Caller stages each argument straight
  into the callee's analyzer-allocated parameter RAM slot,
  bypassing the transport slots entirely. No prologue copy on
  the callee side. Saves ~24 cycles and ~16 bytes per call vs
  the old transport-then-spill path, and — crucially — scales
  past 4 params because the per-param slots live wherever the
  analyzer put them rather than in a fixed ZP window.

The analyzer's ceiling moves from 4 to 8. Functions with 5–8
params are silently promoted to the non-leaf convention (even if
their body has no nested `JSR`), which pays the direct-write cost
rather than the prologue-copy cost — still cheaper than the old
ABI. Declarations with 9+ params still emit E0506.

### Implementation

- `function_is_leaf` now also requires `param_count <= 4`.
- `IrCodeGen::new` populates `non_leaf_param_addrs: HashMap<String,
  Vec<u16>>` — for every non-leaf function, the ordered list of
  addresses its parameters occupy. Callers use this to route each
  arg directly to the right slot.
- `IrOp::Call` branches on presence in the map: non-leaf → direct-
  write, leaf (or absent — 0-arg case) → ZP transport.
- `gen_function` no longer emits a prologue. Leaves didn't have
  one; non-leaves had a 4-LDA/STA copy that is now unnecessary
  because args arrive pre-written to the slot.
- The previous `leaf_functions: HashSet<String>` field is
  removed; leaf-ness is now inferred from absence-in-
  `non_leaf_param_addrs` at the call site.

### Tests and regressions

- `eight_param_non_leaf_function_stages_every_arg_at_its_allocated_slot`
  compiles an 8-param function, scans PRG for a distinct
  `LDA #\$NN / STA <addr>` per arg (immediates `0x11..0x88`), and
  asserts that STAs to the `$04-$07` range are strictly fewer
  than 8 — proof the old transport path is gone for this call.
- `non_leaf_call_direct_writes_args_to_callee_param_slots`
  replaces the old `gen_function_prologue_spills_params_to_local_ram`
  test with a dual assertion: (a) no `LDA \$04` prologue at the
  callee entry, and (b) the caller-side STA lands at the
  analyzer-allocated param slot, not at `\$04-\$07`.
- `analyze_rejects_function_with_more_than_4_params` renamed and
  rewritten for the new 8-param cap.
- `feature_canary.ne` gains a 6-param `sum6` call (1+2+3+4+5+6 =
  21) as check 8. The canary stays green (all eight checks
  pass), so the committed golden is unchanged.

### Blast radius

- Six example ROMs change bytes (arrays_and_functions, function_chain,
  mmc1_banked, pong, sha256, war) because their non-leaf call sites
  pick up the shorter staging sequence.
- Pong and war audio hashes refresh (pure layout-timing shift; no
  behavioural change in the 180-frame no-input window). docs/pong.gif
  and docs/war.gif stay byte-identical.
- `examples/function_chain.ne`'s header comment updated to
  document the leaf vs non-leaf split it exercises.
- `docs/language-guide.md` parameter-count section and E0506 entry
  updated to reflect the new rule.

All 720 Rust tests pass; all 35 emulator goldens pass.

https://claude.ai/code/session_01AoQ678uVeqpyayvWHpfDhC
This commit is contained in:
Claude 2026-04-18 02:34:56 +00:00
parent ee3dddb19e
commit 0602fd9590
No known key found for this signature in database
17 changed files with 364 additions and 156 deletions

View file

@ -1 +1 @@
6c171f3d 132084
6afbe82b 132084

View file

@ -1 +1 @@
60d2ce9d 132084
b054facb 132084

View file

@ -335,6 +335,97 @@ fn program_with_u16_struct_field() {
rom::validate_ines(&rom_data).expect("should be valid iNES");
}
#[test]
fn eight_param_non_leaf_function_stages_every_arg_at_its_allocated_slot() {
// Non-leaf functions use direct-write calling convention: the
// caller stages each argument at the callee's analyzer-
// allocated parameter slot, bypassing the four-slot `$04-$07`
// transport. That lifts the 4-param ceiling to 8 (E0506) and
// saves the old prologue's ~28 cycles per call.
//
// Verify end-to-end by compiling a function that takes eight
// distinct u8 params (so any cross-wiring would show up) and
// writes each to a distinct global. Then scan the PRG for an
// `LDA #N / STA <slot>` pair per arg — eight different
// immediates, eight different destination slots. The eight
// immediates `0x11..0x88` are chosen to be visually
// distinctive and unlikely to appear as incidental runtime
// constants.
let source = r#"
game "EightParams" { mapper: NROM }
var g0: u8 = 0
var g1: u8 = 0
var g2: u8 = 0
var g3: u8 = 0
var g4: u8 = 0
var g5: u8 = 0
var g6: u8 = 0
var g7: u8 = 0
fun spread(a: u8, b: u8, c: u8, d: u8, e: u8, f: u8, g: u8, h: u8) {
g0 = a
g1 = b
g2 = c
g3 = d
g4 = e
g5 = f
g6 = g
g7 = h
}
on frame {
spread(0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88)
}
start Main
"#;
let rom_data = compile(source);
let prg = &rom_data[16..16 + 16384];
// For each of the eight immediates, require at least one
// `LDA #imm / STA <addr>` pair anywhere in PRG. The STA
// target can be zero-page ($85) or absolute ($8D); we don't
// pin down which because the analyzer picks the cheapest
// slot available.
for imm in [0x11u8, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88] {
let found = prg
.windows(4)
.any(|w| w[0] == 0xA9 && w[1] == imm && (w[2] == 0x85 || w[2] == 0x8D));
assert!(
found,
"expected an LDA #${imm:02X} / STA <addr> pair for argument \
staging if this fails, the 8-param non-leaf call is \
dropping args again"
);
}
// Belt-and-braces: in the OLD ABI every arg first got
// staged to $04-$07 (four ZP addresses). The new ABI stages
// *nothing* to those addresses for this call (spread has
// more than four params, so it's forced non-leaf, so direct-
// write). If someone re-introduces the old transport path,
// we'd see STA $04/$05/$06/$07 pairs. Assert absence.
for transport_slot in 0x04..=0x07u8 {
let any_store = prg
.windows(2)
.any(|w| w[0] == 0x85 && w[1] == transport_slot);
// The runtime itself may write to $04-$07 (they're not
// reserved outside of this calling convention), so we
// can't assert zero globally. Just require that the
// number of STA-to-transport stores is strictly smaller
// than the 8 args — if the old transport path were
// active we'd see eight extra such stores.
let _ = any_store; // intentional: see count check below
}
let transport_sta_count = prg
.windows(2)
.filter(|w| w[0] == 0x85 && (0x04..=0x07).contains(&w[1]))
.count();
assert!(
transport_sta_count < 8,
"the 8-param call should NOT stage any arg through the \
`$04-$07` transport slots under the direct-write ABI; saw \
{transport_sta_count} `STA $04-$07` instructions total in PRG"
);
}
#[test]
fn transition_dispatches_leaving_states_on_exit_handler() {
// `on exit` handlers used to be silently never called — the