@asmlift/core 0.8.1 → 0.10.0

package/src/frontend/device-pins.ts

@@ -0,0 +1,296 @@
+/** THE DEVICE PIN: which memory accesses of a lifted function are a device register's, and of those,
+ *  which the recompile must make exactly where the machine did. Such an access is stamped
+ *  `volatile` (the `device` placement, ir/discipline.ts), and the structurer spells it through a
+ *  qualified pointer or declines.
+ *
+ *  The frame-object audit (frontend/frame-objects.ts) decides WHETHER a function is pinned and
+ *  under which policy: it is the pass that sees a frame address handed to a device that reads
+ *  through it, and that chooses the one-object or the per-object model. This module decides WHICH
+ *  accesses, from the policy row the audit names. Nothing here decodes, but the pass pins only
+ *  behind a sink that audit hands it — a `readOnlyAddressSinks` register a frame address was
+ *  stored to — and pins nothing without one, whatever the target's `deviceRegisters` window
+ *  says. thumb.ts is the one frontend that runs that audit.
+ *
+ *  EVERY DEVICE ACCESS OF A FUNCTION KEPT AS ONE OBJECT IS PINNED, as the source's `REG_*` and
+ *  `vu32 *dmaRegs` spell them — store and load alike, because agbcc drops or moves either when it
+ *  is plain:
+ *   • a plain store to an address a later store overwrites, with nothing between that may alias
+ *     it, is deleted (flow.c:2041-2052), and at -O2 a store of another type does not alias (strict
+ *     aliasing, toplev.c:3616) — so of two transfers armed back to back through one channel, with
+ *     only a `u16` member store between, the first one's source, destination and control stores go
+ *     and that transfer never runs; `REG_IME = 0; … REG_IME = saved;` loses its first store the
+ *     same way;
+ *   • a plain load in a loop that stores nothing it may alias is invariant, so
+ *     `while (REG_VCOUNT != 160);` is hoisted into a loop that never reads the register again.
+ *  The address may be a literal, a literal plus a runtime index — `(vu32 *)(0x40000B0 + ch*12)`, a
+ *  channel chosen at run time — or a phi each of whose incoming values is one of those: every way
+ *  the lift names a device register and not a pointer loaded, passed or computed from nothing it
+ *  can place. Over-reach costs a spelling and never an access: `volatile` keeps the accesses the
+ *  machine made, and a pinned read is placed once, as a call is (structure/analysis.ts), so the
+ *  qualifier adds none. The window is the target's `deviceRegisters`, which has to cover every
+ *  register a source reaches — an address outside it stays plain; without one, it is the channels
+ *  handed a frame address.
+ *
+ *  A FUNCTION ACCEPTED OBJECT BY OBJECT pins every device read, and of its device stores only those
+ *  of the first kind (`overwritten`). A read is pinned because a plain one is lost either way:
+ *  nothing uses the `dmaRegs[2];` that ends a DMA macro, so the lift would drop it outright (the
+ *  dead-read pin, frontend/dead-reads.ts, keeps such a read in every function), and a poll is
+ *  hoisted as above, which only this pin prevents. Its other device stores stay plain, their
+ *  qualified spelling left to `/vol-store`'s candidate (l3/volstore.ts): pinned in the structured tree they are pinned in every
+ *  variation, and the ones that home the base or un-reduce a loop refuse a qualified base, which
+ *  costs `synthetic:dmastride` and `synthetic:dmaptrsrc` their matches. That is also why the two
+ *  policies stay two rows: the one-object row's every-store pin is what keeps `threeFills`' nine
+ *  qualified stores (thumb-frontend.test.ts), and on the per-object row it costs those two matches.
+ *
+ *  One store left plain this way is a GAP: a device store a pinned read of the same cell re-reads
+ *  in a loop where nothing else may alias the cell. agbcc's loop pass takes the first access of a
+ *  cell it meets as the cell's and compares no qualifier (loop.c:8767, rtx_equal_p at
+ *  rtlanal.c:1066), so plain, the store moves the cell into a register and the read is served the
+ *  stored value. The variations that home the channel's base name the store and the read through
+ *  different addresses, which are two cells to that pass, and those are the ones a pin here would
+ *  refuse.
+ *
+ *  Under either policy, a read the compiler could not have made of a `volatile` stays plain
+ *  (target.ts `readCouldBeVolatile`): on a compiler that sign-extends a qualified narrow read in a
+ *  register, a sign-extending load is a plain read in the source, and qualified it recompiles to
+ *  another instruction sequence. */
+import { type RangeCtx, type StridedRange, incomingArgs, stridedRange } from '../ir/bits';
+import type { Block, Op, Value } from '../ir/core';
+import type { SymbolMap } from '../symbols';
+import { type TargetDescription, readCouldBeVolatile } from '../target';
+
+/** The literal addresses a function's values denote, over its IR as it stands when asked. */
+export interface LiteralAddresses {
+  readonly defOf: ReadonlyMap<Value, Op>;
+  /** the value of a `const`, else undefined */
+  constOf(v: Value): number | undefined;
+  /** the literal address `v` denotes, or undefined when this cannot say */
+  literalAddrOf(v: Value): number | undefined;
+  /** every address `v` may denote, as a strided unsigned interval, or undefined when this cannot
+   *  bound it */
+  addressRangeOf(v: Value): StridedRange | undefined;
+}
+
+/** `literalAddrOf`: `const` is the bare pool word, `gaddr` is the same word after the symbol map
+ *  named it, a constant shifted by a constant is the word agbcc builds without a pool (`mov r0,
+ *  #0x80; lsl r0, #0x13` is 0x04000000), and `add` or `sub` of a constant, on either side, is the
+ *  base+displacement form an interior attribution or a member access produces — spellings of one
+ *  address, which is the point: the answer must not turn on which one the assembly happened to use.
+ *  A runtime index is not a constant, and neither is a pointer loaded from memory, a parameter or a
+ *  phi.
+ *
+ *  A NAME IS NOT AN ADDRESS. The same symbol name can sit at two addresses — a symbol map is free to
+ *  carry one — and a `gaddr`'s `sym` can also come straight from the assembly text (`.word
+ *  REG_DMA3SAD`), where nothing looked it up at all. So names resolve to an address here or they
+ *  resolve to nothing: a name at more than one address vouches for neither. */
+export function literalAddresses(irBlocks: readonly Block[], symbols: SymbolMap | undefined): LiteralAddresses {
+  const defOf = new Map<Value, Op>();
+  for (const blk of irBlocks) {
+    for (const op of blk.ops) {
+      for (const res of op.results) {
+        defOf.set(res, op);
+      }
+    }
+  }
+  const addrOfName = new Map<string, number | null>();
+  for (const [addr, infos] of symbols ?? []) {
+    for (const si of infos) {
+      addrOfName.set(si.name, addrOfName.has(si.name) ? null : addr);
+    }
+  }
+  const constOf = (v: Value): number | undefined => {
+    const d = defOf.get(v);
+    return d?.opcode === 'const' ? (d.attrs.value as number) : undefined;
+  };
+  const literalAddrOf = (v: Value, depth = 0): number | undefined => {
+    const d = defOf.get(v);
+    if (d === undefined || depth > 8) {
+      return undefined;
+    }
+    if (d.opcode === 'const') {
+      return d.attrs.value as number;
+    }
+    if (d.opcode === 'gaddr') {
+      return addrOfName.get(d.attrs.sym as string) ?? undefined;
+    }
+    if (d.opcode === 'shl') {
+      const shifted = constOf(d.operands[0]);
+      const by = d.operands.length === 1 ? (d.attrs.imm as number | undefined) : constOf(d.operands[1]);
+      return shifted === undefined || by === undefined || by < 0 || by > 31 ? undefined : (shifted << by) >>> 0;
+    }
+    if ((d.opcode === 'add' || d.opcode === 'sub') && d.operands.length === 2) {
+      const [x, y] = d.operands;
+      const cy = constOf(y);
+      if (cy !== undefined) {
+        const base = literalAddrOf(x, depth + 1);
+        return base === undefined ? undefined : d.opcode === 'add' ? base + cy : base - cy;
+      }
+      const cx = d.opcode === 'add' ? constOf(x) : undefined;
+      if (cx !== undefined) {
+        const base = literalAddrOf(y, depth + 1);
+        return base === undefined ? undefined : base + cx;
+      }
+    }
+    return undefined;
+  };
+  // `addressRangeOf`: where `literalAddrOf` names one address, this names every address a value
+  // may hold (ir/bits.ts `stridedRange`), a placed name being the one leaf only this module reads.
+  const rangeCtx: RangeCtx = {
+    defs: defOf,
+    constOf,
+    incoming: incomingArgs(irBlocks),
+    entry: new Set(irBlocks[0]?.params ?? []),
+    pointOf: (v) => (defOf.get(v)?.opcode === 'gaddr' ? literalAddrOf(v) : undefined),
+  };
+  return {
+    defOf,
+    constOf,
+    literalAddrOf: (v) => literalAddrOf(v),
+    addressRangeOf: (v) => stridedRange(rangeCtx, v),
+  };
+}
+
+/** Which device stores a policy pins, beside every device read. */
+type StorePin =
+  /** every one */
+  | 'every'
+  /** those a later store in their own block overwrites (`overwritten`) */
+  | 'overwritten';
+
+/** The model the frame-object audit accepted a function under. */
+export type DevicePinPolicy = 'one-object' | 'per-object';
+
+export const DEVICE_PIN_POLICIES: Readonly<Record<DevicePinPolicy, { readonly stores: StorePin }>> = {
+  'one-object': { stores: 'every' },
+  'per-object': { stores: 'overwritten' },
+};
+
+/** What the frame-object audit hands this pass: the policy it accepted the function under, and the
+ *  `readOnlyAddressSinks` registers it saw a frame address stored to. No sink, no pin. */
+export interface DevicePins {
+  readonly policy: DevicePinPolicy;
+  readonly sinks: readonly number[];
+}
+
+/** The stores pinned as `overwritten` are those a later store in their own block overwrites, with
+ *  no call between to clear flow.c's list of pending stores (flow.c:1962). A plain read of its
+ *  bytes between does not always keep it: one agbcc forwards the stored value to (cse.c) leaves the
+ *  store dead, and one of another type does not alias. A read it does not forward — a `char` read,
+ *  or one it extends — keeps it, and pinning a store agbcc keeps costs a spelling. Two fills through
+ *  one channel back to back is the shape, and plain, the first transfer is gone. */
+function overwritten(op: Op, blk: Block, at: number, { literalAddrOf }: LiteralAddresses): boolean {
+  if (op.opcode !== 'store') {
+    return false;
+  }
+  const addressOf = (x: Op): number | undefined => {
+    const lit = literalAddrOf(x.operands[0]);
+    return lit === undefined ? undefined : lit + (x.attrs.off as number);
+  };
+  // Where `x` starts relative to `op`, when both name their bytes the same way.
+  const startOf = (x: Op): { from: number; by: number } | undefined => {
+    const sameBase = x.operands[0] === op.operands[0];
+    const from = sameBase ? (op.attrs.off as number) : addressOf(op);
+    const by = sameBase ? (x.attrs.off as number) : addressOf(x);
+    return from === undefined || by === undefined ? undefined : { from, by };
+  };
+  const width = op.attrs.width as number;
+  for (const later of blk.ops.slice(at + 1)) {
+    if (later.opcode === 'call') {
+      return false;
+    }
+    const s = later.opcode === 'store' ? startOf(later) : undefined;
+    if (s !== undefined && s.by <= s.from && s.by + (later.attrs.width as number) >= s.from + width) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Stamp `volatile` on the device accesses `pins.policy` pins — none when `pins.sinks` is empty. */
+export function pinDeviceAccesses(
+  irBlocks: Block[],
+  { policy, sinks }: DevicePins,
+  target: TargetDescription,
+  symbols: SymbolMap | undefined,
+): void {
+  if (sinks.length === 0) {
+    return;
+  }
+  const addresses = literalAddresses(irBlocks, symbols);
+  const { defOf, constOf, literalAddrOf } = addresses;
+  const { stores } = DEVICE_PIN_POLICIES[policy];
+  const reach = (target.capabilities.readSourceControl?.offset ?? 2) + 2;
+  const window = target.capabilities.deviceRegisters;
+  const isDevice = (a: number, w: number): boolean =>
+    window !== undefined ? a >= window[0] && a + w <= window[1] : sinks.some((s) => a < s + reach && a + w > s);
+  const incoming = new Map<Value, Value[]>();
+  for (const blk of irBlocks) {
+    for (const op of blk.ops) {
+      for (const sx of op.successors ?? []) {
+        sx.args.forEach((arg, i) => {
+          const param = sx.block.params[i];
+          if (param !== undefined) {
+            (incoming.get(param) ?? incoming.set(param, []).get(param)!).push(arg);
+          }
+        });
+      }
+    }
+  }
+  // The literal a pointer is a device register plus a runtime index from. `'cycle'` is a phi
+  // already on the walk — a pointer stepped around a loop — which contradicts nothing, so a phi
+  // is placed by the incoming values that are not its own back edge.
+  //
+  // Of an `add`, a constant beside a pointer this places — a register, or that phi — is the
+  // pointer's displacement, and the pointer places the sum: `d += 3` on a `vu32 *` is the phi plus
+  // 12, and 12 is no register. Beside anything else the constant is the register and the other
+  // operand its runtime index, `(vu32 *)(0x40000B0 + ch * 12)`.
+  const placed = (v: Value, onWalk: Set<Value>, depth = 0): number | 'cycle' | undefined => {
+    const lit = literalAddrOf(v);
+    if (lit !== undefined || depth > 8) {
+      return lit;
+    }
+    const d = defOf.get(v);
+    if (d?.opcode === 'add' && d.operands.length === 2) {
+      const [x, y] = d.operands.map((o) => placed(o, onWalk, depth + 1));
+      const [cx, cy] = d.operands.map(constOf);
+      if (cy !== undefined && x !== undefined) {
+        return x;
+      }
+      if (cx !== undefined && y !== undefined) {
+        return y;
+      }
+      return typeof x === 'number' ? x : typeof y === 'number' ? y : (x ?? y);
+    }
+    const ins = d === undefined ? incoming.get(v) : undefined;
+    if (ins === undefined || onWalk.has(v)) {
+      return ins === undefined ? undefined : 'cycle';
+    }
+    onWalk.add(v);
+    const each = ins.map((a) => placed(a, onWalk, depth + 1));
+    onWalk.delete(v);
+    if (each.some((a) => a === undefined || (typeof a === 'number' && !isDevice(a, 1)))) {
+      return undefined;
+    }
+    return each.find((a) => typeof a === 'number') ?? 'cycle';
+  };
+  // A read the compiler could not have made of a `volatile` was plain in the source.
+  const pins = (op: Op, blk: Block, at: number): boolean =>
+    op.opcode === 'load'
+      ? readCouldBeVolatile(target.compilerBehaviors, op)
+      : stores === 'every' || overwritten(op, blk, at, addresses);
+  for (const blk of irBlocks) {
+    blk.ops.forEach((op, at) => {
+      if (op.opcode !== 'store' && op.opcode !== 'load') {
+        return;
+      }
+      const base = placed(op.operands[0], new Set());
+      if (
+        typeof base === 'number' &&
+        isDevice(base + (op.attrs.off as number), op.attrs.width as number) &&
+        pins(op, blk, at)
+      ) {
+        op.attrs = { ...op.attrs, volatile: true };
+      }
+    });
+  }
+}

package/src/frontend/emit.ts

@@ -45,13 +45,14 @@ export function mkEmitKit(ops: Op[], write: (reg: string, v: Value) => void): Em
 
 /** Emit a recovered jump-table dispatch: N case successors followed by the default (LAST), with
  *  the dense 0..N-1 `cases` list derived here — the single home of the case/successor
- *  alignment invariant. */
-export function pushSwitchBr(ops: Op[], scrut: Value, successors: Successor[]): void {
+ *  alignment invariant. `exhaustive`: the scrutinee is already known to be in 0..N-1 here (see
+ *  the opcode's attr). */
+export function pushSwitchBr(ops: Op[], scrut: Value, successors: Successor[], exhaustive = false): void {
   ops.push(
     mkOp('switch_br', {
       operands: [scrut],
       successors,
-      attrs: { cases: successors.slice(0, -1).map((_, k) => k) },
+      attrs: { cases: successors.slice(0, -1).map((_, k) => k), ...(exhaustive ? { exhaustive: true } : {}) },
     }),
   );
 }

package/src/frontend/errors.ts

@@ -6,6 +6,11 @@
 // runtime crash (TypeError/RangeError): this is a catchable, intentional "out of scope" boundary
 // signal. `PpcUnsupportedError` subclasses it (annotate-mode classification and the loud-error
 // tests use `instanceof` against this base).
+/** A frontend's own refusal, handed to code it shares with other frontends: it throws the
+ *  frontend's error class with the message as given, so a refusal the shared code makes classifies
+ *  as the frontend's own. */
+export type FrontendRefusal = (message: string) => never;
+
 export class FrontendUnsupportedError extends Error {
   constructor(message: string) {
     super(message);

package/src/frontend/flags-edge.ts

@@ -0,0 +1,101 @@
+// The edge rule for condition state: when a block may begin with the compare its predecessor left.
+//
+// Two frontends carry a compare across a block boundary, and their STATE and CLOBBER rules differ
+// (one implicit flags register and `FLAG_SETTING` on Thumb; eight `cr` fields and the record-form
+// `.` suffix on PowerPC, each also cleared by a call). The EDGE rule is the same thing on both, and it is
+// where the soundness lives, so it is written once, here.
+
+/** What an ISA tells the edge rule about its blocks. `exit` holds what each block left at its last
+ *  instruction: the frontend writes it as it fills blocks in order, so a lookup finds only blocks
+ *  filled EARLIER, and an unlifted predecessor answers "not known" rather than "none". */
+export interface FlagsEdges<S> {
+  preds: readonly (readonly number[])[];
+  exit: ReadonlyMap<number, S>;
+  label: (bi: number) => string;
+  /** The block ends in a jump-table dispatch, so its edges are switch edges. */
+  dispatches: (bi: number) => boolean;
+  /** The block ends in a conditional branch AND this ISA's model does not carry the flags across
+   *  that branch's edges. */
+  refusesConditional: (bi: number) => boolean;
+}
+
+/** The condition state a block starts with, inherited from its predecessor, or the sentence saying
+ *  why it starts with none. One call answers both, so a refusal and its reason cannot drift apart.
+ *
+ *  A block entered from exactly one predecessor begins with exactly the flags that predecessor
+ *  left. agbcc depends on it: a function long enough to need a mid-function literal pool gets a `b`
+ *  over the pool between a `cmp` and the branch that reads it, leaving the branch alone under a
+ *  label. mwcc depends on it across a CONDITIONAL edge: its binary-search switch dispatch is
+ *  `cmpwi r0,1; beq- case1; bge- default`, one compare read by the `beq-` and then by the `bge-` on
+ *  the `beq-`'s fall-through, which starts a block of its own.
+ *
+ *  What crosses the edge is the compare's SSA values, never its register names. A lone
+ *  predecessor dominates, so those values dominate every use on this side, while re-reading `r0`
+ *  here would pick up whatever this block redefined it to.
+ *
+ *  TRANSITIVE, over as many edges as the chain has: each block runs this and writes its own exit
+ *  state, so a compare reaches the end of a run of straight-line blocks and refuses at the first
+ *  one that breaks the chain.
+ *
+ *  NOT THE BLOCK-PARAMETER MACHINERY, though both frontends have SSA with block parameters. Three
+ *  reasons, and the last is the one a later "improvement" would get wrong:
+ *    * the flags are not a register anything reads, so there is nothing for `readVar` to look up.
+ *      The compare is consumed by the terminator, never by a named operand;
+ *    * the value a phi would carry does not exist yet on the predecessor's side. WHICH comparison
+ *      it is comes from the branch's mnemonic, at the SUCCESSOR's terminator, while the
+ *      predecessor is filled first. Flags are not a condition until a branch names one, so at the
+ *      edge there is nothing yet to phi;
+ *    * `preds.length === 1` is deliberately STRONGER than dominance. A dominating predecessor's
+ *      flags can still be overwritten on a longer path that rejoins here, so answering this from
+ *      the dominator tree would state a condition that holds on one path in.
+ *
+ *  Refuses when either half of that sentence fails:
+ *    * the block has no predecessor, or more than one. The flags on two paths need not agree, and
+ *      picking one states a condition the machine does not promise;
+ *    * the only predecessor has not been filled yet, so this pass has nothing to read;
+ *    * the edge leaves a jump-table dispatch. The edge into a case is a switch edge, and the bounds
+ *      guard is not the branch that made it;
+ *    * the edge leaves a conditional branch the ISA's model does not carry across. A branch writes
+ *      no flags on either ISA, so this is UNBUILT rather than unsound where it refuses: Thumb
+ *      refuses it because no ARM row inhabits it, and PowerPC carries it (a `bc` writes no CR
+ *      field) because the mwcc dispatch above does.
+ *
+ *  It does NOT refuse when no compare survives to the predecessor's last instruction, because that
+ *  is not this function's gap to report: the predecessor already wrote down what took the flags,
+ *  and that is what crosses the edge.
+ *
+ *  Not a `Gate` table, on docs/level-tower.md's structural bar rather than on cost: every refusal
+ *  reads `exit`, which exists only because of the order the frontend fills blocks in, so its input
+ *  cannot be prepared as a getter at any price. */
+export function inheritFlags<S>(bi: number, edges: FlagsEdges<S>): S | string {
+  const here = edges.label(bi);
+  const ps = edges.preds[bi];
+  if (ps.length !== 1) {
+    return ps.length === 0
+      ? `no compare reaches '${here}', and it has no predecessor to inherit any from`
+      : `no compare crosses the edges into '${here}': ${ps.length} meet there, and the flags need not agree on all of them`;
+  }
+  const p = ps[0];
+  const carried = edges.exit.get(p);
+  // Named for the fill order that decides it, not for a loop: this is true of any predecessor not
+  // yet lifted, and a CFG with no cycle in it can be laid out so that one is (`f: b .L2` /
+  // `.L1: bge` / `.L2: cmp; b .L1`). A reverse-postorder fill is what would close this, which is
+  // why the sentence points at the walk.
+  if (carried === undefined) {
+    return `no compare crosses the edge into '${here}': its only predecessor '${edges.label(p)}' is lifted after it`;
+  }
+  // Asked BEFORE the conditional-branch arm. On Thumb every dispatch block also ends in a
+  // conditional branch (`recoverJumpTable` only recognises a bounds block ending in `bhi`/`bls`),
+  // so there this arm buys the truer sentence and not the verdict — `thumb-frontend.test.ts` runs
+  // that ablation. On PowerPC the conditional arm carries, so this arm is the one that refuses.
+  if (edges.dispatches(p)) {
+    return `no compare crosses the edge into '${here}': it leaves the jump-table dispatch in '${edges.label(p)}'`;
+  }
+  if (edges.refusesConditional(p)) {
+    return `no compare crosses the edge into '${here}': it leaves '${edges.label(p)}' through a conditional branch`;
+  }
+  // Whatever the predecessor left, verbatim. A reason already names the block the chain broke in,
+  // so it is as true here as it was there, and a run of ten straight-line blocks reports the one
+  // instruction that took the flags rather than the last edge it crossed.
+  return carried;
+}