@asmlift/core 0.9.0 → 0.11.0

package/src/structure/unfolded-branch-constant.ts

@@ -0,0 +1,90 @@
+// AN EARLY RETURN THAT THE JOIN PAST EARLY RETURNS CANNOT SPELL: a return of the value its branch
+// tested equal to a constant, where the object still returns the value and not the constant.
+//
+// On a compiler whose cse folds a branch-proven constant only into the branch's FALL-THROUGH arm
+// (target.ts `foldsBranchConstantOnTakenEdge` false: gcc 2.x at -O1), `if (x == 0) return x;`
+// compiles to `return 0`, and so does the same test spelled `if (x != 0) ; else return x;`. The join
+// writes the early return one of those two ways. A return of `x` the object left unfolded was
+// therefore the jump-target arm of its branch in the source: the `else` of `if (x != 0) { ...tail }
+// else { return x; }`, which is the copies' spelling. So this mark publishes the copies.
+//
+// THE CONSTANT IS NOT REMATERIALISED ON THE EDGE. Read off the lifted IR: the return block's value
+// is the very SSA value the comparison reads, not a constant. A delay slot that set the return
+// register to the constant (`beqz v0,L; move v0,zero`) lifts as a `const` returned on that edge, and
+// is no mark.
+//
+// MEASURED on the probe pair `corpus/probe-rettail-pg-{copies,join}.c` (unfolded-branch-constant.test.ts)
+// and on Mario Party 3's `func_8010BD28_472F98_mgmode`, which it is the shape of: gcc2.7.2 -O1, the
+// copies `nop` in the `beqz`'s slot and the join `move v0,zero`. There the join loses the copies'
+// match (0 -> 1 line off, really compiled, 2026-11-06).
+//
+// AN `if` SITE ONLY. The premise is an `if`'s two arms, one of them the fall-through. A switch's case
+// arms, read as a switch (`tree`) or a jump table (`switch`), are each a jump target, a case label,
+// so no return in one folds the switch value at -O1 whatever the source wrote, and an unfolded one
+// says nothing. Compiled at gcc2.7.2 -O1: `switch (x) { case 0: return x; case 5: p[1] = 2; break; }`
+// followed by its tail, written with the join, keeps `move v0,a0` in the case-0 jump's slot, and
+// the join and the copies both compile byte-exact. A switch the structurer reads as `if`s (three
+// cases of that function) is still read, the residue of the rule: no reading of it is exact.
+//
+// A MARK IS EVIDENCE, NOT PROOF, as structure/cross-jumped-tail.ts says of its own: it moves which
+// verified reading is the default, never what is lifted. Read only where the target says its cse
+// leaves the taken edge unfolded; elsewhere (`true`, or absent) an unfolded return says nothing.
+import type { Block, Fn, Op, Value } from '../ir/core';
+import type { JoinPastReturnsSite } from './structure';
+
+const succsOf = (b: Block): Block[] => [...new Set(b.ops[b.ops.length - 1]?.successors.map((s) => s.block) ?? [])];
+
+/** Does an early return of the `if` site `site` give back, unfolded, the value its own branch tested
+ *  equal to a constant? The return block holds only its `ret`, has one predecessor, and that
+ *  predecessor's `cond_br` takes it on the equal side of an `icmp_eq`/`icmp_ne` of that value against
+ *  a `const`. */
+export function unfoldedBranchConstant(fn: Fn, site: JoinPastReturnsSite): boolean {
+  if (site.kind !== 'if') {
+    return false;
+  }
+  const def = new Map<Value, Op>();
+  const preds = new Map<Block, Block[]>(fn.blocks.map((b) => [b, []]));
+  for (const b of fn.blocks) {
+    for (const op of b.ops) {
+      for (const r of op.results) {
+        def.set(r, op);
+      }
+    }
+    for (const s of succsOf(b)) {
+      preds.get(s)?.push(b);
+    }
+  }
+  const seen = new Set<Block>();
+  const stack = [site.branch];
+  while (stack.length) {
+    const x = stack.pop()!;
+    if (x === site.join || seen.has(x)) {
+      continue;
+    }
+    seen.add(x);
+    stack.push(...succsOf(x));
+  }
+  for (const r of seen) {
+    const ret = r.ops.length === 1 ? r.ops[0] : undefined;
+    const value = ret?.opcode === 'ret' && ret.operands.length === 1 ? ret.operands[0] : undefined;
+    const from = preds.get(r) ?? [];
+    if (value === undefined || from.length !== 1 || fn.asmLayout?.get(r) === undefined) {
+      continue;
+    }
+    const br = from[0].ops[from[0].ops.length - 1];
+    const cmp = br?.opcode === 'cond_br' ? def.get(br.operands[0]) : undefined;
+    if (cmp === undefined || br.successors.length !== 2 || br.successors[0].block === br.successors[1].block) {
+      continue;
+    }
+    const equalSide = cmp.opcode === 'icmp_eq' ? 0 : cmp.opcode === 'icmp_ne' ? 1 : -1;
+    if (equalSide < 0 || br.successors[equalSide].block !== r || cmp.operands.length !== 2) {
+      continue;
+    }
+    const [a, b] = cmp.operands;
+    const isConst = (v: Value) => def.get(v)?.opcode === 'const';
+    if ((a === value && isConst(b)) || (b === value && isConst(a))) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/symbols.ts

@@ -189,6 +189,12 @@ export interface SymbolInfo {
    *  DECLARATION differs — `#define name body` instead of `extern T name;` — which is why the
    *  body is carried rather than reconstructed. */
   macroBody?: string;
+  /** This name is a FILE-SCOPE GLOBAL REGISTER VARIABLE, and this is the register's `__asm__` name
+   *  (`target.globalRegisterVariables`): the lift reads and writes a callee-saved register no
+   *  prologue saved as this global. `gName` and `gName = v` mean what they mean for an `extern`, and
+   *  `&gName` is an error, as for any register variable. Only the DECLARATION differs —
+   *  `register T name __asm__("r8");` instead of `extern T name;`. */
+  globalRegister?: string;
 }
 
 /** THE one reading of {@link SymbolInfo.dims} for spelling C, shared by the access side
@@ -554,19 +560,48 @@ export function pointeeFields(pointee: SymbolPointee | undefined): DeclaredField
   return declaredFields(pointee.layout);
 }
 
-/** Kind-aware two-probe lookup for a pool-loaded 32-bit value. Exact match first (any kind);
- *  on miss, `value & ~1` — accepted ONLY when the hit is code, because ELF function addresses
- *  are stored with the Thumb bit cleared while a Thumb code pointer in a pool is odd. An exact
- *  odd-DATA hit therefore wins over a masked code hit (odd data addresses are real). */
+/** A name C can spell. Splat's `func_X.NON_MATCHING` labels are sized data aliases that are not. */
+const C_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** THE one object an address names, decided once per address so every lookup that lands there
+ *  spells the same name. Two names for one object inside one function are not a style problem:
+ *  the compiler treats distinct symbols as non-aliasing and forwards a store made through one past
+ *  a store made through the other.
+ *
+ *  Usually the canonical `[0]`. The exception is an unsized data label ranked first over the sized
+ *  object that starts at the same address (sa3's `gUnknown_08358528` over the 540-byte
+ *  `Map_zone_1_act_hub_fg0`, pokeemerald's `gMultiBootProgram_BerryGlitchFix_End` over
+ *  `gMultiBootProgram_PokemonColosseum_Start`): the object is the sized one, because only it has
+ *  an extent, so both an exact hit and an interior hit name it. Never where any alias is code: a
+ *  sized data alias there is a label over the function's bytes (MIPS `func_X.NON_MATCHING`, which
+ *  splat maps rank behind an unsized `gcc2_compiled.` marker), not an object. */
+function objectAt(infos: readonly SymbolInfo[]): SymbolInfo {
+  const head = infos[0];
+  if (head.kind !== 'data' || head.size !== undefined || infos.some((i) => i.kind === 'code')) {
+    return head;
+  }
+  return infos.find((i) => i.kind === 'data' && i.size !== undefined && C_IDENTIFIER.test(i.name)) ?? head;
+}
+
+/** Kind-aware two-probe lookup for a pool-loaded 32-bit value. Exact match first (any kind), which
+ *  names {@link objectAt}'s object; on miss, `value & ~1` — accepted ONLY when the hit is code,
+ *  because ELF function addresses are stored with the Thumb bit cleared while a Thumb code pointer
+ *  in a pool is odd. An exact odd-DATA hit therefore wins over a masked code hit (odd data
+ *  addresses are real).
+ *
+ *  The masked probe asks for the CODE alias at that address, not for the canonical `[0]`: a
+ *  table-end or segment marker can share its address with the function that follows it, and the
+ *  provider may rank the marker first (pokeemerald's `gMysteryEventScriptCmdTableEnd` over
+ *  `GameCubeMultiBoot_Hash`). An odd pool word there is still the function's Thumb pointer. */
 export function lookupSymbol(map: SymbolMap, value: number): SymbolInfo | null {
-  const exact = map.get(value)?.[0];
-  if (exact) {
-    return exact;
+  const exact = map.get(value);
+  if (exact !== undefined && exact.length > 0) {
+    return objectAt(exact);
   }
   if ((value & 1) === 1) {
-    const masked = map.get(value & ~1)?.[0];
-    if (masked?.kind === 'code') {
-      return masked;
+    const code = map.get(value & ~1)?.find((info) => info.kind === 'code');
+    if (code) {
+      return code;
     }
   }
   return null;
@@ -574,10 +609,11 @@ export function lookupSymbol(map: SymbolMap, value: number): SymbolInfo | null {
 
 /** Interior attribution: the data symbol whose `[address, address+size)` range contains
  *  `value` strictly inside (offset > 0 — exact bases go through `lookupSymbol`). Only
- *  complete-typed globals carry a size, so unsized arrays never attribute. */
+ *  complete-typed globals carry a size, so unsized arrays never attribute. The symbol at each
+ *  base is {@link objectAt}'s, the same one an exact hit on that base names. */
 export function lookupInterior(map: SymbolMap, value: number): { info: SymbolInfo; offset: number } | null {
   for (const [addr, infos] of map) {
-    const info = infos[0];
+    const info = objectAt(infos);
     if (info.kind !== 'data' || info.size === undefined) {
       continue;
     }
@@ -590,9 +626,16 @@ export function lookupInterior(map: SymbolMap, value: number): { info: SymbolInf
 
 /** The `SymbolInfo` keys a project's DWARF can only carry because the symbol's DEFINITION was
  *  compiled from C. Everything else in the map survives a function that is still `INCLUDE_ASM`:
- *  its `.symtab` entry exists (the asm defines the label), and its globals are typed by the OTHER
- *  translation units that declare them. Listed here, once, so {@link asIfUndecompiled} and any
- *  later definition-derived fact (a signature, a local's type, a register location) stay in sync. */
+ *  its `.symtab` entry exists (the asm defines the label), and most globals it reads are typed by
+ *  other code that references them. Listed here, once, so {@link asIfUndecompiled} and any later
+ *  definition-derived fact (a signature, a local's type, a register location) stay in sync.
+ *
+ *  KNOWN GAP: "other code" is not guaranteed. agbcc writes a DWARF entry for an extern global only
+ *  in a compilation unit that references it, so a global defined in asm (a NOTYPE symbol) that only
+ *  the row's own body references takes its type from the row's decompiled C. Nothing here strips
+ *  that type, because the map does not record which compilation unit typed a symbol. kleod has 10
+ *  such globals across 6 rows, among them PauseMenuScreenHandler's `gUnk_081166F8[4][4]`. The
+ *  CLI's repro reads the same ELF and sees the same types. */
 const DEFINITION_DERIVED_KEYS = ['declared', 'signature'] as const satisfies readonly (keyof SymbolInfo)[];
 
 /** The map a user actually has while decompiling `fn` — i.e. with `fn` still an `INCLUDE_ASM`