@8bitscript/atari8 0.1.0

package/src/banks.8bs

@@ -0,0 +1,124 @@
+// @8bitscript/atari8/banks — the extra RAM behind PORTB, if this machine
+// has any.
+//
+// Named by "8bitscript".exports["./banks"] in this package's package.json:
+//
+//     import { banks } from "@8bitscript/atari8/banks";
+//
+//     let kib: usmallint = banks.kib();   // 0 on an 800XL, 64 on a 130XE
+//
+// A run-time hardware probe, like @8bitscript/c64/reu. A 130XE is an
+// 800XL with 64 KiB more RAM, reached four 16 KiB banks at a time through
+// the window at `$4000`–`$7FFF`; the two machines are otherwise the same,
+// one binary runs on both, and this is how it finds out which it is on.
+// The build says which the emulator is fitted with (the catalog's `model`
+// option; `Memory.BANKED_KIB` from @8bitscript/system). A program that
+// never imports this file carries none of it.
+//
+// PORTB (`$D301`) is the PIA's second port, and on the XL/XE it is not a
+// joystick port at all but the memory-control register: bit 0 the OS ROM,
+// bit 1 BASIC, bits 2–3 which extended bank, bit 4 clear to let the *CPU*
+// see it at `$4000`, bit 5 clear to let *ANTIC* see it, bit 7 the
+// self-test ROM. Read from atari800's `MEMORY_HandlePORTB`, where the
+// 128 KiB machine's bank is `((byte & 0x0c) >> 2) + 1` and a machine with
+// no extended RAM runs the same code with no effect — which is exactly
+// what makes the probe work: on an 800XL the window never stops being
+// ordinary RAM.
+//
+// So the question is whether writing through the window with a bank
+// selected leaves base RAM alone. A marker goes into base RAM at `$4000`;
+// then each bank is selected in turn and given a marker of its own; then
+// base RAM is looked at again. If it still holds its marker, the writes
+// went somewhere else and the machine has extended RAM; if it holds the
+// last bank's marker, there was only ever one RAM there. Each bank is
+// then read back to be sure it kept its own marker and is not a mirror of
+// another.
+//
+// Only bits 2, 3 and 4 are ever touched, and only for the length of the
+// probe: bit 5 is left as it was so ANTIC keeps drawing the screen from
+// base RAM throughout, bit 0 so the OS ROM stays in (its vectors are live
+// — the OS's vertical-blank NMI runs whatever this code does, and `sei`
+// does not stop it), and bits 1 and 7 so BASIC and the self-test stay
+// where they were. PORTB is put back exactly as found.
+//
+// **This probe writes to `$4000`–`$4001`**, which is inside the region
+// the linker gives the program (`$2000`–`$BFFF`). It is safe only while
+// the program's own code and data end below `$4000` and its stack is
+// above `$7FFF` — true of anything this toolchain builds today (the
+// borders example ends at `$2332`, and the soft stack starts from MEMTOP,
+// around `$9C00`), and worth checking with `llvm-nm` for a program big
+// enough to reach `$4000`. See ../AGENTS.md.
+
+@address(0xD301) let portB: volatile<u8>;
+
+namespace Xe {
+    const KEEP: utinyint = 0xE3;         // bits 0, 1, 5, 6, 7 — everything but the bank and CPU-access bits
+    const CPU_BASE: utinyint = 0x10;     // bit 4 set: the CPU sees base RAM again
+    const WINDOW: usmallint = 0x4000;    // first byte of the 16 KiB window
+    const BASE_MARK: utinyint = 0x5A;    // what base RAM is given to hold
+    const BANK_MARK: utinyint = 0xA0;    // plus the bank number, what each bank is given
+    const BANKS: utinyint = 4;           // banks the 130XE's two bits can name
+}
+
+export namespace banks {
+    // Point the window at extended bank `bank` for the CPU only, keeping
+    // every other PORTB bit as `saved` had it.
+    function select(bank: utinyint, saved: utinyint): void {
+        portB = (saved & Xe.KEEP) | (bank * 4);
+    }
+
+    // Put the window back on base RAM.
+    function base(saved: utinyint): void {
+        portB = saved | Xe.CPU_BASE;
+    }
+
+    // Give every bank a marker of its own.
+    function markAll(saved: utinyint): void {
+        let bank: utinyint = 0;
+        while (bank != Xe.BANKS) {
+            banks.select(bank, saved);
+            memory.write(Xe.WINDOW, Xe.BANK_MARK + bank);
+            bank = bank + 1;
+        }
+        banks.base(saved);
+    }
+
+    // How many banks kept their own marker — 0 if the first one did not,
+    // which is what a machine with no extended RAM looks like once base
+    // RAM has been overwritten.
+    function kept(saved: utinyint): utinyint {
+        let bank: utinyint = 0;
+        while (bank != Xe.BANKS) {
+            banks.select(bank, saved);
+            let back: utinyint = memory.read(Xe.WINDOW);
+            banks.base(saved);
+            if (back != (Xe.BANK_MARK + bank)) {
+                return bank;
+            }
+            bank = bank + 1;
+        }
+        return Xe.BANKS;
+    }
+
+    // KiB of extended RAM this machine has: 0 on an 800XL or a 65XE, 64
+    // on a 130XE. One call at start-up; keep the answer.
+    //
+    // A machine with more than the 130XE's four banks (a 320XE, a 1088XE)
+    // needs more bank bits than the two this reads, and answers 64 here —
+    // the four it was asked about.
+    function kib(): usmallint {
+        let saved: utinyint = portB;
+        banks.base(saved);
+        memory.write(Xe.WINDOW, Xe.BASE_MARK);
+        banks.markAll(saved);
+        let found: utinyint = 0;
+        // Base RAM still holding its own marker is what says the bank
+        // writes went somewhere else at all.
+        if (memory.read(Xe.WINDOW) == Xe.BASE_MARK) {
+            found = banks.kept(saved);
+        }
+        portB = saved;
+        let k: usmallint = found;
+        return k * 16;
+    }
+}

package/src/console.8bs

@@ -0,0 +1,85 @@
+// @8bitscript/atari8/console — START, SELECT, OPTION and the console speaker.
+//
+// Named by "8bitscript".exports["./console"] in this package's package.json:
+//
+//     import { console, ConsoleKey } from "@8bitscript/atari8/console";
+//
+//     console.scan();
+//     if (console.pressed(ConsoleKey.START)) { ... }
+//
+// The three keys to the right of the keyboard are not on the keyboard: they
+// are three bits of GTIA's CONSOL ($D01F), active low, read directly with no
+// OS shadow and no interrupt in the way. That makes them the cheapest input
+// on the machine and the reason so many Atari games start on START and cycle
+// difficulty on SELECT — a cartridge with no DOS and no keyboard handler
+// still has these three.
+//
+// CONSOL is the register this project's own `examples/borders`
+// already reads for its OPTION readout; this file is that, named.
+//
+// ---- the fourth bit is an output ------------------------------------------
+//
+// The same register's bit 3 drives the console speaker — the click the OS
+// makes on every keypress. It is not a voice: there is no frequency and no
+// volume, only a cone that moves when the bit changes, so a tone means
+// toggling it in a timed loop and a "click" means toggling it twice. POKEY
+// is where sound lives (./pokey.8bs); this is here because it is the same
+// register and would otherwise be a trap — a program that writes CONSOL to
+// clear something and leaves bit 3 low holds the speaker cone out of centre.
+// `scan()` never writes CONSOL, and `click()` puts the bit back.
+//
+// Reading CONSOL returns the keys; writing it drives the speaker. They are
+// the same address and genuinely different registers, which is why this file
+// declares it twice.
+import { consolRead, consolWrite } from "./index.8bs";
+
+// The last scan: `ConsoleKey.*` bits, 1 = pressed, the hardware's active-low
+// sense inverted once here. Zero until the first scan.
+let state: utinyint = 0;
+
+export namespace ConsoleKey {
+    const START: utinyint = 1;
+    const SELECT: utinyint = 2;
+    const OPTION: utinyint = 4;
+}
+
+export namespace console {
+    // Read the three keys into the snapshot. Once a frame, beside
+    // joystick.scan(); unlike the joystick this reads the hardware and so
+    // is live whether or not the OS VBI is running.
+    function scan(): void {
+        state = (consolRead ^ 0x07) & 0x07;
+    }
+
+    // One key, from the snapshot: `console.pressed(ConsoleKey.START)`.
+    function pressed(key: utinyint): bool {
+        return (state & key) != 0;
+    }
+
+    // All three at once, as `ConsoleKey.*` bits.
+    function bits(): utinyint {
+        return state;
+    }
+
+    // Move the speaker cone out and back — the OS's keyclick, without the
+    // OS. Bit 3 low pushes the cone; the four low bits of a CONSOL write are
+    // the ones that matter, and $08 (bit 3 set) is its resting state, which
+    // is what this leaves behind. Two calls a frame is a buzz; one on an
+    // event is a click. A tone means toggling `speaker()` on a timed loop
+    // instead, which costs the CPU the whole time it sounds — POKEY is the
+    // answer for anything longer than a click.
+    function click(): void {
+        consolWrite = 0x00;
+        consolWrite = 0x08;
+    }
+
+    // The speaker bit on its own, for a program timing its own tone:
+    // `out` true pushes the cone, false lets it rest.
+    function speaker(out: bool): void {
+        if (out) {
+            consolWrite = 0x00;
+        } else {
+            consolWrite = 0x08;
+        }
+    }
+}

package/src/index.8bs

@@ -0,0 +1,150 @@
+// @8bitscript/atari8 — Atari 8-bit target support (400/800/XL/XE/XEGS): 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, cursorInhibit } from "@8bitscript/atari8";
+//
+// The surface is the hardware, one register at a time. 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 — which import these
+// registers and are built on nothing else.
+//
+// Border and background are two genuinely different GTIA registers here —
+// verified on screen under atari800, not inferred: in ANTIC's standard text
+// mode (the mode the OS boots into, and the one a .XEX inherits), COLBK
+// ($D01A) colours the BORDER around the playfield, while the area behind
+// the characters is COLPF2 ($D018). An earlier version of this package had
+// these the wrong way round: it mapped the background to COLBK and left the
+// border inert, so setting the background visibly painted the *border* and
+// setting the border did nothing at all.
+//
+// Every colour write goes through the OS SHADOW registers as well as the
+// hardware ones — see backgroundColorShadow below for why that is not
+// optional.
+
+// $D01A, GTIA's COLBK — the border, in ANTIC's standard text mode.
+@address(0xD01A)
+export let borderColor: volatile<u8>;
+
+// $D018, GTIA's COLPF2 — playfield 2, the colour behind the characters in
+// ANTIC's standard text mode.
+@address(0xD018)
+export let backgroundColor: volatile<u8>;
+
+// $D017, GTIA's COLPF1 — character luminance in ANTIC mode 2 (GR.0). Hue
+// comes from COLPF2; only the luminance nybble here is visible. Without a
+// write, the OS default is close enough to a dark COLPF2 that letters
+// vanish and only the inverse-video cursor block remains.
+@address(0xD017)
+export let textColor: volatile<u8>;
+
+// $02C8 (COLOR4), $02C6 (COLOR2), and $02C5 (COLOR1), the OS SHADOW
+// registers for COLBK, COLPF2, and COLPF1 above — and the ones that
+// actually decide what stays on screen.
+//
+// Writing the hardware registers alone looks correct for about a sixtieth of
+// a second and then silently undoes itself: an Atari program loaded the
+// ordinary way runs with the OS's interrupts live, and the OS's stage-2
+// vertical-blank routine copies its shadow registers in RAM ($02C4-$02C8)
+// over GTIA's colour registers ($D016-$D01A) on every single frame. So the
+// hardware register is not the durable place to put a colour while the OS is
+// running — the shadow is, and the OS then propagates it for us. This is not
+// theoretical: it is exactly why examples/borders rendered as a plain default
+// screen on atari800 before the shadow writes were added. (It is also the
+// same class of problem packages/backend-6502's FRAME_SYNC documents for the
+// PET, where the KERNAL's own IRQ handler wins a race for the vertical-
+// retrace flag; here the OS wins a race for the colour registers, every
+// frame, forever.)
+//
+// A program that takes the machine over completely — disabling the OS VBI —
+// would write only the hardware registers instead. This package's screen.8bs
+// targets the OS-friendly case, so it writes both.
+@address(0x02C8)
+export let borderColorShadow: volatile<u8>;
+
+@address(0x02C6)
+export let backgroundColorShadow: volatile<u8>;
+
+@address(0x02C5)
+export let textColorShadow: volatile<u8>;
+
+// $02F0, CRSINH — set non-zero to stop the OS screen editor drawing its
+// inverse-video cursor over whatever cell it sits on. Both
+// `screen.setColors()` and `text.putChar()` set it, so a program gets a
+// cursor-free screen whichever of the two it calls first.
+@address(0x02F0)
+export let cursorInhibit: volatile<u8>;
+
+// ---- the registers the layers above this file are built on ------------------
+//
+// Everything below is imported by one of this package's own hardware layers —
+// ./joystick.8bs, ./console.8bs, ./keyboard.8bs, ./pokey.8bs, ./random.8bs —
+// and a program that imports none of them links none of this. Each layer's
+// own file says what it does with these and why; this file only says where
+// they are.
+//
+// Two of them are the same address twice, which is not a mistake. On this
+// machine several I/O locations are one register when read and a completely
+// different one when written — GTIA's CONSOL, POKEY's KBCODE/STIMER and
+// SKSTAT/SKCTL — so each direction gets its own name and the layer that uses
+// it cannot pick the wrong one by accident.
+
+// $004D, ATRACT — the OS's attract-mode counter. Its VBI counts this up and,
+// once it passes a threshold (roughly nine minutes), starts cycling the
+// playfield colours to spare the phosphor. The OS zeroes it on a keypress, so
+// only a program read with a joystick has to; @8bitscript/atari8/joystick's
+// scan() does, every frame.
+@address(0x004D)
+export let attract: volatile<u8>;
+
+// $02FC, CH — the last key the OS's keyboard handler decoded, $FF for
+// "nothing new". A program consumes a key by writing $FF back.
+@address(0x02FC)
+export let chShadow: volatile<u8>;
+
+// $D01F read: GTIA's CONSOL as the three console keys, bits 0/1/2 =
+// START/SELECT/OPTION, 0 while pressed.
+@address(0xD01F)
+export let consolRead: volatile<u8>;
+
+// $D01F written: the same address as the console speaker. Bit 3 low pushes
+// the cone; $08 is its resting state.
+@address(0xD01F)
+export let consolWrite: volatile<u8>;
+
+// $D209 read: POKEY's KBCODE, the raw scan code of the last key, with SHIFT
+// in bit 6 and CTRL in bit 7. (Writing this address is STIMER instead, which
+// nothing here does.)
+@address(0xD209)
+export let kbcode: volatile<u8>;
+
+// $D20F read: POKEY's SKSTAT. Its keyboard bits are active low — bit 2 is 0
+// while the last key is still held, bit 3 is 0 while SHIFT is held. (Writing
+// this address is SKCTL, which nothing here does: the OS leaves it at $03 to
+// keep POKEY's keyboard scan and debounce running, and a program that
+// overwrites it breaks its own keyboard.)
+@address(0xD20F)
+export let skstat: volatile<u8>;
+
+// $D208, POKEY's AUDCTL — the global audio control: clock choice, the
+// high-pass links, the 16-bit channel joins. Per-voice AUDF/AUDC are
+// $D200-$D207 and @8bitscript/atari8/pokey reaches them by offset from a
+// base rather than as eight names.
+@address(0xD208)
+export let audctl: volatile<u8>;
+
+// $D20A read: POKEY's RANDOM, a sample of the free-running 17-bit polynomial
+// counter. Behind @8bitscript/atari8/random and deliberately nowhere else.
+@address(0xD20A)
+export let randomRegister: volatile<u8>;
+
+// $D014 read: GTIA's PAL register, the TV standard this machine was built
+// for. A PAL machine answers 1 in the low bits, an NTSC one 14 or 15
+// (atari800 returns $01 and $0F). One binary reads it at start-up and adapts,
+// the way the frame runtime already does.
+@address(0xD014)
+export let palRegister: volatile<u8>;

package/src/input.8bs

@@ -0,0 +1,178 @@
+// @8bitscript/atari8/input — the Atari 8-bit behind @8bitscript/input.
+//
+// Named by "8bitscript".exports["./input"] in this package's package.json,
+// and by "8bitscript".entry.atari8 in @8bitscript/input's, so a portable
+// program writes
+//
+//     import { input } from "@8bitscript/input";
+//
+// and gets this file on a 400, 800, XL or XE. The layers underneath —
+// ./keyboard.8bs with ./keys.8bs, ./joystick.8bs, ./console.8bs — stay
+// available to a program that wants what this file does not map.
+//
+// ---- four directions out of a keyboard that has no arrow keys ------------
+//
+// This machine has no arrow keys. It has four *keys with arrows printed on
+// them* — `+` `*` `-` `=` — which the OS turns into cursor movement only
+// when CTRL is held, and that is genuinely how an Atari user moves a
+// cursor. So:
+//
+//   - **left** CTRL and `+`, **right** CTRL and `*`,
+//     **up** CTRL and `-`, **down** CTRL and `=`.
+//   - **confirm** — RETURN, or the joystick's fire button.
+//   - **cancel** — ESC.
+//
+// A joystick in **port 1** is or'd on top of the keyboard, so a program
+// does not care which the user reached for. Ports 3 and 4 exist only on a
+// 400 or an 800 (`Joystick.PORTS` is the fact), and this file reads
+// neither: the portable surface describes one user driving one interface.
+//
+// The console keys — START, SELECT, OPTION — are *not* mapped here. They
+// are the machine's own three buttons and a program that wants them means
+// them specifically; folding them into `confirm()` would make a menu
+// commit when someone reached for the one that usually means "choose
+// something else". ./console.8bs is one import away.
+//
+// ---- the mouse this file does not drive ----------------------------------
+//
+// **The catalog offers three, and none of them has a driver yet.**
+// `--hardware mouse=st`, `=amiga` and `=trak` all set `input.mouse` true,
+// so `#fact(input.mouse)` says this build may use one — and this file
+// still answers `pointer()` false, because saying "maybe" and then never
+// finding one is worse than saying no.
+//
+// What is missing is a real driver, and it is not the C64's. An ST or
+// Amiga mouse on this machine is **quadrature on the joystick port's four
+// direction lines** — two bits per axis whose *transition order* gives the
+// direction — read through PORTA, not through an analogue converter. The
+// Atari trak-ball is a third protocol again, and a 1350-style mouse would
+// be a fourth. That is a per-device driver in this package with its own
+// `detect`, sitting beside ./joystick.8bs, and then three lines here.
+// Until someone writes and verifies it against atari800, this file says
+// what is true: no pointer.
+//
+// ---- edges, not levels ---------------------------------------------------
+//
+// Every answer is **edge-triggered**: true on the one frame the press
+// begins, false while it is held. `poll()` must be called exactly once a
+// frame, right after waitFrame().
+//
+// One caution this machine brings that the Commodores do not: its keyboard
+// hardware reports **one key code at a time**, not a matrix — so "CTRL and
+// `+`" is the CTRL *modifier bit* alongside the last key code, which the
+// hardware does give, but two ordinary keys at once is not a question this
+// machine can answer. That is a property of the hardware, not of this file.
+import { keyboard } from "./keyboard.8bs";
+import { Key } from "./keys.8bs";
+import { joystick, Joystick } from "./joystick.8bs";
+
+namespace Edge {
+    const LEFT: utinyint = 1;
+    const RIGHT: utinyint = 2;
+    const UP: utinyint = 4;
+    const DOWN: utinyint = 8;
+    const CONFIRM: utinyint = 16;
+    const CANCEL: utinyint = 32;
+}
+
+let held: utinyint = 0;
+let before: utinyint = 0;
+let began: utinyint = 0;
+
+export namespace input {
+
+    // Nothing to set up: no pointer to give a ceiling to. Here so a
+    // program written for nine machines calls the same thing on all.
+    function begin(): void {
+    }
+
+    // Read the key register and the port, and work out what began this
+    // frame. Once a frame, right after waitFrame().
+    function poll(): void {
+        keyboard.scan();
+        joystick.scan();
+
+        before = held;
+        held = 0;
+
+        // The arrows are CTRL plus a printed key — asked once and reused,
+        // because the modifier is a separate bit from the key code.
+        if (keyboard.control()) {
+            if (keyboard.pressed(Key.PLUS)) {
+                held = held | Edge.LEFT;
+            }
+            if (keyboard.pressed(Key.ASTERISK)) {
+                held = held | Edge.RIGHT;
+            }
+            if (keyboard.pressed(Key.DASH)) {
+                held = held | Edge.UP;
+            }
+            if (keyboard.pressed(Key.EQUALS)) {
+                held = held | Edge.DOWN;
+            }
+        }
+        if (keyboard.pressed(Key.RETURN)) {
+            held = held | Edge.CONFIRM;
+        }
+        if (keyboard.pressed(Key.ESC)) {
+            held = held | Edge.CANCEL;
+        }
+
+        let stick: utinyint = joystick.bits(Joystick.PORT_1);
+        if ((stick & Joystick.LEFT) != 0) {
+            held = held | Edge.LEFT;
+        }
+        if ((stick & Joystick.RIGHT) != 0) {
+            held = held | Edge.RIGHT;
+        }
+        if ((stick & Joystick.UP) != 0) {
+            held = held | Edge.UP;
+        }
+        if ((stick & Joystick.DOWN) != 0) {
+            held = held | Edge.DOWN;
+        }
+        if ((stick & Joystick.FIRE) != 0) {
+            held = held | Edge.CONFIRM;
+        }
+
+        began = held & (before ^ 0xFF);
+    }
+
+    function left(): bool {
+        return (began & Edge.LEFT) != 0;
+    }
+
+    function right(): bool {
+        return (began & Edge.RIGHT) != 0;
+    }
+
+    function up(): bool {
+        return (began & Edge.UP) != 0;
+    }
+
+    function down(): bool {
+        return (began & Edge.DOWN) != 0;
+    }
+
+    function confirm(): bool {
+        return (began & Edge.CONFIRM) != 0;
+    }
+
+    function cancel(): bool {
+        return (began & Edge.CANCEL) != 0;
+    }
+
+    // No driver for any of the three mice the catalog offers — see the
+    // header. False rather than "maybe", and a constant either way.
+    function pointer(): bool {
+        return false;
+    }
+
+    function pointerCell(): usmallint {
+        return 0;
+    }
+
+    function pointerButton(): bool {
+        return false;
+    }
+}