badline 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b238dd5194dd5fc7783779eced6e4b718b73890e81d78566d12c26c08a379597
-  data.tar.gz: 4a47225b0d7e2a055674ce9f4f61cd2bc1064413a2c4c8b6bf228ed99f4dde07
+  metadata.gz: 41235fb28f9f33c9a88333beec1c09cd9825d45875f24d22b8cb5f66f9528467
+  data.tar.gz: c214b37efce97c404dcd0838283e65e0f42aaa86a8376f18ef2323933b01b2f2
 SHA512:
-  metadata.gz: c636911838f2d65ae88c6b4e940085790c54573c2cc6a9d97450b68f2319eb374f3330e75243487bd7538b56d5cb695f2fe085739ead20db06eb3f24b9169c45
-  data.tar.gz: c48b8ecfe80b51a178a757246adba3ea267901db096ccb74c28dbc6482a9ff1f71193c26b4829e98744bcd6847f5fe3f073ff01275604d8383dd36dd91f50f69
+  metadata.gz: ab2c530282a35d8ac65c217d6901d46c6f844cde1d7c7ca143acb8ea8f05ac08d1da6b8ee290fb41bd016ce2079e308bfd5c5f338be18ed269be693612e07a50
+  data.tar.gz: 6c27c6d41e73e495bb27e536fae7424b5524c12b9c1d12cdb3bccc2efb3a73be6137e5209c4356394594d71ceaa205309989f193344003a3ed65245df0ec74fa

data/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## [0.7.0](https://github.com/elektronaut/badline/compare/v0.6.1...v0.7.0) (2026-10-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* call a .sid tune's parts subtunes everywhere
+
+### Features
+
+* add a badline sid subcommand that plays tunes and directories ([7dfc21b](https://github.com/elektronaut/badline/commit/7dfc21b5e4ba47cd37a4593da61e95bb1d2329ab))
+* drop .sid files and folders on the SID player to queue them ([cc1f434](https://github.com/elektronaut/badline/commit/cc1f434b7404ded067ef43d1d3d5aa53d338de4c))
+* end a subtune with no known length when it falls silent ([46c4f10](https://github.com/elektronaut/badline/commit/46c4f1064f6382872ec22989253bc9c159f78dcf))
+* open a .sid tune, or no tune at all, in the SID player ([396c010](https://github.com/elektronaut/badline/commit/396c010ee626f95fbb71ced8bf3905909c470c8e))
+* play 2SID and 3SID tunes in stereo in the SID player ([7c72eef](https://github.com/elektronaut/badline/commit/7c72eeff7e5e7b1c56286f9bf6030ae3408f7176))
+* play a queue of tunes, with shuffle, loop and play-all subtunes ([d163106](https://github.com/elektronaut/badline/commit/d163106eea99d90f6ffe74fb91474a2aca4c64eb))
+* play sid tunes in a window that shows what the SID is doing ([60bfd3f](https://github.com/elektronaut/badline/commit/60bfd3f75fe82d928afa374d257d3d21e5ac29ad))
+* seek forward from where the subtune is, not from its start ([34059e8](https://github.com/elektronaut/badline/commit/34059e8f9b12cab44c94124e6455fef9c915d8eb))
+* seek within a subtune, and let the slow warning lapse ([b98ac6e](https://github.com/elektronaut/badline/commit/b98ac6eb6f9c0ce088545f55cc5f2445dd38dd2d))
+* show a tune's STIL entry in the SID player ([82d9dca](https://github.com/elektronaut/badline/commit/82d9dca26d7cefe853a6af41e50fc723a3e90170))
+* show each voice's live output in the SID view ([c61a128](https://github.com/elektronaut/badline/commit/c61a1289983887c0175fca3dc4c37b470e96de92))
+* show HVSC's STIL in the SID player ([bd55c0c](https://github.com/elektronaut/badline/commit/bd55c0c87695ba8cc84dbfd51ab2119a97eccded))
+* show where a seek is headed on the SID player's bar ([1a84b37](https://github.com/elektronaut/badline/commit/1a84b3746a960dba28dc9c789b3d2cd1520d2f94))
+* step subtunes and tunes on separate keys, add --all-subtunes ([eaef338](https://github.com/elektronaut/badline/commit/eaef3384e6205163e2a4b63f5aa8d9204fe5190f))
+* switch a SID between the 6581 and 8580 while it runs ([5920391](https://github.com/elektronaut/badline/commit/592039123d7936b8d22c8fd5f144a9bc9a8f383b))
+
+
+### Bug Fixes
+
+* build the native badline with a Spinel that keeps an array joined mid-expression alive ([d2c4eb2](https://github.com/elektronaut/badline/commit/d2c4eb20d6b80494fb2a20105c0532f3778b205c))
+* build the native badline with a Spinel that reports render progress ([58524ea](https://github.com/elektronaut/badline/commit/58524eaf4881661e7e0e9dd38c32071545bf1fae))
+* show non-ASCII text from a .sid header in the native badline ([959bb6f](https://github.com/elektronaut/badline/commit/959bb6f7d07de4c90ac50ae51ae63f3c66601a78))
+
+
+### Performance Improvements
+
+* draw the SID player's traces in one call each ([afcae15](https://github.com/elektronaut/badline/commit/afcae15ed273aa7a6dd49cb31e0f7180c56feb75))
+
+## [0.6.1](https://github.com/elektronaut/badline/compare/v0.6.0...v0.6.1) (2026-09-30)
+
+
+### Features
+
+* run both builds on one shared front end ([0e1ebfb](https://github.com/elektronaut/badline/commit/0e1ebfb07c4705b2e46c1bb44f1ea76f22370b24))
+* run both builds on one shared front end ([3181d5f](https://github.com/elektronaut/badline/commit/3181d5f2ab73628d515ea88c42ddef4b11f74ac0))
+* script key presses, media swaps and screenshots at given frames ([7a87069](https://github.com/elektronaut/badline/commit/7a87069d9b1491297e9a6ebd4fc0a860be3afd27))
+* script key presses, media swaps and screenshots at given frames ([5554511](https://github.com/elektronaut/badline/commit/5554511868d7986950cac829c3341689c88a32a7))
+
+
+### Bug Fixes
+
+* build the native badline with a Spinel that prints the headless player's display ([d2d3df3](https://github.com/elektronaut/badline/commit/d2d3df32c67c02c0e0f20308a03faca5430dfa26))
+* build the native badline with a Spinel that prints the headless player's display ([8dccecb](https://github.com/elektronaut/badline/commit/8dccecb2a2b8d044162b149203ca8aaf75aa4957))
+* build the native badline with a Spinel that renders .wav files ([bacfbea](https://github.com/elektronaut/badline/commit/bacfbea0c2d9af1c61c34aa09ff828ba767b2af3))
+* build the native badline with a Spinel that renders .wav files ([afc4267](https://github.com/elektronaut/badline/commit/afc42670f8543c50e74268ccc81284e46838df48))
+* end the run at a failed insert and say when there's nothing to eject ([f6b686d](https://github.com/elektronaut/badline/commit/f6b686d4094fbf526bffa37c7aa13dba0908bb71))
+* key testbench results by test key, so a row listed twice gets its own line ([a0f4d55](https://github.com/elektronaut/badline/commit/a0f4d555f568c2e82b08971adc00fa4199c1eac4))
+* leave .claude/ and vendor/ out of the gem ([c3ec867](https://github.com/elektronaut/badline/commit/c3ec867f04ee1840a01dfb0de2cce7cdd7aa30c6))
+* save the REU swap's pending re-read in snapshots, from a module of its own ([3448ac8](https://github.com/elektronaut/badline/commit/3448ac8a8827587b01ea2da6101c1f1b2009bc88))
+* show bank 3 for a cycle after a $dd00 bank swap on the 8565 ([2529eff](https://github.com/elektronaut/badline/commit/2529effb0c5fc3cf463e1d0e5b65e2321b3ed06d))
+* show bank 3 for the cycle after a $dd00 write swaps the bank lines on the 8565 ([c9959f4](https://github.com/elektronaut/badline/commit/c9959f430ac7a95397d906e1c70013bbc25b5ca2))
+* time the REU's swaps and fetches against the VIC, and take the bus from an RMW write ([60e48bd](https://github.com/elektronaut/badline/commit/60e48bd8531d130252101d6227ef296ed0b6395b))
+* time the REU's swaps and fetches against the VIC, and take the bus from an RMW write ([eb045fa](https://github.com/elektronaut/badline/commit/eb045fa3d20e0a1abc9acdf68bfb1f9388d7ca57))
+* write a fetch's first byte twice when BA falls as it starts ([35c4cf4](https://github.com/elektronaut/badline/commit/35c4cf419178bdf1b704f94c815dce259368fa26))
+* write a fetch's first byte twice when BA falls as it starts ([1ab691a](https://github.com/elektronaut/badline/commit/1ab691a512b54d58670d5a2ae244f917c715bb25))
+* write the 6581's pulse+noise lines only mid-shift ([95f84dd](https://github.com/elektronaut/badline/commit/95f84dd6e842bf76e562dd9867f24916039debd5))
+
+
+### Performance Improvements
+
+* give the 1541's 6502 a class of its own ([df64d23](https://github.com/elektronaut/badline/commit/df64d231f97824f2a6dc7bd37a1e4ef4294dc8da))
+* give the 1541's 6502 a class of its own ([8193a52](https://github.com/elektronaut/badline/commit/8193a52c642a8c176cc29591d99beffb91300620))
+
+
+### Miscellaneous Chores
+
+* release 0.6.1 ([059cd50](https://github.com/elektronaut/badline/commit/059cd502dd356760179e5df823402891b99349bd))
+
 ## [0.6.0](https://github.com/elektronaut/badline/compare/v0.5.1...v0.6.0) (2026-09-29)
 
 

data/CLAUDE.md

@@ -25,14 +25,18 @@ live in subdirectories:
 - **Media and host I/O**: `storage/` (disk, tape and cartridge image
   formats), `cartridge/` (mappers), `kernal_trap/` (the LOAD/SAVE and IEC
   traps that stand in for a drive), `media.rb` (attach and autostart),
-  `datasette.rb`, and `gui/` and `input/` (SDL front end, controllers)
-- **Native**: `native/` holds the native `badline`, the core compiled with
-  Spinel in an SDL2 window (`rake native:build`, `native/README.md`).
+  `datasette.rb`, and `input/` (the mouse and paddles)
+- **Front end**: `frontend/`, the SDL window both builds run (app loop,
+  screen, pacer, sound, controls, gamepads, snapshots), in Spinel's
+  subset, over the one binding in `sdl.rb` (`ffi.rb` implements it on
+  CRuby)
+- **Native**: `native/` holds the native `badline`, the core and the
+  front end compiled with Spinel (`rake native:build`, `native/README.md`).
   `spinel/` holds the Spinel test harnesses
 
 Timing-critical code lives in `cpu`, `interrupts`, `vic`, `cia` and `sid` and
 in the order `Computer#cycle!` clocks them. Changes there move the test
-suites below. `gui/` changes move none of them.
+suites below. `frontend/` changes move none of them.
 
 Namespaced groups live in `lib/badline/<namespace>/`, with a sibling
 `lib/badline/<namespace>.rb` that requires the members, directly or through
@@ -157,8 +161,8 @@ the rows your change can't reach tell you nothing about it.
   `ruby --yjit bin/lorenz [image] [start_test] [max_cycles]` (resumes the
   chain at a named test, and `--stop-after NAME` ends it once that test is
   done). These take seconds to minutes
-- A pull request's CI is the verdict. It runs every suite but
-  `testbench-drive` on the Spinel build, compared row by row against
+- A pull request's CI is the verdict. It runs every suite on the Spinel
+  build, compared row by row against
   `test/baselines/`, and every job is a required check. A row that moved
   fails it. Re-record only those rows, in the same change:
   `rake "regression:record:<suite>[filter,...]"` (quote it, because zsh
@@ -174,9 +178,6 @@ the rows your change can't reach tell you nothing about it.
 - For a change whose reach you can't bound to a set of filters, such as
   reordering `Computer#cycle!` or changing the LOAD trap every suite loads
   through, push and let CI run the suites
-- `testbench-drive` needs the true drive, which the Spinel testbench
-  harness doesn't have, so CI leaves it out. Run the rows your change can
-  reach locally
 - 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/README.md

@@ -56,25 +56,64 @@ badline game.prg       # Load and run a program
 badline game.d64       # Mount a disk image as device 8 and load it
 badline game.tap       # Insert a tape and load it
 badline game.crt       # Attach a cartridge
-badline tune.sid       # Play a SID tune
+badline tune.sid       # Play a SID tune in the SID player
 badline game.vsf       # Restore a snapshot, from badline or VICE
 badline ~/c64          # Mount a directory as device 8
 ```
 
-`badline-ruby` takes the same media and the same options, with the
-differences noted below.
-
 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. `--no-autostart` attaches the media and stops at `READY.`, so
-you can type the `LOAD` yourself. `--read-only` mounts a disk image
-write-protected, so the drive reports `26,WRITE PROTECT ON` for any
-write and the image file stays as it was. `--song N` picks a subtune of a
-`.sid` file, `--sid 8580` fits the newer SID and `--reu 512` plugs in a
-512K RAM Expansion Unit. `--ntsc` runs an NTSC C64, with the 6567R8
-VIC-II, instead of a PAL one. `badline-ruby` also
-takes `--disable-jit`, which runs without YJIT, otherwise switched on at
-startup. `--help` lists the options.
+from it.
+
+`badline-ruby` takes the same media and the same options, with the
+differences noted in the table. `--help` lists the options for either.
+
+### Options
+
+| Option | Effect |
+| --- | --- |
+| `--no-autostart` | Attach the media and stop at `READY.`, so you can type the `LOAD` yourself |
+| `--read-only` | Mount a disk image write-protected. The drive reports `26,WRITE PROTECT ON` for any write and the image file stays as it was |
+| `--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 |
+| `--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 |
+| `--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 |
+| `--verbose` | Print the display's refresh rate, the sound's sample rate and the game controllers found as the window opens, then the frame rate and the time each frame takes, once a second |
+| `--disable-jit` | Run without YJIT, otherwise switched on at startup (`badline-ruby` only) |
+| `--version` | Show the version and what built it (`badline` only) |
+| `-h`, `--help` | List the options |
+
+Both run the same window. `badline` plays the SID through the host's
+audio device, and `F10` mutes and unmutes it. In `badline-ruby` the
+machine runs below real time, so the sound stutters: it plays in bursts
+with silent gaps between them, at the right pitch, and never slows the
+emulation down.
+
+### Scripted runs
+
+| Option | Effect |
+| --- | --- |
+| `--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 |
+| `--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 |
+
+```sh
+badline --unpaced --frames 12000 --true-drive disk1.d64 \
+  --at 3500:key=space --at 5600:insert=disk2.d64 \
+  --at 250,500,6000:screenshot=shot%05d.bmp
+```
+
+`--help` lists the events, and [native/README.md](native/README.md#running)
+describes them.
+
+### ROMs
 
 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
@@ -83,20 +122,6 @@ plus `eapi/eapi-am29f040-14` if you attach EasyFlash cartridges. From
 Ruby, `Badline.rom_path = dir` does the same before a
 `Badline::Computer` is built, and `nil` restores the bundled set.
 
-`badline` plays the SID through the host's audio device, and `F10`
-mutes and unmutes it. `--no-sound` turns it off. The window is paced by
-the display's vsync; `--no-vsync` paces it by a timer, or by the sound
-while it plays.
-
-`--verbose` prints the display's refresh rate, the sound's sample rate
-and the game controllers found as the window opens. In `badline` it also
-prints the frame rate and the time each frame takes, once a second.
-
-In `badline-ruby` sound is off by default, and `--sound` turns it on.
-The machine runs below real time there, so the sound stutters: it plays
-in bursts with silent gaps between them, at the right pitch, and never
-slows the emulation down.
-
 ## Media
 
 | Format | Handling |
@@ -201,39 +226,107 @@ out and switches the machine off and on.
 
 `badline-ruby --headless` plays a `.sid` tune on the host's audio
 device without opening the window, and `--audio-out` renders it to a
-16-bit PCM file instead. The file's extension picks the format, `.wav`
+16-bit stereo PCM file instead. The file's extension picks the format, `.wav`
 or `.aiff`. The native `badline` has both modes too.
 
 ```sh
+badline sid ~/C64Music/MUSICIANS/H/Hubbard_Rob               # play every tune below a directory
+badline sid tune.sid other.sid                               # play a queue of tunes
 badline-ruby --headless tune.sid                             # play, length from HVSC
 badline-ruby --headless -s 3 tune.sid                        # play the third subtune
+badline-ruby --headless --all-subtunes tune.sid                 # play on through every subtune
 badline-ruby --seconds 180 tune.sid --audio-out out.aiff
 badline-ruby -s 3 --rate 48000 tune.sid --audio-out out.wav
 badline-ruby --headless --sid 8580 tune.sid
 badline-ruby --filter-chunk 1 tune.sid --audio-out out.wav   # exact filter, slower
 ```
 
+`badline sid FILE|DIR...` plays a queue of tunes in the SID player's
+window, in the order given, and a directory adds every `.sid` tune below
+it in path order. `badline sid --headless` plays the queue in the
+terminal instead. `badline sid` on its own opens the window with an
+empty queue. Dropping `.sid` files or folders on the window adds them
+to the end of the queue, and an empty queue starts playing them. It
+takes
+the options below except `--audio-out`, and `--subtune` picks the first
+tune's subtune. `--sid auto`, the default, fits each of a tune's SIDs
+the model its header names. A tune written for 2 or 3 SIDs plays on as
+many, at the addresses its header gives, in stereo: SID 1 on the left,
+SID 2 on the right and SID 3 in the centre. A tune on one SID plays the
+same on both channels. A file that isn't a tune is skipped.
+`badline tune.sid` plays the tune in the SID player too, unless an
+option of the emulator's window, such as `--ntsc` or `--reu`, asks for
+the machine: then a tune for one SID runs on the emulated C64, started
+through a small driver after boot.
+
 Both modes take the same options. The window's own, `--no-autostart`,
 `--read-only`, `--sound`, `--true-drive`, `--reu`, `--ntsc` and
-`--verbose`, don't apply to them. `--song` (or `-s`) picks the subtune, counting from 1 as HVSC
-does, and defaults to the tune's own start song. Playback asks the
+`--verbose`, don't apply to them. `--subtune` (or `-s`) picks the subtune, counting from 1 as HVSC
+does, and defaults to the tune's own start subtune. Playback asks the
 device for 44.1 kHz and takes whatever rate it offers, unless `--rate`
 says otherwise. Ctrl-C stops it.
 
-Played on a terminal, `--headless` shows the tune's name, author and
-release, the song number and the time played against the song's
-length. When a song reaches its length it goes on to the next, and it
-stops after the last. `n` or → skips to the next song, `p` or ← goes
-back one, space pauses and `q` quits. `--no-tui`, or output that isn't a
-terminal, gives plain progress output instead and plays just the one
-song, as `--audio-out` renders just the one.
+Played on a terminal, `--headless` and `sid` show each tune's name,
+author and release as it starts, then the tune's place in the queue,
+the subtune number and the time played against the subtune's length. `--headless`
+queues just the one tune. Each tune plays its own subtune: `--subtune`, or
+the tune's start subtune. When that subtune ends the player goes on to the next
+tune, and it stops after the last. `a`, or `--all-subtunes`, turns on
+playing all subtunes, so that a subtune that ends goes on to the tune's next
+subtune, and a tune stepped to starts on its first subtune.
+
+→ and ← step to the tune's next and previous subtune, stopping at its
+first and last. `n` and `p` step to the next and previous tune. `s`
+turns shuffle on and off, which plays the queue's tunes in a random
+order, and `l` turns looping on and off, so that the end of the queue
+goes on to its start. `,` and `.` seek 10 seconds back and forward
+within the subtune, which plays it again from its start and runs silently
+up to the point asked for. Space pauses and `q` quits. The status line
+shows which modes are on, and they last until the player quits.
+
+![The SID player's visualizer playing Rob Hubbard's Delta](doc/images/sid-player.png)
+
+The SID player's window is worked with the mouse. Its header shows the
+tune's name, author and release, the tune the subtune covers at the
+moment when HVSC's STIL credits one, following the times STIL gives, and
+buttons that switch between three views and between the tune's own SID
+model, the 6581 and the 8580, which changes the chips playing on the
+spot. Its footer shows the time played on a bar you can click to seek,
+and buttons that pause, step between tunes and between a tune's
+subtunes, and turn shuffle, looping and all subtunes on and off. The
+visualizer view shows each voice's note, and how far off it is in cents,
+over a scope of the voice's output, and the mixed output below them. A
+tune on more than one SID gets a row of voices for each SID, and the mix
+splits into its left and right. The SID view shows one SID at a time,
+and for a tune on more than one, a row of SID 1, 2 and 3 buttons at its
+top picks which. It shows each voice's waveforms and the shape
+they make, its control bits, pulse width, envelope settings, and the
+envelope's level and stage, and the filter's modes, cutoff, resonance,
+volume and its response on the chip playing. The INFO view shows the
+tune's STIL entry and the subtune's, with a scroll bar, the mouse wheel
+or the up and down keys for the long ones. The terminal's keys work in
+the window too, along with Tab to switch views and `c` to step through
+the SID models.
+
+`--no-tui`, or output that isn't a terminal, gives plain progress
+output instead and plays through the queue without the keys, while
+`--audio-out` renders just the one subtune.
 
 A `.sid` file doesn't store its length, so `badline-ruby` looks the
 tune up by MD5 in HVSC's `Songlengths.md5`. It finds the database
 through `--songlengths`, in a `DOCUMENTS` directory in any of the
 tune's parent directories (the layout of an HVSC collection), or under
 `$HVSC_BASE/DOCUMENTS`. Without a database or `--seconds` it runs for
-60 seconds.
+60 seconds, but a subtune that falls silent for 5 seconds before then
+ends there, when played and when rendered alike. Silent means the
+output holds within 16 steps of one level, since a 6581 idles at a DC
+offset rather than at zero. A subtune with a known length plays to its
+length whatever it sounds like.
+
+A tune in an HVSC collection also gets its entry in HVSC's `STIL.txt`,
+found the same way: comments, covers, and subtune names and composers.
+The tune's own fields follow its header, and each subtune's print as it
+starts.
 
 PSID tunes run on a CPU and RAM with only the SID clocked, at about
 twice real time, so they play smoothly. RSID tunes set up their own
@@ -250,9 +343,9 @@ without stuttering. See
 
 ## Input
 
-Keys map by their unshifted symbol, and Shift gives the C64's shifted
-character, not the host's: Shift-2 types `"`. These keys have no
-same-named host key:
+Keys map by their position on a US keyboard, whatever the host's layout,
+and Shift gives the C64's shifted character, not the host's: Shift-2
+types `"`. These keys have no same-named host key:
 
 | C64 | Host |
 |-----|------|
@@ -275,7 +368,7 @@ window title shows the current mode:
 | Mode | What the host drives |
 |------|----------------------|
 | (none) | The keyboard |
-| `[JOY]` | Arrows and Space are joystick 2, `WASD` and Left Shift joystick 1 |
+| `[JOY 2]` / `[JOY 1]` | Arrows and Space (or Right Ctrl) are the joystick named, `WASD` and Left Shift the other. `F9` swaps them |
 | `[MOUSE 1]` / `[MOUSE 2]` | A 1351 mouse in control port 1 or 2 |
 | `[PADDLE 1]` / `[PADDLE 2]` | A pair of paddles in control port 1 or 2 |
 

data/doc/pinned-behaviour.md

@@ -869,6 +869,18 @@ are the row's diff with the rule removed.
     fails with two.
   - Spec guard: *adds one extra half-pixel on the 8565* in
     [`vic_spec.rb`](../spec/badline/vic_spec.rb).
+- **A `$dd00` write that swaps the bank lines shows bank 3 for a cycle.**
+  Where one bank line goes high as the other goes low, every VIC access in
+  the cycle after the write reads bank 3 (both lines low), and the new bank
+  from the cycle after that (`VIC::Bank#sample_lines`). A swap the DDR
+  makes, releasing a line to float high, shows nothing, and neither does a
+  write that moves one line or both the same way.
+  - Pinned by `fetchsplit` (154 → 16 px): every 8565 capture its readme
+    lists shows `3` in the first character after each `$dd00` swap, while
+    the 6569 reference shows none. `M1` also shows it after the DDR swaps;
+    `M7`, which the `-8565` reference is made from, doesn't.
+  - Spec guard: the `#sample_lines` group in
+    [`bank_spec.rb`](../spec/badline/vic/bank_spec.rb).
 
 What the 8565 references don't settle, and so what stays as it is:
 
@@ -882,12 +894,21 @@ What the 8565 references don't settle, and so what stays as it is:
   `vicii_reg_timing-ff` (7 px, the hi-res bitmap into text row) stay FAIL.
   No emulator in the testbench results passes `vicii_reg_timing-a5` or
   `-ff` on the 8565, and only Hoxs64 passes `modesplit`, against the
-  `8565early` reference.
-- `fetchsplit` (154 px) stays FAIL: its readme says its 8565 artefacts
-  differ from chip to chip and change as the machine warms up, and its
-  `M1` and `M7` captures differ. The differences sit in the first character
-  after a `$dd00` bank switch on some lines. Delaying every rising, or
-  every falling, bank bit by a cycle on the 8565 makes it 656 or 752 px.
+  `8565early` reference. Listed by transition, the references disagree
+  on the same pixel: out of ECM+BMM into ECM text a foreground pixel 0 is
+  on time in `videomode-w` and black in `modesplit`; out of ECM into hi-res
+  text a background pixel 0 selecting `$d022` shows the new mode in the
+  `vicii_reg_timing` ECM row and the old one in `modesplit`; out of hi-res
+  bitmap into text a foreground pixel 0 is new in `-a5` and old in `-ff`,
+  with the same screen, colour and pixel values. Each test's position is
+  independent of where it starts: booting 0 to 20000 cycles longer before
+  attaching gives the same diff.
+- `fetchsplit` (16 px) stays FAIL on the one swap the DDR makes that the
+  `-8565` reference shows as bank 3: the swap in column 34 of the `line1c`
+  rows, in the text and ECM blocks but not the bitmap one, while the same
+  swap in column 4 of `line1b` shows nothing. The readme says its 8565
+  artefacts differ from chip to chip and change as the machine warms up,
+  and its `M1` capture shows bank 3 after every DDR swap.
 - VICE's idle g-access also reads ECM from the `$d011` of the column
   before on the 8565. No testprog tells it apart, so the 8565 keeps the
   6569's idle access, without the 6569's `$38ff` read where a DMA delay
@@ -933,6 +954,22 @@ region moves the sprites. The positions live in `Region::Profile` and
   `testbench-ntsc` screenshots, VICE's 247 lines from line 28 running on
   into the next frame, see every line they show painted.
 
+What the NTSC references don't settle, and so what stays as it is:
+
+- `modesplit` on the 6567R56A (62 px) is compared against the PAL
+  reference, since there is no `-ntscold` one, and every pixel of its
+  diff sits in the label bar, where the test prints the line length and
+  line count it measured, and the reference shows the PAL ones.
+- `modesplit` on the 6567R8 (458 px) matches the PAL reference on every
+  row but the label bar. Its `-ntsc` reference differs from the PAL one
+  in ways no 6567R8 rule here produces: light grey on the first pixel
+  after each `$d021` write (a grey dot, 20 px), the ECM split of section
+  2 alone starting and ending a character later (most of the diff) while
+  sections 1 and 3 keep their PAL positions, and single pixels in
+  section 1. The
+  readme says it was matched against screenshots, and the one 6567R8
+  photograph in the testprogs is of revision R01.
+
 ## CIA 6526 timer pipeline
 
 - Start and stop go through two stages. A force load lands one tick after
@@ -1292,27 +1329,78 @@ and each was knocked out: removing it fails the rows named.
 The REC's timing against the VIC, each rule derived from the REU
 testprogs named.
 
-- A requested transfer takes the bus on the CPU's next read cycle with BA
-  high, and moves its first byte there. Starting a cycle later moves every
-  `REU/xfertiming` row and `REU/reutiming/reutiming`.
+- A requested transfer takes the bus on the next cycle with BA high, and
+  moves its first byte there. Starting a cycle later moves every
+  `REU/xfertiming` row and `REU/reutiming/reutiming`. /DMA takes the bus
+  from the CPU from the cycle after the request, even while the REC waits
+  for BA, and RDY only halts the CPU on a read, so a write the CPU makes
+  then goes nowhere (`AddressBus#cycle_cpu_off_bus`). That is how an `INC
+  $FF00` starts an armed transfer without its second write reaching RAM.
+  Pinned by `REU/rmw-trigger/rmwtrigger-ram` and `rmwtrigger-rom`.
 - After reading C64 memory the REC waits out every BA-low cycle. After
   writing it goes on through the first BA-low cycle and waits from the
   second, and a fetch or swap whose last write it waited out takes one
   more cycle before handing the bus back (`REU::DMA#note_ba`,
   `#wind_down`). Pinned by `REU/bonzai/spritetiming`, whose 45 bytes a
   line with eight sprites on is 63 less the 18 cycles this leaves.
-- On the line whose raster matches sprite 0's Y, the REU doesn't see BA
-  fall on the first cycle of sprite 0's window (`VIC#reu_ba_low?`).
-  Without it `REU/bonzai/spritetiming` reads `$5a,$87` where a real REU
-  gives `$5b,$88`.
+- A fetch's last write doesn't go through the first BA-low cycle: the REC
+  waits for BA to rise and writes it then. Pinned by `REU/reutiming2/d`
+  and `d2`, and it takes `REU/reutiming2/c` from 6,403 px to 337.
+- A fetch requested on the last cycle before BA falls writes its first
+  byte on the first BA-low cycle, without counting it, then waits for BA
+  and writes the same byte again when it starts (`REU::DMA#write_ahead`).
+  One requested on a BA-low cycle writes nothing until BA rises. Pinned by
+  `REU/badoublewrite`, whose sixth transfer a frame, requested on the
+  cycle before BA falls for raster `$63`, a bad line, holds `$d021` at its
+  first byte for the whole line, where the program's text says "d021
+  doublewrite on this line". The row captures its screen too early to
+  show this (see below), but the frame after matches the reference to the
+  pixel, and without the rule that line is 199 px off.
+- `REU/badoublewrite` writes `$D7FF` from its raster interrupt on the
+  third transfer of the first frame it runs them in, at raster 77, so the
+  screenshot taken at that write shows the frame before below it, with
+  the text half printed and the background still blue. Its reference
+  shows a whole frame of twelve transfers on black, which only a
+  screenshot a frame or more later can. The exit is locked to the raster:
+  starting the program anywhere up to a frame later leaves it on raster
+  77 with the same 58,880 px. VICE's own x64sc and x64 fail the row in every result the
+  testbench keeps, r41951 to r45942, while Denise passes it from 2023.
+  The row stays at 58,880 px.
+- `REU/reutiming2/c`'s reference shows its last transfer, from raster 250
+  into 251 (`$fb`), waiting on raster 251 as the transfers above it wait
+  on their bad lines: the border holds the transfer's byte `$11` up to
+  x 336 and `$12` from x 337, where BA rises on a bad line. Raster 251 is
+  past the bad line range, `$30`–`$f7`, and the program turns on no
+  sprites, so nothing pulls BA there, and badline writes `$12` on the
+  cycle after `$11`, before the line's visible part starts. The 8565 and
+  8565early references show the same wait. No emulator or FPGA core in
+  the testbench's 59 kept results passes the row, VICE, the Ultimate 64
+  and the Chameleon included, and the testlist marks it `warn:vicefail`.
+  badline keeps the bad line range, and the row stays at 337 px, all of
+  them on raster 251.
+- On the line whose raster matches sprite 0's Y, a REC that read or wrote
+  on the cycle before doesn't see BA fall on the first cycle of sprite
+  0's window (`VIC#reu_ba_late?`). Without it `REU/bonzai/spritetiming`
+  reads `$5a,$87` where a real REU gives `$5b,$88`. A swap's read on that
+  cycle still sees BA low, and is held as the next rule says (pinned by
+  `REU/reutiming2/e4-m2` and `e6-m2`).
 - A swap's read that falls on the first BA-low cycle, after its write, is
   held open while AEC stays high and takes the byte on the bus two cycles
   later. If it is the transfer's last byte it is read there instead, its
   write follows on the next cycle, and the REC hands the bus back
   (`REU::DMA#swap_read_on_ba`). Pinned by `REU/reutiming2/e5-m2`, `f3-m2`
-  and `f4-m2`, whose patterns were captured on a breadbin. The
-  `reutiming2` references without `-m2` read `$42` or a timer value there
-  instead, and still fail.
+  and `f4-m2`, whose patterns were captured on a breadbin.
+- A swap's read made with BA high, when BA falls on the next cycle before
+  its write, is made again when BA rises, and the write follows it
+  (`REU::DMA#read_swap_again`). So is a held read when BA runs straight
+  from a bad line's window into sprite 0's (`VIC#reu_ba_handed_on?`).
+  Pinned by `REU/reutiming2/e4-m2`, `e6-m2`, `g3-m2` and `g4-m2`.
+- The `reutiming2` references without `-m2` read `$42`, the RAM under
+  `$DC04`, on some of the cycles a swap's or stash's read starts with the
+  VIC's DMA. The readme puts that down to a C64C board or an 8565, while
+  the testlist runs those rows on the 6569, the same machine as the `-m2`
+  rows, whose references read the timer there. The two sets can't both
+  pass on one machine, and badline follows the breadbin `-m2` ones.
 
 ## SID oscillator
 
@@ -1340,7 +1428,8 @@ testprogs named.
   its output is latched instead. The cycle after that is phase 2: the
   latched output is written over the taps, then the register shifts.
   Phase 2 writes back by the test bit release rule below, with the old and
-  new waveform the same: noise combined with anything but pulse alone.
+  new waveform the same: noise combined with anything but pulse alone. On
+  the 6581, phase 2 also writes pulse+noise's lines (below).
   Setting the test bit drops a shift in flight.
   - Pinned by `SID/noisewriteback`'s `noise_writeback_test2` (both chips).
     It releases the test bit into noise+triangle, which pulls every tap low,
@@ -1364,6 +1453,9 @@ testprogs named.
     `$f8`/`$80` pairs set the test bit onto all four waveforms from noise
     alone, and zero the register only if this writes back. The release that
     follows goes to noise alone, which writes nothing back (below).
+  - On the 6581, pulse+noise writes its `$00` read back here, as in a
+    shift's phase 2 (below). Pinned by `SID/wf12nsr`'s pulse+noise row,
+    which sets the test bit onto pulse+noise.
   - Spec guard: *as the test bit rises* in
     [`sid/waveform_spec.rb`](../spec/badline/sid/waveform_spec.rb).
 - The test bit does not clear the LFSR. It stalls it halfway through a
@@ -1445,9 +1537,10 @@ testprogs named.
     register and writes `$fc` back, the only pair among `$f8`, `$fc` and the
     full noise that passes `SID/wf12nsr`'s pulse+noise row. That `$fc` is what
     `SID/wb_testsuite`'s `C`→`9` and `C`→`E` rows need written at release.
-    The 6581 reads `$fc` (the readme of `SID/wf12nsr`, VICE bug #1037,
-    unscored) and writes nothing back: its `8`/`9`/`A`/`B`→`C` rows run
-    pulse+noise and leave the register alone.
+    The 6581 reads `$00` of a full register, and pulls nothing down while
+    the register holds. Its lines land only part way through a shift: in
+    a shift's phase 2, and as the test bit rises onto pulse+noise. Both
+    write the `$00` read, so every tap goes low.
   - Pinned by `SID/wf12nsr` (wf9/wfa on both chips, wfc on the 8580) and
     the `SID/wb_testsuite` rows above. Knock-outs: writing back the plain
     AND fails wf9 and wfa on both chips; on the 8580, reading and writing
@@ -1455,17 +1548,25 @@ testprogs named.
     fails wfc and the `C`→`9`/`C`→`E` rows; applying the lone-line rule to
     the read as well makes `noise_writeback_test2` read `$00` on both
     chips.
-  - Can't pass: the 6581's pulse+noise row of `SID/wf12nsr`. The program
-    never writes voice 3's pulse width, so the row depends on whatever width
-    the machine it was recorded on held. The 6581 reference reads `$00`
-    right after the release into pulse+noise at frequency `$ffff`, as if
-    the pulse was still low and grounding every line. After power-on or
-    reset the width is zero and the pulse is high. With the width set
-    before the program runs, the row passes from `$1a0` up and fails from
-    `$198` down. The 8580 program passes from a zero width. `SID/wf12nsr`'s `quicktest.prg` doesn't set the width
-    either. The row stays failing.
+  - The 6581's pulse+noise is pinned by `SID/wf12nsr`'s wfc row and
+    `SID/wb_testsuite`'s `8`→`C` and `C`→`C` rows. The wfc row releases the
+    test bit into pulse+noise at frequency `$ffff` with the pulse width
+    never written, so zero and the pulse high, and reads `$00` on the next
+    instruction, before bit 19 first rises. That read is of a full
+    register, so the `$00` is the read itself. Its noise run afterwards
+    matches the other combined rows, whose taps were all pulled low. The
+    `8`→`C` and `C`→`C` rows hold pulse+noise at frequency zero, where no
+    shift comes, and leave the register alone. Knock-outs: writing the
+    `$00` back every cycle and at release fails `8`→`C`, `C`→`C` and ten
+    more 6581 rows (the recorded VICE r45942 results pass wfc and fail
+    `8`→`C` and `C`→`C`); dropping the phase 2 write or the write as the
+    test bit rises fails wfc. The readme
+    of `SID/wf12nsr` has a warmed-up 6581 reading `$fc` with the test bit
+    held (`quicktest.prg`, unscored), which this model doesn't reproduce.
   - Spec guard: *writes a lone line of a noise combination back low*, *with
-    pulse+noise on the 8580* and *as the test bit falls* in
+    pulse+noise on the 8580*, *reads nothing of pulse+noise on the 6581*,
+    *with pulse+noise on the 6581*, *as the test bit rises* and *as the
+    test bit falls* in
     [`sid/waveform_spec.rb`](../spec/badline/sid/waveform_spec.rb).
 - The pulse comparator's output reaches the lines a cycle after the
   accumulator it compared, on both chips. Setting the test bit forces it