@asmlift/core 0.3.0 → 0.5.0

package/src/structure/switch-recover.ts

@@ -18,18 +18,49 @@ export interface SwitchRecoverDeps {
   /** is this opcode an integer comparison? */
   isCmpOpcode: (opcode: string) => boolean;
   switchAllowsNeqCase: boolean;
+  /** does emitting this block's ops carry a statement beyond the ops themselves? A def-site
+   *  ANCHORED merge copy (structure.ts anchorConstCopies) is attached to a const op and emitted
+   *  with the block's side effects — a test block carrying one is not pure however pure its
+   *  opcodes look, because collapsing it into a `switch` discards the write while the edge copy
+   *  it replaced stays suppressed. */
+  emitsAnchoredWrite: (blk: Block) => boolean;
   expr: (v: Value) => Expr;
   structureRegion: (b: Block, stop: Block | null) => Stmt[];
 }
 
+/** Where ONE switch arm's region leaves it — the fact that decides whether the arm can be spelled
+ *  as C at all, and with or without a `break`.
+ *
+ *   - `break`        every path out of the arm reaches the switch's merge (or returns / loops
+ *                    inside the arm). The ordinary closed arm.
+ *   - `fallthrough`  every path out leaves into exactly ONE sibling arm's entry: C's fall-through.
+ *                    Only spellable when that sibling is the arm emitted NEXT (the caller checks
+ *                    emission adjacency — see the l3/ast.ts non-neutrality note).
+ *   - `unstructurable`  anything else: two different siblings, or a mix of "into a sibling" and
+ *                    "out to the merge". C needs a `goto` for those, so callers decline LOUD. */
+export type ArmExit = { kind: 'break' } | { kind: 'fallthrough'; to: Block } | { kind: 'unstructurable'; why: string };
+
 export interface SwitchRecovery {
   recognizeSwitch: (b: Block, stop: Block | null) => Stmt[] | null;
-  /** shared with the Regime-B (`switch_br`) path in structure.ts, which throws where A declines */
-  caseRegionReachesSibling: (targets: Set<Block>, b: Block, merge: Block | null) => boolean;
+  /** shared with the Regime-B (`switch_br`) path in structure.ts, which recovers the fall-through
+   *  this returns; Regime A only accepts `break` arms and otherwise declines to if-recovery. */
+  analyzeArmExit: (entry: Block, b: Block, merge: Block | null, siblings: Set<Block>) => ArmExit;
 }
 
 export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
-  const { fn, defs, dom, ipdom, opBlock, isNamed, isCmpOpcode, switchAllowsNeqCase, expr, structureRegion } = deps;
+  const {
+    fn,
+    defs,
+    dom,
+    ipdom,
+    opBlock,
+    isNamed,
+    isCmpOpcode,
+    switchAllowsNeqCase,
+    emitsAnchoredWrite,
+    expr,
+    structureRegion,
+  } = deps;
 
   // --- Regime A: comparison-tree switch recovery ----------------------------------------------------
   // Every ambiguity declines. Four preconditions are enforced below, annotated PRE1..PRE4:
@@ -128,9 +159,9 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
     if (!cmp || !isCmpOpcode(cmp.opcode)) {
       return null;
     }
-    if (!isRoot && blk.ops.some((op) => SIDE_EFFECTFUL.has(op.opcode))) {
+    if (!isRoot && (blk.ops.some((op) => SIDE_EFFECTFUL.has(op.opcode)) || emitsAnchoredWrite(blk))) {
       return null;
-    } // PRE4
+    } // PRE4 — anchored writes included: discarded with the block, while their edge copies stay suppressed
     // Which operand is the scrutinee, which is the constant?
     const [lo, ro] = cmp.operands;
     const lc = evalConst(lo),
@@ -180,31 +211,83 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
     }
   };
 
-  // Can any case/default entry's region reach a SIBLING entry (switch fall-through)? Region =
-  // blocks strictly dominated by `b`, short of `merge`. Shared by Regime A (declines to
-  // if-recovery) and Regime B (throws — a jump-table has no fallback).
-  const caseRegionReachesSibling = (targets: Set<Block>, b: Block, merge: Block | null): boolean => {
-    const inRegion = (blk: Block) => blk !== merge && dom.get(blk)!.has(b);
-    for (const entry of targets) {
-      const rseen = new Set<Block>([entry]);
-      const q = [entry];
-      while (q.length) {
-        const cur = q.pop()!;
-        for (const s of successorsOf(cur)) {
-          if (s === entry) {
+  // Where does one arm's region LEAVE? Walk it from `entry`, never stepping THROUGH the merge or a
+  // sibling arm's entry, and classify what it steps INTO. `siblings` is every OTHER arm entry the
+  // caller can emit a `case`/`default` label for — the merge is deliberately not among them, so a
+  // switch whose default block IS the merge (agbcc's usual "the default just leaves") reads as an
+  // ordinary `break`, not as falling into the default.
+  //
+  // Region membership is `dom(blk) ∋ b` as before: a block NOT dominated by the switch is outside
+  // this switch's region and is not walked. It IS recorded as an escape, because an arm that can
+  // leave sideways does not fall into the next case — but only the fall-through verdict consults
+  // that, so no arm that used to be accepted as closed becomes a decline.
+  //
+  // A CONSEQUENCE, not a hole: a sibling reachable only THROUGH such a block is never seen, so the
+  // arm reads as closed and `structureRegion` walks into the sibling's blocks and emits them again
+  // under this arm. That is duplication, not a wrong dispatch — the same duplication the structurer
+  // already does for any tail two arms share, and how the case bodies agbcc tail-merged are put
+  // back. Costly for matching, correct to run.
+  const analyzeArmExit = (entry: Block, b: Block, merge: Block | null, siblings: Set<Block>): ArmExit => {
+    if (entry === merge) {
+      return { kind: 'break' }; // an empty arm (a table slot pointing straight at the switch's end)
+    }
+    const into = new Set<Block>(); // sibling entries this arm flows into
+    let toMerge = false,
+      escapes = false;
+    const seen = new Set<Block>([entry]);
+    const q = [entry];
+    while (q.length) {
+      const cur = q.pop()!;
+      for (const s of successorsOf(cur)) {
+        if (s === merge) {
+          toMerge = true;
+        } else if (s !== entry && siblings.has(s)) {
+          into.add(s);
+        } else if (s !== entry && !seen.has(s)) {
+          if (!dom.get(s)!.has(b)) {
+            escapes = true;
             continue;
           }
-          if (targets.has(s)) {
-            return true;
-          }
-          if (inRegion(s) && !rseen.has(s)) {
-            rseen.add(s);
-            q.push(s);
-          }
+          seen.add(s);
+          q.push(s);
         }
       }
     }
-    return false;
+    if (into.size === 0) {
+      return { kind: 'break' };
+    }
+    if (into.size === 1 && !toMerge && !escapes) {
+      return { kind: 'fallthrough', to: [...into][0] };
+    }
+    // Name what is actually missing. These three are different facts, and only the first is a shape
+    // C has no spelling for — the other two are asmlift's own limits, so say so rather than blame C.
+    const names = () => [...into].map((x) => `#${fn.blocks.indexOf(x)}`).join(', ');
+    if (into.size > 1) {
+      return {
+        kind: 'unstructurable',
+        why: `a case body reaches several sibling cases (${names()}) — C fall-through reaches only one, so this needs a goto`,
+      };
+    }
+    if (escapes) {
+      return {
+        kind: 'unstructurable',
+        why: `a case body reaches sibling case ${names()} on one path and, on another, a block the switch does not dominate`,
+      };
+    }
+    return {
+      kind: 'unstructurable',
+      // `case 0: if (c) { …; break; } /* fall through */ case 1:` is the C for this, and the reason
+      // asmlift cannot write it is its own: `{k:'break'}` is emitted only for the innermost LOOP
+      // (l3/ast.ts), never switch-scoped. That is the capability this shape is waiting on.
+      why: `a case body reaches sibling case ${names()} on one path and the end of the switch on another — a switch-scoped \`break\` inside a case body is not emitted yet`,
+    };
+  };
+
+  /** Every arm closed (`break`)? The precondition Regime A needs — it has a behaviourally identical
+   *  fallback (if-recovery), so it declines on anything else instead of recovering fall-through. */
+  const allArmsClosed = (targets: Set<Block>, b: Block, merge: Block | null): boolean => {
+    const siblings = new Set([...targets].filter((t) => t !== merge));
+    return [...siblings].every((t) => analyzeArmExit(t, b, merge, siblings).kind === 'break');
   };
 
   const recognizeSwitch = (b: Block, stop: Block | null): Stmt[] | null => {
@@ -367,11 +450,12 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
     }
 
     // PRE2 (fall-through): only NON-fall-through switches are handled — decline if any case body
-    // can reach ANOTHER case body (or the default) while staying inside the region. (The SAME
-    // predicate serves the Regime-B path, which throws instead.)
+    // can reach ANOTHER case body (or a default that has its own block) while staying inside the
+    // region. (The SAME analysis serves the Regime-B path, which RECOVERS the adjacent-sibling
+    // case as C fall-through instead of declining; A has if-recovery to fall back on, B does not.)
     const merge = ipdom.get(b) ?? stop;
     const targets = new Set<Block>([...caseBlocks, ...(defaultBlk ? [defaultBlk] : [])]);
-    if (caseRegionReachesSibling(targets, b, merge)) {
+    if (!allArmsClosed(targets, b, merge)) {
       return null;
     }
 
@@ -394,11 +478,14 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
       body: structureRegion(blk, merge),
       fallsThrough: false,
     }));
+    // An empty default arm is not a default (see the Regime-B note in structure.ts): the label
+    // would carry no statement, which says nothing and is not valid C89.
+    const defBody = defaultBlk ? structureRegion(defaultBlk, merge) : [];
     const sw: Stmt = {
       k: 'switch',
       scrutinee: scrutExpr,
       cases: outCases,
-      ...(defaultBlk ? { default: structureRegion(defaultBlk, merge) } : {}),
+      ...(defBody.length ? { default: defBody } : {}),
     };
     const out: Stmt[] = [sw];
     if (merge && merge !== stop) {
@@ -406,5 +493,5 @@ export function makeSwitchRecovery(deps: SwitchRecoverDeps): SwitchRecovery {
     }
     return out;
   };
-  return { recognizeSwitch, caseRegionReachesSibling };
+  return { recognizeSwitch, analyzeArmExit };
 }

package/src/symbols.ts

@@ -52,6 +52,17 @@ export interface SymbolStructField {
   /** ARRAY field only: the element count (absent for a flexible array member, which declares a
    *  stride but no bound) — types the synthesized `T name[n];` field decl */
   length?: number;
+  /** BITFIELD field only: the field's width in BITS. Its PRESENCE is what marks a field a
+   *  bitfield — `size` above stays the byte span its bits touch (the read width the compiler
+   *  uses), which is why the exact (offset,size) scalar-field rules must exclude it. The
+   *  provider only emits these for LITTLE-ENDIAN ELFs: both the extract equation the access
+   *  recognizer solves and the `u32 name : n` layout model the synthesis verifies are LE-GCC
+   *  semantics, so a big-endian map carries no bitfield members at all (today's behavior). */
+  bitWidth?: number;
+  /** BITFIELD field only: the bit position of the field's LOW bit within the byte at `offset`
+   *  (LSB-first) — the field's absolute low bit is `offset*8 + bitOffset`. Required alongside
+   *  `bitWidth`; a bitfield missing it is malformed and declines the whole layout. */
+  bitOffset?: number;
 }
 
 /** What a `shape:'pointer'` global POINTS AT, when the sidecar says its target is a struct/union.
@@ -118,6 +129,15 @@ export interface SymbolInfo {
   elemSize?: number;
   /** element signedness for `shape:'array'` (default unsigned) — types the env entry */
   elemSigned?: boolean;
+  /** ARRAY RANK for `shape:'array'` — the per-dimension extents, outermost first (`u16
+   *  g[4][0x400]` → `[4, 1024]`), `null` for an unbounded one. It is NOT `size`/`elemSize`
+   *  restated: those size the object, this says how many subscripts reach an ELEMENT. `gSym[i]`
+   *  on a rank-2 array is a ROW — against the project's own header that is a type error, or,
+   *  where the row address flows into an integer context, silently the wrong address. So the
+   *  bare spelling needs the leading subscripts (`gSym[0][i]`), and its ABSENCE is what forbids
+   *  the bare spelling from being attempted at all (see the provider's dims capability gate:
+   *  a package that cannot report rank must not be read as "rank 1"). */
+  dims?: (number | null)[];
   /** the real struct tag for `shape:'struct'` — names the synthesized struct declaration
    *  (absent ⇒ synthesis mints a placeholder tag; the tag is codegen-arbitrary) */
   structName?: string;
@@ -145,6 +165,33 @@ export interface SymbolInfo {
   macroBody?: string;
 }
 
+/** THE one reading of {@link SymbolInfo.dims} for spelling C, shared by the access side
+ *  (structure.ts's bare-name gate) and the declaration side (declare.ts) so the two cannot
+ *  disagree about an array's shape.
+ *
+ *  Returns the INNER extents — every dimension but the outermost. The outermost is excluded
+ *  because C lets a declaration omit it, and the inner ones are exactly what scales a leading
+ *  subscript. `[]` is the rank-1 answer: one subscript, `extern T gSym[];`, the spelling this has
+ *  always had.
+ *
+ *  An ABSENT `dims` also reads as rank 1, because that is what the author of such a map said: the
+ *  ELF provider's capability gate refuses a @gba-kit/debug-info that cannot report rank, so
+ *  absence here can only come from a hand-written map whose `shape:'array'` states a plain array.
+ *  Absence never means "the package could not say" — that case fails loudly at load.
+ *
+ *  Null means NO consistent pair is available (a stated rank with an unknown inner extent, which
+ *  neither a declaration nor a subscript can spell). Both sides honour it the same way: the access
+ *  falls back to `((T *)&gSym)[i]`, the declaration to the flat `extern T gSym[];` — valid
+ *  together under whatever the project's own header says. */
+export function arrayInnerExtents(info: SymbolInfo): number[] | null {
+  const dims = info.shape === 'array' ? info.dims : undefined;
+  if (dims === undefined || dims.length <= 1) {
+    return [];
+  }
+  const inner = dims.slice(1);
+  return inner.every((d) => typeof d === 'number' && d > 0) ? (inner as number[]) : null;
+}
+
 /** address → symbols at that address; `[0]` is the provider's canonical pick. */
 export type SymbolMap = Map<number, SymbolInfo[]>;
 
@@ -155,6 +202,13 @@ export function isArrayField(f: SymbolStructField): boolean {
   return f.elemSize !== undefined;
 }
 
+/** THE one test for "is this field a bitfield" — the PRESENCE of `bitWidth` (see the field doc).
+ *  The exact (offset,size) scalar-field rules must exclude these: a 7-bit field whose bits span
+ *  2 bytes carries `size: 2` and would otherwise match a plain u16 read at its offset. */
+export function isBitfieldField(f: SymbolStructField): boolean {
+  return f.bitWidth !== undefined;
+}
+
 /** A layout member that {@link declaredFields} passed: sizable, and seated at an offset no
  *  earlier member already covers. */
 export type DeclaredField = SymbolStructField & { size: number };
@@ -166,12 +220,30 @@ function wellFormedField(f: unknown): f is SymbolStructField {
     return false;
   }
   const m = f as Partial<SymbolStructField>;
-  return (
-    typeof m.name === 'string' &&
-    typeof m.offset === 'number' &&
-    Number.isFinite(m.offset) &&
-    (m.size === null || (typeof m.size === 'number' && Number.isFinite(m.size) && m.size >= 0))
-  );
+  if (
+    typeof m.name !== 'string' ||
+    typeof m.offset !== 'number' ||
+    !Number.isFinite(m.offset) ||
+    !(m.size === null || (typeof m.size === 'number' && Number.isFinite(m.size) && m.size >= 0))
+  ) {
+    return false;
+  }
+  // A bitfield's two facts must be present TOGETHER and internally consistent — a bitWidth with
+  // no bitOffset (or bits outside the byte span `size` claims) leaves the field unseatable, so
+  // the member is malformed and the layout declines whole like any other malformed member.
+  if (m.bitWidth !== undefined) {
+    return (
+      typeof m.bitWidth === 'number' &&
+      Number.isInteger(m.bitWidth) &&
+      m.bitWidth > 0 &&
+      typeof m.bitOffset === 'number' &&
+      Number.isInteger(m.bitOffset) &&
+      m.bitOffset >= 0 &&
+      typeof m.size === 'number' &&
+      m.bitOffset + m.bitWidth <= m.size * 8
+    );
+  }
+  return true;
 }
 
 /**
@@ -202,15 +274,33 @@ export function declaredFields(layout: SymbolStructField[] | undefined): Declare
       return null;
     }
   }
-  const members = (layout as DeclaredField[]).slice().sort((a, b) => a.offset - b.offset);
+  // The cursor is in BITS so co-located bitfields seat correctly: `u32 a:2; u32 b:3;` are two
+  // members at byte offset 0, not a union alias. For plain members the arithmetic is the old
+  // byte cursor times 8 — behavior-identical for every bitfield-free layout.
+  const lowBitOf = (m: DeclaredField): number => m.offset * 8 + (m.bitWidth !== undefined ? m.bitOffset! : 0);
+  const members = (layout as DeclaredField[])
+    .slice()
+    .sort((a, b) => lowBitOf(a) - lowBitOf(b) || (a.bitWidth ?? -1) - (b.bitWidth ?? -1));
   const out: DeclaredField[] = [];
-  let cursor = 0;
+  let bitCursor = 0;
   for (const m of members) {
-    if (m.offset < cursor) {
+    const lo = lowBitOf(m);
+    if (lo < bitCursor) {
       continue; // an overlapping (union) member: the first view is declared, the alias is not
     }
-    out.push(m);
-    cursor = m.offset + m.size;
+    if (m.bitWidth !== undefined) {
+      // The synthesis lays bitfields as LE-GCC `u32 name : n`, whose allocation never straddles
+      // a 32-bit unit — a field that would cannot be reproduced, so it is not declared (its bits
+      // pad instead) and no access may name it. The cursor does NOT advance: the bits stay a hole.
+      if (Math.floor(lo / 32) !== Math.floor((lo + m.bitWidth - 1) / 32)) {
+        continue;
+      }
+      out.push(m);
+      bitCursor = lo + m.bitWidth;
+    } else {
+      out.push(m);
+      bitCursor = (m.offset + m.size) * 8;
+    }
   }
   return out;
 }
@@ -247,14 +337,39 @@ export function symbolFieldType(f: DeclaredField): IrType {
     const scalarPointee = f.pointeeSize === 1 || f.pointeeSize === 2 || f.pointeeSize === 4;
     return T.ptr(scalarPointee ? T.int(f.pointeeSize! * 8, f.pointeeSigned ?? false) : T.void());
   }
-  if (f.size === 1 || f.size === 2 || f.size === 4) {
-    return T.int(f.size * 8, f.signed ?? (f.size === 4 ? ENUM_IS_SIGNED : false));
+  if (isBitfieldField(f)) {
+    // The BASE type of the synthesized `u32 name : n` — the `: n` itself is the declaration
+    // renderer's job (StructFieldDecl.bits). 32-bit base always: that is the LE-GCC unit model
+    // declaredFields verified the layout against. A signless bitfield declares unsigned — the
+    // extract recognizer refuses to NAME one anyway, so the choice only types padding.
+    return T.int(32, f.signed ?? false);
+  }
+  if (isScalarCellSize(f.size)) {
+    return scalarCellType(f.size, f.signed);
   }
   return T.array(T.u(8), f.size);
 }
 /** A 4-byte member/scalar with NO base-type signedness is the enum idiom — C89 says int. */
 export const ENUM_IS_SIGNED = true;
 
+/** Is this byte size one a base type can spell? */
+export function isScalarCellSize(size: number | undefined): size is 1 | 2 | 4 {
+  return size === 1 || size === 2 || size === 4;
+}
+
+/** THE DECLARED type of a 1/2/4-byte scalar cell — what `extern T gSym;` synthesis writes, and
+ *  therefore what `&gSym` actually points to.
+ *
+ *  Extracted because this rule had drifted into a fourth copy. It is NOT `scalarTypeForAccess`,
+ *  which answers a different question — the type an ACCESS of that width reads — and collapses
+ *  every 4-byte access to `s32` whatever the signedness. Using that one to decide "does `&gSym`
+ *  already have the destination's type" silently answered YES for a `u32` cell reaching an
+ *  `s32 *`, and the incompatible-pointer assignment survived. Declaration side and access side are
+ *  separate facts; this is the declaration one. */
+export function scalarCellType(size: 1 | 2 | 4, signed: boolean | undefined): IrType {
+  return T.int(size * 8, signed ?? (size === 4 ? ENUM_IS_SIGNED : false));
+}
+
 /**
  * THE gate on every spelling through a POINTER global's value: the members a `gPtr->member`
  * spelling may name, or null when nothing may be named through this pointee at all. Null unless

package/src/target.ts

@@ -34,7 +34,7 @@ export interface TargetDescription {
   returnReg: string;
   // HARDWARE / ISA facts — independent of the compiler.
   capabilities: {
-    endianness: 'little' | 'big'; // RESERVED — no pass reads it yet (byte-addressing will)
+    endianness: 'little' | 'big'; // consumed by structureOptionsFor (bitfield extract recognition is LSB-first)
     hwDivide: boolean; // consumed by patternApplies (idiom gating)
     hwFloat: boolean; // consumed by patternApplies (idiom gating)
     flags: boolean; // RESERVED — no pass reads it yet (PPC condition regs will)
@@ -132,7 +132,9 @@ export const PPC_MWCC: TargetDescription = {
  *  target's compiler behaviors flow into the target-agnostic structurer — a new behavior lever
  *  is a field in `compilerBehaviors`, consumed automatically. */
 export function structureOptionsFor(t: TargetDescription, returnsVoid: boolean): StructureOptions {
-  return { returnsVoid, ...t.compilerBehaviors };
+  // `littleEndian` is the one HARDWARE capability the structurer consumes (bitfield extract
+  // recognition is LSB-first); everything else is a compiler behavior.
+  return { returnsVoid, littleEndian: t.capabilities.endianness === 'little', ...t.compilerBehaviors };
 }
 
 export const C_TYPEDEFS =

package/src/trace.ts

@@ -72,12 +72,21 @@ export interface TraceOptions {
 // (not in pre-recovery.ts) because these strings are a trace concern — the driver itself is
 // trace-agnostic. `title` is a function so `arrays` can fold its scaled-access count in.
 const PRE_RECOVERY_TRACE: Record<string, { stage: string; title: (result: number | boolean) => string }> = {
+  addrnum: {
+    stage: 'stage:addrnum',
+    title: (r) => `Address numbering (${r} duplicate address def(s) / trivial phi(s) collapsed)`,
+  },
   const: { stage: 'stage:const', title: () => 'Const materialize (lui;ori → one 32-bit const)' },
   magicdiv: { stage: 'stage:magicdiv', title: () => 'Magic-number division recovery (mulh/mulhu → sdiv/udiv)' },
   softdiv: { stage: 'stage:softdiv', title: () => 'Soft-division lower (bl __divsi3 → division op)' },
   arrays: { stage: 'stage:legalize', title: (r) => `Array legalize (${r} scaled access(es) → aload/astore)` },
   structs: { stage: 'stage:structs', title: () => 'Struct-pointer recovery (access-pattern evidence)' },
   shortcircuit: { stage: 'stage:shortcircuit', title: () => 'Short-circuit recovery (boolean && / ||)' },
+  'branch-shortcircuit': {
+    stage: 'stage:branch-shortcircuit',
+    title: () => 'Short-circuit recovery (control-flow && / ||)',
+  },
+  'struct-arrays': { stage: 'stage:struct-arrays', title: () => 'Struct-array recovery (element stride evidence)' },
 };
 
 /** Run the tower while recording a TraceReport. Strict mode throws on any gap (like decompile);