@8bitscript/c64 0.1.0

package/src/index.8bs

@@ -0,0 +1,427 @@
+// @8bitscript/c64 — C64 target support: the hardware underneath.
+//
+// The module entry point named by the "8bitscript".entry field in this
+// package's package.json, resolved and linked for:
+//
+//     import { borderColor, backgroundColor, memoryPointer } from "@8bitscript/c64";
+//     import { spriteEnable, spritePositions, cia1PortA } from "@8bitscript/c64";
+//     import { reuStatus, reuCommand } from "@8bitscript/c64"; // --profile reu*
+//
+// The surface is the hardware, one register at a time — the VIC-II, the
+// SID, the two CIAs, the 6510's own port — under the names llvm-mos-sdk's
+// c64.h gives the chips (`VIC`, `SID`, `CIA1`, `CIA2`) and the fields its
+// _vic2.h/_sid.h/_6526.h give the registers. What a program usually wants
+// sits one layer up, in this package's own implementations of the portable
+// capability packages — `./src/screen.8bs` behind @8bitscript/screen and
+// `./src/text.8bs` behind @8bitscript/text, named by the "8bitscript".exports
+// map in package.json — and in the C64-only subpaths beside them:
+// `@8bitscript/c64/sprites`, `/raster`, `/bitmap`, `/charset`, `/scroll`,
+// `/keyboard` + `/keys`, `/joystick`, `/sid`, `/reu`, `/mouse`. All of
+// them import these registers and are built on nothing else. A
+// project that imports THIS package has declared itself C64 specific.
+//
+// Every fact stated here was read in a primary source or seen on screen
+// under x64sc; packages/c64/AGENTS.md says which, and holds what was not
+// checked. Where the VIC-20's VIC packs border, background, and video mode
+// into one register, the C64's VIC-II gives each its own; both take the low
+// four bits, and the VIC-II has sixteen colours everywhere.
+import { Video } from "./geometry.8bs";
+
+// ---- the 6510's port: what the CPU sees at $A000, $D000, $E000 -------------
+//
+// $0001, the processor port. Bits 0-2 are LORAM, HIRAM and CHAREN: which of
+// BASIC ROM, KERNAL ROM and the I/O area / character ROM the CPU sees over
+// the RAM that is always underneath. The SDK's start-up (unmap-basic.o's
+// .init section: `ldx #$2f / stx $00 / ldx #$3e / stx $01`) leaves it at
+// $3E — BASIC out, KERNAL in, I/O in — so $A000-$BFFF is program RAM. Bits
+// 3-5 are the cassette lines. Change it by reading, masking and writing
+// back, never with a literal: the three functions at the end of this file
+// are the only places this package does.
+//
+// The low three bits, and what the CPU sees (c64-wiki, "Bank Switching"):
+//   %111 $37  BASIC, KERNAL, I/O            the machine's boot state
+//   %110      BASIC, KERNAL, character ROM
+//   %011 $3B  RAM at $A000, KERNAL, I/O     the SDK's state (as $3E)
+//   %010      RAM at $A000, KERNAL, character ROM   the copy below
+//   %101 $35  RAM at $A000 and $E000, I/O   this package's state (as $3D)
+//   %100, %00x  RAM everywhere, no I/O      writes under I/O (as $3C)
+// HIRAM (bit 1) low hides the character ROM as well as the KERNAL: from
+// %101, clearing CHAREN gives RAM everywhere, not the ROM, so a copy of
+// the ROM sets %010 first and %101 after.
+@address(0x0001)
+export let processorPort: volatile<u8>;
+
+// ---- VIC-II ($D000-$D02E) ------------------------------------------------
+
+// $D000-$D00F: sprite 0's X, sprite 0's Y, sprite 1's X, ... — `2 * n` is
+// sprite n's X and `2 * n + 1` its Y (`spr_pos[n].x/.y` in _vic2.h). X is
+// nine bits wide: the ninth of each sprite is a bit of $D010.
+@address(0xD000)
+export let spritePositions: array<u8, 16>;
+
+// $D010, bit n = bit 8 of sprite n's X coordinate (`spr_hi_x`).
+@address(0xD010)
+export let spriteXHigh: volatile<u8>;
+
+// $D011, control register 1 (`ctrl1`): bit 7 RST8 (bit 8 of the raster
+// line, read; of the raster compare, write), 6 ECM, 5 BMM, 4 DEN (display
+// enable), 3 RSEL (25 rows / 24), 0-2 YSCROLL. The frame runtime reads
+// bit 7 (FRAME_SYNC.c64 in packages/backend-6502).
+@address(0xD011)
+export let control1: volatile<u8>;
+
+// $D012, the raster line's low eight bits (read) / raster compare (write).
+@address(0xD012)
+export let raster: volatile<u8>;
+
+// $D015, one enable bit per sprite (`spr_ena`).
+@address(0xD015)
+export let spriteEnable: volatile<u8>;
+
+// $D016, control register 2 (`ctrl2`): bit 4 MCM (multicolour text/bitmap),
+// 3 CSEL (40 columns / 38), 0-2 XSCROLL.
+@address(0xD016)
+export let control2: volatile<u8>;
+
+// $D017 / $D01D, one bit per sprite: drawn twice as tall / twice as wide.
+@address(0xD017)
+export let spriteExpandY: volatile<u8>;
+@address(0xD01D)
+export let spriteExpandX: volatile<u8>;
+
+// $D018, the VIC-II's memory pointer (`addr` in _vic2.h): bits 4-7 the
+// screen matrix's position in the bank in 1K steps, bits 1-3 the character
+// set's in 2K steps (bit 3 alone for a bitmap). $15 is the KERNAL's boot
+// value (screen $0400, ROM upper-case set at $1000, POKE 53272,21 in the
+// Programmer's Reference Guide); this package's screen is at $E000 with
+// its own copy of the ROM at $D000, which in bank 3 is $84 — see
+// Video.MEMORY_POINTER_UPPERCASE in ./geometry.8bs.
+@address(0xD018)
+export let memoryPointer: volatile<u8>;
+
+// $D019 / $D01A, interrupt status and mask (`irr`/`imr`): bit 0 raster,
+// 1 sprite-background collision, 2 sprite-sprite collision, 3 light pen;
+// status bit 7 = any. Writing a 1 to a status bit acknowledges it. The
+// program runs with interrupts off (see FRAME_SYNC.c64) and polls; the
+// one interrupt this package ever enables is the raster compare, for
+// @8bitscript/c64/raster's write list, whose handler acknowledges it.
+@address(0xD019)
+export let interruptStatus: volatile<u8>;
+@address(0xD01A)
+export let interruptMask: volatile<u8>;
+
+// $D01B, one bit per sprite: 1 = the sprite is drawn BEHIND the
+// background's foreground pixels (`spr_bg_prio`). Sprite-to-sprite order
+// is fixed: a lower-numbered sprite is always in front.
+@address(0xD01B)
+export let spritePriority: volatile<u8>;
+
+// $D01C, one bit per sprite: multicolour (12x21 double-width pixels, three
+// colours plus transparent: the sprite's own and the two shared ones).
+@address(0xD01C)
+export let spriteMulticolor: volatile<u8>;
+
+// $D01E / $D01F: which sprites touched another sprite / the background's
+// foreground since last read. Both CLEAR WHEN READ (and cannot be
+// written), so read each once a frame and keep the value.
+@address(0xD01E)
+export let spriteCollision: volatile<u8>;
+@address(0xD01F)
+export let spriteBackgroundCollision: volatile<u8>;
+
+// $D020, the border colour; $D021-$D024, background colours 0-3 (only 0
+// shows in the standard text mode; 1-3 are for extended-colour and
+// multicolour modes); $D025 / $D026, the two colours every multicolour
+// sprite shares; $D027-$D02E, each sprite's own colour. Low four bits.
+@address(0xD020)
+export let borderColor: volatile<u8>;
+@address(0xD021)
+export let backgroundColor: volatile<u8>;
+@address(0xD022)
+export let backgroundColor1: volatile<u8>;
+@address(0xD023)
+export let backgroundColor2: volatile<u8>;
+@address(0xD024)
+export let backgroundColor3: volatile<u8>;
+@address(0xD025)
+export let spriteSharedColor0: volatile<u8>;
+@address(0xD026)
+export let spriteSharedColor1: volatile<u8>;
+@address(0xD027)
+export let spriteColors: array<u8, 8>;
+
+// ---- SID ($D400-$D41C) ------------------------------------------------------
+//
+// Twenty-five registers, seven per voice then the filter and volume. The
+// write-only ones read back as nothing useful — the SID has no readable
+// state below $D419 — so @8bitscript/c64/sid keeps its own copy of what it
+// wrote. Voice n's registers start at 7 * n: 0-1 frequency (low, high),
+// 2-3 pulse width (low, high nybble), 4 control (bit 0 gate, 1 sync, 2
+// ring, 3 test, 4 triangle, 5 sawtooth, 6 pulse, 7 noise), 5 attack/decay
+// nybbles, 6 sustain/release nybbles. 21-22 filter cutoff (low three bits,
+// high eight), 23 resonance nybble / which voices are filtered, 24 = $D418:
+// filter mode bits 4-6, voice 3 off bit 7, master volume in the low nybble.
+@address(0xD400)
+export let sidRegisters: array<u8, 25>;
+
+// $D419 / $D41A, the two paddle A/D converters (`ad1`/`ad2`); which port's
+// paddles is CIA1 port A bits 6-7's choice. $D41B / $D41C, voice 3's
+// oscillator and envelope, readable — the oscillator with a noise waveform
+// is the hardware entropy the root AGENTS.md wants kept out of the
+// deterministic PRNG.
+@address(0xD419)
+export let paddleX: volatile<u8>;
+@address(0xD41A)
+export let paddleY: volatile<u8>;
+@address(0xD41B)
+export let voice3Oscillator: volatile<u8>;
+@address(0xD41C)
+export let voice3Envelope: volatile<u8>;
+
+// ---- CIA1 ($DC00): keyboard, joysticks, the KERNAL's IRQ timer ---------------
+//
+// Port A ($DC00) drives the keyboard's eight columns (a 0 bit selects a
+// column) and reads joystick port 2 on bits 0-4; port B ($DC01) reads the
+// eight rows of the selected column, a 0 bit where a key is down, and
+// joystick port 1 on the same bits 0-4. The joystick lines sit in parallel
+// with the matrix — port 1's pull the rows, port 2's pull the columns —
+// which is why a joystick "types" and why @8bitscript/c64/keyboard and
+// /joystick read the ports in a fixed order once a frame. The KERNAL sets
+// the directions (A out, B in) at boot; the packages set them again.
+// Timer A ($DC04-$DC05) is the KERNAL's 60 Hz IRQ source, silenced by the
+// `sei` the frame runtime starts with; $DC0D is its interrupt control.
+@address(0xDC00)
+export let cia1PortA: volatile<u8>;
+@address(0xDC01)
+export let cia1PortB: volatile<u8>;
+@address(0xDC02)
+export let cia1DirectionA: volatile<u8>;
+@address(0xDC03)
+export let cia1DirectionB: volatile<u8>;
+@address(0xDC0D)
+export let cia1InterruptControl: volatile<u8>;
+
+// ---- CIA2 ($DD00): the VIC bank, the serial bus, the user port ---------------
+//
+// Port A bits 0-1 choose the VIC's 16K bank, INVERTED: %11 = bank 0
+// ($0000, the boot state), %10 = bank 1 ($4000), %01 = bank 2 ($8000),
+// %00 = bank 3 ($C000, this package). Bits 3-5 are the serial bus (ATN,
+// CLOCK and DATA out) and bits 6-7 its inputs, so the bank is changed by
+// masking, never by storing a whole byte. $DD02 is the direction register:
+// bits 0-1 must be outputs (the KERNAL sets $3F). $DD0D is CIA2's
+// interrupt control: its interrupts are the NMI line (the RESTORE key is
+// the other NMI source), and @8bitscript/c64/raster masks them.
+@address(0xDD00)
+export let cia2PortA: volatile<u8>;
+@address(0xDD02)
+export let cia2DirectionA: volatile<u8>;
+@address(0xDD0D)
+export let cia2InterruptControl: volatile<u8>;
+
+// ---- the screen's memory --------------------------------------------------
+//
+// `screenRam`, `colorRam`, `spritePointers` and `spriteShapes` — the arrays
+// over the RAM the VIC reads — are declared in ./geometry.8bs beside the
+// addresses they are built from, and imported from there.
+
+// ---- the machine's state: which mode, and whether interrupts are on --------
+//
+// What the VIC is showing — `VideoMode.TEXT` (the screen at $E000 over the
+// character set at $D000, the state setupVideo() leaves) or
+// `VideoMode.BITMAP` (@8bitscript/c64/bitmap: the bitmap at $E000, its
+// colour matrix under the I/O area). The sprite layer reads it, because
+// the sprite pointers move with the screen matrix; text's prepare() reads
+// it, because its $D018 write is the text mode's.
+export namespace VideoMode {
+    const TEXT: utinyint = 0;
+    const BITMAP: utinyint = 1;
+}
+export let videoMode: utinyint = 0;
+
+// True once @8bitscript/c64/raster has enabled the raster interrupt. The
+// one thing it changes here: a window with the I/O area banked out
+// (bankIoOut/bankIoIn below) has to be an interrupt-free window, because
+// an interrupt handler that fires inside it acknowledges $D019 into RAM
+// and fires again forever — the hang the copy below documents.
+export let interruptsOn: bool = false;
+
+// ---- video set-up: the bank, the character set, the pointer -----------------
+//
+// Once, before the first thing is drawn: copy the character ROM into the
+// RAM under it, point the VIC at bank 3, set $D018, and bank the KERNAL
+// out. Every surface in this package calls it first (screen.blank(),
+// text's prepare(), the sprites' show()), and the guard makes every call
+// after the first cost a load and a branch.
+//
+// The copy (copyCharacterRom): with CHAREN ($01 bit 2) clear and HIRAM
+// set, the CPU READS the character ROM at $D000-$DFFF, and its WRITES
+// there still land in the RAM underneath — so reading each byte and
+// storing it back to the same address copies the ROM into RAM in place.
+// The I/O area is gone for the length of the loop (about four frames at
+// 1 MHz), so nothing here touches a register inside it, and interrupts are
+// off around it: the KERNAL's IRQ handler ends by reading CIA1's interrupt
+// register to acknowledge, which with I/O banked out reads the ROM
+// instead and never acknowledges — the interrupt fires again on return,
+// forever. Seen here: the first version of this copy, run before the
+// frame runtime's own `sei`, hung the machine exactly so. `sei` here as
+// well, so a program that draws before its first waitFrame() — or never
+// calls it — is safe too; from this point on the program owns the machine
+// (packages/c64/AGENTS.md).
+//
+// The KERNAL goes out ($01 low bits %101) at the end, and stays out. Two
+// reasons, both structural. The screen is at $E000, and with the KERNAL
+// ROM mapped the CPU's writes there land in RAM but its READS return ROM:
+// `screenRam[cell]` read back the KERNAL, a coarse scroll copied it, a
+// bitmap plot would read-modify-write it. With the ROM out, $E000-$FFFF
+// reads as the RAM the VIC shows. And the CPU's interrupt vectors at
+// $FFFA-$FFFF are then RAM too, which is how @8bitscript/c64/raster owns
+// the IRQ without the KERNAL's handler in the way: this package's native
+// start-up code (native/6502/raster.s, an .init section, so it runs before
+// main() in every program that links this package) has already pointed
+// both the NMI and the IRQ vector at a bare `rti`, so a RESTORE key press
+// with the ROM out does nothing at all. Nothing in an 8bitscript program
+// calls the KERNAL after this point — main() never returns to it either.
+let videoReady: bool = false;
+
+export function setupVideo(): void {
+    if (videoReady) {
+        return;
+    }
+    videoReady = true;
+    asm6502 {
+        sei
+    }
+    copyCharacterRom();
+    cia2DirectionA = cia2DirectionA | 0x03;
+    cia2PortA = cia2PortA & 0xFC; // bank 3
+    memoryPointer = Video.MEMORY_POINTER_UPPERCASE;
+    spriteEnable = 0; // no sprite until a program asks; the pointers are whatever RAM held
+}
+
+// The character ROM's 4K into the RAM under it, in place, and the port left
+// at %101 (KERNAL out, I/O in). Safe from any port state, and callable
+// again — @8bitscript/c64/charset's restore() is a second copy over a
+// program's own glyphs. Interrupts are off for the copy and back on after
+// it only if the raster interrupt had them on.
+export function copyCharacterRom(): void {
+    asm6502 {
+        sei
+    }
+    processorPort = (processorPort & 0xF8) | 0x02; // %010: KERNAL in, character ROM at $D000, I/O out
+    for (let i: usmallint = 0; i < 4096; i++) {
+        memory.write(Video.CHARSET + i, memory.read(Video.CHARSET + i));
+    }
+    processorPort = (processorPort & 0xF8) | 0x05; // %101: KERNAL out, I/O in
+    if (interruptsOn) {
+        asm6502 {
+            cli
+        }
+    }
+}
+
+// ---- the region, at run time ------------------------------------------------
+//
+// PAL or NTSC is not a build fact: one .prg runs on both, and the frame
+// runtime finds out for itself at start-up (FRAME_SYNC.c64's probe,
+// packages/backend-6502) — but keeps the answer to itself. So this is the
+// same probe, for a program that needs it: @8bitscript/c64/sid's note
+// tables (the SID's pitch is the CPU clock's), a program timing something
+// in raster lines. Sync to the top of a frame, then watch one whole frame
+// go by: only a PAL raster (312 lines) ever reaches line 288 — bit 8 set
+// in $D011 with $D012 at 32 or more — where an NTSC frame stops at 262.
+// Two frames, once; keep the answer. A cross-machine builtin that
+// publishes the runtime's own answer is the design this waits for.
+export namespace Region {
+    const PAL: utinyint = 0;
+    const NTSC: utinyint = 1;
+}
+
+function rasterInTopHalf(): bool {
+    // $D012 first, then $D011 bit 8 (FRAME_SYNC.c64 says why the order).
+    return raster < 128 && (control1 & 0x80) == 0;
+}
+
+export function detectRegion(): utinyint {
+    let pal: bool = false;
+    while (rasterInTopHalf()) {}
+    while (!rasterInTopHalf()) {} // the wrap to line 0
+    while (rasterInTopHalf()) {}
+    while (!rasterInTopHalf()) {
+        if ((control1 & 0x80) != 0 && raster >= 32) {
+            pal = true;
+        }
+    }
+    if (pal) {
+        return Region.PAL;
+    }
+    return Region.NTSC;
+}
+
+// ---- writes under the I/O area --------------------------------------------
+//
+// $D000-$DFFF is RAM the VIC reads (the character set, and in bitmap mode
+// the colour matrix and the sprite pointers) that the CPU can only reach
+// with the I/O area banked out — so every write there is a window: `sei`,
+// CHAREN clear (%100 from %101: RAM everywhere), the writes, I/O back,
+// `cli` if the raster interrupt is on. Nothing between bankIoOut() and
+// bankIoIn() may touch a register, and the window is kept short: the
+// raster interrupt, if enabled, is late by the window's length.
+export function bankIoOut(): void {
+    asm6502 {
+        sei
+    }
+    processorPort = processorPort & 0xFB;
+}
+
+export function bankIoIn(): void {
+    processorPort = processorPort | 0x04;
+    if (interruptsOn) {
+        asm6502 {
+            cli
+        }
+    }
+}
+
+// One byte into the RAM under the I/O area, in its own window.
+export function writeUnderIo(address: usmallint, value: utinyint): void {
+    bankIoOut();
+    memory.write(address, value);
+    bankIoIn();
+}
+
+// One byte from the RAM under the I/O area.
+export function readUnderIo(address: usmallint): utinyint {
+    bankIoOut();
+    let value: utinyint = memory.read(address);
+    bankIoIn();
+    return value;
+}
+
+// ---- REU (RAM Expansion Unit) --------------------------------------------
+//
+// $DF00-$DF0A, the standard Commodore 1764/1750-compatible REU DMA
+// controller register map — confirmed against VICE's own `-reu`/`-reusize`
+// support (x64sc -help) and the register layout every REU-compatible
+// expansion since the 1700 has shared. These addresses exist in the SDK for
+// every c64 program (the same reasoning @8bitscript/pet's screen.8bs
+// documents for `setColors` on a machine without colour): they only do
+// something when the program is actually built and run against a `reu*`
+// hardware profile (--profile in packages/cli/src/build.mjs and run.mjs's
+// `-reu -reusize`) — on the stock C64 these are ordinary, if unusual,
+// memory-mapped I/O addresses, not a real DMA controller. This is raw
+// register access, not a transfer driver: a caller sequences the registers
+// itself (base addresses, length, then a command byte — bit 7 set to
+// execute, bits 0-1 for the transfer direction: 00 stash C64→REU, 01 fetch
+// REU→C64, 10 swap, 11 verify), the same level @8bitscript/vic20's
+// `vicColor` and this package's own `borderColor` above operate at.
+@address(0xDF00) export let reuStatus: volatile<u8>;
+@address(0xDF01) export let reuCommand: volatile<u8>;
+@address(0xDF02) export let reuC64AddressLow: volatile<u8>;
+@address(0xDF03) export let reuC64AddressHigh: volatile<u8>;
+@address(0xDF04) export let reuAddressLow: volatile<u8>;
+@address(0xDF05) export let reuAddressHigh: volatile<u8>;
+@address(0xDF06) export let reuBank: volatile<u8>;
+@address(0xDF07) export let reuLengthLow: volatile<u8>;
+@address(0xDF08) export let reuLengthHigh: volatile<u8>;
+@address(0xDF09) export let reuInterruptMask: volatile<u8>;
+@address(0xDF0A) export let reuAddressControl: volatile<u8>;