@asmlift/core 0.9.0 → 0.11.0

package/src/proto.ts

@@ -1,5 +1,6 @@
 import { parseTypeName } from './cdecl/parse';
 import type { IrType } from './ir/types';
+import { demangle, implicitArgumentWords, spellType } from './mangle';
 import type { SymbolInfo, SymbolMap, SymbolTypeFacts } from './symbols';
 import type { TargetDescription } from './target';
 
@@ -30,11 +31,44 @@ export type ParamType = string;
 export interface FnProto {
   /** declared parameters — either the typed parameter list a header extraction produces
    *  (`["u8", "s32"]`), which is a list of C PARAMETERS, or a bare COUNT, which is the user's word
-   *  for how many argument REGISTERS the call occupies. The two are the same number only while
-   *  every parameter fits in a register, and `declaredCallArgs` is what converts the first into
-   *  the second. Omit — or spell a parameter that conversion cannot size — to let the frontend
+   *  for how many argument REGISTERS the call occupies — read so at a call. On the function's OWN
+   *  entry a count bounds no argument register (`ownArgumentWords` abstains): a header's count may
+   *  be of C parameters, and one of those may span any number of words. The two are the
+   *  same number only while every parameter fits in a register, and `declaredCallArgs` is what
+   *  converts the first into the second. Omit — or spell a parameter that conversion cannot size — to let the frontend
    *  fall back to its contiguous-arg-register heuristic. */
   params?: number | ParamType[];
+  /** The parameters, by index into a typed `params`, whose spelling `declaredWidth` cannot size and
+   *  which still travel in one register: an enum, or an array or function type a typedef name
+   *  stands for, which the parameter adjusts to a pointer. A context states it, reading the types
+   *  behind the names (`prototypesFromContext`). Every reader sizes such a parameter at one word
+   *  (`paramClassOf`): the call lowering's widths (`declaredCallArgs`) and a frontend's frame
+   *  partition alike. */
+  wordParams?: readonly number[];
+  /** The parameters, by index into a typed `params`, that are a struct, union or class passed BY
+   *  VALUE: mwcc passes the address of a copy it builds in the caller's own frame, which no source
+   *  declares (`frontend/ppc.ts` `measurePpcFrame`). A context states it, reading the tag behind the
+   *  name (`prototypesFromContext`). A spelling neither this nor `wordParams` lists, and that
+   *  nothing else sizes, is UNSIZED — a name nothing here resolved, not a struct by inference — and
+   *  every reader abstains on it. */
+  byValueParams?: readonly number[];
+  /** The members of each struct or union a typed `params` list passes BY VALUE, keyed by the
+   *  parameter's index: what sizes it, and so how many argument words it takes on a target that
+   *  passes one in words (`compilerBehaviors.byValueAggregateArgWords`, read by `aggregate.ts`
+   *  `byValueCallArgs`). A context states it from the struct's definition, as it states
+   *  `returnLayout`. A by-value parameter with no layout here is unsized, and a call to it refuses
+   *  (`aggregate.ts` `byValueRefusal`) rather than take the argument-register guess. */
+  byValueLayouts?: Readonly<Record<number, AggregateLayout>>;
+  /** The FIXED parameters of a VARIADIC declaration, spelled as a typed `params` list spells them.
+   *  Such a declaration states no `params`, because its arity is the call's and a list would read
+   *  as the whole of it; `wordParams` and `byValueParams` index into this list instead. A context
+   *  states it (`prototypesFromContext`). Read for two things, and never as a layout of its own.
+   *  Where each fixed parameter is one word, they are the call's first argument words, and only
+   *  what the `...` takes is guessed (frontend/call-plan.ts `variadicFloor`). Where one is not, the
+   *  call refuses (`variadicRefusal`): the arity guess reads argument words one by one, so a fixed
+   *  parameter that is not one word is split or dropped: `void takeV(struct W, ...)` would lift
+   *  `takeV(*(s32 *)&gW, 5)`, which compiles against the header. */
+  variadicParams?: ParamType[];
   /** The declared return type is `void`. Read for the function under decompilation, where a
    *  trailing `bx lr` leaves a meaningless return register that must not surface as a `return`
    *  value — and, since the out-parameter path landed, for a CALLEE, where it is the only thing
@@ -89,6 +123,16 @@ export interface FnProto {
    *  this key also says it of a typedef name, which spells no keyword, and carries the members
    *  whose layout decides whether the target returns it through memory at all (`aggregate.ts`). */
   returnLayout?: AggregateLayout;
+  /** ON THE FUNCTION'S OWN ENTRY, `true` says the entry is its declaration context's header entry
+   *  (proto-context.ts `ownContextEntry`) and not the caller's word: it bounds the argument
+   *  registers SOFTLY (pipeline.ts `liftWithinContextBound`), and a struct it returns through
+   *  memory is lifted as that struct where the lift proves the hidden pointer is only its storage
+   *  (pipeline.ts `returnOwnStruct`), and kept as the pointer function with a note where it does
+   *  not; it is read as nothing else — not as a scalar return, not by any reader of a stated own
+   *  entry. Each entry path takes it out of the table before anything reads it (proto-context.ts `splitOwnContext`). It is how a table carries the
+   *  entry a `--context` lift was handed: a benchmark row publishes it so its `--proto` replay
+   *  lifts as the harness did. On a callee's entry it is ignored. */
+  fromContext?: boolean;
 }
 
 /** A struct or union a declaration spells: what it is, and its members as the header lists them.
@@ -118,8 +162,10 @@ export interface AggregateMember {
 /** symbol → prototype. The function under decompilation and its callees share one table. */
 export type Prototypes = Record<string, FnProto>;
 
-/** How many argument REGISTERS a list of parameter WIDTHS occupies: a parameter wider than a
- *  machine word travels in a register pair, every other one in a single register.
+/** How many argument WORDS a list of parameter WIDTHS occupies: a parameter wider than a machine
+ *  word travels in a pair of words, every other one in a single word, and where the target aligns
+ *  an 8-byte argument (`TargetDescription.evenWordAlignedArgs`) a pair that would start at an odd
+ *  word skips one.
  *
  *  The rule lives here rather than beside either caller because it has two, and they are the two
  *  vocabularies a declaration is written in. `runtime-helpers.ts` states a compiler's own helper
@@ -127,17 +173,14 @@ export type Prototypes = Record<string, FnProto>;
  *  `declaredCallArgs` below reads the same widths off a project's C types. One ABI fact, one
  *  copy of it; a second copy is a rule that can disagree with itself.
  *
- *  NO EVEN-REGISTER ALIGNMENT, and that is a measured agbcc fact rather than an omission: its
- *  `thumb.h` computes an argument's register from a plain byte counter with no rounding, so
- *  `void f(s32, long long)` passes the pair in r1:r2 where AAPCS would pad to r2:r3.
- *
- *  AN ABI THAT DOES ALIGN HAS NO READER HERE YET, which is why the rule is flat rather than a
- *  knob on `TargetDescription` beside `argRegs` and `stagesOutgoingArgsInFrame`. MIPS o32 aligns a
- *  64-bit argument to an even register pair and is the target that will want one, and
- *  `frontend/mips.ts` refuses a declared 64-bit parameter (`CallLowering.pairs`), so every list it
- *  counts is one word per parameter. The lowering that builds an o32 pair owes the rule a home. */
-export function wordsOf(params: readonly number[]): number {
-  return params.reduce((n, w) => n + (w > 32 ? 2 : 1), 0);
+ *  agbcc DOES NOT ALIGN, a measured fact rather than an omission: its `thumb.h` computes an
+ *  argument's register from a plain byte counter with no rounding, so `void f(s32, long long)`
+ *  passes the pair in r1:r2 where AAPCS would pad to r2:r3. O32 does, for a scalar and a struct
+ *  alike, and that is the one fact both read here: `aggregate.ts` `byValueCallArgs` places a struct
+ *  by this count, and the lowering that builds an o32 pair, which `frontend/mips.ts` does not yet
+ *  (it refuses a declared 64-bit parameter, `CallLowering.pairs`), counts its words the same way. */
+export function wordsOf(params: readonly number[], target: Pick<TargetDescription, 'evenWordAlignedArgs'>): number {
+  return params.reduce((n, w) => (w > 32 ? n + (target.evenWordAlignedArgs === true ? n % 2 : 0) + 2 : n + 1), 0);
 }
 
 /** Whether a proto states a parameter list at all — readably or not. The tier question, asked
@@ -148,25 +191,49 @@ export function declaresParams(p: FnProto | undefined): boolean {
   return typeof p?.params === 'number' || Array.isArray(p?.params);
 }
 
+/** The declaration a call to `callee` is read at — THE TIER ORDER, written once: the project's own
+ *  entry where it states a parameter list (`declaresParams`), then the compiler's runtime table
+ *  (`helpers`: `runtime-helpers.ts` `helperPrototypes` of the target), then the signatures the C
+ *  standard fixes. `frontend/call-plan.ts` lowers every call at it, and the CLI asks it which
+ *  callees a run guessed, so a callee the lowering reads a signature for is never reported as
+ *  guessed, and one it guesses for always is. `Object.hasOwn` on all three tables: a callee named
+ *  `toString` would otherwise read a `Function` off `Object.prototype` as its entry. */
+export function calleeDeclaration(callee: string, prototypes: Prototypes, helpers: Prototypes): FnProto | undefined {
+  const known = (t: Prototypes) => (Object.hasOwn(t, callee) ? t[callee] : undefined);
+  const own = known(prototypes);
+  return declaresParams(own) ? own : (known(helpers) ?? known(STANDARD_SIGNATURES));
+}
+
 /** What a declaration says about the argument registers a call occupies — the width each declared
  *  parameter travels in, in argument order — or `undefined` when it says nothing this can act on.
  *
  *  THREE WAYS TO SAY NOTHING, AND THEY ARE ONE ANSWER. `params` omitted; `params` malformed (a
  *  bare `"u8"` string, the shape the untyped CLI `--proto` JSON admits); and a list holding a
- *  spelling `declaredWidth` cannot read — a project typedef (`bool8`, `Direction`, `TaskFunc`), a
- *  by-value struct, a floating type. The first two are not a reading of the list at all. The third
- *  is a list read to the end that cannot be CONVERTED: a parameter of unknown width occupies one
- *  argument register or two, the choice moves every later argument's home, and nothing a
- *  declaration holds settles it.
+ *  spelling neither `declaredWidth` reads nor the declaration sizes — a project typedef
+ *  (`bool8`, `Direction`, `TaskFunc`) that `wordParams` does not list, a by-value struct, a
+ *  floating type (a by-value struct is the exception below). The first two are not a reading of the
+ *  list at all. The third is a list read to the end that cannot be CONVERTED: a parameter of
+ *  unknown width occupies one argument register or two, and the choice moves every later argument's
+ *  home. Where the declaration does settle it
+ *  — a typedef'd enum, an array or a function type the context resolved to one word, which
+ *  `wordParams` lists (`paramClassOf`) — the parameter is 32 bits and the list converts.
  *
  *  SO IT ABSTAINS, AND ABSTAINING IS NEITHER A REFUSAL NOR A GUESS. The caller falls back to its
  *  own contiguous-arg-register scan — exactly what it does for a callee the project never declared
  *  — and that scan names itself a guess: `SsaBuilder.readGuessedArg` ASKS whether a register was
  *  set up, and `finish()` retracts the ones an intervening call destroyed. Refusing instead would
- *  be a function that lifts when told nothing and declines when told more. Returning
+ *  be a function that lifts when told nothing and declines when told more. The list's LENGTH is
+ *  still read: every parameter is at least one word, so a guess that counts fewer registers has
+ *  dropped one, and that refuses (frontend/call-plan.ts `refuseShortOfDeclared`). Returning
  *  one-register-each instead would be a layout nothing could know to be right, and the frontend
  *  would then ASSERT those registers rather than ask for them.
  *
+ *  A PARAMETER THE DECLARATION PASSES AS A STRUCT OR UNION BY VALUE IS THE EXCEPTION, because it is
+ *  known not to be one register: the caller asks `aggregate.ts` `byValueCallArgs` to place it, and
+ *  where no rule does (`byValueRefusal`) the call refuses (frontend/call-plan.ts
+ *  `refuseUnplacedByValue`). That is a function that declines when told more, on purpose: a guess
+ *  over a struct drops it or reads its words as separate arguments, and both compile.
+ *
  *  THE MACHINE IS NOT A WITNESS FOR A WIDTH NOBODY STATED, which is the reading this replaces. The
  *  contiguous scan is wrong in both directions and neither is recoverable here. It OVER-counts:
  *  it is read before `frontend/ssa.ts` `narrowToSetupArgs` trims the registers a call sat between,
@@ -186,7 +253,9 @@ export function declaresParams(p: FnProto | undefined): boolean {
  *  target that states no such words the list abstains. A `float` states no layout on either: it
  *  is one word on a soft-float target, but that word is a float only to a callee whose declaration
  *  the candidate prints, and `spellableProto` prints no `float` — an undeclared callee is handed a
- *  `float` promoted to a `double`, which is two words. */
+ *  `float` promoted to a `double`, which is two words. A known spelling with no layout is not the
+ *  unsized abstention, so on a target with no FPU a call to such a declaration refuses rather than
+ *  guess (frontend/call-plan.ts `refuseUnplacedFloat`). */
 export function declaredCallArgs(
   p: FnProto | undefined,
   target: Pick<TargetDescription, 'doubleArgWords'>,
@@ -200,7 +269,7 @@ export function declaredCallArgs(
   const widths: number[] = [];
   const doubles = new Set<number>();
   for (const [i, t] of p.params.entries()) {
-    const w = declaredWidth(t);
+    const w = declaredWidth(t) ?? (paramClassOf(p, p.params, i) === 'word' ? 32 : undefined);
     if (w !== undefined) {
       widths.push(w);
     } else if (target.doubleArgWords !== undefined && isDoubleSpelling(t)) {
@@ -213,19 +282,310 @@ export function declaredCallArgs(
   return { widths, doubles };
 }
 
+/** WHAT ONE DECLARED PARAMETER IS, as far as where a caller places it goes — the one reading every
+ *  reader of a declaration takes, so the call lowering (`declaredCallArgs`) and a frontend's frame
+ *  partition (`frontend/call-plan.ts` `declaredParams`) cannot give one declaration two answers: a
+ *  value of one word (`declaredWidth` sizes it at 32 bits or less, or `wordParams` lists it), one
+ *  wider than a word, a floating type (`isFloatingSpelling`), a struct or union passed by value
+ *  (`byValueParams` lists it, or the spelling says so with its keyword: `struct B`), or UNSIZED — a
+ *  spelling nothing here resolved, which states none of those and is not read as any of them. A
+ *  count states words. */
+export type ParamClass = 'word' | 'wide' | 'float' | 'by-value' | 'unsized';
+
+/** A struct, union or class named by its keyword and tag, with no declarator: passed by value. */
+const BY_VALUE_SPELLING = /^\s*(?:struct|union|class)\s+\w+\s*$/;
+
+/** The class of parameter `k` of the typed list `params` that declaration `p` states (`ParamClass`). */
+export function paramClassOf(p: FnProto, params: readonly ParamType[], k: number): ParamClass {
+  const spelling = params[k];
+  const w = declaredWidth(spelling);
+  return w !== undefined
+    ? w > 32
+      ? 'wide'
+      : 'word'
+    : isFloatingSpelling(spelling)
+      ? 'float'
+      : p.wordParams?.includes(k)
+        ? 'word'
+        : p.byValueParams?.includes(k) || BY_VALUE_SPELLING.test(spelling.replace(/\b(?:const|volatile)\b/g, ' '))
+          ? 'by-value'
+          : 'unsized';
+}
+
+/** Why a call to the VARIADIC declaration `p` cannot be placed by the arity guess: its first fixed
+ *  parameter (`FnProto.variadicParams`, an index into it) that is not one argument word, and the
+ *  reason. Undefined where `p` is no variadic declaration, or where every fixed parameter is a word
+ *  or UNSIZED — a spelling nothing here resolved, which may be one word, and on which every reader
+ *  abstains (`declaredCallArgs`) rather than refuse. */
+export function variadicRefusal(p: FnProto | undefined): { refused: string; param: number } | undefined {
+  const fixed = p?.variadicParams;
+  if (fixed === undefined || p?.params !== undefined) {
+    return undefined;
+  }
+  const reasons: Partial<Record<ParamClass, string>> = {
+    'by-value': 'reads a struct or union passed by value as that many separate words',
+    wide: 'reads a value wider than a word as two separate arguments',
+    float: 'reads a floating-point value as integer words, or misses it in the FPU registers',
+  };
+  for (const k of fixed.keys()) {
+    const why = reasons[paramClassOf(p!, fixed, k)];
+    if (why !== undefined) {
+      return {
+        refused: `its declaration is variadic: the call's arguments are placed by the arity guess, which ${why}`,
+        param: k,
+      };
+    }
+  }
+  return undefined;
+}
+
+/** HOW MANY GENERAL ARGUMENT WORDS THE FUNCTION UNDER DECOMPILATION'S OWN DECLARATION FILLS — an
+ *  UPPER BOUND, never an exact layout — or `undefined` where the declaration bounds nothing.
+ *
+ *  Its one reader is the live-in model (`frontend/ssa.ts` `registerLiveIns`): an argument register
+ *  at or past this many words is one no caller fills, so a read of it before any write is an
+ *  uninitialised local the compiler homed there, never a parameter. KMC and gcc 2.7.2 home a local
+ *  in `a2`/`a3` past a two-parameter declaration, agbcc in `r3` and mwcc 2.3.3 in `r5`..`r10`, and
+ *  unbounded, each such read is a made-up parameter (`uninitfirst(a0, *a1, a2, a3)`).
+ *
+ *  AN UPPER BOUND, because the direction of every error decides what it costs. A bound too HIGH
+ *  leaves a register a parameter, as no bound at all does. A bound
+ *  too LOW turns a real argument into `uninit_<reg>`, which is wrong C. So:
+ *   - the declared words are laid out by {@link wordsOf}, the call's own rule: a floating parameter
+ *     takes no general word where floats count on their own (`fpu.slots: 'separate'`, the PowerPC
+ *     EABI), and everywhere else a floating parameter takes two, as a `long long` does (O32's
+ *     leading floats still take their integer slots, and agbcc passes both in general words).
+ *     A `float` takes two as well: a list cannot say whether the definition is prototyped, and an
+ *     old-style one (`int k(a, b) float a; int b;`) is handed `a` promoted to `double`, so `b`
+ *     sits in r2 / a2. Two words are an upper bound for a prototyped `float` too.
+ *   - UP TO TWO HIDDEN WORDS ARE ADDED to a typed list where they may come first, because no
+ *     parameter list states them and each pushes every declared parameter one register up. A return the
+ *     declaration does not show is a scalar or `void` may be a struct handed back through a
+ *     pointer in argument 0, and a symbol that may name a C++ member function is handed `this`
+ *     there (`mangle.ts` `implicitArgumentWords`). Both are "may": a static member or a struct
+ *     returned in registers leaves one register a parameter.
+ *
+ *  THE PARAMETERS ARE THE STATED ONES, or where the declaration states none, the ones a mangled
+ *  symbol records (`demangle`: `uninitfirst__FiPi` is `(int, int *)`), which is the compiler's own
+ *  copy of the declaration. A BARE COUNT BOUNDS NOTHING: it may count argument registers
+ *  (`FnProto.params`) or C parameters, any of which may be a pair or a struct passed by value of
+ *  any size. IT ABSTAINS where neither states a list, or on one it cannot lay out: an
+ *  unsized spelling (which may be two words), a struct passed by value (sized by a layout this
+ *  does not read), a `long double`; and on a constructor or destructor, which
+ *  may be handed a flag beside `this`. A variadic declaration states no `params` and so
+ *  abstains: its arity is each caller's.
+ *
+ *  `registerReturn` says the declared struct return is one the target hands back in registers, so
+ *  no hidden pointer comes ahead of the parameters: the target's rule, which this module cannot
+ *  read, so every reader asks through `aggregate.ts` `ownArgumentWordsOn`, which reads it as the call
+ *  lowering does. */
+export function ownArgumentWords(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu' | 'evenWordAlignedArgs'>,
+  registerReturn = false,
+): number | undefined {
+  const own = ownArguments(name, p, target, registerReturn);
+  if (own === undefined || own.hidden === undefined) {
+    return undefined;
+  }
+  // The hidden words are laid out WITH the declared ones, not added after them: they come first,
+  // so they move where the even-word rule puts a 64-bit parameter. O32's `struct P f(double x)`
+  // passes the struct pointer in a0, skips a1 and passes `x` in a2:a3 — 4 words, where `1 +
+  // wordsOf([64])` says 3 and turns a3 into `uninit_a3`. The call side counts the same way
+  // (`frontend/call-plan.ts`, `[32, ...params]`).
+  return wordsOf([...Array.from({ length: own.hidden }, () => 32), ...own.widths], target);
+}
+
+/** WHETHER THE OWN DECLARATION SAYS THE CALLER FILLS ARGUMENT 0, asked of a function that RETURNS A
+ *  WORD — so no hidden struct pointer is in question: `true` where a declared parameter word or
+ *  `this` comes first, `false` where it states no argument word at all (`g__Fv`, a free
+ *  function of none), and `undefined` where it does not say (no declaration, one {@link
+ *  ownArgumentWords} cannot lay out, or no parameters on a symbol that only MAY be a method, which a
+ *  static member is not). The PowerPC frontend asks it before a bare return hands back r3's entry
+ *  value (`frontend/ppc.ts` `r3IsAnArgument`), and it reads the declaration the bound reads, so the
+ *  two cannot give one declaration two answers. */
+export function ownFirstArgumentPassed(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu' | 'evenWordAlignedArgs'>,
+): boolean | undefined {
+  const own = ownArguments(name, p, target);
+  if (own === undefined) {
+    return undefined;
+  }
+  if (own.widths.length > 0 || own.passesThis === true) {
+    return true;
+  }
+  return own.passesThis === false ? false : undefined;
+}
+
+/** The own declaration as both readers above read it: the declared parameter words' widths, the
+ *  hidden words that may come ahead of them (`undefined` where they cannot be bounded: a
+ *  constructor's or destructor's flag), and whether `this` is surely passed (`true` for a
+ *  constructor or destructor, `false` for a free function, `undefined` for a symbol that only may
+ *  be a method).
+ *
+ *  A bare count is no declaration this can lay out, so it reads as none. */
+function ownArguments(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu' | 'evenWordAlignedArgs'>,
+  registerReturn = false,
+): { widths: number[]; hidden: number | undefined; passesThis: boolean | undefined } | undefined {
+  // A COUNT BOUNDS NOTHING: it may mean argument registers or C parameters, and a C parameter
+  // may be a pair or a struct passed by value of any size (`f(struct S12 s)` {params: 1} fills 3
+  // words), so no layout of it is an upper bound.
+  if (typeof p?.params === 'number') {
+    return undefined;
+  }
+  const implicit = implicitArgumentWords(name);
+  const widths = ownParamWidths(name, p ?? undefined, target);
+  if (widths === undefined) {
+    return undefined;
+  }
+  return {
+    widths,
+    hidden: implicit === undefined ? undefined : (registerReturn || showsScalarReturn(p) ? 0 : 1) + implicit,
+    passesThis: implicit === undefined ? true : implicit === 0 ? false : undefined,
+  };
+}
+
+/** Whether a declaration shows its return is a scalar or `void`, so no struct pointer is handed
+ *  in ahead of its parameters: a `void`, or a stated return that is no aggregate and whose width
+ *  or floating type this can read. A project typedef (`Pt`) shows nothing. */
+function showsScalarReturn(p: FnProto | undefined): boolean {
+  return (
+    declaresVoidReturn(p) ||
+    (p?.returns !== undefined &&
+      !declaresAggregateReturn(p) &&
+      (declaredWidth(p.returns) !== undefined || isFloatingSpelling(p.returns)))
+  );
+}
+
+/** The parameter list the own declaration states, or where it states none the one a mangled symbol
+ *  records (`demangle`), as {@link ownArgumentWords} reads it. */
+function ownParamList(name: string, p: FnProto | undefined): (FnProto & { params: ParamType[] }) | undefined {
+  const mangled = Array.isArray(p?.params) ? null : demangle(name);
+  const decl: FnProto | undefined = Array.isArray(p?.params)
+    ? p
+    : mangled === null
+      ? undefined
+      : { params: mangled.params.map(spellType) };
+  return Array.isArray(decl?.params) ? (decl as FnProto & { params: ParamType[] }) : undefined;
+}
+
+/** HOW MANY OF THE FIRST ARGUMENT REGISTERS SURELY HOLD ONE OF THE FUNCTION'S OWN PARAMETERS, each a
+ *  single integer-class word — a LOWER bound, where {@link ownArgumentWords} is an upper one, and 0
+ *  where the declaration says nothing surely.
+ *
+ *  Its reader is the guessed-arity gap (`frontend/call-plan.ts` `decideGap`), which may read an
+ *  argument register left at its incoming value as an argument passed on only where that register
+ *  surely holds a parameter. So every "may" counts against it: a hidden word that may come first (a
+ *  return the declaration does not show is a scalar, a symbol that may be a method) makes it 0,
+ *  and the count stops at the first parameter that is not one integer word — a floating one may
+ *  travel in the FPU's registers and leave its general words holding nothing (O32's leading
+ *  float), a wide or unsized one takes words this does not place.
+ *
+ *  {@link ownLeadingWordRegisters} asks the other question the same run of parameters answers. */
+export function ownLeadingWordParams(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu' | 'evenWordAlignedArgs'>,
+  registerReturn = false,
+): number {
+  const decl = ownParamList(name, p);
+  const own = ownArguments(name, p, target, registerReturn);
+  return decl === undefined || own === undefined || own.hidden !== 0 ? 0 : leadingWordRun(decl);
+}
+
+/** HOW MANY OF THE FIRST ARGUMENT REGISTERS SURELY HOLD ONE INTEGER WORD, WHOEVER'S, by the own
+ *  declaration (or the parameter list a mangled symbol records), and 0 where it states no list. A
+ *  hidden word (a struct return's pointer, `this`, a constructor's flag) is a word too, and only
+ *  moves the parameters to later registers, so each of the first that-many registers holds a word
+ *  whichever way it falls, and a later parameter this cannot place does not move the ones before
+ *  it. Its reader is the Thumb frame's by-value home test (`frontend/thumb.ts` `argumentHomes`): a
+ *  register that surely holds a word is no by-value struct's home. */
+export function ownLeadingWordRegisters(name: string, p: FnProto | undefined): number {
+  const decl = ownParamList(name, p);
+  return decl === undefined ? 0 : leadingWordRun(decl);
+}
+
+/** The run of leading parameters that are each one integer-class word: it stops at the first
+ *  floating one or the first {@link paramClassOf} does not call `'word'`. */
+function leadingWordRun(decl: FnProto & { params: ParamType[] }): number {
+  let n = 0;
+  while (
+    n < decl.params.length &&
+    !isFloatingSpelling(decl.params[n]) &&
+    paramClassOf(decl, decl.params, n) === 'word'
+  ) {
+    n++;
+  }
+  return n;
+}
+
+/** Whether the own declaration (or the parameter list a mangled symbol records) states a floating
+ *  parameter, or `undefined` where it states no list. Its reader is the guessed-arity gap
+ *  (`frontend/call-plan.ts` `decidedCallRefusal`): a float may travel in an FPU register that no
+ *  guess counts. */
+export function ownDeclaresFloatingParam(name: string, p: FnProto | undefined): boolean | undefined {
+  return ownParamList(name, p)?.params.some((t) => isFloatingSpelling(t));
+}
+
+/** The widths `ownArgumentWords` lays out: one per declared parameter that takes general words. */
+function ownParamWidths(
+  name: string,
+  p: FnProto | undefined,
+  target: Pick<TargetDescription, 'fpu'>,
+): number[] | undefined {
+  const decl = ownParamList(name, p);
+  if (decl === undefined) {
+    return undefined;
+  }
+  const params = decl.params;
+  const widths: number[] = [];
+  for (const k of params.keys()) {
+    const cls = paramClassOf(decl, params, k);
+    if (cls === 'word' || cls === 'wide') {
+      widths.push(cls === 'word' ? 32 : (declaredWidth(params[k]) ?? 64));
+    } else if (cls === 'float') {
+      const bare = params[k]
+        .replace(/\b(?:const|volatile)\b/g, ' ')
+        .trim()
+        .replace(/\s+/g, ' ');
+      const spelled = FLOAT_TYPEDEFS.get(bare) ?? bare;
+      if (spelled === 'long double') {
+        return undefined;
+      }
+      // a `float` may be an old-style definition's, promoted to `double`
+      if (target.fpu?.slots !== 'separate') {
+        widths.push(64);
+      }
+    } else {
+      return undefined;
+    }
+  }
+  return widths;
+}
+
 /** Whether a declared type is `double`, qualifiers aside. */
 const isDoubleSpelling = (t: ParamType): boolean => t.replace(/\b(?:const|volatile)\b/g, ' ').trim() === 'double';
 
-/** Whether a declared type is a floating type, qualifiers aside: a C keyword, or a typedef of one
- *  every project declares (`FLOAT_TYPEDEFS`). */
-export const isFloatingSpelling = (t: ParamType): boolean => {
+/** The floating type a declared type is, qualifiers aside — a C keyword, or a typedef of one every
+ *  project declares (`FLOAT_TYPEDEFS`) — or undefined for any other type. */
+export const floatingSpelling = (t: ParamType): 'float' | 'double' | 'long double' | undefined => {
   const bare = t
     .replace(/\b(?:const|volatile)\b/g, ' ')
     .trim()
     .replace(/\s+/g, ' ');
-  return /^(?:float|double|long double)$/.test(FLOAT_TYPEDEFS.get(bare) ?? bare);
+  const spelled = FLOAT_TYPEDEFS.get(bare) ?? bare;
+  return spelled === 'float' || spelled === 'double' || spelled === 'long double' ? spelled : undefined;
 };
 
+/** Whether a declared type is a floating type (`floatingSpelling`). */
+export const isFloatingSpelling = (t: ParamType): boolean => floatingSpelling(t) !== undefined;
+
 /** A signature the C standard fixes is a COMPLETE one, which an `FnProto` is not: a project
  *  prototype is a lower bound assembled from whatever a header extraction could read, and omits
  *  what it could not. The standard omits nothing, so the RETURN is spelled here and is required —
@@ -233,6 +593,16 @@ export const isFloatingSpelling = (t: ParamType): boolean => {
 interface StandardSignature extends FnProto {
   /** the return type, as its C spelling (`"void *"`, `"u32"`, `"void"`) */
   returns: ParamType;
+  /** for a BLOCK COPY, the operand each role is: it reads `[0, n)` through `src`, writes `[0, n)`
+   *  through `dst`, and keeps neither address (`blockCopyRoles`) */
+  copies?: BlockCopyRoles;
+}
+
+/** The operands of a standard block copy, by role (`StandardSignature.copies`). */
+export interface BlockCopyRoles {
+  readonly dst: number;
+  readonly src: number;
+  readonly n: number;
 }
 
 /** Signatures FIXED BY THE C STANDARD, so they are not a project fact and need no header to be
@@ -251,9 +621,20 @@ interface StandardSignature extends FnProto {
  *  standard and equally addable, and they are absent because nothing measures them — a table
  *  grown by appetite would be a table nobody priced. */
 export const STANDARD_SIGNATURES: Record<string, StandardSignature> = {
-  memcpy: { params: ['void *', 'const void *', 'u32'], returns: 'void *' },
+  memcpy: { params: ['void *', 'const void *', 'u32'], returns: 'void *', copies: { dst: 0, src: 1, n: 2 } },
 };
 
+/** The roles of `callee`'s operands where the C standard fixes it as a BLOCK COPY, or `undefined`.
+ *  ONE TABLE for every reader: the frame audit bounds the bytes a copy with a literal count reaches
+ *  (frontend/frame-objects.ts `boundedCopy`), and the constant-initializer fold reads the copy an
+ *  aggregate initializer compiles to (l3/constinit.ts). `memmove` is equally fixed, and absent for
+ *  the reason the list above is short. */
+export function blockCopyRoles(callee: unknown): BlockCopyRoles | undefined {
+  return typeof callee === 'string' && Object.hasOwn(STANDARD_SIGNATURES, callee)
+    ? STANDARD_SIGNATURES[callee].copies
+    : undefined;
+}
+
 /** Whether a declaration says the function returns NO VALUE — the one question `returnsVoid` was
  *  added for, asked through both keys that can answer it.
  *
@@ -271,6 +652,18 @@ export function declaresVoidReturn(p: FnProto | undefined): boolean {
   return p?.returnsVoid === true || p?.returns?.trim() === 'void';
 }
 
+/** The bit width of the scalar the function UNDER DECOMPILATION declares it returns, or `undefined`
+ *  where its declaration states none this can read: no `returns`, a struct or union by value, a
+ *  floating type or a project typedef (`declaredWidth`'s "no opinion"). A pointer answers 32,
+ *  `long long` 64.
+ *
+ *  Not {@link declaredReturnWidth}, which answers for a CALLEE and only where the candidate can
+ *  print its declaration: the lifted function's own signature is the one the candidate defines,
+ *  so whether its parameters are spellable says nothing about what it returns. */
+export function ownReturnWidth(p: FnProto | undefined): number | undefined {
+  return p?.returns === undefined || declaresAggregateReturn(p) ? undefined : declaredWidth(p.returns);
+}
+
 /** Whether a declaration says nothing any reader acts on about the return — no spelling, no
  *  layout, and no `returnsVoid: true`. `returnsVoid: false` is silence (`declaresVoidReturn`), and
  *  it is how a manifest spells a callee it knows only the parameters of. Such an entry can take a
@@ -370,6 +763,26 @@ export function declaredWidth(t: ParamType): number | undefined {
   return BASE_WIDTHS.get(base === '' && s !== '' ? 'int' : base);
 }
 
+/** Whether one declared parameter type spells a signed integer, or `undefined` where it does not say:
+ *  a project typedef, a pointer, a plain `char` (whose signedness is the compiler's). */
+export function declaredSigned(t: ParamType): boolean | undefined {
+  const s = t
+    .replace(/\b(?:const|volatile)\b/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+  if (isAddress(s)) {
+    return undefined;
+  }
+  const own = /^([su])(8|16|32|64)$/.exec(s);
+  if (own) {
+    return own[1] === 's';
+  }
+  if (/\bunsigned\b/.test(s) || /^uint\d+_t$/.test(s)) {
+    return false;
+  }
+  return /\bsigned\b/.test(s) || /^int\d+_t$/.test(s) || /^(?:short|int|long)\b/.test(s) ? true : undefined;
+}
+
 /** Whether the type name `s` is a pointer by its abstract declarator, the derivation nearest the
  *  absent name: `u8 *`, `void (*)(s32)`, `f32 (*)[3]`, `void (**)(void)`. A C++ pointer to a data
  *  member is one too, and a pointer to a member function is not: compiled with mwcc GC/1.2.5n,
@@ -519,15 +932,25 @@ export function spellableProto(
   p: FnProto | undefined,
   target: Pick<TargetDescription, 'doubleArgWords'>,
   returned?: IrType,
+  byValue?: ReadonlySet<number>,
 ): { readonly params: readonly ParamType[]; readonly returns: ParamType } | undefined {
   // A struct returned through memory prints as the headers spell the struct the lift typed its call
   // as (`returned`), which the declarations block defines beside this prototype (declare.ts). With
   // no such call it is a return this cannot print.
-  const returns = returned?.kind === 'struct' ? (returned.declared ?? `struct ${returned.name}`) : p?.returns;
+  // A callee passed a struct by value prints whenever its declaration is complete, `returnsVoid`
+  // standing for `void`: the struct is defined only beside it, and the local the lift passes is of
+  // that type, so without it the candidate cannot declare its own local.
+  const passesStruct = byValue !== undefined && byValue.size > 0;
+  const returns =
+    returned?.kind === 'struct'
+      ? (returned.declared ?? `struct ${returned.name}`)
+      : (p?.returns ?? (passesStruct && p?.returnsVoid === true ? 'void' : undefined));
   if (
     p === undefined ||
     returns === undefined ||
-    (returned === undefined && (!spellableType(returns) || declaredWidth(returns) === undefined))
+    (returned === undefined &&
+      !(passesStruct && returns.trim() === 'void') &&
+      (!spellableType(returns) || declaredWidth(returns) === undefined))
   ) {
     return undefined;
   }
@@ -535,7 +958,19 @@ export function spellableProto(
     return { params: [], returns };
   }
   // A parameter prints where the frontend lays it out (`declaredCallArgs`): a type this spells, or a
-  // `double` the target gives general words, which as a C keyword needs no typedef.
+  // `double` the target gives general words, which as a C keyword needs no typedef — or a struct
+  // the lift passed by value (`byValue`, by parameter index), which the declarations block defines
+  // beside this prototype from its `byValueLayouts`, as it defines a returned one.
+  if (Array.isArray(p.params) && byValue !== undefined && passesStruct) {
+    const params = p.params;
+    const rest = params.map((t, i) => (byValue.has(i) ? 'u32' : t));
+    const laid = declaredCallArgs({ ...p, params: rest }, target);
+    return laid !== undefined &&
+      [...byValue].every((i) => p.byValueLayouts !== undefined && Object.hasOwn(p.byValueLayouts, i)) &&
+      rest.every((t, i) => laid.doubles.has(i) || spellableType(t))
+      ? { params, returns }
+      : undefined;
+  }
   const laid = declaredCallArgs(p, target);
   return Array.isArray(p.params) &&
     laid !== undefined &&
@@ -586,16 +1021,96 @@ export function validatePrototypes(value: unknown): string[] {
       continue;
     }
     for (const key of Object.keys(proto)) {
-      if (key !== 'params' && key !== 'returnsVoid' && key !== 'returns' && key !== 'returnLayout') {
-        problems.push(`${sym}: unknown key "${key}" (expected "params", "returnsVoid", "returns" or "returnLayout")`);
+      if (
+        key !== 'params' &&
+        key !== 'returnsVoid' &&
+        key !== 'returns' &&
+        key !== 'returnLayout' &&
+        key !== 'wordParams' &&
+        key !== 'byValueParams' &&
+        key !== 'byValueLayouts' &&
+        key !== 'variadicParams' &&
+        key !== 'fromContext'
+      ) {
+        problems.push(
+          `${sym}: unknown key "${key}" (expected "params", "returnsVoid", "returns", "returnLayout", "wordParams", ` +
+            '"byValueParams", "byValueLayouts", "variadicParams" or "fromContext")',
+        );
+      }
+    }
+    if ('fromContext' in proto && typeof (proto as { fromContext?: unknown }).fromContext !== 'boolean') {
+      problems.push(`${sym}: "fromContext" must be a boolean`);
+    }
+    const { params, returnsVoid, returns, returnLayout, wordParams, byValueParams, byValueLayouts, variadicParams } =
+      proto as {
+        params?: unknown;
+        returnsVoid?: unknown;
+        returns?: unknown;
+        returnLayout?: unknown;
+        wordParams?: unknown;
+        byValueParams?: unknown;
+        byValueLayouts?: unknown;
+        variadicParams?: unknown;
+      };
+    // a variadic declaration's fixed parameters, which it states beside no typed list
+    if (
+      variadicParams !== undefined &&
+      !(Array.isArray(variadicParams) && variadicParams.every((t) => typeof t === 'string') && params === undefined)
+    ) {
+      problems.push(`${sym}: "variadicParams" must be a list of parameter types, beside no "params"`);
+    }
+    const listed = Array.isArray(params) ? params : Array.isArray(variadicParams) ? variadicParams : undefined;
+    for (const [key, list] of [
+      ['wordParams', wordParams],
+      ['byValueParams', byValueParams],
+    ] as const) {
+      if (
+        list !== undefined &&
+        !(
+          listed !== undefined &&
+          Array.isArray(list) &&
+          list.every((k) => Number.isInteger(k) && k >= 0 && k < listed.length)
+        )
+      ) {
+        problems.push(`${sym}: "${key}" must list indices into a typed "params" or "variadicParams" list`);
+      }
+    }
+    // Two answers to one question — whether the parameter travels in a register or as a copy.
+    if (
+      Array.isArray(wordParams) &&
+      Array.isArray(byValueParams) &&
+      wordParams.some((k) => byValueParams.includes(k))
+    ) {
+      problems.push(`${sym}: "wordParams" and "byValueParams" both list one parameter`);
+    }
+    // A layout keyed by a parameter the list does not pass by value would size a word as a struct.
+    if (byValueLayouts !== undefined) {
+      if (typeof byValueLayouts !== 'object' || byValueLayouts === null || Array.isArray(byValueLayouts)) {
+        problems.push(`${sym}: "byValueLayouts" must map a parameter index to its layout`);
+      } else {
+        for (const [key, layout] of Object.entries(byValueLayouts)) {
+          const k = Number(key);
+          if (
+            !Array.isArray(params) ||
+            !params.every((t) => typeof t === 'string') ||
+            !/^\d+$/.test(key) ||
+            k >= params.length ||
+            paramClassOf(
+              {
+                wordParams: Array.isArray(wordParams) ? wordParams : [],
+                byValueParams: Array.isArray(byValueParams) ? byValueParams : [],
+              },
+              params,
+              k,
+            ) !== 'by-value'
+          ) {
+            problems.push(`${sym}: "byValueLayouts" key "${key}" is not a parameter the typed "params" pass by value`);
+            continue;
+          }
+          problems.push(...layoutProblems(`${sym}: "byValueLayouts" ${key}`, layout));
+        }
       }
     }
-    const { params, returnsVoid, returns, returnLayout } = proto as {
-      params?: unknown;
-      returnsVoid?: unknown;
-      returns?: unknown;
-      returnLayout?: unknown;
-    };
     if (returnLayout !== undefined) {
       problems.push(...layoutProblems(`${sym}: "returnLayout"`, returnLayout));
       // A layout beside a return that says `void` or spells a scalar is two answers to one question