@asmlift/core 0.2.0 → 0.4.0

package/src/frontend/thumb.ts

@@ -19,7 +19,9 @@ import type { Opcode } from '../ir/opcodes';
 import { T } from '../ir/types';
 import { type Prototypes, protoArity } from '../proto';
 import { RUNTIME_HELPERS } from '../raise/softdiv';
+import { type SymbolMap, lookupInterior, lookupSymbol } from '../symbols';
 import type { TargetDescription } from '../target';
+import type { AsmData } from './asmdata';
 import { pushSwitchBr } from './emit';
 import { FrontendUnsupportedError } from './errors';
 import { assertInputFormat } from './format';
@@ -28,14 +30,74 @@ import { opaqueDest } from './opaque';
 import { abiSortEntryParams, fallbackArgc, makeSsaBuilder } from './ssa';
 
 interface Instr {
+  /** the CANONICAL spelling — legacy names are normalised (see LEGACY_MNEMONICS) so that every
+   *  consumer matches one name. */
   mnemonic: string;
   ops: string[];
+  /** the spelling the input file actually used, present only when normalisation changed it.
+   *  Messages must use this: a decline naming `ldrsh` for a file containing `ldsh` sends the
+   *  reader looking for an instruction that is not there. */
+  asWritten?: string;
 }
 interface AsmBlock {
   label: string;
   instrs: Instr[];
 }
 
+// Alternative mnemonic spellings, normalised at the single point where an instruction enters the
+// IR. Each maps to a name the decode switch below already handles.
+//
+// These are not "similar" instructions — each pair is ONE instruction with two accepted spellings.
+// The ARM7TDMI Technical Reference Manual (ARM DDI 0029G) gives a single encoding for each:
+// Figure 1-6 "Thumb instruction set formats" lists Format 08 "Load and store sign-extended byte and
+// halfword" (0101 H S 1 Ro Rb Rd) and Format 15 "Multiple load and store" (1100 L Rb Rlist), and
+// Table 1-7 "Thumb instruction set summary" spells them `LDRSH Rd, [Rb, Ro]`, `LDRSB Rd, [Rb, Ro]`,
+// `LDMIA Rb!, <reglist>` and `STMIA Rb!, <reglist>`. Older ARM7TDMI documentation used LDSH/LDSB,
+// which is where the short spellings come from; the stack-suffix forms (FD, EA) are the same
+// instructions named after the stack discipline they implement.
+//
+// Confirmed with this project's own toolchain — same encoding, and gba-kit executes them with the
+// same architectural effect (sign extension, transfers, base writeback):
+//
+//     ldsh  / ldrsh        885e / 885e        ldm   / ldmia / ldmfd   01c9 / 01c9 / 01c9
+//     ldsb  / ldrsb        8856 / 8856        stm   / stmia / stmea   01c1 / 01c1 / 01c1
+//
+// Measured on the Klonoa: Empire of Dreams disassembly (luvdis, 469 .s files): `ldsh` 292 and
+// `ldsb` 180 against `ldrsh` 0 and `ldrsb` 12 — the same tool emits both spellings for the signed
+// byte load — and `ldm` 12 / `stm` 34 against `ldmia` 0 / `stmia` 0. The UAL names this frontend
+// cased for the multiple forms never appear in that corpus at all.
+//
+// These are PURE SYNONYMS — identical operands — which is why they belong in a table here rather
+// than in decode arms like MIPS's `move` or PPC's `slwi`. That distinction, and why there is no
+// shared alias helper across the three frontends, is written up once in ./opaque.ts.
+//
+// The LOAD aliases matter more than the store ones, and the asymmetry is worth knowing: an
+// unrecognised `stm*` matches `opaquePolicy.storeClass` and fails LOUD, but an unrecognised `ldm*`
+// does not — it reaches opaqueDest, which takes ops[0] (the BASE) as the destination, so the opaque
+// is dead, DCE removes it, and the load silently vanishes. Measured: `ldmfd r1, {r0}; bx lr` lifted
+// to `return a0;` where the answer is `return *a0;`. Every load spelling ARMv4T Thumb accepts is
+// therefore listed. (`ldmed`/`ldmea` are NOT: they mean IB/DB, which Thumb-1 does not have, and
+// `as` rejects them — so they cannot appear.)
+//
+// `stmfd` is deliberately absent, and the asymmetry is real rather than an oversight: `stmfd` is
+// `stmdb`, and ARMv4T Thumb has neither — `as` rejects both with "selected processor does not
+// support ... in Thumb mode". There is nothing to normalise it TO.
+//
+// Null-prototype so that an inherited key (`constructor`, `toString`) cannot be mistaken for an
+// entry. Unreachable from real assembly, but the lookup should not depend on that.
+const LEGACY_MNEMONICS: Readonly<Record<string, string>> = Object.assign(Object.create(null), {
+  ldsh: 'ldrsh',
+  ldsb: 'ldrsb',
+  ldm: 'ldmia',
+  ldmfd: 'ldmia',
+  stm: 'stmia',
+  stmea: 'stmia',
+});
+
+function canonicalMnemonic(mn: string): string {
+  return LEGACY_MNEMONICS[mn] ?? mn;
+}
+
 // Map a Thumb conditional-branch mnemonic to the icmp opcode for "branch taken". The signed forms
 // (`blt`/`ble`/`bgt`/`bge`) follow a signed `cmp`; the UNSIGNED forms carry the carry/borrow sense:
 // `bhi` = unsigned > (higher), `bls` = unsigned <= (lower-or-same), `bcc`/`blo` = unsigned <
@@ -117,6 +179,48 @@ const imm = (s: string) => parseInt(s.replace(/^#/, ''), s.includes('0x') ? 16 :
 // detection sees them, and any consumer that needs the exact list rejects the leftover `-` token
 // loudly rather than treating the fused range as one phantom register.
 const REG_NUM: Record<string, number> = { sp: 13, lr: 14, pc: 15 };
+
+// Thumb-1 data-processing mnemonics that write the condition flags when their destination is a LOW
+// register — which is all of them on this ISA, `s`-suffix or not (the assembler picks the encoding).
+// Used to invalidate a pending compare: see the decode loop. `cmp`/`cmn`/`tst` are absent on purpose
+// — they set flags but define no register, and `cmp` is the very instruction that seeds the pending
+// compare. Loads, stores, push/pop, `bl` and the high-register forms leave the flags alone.
+const FLAG_SETTING = new Set([
+  'mov',
+  'movs',
+  'add',
+  'adds',
+  'sub',
+  'subs',
+  'lsl',
+  'lsls',
+  'lsr',
+  'lsrs',
+  'asr',
+  'asrs',
+  'neg',
+  'negs',
+  'rsb',
+  'rsbs',
+  'mvn',
+  'mvns',
+  'bic',
+  'bics',
+  'ror',
+  'rors',
+  'mul',
+  'muls',
+  'and',
+  'ands',
+  'orr',
+  'orrs',
+  'eor',
+  'eors',
+  'adc',
+  'adcs',
+  'sbc',
+  'sbcs',
+]);
 const regNum = (r: string) => (r[0] === 'r' ? Number(r.slice(1)) : REG_NUM[r]);
 function expandRegList(tokens: string[]): string[] {
   const out: string[] = [];
@@ -171,10 +275,15 @@ function splitOperands(s: string): string[] {
 // Parse a Thumb memory addressing operand `[base]` or `[base, #off]` into base register +
 // constant byte offset. (Register-scaled indices like `[base, r1, lsl #2]` are not handled
 // yet — agbcc materialises those as explicit add/lsl before the load in the cases we target.)
-function parseAddr(operand: string): { base: string; off: number } {
+function parseAddr(operand: string): { base: string; off: number; regOff?: string } {
   const inner = operand.replace(/[[\]]/g, '').trim();
   const parts = inner.split(',').map((s) => s.trim());
   const base = parts[0];
+  // `[rB, rX]` — REGISTER-offset addressing. Surfaced to the caller so load/store DECLINE
+  // loud: silently reading `[rB]` (the old behavior) dropped the index — a silent miscompile.
+  if (parts[1] !== undefined && !parts[1].startsWith('#')) {
+    return { base, off: 0, regOff: parts[1] };
+  }
   const off = parts[1]?.startsWith('#') ? imm(parts[1]) : 0;
   return { base, off };
 }
@@ -298,7 +407,14 @@ function decode(name: string, asm: string): { blocks: AsmBlock[]; dataWords: Map
       continue;
     }
     dataLabel = null; // a real instruction ends a data run
-    flat.push({ instr: { mnemonic: m[1], ops: m[2] ? splitOperands(m[2]) : [] } });
+    const canon = canonicalMnemonic(m[1]);
+    flat.push({
+      instr: {
+        mnemonic: canon,
+        ops: m[2] ? splitOperands(m[2]) : [],
+        ...(canon === m[1] ? {} : { asWritten: m[1] }),
+      },
+    });
   }
   if (
     armLabels.has(name) ||
@@ -601,6 +717,41 @@ function decode(name: string, asm: string): { blocks: AsmBlock[]; dataWords: Map
         `cannot lift '${name}': block '${mixed.label}' interleaves raw data (.${subwordData.get(mixed.label)}) with instructions`,
       );
     }
+    // Two labels on the same instruction (`.LCB80:` immediately followed by `.L7:`) make the first
+    // an ALIAS of the second, not a block of its own — agbcc emits exactly that when a long-jump
+    // helper label lands on an existing one. The empty block is dropped just below, so a branch
+    // naming the alias would afterwards resolve to nothing and decline as a dangling target. Point
+    // those branches at the block the label actually names, before anything reads the CFG.
+    // A label naming DATA is emphatically NOT an alias, and this is the guard the whole pass turns
+    // on. Decode pushes an empty block for a literal-pool / jump-table label too, so aliasing them
+    // blindly would silently retarget `beq .Lpool` at whatever code happens to follow the pool —
+    // marker-free, plausible, wrong C where the frontend used to decline. Every agbcc pool is a
+    // label on data, so that is the common case, not an exotic one. A data label therefore neither
+    // aliases nor is aliased THROUGH: scanning past one for a later code block would silently jump
+    // over the data.
+    const isDataLabel = (l: string) => dataWords.has(l) || subwordData.has(l);
+    const aliasOf = new Map<string, string>();
+    for (let i = 0; i < blocks.length; i++) {
+      if (blocks[i].instrs.length > 0 || isDataLabel(blocks[i].label)) {
+        continue;
+      }
+      let j = i + 1;
+      while (j < blocks.length && blocks[j].instrs.length === 0 && !isDataLabel(blocks[j].label)) {
+        j++;
+      }
+      const next = blocks[j];
+      if (next && next.instrs.length > 0) {
+        aliasOf.set(blocks[i].label, next.label);
+      } // otherwise a trailing or data-fronted label: left dangling so a branch to it still declines
+    }
+    for (const b of aliasOf.size ? blocks : []) {
+      for (const ins of b.instrs) {
+        const k = ins.ops.length - 1;
+        if ((ins.mnemonic === 'b' || COND_OPCODE[ins.mnemonic]) && k >= 0) {
+          ins.ops[k] = aliasOf.get(ins.ops[k]) ?? ins.ops[k];
+        }
+      }
+    }
     let live = blocks.filter((b) => b.instrs.length > 0);
     // Alignment-pad NOPs a splitter emits around returns and literal pools: `lsls r0, r0, #0`
     // is the 0x0000 halfword, `mov r8, r8` is 0x46C0, plus a literal `nop`. A block made ONLY
@@ -724,6 +875,37 @@ function poolRef(operand: string, dataWords: Map<string, string[]>): PoolRef | n
   return { kind: 'unmodelled', why: `pool word '${w}' is a symbol offset or code label` };
 }
 
+/** Does this function's literal pool name at least one EXTERNAL symbol?
+ *
+ *  agbcc emits a pool word symbolically exactly when the source expression named a linker symbol,
+ *  and numerically when it did not (`*(vu16 *)0x4000130`, an address-cast macro). So within one
+ *  function, a numeric word sitting alongside a symbolic one is numeric *by the source's choice* —
+ *  which is what lets {@link liftThumb} refuse to invent a name for it.
+ *
+ *  The witness is required because that inference only holds for asm that KEPT its symbols. A
+ *  linked-ROM disassembly resolves every relocation to a number, and there "numeric" says nothing
+ *  about the source; vetoing on it would disable the map's naming for the users who need it most.
+ *  A function whose pool names nothing external is therefore left alone (both spellings still
+ *  enumerate, and the differ referees) rather than being read as evidence of anything.
+ *
+ *  Labels DEFINED in this same asm — the jump-table pointer word, a pret-style `_08012358` pool
+ *  label — are not external symbols and never witness: they survive disassembly whether or not
+ *  relocations did. */
+function poolNamesASymbol(dataWords: Map<string, string[]>, blockLabels: Set<string>): boolean {
+  for (const [, words] of dataWords) {
+    for (const raw of words) {
+      const w = raw.trim();
+      if (!/^[A-Za-z_]\w*$/.test(w) || w.startsWith('.L')) {
+        continue;
+      }
+      if (!dataWords.has(w) && !blockLabels.has(w)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 // Recover an agbcc Thumb jump-table dispatch. Given a dispatch block `disp` ending in `mov pc, rV`
 // and its unique bounds predecessor `bounds` ending in `cmp rX,#(N-1); bhi DEF`, verify the exact
 // idiom and read the inline table — else return null (→ the indirect-jump loud-fail fires). The
@@ -746,21 +928,47 @@ function recoverJumpTable(
   disp: AsmBlock,
   dataWords: Map<string, string[]>,
   blockLabels: Set<string>,
+  longDefault?: string,
 ): JumpTable | null {
-  // bounds: last two instrs must be `cmp rX,#M` then `bhi DEF` (unsigned upper-bound guard).
+  // bounds: last two instrs are `cmp rX,#M` then the out-of-range guard, in one of two spellings.
+  //
+  //   direct    cmp rX,#M ; bhi DEF                 → fall through to the dispatch
+  //   long jump cmp rX,#M ; bls DISP ; b DEF        → branch TO the dispatch, long-branch the default
+  //
+  // The second is what agbcc emits whenever the default is out of a conditional branch's reach —
+  // Thumb-1 `B<cond>` carries a signed 8-bit HALFWORD offset, so ±256 BYTES, about 128
+  // instructions — which on a real switch it usually is: five of the six benchmark
+  // functions with a table use it, and only the sixth uses the direct form. `longDefault` is the
+  // target of that trailing `b`, read by the caller from the block after `bounds`.
   const bi = bounds.instrs;
-  const bhi = bi[bi.length - 1],
+  const guard = bi[bi.length - 1],
     cmp = bi[bi.length - 2];
-  if (!bhi || !cmp || bhi.mnemonic !== 'bhi' || cmp.mnemonic !== 'cmp') {
+  if (!guard || !cmp || cmp.mnemonic !== 'cmp') {
     return null;
   }
+  let defaultLabel: string;
+  if (longDefault === undefined) {
+    if (guard.mnemonic !== 'bhi') {
+      return null;
+    }
+    defaultLabel = guard.ops[0];
+  } else {
+    // The `bls` must name THIS dispatch block, or the guard belongs to some other branch and the
+    // `b` we picked up is not its default.
+    if (guard.mnemonic !== 'bls' || guard.ops[0] !== disp.label) {
+      return null;
+    }
+    defaultLabel = longDefault;
+  }
   const scrutReg = cmp.ops[0];
   const m = cmp.ops[1];
   if (!m?.startsWith('#')) {
     return null;
   }
   const n = imm(m) + 1; // cases 0..M  → N = M+1
-  const defaultLabel = bhi.ops[0];
+  if (n < 1) {
+    return null; // a bound that admits no case at all is not a dispatch — fail closed
+  }
 
   // disp: exactly the 5-op idiom, threading a single index register from `lsl rY,rX,#2`.
   const d = disp.instrs;
@@ -797,11 +1005,28 @@ function recoverJumpTable(
   }
 
   // Read the table: the ldr loads a POINTER word (PTR: .word TABLE); the table is TABLE: .word C0…
-  const ptrWords = dataWords.get(ptrLabel);
-  if (!ptrWords || ptrWords.length !== 1) {
+  // Note the case labels are matched against `blockLabels` as WRITTEN: the adjacent-label aliasing in
+  // `decode` rewrites branch operands, not `.word` entries, so a table naming an aliased label would
+  // decline here rather than dispatch anywhere. Loud, and no corpus instance — left as a known edge
+  // rather than fixed speculatively.
+  //
+  // The pointer word is addressed the same way every other pool load in this frontend is —
+  // `LABEL[+N]`, selecting word N/4 — because a literal pool is a POOL: agbcc packs the dispatch
+  // pointer in beside whatever else the function needed, and which slot it lands in is an artifact
+  // of emission order. Reading only a bare label whose pool held exactly ONE word declined six real
+  // benchmark functions whose table pointer merely sat later in the pool. Same fix m2c made in
+  // `a7c5c2d`, and the same shared POOL_LABEL grammar the const/gaddr resolvers use, so the three
+  // cannot disagree about what `.L21+0x4` addresses.
+  const pm = ptrLabel.match(POOL_LABEL);
+  const ptrWords = pm ? dataWords.get(pm[1]) : undefined;
+  if (!pm || !ptrWords) {
     return null;
   }
-  const caseLabels = dataWords.get(ptrWords[0]);
+  const ptrOff = pm[2] ? Number(pm[2]) : 0;
+  if (ptrOff % 4 !== 0 || ptrOff / 4 >= ptrWords.length) {
+    return null; // misaligned or past the end of the pool — not a word this pool holds
+  }
+  const caseLabels = dataWords.get(ptrWords[ptrOff / 4].trim());
   if (!caseLabels || caseLabels.length !== n) {
     return null;
   } // table length must equal the bound
@@ -816,7 +1041,14 @@ function recoverJumpTable(
 /** Lift decoded asm → an L1 Fn with block-argument SSA. `prototypes` supplies each callee's
  *  declared parameter count (from the project's headers); it is authoritative for recovering
  *  how many argument registers a `bl` passes (falling back to a heuristic when absent). */
-export function lift(name: string, asm: string, target: TargetDescription, prototypes: Prototypes = {}): Fn {
+export function lift(
+  name: string,
+  asm: string,
+  target: TargetDescription,
+  prototypes: Prototypes = {},
+  _asmData?: AsmData,
+  symbols?: SymbolMap,
+): Fn {
   assertInputFormat('thumb', 'gnu-as', asm);
   const { blocks: rawBlocks, dataWords } = decode(name, asm);
 
@@ -825,28 +1057,54 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
   // dispatch block is ELIDED from the CFG. A `mov pc` that is NOT a recognised table falls through
   // to the loud-fail below.
   const blockLabels = new Set(rawBlocks.map((b) => b.label));
+  // Whether THIS asm preserves symbol names in its literal pools — the witness the numeric-pool
+  // naming veto needs (see poolNamesASymbol).
+  const poolNamesSymbols = poolNamesASymbol(dataWords, blockLabels);
   // Any label referenced as a branch target (so we can tell if an elided dispatch block has a SECOND
   // predecessor — a `b disp` from elsewhere — which would dangle after elision; decline if so).
-  const branchTargets = new Set<string>();
+  // How many branches name each label — not just whether any does, because the long-jump bounds
+  // form legitimately branches to its own dispatch block exactly once.
+  const branchRefs = new Map<string, number>();
   for (const b of rawBlocks) {
     for (const ins of b.instrs) {
       if ((ins.mnemonic === 'b' || COND_OPCODE[ins.mnemonic]) && ins.ops.length) {
-        branchTargets.add(ins.ops[ins.ops.length - 1]);
+        const t = ins.ops[ins.ops.length - 1];
+        branchRefs.set(t, (branchRefs.get(t) ?? 0) + 1);
       }
     }
   }
   const tables = new Map<AsmBlock, JumpTable>(); // bounds block → recovered table
-  const elided = new Set<AsmBlock>(); // dispatch blocks removed from the CFG
+  const elided = new Set<AsmBlock>(); // dispatch (and long-jump default) blocks removed from the CFG
   rawBlocks.forEach((d, i) => {
     const last = d.instrs[d.instrs.length - 1];
-    if (last && last.mnemonic === 'mov' && last.ops[0] === 'pc' && last.ops[1] !== 'lr') {
-      const bounds = rawBlocks[i - 1];
-      // The dispatch block must be reached ONLY by falling through from its bounds predecessor — a
-      // `b disp` target elsewhere would leave a dangling edge after elision, so decline (→ loud-fail).
-      const jt = bounds && !branchTargets.has(d.label) ? recoverJumpTable(bounds, d, dataWords, blockLabels) : null;
+    if (!last || last.mnemonic !== 'mov' || last.ops[0] !== 'pc' || last.ops[1] === 'lr') {
+      return;
+    }
+    const refs = branchRefs.get(d.label) ?? 0;
+    const prev = rawBlocks[i - 1];
+    // Direct form: the dispatch is reached ONLY by falling through from its bounds predecessor. A
+    // `b disp` from anywhere else would leave a dangling edge after elision, so decline (→ loud-fail).
+    if (prev && refs === 0) {
+      const jt = recoverJumpTable(prev, d, dataWords, blockLabels);
+      if (jt) {
+        tables.set(prev, jt);
+        elided.add(d);
+        return;
+      }
+    }
+    // Long-jump form: `bounds` (cmp; bls DISP), then a lone `b DEF` block, then the dispatch. The
+    // dispatch is entered by exactly that one `bls` and nothing else, and the `b DEF` block —
+    // synthetically labelled, so unnameable and unreachable once the bounds block dispatches — is
+    // elided WITH it. Leaving it would make it a parameterless predecessor of the default block,
+    // and wiring a phi through it fabricates an entry parameter (the phantom-param miscompile).
+    const boundsB = rawBlocks[i - 2];
+    const prevNamed = prev ? (branchRefs.get(prev.label) ?? 0) > 0 : false;
+    if (refs === 1 && prev && boundsB && !prevNamed && prev.instrs.length === 1 && prev.instrs[0].mnemonic === 'b') {
+      const jt = recoverJumpTable(boundsB, d, dataWords, blockLabels, prev.instrs[0].ops[0]);
       if (jt) {
-        tables.set(bounds, jt);
+        tables.set(boundsB, jt);
         elided.add(d);
+        elided.add(prev);
       }
     }
   });
@@ -980,7 +1238,7 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
     // adjustments have no low-register data destination, so they fall through harmlessly;
     // terminators are handled in the terminator section below.
     const isThumbReg = (s: string | undefined): s is string => /^r\d+$/.test(s ?? '');
-    const emitOpaqueDest = (ins: { mnemonic: string; ops: string[] }) => {
+    const emitOpaqueDest = (ins: { mnemonic: string; ops: string[]; asWritten?: string }) => {
       // storeClass: unmodelled Thumb stores are str*/stm* — `stmia rN!, {…}`'s dest token `r0!`
       // fails isReg, so without this it would be skipped as "no reg dest", silently deleting the
       // memory writes AND the base writeback. push/pop stay transparent frame ops (they don't match).
@@ -992,6 +1250,7 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
         storeClass: /^(str|stm)/,
         skipSafe: /^(push|pop|nop)$/,
         context: name,
+        display: ins.asWritten,
       });
       if (!od) {
         return;
@@ -999,7 +1258,7 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
       const operands = od.srcRegs.map((r) => readVar(r, bi));
       const res = mkValue(T.unk(32));
       // carry the mnemonic so annotate mode can name the gap (`ASMLIFT_ERROR("unmodelled 'rsb'")`)
-      irb.ops.push(mkOp('opaque', { operands, results: [res], attrs: { mnemonic: ins.mnemonic } }));
+      irb.ops.push(mkOp('opaque', { operands, results: [res], attrs: { mnemonic: ins.asWritten ?? ins.mnemonic } }));
       writeVar(od.dst, bi, res);
     };
     // 2-operand ALU form `op rD, op2` (rD = rD ⟨op⟩ op2). `op2` is an immediate (`#N`) or a
@@ -1028,6 +1287,22 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
       if (classifyXfer(ins)) {
         continue;
       }
+      // A Thumb-1 data-processing instruction on LOW registers writes the condition flags whether or
+      // not the mnemonic carries the `s` (agbcc spells `adds r0,r0,r3` as `add r0,r0,r3`, and the
+      // assembler picks the flag-setting encoding) — so an instruction between a `cmp` and its branch
+      // REPLACES the flags the branch will test. Folding the earlier `cmp` in anyway would emit a
+      // condition on the wrong operands: silently wrong C with no marker. Drop the pending compare
+      // and let the terminator's existing "no reaching compare in its block" decline fire — the loud
+      // answer, since modelling arithmetic flags is a capability asmlift does not have.
+      //
+      // The HIGH-register forms (`mov rD,rH`, `add rD,rH`) do NOT set flags and stay transparent,
+      // which is what keeps agbcc's callee-saved shuffling from tripping this. Measured free: across
+      // every agbcc row in the benchmark, no conditional-branch block has ANY instruction between its
+      // compare and the branch — compilers keep the pair adjacent. The inhabitant this guards is
+      // hand-written asm in the playground, where there is no oracle to catch a lie.
+      if (FLAG_SETTING.has(ins.mnemonic) && /^r[0-7]$/.test(reg(ins.ops[0] ?? ''))) {
+        pendingCmp = null;
+      }
       const [a, b, c] = ins.ops;
       switch (ins.mnemonic) {
         case 'mov':
@@ -1167,9 +1442,18 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
           // rejoin below also tolerates a split list defensively. Thumb-1 LDMIA skips the
           // writeback when rN is itself in the list (the loaded value wins) — modelled; any
           // malformed shape degrades to the loud opaque.
-          // `!` = writeback (`ldmia rN!, {…}`); its absence is the valid no-writeback form
-          // (`ldmia rN, {…}` — same transfers, base unchanged). A missing register list is
-          // malformed → loud opaque.
+          // There is NO no-writeback form in Thumb-1, so the `!` is decoration and must not drive
+          // the model. Four sources agree:
+          //   * ARM DDI 0029G Table 1-7 gives the canonical syntax as `LDMIA Rb!, <reglist>` and
+          //     `STMIA Rb!, <reglist>` — the `!` is part of the mnemonic, not an option, and
+          //     Figure 1-6 Format 15 has no bit that could encode its absence;
+          //   * GNU as assembles `ldm r1,{r0}` and `ldm r1!,{r0}` to the same halfword, 0xc901,
+          //     and warns "this instruction will write back the base register";
+          //   * gba-kit executes both with the base advanced by 4;
+          //   * GBATEK, THUMB.15: "Both STM and LDM are incrementing the Base Register".
+          // An earlier version of this comment called the `!`-less spelling "the valid
+          // no-writeback form — same transfers, base unchanged", which is false, and the code
+          // below acted on it. A missing register list is malformed → loud opaque.
           const baseTok = a;
           const writeback = !!baseTok?.endsWith('!');
           if (baseTok === undefined || b === undefined || !b.startsWith('{')) {
@@ -1196,6 +1480,30 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
             emitOpaqueDest(ins);
             break;
           }
+          // An STM whose base is in its own list, but is not the LOWEST entry, stores a value this
+          // frontend must not guess — because the available references DISAGREE about what it is.
+          //
+          //   ARM:      UNPREDICTABLE, "the stored value cannot be relied upon".
+          //   GNU as:   warns "value stored for rN is UNKNOWN".
+          //   GBATEK:   version-specific — "Store OLD base if Rb is FIRST entry in Rlist,
+          //             otherwise store NEW base (STM/ARMv4), always store OLD base (STM/ARMv5)".
+          //   mGBA:     stores the OLD base unconditionally, on an ARMv4T core — its STM_LOOP
+          //             reads gprs[i] during the loop and the writeback runs after it.
+          //
+          // So GBATEK's ARMv4 rule and the reference emulator's behaviour do not agree, and no
+          // hardware test result was found either way. This frontend used to emit the old base,
+          // i.e. it silently picked one side of that disagreement. Declining is the contract:
+          // where the architecture declines to define a value, so do we.
+          //
+          // (One site in the Klonoa corpus, in unreachable code after a `pop`/`bx`, and it already
+          // declines for an unrelated pc-relative-pool reason — so this costs nothing today.)
+          if (ins.mnemonic === 'stmia' && list.some((r) => reg(r) === baseReg) && reg(list[0]) !== baseReg) {
+            throw new FrontendUnsupportedError(
+              `cannot lift '${name}': stm with the base register in its own list, not as the lowest ` +
+                `entry — the value stored for that register is UNPREDICTABLE and differs between ` +
+                `ARMv4 (new base) and ARMv5 (old base)`,
+            );
+          }
           // SNAPSHOT the base ONCE: hardware performs every transfer from the ORIGINAL base, but
           // a base-in-list ldmia overwrites that register mid-list — re-reading it per iteration
           // loaded the siblings from the freshly-loaded value instead (silent wrong addresses,
@@ -1212,10 +1520,12 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
               irb.ops.push(mkOp('store', { operands: [base0, readData(reg(r), bi)], attrs: { off: 4 * i, width: 4 } }));
             }
           });
-          // Writeback advances the base by 4×count — SUPPRESSED when there is no `!`, or (ldmia)
-          // when the base is itself in the list (the loaded value wins, ARMv4T).
+          // Writeback advances the base by 4×count. It is suppressed ONLY for an ldmia whose base
+          // is in its own list — the loaded value wins. GBATEK, THUMB.15: "no writeback
+          // (LDM/ARMv4/ARMv5; at this point, THUMB opcodes work different than ARM opcodes)".
+          // The `!` is NOT what decides it: see above, there is no encoding without writeback.
           const wroteBase = ins.mnemonic === 'ldmia' && list.some((r) => reg(r) === baseReg);
-          if (writeback && !wroteBase) {
+          if (!wroteBase) {
             const adv = mkValue(T.unk(32));
             irb.ops.push(mkOp('add', { operands: [base0, constVal(4 * list.length, bi)], results: [adv] }));
             writeVar(baseReg, bi, adv);
@@ -1278,6 +1588,54 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
           if (ins.mnemonic === 'ldr' && b !== undefined) {
             const pr = poolRef(b, dataWords);
             if (pr?.kind === 'const') {
+              // Numeric-pool PROMOTION (symbols.ts): a pool-loaded word whose value the
+              // project's symbol map knows becomes the NAMED global's address — the same
+              // `gaddr` the symbol-pool path emits, so everything downstream is the existing
+              // named-global machinery. Only pool-loaded words promote (an address built by
+              // arithmetic never reaches here); a promoted `code` symbol carries `code: true`
+              // so the structurer spells it `(u32)Name`, not `&Name`.
+              //
+              // VETOED when this asm's pool names other symbols (poolNamesASymbol): agbcc would
+              // have emitted THIS word symbolically too had the source named it, so promoting it
+              // spells a name the source did not use.
+              //
+              // …but the veto is really about RELOCATION, not about naming. An `extern` name makes
+              // the compiler emit a relocated pool word, which contradicts the numeric word the
+              // target shows. An address-cast MACRO expands to that same numeric literal, so it is
+              // COMPATIBLE with the evidence by construction and is never vetoed — indeed it is
+              // the spelling the numeric word is evidence FOR (klonoa's true source reaches these
+              // cells through exactly such macros). Nothing is guessed in either case: a vetoed
+              // word stays the raw constant the target says it is.
+              const found = symbols ? lookupSymbol(symbols, pr.value) : null;
+              const si = found && (!poolNamesSymbols || found.macroBody !== undefined) ? found : null;
+              if (si) {
+                const res = mkValue(T.unk(32));
+                irb.ops.push(
+                  mkOp('gaddr', {
+                    results: [res],
+                    attrs: { sym: si.name, ...(si.kind === 'code' ? { code: true } : {}) },
+                  }),
+                );
+                writeVar(reg(a), bi, res);
+                break;
+              }
+              // INTERIOR attribution: a value strictly inside a sized data symbol becomes
+              // `gaddr sym + offset` — the `&gSym + K` tree structure.ts already lowers (and,
+              // with a struct layout, spells as the named field). Sized symbols only; an
+              // unattributed address stays a raw const — nothing guesses.
+              // Interior attribution is always an `&gSym + K` spelling — extern-shaped, hence
+              // relocated — so the veto applies to it without the macro exemption above.
+              const interior = symbols && !poolNamesSymbols ? lookupInterior(symbols, pr.value) : null;
+              if (interior) {
+                const g = mkValue(T.unk(32));
+                const k = mkValue(T.unk(32));
+                const res = mkValue(T.unk(32));
+                irb.ops.push(mkOp('gaddr', { results: [g], attrs: { sym: interior.info.name } }));
+                irb.ops.push(mkOp('const', { results: [k], attrs: { value: interior.offset } }));
+                irb.ops.push(mkOp('add', { operands: [g, k], results: [res] }));
+                writeVar(reg(a), bi, res);
+                break;
+              }
               const res = mkValue(T.unk(32));
               irb.ops.push(mkOp('const', { results: [res], attrs: { value: pr.value } }));
               writeVar(reg(a), bi, res);
@@ -1303,9 +1661,19 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
           }
           const width = /b/.test(ins.mnemonic) ? 1 : /h/.test(ins.mnemonic) ? 2 : 4;
           const signed = ins.mnemonic === 'ldr' || /s/.test(ins.mnemonic.slice(3));
-          const { base, off } = parseAddr(b);
+          const { base, off, regOff } = parseAddr(b);
+          // `[rB, rX]` register-offset: lower EXACTLY as `rB + rX` then a load at offset 0 —
+          // the same address arithmetic the encoding performs. (parseAddr used to silently
+          // read `[rB]`, dropping the index — a silent miscompile; ldrsh exists ONLY in this
+          // form in Thumb-1, so every ldrsh went through here.)
+          let baseVal = readData(base, bi);
+          if (regOff !== undefined) {
+            const sum = mkValue(T.unk(32));
+            irb.ops.push(mkOp('add', { operands: [baseVal, readData(regOff, bi)], results: [sum] }));
+            baseVal = sum;
+          }
           const res = mkValue(T.unk(32));
-          irb.ops.push(mkOp('load', { operands: [readData(base, bi)], results: [res], attrs: { off, width, signed } }));
+          irb.ops.push(mkOp('load', { operands: [baseVal], results: [res], attrs: { off, width, signed } }));
           writeVar(reg(a), bi, res);
           break;
         }
@@ -1318,8 +1686,15 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
             break;
           }
           const width = /b/.test(ins.mnemonic) ? 1 : /h/.test(ins.mnemonic) ? 2 : 4;
-          const { base, off } = parseAddr(b);
-          irb.ops.push(mkOp('store', { operands: [readData(base, bi), readData(reg(a), bi)], attrs: { off, width } }));
+          const { base, off, regOff } = parseAddr(b);
+          let storeBase = readData(base, bi);
+          if (regOff !== undefined) {
+            // register-offset store: same exact `rB + rX` lowering as the load path above
+            const sum = mkValue(T.unk(32));
+            irb.ops.push(mkOp('add', { operands: [storeBase, readData(regOff, bi)], results: [sum] }));
+            storeBase = sum;
+          }
+          irb.ops.push(mkOp('store', { operands: [storeBase, readData(reg(a), bi)], attrs: { off, width } }));
           break;
         }
         case 'bl':
@@ -1364,7 +1739,20 @@ export function lift(name: string, asm: string, target: TargetDescription, proto
       irb.ops.push(mkOp('br', { successors: [succ(fallLabel(bi))] }));
     } else if (kind === 'return') {
       // bx lr / pop {…,pc} / mov pc,lr
-      irb.ops.push(mkOp('ret', { operands: [readVar(target.returnReg, bi)] }));
+      //
+      // A `bx rN` BRANCHES THROUGH rN, so at that instruction rN holds the RETURN ADDRESS. When rN
+      // is the return-VALUE register the two uses collide, and the address wins by definition —
+      // whatever value was in r0 is gone, so the function cannot be returning one. agbcc spells an
+      // interworking return that way (`push {lr}` … `pop {r0}; bx r0`), and reading r0 as a value
+      // there invents a return the machine provably cannot make: a phantom `return`, a non-`void`
+      // signature that would contradict the project's own prototype, and a live range that keeps
+      // otherwise-dead computation alive.
+      //
+      // The other return forms are untouched, because none of them writes the return register:
+      // `bx lr` and `bx r1`/`bx r2` branch through a different one, and `pop {…,pc}` / `mov pc,lr`
+      // load PC directly. Only the register actually branched through is disqualified.
+      const viaReturnReg = last.mnemonic === 'bx' && last.ops[0] === target.returnReg;
+      irb.ops.push(mkOp('ret', { operands: viaReturnReg ? [] : [readVar(target.returnReg, bi)] }));
     } else if (kind === 'uncond') {
       irb.ops.push(mkOp('br', { successors: [succ(last.ops[0])] }));
     } else if (kind === 'cond') {