@henols/c64-re-tools 2.0.0-rc.9 → 2.0.1

package/skills/c64-source/scripts/{loader.ts → lib/loader.ts}

@@ -1,7 +1,7 @@
-// The loader of a generated source (D48): a PRG that copies each segment and
+// The loader of a generated source: a PRG that copies each segment and
 // 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
+// of the VIC-II and the VIC bank, waits for the entry's raster line,
+// sets the CIA timers and interrupt masks, 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
@@ -22,9 +22,9 @@ 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). */
+  /** The VIC-II at the entry: $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 1 and CIA 2 at the entry. */
   cia?: [EntryCia, EntryCia];
 }
 
@@ -37,7 +37,7 @@ export interface EntryCia {
 }
 
 /**
- * The VIC-II registers that the loader sets (D60), each with the bits that a
+ * The VIC-II registers that the loader sets, 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.
  */
@@ -125,20 +125,31 @@ 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). */
+  /** The CIA timers and masks that the loader sets, when the entry state has them. */
   cia?: CiaPlan;
 }
 
+/**
+ * What the loader cannot set as it was at the entry. An entry state
+ * without CIA values (from a capture of an older version) gives no timers at all.
+ */
+export function loaderLimits(plan: { cia?: CiaPlan }): string[] {
+  if (plan.cia === undefined) {
+    return ["The entry state has no CIA values, so the loader does not set the CIA timers. Capture the program again with c64-unpacker to get them."];
+  }
+  return plan.cia.limits;
+}
+
 /** The label of the loader's jump to the entry, in ACME's symbol list. */
 export const LOADER_JUMP = "c64_source_loader_jump";
 
 const LOAD = 0x0801;
 const STUB = 0x080d;
-/** sei, ldx, the 2-page move loop and jmp. */
-const STUB_SIZE = 21;
+/** sei, all RAM, ldx, the 2-page move loop and jmp. */
+const STUB_SIZE = 25;
 /** 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. */
+/** The VIC-II code of the copier, 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. */
@@ -193,6 +204,31 @@ export function simulate(memory: Int16Array, copies: Copy[], expected: (address:
   return undefined;
 }
 
+/** True when a read of the address with $01 = $37, as RUN leaves it, gives a ROM byte. */
+const underRom = (address: number) => (address >= 0xa000 && address <= 0xbfff) || address >= 0xe000;
+
+/**
+ * Why a loader stopped before its jump, from the RAM after the stop: the first
+ * byte of the moved copier that is not the byte of the loader file, else, when
+ * the copier ran, the first byte that a copy did not write as planned.
+ */
+export function stopCause(ram: Uint8Array, plan: LoaderPlan, copierSource: number, fileByte: (address: number) => number, copied: boolean, expected: (address: number) => number): string | undefined {
+  for (let offset = 0; offset <= plan.end - copierSource; offset++) {
+    const got = ram[plan.copier + offset]!;
+    const wanted = fileByte(copierSource + offset);
+    if (got === wanted) continue;
+    const rom = underRom(copierSource + offset) ? `; ${hex4(copierSource + offset)} is under a ROM, so the move read the ROM` : "";
+    return `The copier at ${hex4(plan.copier + offset)} holds ${hex2(got)}, not ${hex2(wanted)} from ${hex4(copierSource + offset)} of the loader file${rom}.`;
+  }
+  if (!copied) return undefined;
+  for (const copy of plan.copies) {
+    for (let address = copy.target.start; address <= copy.target.end; address++) {
+      if (ram[address] !== expected(address)) return `The copy of ${copy.what} wrote ${hex2(ram[address]!)} at ${hex4(address)}, not ${hex2(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 {};
@@ -260,7 +296,7 @@ interface Op {
 }
 
 /**
- * The copier's CIA part (D63), after the raster wait: the timers and
+ * The copier's CIA part, 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.
@@ -354,9 +390,19 @@ export interface LoaderInput {
   byteAt: (address: number) => number;
   state: EntryState;
   entry: number;
+  /** The label of the entry in the source: the loader jumps to it, so the jump follows the code when it moves. */
+  entryName?: string;
   header: string[];
+  /** The source has macros.asm: the loader includes it after the constants. */
+  macros?: boolean;
 }
 
+/** The label of a block: its first byte and the byte after it in the loader file, and its first address where it runs. */
+const blockLabel = (start: number, part: "from" | "end" | "to") => `loader_${part}_${start.toString(16).padStart(4, "0")}`;
+const plus = (label: string, offset: number) => (offset === 0 ? label : `${label}+${offset}`);
+/** The label of the copier in the loader file, which the stub moves to its two pages. */
+export const COPIER_SOURCE = "loader_copier_src";
+
 /** 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;
@@ -371,12 +417,15 @@ export function planLoader(input: LoaderInput): LoaderPlan {
   let at = STUB + STUB_SIZE;
   const plain: Array<Omit<Copy, "backward">> = [];
   const packedAt: number[] = [];
+  /** The block start of each copy in `plain`, which names its labels. */
+  const blockOf: 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 });
+      blockOf.push(block.range.start);
     }
     at += block.range.end - block.range.start + 1;
   }
@@ -405,25 +454,30 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     const copy = plain[index]!;
     return { ...copy, backward: copy.target.start > copy.source.start && overlaps(copy.target, copy.source) };
   });
+  const copyBlocks = order.map((index) => blockOf[index]!);
 
   const stackByte = 0x0100 + state.sp;
-  const lines: string[] = [...input.header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', "", `* = ${hex4(LOAD)}`];
+  const lines: string[] = [...input.header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', ...(input.macros ? ['!source "macros.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",
+    // The copier lies at the end of the loader file, which can be at $a000 or higher, under the BASIC ROM.
+    "        lda #$34",
+    "        sta $01",
     "        ldx #0",
-    `-       lda ${hex4(copierImage)},x`,
+    `-       lda ${COPIER_SOURCE},x`,
     `        sta ${hex4(copier)},x`,
-    `        lda ${hex4(copierImage + 0x100)},x`,
+    `        lda ${COPIER_SOURCE}+$100,x`,
     `        sta ${hex4(copier + 0x100)},x`,
     "        inx",
     "        bne -",
     `        jmp ${hex4(copier)}`,
     "}",
   );
+  // The labels around each block give the copy table its numbers, so a block can change its length.
   for (const block of blocks) {
-    lines.push("", `; ${block.what}`, `!pseudopc ${hex4(block.pseudo)} {`);
+    lines.push("", `; ${block.what}`, blockLabel(block.range.start, "from"), `!pseudopc ${hex4(block.pseudo)} {`, blockLabel(block.range.start, "to"));
     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) {
@@ -431,12 +485,13 @@ export function planLoader(input: LoaderInput): LoaderPlan {
         lines.push(`        !byte ${Array.from({ length: last - address + 1 }, (_, offset) => hex2(block.bytes(address + offset))).join(",")}`);
       }
     }
-    lines.push("}");
+    lines.push("}", blockLabel(block.range.start, "end"));
   }
   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.`,
+    COPIER_SOURCE,
     `!pseudopc ${hex4(copier)} {`,
     "!zone loader_copier {",
     "        lda #$34",
@@ -507,8 +562,8 @@ export function planLoader(input: LoaderInput): LoaderPlan {
     `        ldx #${hex2(state.x)}`,
     `        ldy #${hex2(state.y)}`,
     "        plp",
-    // A global label: the check of the loader stops here, before an interrupt can run (F-32).
-    `${LOADER_JUMP} jmp ${hex4(input.entry)}`,
+    // A global label: the check of the loader stops here, before an interrupt can run.
+    `${LOADER_JUMP} jmp ${input.entryName ?? hex4(input.entry)}`,
     ".count  !word 0",
     ".index  !byte 0",
     ".back   !byte 0",
@@ -520,12 +575,16 @@ export function planLoader(input: LoaderInput): LoaderPlan {
         ]),
     ".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}`);
-  }
+  copies.forEach((copy, index) => {
+    // A block that starts at $0000 skips $00/$01, which the loader sets last.
+    const start = copyBlocks[index]!;
+    const skip = copy.target.start - start;
+    const [from, end, to] = [blockLabel(start, "from"), blockLabel(start, "end"), blockLabel(start, "to")];
+    const length = skip === 0 ? `${end} - ${from}` : `${end} - ${from} - ${skip}`;
+    const read = copy.backward ? `${end} - 1` : plus(from, skip);
+    const write = copy.backward ? `${to} + ${end} - ${from} - 1` : plus(to, skip);
+    lines.push(`        !word ${length}, ${read}, ${write} : !byte ${copy.backward ? 1 : 0} ; ${copy.what}`);
+  });
   lines.push("        !word 0", "}", "}");
 
   return {
@@ -540,7 +599,7 @@ export function planLoader(input: LoaderInput): LoaderPlan {
 }
 
 /**
- * The copier's VIC-II part (D60): with the I/O area visible it sets the
+ * The copier's VIC-II part: 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.
  */