@henols/c64-re-tools 2.0.0-rc.6 → 2.0.0-rc.7

package/skills/c64-source/scripts/loader.ts

@@ -1,6 +1,8 @@
 // The loader of a generated source (D48): a PRG that copies each segment and
-// the entry state's pages $0002-$03ff into place, sets $00/$01, the stack
-// pointer, A, X, Y and the flags, and jumps to the entry. The copies run
+// the entry state's pages $0002-$03ff into place, sets the display registers
+// of the VIC-II and the VIC bank, waits for the entry's raster line (D60),
+// sets $00/$01, the stack pointer, A, X, Y and the flags, and jumps to the
+// entry. The copies run
 // from a free page with SEI and all RAM visible, in an order where no copy
 // overwrites the packed bytes of a copy that has not run yet. The plan is
 // simulated here before the emulator runs it.
@@ -20,6 +22,31 @@ export interface EntryState {
   port: [number, number];
   /** $0000-$03ff at the entry. */
   pages: Uint8Array;
+  /** The VIC-II at the entry (D60): $d000-$d02e, and the VIC bank (bits 0-1 of $dd00). */
+  vic?: { registers: Uint8Array; bank: number };
+}
+
+/**
+ * The VIC-II registers that the loader sets (D60), each with the bits that a
+ * read gives back: not the raster, the light pen, the interrupt registers or
+ * the collisions. The raster line comes from a wait instead.
+ */
+export const VIC_DISPLAY_REGISTERS: ReadonlyArray<{ register: number; mask: number }> = [
+  ...Array.from({ length: 0x11 }, (_, register) => ({ register, mask: 0xff })),
+  { register: 0x11, mask: 0x7f },
+  { register: 0x15, mask: 0xff },
+  { register: 0x16, mask: 0x3f },
+  { register: 0x17, mask: 0xff },
+  { register: 0x18, mask: 0xfe },
+  { register: 0x1b, mask: 0xff },
+  { register: 0x1c, mask: 0xff },
+  { register: 0x1d, mask: 0xff },
+  ...Array.from({ length: 0x0f }, (_, index) => ({ register: 0x20 + index, mask: 0x0f })),
+];
+
+/** The raster line of the entry, from $d011 bit 7 and $d012 as the capture read them. */
+export function rasterLine(registers: Uint8Array): number {
+  return ((registers[0x11]! & 0x80) << 1) | registers[0x12]!;
 }
 
 const FLAG_BITS: Record<string, number> = { n: 0x80, v: 0x40, b: 0x10, d: 0x08, i: 0x04, z: 0x02, c: 0x01 };
@@ -57,6 +84,7 @@ export function readEntryState(text: string, path: string): EntryState {
     flags,
     port: [byte(value.cpuPort?.$00, "cpuPort.$00"), byte(value.cpuPort?.$01, "cpuPort.$01")],
     pages,
+    ...readVic(value.io, fail),
   };
 }
 
@@ -97,9 +125,14 @@ const STUB = 0x080d;
 const STUB_SIZE = 21;
 /** The copier code and its three variables, without the table. */
 const COPIER_CODE_SIZE = 167;
+/** The VIC-II code of the copier (D60), without its two tables of one byte per register. */
+const VIC_CODE_SIZE = 44;
+const VIC_SIZE = VIC_CODE_SIZE + 2 * VIC_DISPLAY_REGISTERS.length;
+/** The copier and the stub's move of it: two pages. */
+const COPIER_LIMIT = 0x200;
 const COPY_ENTRY = 7;
-/** X indexes the table, so the table fits in 256 bytes. */
-export const MAX_COPIES = Math.floor((256 - 2) / COPY_ENTRY);
+/** X indexes the table, so the table fits in 256 bytes, and the copier with the VIC-II code fits in two pages. */
+export const MAX_COPIES = Math.min(Math.floor((256 - 2) / COPY_ENTRY), Math.floor((COPIER_LIMIT - COPIER_CODE_SIZE - VIC_SIZE - 2) / COPY_ENTRY));
 /** A loader that loads into $d000 or higher would write the I/O area. */
 const LOAD_LIMIT = 0xcfff;
 const COPIER_PAGES = [...Array.from({ length: 15 }, (_, index) => 0xc000 + index * 0x100), ...Array.from({ length: 0x9b }, (_, index) => 0x9e00 - index * 0x100)];
@@ -147,6 +180,16 @@ export function simulate(memory: Int16Array, copies: Copy[], expected: (address:
   return undefined;
 }
 
+/** The VIC-II and its bank from the io part of an entry state, when it has them. */
+function readVic(io: Record<string, any> | undefined, fail: (what: string) => never): { vic: NonNullable<EntryState["vic"]> } | Record<string, never> {
+  if (io?.vic === undefined) return {};
+  const vic = io.vic.bytes;
+  const cia2 = io.cia2?.bytes;
+  if (typeof vic !== "string" || !/^[0-9a-f]{94}$/i.test(vic)) return fail("io.vic.bytes is not 47 bytes of hex");
+  if (typeof cia2 !== "string" || !/^[0-9a-f]{2}/i.test(cia2)) return fail("io.cia2.bytes is missing");
+  return { vic: { registers: Buffer.from(vic, "hex"), bank: Number.parseInt(cia2.slice(0, 2), 16) & 0x03 } };
+}
+
 export interface LoaderInput {
   /** The segments with the files that hold them, in address order. */
   segments: Array<Range & { files: string[] }>;
@@ -181,7 +224,7 @@ export function planLoader(input: LoaderInput): LoaderPlan {
   }
   if (plain.length > MAX_COPIES) throw new WireFailure("invalid-input", `The loader needs ${plain.length} copies; it can do at most ${MAX_COPIES}. Join segments in the unpacker capture (--range) or write the loader by hand.`);
   const copierImage = at;
-  const copierSize = COPIER_CODE_SIZE + COPY_ENTRY * plain.length + 2;
+  const copierSize = COPIER_CODE_SIZE + (state.vic === undefined ? 0 : VIC_SIZE) + COPY_ENTRY * plain.length + 2;
   const end = copierImage + copierSize - 1;
   if (end > LOAD_LIMIT) throw new WireFailure("invalid-input", `The loader would end at ${hex4(end)}, after ${hex4(LOAD_LIMIT)}: loading it would write the I/O area. The image is too large for one loader file.`);
 
@@ -286,7 +329,9 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     "        adc #7",
     "        tax",
     "        jmp .next",
-    `.done   lda #${hex2(port0)}`,
+    ".done",
+    ...vicLines(state),
+    `        lda #${hex2(port0)}`,
     "        sta $00",
     `        lda #${hex2(port1)}`,
     "        sta $01",
@@ -303,6 +348,12 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     ".count  !word 0",
     ".index  !byte 0",
     ".back   !byte 0",
+    ...(state.vic === undefined
+      ? []
+      : [
+          `.vicreg !byte ${VIC_DISPLAY_REGISTERS.map((item) => hex2(item.register)).join(",")}`,
+          `.vicval !byte ${VIC_DISPLAY_REGISTERS.map((item) => hex2(state.vic!.registers[item.register]!)).join(",")}`,
+        ]),
     ".table",
   );
   for (const copy of copies) {
@@ -322,3 +373,34 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     text: `${lines.join("\n")}\n`,
   };
 }
+
+/**
+ * The copier's VIC-II part (D60): with the I/O area visible it sets the
+ * display registers and the VIC bank of the entry state, then waits for the
+ * entry's raster line, so the program starts in the same phase of the frame.
+ */
+function vicLines(state: EntryState): string[] {
+  if (state.vic === undefined) return [];
+  const line = rasterLine(state.vic.registers);
+  return [
+    "        lda #$35",
+    "        sta $01",
+    `        ldx #${hex2(VIC_DISPLAY_REGISTERS.length - 1)}`,
+    ".vic    ldy .vicreg,x",
+    "        lda .vicval,x",
+    "        sta $d000,y",
+    "        dex",
+    "        bpl .vic",
+    "        lda $dd00",
+    "        and #$fc",
+    `        ora #${hex2(state.vic.bank)}`,
+    "        sta $dd00",
+    `.raster lda $d012`,
+    `        cmp #${hex2(line & 0xff)}`,
+    "        bne .raster",
+    "        lda $d011",
+    "        and #$80",
+    `        cmp #${hex2((line >> 1) & 0x80)}`,
+    "        bne .raster",
+  ];
+}

package/skills/c64-source/scripts/source.ts

@@ -7,7 +7,7 @@
 
 import { COVERAGE, formatC64Address } from "#src/c64.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
-import type { CommentPlacement, RegionType } from "#src/knowledge/schema.ts";
+import { isGeneratedFile, type CommentPlacement, type RegionType } from "#src/knowledge/schema.ts";
 import { hasZeroPageForm, MNEMONICS, MODE_LENGTH, OPCODES, takesAddress, type Mode } from "./opcodes.ts";
 
 export interface Range {
@@ -31,13 +31,10 @@ export interface SourceInput {
   referenceTargets: readonly number[];
   /** Joined coverage files (D40): an instruction that no run executed is marked (D49). */
   coverage?: Uint8Array;
-  /** Platform names (D52): the name of an address that knowledge does not name. */
-  platform?: ReadonlyMap<number, string>;
+  /** Platform names (D52): the name of an address that knowledge does not name, and the last address of its entry. */
+  platform?: ReadonlyArray<{ address: number; end: number; name: string }>;
 }
 
-/** Files that the generator writes itself; a module cannot have these names. */
-export const GENERATED_FILES = ["main.asm", "loader.asm", "constants.asm"] as const;
-
 const CODE_TYPES: readonly RegionType[] = ["code", "jumps", "dual-use"];
 const BYTES_PER_LINE = 8;
 const WORDS_PER_LINE = 4;
@@ -106,6 +103,24 @@ function operandValue(address: number, opcode: number, byteAt: (address: number)
   return low;
 }
 
+/**
+ * Each entry point inside a data region of the knowledge, with that region.
+ * A data region wins over an entry (D44, D48): Ghidra does not decode there,
+ * and the source has data there. A code region in the knowledge changes that (F-27).
+ */
+export function entriesInData<R extends { start: number; end: number; type: RegionType }>(entries: readonly number[], regions: readonly R[]): Array<{ entry: number; region: R }> {
+  return entries.flatMap((entry) => {
+    const region = regions.find((row) => entry >= row.start && entry <= row.end && !CODE_TYPES.includes(row.type));
+    return region === undefined ? [] : [{ entry, region }];
+  });
+}
+
+/** Why an image without its entry fails: the image does not hold the program (R2-02). Undefined when the entry is in a segment, or the image has no entry. */
+export function entryOutsideImage(entry: number | undefined, segments: readonly Range[]): string | undefined {
+  if (entry === undefined || segments.some((segment) => entry >= segment.start && entry <= segment.end)) return undefined;
+  return `The entry ${hex4(entry)} is in no segment of the image: the image does not hold the program. Capture it again with c64-unpacker loads or capture.`;
+}
+
 /** Splits the segments into pieces at module starts and lays out instructions and data. */
 export function layout(input: SourceInput): Layout {
   const inImage = (address: number) => input.segments.some((segment) => address >= segment.start && address <= segment.end);
@@ -116,7 +131,7 @@ export function layout(input: SourceInput): Layout {
   };
 
   for (const module of input.modules) {
-    if ((GENERATED_FILES as readonly string[]).includes(module.file)) throw new WireFailure("invalid-input", `The module at ${hex4(module.start)} has the file ${module.file}, which the generator writes itself. Give the module another file.`);
+    if (isGeneratedFile(module.file)) throw new WireFailure("invalid-input", `The module at ${hex4(module.start)} has the file ${module.file}, which the generator writes itself. Give the module another file.`);
   }
   const modules = [...input.modules].sort((a, b) => a.start - b.start);
   const unusedModules = modules.filter((module) => !inImage(module.start)).map(({ start, file }) => ({ start, file }));
@@ -184,10 +199,18 @@ export function layout(input: SourceInput): Layout {
   const symbols = new Map(input.symbols.map((symbol) => [symbol.address, symbol.name]));
   // A platform name that knowledge gives to another address, or that reads as an instruction, is not used.
   const knowledgeNames = new Set(input.symbols.map((symbol) => symbol.name));
-  const platform = new Map([...(input.platform ?? [])].filter(([, name]) => !knowledgeNames.has(name) && !MNEMONICS.has(name.toLowerCase())));
+  const platform = new Map((input.platform ?? []).filter(({ name }) => !knowledgeNames.has(name) && !MNEMONICS.has(name.toLowerCase())).map(({ address, name }) => [address, name]));
+  /** Addresses outside the image without a name of their own, inside a named platform entry of more bytes: the start of that entry (F-20). */
+  const insideEntry = new Map<number, number>();
   const use = (address: number) => {
     if (inImage(address)) wanted.add(address);
     else if (symbols.has(address) || platform.has(address)) outside.add(address);
+    else {
+      const entry = input.platform?.find((row) => address > row.address && address <= row.end && !inImage(row.address) && (symbols.has(row.address) || platform.has(row.address)));
+      if (entry === undefined) return;
+      outside.add(entry.address);
+      insideEntry.set(address, entry.address);
+    }
   };
   for (const piece of pieces) {
     for (const item of piece.items) {
@@ -226,6 +249,8 @@ export function layout(input: SourceInput): Layout {
     names.set(address, name);
     generatedLabels++;
   }
+  // The high byte of a vector is NMINV+1. A zero-page entry keeps zero-page instructions: its constant has two digits.
+  for (const [address, start] of insideEntry) names.set(address, `${names.get(start)!}+${address - start}`);
   return {
     pieces,
     names,
@@ -490,6 +515,8 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
     const out: string[] = [`; ${piece.title}`, `; ${hex4(piece.start)}-${hex4(piece.end)}`, ""];
     /** True while the instructions before have not executed: they form one range. */
     let running = false;
+    /** The line of the mark of the open range of instructions that did not execute. */
+    let markLine = 0;
     const head = (address: number) => {
       for (const text of lineComments.get(address) ?? []) out.push(`; ${text}`.trimEnd());
       const label = layout.names.get(address);
@@ -503,8 +530,12 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
           if (running) notExecuted.ranges.at(-1)!.end = item.address + item.length - 1;
           else {
             notExecuted.ranges.push({ start: item.address, end: item.address + item.length - 1 });
-            out.push("; not executed");
+            markLine = out.length;
+            out.push("");
           }
+          // The mark gives the range, so a reader finds it in the full list (D49).
+          const range = notExecuted.ranges.at(-1)!;
+          out[markLine] = `; not executed ${hex4(range.start)}-${hex4(range.end)}`;
           notExecuted.instructions++;
         }
         running = !executed;

package/skills/c64-static-analysis/SKILL.md

@@ -31,7 +31,7 @@ node <skill>/scripts/analyze.ts extracted/game.prg --entry '$080d' --decompile '
 | `--listing analysis/game.lst` | DXA only: write the disassembly listing to this project file. |
 | `--decompile '$0818'` | Ghidra only: decompile the routine at this address. Use it again for more routines, at most 32. |
 | `--flat64k` | The file is 64 KiB of memory from `$0000`, not a PRG. |
-| `--max-listed 20` | List at most this number of labels or functions. The default is 50. Use 0 to list none. |
+| `--max-listed 20` | List at most this number of labels, functions or candidates. The default is 50. Use 0 to list none. |
 | `--instructions analysis/instructions.json` | Ghidra only: write every instruction to this project file as JSON. Each has `address`, `bytes`, `mnemonic`, `mode` and `operand` in 6502 syntax. A branch, jump or call also has its `target`. With `--coverage`, `executed` tells if it ran. |
 | `--space drive8` | The knowledge space of the image: `drive8` for code from the 1541 drive, or `bank0` to `bank255` for a cartridge bank. The default is `c64`. The seeds come from that space, and the findings go into it. |
 | `--coverage coverage/attract.bin` | A coverage file of 64 KiB from `c64_memmap` (action `read` with `out`). Use it again for more runs. The executed code becomes entry points. |
@@ -63,9 +63,9 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
    - `changes` counts the symbols, regions and references that the analysis `added`, `changed`, `retired` or kept `unchanged`. `suppressed` counts the findings that the analysis did not write, because a removal blocks that place.
    - DXA: `regions` lists the code and data regions. `labels` gives the number of names that DXA found (`count`) and lists the first names (`listed`).
    - Ghidra: `functions` gives the number of routines that Ghidra found (`count`) and lists the first routines (`listed`). `decompilations` gives C-like code for the requested routines.
-   - If a list is not complete, `rest` gives the c64-knowledge command that lists all of them.
+   - If a list is not complete, `rest` gives the c64-knowledge command that lists all of them. For `candidates`, `rest` tells you to give a larger `--max-listed`.
    - `conflicts` lists the places where the analyzer and the current knowledge disagree.
-   - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). The script writes them as knowledge with the origin `heuristic`, and seeds their targets into the same analysis. `candidates` gives DOP padding and opcodes that the program wrote and then executed. The script does not write those. Look at them and decide.
+   - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). The script writes them as knowledge with the origin `heuristic`, and seeds their targets into the same analysis. `candidates` gives DOP padding (`dop`) and opcodes that the program wrote and then executed (`selfModified`). For `selfModified`, the write and the execution must be in one coverage file. Each list has a `count`. The script does not write the candidates. Look at them and decide.
    - With `--coverage`, a code finding replaces the DXA or Ghidra data where a run executed an instruction start. `coverageConflicts` lists the analyzer data regions where the coverage still shows executed code. Classify them as code with the c64-knowledge skill, or as `dual-use` when the bytes are also data.
 6. Give each important routine a name with the c64-knowledge skill. Then run the analysis again. The analyzers use the new names.
 
@@ -108,7 +108,7 @@ The exit status is 0 for a result, also with conflicts. The exit status is 1 for
 - `invalid-input` with a message about an entry point: no entry point is inside the program for Ghidra. Give one with `--entry`.
 - `stale-revision`: the knowledge changed during the analysis. The script recorded nothing. Run the analysis again.
 - `operation-failed` with a message about an incomplete result or listing: the analyzer did not give a complete result. The script recorded nothing. Tell the user.
-- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `notDecompiled`: Ghidra did not decompile these routines. Each entry has the reason. If the reason says that the decompiler did not start, tell the user the remedy in the reason. On macOS, Ghidra has no native decompiler until the user builds it: `./gradlew buildNatives` in the `support/gradle` directory of Ghidra.
 
 ## Handoffs

package/skills/c64-static-analysis/scripts/analyze.ts

@@ -9,6 +9,7 @@ import { dirname } from "node:path";
 import { parseArgs } from "node:util";
 
 import { COVERAGE, formatC64Address, parseC64Address, prgRange } from "#src/c64.ts";
+import { joinCoverage } from "#src/host-client/coverage.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { analyze as analyzeWithDxa } from "#src/native/dxa.ts";
@@ -21,7 +22,7 @@ import { currentRevision } from "#src/knowledge/read.ts";
 import { DEFAULT_SPACE, SPACE } from "#src/knowledge/schema.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { codeEntries, coverageConflicts, coverageEntries, imageReader, readCoverageFiles } from "./coverage.ts";
+import { codeEntries, coverageConflicts, coverageEntries, imageReader, readCoverageMaps } from "./coverage.ts";
 import { dxaFindings, ghidraFindings, seedsFromKnowledge } from "./findings.ts";
 import { findIdioms } from "./idioms.ts";
 import { instructionList } from "./instructions.ts";
@@ -38,8 +39,9 @@ const USAGE = `analyze.ts <image> [options]
                           mode, operand, target, executed) to this project file as JSON
   --coverage <file>       a coverage map of 64 KiB from c64_memmap (repeatable): its
                           executed code is seeded, and analyzer data over it is reported
-  --max-listed <n>        list at most n labels or functions (default 50, 0 for none);
-                          the counts are always given, and knowledge has all of them
+  --max-listed <n>        list at most n labels, functions or candidates (default 50,
+                          0 for none); the counts are always given, and knowledge has
+                          all labels and functions
   --space <space>         the knowledge space of the image: c64 (the default), drive8
                           for 1541 drive code, or bank0 to bank255 for a cartridge bank
 
@@ -158,7 +160,8 @@ async function run(argv: string[]): Promise<unknown> {
   if (space !== DEFAULT_SPACE && values.coverage !== undefined) throw new UsageError("--coverage works only in space c64");
   const imageKind = values.flat64k ? "flat64k" : "prg";
   const bytes = readProjectFile(image).bytes;
-  const coverage = readCoverageFiles(values.coverage ?? []);
+  const runs = readCoverageMaps(values.coverage ?? []);
+  const coverage = runs.length === 0 ? undefined : joinCoverage(runs);
   const byteAt = imageReader(bytes, imageKind);
   // With coverage, a code finding over an executed instruction start replaces the data of the other analyzer (D58), and the files are the evidence.
   const executed = coverage === undefined ? {} : { executed: (address: number) => (coverage[address]! & COVERAGE.ramExecute) !== 0 };
@@ -170,7 +173,7 @@ async function run(argv: string[]): Promise<unknown> {
   } catch (error) {
     throw new UsageError(`${image}: ${(error as Error).message}`);
   }
-  const idioms = findIdioms(byteAt, { start: loaded.start, end: loaded.end }, coverage);
+  const idioms = findIdioms(byteAt, { start: loaded.start, end: loaded.end }, runs);
 
   const reader = openForRead();
   const revision = currentRevision(reader);
@@ -192,7 +195,11 @@ async function run(argv: string[]): Promise<unknown> {
         revision: imported.revision,
         changes: { regions: imported.regions, references: imported.references },
         conflicts: imported.conflicts.map((conflict) => showConflict(conflict, "heuristic")),
-        candidates: { dop: idioms.candidates.dop.map(formatC64Address), selfModified: idioms.candidates.selfModified.map(formatC64Address) },
+        // Candidates are not knowledge: a larger --max-listed gives more of them.
+        candidates: {
+          dop: listed(idioms.candidates.dop, max, formatC64Address, "a larger --max-listed"),
+          selfModified: listed(idioms.candidates.selfModified, max, formatC64Address, "a larger --max-listed"),
+        },
       },
     };
   };

package/skills/c64-static-analysis/scripts/coverage.ts

@@ -5,7 +5,7 @@
 import type { DatabaseSync } from "node:sqlite";
 
 import { COVERAGE, instructionLength } from "#src/c64.ts";
-import { FULL_COVERAGE, readCoverageFiles as readFiles } from "#src/host-client/coverage.ts";
+import { FULL_COVERAGE, readCoverageMaps as readMaps } from "#src/host-client/coverage.ts";
 import { listRegions, type RegionRow } from "#src/knowledge/read.ts";
 import { CODE_REGION_TYPES, DEFAULT_SPACE, type Space } from "#src/knowledge/schema.ts";
 import { UsageError } from "#src/script.ts";
@@ -15,9 +15,9 @@ const FULL_MAP = FULL_COVERAGE;
 const FLOW_ENDS = new Set([0x00, 0x40, 0x4c, 0x60, 0x6c]);
 const ANALYZER_ORIGINS = new Set(["dxa", "ghidra", "heuristic"]);
 
-/** Reads coverage files and joins them: an address has every flag that any run gave it. */
-export function readCoverageFiles(paths: string[]): Uint8Array | undefined {
-  return readFiles(paths, (message) => {
+/** Reads coverage files, one map per file (a run). */
+export function readCoverageMaps(paths: string[]): Uint8Array[] {
+  return readMaps(paths, (message) => {
     throw new UsageError(message);
   });
 }

package/skills/c64-static-analysis/scripts/idioms.ts

@@ -1,10 +1,13 @@
 // 6502 idioms that hide code from a disassembler (D44): RTS dispatch tables,
 // JMP tables and BIT skips are found by their exact instruction patterns and
 // become heuristic findings and entry points; DOP padding and self-modified
-// opcodes are only reported. A table's length is not known statically:
-// entries count while each target is a plausible instruction in the program.
+// opcodes are only reported. A self-modified opcode is one that one run wrote
+// and executed: a copier's writes in one run and their execution in another
+// do not count (F-16). A table's length is not known statically: entries
+// count while each target is a plausible instruction in the program.
 
 import { COVERAGE } from "#src/c64.ts";
+import { joinCoverage } from "#src/host-client/coverage.ts";
 import type { NormalizedFindings } from "#src/knowledge/import.ts";
 import type { ImageByte } from "./coverage.ts";
 
@@ -22,7 +25,7 @@ export interface Idioms {
   /** Table ranges for the same run: they are data. */
   dataRanges: Array<{ start: number; end: number }>;
   counts: { rtsTables: number; jumpTables: number; bitSkips: number };
-  /** Seen in the coverage, not written: the LLM decides. */
+  /** Seen in the coverage, not written: the LLM decides. All of them: the result lists the first ones. */
   candidates: { dop: number[]; selfModified: number[] };
 }
 
@@ -38,7 +41,9 @@ const word = (byteAt: ImageByte, address: number) => {
   return low === undefined || high === undefined ? undefined : low | (high << 8);
 };
 
-export function findIdioms(byteAt: ImageByte, range: { start: number; end: number }, coverage?: Uint8Array): Idioms {
+/** `runs` are the coverage maps, one for each file. */
+export function findIdioms(byteAt: ImageByte, range: { start: number; end: number }, runs: readonly Uint8Array[] = []): Idioms {
+  const coverage = runs.length === 0 ? undefined : joinCoverage(runs);
   const regions: NormalizedFindings["regions"] = [];
   const references: NormalizedFindings["references"] = [];
   const entryPoints = new Set<number>();
@@ -113,14 +118,14 @@ export function findIdioms(byteAt: ImageByte, range: { start: number; end: numbe
     }
   }
 
-  // Candidates from the coverage: DOP padding that ran, and opcodes that the program wrote and then ran.
+  // Candidates from the coverage: DOP padding that ran, and opcodes that one run wrote and executed.
   const candidates = { dop: [] as number[], selfModified: [] as number[] };
   if (coverage !== undefined) {
+    const both = COVERAGE.ramWrite | COVERAGE.ramExecute;
     for (let address = range.start; address <= range.end; address++) {
-      const flags = coverage[address]!;
-      if ((flags & COVERAGE.ramExecute) === 0) continue;
-      if (DOPS.has(byteAt(address)!) && candidates.dop.length < MAX_TABLE) candidates.dop.push(address);
-      if ((flags & COVERAGE.ramWrite) !== 0 && candidates.selfModified.length < MAX_TABLE) candidates.selfModified.push(address);
+      if ((coverage[address]! & COVERAGE.ramExecute) === 0) continue;
+      if (DOPS.has(byteAt(address)!)) candidates.dop.push(address);
+      if (runs.some((run) => (run[address]! & both) === both)) candidates.selfModified.push(address);
     }
   }
 

package/skills/c64-testing/SKILL.md

@@ -86,7 +86,7 @@ PASS, FAIL or INCONCLUSIVE, the checkpoints and the smallest differences that ex
 - INCONCLUSIVE, "did not reach the checkpoint": one side did not reach the checkpoint in the frame limit. Find the reason with the c64-emulator skill. Do not report a FAIL.
 - INCONCLUSIVE, "has no symbol": one side has no symbol with that name. Add the name to the knowledge or to the rebuild source.
 - INCONCLUSIVE, "no emulator" or "could not run": the host runtime or the emulator failed. Tell the user the message.
-- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - A FAIL with only a `screen` difference: add `vicii` or `sprites` to the observation to find which chip state is different.
 - A program that uses random numbers: set the random seed with a `write` step on both sides. If that is not possible, observe only values that do not depend on the random numbers.
 - The two sides start differently, for example the original after a cracked intro. Give the steps that only one side needs a `side`. Then make the memory the same with a `normalize` step from the entry state of the c64-unpacker skill.

package/skills/c64-testing/scripts/scenario.ts

@@ -283,7 +283,7 @@ export function resolve(location: Location, symbols: Map<string, number>, side:
 interface Observation {
   memory: Array<{ label: string; address: number; bytes: number[]; tolerance: number; excluded: Array<{ offset: number; at: Location; reason: string }> }>;
   registers: Partial<Record<ObservedRegister, unknown>>;
-  screen?: { match: boolean; mismatchingPixels: number; mismatchRatio: number; bounds?: unknown };
+  screen?: { match: boolean; mismatchingPixels: number; comparedPixels: number; mismatchRatio: number; bounds?: unknown };
   vicii?: unknown;
   sprites?: unknown;
   /** PNG images for the files of a FAIL (D46): the side's screen, and on the rebuild the difference image. */
@@ -371,7 +371,7 @@ async function runSide(client: ViceSessionClient, scenario: Scenario, side: Side
           if (files) observation.png = shot.png;
         } else {
           const compared = await client.screenCompare({ baseline, maxMismatchRatio: step.screen.maxMismatchRatio ?? 0, mask: step.screen.mask ?? [], includeDiff: files });
-          observation.screen = { match: compared.match, mismatchingPixels: compared.mismatchingPixels, mismatchRatio: compared.mismatchRatio, ...(compared.bounds === undefined ? {} : { bounds: compared.bounds }) };
+          observation.screen = { match: compared.match, mismatchingPixels: compared.mismatchingPixels, comparedPixels: compared.comparedPixels, mismatchRatio: compared.mismatchRatio, ...(compared.bounds === undefined ? {} : { bounds: compared.bounds }) };
           if (files) {
             observation.png = (await client.screenCapture()).png;
             if (compared.diffPng !== undefined) observation.diffPng = compared.diffPng;

package/skills/c64-unpacker/SKILL.md

@@ -26,11 +26,11 @@ node <skill>/scripts/unpack.ts stages original/game.prg --steps input.json
 node <skill>/scripts/unpack.ts loads original/game.d64 --steps parts.json --out parts --drive
 ```
 
-`inspect` examines the file locally. `trace` and `capture` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `capture` stops the program when the CPU gets to the `--until` address. `stages` runs the program and finds each stage: a decruncher, an intro, a copier, and then the program. For each stage it gives the entry, the frames, the written memory (`wrote`) and the entry of the next stage (`next`). In `stages`, a `frames` step counts as run time, and a `runUntil` step is not possible.
+`inspect` examines the file locally. `trace` and `capture` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `capture` stops the program when the CPU gets to the `--until` address. `stages` runs the program and finds each stage: a decruncher, an intro, a copier, and then the program. For each stage it gives the entry, the frames, the written memory (`wrote`) and the entry of the next stage (`next`). In `stages` and `capture`, a `frames` step and a `runUntil` step with only `at` count as run time. `stages` refuses a `runUntil` step with `raster` or `memory`.
 
 | Option | Meaning |
 |---|---|
-| `--until '$c000'` | The address where the unpacked program starts. |
+| `--until '$c000'` | The address where the unpacked program starts. The capture stops there after the steps. To capture a later arrival at the address, add a `runUntil` step to an address after the first arrival. |
 | `--out unpacked/game.prg` | Where to write the result, relative to the project directory. |
 | `--range '$c000' '$cfff'` | Write this range as a PRG. Without it, the script writes all 64 KiB of RAM as a flat file. |
 | `--timeout-frames 3000` | How many frames the program can run before the capture stops (default 3000). |
@@ -64,16 +64,17 @@ A `type` step puts keys in the keyboard queue of the KERNAL. A program that read
    - `start`: the code at the SYS address. `jumpsOutside` and `writesOutside` give an address outside the loaded program, where the code jumps or writes.
    - `decodeLoops`: EOR instructions in loops that store with an index. This is usually decryption or decoding.
 2. Run `trace`. It gives the evidence from the run. Read `packing`:
-   - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the written code that runs at the end of the trace. When the trace ends in ROM code, for example in an interrupt, it is the written code that runs next. Its `start` is usually the entry point of the unpacked program. When no written code runs in 50 more frames, the result has no `runningRange` and no `suggestedUntil`.
+   - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the written code that runs at the end of the trace. When the trace ends in ROM code, for example in an interrupt, it is the written code that runs next. Its `start` is code that runs after the unpacking. It is not always the entry point of the program. When no written code runs in 50 more frames, the result has no `runningRange` and no `suggestedUntil`.
    - `unclear`: the program executed a small quantity of code that it wrote. This can be code that changes itself.
    - `unlikely`: the program executed no code that it wrote. If the program waits for a key or a joystick, it can move code after that input. Then use the c64-emulator skill.
 3. Find the address where the unpacked program starts:
-   - Run `stages`. The `entry` of the last stage is usually the start of the program.
+   - Run `stages`. The `entry` of the last stage is usually the start of the program. A routine that a stage writes and calls is part of that stage when it returns to the stage.
    - Or use `runningRange.start` from `trace`, or `suggestedUntil`. The CPU gets to `suggestedUntil` after the unpacking.
    - Or use the c64-emulator skill: set a breakpoint after the unpack loop, or look at the last JMP of the unpacker.
+   - Disassemble the code at the address with the c64-emulator skill. Make sure that it is the start of the program. The start of a program often sets the stack pointer, the interrupts and the vectors.
 4. Run `capture` with that address and a directory in `--out`. Give the same `--steps` as before. The directory gets:
    - `image.bin`: all 64 KiB of RAM at the entry.
-   - `image.json`: the entry, the segments, the vectors and the stages. A segment is a block that a stage wrote. Blocks with the code of an earlier stage are not segments. `writtenBy` tells which stage wrote the segment.
+   - `image.json`: the entry, the segments, the vectors and the stages. A segment is a block that a stage wrote. A block is not a segment when it holds the entry of a later stage before the program, and no stage wrote over that entry. The block with the capture entry is always a segment. Segments do not overlap. `writtenBy` tells the last stage that wrote into the segment.
    - One PRG for each segment.
    - `entry_state.json`: the registers, `$00` and `$01`, pages 0 to 3, the VIC, SID and CIA registers, and the vectors. `differsFromReset` lists the bytes that are not as a clean C64 has them at READY. A rebuild must make these bytes the same, because the program can read them.
 5. Make sure that the result is the application: the code at the entry must not be the unpacker again. A segment can be data that a loader left, for example intro graphics. Keep it until other evidence shows that the program does not use it.
@@ -113,7 +114,7 @@ Do not record the unpacker in the project knowledge, unless the user asks to exa
 
 The packing evidence, the stages, or the unpacked program with its image, segments and entry state in a directory of the project.
 
-For `loads`: `captures`, with the name, the PC, the segments and the drive file of each capture.
+For `loads`: `captures`, with the name, the PC, the segments and the drive file of each capture. `keyWait: true` tells that the CPU was in the KERNAL wait for a key.
 
 The exit status is 0 for a result. The exit status is 1 for `traced: false`, for `captured: false`, for `loaded: false` and for an error. The exit status is 2 for a wrong argument.
 
@@ -122,10 +123,11 @@ The exit status is 0 for a result. The exit status is 1 for `traced: false`, for
 - `traced: false`: the emulator did not load the program into memory in the time limit. The reason gives the load address. Make sure that the file is a PRG that the C64 can load.
 - `captured: false`: the program did not get to the address in the time limit. The reason tells where it stopped. Find a better address with the c64-emulator skill, or give more frames. If it stopped in a key wait, give `--steps` with a key.
 - A step did not reach its target: the reason names the step. Change the step or give it more frames.
+- `loaded: false` and no capture has a segment: the program did not load a part, or it did not start. `keyWait: true` on a capture tells that the C64 waited at READY. or at an INPUT statement. For a tape image, read `emulatorFlaw`. A known VICE flaw can stop a tape load. Tell the user to install the latest VICE.
 - Do not name a packer from weak evidence. The script never names one.
 - Some programs unpack in more than one stage. Run `stages` to find each stage. Capture at the entry of the last stage. Make sure that it is the application and not a second unpacker.
 - `not-found` or `invalid-input`: a path or an argument is wrong. Read the message.
-- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 
 ## Handoffs
 

package/skills/c64-unpacker/scripts/loads.ts

@@ -24,6 +24,8 @@ const DRIVE_RAM = 0x0800;
 const FIRST_SEGMENT_ADDRESS = 0x0400;
 /** The KERNAL LOAD entry in the jump table. */
 const KERNAL_LOAD = 0xffd5;
+/** The KERNAL loop that waits for a key at READY. or at an INPUT statement. */
+const KERNAL_KEY_WAIT = { start: 0xe5cd, end: 0xe5d5 };
 
 /** Reads and checks the steps file of loads: action steps with $ addresses, and capture steps with new names. */
 export function readLoadSteps(path: string): LoadStep[] {
@@ -100,6 +102,8 @@ export async function loads(program: string, options: { out: string; steps: Load
     let loadedProgram: Buffer | undefined;
     /** False while the map holds the writes of the KERNAL RAM test. */
     let writesKnown = true;
+    /** A known flaw of the host's VICE version that a tape load meets (D56). */
+    let emulatorFlaw: string | undefined;
     if (program.toLowerCase().endsWith(".prg")) {
       const { bytes } = readProjectFile(program);
       if (!(await autostartLoaded(client, program, bytes))) return { output: { loaded: false, reason: `The program was not in memory after ${LOAD_LIMIT_FRAMES} frames.` }, failed: true };
@@ -114,7 +118,7 @@ export async function loads(program: string, options: { out: string; steps: Load
       // A disk, tape or cartridge: VICE loads and starts it. The RAM test of the KERNAL puts back what it writes.
       previous = await readRam(client, 0x0000, 0x10000);
       await client.memmap({ action: "clear" });
-      await client.autostart({ path: program, index: 0, run: true });
+      ({ emulatorFlaw } = await client.autostart({ path: program, index: 0, run: true }));
       writesKnown = false;
       if (!program.toLowerCase().endsWith(".crt")) {
         // The map starts again where the KERNAL LOAD starts, after the RAM test: then it holds only what the program wrote.
@@ -178,10 +182,12 @@ export async function loads(program: string, options: { out: string; steps: Load
         }),
       );
       write("entry_state.json", json(entryState(registers, state, vectors)));
+      const keyWait = registers.pc >= KERNAL_KEY_WAIT.start && registers.pc <= KERNAL_KEY_WAIT.end;
       captures.push({
         capture: step.capture,
         out: directory,
         pc: formatC64Address(registers.pc),
+        ...(keyWait ? { keyWait: true } : {}),
         segments: segments.map(showRange),
         ...(small === 0 ? {} : { smallChanges: small }),
         ...(drive === undefined ? {} : { drive: drive.file }),
@@ -190,6 +196,11 @@ export async function loads(program: string, options: { out: string; steps: Load
       await client.memmap({ action: "clear" });
       writesKnown = true;
     }
+    if (captures.length > 0 && captures.every((capture) => (capture.segments as unknown[]).length === 0)) {
+      const waits = captures.some((capture) => capture.keyWait === true) ? " The C64 waited for a key at READY. or at an INPUT statement, so the load ended or did not start." : "";
+      const reason = `No capture has a segment: the program changed no block of RAM from ${formatC64Address(FIRST_SEGMENT_ADDRESS)} on.${waits}`;
+      return { output: { loaded: false, reason, captures, ...(emulatorFlaw === undefined ? {} : { emulatorFlaw }) }, failed: true };
+    }
     return { output: { loaded: true, captures }, failed: false };
   } finally {
     await client.close();