@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.21

package/src/native/ghidra/language/c64rt_6510.slaspec

@@ -263,13 +263,16 @@ REL: target      is rel [ target = inst_next + rel; ] { export *:2 target; }
 }
 
 # BRK skips its padding byte: the return address is two bytes on.
+# The vector at $FFFE is in ROM unless the program banks the KERNAL out, and
+# the analysis cannot know the banking. Thus BRK ends the flow, and Ghidra
+# does not follow the RAM bytes at $FFFE of a flat image (R2-07).
 :BRK is op=0x00 {
 	*:2 (SP - 1) = inst_next + 1;
 	SP = SP - 2;
 	pushP(1);
 	I = 1;
 	local vector:2 = 0xfffe;
-	goto [*:2 vector];
+	return [*:2 vector];
 }
 
 :CLC is op=0x18 { C = 0; }

package/src/native/ghidra/scripts/C64Export.java

@@ -2,7 +2,8 @@
 //
 // Writes the structural result for the loaded image: functions with the
 // source of their names, code and defined-data regions, memory references
-// from instructions, and the requested decompilations within their bounds.
+// from instructions, every instruction with its bytes, mnemonic, operand
+// text and flow targets (D44), and the requested decompilations within their bounds.
 //@category c64-re-tools
 
 import java.io.FileReader;
@@ -53,6 +54,7 @@ public class C64Export extends GhidraScript {
 		out.add("functions", functions(coverage));
 		out.add("regions", regions(coverage));
 		out.add("references", references(coverage));
+		out.add("instructions", instructions(coverage));
 		JsonArray notDecompiled = new JsonArray();
 		out.add("decompilations", decompile(request, notDecompiled));
 		out.add("notDecompiled", notDecompiled);
@@ -156,6 +158,36 @@ public class C64Export extends GhidraScript {
 		return references;
 	}
 
+	/** Every instruction in the coverage, in address order, as Ghidra decoded it with the 6510 language. */
+	private JsonArray instructions(AddressSet coverage) throws Exception {
+		JsonArray instructions = new JsonArray();
+		for (Instruction instruction : currentProgram.getListing().getInstructions(coverage, true)) {
+			JsonObject item = new JsonObject();
+			item.addProperty("address", instruction.getMinAddress().getOffset());
+			StringBuilder bytes = new StringBuilder();
+			for (byte value : instruction.getBytes()) {
+				bytes.append(String.format("%02x", value & 0xff));
+			}
+			item.addProperty("bytes", bytes.toString());
+			item.addProperty("mnemonic", instruction.getMnemonicString().toLowerCase());
+			StringBuilder operands = new StringBuilder();
+			for (int index = 0; index < instruction.getNumOperands(); index++) {
+				if (index > 0) {
+					operands.append(",");
+				}
+				operands.append(instruction.getDefaultOperandRepresentation(index));
+			}
+			item.addProperty("operands", operands.toString());
+			JsonArray flows = new JsonArray();
+			for (Address flow : instruction.getFlows()) {
+				flows.add(flow.getOffset());
+			}
+			item.add("flows", flows);
+			instructions.add(item);
+		}
+		return instructions;
+	}
+
 	private static void add(JsonArray references, Set<String> seen, long from, long to, String type) {
 		if (!seen.add(from + ":" + to + ":" + type)) {
 			return;

package/src/native/ghidra/scripts/C64Prepare.java

@@ -3,7 +3,8 @@
 // Fills the rest of the 64 KiB address space with uninitialized memory, so
 // references to I/O and other RAM resolve, then applies the knowledge seeds:
 // labels (user-defined names), data ranges (defined bytes that analysis does
-// not disassemble) and entry points (disassembled functions).
+// not disassemble), entry points (disassembled functions) and code starts
+// (disassembled code without a function: a branch target is no routine).
 //@category c64-re-tools
 
 import java.io.FileReader;
@@ -56,5 +57,10 @@ public class C64Prepare extends GhidraScript {
 				createFunction(entry, null);
 			}
 		}
+		if (seeds.has("codeStarts")) {
+			for (JsonElement element : seeds.getAsJsonArray("codeStarts")) {
+				disassemble(toAddr(element.getAsLong()));
+			}
+		}
 	}
 }

package/src/native/status.ts

@@ -9,7 +9,7 @@ import { stripVTControlCharacters } from "node:util";
 import { WireFailure } from "../protocol/messages.ts";
 import { type ToolStatus } from "../protocol/tools.ts";
 import { ACME, DXA, findTool } from "./discover.ts";
-import { findGhidra, ghidraVersion } from "./ghidra/index.ts";
+import { findGhidra, ghidraVersion, NO_USABLE_JDK, noJdk } from "./ghidra/index.ts";
 import { runTool, type ToolContext } from "./run.ts";
 import { Workspace } from "./staging.ts";
 
@@ -35,10 +35,21 @@ export function versionLine(output: string, pattern: RegExp): string | undefined
     .find((line) => pattern.test(line));
 }
 
-async function run(name: string, path: string, args: string[], version: (output: string) => string | undefined, context: ToolContext): Promise<ToolStatus> {
+async function run(
+  name: string,
+  path: string,
+  args: string[],
+  version: (output: string) => string | undefined,
+  context: ToolContext,
+  /** A known cause in the output, said in place of the exit status. */
+  cause?: (output: string) => string | undefined,
+): Promise<ToolStatus> {
   const result = await runTool({ argv: [path, ...args], cwd: tmpdir(), supervisor: context.supervisor, signal: context.signal, timeoutMs: PROBE_TIMEOUT_MS, env: context.env });
-  const found = version(`${result.stdout}\n${result.stderr}`);
+  const output = `${result.stdout}\n${result.stderr}`;
+  const found = version(output);
   if (found !== undefined) return { name, found: true, path, version: found, runs: true };
+  const known = cause?.(output);
+  if (known !== undefined) return { name, found: true, path, runs: false, problem: known };
   const problem = result.timedOut ? "It did not answer in time." : result.spawnError !== undefined ? `It did not start (${result.spawnError}).` : `It did not run correctly (exit ${result.code ?? result.signal}).`;
   return { name, found: true, path, runs: false, problem };
 }
@@ -79,6 +90,7 @@ export async function probeGhidra(context: ToolContext): Promise<ToolStatus> {
         [],
         (output) => (/Headless Analyzer Usage/.test(output) ? ghidraVersion(ghidra) : undefined),
         { ...context, env: { ...env, XDG_CONFIG_HOME: settings, XDG_CACHE_HOME: settings } },
+        (output) => (NO_USABLE_JDK.test(output) ? noJdk(ghidra).message : undefined),
       );
       return { ...status, path: ghidra.root };
     } finally {

package/src/native/types.ts

@@ -39,19 +39,32 @@ export interface AcmeResult {
 export const IMAGE_KINDS = ["prg", "flat64k"] as const;
 export type ImageKind = (typeof IMAGE_KINDS)[number];
 
-export const GHIDRA_LIMITS = { entryPoints: 1024, dataRanges: 1024, labels: 4096, decompile: 32, decompiledChars: 16_000, decompiledTotalChars: 128_000 } as const;
+export const GHIDRA_LIMITS = { entryPoints: 1024, codeStarts: 8192, dataRanges: 1024, labels: 4096, decompile: 32, decompiledChars: 16_000, decompiledTotalChars: 128_000 } as const;
 
 /** The Ghidra analysis. Its image is given next to these fields: a PRG, or 64 KiB from $0000. */
 export interface GhidraParams {
   imageKind: ImageKind;
   /** Seeds from current knowledge. */
   entryPoints: number[];
+  /** Executed instruction starts that Ghidra disassembles without making a function (D74): a branch target is no routine. */
+  codeStarts?: number[];
   dataRanges: Array<{ start: number; end: number }>;
   labels: Array<{ address: number; name: string }>;
   /** Routine entries to decompile for immediate reasoning; the text is never stored. */
   decompile: number[];
 }
 
+export interface GhidraInstruction {
+  address: number;
+  /** Lowercase hex, 1 to 3 bytes. */
+  bytes: string;
+  mnemonic: string;
+  /** Ghidra's text of the operands, empty for an implied operand. */
+  operands: string;
+  /** Where the flow goes besides the next instruction: a branch, jump or call target. */
+  flows: number[];
+}
+
 export interface GhidraResult {
   coverage: Array<{ start: number; end: number }>;
   functions: Array<{ entry: number; name: string; nameSource: "seed" | "generated" | "native" }>;
@@ -60,6 +73,8 @@ export interface GhidraResult {
   decompilations: Array<{ entry: number; text: string; truncated: boolean }>;
   /** Requested routines without decompiled code, with the decompiler's reason. */
   notDecompiled?: Array<{ entry: number; reason: string }>;
+  /** Every instruction in the coverage, as Ghidra decoded it (D44). */
+  instructions: GhidraInstruction[];
   /** Which categories are complete inside the coverage; private to the importer. */
   completeness: { functions: boolean; regions: boolean; references: boolean };
   /** The version of the Ghidra that made the result, for example "Ghidra 12.1.3". */
@@ -67,9 +82,10 @@ export interface GhidraResult {
 }
 
 /** Refuses a DXA or Ghidra request with more seeds or decompilations than the request bounds allow, by name. */
-export function checkRequestBounds(params: DxaParams & { decompile?: number[] }): void {
+export function checkRequestBounds(params: DxaParams & { decompile?: number[]; codeStarts?: number[] }): void {
   const bounds = [
     ["entry points", params.entryPoints.length, GHIDRA_LIMITS.entryPoints],
+    ["code starts", params.codeStarts?.length ?? 0, GHIDRA_LIMITS.codeStarts],
     ["data ranges", params.dataRanges.length, GHIDRA_LIMITS.dataRanges],
     ["labels", params.labels.length, GHIDRA_LIMITS.labels],
     ["routines to decompile", params.decompile?.length ?? 0, GHIDRA_LIMITS.decompile],
@@ -80,7 +96,7 @@ export function checkRequestBounds(params: DxaParams & { decompile?: number[] })
 }
 
 /** The DXA analysis: the same image and seeds as Ghidra, without decompilation. */
-export type DxaParams = Omit<GhidraParams, "decompile">;
+export type DxaParams = Omit<GhidraParams, "decompile" | "codeStarts">;
 
 export interface DxaResult {
   coverage: Array<{ start: number; end: number }>;
@@ -115,7 +131,7 @@ const isList = (value: unknown): value is unknown[] => Array.isArray(value);
  */
 export function checkGhidraResult(value: unknown): GhidraResult {
   if (!isObject(value)) fail("not an object");
-  const { coverage, functions, regions, references, decompilations, notDecompiled, completeness, toolVersion } = value;
+  const { coverage, functions, regions, references, decompilations, notDecompiled, completeness, toolVersion, instructions } = value;
   if (!isList(coverage) || coverage.length === 0) fail("no coverage");
   const ranges: Array<{ start: number; end: number }> = [];
   for (const range of coverage) {
@@ -138,6 +154,22 @@ export function checkGhidraResult(value: unknown): GhidraResult {
     if (!ranges.some((range) => range.start <= start && end <= range.end)) fail("a region lies outside the coverage");
     previousEnd = end;
   }
+  if (!isList(instructions)) fail("no instructions");
+  for (const instruction of instructions) {
+    if (
+      !isObject(instruction) ||
+      !isInteger(instruction.address, 0, 0xffff) ||
+      typeof instruction.bytes !== "string" ||
+      !/^(?:[0-9a-f]{2}){1,3}$/.test(instruction.bytes) ||
+      typeof instruction.mnemonic !== "string" ||
+      typeof instruction.operands !== "string" ||
+      !isList(instruction.flows) ||
+      !instruction.flows.every((flow) => isInteger(flow, 0, 0xffff))
+    ) {
+      fail("bad instruction");
+    }
+    if (!covered(instruction.address)) fail("an instruction lies outside the coverage");
+  }
   if (!isList(references)) fail("no references");
   for (const reference of references) {
     if (!isObject(reference) || !isInteger(reference.from, 0, 0xffff) || !isInteger(reference.to, 0, 0xffff) || !isOneOf(REFERENCE_KINDS, reference.type)) fail("bad reference");
@@ -218,11 +250,14 @@ export function imageRange(kind: ImageKind, image: Uint8Array): { start: number;
  * it, and the data ranges cut to it. A data range that holds an entry point
  * is left out, so that the entry point is disassembled.
  */
-export function seedsInside(params: Pick<DxaParams, "entryPoints" | "dataRanges">, start: number, end: number): Pick<DxaParams, "entryPoints" | "dataRanges"> {
-  const entryPoints = params.entryPoints.filter((address) => address >= start && address <= end);
+export function seedsInside(params: Pick<GhidraParams, "entryPoints" | "dataRanges" | "codeStarts">, start: number, end: number): { entryPoints: number[]; codeStarts: number[]; dataRanges: GhidraParams["dataRanges"] } {
+  const inside = (address: number) => address >= start && address <= end;
+  const entryPoints = params.entryPoints.filter(inside);
+  const codeStarts = (params.codeStarts ?? []).filter(inside);
+  const code = [...entryPoints, ...codeStarts];
   const dataRanges = params.dataRanges
     .filter((range) => range.end >= start && range.start <= end)
     .map((range) => ({ start: Math.max(range.start, start), end: Math.min(range.end, end) }))
-    .filter((range) => !entryPoints.some((entry) => entry >= range.start && entry <= range.end));
-  return { entryPoints, dataRanges };
+    .filter((range) => !code.some((entry) => entry >= range.start && entry <= range.end));
+  return { entryPoints, codeStarts, dataRanges };
 }

package/src/opcodes.ts

@@ -0,0 +1,133 @@
+// The ACME spelling of each 6510 opcode (D48, D78): the mnemonic and the addressing
+// mode, undocumented opcodes included. Ghidra gives the instruction
+// boundaries; this table gives the text. Where several opcodes share one
+// spelling, ACME writes only one of them: the generator finds those with a
+// probe and writes the others as bytes.
+
+export type Mode = "imp" | "imm" | "zp" | "zpx" | "zpy" | "abs" | "abx" | "aby" | "ind" | "izx" | "izy" | "rel";
+
+export interface Opcode {
+  mnemonic: string;
+  mode: Mode;
+}
+
+const ROWS = `
+00 brk imp|01 ora izx|02 jam imp|03 slo izx|04 nop zp|05 ora zp|06 asl zp|07 slo zp|08 php imp|09 ora imm|0a asl imp|0b anc imm|0c nop abs|0d ora abs|0e asl abs|0f slo abs
+10 bpl rel|11 ora izy|12 jam imp|13 slo izy|14 nop zpx|15 ora zpx|16 asl zpx|17 slo zpx|18 clc imp|19 ora aby|1a nop imp|1b slo aby|1c nop abx|1d ora abx|1e asl abx|1f slo abx
+20 jsr abs|21 and izx|22 jam imp|23 rla izx|24 bit zp|25 and zp|26 rol zp|27 rla zp|28 plp imp|29 and imm|2a rol imp|2b anc imm|2c bit abs|2d and abs|2e rol abs|2f rla abs
+30 bmi rel|31 and izy|32 jam imp|33 rla izy|34 nop zpx|35 and zpx|36 rol zpx|37 rla zpx|38 sec imp|39 and aby|3a nop imp|3b rla aby|3c nop abx|3d and abx|3e rol abx|3f rla abx
+40 rti imp|41 eor izx|42 jam imp|43 sre izx|44 nop zp|45 eor zp|46 lsr zp|47 sre zp|48 pha imp|49 eor imm|4a lsr imp|4b asr imm|4c jmp abs|4d eor abs|4e lsr abs|4f sre abs
+50 bvc rel|51 eor izy|52 jam imp|53 sre izy|54 nop zpx|55 eor zpx|56 lsr zpx|57 sre zpx|58 cli imp|59 eor aby|5a nop imp|5b sre aby|5c nop abx|5d eor abx|5e lsr abx|5f sre abx
+60 rts imp|61 adc izx|62 jam imp|63 rra izx|64 nop zp|65 adc zp|66 ror zp|67 rra zp|68 pla imp|69 adc imm|6a ror imp|6b arr imm|6c jmp ind|6d adc abs|6e ror abs|6f rra abs
+70 bvs rel|71 adc izy|72 jam imp|73 rra izy|74 nop zpx|75 adc zpx|76 ror zpx|77 rra zpx|78 sei imp|79 adc aby|7a nop imp|7b rra aby|7c nop abx|7d adc abx|7e ror abx|7f rra abx
+80 nop imm|81 sta izx|82 nop imm|83 sax izx|84 sty zp|85 sta zp|86 stx zp|87 sax zp|88 dey imp|89 nop imm|8a txa imp|8b ane imm|8c sty abs|8d sta abs|8e stx abs|8f sax abs
+90 bcc rel|91 sta izy|92 jam imp|93 sha izy|94 sty zpx|95 sta zpx|96 stx zpy|97 sax zpy|98 tya imp|99 sta aby|9a txs imp|9b tas aby|9c shy abx|9d sta abx|9e shx aby|9f sha aby
+a0 ldy imm|a1 lda izx|a2 ldx imm|a3 lax izx|a4 ldy zp|a5 lda zp|a6 ldx zp|a7 lax zp|a8 tay imp|a9 lda imm|aa tax imp|ab lxa imm|ac ldy abs|ad lda abs|ae ldx abs|af lax abs
+b0 bcs rel|b1 lda izy|b2 jam imp|b3 lax izy|b4 ldy zpx|b5 lda zpx|b6 ldx zpy|b7 lax zpy|b8 clv imp|b9 lda aby|ba tsx imp|bb las aby|bc ldy abx|bd lda abx|be ldx aby|bf lax aby
+c0 cpy imm|c1 cmp izx|c2 nop imm|c3 dcp izx|c4 cpy zp|c5 cmp zp|c6 dec zp|c7 dcp zp|c8 iny imp|c9 cmp imm|ca dex imp|cb sbx imm|cc cpy abs|cd cmp abs|ce dec abs|cf dcp abs
+d0 bne rel|d1 cmp izy|d2 jam imp|d3 dcp izy|d4 nop zpx|d5 cmp zpx|d6 dec zpx|d7 dcp zpx|d8 cld imp|d9 cmp aby|da nop imp|db dcp aby|dc nop abx|dd cmp abx|de dec abx|df dcp abx
+e0 cpx imm|e1 sbc izx|e2 nop imm|e3 isc izx|e4 cpx zp|e5 sbc zp|e6 inc zp|e7 isc zp|e8 inx imp|e9 sbc imm|ea nop imp|eb sbc imm|ec cpx abs|ed sbc abs|ee inc abs|ef isc abs
+f0 beq rel|f1 sbc izy|f2 jam imp|f3 isc izy|f4 nop zpx|f5 sbc zpx|f6 inc zpx|f7 isc zpx|f8 sed imp|f9 sbc aby|fa nop imp|fb isc aby|fc nop abx|fd sbc abx|fe inc abx|ff isc abx`;
+
+export const OPCODES: readonly Opcode[] = (() => {
+  const table: Opcode[] = [];
+  for (const cell of ROWS.trim().split(/[|\n]/)) {
+    const [code, mnemonic, mode] = cell.trim().split(" ");
+    table[Number.parseInt(code!, 16)] = { mnemonic: mnemonic!, mode: mode as Mode };
+  }
+  return table;
+})();
+
+export const MODE_LENGTH: Record<Mode, 1 | 2 | 3> = { imp: 1, imm: 2, zp: 2, zpx: 2, zpy: 2, izx: 2, izy: 2, rel: 2, abs: 3, abx: 3, aby: 3, ind: 3 };
+
+/** Every mnemonic in the table: a symbol with one of these names would read as an instruction. */
+export const MNEMONICS: ReadonlySet<string> = new Set(OPCODES.map((opcode) => opcode.mnemonic));
+
+const ZERO_PAGE_OF: Partial<Record<Mode, Mode>> = { abs: "zp", abx: "zpx", aby: "zpy" };
+
+/** True when the mnemonic also has the zero-page form of an absolute mode: ACME would pick it for a small operand. */
+export function hasZeroPageForm(mnemonic: string, mode: Mode): boolean {
+  const zeroPage = ZERO_PAGE_OF[mode];
+  return zeroPage !== undefined && OPCODES.some((opcode) => opcode.mnemonic === mnemonic && opcode.mode === zeroPage);
+}
+
+/** True for a mode whose operand is an address (or a branch target), so a name can stand for it. */
+export function takesAddress(mode: Mode): boolean {
+  return mode !== "imp" && mode !== "imm";
+}
+
+/** How an instruction uses the address of its operand, in the order a summary lists them. */
+export const USE_KINDS = ["read", "written", "modified", "called", "jumped to", "jumped through", "branched to", "pointer", "address", "table", "macro argument"] as const;
+export type UseKind = (typeof USE_KINDS)[number];
+
+const WRITES = new Set(["sta", "stx", "sty", "sax", "sha", "shx", "shy", "tas"]);
+const MODIFIES = new Set(["inc", "dec", "asl", "lsr", "rol", "ror", "slo", "rla", "sre", "rra", "dcp", "isc"]);
+
+/** The use of the operand address of an instruction that takes an address. Through (zp),y and (zp,x) the address is a pointer. */
+export function useKind(opcode: number): UseKind {
+  const { mnemonic, mode } = OPCODES[opcode]!;
+  if (mode === "izx" || mode === "izy") return "pointer";
+  if (mode === "rel") return "branched to";
+  if (mnemonic === "jsr") return "called";
+  if (mnemonic === "jmp") return mode === "ind" ? "jumped through" : "jumped to";
+  if (WRITES.has(mnemonic)) return "written";
+  if (MODIFIES.has(mnemonic)) return "modified";
+  return "read";
+}
+
+const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
+const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+
+/** The text of the instruction in `bytes` at `pc`, for example "sta $d011" or "bne $c002". */
+export function instructionText(bytes: readonly number[], pc: number): string {
+  const { mnemonic, mode } = OPCODES[bytes[0]!]!;
+  const low = bytes[1] ?? 0;
+  const word = low | ((bytes[2] ?? 0) << 8);
+  const operand: Record<Mode, string> = {
+    imp: "",
+    imm: `#${hex2(low)}`,
+    zp: hex2(low),
+    zpx: `${hex2(low)},x`,
+    zpy: `${hex2(low)},y`,
+    abs: hex4(word),
+    abx: `${hex4(word)},x`,
+    aby: `${hex4(word)},y`,
+    ind: `(${hex4(word)})`,
+    izx: `(${hex2(low)},x)`,
+    izy: `(${hex2(low)}),y`,
+    rel: hex4((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff),
+  };
+  return operand[mode] === "" ? mnemonic : `${mnemonic} ${operand[mode]}`;
+}
+
+/**
+ * The address that a read or write of the instruction in `bytes` uses, with X
+ * and Y as they were before it; `byteAt` reads a zero-page pointer. Undefined
+ * for a mode that uses no memory operand.
+ */
+export function operandAddress(bytes: readonly number[], x: number, y: number, byteAt: (address: number) => number): number | undefined {
+  const { mode } = OPCODES[bytes[0]!]!;
+  const low = bytes[1] ?? 0;
+  const word = low | ((bytes[2] ?? 0) << 8);
+  const pointer = (at: number) => byteAt(at & 0xff) | (byteAt((at + 1) & 0xff) << 8);
+  switch (mode) {
+    case "zp":
+      return low;
+    case "zpx":
+      return (low + x) & 0xff;
+    case "zpy":
+      return (low + y) & 0xff;
+    case "abs":
+      return word;
+    case "abx":
+      return (word + x) & 0xffff;
+    case "aby":
+      return (word + y) & 0xffff;
+    case "izx":
+      return pointer(low + x);
+    case "izy":
+      return (pointer(low) + y) & 0xffff;
+    default:
+      return undefined;
+  }
+}

package/src/package.ts

@@ -0,0 +1,21 @@
+// The name, version and npm channel of this copy of c64-re-tools, for the npx
+// commands that refusals and help texts give. The package.json above src/ is
+// the package's own one; in an installed skill it is the skill's one, which
+// has the same name and version (distribution/plugin.ts).
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The npm dist-tag that a version is published under: a prerelease
+ * (2.0.0-rc.1) goes to "next", a release to "latest".
+ */
+export function channelOf(version: string): "latest" | "next" {
+  return version.includes("-") ? "next" : "latest";
+}
+
+/** The name, version and dist-tag of this npm package, from its package.json. */
+export const PACKAGE = (() => {
+  const metadata = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { name: string; version: string };
+  return { name: metadata.name, version: metadata.version, tag: channelOf(metadata.version) };
+})();

package/{skills/c64-memory-map/scripts → src}/platform.ts

@@ -1,8 +1,9 @@
-// C64 platform reference data and decoders for the c64-memory-map script.
+// C64 platform reference data and decoders: the c64-memory-map script, and the
+// platform names that c64-source uses (D52).
 // Names follow "Mapping the Commodore 64". Only platform facts live here:
 // an address without one belongs to the application.
 
-import { d018Offsets, vicBankBase } from "#src/c64.ts";
+import { d018Offsets, vicBankBase } from "./c64.ts";
 
 export interface Entry {
   start: number;
@@ -322,10 +323,33 @@ const AREAS: Array<{ start: number; end: number; area: string; kind: Lookup["kin
 
 const hex = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
 
+export interface Area {
+  name: string;
+  start: number;
+  end: number;
+  kind: Lookup["kind"];
+  /** What a memory area holds. A chip register block has none: its name says it. */
+  meaning?: string;
+}
+
+/** The memory area or the I/O register block of an address. */
+export function areaOf(address: number): Area {
+  const block = IO.find((candidate) => address >= candidate.start && address <= candidate.end);
+  if (block !== undefined) return { name: block.area, start: block.start, end: block.end, kind: "platform" };
+  const area = AREAS.find((candidate) => address >= candidate.start && address <= candidate.end)!;
+  return { name: area.area, start: area.start, end: area.end, kind: area.kind, meaning: area.meaning };
+}
+
+/** The area of an address, and the register that an I/O mirror repeats: c64-source groups and describes its constants with them. */
+export function describeAddress(address: number): { area: Area; mirrorOf?: number } {
+  const { mirrorOf } = lookup(address);
+  return { area: areaOf(address), ...(mirrorOf === undefined ? {} : { mirrorOf }) };
+}
+
 /** The platform meaning of one address, or its application area. */
 export function lookup(address: number): Lookup {
-  for (const block of IO) {
-    if (address < block.start || address > block.end) continue;
+  const block = IO.find((candidate) => address >= candidate.start && address <= candidate.end);
+  if (block !== undefined) {
     const base = block.start + ((address - block.start) % block.period);
     const register = block.registers.find((entry) => entry.start === base);
     const mirror = base !== address ? { mirrorOf: base } : {};
@@ -333,11 +357,67 @@ export function lookup(address: number): Lookup {
     return { address, kind: "platform", area: block.area, name: register.name, meaning: register.meaning, ...mirror };
   }
   const entry = [...SYSTEM, ...ROM].find((candidate) => address >= candidate.start && address <= candidate.end);
-  const area = AREAS.find((candidate) => address >= candidate.start && address <= candidate.end)!;
+  const area = areaOf(address);
   if (entry !== undefined) {
-    return { address, kind: "platform", area: area.area, name: entry.name, meaning: entry.meaning, ...(entry.start !== address ? { entryStart: entry.start } : {}) };
+    return { address, kind: "platform", area: area.name, name: entry.name, meaning: entry.meaning, ...(entry.start !== address ? { entryStart: entry.start } : {}) };
   }
-  return { address, kind: area.kind, area: area.area, meaning: area.meaning };
+  return { address, kind: area.kind, area: area.name, meaning: area.meaning! };
+}
+
+/**
+ * The platform name of each named address (D52): system variables, ROM
+ * entries and I/O registers, not mirrors, in address order. Only names that
+ * an assembler can use as a symbol, and each name once, at its lowest address.
+ * `end` is the last address of the entry: a vector has two bytes.
+ */
+export function platformNames(): Array<{ address: number; end: number; name: string; meaning: string }> {
+  const io = IO.flatMap((block) => block.registers);
+  const seen = new Set<string>();
+  return [...SYSTEM, ...ROM, ...io]
+    .map((entry) => ({ address: entry.start, end: entry.end, name: entry.name, meaning: entry.meaning }))
+    .filter((entry) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(entry.name))
+    .sort((a, b) => a.address - b.address)
+    .filter((entry) => !seen.has(entry.name) && seen.add(entry.name) !== undefined);
+}
+
+/** Which ROMs a program uses (D75): a ROM it does not use gives no names, and without both the system area gives none. */
+export interface RomUse {
+  basic: boolean;
+  kernal: boolean;
+}
+
+/**
+ * The platform names of a program that uses only some ROMs (D75): the BASIC
+ * ROM entries need the BASIC ROM, the KERNAL ROM entries the KERNAL, and the
+ * system variables of $0002-$03FF (the workspace of both) one of them. The
+ * processor port and the I/O registers always stay.
+ */
+export function platformNamesFor(use: RomUse): ReturnType<typeof platformNames> {
+  return platformNames().filter((entry) => {
+    if (entry.address >= 0xa000 && entry.address <= 0xbfff) return use.basic;
+    if (entry.address >= 0xe000) return use.kernal;
+    if (entry.address >= 0x0002 && entry.address <= 0x03ff) return use.basic || use.kernal;
+    return true;
+  });
+}
+
+/**
+ * The ROMs that a coverage map shows in use: code of the ROM executed. A read
+ * of ROM bytes is data, for example a table or random numbers, and does not use
+ * the routines of the ROM or their workspace (Bruce Lee reads 1,571 bytes of the
+ * BASIC ROM and executes none).
+ */
+export function romUseOf(coverage: Uint8Array, romExecute: number): RomUse {
+  const used = (start: number, end: number) => {
+    for (let address = start; address <= end; address++) if ((coverage[address]! & romExecute) !== 0) return true;
+    return false;
+  };
+  return { basic: used(0xa000, 0xbfff), kernal: used(0xe000, 0xffff) };
+}
+
+/** The ROMs that a value of $01 switches in: HIRAM for the KERNAL, LORAM and HIRAM for BASIC. */
+export function romUseOfPort(port: number): RomUse {
+  return { basic: (port & 0x03) === 0x03, kernal: (port & 0x02) !== 0 };
 }
 
 export type Decoded = Record<string, unknown>;