@asmlift/core 0.1.0

package/src/frontend/asmdata.ts

@@ -0,0 +1,170 @@
+// asmlift — the AsmData side-table. MIPS/PPC frontends parse
+// `objdump -d` (`.text` only), so a dense-switch's case→target jump table — which lives in a DATA
+// section (`.rodata`/`.data`/`.sdata2`) as bytes + relocations — never reaches them. This module is
+// an ISA-agnostic bag of `{ section bytes, relocations, symbols }` extracted from a companion
+// `objdump -s`/`-r`/`-t` pass on the SAME object, threaded as an OPTIONAL `lift()` parameter.
+// Absent ⇒ the frontends decline; only Regime-B recovery reads it. Reloc *interpretation* (MIPS
+// gp-relative vs PPC named-symbol) stays per-frontend — this layer is pure parse + a fail-closed
+// table reader.
+//
+// Empirically grounded against the three
+// toolchains: IDO stores `.text` offsets in `.rodata` with `R_MIPS_GPREL32 .text` relocs; KMC gcc
+// stores them in `.rodata` with `R_MIPS_32 .text`; mwcc stores ZERO bytes in `.data` and carries
+// the whole map in `R_PPC_ADDR32 <fn>+<off>` relocs. All three reduce to: target .text offset =
+// symbolBase(reloc.sym) + reloc.addend + inlineWord — the reader below.
+
+/** One relocation record (from `objdump -r`). `sym` is the target symbol (a section symbol like
+ *  `.text`/`.rodata`, an object symbol like `@15`, or a function symbol like `sw_jt`); `addend` is the
+ *  RELA addend (0 for REL relocs, whose addend lives inline in the section bytes). */
+export interface Reloc {
+  section: string;
+  offset: number;
+  type: string;
+  sym: string;
+  addend: number;
+}
+
+/** A parsed object's data sections + relocations + symbol offsets. Big-endian for MIPS-N64 / PPC (the
+ *  only Regime-B consumers today); `bigEndian` records it so the word reader is not ISA-hardcoded. */
+export interface AsmData {
+  sections: Map<string, Uint8Array>; // section name → raw bytes (file order)
+  relocs: Reloc[];
+  symbols: Map<string, { section: string; value: number }>; // symbol name → {section, offset-in-section}
+  bigEndian: boolean;
+}
+
+const readU32 = (b: Uint8Array, off: number, big: boolean): number =>
+  big
+    ? ((b[off] << 24) | (b[off + 1] << 16) | (b[off + 2] << 8) | b[off + 3]) >>> 0
+    : ((b[off + 3] << 24) | (b[off + 2] << 16) | (b[off + 1] << 8) | b[off]) >>> 0;
+
+// Parse an `objdump -r` VALUE field: `sw_jt+0x00000020` / `.text` / `@15` → {sym, addend}.
+function parseRelocValue(v: string): { sym: string; addend: number } {
+  const plus = v.indexOf('+');
+  if (plus < 0) {
+    return { sym: v, addend: 0 };
+  }
+  const a = v.slice(plus + 1).trim();
+  return { sym: v.slice(0, plus), addend: parseInt(a, /^0x/i.test(a) ? 16 : 10) >>> 0 };
+}
+
+/** Parse the three companion objdump dumps into an `AsmData`. Pure (no shell) so it is unit-testable
+ *  against captured output; the callers (cli score.ts, benchmark cache.ts) supply the strings. */
+export function parseAsmData(
+  sectionsDump: string,
+  relocsDump: string,
+  symbolsDump: string,
+  bigEndian: boolean,
+): AsmData {
+  // --- `objdump -s`: `Contents of section .rodata:` then ` 0000 00000034 0000003c …  ascii` ---
+  const sections = new Map<string, Uint8Array>();
+  let curSec: string | null = null;
+  let bytes: number[] = [];
+  const flush = () => {
+    if (curSec) {
+      sections.set(curSec, Uint8Array.from(bytes));
+    }
+    curSec = null;
+    bytes = [];
+  };
+  for (const line of sectionsDump.split('\n')) {
+    const hdr = line.match(/^Contents of section (\S+):/);
+    if (hdr) {
+      flush();
+      curSec = hdr[1];
+      continue;
+    }
+    if (!curSec) {
+      continue;
+    }
+    // ` 0000 00000034 0000003c 00000044 0000004c  ...4...<...D...L` — hex columns end at the 2-space
+    // gap before the ascii gutter; take everything between the offset and that gap.
+    const m = line.match(/^\s*[0-9a-f]+\s+([0-9a-f ]+?)\s{2,}/i);
+    if (!m) {
+      continue;
+    }
+    for (const grp of m[1].trim().split(/\s+/)) {
+      for (let i = 0; i + 1 < grp.length; i += 2) {
+        bytes.push(parseInt(grp.slice(i, i + 2), 16));
+      }
+    }
+  }
+  flush();
+
+  // --- `objdump -r`: `RELOCATION RECORDS FOR [.text]:` then `OFFSET TYPE VALUE` rows ---
+  const relocs: Reloc[] = [];
+  let relSec: string | null = null;
+  for (const line of relocsDump.split('\n')) {
+    const hdr = line.match(/^RELOCATION RECORDS FOR \[(\S+)\]:/);
+    if (hdr) {
+      relSec = hdr[1];
+      continue;
+    }
+    if (!relSec) {
+      continue;
+    }
+    const m = line.match(/^([0-9a-f]+)\s+(R_\S+)\s+(\S+)/i);
+    if (!m) {
+      continue;
+    }
+    const { sym, addend } = parseRelocValue(m[3]);
+    relocs.push({ section: relSec, offset: parseInt(m[1], 16), type: m[2], sym, addend });
+  }
+
+  // --- `objdump -t`: `VALUE FLAGS SECTION\tSIZE NAME` (section/size split by TAB) ---
+  const symbols = new Map<string, { section: string; value: number }>();
+  for (const line of symbolsDump.split('\n')) {
+    const tab = line.indexOf('\t');
+    if (tab < 0) {
+      continue;
+    }
+    const left = line.slice(0, tab),
+      right = line.slice(tab + 1);
+    const lm = left.match(/^([0-9a-f]+)\s+.{6,8}\s(\S+)\s*$/i); // value … flags(7) section
+    const rm = right.match(/^[0-9a-f]+\s+(.+?)\s*$/i); // size name
+    if (!lm || !rm) {
+      continue;
+    }
+    symbols.set(rm[1], { section: lm[2], value: parseInt(lm[1], 16) });
+  }
+
+  return { sections, relocs, symbols, bigEndian };
+}
+
+/** Read a dense jump table's N target `.text` byte-offsets, or `null` if ANYTHING doesn't resolve
+ *  cleanly (fail-closed — a partial/ambiguous table declines, never a wrong switch).
+ *
+ *  `tableSym`/`tableAddend` locate the table (from the dispatch's `.text` reloc: MIPS `GOT16`/`HI16`/
+ *  `LO16 .rodata`; PPC `ADDR16_HA/LO @tbl`). Each entry resolves to a `.text` offset via
+ *  `symbolBase(entryReloc.sym) + entryReloc.addend + inlineWord`, and MUST target `.text`. */
+export function readJumpTable(ad: AsmData, tableSym: string, tableAddend: number, n: number): number[] | null {
+  if (n < 2) {
+    return null;
+  }
+  const tsym = ad.symbols.get(tableSym);
+  const section = tsym ? tsym.section : tableSym; // ".rodata" is its own section symbol
+  const baseOff = (tsym ? tsym.value : 0) + tableAddend;
+  const secBytes = ad.sections.get(section);
+  const out: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const slot = baseOff + i * 4;
+    const r = ad.relocs.find((x) => x.section === section && x.offset === slot);
+    if (!r) {
+      return null;
+    } // every entry must be a relocated pointer
+    const rsym = ad.symbols.get(r.sym);
+    const rsec = rsym ? rsym.section : r.sym; // ".text" section symbol → ".text"
+    if (rsec !== '.text') {
+      return null;
+    } // only .text-directed entries are valid
+    const inline = secBytes && slot + 4 <= secBytes.length ? readU32(secBytes, slot, ad.bigEndian) : 0;
+    out.push(((rsym ? rsym.value : 0) + r.addend + inline) >>> 0);
+  }
+  return out;
+}
+
+/** The single `.text` relocation whose *instruction* address is `insnAddr` (a table-base HI/LO/GOT16
+ *  or ADDR16 reloc), or `null`. Used by a frontend to find where its dispatch's table lives. */
+export function textRelocAt(ad: AsmData, insnAddr: number): Reloc | null {
+  return ad.relocs.find((r) => r.section === '.text' && r.offset === insnAddr) ?? null;
+}

package/src/frontend/disasm.ts

@@ -0,0 +1,102 @@
+// asmlift — shared objdump-text scaffolding for the MIPS and PPC frontends. The Thumb frontend
+// parses GNU-as text, not objdump, so it does not route through here.
+import { FrontendUnsupportedError } from './errors';
+
+/** Slice a multi-symbol objdump listing down to ONE function's lines. objdump marks each
+ *  function with an `ADDR <sym>:` header line; when headers are present the input is sliced to
+ *  exactly the requested symbol — and an ABSENT symbol declines LOUD, because emitting some
+ *  other function's body under the requested name is precisely the silent miscompile the
+ *  cardinal rule forbids. Headerless input (a raw instruction fragment) passes through. */
+export function sliceSymbol(disasm: string, symbol: string): string {
+  const lines = disasm.split('\n');
+  const headers: { line: number; sym: string }[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^[0-9a-f]+\s+<([^>]+)>:\s*$/i);
+    if (m) {
+      headers.push({ line: i, sym: m[1] });
+    }
+  }
+  if (headers.length === 0) {
+    return disasm;
+  }
+  const at = headers.findIndex((h) => h.sym === symbol);
+  if (at === -1) {
+    throw new FrontendUnsupportedError(
+      `symbol '${symbol}' not found in the disassembly (symbols present: ${headers.map((h) => h.sym).join(', ')})`,
+    );
+  }
+  const end = at + 1 < headers.length ? headers[at + 1].line : lines.length;
+  return lines.slice(headers[at].line, end).join('\n');
+}
+
+/** One disassembled instruction. `target` is a decoded branch-target address (objdump prints the
+ *  target as `10 <sym+0x10>` in the last operand); `sym` is a relocation-attached callee symbol
+ *  (PPC `-r` output), absent otherwise. */
+export interface DisasmInstr {
+  addr: number;
+  mnemonic: string;
+  ops: string[];
+  target?: number;
+  sym?: string;
+}
+
+export interface DisasmOptions {
+  /** Attach relocation lines (`ADDR: R_* <sym>[+addend]`) to the PRECEDING instruction — the
+   *  callee symbol for a `bl` whose encoded offset is a 0 placeholder (PPC `-r` output). Tested
+   *  BEFORE the instruction regex, which would otherwise mis-read `R_PPC_…` as a mnemonic. */
+  relocs?: boolean;
+  /** Strip branch-prediction hint suffixes glued onto the mnemonic (`blt-`, `bge+`, `bgelr-`).
+   *  The suffix is a prediction hint, not a different instruction — without stripping, the
+   *  mnemonic misses the cond tables and the branch is silently dropped. */
+  hintSuffixes?: boolean;
+}
+
+/** Parse objdump `-d --no-show-raw-insn` output into a flat instruction list with addresses. */
+export function parseDisasm(disasm: string, opts: DisasmOptions = {}): DisasmInstr[] {
+  const out: DisasmInstr[] = [];
+  for (const raw of disasm.split('\n')) {
+    if (opts.relocs) {
+      const rel = raw.match(/^\s+[0-9a-f]+:\s+R_\w+\s+(\S+)/i);
+      if (rel) {
+        if (out.length) {
+          out[out.length - 1].sym = rel[1].split('+')[0];
+        }
+        continue;
+      }
+    }
+    const m = opts.hintSuffixes
+      ? raw.match(/^\s*([0-9a-f]+):\s+([a-z][a-z0-9._]*)([-+]?)\s*(.*?)\s*$/i)
+      : raw.match(/^\s*([0-9a-f]+):\s+([a-z][a-z0-9._]*)\s*(.*?)\s*$/i);
+    if (!m) {
+      continue;
+    }
+    const addr = parseInt(m[1], 16);
+    const mnemonic = m[2]; // hint suffix (group 3), when parsed, is dropped
+    const opsStr = opts.hintSuffixes ? m[4] : m[3];
+    const ops = opsStr
+      ? opsStr
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+    let target: number | undefined;
+    const tm = ops.length ? ops[ops.length - 1].match(/^([0-9a-f]+)\s+</i) : null;
+    if (tm) {
+      target = parseInt(tm[1], 16);
+    }
+    out.push({ addr, mnemonic, ops, target });
+  }
+  return out;
+}
+
+/** An objdump immediate: decimal or hex (objdump prints hex as 0x…, negatives as -N). */
+export const parseImm = (s: string): number => parseInt(s, /^-?0x/i.test(s) ? 16 : 10);
+
+/** A memory operand `off(base)` (e.g. `8(a0)`, `-4(r1)`) → constant byte offset + base register.
+ *  `baseRe` narrows what counts as a base (PPC: `r\d+` — a non-register base is an SDA/global
+ *  placeholder the caller must decline). A non-matching operand falls back to offset 0 with the
+ *  parens stripped. */
+export function parseMem(operand: string, baseRe: RegExp = /\w+/): { off: number; base: string } {
+  const m = operand.match(new RegExp(`^(-?(?:0x)?[0-9a-f]+)\\((${baseRe.source})\\)$`, 'i'));
+  return m ? { off: parseImm(m[1]), base: m[2] } : { off: 0, base: operand.replace(/[()]/g, '') };
+}

package/src/frontend/emit.ts

@@ -0,0 +1,57 @@
+// asmlift — the shared per-block IR emitter kit for the MIPS and PPC decode loops. Bound per
+// block (the `ops` array and `write` are block-scoped); the ISA-specific readers/guards
+// (sp-as-data, frame transparency) stay in the frontends.
+import { Op, Successor, Value, mkOp, mkValue } from '../ir/core';
+import type { Opcode } from '../ir/opcodes';
+import { T } from '../ir/types';
+
+export interface EmitKit {
+  /** a fresh `const` value */
+  cnst: (n: number) => Value;
+  /** emit `opc` over operands into register `d`; returns the result value */
+  emit: (opc: Opcode, d: string, operands: Value[], attrs?: Record<string, number | boolean | string>) => Value;
+  bin: (opc: Opcode, d: string, x: Value, y: Value) => Value;
+  un: (opc: Opcode, d: string, x: Value) => Value;
+  shImm: (opc: Opcode, d: string, x: Value, imm: number) => Value;
+  /** emit `opc` into an unwritten temporary (a value feeding a following op, not a register dest) */
+  tmp: (opc: Opcode, operands: Value[], attrs?: Record<string, number | boolean | string>) => Value;
+}
+
+export function mkEmitKit(ops: Op[], write: (reg: string, v: Value) => void): EmitKit {
+  const tmp = (opc: Opcode, operands: Value[], attrs?: Record<string, number | boolean | string>): Value => {
+    const v = mkValue(T.unk(32));
+    ops.push(mkOp(opc, { operands, results: [v], ...(attrs ? { attrs } : {}) }));
+    return v;
+  };
+  const emit = (
+    opc: Opcode,
+    d: string,
+    operands: Value[],
+    attrs?: Record<string, number | boolean | string>,
+  ): Value => {
+    const res = tmp(opc, operands, attrs);
+    write(d, res);
+    return res;
+  };
+  return {
+    tmp,
+    emit,
+    cnst: (n) => tmp('const', [], { value: n }),
+    bin: (opc, d, x, y) => emit(opc, d, [x, y]),
+    un: (opc, d, x) => emit(opc, d, [x]),
+    shImm: (opc, d, x, imm) => emit(opc, d, [x], { imm }),
+  };
+}
+
+/** Emit a recovered jump-table dispatch: N case successors followed by the default (LAST), with
+ *  the dense 0..N-1 `cases` list derived here — the single home of the case/successor
+ *  alignment invariant. */
+export function pushSwitchBr(ops: Op[], scrut: Value, successors: Successor[]): void {
+  ops.push(
+    mkOp('switch_br', {
+      operands: [scrut],
+      successors,
+      attrs: { cases: successors.slice(0, -1).map((_, k) => k) },
+    }),
+  );
+}

package/src/frontend/errors.ts

@@ -0,0 +1,14 @@
+// asmlift — the shared DESIGNED loud-failure signal for ISA frontends. A frontend throws this when
+// it meets a construct it cannot faithfully model (an out-of-scope call, an indirect/tail transfer,
+// a stack frame it can't abstract) — the "fail LOUD, never silently miscompile" contract for cases
+// the `opaque`-destination path cannot reach: an instruction whose clobbered register is IMPLICIT
+// (a call's return reg) or a control transfer with no data destination at all. Distinct from a
+// runtime crash (TypeError/RangeError): this is a catchable, intentional "out of scope" boundary
+// signal. `PpcUnsupportedError` subclasses it (annotate-mode classification and the loud-error
+// tests use `instanceof` against this base).
+export class FrontendUnsupportedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FrontendUnsupportedError';
+  }
+}

package/src/frontend/format.ts

@@ -0,0 +1,47 @@
+// asmlift — input-text format classification. Each target's ecosystem produces a different
+// textual artifact (agbcc emits GNU-as `.s`; IDO/mwcc emit no asm text, so their input is
+// `objdump -d` output), and each frontend reads exactly one of them. Feeding the wrong one
+// would otherwise fail confusingly deep in decode (an objdump header parsed as an instruction,
+// or a crash on an empty CFG) — this module makes the mismatch a boundary decline instead.
+//
+// Classification is CONSERVATIVE: it only names a format on a positive signal, and a frontend
+// only declines on a positive MISMATCH. Text with no recognizable signals (a bare fragment of
+// hand-written instructions) stays "unknown" and flows through to the frontend — the
+// decode-level loud-fail nets still own that case.
+import { FrontendUnsupportedError } from './errors';
+
+export type AsmTextFormat = 'objdump' | 'gnu-as';
+
+const FORMAT_LABEL: Record<AsmTextFormat, string> = {
+  objdump: 'objdump disassembly (`objdump -d --no-show-raw-insn` output)',
+  'gnu-as': 'GNU-as assembly text (compiler-emitted `.s`)',
+};
+
+// objdump output: `ADDR <sym>:` section headers, address-prefixed instruction lines, or the
+// `file format` banner. GNU-as text: assembler directives (`.text`, `.globl`, `.thumb_func`…).
+const OBJDUMP_SIGNAL = /^[0-9a-f]{2,} <[^>]+>:|^\s+[0-9a-f]+:\t|file format /im;
+const GNU_AS_SIGNAL =
+  /^\s*\.(text|code|align|globl|global|thumb_func|section|syntax|arch|cpu|set|ent|type|size|file)\b/im;
+
+/** Classify assembly TEXT by positive signals; "unknown" when neither (or both) match. */
+export function classifyAsmText(text: string): AsmTextFormat | 'unknown' {
+  const objdump = OBJDUMP_SIGNAL.test(text);
+  const gnuAs = GNU_AS_SIGNAL.test(text);
+  if (objdump === gnuAs) {
+    return 'unknown';
+  } // neither, or contradictory signals
+  return objdump ? 'objdump' : 'gnu-as';
+}
+
+/** Decline loudly when the input positively classifies as a format this frontend does not
+ *  read. Called at the top of every frontend's lift. */
+export function assertInputFormat(frontendId: string, expected: AsmTextFormat, asm: string): void {
+  const got = classifyAsmText(asm);
+  if (got === 'unknown' || got === expected) {
+    return;
+  }
+  throw new FrontendUnsupportedError(
+    `cannot lift: input looks like ${FORMAT_LABEL[got]}, but the '${frontendId}' frontend reads ` +
+      `${FORMAT_LABEL[expected]} — MIPS/PPC targets take objdump output; the ARM/agbcc target takes agbcc .s text`,
+  );
+}

package/src/frontend/frontend.ts

@@ -0,0 +1,22 @@
+// asmlift — the ISA-frontend seam. A Frontend turns one function's assembly text into an L1
+// Fn (block-argument SSA); everything downstream (recover, structure, backends) is ISA-
+// neutral and consumes the Fn without knowing which frontend produced it. See registry.ts
+// for target→frontend dispatch.
+import type { Fn } from '../ir/core';
+import type { Prototypes } from '../proto';
+import type { TargetDescription } from '../target';
+import type { AsmData } from './asmdata';
+import type { AsmTextFormat } from './format';
+
+export interface Frontend {
+  /** stable id, e.g. "thumb", "mips" — for diagnostics/reporting, not dispatch */
+  id: string;
+  /** the one input-text format this frontend reads; a positive mismatch declines at the
+   *  lift boundary (format.ts) instead of failing confusingly deep in decode */
+  inputFormat: AsmTextFormat;
+  /** decode one function's assembly into an L1 Fn. `prototypes` supplies callee arities
+   *  (and any other header facts the frontend needs); an empty map is valid. `asmData` is the
+   *  OPTIONAL Regime-B side-table (data-section jump tables + relocations); absent ⇒ a
+   *  dense-switch dispatch declines/loud-fails. */
+  lift(name: string, asm: string, target: TargetDescription, prototypes: Prototypes, asmData?: AsmData): Fn;
+}