badline 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feaedb95b99aa7efed205645c112426a2649ad7a08c975708d085bf69a7e9555
-  data.tar.gz: b284281a2e1256f0fe94abf5174990ac8dc8a98cd7035f1cd53aebd3ccbefbd6
+  metadata.gz: bd764dccd3b8af3f8e0dcbb7d17debc3fceb24a9899f80871ebbf184ffefd65b
+  data.tar.gz: 46a62d801813476242a407c09ab3ff4fec1126d10bfee134047f18e90fd86955
 SHA512:
-  metadata.gz: 870ff9cb5c9a9d65c8e9dd8dee6cc87a45871c1a07c79c4b9dc69a692600c3167f92b1debca0f860ab96b783a81bb608276542322b17e305acb82e95c9fc560b
-  data.tar.gz: 7c12bf1fd073b2b0e58e41195d67316f0c518a0f5b8c013ded19f025b48456fea738e5ad3df26a796c84151638e8c0449b5bf14b7d013fcb876c61db5d2d9469
+  metadata.gz: 82a62fb4a3de3ef65e123bacf22ba300efe628f1bde38815dc950a39034d8c2b9423de79b3805fce84e19bcbaa8100a3e67488d5ef0a3ecb2de6434689886883
+  data.tar.gz: 595b19f034d708db60089e707507e74281059d271527fe61e0a205d9e8e0853a4f6b4d077aeed648f59a86d06bf31d3ee6e5902345fdb52d5fb36ded8de94da3

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # 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)
+
+
+### Features
+
+* add a per-user data folder for badline's own files ([27bdf0e](https://github.com/elektronaut/badline/commit/27bdf0edc16d95fc57dea940741cc0b7de74bbb1))
+* add the Drean C64, PAL-N with the 6572, as --model drean ([0562d8e](https://github.com/elektronaut/badline/commit/0562d8eb5b11239039eac934fd21eb7824868f98))
+* add the SX-64 as --model sx64 ([e947cba](https://github.com/elektronaut/badline/commit/e947cba8ff46f0f01eeb6e1a49c0bd4bf91324ea))
+* autosave, and a Snapshots page in the pause menu ([78aede9](https://github.com/elektronaut/badline/commit/78aede9a6052ce6c32184952a7b1d380e7c129e2))
+* keep five quicksave slots in the data folder ([6043543](https://github.com/elektronaut/badline/commit/6043543632aa61a42ff69bdff8ea15ae354ce810))
+* pick the C64 to run with --model ([d5539c8](https://github.com/elektronaut/badline/commit/d5539c8ade245b1e96e78765f15906ce4a80da5b))
+* restore snapshots without their tape, .t64 or true drive disk files ([0c0733a](https://github.com/elektronaut/badline/commit/0c0733a5c7eaf9c217466f7569769eb005c5248f))
+* run the testlist's Drean rows as testbench-drean ([dc8a075](https://github.com/elektronaut/badline/commit/dc8a07524168d399fb7c0305c661ab694c53bc2c))
+* save NTSC, Drean and REU machines as .vsf snapshots ([c4126cf](https://github.com/elektronaut/badline/commit/c4126cfa878d8efe7aaaa9e5113c4ee2a4886e6b))
+* seek within a subtune from checkpoints kept as it plays ([3ac57be](https://github.com/elektronaut/badline/commit/3ac57beac448a43a76387a0ff1f370cd07d06d81))
+* take disk sets from .m3u and .vfl lists ([b4e6845](https://github.com/elektronaut/badline/commit/b4e6845eb04cde80f87c1fcb372987311bf1dd97))
+
+
+### Bug Fixes
+
+* describe F11's quicksave slots, F12 and the autosave in --help ([6cbf148](https://github.com/elektronaut/badline/commit/6cbf148d327699070ef4fba4f2b3e3dd39d41348))
+* keep the board's low-pass stable for long filter steps ([c5af022](https://github.com/elektronaut/badline/commit/c5af0224aad60dbb665e6804bb536746e354da96))
+* leave CIA 1's timer B and the serial lines as the KERNAL's LOAD does ([b4f1a41](https://github.com/elektronaut/badline/commit/b4f1a4173b9413fd59b05bab12d173e0679c4c17))
+* play an NTSC machine's sound at its own clock ([510aab1](https://github.com/elektronaut/badline/commit/510aab1052a58a54b1790802e2a5705fcb208c5c))
+* put CIA 2's port A on the serial bus without a drive ([31f8a4f](https://github.com/elektronaut/badline/commit/31f8a4fad0ea210d4272b4672a84414527b68e31))
+* run the 6567R8 and 6572 X counter over $180-$187 twice ([08a4da3](https://github.com/elektronaut/badline/commit/08a4da33d4bd68a85d61895dcf8c1ea5fa5b539c))
+* set CIA 1's timer B for each byte the serial traps stand in for ([f98e6d7](https://github.com/elektronaut/badline/commit/f98e6d7666d2326ce4d8d3ab7f938dc4fd60cbd1))
+* take .m3u and .vfl lists of disks in --at's insert ([d1e771e](https://github.com/elektronaut/badline/commit/d1e771e6781fc5560dda2e10e6d76abb53be0807))
+
 ## [0.8.0](https://github.com/elektronaut/badline/compare/v0.7.0...v0.8.0) (2026-10-03)
 
 

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,10 @@ 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 |
-| `--ntsc` | Run an NTSC C64, with the 6567R8 VIC-II, instead of a PAL one |
+| `--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) |
 | `--no-vsync` | Pace the window by a timer, or by the sound while it plays, instead of the display's vsync |
@@ -93,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 |
@@ -117,6 +125,7 @@ library, are covered in [doc/library.md](doc/library.md).
 | `.prg`, `.p00` | Loaded into memory after boot. A program at the BASIC start (`$0801`) is `RUN`, anything else is left for you to `SYS` |
 | `.d64`, `.d71`, `.d81` | Mounted as device 8, then `LOAD"*",8,1` and `RUN`. Write-protected unless `--writable` |
 | `.g64` | Put in a true 1541, then `LOAD"*",8,1` and `RUN`. It holds the disk's raw GCR, so copy protection that reads it works. Write-protected unless `--writable` |
+| `.m3u`, `.vfl` | A list of disk images, one path a line, relative to the list: an `.m3u` playlist, or a VICE flip list, which only unit 8's entries are taken from. Its first disk goes in as above, and the list is its set for the pause menu |
 | `.t64` | Mounted read-only as device 8 and loaded like a disk image. The files load by name, and no tape is involved |
 | `.tap` | Inserted in the datasette with PLAY pressed, then `LOAD` and `RUN`. It loads at the speed of a real tape |
 | `.crt` | The hardware types listed under [Cartridges](#whats-emulated). Other types are rejected |
@@ -132,14 +141,38 @@ 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` saves the whole machine to a new `badline-<date>-<time>.vsf` in
-the working directory, and `F12` goes back to the snapshot last saved
-or opened. Snapshots use VICE's `.vsf` format: badline opens those
-x64sc saves, and x64sc opens badline's. See
-[doc/snapshots.md](doc/snapshots.md) for what they hold and how far the
-two agree.
+`F11` quicksaves the whole machine to the next of five slots in
+badline's data folder, replacing the oldest, and `F12` restores the
+newest, even after badline has quit and started again. badline also
+autosaves every two minutes of play, and the pause menu's Snapshots page
+saves under a name and loads any of them. Snapshots use
+VICE's `.vsf` format: badline opens those x64sc saves, and x64sc opens
+badline's. See [doc/snapshots.md](doc/snapshots.md) for where they're
+kept, what they hold and how far the two agree.
 
 ## Playing and rendering SID tunes
 
@@ -215,8 +248,11 @@ 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 |
 | Drive 8 | The disk: insert, eject, the previous or next disk of its set, and whether it's writable |
 | Datasette | The tape: insert, eject, PLAY and REWIND |
 | Expansion port | The cartridge: insert, remove, and its freeze button if it has one |
@@ -224,15 +260,17 @@ too.
 | Sound | Mute, and the SID's model |
 | Power | Reset, power cycle and quit |
 
-INSERT opens a file browser. A disk's set comes from the names in its
-folder: `Disk 1`, `Side B`, `d2`, TOSEC's `(Disk 1 of 2)`, or a trailing
-`_1`, `_2` when the first of the set is there. WRITABLE starts as
+INSERT opens a file browser. A disk's set is the `.m3u` or `.vfl` list it
+was opened from, or one in its folder that lists it. Without one, it comes
+from the names in its folder: `Disk 1`, `Side B`, `d2`, TOSEC's
+`(Disk 1 of 2)`, or a trailing `_1`, `_2` when the first of the set is
+there. WRITABLE starts as
 `--writable` sets it and stays as set for the next disk. Quick open starts
 a file in a new machine, as the command line does. It asks first, as
 inserting or removing a cartridge does, since each power cycles the
 machine.
 
-A disk or tape dropped on the window goes into its drive. A cartridge,
+A disk, list of disks or tape dropped on the window goes into its drive. A cartridge,
 program or `.sid` dropped on it opens the menu to ask first.
 
 ## What's emulated
@@ -242,8 +280,8 @@ program or `.sid` dropped on it opens the menu to ask first.
   [65x02 single step tests](https://github.com/SingleStepTests/65x02).
 - **Memory**: banking through the 6510 port, the cartridge lines and
   Ultimax mode, and the +60K and +256K RAM expansions.
-- **VIC-II**: the PAL 6569, the C64C's 8565, and NTSC's 6567R8 (`--ntsc`)
-  and 6567R56A: every graphics mode, sprites, collisions, bad lines,
+- **VIC-II**: the PAL 6569, the C64C's 8565, NTSC's 6567R8, 8562 and
+  6567R56A, and the Drean's PAL-N 6572 (`--model`): every graphics mode, sprites, collisions, bad lines,
   sprite DMA, the border and the light pen.
 - **CIA 1 and 2**: the 6526 and the C64C's 6526A, with timers,
   time-of-day clocks, the serial shift register, the keyboard matrix
@@ -252,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
@@ -261,8 +303,8 @@ program or `.sid` dropped on it opens the menu to ask first.
   Power / Nordic Power, Retro Replay / Nordic Replay, Final Cartridge III
   / III+ and the KCS Power Cartridge. Flash writes stay in memory.
 
-Machines other than the default, and the cartridges' jumpers, are
-built from Ruby: see [doc/library.md](doc/library.md).
+Chip combinations `--model` doesn't name, and the cartridges' jumpers,
+are built from Ruby: see [doc/library.md](doc/library.md).
 
 Known gaps:
 
@@ -270,7 +312,6 @@ Known gaps:
   turns on, stutters: it plays in bursts with silent gaps between them.
 - Without `--true-drive`, fast loaders and anything else that runs code
   on the drive won't work.
-- No PAL-N (Drean) machine.
 
 ## Contributing
 

data/doc/library.md

@@ -19,7 +19,9 @@ computer.address_bus.peek(0x0400)                   # screen RAM starts at $0400
 ## Building a machine
 
 `Badline::Computer.new` builds the default machine: a PAL C64 with the
-6569 VIC-II, 6526 CIAs and a 6581 SID. Its keywords build others:
+6569 VIC-II, 6526 CIAs and a 6581 SID. Its keywords build others, and
+`Badline::Model.named("c64c")` gives the ones `--model` names for each
+model (`Badline::Model::ALL`):
 
 - `vic_model: :mos8565` fits the C64C's 8565, with its grey dots on
   colour register writes and its own timing for mode splits, sprite
@@ -28,7 +30,8 @@ computer.address_bus.peek(0x0400)                   # screen RAM starts at $0400
   65 cycles by 263 lines at 1,022,727 Hz, with its later sprite fetches
   and its X counter, and TOD clocks on 60 Hz mains.
   `Badline::Region::NTSC_OLD` is the first NTSC C64s' 6567R56A, 64 cycles
-  by 262 lines. The stock KERNAL tells them from PAL by the raster, so
+  by 262 lines, and `Badline::Region::DREAN` the Drean C64's PAL-N
+  6572, 65 cycles by 312 lines at 1,023,440 Hz. The stock KERNAL tells them from PAL by the raster, so
   every region boots the same ROMs.
 - `cia_model: :mos6526a` fits the C64C's 6526As, whose interrupt
   register timing differs.
@@ -36,6 +39,9 @@ computer.address_bus.peek(0x0400)                   # screen RAM starts at $0400
 - `ram_expansion: :plus60k` or `:plus256k` fits the +60K or +256K RAM
   expansion, banked through its register at `$D100`.
 - `reu: 512` plugs in a RAM Expansion Unit of that many K.
+- `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.
 
 ## Cartridges
 
@@ -57,6 +63,7 @@ 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
-`eapi/eapi-am29f040-14` if you attach EasyFlash cartridges.
+`kernal-sx64.rom` for the SX-64 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/media.md

@@ -59,8 +59,17 @@ traps, so `LOAD` and `SAVE` reach the 1541 too. With the 1541 in device
 8, a `.d64` goes in its drive as well.
 
 `Badline::Media::DiskSet.around(path)` lists the disks of the set a disk
-image belongs to, found by name in its folder, which the pause menu's
-PREVIOUS DISK and NEXT DISK step through.
+image belongs to, which the pause menu's PREVIOUS DISK and NEXT DISK step
+through. An `.m3u` or `.vfl` list in the disk's folder that names it
+gives the set. Without one, the set is found by name in the folder.
+Given a list, it returns the disks the list names.
+
+A list names one disk image a line, as a path relative to the list or an
+absolute one. Blank lines and lines starting with `#` are skipped, and
+entries that aren't there are left out. In a VICE `.vfl` flip list, only
+the entries after a `UNIT 8` line, or before any `UNIT` line, count.
+`Media.attach` and the command line take a list as media and attach its
+first disk.
 
 ## The light pen
 

data/doc/pinned-behaviour.md

@@ -26,11 +26,16 @@ only catches the rows that happen to move.
 - [VIC light pen](#vic-light-pen)
 - [VIC-II 8565](#vic-ii-8565)
 - [VIC-II NTSC](#vic-ii-ntsc)
+- [VIC-II 6572 (Drean)](#vic-ii-6572-drean)
 - [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)
@@ -293,7 +298,9 @@ only catches the rows that happen to move.
   early in the next one for 3–7.
   - A sprite still shifting at K loses the rest of its row. Its output
     holds its last pixel from K through **K+6**, then goes dark.
-  - A comparator hit in K..K+11 shows nothing.
+  - A comparator hit in K..K+11 shows nothing. Where K falls in the
+    last 11 pixels of the line, as sprite 3's does on a 65-cycle line,
+    the twelve run on into the next line's first pixels.
   - A hit from K+12 on shows the row the reload brought. For sprites 0–2
     that is the *next* line's row, a line early. For sprites 3–7 it is the
     current row, and a hit ahead of their K shows the previous line's row.
@@ -307,6 +314,11 @@ only catches the rows that happen to move.
     `spritex/demusinterruptus` and `spritegap2` pass on it too.
   - Spec guard: *the reload* in
     [`vic/sprite_spec.rb`](../spec/badline/vic/sprite_spec.rb).
+  - The run into the next line is pinned by `spritescan_drean`'s 6572
+    dump, where sprite 3 shows nothing for X = $193 to $19e, the twelve
+    pixels from K = 515 on a 520-pixel line. Without it a hit at $198 to
+    $19e collides. Spec guard: *the reload near the end of a 65-cycle
+    line*. The `testbench-ntsc` sprite rows pass either way.
   - The hold's length is pinned by `spritefetchbug/test-136-2a`, whose
     X-expanded sprite 0 sits at X = $136 and is still shifting at 459. Its
     reference holds the last pixel through 465. Holding it for one pixel
@@ -941,14 +953,22 @@ region moves the sprites. The positions live in `Region::Profile` and
   - Spec guard: *sprite DMA cycle stealing on NTSC* and *#phi1_data on
     NTSC* in [`vic_spec.rb`](../spec/badline/vic_spec.rb), and
     [`timing_spec.rb`](../spec/badline/vic/sprite/timing_spec.rb).
-- **Display compare and X counter.** The 6567R8 turns a sprite's display
-  on and off in cycle 59 (`sprite_display_cycle`), where the 6567R56A
-  keeps the 6569's cycle 58. Its X counter holds for 8 pixels
-  (`x_hold`), reading $184-$187 three times, so it reaches $1ff on a
-  520-pixel line. The 6567R56A's runs straight through 512 pixels.
-  Neither is pinned yet: moving the 6567R8's display compare to 58, the
-  6567R56A's to 59, or running the 6567R8's counter straight through and
-  wrapping it at 512 fails no row of those subsets.
+- **Display compare.** The 6567R8 turns a sprite's display on and off in
+  cycle 59 (`sprite_display_cycle`), where the 6567R56A keeps the 6569's
+  cycle 58. This isn't pinned yet: moving the 6567R8's to 58 or the
+  6567R56A's to 59 fails no row of those subsets.
+- **X counter.** The 6567R8's X counter spends 8 pixels more on a line
+  (`x_hold`): after $187 it runs over $180-$187 a second time, then on
+  from $188, so it reaches $1ff on a 520-pixel line. The 6567R56A's runs
+  straight through 512 pixels.
+  - Pinned for the 6572, which shares the line, by `spritescan_drean`'s
+    dump (see [VIC-II 6572 (Drean)](#vic-ii-6572-drean)).
+  - The 6567R8's own lightpen dump (`split-tests/lightpen`'s
+    `dump6567.prg`, run by hand on `--model ntsc`) agrees: the sample the
+    test takes 8 pixels into the hold reads $c2 ($180-$181). Reading
+    $184-$187 there instead, as badline did before, gives $c4. The 6572's
+    `dump6572.prg` has the same values. The `testbench-ntsc` rows pass
+    either way.
 - **Blanking and crop.** The blanked lines are the ones VICE's NTSC view
   leaves out, 12-27 on the 6567R8 and 13-27 on the 6567R56A, so the
   `testbench-ntsc` screenshots, VICE's 247 lines from line 28 running on
@@ -970,6 +990,34 @@ What the NTSC references don't settle, and so what stays as it is:
   readme says it was matched against screenshots, and the one 6567R8
   photograph in the testprogs is of revision R01.
 
+## VIC-II 6572 (Drean)
+
+The 6572 of the Drean C64 (`Region::DREAN`) runs the 6567R8's line, 65
+cycles with its sprite fetches in cycle 59, its display compare in cycle
+59 and its X counter running over $180-$187 twice, on PAL-N's 312 lines at
+1,023,440 Hz. The oracle is `split-tests/spritescan/spritescan_drean.prg`,
+which checks itself against its `dump6572.bin`, from a real 6572R1. The
+testlist comments that row out, and `testbench-drean`
+(`bin/testbench --drean`) runs it.
+
+- Pinned by that dump: every byte the test compares matches, and the
+  test passes.
+- The X counter's second run over $180-$187 is pinned by sprite 1,
+  pattern C (a one-pixel sprite against one shifted a pixel left), which
+  collides for X = $180 to $186 on the 6572. Those are inside sprite 1's
+  twelve dead pixels (K = 483), so the sprite only shows from the second
+  time the counter reads its X. Repeating $184-$187 in the hold instead
+  misses $180-$183 (4 bytes), repeating $180-$183 misses $184-$186 (3),
+  and repeating $17c-$183 or $184-$18b moves 18 bytes. Spec guard: the
+  6567R8 and 6572 examples in
+  [`timing_spec.rb`](../spec/badline/vic/sprite/timing_spec.rb).
+- The display compare isn't pinned: the dump matches with it in cycle
+  58 as well as 59.
+- Not matched: `spritegap3`'s 6572 dump has sprite 0 at X = 0 miss the
+  sprite at X = 1 for every pair it is in, where badline, like the
+  6567R8 dump, has them collide. The test still passes, because it
+  accepts the 6567R8's dump too.
+
 ## CIA 6526 timer pipeline
 
 - Start and stop go through two stages. A force load lands one tick after
@@ -1152,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
@@ -1195,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