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

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

@@ -25,9 +25,9 @@ import { GHIDRA_LIMITS, type AssembledSymbol, type Diagnostic } from "#src/nativ
 import { platformNames } from "#src/platform.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { LOADER_JUMP, planLoader, readEntryState, simulate, type EntryState, type LoaderPlan } from "./loader.ts";
+import { LOADER_JUMP, planLoader, rasterLine, readEntryState, simulate, VIC_DISPLAY_REGISTERS, type EntryState, type LoaderPlan } from "./loader.ts";
 import { OPCODES } from "./opcodes.ts";
-import { instructionText, layout, literalOperand, probeForms, render, type Layout, type Range } from "./source.ts";
+import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, type Layout, type Range } from "./source.ts";
 
 const USAGE = `generate.ts <image> --out <dir> [options]
 
@@ -36,7 +36,8 @@ const USAGE = `generate.ts <image> --out <dir> [options]
   --out <dir>        the directory for the source files, relative to the project
   --entry <address>  an entry point for Ghidra, for example '$080d' (repeatable)
   --coverage <file>  a coverage map of 64 KiB from c64_memmap (repeatable): code
-                     that no run executed is marked and listed
+                     that no run executed is marked and listed; <dir>/not_executed.json
+                     has all of its ranges
   --space <space>    the knowledge space of the image: c64 (the default), drive8, or
                      bank0 to bank255; --coverage and --loader are for c64 only
   --loader           also write loader.asm and loader.prg: the loader copies the
@@ -129,6 +130,8 @@ async function decode(image: Image, knowledge: ReturnType<typeof readKnowledge>,
   }
   const entryPoints = [...seeds].filter(inImage).sort((a, b) => a - b);
   if (entryPoints.length === 0) {
+    // An entry in no segment is a capture fault: the image is data only, and the result says entryOutside (R3-01).
+    if (image.entry !== undefined && !inImage(image.entry)) return new Map();
     throw new UsageError("Ghidra needs an entry point: give --entry, or record a routine or a code region in knowledge with the c64-knowledge skill");
   }
   const dataRanges = knowledge.regions
@@ -276,6 +279,30 @@ async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image:
     differ("sp", registers.sp, state.sp);
     const flags = (["n", "v", "d", "i", "z", "c"] as const).reduce((value, name, index) => value | (registers.flags[name] ? [0x80, 0x40, 0x08, 0x04, 0x02, 0x01][index]! : 0), 0);
     differ("flags", flags, state.flags & 0xcf);
+    if (state.vic !== undefined) {
+      // The display registers and the raster line (D60): the loader waited for the line, so the jump comes in it or the next one.
+      const vic = Buffer.from((await client.ioRead(0xd000, 0x2f)).data, "hex");
+      for (const { register, mask } of VIC_DISPLAY_REGISTERS) differ(formatC64Address(0xd000 + register), vic[register]! & mask, state.vic.registers[register]! & mask);
+      differ("the VIC bank", Buffer.from((await client.ioRead(0xdd00, 1)).data, "hex")[0]! & 0x03, state.vic.bank);
+      const line = rasterLine(vic);
+      const wanted = rasterLine(state.vic.registers);
+      if (line !== wanted && line !== wanted + 1) differences.push(`the raster line is ${line}, not ${wanted}`);
+    }
+    if (plan.cia !== undefined) {
+      // The CIA timers (D63): at the jump a running timer is 3 cycles, the JMP, before its value at the entry.
+      const chips = (await client.cia("both")).chips;
+      const word = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+      const differWord = (what: string, got: number, wanted: number) => got !== wanted && differences.push(`${what} is ${word(got)}, not ${word(wanted)}`);
+      for (const timer of plan.cia.timers) {
+        const chip = chips[timer.cia - 1]!;
+        const name = `CIA ${timer.cia} timer ${timer.timer}`;
+        const [counter, latch, control] = timer.timer === "A" ? [chip.timerA, chip.latchA, chip.controlA] : [chip.timerB, chip.latchB, chip.controlB];
+        differ(`${name} control`, control, timer.control);
+        differWord(`${name} latch`, latch, timer.latch);
+        if (timer.counterAtJump !== undefined) differWord(`${name} counter`, counter, timer.counterAtJump);
+      }
+      plan.cia.masks.forEach((mask, index) => differ(`CIA ${index + 1} interrupt mask`, chips[index]!.interruptMask, mask));
+    }
     return { verified: differences.length === 0, differences: differences.slice(0, MAX_LISTED) };
   } finally {
     await client.close();
@@ -284,8 +311,10 @@ async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image:
 
 /** The first words of every file that the script writes. */
 const GENERATED_MARK = "; Generated by c64-source";
+/** The file with every range of instructions that no run executed (D49). */
+const NOT_EXECUTED_FILE = "not_executed.json";
 
-/** Removes the .asm files of an earlier run that this run does not write, and an earlier loader.prg; other files stay. */
+/** Removes the .asm files of an earlier run that this run does not write, and an earlier loader.prg and not_executed.json; other files stay. */
 function removeOldFiles(out: string, keep: ReadonlySet<string>): void {
   const directory = resolveProjectPath(out);
   if (!existsSync(directory)) return;
@@ -293,7 +322,7 @@ function removeOldFiles(out: string, keep: ReadonlySet<string>): void {
     if (!entry.isFile()) continue;
     const name = entry.name;
     const path = join(directory, name);
-    if (name === "loader.prg") rmSync(path, { force: true });
+    if (name === "loader.prg" || name === NOT_EXECUTED_FILE) rmSync(path, { force: true });
     else if (name.endsWith(".asm") && !keep.has(name) && readFileSync(path, "utf8").startsWith(GENERATED_MARK)) rmSync(path, { force: true });
   }
 }
@@ -344,16 +373,18 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     referenceTargets: knowledge.references.map((reference) => reference.to),
     ...(coverage === undefined ? {} : { coverage }),
     // The platform names are C64 names: drive code and banks get none.
-    ...(space === DEFAULT_SPACE ? { platform: new Map(platformNames().map((item) => [item.address, item.name])) } : {}),
+    ...(space === DEFAULT_SPACE ? { platform: platformNames() } : {}),
   });
   const asBytes = await probe(laid);
   const header = [`Generated by c64-source from ${image.path}${space === DEFAULT_SPACE ? "" : ` in space ${space}`} and knowledge revision ${knowledge.revision}.`, "Change names, comments, regions and modules in knowledge, then generate again."];
   const rendered = render(laid, asBytes, header);
   const files = [...rendered.files];
   let loader: LoaderPlan | undefined;
+  // An image without its entry has no program: the source is still written and checked, but the run fails (R2-02).
+  const missingEntry = entryOutsideImage(image.entry, image.segments);
   // A loader that cannot be planned does not stop the source: the source is written and checked, and the result says why.
-  let loaderRefused: string | undefined;
-  if (state !== undefined) {
+  let loaderRefused: string | undefined = state === undefined ? undefined : missingEntry;
+  if (state !== undefined && missingEntry === undefined) {
     const segments = image.segments.map((segment) => ({ ...segment, files: laid.pieces.filter((piece) => piece.start >= segment.start && piece.start <= segment.end).map((piece) => piece.file) }));
     try {
       loader = planLoader({ segments, byteAt: image.byteAt, state, entry: image.entry!, header: [`Loader generated by c64-source from ${image.path}.`, "It copies the segments into place, sets the entry state and jumps to the entry."] });
@@ -367,6 +398,12 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   for (const [index, file] of files.entries()) if (!file.text.startsWith(GENERATED_MARK)) files[index] = { ...file, text: `${GENERATED_MARK}. Do not edit: change the knowledge and generate again.\n${file.text}` };
   removeOldFiles(values.out, new Set(files.map((file) => file.name)));
   for (const file of files) writeProjectFile(`${values.out}/${file.name}`, Buffer.from(file.text, "utf8"), { what: "--out" });
+  const showRange = (range: Range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) });
+  const inData = entriesInData(entries, knowledge.regions);
+  if (rendered.notExecuted !== undefined) {
+    const all = { image: image.path, revision: knowledge.revision, instructions: rendered.notExecuted.instructions, ranges: rendered.notExecuted.ranges.map(showRange) };
+    writeProjectFile(`${values.out}/${NOT_EXECUTED_FILE}`, Buffer.from(`${JSON.stringify(all, null, 2)}\n`, "utf8"), { what: "--out" });
+  }
 
   const output: Record<string, unknown> = {
     out: values.out,
@@ -375,7 +412,12 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     instructions: rendered.instructions,
     dataBytes: rendered.dataBytes,
     ...(rendered.undecodedBytes === 0 ? {} : { undecodedBytes: rendered.undecodedBytes }),
+    ...(missingEntry === undefined ? {} : { entryOutside: { entry: formatC64Address(image.entry!), reason: missingEntry } }),
     labels: { named: laid.namedLabels, generated: laid.generatedLabels },
+    // An --entry in a data region decodes nothing: the result says so, and a code region in the knowledge changes it (F-27).
+    ...(inData.length === 0
+      ? {}
+      : { entriesInData: inData.map(({ entry, region }) => ({ entry: formatC64Address(entry), region: { ...showRange(region), type: region.type }, origin: region.origin })) }),
     ...(rendered.asBytes.length === 0
       ? {}
       : { asBytes: { count: rendered.asBytes.length, listed: rendered.asBytes.slice(0, MAX_LISTED).map((item) => ({ address: formatC64Address(item.address), instruction: item.text })) } }),
@@ -385,7 +427,8 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
           notExecuted: {
             instructions: rendered.notExecuted.instructions,
             ranges: rendered.notExecuted.ranges.length,
-            listed: rendered.notExecuted.ranges.slice(0, MAX_LISTED).map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) })),
+            listed: rendered.notExecuted.ranges.slice(0, MAX_LISTED).map(showRange),
+            all: `${values.out}/${NOT_EXECUTED_FILE}`,
           },
         }),
     ...(laid.unusedModules.length === 0 ? {} : { unusedModules: laid.unusedModules.map((module) => ({ start: formatC64Address(module.start), file: module.file })) }),
@@ -400,7 +443,7 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   output.check = checked;
   if (!checked.identical) return { output: { ...output, ...notBuilt("The source does not assemble to the image, and the loader includes it.") }, failed: true };
   if (loaderRefused !== undefined) return { output: { ...output, loader: { verified: false, reason: loaderRefused } }, failed: true };
-  if (loader === undefined || state === undefined) return { output, failed: false };
+  if (loader === undefined || state === undefined) return { output, failed: missingEntry !== undefined };
 
   const loaderBuilt = await assembleFiles(files, "loader.asm");
   if (loaderBuilt.program === undefined) return { output: { ...output, loader: { verified: false, reason: "loader.asm does not assemble.", diagnostics: loaderBuilt.diagnostics.slice(0, MAX_LISTED) } }, failed: true };
@@ -431,6 +474,8 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     copier: formatC64Address(loader.copier),
     stackByte: formatC64Address(loader.stackByte),
     ...ran,
+    // What the loader cannot set as it was at the entry (D63).
+    ...(loader.cia === undefined || loader.cia.limits.length === 0 ? {} : { limits: loader.cia.limits }),
   };
   return { output, failed: !ran.verified };
 }

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

@@ -1,5 +1,7 @@
 // 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
+// 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 the CIA timers and interrupt masks (D63), 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
@@ -20,6 +22,41 @@ 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 };
+  /** CIA 1 and CIA 2 at the entry (D63). */
+  cia?: [EntryCia, EntryCia];
+}
+
+/** A CIA at the entry: $xx00-$xx0f as a read without side effects gives them, and what no read gives. */
+export interface EntryCia {
+  registers: Uint8Array;
+  latchA: number;
+  latchB: number;
+  interruptMask: 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 +94,8 @@ 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),
+    ...readCia(value, fail),
   };
 }
 
@@ -86,6 +125,8 @@ export interface LoaderPlan {
   stackByte: number;
   end: number;
   text: string;
+  /** The CIA timers and masks that the loader sets, when the entry state has them (D63). */
+  cia?: CiaPlan;
 }
 
 /** The label of the loader's jump to the entry, in ACME's symbol list. */
@@ -97,9 +138,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 +193,161 @@ 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 } };
+}
+
+function readCia(value: Record<string, any>, fail: (what: string) => never): { cia: [EntryCia, EntryCia] } | Record<string, never> {
+  if (value.cia === undefined) return {};
+  const chip = (name: "cia1" | "cia2"): EntryCia => {
+    const bytes = value.io?.[name]?.bytes;
+    if (typeof bytes !== "string" || !/^[0-9a-f]{32}$/i.test(bytes)) return fail(`io.${name}.bytes is not 16 bytes of hex`);
+    const hidden = value.cia[name];
+    const number = (item: unknown, what: string, max: number) => (Number.isInteger(item) && (item as number) >= 0 && (item as number) <= max ? (item as number) : fail(`cia.${name}.${what} is not a number from 0 to ${max}`));
+    return { registers: Buffer.from(bytes, "hex"), latchA: number(hidden?.latchA, "latchA", 0xffff), latchB: number(hidden?.latchB, "latchB", 0xffff), interruptMask: number(hidden?.interruptMask, "interruptMask", 0x1f) };
+  };
+  return { cia: [chip("cia1"), chip("cia2")] };
+}
+
+/** One CIA timer that the loader sets, and what the check of the loader expects of it at the jump. */
+export interface CiaTimerPlan {
+  cia: 1 | 2;
+  timer: "A" | "B";
+  /** The control register as a read gives it: without bit 4, the force load. */
+  control: number;
+  latch: number;
+  /** The counter at the jump, 3 cycles before the entry; undefined when the loader cannot set it. */
+  counterAtJump?: number;
+}
+
+export interface CiaPlan {
+  timers: CiaTimerPlan[];
+  masks: [number, number];
+  /** What the loader cannot set as it was at the entry. */
+  limits: string[];
+}
+
+/**
+ * The CIA timers as the KERNAL leaves them when RUN starts the loader, on a
+ * PAL C64: only CIA 1 timer A runs, for the 60 Hz interrupt. A timer that the
+ * entry has in this state is not written. The loader check reads every timer.
+ */
+const KERNAL_TIMERS: ReadonlyArray<{ control: number; latch: number; counter?: number }> = [
+  { control: 0x01, latch: 0x4025 },
+  { control: 0x08, latch: 0xffff, counter: 0xffff },
+  { control: 0x08, latch: 0xffff, counter: 0xffff },
+  { control: 0x08, latch: 0xffff, counter: 0xffff },
+];
+const KERNAL_MASKS: readonly [number, number] = [0x01, 0x00];
+/** Cycles from the end of the CIA part to the entry: $00, $01, the stack pointer, the flags, A, X, Y, PLP and JMP. */
+const TAIL_CYCLES = 33;
+/** Cycles after the write that starts a CIA timer in which it does not count yet, measured in VICE. */
+const CIA_START_DELAY = 1;
+/** Cycles of one raster line of a PAL C64. */
+const LINE_CYCLES = 63;
+const PAL_LINES = 312;
+
+interface Op {
+  text: string;
+  bytes: number;
+  cycles: number;
+}
+
+/**
+ * The copier's CIA part (D63), after the raster wait: the timers and
+ * interrupt masks of the entry state. A running timer is stopped, loaded
+ * with its counter at the entry plus the cycles to the entry, started, and
+ * given its latch, so it counts to the entry's value just at the entry.
+ * Then the interrupt flags that the copy left are read away.
+ */
+export function ciaSection(state: EntryState): { ops: Op[]; plan: CiaPlan } | undefined {
+  if (state.cia === undefined) return undefined;
+  const lda = (value: number): Op => ({ text: `lda #${hex2(value)}`, bytes: 2, cycles: 2 });
+  const sta = (address: number): Op => ({ text: `sta ${hex4(address)}`, bytes: 3, cycles: 4 });
+  const limits: string[] = [];
+  const timers: CiaTimerPlan[] = [];
+  const disable: Op[] = [];
+  const loads: Array<Op | ((cycles: number[]) => Op)> = [];
+  const starts: Op[] = [];
+  const latches: Op[] = [];
+  const acks: Op[] = [];
+  const masks: Op[] = [];
+  /** For each running timer: its index in starts, and how its load value follows from the cycles after its start. */
+  const running: Array<{ start: number; counter: number; latch: number; system: boolean; name: string; plan: CiaTimerPlan }> = [];
+  state.cia.forEach((chip, index) => {
+    const id = (index + 1) as 1 | 2;
+    const base = index === 0 ? 0xdc00 : 0xdd00;
+    let touched = false;
+    for (const timer of ["A", "B"] as const) {
+      const at = timer === "A" ? 0x04 : 0x06;
+      const controlAt = base + (timer === "A" ? 0x0e : 0x0f);
+      const control = chip.registers[timer === "A" ? 0x0e : 0x0f]! & 0xef;
+      const counter = chip.registers[at]! | (chip.registers[at + 1]! << 8);
+      const latch = timer === "A" ? chip.latchA : chip.latchB;
+      const name = `CIA ${id} timer ${timer}`;
+      const plan: CiaTimerPlan = { cia: id, timer, control, latch, counterAtJump: counter };
+      timers.push(plan);
+      const kernal = KERNAL_TIMERS[index * 2 + (timer === "A" ? 0 : 1)]!;
+      const runs = (control & 0x01) !== 0;
+      if (!runs && control === kernal.control && latch === kernal.latch && counter === kernal.counter) continue;
+      touched = true;
+      // Stopped, a write of the high latch byte also loads the counter.
+      loads.push(lda(control & 0xee), sta(controlAt));
+      if (runs) {
+        // Timer A counts system cycles without bit 5, timer B without bits 5 and 6; other inputs do not count in the loader.
+        const system = timer === "A" ? (control & 0x20) === 0 : (control & 0x60) === 0;
+        const slot = running.length;
+        running.push({ start: starts.length, counter, latch, system, name, plan });
+        loads.push((values) => lda(values[slot]! & 0xff), sta(base + at), (values) => lda(values[slot]! >> 8), sta(base + at + 1));
+        starts.push(lda(control), sta(controlAt));
+        latches.push(lda(latch & 0xff), sta(base + at), lda(latch >> 8), sta(base + at + 1));
+        if (system) plan.counterAtJump = counter + 3;
+        continue;
+      }
+      loads.push(lda(counter & 0xff), sta(base + at), lda(counter >> 8), sta(base + at + 1));
+      if (latch === counter) continue;
+      if (latch >> 8 === counter >> 8) {
+        loads.push(lda(latch & 0xff), sta(base + at));
+        continue;
+      }
+      // The high byte loads the counter of a stopped timer too.
+      loads.push(lda(latch & 0xff), sta(base + at), lda(latch >> 8), sta(base + at + 1));
+      plan.counterAtJump = latch;
+      limits.push(`${name} is stopped with the counter $${counter.toString(16).padStart(4, "0")} and the latch $${latch.toString(16).padStart(4, "0")}: a stopped CIA timer loads its latch, so the counter is the latch.`);
+    }
+    const mask = chip.interruptMask;
+    if (mask !== KERNAL_MASKS[index]) {
+      disable.push(lda(0x7f), sta(base + 0x0d));
+      if (mask !== 0) masks.push(lda(0x80 | mask), sta(base + 0x0d));
+      touched = true;
+    }
+    if (touched) acks.push({ text: `lda ${hex4(base + 0x0d)}`, bytes: 3, cycles: 4 });
+    const flags = chip.registers[0x0d]! & 0x1f;
+    if (flags !== 0) limits.push(`CIA ${id} has the interrupt flags $${flags.toString(16).padStart(2, "0")} at the entry: only an event sets a flag, so the loader cannot.`);
+  });
+  if (loads.length === 0 && disable.length === 0) return { ops: [], plan: { timers, masks: [state.cia[0].interruptMask, state.cia[1].interruptMask], limits } };
+  // The cycles from each start write to the entry: what follows it here, and the tail.
+  const after = [...starts, ...latches, ...acks, ...masks];
+  const values = running.map((item) => {
+    const followers = after.slice(item.start + 2).reduce((sum, op) => sum + op.cycles, 0);
+    if (!item.system) return item.counter;
+    const load = item.counter + followers + TAIL_CYCLES - CIA_START_DELAY;
+    if (load <= 0xffff) return load;
+    limits.push(`${item.name} counts from $${item.counter.toString(16).padStart(4, "0")} at the entry: the loader cannot start it so near $ffff without an underflow, so the counter differs.`);
+    delete item.plan.counterAtJump;
+    return item.counter;
+  });
+  const pre: Op[] = state.vic === undefined ? [lda(0x35), { text: "sta $01", bytes: 2, cycles: 3 }] : [];
+  const ops = [...pre, ...disable, ...loads.map((op) => (typeof op === "function" ? op(values) : op)), ...after];
+  return { ops, plan: { timers, masks: [state.cia[0].interruptMask, state.cia[1].interruptMask], limits } };
+}
+
 export interface LoaderInput {
   /** The segments with the files that hold them, in address order. */
   segments: Array<Range & { files: string[] }>;
@@ -179,9 +380,13 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     }
     at += block.range.end - block.range.start + 1;
   }
-  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 cia = ciaSection(state);
+  const ciaSize = cia === undefined ? 0 : cia.ops.reduce((sum, op) => sum + op.bytes, 0);
+  // The CIA part takes room from the copy table in the copier's two pages.
+  const maxCopies = Math.min(MAX_COPIES, Math.floor((COPIER_LIMIT - COPIER_CODE_SIZE - (state.vic === undefined ? 0 : VIC_SIZE) - ciaSize - 2) / COPY_ENTRY));
+  if (plain.length > maxCopies) throw new WireFailure("invalid-input", `The loader needs ${plain.length} copies; it can do at most ${maxCopies}. 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) + ciaSize + 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 +491,11 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     "        adc #7",
     "        tax",
     "        jmp .next",
-    `.done   lda #${hex2(port0)}`,
+    ".done",
+    // The CIA part runs after the raster wait: the wait ends its whole lines earlier, so the entry comes in its line.
+    ...vicLines(state, Math.floor((cia?.ops.reduce((sum, op) => sum + op.cycles, 0) ?? 0) / LINE_CYCLES)),
+    ...(cia === undefined ? [] : cia.ops.map((op) => `        ${op.text}`)),
+    `        lda #${hex2(port0)}`,
     "        sta $00",
     `        lda #${hex2(port1)}`,
     "        sta $01",
@@ -303,6 +512,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) {
@@ -320,5 +535,37 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     stackByte,
     end,
     text: `${lines.join("\n")}\n`,
+    ...(cia === undefined ? {} : { cia: cia.plan }),
   };
 }
+
+/**
+ * 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, earlier: number): string[] {
+  if (state.vic === undefined) return [];
+  const line = (rasterLine(state.vic.registers) - earlier + PAL_LINES) % PAL_LINES;
+  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,8 @@
 
 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 { ANALYZERS } from "#src/knowledge/import.ts";
+import { isGeneratedFile, type CommentPlacement, type Origin, type RegionType } from "#src/knowledge/schema.ts";
 import { hasZeroPageForm, MNEMONICS, MODE_LENGTH, OPCODES, takesAddress, type Mode } from "./opcodes.ts";
 
 export interface Range {
@@ -23,7 +24,8 @@ export interface SourceInput {
   entry?: number;
   /** Where Ghidra decoded an instruction, with its length. */
   instructions: ReadonlyMap<number, number>;
-  symbols: ReadonlyArray<{ address: number; name: string }>;
+  /** Without an origin, a symbol counts as a user or LLM name. */
+  symbols: ReadonlyArray<{ address: number; name: string; origin?: Origin }>;
   regions: ReadonlyArray<{ start: number; end: number; type: RegionType; element?: number }>;
   comments: ReadonlyArray<{ address: number; placement: CommentPlacement; text: string }>;
   modules: ReadonlyArray<{ start: number; file: string; title?: string }>;
@@ -31,13 +33,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 +105,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 +133,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 }));
@@ -181,13 +198,23 @@ export function layout(input: SourceInput): Layout {
   const wanted = new Set<number>();
   const want = (address: number) => inImage(address) && wanted.add(address);
   const outside = new Set<number>();
-  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]));
+  // An analyzer name (DXA's ld020) gives way to the platform name (EXTCOL); a user or LLM name wins (D61).
+  const isAnalyzer = (origin: Origin | undefined) => (ANALYZERS as readonly (Origin | undefined)[]).includes(origin);
+  const symbols = new Map(input.symbols.filter((symbol) => !(isAnalyzer(symbol.origin) && platform.has(symbol.address))).map((symbol) => [symbol.address, symbol.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 +253,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 +519,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 +534,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 executed (`selfModified`). For `selfModified`, the write and the execution must be in one coverage file. A coverage file does not record the order. Thus a candidate can also be code that ran first, and that the program then wrote over. To prevent this, save one coverage file for each part of the program, for example the intro and the game. Clear the memory map between the parts. 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