@henols/c64-re-tools 2.0.0-rc.3 → 2.0.0-rc.4

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

@@ -0,0 +1,320 @@
+// 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
+// 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.
+
+import { formatC64Address } from "#src/c64.ts";
+import { WireFailure } from "#src/host-client/tools.ts";
+import type { Range } from "./source.ts";
+
+export interface EntryState {
+  pc: number;
+  a: number;
+  x: number;
+  y: number;
+  sp: number;
+  /** The status register as PLP reads it. */
+  flags: number;
+  port: [number, number];
+  /** $0000-$03ff at the entry. */
+  pages: Uint8Array;
+}
+
+const FLAG_BITS: Record<string, number> = { n: 0x80, v: 0x40, b: 0x10, d: 0x08, i: 0x04, z: 0x02, c: 0x01 };
+
+/** Reads entry_state.json of the c64-unpacker skill. */
+export function readEntryState(text: string, path: string): EntryState {
+  const fail = (what: string): never => {
+    throw new WireFailure("invalid-input", `${path} is not an entry_state.json of the c64-unpacker skill: ${what}.`);
+  };
+  let value: Record<string, any>;
+  try {
+    value = JSON.parse(text) as Record<string, any>;
+  } catch (error) {
+    return fail((error as Error).message);
+  }
+  const registers = value.registers;
+  const byte = (item: unknown, what: string) => (Number.isInteger(item) && (item as number) >= 0 && (item as number) <= 0xff ? (item as number) : fail(`${what} is not a byte`));
+  if (typeof registers !== "object" || registers === null) return fail("it has no registers");
+  const pc = typeof registers.pc === "string" && /^\$[0-9a-f]{4}$/i.test(registers.pc) ? Number.parseInt(registers.pc.slice(1), 16) : fail("registers.pc is not a $ address");
+  if (typeof registers.flags !== "object" || registers.flags === null) fail("registers.flags is missing");
+  let flags = 0x20;
+  for (const [name, bit] of Object.entries(FLAG_BITS)) if (registers.flags[name] === true) flags |= bit;
+  const pages = new Uint8Array(0x400);
+  for (let page = 0; page < 4; page++) {
+    const hex = value.pages?.[formatC64Address(page << 8)];
+    if (typeof hex !== "string" || !/^[0-9a-f]{512}$/i.test(hex)) fail(`pages.${formatC64Address(page << 8)} is not 256 bytes of hex`);
+    pages.set(Buffer.from(hex as string, "hex"), page << 8);
+  }
+  return {
+    pc,
+    a: byte(registers.a, "registers.a"),
+    x: byte(registers.x, "registers.x"),
+    y: byte(registers.y, "registers.y"),
+    sp: byte(registers.sp, "registers.sp"),
+    flags,
+    port: [byte(value.cpuPort?.$00, "cpuPort.$00"), byte(value.cpuPort?.$01, "cpuPort.$01")],
+    pages,
+  };
+}
+
+export interface Copy {
+  /** What the copy writes: a segment or a part of pages 0-3. */
+  what: string;
+  target: Range;
+  source: Range;
+  /** True when the copy runs from the last byte down: its target is above an overlapping source. */
+  backward: boolean;
+}
+
+/** What the loader holds, in its order: a segment or a part of pages 0-3, packed at an address of the loader. */
+export interface PackedBlock {
+  what: string;
+  range: Range;
+  packedAt: number;
+  bytes: (address: number) => number;
+}
+
+export interface LoaderPlan {
+  blocks: PackedBlock[];
+  copies: Copy[];
+  /** The first of the two free pages where the copier runs. */
+  copier: number;
+  /** The address of the free stack byte below the stack pointer, which the flags pass through. */
+  stackByte: number;
+  end: number;
+  text: string;
+}
+
+const LOAD = 0x0801;
+const STUB = 0x080d;
+/** sei, ldx, the 2-page move loop and jmp. */
+const STUB_SIZE = 21;
+/** The copier code and its three variables, without the table. */
+const COPIER_CODE_SIZE = 167;
+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);
+/** 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)];
+
+const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
+const hex4 = formatC64Address;
+const overlaps = (a: Range, b: Range) => a.start <= b.end && b.start <= a.end;
+const show = (range: Range) => `${hex4(range.start)}-${hex4(range.end)}`;
+
+/** Parts of `range` that no range in `holes` covers. */
+function subtract(range: Range, holes: Range[]): Range[] {
+  let pieces = [range];
+  for (const hole of holes) {
+    pieces = pieces.flatMap((piece) => {
+      if (!overlaps(piece, hole)) return [piece];
+      return [...(hole.start > piece.start ? [{ start: piece.start, end: hole.start - 1 }] : []), ...(hole.end < piece.end ? [{ start: hole.end + 1, end: piece.end }] : [])];
+    });
+  }
+  return pieces;
+}
+
+/** Orders the copies so that no copy writes over the source of a later one; undefined when they form a cycle. */
+export function copyOrder(copies: Array<Omit<Copy, "backward">>): number[] | undefined {
+  const order: number[] = [];
+  const done = new Set<number>();
+  while (order.length < copies.length) {
+    const next = copies.findIndex((copy, index) => !done.has(index) && copies.every((other, at) => at === index || done.has(at) || !overlaps(copy.target, other.source)));
+    if (next < 0) return undefined;
+    order.push(next);
+    done.add(next);
+  }
+  return order;
+}
+
+/** Runs the copies on a memory model as the copier does, byte by byte; returns the first wrong target byte. */
+export function simulate(memory: Int16Array, copies: Copy[], expected: (address: number) => number): number | undefined {
+  for (const copy of copies) {
+    const length = copy.target.end - copy.target.start + 1;
+    for (let step = 0; step < length; step++) {
+      const offset = copy.backward ? length - 1 - step : step;
+      memory[copy.target.start + offset] = memory[copy.source.start + offset]!;
+    }
+  }
+  for (const copy of copies) for (let address = copy.target.start; address <= copy.target.end; address++) if (memory[address] !== expected(address)) return address;
+  return undefined;
+}
+
+export interface LoaderInput {
+  /** The segments with the files that hold them, in address order. */
+  segments: Array<Range & { files: string[] }>;
+  byteAt: (address: number) => number;
+  state: EntryState;
+  entry: number;
+  header: string[];
+}
+
+/** Plans the loader: the packed layout, the copy order and the copier page, and writes loader.asm. Refuses by name when no plan exists. */
+export function planLoader(input: LoaderInput): LoaderPlan {
+  const { state } = input;
+  // What the copies write: each segment without $00/$01, which the loader sets last, and pages $0002-$03ff where no segment is.
+  const blocks: Array<{ what: string; range: Range; files?: string[]; pseudo: number; bytes: (address: number) => number }> = [];
+  for (const segment of input.segments) blocks.push({ what: `segment ${show(segment)}`, range: segment, files: segment.files, pseudo: segment.start, bytes: input.byteAt });
+  for (const part of subtract({ start: 0x0002, end: 0x03ff }, input.segments)) {
+    blocks.push({ what: `entry state ${show(part)}`, range: part, pseudo: part.start, bytes: (address) => state.pages[address]! });
+  }
+  blocks.sort((a, b) => a.range.start - b.range.start);
+
+  let at = STUB + STUB_SIZE;
+  const plain: Array<Omit<Copy, "backward">> = [];
+  const packedAt: number[] = [];
+  for (const block of blocks) {
+    packedAt.push(at);
+    const target = { start: Math.max(block.range.start, 0x0002), end: block.range.end };
+    if (target.start <= target.end) {
+      const source = { start: at + (target.start - block.range.start), end: at + (target.end - block.range.start) };
+      plain.push({ what: block.what, target, source });
+    }
+    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 copierImage = at;
+  const copierSize = COPIER_CODE_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.`);
+
+  const order = copyOrder(plain);
+  if (order === undefined) {
+    const clashing = plain.filter((copy) => plain.some((other) => other !== copy && overlaps(copy.target, other.source))).map((copy) => `${copy.what} (packed at ${show(copy.source)})`);
+    throw new WireFailure("invalid-input", `No copy order exists: each of these copies writes over the packed bytes of another one: ${clashing.join(", ")}. Write the loader by hand.`);
+  }
+  const loaded = { start: LOAD, end };
+  const copier = COPIER_PAGES.find((page) => {
+    const pages = { start: page, end: page + 0x1ff };
+    return !overlaps(pages, loaded) && plain.every((copy) => !overlaps(pages, copy.target));
+  });
+  if (copier === undefined) throw new WireFailure("invalid-input", `No two free pages exist for the copier in $0400-$9fff or $c000-$cfff outside the loader (${show(loaded)}) and the targets: ${plain.map((copy) => show(copy.target)).join(", ")}.`);
+  const copies: Copy[] = order.map((index) => {
+    const copy = plain[index]!;
+    return { ...copy, backward: copy.target.start > copy.source.start && overlaps(copy.target, copy.source) };
+  });
+
+  const stackByte = 0x0100 + state.sp;
+  const lines: string[] = [...input.header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', "", `* = ${hex4(LOAD)}`];
+  lines.push(`        !byte $0b,$08,$0a,$00,$9e,${[...String(STUB)].map((digit) => hex2(digit.charCodeAt(0))).join(",")},$00,$00,$00 ; 10 SYS ${STUB}`);
+  lines.push(
+    "!zone loader_stub {",
+    "        sei",
+    "        ldx #0",
+    `-       lda ${hex4(copierImage)},x`,
+    `        sta ${hex4(copier)},x`,
+    `        lda ${hex4(copierImage + 0x100)},x`,
+    `        sta ${hex4(copier + 0x100)},x`,
+    "        inx",
+    "        bne -",
+    `        jmp ${hex4(copier)}`,
+    "}",
+  );
+  for (const block of blocks) {
+    lines.push("", `; ${block.what}`, `!pseudopc ${hex4(block.pseudo)} {`);
+    if (block.files !== undefined) for (const file of block.files) lines.push(`!source "${file}"`);
+    else {
+      for (let address = block.range.start; address <= block.range.end; address += 16) {
+        const last = Math.min(block.range.end, address + 15);
+        lines.push(`        !byte ${Array.from({ length: last - address + 1 }, (_, offset) => hex2(block.bytes(address + offset))).join(",")}`);
+      }
+    }
+    lines.push("}");
+  }
+  const [port0, port1] = state.port;
+  lines.push(
+    "",
+    `; The copier runs at ${hex4(copier)}. The flags pass through ${hex4(stackByte)}, the free stack byte below the stack pointer.`,
+    `!pseudopc ${hex4(copier)} {`,
+    "!zone loader_copier {",
+    "        lda #$34",
+    "        sta $01",
+    "        ldx #0",
+    ".next   lda .table,x",
+    "        sta .count",
+    "        lda .table+1,x",
+    "        sta .count+1",
+    "        ora .count",
+    "        beq .done",
+    "        lda .table+2,x",
+    "        sta .read+1",
+    "        lda .table+3,x",
+    "        sta .read+2",
+    "        lda .table+4,x",
+    "        sta .write+1",
+    "        lda .table+5,x",
+    "        sta .write+2",
+    "        lda .table+6,x",
+    "        sta .back",
+    "        stx .index",
+    ".read   lda $ffff",
+    ".write  sta $ffff",
+    "        lda .back",
+    "        bne .down",
+    "        inc .read+1",
+    "        bne +",
+    "        inc .read+2",
+    "+       inc .write+1",
+    "        bne +",
+    "        inc .write+2",
+    "+       jmp .counted",
+    ".down   lda .read+1",
+    "        bne +",
+    "        dec .read+2",
+    "+       dec .read+1",
+    "        lda .write+1",
+    "        bne +",
+    "        dec .write+2",
+    "+       dec .write+1",
+    ".counted",
+    "        lda .count",
+    "        bne +",
+    "        dec .count+1",
+    "+       dec .count",
+    "        lda .count",
+    "        ora .count+1",
+    "        bne .read",
+    "        lda .index",
+    "        clc",
+    "        adc #7",
+    "        tax",
+    "        jmp .next",
+    `.done   lda #${hex2(port0)}`,
+    "        sta $00",
+    `        lda #${hex2(port1)}`,
+    "        sta $01",
+    `        ldx #${hex2((state.sp - 1) & 0xff)}`,
+    "        txs",
+    `        lda #${hex2(state.flags)}`,
+    `        sta ${hex4(stackByte)}`,
+    `        lda #${hex2(state.a)}`,
+    `        ldx #${hex2(state.x)}`,
+    `        ldy #${hex2(state.y)}`,
+    "        plp",
+    `        jmp ${hex4(input.entry)}`,
+    ".count  !word 0",
+    ".index  !byte 0",
+    ".back   !byte 0",
+    ".table",
+  );
+  for (const copy of copies) {
+    const length = copy.target.end - copy.target.start + 1;
+    const read = copy.backward ? copy.source.end : copy.source.start;
+    const write = copy.backward ? copy.target.end : copy.target.start;
+    lines.push(`        !word ${hex4(length)},${hex4(read)},${hex4(write)} : !byte ${copy.backward ? 1 : 0} ; ${copy.what}`);
+  }
+  lines.push("        !word 0", "}", "}");
+
+  return {
+    blocks: blocks.map((block, index) => ({ what: block.what, range: block.range, packedAt: packedAt[index]!, bytes: block.bytes })),
+    copies,
+    copier,
+    stackByte,
+    end,
+    text: `${lines.join("\n")}\n`,
+  };
+}

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

@@ -0,0 +1,61 @@
+// The ACME spelling of each 6510 opcode (D48): 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";
+}
+
+export function isZeroPageMode(mode: Mode): boolean {
+  return mode === "zp" || mode === "zpx" || mode === "zpy" || mode === "izx" || mode === "izy";
+}