@asmlift/core 0.9.0 → 0.10.0

package/src/trace.ts

@@ -12,8 +12,9 @@ import { print } from './ir/print';
 import { verify } from './ir/verify';
 import type { LanguageBackend } from './l3/ast';
 import { DEFAULT_IDIOM_PATTERNS, RewritePattern, applyPattern, dce, patternApplies } from './pattern/engine';
-import { type OnGap, liftStamped, raiseRecovered, structureChecked, stubResult } from './pipeline';
-import { type Prototypes, declaresVoidReturn, prototypesFromSymbols } from './proto';
+import { type OnGap, liftStamped, raiseRecovered, stampBehaviorsFor, structureChecked, stubResult } from './pipeline';
+import { type FnProto, type Prototypes, declaresVoidReturn, prototypesFromSymbols } from './proto';
+import { type ContextGlobals, splitOwnContext } from './proto-context';
 import { assumedShapes, inferGlobalArrays, orderLicensedGlobals } from './raise/globalshape';
 import { OFFSET_NAME_PASS } from './raise/offsetnames';
 import { type SymbolInfo, type SymbolMap, symbolsByName } from './symbols';
@@ -92,6 +93,8 @@ export interface TraceOptions {
   prototypes?: Prototypes; // header facts (callee arities + void-ness), keyed by symbol
   asmData?: AsmData; // data-section side table (Regime-B jump tables), as in decompile()
   symbols?: SymbolMap; // address→symbol map (symbols.ts), as in decompile(); absent ⇒ inert
+  contextGlobals?: ContextGlobals; // the declaration context's globals, as in decompile()
+  ownContextProto?: FnProto; // the context's own entry, as in decompile()
   onGap?: OnGap; // "strict" (default) | "annotate", as in decompile()
   /** Source probe at pattern boundaries: the source asmlift would emit there, which the cli report
    *  scores. One call per boundary: pattern N's after-source is pattern N+1's before-source. Absent ⇒
@@ -189,13 +192,24 @@ function traceTower(
   // Merged exactly as pipeline.ts does: the project's own DWARF signatures fill in what the caller
   // did not state. A trace that lifted from a different table would explain a run that never
   // happened.
-  const prototypes = prototypesFromSymbols(opts.symbols, opts.prototypes ?? {});
+  const ownContext = splitOwnContext(opts.prototypes, name, opts.ownContextProto);
+  const prototypes = prototypesFromSymbols(opts.symbols, ownContext.prototypes ?? {});
   const returnsVoid = declaresVoidReturn(prototypes[name]);
   const trace: StageTrace[] = [];
   const patternEvents: PatternEvent[] = [];
 
   // (1) lift → typed-SSA IR
-  const fn = liftStamped(name, asm, target, prototypes, opts.asmData, opts.symbols);
+  const fn = liftStamped(
+    name,
+    asm,
+    target,
+    prototypes,
+    opts.asmData,
+    opts.symbols,
+    opts.contextGlobals,
+    undefined,
+    ownContext.ownContextProto,
+  );
   trace.push({ id: 'stage:lift', title: 'Lift (ISA frontend → typed-SSA IR)', irDump: irDump(fn), verified: true });
   // The array shapes the assembly evidences, off the LIFTED fn — same reading, same reason, as
   // pipeline.ts's runTower: the fold and the tower below destroy the order the licence reads.
@@ -221,7 +235,9 @@ function traceTower(
   // The names the map holds for addresses this machine code built by arithmetic off a named one
   // (raise/offsetnames.ts), off the same lifted fn and for the same reason as pipeline.ts's
   // runTower.
-  const named = opts.symbols ? OFFSET_NAME_PASS.run(fn, opts.symbols, target.compilerBehaviors) : [];
+  const named = opts.symbols
+    ? OFFSET_NAME_PASS.run(fn, opts.symbols, stampBehaviorsFor(target, opts.contextGlobals))
+    : [];
   trace.push({
     id: 'stage:offsetnames',
     title: 'Name a walked-to address the symbol map knows',
@@ -302,10 +318,10 @@ function traceTower(
           irDump: irDump(fn),
           verified: true,
         }),
-      afterLatchFold: () =>
+      afterFold: (fold) =>
         trace.push({
-          id: 'stage:latchfold',
-          title: 'Empty-latch folding (splice out an SSA-emptied back-edge block)',
+          id: `stage:${fold.id}`,
+          title: fold.title,
           irDump: irDump(fn),
           verified: true,
         }),
@@ -319,8 +335,10 @@ function traceTower(
   const sfn = structureChecked(fn, {
     ...structureOptionsFor(target, returnsVoid, prototypes),
     spellSwitchFallthrough: (opts.backend ?? cBackend).spellsSwitchFallthrough,
+    spellSwitchBreak: (opts.backend ?? cBackend).spellsSwitchBreak,
     onGap: opts.onGap ?? 'strict',
     ...(mapSymbols ? { symbols: mapSymbols } : {}),
+    ...(opts.contextGlobals ? { contextGlobals: opts.contextGlobals } : {}),
     ...(inferredSymbols.size ? { inferredSymbols } : {}),
     ...(orderLicensed.size ? { orderLicensedGlobals: orderLicensed } : {}),
   });

package/src/variation-definitions.ts

@@ -96,7 +96,7 @@ export const VARIATION_KIND_DEFINITIONS: { readonly [K in VariationKind]: Variat
     title: 'Structure',
     meaning:
       'How the checked control flow becomes C: which way a test reads, where a loop starts, what reaches a merge (the point where two paths meet), where a value is kept, and how a read or a compare is spelled.',
-    examples: ['flip-branch', 'defsite', 'loop-entry', 'reread-globals', 'uns-cmp'],
+    examples: ['flip-branch', 'defsite', 'loop-entry', 'reread-globals', 'signed-cmp'],
   },
   respell: {
     title: 'Respell',
@@ -296,7 +296,7 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
       after: 's32 example(u32 a0, u32 a1)',
     },
     implementedIn: RANK,
-    seeAlso: ['signed', 'uns-cmp'],
+    seeAlso: ['signed', 'signed-cmp'],
   },
   signed: {
     title: 'Signed parameters',
@@ -371,6 +371,31 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: 'packages/core/src/raise/shortcircuit.ts',
     seeAlso: ['site-sense'],
   },
+  'narrow-param': {
+    title: 'Parameter declared at the width every use extends it to',
+    summary: 'a parameter read only through narrowing casts is declared narrow, though the prologue does not widen it',
+    detail:
+      'A parameter the function only ever reads through narrowing casts can be declared at 32 bits and cast ' +
+      'at each use, or declared at the widest cast and read bare. Every use is the same value either way, ' +
+      'and where the compiler widens it at each use rather than on entry, the assembly does not say which ' +
+      'one the source declared. This lift declares it narrow, and loses a tie when no prototype declares the width.',
+    compilerBehavior:
+      'agbcc widens an `s16` parameter at each use when every use extends it, and then the two declarations ' +
+      'differ only in how the registers around them are allocated: a sibling `u8` parameter is copied ' +
+      'before it is widened under the narrow one.',
+    offeredWhen: {
+      when: 'Some parameter is read only through 8- or 16-bit casts or masks, and the default lift left it 32 bits wide.',
+      decidedBy: { symbol: 'runPreRecovery', file: 'packages/core/src/raise/pre-recovery.ts' },
+      gates: ['PARAM_READER_WIDTH_GATES'],
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: 'extern u8 *gM; void f3(u8 *, u16, u8); void f2(u8 *, u8);\n@',
+      before: 'void example(s32 a, u8 b) { u8 *p = gM; f3(p + (s16)a * 4, (u16)a, b); f2(p + b * 8, b); }',
+      after: 'void example(s16 a, u8 b) { u8 *p = gM; f3(p + a * 4, (u16)a, b); f2(p + b * 8, b); }',
+    },
+    implementedIn: 'packages/core/src/raise/paramwidth.ts',
+  },
   'shared-ret': {
     title: 'Shared code after an early return',
     summary: 'code both arms of an `if` reach before returning is written once, after the `if`',
@@ -420,6 +445,63 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: 'packages/core/src/raise/tailsink.ts',
     seeAlso: ['shared-ret'],
   },
+  'kept-slot': {
+    title: 'Each arm keeps its copy of a shared tail',
+    summary: "a MIPS jump's delay slot that ends a tail both arms spell stays in its own arm",
+    detail:
+      'IDO, KMC and GCC 2.7.2 fill the delay slot of a `b` or `j` with a copy of the first word at its ' +
+      'target, so by default the jump is read as landing one word earlier and the two arms meet there. ' +
+      'Where the word before the jump also matches the word before that copy, the two arms may instead ' +
+      'have been written out twice, each ending in the same instructions. This lift keeps the slot in its ' +
+      'own arm, so each arm keeps the whole tail it spells.',
+    compilerBehavior:
+      'The two readings are one object: the slot runs before the target on its one edge either way. ' +
+      'Which arms the source wrote out is something only the differ can tell. The question arises on IDO ' +
+      'alone: GCC 2.7.2 and KMC cross-jump a tail both arms spell into one copy at the join before they ' +
+      'fill any slot, so their output has no tail written twice (`mergenarrow` builds with no `b` on either).',
+    offeredWhen: {
+      when: 'The MIPS lift reported a `b`/`j` whose slot ends a common tail of two or more words, and retargeted it.',
+      decidedBy: { symbol: 'enumerateCandidates', file: RANK },
+    },
+    example: {
+      compiler: 'ido',
+      unit: 'void example(s32 *out, s32 a, s32 b, s32 c) { @ }',
+      before: 's32 v; if (c) { v = (a + b) << 16; } else { v = (a - b) << 16; } out[0] = v >> 16;',
+      after: 's16 v; if (c) { v = a + b; } else { v = a - b; } out[0] = v;',
+      note: 'the shape of `synthetic:mergenarrow`',
+    },
+    implementedIn: 'packages/core/src/frontend/mips.ts',
+  },
+  'far-cast': {
+    title: 'Store past the displacement range through a cast',
+    summary: 'a store to a member past the instruction offset range is spelled through a cast of the base',
+    detail:
+      'A member past the offset an instruction can carry is reached through an address the machine adds up ' +
+      'first, and by default that access joins its struct and is spelled as the member. A store there could ' +
+      'equally have been written through a cast of the base, `*((u8 *)p + 38) = v`, or through a pointer the ' +
+      'source held, and on some compilers that is a different object. This lift keeps every such store on ' +
+      'the address it was reached through; loads still join the struct.',
+    compilerBehavior:
+      'agbcc evaluates the right-hand side of a member store before it adds up the address, and the address ' +
+      'of a cast store before the right-hand side, so the two spellings allocate and order registers ' +
+      "differently; a hoisted `u8 *d = &p->f38; *d = v;` builds the cast spelling's object. Elsewhere the " +
+      'member and the cast compile alike one access at a time, but a folded store no longer aliases the ' +
+      'loads beside it, so the lift moves those loads past it, and a pointer the source held is spelled as ' +
+      'members: KMC and GCC 2.7.2 build two loads written before a store and the same loads written after ' +
+      'it into different objects, and two of the three mwcc builds allocate a held pointer and the member ' +
+      'spelling different registers.',
+    offeredWhen: {
+      when: 'The default lift folded a store through a materialised `base + K` address into its struct.',
+      decidedBy: { symbol: 'enumerateCandidates', file: RANK },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: 'struct S { s32 a; u8 pad[34]; u8 f38; };\nvoid example(struct S *p, u8 *q) { @ }',
+      before: 'p->f38 = *q; p->a = 0;',
+      after: '*((u8 *)p + 38) = *q; p->a = 0;',
+    },
+    implementedIn: 'packages/core/src/raise/structs.ts',
+  },
 
   // ── structure ───────────────────────────────────────────────────────────────────────────────
   'flip-branch': {
@@ -772,14 +854,16 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: ANALYSIS,
     seeAlso: ['expr-home', 'derived-home'],
   },
-  'uns-cmp': {
-    title: 'Unsigned compare spelled unsigned',
-    summary: 'an unsigned compare carries a `(u32)` cast where its operands do not already say so',
+  'signed-cmp': {
+    title: 'Unsigned compare spelled signed',
+    summary: 'an unsigned compare drops the `(u32)` cast the default gives an operand that does not already say so',
     detail:
-      'An unsigned comparison takes a `(u32)` cast on an operand the rendering does not already make ' +
-      'unsigned, and a declaration claimed by both kinds of use becomes `u32` when nothing under it needs ' +
-      'signed. Which the source wrote is open in one direction: a signed spelling that matched was proved ' +
-      'non-negative by the compiler, and asmlift can prove less than the compiler can.',
+      'By default an unsigned comparison takes a `(u32)` cast on an operand the rendering does not already ' +
+      'make unsigned, and a declaration claimed by both kinds of use becomes `u32` when nothing under it ' +
+      'needs signed. This writes the comparison without them, as a signed one. The source may have done so: ' +
+      'a compiler emits an unsigned compare for a signed one where it proved both sides non-negative, and ' +
+      'asmlift can prove less than the compiler can. Where the sides can be negative it computes something ' +
+      'else, so it is published only when the candidate matches byte for byte; otherwise it is withheld.',
     compilerBehavior:
       'A compiler emits an unsigned branch from a signed compare only where it proved both sides non-negative.',
     offeredWhen: {
@@ -789,8 +873,8 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     example: {
       compiler: 'agbcc',
       unit: CALLS + 'void example(s32 a, s32 b) { @ A(); }',
-      before: 'if (a < b)',
-      after: 'if ((u32)a < b)',
+      before: 'if ((u32)a < b)',
+      after: 'if (a < b)',
     },
     implementedIn: STRUCTURE,
     seeAlso: ['unsigned', 'signed'],
@@ -835,8 +919,12 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     },
     example: {
       compiler: 'agbcc',
+      // The callees are PROTOTYPED here, unlike `CALLS`: `bl f` sees `c` read in r2 and a0 untouched
+      // in r0, which a pass-through `f(a0, a1, c)` would leave the same way, so an undeclared `f`
+      // declines (frontend/ssa.ts `fallbackArgc` refuses the gap). The lift reads these declarations
+      // off the unit as shown.
       unit:
-        CALLS +
+        's32 f(void); s32 g(void); s32 h(s32, s32);\n' +
         's32 example(s32 a0, s32 a1, s32 c) { s32 v1; s32 v2; if (c) { v1 = f() + 1; v2 = g(); } else { @ } return h(v1, v2); }',
       before: 'v2 = a1; v1 = a0;',
       after: 'v1 = a0; v2 = a1;',
@@ -1630,7 +1718,31 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
       after: 'u8 v; v = gA[12] - 1; gB[14] = (v & 1) + f() % (5 - v) + 1;',
     },
     implementedIn: l3('narrowdecl'),
-    seeAlso: ['narrow-read', 'derived-home', 'escape-home'],
+    seeAlso: ['narrow-load', 'narrow-read', 'derived-home', 'escape-home'],
+  },
+  'narrow-load': {
+    title: 'Narrow load declared at its width',
+    summary: 'a local holding one narrow memory read is declared at that width instead of as an `s32`',
+    detail:
+      'A byte or halfword read from memory into a local can be spelled two ways: an `s32` local assigned the ' +
+      "read, or a local declared at the read's width. Every read of the local is the same value either way; " +
+      "which one the source declared is not in the assembly. Applied on top of every other candidate's source.",
+    compilerBehavior:
+      'agbcc loads a narrow local where it is written and an `s32` one where it is first read, so two byte ' +
+      'reads held across two calls are loaded at different points.',
+    offeredWhen: {
+      when: 'An `s32` local written once, outside a `for` init, by an element or member read of a narrower integer, in no memory.',
+      decidedBy: { symbol: 'narrowLoadDeclarations', file: l3('narrowdecl') },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: 'void f7(u8 *, u8 *, u8, u8, s32, u8, u8);\nvoid example(u8 *p, s32 x) { @ }',
+      before:
+        's32 a; s32 b; a = p[100]; b = p[101]; f7(p + 4, p + 8, a, b, x, 1, 2); f7(p + 8, p + 12, a, b, x, 3, 4);',
+      after: 'u8 a; u8 b; a = p[100]; b = p[101]; f7(p + 4, p + 8, a, b, x, 1, 2); f7(p + 8, p + 12, a, b, x, 3, 4);',
+    },
+    implementedIn: l3('narrowdecl'),
+    seeAlso: ['narrow-decl', 'narrow-read'],
   },
   'narrow-read': {
     title: 'Narrow value declared at its width, read bare',
@@ -1653,7 +1765,7 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
       after: 'u8 y; u8 m; y = cv(p[0]); m = cv(p[1]); return dc(y, m, (u8)cv(p[2]));',
     },
     implementedIn: l3('narrowdecl'),
-    seeAlso: ['narrow-decl'],
+    seeAlso: ['narrow-decl', 'narrow-load'],
   },
   'int-cell': {
     title: 'Global stored a pointer, spelled as an integer',

package/src/variation-gates.ts

@@ -29,6 +29,7 @@ import {
 import { UNREDUCE_GATES } from './l3/unreduce';
 import { VOL_SLOT_GATES } from './l3/volatileval';
 import { VOL_STORE_GATES } from './l3/volstore';
+import { PARAM_READER_WIDTH_GATES } from './raise/paramwidth';
 import { ARM_REREAD_GATES } from './raise/shortcircuit';
 import { NAME_COALESCE_GATES } from './structure/namecoalesce';
 import { FRESH_MERGE_GATES } from './structure/structure';
@@ -59,6 +60,7 @@ export const VARIATION_GATE_TABLES = {
   NAME_COALESCE_GATES,
   OFFMEMBER_GATES,
   ORDERBASE_GATES,
+  PARAM_READER_WIDTH_GATES,
   PTR_FIELD_GATES,
   REGIONBASE_GATES,
   SCOPEBASE_ELIGIBILITY,

package/src/variation-tokens.ts

@@ -67,8 +67,11 @@ const TOKENS = [
   // lift: the assembly lifted or raised again
   { name: 'setup-args', variationKind: 'lift' },
   { name: 'connective', variationKind: 'lift' },
+  { name: 'narrow-param', variationKind: 'lift' },
   { name: 'shared-ret', variationKind: 'lift' },
   { name: 'shared-tail', variationKind: 'lift' },
+  { name: 'kept-slot', variationKind: 'lift' },
+  { name: 'far-cast', variationKind: 'lift' },
   // structure: `structure()` re-run with other options
   { name: 'flip-branch', variationKind: 'structure' },
   { name: 'defsite', variationKind: 'structure' },
@@ -86,7 +89,7 @@ const TOKENS = [
   { name: 'derived-home', variationKind: 'structure' },
   { name: 'merge-home', variationKind: 'structure' },
   { name: 'escape-home', variationKind: 'structure' },
-  { name: 'uns-cmp', variationKind: 'structure' },
+  { name: 'signed-cmp', variationKind: 'structure' },
   { name: 'fresh-merge', variationKind: 'structure' },
   { name: 'copy-defpos', variationKind: 'structure' },
   { name: 'site-sense', variationKind: 'structure' },
@@ -131,6 +134,7 @@ const TOKENS = [
   { name: 'pollguard', variationKind: 'respell' },
   { name: 'pollread', variationKind: 'respell' },
   { name: 'narrow-decl', variationKind: 'respell' },
+  { name: 'narrow-load', variationKind: 'respell' },
   { name: 'narrow-read', variationKind: 'respell' },
   {
     name: 'int-cell',