@asmlift/core 0.7.0 → 0.8.0

package/src/frontend/disasm.ts

@@ -2,6 +2,29 @@
 // parses GNU-as text, not objdump, so it does not route through here.
 import { FrontendUnsupportedError } from './errors';
 
+/** The objdump function-header line, exported through the two readers below so that nothing can
+ *  disagree about where a function starts. GREEDY to the LAST `>`: a C++ template symbol contains
+ *  `>` of its own (`invoke__Q23zen20NumberPicCallBack<i>FP7P2DPane`), and a header a pattern cannot
+ *  see is worse than one it misreads — the PRECEDING function's slice runs on through it, and the
+ *  prologue split swallows it. */
+const HEADER_LINE = /^([0-9a-f]+)\s+<(.+)>:\s*$/i;
+const HEADER_SEARCH = new RegExp(HEADER_LINE.source, 'im');
+
+/** Character offset of the FIRST function header in an objdump listing, or -1 — everything before
+ *  it is the listing's own prologue (`target.o: file format …`, section headings). */
+export function firstFunctionHeader(disasm: string): number {
+  return disasm.search(HEADER_SEARCH);
+}
+
+/** The ADDRESS the first function header gives, or undefined for headerless input (a raw
+ *  instruction fragment, which says where it starts only by its first line). It is the one thing
+ *  that tells a word with nothing before it apart from a word the listing does not spell, and
+ *  those two have opposite answers wherever what precedes a word decides how it may be read. */
+export function symbolStart(disasm: string): number | undefined {
+  const m = disasm.match(HEADER_SEARCH);
+  return m ? parseInt(m[1], 16) : undefined;
+}
+
 /** 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
@@ -11,9 +34,9 @@ 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);
+    const m = lines[i].match(HEADER_LINE);
     if (m) {
-      headers.push({ line: i, sym: m[1] });
+      headers.push({ line: i, sym: m[2] });
     }
   }
   if (headers.length === 0) {
@@ -29,38 +52,136 @@ export function sliceSymbol(disasm: string, symbol: string): string {
   return lines.slice(headers[at].line, end).join('\n');
 }
 
+/** A relocation objdump printed (with `-r`) under the instruction whose operand field it fills.
+ *  All three fields carry meaning the rest of the listing does not:
+ *  the TYPE says WHICH field — an `@ha` immediate half (`R_PPC_ADDR16_HA`), an `@l` half
+ *  (`R_PPC_ADDR16_LO`), a small-data memory base (`R_PPC_EMB_SDA21`), a call target
+ *  (`R_PPC_REL24`) — and the mnemonic cannot stand in for it; the ADDEND is part of the address,
+ *  so `SYM` and `SYM+0x4` are different words; the SYMBOL is the name. */
+export interface DisasmReloc {
+  type: string;
+  sym: string;
+  addend: number;
+}
+
 /** 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. */
+ *  target as `10 <sym+0x10>` in the last operand); `reloc` is the relocation objdump attached to
+ *  this instruction (PPC `-r` output), absent otherwise. */
 export interface DisasmInstr {
   addr: number;
   mnemonic: string;
   ops: string[];
   target?: number;
-  sym?: string;
+  reloc?: DisasmReloc;
 }
 
 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. */
+   *  callee symbol for a `bl` whose encoded offset is a 0 placeholder, the named global behind a
+   *  printed-as-0 immediate or memory base (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;
+  /** What an all-zero word decodes to on this architecture (MIPS: `nop` — `sll zero,zero,0`).
+   *  objdump prints a run of zero words as a bare `...` instead of the words themselves, and the
+   *  words it stands for are real program text: a `mflo` hazard pad sits between a multiply and
+   *  the branch that reads it. Without a decoding they cannot be recovered, so the listing is
+   *  refused rather than parsed one word short (a zero word is not an instruction at all on
+   *  PowerPC, whose frontend therefore supplies none). */
+  zeroWord?: string;
+}
+
+/** Fixed instruction width, in bytes, of every ISA that reaches this reader (MIPS, PowerPC), so an
+ *  address gap is a whole number of words. Thumb is variable-width and has a reader of its own. */
+const WORD = 4;
+
+/** objdump's elision of a run of zero words: a bare `...` on its own line (`-d` prints it only
+ *  for zeroes; `-z` prints the words instead). */
+const ELISION_LINE = /^\s*\.\.\.\s*$/;
+
+/** An instruction line's address column, whatever the mnemonic column holds. A line that carries
+ *  an address carries a WORD of the function, so one this reader cannot decode must not be
+ *  skipped: the words after it would keep their addresses while the list lost one, and every
+ *  reader of that list — the delay slot at `branch + 4` above all — would be answering about a
+ *  word that is not there. */
+const ADDRESSED_LINE = /^\s*[0-9a-f]+:\s/i;
+
+/** Replace an elision with the zero words it stands for: from the word after the last instruction
+ *  parsed up to (not including) the address of the line that ends the run. Every way the run's
+ *  extent is unknowable refuses by name — a run of unknown length is exactly the silent hole this
+ *  exists to remove. A run with NO line after it is not a hole: it is the padding past the last
+ *  word objdump printed, it bounds nothing, and nothing is invented for it. */
+function expandElision(out: DisasmInstr[], next: number, zeroWord: string | undefined): void {
+  const prev = out[out.length - 1];
+  const hex = (a: number) => `0x${a.toString(16)}`;
+  if (!prev) {
+    throw new FrontendUnsupportedError(
+      `objdump elided a run of zero words ('...') before the first instruction of the listing, ` +
+        `ending at ${hex(next)}: where the run begins is unknown`,
+    );
+  }
+  const from = prev.addr + WORD;
+  if (zeroWord === undefined) {
+    throw new FrontendUnsupportedError(
+      `objdump elided a run of zero words ('...') at ${hex(from)}, but a zero word is not a ` +
+        `decodable instruction on this architecture`,
+    );
+  }
+  if (next <= from || (next - from) % WORD !== 0) {
+    throw new FrontendUnsupportedError(
+      `objdump elided a run of zero words ('...') between ${hex(from)} and ${hex(next)}, which is ` +
+        `not a whole number of instruction words`,
+    );
+  }
+  for (let addr = from; addr < next; addr += WORD) {
+    out.push({ addr, mnemonic: zeroWord, ops: [] });
+  }
+}
+
+/** Attach a parsed relocation to the instruction it belongs to. The binding is POSITIONAL —
+ *  objdump prints a relocation directly beneath its instruction — and both ways that assumption
+ *  can break fail LOUD, because each one silently relocates the wrong operand: an offset outside
+ *  the preceding instruction's four bytes means the listing is not the assumed shape (the offset
+ *  points at the relocated FIELD, so a 16-bit immediate's offset is the instruction's address + 2),
+ *  and a second relocation on one instruction would overwrite the first, leaving one symbol
+ *  standing for two. */
+function attachReloc(out: DisasmInstr[], offset: number, reloc: DisasmReloc): void {
+  const ins = out[out.length - 1];
+  if (!ins || offset < ins.addr || offset >= ins.addr + 4) {
+    throw new FrontendUnsupportedError(
+      `relocation '${reloc.type} ${reloc.sym}' at 0x${offset.toString(16)} does not fall inside ` +
+        (ins ? `the preceding instruction ('${ins.mnemonic}' at 0x${ins.addr.toString(16)})` : 'any instruction'),
+    );
+  }
+  if (ins.reloc) {
+    throw new FrontendUnsupportedError(
+      `two relocations on one instruction ('${ins.mnemonic}' at 0x${ins.addr.toString(16)}): ` +
+        `'${ins.reloc.type} ${ins.reloc.sym}' and '${reloc.type} ${reloc.sym}'`,
+    );
+  }
+  ins.reloc = reloc;
 }
 
 /** 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[] = [];
+  let elided = false;
   for (const raw of disasm.split('\n')) {
+    if (ELISION_LINE.test(raw)) {
+      elided = true;
+      continue;
+    }
     if (opts.relocs) {
-      const rel = raw.match(/^\s+[0-9a-f]+:\s+R_\w+\s+(\S+)/i);
+      const rel = raw.match(/^\s+([0-9a-f]+):\s+(R_\w+)\s+([^\s+-]+)(?:\s*([+-])\s*(0x[0-9a-f]+|\d+))?\s*$/i);
       if (rel) {
-        if (out.length) {
-          out[out.length - 1].sym = rel[1].split('+')[0];
-        }
+        attachReloc(out, parseInt(rel[1], 16), {
+          type: rel[2],
+          sym: rel[3],
+          addend: rel[5] ? parseImm(rel[5]) * (rel[4] === '-' ? -1 : 1) : 0,
+        });
         continue;
       }
     }
@@ -68,9 +189,18 @@ export function parseDisasm(disasm: string, opts: DisasmOptions = {}): DisasmIns
       ? 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) {
+      if (ADDRESSED_LINE.test(raw)) {
+        throw new FrontendUnsupportedError(
+          `objdump line '${raw.trim()}' carries an address but no instruction this reader can decode`,
+        );
+      }
       continue;
     }
     const addr = parseInt(m[1], 16);
+    if (elided) {
+      expandElision(out, addr, opts.zeroWord);
+      elided = false;
+    }
     const mnemonic = m[2]; // hint suffix (group 3), when parsed, is dropped
     const opsStr = opts.hintSuffixes ? m[4] : m[3];
     const ops = opsStr

package/src/frontend/high-half.ts

@@ -0,0 +1,149 @@
+// asmlift — the HIGH HALF of a relocated address, shared by the MIPS and PowerPC frontends.
+//
+// Both ISAs materialise a global's address in two instructions: a high-half producer (`lis
+// rD,SYM@ha`, `lui rD,%hi(SYM)`) and a low-half consumer (`addi rD,rHi,SYM@l`, `lw rD,%lo(SYM)(rHi)`)
+// that completes it. In a RELOCATABLE object neither printed immediate carries the address — it
+// lives entirely in the two relocation records — so the high half is NOT A VALUE but a placeholder
+// that means nothing until its matching low half completes it. Letting one reach the IR as an
+// ordinary number hands the pipeline a plausible address that compiles and is simply wrong, so the
+// invariant is absolute: a placeholder is either consumed by its low half or refuses.
+//
+// KEYED BY VALUE, NOT BY REGISTER, and the difference is the whole point. A register-keyed map
+// answers "was a high half put in rX?", which is not the question; the question is "does the half
+// reach THIS read?". Those differ whenever a redefinition on any path erases the entry, or a
+// sibling path the reader never takes writes the register — and the register-keyed reading then
+// falls through to whatever def reached before the producer. Keying by the SSA value makes the
+// pairing a PROOF, answered by SSA rather than by a side map with an invalidation discipline every
+// future writer must maintain.
+//
+// WHAT EACH ISA KEEPS FOR ITSELF is the ADDEND, and it is a relocation-format fact, not a
+// preference. PowerPC objects are RELA: the addend rides on the relocation record. MIPS objects are
+// REL: the record has no addend field and the value is split across the two instruction immediates
+// (`(hi_imm << 16) + (s16)lo_imm`), so the MIPS fold computes the high half's contribution itself.
+// Either way `addend` is "the part of the address this producer contributed", and the consumer adds
+// its own.
+import type { Block, Value } from '../ir/core';
+
+/** A pending high half: what it names, what it contributed, and the instruction that produced it,
+ *  so a refusal can point a reader at it. Whether it has been consumed is deliberately NOT here: it
+ *  is this module's own bookkeeping, set by `pair`, so no frontend can fold a pair and forget to
+ *  mark it — forgetting would refuse a well-formed function with nothing to catch it. */
+export interface HighHalfInfo {
+  sym: string;
+  /** This producer's contribution to the address — RELA carries it, REL computes it. */
+  addend: number;
+  addr: number;
+  mnemonic: string;
+}
+
+/** How one ISA spells the two halves in a refusal, and how it fails loud. */
+export interface HighHalfDialect {
+  /** The high-half marker as the ISA's asm spells it: `@ha` (PowerPC), `%hi` (MIPS). */
+  hi: string;
+  /** The indefinite article `hi` takes, so one shared sentence reads right in both ISAs' asm. */
+  hiArticle: string;
+  /** The low-half marker: `@l` (PowerPC), `%lo` (MIPS). */
+  lo: string;
+  /** The frontend's designed loud-failure signal (`PpcUnsupportedError`, `FrontendUnsupportedError`). */
+  fail(message: string): never;
+}
+
+export interface HighHalves {
+  /** Record the placeholder `v` as the high half `info`. The producer writes `v` as an ordinary SSA
+   *  definition, which is what lets SSA answer the pairing question later. */
+  record(v: Value, info: HighHalfInfo): void;
+  /** THE PAIRING. `v` is what the low half's base register holds HERE; it must be the very
+   *  placeholder a producer defined, and the two halves must name the same symbol (`alsoMatches`
+   *  adds the per-ISA rest of the match — PowerPC's RELA addend). Anything else refuses, naming
+   *  `reg` and what it really holds. The half is CONSUMED on the way out, which is why this is a
+   *  call and not a public flag: the mark and the proof cannot come apart. */
+  pair(site: string, reg: string, v: Value, loSym: string, alsoMatches?: (hi: HighHalfInfo) => boolean): HighHalfInfo;
+  /** True when `v` is a placeholder — for a caller that must EXCLUDE one (a call's argument count
+   *  must not treat a half parked in an argument register as an argument). */
+  has(v: Value): boolean;
+  /** Reading a register AS A VALUE. A register holding a high half is not one, so this refuses
+   *  rather than handing back a plausible number standing for an address. */
+  guardRead(name: string, reg: string, v: Value): Value;
+  /** A high half no low half ever completed. Finishing the lift would SILENTLY DROP the address it
+   *  was building — every low-half consumer a frontend does not model lands here, which is what
+   *  keeps "not modelled" from turning into "not emitted". */
+  assertAllConsumed(name: string): void;
+  /** The LAST line of defence, because `guardRead` sees only the reads a frontend routes through
+   *  it. SSA builds a block parameter's incoming arguments with reads of its own: at a merge of a
+   *  path that holds a half and a path that does not, the read returns the PARAMETER — an ordinary
+   *  value — while the placeholder is appended to the predecessor's successor arguments. So the
+   *  finished function is checked once: a placeholder anywhere in the IR refuses. */
+  assertNoneEscaped(name: string, blocks: Block[]): void;
+}
+
+export function makeHighHalves(d: HighHalfDialect): HighHalves {
+  const halves = new Map<Value, { info: HighHalfInfo; consumed: boolean }>();
+  return {
+    record: (v, info) => void halves.set(v, { info, consumed: false }),
+    has: (v) => halves.has(v),
+    pair(site, reg, v, loSym, alsoMatches) {
+      const entry = halves.get(v);
+      const hi = entry && entry.info.sym === loSym && (alsoMatches?.(entry.info) ?? true) ? entry.info : undefined;
+      if (!hi) {
+        d.fail(
+          `${site} carries the '${d.lo}' half of '${loSym}' but ${reg} ` +
+            (entry
+              ? `holds the high half of '${entry.info.sym}'`
+              : `holds no high half here — a reused register, a missing '${d.hi}', or ${d.hiArticle} ` +
+                `'${d.hi}' that reaches this instruction only through a merge or a loop header, where ` +
+                `what the register holds is the block parameter standing for the join and not the half`) +
+            ` — this frontend will not guess at the pair`,
+        );
+      }
+      entry!.consumed = true;
+      return hi;
+    },
+    guardRead(name, reg, v) {
+      const hi = halves.get(v)?.info;
+      if (hi) {
+        d.fail(
+          `cannot lift '${name}': ${reg} holds the high half of '${hi.sym}' (the '${hi.mnemonic}' at ` +
+            `0x${hi.addr.toString(16)}) and is read as a value — only its matching '${d.lo}' half may consume it`,
+        );
+      }
+      return v;
+    },
+    assertAllConsumed(name) {
+      // Lowest address first, so a function with several dangling halves names the one a reader
+      // meets first in the listing rather than whichever the map happened to iterate to.
+      const dangling = [...halves.values()]
+        .filter((h) => !h.consumed)
+        .map((h) => h.info)
+        .sort((a, b) => a.addr - b.addr)[0];
+      if (dangling) {
+        d.fail(
+          `cannot lift '${name}': '${dangling.mnemonic}' at 0x${dangling.addr.toString(16)} carries the ` +
+            `'${d.hi}' half of '${dangling.sym}' and no modelled instruction consumes its '${d.lo}' half — ` +
+            `the address is never completed`,
+        );
+      }
+    },
+    assertNoneEscaped(name, blocks) {
+      const escaped = (v: Value): void => {
+        const hi = halves.get(v)?.info;
+        if (hi) {
+          d.fail(
+            `cannot lift '${name}': the high half of '${hi.sym}' (the '${hi.mnemonic}' at ` +
+              `0x${hi.addr.toString(16)}) reaches a merge with values that are not it — what the register ` +
+              `holds there is not a value this frontend can write down`,
+          );
+        }
+      };
+      for (const b of blocks) {
+        b.params.forEach(escaped);
+        for (const op of b.ops) {
+          op.operands.forEach(escaped);
+          op.results.forEach(escaped);
+          for (const s of op.successors) {
+            s.args.forEach(escaped);
+          }
+        }
+      }
+    },
+  };
+}