@asmlift/core 0.4.0 → 0.6.0

package/src/raise/gvn.ts

@@ -1,4 +1,5 @@
-// asmlift — value numbering for OPERAND-FREE PURE definitions (today: `gaddr`).
+// asmlift — value numbering for OPERAND-FREE PURE definitions (today `gaddr` and its frame-local
+// twin `laddr`).
 //
 // A compiler materializes a global's address wherever it needs one. Two arms of an `if` that both
 // touch `gTable` each get their own pool load, so the frontend lifts two DISTINCT SSA values that
@@ -23,13 +24,20 @@
 // alone, so two with equal attrs are equal in every execution, on every path, always. Replacing all
 // of them with ONE definition is exact.
 //
-// THE ADMISSION RULE IS `gaddr`, NOT "operand-free and pure" — and the difference is the whole
-// safety argument, so do not relax it to the general-sounding version. `const` is ALSO operand-free
-// and pure, and numbering consts function-wide would be actively harmful: structure/analysis.ts
-// materializes a multi-use `const` that is live across a call into a named local, and its own
-// comment records that this exact widening ("the small-constant regression") already cost matches
-// once. The gate is a MATCHING policy, not a property of the opcode — which is why it is not a flag
-// on the opcode table, where `const` would satisfy it.
+// THE ADMISSION RULE IS A LIST, NOT "operand-free and pure" — and the difference is the whole
+// safety argument, so do not relax it to the general-sounding version. Two more opcodes satisfy the
+// general predicate and each is deliberately out, for a different reason:
+//
+//   `const`   — numbering consts function-wide would be actively HARMFUL: structure/analysis.ts
+//               materializes a multi-use `const` that is live across a call into a named local, and
+//               its own comment records that this exact widening ("the small-constant regression")
+//               already cost matches once.
+//   `undef`   — numbering it would be VACUOUS: two `undef`s in one function always carry different
+//               `key`s (ir/opcodes.ts says so at the opcode), so "same key, therefore same value"
+//               never has two members to collapse.
+//
+// The gate is a MATCHING policy, not a property of the opcode — which is why it is not a flag on
+// the opcode table, where `const` would satisfy it.
 //
 // PLACEMENT. One fresh definition per class is created in the ENTRY block, which dominates every
 // REACHABLE block — so no reachable use can precede it (unreachable blocks are excluded from the
@@ -39,6 +47,9 @@
 // analysis.ts, whose materialize-into-a-local rule covers `const`, `call` and the memory reads, NOT
 // address ops), so the address is re-spelled at each access exactly as the original source did.
 // Hoisting therefore does not create the long live range that hoisting a LOADED value would.
+// That is a promise ANOTHER module keeps, so `test/addr-placement.test.ts` holds it to it: let
+// analysis.ts materialize an address op and the entry hoist becomes a function-top local — the one
+// this pass exists to delete, reintroduced one level up.
 //
 // SCOPE, deliberately narrow: `code: true` symbols (a promoted function pointer, spelled `(u32)Name`
 // rather than `&Name`) are numbered separately from data ones, because the attr is part of what the
@@ -47,15 +58,31 @@
 // THE WIN IS CONTINGENT ON THE SYMBOL MAP, which is worth knowing before relying on it. With a map
 // supplying an array's rank the accesses render as `gSym[0][i]`, a `var` base that
 // `l3/basecse.ts`'s `isHoistableBase` cannot see, so nothing re-creates the local this pass
-// deleted. WITHOUT a map (verified by running the row map-less) the same accesses spell as
-// `addr`, basecse sees the reuse, and it hoists a function-top `p0 = (u16 *)&gBgTilemapBufs` —
-// the same local, one level up. Three modules now answer "is this
-// address a local?" with independent policies (here: never; basecse: when reused 2+ times;
-// l3/scopebase.ts: at the innermost scope), and reconciling them is recorded debt.
+// deleted. WITHOUT one the same accesses spell as `addr`, basecse sees the reuse, and it hoists a
+// function-top `p0 = (u16 *)&gBgTilemapBufs` — the same local, one level up. Both arms are pinned
+// in `test/addr-placement.test.ts`; before that they rested on a run nobody could repeat.
+//
+// Several modules answer "is this address a local?" with independent policies — here: never;
+// basecse: at whichever of the two positions `l3/hoist.ts` is handed (the COMMITTED call states
+// the function top, its roster admissions also offer each init's first use), when the gate table
+// admits the base; l3/scopebase.ts: at the innermost scope holding the uses; l3/argbase.ts:
+// immediately before a call whose arguments share it. The newer placement levers — l3/nearbase.ts,
+// l3/inlinebase.ts, l3/homesplit.ts — answer it too, each with its own.
+// Reconciling them is recorded debt, and the same test pins the two places they actively disagree, because a
+// consolidation has to PICK rather than discover them: a `for`'s init (basecse reads it at loop
+// cadence and refuses, scopebase at the enclosing one and hoists) and a global name shadowed by a
+// local (scopebase must refuse — it re-spells the base as `&g` — while argbase may fire, because it
+// keeps the base expression verbatim).
 import { Block, Fn, Op, Value, mkOp, replaceAllUsesWith } from '../ir/core';
+import type { Opcode } from '../ir/opcodes';
 
-/** Ops whose result depends on `attrs` alone — no operands, no memory, no control flow. */
-const NUMBERABLE = new Set(['gaddr']);
+/** Ops whose result depends on `attrs` alone — no operands, no memory, no control flow. The LIST,
+ *  not the predicate (see the module note); `satisfies` makes a typo a compile error rather than an
+ *  entry that silently matches nothing. `laddr` earns its place on the same argument `gaddr` does —
+ *  operand-free, pure, attr-keyed. */
+const NUMBERABLE = ['gaddr', 'laddr'] as const satisfies readonly Opcode[];
+type NumberableOpcode = (typeof NUMBERABLE)[number];
+const isNumberable = (opcode: string): opcode is NumberableOpcode => (NUMBERABLE as readonly string[]).includes(opcode);
 
 /** The value-number key: the opcode plus every attribute, in a stable order. */
 function keyOf(op: Op): string {
@@ -99,7 +126,7 @@ export function numberPureValues(fn: Fn): number {
       return;
     }
     for (const op of b.ops) {
-      if (NUMBERABLE.has(op.opcode) && op.results.length === 1) {
+      if (isNumberable(op.opcode) && op.results.length === 1) {
         const k = keyOf(op);
         groups.set(k, [...(groups.get(k) ?? []), { op, block: bi }]);
       }
@@ -118,9 +145,7 @@ export function numberPureValues(fn: Fn): number {
     // block, so no path is left reading a definition this pass has moved.
     const survivor = dups[0].op;
     const value: Value = { type: survivor.results[0].type };
-    hoisted.push(
-      mkOp(survivor.opcode as Parameters<typeof mkOp>[0], { results: [value], attrs: { ...survivor.attrs } }),
-    );
+    hoisted.push(mkOp(survivor.opcode as NumberableOpcode, { results: [value], attrs: { ...survivor.attrs } }));
     for (const d of dups) {
       replaceAllUsesWith(fn, d.op.results[0], value);
       removed++;

package/src/raise/latch.ts

@@ -0,0 +1,126 @@
+// asmlift — empty-latch folding (F-CFG-class structural pass; successor-aware, ISA-neutral).
+//
+// A loop whose back-edge carries a register copy — `add r3, r0, #0` then `b .L6` — lifts to a block
+// holding nothing but that branch, because SSA construction turns the copy into an EDGE ARGUMENT.
+// The loop is unchanged; its latch has just become a separate empty block between the exit test and
+// the header. Loop DISCOVERY still finds the loop — `structure/loops.ts` reads the same back-edge —
+// but the do-while emitter requires the latch to end in a `cond_br`, an empty one ends in `br`, and
+// the test is at the bottom so the `while` form is unavailable too. The back-edge survives to the
+// `onStack` refusal and the whole function declines with "unrecovered back-edge".
+//
+// Splicing the block out — every predecessor edge re-pointed at the header, carrying the latch's
+// own edge arguments — restores the single-latch loop, which is a canonicalization the emitter
+// already handles rather than a new case inside it.
+//
+// The arguments move soundly because the block has no params and one op: a value the latch's `br`
+// passes dominates the latch, so it dominates the end of every predecessor of the latch too.
+//
+// WHY DOMINANCE, AND NOT "the target can reach this block". The two disagree on a loop PREHEADER —
+// the same empty forwarding block seen from the other side, which dominates its header instead of
+// the reverse. Reachability alone cannot refuse one, because an INNER loop's preheader sitting
+// inside an OUTER loop is reachable from the inner header round the outer back-edge. Folding a
+// preheader hands the structurer a guard branching straight at the header — the guarded-self-loop
+// shape, where the structurer either fuses under its guard proof or keeps the guard as its own
+// `if` (declining loud on the hazards). The guard therefore survives the fold either way; what the
+// gate preserves is the SHAPE — a forward trampoline is not a latch, and folding one re-casts an
+// unrelated branch as a loop guard — which is the `target-dominates` entry's own note below.
+import { Fn, dominators, foldWriteOrder } from '../ir/core';
+import { type Gate, firstRejection } from '../l3/gates';
+
+/** What the gates below judge: one candidate block and the block its `br` goes to. */
+interface LatchCandidate {
+  block: Fn['blocks'][number];
+  target: Fn['blocks'][number];
+  dominatesBlock: boolean;
+}
+
+export const LATCH_GATES: readonly Gate<LatchCandidate>[] = [
+  {
+    id: 'latch-has-params',
+    why: "a param means the block JOINS edges, so its br args are not this one edge's copy",
+    sound: false,
+    rejects: (c) => c.block.params.length > 0,
+  },
+  {
+    // WHAT THIS RULE ACTUALLY DECIDES, which is narrower than its id suggests. A block carrying real
+    // work never reaches the table at all: `foldEmptyLatches`' pre-check reads `ops[0].successors[0]`,
+    // so a first op that is a `store` (or any non-terminator) has no target and is refused there.
+    // What is left for this rule is the block whose sole op IS a terminator but not a `br` — a
+    // `cond_br`, whose SECOND successor the fold would discard along with the block.
+    id: 'latch-does-work',
+    why: 'the sole terminator must be an unconditional `br`: folding a `cond_br` block discards its second successor',
+    sound: true,
+    guardedBy: 'latch.test.ts: a latch whose sole op is a cond_br is refused — folding it would drop its second arm',
+    // `br` is a terminator, so a block whose FIRST op is one holds nothing but that branch.
+    rejects: (c) => c.block.ops[0]?.opcode !== 'br',
+  },
+  {
+    id: 'self-branch',
+    why: 'every block dominates itself, so this is an infinite loop rather than a trampoline',
+    sound: false,
+    rejects: (c) => c.target === c.block,
+  },
+  {
+    id: 'target-dominates',
+    why: "a preheader is the same empty block from the other side; folding it re-shapes another block's branch into a loop guard",
+    // NOT `sound`, and the burden it used to carry now lives elsewhere: the guarded-self-loop
+    // emitter refuses to fuse an unproven guard — it keeps its `if`, or declines loud — and a
+    // multi-block loop's guard has no fusion path to lose it to at all. So ablating this gate
+    // re-shapes the C without making it wrong, which is a heuristic by the Gate contract. The named
+    // test pins that second layer.
+    sound: false,
+    guardedBy: 'latch.test.ts: ablating the dominance gate hands a guard to the kept-guard loop emitter',
+    rejects: (c) => !c.dominatesBlock,
+  },
+];
+
+/** Splice out every EMPTY LATCH the gates above admit; returns how many were removed.
+ *
+ *  Iterated, because folding one latch can make its predecessor into one: the predecessor's
+ *  SUCCESSOR changes, so an edge that was not a back-edge becomes one. (Dominator sets themselves
+ *  only ever shrink — removing a block removes it from every set it was in.)
+ *
+ *  A predecessor that already branches to the target ends up with two edges into one block. That is
+ *  a block whose every edge continues the loop, so it has no exit and loop recovery declines — the
+ *  same loud decline it gave before the fold.
+ */
+export function foldEmptyLatches(fn: Fn, gates: readonly Gate<LatchCandidate>[] = LATCH_GATES): number {
+  let folded = 0;
+  for (;;) {
+    const dom = dominators(fn);
+    const latch = fn.blocks.find((b) => {
+      // THE PRE-CHECK IS WHAT REFUSES A WORK-CARRYING BLOCK. A block whose first op computes
+      // something — a `store`, an arithmetic op — is not a terminator and so has no successors, and
+      // a candidate with no target is not judged at all. The gates below therefore only ever see a
+      // block whose FIRST op is a terminator; `latch-does-work` is the one that then insists it be
+      // an unconditional `br`.
+      const target = b.ops[0]?.successors[0]?.block;
+      return (
+        target !== undefined &&
+        firstRejection(gates, { block: b, target, dominatesBlock: dom.get(b)!.has(target) }) === null
+      );
+    });
+    if (!latch) {
+      return folded;
+    }
+    const onward = latch.ops[0].successors[0];
+    for (const b of fn.blocks) {
+      let repointed = false;
+      for (const op of b.ops) {
+        op.successors.forEach((s, i) => {
+          if (s.block === latch) {
+            op.successors[i] = { block: onward.block, args: [...onward.args] };
+            repointed = true;
+          }
+        });
+      }
+      // The copies the latch stood for now happen at the end of this predecessor — after its own
+      // writes, which the write-order record has to keep saying (ir/core.ts `foldWriteOrder`).
+      if (repointed) {
+        foldWriteOrder(fn.writeOrder, latch, b);
+      }
+    }
+    fn.blocks = fn.blocks.filter((b) => b !== latch);
+    folded++;
+  }
+}