badline 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a3848536bdfa64fefb71cdb9347928e1ce8494c7b13594c07df72abc60f5ca0
-  data.tar.gz: 56c2eb4db9e9cc1953a4255c4d05d46ac01049c143d72a79f972bafefab2a919
+  metadata.gz: 45be9424707255afd6c8c04be00d7bde36cca422c188b66229fb6fab9355bd3b
+  data.tar.gz: 7571cfbef8994cc7aeb82bcc619548abd88762f0b7f43807b18a5a6a6e50ff7a
 SHA512:
-  metadata.gz: bc38c1d29d366004792db0dd24928c238f6396ce99a24491cb74fa1eb6d95e4f02e843d09da7f179f0a1b33f5e7ceae2e1ed73dfad2abd852802c714ccdb91b3
-  data.tar.gz: f81c7525afd46d0325feecce49bd2f9abda8c3410fc5854b0dea1166703f3c8bdb775bfd84d6c83e161dd3fd586cd0b23c286e564d5559c5d2d006427fedea6f
+  metadata.gz: 33fc10445d3bb1971c698c4adcfbfa8fae3de078a62f808f3e62f06b31f9bd1728653c34f6e5a2f7944187d063377a81f8bd6d6f475d76cbab121f481948386c
+  data.tar.gz: 90b6dbdf27f29321a191ee63bcb8f96faafb02ce768d8ffc332d5a49cabc40326062824eb04552fb790f0575ad79849e69c1904b8c8005878a4f6a20337b3d0d

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [0.19.0](https://github.com/elektronaut/badline/compare/v0.18.0...v0.19.0) (2026-10-27)
+
+### Highlights
+
+- **VIC-20 snapshots in VICE's format**: badline reads and writes xvic's `.vsf` snapshots of the PAL and NTSC VIC-20, so a machine saved in one emulator carries on in the other.
+- **SuperPET snapshots**: xpet's `.vsf` now carries the SuperPET's 6702 dongle in both directions.
+- **6502 reset**: the CPU runs its seven-cycle reset sequence through the bus, as the chip does, so a machine starts its first instruction on the same cycle as x64sc.
+- **C64GS and MAX Machine**: neither has a serial port, so disks and true drives are refused on them rather than attached to a bus that isn't there.
+- **Homebrew bottles**: `brew install elektronaut/tap/badline` pours a prebuilt binary on Apple Silicon (Sequoia) and x86_64 Linux instead of compiling it.
+
+### Features
+
+* read and write the SuperPET's 6702 in xpet's .vsf ([75beb83](https://github.com/elektronaut/badline/commit/75beb8365760b19561e7178df5ddfe20e983ba87))
+* read and write xvic's snapshots of the VIC-20, PAL and NTSC ([7e039a7](https://github.com/elektronaut/badline/commit/7e039a7deffc6e1283d5bc7e00182ae5350235e6))
+* refuse disks and true drives on the C64GS and the MAX Machine, which have no serial port ([a4ba76d](https://github.com/elektronaut/badline/commit/a4ba76d0d40180fc3e6113fbb35306114e940bc5))
+* run the VIC-20 testbench's screenshot rows and its NTSC raster and light pen programs ([1f54561](https://github.com/elektronaut/badline/commit/1f54561f2d8ba3bc511bf5d80d3b5f0365cc3a5b))
+
+
+### Bug Fixes
+
+* autostart the first program off a disk image on BASIC 1, not the image itself ([3f31daa](https://github.com/elektronaut/badline/commit/3f31daa044497d2524b7906691cf9f4e8881eb6b))
+* carry a recording SID's sample window across snapshots ([c4472c1](https://github.com/elektronaut/badline/commit/c4472c1d1a5027171527bdc9b1d82614aefe94d2))
+* latch the VIC-20's light pen as the fire button moves ([37ab4b9](https://github.com/elektronaut/badline/commit/37ab4b945a036ade5ea5f9064f91c6267777a912))
+* read a 1541 data block back as far as its checksum ([bcb167e](https://github.com/elektronaut/badline/commit/bcb167e263504610129d43bc26c9c87b16388b68))
+* run the 6502's reset sequence through the bus ([a32f25c](https://github.com/elektronaut/badline/commit/a32f25cd04d4df9cd2e7aa8a63393a9661452aad))
+
+
+### Performance Improvements
+
+* build Memory's storage as an Integer array and seed the VIC's geometry for Spinel ([b84353d](https://github.com/elektronaut/badline/commit/b84353d792f20fbfe5421fda534946b4f3e2cd19))
+* seed CPU::Core's fields for every 6502 and qualify the drive and PET memory seeds ([6bf511c](https://github.com/elektronaut/badline/commit/6bf511c040105d7e8403593501fc9d8fb2a785fe))
+* seed Snapshot::Keyed::Reader#int and #bool for Spinel ([8e1692b](https://github.com/elektronaut/badline/commit/8e1692bae61c76bc69869a094a7eb4fd748ddd95))
+* seed the CIA's interrupt register, timers, shift register and TOD types for Spinel ([bc1e468](https://github.com/elektronaut/badline/commit/bc1e4686314f90a66be038d78f92a0b297538989))
+* seed the KIM-1's CPU, 6530s, timer and bus types for Spinel ([0e42b9d](https://github.com/elektronaut/badline/commit/0e42b9d888e7ff1c4e871b49d32fe593c3e33a76))
+* seed the Plus/4's CPU, TED and bus types for Spinel ([50d0c1f](https://github.com/elektronaut/badline/commit/50d0c1f63c2401158a77342fc8a37f4bb2031e95))
+* sleep a 4040 whose motors turn with no disk in either drive ([2203749](https://github.com/elektronaut/badline/commit/22037497b80b04d26e947fb999f517422b59a18b))
+* sleep an idle D9060 through planned host cycles and wake it as the controller moves a line ([5823192](https://github.com/elektronaut/badline/commit/582319299c75b9c1f39b22d2879b4ac06c8cf3c3))
+* splice a disk image's sectors back in ([1f7242d](https://github.com/elektronaut/badline/commit/1f7242de9bd6e7c3001a96143efc171995e54ed2))
+* wake only an idle 8050's controller for its 5 ms timer ([d733081](https://github.com/elektronaut/badline/commit/d7330814ca73b84c5537e8ca8d4e65121742b9b6))
+
 ## [0.18.0](https://github.com/elektronaut/badline/compare/v0.17.0...v0.18.0) (2026-10-20)
 
 ### Highlights

data/CLAUDE.md

@@ -250,6 +250,14 @@ the rows your change can't reach tell you nothing about it.
   builds the native binary locally (`rake native:build`; on macOS with
   `SPINEL_CC="cc -Wno-nullability-completeness"`) before it's pushed, or
   types its arguments in `spinel/sig`
+- Anywhere in `lib/`, don't name a method after one that Array, String,
+  Hash, Integer or IO define (`length`, `size`, `fill`, `step`, `sample`,
+  `write`, `truncate`) unless it returns the same type. Spinel can't tell
+  which classes a dynamic `new` builds, such as `BankedRAM.build`'s
+  `TYPES.fetch(type).new`, so it counts every class as constructible, and
+  the new method widens every untyped call of that name in the emulator.
+  In 0.18.0, a KIM-1 tape's `length` broke `D90Image`'s `Array#fill` in
+  a harness that never builds a KIM-1
 - The Regression workflow runs the suites on CRuby, started by hand from
   the Actions tab, for a person checking that CRuby and Spinel agree.
   Agents don't start it

data/CONTRIBUTING.md

@@ -103,6 +103,10 @@ bundle exec rubocop
   `main` every two hours. When a change moves rows on purpose, re-record just
   those rows as [test/baselines/README.md](test/baselines/README.md)
   describes, and say why in the pull request.
+- Timing rules derived against a test are in
+  [doc/pinned-behaviour.md](doc/pinned-behaviour.md). What VICE's
+  emulators check, how they're driven, their known quirks and where
+  badline differs from them are in [doc/vice.md](doc/vice.md).
 - Write commit messages using
   [Conventional Commits](https://www.conventionalcommits.org). The
   changelog and releases are generated from them, so the `feat:` and

data/README.md

@@ -33,8 +33,10 @@ The native `badline`, with Homebrew:
 brew install elektronaut/tap/badline
 ```
 
-The formula builds it from the release's generated C, so it needs no
-Spinel or Ruby. To build it from a checkout instead, see
+It installs a prebuilt bottle on macOS 15 or newer on Apple Silicon and
+on x86_64 Linux. Elsewhere the formula builds it from the release's
+generated C, so it needs no Spinel or Ruby. To build it from a checkout
+instead, see
 [native/README.md](native/README.md).
 
 The gem needs Ruby 4.0 or newer and the SDL2 library:
@@ -96,7 +98,7 @@ differences noted in the table. `--help` lists the options for either.
 | `--sid-card-address fd40`, `--sid-card-address fe80` | Put the SID card at `$FD40` (the default) or at `$FE80` |
 | `--ram-expansion NAME` | Fit a Plus/4 or C16 with a RAM expansion: `hannes256`, `hannes1m` or `csory256`. See [The Plus/4](#the-plus4) |
 | `--reu SIZE` | Plug in a RAM Expansion Unit of `SIZE` K: 128, 256, 512 (a 1750) or up to 16384 |
-| `--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. The VIC-20, the C128, the Plus/4, the PET and the CBM-II have models of their own: see their sections |
+| `--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, datasette or disk drive) or `ultimax` (the MAX Machine of Japan, NTSC with 2K of RAM, one CIA, no ROMs and no disk drive, which runs only a cartridge). `--sid` or a `.sid` tune's own SID takes the model's place. The VIC-20, the C128, the Plus/4, the PET and the CBM-II have models of their own: see their sections |
 | `--ntsc` | Run an NTSC C64 or VIC-20, as `--model ntsc` does |
 | `--tty` | Fit the KIM-1's TTY/KB jumper, so its monitor talks to a teletype: a page in the window, or the terminal with `--headless`. See [The KIM-1](#the-kim-1) |
 | `--baud N` | Run the KIM-1's teletype at `110`, `300`, `1200`, `2400`, `4800` or `9600` baud (the default) |
@@ -122,7 +124,7 @@ differences noted in the table. `--help` lists the options for either.
 | `--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 |
-| `--vice` | Add VICE's modules to `--save-snapshot`'s C64, PET or CBM-II snapshot, so x64sc, xpet, xcbm2 or xcbm5x0 opens it too |
+| `--vice` | Add VICE's modules to `--save-snapshot`'s C64, VIC-20, PET or CBM-II snapshot, so x64sc, xvic, xpet, xcbm2 or xcbm5x0 opens it too |
 
 ```sh
 badline --unpaced --frames 12000 --true-drive disk1.d64 \
@@ -185,8 +187,8 @@ 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.
+save and load the VIC-20 too, and xvic's `.vsf` files load, as
+[doc/snapshots.md](doc/snapshots.md#xvic) describes.
 
 ## The C128
 
@@ -756,7 +758,8 @@ in cartridge 1 as it does from the command line.
   (`--reu`), with DMA timed against the VIC's bad lines and sprites.
 - **Datasette**: `.tap` playback.
 - **VIC-20**: the 6502, the PAL 6561 and NTSC 6560 VIC-I with its
-  picture and sound and the 6560's interlaced fields' timing, both 6522
+  picture, sound and light pen latch and the 6560's interlaced fields'
+  timing, 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`).

data/doc/library.md

@@ -49,12 +49,16 @@ model (`Badline::Model::ALL`):
 - `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: :gs` and `board: :max` have no serial port, so
+  `Badline::Media.attach` and `Media.insert_disk` raise
+  `Badline::Machine::Unsupported` for a disk image, a `.t64` or a host
+  directory, and `Media::TrueDrive.plug` for a true drive.
 - `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`.
+  `Badline::Region::NTSC_OLD`, with a datasette at its cassette port.
 
 ## Cartridges
 

data/doc/media.md

@@ -127,11 +127,12 @@ of half waves.
 
 A program SAVEd that way on the C64 loads and runs in VICE's x64sc, on
 the VIC-20 in xvic, and on the Plus/4 or the C16 in xplus4 as a Plus/4.
-Neither the Plus/4's tape nor the C16's ran on xplus4's C16 model.
+xplus4's C16 model loads no tape, its own included (#704).
 Checked with VICE 3.10.
 
 ## The light pen
 
 Control port 1's fire line is also the VIC-II's light pen input, so
 joystick 1's fire button and the 1351's left button in port 1 latch the
-light pen registers.
+light pen registers. On the VIC-20 the joystick's fire line is the
+VIC-I's light pen input, and the fire button latches `$9006` and `$9007`.

data/doc/pinned-behaviour.md

@@ -37,6 +37,7 @@ only catches the rows that happen to move.
 - [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 light pen](#vic-i-light-pen)
 - [VIC-I sound](#vic-i-sound)
 - [TED beam and the 7501 port](#ted-beam-and-the-7501-port)
 - [TED sound](#ted-sound)
@@ -1424,11 +1425,24 @@ and each was knocked out: removing it fails the rows named.
   - 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.
+    `$20` in the idle cycles instead; badline follows the 6561E. On the
+    6560, `timing_ntsc` matches `dumps/dump6560-101.prg` byte for byte
+    from `$17E0`, and `dumps/dump6560.prg`, from another NTSC machine,
+    reads `$20` in the idle cycles as the 6561-101 does.
   - Spec guard:
     [`chips/vic_i_split_tests_timing_spec.rb`](../spec/badline/chips/vic_i_split_tests_timing_spec.rb)
     (`:slow`), and *the fetches* in
     [`chips/vic_i_video_spec.rb`](../spec/badline/chips/vic_i_video_spec.rb).
+- The 6560's raster count, which `$9003` bit 7 and `$9004` read, moves
+  on to the next line 28 cycles into a line, and on the last line wraps
+  to 0 at column 61 (`Chips::VICI::NTSC`), measured on xvic as a black
+  box.
+  - Pinned by `VIC20/split-tests/timing`'s `timing_ntsc`, whose `$9003`
+    and `$9004` readings match `dumps/dump6560-101.prg`, and by
+    `VIC20/vic_line0/raster-ntsc`, whose effect starts 33 cycles later
+    for `$9004` at 0 than for 1, as its readme reports from a real
+    machine, and in one field 33 later and in the other on time with
+    interlace (`testbench-vic20-ntsc`).
 - 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
@@ -1437,6 +1451,32 @@ and each was knocked out: removing it fails the rows named.
   - Spec guard: *a colour write* in
     [`chips/vic_i_video_spec.rb`](../spec/badline/chips/vic_i_video_spec.rb).
 
+## VIC-I light pen
+
+- A falling edge on the light pen line, VIA 1's PA5 on the VIC-20,
+  latches `$9006` = 2h + 1, where h is the edge's column plus two,
+  wrapping at the line's end, and `$9007` = the raster count of the next
+  cycle, bits 8-1, the 6560's early count included
+  (`Chips::VICI::LightPen`). The column is badline's, the VIC's at the
+  cycle of the VIA write.
+- Around the cycle where the count turns to 0 (the 6561's frame start,
+  the 6560's column 61 of its last line): an edge from 8 cycles before it
+  to 1 after it latches as an edge in the cycle after it would, with
+  `$9007` at 0, but an edge 2 cycles before it latches an even `$9006`,
+  one less. Earlier, an edge latches nothing while the count read its
+  last value of the frame in the cycle before the edge: 311 on the 6561,
+  261 on the 6560.
+- A second edge in a frame latches again. The test drives one edge a
+  measurement, so no dump checks it.
+  - Pinned by `VIC20/split-tests/lightpen`: `lightpen.prg`'s 1,024
+    readings of `$9003`, `$9004`, `$9006` and `$9007` match
+    `dumps/dump6561e.prg`, and `lightpen_ntsc.prg`'s match
+    `dumps/dump6560.prg`, both from `$17E0` (`testbench-vic20` and
+    `testbench-vic20-ntsc`). The even `$9006` shows in both dumps; the
+    readme says the 6561E's was verified with 3 more dumps.
+  - Spec guard:
+    [`chips/vic_i_light_pen_spec.rb`](../spec/badline/chips/vic_i_light_pen_spec.rb).
+
 ## VIC-I sound
 
 No testprog checks the VIC-I's sound, so these rules are pinned by xvic

data/doc/snapshot-format.md

@@ -129,12 +129,12 @@ Written by the C64, C128, Plus/4, VIC-20, PET, CBM-II, KIM-1.
 | `port.ddr` | byte | C64: 0; C128: 0; Plus/4: 0 |
 | `port.data` | byte | C64: 0; C128: 0; Plus/4: 0 |
 | `port.floating` | byte | C64: 0; C128: 0 |
-| `pc` | word | C64: 64738; VIC-20: 64802; C128: 65341; Plus/4: 65526; PET: 64790 or 64824; CBM-II: 63895 or 63902; KIM-1: 7202 |
-| `sp` | byte | 255 |
+| `pc` | word | C64: 0; VIC-20: 0; C128: 65341; Plus/4: 0; PET: 0; CBM-II: 0; KIM-1: 0 |
+| `sp` | byte | C64: 0; VIC-20: 0; C128: 255; Plus/4: 0; PET: 0; CBM-II: 0; KIM-1: 0 |
 | `a` | byte | 0 |
 | `x` | byte | 0 |
 | `y` | byte | 0 |
-| `p` | byte | 32 |
+| `p` | byte | C64: 36; VIC-20: 36; C128: 32; Plus/4: 36; PET: 36; CBM-II: 36; KIM-1: 36 |
 | `nmi` | bool | false |
 | `so_high` | bool | true |
 | `irq.sample` | bool | false |
@@ -147,7 +147,17 @@ Written by the C64, C128, Plus/4, VIC-20, PET, CBM-II, KIM-1.
 | `cycles` | int | 0 |
 | `instructions` | int | 0 |
 | `stalled` | int, optional | absent |
-| `pos.seq` | text: boundary op interrupt jam | "boundary" |
+| `pos.seq` | text: boundary op interrupt jam reset | "boundary" |
+| `pos.crossed` | bool | PET: false |
+| `pos.t` | int | PET: 0 |
+| `pos.branch_taken` | bool | PET: false |
+| `pos.brk` | bool | PET: false |
+| `pos.vector` | int, optional | PET: absent |
+| `pos.address` | int, optional | PET: absent |
+| `pos.dummy_address` | int, optional | PET: absent |
+| `pos.value` | int, optional | PET: absent |
+| `pos.rmw` | int, optional | PET: absent |
+| `pos.pointer` | int, optional | PET: absent |
 
 ## BL-VIC
 
@@ -449,6 +459,13 @@ Written by the C64, C128, Plus/4, CBM-II.
 | `ext.lowpass` | int | 0 |
 | `ext.highpass` | int | 0 |
 | `ext.output` | int | 0 |
+| `rec.rate` | int | 0 |
+| `rec.clock_hz` | int | C64: 985248 |
+| `rec.phase` | int | C64: 0 |
+| `rec.sum` | int | C64: 0 |
+| `rec.count` | int | C64: 0 |
+| `rec.cycles_to_close` | int | C64: 23 |
+| `rec.filter_chunk` | int | C64: 4 |
 
 ## BL-TAPE
 
@@ -747,12 +764,12 @@ Written by the C64, C128, Plus/4, PET.
 
 | Key | Type | Default |
 | --- | --- | --- |
-| `pc` | word | C64: 60064 or 44836; C128: 60064; Plus/4: 60064 or 59829; PET: 60101 |
-| `sp` | byte | 255 |
+| `pc` | word | 0 |
+| `sp` | byte | 0 |
 | `a` | byte | 0 |
 | `x` | byte | 0 |
 | `y` | byte | 0 |
-| `p` | byte | 32 |
+| `p` | byte | 36 |
 | `nmi` | bool | false |
 | `so_high` | bool | true |
 | `irq.sample` | bool | false |
@@ -765,7 +782,18 @@ Written by the C64, C128, Plus/4, PET.
 | `cycles` | int | 0 |
 | `instructions` | int | 0 |
 | `stalled` | int, optional | absent |
-| `pos.seq` | text: boundary op interrupt jam | "boundary" |
+| `pos.seq` | text: boundary op interrupt jam reset | "boundary" |
+| `pos.op` | byte | C64: 234; Plus/4: 234 |
+| `pos.crossed` | bool | C64: false; C128: false; Plus/4: false |
+| `pos.t` | int | C64: 1; C128: 0; Plus/4: 1 |
+| `pos.branch_taken` | bool | C64: false; C128: false; Plus/4: false |
+| `pos.brk` | bool | C64: false; C128: false; Plus/4: false |
+| `pos.vector` | int, optional | C64: absent; C128: absent; Plus/4: absent |
+| `pos.address` | int, optional | C64: absent; C128: absent; Plus/4: absent |
+| `pos.dummy_address` | int, optional | C64: absent; C128: absent; Plus/4: absent |
+| `pos.value` | int, optional | C64: absent; C128: absent; Plus/4: absent |
+| `pos.rmw` | int, optional | C64: absent; C128: absent; Plus/4: absent |
+| `pos.pointer` | int, optional | C64: absent; C128: absent; Plus/4: absent |
 
 ## BL-D8-DISK
 
@@ -795,7 +823,7 @@ Written by the C64, C128, Plus/4, PET.
 | `side` | int | C64: 0 or 1; C128: 85; Plus/4: 0; PET: 0 |
 | `zone` | int & 0x3 | C64: 3; C128: 3; Plus/4: 3 or 0; PET: 3 |
 | `time` | int | 0 |
-| `read_clock_in` | int | 2097152 |
+| `read_clock_in` | int | C64: -3145728; C128: 2097152; Plus/4: -4194304 or 2097152; PET: -3145728 |
 | `clocks` | int | 0 |
 | `shift` | int | 0 |
 | `ones` | int | 0 |
@@ -976,6 +1004,7 @@ Written by the C64.
 | `ext.lowpass` | int | 0 |
 | `ext.highpass` | int | 0 |
 | `ext.output` | int | 0 |
+| `rec.rate` | int | 0 |
 
 ## BL-VICI
 
@@ -997,6 +1026,9 @@ Written by the VIC-20.
 | `fetch_from` | int | 0 |
 | `fetched` | int | 0 |
 | `code` | byte | 0 |
+| `pen.x` | byte | 0 |
+| `pen.y` | byte | 0 |
+| `pen.low` | bool | false |
 | `line.layout` | int | 0 |
 | `display` | bytes | 88608 × 0 |
 | `line.row` | int | 311 |
@@ -1009,8 +1041,8 @@ Written by the VIC-20.
 | `sound.shift_registers` | ints | [0, 0, 0, 255] |
 | `sound.lfsr` | int & 0xffff | 65535 |
 | `sound.level` | int | 0 |
-| `sound.ran_ago` | int | 0 |
-| `sound.next_shifts` | ints | [2048, 1024, 512, 256] |
+| `sound.ran_ago` | int | 5 |
+| `sound.next_shifts` | ints | [2043, 1019, 507, 251] |
 
 ## BL-VIA1
 
@@ -1225,7 +1257,7 @@ Written by the Plus/4.
 | `voice<N>.phase` | int & 0x1 | 1 |
 | `voice<N>.toggle_in` | int, optional | absent |
 | `noise` | byte | 255 |
-| `ran_ago` | int | 0 |
+| `ran_ago` | int | 6 |
 
 ## BL-KEYPORT
 
@@ -1552,12 +1584,12 @@ Written by the PET.
 
 | Key | Type | Default |
 | --- | --- | --- |
-| `pc` | word | 62135 or 54059 or 61972 |
-| `sp` | byte | 255 |
+| `pc` | word | 0 |
+| `sp` | byte | 0 |
 | `a` | byte | 0 |
 | `x` | byte | 0 |
 | `y` | byte | 0 |
-| `p` | byte | 32 |
+| `p` | byte | 36 |
 | `nmi` | bool | false |
 | `so_high` | bool | true |
 | `irq.sample` | bool | false |
@@ -1570,7 +1602,7 @@ Written by the PET.
 | `cycles` | int | 0 |
 | `instructions` | int | 0 |
 | `stalled` | int, optional | absent |
-| `pos.seq` | text: boundary op interrupt jam | "boundary" |
+| `pos.seq` | text: boundary op interrupt jam reset | "boundary" |
 
 ## BL-D8-FDCCPU
 
@@ -1578,12 +1610,12 @@ Written by the PET.
 
 | Key | Type | Default |
 | --- | --- | --- |
-| `pc` | word | 64516 or 64521 |
-| `sp` | byte | 255 |
+| `pc` | word | 0 |
+| `sp` | byte | 0 |
 | `a` | byte | 0 |
 | `x` | byte | 0 |
 | `y` | byte | 0 |
-| `p` | byte | 32 |
+| `p` | byte | 36 |
 | `nmi` | bool | false |
 | `so_high` | bool | true |
 | `irq.sample` | bool | false |
@@ -1596,7 +1628,7 @@ Written by the PET.
 | `cycles` | int | 0 |
 | `instructions` | int | 0 |
 | `stalled` | int, optional | absent |
-| `pos.seq` | text: boundary op interrupt jam | "boundary" |
+| `pos.seq` | text: boundary op interrupt jam reset | "boundary" |
 
 ## BL-D8-VIA
 
@@ -1671,12 +1703,12 @@ Written by the PET.
 
 | Key | Type | Default |
 | --- | --- | --- |
-| `pc` | word | 63489 |
-| `sp` | byte | 255 |
+| `pc` | word | 0 |
+| `sp` | byte | 0 |
 | `a` | byte | 0 |
 | `x` | byte | 0 |
 | `y` | byte | 0 |
-| `p` | byte | 32 |
+| `p` | byte | 36 |
 | `nmi` | bool | false |
 | `so_high` | bool | true |
 | `irq.sample` | bool | false |
@@ -1689,7 +1721,7 @@ Written by the PET.
 | `cycles` | int | 0 |
 | `instructions` | int | 0 |
 | `stalled` | int, optional | absent |
-| `pos.seq` | text: boundary op interrupt jam | "boundary" |
+| `pos.seq` | text: boundary op interrupt jam reset | "boundary" |
 
 ## BL-D8-SASIRAM
 

data/doc/snapshots.md

@@ -83,6 +83,9 @@ disk comes back write-protected. A directory mounted as device 8 opens
 again from its path. What the host holds stays the
 host's: the keyboard, the joysticks, the mouse and paddles, sound, and
 blocks given to `on_init` that hadn't run yet, which a restore reports.
+A SID that was recording saves how far into its current sample it had
+got, and a restored one that records again at the same rate carries on
+from there, so its output runs on as the saved one's would have.
 
 Every model saves this way, PAL, NTSC, old NTSC and Drean alike, and so
 does a machine with an REU, with its RAM and its registers. A snapshot
@@ -105,11 +108,42 @@ 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 or 1581, and restores into a
 VIC-20 with the same RAM expansion. Its file names its machine `VIC20`,
-as xvic's do, and holds only badline's modules, so xvic doesn't open it,
-and badline doesn't open xvic's. Restoring a
+as xvic's do, and holds only badline's modules, so xvic doesn't open it
+unless it is saved with `--vice` (see [xvic](#xvic)). Restoring a
 VIC-20 snapshot while a C64 runs, or a C64 one while a VIC-20 runs,
 swaps the machine in the window.
 
+### xvic
+
+A VIC-20 snapshot saved with `--vice`, or `computer.export_snapshot(path)`,
+also holds xvic's modules for the CPU, the RAM, the VIC-I with the colour
+RAM and both VIAs, and the ones xvic 3.10 needs to open the file, with no
+cartridge, nothing open on the file system drive, the joystick released
+and nothing on the user port. The file says it is in VICE's snapshot
+format 3.1, the only one xvic reads.
+
+xvic 3.10 opens those snapshots as long as its model matches:
+`-model vic20` or `vic20ntsc`. It takes the RAM expansion from the
+snapshot, whatever its `-memory` says, keeps its own drives and leaves
+out badline's cartridge, tapes and disks. A program it runs on from badline's
+snapshot runs as it does in badline, cycle for cycle, with the raster,
+the VIAs' timers and RAM alike, but for a snapshot taken in an
+interlaced frame, whose field xvic ends early (see
+[VICE](vice.md#xvic)).
+
+Snapshots xvic saves open in badline through the same modules: the CPU
+at its instruction boundary, the RAM and the data lines' last bytes, the
+VIC-I's registers, beam, frame, interlaced field, text window and
+fetches, its light pen and the colour RAM, and both VIAs' registers,
+timers and shift registers. The picture starts again with the next
+frame, and the sound as at power-on. VIC20MEM's blocks and the VIC-I's
+picture size build the machine: its RAM expansion and model. It reports
+the modules it leaves out, such as the drives, the cartridge, the
+datasette and the keyboard, and carries on without them. Restored into a
+running VIC-20, an xvic snapshot fails for a VIC-20 built another way,
+and otherwise switches the machine off and on, keeping its cartridge,
+tapes and the disk device 8 serves.
+
 ## The C128
 
 `badline c128` saves and restores the same way too. A C128 snapshot
@@ -180,8 +214,8 @@ xpet 3.10 opens those snapshots as long as its model and editor match:
 `-model 2001`, `3032`, `3032B`, `4032`, `8032`, `8096`, `8296` or
 `SuperPET`, and for a badline editor other than xpet's own, `-editor`
 naming badline's ROM. xpet runs a SuperPET's 6809 when the snapshot
-says it has the bus, whatever its own CPU switch, and has no system
-latch, write protect or 6702 to take from it. xpet's 8296 runs the 8032's editor, 901474-04 dated 0283, so an
+says it has the bus, whatever its own CPU switch, takes its 6702, and
+has no system latch or write protect to take from it. xpet's 8296 runs the 8032's editor, 901474-04 dated 0283, so an
 8296 saved for it has to run that editor (`--editor 4-80-b-50hz-0283`),
 and xpet takes the 8296's jumpers from its own settings. It keeps its
 own datasettes and leaves out badline's tapes and disks. A true drive
@@ -227,9 +261,9 @@ fitted, or a SuperPET, at 50 or 60 Hz, and an 8032, 8096 or 8296 whose
 CRTC lines are 64 cycles long runs xpet's own 50 Hz editor, 901474-04
 dated 0283. A SuperPET comes with its bank RAM, its bank, its `$EFFE`
 bit and its ACIA, its CPU switch at the CPU that had the bus, and while
-that is the 6809, the 6809's registers. Its RAM switch is at R/W, the
-only position xpet has, its system latch is clear and its 6702 is as the
-RES line leaves it, since xpet saves none of them, and in 6809 mode its
+that is the 6809, the 6809's registers, and its 6702. Its RAM switch is
+at R/W, the only position xpet has, and its system latch is clear, since
+xpet saves neither, and in 6809 mode its
 frame rate is the one the Waterloo ROM's CRTC table sets. It reports the modules it leaves out, such
 as the drives past device 8, the datasettes and the keyboard, and
 carries on without them, and a snapshot without a true drive takes
@@ -379,7 +413,10 @@ snapshot from its own modules, and leaves VICE's alone.
 x64sc 3.10 opens those snapshots, which are saved between
 instructions with no REU transfer under way, as long as its VIC-II
 model matches: `-model c64`, `c64c`, `ntsc`, `newntsc`,
-`oldntsc` or `drean`, as `--model` names the machine. It takes the REU
+`oldntsc`, `drean`, `pet64` or `c64gs`, as `--model` names the machine.
+The MAX Machine's needs `-model ultimax -VICIImodel 5`, since x64sc's
+`ultimax` has the 6567R8 and badline's the 6567R56A. The snapshot names
+the discrete glue logic, which x64sc's `c64c` and `c64gs` switch to. It takes the REU
 from the snapshot, keeps its own drives and leaves out the cartridge,
 the other expansions and the tape. A program x64sc runs on from badline's
 snapshot reads the raster as badline does, cycle for cycle.