@asmlift/core 0.9.0 → 0.10.0

package/src/frontend/frontend.ts

@@ -3,7 +3,8 @@
 // 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 { FnProto, Prototypes } from '../proto';
+import type { ContextGlobals } from '../proto-context';
 import type { SymbolMap } from '../symbols';
 import type { TargetDescription } from '../target';
 import type { AsmData } from './asmdata';
@@ -19,8 +20,10 @@ export interface Frontend {
    *  (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. `symbols` is the OPTIONAL address→symbol map
-   *  (symbols.ts); today only the Thumb frontend consumes it (numeric-pool promotion) — the
-   *  MIPS/PPC objdump dialect already carries symbol names in the asm text. */
+   *  (symbols.ts): the Thumb frontend promotes a numeric pool word through it — the
+   *  MIPS/PPC objdump dialect already carries symbol names in the asm text — and every frontend
+   *  hands it, with the OPTIONAL declaration `context`, to the dead-read pin, which reads a global's
+   *  declaration there (frontend/dead-reads.ts `declared-plain`). */
   lift(
     name: string,
     asm: string,
@@ -28,5 +31,63 @@ export interface Frontend {
     prototypes: Prototypes,
     asmData?: AsmData,
     symbols?: SymbolMap,
+    context?: ContextGlobals,
+    options?: LiftOptions,
   ): Fn;
 }
+
+/** THE FUNCTION'S OWN DECLARATION, as a call lowering reads it (frontend/call-plan.ts
+ *  `callDeclarations`): a stated entry, which `proves`, or the declaration context's
+ *  (`LiftOptions.contextOwnProto`). */
+export interface OwnDeclaration {
+  readonly proto: FnProto;
+  /** whether it may rule a reading OUT (a hole, a shadow, a float) as well as refuse one */
+  readonly proves: boolean;
+}
+
+/** The own declaration of `name`: the stated entry in `prototypes`, else the context's. */
+export function ownDeclarationOf(
+  name: string,
+  prototypes: Prototypes,
+  context: OwnDeclaration | undefined,
+): OwnDeclaration | undefined {
+  return Object.hasOwn(prototypes, name) ? { proto: prototypes[name], proves: true } : context;
+}
+
+/** A question the asm leaves open that a frontend answers one way by default and, asked, the other
+ *  way: the LIFT variations of rank.ts that live in the frontend. A frontend with no such question
+ *  ignores the whole bag. Two inputs ride beside them that no variation sets, both from the
+ *  declaration context's own entry: its bound (`contextOwnWords`) and the entry itself
+ *  (`contextOwnProto`). */
+export interface LiftOptions {
+  /** The argument words the declaration context's own entry for the function fills, where no
+   *  stated entry does (pipeline.ts `liftWithinContextBound`, which raises it past a register the
+   *  lift reads, and lifts without it where it refuses), so a frontend given it reads it in place
+   *  of the stated entry's words (frontend/ssa.ts `registerLiveIns`). Every frontend reads it; PowerPC,
+   *  as with a stated entry, only for a body a compiler wrote. */
+  contextOwnWords?: number;
+  /** The declaration context's own entry itself, where no stated entry binds the body. Read where
+   *  the TYPES of the own parameters decide something the word count cannot (frontend/call-plan.ts
+   *  `decideGap`). `proves` says whether it may serve as positive proof as well. It holds only where
+   *  the lift is bounded by exactly the entry's words, or the entry fills every argument register,
+   *  and never once the bound was raised past a register the body reads or the lift fell back to
+   *  no bound, which says the entry is wrong. Without `proves`, it only refuses. */
+  contextOwnProto?: OwnDeclaration;
+  /** The size in bytes of a struct the function's own declaration returns through a hidden pointer
+   *  (pipeline.ts `liftStamped`), and where to hand a refusal that declaration may answer: one about
+   *  the RETURN's width that such a struct explains, which the frontend then defers instead of
+   *  throwing, as the function that throws it. The pipeline calls that after all unless the lift
+   *  proves the pointer is that struct's storage (frontend/own-struct-return.ts), handing it why the
+   *  proof failed, which the refusal then says. Thumb only: agbcc's interworking epilogue sizes an
+   *  8-byte struct returned through memory as it sizes a `long long` (`eightByteReturnScratch`). */
+  ownMemoryReturn?: { bytes: number; defer(refuse: (unproved: string) => never): void };
+  /** MIPS: keep the slot of a `b`/`j` whose slot is the last word of a common tail its two arms
+   *  both spell (`sll; b T; sra` against `sll; sra; T:`), rather than retarget it to the copy at
+   *  T-4 and merge the arms. The default retargets (frontend/mips.ts `normaliseBranchLikely`). An
+   *  IDO question: GCC 2.7.2 and KMC cross-jump such a tail into one copy before filling a slot, so
+   *  on their output the slot is never a tail written twice. */
+  keepTailSlots?: boolean;
+  /** Called when the lift met such a slot, whichever way it answered: what rank.ts asks before
+   *  enumerating `/kept-slot` at all. */
+  onTailSlot?: () => void;
+}

package/src/frontend/high-half.ts

@@ -6,7 +6,9 @@
 // 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.
+// invariant is absolute: a placeholder is either consumed by its low half or refuses. The one other
+// consumer is `index`, and it does not break the rule: it consumes the half only to define a NEW
+// placeholder, the half plus a runtime index, which is held to the same rule in turn.
 //
 // 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
@@ -35,6 +37,11 @@ export interface HighHalfInfo {
   addend: number;
   addr: number;
   mnemonic: string;
+  /** A RUNTIME BYTE INDEX added between the halves (`lui rH,%hi(S); addu rH,rH,idx; lw x,%lo(S)(rH)`,
+   *  which is how ido, KMC and GCC 2.7.2 address `S[i]`), set only on a half `index` derived. The
+   *  index sits outside both relocated immediates, so the `%lo` carry is the same with and without
+   *  it and the completed address is exactly `S + addend + lo + index`. */
+  index?: Value;
 }
 
 /** How one ISA spells the two halves in a refusal, and how it fails loud. */
@@ -57,8 +64,28 @@ export interface HighHalves {
    *  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;
+   *  call and not a public flag: the mark and the proof cannot come apart.
+   *
+   *  An INDEXED half (`index`) pairs only for a caller that passes `takesIndex`, and the index and
+   *  the proof cannot come apart either: a consumer that completes the address as `gaddr(sym) +
+   *  addend` without reading `index` would drop the index and still compile. So a caller that has
+   *  not said it adds `index` back gets a refusal in place of that address. */
+  pair(
+    site: string,
+    reg: string,
+    v: Value,
+    loSym: string,
+    alsoMatches?: (hi: HighHalfInfo) => boolean,
+    takesIndex?: boolean,
+  ): HighHalfInfo;
+  /** AN INDEXED HIGH HALF: `v` is the half `base` plus the runtime byte index `idx`, made by the
+   *  instruction at `at`. It is a placeholder like the half it came from — read as a value, left
+   *  uncompleted or carried into a merge it refuses through the same guards, because it lives in the
+   *  same value-keyed map — and only its `%lo` completes it, `pair` handing the index back. Deriving
+   *  CONSUMES `base`: the derivation is the use the base half was waiting for. Indexing a half that
+   *  is already indexed refuses — no compiler measured chains two (lui;addu;addu); a frontend that
+   *  meets one has hand-written or unmodelled code, not `S[i][j]`, which every compiler sums first. */
+  index(v: Value, base: Value, idx: Value, at: { addr: number; mnemonic: string }): void;
   /** 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;
@@ -82,8 +109,30 @@ export function makeHighHalves(d: HighHalfDialect): HighHalves {
   return {
     record: (v, info) => void halves.set(v, { info, consumed: false }),
     has: (v) => halves.has(v),
-    pair(site, reg, v, loSym, alsoMatches) {
+    index(v, base, idx, at) {
+      const entry = halves.get(base);
+      if (!entry) {
+        d.fail(`the '${at.mnemonic}' at 0x${at.addr.toString(16)} indexes a value that holds no high half`);
+      }
+      if (entry!.info.index !== undefined) {
+        d.fail(
+          `the '${at.mnemonic}' at 0x${at.addr.toString(16)} adds a second index to the high half of ` +
+            `'${entry!.info.sym}' (the '${entry!.info.mnemonic}' at 0x${entry!.info.addr.toString(16)}) — ` +
+            `a chain of indexes between the halves is not modelled`,
+        );
+      }
+      entry!.consumed = true;
+      halves.set(v, { info: { ...entry!.info, addr: at.addr, mnemonic: at.mnemonic, index: idx }, consumed: false });
+    },
+    pair(site, reg, v, loSym, alsoMatches, takesIndex = false) {
       const entry = halves.get(v);
+      if (entry?.info.index !== undefined && !takesIndex) {
+        d.fail(
+          `${site} carries the '${d.lo}' half of '${loSym}' but ${reg} holds the high half of ` +
+            `'${entry.info.sym}' plus a runtime index (the '${entry.info.mnemonic}' at ` +
+            `0x${entry.info.addr.toString(16)}), and this consumer completes no index`,
+        );
+      }
       const hi = entry && entry.info.sym === loSym && (alsoMatches?.(entry.info) ?? true) ? entry.info : undefined;
       if (!hi) {
         d.fail(