@asmlift/core 0.8.1 → 0.9.0

package/src/frontend/device-pins.ts

@@ -0,0 +1,277 @@
+/** 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 drops it outright, and a poll
+ *  is hoisted as above. 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 { 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;
+}
+
+/** `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;
+  };
+  return { defOf, constOf, literalAddrOf: (v) => literalAddrOf(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/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;
+}

package/src/frontend/fpu.ts

@@ -0,0 +1,167 @@
+// asmlift — the argument ABI at a function's boundary, both register files, read once for the two
+// frontends that lift hardware floating point (frontend/mips.ts, frontend/ppc.ts). The homes are
+// target data (`TargetDescription.fpu`); this is where a lift is held to them.
+//
+// WHY A FRONTEND NEEDS THIS AT ALL, and why decoding the arithmetic alone is not a smaller version
+// of it: a register of the FPU's file read before any write mints an entry parameter like any other
+// key (frontend/ssa.ts), and a value left in the float return register is not the integer one. With
+// the decode and neither of these, `float fadd(float a, float b){ return a + b; }` lifts on every
+// FPU target as `void fadd(s32 a0, s32 a1) { return; }` — two phantom integer parameters and a dead
+// add. `docs/floating-point.md` §2 measures that.
+import { type IrType, T } from '../ir/types';
+import type { TargetDescription } from '../target';
+import { FrontendUnsupportedError } from './errors';
+import type { ArgSlots } from './ssa';
+
+export type Fpu = NonNullable<TargetDescription['fpu']>;
+
+/** The one float type a function's FPU registers hold: double where it decodes a double op, single
+ *  where it decodes a single one, of no stated precision (`T.fUnstated`) where every op it decodes
+ *  carries none, and null where it decodes both. `widthOf` is the frontend's reading of a mnemonic
+ *  (null for one that carries no precision, undefined for one it does not decode). */
+export function fpPrecision(
+  instrs: readonly { mnemonic: string }[],
+  widthOf: (mnemonic: string) => 32 | 64 | null | undefined,
+): IrType | null {
+  const widths = new Set(instrs.map((ins) => widthOf(ins.mnemonic)).filter((w) => w !== null && w !== undefined));
+  return widths.size > 1 ? null : widths.has(64) ? T.f64() : widths.has(32) ? T.f32() : T.fUnstated();
+}
+
+/** Refuse a function computing in both precisions, where the frontend DECODES a float instruction of
+ *  it, so a refusal the stream reaches first keeps its own reason. The SSA builder types a register
+ *  per key, not per value, and the rounding between the precisions (a conversion, PowerPC's `frsp`,
+ *  or a single op over a double operand) is not modelled. It throws here, so its throw site is the
+ *  one `declines.test.ts` harvests. */
+export function refuseBothPrecisions(name: string, mnemonic: string): never {
+  throw new FrontendUnsupportedError(
+    `cannot lift '${name}': '${mnemonic}' is in a function that computes in ` +
+      'both single and double precision, and the rounding between them is not modelled',
+  );
+}
+
+/** THE ARGUMENT SLOTS OF BOTH REGISTER FILES, as the one `ArgSlots` the MIPS and PowerPC frontends
+ *  hand to `mintArgSlotHoles` and `abiSortEntryParams` (frontend/ssa.ts). Naming is positional
+ *  (`a0`, `a1`, … in sort order), so the ORDER `slotOf` gives and the HOLES `holes` fills are two
+ *  uses of one reading — kept in one place because under `'leading'` the files share a slot
+ *  sequence, and a hole filled from the wrong file is a signature that compiles and binds its
+ *  caller's arguments one slot off.
+ *
+ *  `slotOf` is the slot, with one exception: under `'separate'` a float argument ranks after every
+ *  integer one. THAT ORDER IS A SPELLING, NOT A READING. Under the PowerPC EABI the two files count
+ *  independently, so `float g(int *p, float b)` and `float g(float b, int *p)` compile to one object
+ *  and nothing in it says which the source wrote. Either spelling reproduces the bytes in a unit
+ *  that does not declare the function; this one is fixed so the output is deterministic. KNOWN GAP:
+ *  a unit that does declare it — a project context — decides the order, and only the C++ backend
+ *  reads that declaration (`bindSpecParams`). In C the int-first spelling of
+ *  `float mix(float a, int n);` is a redeclaration mwcc refuses: a noncompile, not a wrong program.
+ *  Ranking by the function's own declared parameters here would close it, once `proto.ts` can
+ *  size a float. A key in neither file is no slot (null), and sorts after every argument.
+ *
+ *  `holes` applies FOUR RULES to the keys the entry reads, each a refusal or a parameter the ABI
+ *  proves:
+ *   1. A register of the FPU file that arrives at the entry is a float ARGUMENT, or the lift is
+ *      refused. Nothing else in that file carries a caller's value: a read of `$f4` before any write
+ *      is uninitialised storage or code this frontend has not followed, and minting a parameter for
+ *      it would fabricate an argument.
+ *   2. Every slot below the highest one read is a parameter too, read or not. Arguments take their
+ *      registers in order, so `r5` is the third argument whatever became of the first two, and a
+ *      signature holding only the registers read would bind every later argument one slot low.
+ *   3. …and it is minted from the file the ABI puts that slot in. Under `'separate'` each file fills
+ *      its own holes. Under `'leading'` (MIPS o32) a float argument is in `argRegs[k]` only while
+ *      arguments 0..k are all floating, so a hole below the highest float read is a float, and one
+ *      above it an integer — `float f(float a, float b, int c, int d){ return d ? a : b; }` reads
+ *      `$f12`, `$f14` and `a3`, and its third argument is `a2`. Which file a hole comes from thus
+ *      depends on what the function reads, which is why `ArgSlots` asks for the holes of a read
+ *      set rather than for the key of a slot: `int ib(int a, int b){ return b; }` reads only `a1`,
+ *      and its first argument is `a0`, not `$f12`.
+ *   4. Under `'leading'` a float argument still takes the INTEGER slots it shadows — one for a
+ *      single, two for a double (`floatType`) — so an integer argument register read in one of those
+ *      slots is a contradiction the ABI does not produce, and is refused rather than ranked. */
+export function fpuArgSlots(
+  name: string,
+  fpu: Fpu | undefined,
+  argRegs: readonly string[],
+  isFpKey: (key: string) => boolean,
+  floatType: IrType | null = T.f32(),
+): ArgSlots {
+  // How many integer slots a float argument takes under `'leading'`: IDO reads the integer after a
+  // double two slots on (`double di(double a, int b)` reads b from a2).
+  const words = floatType?.kind === 'float' && floatType.width === 64 ? 2 : 1;
+  const slotOf = (key: string): { slot: number; float: boolean } | null => {
+    const gpr = argRegs.indexOf(key);
+    if (gpr >= 0) {
+      return { slot: gpr, float: false };
+    }
+    const fp = fpu?.argRegs.indexOf(key) ?? -1;
+    return fp >= 0 ? { slot: fpu?.slots === 'leading' ? fp * words : fp, float: true } : null;
+  };
+  return {
+    slotOf: (key) => {
+      const s = slotOf(key);
+      return s === null ? null : s.float && fpu?.slots === 'separate' ? argRegs.length + s.slot : s.slot;
+    },
+    holes: (readKeys) => {
+      for (const k of readKeys.filter(isFpKey)) {
+        if (!fpu?.argRegs.includes(k)) {
+          throw new FrontendUnsupportedError(
+            `cannot lift '${name}': ${k} is read before this function writes it, and no floating-point argument ` +
+              `arrives there — not modelled`,
+          );
+        }
+      }
+      const read = readKeys.map(slotOf).filter((s) => s !== null);
+      const top = (float: boolean) => Math.max(-1, ...read.filter((s) => s.float === float).map((s) => s.slot));
+      const floatTop = top(true);
+      const intTop = top(false);
+      if (fpu?.slots === 'leading') {
+        // The last integer slot the floats read shadow; a double shadows two.
+        const floatEnd = floatTop < 0 ? -1 : floatTop + words - 1;
+        const shadowed = read.find((s) => !s.float && s.slot <= floatEnd);
+        if (shadowed) {
+          const k = shadowed.slot;
+          throw new FrontendUnsupportedError(
+            `cannot lift '${name}': ${argRegs[k]} and ${fpu.argRegs[Math.floor(k / words)]} both carry argument ` +
+              `slot ${k} — a floating-point argument takes the integer slots it shadows, so the ABI does not ` +
+              'produce this — not modelled',
+          );
+        }
+        return [
+          ...fpu.argRegs.slice(0, Math.max(0, floatTop / words)),
+          ...argRegs.slice(floatEnd + 1, Math.max(floatEnd + 1, intTop)),
+        ];
+      }
+      return [...(fpu?.argRegs.slice(0, Math.max(0, floatTop)) ?? []), ...argRegs.slice(0, Math.max(0, intTop))];
+    },
+  };
+}
+
+/** Whether a function RETURNS a float: some instruction the frontend decodes writes the float return
+ *  register, in a block the entry REACHES. Decided over the whole function, before any `ret` is
+ *  emitted, because a function has one return type on every path — a path that leaves the register
+ *  untouched returns the float argument that arrived there (PowerPC's `f1` is both), or refuses by
+ *  `fpuArgSlots`' rule 1. Reachable blocks only: `addi r3,r3,1; blr; fmr f1,f2` returns `r3`, and
+ *  the `fmr` past the `blr` is on no path of it.
+ *
+ *  And then the INTEGER return register is scratch, even where the function writes it. Both halves
+ *  rest on one fact: the arithmetic is ALL the decode admits, so a float reaches nothing but another
+ *  float op or the return — every move to memory, to the integer file or through a compare or a
+ *  conversion is refused. A write to the float return register that did not feed the return would
+ *  therefore be dead in the source, and the compiler does not emit dead arithmetic; an integer
+ *  result, meanwhile, could only have come from a float by a conversion, which refuses. IDO's
+ *  unrolled `float pw(float a, int n)` is the witness for the second half: it counts in `v0`.
+ *
+ *  THAT FACT IS WHAT HOLDS THIS RULE UP, and the next layer removes it: a layer that lets a float
+ *  reach memory, the integer file or a compare must first decide the return from the value that
+ *  reaches each `ret`, not from a mnemonic scan (`fpu-lift.test.ts` pins the function that breaks
+ *  it, `docs/floating-point.md` §6). */
+export function writesFloatReturn(
+  instrs: readonly { mnemonic: string; ops: string[] }[],
+  decodes: ReadonlySet<string>,
+  destKey: (tok: string) => string | null,
+  fpu: Fpu | undefined,
+): boolean {
+  return (
+    fpu !== undefined &&
+    instrs.some((ins) => decodes.has(ins.mnemonic) && ins.ops[0] !== undefined && destKey(ins.ops[0]) === fpu.returnReg)
+  );
+}