@asmlift/core 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asmlift/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "description": "Match decompile an assembly function to C or Pascal",

package/src/backend/cfamily.ts

@@ -388,7 +388,10 @@ function printStmt(s: Stmt, indent: string, vt: VarTypes, leaf?: LeafHook): stri
           out.push(`${bi}break;`);
         }
       }
-      if (s.default) {
+      // `?.length`, not just presence: a label with no statement under it is not valid C89, and an
+      // L3 pass (dce, reindex) may empty a default that arrived with statements — the structurer's
+      // own "don't attach an empty default" rule cannot see that.
+      if (s.default?.length) {
         out.push(`${ci}default:`);
         for (const t of s.default) {
           out.push(...printStmt(t, bi, vt, leaf));
@@ -470,7 +473,7 @@ function cFamilyBody(fn0: SFn, leaf?: LeafHook): string[] {
   const vt: VarTypes = declaredTypes(fn);
   const lines: string[] = [];
   for (const l of fn.locals) {
-    lines.push(`    ${cType(l.type)} ${l.name};`);
+    lines.push(`    ${l.volatile ? 'volatile ' : ''}${cType(l.type)} ${l.name};`);
   }
   for (const s of fn.body) {
     lines.push(...printStmt(s, '    ', vt, leaf));

package/src/contracts.ts

@@ -3,10 +3,10 @@
 // decompileRanked / decompileWithReport).
 // A pass that regresses fails AT its boundary with a diagnostic, not three stages later as
 // wrong C.
-import type { Fn, Value } from './ir/core';
+import { type Block, type Fn, type Value, successorsOf } from './ir/core';
 import { type IrType, typeToString } from './ir/types';
 import type { BinOp, Expr, SFn, Stmt } from './l3/ast';
-import { exprChildren, fieldSpellsDot, stmtChildren, stmtExprs } from './l3/ast';
+import { exprChildren, fieldSpellsDot, gapReasonFor, stmtChildren, stmtExprs } from './l3/ast';
 import { declaredTypes, exprCType } from './l3/typing';
 
 export class ContractError extends Error {
@@ -58,6 +58,170 @@ export function assertResolved(sfn: SFn): void {
   }
 }
 
+// ── effects: executed once, never dropped ──────────────────────────────────────────────────
+//
+// The three contracts around this one are about TYPING and SPELLABILITY. Nothing checked the
+// property the structurer's materialization model exists to preserve: a call in the asm must run
+// exactly as often in the emitted source. Its two failure modes are the two that hurt most —
+// asmlift's first rule is that a loud failure beats a silently wrong answer, and both of these are
+// silent:
+//
+//   • DROPPED — a call the asm makes has no counterpart in the tree at all;
+//   • RE-RUN  — inlining a call's value at more than one render position (or a structuring copy
+//     that duplicates a region onto a single path) makes one call execute twice. The round that
+//     recovered switch fall-through hit exactly this shape, and only an adversarial reviewer
+//     caught it.
+//
+// Deliberately narrow, so it never declines a function that is fine:
+//
+//   • CALLS only. Loads legitimately re-render (that is the whole point of the inline-at-use
+//     model, and the alias gate governs it); stores are checked by neither direction here because
+//     the readability DCE pass is allowed to drop a provably dead one.
+//   • PER PATH, not per tree. Structuring may legitimately emit one block twice — two exclusive
+//     switch arms sharing a body, a duplicated return merge — and each path still executes it
+//     once. So the duplication rule compares the maximum over syntactic root-to-leaf paths (a
+//     branch takes the max of its arms, a loop body counts once, a fall-through arm chains into
+//     the next) against the IR's static count.
+//   • Names the IR does not have are ignored, and only calls carrying a target symbol are counted
+//     (every frontend that emits `call` today stamps one).
+type CallCounts = Map<string, number>;
+
+/** per-key combine of two count maps (`sum` for sequence, `max` for exclusive alternatives) */
+function combine(a: CallCounts, b: CallCounts, f: (x: number, y: number) => number): CallCounts {
+  const out = new Map(a);
+  for (const [k, v] of b) {
+    out.set(k, f(out.get(k) ?? 0, v));
+  }
+  return out;
+}
+
+/** every `call` expression under `e`, counted by target name */
+function callsInExpr(e: Expr, into: CallCounts): void {
+  if (e.k === 'call') {
+    into.set(e.fn, (into.get(e.fn) ?? 0) + 1);
+  }
+  exprChildren(e).forEach((c) => callsInExpr(c, into));
+}
+
+/** `total` = every occurrence in the tree; `path` = the most any single syntactic path executes */
+function countCalls(stmts: Stmt[]): { total: CallCounts; path: CallCounts } {
+  let total: CallCounts = new Map();
+  let path: CallCounts = new Map();
+  const add = (r: { total: CallCounts; path: CallCounts }, pathF: (x: number, y: number) => number) => {
+    total = combine(total, r.total, (x, y) => x + y);
+    path = combine(path, r.path, pathF);
+  };
+  for (const s of stmts) {
+    const own: CallCounts = new Map();
+    stmtExprs(s).forEach((e) => callsInExpr(e, own));
+    add({ total: own, path: own }, (x, y) => x + y);
+    if (s.k === 'if') {
+      const t = countCalls(s.then);
+      const e = countCalls(s.else);
+      // exclusive arms: the path count is whichever arm runs, the total counts both
+      add(
+        { total: combine(t.total, e.total, (x, y) => x + y), path: combine(t.path, e.path, Math.max) },
+        (x, y) => x + y,
+      );
+    } else if (s.k === 'switch') {
+      const arms = s.cases.map((c) => countCalls(c.body));
+      const dflt = countCalls(s.default ?? []);
+      // A fall-through arm continues into the NEXT one emitted (the last into `default`), so a
+      // path through arm i runs the chain starting at i — the shape the fall-through round's
+      // CRITICAL took. Built from the end; `chain[i]` is that arm's per-path count.
+      const chain: CallCounts[] = new Array(arms.length);
+      for (let i = arms.length - 1; i >= 0; i--) {
+        const next = i + 1 < arms.length ? chain[i + 1] : dflt.path;
+        chain[i] = s.cases[i].fallsThrough ? combine(arms[i].path, next, (x, y) => x + y) : arms[i].path;
+      }
+      const armTotal = arms.reduce((acc, a) => combine(acc, a.total, (x, y) => x + y), dflt.total);
+      const armPath = chain.reduce((acc, c) => combine(acc, c, Math.max), dflt.path);
+      add({ total: armTotal, path: armPath }, (x, y) => x + y);
+    } else {
+      // Sequenced children (a loop body, a `for`'s init/inc): counted ONCE — a loop's dynamic trip
+      // count is not a syntactic occurrence, and the IR side is static too.
+      for (const c of stmtChildren(s)) {
+        add(countCalls([c]), (x, y) => x + y);
+      }
+    }
+  }
+  return { total, path };
+}
+
+/**
+ * Post structuring: every call the asm makes is emitted, and none is emitted more times than the
+ * asm makes it on any one path. See the note above for what this deliberately does not cover.
+ */
+export function assertEffectsPreserved(fn: Fn, sfn: SFn): void {
+  // Reachable blocks only: an unreachable block's call is legitimately never emitted.
+  const seen = new Set<Block>([fn.blocks[0]]);
+  for (const stack = [fn.blocks[0]]; stack.length;) {
+    for (const s of successorsOf(stack.pop()!)) {
+      if (!seen.has(s)) {
+        seen.add(s);
+        stack.push(s);
+      }
+    }
+  }
+  const irCalls: CallCounts = new Map();
+  // Unmodelled instructions, by the mnemonic the frontend stamped. Same "never dropped" property as
+  // a call, and it needs its own tally because an `opaque` carries no `target`.
+  const irOpaques = new Set<string>();
+  for (const b of seen) {
+    for (const op of b.ops) {
+      if (op.opcode === 'call' && typeof op.attrs.target === 'string') {
+        const t = op.attrs.target;
+        irCalls.set(t, (irCalls.get(t) ?? 0) + 1);
+      } else if (op.opcode === 'opaque') {
+        irOpaques.add(gapReasonFor(op.attrs.mnemonic));
+      }
+    }
+  }
+  // DROPPED only, not the RE-RUN half: a gap rendered twice is a diagnostic printed twice, which
+  // costs nothing because nothing recompiles it, and structuring legitimately duplicates a shared
+  // arm — so a per-path count here would fire on correct output.
+  //
+  // Bites only in ANNOTATE mode (under `strict` the gap is the `?` sentinel and structure() has
+  // already thrown), which is where it is needed: that is the CLI and benchmark default, and the
+  // only mode with no other backstop against a silently dropped opaque.
+  if (irOpaques.size) {
+    const emitted = new Set<string>();
+    const we = (e: Expr): void => {
+      if (e.k === 'marker') {
+        emitted.add(e.reason);
+      }
+      exprChildren(e).forEach(we);
+    };
+    const ws = (s: Stmt): void => {
+      stmtExprs(s).forEach(we);
+      stmtChildren(s).forEach(ws);
+    };
+    sfn.body.forEach(ws);
+    for (const reason of irOpaques) {
+      if (!emitted.has(reason)) {
+        throw new ContractError(
+          `structuring dropped the ${reason} in '${sfn.name}' — an instruction asmlift could not model left no trace`,
+        );
+      }
+    }
+  }
+  if (!irCalls.size) {
+    return;
+  }
+  const { total, path } = countCalls(sfn.body);
+  for (const [name, n] of irCalls) {
+    if (!(total.get(name) ?? 0)) {
+      throw new ContractError(`structuring dropped the call to '${name}' in '${sfn.name}' — its effect is lost`);
+    }
+    const p = path.get(name) ?? 0;
+    if (p > n) {
+      throw new ContractError(
+        `structuring emitted ${p} calls to '${name}' on one path in '${sfn.name}', where the asm makes ${n}`,
+      );
+    }
+  }
+}
+
 /** Post structuring: the AST's memory accesses and operators must be SPELLABLE — a `field`
  *  node's base a pointer-to-struct (`->`) or a struct value (`.`, an array element) carrying
  *  that field; no pointer operand under an operator C rejects; and every SCALAR `index` node's

package/src/frontend/mips.ts

@@ -31,7 +31,7 @@ import { assertInputFormat } from './format';
 import type { Frontend } from './frontend';
 import { opaqueDest } from './opaque';
 import { isSplatMips, parseSplatMips } from './splat';
-import { abiSortEntryParams } from './ssa';
+import { abiSortEntryParams, stackSlotKey } from './ssa';
 import { makeSsaBuilder } from './ssa';
 
 type Instr = DisasmInstr;
@@ -54,7 +54,7 @@ const isZero = (r: string) => r === 'zero' || r === '$0';
 const isStackPtr = (r: string) => r === 'sp' || r === '$sp' || r === '$29';
 // SSA-variable name for the stack slot at a constant `sp`-offset. Distinct namespace from the
 // register names (which are alphabetic / `$N`), so it never collides with a real register var.
-const stackSlot = (off: number) => `sp@${off}`;
+const stackSlot = stackSlotKey; // shared spelling: frontend/ssa.ts
 // Sub-word memory mnemonics (widths 1 and 2). Used by the `spSlotSafe` guard in `lift`: a sub-word
 // `sp`-relative access means the word stack-slot model is unsafe for that function.
 const SUBWORD_MEM = new Set(['lb', 'lbu', 'lh', 'lhu', 'sb', 'sh']);
@@ -866,8 +866,8 @@ export function lift(
       }
     };
     // TRUSTWORTHINESS GUARD (mirrors the PPC frontend): an unmodelled instruction must not silently
-    // drop its destination register — emit an honest `opaque`: dead ⇒ it vanishes; live ⇒
-    // assertResolved fails LOUD (see frontend/opaque.ts for the policy).
+    // drop its destination register — emit an honest `opaque`, which fails LOUD at assertResolved
+    // whether or not anything reads that register (see frontend/opaque.ts for the policy).
     const emitOpaqueDest = (ins: Instr) => {
       // A `%hi`/`%lo` operand on an instruction NOT modelled as a global consumer — an FP load/store
       // (`lwc1`/`ldc1`), or any unmodelled op — reaches here (the modelled consumers handle their own
@@ -889,8 +889,8 @@ export function lift(
       const od = opaqueDest(ins.mnemonic, ins.ops, {
         isReg: isMipsReg,
         isZero,
-        storeClass: /^(sb|sh|sw|swl|swr|sc|sd|sdl|sdr|swc1|sdc1)$/,
-        skipSafe: /^(nop|ssnop|break)$/,
+        storeClass: /^(sb|sh|sw|swl|swr|sc|sd|sdl|sdr|swc1|sdc1)$/i,
+        skipSafe: /^(nop|ssnop|break)$/i,
         context: `${name} @0x${ins.addr.toString(16)}`,
       });
       if (!od) {
@@ -938,6 +938,13 @@ export function lift(
         // incoming STACK-PASSED argument (5th+ param, O32) or an uninitialised local — neither modelled.
         // Without this, readVar would FABRICATE a phantom entry parameter for the slot, silently emitting a
         // function of wrong arity that returns the wrong argument. Loud-fail instead of miscompiling.
+        //
+        // Those two cases are SEPARABLE, and the Thumb frontend now separates them (frontend/thumb.ts,
+        // incomingArgIndex): a slot at or above the callee's own frame cannot have been written by this
+        // function, so it is an incoming argument; below the frame top it is a local. Doing the same here
+        // needs O32's own frame rule — the 16-byte home area means a stack argument is NOT simply "above
+        // the frame", so the Thumb arithmetic does not carry over — plus ssa.ensureParam for the register
+        // half. Until then this stays one loud decline for both.
         if (!ssa.hasReachingDef(stackSlot(off), bi)) {
           throw new FrontendUnsupportedError(
             `cannot lift '${name}': load from stack slot sp@${off} that was never stored ` +

package/src/frontend/opaque.ts

@@ -46,8 +46,9 @@ export interface OpaquePolicy {
   /** token cleanup before classification — e.g. Thumb strips `[`/`]` off a memory operand.
    *  Default: identity. */
   normalize?: (s: string) => string;
-  /** true iff the register is hardwired-zero (MIPS `$zero`/`$0`): writing it is a no-op, so it is
-   *  NOT a real destination and the instruction is safe to skip. Default: nothing is zero. */
+  /** true iff the register is hardwired-zero (MIPS `$zero`/`$0`). It is then not a real
+   *  destination — so there is nothing to degrade and the instruction is REFUSED, not skipped
+   *  (`teq zero, zero` is a trap). Default: nothing is zero. */
   isZero?: (r: string) => boolean;
   /** Mnemonics that WRITE MEMORY in this ISA: the "no register destination ⇒ safe to fall
    *  through" premise is FALSE for stores — skipping one silently deletes the write (Thumb
@@ -63,10 +64,10 @@ export interface OpaquePolicy {
    *  canonical name but must report the one the input file actually contains — otherwise a decline
    *  names an instruction the reader cannot find in their own .s. Defaults to `mnemonic`. */
   display?: string;
-  /** Mnemonics PROVABLY effect-free — or deliberately transparent (Thumb push/pop frame ops) —
-   *  in this ISA: the ONLY unmodelled no-destination instructions that may be skipped. Any other
-   *  no-destination unmodelled instruction THROWS: a side-effect-only instruction (swi, syscall,
-   *  sync, cache…) skipped silently is a deleted effect — a silent miscompile. Default: none. */
+  /** Mnemonics PROVABLY effect-free — or deliberately transparent (Thumb push/pop frame ops) — in
+   *  this ISA: the only unmodelled instructions that may be skipped at all. Anything else with no
+   *  degradable destination THROWS, because a side-effect-only instruction (swi, syscall, sync,
+   *  cache…) skipped silently is a deleted effect. Default: none. */
   skipSafe?: RegExp;
 }
 
@@ -79,16 +80,28 @@ export interface OpaqueDest {
 
 /** Decide the opaque destination + register source operands for an unmodelled instruction
  *  `mnemonic` with operand list `ops` (operands in objdump order — destination first). Returns
- *  `null` only when the instruction is provably skippable: a write to a hardwired-zero register,
- *  or a policy.skipSafe mnemonic. An unmodelled STORE-CLASS instruction (policy.storeClass)
- *  throws loud (a skipped memory write is a silent miscompile) — and so does any OTHER
- *  no-destination instruction not in skipSafe: with no register to degrade to a live-`?`
- *  sentinel, skipping would silently delete a side effect (swi/syscall/sync/cache).
+ *  `null` only for a policy.skipSafe mnemonic. An unmodelled STORE-CLASS instruction
+ *  (policy.storeClass) throws loud (a skipped memory write is a silent miscompile), and so does any
+ *  instruction with no degradable destination: with no register to carry the live-`?` sentinel,
+ *  skipping would silently delete a side effect (swi/syscall/sync/cache).
  *
  *  When non-null, the caller MUST emit an `opaque` op that writes `dst` and consumes `srcRegs`
- *  (read through the frontend's own SSA): a DEAD opaque is DCE'd away harmlessly, while a LIVE one
- *  reaches structuring as the sentinel `?` and trips `assertResolved` — the loud failure the
- *  contract requires, instead of a stale/absent value surfacing as confidently-wrong source. */
+ *  (read through the frontend's own SSA). It reaches structuring as the sentinel `?` and trips
+ *  `assertResolved` — the loud failure the contract requires — WHETHER OR NOT anything reads `dst`;
+ *  `opaque` carries `effects: true` (ir/opcodes.ts) for the same reason `call` does.
+ *
+ *  Two properties of `ops[0]` read as permission to skip and are not. Both describe the
+ *  DESTINATION, while the risk is everything else the instruction does:
+ *    - nobody reads it — a dead register says nothing about a memory or system effect;
+ *    - it is hardwired zero — MIPS `teq zero, zero` is a conditional TRAP.
+ *  So `skipSafe`, a short per-ISA list of provably transparent mnemonics, is the only way an
+ *  unmodelled instruction leaves no trace.
+ *
+ *  `storeClass` is not load-bearing for soundness — a missed store degrades loudly like anything
+ *  else — but it throws naming the memory write instead of an unresolvable value, and it catches
+ *  the shape where `ops[0]` is a SOURCE (MIPS `swl rt, off(base)`) before a `dst` is fabricated
+ *  from it. It and `skipSafe` match case-INSENSITIVELY: mnemonic case is a property of the
+ *  disassembler, not of the instruction. */
 export function opaqueDest(mnemonic: string, ops: string[], policy: OpaquePolicy): OpaqueDest | null {
   const shown = policy.display ?? mnemonic;
   if (policy.storeClass?.test(mnemonic)) {
@@ -102,7 +115,10 @@ export function opaqueDest(mnemonic: string, ops: string[], policy: OpaquePolicy
   }
   const norm = policy.normalize ?? ((s) => s);
   const dst = norm(ops[0] ?? '');
-  if (!policy.isReg(dst)) {
+  // No DEGRADABLE destination: `ops[0]` is not a register, or it is the hardwired zero. Same answer
+  // for both — a zero write is a genuine no-op only for a MODELLED instruction, and by construction
+  // nothing modelled reaches here.
+  if (!policy.isReg(dst) || policy.isZero?.(dst)) {
     if (policy.skipSafe?.test(mnemonic)) {
       return null;
     } // explicitly transparent for this ISA
@@ -111,9 +127,6 @@ export function opaqueDest(mnemonic: string, ops: string[], policy: OpaquePolicy
       `${where}unmodelled effect instruction '${shown}' — no register destination to degrade, and skipping it would silently delete its effect`,
     );
   }
-  if (policy.isZero?.(dst)) {
-    return null;
-  } // writes hardwired zero → a genuine no-op
   const srcRegs = ops.slice(1).map(norm).filter(policy.isReg);
   return { dst, srcRegs };
 }

package/src/frontend/ppc.ts

@@ -24,7 +24,7 @@
 //    the result against 0; that implicit compare is wired so a following `beq`/`bne` fuses.
 //
 // TRUSTWORTHINESS: an unmodelled instruction with a register destination emits an `opaque` value
-// (dead ⇒ vanishes, live ⇒ fails LOUD downstream); an unmodelled CONTROL TRANSFER throws
+// that fails LOUD downstream read or not; an unmodelled CONTROL TRANSFER throws
 // PpcUnsupportedError in `lift`. Never plausible-but-wrong C.
 //
 // Scope: straight-line + `if`/diamond integer functions (incl. the conditional-return idiom),
@@ -480,15 +480,15 @@ export function lift(
     const constVal = kit.cnst;
     const emit = kit.emit;
     // TRUSTWORTHINESS GUARD: an unmodelled instruction must not silently drop its destination —
-    // emit an honest `opaque` instead: dead ⇒ DCE'd; live ⇒ assertResolved fails LOUD (see
-    // frontend/opaque.ts for the policy).
+    // emit an honest `opaque` instead, which fails LOUD at assertResolved whether or not anything
+    // reads that register (see frontend/opaque.ts for the policy).
     const emitOpaqueDest = (ins: Instr) => {
       // storeClass: every PPC store mnemonic is st* — an unmodelled one (`stwbrx`, `sthbrx`, …)
       // must throw, never skip (its first token is the SOURCE register).
       const od = opaqueDest(ins.mnemonic, ins.ops, {
         isReg,
-        storeClass: /^st/,
-        skipSafe: /^nop$/,
+        storeClass: /^st/i,
+        skipSafe: /^nop$/i,
         context: `${name} @0x${ins.addr.toString(16)}`,
       });
       if (!od) {
@@ -567,12 +567,23 @@ export function lift(
         // (anything live across the call has already been moved to a callee-saved register).
         case 'bl': {
           const sym = ins.sym ?? 'func';
-          const argc = protoArity(prototypes[sym]) ?? fallbackArgc(bi);
+          const declared = protoArity(prototypes[sym]);
+          const argc = declared ?? fallbackArgc(bi);
           const args: Value[] = [];
           for (let k = 0; k < argc; k++) {
             args.push(read(ARG_REGS[k]));
           }
-          emit('call', RET, args, { target: sym });
+          // Pushed with `tmp` rather than `emit` so the result register is written AFTER the clobber
+          // is recorded — the order matters: r3.. are volatile under the EABI, so a GUESSED arity
+          // that counted a register set up before an intervening call passes an argument the caller
+          // never set up (`finish()` cuts those back — frontend/ssa.ts), while the call's OWN result
+          // must stay fresh for the next call (`bar(foo())`).
+          const res = kit.tmp('call', args, { target: sym });
+          if (declared === undefined) {
+            ssa.recordGuessedCall(ops[ops.length - 1], bi, ARG_REGS);
+          }
+          ssa.noteCall(bi);
+          write(RET, res);
           break;
         }
         // Stack-frame + link-register bookkeeping. `stwu r1,-N(r1)` / `addi r1,r1,N` adjust the frame