@asmlift/core 0.10.0 → 0.11.0

package/src/frontend/thumb.ts

@@ -22,12 +22,20 @@ import { ownArgumentWordsOn } from '../aggregate';
 import { Block, Fn, Successor, Value, mergeClasses, mkOp, mkValue } from '../ir/core';
 import type { Opcode } from '../ir/opcodes';
 import { T } from '../ir/types';
-import { type FnProto, type Prototypes, ownLeadingWordRegisters, wordsOf } from '../proto';
+import {
+  type FnProto,
+  type Prototypes,
+  declaresVoidReturn,
+  ownLeadingWordRegisters,
+  ownReturnWidth,
+  wordsOf,
+} from '../proto';
 import type { ContextGlobals } from '../proto-context';
 import { type SymbolMap, lookupInterior, lookupSymbol } from '../symbols';
 import { ARM_REGISTER_ALIASES, type TargetDescription } from '../target';
 import type { AsmData } from './asmdata';
 import { type CallDeclarations, type CallLowering, callDeclarations, foldByValueArgs } from './call-plan';
+import { type CalleeStackWords, asksCalleeBody } from './callee-body';
 import { pinDeadReads, unreadPairHalf } from './dead-reads';
 import { pinDeviceAccesses } from './device-pins';
 import { pushSwitchBr } from './emit';
@@ -70,6 +78,7 @@ import {
   assertScratchRegsPartitioned,
   makeSsaBuilder,
   mintArgSlotHoles,
+  recordAsmLayout,
   registerArgSlots,
   registerLiveIns,
   stackArgKey,
@@ -84,6 +93,7 @@ import {
   analyzeOutgoingArgs,
   loadedWordBound,
 } from './stackargs';
+import { thumbEntryWordsFromText } from './thumb-entry';
 
 interface Instr {
   /** the CANONICAL spelling — legacy names are normalised (see LEGACY_MNEMONICS) so that every
@@ -1357,9 +1367,17 @@ function decode(
   if (funcLabels.length > 0) {
     const fi = funcLabels.indexOf(name);
     if (fi !== -1) {
-      sliceStart = allFlat.findIndex((f) => f.label === name);
+      // each label's first item, read in one pass: a search per function label costs labels × lines
+      // on every lift, and a callee body bound lifts the whole unit once per callee it asks
+      const firstAt = new Map<string, number>();
+      allFlat.forEach((f, k) => {
+        if (f.label !== undefined && !firstAt.has(f.label)) {
+          firstAt.set(f.label, k);
+        }
+      });
+      sliceStart = firstAt.get(name) ?? -1;
       const starts = funcLabels
-        .map((l) => allFlat.findIndex((f) => f.label === l))
+        .map((l) => firstAt.get(l) ?? -1)
         .filter((s) => s > sliceStart)
         .sort((a, b) => a - b);
       boundaries = [...starts, allFlat.length];
@@ -2524,10 +2542,10 @@ function recoverJumpTable(
 //   - a store, a call, a transfer, a flag READ (`adc`/`sbc`), or any other mnemonic;
 //   - a write to the loaded target (it is what `mov pc` jumps through), or to sp/pc/lr. A write to
 //     the scrutinee is admitted: the switch does not read it after the extras, and the case blocks
-//     read what the extras left there on the hardware too. lr is refused because the lifter reads
-//     `bx lr` as a return by the register's name (`refuseReturnsNotThroughCallersLr`'s NOT ASKED):
-//     a case's `bx lr` after `mov lr, r3` would lift as `return`, where the hardware jumps to r3.
-//     PRE never inserts an lr write, so the refusal costs no compiled dispatch;
+//     read what the extras left there on the hardware too. lr is refused as the register a case's
+//     `bx lr` returns through: a write to it here makes that `bx lr` a jump, which only the return
+//     proof (`refuseReturnsNotThroughCallersLr`) would otherwise have to catch. PRE never inserts
+//     an lr write, so the refusal costs no compiled dispatch;
 //   - a read of a register the idiom wrote (index, table pointer, target) before an extra rewrote it:
 //     the idiom is not lifted, so such a read would see the value from before the dispatch.
 // The reason is returned so the decline can name it (`readThumbText`'s indirect-jump refusal).
@@ -2580,8 +2598,8 @@ export function lift(
   context?: ContextGlobals,
   options: LiftOptions = {},
 ): Fn {
-  return liftWithRelift(name, (oneObject) =>
-    liftOnce(name, asm, target, prototypes, asmData, symbols, context, oneObject, options),
+  return liftWithRelift(name, (oneObject, homesReleased) =>
+    liftOnce(name, asm, target, prototypes, asmData, symbols, context, oneObject, homesReleased, options),
   );
 }
 
@@ -2603,9 +2621,19 @@ function liftOnce(
   symbols: SymbolMap | undefined,
   context: ContextGlobals | undefined,
   oneObject: FrameRange | undefined,
-  options: Pick<LiftOptions, 'contextOwnWords' | 'contextOwnProto' | 'ownMemoryReturn'>,
+  homesReleased: boolean,
+  options: Pick<
+    LiftOptions,
+    | 'contextOwnWords'
+    | 'contextOwnProto'
+    | 'ownMemoryReturn'
+    | 'calleeBodyBound'
+    | 'calleeStackWords'
+    | 'stackSized'
+    | 'entryReadCalls'
+  >,
 ): Fn | FrameObjectRelift {
-  const fill = thumbFillOf(name, asm, target, prototypes, symbols, oneObject, options);
+  const fill = thumbFillOf(name, asm, target, prototypes, symbols, oneObject, options, homesReleased);
   const { cfg, frame, ssa, pairs, statics } = fill;
   const { fn, irBlocks, paramReg } = ssa;
 
@@ -2624,6 +2652,7 @@ function liftOnce(
       throw new FrontendUnsupportedError(m);
     },
     fill.calls,
+    declaresVoidReturn(prototypes[name]),
   );
   // After the fill, so a block's own refusal (the frame's, the operands') keeps its place in the
   // refusal order: the proof reads only the text and the CFG, and changes nothing.
@@ -2649,6 +2678,20 @@ function liftOnce(
   const argSlots = stackArgSlots(registerArgSlots(target.argRegs), target.argRegs);
   mintArgSlotHoles(ssa, cfg.preds[0].length > 0, argSlots);
   ssa.finish();
+  // A scratch register a `pop` fills with another word is a copy the fill never makes: `push {r1};
+  // pop {r0}; bx lr` returns a1, and read by name it would lift `return a0`. Asked after the SSA's own
+  // refusals, which name a register misused across its save before the copy that misuse makes. A
+  // return hands r0 back unless the function's own declaration says it returns nothing.
+  const declaredVoid = (prototypes[name] ?? options.contextOwnProto?.proto)?.returnsVoid === true;
+  const [copy] = [...fill.poppedCopies, ...(declaredVoid ? [] : fill.poppedReturns)];
+  if (copy !== undefined) {
+    const [reg, at] = copy;
+    throw new FrontendUnsupportedError(
+      `cannot lift '${name}': '${at.mnemonic} ${at.ops.join(', ')}' loads a word that is not ${reg}'s own ` +
+        `into ${reg}, which is then used as a value — a pop is read as restoring each register it names, ` +
+        'so the copy it makes is not modelled',
+    );
+  }
 
   // A struct passed by value becomes the one object its words hold (call-plan.ts `foldByValueArgs`)
   // before the audit judges the frame objects, that one among them.
@@ -2671,6 +2714,7 @@ function liftOnce(
     symbols,
     target,
     oneObject,
+    releasableHomes: frame.releasableHomes,
   });
   if (verdict !== undefined && 'oneObject' in verdict) {
     return verdict;
@@ -2803,16 +2847,23 @@ interface LrState {
  *  far-jump relay's lowering needs and does not itself prove (`lowerFarJumpRelays`): with every
  *  return reading the CALLER's lr, the lr a relay writes cannot be what a return jumps to.
  *
- *  NOT ASKED: `bx lr` and `mov pc, lr` are returns by the register's name, whether or not a call
- *  has since overwritten lr. A compiler saves lr before it calls, so no compiled function reaches
- *  that case. The far-jump relay does not lean on it: its lowering declines any function in which
- *  an instruction other than the entry `push` names lr.
+ *  `bx lr` and `mov pc, lr` are asked the same question: lr itself must still hold the caller's lr,
+ *  so an instruction that writes lr by name before one (`mov lr, r4`, `pop {lr}`, `ldr lr, …`)
+ *  declines. Read by the register's name instead, `push {r4, lr}; ldr r4, =g; mov lr, r4; pop {r4};
+ *  bx lr` — a tail jump to g with every argument register live — would lift as a return, and a
+ *  caller whose call to it no declaration lays out would take that lift's one parameter as the
+ *  callee's whole arity (frontend/callee-body.ts). A compiler returns through the word it saved lr in, so no
+ *  compiled function reaches the refusal.
+ *
+ *  NOT ASKED: a CALL's write of lr. `bl g; bx lr` returns to the instruction after the call on the
+ *  hardware, and lifts as `g(); return;`. No compiler emits it (one saves lr before it calls), and
+ *  many call tests' fixtures are written so, so a call leaves lr held. The far-jump relay leans on
+ *  neither: its lowering declines any function in which an instruction other than the entry `push`
+ *  names lr.
  *
  *  Blocks no path from the entry reaches are not asked: they never run. */
 function refuseReturnsNotThroughCallersLr(name: string, cfg: ThumbCfg): void {
-  const { asmBlocks, preds, entryReachable } = cfg;
-  const succs: number[][] = asmBlocks.map(() => []);
-  preds.forEach((ps, b) => ps.forEach((p) => succs[p].push(b)));
+  const { asmBlocks, succs, entryReachable } = cfg;
   const LR = 'r14';
   const join = (a: LrState, b: LrState): LrState => {
     const depth = a.depth !== null && a.depth === b.depth ? a.depth : null;
@@ -2863,10 +2914,9 @@ function refuseReturnsNotThroughCallersLr(name: string, cfg: ThumbCfg): void {
           }
         }
       } else if (xfer === 'return') {
-        // `bx rN`: the register itself must hold the caller's lr. `bx lr` and `mov pc, lr` are
-        // returns by name (see the doc comment).
+        // `bx rN`, `bx lr` and `mov pc, lr` alike: the register must still hold the caller's lr.
         const via = canonReg(mn === 'bx' ? (ins.ops[0] ?? '') : (ins.ops[1] ?? ''));
-        if (via !== LR && (via === null || !regs.has(via))) {
+        if (via === null || !regs.has(via)) {
           refuse(ins);
         }
       } else if (mn === 'push') {
@@ -2887,7 +2937,12 @@ function refuseReturnsNotThroughCallersLr(name: string, cfg: ThumbCfg): void {
       } else if (!isSpReg(ins.ops[0])) {
         const writes = regWritesOf(ins);
         if (writes === 'all') {
+          // a call's own write of lr is not asked (see the doc comment)
+          const kept = /^(bl|blx|swi)$/.test(mn) && regs.has(LR);
           regs.clear();
+          if (kept) {
+            regs.add(LR);
+          }
         } else {
           const src = /^movs?$/.test(mn) ? canonReg(ins.ops[1] ?? '') : null;
           const copies = src !== null && regs.has(src);
@@ -3196,6 +3251,8 @@ interface ThumbCfg {
   readonly labelIndex: ReadonlyMap<string, number>;
   /** Each block's predecessors, one entry per edge. */
   readonly preds: number[][];
+  /** Each block's successors, `preds` turned around. */
+  readonly succs: readonly (readonly number[])[];
   readonly entryReachable: ReadonlySet<number>;
 }
 
@@ -3238,7 +3295,9 @@ function thumbCfg(name: string, blocks: readonly AsmBlock[], tables: ReadonlyMap
     }
     return live;
   })();
-  return { asmBlocks, labelIndex, preds, entryReachable };
+  const succs: number[][] = asmBlocks.map(() => []);
+  preds.forEach((ps, at) => ps.forEach((p) => succs[p].push(at)));
+  return { asmBlocks, labelIndex, preds, succs, entryReachable };
 }
 
 // --- CFG (successors per block) as label lists; fallthrough + branch targets (via classifyXfer) ---
@@ -3332,6 +3391,9 @@ interface ThumbFrame {
    *  (`narrowSlotReloads`), and the copies those reloads consume, which name no object */
   readonly narrowReloadOf: ReadonlyMap<Instr, number>;
   readonly narrowReloadCopies: ReadonlySet<Instr>;
+  /** the argument homes whose narrow reloads were kept as captures for the one-object answer alone
+   *  (`argumentHomes`), which the audit may ask to release (`FrameObjectAudit.releasableHomes`) */
+  readonly releasableHomes: ReadonlySet<number>;
 }
 
 /** The frame offset of each word of a declared call's outgoing block, or null where it stages none.
@@ -3377,18 +3439,31 @@ function calleeRegister(ins: Instr, target: TargetDescription): string | null |
 function measureThumbFrame({
   name,
   target,
-  cfg: { asmBlocks, preds, entryReachable },
+  cfg: { asmBlocks, preds, succs, entryReachable },
   calls,
   oneObject,
+  homesReleased = false,
   own,
+  dropsVoidReturn,
+  stackWordsOf,
 }: {
   name: string;
   target: TargetDescription;
   cfg: ThumbCfg;
   calls: CallDeclarations;
   oneObject: FrameRange | undefined;
+  /** whether a first audit released the argument homes to the slot model (`releasableHomes`) */
+  homesReleased?: boolean;
   /** the function's own declaration (`ownDeclarationOf`), read only where it `proves` */
   own: OwnDeclaration | undefined;
+  /** whether the lift's `ret` reads nothing: a STATED void entry (`prototypes[name]`), the one
+   *  pipeline.ts `raiseRecovered` drops ret operands for. The context's own entry, proving or not,
+   *  leaves the operand in place. */
+  dropsVoidReturn: boolean;
+  /** the incoming stack words a callee nothing declares loads, off its own body
+   *  (`LiftOptions.calleeStackWords`): the outgoing-argument analysis's `bodyReads`, which asks it
+   *  only where the code stages a block */
+  stackWordsOf?: CalleeStackWords;
 }): ThumbFrame {
   // THE FRAME BASE PASSED TO A CALLEE. What this computes is exactly what its name says and nothing
   // more: somewhere in entry-reachable code a bare `mov rD, sp` copies the frame base into a
@@ -3469,7 +3544,7 @@ function measureThumbFrame({
   // wider frame the publish escape admits exactly the shape the callee escape's table warns
   // about; at one word it cannot occur. A wider frame's publish is read by the outgoing-argument
   // `escape` event instead (below), per program point, which is the reading that survives a block
-  // copy: see "ONE DECISION, TWO LICENCES" above `capturedObjectIsTheWholeFrame`.
+  // copy: see "ONE DECISION, FOUR LICENCES" above `capturedObjectIsTheWholeFrame`.
   //
   // THE WALK IS `heldFrameWalk`, the same one the callee escape is spelled with, because the
   // question is the same one and only the consuming event differs. Here that event is a WORD store
@@ -3606,7 +3681,7 @@ function measureThumbFrame({
   // `localArea >= 4` (measured). Nothing about the frame size moves it either way — which is what
   // makes it the wrong function to reason about a wider licence from.
   //
-  // ONE DECISION, TWO LICENCES. This gate and the outgoing-argument `escape` event (fed below,
+  // ONE DECISION, FOUR LICENCES. This gate and the outgoing-argument `escape` event (fed below,
   // under `compilerBehaviors.escapedFrameAddressNamesALocal`) read the same escapes
   // (`frameAddressReceivers`) and differ only in flow-sensitivity. This gate is flow-INSENSITIVE —
   // one escape anywhere and no frame word is any call's argument — which is sound only where no
@@ -3614,6 +3689,17 @@ function measureThumbFrame({
   // leaves, at any frame size; that field says why that survives a block copy. So what this gate
   // adds is a store that reaches an undeclared call BEFORE the address leaves (the CONTROL of "a
   // capture in an unreachable block proves nothing"), and every "not widened" above is about it.
+  //
+  // The THIRD is the [sp,#0] struct-return capture (`frameBaseIsReturnStorage`, below): flow-
+  // insensitive at any frame size, but only for the hidden pointer of a callee declared to return a
+  // struct through memory, which a block copy's base never is (why: the field's comment). It
+  // matters only where some call may take a stack word: the hidden pointer is r0, which
+  // `frameAddressReceivers` hands over, so such a base always escapes and the fourth licence
+  // admits it everywhere else.
+  //
+  // The FOURTH is the [sp,#0] capture where no call takes a stack word (`noCallTakesAStackWord &&
+  // frameBaseEscapes`, below): flow-insensitive at any frame size too, and sound for a block copy's
+  // base as well, because with no outgoing area no frame word is any call's argument at all.
   const capturedObjectIsTheWholeFrame =
     target.compilerBehaviors.oneWordFrameIsTheCapturedObject === true &&
     (frameBasePassedToCallee || frameBasePublishedToMemory) &&
@@ -3661,22 +3747,35 @@ function measureThumbFrame({
   // offsets either: a store there reaching a call unread is the object being filled for the
   // callee that is handed it.
   //
-  // THE FRAME BASE, ONLY AS A DECLARED CALL'S RETURN STORAGE AND ONLY WHERE NO CALL TAKES A STACK
-  // WORD. A bare `mov rD, sp` is also the base of a by-value argument's block copy into the
-  // outgoing area, and [sp,#0] is then a call's fifth argument word (the producer table above
-  // `capturedObjectIsTheWholeFrame`, which keeps its own licence for a one-word frame). Where every
-  // call is to a callee whose declaration places all of its arguments in registers there is no
-  // outgoing area, and where the base is handed as the hidden pointer of a callee declared to
-  // return a struct through memory it is that struct's storage: two struct-return temps,
-  // `mov r0, sp / bl mk` and `add r0, sp, #4 / bl mk`. A call nothing declares, a call through a
-  // register, or a declaration nothing sizes may take a stack word, and keeps offset 0 out.
+  // THE FRAME BASE, ONLY WHERE ITS ADDRESS ESCAPES AND NO CALL TAKES A STACK WORD, OR AS A
+  // DECLARED CALL'S RETURN STORAGE. A bare `mov rD, sp` is also the base of a by-value argument's
+  // block copy into the outgoing area, and [sp,#0] is then a call's fifth argument word (the
+  // producer table above `capturedObjectIsTheWholeFrame`, which keeps its own licence for a
+  // one-word frame). Where every call's declaration places all of its arguments in registers — no
+  // call at all included — there is no outgoing area on any compiler, so a frame base handed out
+  // (`escapedOffsetOf`: to a call, or stored as a word to memory) is a local's address whoever
+  // receives it: a struct-return temp (`mov r0, sp / bl mk`), or a DMA fill's source published to
+  // the device's registers (`dmafill_wh`). A direct `str rX, [sp]` is then that local's store, as
+  // one at [sp,#4] beside `add rD, sp, #4` is. A frame base only ADDRESSED THROUGH (`mov r3, sp /
+  // strh r1, [r3, #4]`, Thumb's sole spelling of a sub-word frame access) hands nothing out and
+  // leaves [sp,#0] a slot. A call nothing declares, a call through a register, or a declaration
+  // nothing sizes may take a stack word, and keeps offset 0 out — unless the base is a
+  // struct-return callee's hidden pointer and `compilerBehaviors.escapedFrameAddressNamesALocal`
+  // holds (its second reader).
+  //
+  // THUMB ONLY: the MIPS and PPC frontends (`inLocalArea`) route every local-area access through
+  // memory once any frame address is taken, so a direct store at the frame base is already the
+  // object's there.
+  const frameBaseEscapes = [...escapedOffsetOf.values()].includes(0);
   const noCallTakesAStackWord = [...entryReachable].every((b) =>
     asmBlocks[b].instrs.every((ins) => {
       if (ins.mnemonic !== 'bl' && ins.mnemonic !== 'blx') {
         return true;
       }
       const declared = calleeRegister(ins, target) === null ? calls.declaredCall(ins.ops[0] ?? '?') : null;
-      return declared !== null && outgoingBlock(declared.widths, target) === null;
+      // the declaration alone, not `outgoingBlock`: a call whose arguments run past the registers
+      // takes a stack word whether or not the target claims agbcc's staging premise
+      return declared !== null && wordsOf(declared.widths, target) <= target.argRegs.length;
     }),
   );
 
@@ -3738,12 +3837,67 @@ function measureThumbFrame({
   // `ownLeadingWordRegisters`): a `u32 k` spilled on entry and read back as `(u8)k` is no struct's
   // home, and lifts as the slot narrowed. A copy kept here is no capture, so its offset leaves
   // `constantCaptureOffsets` and the slot's own `str`/`ldr` stay slot accesses; one dropped stays a
-  // capture.
+  // capture. A home is held for the one-object answer alone, so the audit may hand it back: where
+  // that answer is withheld (a struct-return temp escapes beside the home) and the audit declines
+  // with the home held, the second lift reads it as any other slot (`releasableHomes`,
+  // `homesReleased`). The hold decides how the LIFT reads a home's reloads, not whether the word
+  // is reloaded: the stack-argument analysis takes a held home's narrow reload as that word's
+  // reload (`capturedReloadOf`) in every lift, as it takes a narrow reload inside the bytes a
+  // first audit asked to keep as one object, which that relift keeps as a capture too. Read as no
+  // reload, a home at the frame's bottom would decline as a possible outgoing argument, and agbcc
+  // compiles that shape: reload spills a DImode struct's registers above the locals, but
+  // `assign_parms` stores a BLKmode one (over 8 bytes) at the frame's bottom, below any temp
+  // (`str r0, [sp] / … / add r0, sp, #0xc / bl mk0 / … / mov r0, sp / ldrb r0, [r0]`). Below an
+  // escaping temp the first lift would decline before any audit could release the home; with a
+  // call and no temp (`g(); return p.m0 + p.m8;`) the one-object relift would.
+  //
+  // A COPY THAT OUTLIVES ITS LOAD. Where reload hands the load another register (`add r3, sp, #0x28
+  // / ldrb r1, [r3]`, the left operand of a `?:` join whose hard register is r1), rD still holds the
+  // address after it. The copy is not lifted, so rD must be DEAD there: no path from the load reads
+  // it before writing it (`readsBeforeWrite`), a return that may hand it back counting as a read.
+  // The lift holds to that proof: the dropped copy leaves a marker in rD (`writeNarrowCopyMarker`),
+  // and a read of it declines. A CALL READS WHAT IT IS HANDED, the one receiver rule
+  // (`frameAddressReceivers`: a declared callee's argument words, every argument register where
+  // nothing declares it), plus the register it calls through (`calleeRegister`). Any other register
+  // it clobbers, r0 among them, is dead past it, and a callee-saved one still holds the copy. Read
+  // as `readsBeforeWrite` reads a call for the save analysis (every register but r12), kleod
+  // sub_08016EEC keeps two copies live, in r3 and in r6.
+  //
+  // A RETURN HANDS BACK WHAT THE OWN DECLARATION RETURNS. Where a STATED entry declares a void
+  // return, a return reads neither r0 nor r1 (pipeline.ts `dropVoidReturnOperands`, the exemption
+  // `refuseStaleIdiomReads` makes for the marker), and where the own declaration proves a return no
+  // wider than a word, it reads r0 alone: `add r1, sp, #4 / ldrb r0, [r1] / … / pop {r0} / bx r0` in
+  // a `void f(u32)` leaves no read of r1. Undeclared, a return may hand back the pair r0:r1. The void
+  // reading of r0 is the stated entry's alone because the drop is: under the context's `void f(u32)`
+  // the lifted `ret` still reads r0, and an r0 copy dropped there would print as `return uninit_r0`.
+  // The reading of r1 needs no such care, under a void or a one-word declaration from either source,
+  // as the lifted `ret` reads r1 only through a pair the asm builds (`wideReturn`), where the marker
+  // declines.
+  const narrowCallReads = (call: Instr): readonly string[] => {
+    const through = calleeRegister(call, target);
+    return typeof through === 'string' ? [...handedOutRegs(call), through] : handedOutRegs(call);
+  };
+  // `callClobbers` leaves out r0, which the lift writes with what the call returns
+  const narrowCallClobbers = [...calls.callClobbers, target.returnReg];
+  const ownProven = own?.proves === true ? own.proto : undefined;
+  const returnMayHand = (r: string): boolean =>
+    !dropsVoidReturn &&
+    !(
+      r !== target.returnReg &&
+      (declaresVoidReturn(ownProven) || (ownReturnWidth(ownProven) ?? Number.POSITIVE_INFINITY) <= 32)
+    );
   const narrowCandidates = narrowSlotReloads(
     asmBlocks,
     entryReachable,
     localArea,
     target.capabilities.endianness === 'little',
+    (b, from, r) => {
+      const use = readsBeforeWrite(asmBlocks, succs, b, from, r, {
+        reads: narrowCallReads,
+        clobbers: narrowCallClobbers,
+      });
+      return use === false || (use === 'returned' && !returnMayHand(r));
+    },
   );
   const candidateCopies = new Set([...narrowCandidates.values()].map((n) => n.copy));
   const otherCaptureOffsets = new Set(
@@ -3783,15 +3937,21 @@ function measureThumbFrame({
     }
   }
   const narrowReloadOf = new Map<Instr, number>();
+  const releasableHomes = new Set<number>();
+  // the narrow reloads the lift keeps as captures (a held home's, and every one inside the bytes
+  // a first audit asked to keep as one object), which are still reloads of that word for the
+  // outgoing-argument analysis below
+  const capturedReloadOf = new Map<Instr, number>();
   for (const [load, { slot }] of narrowCandidates) {
-    if (
-      wordStoredSlots.has(slot) &&
-      !argumentHomes.has(slot) &&
-      !otherCaptureOffsets.has(slot) &&
-      !inByValueBlock(slot, 4) &&
-      !(oneObject !== undefined && slot < oneObject.to && slot + 4 > oneObject.from)
-    ) {
-      narrowReloadOf.set(load, slot);
+    if (oneObject !== undefined && slot < oneObject.to && slot + 4 > oneObject.from) {
+      capturedReloadOf.set(load, slot);
+    } else if (wordStoredSlots.has(slot) && !otherCaptureOffsets.has(slot) && !inByValueBlock(slot, 4)) {
+      if (argumentHomes.has(slot) && !homesReleased) {
+        releasableHomes.add(slot);
+        capturedReloadOf.set(load, slot);
+      } else {
+        narrowReloadOf.set(load, slot);
+      }
     }
   }
   const narrowReloadCopies: ReadonlySet<Instr> = new Set(
@@ -3801,7 +3961,13 @@ function measureThumbFrame({
     [...captureOffsetOf]
       .filter(([ins]) => !narrowReloadCopies.has(ins))
       .map(([, o]) => o)
-      .filter((o) => o > 0 || (o === 0 && frameBaseIsReturnStorage && noCallTakesAStackWord)),
+      .filter(
+        (o) =>
+          o > 0 ||
+          (o === 0 &&
+            ((noCallTakesAStackWord && frameBaseEscapes) ||
+              (frameBaseIsReturnStorage && target.compilerBehaviors.escapedFrameAddressNamesALocal === true))),
+      ),
   );
 
   // THE OUTGOING STACK-ARGUMENT AREA. `frontend/stackargs.ts` holds the licence and every refusal;
@@ -3825,14 +3991,18 @@ function measureThumbFrame({
     const off = escapedOffsetOf.get(ins);
     return escapesHere && off !== undefined ? [{ kind: 'escape', off }] : [];
   };
+  const stagesOutgoing = target.compilerBehaviors.stagesOutgoingArgsInFrame === true;
   const eventBlocks = asmBlocks.map((ab) => ({
     events: ab.instrs.flatMap((ins): StackArgsEvent<Instr>[] => {
       const escaped = escapeEvent(ins);
       if (escaped.length > 0 && ins.mnemonic === 'str') {
         return escaped;
       }
-      // …and a narrow reload of a word slot is that slot's reload, as its word reload would be
-      const off = slotAcc(ins) ?? narrowReloadOf.get(ins) ?? null;
+      // …and a narrow reload of a word slot is that slot's reload, as its word reload would be,
+      // one the lift keeps as a capture included (a held argument home's, or one inside the
+      // one-object bytes): that decides how the lift reads the load, not whether the word is
+      // loaded, and a word this function loads is no outgoing argument
+      const off = slotAcc(ins) ?? narrowReloadOf.get(ins) ?? capturedReloadOf.get(ins) ?? null;
       if (off !== null && !constantCaptureOffsets.has(off) && !inByValueBlock(off, 4)) {
         return [{ kind: /^str/.test(ins.mnemonic) ? 'store' : 'load', off }];
       }
@@ -3847,6 +4017,10 @@ function measureThumbFrame({
             callee,
             declared: declared === null ? null : outgoingBlock(declared.widths, target),
             params: declared?.params,
+            // where nothing declares a named call, what its callee's body loads of the stack words
+            ...(declared === null && calleeRegister(ins, target) === null && stagesOutgoing
+              ? { bodyReads: () => stackWordsOf?.(callee) }
+              : {}),
           },
         ];
       }
@@ -4021,6 +4195,7 @@ function measureThumbFrame({
     isOwnFrameWordSlot,
     narrowReloadOf,
     narrowReloadCopies,
+    releasableHomes,
   };
 }
 
@@ -4138,10 +4313,11 @@ function frameAddressDefined(ins: Instr, held: ReadonlyMap<string, number>): [st
 //
 // What this finds is a shape and not yet a licence; the copy is a capture everywhere it fails:
 //   * the copy is `mov rD, sp` or `add rD, sp, #c`, entry-reachable, and in ONE block it is read
-//     by exactly one instruction, a zero-extending `ldrb`/`ldrh` at an immediate offset from rD
-//     that writes rD itself, so the address dies at that load. Anything else that mentions rD
-//     before it (a second load, a store through it, an escape), a call, a control transfer or a
-//     write of sp ends the search, and the copy stays a capture.
+//     by exactly one instruction, a zero-extending `ldrb`/`ldrh` at an immediate offset from rD,
+//     after which the address is dead: the load writes rD itself, or it writes another register
+//     and the caller's `diesAfter` proves no path from it reads rD before writing it. Anything else
+//     that mentions rD before the load (a second load, a store through it, an escape), a call, a
+//     control transfer or a write of sp ends the search, and the copy stays a capture.
 //   * the load's bytes are the low-order part of a whole aligned word of the reserved local area.
 //     A load at any other byte of the word is not that word's value narrowed, whatever it reads.
 //   * `ldrsb`/`ldrsh` exist only register-offset in Thumb-1, and agbcc's signed use reloads a word
@@ -4157,6 +4333,7 @@ function narrowSlotReloads(
   entryReachable: ReadonlySet<number>,
   localArea: number,
   littleEndian: boolean,
+  diesAfter: (b: number, from: number, r: string) => boolean,
 ): Map<Instr, { copy: Instr; slot: number }> {
   const found = new Map<Instr, { copy: Instr; slot: number }>();
   for (const b of entryReachable) {
@@ -4172,7 +4349,8 @@ function narrowSlotReloads(
         return;
       }
       const rD = reg(d);
-      for (const ins of instrs.slice(at + 1)) {
+      for (let li = at + 1; li < instrs.length; li++) {
+        const ins = instrs[li];
         if (ins.mnemonic === 'bl' || ins.mnemonic === 'blx' || classifyXfer(ins) !== null || modifiesSp(ins)) {
           return;
         }
@@ -4181,7 +4359,10 @@ function narrowSlotReloads(
         }
         const width = ins.mnemonic === 'ldrb' ? 1 : ins.mnemonic === 'ldrh' ? 2 : 0;
         const addr = ins.ops[1] === undefined ? null : parseAddr(ins.ops[1]);
-        if (width === 0 || reg(ins.ops[0] ?? '') !== rD || addr === null || reg(addr.base) !== rD || addr.regOff) {
+        if (width === 0 || addr === null || reg(addr.base) !== rD || addr.regOff) {
+          return;
+        }
+        if (reg(ins.ops[0] ?? '') !== rD && !diesAfter(b, li + 1, rD)) {
           return;
         }
         const slot = from + addr.off - (littleEndian ? 0 : 4 - width);
@@ -4638,7 +4819,14 @@ const ALL_REGS = ['r0', 'r1', 'r2', 'r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r
 function bodySavedRegs(
   blocks: readonly AsmBlock[],
   preds: readonly (readonly number[])[],
-): { saved: ReadonlySet<string>; misSaved: ReadonlySet<string>; leaked: ReadonlyMap<string, Instr> } {
+  succs: readonly (readonly number[])[],
+): {
+  saved: ReadonlySet<string>;
+  misSaved: ReadonlySet<string>;
+  leaked: ReadonlyMap<string, Instr>;
+  copied: ReadonlyMap<string, Instr>;
+  returned: ReadonlyMap<string, Instr>;
+} {
   // What each instruction saves, restores and otherwise names; the staging `mov`s first.
   const savesHi = new Map<Instr, string>(); // `mov rLow, rHi` ⇒ rHi, where rLow is pushed unchanged
   const restoresHi = new Set<Instr>(); // `mov rHi, rLow` where rLow was popped unchanged
@@ -4711,6 +4899,8 @@ function bodySavedRegs(
     i === 0 ? { cur: new Set(), open: new Set(), depth: 0, stack: [], clobbered: new Map(), dirty: new Set() } : null,
   );
   const leaked = new Map<string, Instr>();
+  const copied = new Map<string, Instr>();
+  const returned = new Map<string, Instr>();
   const word = (r: string) => canonReg(r) ?? r;
   const walk = (b: number, record: boolean): State => {
     const cur = new Set(stateIn[b]!.cur);
@@ -4721,7 +4911,7 @@ function bodySavedRegs(
     let stack: (string | null)[] | null = stateIn[b]!.stack === null ? null : [...stateIn[b]!.stack!];
     const holds = new Map<string, string>(); // low register ← the high one a save's staging `mov` copied
     const loaded = new Map<string, string | null>(); // a staging pop's low register ← whose word it loaded
-    for (const x of blocks[b].instrs) {
+    for (const [i, x] of blocks[b].instrs.entries()) {
       const before = frame.depthNow();
       frame.step(x);
       const after = frame.depthNow();
@@ -4815,6 +5005,13 @@ function bodySavedRegs(
           cur.delete(r);
           if (/^r([4-9]|1[01])$/.test(word(r))) {
             clobbered.set(word(r), x);
+          } else if (record && own !== null && /^r([0-3]|12)$/.test(word(r))) {
+            // a scratch register: the fill never makes the copy, so a later use of it is refused
+            const use = readsBeforeWrite(blocks, succs, b, i + 1, word(r));
+            const into = use === 'read' ? copied : use === 'returned' ? returned : undefined;
+            if (into !== undefined && !into.has(word(r))) {
+              into.set(word(r), x);
+            }
           }
         });
       // Only a return the frame is balanced at: one with the `push` still on the stack is an
@@ -4871,9 +5068,79 @@ function bodySavedRegs(
     saved: new Set([...savedSomewhere].filter((r) => !mis(r))),
     misSaved: new Set([...savedSomewhere, ...restoredSomewhere].filter(mis)),
     leaked,
+    copied,
+    returned,
   };
 }
 
+/** Whether some path from instruction `from` of block `b` uses what scratch register `reg` holds
+ *  there as a VALUE before writing it: 'read' for an operand that reads it (a `push` of it among
+ *  them) or a call (which may be handed r0-r3), else 'returned' where a return may hand it back (r0
+ *  or r1), which is a use only in a function not declared to return nothing. A `bx` through it is
+ *  the return idiom `pop {r1}; bx r1` (agbcc's `pop {r3}; add sp, #0x10; bx r3` after a variadic
+ *  save), which uses the word as where to go; a write that reads no `reg` ends the path. Any
+ *  spelling of the register counts (`ip` is r12).
+ *
+ *  `calls`, where a caller passes it, reads a `bl`/`blx` by what it is handed instead: a call that
+ *  names `reg` or whose `reads` include it reads it, one that clobbers it (`clobbers`) ends the
+ *  path, and past one that does neither the callee preserved it and the walk goes on. A `swi` is
+ *  read as without it. */
+function readsBeforeWrite(
+  blocks: readonly AsmBlock[],
+  succs: readonly (readonly number[])[],
+  b: number,
+  from: number,
+  reg: string,
+  calls?: { readonly reads: (call: Instr) => readonly string[]; readonly clobbers: readonly string[] },
+): 'read' | 'returned' | false {
+  const names = (x: Instr): boolean =>
+    expandRegList(
+      x.ops
+        .join(' ')
+        .toLowerCase()
+        .replace(/[[\]{}!#]/g, ' ')
+        .split(/[,\s]+/)
+        .filter(Boolean),
+    ).some((t) => canonReg(t) === reg);
+  const seen = new Set<number>();
+  let returned = false;
+  // true where this path reads it; a path that returns it notes so and reads nothing
+  const path = (at: number, start: number): boolean => {
+    for (const x of blocks[at].instrs.slice(start)) {
+      const mn = x.mnemonic;
+      if (classifyXfer(x) === 'return') {
+        returned ||= !(mn === 'bx' && canonReg(x.ops[0] ?? '') === reg) && (reg === 'r0' || reg === 'r1');
+        return false;
+      }
+      if (calls !== undefined && (mn === 'bl' || mn === 'blx')) {
+        if (names(x) || calls.reads(x).some((r) => canonReg(r) === reg)) {
+          return true;
+        }
+        if (calls.clobbers.some((r) => canonReg(r) === reg)) {
+          return false;
+        }
+        continue;
+      }
+      if (/^(bl|blx|swi)$/.test(mn)) {
+        return reg !== 'r12';
+      }
+      if (names(x)) {
+        const dest = canonReg(x.ops[0] ?? '');
+        // Thumb's three-operand forms (`add rD, rN, #i`, `add rD, sp, #k`, `lsl rD, rM, #s`, `sub rD,
+        // rN, rM`) read only their sources; the two-operand ones (`add rD, #i`, `mul rD, rM`) read rD.
+        const writesOnly =
+          mn === 'pop' ||
+          ((DEST_ONLY.test(mn) || SINGLE_LOAD.test(mn) || (WRITES_OPERAND_0.test(mn) && x.ops.length === 3)) &&
+            dest === reg &&
+            !names({ ...x, ops: x.ops.slice(1) }));
+        return !writesOnly;
+      }
+    }
+    return succs[at].some((s) => !seen.has(s) && (seen.add(s), path(s, 0)));
+  };
+  return path(b, from) ? 'read' : returned ? 'returned' : false;
+}
+
 /** How the fill reads and writes an operand: the guards that keep sp, pc and a data label from
  *  being read or written as a register, and the function-scope statics a pool word names. */
 interface ThumbOperands {
@@ -5361,6 +5628,13 @@ interface ThumbFill {
   /** Each callee-saved register a `pop` loads another word into and that reaches a balanced return
    *  so (`bodySavedRegs`'s `leaked`), with that pop: refused once the return proof has run. */
   readonly poppedForeign: ReadonlyMap<string, Instr>;
+  /** Each caller-saved register a `pop` loads another word into and some path then reads as a value
+   *  before writing it (`bodySavedRegs`'s `copied`, `readsBeforeWrite`), with that pop: refused once
+   *  the return proof has run. */
+  readonly poppedCopies: ReadonlyMap<string, Instr>;
+  /** …and each one a return may hand back so (`bodySavedRegs`'s `returned`): refused unless the
+   *  function's own declaration returns nothing. */
+  readonly poppedReturns: ReadonlyMap<string, Instr>;
 }
 
 /** EVERY STAGE BEFORE THE FILL, in their refusal order: the text, the CFG, the target's scratch
@@ -5378,7 +5652,21 @@ function thumbFillOf(
     contextOwnWords,
     contextOwnProto,
     ownMemoryReturn,
-  }: Pick<LiftOptions, 'contextOwnWords' | 'contextOwnProto' | 'ownMemoryReturn'> = {},
+    calleeBodyBound,
+    calleeStackWords,
+    stackSized,
+    entryReadCalls,
+  }: Pick<
+    LiftOptions,
+    | 'contextOwnWords'
+    | 'contextOwnProto'
+    | 'ownMemoryReturn'
+    | 'calleeBodyBound'
+    | 'calleeStackWords'
+    | 'stackSized'
+    | 'entryReadCalls'
+  > = {},
+  homesReleased = false,
 ): ThumbFill {
   const text = readThumbText(name, asm, target.compilerBehaviors.farJumpRelay?.comment);
   const cfg = thumbCfg(name, text.blocks, text.tables);
@@ -5392,6 +5680,9 @@ function thumbFillOf(
       throw new FrontendUnsupportedError(message);
     },
     () => ownDeclarationOf(name, prototypes, contextOwnProto),
+    calleeBodyBound,
+    entryReadCalls,
+    stackSized,
   );
   const frame = measureThumbFrame({
     name,
@@ -5399,7 +5690,13 @@ function thumbFillOf(
     cfg,
     calls,
     oneObject,
+    homesReleased,
     own: ownDeclarationOf(name, prototypes, contextOwnProto),
+    dropsVoidReturn: declaresVoidReturn(prototypes[name]),
+    stackWordsOf: (callee) =>
+      asksCalleeBody(Object.hasOwn(prototypes, callee) ? prototypes[callee] : undefined)
+        ? calleeStackWords?.(callee)
+        : undefined,
   });
 
   // --- ISA-neutral SSA construction (shared Braun builder) ---
@@ -5416,7 +5713,7 @@ function thumbFillOf(
   // a two-parameter one.
   // A prologue save that some path uses past its restore, or carries to a return unrestored, is
   // `misSaved` and no save: the prologue's reading of it sees only the `push`.
-  const body = bodySavedRegs(cfg.asmBlocks, cfg.preds);
+  const body = bodySavedRegs(cfg.asmBlocks, cfg.preds, cfg.succs);
   const liveIns = registerLiveIns(
     target,
     new Set([...frame.savedRegs, ...body.saved].filter((r) => !body.misSaved.has(r))),
@@ -5431,6 +5728,21 @@ function thumbFillOf(
     undefined,
     liveIns.globalRegs,
   );
+  // Where agbcc put each block (ir/core.ts `AsmLayout`), read off the text the CFG was cut from:
+  // the transfer `classifyXfer` names is the block's branch, and everything before it its body.
+  ssa.fn.asmLayout = recordAsmLayout(
+    ssa.irBlocks,
+    cfg.asmBlocks.map((ab) => {
+      const xfer = ab.instrs.length ? classifyXfer(ab.instrs[ab.instrs.length - 1]) : null;
+      const branch = xfer === 'uncond' || xfer === 'cond';
+      return {
+        body: branch ? ab.instrs.slice(0, -1) : ab.instrs,
+        endsInJump: xfer === 'uncond',
+        // a far-jump relay wears `bl` and is a branch (`classifyXfer`)
+        isCall: (ins) => (ins.mnemonic === 'bl' && !(ins as Instr).farJump) || ins.mnemonic === 'blx',
+      };
+    }),
+  );
   const statics = makeLocalStatics();
   const operands = thumbOperands({
     name,
@@ -5471,6 +5783,8 @@ function thumbFillOf(
     staleIdiomValues: new Map(),
     caseEntries: elidedCaseEntries(cfg, text.tables),
     poppedForeign: body.leaked,
+    poppedCopies: body.copied,
+    poppedReturns: body.returned,
   };
 }
 
@@ -5999,6 +6313,7 @@ function lowerMov(fill: ThumbFill, cur: BlockCursor, ins: Instr): void {
     if (frame.slotsOk && frame.localArea > 0) {
       // a copy only a narrow slot reload reads names no object; the reload reads the slot
       if (frame.narrowReloadCopies.has(ins)) {
+        writeNarrowCopyMarker(fill, cur, reg(a));
         return;
       }
       const res = mkValue(T.unk(32));
@@ -6012,6 +6327,18 @@ function lowerMov(fill: ThumbFill, cur: BlockCursor, ins: Instr): void {
   writeData(reg(a), bi, v);
 }
 
+/** What a narrow reload's unlifted copy of sp leaves in `r`: an address no C spells.
+ *  `measureThumbFrame` accepts the copy only where `r` is dead past its load, and the marker holds
+ *  the lift to that: a read of it declines (`refuseStaleIdiomReads`) rather than reading what `r`
+ *  held before the copy. */
+function writeNarrowCopyMarker(fill: ThumbFill, cur: BlockCursor, r: string): void {
+  fill.operands.writeData(
+    r,
+    cur.bi,
+    staleMarker(cur.irb.ops, r, { reg: r, form: 'narrow', parks: false }, fill.staleIdiomValues),
+  );
+}
+
 /** `add`: a frame adjustment, a 64-bit pair with the `adc` after it, a frame capture,
  *  the copy idiom, or an add. */
 function lowerAdd(fill: ThumbFill, cur: BlockCursor, ins: Instr, ii: number): void {
@@ -6036,7 +6363,8 @@ function lowerAdd(fill: ThumbFill, cur: BlockCursor, ins: Instr, ii: number): vo
   if (isSpReg(b ?? '') && !isSpReg(a ?? '') && c !== undefined && IMM_LITERAL.test(c)) {
     if (frame.slotsOk && frame.localArea > 0) {
       if (frame.narrowReloadCopies.has(ins)) {
-        return; // see lowerMov
+        writeNarrowCopyMarker(fill, cur, reg(a)); // see lowerMov
+        return;
       }
       const res = mkValue(T.unk(32));
       irb.ops.push(mkOp('laddr', { results: [res], attrs: { off: imm(c) } }));
@@ -6287,7 +6615,16 @@ function lowerLoad(fill: ThumbFill, cur: BlockCursor, ins: Instr): void {
         irb.ops.push(
           mkOp('gaddr', {
             results: [res],
-            attrs: { sym: si.name, ...(si.kind === 'code' ? { code: true } : {}) },
+            // `fromMap`: the NAME is asmlift's reading of a numeric word, not the asm's own
+            // spelling (raise/offsetnames.ts `cellSpelledTwice` asks which), and `mapAddr` the
+            // word itself — the one address of a name the map places at several that this
+            // spelling denotes. A macro expands to the numeric literal the asm holds, so it is
+            // not marked.
+            attrs: {
+              sym: si.name,
+              ...(si.kind === 'code' ? { code: true } : {}),
+              ...(si.macroBody === undefined ? { fromMap: true, mapAddr: pr.value >>> 0 } : {}),
+            },
           }),
         );
         writeData(reg(a), bi, res);
@@ -6304,7 +6641,12 @@ function lowerLoad(fill: ThumbFill, cur: BlockCursor, ins: Instr): void {
         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('gaddr', {
+            results: [g],
+            attrs: { sym: interior.info.name, fromMap: true, mapAddr: (pr.value - interior.offset) >>> 0 },
+          }),
+        );
         irb.ops.push(mkOp('const', { results: [k], attrs: { value: interior.offset } }));
         irb.ops.push(mkOp('add', { operands: [g, k], results: [res] }));
         writeData(reg(a), bi, res);
@@ -6541,6 +6883,8 @@ function lowerCall(fill: ThumbFill, cur: BlockCursor, ins: Instr): void {
       usedSlotOffsets.add(off);
       return ssa.readVar(stackSlotKey(off), bi);
     },
+    // …and that block is the arity of a call nothing declares, where its callee's body licensed it
+    stackWords: frame.slotsOk ? frame.outgoingArgs.blocks.get(ins)?.length : undefined,
     // A FRAME ADDRESS AN UNDECLARED ARITY LEAVES OUT IS AN ARGUMENT ALL THE SAME. The frame walks
     // read the call as handed every argument register it holds (`frameAddressReceivers`), and the
     // lift reads the object as written by that receiver (`isFrameObjectAccess`, with no reaching-
@@ -6735,7 +7079,12 @@ function fallLabel(asmBlocks: readonly AsmBlock[], name: string, bi: number): st
 }
 
 /** The ARMv4T / Thumb (agbcc) frontend, registered for the `armv4t` target. */
-export const thumbFrontend: Frontend = { id: 'thumb', inputFormat: 'gnu-as', lift };
+export const thumbFrontend: Frontend = {
+  id: 'thumb',
+  inputFormat: 'gnu-as',
+  lift,
+  entryStackWords: thumbEntryWordsFromText,
+};
 
 /** Internal surface for this module's own tests, and for nothing else. `@asmlift/core` exports
  *  every source path under `./*`, so a plain `export` here would put the pad table, the pad predicate, the witness serialisation and the lift's stages into the