@asmlift/core 0.8.1 → 0.10.0

package/src/l3/storage.ts

@@ -17,7 +17,10 @@
 //     silently a different object: `addressableGlobals`;
 //   • it asks which of the three classes a bare `assign` name denotes at all: `nameStorage`, the
 //     primitive the other two are the shadow-sensitive projections over.
-import type { SFn } from './ast';
+// One question about LOCAL storage sits beside them, because it is asked from the same lists:
+// which expressions are a local object's ADDRESS (`localAddresses`), the frame bytes a respelled
+// tree must keep reading as integers (contracts.ts `assertLocalStorageStaysInteger`).
+import { type Expr, type SFn, type Stmt, assignsIn, dotBase, stmtChildren, taintOverAssigns, walkExprs } from './ast';
 
 export type Storage = 'local' | 'param' | 'global';
 
@@ -46,3 +49,97 @@ export function declaredGlobals(sfn: SFn): Set<string> {
 export function addressableGlobals(sfn: SFn): Set<string> {
   return new Set([...nameStorage(sfn)].filter(([, s]) => s === 'global').map(([n]) => n));
 }
+
+/** The ADDRESSES of a tree's local objects — the frame bytes, which nothing but the function's own
+ *  accesses and the callees it hands an address to can reach.
+ *
+ *  `isAddress(e)`: `e` evaluates to an address inside a local object — a local array (`sp0`,
+ *  which decays), a local's address (`&v`), a local ever assigned one (`p0 = (s32 *)sp0;`, a
+ *  flow-insensitive taint), under a cast or moved by `+`/`-`. PRECISE in the direction that
+ *  matters to its readers: a value READ OUT of the bytes (`((s32 *)sp0)[i]`, a pointer the frame
+ *  holds) is not an address of them, so an access through it is not an access to the frame.
+ *  Known gap, on the side of answering no: an array MEMBER spelled as a `field` (`s.arr`) is an
+ *  address C decays, and this does not follow it.
+ *
+ *  `accessAddress(e)`: the operand an access node reads its address from — an `index`'s base, an
+ *  arrow `field`'s base, a dot `field`'s array element's base, or a struct VALUE's own address
+ *  (`s.f` reads at `&s`). A param counts as a local throughout: its home is the frame once its
+ *  address is taken, and a param assigned an address holds it as a local would. */
+export function localAddresses(sfn: SFn): {
+  isAddress: (e: Expr) => boolean;
+  accessAddress: (e: Extract<Expr, { k: 'index' } | { k: 'field' }>) => Expr;
+} {
+  const storage = nameStorage(sfn);
+  // a param is a local variable of the callee: its home is the frame once its address is taken
+  const isLocal = (n: string): boolean => storage.get(n) === 'local' || storage.get(n) === 'param';
+  const addressIn = (e: Expr, tainted: ReadonlySet<string>): boolean => {
+    switch (e.k) {
+      case 'var':
+      case 'postincr':
+        return tainted.has(e.name);
+      case 'addr':
+        return isLocal(e.name);
+      case 'cast':
+        return addressIn(e.e, tainted);
+      case 'bin':
+        return (
+          (e.op === '+' && (addressIn(e.l, tainted) || addressIn(e.r, tainted))) ||
+          (e.op === '-' && addressIn(e.l, tainted))
+        );
+      default:
+        return false;
+    }
+  };
+  const tainted = taintOverAssigns(
+    assignsIn(sfn.body),
+    sfn.locals.filter((l) => l.type.kind === 'array').map((l) => l.name),
+    (a, t) => isLocal(a.name) && addressIn(a.value, t),
+  );
+  return {
+    isAddress: (e) => addressIn(e, tainted),
+    accessAddress: (e) =>
+      e.k === 'index'
+        ? e.base
+        : (dotBase(e)?.base ?? (e.dot === true && e.base.k === 'var' ? { k: 'addr', name: e.base.name } : e.base)),
+  };
+}
+
+/** Whether a local object's address LEAVES the function — passed to a call, stored to memory,
+ *  assigned to a non-local, or returned — AND the function itself writes local storage. Both
+ *  halves are what let a pointer the function obtains LATER (a call's result, a load) name bytes
+ *  the function also stores to: a callee that keeps the address can hand it back.
+ *
+ *  OVER-WIDE ON PURPOSE, and what it costs is measured: a store to a DEVICE register counts as an
+ *  escape, since the tree cannot tell a DMA source register (`REG_DMA3SAD = sp0;`, the GBA's fill
+ *  idiom) from memory a later load reads back. On kleod:PauseMenuScreenHandler that refuses every
+ *  `/ptr-field` candidate, none of which was its winner. */
+export function localStorageEscapesWritten(sfn: SFn): boolean {
+  const { isAddress, accessAddress } = localAddresses(sfn);
+  const storage = nameStorage(sfn);
+  const held = (n: string): boolean => storage.get(n) === 'local' || storage.get(n) === 'param';
+  let escapes = false;
+  let written = false;
+  const addressTaken = new Set<string>();
+  for (const e of walkExprs(sfn.body)) {
+    if (e.k === 'call' && e.args.some(isAddress)) {
+      escapes = true;
+    }
+    if (e.k === 'addr' && held(e.name)) {
+      addressTaken.add(e.name);
+    }
+  }
+  const visit = (s: Stmt): void => {
+    if (s.k === 'store') {
+      escapes ||= isAddress(s.value);
+      written ||= (s.lval.k === 'index' || s.lval.k === 'field') && isAddress(accessAddress(s.lval));
+    } else if (s.k === 'assign') {
+      escapes ||= !held(s.name) && isAddress(s.value);
+      written ||= addressTaken.has(s.name);
+    } else if (s.k === 'return' && s.value !== undefined) {
+      escapes ||= isAddress(s.value);
+    }
+    stmtChildren(s).forEach(visit);
+  };
+  sfn.body.forEach(visit);
+  return escapes && written;
+}

package/src/l3/symbol-refs.ts

@@ -16,8 +16,12 @@
 // to recompute it (a dead-store DCE that drops a tree's only reference would otherwise leave a
 // stale ref, transitively reintroducing the hazards the collector excludes). Deriving at the
 // consumption point makes staleness impossible by construction.
+import type { IrType } from '../ir/types';
+import { type AggregateLayout, type FnProto, type ParamType, type Prototypes, spellableProto } from '../proto';
 import type { SymbolInfo } from '../symbols';
-import { Expr, Stmt, exprChildren, stmtChildren, stmtExprs } from './ast';
+import type { TargetDescription } from '../target';
+import { Expr, SFn, Stmt, exprChildren, mentionedName, stmtChildren, stmtExprs } from './ast';
+import { pointerCellsOf, pointerPartners } from './ptrcell';
 
 /** One recorded VALUE reference — a name the tree references plus the facts to declare it. */
 export interface SymbolRef {
@@ -27,43 +31,137 @@ export interface SymbolRef {
    *  own IR — attached by the enumeration (rank.ts bareGlobalAccessFacts), consumed by the
    *  declaration synthesis (declare.ts) as the width/signedness authority for `extern T name;`. */
   access?: { width: number; signed: boolean };
-  /** NO SYMBOL MAP KNOWS THIS NAME — the declaration for it is a HYPOTHESIS, not a fact. Both the
-   *  name and (through `access`) its width and signedness were read out of the candidate's own
-   *  asm: the very bytes the candidate is then scored against. A fitted declaration cannot LOSE
-   *  score, so it is not covered by declare.ts's only-loses-score argument — it can manufacture
-   *  agreement instead. Which is legitimate (the artifact is decls + source, and it does compile
-   *  to those bytes) exactly as long as the consumer SHOWS the declarations with the verdict.
-   *  Marked here so a consumer can tell the two provenances apart inside one block. */
+  /** NO SYMBOL MAP ACCOUNTS FOR THIS NAME — that is the whole predicate, and it is one fact with
+   *  two provenances the consumer must be able to tell apart.
+   *
+   *  WITHOUT `proto`, the declaration is a HYPOTHESIS: the name and (through `access`) its width
+   *  and signedness were read out of the candidate's own asm — the very bytes the candidate is
+   *  then scored against. A fitted declaration cannot LOSE score, so it is not covered by
+   *  declare.ts's only-loses-score argument; it can manufacture agreement instead. Which is
+   *  legitimate (the artifact is decls + source, and it does compile to those bytes) exactly as
+   *  long as the consumer SHOWS the declarations with the verdict.
+   *
+   *  WITH `proto`, the declaration's TEXT is the project's own — a call target asmlift has a
+   *  prototype for — and asmlift invented nothing about it. It is still marked, because the
+   *  predicate this flag states is about the symbol MAP and not about who wrote the type, and
+   *  because the score rests on that line being in the translation unit either way. A consumer
+   *  wording the block reads `proto` to say which it is looking at; dropping the mark instead
+   *  would under-report a declaration the verdict depends on, which is the direction
+   *  `synthesizedRefs` exists to avoid. */
   synthesized?: true;
+  /** A CALL TARGET's own declaration, re-spelled from the prototype the project supplied — the
+   *  parameter type texts and the return type text, verbatim as the user wrote them. Present only
+   *  where {@link spellableProto} could read a COMPLETE C prototype out of the `FnProto`, and it
+   *  is what `declare.ts` prints instead of an `extern`: a call target is a function, and
+   *  `extern u32 llsrc;` is not a declaration of it. Absent where the symbol map calls the name
+   *  something other than code — two facts that disagree are not one fact — and that subtraction
+   *  happens at the table (`proto.ts` `prototypesFromSymbols`), so the frontend loses the same
+   *  fact in the same place rather than acting on one this withheld. */
+  proto?: { readonly params: readonly ParamType[]; readonly returns: ParamType };
+  /** The struct a call target returns through memory — a type the project's headers own
+   *  (ir/types.ts `declared`), so `declare.ts` defines it beside `proto`, whose `returns` spells it:
+   *  by its tag (`name`), from the members the declaration lists (`layout`, which the lift laid out
+   *  to type the call). */
+  returned?: { readonly name: string; readonly declared: string; readonly layout: AggregateLayout };
+  /** The structs a call target is passed BY VALUE (`byValue` on the call), defined the same way
+   *  from the declaration's `byValueLayouts`. */
+  passed?: readonly { readonly name: string; readonly declared: string; readonly layout: AggregateLayout }[];
+  /** A global the body passes BARE as a struct by value (`take(gS)`), as `struct <tag>`: a
+   *  name-only declaration of it is that struct, which the call needs and an integer cell rejects. */
+  passedAs?: string;
+  /** The bare name holds a pointer (l3/ptrcell.ts): the body stores one into it, or it meets such a
+   *  cell bare and nothing reads it as an integer (`pointerPartners`). A name-only declaration of it
+   *  is a pointer, which the store needs and an integer cell rejects on CodeWarrior. */
+  holdsPointer?: true;
+  /** A call target with NO spellable prototype whose address a function-scope static's (or an
+   *  anonymous image's) initializer holds. The static's `(u32)&F` precedes every call, so the
+   *  implicit declaration a call makes comes too late for it; `declare.ts` prints that same
+   *  declaration first, `int F();`, which states no parameter and so binds the call as before. */
+  implicitCall?: true;
+  /** THE STRUCT THE FUNCTION ITSELF RETURNS ({@link ownReturnDefinition}): a ref under the
+   *  function's own name that declares nothing of it — its definition is its declaration — and only
+   *  defines `returned`, the type its own signature spells. */
+  definesReturn?: true;
+}
+
+/** The ref that defines the struct `tree` itself returns by value — a type the project's headers
+ *  own (ir/types.ts `declared`), so the candidate's declarations define it as they define a
+ *  callee's (`SymbolRef.returned`) — from the members its own declaration `own` lists. Undefined
+ *  where it returns no such struct, or its declaration lists no members. */
+export function ownReturnDefinition(tree: SFn, own: FnProto | undefined): SymbolRef | undefined {
+  const t = tree.retType;
+  const layout = own?.returnLayout;
+  if (t.kind !== 'struct' || t.declared === undefined || layout?.members === undefined) {
+    return undefined;
+  }
+  return {
+    name: tree.name,
+    info: { name: tree.name, kind: 'code' },
+    returned: { name: t.name, declared: t.declared, layout },
+    definesReturn: true,
+  };
 }
 
 /** The declarable symbols a structured body references in a VALUE context — the input to the
  *  scoring layer's declaration synthesis. A name counts when it appears as a `var`/`addr` leaf
  *  and the caller's dictionary knows it (bare `gSym`, `&gSym`, `(u32)Func`, a `field` base — all reduce to
- *  those leaves). A name that is ANY call's target is excluded entirely, even if also
- *  value-referenced: prototyping a called symbol `void F(void);` hard-errors under gcc-2.9
- *  when the call passes args, while leaving it undeclared keeps today's implicit-declaration
- *  behavior (the one honest option without arity knowledge). The function's OWN name
- *  (`selfName`) is excluded too — the candidate's definition IS its declaration, and a
+ *  those leaves). The function's OWN name
+ *  (`tree.name`) is excluded too — the candidate's definition IS its declaration, and a
  *  synthesized `void F(void);` above `s32 F(...)` is a conflicting-types hard error (a
  *  self-address reference resolves against the definition itself).
  *
+ *  A CALL TARGET IS DECLARED WHEN, AND ONLY WHEN, THE PROJECT DECLARED IT COMPLETELY. `void
+ *  F(void);` hard-errors under gcc-2.9 the moment the call passes an argument, so with no arity
+ *  knowledge the honest option is to leave the name undeclared and keep C's implicit-declaration
+ *  behaviour — which is what this did for every call target and still does for every one the
+ *  prototype table cannot spell. Where it CAN (`spellableProto`), that knowledge is exactly what
+ *  the refusal said it lacked, and the declaration is the project's own text rather than a guess.
+ *  It is needed: an implicit declaration is `int`, so `(s64)llsrc()` sign-extends a word and the
+ *  candidate carries an `asr` the target does not have.
+ *
  *  Both exclusions are REPORTED through `onRefused`, on the caller's own refusal channel: they
  *  leave a name undeclared for asmlift's own reason, and a consumer's list of those reasons is
  *  incomplete without them. */
 export function collectSymbolRefs(
-  body: Stmt[],
+  tree: SFn,
   symbols: Map<string, SymbolInfo>,
-  selfName: string,
+  /** the project's prototype table — the only thing that can turn a call target into a
+   *  declaration. REQUIRED, not optional: a caller that forgot it would silently get the old
+   *  blanket refusal back, which is the shape of an optional refusal a second caller switches off. */
+  prototypes: Prototypes,
+  /** which declared types the frontend lays out, so which a printed prototype may carry */
+  target: Pick<TargetDescription, 'doubleArgWords'>,
   onRefused?: (name: string, reason: 'call-target' | 'self-name') => void,
 ): SymbolRef[] {
   const called = new Set<string>();
+  // the struct a callee returns through memory or by value in registers, as the lift typed it
+  const returned = new Map<string, Extract<IrType, { kind: 'struct' }>>();
+  // …and the structs it is passed by value, by declared parameter index
+  const passedTo = new Map<string, Map<number, Extract<IrType, { kind: 'struct' }>>>();
+  // …and the globals passed bare as one, by its spelling
+  const passedAs = new Map<string, string>();
   const valueRefs = new Set<string>();
   const visitExpr = (e: Expr): void => {
-    if (e.k === 'call') {
+    const named = mentionedName(e);
+    if (e.k === 'call' && typeof e.fn === 'string') {
       called.add(e.fn);
-    } else if ((e.k === 'var' || e.k === 'addr') && symbols.has(e.name)) {
-      valueRefs.add(e.name);
+      const struct = e.sret ?? e.returns;
+      if (struct?.kind === 'struct') {
+        returned.set(e.fn, struct);
+      }
+      for (const b of e.byValue ?? []) {
+        if (b.type.kind === 'struct') {
+          const params = passedTo.get(e.fn) ?? passedTo.set(e.fn, new Map()).get(e.fn)!;
+          params.set(b.param, b.type);
+          const arg = e.args[b.at];
+          if (arg?.k === 'var' && symbols.has(arg.name)) {
+            // by its tag, which declares even ahead of the definition and of a typedef of it
+            passedAs.set(arg.name, `struct ${b.type.name}`);
+          }
+        }
+      }
+    } else if (named !== undefined && symbols.has(named)) {
+      valueRefs.add(named);
     }
     exprChildren(e).forEach(visitExpr);
   };
@@ -76,19 +174,80 @@ export function collectSymbolRefs(
     stmtExprs(s).forEach(visitExpr);
     stmtChildren(s).forEach(visitStmt);
   };
-  body.forEach(visitStmt);
-  return [...valueRefs]
+  tree.body.forEach(visitStmt);
+  // A function-scope static's initializer names the globals whose addresses it holds
+  // (`(u32)&MetatileBehavior_IsTallGrass`), which the candidate must declare as much as the body's —
+  // and so does an anonymous image, which the emitter folds into a local's initializer.
+  const initAddresses = new Set<string>();
+  for (const st of [...(tree.statics ?? []), ...(tree.images ?? [])]) {
+    for (const v of st.init ?? []) {
+      if (v !== null && typeof v === 'object' && symbols.has(v.symbol)) {
+        valueRefs.add(v.symbol);
+        initAddresses.add(v.symbol);
+      }
+    }
+  }
+  const holdsPointer = new Set([...pointerCellsOf(tree), ...pointerPartners(tree)]);
+  // A call target is a ref in its own right, whether or not the body also names it as a value —
+  // `Object.hasOwn`, because `prototypes` is caller-supplied JSON and a callee may be named
+  // `toString`. The union is sorted as one list so the rendered block stays deterministic.
+  const proto = new Map<string, NonNullable<SymbolRef['proto']>>();
+  for (const n of called) {
+    // TWO FACTS ABOUT ONE NAME, AND A DISAGREEMENT IS SILENCE — decided at the TABLE, not here. A
+    // map entry that states a data shape for this name contradicts the prototype that calls it a
+    // function, and `proto.ts` `prototypesFromSymbols` has already taken the `returns` off such an
+    // entry, so what arrives here states no printable prototype and the frontend read the call the
+    // same way. Testing it a second time at this reader is what let the two answer differently.
+    const p = Object.hasOwn(prototypes, n)
+      ? spellableProto(prototypes[n], target, returned.get(n), new Set(passedTo.get(n)?.keys()))
+      : undefined;
+    if (p !== undefined) {
+      proto.set(n, p);
+    }
+  }
+  return [...new Set([...valueRefs, ...proto.keys()])]
     .sort()
     .filter((n) => {
-      if (called.has(n)) {
+      // …except where an initializer holds its address: there the name is spelled ahead of every
+      // call, so leaving it to the call's implicit declaration leaves the initializer naming an
+      // undeclared identifier, and the implicit declaration itself is the one that is printed
+      // (`SymbolRef.implicitCall`).
+      if (called.has(n) && !proto.has(n) && !initAddresses.has(n)) {
         onRefused?.(n, 'call-target');
         return false;
       }
-      if (n === selfName) {
+      if (n === tree.name) {
         onRefused?.(n, 'self-name');
         return false;
       }
       return true;
     })
-    .map((n) => ({ name: n, info: symbols.get(n)! }));
+    .map((n) => {
+      const p = proto.get(n);
+      // A call target the map never mentioned still has to carry an `info` — it is a code symbol
+      // and that is all this knows about it. `declare.ts` prints the prototype and never reaches
+      // the shape, so nothing here is guessed about storage that does not exist.
+      const info = symbols.get(n) ?? { name: n, kind: 'code' as const };
+      const r = p ? returned.get(n) : undefined;
+      const layout = r?.declared !== undefined ? prototypes[n].returnLayout : undefined;
+      const definition = layout?.members !== undefined ? { name: r!.name, declared: r!.declared!, layout } : undefined;
+      const passed = p
+        ? [...(passedTo.get(n) ?? [])].flatMap(([k, t]) => {
+            const l = prototypes[n].byValueLayouts?.[k];
+            return l?.members !== undefined && t.declared !== undefined
+              ? [{ name: t.name, declared: t.declared, layout: l }]
+              : [];
+          })
+        : [];
+      return {
+        name: n,
+        info,
+        ...(p ? { proto: p } : {}),
+        ...(definition ? { returned: definition } : {}),
+        ...(passed.length > 0 ? { passed } : {}),
+        ...(passedAs.has(n) ? { passedAs: passedAs.get(n)! } : {}),
+        ...(holdsPointer.has(n) ? { holdsPointer: true as const } : {}),
+        ...(called.has(n) && !p ? { implicitCall: true as const } : {}),
+      };
+    });
 }

package/src/l3/tailmerge.ts

@@ -53,37 +53,24 @@
 //     lifts alike. What no arm of the fan spells is the third form, the hidden statement merged
 //     while KEEPING the record's order.
 //
-// SCOPE. Only `assign`/`store`/`exprstmt` merge, compared structurally through `exprEquals`.
+// SCOPE. Only `assign`/`store`/`exprstmt` merge, compared structurally through `stmtEquals`.
 // Control flow (`break`/`continue`/`return`) is excluded: moving one out of an arm changes which
-// statements the arm can still reach. Nested `if`/loop/`switch` statements are excluded because
-// comparing them needs a full `Stmt` congruence, and there is no second inhabitant for one — the
-// `Expr`-level comparison is the part that already exists, is tested, and is all this needs.
+// statements the arm can still reach. Nested `if`/loop/`switch` statements are excluded: merging
+// one needs a congruence over loops and `switch` too, which `stmtEquals` does not have, and there
+// is no second inhabitant for one.
 //
 // An `ASMLIFT_ERROR` marker ending both arms merges like anything else. The gap stays loud (the
 // artifact still refuses to compile) but `collectMarkers` then reports it once rather than twice,
 // which is accurate — it is one gap that ran on both paths.
 import type { SFn, Stmt } from './ast';
-import { exprEquals } from './ast';
+import { stmtEquals, unionStmtEvidence } from './ast';
 
 /** Statements this pass may move. Deliberately narrow — see SCOPE. */
 type Mergeable = Extract<Stmt, { k: 'assign' } | { k: 'store' } | { k: 'exprstmt' }>;
 const isMergeable = (s: Stmt): s is Mergeable => s.k === 'assign' || s.k === 'store' || s.k === 'exprstmt';
 
 /** Do these two statements write the same thing from the same expression? */
-function sameStmt(a: Stmt, b: Stmt): boolean {
-  if (!isMergeable(a) || !isMergeable(b) || a.k !== b.k) {
-    return false;
-  }
-  if (a.k === 'assign' && b.k === 'assign') {
-    return a.name === b.name && exprEquals(a.value, b.value);
-  }
-  if (a.k === 'store' && b.k === 'store') {
-    return exprEquals(a.lval, b.lval) && exprEquals(a.value, b.value);
-  }
-  const av = (a as Extract<Stmt, { k: 'exprstmt' }>).value;
-  const bv = (b as Extract<Stmt, { k: 'exprstmt' }>).value;
-  return exprEquals(av, bv);
-}
+const sameStmt = (a: Stmt, b: Stmt): boolean => isMergeable(a) && isMergeable(b) && stmtEquals(a, b);
 
 /** Rewrite one statement, then the list it lives in. */
 function rewrite(s: Stmt): Stmt[] {
@@ -102,7 +89,9 @@ function rewrite(s: Stmt): Stmt[] {
       // it, but it is the one shape where a zero-arm merge is qualitatively unlike a partial one.
       const tail: Stmt[] = [];
       while (then.length > 0 && els.length > 0 && sameStmt(then[then.length - 1], els[els.length - 1])) {
-        tail.unshift(then[then.length - 1]);
+        // The two print alike, but an unsigned compare in one prints like the signed one in the
+        // other: the moved statement carries the evidence of both (ast.ts `unionEvidence`).
+        tail.unshift(unionStmtEvidence(then[then.length - 1], els[els.length - 1]));
         then.pop();
         els.pop();
       }