badline 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2916044b89e174698de9dd60a2a72121dc6aa91058a9de914dfbaa5e70170f29
-  data.tar.gz: 56adae369f806a6adb31dea00b5164d6e02e4b88d6a6cc08209808abdae0392b
+  metadata.gz: bd764dccd3b8af3f8e0dcbb7d17debc3fceb24a9899f80871ebbf184ffefd65b
+  data.tar.gz: 46a62d801813476242a407c09ab3ff4fec1126d10bfee134047f18e90fd86955
 SHA512:
-  metadata.gz: cac3c6ba20fff4bbabd7e77dd8eae4e53cb12a3785f946908407627eb29783764684c0e2cf208b6a8030ad31bcfb35811526873119d51cb5badd0f2598257b41
-  data.tar.gz: 93cecca78dbb7f4ca6393a629d113fa80a68a573359193ae4bcc54b87aadea883fdba0f84ad3ccb8acbad54539867b676e82e9f940420b50365f0fc7b93c33ff
+  metadata.gz: 82a62fb4a3de3ef65e123bacf22ba300efe628f1bde38815dc950a39034d8c2b9423de79b3805fce84e19bcbaa8100a3e67488d5ef0a3ecb2de6434689886883
+  data.tar.gz: 595b19f034d708db60089e707507e74281059d271527fe61e0a205d9e8e0853a4f6b4d077aeed648f59a86d06bf31d3ee6e5902345fdb52d5fb36ded8de94da3

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [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) 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 |
 | `--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/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

@@ -66,6 +66,19 @@ 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.
 
+## 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
 
 Snapshots use VICE's `.vsf` format. badline writes VICE's modules for

data/lib/badline/address_bus/pla.rb

@@ -0,0 +1,130 @@
+# 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
+      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 cartridges ignore 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.
+      def map_ultimax_pages
+        @read_pages.fill(@open_bus, 0x10, 0xf0)
+        @write_pages.fill(@open_bus, 0x10, 0xf0)
+        @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
+        map_io_pages
+      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
+
+      # 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

data/lib/badline/address_bus.rb

@@ -3,7 +3,7 @@
 require "badline/address_bus/saved_state"
 require "badline/address_bus/sid_slots"
 require "badline/address_bus/extra_sids"
-require "badline/address_bus/ultimax_pages"
+require "badline/address_bus/pla"
 require "badline/address_bus/roms"
 
 module Badline
@@ -34,7 +34,7 @@ module Badline
   # 0xE000-0xFFFF - KERNAL ROM / Cartridge ROM (high) - 8kb
   class AddressBus
     include Addressable
-    include UltimaxPages
+    include PLA
     include ExtraSIDs
     include ROMs
 
@@ -79,7 +79,7 @@ module Badline
       @joystick1 = Joystick.new
       @joystick2 = Joystick.new
       @control_ports = ControlPorts.new(keyboard: @keyboard, joystick1: @joystick1, joystick2: @joystick2)
-      @vic  = VIC.new(self, model: vic_model, region:)
+      @vic  = VIC.new(model: vic_model, region:)
       @cia1 = CIA.new(start: 0xdc00, peripheral: @control_ports, model: cia_model, region:)
       @cia2 = CIA.new(start: 0xdd00, model: cia_model, region:)
       @control_ports.port_a_source = @cia1
@@ -92,6 +92,8 @@ module Badline
       @datasette.on_sense_change { @io_port.value = port_value }
 
       @color_ram = ColorMemory.new(@vic)
+      @vic.vic_bank.connect(cia2: @cia2, color_ram: @color_ram)
+      @vic.vic_bank.map_character_rom(character_rom)
       @open_bus = OpenBus.new(@vic)
       @cpu_off_bus = false
 
@@ -201,96 +203,15 @@ module Badline
     def update_overlays!
       @ultimax = @cartridge ? @cartridge.ultimax? : false
       @phi1_ultimax = @cartridge ? @cartridge.phi1_ultimax? : false
-      @ram_expansion.map(@read_pages, @write_pages)
       @video_ram = @ram_expansion.video_ram
+      @vic.vic_bank.map(@video_ram, phi1_ultimax: @phi1_ultimax, ultimax: @ultimax, romh: @cartridge&.romh)
 
-      @ultimax ? map_ultimax_pages : map_banked_pages
+      map_pla_pages
       @write_pages[0xff] = @reu.trigger.wrap(@write_pages[0xff]) if @reu
     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
-
-    # 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?
+    def map_ram_pages
+      @ram_expansion.map(@read_pages, @write_pages)
     end
   end
 end

data/lib/badline/chrout_trap.rb

@@ -2,7 +2,7 @@
 
 module Badline
   # Observe-only PC trap on the KERNAL CHROUT routine ($FFD2). Records each
-  # character written while the KERNAL is banked in, then lets execution fall
+  # character written while the layout finds the KERNAL mapped in, then lets execution fall
   # through to the ROM, so the screen output is unaffected. Used for headless
   # capture of program output.
   class ChroutTrap
@@ -10,14 +10,15 @@ module Badline
 
     attr_reader :output
 
-    def initialize(cpu:, bus:)
+    def initialize(cpu:, bus:, layout:)
       @cpu = cpu
       @bus = bus
+      @layout = layout
       @output = +""
     end
 
     def call
-      @output << ascii(@cpu.a) if @bus.io_port.kernal?
+      @output << ascii(@cpu.a) if @layout.kernal_mapped?(@bus)
     end
 
     def inspect