badline 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a074ca0626351bec4132e06bc5e4ab951f7a4b18cf9e78ddc3c16adfd4194b8
-  data.tar.gz: 878629423f450e6c6440649b00d87646c1ff59d5ccb99801d5909fedc14f9108
+  metadata.gz: dcc4aea1603a5dac88787b701529e7019573fa5bd3b66cdd31a6d4f071fb3ecf
+  data.tar.gz: bc8de62e989822edd15ff2d59002a034c361c176e50a0e064a3482ff820b150a
 SHA512:
-  metadata.gz: 8eb5553980d187ccafd1ac4906b8a3d7fb6a80a8219375ef872f208411c362bf3724e721946ed166b91595177ce3adf38632e2b69008d9a4082032239cfcb697
-  data.tar.gz: dcb3a6ab34cceff4e85b56d09c2e38eaeab8350f57928c07e23ba7c6f5de38b32a88a0735802a2d196bb2ccf89a6a058579a47daf85ca8ac275f5b6bce90a975
+  metadata.gz: 88c53ecfb3d2322c4f2ed6cc99c58e3e5cdb9b135b9afaae85a183f95d23d1546c0c7d245547dfe968574849689508e0669dda8648c3a0cb123251672895d442
+  data.tar.gz: 2d2d289ef46a002ff548fb7a219805a8c6fcbd555f469f4f8bb8eb87bc6895df48e83d8694ec262251d87997a2f2d325120f608f491df76ef9c47f83be1cc0e2

data/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## [0.15.0](https://github.com/elektronaut/badline/compare/v0.14.0...v0.15.0) (2026-10-12)
+
+
+### Features
+
+* run the Plus/4 and the C16 in the window with badline plus4 ([935bcf1](https://github.com/elektronaut/badline/commit/935bcf11b986c65f01024515d7c98ac1efa46530))
+* paint the TED's picture ([ede7805](https://github.com/elektronaut/badline/commit/ede7805b8113cb6321fbfdffedcb6b7a79e95983))
+* play the TED's sound ([a34efd6](https://github.com/elektronaut/badline/commit/a34efd67dbec995f246781452bce7c9c070ed10b))
+* read the Plus/4's joysticks through the keyboard latch and map its keys ([6a1f7cb](https://github.com/elektronaut/badline/commit/6a1f7cb5a9a9426562fe5b3c9106a245bc23d287))
+* attach programs, disks and cartridges to a Plus/4 ([84a86f4](https://github.com/elektronaut/badline/commit/84a86f43e97e08fdb4ea21ef909adf54bc09540c))
+* put a true 1541 or 1581 on the Plus/4's serial bus ([bd068ff](https://github.com/elektronaut/badline/commit/bd068ffd1b337915ad70ed9e96f10df6ca770c05))
+* put Plus/4 cartridges in both slots, from .crt or raw .bin ([42ae7c0](https://github.com/elektronaut/badline/commit/42ae7c0f66dd200bc1787ad3a9bd62c4f57719eb))
+* play and record Plus/4 and C16 tapes ([cd19fa9](https://github.com/elektronaut/badline/commit/cd19fa920a4e2b8a488011872ca98f6bd95cb43a))
+* show the Plus/4's picture, play its sound and drive its joysticks in the front end ([4213c26](https://github.com/elektronaut/badline/commit/4213c26ffeaafe46bc6ec42433e2dc763b70aa6a))
+* keyed snapshots for the Plus/4 and the C16 ([c7a1ace](https://github.com/elektronaut/badline/commit/c7a1ace2c3c94064bb14841773e109c56e49f1d6))
+* save the Plus/4 from F11 and the Snapshots page ([853085f](https://github.com/elektronaut/badline/commit/853085f0c177fcbf305c1fd60cd1a800dfcbc266))
+* save cartridge mappers' registers in snapshots ([9ea6e0b](https://github.com/elektronaut/badline/commit/9ea6e0b2669c4ae9ed8270cf3de345787c76dcb3))
+* save the extra SIDs in snapshots ([bf7f142](https://github.com/elektronaut/badline/commit/bf7f1426472620b6168352ba3bf74e4780d29e89))
+
+### Bug Fixes
+
+* store a C128 bank LOAD into the I/O that bank maps ([58672c2](https://github.com/elektronaut/badline/commit/58672c2bb7b9a5fed8d75d72007d00444eebb696))
+
+## [0.14.0](https://github.com/elektronaut/badline/compare/v0.13.0...v0.14.0) (2026-10-11)
+
+
+### Features
+
+* add the keyed snapshot record encoding ([1b87aed](https://github.com/elektronaut/badline/commit/1b87aeddea27f81cb1ccedbbef2bba58c2db0bb3))
+* boot the Plus/4 and the C16 to READY headless ([278020e](https://github.com/elektronaut/badline/commit/278020ee0256fa1d085391fd0e7a6679ac80dbcb))
+* bundle the 264 series ROMs and refuse badline plus4 until it runs ([7072ae7](https://github.com/elektronaut/badline/commit/7072ae7cb6e1ccd96a4e02eb1146b7b1bfaf7125))
+* give each machine its keyboard buffer layout ([0b64648](https://github.com/elektronaut/badline/commit/0b64648fec3cd56bbbee1ac4dc8fe446c84dd4b9))
+* keep the KERNAL's file variables in KernalTrap::Layout ([0ca7488](https://github.com/elektronaut/badline/commit/0ca7488505b2b7af9f358bdf6d3e86a1e1c768e3))
+* keyed snapshot fields for device 8 through the KERNAL traps ([cce36f2](https://github.com/elektronaut/badline/commit/cce36f2f740c5337cd2b0a66fe99394114409c32))
+* keyed snapshot fields for each machine's own state and setup ([ff251a6](https://github.com/elektronaut/badline/commit/ff251a62cbad4502f576628a4f4c5d3d6a22eaf8))
+* keyed snapshot fields for the 1541 ([f3f57b7](https://github.com/elektronaut/badline/commit/f3f57b7e24471e198304bfd90ba16c4abb7c4c16))
+* keyed snapshot fields for the 1571 ([5ceb741](https://github.com/elektronaut/badline/commit/5ceb7416a1902252d97c80aff22658a68e4abfb6))
+* keyed snapshot fields for the 1581 ([1c67e29](https://github.com/elektronaut/badline/commit/1c67e298c24e82e92cc5feddcc0153143d4eda8d))
+* keyed snapshot fields for the 6502 cores and the Z80 ([8ee592e](https://github.com/elektronaut/badline/commit/8ee592e5ee5b658c8f452cf4bdf9df044f8c19ab))
+* keyed snapshot fields for the C128's MMU ([aa861ca](https://github.com/elektronaut/badline/commit/aa861cac0a33d79f777b60310f0cb573024f2d60))
+* keyed snapshot fields for the cartridges ([349ae81](https://github.com/elektronaut/badline/commit/349ae81c7c002f5c1b94fa50cc994a6b7ec16915))
+* keyed snapshot fields for the CIA ([b5a6ff8](https://github.com/elektronaut/badline/commit/b5a6ff8b02026daa3ec6247ab4024d35efedb18e))
+* keyed snapshot fields for the datasette and its tape ([37a52f1](https://github.com/elektronaut/badline/commit/37a52f1018ab226a60395e1c98c6a362c0159f01))
+* keyed snapshot fields for the memories, RAM expansions and buses ([14b1a95](https://github.com/elektronaut/badline/commit/14b1a951a44c2bc23871208b9843489d4ca6963c))
+* keyed snapshot fields for the REU ([8088ac5](https://github.com/elektronaut/badline/commit/8088ac52c68667db7d6acdc6e0f0b629e165b0b3))
+* keyed snapshot fields for the SID ([b58f88d](https://github.com/elektronaut/badline/commit/b58f88d1a98346aba4dbec0dead306b3d36b32f7))
+* keyed snapshot fields for the VDC ([b894c3e](https://github.com/elektronaut/badline/commit/b894c3ef0b83988d17f03027b1831e7be3739be3))
+* keyed snapshot fields for the VIA ([52ab12c](https://github.com/elektronaut/badline/commit/52ab12cb129adedc8a3f0b7df469a1440eb72309))
+* keyed snapshot fields for the VIC-I and its sound ([a47d3e8](https://github.com/elektronaut/badline/commit/a47d3e823891e5d597141423f1675962ac266df7))
+* keyed snapshot fields for the VIC-II ([8fc8b4c](https://github.com/elektronaut/badline/commit/8fc8b4c39f8ae5cac781f51f0bbeab5134c3bc9f))
+* latch the VIC's sprite collisions when a snapshot settles ([a1c9429](https://github.com/elektronaut/badline/commit/a1c9429fefdbbc57407fb68baf057209d7163db1))
+* let a unit report its own adjustments when its snapshot loads ([3b3af19](https://github.com/elektronaut/badline/commit/3b3af19ef0d74b0a45fbea96feef107f26db12a6))
+* read Plus/4 CRT images ([450148d](https://github.com/elektronaut/badline/commit/450148db02c8057cc071f6d867707aa45a87c996))
+* read version 2 C16 tapes and time the datasette's read level ([7e78070](https://github.com/elektronaut/badline/commit/7e78070877394a4657e23699a3098f297469be05))
+* report a VIC-II line restarted from another renderer's snapshot ([6cb0607](https://github.com/elektronaut/badline/commit/6cb06075d410e59a8cd6f7d82d29757819e23e67))
+* run the 264 testbench's exitcode rows as testbench-plus4 and testbench-c16 ([862f14b](https://github.com/elektronaut/badline/commit/862f14bd474bdac92017f25a57a057cf1f42a63f))
+* run the Lorenz suite's plus4 build as lorenz-plus4 ([006efdd](https://github.com/elektronaut/badline/commit/006efddeb3a052714b99ff9b11ec18dd85cb6778))
+* save and load snapshots as BL-* modules ([25db1be](https://github.com/elektronaut/badline/commit/25db1be28817d292c314672c5401251d36d11902))
+* save snapshots at the next instruction boundary ([3f9ae3c](https://github.com/elektronaut/badline/commit/3f9ae3cf5392c194a1915801c9da4739832649e3))
+
+
+### Bug Fixes
+
+* boot C128 boot sectors on .g64 and .g71 images ([81ad184](https://github.com/elektronaut/badline/commit/81ad1842fdc66b5ddb5d2988eb699409741f376a))
+* draw the true drive's power LED, and the LEDs of a drive plugged in after start ([982c522](https://github.com/elektronaut/badline/commit/982c522c56c46d193ca5d15f49c59f221f04ad8e))
+* drive the datasette's write line from the CPU port's bit 3 ([b90c29d](https://github.com/elektronaut/badline/commit/b90c29dd758eb7867930c5f26dbd0ae510f430af))
+* let a held key go as the key it pressed across a C128 mode switch ([3a8d731](https://github.com/elektronaut/badline/commit/3a8d7313034f0b69057528b58ff247250b7e7168))
+* read the ROMs and I/O a C128 KERNAL bank maps when saving ([3e4db21](https://github.com/elektronaut/badline/commit/3e4db218959237fada950e4b65238203af10e3c6))
+* run the VIC-20's sound voices whether or not the host plays them ([13052c7](https://github.com/elektronaut/badline/commit/13052c7bbb9ca2b4ed678935ec6b88cc84bb2806))
+* take the C128's own keys in --at key= ([428047c](https://github.com/elektronaut/badline/commit/428047cc4eca55b70967048d49579840b90ea946))
+* type --at type= text on the C128's key matrix while the Z80 runs ([39d77ff](https://github.com/elektronaut/badline/commit/39d77ff29989a46c82184cd2dde03e8d470c553b))
+
 ## [0.13.0](https://github.com/elektronaut/badline/compare/v0.12.1...v0.13.0) (2026-10-11)
 
 
@@ -81,7 +153,6 @@
 * bundle the PET 64's KERNAL, 901246-01 ([9a029ec](https://github.com/elektronaut/badline/commit/9a029ecfe25c0d9a806d8858253c4c172e175b7f))
 
 
-### Miscellaneous Chores
 
 * release 0.10.1 ([9d6f6ba](https://github.com/elektronaut/badline/commit/9d6f6ba71a647f24f00a830fbc772531fbcb4d92))
 

data/CLAUDE.md

@@ -69,10 +69,10 @@ file: `core.rb` requires their members one by one.
 | rspec (`spec/`) | `bundle exec rspec` | Unit behaviour, all of `lib/` |
 | SingleStepTests 65x02 | `rake test` (100 sampled cases per opcode) | CPU, per-cycle bus traces |
 | SingleStepTests z80 | `rake test` (the first 100 cases per opcode, `Z80_SAMPLE=all` for all 1,604,000) | `Z80`: registers, flags, ports and the bus pins on every T-state |
-| Wolfgang Lorenz suite | `bin/lorenz` | CPU, CIA, interrupts |
-| VICE testbench | `bin/testbench <subtree>` | `VICII/`, `CIA/`, `interrupts/`, `CPU/`, cartridges with `--carts`, the true 1541 drive with `--drive`, the VIC-20 with `--vic20`, the C128 in C64 mode with `--c128c64`, in C128 mode with `--c128`, and its Z80 with `--c128-z80` |
+| Wolfgang Lorenz suite | `bin/lorenz` | CPU, CIA, interrupts; its plus4 build with `--plus4`: the CPU on the 264's bus, the TED's clock, DMA, timers and interrupt |
+| VICE testbench | `bin/testbench <subtree>` | `VICII/`, `CIA/`, `interrupts/`, `CPU/`, cartridges with `--carts`, the true 1541 drive with `--drive`, the VIC-20 with `--vic20`, the C128 in C64 mode with `--c128c64`, in C128 mode with `--c128`, and its Z80 with `--c128-z80`, the Plus/4 with `--plus4` and the C16 with `--c16` |
 | 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 |
+| Drive scenarios | `bin/drive_scenarios` | The true 1541 running the DOS ROM: save, format, the error channel, idle, write protect and autostart; the `plus4-*` rows on the Plus/4 and C16, with the 1541 and 1581 on their serial bus and a tape saved and loaded back on the datasette |
 | CIA offline grids | `bundle exec rspec --tag slow spec/badline/chips/cia` | CIA timers and shift register, against a bare CIA in about 2 min |
 
 The CIA offline grids replay Lorenz's `cia1ta` and `cia1tb` sweeps (about
@@ -92,6 +92,13 @@ Z80), and names the first component that differs. It builds a C64 unless
 `--family vic20` or `--family c128` (with `--mode c64|c128`) says
 otherwise. Use it for refactors and speed work.
 
+`bin/snapshot_check` checks snapshots. For each scenario (`--list`) it saves
+twice, then saves, loads and saves again, and expects the same bytes each
+time. It then runs the saved and the loaded machine side by side and names
+the first difference. `--carts` does the same for every cartridge mapper,
+and `--diff A B` compares two snapshot files module by module. Run it on any
+change to a unit's saved state.
+
 ## Driving the emulator headlessly
 
 `exe/badline-ruby <media>` opens the SDL window, which is no use for checking
@@ -153,7 +160,7 @@ worktree and owns a different set of files.
 
 - `rake vendor:checkout` fetches SingleStepTests 65x02, the Z80 sample
   and VICE-testprogs into `vendor/`
-- `bundle exec rspec`: line coverage is about 97%. `spec/spec_helper.rb`
+- `bundle exec rspec`: line coverage is about 95%. `spec/spec_helper.rb`
   fails a whole-suite run (every spec file, no filters) below 90%, while
   single-file and filtered runs skip the floor. `:slow` specs are excluded
   by default: run them with `bundle exec rspec --tag slow`
@@ -183,7 +190,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`, about 25 for `testbench-expansions`, under 1 for `testbench-vic20` and about 30 for `testbench-c128c64`. `sid` takes about 12 min. `lorenz` chains itself and takes
+`testbench-cpu`, 2 for `testbench-carts`, about 25 for `testbench-expansions`, under 1 for `testbench-vic20`, `testbench-plus4`, `testbench-c16` and `testbench-plus4-ntsc`, and about 30 for `testbench-c128c64`. `lorenz-plus4` takes about 21 min whole on the Spinel build. `rake regression:lorenz-plus4-1` to `lorenz-plus4-4` run it as four stretches, cut where `lorenz` is, and the last, through the trap tests the chain resumes past, is about half of it. `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
@@ -200,12 +207,25 @@ 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 on the Spinel
-  build, compared row by row against
-  `test/baselines/`, and every job is a required check. A row that moved
-  fails it. A pull request that changes only docs, or only a release's
-  version bump, skips the specs and suites; pushes to main always run
-  them. Re-record only those rows, in the same change:
+- A pull request's CI is the verdict, and a pull request merges on it
+  alone. It runs the specs, Rubocop, Minitest, the harness builds, the
+  Spinel checks, the native round trip, and the suites its changed files
+  can reach, on the Spinel build, compared row by row against
+  `test/baselines/`. `test/support/ci_reach.rb` maps paths to suites, and
+  a path it doesn't name runs every suite. A row that moved fails it. A
+  pull request that changes only docs, or only a release's version bump,
+  skips the specs and suites. A row that moves in a pull request's CI is
+  re-recorded in that pull request with its reason; nobody waits for
+  `suites.yml` to confirm it. A change that reaches a suite the map
+  doesn't name adds the path to `test/support/ci_reach.rb` in the same
+  pull request, and a change that adds a directory under `lib/badline/`
+  gives it a rule
+- The full suites run on main every two hours (`.github/workflows/suites.yml`).
+  Nobody waits for it, polls it or dispatches it to check a pull request.
+  Its result is a `suites` commit status and, when red, one `suites-red`
+  issue the planner owns. A red main never blocks a merge. A release
+  publishes only once its tagged commit is green
+- Re-record only the rows that moved, in the same change:
   `rake "regression:record:<suite>[filter,...]"` (quote it, because zsh
   globs the brackets). It runs only the matching tests on CRuby and
   splices their rows into the baseline, and every other row keeps its
@@ -235,7 +255,17 @@ the 6526A) for anything the interrupt register or the CIA model reaches; cartrid
 `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>`), plus `testbench-vic20` for the VIA; the VIC-20 (`vic20/`) →
-`testbench-vic20` (`bin/testbench --vic20`); the C128 (`c128.rb`, `c128/`), or
+`testbench-vic20` (`bin/testbench --vic20`); the 264 series (`plus4.rb`,
+`plus4/`), the TED (`chips/ted.rb`, `chips/ted/`) or the TIA (`chips/tia.rb`)
+→ `testbench-plus4` (`bin/testbench --plus4`) and `testbench-c16`
+(`bin/testbench --c16`), plus `testbench-plus4-ntsc`
+(`bin/testbench --plus4 --ntsc`) for anything NTSC timing or the picture
+reaches, `lorenz-plus4` (`bin/lorenz --plus4`) for
+anything the CPU's clock, the TED's DMA, its timers or its interrupt reach,
+and the `plus4-*` drive scenarios (`bin/drive_scenarios plus4`) for its
+serial bus, its media, the CPU port or the datasette.
+Its tests run one at a time as the C64's do, with
+`ruby --yjit bin/lorenz --plus4 --resume <test> --stop-after <test>`; the C128 (`c128.rb`, `c128/`), or
 the VIC-IIe, CPU or PLA code it shares with the C64 → `testbench-c128c64`
 (`bin/testbench --c128c64`); the C128's Z80, MMU or hand-over → `testbench-c128-z80` (`bin/testbench --c128-z80`) and `testbench-c128`; SID → `sid`, plus `sid-8580` for anything the 8580
 model reaches (`bin/sidtests --sid 8580`). Leave the Lorenz chain to CI,

data/CONTRIBUTING.md

@@ -91,9 +91,10 @@ bundle exec rubocop
 ## Tests and commits
 
 - Add tests for any behavior you change.
-- CI runs rubocop, the specs and every regression suite on each pull
-  request, and fails on any suite row that differs from its baseline in
-  `test/baselines/`. When a change moves rows on purpose, re-record just
+- CI runs rubocop, the specs and the regression suites a pull request's
+  changes can reach on each pull request, and fails on any suite row that
+  differs from its baseline in `test/baselines/`. Every suite runs on
+  `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.
 - Write commit messages using

data/README.md

@@ -13,7 +13,7 @@ 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. It also runs a PAL VIC-20, as
-`badline vic20`, and the C128, in C128 mode on 40 or 80 columns and in C64 mode, as `badline c128`. See [What's emulated](#whats-emulated) for the details.
+`badline vic20`, the C128, in C128 mode on 40 or 80 columns and in C64 mode, as `badline c128`, and the Plus/4, the C16 and the C116, as `badline plus4`. See [What's emulated](#whats-emulated) for the details.
 
 It comes in two builds of the same emulator:
 
@@ -69,8 +69,8 @@ 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` and [The C128](#the-c128)
-for `badline c128`.
+[The VIC-20](#the-vic-20) for `badline vic20`, [The C128](#the-c128)
+for `badline c128` and [The Plus/4](#the-plus4) for `badline plus4`.
 
 `badline-ruby` takes the same media and the same options, with the
 differences noted in the table. `--help` lists the options for either.
@@ -84,9 +84,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) |
+| `--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). On the Plus/4, `16k`, `32k` or `64k` of RAM in place of the model's own |
+| `--c1lo FILE`, `--c1hi FILE`, `--c2lo FILE`, `--c2hi FILE` | Put a raw `.bin` ROM image in one of the Plus/4's cartridge slots: cartridge 1 or 2, low (`$8000`) or high (`$C000`). 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 |
+| `--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 and the Plus/4 have models of their own: see their sections |
 | `--ntsc` | Run an NTSC C64, as `--model ntsc` does |
 | `--c64` | Start a C128 in C64 mode, holding `C=` at power-on. See [The C128](#the-c128) |
 | `--no-sound` | Don't play the SID (`badline` only, where sound is on by default) |
@@ -107,6 +108,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 snapshot, so x64sc opens it too |
 
 ```sh
 badline --unpaced --frames 12000 --true-drive disk1.d64 \
@@ -139,7 +141,8 @@ Without `--true-drive`, device 8 is no drive at all but traps on the
 KERNAL's disk routines. Loading is instant, but fast loaders and copy
 protection that run code on the drive need `--true-drive`, which puts
 an emulated 1541 there, running its own DOS at a real 1541's speed. Its
-red LED lights in the bottom right corner of the border. With
+red activity LED and green power LED light in the bottom right corner
+of the border. With
 `--true-drive`, a `.d81` goes in an emulated 1581 in place of the 1541.
 [doc/media.md](doc/media.md) has the details, and how to attach media
 from Ruby.
@@ -219,16 +222,55 @@ no host key yet: `Tab` and the arrows keep their C64 uses.
 `F11`, `F12` and the pause menu save and load the C128 in badline's own
 snapshots, and x128's `.vsf` files don't load.
 
+## The Plus/4
+
+`badline plus4` runs a PAL Plus/4, with BASIC 3.5 and the 3-plus-1
+function ROMs, and takes the same media as the C64 apart from SID tunes:
+
+```sh
+badline plus4                       # READY., in BASIC 3.5
+badline plus4 game.prg              # Load and run a program
+badline plus4 game.d64              # Mount a disk image as device 8 and load it
+badline plus4 game.tap              # Insert a tape and load it
+badline plus4 game.crt              # Attach a cartridge
+badline plus4 --model c16 game.bin  # A C16 with a cartridge's ROM image
+```
+
+`--model` picks the machine: `plus4` (the default, PAL with 64K of RAM),
+`c16` (PAL with 16K, without the function ROMs, the ACIA and the user
+port), `c116`, which is the C16 in another case, and `plus4ntsc` and
+`c16ntsc` for their NTSC versions. `--ram 16k`, `32k` or `64k` fits other
+RAM in place of the model's own.
+
+A program loads at the start of BASIC 3.5, `$1001`, and runs. A tape's
+`LOAD` reads the datasette, as the 264 KERNAL's does by default. A
+cartridge is a `.crt` or a raw `.bin` ROM image. A `.bin` goes in
+cartridge 1, its low slot for up to 16K and both slots for 32K, and
+`--c1lo`, `--c1hi`, `--c2lo` and `--c2hi` put one in the slot they name,
+as xplus4's options do:
+
+```sh
+badline plus4 --c1lo game-low.bin --c1hi game-high.bin
+```
+
+Disks go through the KERNAL traps or, with `--true-drive`, a 1541 or a
+1581 on the serial bus. There is no 1551 yet. The pause menu's Power
+page names the model and its RAM, and its Expansion port page shows the
+slots that hold a cartridge and takes them all out. `F11` and the
+Snapshots page save it as they do the others, but not for VICE.
+[Input](#input) lists its keys.
+
 ## Snapshots
 
 `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.
+saves under a name and loads any of them. Snapshots from badline 0.14.0
+on load in every later version. They use VICE's `.vsf` format: badline
+opens those x64sc saves, and x64sc opens badline's saved with `--vice`.
+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
 
@@ -269,6 +311,21 @@ types `"`. These keys have no same-named host key:
 | `+` / `*` | Keypad `+` / Keypad `*` |
 | `RESTORE` | `Page Up` |
 
+The Plus/4 and the C16 keep the C64's host keys for the keys they share,
+and put their own here:
+
+| Plus/4 | Host |
+|--------|------|
+| `ESC` | `Escape` |
+| `RUN/STOP` | `Page Down` |
+| `F1` / `F2` / `F3` | `F1` / `F2` / `F3` |
+| `HELP` | `F4`, `Insert` or `Help` |
+| `CRSR ←` / `→` / `↑` / `↓` | `Left` / `Right` / `Up` / `Down` |
+| `SHIFT` | `Left Shift` or `Right Shift` |
+
+They have no `RESTORE`, `←` or `↑` key, so `Page Up`, `` ` `` and `]`
+press nothing.
+
 `Tab` switches the keys between the C64 keyboard and the joysticks. The
 window title shows where they go, and any device plugged into a control
 port:
@@ -311,10 +368,10 @@ too.
 | 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 |
+| Expansion port | The cartridge: insert, remove, and its freeze button if it has one. On the Plus/4, the slots that hold one |
 | Ports | The device in each control port, and where the keys go |
 | Sound | Mute, and the SID's model |
-| Power | Reset, power cycle and quit, and on a C128 its model and mode |
+| Power | Reset, power cycle and quit, on a C128 its model and mode, and on a Plus/4 its model and RAM |
 
 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
@@ -354,12 +411,18 @@ program or `.sid` dropped on it opens the menu to ask first.
   port, FAST mode, the VIC-IIe with its extra keyboard lines, the 8722
   MMU, the 8563 or 8568 VDC with its 80 column display, and 128K of RAM
   (`badline c128`), and the Z80, which boots the machine.
+- **Plus/4, C16 and C116**: the 7501, the TED with its picture, sound,
+  timers and the CPU's single and double clock, 16K to 64K of RAM, ROM
+  banking with the 3-plus-1 function ROMs, the keyboard and both
+  joysticks, cartridges in both slots, the datasette and the serial bus
+  to device 8, PAL and NTSC (`badline plus4`). The ACIA's registers are
+  there but send and receive nothing.
 - **1541**: an emulated drive running its own DOS (`--true-drive`).
 - **1571**: the C128D's drive running DOS 3.0, in 1541 mode and in 1571
   mode at 2 MHz with both sides of a `.d71` or `.g71`, and fast serial
   (burst) to a C128 in C128 mode (`badline c128 --true-drive`).
 - **1581**: the 3.5" drive running its own DOS on its WD1772 and 8520,
-  reading and writing `.d81` images, on the C64, the VIC-20 and the C128
+  reading and writing `.d81` images, on the C64, the VIC-20, the C128 and the Plus/4
   (`--true-drive` with a `.d81`).
 - **Cartridges**: standard 8K, 16K and Ultimax, Simons' BASIC, Ocean,
   Fun Play / Power Play, Super Games, Epyx FastLoad, Westermann

data/doc/media.md

@@ -31,7 +31,8 @@ own DOS ROM on its own 6502 and talking to the machine over the serial
 bus. It reads `.d64` and `.g64` images, which it autostarts with the
 same `LOAD"*",8,1` and `RUN`, but not `.d71`, `.d81` or `.t64` images
 or directories. Loading runs at the speed of a real 1541, and the
-drive's red LED lights in the bottom right corner of the border.
+drive's red activity LED and green power LED light in the bottom right
+corner of the border. A 1581 flashes its power LED after an error.
 
 A `.g64` holds the disk's raw GCR, half tracks and all, so copy
 protection and fast loaders that read it work.

data/doc/pinned-behaviour.md

@@ -38,6 +38,8 @@ only catches the rows that happen to move.
 - [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)
+- [TED beam and the 7501 port](#ted-beam-and-the-7501-port)
+- [TED sound](#ted-sound)
 - [1541 serial port](#1541-serial-port)
 - [1541 disk mechanism](#1541-disk-mechanism)
 - [REU DMA](#reu-dma)
@@ -1490,6 +1492,178 @@ wasn't read.
   - Spec guard: *a step* in
     [`vic_i/sound/output_spec.rb`](../spec/badline/chips/vic_i/sound/output_spec.rb).
 
+## TED beam and the 7501 port
+
+Two places where badline knowingly differs from xplus4 r45942, which was
+run as a black box. No hardware capture settles either of them. Whoever
+finds one should start here.
+
+- The line count steps, and the raster interrupt fires, at horizontal
+  count 376, column 47 of `Chips::TED::Beam`: the datasheet's "Increment
+  Vertical Line" decode, which fits its "8 cycles before the character
+  window" for the raster interrupt. xplus4 steps the line about 3 single
+  clock cycles later, and its raster interrupt reaches the handler 2-3
+  cycles later, on display and border lines alike.
+  - Pinned by the TED datasheet in the *Plus/4 Hardware Manual*, the
+    scanned decode table on sheet 11 (page 62 of `hw.pdf`), not by a test.
+    The comparison with xplus4 used trace probes that sample `$FF1E` and
+    `$FF1D` through the lines, described with #644. The Lorenz plus4 rows
+    don't move either way.
+  - Spec guard: *the beam* in
+    [`chips/ted_spec.rb`](../spec/badline/chips/ted_spec.rb).
+- `trap10`, `trap12` and `trap14` of the Lorenz suite's plus4 build, and
+  their `ane` and `lxa` variants, pass on badline and fail (`$ff`) on
+  xplus4. They are the trap tests that put their data on the 7501's port
+  at `$00`-`$01` (`Plus4::CPUPort`: a full 8-bit direction register, P5
+  reading 1 as an input). `readme-plus4.txt` says the trap tests don't
+  work on a real 264, so its results don't decide this either.
+  - Pinned by `lorenz-plus4`'s rows for those tests. The xplus4 verdicts
+    are its exit codes with `-debugcart`, one program at a time.
+
+The TED's fetch counters (`Chips::TED::Fetches`) follow xplus4 where the
+datasheet is silent, and the datasheet where the two disagree. Each was
+checked with probes that sample `$FF1A`, `$FF1B`, `$FF1D`, `$FF1E` and
+`$FF1F` through a frame, run on badline and xplus4 r45942 alike.
+
+- The row's line (`$FF1F` bits 0-2) steps with the line count only on the
+  display window's lines, so it holds 7 from line 204 to the end of the
+  frame, and the character position reload holds 1000 there. The frame's
+  end clears both.
+- The blink counter (`$FF1F` bits 3-6) counts at horizontal count 336, the
+  datasheet's "Increment Blink", on line 256 of a PAL frame and line 228
+  of an NTSC one, the lines xplus4 counts on. The datasheet gives no line.
+- A row's last line keeps its own attributes, although the line fetches
+  the next row's, as xplus4 shows it: the attributes take hold as each
+  character's pointer is fetched.
+- The attribute line reads the row the reload will point to after its own
+  latch: 40 on from it on a row's eighth line, and the reload itself on any
+  other line, as on the first row of a frame or after a scroll change
+  stretched a row past eight lines.
+- The pointer line is the line after an attribute line, whatever the
+  scroll says by then (the datasheet's DMA timing, step 8). A line whose
+  scroll alone asks for pointers fetches none, so a scroll of 7 starts the
+  first row on line 8, not line 0.
+- The row's line runs on from the frame's first row, wrapping from 7 to
+  0, and a pointer line doesn't reset it. After a scroll change moves the
+  DMA lines, a row starts on whatever line the counter has reached.
+- Both pinned by xplus4 screenshots of scroll changes inside a text row,
+  on lines 20, 100 and 101.
+- `$FF1A` reads back both bits written to it, the datasheet's two MSBs of
+  the reload. xplus4 reads bit 1 as 0.
+- xplus4 reads the reload 40 higher for a few cycles around the line step
+  on some lines. badline reads the register as it stands.
+
+The TED's picture (`Chips::TED::Picture` and `Modes`) matches xplus4's
+screenshots pixel for pixel, by palette index, on probes for every mode,
+both column widths, both row counts, each horizontal and vertical scroll,
+the idle lines before the first row, cursor and flash, and scroll changes
+mid-frame. Where it follows xplus4 over the datasheet:
+
+- The 38-column window is pixels 39-342 of the 384, 7 in on the left and
+  9 on the right. The datasheet's counts (3 and 307 against 451 and 315)
+  would make it 8 and 8.
+- A multicolour bitmap's 01 takes the luminance of the attribute's bits
+  0-2, as the hires bitmap's 1 does. The datasheet gives it bits 4-6.
+- A register write takes hold 19 dots after its cycle starts
+  (`Picture::WRITE_DELAY`), on a character cell's boundary with no scroll.
+  That puts a raster interrupt's colour change within a cycle or two of
+  where xplus4 puts it. Code timed from `$FF1E` or a DMA stall lands 3
+  cycles later than in xplus4, the other side of the line-step difference
+  above. Pinned by probes that change `$FF15` and `$FF19` every 6 cycles,
+  timed both ways, and the spec guard *shows a register written mid-line
+  from the pixel the write lands on* in
+  [`chips/ted_spec.rb`](../spec/badline/chips/ted_spec.rb).
+- The picture's lines are scanlines as they go out. They follow the line
+  count until a write to `$FF1C`-`$FF1D` moves it, start over where the
+  count wraps to 0 at the end of the frame, and step with each line
+  otherwise. The vertical border is a flip-flop: the window opens when
+  the count reaches line 4 (8 with 24 rows) and shuts when it reaches 204
+  (200), so a count moved past line 4 leaves the frame bordered. Pinned by
+  `TED/write-scanline-coarse.prg`, which matches xplus4's screenshot pixel
+  for pixel, and the spec guards *keeps the window shut through a frame
+  whose line count jumps past line 4* and *paints the scanline after a
+  line count write on the picture's next line*.
+- A write to `$FF1E` changes nothing: xplus4 reads the same positions
+  after writes of `$00` to `$FF` on line 100, and its screenshots don't
+  move. Härsfalvi says writing back a value read at the right time
+  affects the screen, which no probe here reproduces.
+- Freezing the TED (`$FF07` bit 5) for about 100 cycles on line 100
+  leaves the picture as xplus4 shows it.
+- The blink counter's carry turns cursor and flash over together: in one
+  turn flashing characters show the background and the cursor is off, in
+  the other both show, the cursor as reverse.
+
+## TED sound
+
+No testprog checks the TED's sound, so these rules are pinned by xplus4
+(VICE 3.10) recordings, run as a black box: `-sounddev wav` at 96 kHz of
+probe programs that set the registers, the same programs run on badline
+with the sound's level sampled at the same rate, and the two compared by
+period, level and noise bits. xplus4 records the raw level, with no
+filter, so its samples read off as levels. xplus4's own source wasn't
+read.
+
+- A voice counts once every 4 cycles and toggles its output every
+  1023 - x counts, so its frequency is the clock over 8 * (1023 - x).
+  `$3FF` counts 1,024. The datasheet's formula has 1024 - x, and its PAL
+  constant, 111,840.45, is 1,000 above the clock over 8.
+  - Pinned by xplus4: voice 1 at `$000`, `$200`, `$300`, `$3F0` and `$3FF`
+    measures 108.344, 216.900, 434.653, 7389.08 and 108.239 Hz. Their
+    ratios are 1023 : 511 : 255 : 15 : 1024 to 5 digits, which 1024 - x
+    can't give, and badline's recordings measure the same within 0.005%.
+  - Spec guard: *a voice's counter* in
+    [`chips/ted/sound_spec.rb`](../spec/badline/chips/ted/sound_spec.rb).
+- `$3FE` stops a voice after its next toggle, its output high whatever
+  the phase, square wave or noise, and stops the noise's shifts.
+  - Pinned by xplus4: `$3FE` written while voice 1 plays at `$200`, after
+    21, 22, 23 and 24 frames, holds the level high each time, and noise
+    at `$3FE` holds high too. Noise held at `$3FE` for 20, 21 or 23
+    frames plays on with the same bits once it leaves, one shift on from
+    where it would be if the pending toggle were dropped.
+  - Spec guard: *$3FE* in
+    [`chips/ted/sound_spec.rb`](../spec/badline/chips/ted/sound_spec.rb).
+- The noise is an 8-bit shift register that shifts at each of voice 2's
+  toggles, taking in the XOR of bits 1, 4, 5 and 7 at bit 0. Bit 1 is the
+  output. Voice 2's counter and the noise run whether voice 2 plays the
+  square wave, the noise or nothing, and the square wins when bits 5 and
+  6 of `$FF11` are both set.
+  - Pinned by xplus4: 21,306 bits of noise at `$3D7` after a reload,
+    decoded from a recording, satisfy s(n) = s(n-2) ^ s(n-5) ^ s(n-6) ^
+    s(n-8) (Berlekamp-Massey gives linear complexity 8), with period 255,
+    starting 1100110111101110. Run back from there, the register held all
+    ones with the first two output bits already in it, so the output is
+    bit 1. Released from the reload into the square wave, into nothing or
+    into noise, voice 2 plays the same bits once switched to noise.
+    badline's recordings decode to the same first 64 bits in each of
+    these runs and in the `$3FE` ones above.
+  - Spec guard: *the noise* in
+    [`chips/ted/sound_spec.rb`](../spec/badline/chips/ted/sound_spec.rb).
+- While `$FF11` bit 7 is set, the voices that are on hold high, the noise
+  is silent and its register holds all ones. Written clear, each voice
+  starts on a whole high half-wave. With the voices held high, the volume
+  plays 9-level samples.
+  - Pinned by xplus4: voice 1, voice 2's square wave and both hold the
+    level high under bit 7, noise holds it at 0, and the half-wave after
+    the release is 221 samples at `$200`, a whole one.
+  - Spec guard: *the reload bit* in
+    [`chips/ted/sound_spec.rb`](../spec/badline/chips/ted/sound_spec.rb).
+- The level comes from the volume and how many voices are on and high.
+  One voice measures 586, 1610, 2634, 3658, 4682, 5706, 6730 and 7754 at
+  volumes 1-8, and both 1172, 3284, 5526, 7984, 10658, 13548, 16654 and
+  19976. Volumes 9-15 are 8, and volume 0 or no voice on is silent.
+  - Pinned by xplus4: those are its sample values, read off recordings
+    that step the volume with one voice and with both held high.
+  - Not pinned: that the hardware's levels are these. Nothing here says
+    why two voices come out above twice one.
+  - Spec guard: *the levels* in
+    [`chips/ted/sound_spec.rb`](../spec/badline/chips/ted/sound_spec.rb).
+- The output stage is the level averaged over each sample, then a one-pole
+  high-pass at 2.7 Hz. The Plus/4 schematic (310164, sheet 2) couples SND
+  through R10 (1K) and C18 (10 uF) into R11 (12K) and R12 (10K), with C19
+  (2,700 pF) as a low-pass at about 70 kHz, above any audio rate.
+  - Not pinned: xplus4 records no output stage, and there is no hardware
+    recording.
+
 ## 1541 serial port
 
 - The drive sees the C64's side of the serial bus a host cycle late. The