@asmlift/core 0.9.0 → 0.11.0

package/src/frontend/stackargs.ts

@@ -15,7 +15,7 @@
  *  that matter — a sub-word or register-offset access is not a slot, and one anywhere turns the
  *  whole word-slot model off at the same gate this analysis's `blocker` feeds, so no access that
  *  could alias a licensed word is ever silently missing from the events. */
-export type StackArgsEvent<C> = StackArgsSlot | StackArgsCall<C>;
+export type StackArgsEvent<C> = StackArgsSlot | StackArgsCall<C> | StackArgsEscape;
 
 /** A whole-word access to a reserved frame slot at `off`, which must lie inside `[0, localArea)`. */
 export interface StackArgsSlot {
@@ -23,11 +23,25 @@ export interface StackArgsSlot {
   readonly off: number;
 }
 
+/** A frame address `sp + off` LEAVING this function — in an argument register at a call, or stored
+ *  to memory a device or another function reads. Its receiver may read the frame from `off` up, so
+ *  a word there that this function stored and never reloads has been read, by the receiver.
+ *
+ *  Emitted only under `compilerBehaviors.escapedFrameAddressNamesALocal`: that premise is what
+ *  makes the words from `off` up a local's rather than an argument area's. It ends only what is
+ *  pending WHERE it fires, never a word staged after it, and the field says why that is the safe
+ *  reading of a whole-function layout fact (a block copy's base escapes too). */
+export interface StackArgsEscape {
+  readonly kind: 'escape';
+  readonly off: number;
+}
+
 /** A call, and what its callee's DECLARATION says it takes on the stack. `declared` is the block
  *  `[0, 4*(n - argRegs))` as an ascending offset list, or null when nothing declares this call —
  *  an indirect call, a callee with no prototype, or one whose arity fits in registers. The code
- *  alone cannot say where a null declaration's block ENDS, so such a call is never handed a stack
- *  word; it lifts only when `survivorBound` clears every word that could open one. */
+ *  alone cannot say where a null declaration's block ENDS, so such a call is handed a stack word
+ *  only where its callee's body says where it starts (`bodyReads`); otherwise it lifts only when
+ *  `loadedWordBound` clears every word that could open one. */
 export interface StackArgsCall<C> {
   readonly kind: 'call';
   /** The frontend's own handle for this call — the key of `OutgoingArgs.blocks`. */
@@ -38,6 +52,11 @@ export interface StackArgsCall<C> {
   /** The parameters the declaration lists, for the refusal messages — fewer than its words when a
    *  64-bit parameter takes two or a hidden struct-return pointer takes one. Absent, one per word. */
   readonly params?: number;
+  /** Where nothing declares the call: one past the highest word of its incoming stack area the
+   *  callee's own body is proven to load (frontend/callee-body.ts `CalleeStackWords`), a LOWER bound
+   *  on its stack words — asked, since it may lift the callee, only where [sp,#0] is stored and never
+   *  loaded (`analyzeOutgoingArgs`). Absent, or answering 0 or nothing, the body proves nothing. */
+  readonly bodyReads?: () => number | undefined;
 }
 
 /** One basic block's events. Where control goes afterwards is read out of `preds`, so a block is
@@ -60,10 +79,12 @@ export interface StackArgsInput<C> {
   readonly argRegs: number;
   /** The frontend's verdict that the whole frame is one addressable object handed to a callee. */
   readonly capturedWholeFrame: boolean;
-  /** The compiler keeps ONE outgoing area at the bottom of the frame, sized for its widest call and
-   *  below every local, and never reads a word of it back after a call. Only then does a word
-   *  loaded after a call prove itself a local — see `survivorBound`. */
-  readonly localsAboveOutgoingArea: boolean;
+  /** The lowest frame word this function loads where its compiler loads no word of the outgoing
+   *  area, before a call or after (`target.ts` `outgoingAreaNeverLoadedFrom`, the strong form of
+   *  `localsAboveOutgoingArea`, 0 on agbcc): `loadedWordBound` over these blocks, which the frontend
+   *  computes once and hands the frame-object audit too. Every word at or above it is a local's.
+   *  `Infinity` where the compiler claims no such offset. */
+  readonly loadedWordBound: number;
 }
 
 /** What this function's calls do with the BOTTOM of its frame — the outgoing stack-argument area
@@ -82,45 +103,35 @@ export interface OutgoingArgs<C> {
 }
 
 const isCallEvent = <C>(ev: StackArgsEvent<C>): ev is StackArgsCall<C> => ev.kind === 'call';
+const isSlotEvent = <C>(ev: StackArgsEvent<C>): ev is StackArgsSlot => ev.kind === 'store' || ev.kind === 'load';
 
-/** THE LOWEST FRAME WORD THAT SURVIVES A CALL, or `Infinity` when none does. A word LOADED on some
- *  path out of a live call before anything re-stores it held a value across that call. Under
- *  `localsAboveOutgoingArea` the caller never reads its outgoing area back after a call, so that
- *  word is a local; and since the area is one region at the frame bottom that every call shares,
- *  every word at or above the bound is proven not to be an argument.
+/** THE LOWEST FRAME WORD THIS FUNCTION LOADS AT OR ABOVE `from`, or `Infinity` when it loads none
+ *  or nothing states `from`. The Thumb frontend calls it once per lift and hands the number to both
+ *  readers: `analyzeOutgoingArgs` and the frame-object audit (`FrameObjectAudit.loadedWords`).
+ *  Under `outgoingAreaNeverLoadedFrom` the caller never reads a word of its outgoing area from that
+ *  offset up — not after a call, where the callee may have assigned to it, and not before one
+ *  either: the area holds only what the caller staged for a callee, every argument that contains a
+ *  call is computed before any word is staged, and nothing is saved there around a nested call
+ *  (agbcc-restage.s pins all three). So a word it loads is a local; and since the area is one
+ *  region at the frame bottom that every call shares, every word at or above the bound is proven
+ *  not to be an argument.
  *
- *  A backward liveness over the live blocks: a load makes its offset live, a store kills it, and a
- *  call is transparent — a word read after two calls survived both. Dead blocks contribute nothing:
- *  a load that cannot run proves nothing, and a call that cannot run is not a call it survived. */
-function survivorBound<C>(
+ *  Only a load in a live block counts: a load that cannot run proves nothing. An ESCAPE does not
+ *  count: its receiver MAY read the words, and a bound is a proof, which a read that may not happen
+ *  cannot supply. */
+export function loadedWordBound<C>(
   blocks: readonly StackArgsBlock<C>[],
-  succs: readonly (readonly number[])[],
   live: ReadonlySet<number>,
+  from: number | undefined,
 ): number {
-  const liveIn = blocks.map(() => new Set<number>());
-  const liveOut = (b: number): Set<number> => new Set(succs[b].flatMap((s) => [...liveIn[s]]));
+  if (from === undefined) {
+    return Infinity;
+  }
   let bound = Infinity;
-  for (let changed = true; changed;) {
-    changed = false;
-    for (let b = blocks.length - 1; b >= 0; b--) {
-      if (!live.has(b)) {
-        continue;
-      }
-      const cur = liveOut(b);
-      for (const ev of [...blocks[b].events].reverse()) {
-        if (isCallEvent(ev)) {
-          for (const o of cur) {
-            bound = Math.min(bound, o);
-          }
-        } else if (ev.kind === 'load') {
-          cur.add(ev.off);
-        } else {
-          cur.delete(ev.off);
-        }
-      }
-      if ([...cur].some((o) => !liveIn[b].has(o))) {
-        liveIn[b] = cur;
-        changed = true;
+  for (const b of live) {
+    for (const ev of blocks[b].events) {
+      if (ev.kind === 'load' && ev.off >= from) {
+        bound = Math.min(bound, ev.off);
       }
     }
   }
@@ -164,14 +175,14 @@ function survivorBound<C>(
 // and (b) below, kept for every call no declaration covers).
 //
 // A THIRD WITNESS SAYS WHERE THE AREA ENDS, and it only ever clears words. Under a compiler that
-// keeps one outgoing area below every local and never reads it back after a call
-// (`localsAboveOutgoingArea`), a word LOADED after a call before any re-store is a local, and so
-// is every word above it (`survivorBound`). Every refusal that reads the code — NOTHING EXTRA,
-// (a) and (b) — then weighs only the words beneath the bound, so an undeclared call lifts once no
-// word there could open an argument block, and takes no stack word. Hand-written asm that reads
-// its own outgoing argument back after a call defeats it, and lifts with that argument dropped — a
-// producer assumption of the same kind as CONTIGUITY below, which is why the premise is declared
-// per compiler (`target.ts` `localsAboveOutgoingArea`) and never inferred.
+// keeps one outgoing area below every local and never loads a word of it
+// (`outgoingAreaNeverLoadedFrom`), a word this function LOADS is a local, and so is every word above it
+// (`loadedWordBound`). Every refusal that reads the code — NOTHING EXTRA, (a) and (b) — then
+// weighs only the words beneath the bound, so an undeclared call lifts once no word there could
+// open an argument block, and takes no stack word. Hand-written asm that reads its own outgoing
+// argument defeats it, and lifts with that argument dropped — a producer assumption of the same
+// kind as CONTIGUITY below, which is why the premise is declared per compiler (`target.ts`
+// `outgoingAreaNeverLoadedFrom`) and never inferred.
 //
 // THE TWO SIDES ARE CHECKED AGAINST DIFFERENT SETS, and the asymmetry is the point.
 //   * NOTHING EXTRA is checked against the MAY set (stored and unreloaded on SOME path): the
@@ -183,12 +194,12 @@ function survivorBound<C>(
 //     must never render as a plausible value.
 //
 // A SPILL LIVE ACROSS A LICENSED CALL sits in the may set and is not in the declared block — agbcc's
-// commonest frame with an outgoing area. The declaration cannot excuse it; `survivorBound` can: a
-// word loaded after a call before any re-store is a local, so NOTHING EXTRA counts only the pending
-// words beneath the bound. A declared block that reaches the bound contradicts it, and needs no
-// check of its own: the block is contiguous words from zero, so it holds the bound's word, which
-// this function loads — "this function also LOADS it" below refuses it if nothing earlier does.
-// A spill with no survivor at or beneath it still refuses, and its decline names a STORE ("[sp,#k]
+// commonest frame with an outgoing area. The declaration cannot excuse it; `loadedWordBound` can: a
+// word this function loads is a local, so NOTHING EXTRA counts only the pending words beneath the
+// bound. A declared block that reaches the bound contradicts it, and needs no check of its own:
+// the block is contiguous words from zero, so it holds the bound's word, which this function loads
+// — "this function also LOADS it" below refuses it if nothing earlier does.
+// A spill with no load at or beneath it still refuses, and its decline names a STORE ("[sp,#k]
 // also reaches the call unread") rather than the capability, so a gap histogram groups it under
 // that message.
 // The must set is an intersection over predecessors, which is exactly what a TAIL-MERGED call
@@ -204,8 +215,33 @@ function survivorBound<C>(
 //
 // A LICENSED CALL CONSUMES ITS BLOCK, which is what lets a function make several calls: the
 // callee reads those words, so they stop being pending after it, exactly as a reload would end
-// them. The deletion is driven by the DECLARATION alone, never by the licence, so the fixpoint
-// cannot depend on its own outcome.
+// them. The deletion is driven by the DECLARATION (or the body's reads, below) alone, never by the
+// licence, so the fixpoint cannot depend on its own outcome.
+//
+// THE CALLEE'S BODY STANDS IN FOR A MISSING DECLARATION, on one side only. A compiled callee loads
+// incoming stack word k only as its argument |argRegs|+k, so a body proven to load word n-1
+// (`bodyReads` n) takes at least n stack words — a LOWER bound, as a declaration is, and never an
+// upper one: a parameter it does not load, or one it loads past the straight-line entry it was
+// scanned over, is a word it takes all the same. The CODE closes the block from above: the call is
+// licensed only where what reaches it staged, on every path (must) and on some path (may, beneath
+// the loaded-word bound), is exactly `[0, 4n)` — by CONTIGUITY a conforming caller stores every
+// argument word of a call, so a word past the body's reads that it does not stage is no argument.
+// Anything else is the call it was before the witness existed: unlicensed, and refused by (a) or
+// (b) wherever they refused it — so the witness only ever turns a decline into a lift, and only at
+// a call [sp,#0] reached staged, which (b) refused.
+/** THE BODY'S LICENCE, the one rule both ISAs that stage stack arguments decide by (this file's
+ *  dataflow for Thumb, frontend/mips.ts `lowerJal` for O32 over its SSA reaching definitions): a
+ *  call nothing declares, whose callee's body loads `n` incoming stack words, takes exactly those
+ *  `n` where the words staged for it are exactly `[0, 4n)` from the start of the outgoing area —
+ *  `may` the words that reach it pending on SOME path (beneath the loaded-word bound), and `must`
+ *  whether a word reaches it pending on EVERY path. Pending means stored and not consumed since: a
+ *  load, or an earlier call whose block held the word, ends it. Offsets are relative to the area's
+ *  start (0 on agbcc, 16 on O32). */
+export function bodyBlockAgrees(n: number, may: Iterable<number>, must: (off: number) => boolean): boolean {
+  const staged = [...may].sort((x, y) => x - y);
+  return n > 0 && staged.length === n && staged.every((o, i) => o === 4 * i && must(o));
+}
+
 export function analyzeOutgoingArgs<C>({
   blocks: asmBlocks,
   preds,
@@ -213,9 +249,29 @@ export function analyzeOutgoingArgs<C>({
   localArea,
   argRegs,
   capturedWholeFrame,
-  localsAboveOutgoingArea,
+  loadedWordBound: bound,
 }: StackArgsInput<C>): OutgoingArgs<C> {
   const refuse = (blocker: string): OutgoingArgs<C> => ({ blocker, blocks: new Map(), area: 0 });
+  // the block the callee's body proves it reads into, for an undeclared call (`bodyReads`), asked
+  // only where [sp,#0] is stored and never loaded: every block a licence names starts there, and
+  // a load of it puts the loaded-word bound at 0, so no word reaches any call beneath it. A fact of
+  // the code, not of the dataflow, so the fixpoint below never decides which calls ask.
+  const events = asmBlocks.flatMap((ab) => ab.events);
+  const asksBodies =
+    events.some((e) => e.kind === 'store' && e.off === 0) && !events.some((e) => e.kind === 'load' && e.off === 0);
+  const bodyWords = new Map<StackArgsCall<C>, number[]>();
+  const bodyBlock = (ev: StackArgsCall<C>): number[] => {
+    if (ev.declared !== null || ev.bodyReads === undefined || !asksBodies) {
+      return [];
+    }
+    if (!bodyWords.has(ev)) {
+      bodyWords.set(
+        ev,
+        Array.from({ length: ev.bodyReads() ?? 0 }, (_, i) => 4 * i),
+      );
+    }
+    return bodyWords.get(ev)!;
+  };
   // EVERY block, not the entry-reachable ones: a call in dead code stages nothing, so the
   // dataflow below never finds its block and it refuses — which is the verdict it had before
   // consumption existed. An unreachable `bl` is not evidence about the frame either way, and
@@ -230,6 +286,7 @@ export function analyzeOutgoingArgs<C>({
     return { blocker: null, blocks: new Map(), area: 0 };
   }
   const say = (offs: readonly number[]) => offs.map((o) => `[sp,#${o}]`).join(', ');
+  const sayAll = (offs: readonly number[]) => (offs.length === 0 ? 'none' : say(offs));
   const declaredAs = (ev: StackArgsCall<C>, offs: readonly number[]) => {
     const words = argRegs + offs.length;
     return ev.params === undefined || ev.params === words
@@ -242,6 +299,9 @@ export function analyzeOutgoingArgs<C>({
   // that computes it owns which escapes qualify. A declared fifth argument says [sp,#0] is a
   // DIFFERENT callee's argument slot. Two contradictory claims about the same word, and nothing
   // here can decide which to believe, so the honest answer is the decline it has always been.
+  // This is the flow-INSENSITIVE reading of an escape, sound only at one word; the `escape` event
+  // is the per-program-point reading of the same escapes at any frame size, and its contradiction
+  // with a declared block is the "ESCAPED ADDRESS AT OR BELOW A LICENSED WORD" refusal below.
   if (capturedWholeFrame) {
     for (const ev of calls) {
       const offs = ev.declared;
@@ -272,7 +332,6 @@ export function analyzeOutgoingArgs<C>({
   // code-reading refusals below — the licence's NOTHING EXTRA, (a) and (b) — each hunt for a word
   // that could be one, so the words they weigh are cut to those beneath the bound once, where
   // they are collected (`mayAt`, `storedAnywhere`), and none of them repeats the test.
-  const bound = localsAboveOutgoingArea ? survivorBound(asmBlocks, succs, live) : Infinity;
   const belowBound = (s: Iterable<number>): Set<number> => new Set([...s].filter((o) => o < bound));
 
   const everySlot: number[] = [];
@@ -324,7 +383,7 @@ export function analyzeOutgoingArgs<C>({
           mayAt.set(ev, belowBound(may));
           mustAt.set(ev, new Set(must));
           storedAt.set(ev, new Set(stored));
-          for (const o of ev.declared ?? []) {
+          for (const o of ev.declared ?? bodyBlock(ev)) {
             may.delete(o);
             must.delete(o);
           }
@@ -332,9 +391,18 @@ export function analyzeOutgoingArgs<C>({
           may.add(ev.off);
           must.add(ev.off);
           stored.add(ev.off);
-        } else {
+        } else if (ev.kind === 'load') {
           may.delete(ev.off);
           must.delete(ev.off);
+        } else {
+          // the receiver of the escaped address reads what it was handed, so those words stop
+          // being pending exactly as a reload would end them
+          for (const o of everySlot) {
+            if (o >= ev.off) {
+              may.delete(o);
+              must.delete(o);
+            }
+          }
         }
       }
       const grow = (out: Array<Set<number>>, cur: Set<number>): void => {
@@ -376,6 +444,13 @@ export function analyzeOutgoingArgs<C>({
   for (const ev of calls) {
     const offs = ev.declared;
     if (offs === null) {
+      // the body's witness: licensed on exact agreement, else left to (a) and (b) as before
+      const body = bodyBlock(ev);
+      const must = mustAt.get(ev) ?? new Set<number>();
+      if (bodyBlockAgrees(body.length, mayAt.get(ev) ?? [], (o) => must.has(o))) {
+        blocks.set(ev.call, body);
+        area = Math.max(area, 4 * body.length);
+      }
       continue;
     }
     const may = mayAt.get(ev) ?? new Set<number>();
@@ -400,6 +475,24 @@ export function analyzeOutgoingArgs<C>({
       licensed.add(o);
     }
   }
+  // An ESCAPED ADDRESS AT OR BELOW A LICENSED WORD — the one-word captured frame's contradiction,
+  // at any frame size. The escape names the words from its offset up as an object's, a licensed
+  // block names one of them as a callee's argument, and nothing here can decide which to believe.
+  // Under agbcc the two never meet (an address-taken local sits ABOVE the outgoing area, and at
+  // [sp,#0] only when no call takes a stack word), so a function that has both is not agbcc's
+  // layout and declines.
+  const escapes = [...live].flatMap((b) => asmBlocks[b].events.flatMap((ev) => (ev.kind === 'escape' ? [ev.off] : [])));
+  const lowestEscape = Math.min(Infinity, ...escapes);
+  for (const ev of calls) {
+    const offs = blocks.get(ev.call) ?? [];
+    const clash = offs.find((o) => o >= lowestEscape);
+    if (clash !== undefined) {
+      return refuse(
+        `callee \`${ev.callee}\` ${ev.declared === null ? `loads ${offs.length} incoming stack words in its body` : `is declared with ${declaredAs(ev, offs)}`}, so [sp,#${clash}] is its outgoing stack argument — ` +
+          `but the frame address [sp,#${lowestEscape}] escapes this function, so the words from there up are an object's, and the two name the same word`,
+      );
+    }
+  }
   // The two whole-function facts the next two refusals read: every offset live code stores, and
   // every offset live code loads back. A reload in dead code is not evidence that anything reads
   // the slot back, so it does not count.
@@ -407,11 +500,26 @@ export function analyzeOutgoingArgs<C>({
   const stores = new Set<number>();
   for (const b of live) {
     for (const ev of asmBlocks[b].events) {
-      if (ev.kind !== 'call') {
+      if (isSlotEvent(ev)) {
         (ev.kind === 'store' ? stores : reloaded).add(ev.off);
       }
     }
   }
+  // …and a word an escaped address hands over is read by its receiver, which is a reload for (a):
+  // its never being read back HERE is explained by who reads it THERE.
+  //
+  // WHOLE-FUNCTION, unlike the pending sets above: a store after the last escape, or on a path
+  // that never escapes, is excused here too. That is sound because (a) is not what clears a word
+  // for a call. A word that is some call's argument reaches that call pending, and the licence's
+  // equality (a declared callee) or (b) (an undeclared one) refuses it there, per program point:
+  // `qh5`'s fifth `h5` word, staged after its memcpy base escapes, is refused by (b). What this
+  // widening lets through is a store that reaches no call pending with its lower slots supplied,
+  // which by CONTIGUITY (above) no call takes as an argument.
+  for (const o of everySlot) {
+    if (o >= lowestEscape) {
+      reloaded.add(o);
+    }
+  }
   const storedAnywhere = belowBound(stores);
   // A LICENSED WORD THIS FUNCTION ALSO LOADS. The area belongs to the CALLEE — which may assign
   // to a stack parameter — so after the `bl` the word holds whatever the callee left, and an
@@ -432,6 +540,33 @@ export function analyzeOutgoingArgs<C>({
       );
     }
   }
+  // (b)'s question, asked of one call (see (b) below): the refusal, or null where nothing staged
+  // there could open an argument block. A call the body's witness was asked of and did not license
+  // is asked it BEFORE (a), so its decline names both witnesses; (a) would refuse it anyway, or (b)
+  // would, so only the message moves.
+  const pendingAtUndeclared = (ev: StackArgsCall<C>): string | null => {
+    if (ev.declared !== null || blocks.has(ev.call)) {
+      return null;
+    }
+    const may = mayAt.get(ev) ?? new Set<number>();
+    const stored = storedAt.get(ev) ?? new Set<number>();
+    const body = bodyBlock(ev);
+    const why =
+      body.length === 0
+        ? ''
+        : ` (its body loads ${body.length} incoming stack word${body.length === 1 ? '' : 's'}, ${say(body)}, ` +
+          `but the words staged for it are ${sayAll(asc(may))}, on every path ${sayAll(asc(mustAt.get(ev) ?? []))})`;
+    const k = asc(may).find((o) => prefixStored(o, stored));
+    return k === undefined
+      ? null
+      : `the store to [sp,#${k}] reaches \`bl ${ev.callee}\` unread with its lower slots supplied — it may be that call's outgoing stack argument${why}`;
+  };
+  for (const ev of calls) {
+    const refusal = bodyBlock(ev).length > 0 ? pendingAtUndeclared(ev) : null;
+    if (refusal !== null) {
+      return refuse(refusal);
+    }
+  }
   // (a) — a store never reloaded ANYWHERE, with its lower slots supplied, is an argument's
   // signature: an outgoing argument is read by the CALLEE, never by the caller. Its real theorem
   // is the layout one (the area sits at the BOTTOM of localArea, disjoint from the locals, so no
@@ -455,17 +590,9 @@ export function analyzeOutgoingArgs<C>({
   // histogram keys on, and scanning a Set in insertion order named whichever offset the code stored
   // FIRST instead (pokeemerald's `PickLotteryCornerTicket` stores [sp,#4] before [sp,#0]).
   for (const ev of calls) {
-    if (ev.declared !== null) {
-      continue;
-    }
-    const may = mayAt.get(ev) ?? new Set<number>();
-    const stored = storedAt.get(ev) ?? new Set<number>();
-    for (const k of asc(may)) {
-      if (prefixStored(k, stored)) {
-        return refuse(
-          `the store to [sp,#${k}] reaches \`bl ${ev.callee}\` unread with its lower slots supplied — it may be that call's outgoing stack argument`,
-        );
-      }
+    const refusal = pendingAtUndeclared(ev);
+    if (refusal !== null) {
+      return refuse(refusal);
     }
   }
   // NOTHING LEFT OVER. The exclusion above is per OFFSET, so it would also excuse a store to a