@asmlift/core 0.10.0 → 0.11.0

package/src/variation-definitions.ts

@@ -264,6 +264,7 @@ export interface VariationDefinition {
 const CALLS =
   'void A(); void B(); void C(); void D(); void X(); void Y(); void P(); void Q(); s32 f(); s32 g(); s32 h(); void use();\n';
 
+const PIPELINE = 'packages/core/src/pipeline.ts';
 const RANK = 'packages/core/src/rank.ts';
 const RANK_VARIATIONS = 'packages/core/src/rank-variations.ts';
 const SYMBOLS = 'packages/core/src/symbols.ts';
@@ -400,10 +401,14 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     title: 'Shared code after an early return',
     summary: 'code both arms of an `if` reach before returning is written once, after the `if`',
     detail:
-      'An `if` whose arms never meet again before the function returns has no follow, so by default a ' +
-      'region both arms reach is written in each of them. This structures the same raised function again ' +
-      "with that shared region as the `if`'s follow: it is written once after the `if`, and every other " +
-      'path leaves through an early `return`.',
+      'An `if` whose arms never meet again before the function returns has no follow, so under the ' +
+      'return-tail copies (`ret-copy`) a region both arms reach is written in each of them. This structures ' +
+      "the same raised function again with the copies and that shared region as the `if`'s follow: it is " +
+      'written once after the `if`, and every other path leaves through an early `return`. On agbcc, ' +
+      "this example's compiler, the copies are the default, so this is the step from them to the region " +
+      'written once. Where the join past early returns is the default instead (CodeWarrior ' +
+      "2.4.2 and 2.3.3), it already writes this example's region once, since the paths that do not " +
+      'return meet at it: the variation is a reading of the copies, ranked beside them.',
     offeredWhen: {
       when: 'Some `if` has arms that reach a common `return` block and no common block before it.',
       decidedBy: { symbol: 'hasDivergentSharedRet', file: STRUCTURE },
@@ -415,7 +420,68 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
       after: 'if (c) { A(); } else { if (x) { C(); return; } } B();',
     },
     implementedIn: STRUCTURE,
-    seeAlso: ['shared-tail'],
+    seeAlso: ['shared-tail', 'ret-copy'],
+  },
+  'ret-copy': {
+    title: 'Return tails copied',
+    summary: 'code below an `if` whose arms only meet at the `return` is written into each arm',
+    detail:
+      'An `if` with an early `return` in one arm has no block both arms reach before the function ' +
+      'returns. Where the join past early returns is the default (CodeWarrior 2.3.3, and 2.4.2, ' +
+      "this example's compiler), asmlift gives it the block where the paths that do not return meet as its " +
+      'join, so the code from there is written once and every other path leaves through its early ' +
+      '`return`; that also reads early returns the compiler merged into the epilogue or cross-jumped ' +
+      'into one return tail, and a `switch` with a `case` that returns early. This structures the same ' +
+      'raised function again with no such join: everything below the `if` is written into each arm, ' +
+      'once more per such `if` of a chain, which is the source some functions were written as. Where ' +
+      'the copies spell the whole function in fewer lines than the join, where the compiler is one that ' +
+      'cross-jumps return tails and the layout shows it did, or where an early return keeps a constant ' +
+      'its branch proved unfolded (gcc 2.x below -O2), they are the default instead, and the join is ' +
+      'offered as `ret-join`. On agbcc and IDO 7.1, measured against held-out functions where the join ' +
+      'loses matches, on GCC 2.7.2 and KMC, measured against generated functions where it does, and on CodeWarrior 2.4.7, where no held-out function was measured, the copies are ' +
+      'the default outright, and this variation is never offered there. Past the copy budget the copies ' +
+      'are not offered.',
+    offeredWhen: {
+      when: 'Some `if` or `switch` outside every loop took a join past early returns that the default kept.',
+      decidedBy: { symbol: 'structureReturnTailReading', file: PIPELINE },
+    },
+    example: {
+      compiler: 'mwcc',
+      unit: CALLS + 'extern s32 gT; void example(s32 a, s32 b) { @ }',
+      before: 'if (a > 3) { if (b == 1) { A(); gT = 0; return; } B(); } else { C(); } X(); Y();',
+      after: 'if (a > 3) { if (b == 1) { A(); gT = 0; return; } B(); X(); Y(); } else { C(); X(); Y(); }',
+      note: 'the shape of `synthetic:retchain_one`',
+    },
+    implementedIn: STRUCTURE,
+    seeAlso: ['shared-ret', 'ret-join'],
+  },
+  'ret-join': {
+    title: 'Join past early returns, where the copies are the default',
+    summary: 'the join past early returns, where it writes a return tail into early returns',
+    detail:
+      'The join past early returns writes the code below a divergent `if` once, but where the paths that ' +
+      'do not return meet at a block only some of them reach, every other path becomes an early `return` ' +
+      'that takes its own copy of the tail below. Where that spells the whole function in more lines than ' +
+      'the return-tail copies, or where the layout shows the compiler cross-jumped a return tail the ' +
+      'source wrote into every arm, or where an early return keeps a constant its branch proved unfolded ' +
+      '(gcc 2.x below -O2), the copies are the default and this is the join, offered beside them, which is ' +
+      "the source some functions were written as. On agbcc, this example's compiler, and on IDO 7.1, GCC 2.7.2, KMC and " +
+      'CodeWarrior 2.4.7, the copies are the default outright: the join is this variation ' +
+      'wherever it is taken.',
+    offeredWhen: {
+      when: 'Some `if` or `switch` outside every loop took a join past early returns that the default gave up for the copies.',
+      decidedBy: { symbol: 'structureReturnTailReading', file: PIPELINE },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit: CALLS + 'void example(s32 a) { @ }',
+      before: 'if (a == 1) { A(); B(); } else if (a == 2 || a == 3) { A(); } else { A(); B(); } X(); Y(); C();',
+      after:
+        'if (a == 1) { A(); } else { if (a == 2 || a == 3) { A(); X(); Y(); C(); return; } A(); } B(); X(); Y(); C();',
+      note: 'the shape of sa3 `sub_809A808`',
+    },
+    implementedIn: PIPELINE,
+    seeAlso: ['ret-copy'],
   },
   'shared-tail': {
     title: 'Store tail copied back',
@@ -423,7 +489,7 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     detail:
       "agbcc's global common-subexpression pass can move a trailing store into every predecessor of a join, " +
       'and the paths then jump into one `store; return` tail. This lift copies that tail back into each ' +
-      'path that branches to it, and then structures with the shared follow `shared-ret` uses, so the ' +
+      'path that branches to it, and then structures with the copies and the shared follow `shared-ret` uses, so the ' +
       'store the source wrote once is written after the `if` and the others before an early `return`. It is ' +
       'enumerated apart from `shared-ret` because the sink can delete the shared `return` that variation needs.',
     compilerBehavior:
@@ -957,6 +1023,107 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: STRUCTURE,
     seeAlso: ['flip-join', 'flip-branch', 'sense', 'connective'],
   },
+  'tail-copies': {
+    title: 'Shared switch tail copied into every arm',
+    summary: 'every `case` that runs into the tail a cross-jump kept gets its own copy of it',
+    detail:
+      'When several `case` arms end in the same code, the compiler keeps one copy and the other arms jump ' +
+      "into it, so they all enter one arm's body. By default the arm placed directly above that body keeps " +
+      'falling into it and the others get a copy. This gives every one of them its own copy.',
+    compilerBehavior:
+      'Which arm the source wrote the shared code under is not in the assembly. On KMC and gcc 2.7.2, an ' +
+      'arm written above its target in case order wants the fall-through, and arms written out of case ' +
+      'order want the copies.',
+    offeredWhen: {
+      when: "Structuring this lift without it left a jump-table arm falling into a sibling arm's body that another arm also enters.",
+      decidedBy: { symbol: 'STRUCTURE_VARIATIONS', file: RANK_VARIATIONS },
+    },
+    example: {
+      compiler: 'gcc',
+      unit:
+        'extern s32 gOut; void f(s32); void g(s32); void h(s32); void m(s32); void r(s32);\n' +
+        'void example(s32 id, s32 v) { switch (id) { @ } r(0); }',
+      before:
+        'case 0: f(1); break; case 1: g(v); case 2: gOut = v; break; case 3: h(v); gOut = v; break; case 4: m(5); break;',
+      after:
+        'case 0: f(1); break; case 1: g(v); gOut = v; break; case 2: gOut = v; break; case 3: h(v); gOut = v; break; case 4: m(5); break;',
+      note: 'cases 1 and 3 both enter case 2',
+    },
+    implementedIn: STRUCTURE,
+    seeAlso: ['unmerge', 'shared-tail'],
+  },
+  'for-continue': {
+    title: 'Counted loop spelled as a `for`',
+    summary: 'a `while (1)` whose last block steps and tests a counter is written `for (init; test; step)`',
+    detail:
+      'A loop whose last block adds to a counter and tests it is written by default as `while (1)` with ' +
+      '`i++; if (!(test)) break;` at the foot of its body, and a jump-table arm inside it that leaves the ' +
+      'loop copies the code after the loop and returns. This writes it as `for (i = init; test; i++)` instead, ' +
+      'so an arm that reaches the step is `continue;`, an arm that leaves the loop ends the switch, and a ' +
+      '`break;` after the switch leaves the loop. Only a loop whose entry test is the same test (or folds to ' +
+      'true) and whose last block does nothing but step one counter and test it is written this way.',
+    compilerBehavior:
+      'agbcc and gcc 2.7.2 lay a `for` out as a guard, the body and a latch that steps and tests, which is ' +
+      'also how they lay out the `while (1)` spelling of the same loop. Which one the source wrote decides ' +
+      'how the arms that leave the loop are laid out, and that is not in the assembly before it is compiled.',
+    offeredWhen: {
+      when: 'Structuring this lift without it met a `while (1)` loop whose last block steps one counter and tests it.',
+      decidedBy: { symbol: 'STRUCTURE_VARIATIONS', file: RANK_VARIATIONS },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit:
+        'struct E { s32 x; u8 id; u8 u; }; extern struct E gE[]; void k(s32);\n' +
+        'void example(s32 lo, s32 hi) { s32 i; @ k(99); }',
+      before:
+        'if (lo <= hi) { i = lo; while (1) { switch (gE[i].id) { case 1: if (gE[i].u != 1) { k(4); k(99); return; } break; ' +
+        'case 2: if (gE[i].x <= 20) { k(5); k(99); return; } break; case 3: if (gE[i].x >= 0) { k(6); k(99); return; } break; ' +
+        'case 4: if (gE[i].x > 2) { k(7); k(99); return; } break; case 5: if (gE[i].x != 9) { k(8); k(99); return; } break; } ' +
+        'i++; if (i > hi) break; } }',
+      after:
+        'for (i = lo; i <= hi; i++) { switch (gE[i].id) { case 1: if (gE[i].u == 1) continue; k(4); break; ' +
+        'case 2: if (gE[i].x > 20) continue; k(5); break; case 3: if (gE[i].x < 0) continue; k(6); break; ' +
+        'case 4: if (gE[i].x <= 2) continue; k(7); break; case 5: if (gE[i].x == 9) continue; k(8); break; ' +
+        'default: continue; } break; }',
+      note: 'every arm either goes round the loop or calls `k` and leaves it; five arms, so agbcc dispatches through a jump table',
+    },
+    implementedIn: STRUCTURE,
+    seeAlso: ['tail-copies'],
+  },
+  'case-goto': {
+    title: 'Shared case body entered by `goto`',
+    summary:
+      "every `case` that runs into another case's body the default copies it into ends `goto` to that case instead",
+    detail:
+      "When several `case` arms run on into one other arm's body, by default the arm placed directly above " +
+      'that body keeps falling into it and the others get a copy of it. This leaves the copies out: those ' +
+      'arms end in `goto` to a label on that arm, after its `case` labels. It is one of the two kinds of `goto` asmlift writes.',
+    compilerBehavior:
+      'A compiler that cross-jumps keeps one copy of code that several arms end in, so a copy and a `goto` can ' +
+      'build the same object. agbcc stops that merge short where an arm already formed an address the copy ' +
+      'forms again, and the copy then compiles to more code than the `goto`.',
+    offeredWhen: {
+      when: "Structuring this lift without it copied a case arm's body into another jump-table arm that runs on into it.",
+      decidedBy: { symbol: 'STRUCTURE_VARIATIONS', file: RANK_VARIATIONS },
+    },
+    example: {
+      compiler: 'agbcc',
+      unit:
+        'struct E { s32 x; u8 id; u8 f; u8 u; u8 v; }; extern struct E gE[]; extern s32 gOut; void k(s32);\n' +
+        'void example(s32 lo, s32 hi) { s32 i; for (i = lo; i <= hi; i++) { switch (gE[i].id) { @ default: continue; } break; } }',
+      before:
+        'case 1: if (gE[i].u == 1) continue; if (gE[i].x > 20) continue; gOut = 1; k(i); break; ' +
+        'case 2: if (gE[i + 1].v != 0) continue; case 3: case 4: if (gE[i].x > 20) continue; gOut = 1; k(i); break; ' +
+        'case 7: k(7); break;',
+      after:
+        'case 1: if (gE[i].u == 1) continue; goto case_3; ' +
+        'case 2: if (gE[i + 1].v != 0) continue; case 3: case 4: case_3: if (gE[i].x > 20) continue; gOut = 1; k(i); ' +
+        'break; case 7: k(7); break;',
+      note: 'cases 1 and 2 both run on into the body of cases 3 and 4',
+    },
+    implementedIn: STRUCTURE,
+    seeAlso: ['tail-copies'],
+  },
 
   // ── respell ─────────────────────────────────────────────────────────────────────────────────
   unmerge: {
@@ -990,6 +1157,40 @@ export const VARIATION_DEFINITIONS: { readonly [N in VariationName]: VariationDe
     implementedIn: l3('unmerge'),
     seeAlso: ['initfirst', 'regionbase'],
   },
+  'case-end-goto': {
+    title: 'Search loop leaving its case by `goto`',
+    summary: "a search loop's hit that skips the rest of its `case` jumps to a label on the case's closing `break;`",
+    detail:
+      'When a loop inside a `case` has a second way out that skips the code after the loop and ends the ' +
+      '`case`, the default sets a flag before it leaves the loop and runs that code under `if (flag == 0)` ' +
+      'after it. This leaves the flag out: the second way out is `goto` to a label on the `break;` that ' +
+      'ends the case, and the code after the loop runs unguarded before that label. It is one of the two ' +
+      'kinds of `goto` asmlift writes.',
+    compilerBehavior:
+      'agbcc sends a `goto` to a `break;` straight to the end of the `switch`, and past a loop the switch ' +
+      'ends, so only the `goto` builds the bytes the source did; the flag adds a variable and its tests.',
+    offeredWhen: {
+      judges: "each flag set at a loop's own `break` and tested right after that loop",
+      gates: ['CASE_END_GOTO_GATES'],
+    },
+    example: {
+      compiler: 'agbcc',
+      unit:
+        'struct E { s32 x; u8 id; u8 f; u8 u; u8 v; }; extern struct E gE[]; extern s32 gLo, gHi; void k(s32);\n' +
+        'void example(s32 lo, s32 hi) { s32 i, j, h, a = 0; for (i = lo; i <= hi; i++) { if (gE[i].f <= 26) { ' +
+        'switch (gE[i].id) { @ default: continue; } break; } } k(a); }',
+      before:
+        'case 1: case 2: if (gE[i].x > 5) continue; h = 0; for (j = gLo; j <= gHi; j++) { if (i != j && gE[j].f == 28) ' +
+        '{ a = 1; k(j); h = 1; break; } } if (h == 0) { gE[i].f = 19; k(i); } break; case 4: k(i + 4); break;',
+      after:
+        'case 1: case 2: if (gE[i].x > 5) continue; for (j = gLo; j <= gHi; j++) { if (i != j && gE[j].f == 28) ' +
+        '{ a = 1; k(j); goto hit; } } gE[i].f = 19; k(i); hit: break; case 4: k(i + 4); break;',
+      note: 'the search loop in cases 1 and 2 either finds a hit, which skips the rest of the case, or runs out into it',
+    },
+    implementedIn: l3('caseendgoto'),
+    seeAlso: ['case-goto'],
+  },
+
   argbase: {
     title: 'Argument bases named before the call',
     summary: "the fixed addresses a call's arguments read are loaded into pointer locals first",

package/src/variation-gates.ts

@@ -11,6 +11,7 @@
 import { ADVANCE_HEAD_GATES, ADVANCE_MEMBER_GATES } from './l3/advance';
 import { ARGCOPY_GATES, ARGCOPY_REGION_GATES } from './l3/argcopy';
 import { BASEFOLD_GATES, LIVEBASE_BLOCK_GATES, LIVEBASE_GATES, ORDERBASE_GATES, UNFOLDED_GATES } from './l3/basecse';
+import { CASE_END_GOTO_GATES } from './l3/caseendgoto';
 import { ARM_DISJOINT_GATES, COALESCE_GATES } from './l3/coalesce';
 import type { Gate } from './l3/gates';
 import { HOMESPLIT_FAN_GATES, HOMESPLIT_GATES } from './l3/homesplit';
@@ -49,6 +50,7 @@ export const VARIATION_GATE_TABLES = {
   ARM_DISJOINT_GATES,
   ARM_REREAD_GATES,
   BASEFOLD_GATES,
+  CASE_END_GOTO_GATES,
   COALESCE_GATES,
   COUNTDOWN_GATES,
   FRESH_MERGE_GATES,

package/src/variation-tokens.ts

@@ -69,6 +69,8 @@ const TOKENS = [
   { name: 'connective', variationKind: 'lift' },
   { name: 'narrow-param', variationKind: 'lift' },
   { name: 'shared-ret', variationKind: 'lift' },
+  { name: 'ret-copy', variationKind: 'lift' },
+  { name: 'ret-join', variationKind: 'lift' },
   { name: 'shared-tail', variationKind: 'lift' },
   { name: 'kept-slot', variationKind: 'lift' },
   { name: 'far-cast', variationKind: 'lift' },
@@ -93,8 +95,12 @@ const TOKENS = [
   { name: 'fresh-merge', variationKind: 'structure' },
   { name: 'copy-defpos', variationKind: 'structure' },
   { name: 'site-sense', variationKind: 'structure' },
+  { name: 'tail-copies', variationKind: 'structure' },
+  { name: 'for-continue', variationKind: 'structure' },
+  { name: 'case-goto', variationKind: 'structure' },
   // respell: the structured tree rewritten
   { name: 'unmerge', variationKind: 'respell' },
+  { name: 'case-end-goto', variationKind: 'respell' },
   { name: 'argbase', variationKind: 'respell' },
   { name: 'zerosub', variationKind: 'respell' },
   { name: 'volatile', variationKind: 'respell', subject: LOCALS },
@@ -293,6 +299,40 @@ export function splitVariations(name: string): string[] {
   return variations;
 }
 
+/** What is wrong with one candidate's name, or `undefined`: no variation at all, a variation the
+ *  registry does not hold, a first variation that is not a signedness, or a variation after one of
+ *  a later kind. The mint sites are typed, so none of these is a `tsc` error; enumeration data is
+ *  the only place one shows, and `tallyFanVariations` asks this of every candidate it counts. */
+export function variationsDefect(variations: readonly string[]): string | undefined {
+  try {
+    return orderDefect(variations, (part) => kindIndex(parseVariation(part).name));
+  } catch (e) {
+    return `${variations.join('/')}: ${e instanceof Error ? e.message : String(e)}`;
+  }
+}
+
+const kindIndex = (name: string): number => VARIATION_KINDS.indexOf(variationToken(name).variationKind);
+
+/** `variationsDefect` past the registry lookup, which `kindOf` does (and throws from) so the tally
+ *  can serve it from its own cache. */
+function orderDefect(variations: readonly string[], kindOf: (part: string) => number): string | undefined {
+  if (variations.length === 0) {
+    return 'a candidate with no variations: it applies at least its signedness';
+  }
+  let previous = -1;
+  for (const [i, part] of variations.entries()) {
+    const kind = kindOf(part);
+    if (i === 0 && VARIATION_KINDS[kind] !== 'signedness') {
+      return `${variations.join('/')}: the first variation is '${part}', not a signedness`;
+    }
+    if (kind < previous) {
+      return `${variations.join('/')}: '${part}' (${VARIATION_KINDS[kind]}) after a ${VARIATION_KINDS[previous]} variation`;
+    }
+    previous = kind;
+  }
+  return undefined;
+}
+
 /** How many of one fan's candidates carry one variation. `candidates` counts the whole fan —
  *  scored, dropped, withheld and never compiled alike — and `dropped`, `withheld` and
  *  `notCompiled` are the parts of that count the ranking did not score, each absent when 0.
@@ -319,7 +359,15 @@ interface NamedCandidate {
  *
  *  A tally, not a factorisation: enumeration gates prune the fan, so the counts do not multiply to
  *  its size. Keys run in kind order, then by name, so two tallies of one fan serialize to the same
- *  bytes whatever order the fan was listed in. Throws on a variation the registry does not hold. */
+ *  bytes whatever order the fan was listed in.
+ *
+ *  Throws on any candidate whose name `variationsDefect` refuses — an unregistered variation, a
+ *  first variation that is not a signedness, parts out of kind order. The bench tallies every fan
+ *  it ranks to a verdict or refuses whole, every candidate of it, on both tiers, so this is where a
+ *  malformed mint is caught: the artifact keeps only the winner's and the refused candidates' names,
+ *  and a test that re-enumerated the synthetic tier to read the rest cost minutes and never saw the
+ *  real one. A rank a scorer dies in leaves a `noncompile` row with no fan, so nothing is tallied
+ *  there. */
 export function tallyFanVariations(fan: {
   candidates: readonly NamedCandidate[];
   dropped: readonly NamedCandidate[];
@@ -335,9 +383,23 @@ export function tallyFanVariations(fan: {
     }
     return name;
   };
+  const kindOfName = new Map<string, number>();
+  const kindOf = (part: string): number => {
+    const name = nameOf(part);
+    let kind = kindOfName.get(name);
+    if (kind === undefined) {
+      kind = kindIndex(name);
+      kindOfName.set(name, kind);
+    }
+    return kind;
+  };
   const counts = new Map<string, { candidates: number; dropped: number; withheld: number; notCompiled: number }>();
   const add = (list: readonly NamedCandidate[], refusal: 'dropped' | 'withheld' | 'notCompiled' | undefined): void => {
     for (const c of list) {
+      const defect = orderDefect(c.variations, kindOf);
+      if (defect !== undefined) {
+        throw new Error(`a fan candidate's name is malformed — ${defect} (packages/core/src/variation-tokens.ts)`);
+      }
       for (const name of new Set(c.variations.map(nameOf))) {
         let n = counts.get(name);
         if (n === undefined) {
@@ -355,7 +417,6 @@ export function tallyFanVariations(fan: {
   add(fan.dropped, 'dropped');
   add(fan.withheld, 'withheld');
   add(fan.notCompiled, 'notCompiled');
-  const kindIndex = (name: string): number => VARIATION_KINDS.indexOf(variationToken(name).variationKind);
   const names = [...counts.keys()].sort((a, b) => kindIndex(a) - kindIndex(b) || (a < b ? -1 : a > b ? 1 : 0));
   return Object.fromEntries(
     names.map((name) => {