@asmlift/core 0.9.0 → 0.11.0

package/src/runtime-helpers.ts

@@ -29,9 +29,10 @@
 // REGISTERS the list occupies, and `irWidthOf` gives the IR width one parameter ARRIVES at once a
 // frontend has paired those registers up.
 import { type Op, type Value, mkOp } from './ir/core';
-import { FLOAT_OPS, type Opcode, WIDE_BITS } from './ir/opcodes';
+import { FLOAT_COMPUTING, FLOAT_TO_INT, INT_TO_FLOAT, NEGATED_FCMP, type Opcode, WIDE_BITS } from './ir/opcodes';
 import { type IrType, intWidth } from './ir/types';
 import { type Prototypes, wordsOf } from './proto';
+import type { TargetDescription } from './target';
 
 export interface RuntimeHelper {
   /** the op this helper computes, where asmlift has one. Absent for a helper it can only SIGN. */
@@ -40,6 +41,19 @@ export interface RuntimeHelper {
   params: readonly number[];
   /** the returned width: 0 (void), 32, or 64 (a register PAIR). */
   returns: 0 | 32 | 64;
+  /** A THREE-WAY FLOAT COMPARE: its result's SIGN orders its two operands (negative, zero, positive
+   *  for less, equal, greater), and this is the value it returns where either is a NaN. A compare
+   *  folds through the integer test its caller applies to the result (raise/floathelpers.ts), so it
+   *  carries this in place of an `op`. */
+  unordered?: 1 | -1;
+  /** THE RELATION THE SOURCE SPELLED, for a compare helper whose relation and its negation are both
+   *  C operators — `__eqsf2` for `==`, `__nesf2` for `!=`. agbcc's gcc folds `!(a == b)` into
+   *  `a != b` before it picks a helper, so the helper names the relation the source wrote, and a
+   *  lift that spells its negation (or the negation's `!`) recompiles to the other helper. The fold
+   *  stamps it on the compare as `attrs.relation` (raise/floathelpers.ts), and the structurer keeps
+   *  that relation's spelling by choosing the arm order instead (l3/ast.ts `Expr.helperRel`). The
+   *  ordered four need none: `!(a > b)` keeps `__gtsf2`, and no other helper computes it. */
+  relation?: 'fcmp_oeq' | 'fcmp_une';
 }
 
 /** The entry a target's table holds for `callee`, or undefined. THE ONE READER, because the table
@@ -118,19 +132,34 @@ export function helperOp(opcode: Opcode, helper: string, operands: readonly Valu
   return mkOp(opcode, { operands: [...operands], results: [result], attrs: { helper } });
 }
 
-/** Whether a helper computes on floats: its op is a float op, so its operands and result are floats
- *  of the widths its signature states, carried in integer registers by a soft-float runtime. Every
- *  reader of the table asks this and not the width, because the two families fold into different
- *  IR: an integer helper into its op over the same values, a float helper into a float op over
- *  values re-typed as floats (`raise/floathelpers.ts`). */
+/** Whether a helper computes on floats: its op is a float op, a conversion or a compare, so the
+ *  operands and the result that op takes as floats are floats of the widths its signature states,
+ *  carried in integer registers by a soft-float runtime. Every reader of the table asks this and
+ *  not the width, because the two families fold into different IR: an integer helper into its op
+ *  over the same values, a float helper into its op over values re-typed as floats where the op
+ *  takes one (`raise/floathelpers.ts`). */
 export function isFloatHelper(h: RuntimeHelper): boolean {
-  return h.op !== undefined && FLOAT_OPS.has(h.op);
+  return h.unordered !== undefined || (h.op !== undefined && FLOAT_COMPUTING.has(h.op));
+}
+
+/** Which sides of a float helper are floats: its operands (one kind for all of them, in every op
+ *  here) and its result. A conversion has an integer on one side; a compare returns one. */
+export function floatSidesOf(h: RuntimeHelper): { operands: boolean; result: boolean } {
+  const op = h.op ?? '';
+  return {
+    operands: !INT_TO_FLOAT.has(op),
+    result: h.unordered === undefined && !FLOAT_TO_INT.has(op) && NEGATED_FCMP[op] === undefined,
+  };
 }
 
 /** Signatures for a target's helpers, in the WORD arity the frontend's prototype lookup speaks.
  *  Consumed behind any caller-supplied prototype — the project's own headers win. */
-export function helperPrototypes(table: Readonly<Record<string, RuntimeHelper>> | undefined): Prototypes {
-  return Object.fromEntries(Object.entries(table ?? {}).map(([sym, h]) => [sym, { params: wordsOf(h.params) }]));
+export function helperPrototypes(
+  target: Pick<TargetDescription, 'runtimeHelpers' | 'evenWordAlignedArgs'>,
+): Prototypes {
+  return Object.fromEntries(
+    Object.entries(target.runtimeHelpers ?? {}).map(([sym, h]) => [sym, { params: wordsOf(h.params, target) }]),
+  );
 }
 
 /** agbcc's runtime, which is GCC 2.9's libgcc for ARM.
@@ -142,20 +171,32 @@ export function helperPrototypes(table: Readonly<Record<string, RuntimeHelper>>
  *  operand SET-UP instead — `asr rN,rM,#31` per half for signed, `mov rN,#0` for unsigned. The
  *  DIVISIONS do split, and their entries say so.
  *
- *  THE DOUBLE ARITHMETIC IS HERE, AND NOTHING ELSE OF THE SOFT FLOAT. `optabs.c:4022`
- *  `init_floating_libfuncs` names DFmode's add, sub, mul, div (4129-4140) and neg (4155), and
- *  `thumb.md` has no DF pattern but the move, so every one of them is a call; the ABI is a long
- *  long's (thumb.h:632, 655). `raise/floathelpers.ts` folds them to the float ops over a `double`.
+ *  THE FLOAT ARITHMETIC OF BOTH PRECISIONS IS HERE, AND FOLDS. `optabs.c:4022`
+ *  `init_floating_libfuncs` names each mode's add, sub, mul, div (4129-4140) and neg (4155), and
+ *  `thumb.md` has no SF or DF pattern but the move, so every one of them is a call; a single
+ *  travels as an int's word and a double as a long long's pair (thumb.h:632, 655).
+ *  `raise/floathelpers.ts` folds them to the float ops over a `float` or a `double`.
  *
- *  NAMING THEM IS A TRADE, and these five make it: a call the fold refuses declines where an
- *  unnamed helper would publish as a pass-through that matches for free. So a function whose
- *  double arithmetic feeds a compare (`__gtdf2`…), a conversion (`__fixdfsi`…) or any other call
- *  declines, where unnamed it would print `__muldf3(); return __fixdfsi();`. The compares and
- *  conversions of both precisions stay out, because the IR has no int<->float op to fold one into;
- *  the single-precision arithmetic stays out because its pass-throughs are what the float rows
- *  score on (`synthetic:fadd:agbcc`), and declining them is the same trade, to be made with a
- *  measurement of those rows. Making it is a table row: the fold reads each value's width off the
- *  signature. */
+ *  NAMING THEM IS A TRADE, and these ten make it: a call the fold refuses declines where an unnamed
+ *  helper would publish as a pass-through. So a function whose float arithmetic feeds a compare, a
+ *  conversion or an ordinary call declines, where unnamed it would print `__muldf3(); g();`. For
+ *  the singles that pass-through is wrong C: unnamed, `__mulsf3`'s arity is GUESSED (frontend/ssa.ts
+ *  `fallbackArgc`), and a guess drops what the function passes on unchanged — `a * b + c` as
+ *  `__addsf3(__mulsf3(), a2)`, `a + b` as `__addsf3()`.
+ *
+ *  THE CONVERSIONS FOLD TOO, to the cast each computes (`fptosi`, `sitofp`, `fpext` …), with an
+ *  integer on one side that `raise/floathelpers.ts` takes as any integer. THE COMPARES fold through
+ *  the test their caller applies to the integer they return, by libgcc's contract for it
+ *  (`unordered`), and one whose result is read any other way refuses (`refuseUnmodelledHelpers`).
+ *  Unnamed, each would be the same guess, dropping the argument passed on unchanged and matching
+ *  byte for byte: `(int)x` as `__fixsfsi()`, `(float)i` as `__floatsisf()`, `a > b` as
+ *  `__gtsf2() > 0`. The names are the ones agbcc
+ *  emits for every compare, every conversion between `int`, `unsigned`, `long long` and either
+ *  precision, and every widening and narrowing between the two precisions (compiled evidence: one
+ *  function per operation at the canonical flags). There is no conversion of an unsigned integer
+ *  INTO a float: agbcc open-codes `(float)u` around `__floatsisf` and `__addsf3`. `__cmpdi2`, which
+ *  it also calls converting an `unsigned long long`, is an integer compare and outside this
+ *  family. */
 export const AGBCC_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> = {
   // 32-bit software division — the ops `raise/softdiv.ts` rewrites, gated on the target having no
   // hardware divider, which is what those four are about.
@@ -180,6 +221,45 @@ export const AGBCC_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> = {
   __muldf3: { op: 'fmul', params: [64, 64], returns: 64 },
   __divdf3: { op: 'fdiv', params: [64, 64], returns: 64 },
   __negdf2: { op: 'fneg', params: [64], returns: 64 },
+  // Single arithmetic, one float in one register each way (thumb.h:632's word).
+  __addsf3: { op: 'fadd', params: [32, 32], returns: 32 },
+  __subsf3: { op: 'fsub', params: [32, 32], returns: 32 },
+  __mulsf3: { op: 'fmul', params: [32, 32], returns: 32 },
+  __divsf3: { op: 'fdiv', params: [32, 32], returns: 32 },
+  __negsf2: { op: 'fneg', params: [32], returns: 32 },
+  // The compares, one int out of two floats of either precision, each libgcc's three-way
+  // `__fpcmp_parts` when both are ordered (fp-bit.c:1117-1188). On a NaN each returns the value its
+  // own relation tests FALSE on — `== 0`, `< 0`, `<= 0` are false on 1, `> 0`, `>= 0` on -1 — except
+  // `__nesf2`, whose 1 makes `!=` true (fp-bit.c:1214-1309). agbcc tests the result against 0 with
+  // the relation the helper is named for.
+  __eqsf2: { params: [32, 32], returns: 32, unordered: 1, relation: 'fcmp_oeq' },
+  __nesf2: { params: [32, 32], returns: 32, unordered: 1, relation: 'fcmp_une' },
+  __gtsf2: { params: [32, 32], returns: 32, unordered: -1 },
+  __gesf2: { params: [32, 32], returns: 32, unordered: -1 },
+  __ltsf2: { params: [32, 32], returns: 32, unordered: 1 },
+  __lesf2: { params: [32, 32], returns: 32, unordered: 1 },
+  __eqdf2: { params: [64, 64], returns: 32, unordered: 1, relation: 'fcmp_oeq' },
+  __nedf2: { params: [64, 64], returns: 32, unordered: 1, relation: 'fcmp_une' },
+  __gtdf2: { params: [64, 64], returns: 32, unordered: -1 },
+  __gedf2: { params: [64, 64], returns: 32, unordered: -1 },
+  __ltdf2: { params: [64, 64], returns: 32, unordered: 1 },
+  __ledf2: { params: [64, 64], returns: 32, unordered: 1 },
+  // The conversions: to and from a word, to and from a long long, and between the precisions.
+  // `__fix*` truncates toward zero, as C's conversion out of a float does.
+  __fixsfsi: { op: 'fptosi', params: [32], returns: 32 },
+  __fixunssfsi: { op: 'fptoui', params: [32], returns: 32 },
+  __floatsisf: { op: 'sitofp', params: [32], returns: 32 },
+  __fixdfsi: { op: 'fptosi', params: [64], returns: 32 },
+  __fixunsdfsi: { op: 'fptoui', params: [64], returns: 32 },
+  __floatsidf: { op: 'sitofp', params: [32], returns: 64 },
+  __fixsfdi: { op: 'fptosi', params: [32], returns: 64 },
+  __fixunssfdi: { op: 'fptoui', params: [32], returns: 64 },
+  __floatdisf: { op: 'sitofp', params: [64], returns: 32 },
+  __fixdfdi: { op: 'fptosi', params: [64], returns: 64 },
+  __fixunsdfdi: { op: 'fptoui', params: [64], returns: 64 },
+  __floatdidf: { op: 'sitofp', params: [64], returns: 64 },
+  __extendsfdf2: { op: 'fpext', params: [32], returns: 64 },
+  __truncdfsf2: { op: 'fptrunc', params: [64], returns: 32 },
 };
 
 /** CodeWarrior's PowerPC runtime (`Runtime.PPCEABI.H`), as the GameCube projects vendor it.
@@ -220,6 +300,44 @@ export const PPC_MWCC_RUNTIME_HELPERS: Readonly<Record<string, RuntimeHelper>> =
   __shr2u: { op: 'shr_u', params: [64, 32], returns: 64 },
 };
 
+/** A compiler runtime's OUT-OF-LINE REGISTER SAVE AND RESTORE ROUTINES: a prologue that saves a run
+ *  of callee-saved registers by calling into the runtime instead of storing each one inline. A
+ *  compiler fact, like the table above, and it hangs off `TargetDescription` for the same reason:
+ *  which compiler emits the family, at which level, is measured per build, and a frontend that
+ *  hard-coded the names would recognise them on a target whose runtime has no such routine.
+ *
+ *  A call to one is FRAME BOOKKEEPING, not a call: it writes no register but the link register, and
+ *  the frame address in `frameReg` is the only thing it reads (frontend/ppc.ts `saveRoutine`). */
+export interface RegisterSaveRoutines {
+  /** the register a routine takes its frame address in. The save area is the words just BELOW it. */
+  frameReg: string;
+  /** every routine name, with three groups: `save` or `rest`, the register file (`gpr`/`fpr`), and
+   *  the first register the routine moves — it moves that one up to the file's last, 31. */
+  name: RegExp;
+}
+
+/** The routine a callee symbol names under `routines`, or null when it names none. */
+export function registerSaveRoutineOf(
+  routines: RegisterSaveRoutines | undefined,
+  sym: string,
+): { sym: string; restore: boolean; fpr: boolean; first: number } | null {
+  const m = routines?.name.exec(sym);
+  return m ? { sym: m[0], restore: m[1] === 'rest', fpr: m[2] === 'fpr', first: Number(m[3]) } : null;
+}
+
+/** CodeWarrior's `_savegpr_NN` / `_restgpr_NN` and `_savefpr_NN` / `_restfpr_NN`, called after
+ *  `addi r11,r1,N`. `_savegpr_NN` stores rNN..r31 into the 4*(32-NN) bytes just below r11, and
+ *  `_savefpr_NN` stores fNN..f31 into the 8*(32-NN) bytes below it.
+ *
+ *  COMPILED, per build: 2.4.2 and 2.4.7 emit the family at every level (`-O4,p`, `-O4,s`, `-O0,p`).
+ *  2.3.3 never does at Pikmin's `-O4,p`, where it saves with `stmw` and inline `stfd`, but does at
+ *  `-O0,p` and `-O4,s`; all three builds share `PPC_MWCC`, so the description carries it. The bench's
+ *  feature tagger reads this same pattern (apps/benchmark `features.ts`). */
+export const PPC_MWCC_SAVE_ROUTINES: RegisterSaveRoutines = {
+  frameReg: 'r11',
+  name: /^_(save|rest)(gpr|fpr)_(\d+)$/,
+};
+
 /** IDO 7.1's runtime for the 64-bit operations MIPS II has no instruction for, a family of its own
  *  (`__ll_*` for signed, `__ull_*` for unsigned): a scan for `__*di3` reports zero on it.
  *

package/src/structure/analysis.ts

@@ -28,6 +28,7 @@ import {
   defOpMap,
   dominators,
   mergeClasses,
+  opShape,
   predecessors,
   successorsOf,
 } from '../ir/core';
@@ -892,7 +893,7 @@ export interface AnalyzeOptions {
    *  A compiler behavior (TargetDescription.compilerBehaviors `readsStayWhereWritten`), not
    *  a differ-refereed variation, and that distinction is the argument: a variation exists where the asm
    *  UNDERDETERMINES the source, some pass having collapsed two spellings onto one output
-   *  (`/uns-cmp`'s non-negativity proof is the type case). Where the compiler emits a read in the
+   *  (`/signed-cmp`'s non-negativity proof is the type case). Where the compiler emits a read in the
    *  block the source spelled it in, re-spelling it at the block the asm read in reproduces that
    *  asm while the sunk spelling is one it emits only for a source that read per arm — nothing for
    *  the differ to referee, and the extra candidate is pure cost. Which compilers may declare
@@ -1006,12 +1007,18 @@ function makeMemWriteBetween(deps: {
     if (wDirty(b.ops, oi + 1, b.ops.length) || wDirty(render.blk.ops, 0, render.idx)) {
       return true;
     }
-    for (const x of reachAvoiding(b, b)) {
-      if (x === render.blk && !reachAvoiding(render.blk, b).has(render.blk)) {
-        continue; // acyclic render block: head checked
-      }
-      if (x !== render.blk && !reachAvoiding(x, b).has(render.blk)) {
-        continue; // not on a def→render path
+    // The between-blocks: every `x` the def's block reaches without re-crossing it from which the
+    // render block is reached again in at least one step, by the same def-avoiding walk. The render
+    // block itself counts only where it reaches itself so (its head is checked above); any other
+    // block only where it lies on a def→render path.
+    const forward = reachAvoiding(b, b);
+    if (!forward.has(render.blk)) {
+      return false; // every block on a def→render path is one the def's block reaches
+    }
+    const onPath = blocksReaching(forward, render.blk, b);
+    for (const x of forward) {
+      if (!successorsOf(x).some((s) => s !== b && onPath.has(s))) {
+        continue; // not on a def→render path (or, for the render block, acyclic: head checked)
       }
       if (wDirty(x.ops, 0, x.ops.length)) {
         return true;
@@ -1021,6 +1028,49 @@ function makeMemWriteBetween(deps: {
   };
 }
 
+/** The blocks of `within` that reach `target` in zero or more steps without passing `avoid`,
+ *  `target` included: one backward walk over `within`'s own edges.
+ *
+ *  `makeMemWriteBetween` asks, for each block `x` the def's block reaches, whether `target` is in
+ *  `reachAvoiding(x, avoid)`. That is a forward walk per `x`, quadratic in the function's size per
+ *  question, and the question is asked per op `analyze` names (`nameAccess`): Klonoa's
+ *  sub_0800D188 (1,783 blocks) spent most of its structuring in those walks. `target` is in
+ *  `reachAvoiding(x, avoid)` exactly where some successor of `x` other than `avoid` is in this set,
+ *  since every block on such a path after `x` is in `within` (`within` being everything the def's
+ *  block reaches without passing `avoid`, from which `x` was drawn). */
+function blocksReaching(within: ReadonlySet<Block>, target: Block, avoid: Block): Set<Block> {
+  const into = new Map<Block, Block[]>();
+  for (const y of within) {
+    if (y === avoid) {
+      continue;
+    }
+    for (const s of successorsOf(y)) {
+      if (s !== avoid && within.has(s)) {
+        const list = into.get(s);
+        if (list === undefined) {
+          into.set(s, [y]);
+        } else {
+          list.push(y);
+        }
+      }
+    }
+  }
+  const out = new Set<Block>();
+  if (target === avoid) {
+    return out;
+  }
+  out.add(target);
+  for (const work = [target]; work.length;) {
+    for (const y of into.get(work.pop()!) ?? []) {
+      if (!out.has(y)) {
+        out.add(y);
+        work.push(y);
+      }
+    }
+  }
+  return out;
+}
+
 /** INTERDEPENDENT PARALLEL-COPY ARGS. A terminator's successor args are ONE parallel copy
  *  (argAssigns), whose every read means the PRE-copy value. An arg whose def-tree reads a SIBLING
  *  arg of the same edge cannot read it by name there — so the sibling's whole expression is
@@ -1521,6 +1571,9 @@ interface LoopRules {
   /** The def's value enters some loop's header live and every consumer sits outside that loop, as
    *  does the def: the value is carried ACROSS the loop, not into it. */
   liveAcrossLoop(def: Op, r: Value, consumers: Op[]): boolean;
+  /** `liveAcrossLoop`, and neither the def nor any consumer sits in any loop, enclosing ones
+   *  included: never a value the compiler could have hoisted out of one. */
+  carriedPastLoops(def: Op, r: Value, consumers: Op[]): boolean;
   /** Does `r`, computed by `op` in `L`'s body, read a loop variable the update overwrites? */
   readsPreUpdate(L: BottomTestedLoop, op: Op, r: Value): boolean;
   escapesAheadOfUpdate(op: Op, r: Value, consumers: Op[]): boolean;
@@ -1551,6 +1604,9 @@ function makeLoopRules(a: {
         !L.body.has(opBlock.get(def)!) &&
         consumers.every((c) => !L.body.has(opBlock.get(c)!)),
     );
+  const carriedPastLoops = (def: Op, r: Value, consumers: Op[]): boolean =>
+    liveAcrossLoop(def, r, consumers) &&
+    loopBodies.every((L) => !L.body.has(opBlock.get(def)!) && consumers.every((c) => !L.body.has(opBlock.get(c)!)));
   /** THE PRE-UPDATE ESCAPE. A value a bottom-tested loop computes and the code after it reads,
    *  whose expression reads a loop variable — `do { s = &f->v; f = f->next; } while (--n); *out =
    *  s;`. Inlined at the post-loop read it re-reads that variable's NAME, which by then holds the
@@ -1710,6 +1766,7 @@ function makeLoopRules(a: {
     multiBlockHeaders,
     bottomTested,
     liveAcrossLoop,
+    carriedPastLoops,
     readsPreUpdate,
     escapesAheadOfUpdate,
     rebuiltPast,
@@ -2042,6 +2099,20 @@ function namePureOp(rules: MaterializeRules, state: MaterializeState, op: Op, b:
   } else if (op.opcode !== 'const' && pr && copyInterdependent.has(pr) && !scopes.addressCone(op)) {
     materialize.add(op);
   }
+  // A PURE VALUE CARRIED ACROSS A LOOP, computed and read outside every loop, as `nameAccess` names
+  // a read (`carriedPastLoops`; a value read inside a loop is `/expr-home`'s question, where loop.c's
+  // invariant motion may have put it). `j = n * 3; for (…) { if (t[i] == 7) { gHit = j; break; } }`
+  // computes `j` ahead of the loop and holds it in a register to the break arm, which sits outside
+  // the natural loop. Inlined, `gHit = n * 3` moves the computation into the arm, and every profile
+  // compiles it there (IDO scores the two alike). A `const` is re-materialized where it is used, and
+  // an address loses its inline byte-stride cast standing alone and is what a compiler CSEs and
+  // moves freely, so neither is named.
+  if (op.opcode !== 'const' && pr && useSitesOf.has(pr) && !scopes.addressCone(op) && !rendersAsAddress(op)) {
+    const cons = [...new Set((useSitesOf.get(pr) ?? []).map((s) => s.op))];
+    if (loops.carriedPastLoops(op, pr, cons)) {
+      materialize.add(op);
+    }
+  }
   // A float PRODUCT read by a float add or subtract, directly or through a negation, is named
   // on a compiler that contracts (target.ts `contractsFloatProducts`): it fuses only WITHIN
   // one expression, so the inline `a * b + c` recompiles to one `fmadds` — one rounding, a
@@ -2248,7 +2319,7 @@ function isBarrier(rules: MaterializeRules, materialize: ReadonlySet<Op>, access
   // order is the compiler's to choose (`gY = VCOUNT - TM0CNT_L` reads VCOUNT first); a
   // qualified read spelled as a bare statement because nothing uses it is an access too.
   if (once && !isCall && (x.opcode === 'load' || x.opcode === 'aload') && counted(x)) {
-    return true;
+    return !interchangeableReads(rules, x, op);
   }
   if (!isCall) {
     return false;
@@ -2261,6 +2332,144 @@ function isBarrier(rules: MaterializeRules, materialize: ReadonlySet<Op>, access
   return false;
 }
 
+const COMMUTATIVE_OPS: ReadonlySet<string> = new Set(['add', 'mul', 'and', 'or', 'xor']);
+
+/** Do two values name the same address: one value, or two `gaddr`s of one symbol? */
+function sameAddress(defOf: Map<Value, Op>, a: Value, b: Value): boolean {
+  if (a === b) {
+    return true;
+  }
+  const da = defOf.get(a);
+  const db = defOf.get(b);
+  return (
+    da !== undefined &&
+    db !== undefined &&
+    da.opcode === 'gaddr' &&
+    db.opcode === 'gaddr' &&
+    opShape(da) === opShape(db)
+  );
+}
+
+/** Are two qualified reads of ONE cell interchangeable in the one expression they feed: the same
+ *  access of the same address, each the sole use of its value up a chain of ops alike but for it,
+ *  the two chains meeting as the two operands of one commutative op? Then the expression's value is
+ *  the same whichever read the compiler makes first, and its order is the compiler's to choose:
+ *  `gR + gR` over `extern volatile u32 gR;` and `*gPV + *gPV` over `u16 *volatile gPV` read the
+ *  object twice, in an order the source never stated, so naming the first read into a temp spells
+ *  an order the source did not have (ido 7.1 loads `gR + gR` in the other order). The meeting op
+ *  may also be a sum both reads enter with one sign, past a reassociation (`sameSignInOneSum`).
+ *  `gR - gR` is not symmetric — the order decides which read is the minuend — and stays sequenced.
+ *  `a` is the later read, `b` the earlier one placed past it. */
+function interchangeableReads(rules: MaterializeRules, a: Op, b: Op): boolean {
+  const { defOf } = rules;
+  if (
+    a === b ||
+    opShape(a) !== opShape(b) ||
+    a.operands.length !== b.operands.length ||
+    !a.operands.every((v, i) => sameAddress(defOf, v, b.operands[i]))
+  ) {
+    return false;
+  }
+  return mirroredChains(rules, a, b) || sameSignInOneSum(rules, b, a);
+}
+
+/** The two reads' sole-use chains are alike but for them and meet as the two operands of one
+ *  commutative op: `(gR << 1) * (gR << 1)`. */
+function mirroredChains(rules: MaterializeRules, a: Op, b: Op): boolean {
+  const { useSitesOf } = rules.uses;
+  let ca = a;
+  let cb = b;
+  for (let depth = 0; depth < 8; depth++) {
+    const va = ca.results[0];
+    const vb = cb.results[0];
+    const ua = va === undefined ? undefined : useSitesOf.get(va);
+    const ub = vb === undefined ? undefined : useSitesOf.get(vb);
+    if (ua?.length !== 1 || ub?.length !== 1) {
+      return false;
+    }
+    const na = ua[0].op;
+    const nb = ub[0].op;
+    if (na === nb) {
+      return (
+        COMMUTATIVE_OPS.has(na.opcode) &&
+        na.successors.length === 0 &&
+        na.operands.length === 2 &&
+        ((na.operands[0] === va && na.operands[1] === vb) || (na.operands[0] === vb && na.operands[1] === va))
+      );
+    }
+    if (
+      opShape(na) !== opShape(nb) ||
+      na.successors.length > 0 ||
+      nb.successors.length > 0 ||
+      (MEM_BASE_OPS.has(na.opcode) && counted(na)) ||
+      na.operands.length !== nb.operands.length ||
+      !na.operands.every((v, i) => (v === va ? nb.operands[i] === vb : v === nb.operands[i] && v !== vb))
+    ) {
+      return false;
+    }
+    ca = na;
+    cb = nb;
+  }
+  return false;
+}
+
+/** Each read's sole-use chain up through `add`/`sub` ops, as the ops it passes and the read's sign in
+ *  each: entering an `add`, or a `sub` as its minuend, keeps the sign; entering a `sub` as its
+ *  subtrahend flips it. The value of every op on the chain is then that sign times the read, plus
+ *  terms the read is not in. */
+function additiveChain(rules: MaterializeRules, read: Op): Map<Op, { sign: number; operand: number }> {
+  const { useSitesOf } = rules.uses;
+  const chain = new Map<Op, { sign: number; operand: number }>();
+  let v = read.results[0];
+  let sign = 1;
+  for (let depth = 0; depth < 8 && v !== undefined; depth++) {
+    const uses = useSitesOf.get(v);
+    if (uses?.length !== 1) {
+      break;
+    }
+    const n = uses[0].op;
+    const operand = n.operands.indexOf(v);
+    if (
+      (n.opcode !== 'add' && n.opcode !== 'sub') ||
+      n.operands.length !== 2 ||
+      n.results.length !== 1 ||
+      n.successors.length > 0 ||
+      n.operands.lastIndexOf(v) !== operand
+    ) {
+      break;
+    }
+    sign = n.opcode === 'sub' && operand === 1 ? -sign : sign;
+    chain.set(n, { sign, operand });
+    v = n.results[0];
+  }
+  return chain;
+}
+
+/** The two reads meet in one sum with the same sign: their sole-use chains run through `add`/`sub`
+ *  ops only, to an op one reaches through each operand, where each counts with the same sign. The
+ *  sum is then the same whichever read is made first, however the compiler reassociated it:
+ *  ido 7.1 compiles `(gR - x) + (gR - x)` as `((gR - x) + gR) - x`, where one read passes a `sub`
+ *  before the `add` they meet in and the other does not, so the chains are not mirrored. `gR - gR`
+ *  meets with opposite signs and stays sequenced. Wrapping arithmetic keeps the sum associative.
+ *  The value is then right in either order, but the match is not: the earlier read must also be
+ *  the one the expression spells first, entering the meeting op as its left operand, or a compiler
+ *  that reads operands left to right reverses the asm's two loads. mwcc 2.4.2 reads
+ *  `gMS.f + ((t + gMS.f) + t)`'s right-hand `gMS.f` first, so spelling both in one expression
+ *  there puts the asm's second load first. */
+function sameSignInOneSum(rules: MaterializeRules, earlier: Op, later: Op): boolean {
+  const ofEarlier = additiveChain(rules, earlier);
+  if (ofEarlier.size === 0) {
+    return false;
+  }
+  for (const [n, inLater] of additiveChain(rules, later)) {
+    const inEarlier = ofEarlier.get(n);
+    if (inEarlier !== undefined) {
+      return inEarlier.operand === 0 && inLater.operand === 1 && inEarlier.sign === inLater.sign;
+    }
+  }
+  return false;
+}
+
 /** The rules for a memory access — a `call`, `load` or `aload` — in order; the first that names
  *  the op ends the walk. */
 function nameAccess(rules: MaterializeRules, state: MaterializeState, op: Op, b: Block): void {

package/src/structure/arith-ops.ts

@@ -0,0 +1,23 @@
+// asmlift structurer — the IR's integer arithmetic opcodes and the L3 operator each one renders
+// as. The float ops are FLOAT_TO_BIN in structure.ts, which says why they are not here.
+import type { BinOp } from '../l3/ast';
+
+export const ARITH_TO_BIN: Record<string, BinOp> = {
+  add: '+',
+  sub: '-',
+  mul: '*',
+  sdiv: '/',
+  // the UNSIGNED quotient/remainder — the C backend spells them `/`/`%` over an operand it casts
+  // unsigned (l3/ast.ts BinOp, backend/cfamily.ts C_SPELLING)
+  udiv: '/u',
+  smod: '%',
+  umod: '%u',
+  or: '|',
+  and: '&',
+  xor: '^',
+  shl: '<<',
+  shr_u: '>>>', // the LOGICAL right shift; the C backend spells it `>>` over an unsigned operand
+  shr_s: '>>',
+  logic_and: '&&',
+  logic_or: '||', // short-circuit connectives (raise/shortcircuit.ts)
+};