badline 0.9.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2916044b89e174698de9dd60a2a72121dc6aa91058a9de914dfbaa5e70170f29
-  data.tar.gz: 56adae369f806a6adb31dea00b5164d6e02e4b88d6a6cc08209808abdae0392b
+  metadata.gz: e82b9f5bb012d15fd7744f164b82420c3b71c00b14b43843093e1a2b3722beeb
+  data.tar.gz: cf94f9a74e8c9d5d6b9d3a94a5404d29376a4c57da7f18b78c9dd87da4a7c880
 SHA512:
-  metadata.gz: cac3c6ba20fff4bbabd7e77dd8eae4e53cb12a3785f946908407627eb29783764684c0e2cf208b6a8030ad31bcfb35811526873119d51cb5badd0f2598257b41
-  data.tar.gz: 93cecca78dbb7f4ca6393a629d113fa80a68a573359193ae4bcc54b87aadea883fdba0f84ad3ccb8acbad54539867b676e82e9f940420b50365f0fc7b93c33ff
+  metadata.gz: 14986d25fea5add5cecf4c10001b4f9cf9e087023f07bf8a8fc27d950f799ff41ae086518165ca67b840c440e5f56cf661d335ac5d4f5de347260c0bd44864bb
+  data.tar.gz: 12ba3fa5d2276efb1003edaa884e8f1c58ee7d2e2ac5e05b0f7d927e6d8b5a37869893f012d92560772b3adf18ea2d886c058737bf9e10aac25aec54e36afe6b

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [0.10.1](https://github.com/elektronaut/badline/compare/v0.10.0...v0.10.1) (2026-10-08)
+
+
+### Features
+
+* add the C64GS as --model c64gs ([ea04c0d](https://github.com/elektronaut/badline/commit/ea04c0d03b3a8c34426ff68a80ae0fc36db8123b))
+* add the C64GS as --model c64gs ([e533932](https://github.com/elektronaut/badline/commit/e533932360befa88d05cf1369cc417f40cababa7))
+* add the MAX Machine as --model ultimax ([fc48c40](https://github.com/elektronaut/badline/commit/fc48c40035892409175bf3d8fd08add6af0bbac9))
+* add the MAX Machine as --model ultimax ([22aca64](https://github.com/elektronaut/badline/commit/22aca643abc0746e362209fb48977cee94c2b985))
+* add the PET 64 as --model pet64 ([e17c0bd](https://github.com/elektronaut/badline/commit/e17c0bd0d13d15caf6d0b5377a5ac0a5756847cf))
+* add the PET 64 as --model pet64 ([2320ac7](https://github.com/elektronaut/badline/commit/2320ac7cd41ef6a4865e56d433585ddebb7ef01f))
+* bundle the C64GS's ROM, 390852-01 ([e31b280](https://github.com/elektronaut/badline/commit/e31b280044c18e639cc65df62a8b39d97dd874be))
+* bundle the PET 64's KERNAL, 901246-01 ([9a029ec](https://github.com/elektronaut/badline/commit/9a029ecfe25c0d9a806d8858253c4c172e175b7f))
+
+
+### Miscellaneous Chores
+
+* release 0.10.1 ([9d6f6ba](https://github.com/elektronaut/badline/commit/9d6f6ba71a647f24f00a830fbc772531fbcb4d92))
+
+## [0.10.0](https://github.com/elektronaut/badline/compare/v0.9.0...v0.10.0) (2026-10-08)
+
+
+### Features
+
+* add the VIC-20's bus and CPU ([184f4c2](https://github.com/elektronaut/badline/commit/184f4c28c609fe0d46358c0143fabe2beba2fa70))
+* name the machine family with a c64 or vic20 subcommand ([586a02f](https://github.com/elektronaut/badline/commit/586a02fbd80c6e6351d85c91263b5a39438ba13e))
+* open the pause menu from the timeline and screenshot it ([63dc744](https://github.com/elektronaut/badline/commit/63dc74468432397c1ec0273a64fcd28ff46008d2))
+* paint the VIC-20's display from the VIC-I's fetches ([76f67c3](https://github.com/elektronaut/badline/commit/76f67c3709363f682715681d17ea799441412f12))
+* play the VIC-20's sound from the VIC-I's voices ([c490a86](https://github.com/elektronaut/badline/commit/c490a86959e18e0fecdcf21bf0139b63be25d9a9))
+* read the VIC-20 .crt signature and the .tap platform byte ([fc0b130](https://github.com/elektronaut/badline/commit/fc0b130ad3a9481e7a9e61d909286281026797b1))
+* run the VIC-20 in the window, in both builds ([24c056c](https://github.com/elektronaut/badline/commit/24c056c531fb356d3d47a9aad94c50ba0a0b0031))
+* run the VIC-20 with its VIC-I registers and VIAs ([6089cee](https://github.com/elektronaut/badline/commit/6089ceee361e65d59c33a1eaeb3395f315eeed2d))
+* save and restore the VIC-20 in badline's own snapshots ([8620849](https://github.com/elektronaut/badline/commit/8620849be5177069e16a559a35b239d75d7cc82a))
+* serve the VIC-20's device 8 through the KERNAL traps and autostart its media ([356695e](https://github.com/elektronaut/badline/commit/356695e7529f999acf4bdc82951b107460ecdf39))
+* wire the VIC-20's datasette and serial bus to its VIAs, with a true 1541 ([2f06e88](https://github.com/elektronaut/badline/commit/2f06e88cf5276780cc03f7d8121480e95b05480f))
+* wire the VIC-20's keyboard, joystick and RESTORE to its VIAs ([32139f6](https://github.com/elektronaut/badline/commit/32139f647aeb3f5e7601928150b85973db6b9b5e))
+
+
+### Bug Fixes
+
+* show the disk device 8 holds on the menu's Drive page ([c8b0eaf](https://github.com/elektronaut/badline/commit/c8b0eaf05573246114af6b6f8404095424a1981c))
+* start the VIA shift register only when idle, on the 6522's clock ([bdcb1c8](https://github.com/elektronaut/badline/commit/bdcb1c88bb729e48ffdaaffd91e1274778c4ee29))
+
+
+### Performance Improvements
+
+* type Memory's storage as Array[Integer] for Spinel ([797c9b1](https://github.com/elektronaut/badline/commit/797c9b1cab26e6ace4f0d0a20011a3a084e73bc9))
+
 ## [0.9.0](https://github.com/elektronaut/badline/compare/v0.8.0...v0.9.0) (2026-10-05)
 
 

data/CLAUDE.md

@@ -50,7 +50,7 @@ requires only the namespace file.
 | rspec (`spec/`) | `bundle exec rspec` | Unit behaviour, all of `lib/` |
 | SingleStepTests 65x02 | `rake test` (100 sampled cases per opcode) | CPU, per-cycle bus traces |
 | Wolfgang Lorenz suite | `bin/lorenz` | CPU, CIA, interrupts |
-| VICE testbench | `bin/testbench <subtree>` | `VICII/`, `CIA/`, `interrupts/`, `CPU/`, cartridges with `--carts`, and the true 1541 drive with `--drive` |
+| VICE testbench | `bin/testbench <subtree>` | `VICII/`, `CIA/`, `interrupts/`, `CPU/`, cartridges with `--carts`, the true 1541 drive with `--drive`, and the VIC-20 with `--vic20` |
 | VICE SID testprogs | `bin/sidtests` | SID |
 | Drive scenarios | `bin/drive_scenarios` | The true 1541 running the DOS ROM: save, format, the error channel, idle, write protect and autostart |
 | CIA offline grids | `bundle exec rspec --tag slow spec/badline/cia` | CIA timers and shift register, against a bare CIA in about 2 min |
@@ -144,7 +144,7 @@ overrides that, capped by the core count, but keep the default, because
 other worktrees share the machine. Whole runs at 4 shards on an M-series
 laptop take 15 min for `testbench` (`VICII/`), 11 for `testbench-cia`, 1 for
 `testbench-interrupts`, 37 for `testbench-irqdma`, 11 for
-`testbench-cpu`, 2 for `testbench-carts` and about 25 for `testbench-expansions`. `sid` takes about 12 min. `lorenz` chains itself and takes
+`testbench-cpu`, 2 for `testbench-carts`, about 25 for `testbench-expansions` and under 1 for `testbench-vic20`. `sid` takes about 12 min. `lorenz` chains itself and takes
 about 2.5 h on CI whole. `rake regression:lorenz-1` to `lorenz-4` run it as
 four stretches of about 40 min each, and they can run side by side.
 `test/baselines/README.md` has the full table. A killed `bin/testbench` run
@@ -187,14 +187,16 @@ the rows your change can't reach tell you nothing about it.
 Pick the filters from the suites your change can move: VIC → `testbench`,
 plus `testbench-vicii-new` (`bin/testbench --vicii-new`, the 8565) for
 anything the VIC model reaches, and `testbench-ntsc` (`bin/testbench --ntsc`,
-the 6567R8 and 6567R56A) for anything a region's timing reaches;
+the 6567R8 and 6567R56A) and `testbench-drean` (`bin/testbench --drean`,
+the 6572) for anything a region's timing reaches;
 CPU, interrupts or timing → the matching `testbench-*` suite, plus
 `rake test` for CPU; CIA → the slow CIA specs first, then the matching
 `testbench-cia` rows, plus `testbench-cia-new` (`bin/testbench --cia-new`,
 the 6526A) for anything the interrupt register or the CIA model reaches; cartridge mappers, banking or power-on state →
 `testbench-carts`, plus `testbench-expansions` for banking; GEO-RAM, +60K,
 +256K, the REU or the VIC's BA line the REU follows → `testbench-expansions`; the 1541 drive, VIA or IEC bus →
-`testbench-drive` (`bin/testbench --drive`) and `drive-scenarios` (`bin/drive_scenarios <filter>`); SID → `sid`, plus `sid-8580` for anything the 8580
+`testbench-drive` (`bin/testbench --drive`) and `drive-scenarios` (`bin/drive_scenarios <filter>`), plus `testbench-vic20` for the VIA; the VIC-20 (`vic20/`) →
+`testbench-vic20` (`bin/testbench --vic20`); SID → `sid`, plus `sid-8580` for anything the 8580
 model reaches (`bin/sidtests --sid 8580`). Leave the Lorenz chain to CI,
 unless your code has a rule in `doc/pinned-behaviour.md` that names Lorenz
 tests: the interrupt polling, CPU port and CIA timer rules. Run just the

data/README.md

@@ -3,6 +3,8 @@
 
 # Badline
 
+![A C64 booted to BASIC in badline, its cursor blinking](doc/images/boot.gif)
+
 Badline is a Commodore 64 emulator written in Ruby. It emulates a PAL
 or NTSC machine one clock cycle at a time, stepping the 6510, the VIC-II, both
 CIAs and the SID together, so raster timing, bad lines and sprite DMA
@@ -10,8 +12,8 @@ are modelled at the cycle level.
 
 It runs programs, disk and tape images, cartridges and SID tunes, and
 the SDL2 front end supports the keyboard, joysticks, game controllers,
-paddles and a 1351 mouse. See [What's emulated](#whats-emulated) for the
-details.
+paddles and a 1351 mouse. It also runs a PAL VIC-20, as
+`badline vic20`. See [What's emulated](#whats-emulated) for the details.
 
 It comes in two builds of the same emulator:
 
@@ -65,6 +67,10 @@ Programs, disk and tape images and SID tunes start automatically, and
 a cartridge starts itself. A mounted directory waits for you to `LOAD`
 from it.
 
+The first argument can name the machine, as in `badline c64 game.prg`.
+The C64 is the default, and `--model` picks which C64. See
+[The VIC-20](#the-vic-20) for `badline vic20`.
+
 `badline-ruby` takes the same media and the same options, with the
 differences noted in the table. `--help` lists the options for either.
 
@@ -77,8 +83,9 @@ differences noted in the table. `--help` lists the options for either.
 | `--true-drive` | Put an emulated 1541 on device 8 instead of the KERNAL traps. See [Media](#media) |
 | `-s`, `--subtune N` | Pick a subtune of a `.sid` file, counting from 1 |
 | `--sid 6581`, `--sid 8580` | Fit the older or newer SID. `--sid auto`, the default, takes a `.sid` tune's own |
+| `--ram SIZE` | Give a VIC-20 the RAM expansion `SIZE`: `unexpanded`, `3k`, `8k`, `16k`, `24k`, `32k` or `all`. Without it, the VIC-20 gets the expansion its media needs. See [The VIC-20](#the-vic-20) |
 | `--reu SIZE` | Plug in a RAM Expansion Unit of `SIZE` K: 128, 256, 512 (a 1750) or up to 16384 |
-| `--model NAME` | Run another C64, named as in VICE: `c64` (the default, a PAL C64 with the 6569 VIC-II, 6526 CIAs and the 6581 SID), `c64c` (the PAL C64C, with the 8565, 6526As and the 8580), `ntsc` (the 6567R8), `newntsc` (the NTSC C64C, with the 8562, 6526As and the 8580), `oldntsc` (the first NTSC C64s' 6567R56A), `drean` (the Drean C64 of Argentina, PAL-N with the 6572) or `sx64` (the portable SX-64, with its own KERNAL and no datasette). `--sid` or a `.sid` tune's own SID takes the model's place |
+| `--model NAME` | Run another model of the machine, named as in VICE. For the C64: `c64` (the default, a PAL C64 with the 6569 VIC-II, 6526 CIAs and the 6581 SID), `c64c` (the PAL C64C, with the 8565, 6526As and the 8580), `ntsc` (the 6567R8), `newntsc` (the NTSC C64C, with the 8562, 6526As and the 8580), `oldntsc` (the first NTSC C64s' 6567R56A), `drean` (the Drean C64 of Argentina, PAL-N with the 6572), `sx64` (the portable SX-64, with its own KERNAL and no datasette), `pet64` (the PET 64 or Educator 64, a PAL C64 in a PET's case with its own KERNAL and a green monochrome monitor) `c64gs` (the C64GS games console, a PAL C64C with its own BASIC and KERNAL, and no keyboard or datasette) or `ultimax` (the MAX Machine of Japan, NTSC with 2K of RAM, one CIA and no ROMs, which runs only a cartridge). `--sid` or a `.sid` tune's own SID takes the model's place |
 | `--ntsc` | Run an NTSC C64, as `--model ntsc` does |
 | `--no-sound` | Don't play the SID (`badline` only, where sound is on by default) |
 | `--sound` | Play the SID (`badline-ruby`, where sound is off by default) |
@@ -94,7 +101,7 @@ differences noted in the table. `--help` lists the options for either.
 | --- | --- |
 | `--frames N` | Quit after N frames |
 | `--unpaced` | Run as fast as it can, without vsync or pacing |
-| `--at FRAME:EVENT` | Press keys, type, swap media or take a screenshot once `FRAME` frames have run |
+| `--at FRAME:EVENT` | Press keys, type, swap media, open the pause menu or take a screenshot once `FRAME` frames have run |
 | `--script FILE` | Run the events in `FILE`, one `FRAME:EVENT` a line |
 | `--screenshot FILE` | Save the last frame as a `.bmp` |
 | `--save-snapshot FILE` | Save the machine as a `.vsf` snapshot after the last frame |
@@ -134,6 +141,28 @@ red LED lights in the bottom right corner of the border.
 [doc/media.md](doc/media.md) has the details, and how to attach media
 from Ruby.
 
+## The VIC-20
+
+`badline vic20` runs a PAL VIC-20, and takes the same media as the C64
+apart from SID tunes:
+
+```sh
+badline vic20             # READY.
+badline vic20 game.prg    # Load and run a program
+badline vic20 game.d64    # Mount a disk image as device 8 and load it
+badline vic20 game.tap    # Insert a tape and load it
+badline vic20 game.crt    # Attach a cartridge
+```
+
+Without `--ram`, it picks the RAM expansion from where the program, or
+the first program on a disk, loads: a BASIC program gets the expansion
+its start of BASIC comes with, and more of BLK1 to BLK3 when it runs
+past `$3FFF`. A program that loads at `$A000` is a cartridge's ROM, and
+goes in as a `.crt` does. Disks go through the KERNAL traps or, with
+`--true-drive`, a 1541, as on the C64. `F11`, `F12` and the pause menu
+save and load the VIC-20 too, in badline's own snapshots: xvic's `.vsf`
+files don't load.
+
 ## Snapshots
 
 `F11` quicksaves the whole machine to the next of five slots in
@@ -219,6 +248,8 @@ through the rows, Right goes into a page and Left back out, and Return or
 Space presses a row. A row with choices steps to the next. The mouse works
 too.
 
+![The pause menu's Drive 8 page, with a disk in](doc/images/pause-menu.png)
+
 | Page | What it holds |
 |------|---------------|
 | Snapshots | Quicksave, save under a name, load a named save, and the latest quicksaves and autosaves |
@@ -259,6 +290,10 @@ program or `.sid` dropped on it opens the menu to ask first.
 - **REU**: the 1700, 1764 and 1750 and bigger units up to 16M
   (`--reu`), with DMA timed against the VIC's bad lines and sprites.
 - **Datasette**: `.tap` playback.
+- **VIC-20**: the 6502, the PAL 6561 VIC-I with its picture and sound,
+  both 6522 VIAs, the keyboard, the joystick and RESTORE, RAM
+  expansions up to 35K (`--ram`), cartridges, the datasette and the
+  serial bus to device 8 (`badline vic20`).
 - **1541**: an emulated drive running its own DOS (`--true-drive`).
 - **Cartridges**: standard 8K, 16K and Ultimax, Simons' BASIC, Ocean,
   Fun Play / Power Play, Super Games, Epyx FastLoad, Westermann

data/doc/library.md

@@ -42,6 +42,19 @@ model (`Badline::Model::ALL`):
 - `kernal: :sx64` fits the SX-64's KERNAL, and `datasette: false`
   leaves the cassette port empty, so inserting a tape raises
   `Badline::Datasette::Missing`. The SX-64 has both.
+- `kernal: :pet64` fits the PET 64's KERNAL, and `board: :pet64` its
+  green monochrome monitor: the VIC's `palette` is
+  `Badline::VIC::GREEN_PALETTE`, each colour's luminance in green. The
+  PET 64 has both.
+- `kernal: :gs` fits the C64GS's BASIC and KERNAL, and `board: :gs` its
+  case, which has no keyboard: `computer.keyboard` takes no keys. The
+  C64GS has both, and no datasette.
+- `board: :max` builds the MAX Machine's board: 2K of RAM at
+  `$0000-$07FF`, no ROMs mapped, CIA 1 alone, answering all through
+  `$DC00-$DFFF` but for the I/O 1 page a cartridge takes, and Ultimax
+  mode with or without a cartridge. CIA 2 is never on the bus, so the
+  VIC stays in bank 0. `Badline::Model::ULTIMAX` runs it on
+  `Badline::Region::NTSC_OLD`.
 
 ## Cartridges
 
@@ -63,7 +76,8 @@ Its contents are lost when the emulator quits.
 The KERNAL, BASIC and character ROMs come with the gem. To run other
 images, such as a patched KERNAL, point `BADLINE_ROM_PATH` at a
 directory that holds `kernal.rom`, `basic.rom` and `character.rom`, plus
-`kernal-sx64.rom` for the SX-64 and `eapi/eapi-am29f040-14` if you
+`kernal-sx64.rom` for the SX-64, `kernal-pet64.rom` for the PET 64,
+`c64gs.rom` for the C64GS and `eapi/eapi-am29f040-14` if you
 attach EasyFlash cartridges.
 `Badline.rom_path = dir` does the same before a `Badline::Computer` is
 built, and `nil` restores the bundled set.

data/doc/pinned-behaviour.md

@@ -30,8 +30,12 @@ only catches the rows that happen to move.
 - [CIA 6526 timer pipeline](#cia-6526-timer-pipeline)
 - [CIA 6526A interrupt register](#cia-6526a-interrupt-register)
 - [CIA serial shift register](#cia-serial-shift-register)
+- [VIA shift register](#via-shift-register)
 - [6510 I/O port](#6510-io-port)
 - [RAM power-on pattern](#ram-power-on-pattern)
+- [VIC-20 RAM power-on pattern](#vic-20-ram-power-on-pattern)
+- [VIC-I fetches and the V-bus](#vic-i-fetches-and-the-v-bus)
+- [VIC-I sound](#vic-i-sound)
 - [1541 serial port](#1541-serial-port)
 - [1541 disk mechanism](#1541-disk-mechanism)
 - [REU DMA](#reu-dma)
@@ -1196,6 +1200,43 @@ and each was knocked out: removing it fails the rows named.
   [`cia_spec.rb`](../spec/badline/cia_spec.rb) covers the flag timing, the
   waiting byte, both mode-change reports and the zero-latch stall.
 
+## VIA shift register
+
+- A read or write of SR starts a byte only while the register is idle
+  and enabled. An access in mode 0 starts nothing, even once the mode
+  changes, and an access before the eighth bit is in leaves the count
+  alone. The byte in progress runs on, and the first access after it
+  ends starts the next.
+- In the φ2 modes (2 and 6) CB1 falls on the second cycle after the
+  access, rises on the third, and so on. Mode 6 puts a bit out on cycles
+  +2, +4 … +16, mode 2 takes one in on cycles +3, +5 … +17, and the flag
+  rises with the eighth rising edge, on cycle +17.
+- In the timer 2 modes (1, 4 and 5) each clock edge comes two cycles
+  after the timer 2 low byte underflows, on the cycle after the low byte
+  reloads from its latch. The half period stays N + 2 cycles.
+- Pinned by the `VIC20/via_sr` rows, each checked by breaking the rule and
+  rerunning all 32. The plain and `exp` rows dump SR every 7 cycles, the
+  `ifr` and `iex` rows dump IFR, and the SR write comes before the ACR
+  write that sets the mode:
+  - Mode 0 starts nothing: `viasr08` and `viasr18`, and the `ifr`/`iex`
+    rows of modes 04, 08, 14 and 18, which would see the SR flag.
+  - No restart before the eighth bit: `viasr14` and `viasr18`. Their
+    reads come every 7 cycles, faster than a byte.
+  - The φ2 start a cycle late: `viasr08` and `viasr18`. Ticking from the
+    first cycle, or from the third, fails both.
+  - The timer 2 edge two cycles late: `viasr04`, `viasr10` and `viasr14`.
+    A delay of 0, 1 or 3 cycles fails all three.
+  - Every rule also fails the row's `exp` twin, the same test on an
+    expanded VIC-20.
+- Nothing pins whether the timer 2 delay keeps running while the register
+  is idle. It does, and freezing it passes every row too. Nothing pins
+  the flag's cycle in the φ2 modes either: no row starts a byte and then
+  reads IFR.
+- Spec guard: the mode blocks in
+  [`shift_register_spec.rb`](../spec/badline/via/shift_register_spec.rb)
+  and *the shift register* in
+  [`via_spec.rb`](../spec/badline/via_spec.rb).
+
 ## 6510 I/O port
 
 - DDR at `$00`/`$01`: inputs are pulled up, bit 5 reads low, and bits 3, 6
@@ -1239,6 +1280,111 @@ and each was knocked out: removing it fails the rows named.
     [`address_bus_spec.rb`](../spec/badline/address_bus_spec.rb).
 - The RAM expansions' extra banks still power on at `$00`.
 
+## VIC-20 RAM power-on pattern
+
+- The VIC-20's RAM powers on in alternating bytes, `$ff` at the even
+  addresses and `$00` at the odd ones, on every power cycle. The internal
+  RAM and the expansion blocks (RAM1-3, BLK1-3, BLK5) all follow it.
+  Colour RAM powers on at zero. `Vic20::Bus::RAM_POWER_ON` holds it.
+  - Pinned by `VIC20/raminitpattern`: `ae.crt` fails unless `$0288` reads
+    `$ff` and `jellymonsters.crt` unless `$1046` does, read from a
+    cartridge before the KERNAL clears RAM. The readme says AE and Jelly
+    Monsters need `$ff` there. Its dumps of real machines' `$1000-$1fff`
+    show bytes alternating `$00` and `$ff` on most machines, with either
+    phase, and noise or other patterns on the rest. They show nothing
+    for colour RAM or expansion RAM that a pattern could be read from.
+  - Spec guard: *RAM at power-on* in
+    [`vic20/bus_spec.rb`](../spec/badline/vic20/bus_spec.rb).
+
+## VIC-I fetches and the V-bus
+
+- On a line of the text window the 6561 fetches the first character code
+  4 cycles after the column in `$9000`, 16 cycles after the raster count
+  moves with the KERNAL's origin of 12, then the code's pattern byte in
+  the next cycle, two cycles a character. Outside the window it fetches
+  nothing.
+- A read where no chip answers in I/O 0 (`$9100`, `$9200`) returns the
+  V-bus's last byte: the VIC's fetch in a cycle it fetches in, and the
+  CPU's own last byte on the V-bus in the other cycles.
+  - Pinned by `VIC20/split-tests/timing`: all 1,024 bytes of its readings
+    of `$9003`, `$9004`, `$9100` and `$9200` over 256 cycles match
+    `dumps/dump6561e.prg`, a real 6561E. The later 6561-101's dump reads
+    `$20` in the idle cycles instead; badline follows the 6561E.
+  - Spec guard:
+    [`vic20/vic_split_tests_timing_spec.rb`](../spec/badline/vic20/vic_split_tests_timing_spec.rb)
+    (`:slow`), and *the fetches* in
+    [`vic20/vic_video_spec.rb`](../spec/badline/vic20/vic_video_spec.rb).
+- A write to `$900F` or `$900E` takes hold from the second of the four
+  pixels of the cycle it lands in, the reverse bit two pixels later, and
+  a character's pixels come out in the two cycles after its pattern
+  fetch. These match xvic's screenshots of a test of cycle-timed writes
+  pixel for pixel; no testprog or hardware capture checks them.
+  - Spec guard: *a colour write* in
+    [`vic20/vic_video_spec.rb`](../spec/badline/vic20/vic_video_spec.rb).
+
+## VIC-I sound
+
+No testprog checks the VIC-I's sound, so these rules are pinned by xvic
+(VICE 3.10) recordings, run as a black box: `-sounddev wav` at 44.1 kHz of
+programs that set the registers, the same programs run on badline, and
+the two compared by period, harmonics and spectrum. xvic's own source
+wasn't read.
+
+- A voice's counter comes round every 128 - ((value + 1) & 127) ticks of
+  16, 8, 4 and 2 cycles from bass to noise, and a tone voice's shift
+  register plays 16 shifts a period, as Marko Mäkelä's `VIC-I.txt`
+  (revision 1.2, Levente Hársfalvi's measurements) gives the frequencies.
+  - Pinned by xvic: `$900A` = `$FE`, `$80` and `$FF` measure 4329.70,
+    34.0922 and 33.8256 Hz, `$900B` = `$F0` 577.29 Hz, and `$900C` = `$F0`
+    and `$A0` 1154.59 and 182.30 Hz, each within 0.001 Hz of the formula
+    on the PAL clock.
+  - Spec guard: *a tone voice's counter* in
+    [`vic20/sound_spec.rb`](../spec/badline/vic20/sound_spec.rb).
+- A tone voice's shift register takes bit 7 back into bit 0 inverted while
+  the voice is on and a zero while it's off, and keeps shifting either way.
+  Bit 0 is the output, not gated by the enable bit. This is the die-shot
+  reading of the 6561 on the Denial forum (Lance Ewing: the feedback is a
+  NOR of bit 7 and the inverted enable bit, and the counter keeps shifting
+  a voice that's off).
+  - Pinned by xvic: a bass voice loaded with 10101010, 11000000, 10000000
+    and 11101000 by turning it on and off a shift at a time, then left
+    on, has the same harmonics in xvic's recording and badline's to
+    0.1 dB through the 12th. 10101010 puts the 7th and 9th harmonics
+    above the fundamental, which a register cleared while off couldn't.
+  - Spec guard: *a tone voice* in
+    [`vic20/sound_spec.rb`](../spec/badline/vic20/sound_spec.rb).
+- The noise voice's counter steps a 16-bit LFSR: bit 0 takes the XOR of
+  bits 3, 12, 14 and 15 while the voice is on and a one while it's off.
+  Each rise of the LFSR's bit 0 shifts the noise voice's own shift
+  register, bit 7 back into bit 0, inverted while the voice is on, and
+  its bit 0 is the output while the voice is on. These are the die-shot
+  readings on the Denial forum (Lance Ewing and nippur72), which also
+  say the voice is silent while off.
+  - Pinned by xvic: noise at `$FE` and `$FD` repeats every 0.11825 s and
+    0.2365 s (autocorrelation 0.98 at those lags, in both xvic's
+    recording and badline's), 65535 steps of 2 and 4 cycles. The octave
+    band levels of noise at `$FE`, `$FD`, `$F0`, `$C0` and `$80` match
+    xvic's within 0.5 dB up to 8 kHz.
+  - Spec guard: *the noise voice* in
+    [`vic20/sound_spec.rb`](../spec/badline/vic20/sound_spec.rb).
+- The output is the voices that are high plus 2/9 of a voice, times the
+  volume, so a volume write steps the output with every voice off, as
+  4-bit samples played through `$900E` need.
+  - Pinned by xvic: a volume step from 0 to 15 with every voice off peaks
+    at 0.218 of a voice turned on at volume 15.
+  - Spec guard: *the volume* in
+    [`vic20/sound_spec.rb`](../spec/badline/vic20/sound_spec.rb).
+  - Not pinned: the volume scales the output linearly. xvic's tone level
+    per volume step isn't linear (volume 1 is 0.099 of volume 15 and 14
+    is 1.015), and nothing here says whether the hardware is.
+- The output stage is a one-pole low-pass at 1,420 Hz and a one-pole
+  high-pass at 158 Hz.
+  - Pinned by xvic: a bass voice turned on at volume 15 fits those two RC
+    stages at 1,417 and 158.0 Hz, with an RMS error of 6 against a peak of
+    11,280. badline's own recording fits 1,420 and 157.6 Hz.
+  - Spec guard: *a step* in
+    [`vic20/sound/output_spec.rb`](../spec/badline/vic20/sound/output_spec.rb).
+
 ## 1541 serial port
 
 - The drive sees the C64's side of the serial bus a host cycle late. The

data/doc/snapshots.md

@@ -62,9 +62,23 @@ Every model saves this way, PAL, NTSC, old NTSC and Drean alike, and so
 does a machine with an REU, with its RAM, its registers and a transfer
 part way through. A snapshot only restores in the badline version that
 wrote it, into a machine with the same chip models, region, RAM
-expansion, REU, KERNAL and datasette. One saved before badline recorded
-the KERNAL and the datasette restores as a machine with the C64's KERNAL
-and a datasette.
+expansion, REU, KERNAL, datasette and board. One saved before badline
+recorded the KERNAL and the datasette restores as a machine with the
+C64's KERNAL and a datasette, and one saved before it recorded the board
+restores on a C64's.
+
+## The VIC-20
+
+`badline vic20` saves and restores the same way, with the same keys,
+slots and pause menu page. A VIC-20 snapshot holds its RAM and colour
+RAM, a cartridge's ROM, the VIC with its picture and sound, both VIAs,
+the CPU, the tape with its place on it, the disk or directory device 8
+serves through the traps and a true 1541, and restores into a VIC-20
+with the same RAM expansion. Its file names its machine `VIC20`, as
+xvic's do, and holds only the `BADLINE` module, so xvic doesn't open
+it, and badline doesn't open xvic's. Restoring a
+VIC-20 snapshot while a C64 runs, or a C64 one while a VIC-20 runs,
+swaps the machine in the window.
 
 ## VICE
 

data/lib/badline/address_bus/fittings.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Badline
+  class AddressBus
+    # What a model fits around the chips: its KERNAL, a datasette or none,
+    # and the board and case they sit in.
+    module Fittings
+      # The keywords #fit takes.
+      NAMES = %i[kernal datasette board].freeze
+
+      # The C64's board and case, the PET 64's, whose built-in monitor
+      # shows the VIC's output in shades of green, the C64GS's, which has
+      # no keyboard, or the MAX Machine's (:max): 2K of RAM, no ROMs, CIA 1
+      # alone at $DC00-$DFFF and the cartridge port in Ultimax mode.
+      BOARDS = %i[c64 pet64 gs max].freeze
+
+      attr_reader :board
+
+      # Fits the KERNAL ROM ROMs::KERNALS names, leaves the cassette port
+      # empty unless `datasette`, and puts the chips in the board BOARDS
+      # names.
+      def fit(kernal: :c64, datasette: true, board: :c64)
+        self.kernal = kernal unless kernal == :c64
+        @datasette.disconnect! unless datasette
+        self.board = board unless board == :c64
+      end
+
+      def board=(name)
+        raise ArgumentError, "no board named #{name}" unless BOARDS.include?(name)
+
+        @board = name
+        vic.palette = name == :pet64 ? VIC::GREEN_PALETTE : VIC::PALETTE
+        keyboard.connected = name != :gs
+        update_overlays!
+      end
+    end
+  end
+end

data/lib/badline/address_bus/pla.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Badline
+  class AddressBus
+    # The C64's PLA: what each page of the CPU's view maps to, from the
+    # CPU port's LORAM, HIRAM and CHAREN lines and the cartridge's EXROM
+    # and GAME. The bus that includes it supplies the page tables, the
+    # ROMs, the chips, and #map_ram_pages, which lays out the RAM that the
+    # ROMs, the cartridge and I/O map over.
+    module PLA
+      # A chip's registers seen at another page, which reads and writes
+      # them as at the page the chip starts at.
+      class Mirror
+        def initialize(chip, start)
+          @chip = chip
+          @start = start
+        end
+
+        def peek(addr) = @chip.peek(@start | (addr & 0xff))
+        def poke(addr, value) = @chip.poke(@start | (addr & 0xff), value)
+      end
+
+      private
+
+      def map_pla_pages
+        map_ram_pages
+        @ultimax ? map_ultimax_pages : map_banked_pages
+      end
+
+      def map_banked_pages
+        map_rom_overlays
+        map_cartridge_ram
+        @write_pages.fill(@cartridge.romh_writes, 0xe0, 0x20) if @cartridge&.romh_writes
+
+        if io?
+          map_io_pages
+        elsif character?
+          @read_pages.fill(character_rom, 0xd0, 0x10)
+        end
+      end
+
+      # Ultimax mode ignores the $01 lines: 4K of RAM, ROML/ROMH windows,
+      # I/O always visible and open address space everywhere else. The ROML
+      # and ROMH selects fire on writes as well, so cartridge RAM or flash in
+      # either window takes the writes there. The MAX has 2K of RAM, and is
+      # in Ultimax mode with no cartridge too.
+      def map_ultimax_pages
+        first = @board == :max ? 0x08 : 0x10
+        @read_pages.fill(@open_bus, first, 0x100 - first)
+        @write_pages.fill(@open_bus, first, 0x100 - first)
+        map_ultimax_cartridge if @cartridge
+        map_io_pages
+        map_max_io if @board == :max
+      end
+
+      def map_ultimax_cartridge
+        @read_pages.fill(@cartridge.roml, 0x80, 0x20) if @cartridge.roml
+        map_ultimax_writes(@cartridge.roml, 0x80)
+        @read_pages.fill(@cartridge.romh, 0xe0, 0x20) if @cartridge.romh
+        map_ultimax_writes(@cartridge.romh, 0xe0)
+        map_ultimax_a000
+      end
+
+      def map_ultimax_writes(bank, first_page)
+        @write_pages.fill(bank, first_page, 0x20) if bank.respond_to?(:poke)
+      end
+
+      def map_ultimax_a000
+        return unless (window = @cartridge.ultimax_a000)
+
+        @read_pages.fill(window, 0xa0, 0x20)
+        @write_pages.fill(window, 0xa0, 0x20)
+      end
+
+      # The MAX has no CIA 2 and no I/O 2: CIA 1 answers all through
+      # $DC00-$DFFF, but for the I/O 1 page a cartridge takes.
+      def map_max_io
+        @cia1_mirror ||= Mirror.new(cia1, 0xdc00)
+        (0xdd..0xdf).each { |page| @read_pages[page] = @write_pages[page] = @cia1_mirror }
+        return unless @cartridge
+
+        @write_pages[0xde] = @cartridge
+        @read_pages[0xde] = @cartridge if @cartridge.readable_io_pages.include?(0xde)
+      end
+
+      # EXROM and GAME select the cartridge whether or not it has a chip
+      # there, and an empty socket leaves the bus floating.
+      def map_rom_overlays
+        @read_pages.fill(@cartridge.roml || @open_bus, 0x80, 0x20) if roml?
+        if romh?
+          @read_pages.fill(@cartridge.romh || @open_bus, 0xa0, 0x20)
+        elsif basic?
+          @read_pages.fill(basic_rom, 0xa0, 0x20)
+        end
+        @read_pages.fill(kernal_rom, 0xe0, 0x20) if kernal?
+      end
+
+      # Cartridge RAM in the ROML or ROMH window decodes writes itself,
+      # whatever the $01 lines say.
+      def map_cartridge_ram
+        return unless @cartridge&.exrom&.zero?
+
+        map_cartridge_ram_bank(@cartridge.roml, 0x80)
+        map_cartridge_ram_bank(@cartridge.romh, 0xa0) if @cartridge.game.zero?
+      end
+
+      def map_cartridge_ram_bank(bank, first_page)
+        @write_pages.fill(bank, first_page, 0x20) if bank.is_a?(Cartridge::RAMBank)
+      end
+
+      def map_io_pages
+        {
+          vic => 0xd0..0xd3, sid => 0xd4..0xd7, color_ram => 0xd8..0xdb,
+          cia1 => 0xdc..0xdc, cia2 => 0xdd..0xdd, @open_bus => 0xde..0xdf
+        }.each do |chip, pages|
+          pages.each { |p| @read_pages[p] = @write_pages[p] = chip }
+        end
+        @ram_expansion.map_io(@read_pages, @write_pages)
+        @read_pages[0xd7] = @write_pages[0xd7] = @debug_register if @debug_register
+        @read_pages[0xdf] = @write_pages[0xdf] = @reu if @reu
+        map_cartridge_io if @cartridge
+        map_extra_sids unless @sid_slots.empty?
+      end
+
+      def map_cartridge_io
+        @write_pages.fill(@cartridge, 0xde, 2)
+        @cartridge.readable_io_pages.each { |p| @read_pages[p] = @cartridge }
+      end
+
+      def basic?
+        io_port.kernal? && io_port.basic? && game_high?
+      end
+
+      def game_high?
+        @cartridge.nil? || @cartridge.game == 1
+      end
+
+      def roml?
+        @cartridge&.exrom&.zero? && io_port.kernal? && io_port.basic?
+      end
+
+      def romh?
+        @cartridge&.exrom&.zero? && @cartridge.game.zero? && io_port.kernal?
+      end
+
+      # In 16K mode LORAM alone leaves $d000 as RAM, where it still maps I/O.
+      def character?
+        (io_port.kernal? || (io_port.basic? && game_high?)) && !io_port.io?
+      end
+
+      def io?
+        (io_port.basic? || io_port.kernal?) && io_port.io?
+      end
+
+      def kernal?
+        io_port.kernal?
+      end
+    end
+  end
+end