badline 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a05f51e8da6e71ad0d80cc763b3daa5d806245164be400d4736ab63de9c0006
-  data.tar.gz: 58353de430b44bec2aff4f1b401186f1684b7a1898a1f3bb903d2e43b2abbe88
+  metadata.gz: 0c6abfa72fe3a5e5f8e88efe9d53e04b4e6eaeb355550ef5ac23c47c1a0916fc
+  data.tar.gz: e15d996a7121eb244ba6ad7a8870694389f59ab8139977b2cf7b9d344f35bbe7
 SHA512:
-  metadata.gz: d58d47e49a8618017a7cf36ed5c7627a4cd3b88f0a0862497ced34d67935be5d96276d5ab2b8cccb2f07a69c9a48acc4188eeac308839a94d68c20e6ac0435b8
-  data.tar.gz: caa5504d1cd1f9ebacd1661a85b1ea39e86756d91fc2a0b276a4a416113510b836f9f0f61643712a99874c7c0e0ced5b40b35f84696e77bd36dec159c875c7c9
+  metadata.gz: d6fdecfc6b65d6b67d296fafb91e1cbdad7920e0326f146c5bae4bfed08fdd3fad9b4b38007a7f3bdb6a859ff5f1428ff7d94f573e13b68dfdb2e31c5c15e9fe
+  data.tar.gz: 6843561cca4725f4d6a93cff613ea9b0a9db78d1d45aebee9c4ba7573c49205b0162c4431d4cb78b81e12ded0e84388866017e88b94e065790934e2aaa0c4e8e

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.5.0](https://github.com/elektronaut/badline/compare/v0.4.2...v0.5.0) (2026-09-29)
+
+
+### Features
+
+* add a --true-drive option ([3df4183](https://github.com/elektronaut/badline/commit/3df4183dec298ff6b386a6b6a1c12fb04ce3cca0))
+* run the 1541 as its own machine ([9a4bafa](https://github.com/elektronaut/badline/commit/9a4bafab4c53fc7dc479a8c78527e8711d96c8cf))
+* join the C64 and the 1541 over the IEC serial bus ([7671045](https://github.com/elektronaut/badline/commit/7671045bd47fdf363eb9a57faae3c463835c7544))
+* read D64 disks through the 1541's GCR mechanism ([4c812fa](https://github.com/elektronaut/badline/commit/4c812fa25bad92c5c18219fc22c7a0ed804fe159))
+* write and format disks through the 1541 ([22a2a8b](https://github.com/elektronaut/badline/commit/22a2a8be6b9f84b9fc4d7e214603165462c7ddef))
+* read and write .g64 disk images ([884ac19](https://github.com/elektronaut/badline/commit/884ac19baeb83468444e0631c2fd5840bdffc327))
+* take .g64 images in the native badline ([8d9ab92](https://github.com/elektronaut/badline/commit/8d9ab9285555eaa0681a3113290af872a79d9f0b))
+* skip the 1541's cycles while it idles ([d8502cd](https://github.com/elektronaut/badline/commit/d8502cd589aed3ab7590cf2467b9ea57a76330fc))
+* list a mounted disk with LOAD"$",8 through the KERNAL traps ([c634e18](https://github.com/elektronaut/badline/commit/c634e18e3aa8e1b5ba3096d9b6b4ec9d41afa77b)), closes [#324](https://github.com/elektronaut/badline/issues/324)
+* emulate the REU and run the testbench REU rows ([3d5d69e](https://github.com/elektronaut/badline/commit/3d5d69e7570b9961bfd823adf00c2924c65d45e9)), closes [#232](https://github.com/elektronaut/badline/issues/232)
+* run NTSC machines and the testbench's NTSC rows ([e01ebf1](https://github.com/elektronaut/badline/commit/e01ebf17a03d606ff4a71afdb89506af962300e6)), closes [#306](https://github.com/elektronaut/badline/issues/306)
+* power RAM on in a $00/$ff pattern ([59822c3](https://github.com/elektronaut/badline/commit/59822c3dc2956cd871a6e218cac213cfb38f6bad)), closes [#319](https://github.com/elektronaut/badline/issues/319)
+* go on to the next subtune when one ends in the SID player ([0b2f2a2](https://github.com/elektronaut/badline/commit/0b2f2a209f3cb47d8117126f80217e4cc9030342)), closes [#359](https://github.com/elektronaut/badline/issues/359)
+
+
+### Bug Fixes
+
+* keep the KCS Power Cartridge's RAM apart from the C64's ([c538b43](https://github.com/elektronaut/badline/commit/c538b43e6794cbeedcc4056fb71b38598525bfa9))
+* write stdout as it goes, so errors appear in order ([42ccb02](https://github.com/elektronaut/badline/commit/42ccb026d6fe92c1ec5b67ab6f561084c5b154b2)), closes [#369](https://github.com/elektronaut/badline/issues/369)
+
 ## [0.4.2](https://github.com/elektronaut/badline/compare/v0.4.1...v0.4.2) (2026-09-28)
 
 ### Features

data/CLAUDE.md

@@ -17,6 +17,9 @@ live in subdirectories:
 - **VIC-II**: `vic.rb` and `vic/`, covering the sequencer, sprites, graphics
   modes, border and register timing
 - **CIA**: `cia.rb` and `cia/` (timers, serial), plus `time_of_day.rb`
+- **REU**: `reu.rb` and `reu/`, the RAM Expansion Unit's registers and
+  its DMA, which `Computer#cycle!` clocks in place of the CPU while it
+  holds the bus
 - **SID**: `sid.rb` and `sid/`. `audio/` plays and renders tunes for
   `badline-ruby --headless` and `--audio-out`
 - **Media and host I/O**: `storage/` (disk, tape and cartridge image
@@ -43,7 +46,7 @@ requires only the namespace file.
 | rspec (`spec/`) | `bundle exec rspec` | Unit behaviour, all of `lib/` |
 | SingleStepTests 65x02 | `rake test` (100 sampled cases per opcode) | CPU, per-cycle bus traces |
 | Wolfgang Lorenz suite | `bin/lorenz` | CPU, CIA, interrupts |
-| VICE testbench | `bin/testbench <subtree>` | `VICII/`, `CIA/`, `interrupts/`, `CPU/`, and cartridges with `--carts` |
+| VICE testbench | `bin/testbench <subtree>` | `VICII/`, `CIA/`, `interrupts/`, `CPU/`, cartridges with `--carts`, and the true 1541 drive with `--drive` |
 | VICE SID testprogs | `bin/sidtests` | SID |
 | CIA offline grids | `bundle exec rspec --tag slow spec/badline/cia` | CIA timers and shift register, against a bare CIA in about 2 min |
 
@@ -136,7 +139,7 @@ overrides that, capped by the core count, but keep the default, because
 other worktrees share the machine. Whole runs at 4 shards on an M-series
 laptop take 15 min for `testbench` (`VICII/`), 11 for `testbench-cia`, 1 for
 `testbench-interrupts`, 37 for `testbench-irqdma`, 11 for
-`testbench-cpu`, 2 for `testbench-carts` and 10 for `testbench-expansions`. `sid` takes about 12 min. `lorenz` chains itself and takes
+`testbench-cpu`, 2 for `testbench-carts` and about 25 for `testbench-expansions`. `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
@@ -179,13 +182,15 @@ the rows your change can't reach tell you nothing about it.
 
 Pick the filters from the suites your change can move: VIC → `testbench`,
 plus `testbench-vicii-new` (`bin/testbench --vicii-new`, the 8565) for
-anything the VIC model reaches;
+anything the VIC model reaches, and `testbench-ntsc` (`bin/testbench --ntsc`,
+the 6567R8 and 6567R56A) for anything a region's timing reaches;
 CPU, interrupts or timing → the matching `testbench-*` suite, plus
 `rake test` for CPU; CIA → the slow CIA specs first, then the matching
 `testbench-cia` rows, plus `testbench-cia-new` (`bin/testbench --cia-new`,
 the 6526A) for anything the interrupt register or the CIA model reaches; cartridge mappers, banking or power-on state →
-`testbench-carts`, plus `testbench-expansions` for banking; GEO-RAM, +60K
-or +256K → `testbench-expansions`; SID → `sid`, plus `sid-8580` for anything the 8580
+`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`); SID → `sid`, plus `sid-8580` for anything the 8580
 model reaches (`bin/sidtests --sid 8580`). Lorenz isn't a per-change check:
 its full chain runs nightly, and the planner assigns any row it moves. The
 exception is code whose rule in `doc/pinned-behaviour.md` names Lorenz

data/README.md

@@ -4,7 +4,7 @@
 # Badline
 
 Badline is a Commodore 64 emulator written in Ruby. It emulates a PAL
-machine one clock cycle at a time, stepping the 6510, the VIC-II, both
+or NTSC machine one clock cycle at a time, stepping the 6510, the VIC-II, both
 CIAs and the SID together, so raster timing, bad lines and sprite DMA
 are modelled at the cycle level.
 
@@ -69,7 +69,9 @@ 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 and `--sid 8580` fits the newer SID. `badline-ruby` also
+`.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.
 
@@ -100,27 +102,42 @@ slows the emulation down.
 |--------|----------|
 | `.prg`, `.p00` | Loaded into memory after boot. A program at the BASIC start (`$0801`) is `RUN`, anything else is left for you to `SYS` |
 | `.d64`, `.d71`, `.d81` | Mounted read-write as device 8, then `LOAD"*",8,1` and `RUN`. Writes go straight back to the image file. With `--read-only`, or an image the host can't write, it acts as a write-protected disk |
+| `.g64` | Put in a true 1541, which is plugged in as device 8 for it, then `LOAD"*",8,1` and `RUN`. The image holds the disk's raw GCR, half tracks and all, so copy protection and fast loaders that read it work. Tracks the drive writes go back to the image file. With `--read-only`, or an image the host can't write, it acts as a write-protected disk |
 | `.t64` | Mounted read-only as device 8 and loaded like a disk image. The files load by name, and no tape is involved |
 | `.tap` | Inserted in the datasette with PLAY pressed, then `LOAD` and `RUN`. It loads at the speed of a real tape |
 | `.crt` | The hardware types listed under [Cartridges](#whats-emulated). Other types are rejected |
 | `.sid` | PSID and RSID tunes, started through a small driver after boot |
 | A directory | Mounted read-write as device 8. It serves the `.prg` and `.p00` files in it and the contents of any `.t64`, and `SAVE` writes a new `.prg` |
 
-There is no 1541. Device 8 works by trapping the KERNAL's `LOAD` and
-`SAVE` routines and its serial bus primitives, so files open by name
-through `OPEN` and `CHRIN` as well. The command channel answers `I`,
-`B-P` and `U1` block reads, which covers loaders that read blocks
-directly. On a disk image it also takes `SAVE` (with `@0:` to replace a
-file), files opened for writing or appending, `S` to scratch, `U2` and
-`B-W` block writes, and `B-A` and `B-F`. Loaders that upload their own
-code to the drive with `M-W` and `M-E`, and copy protection that reads
-raw GCR, won't work.
+Apart from a `.g64`, which only a true drive can read, there is no 1541
+unless `--true-drive` asks for one. Device 8 works by trapping the
+KERNAL's `LOAD` and `SAVE` routines and its serial bus primitives, so
+files open by name through `OPEN` and `CHRIN` as well. `LOAD"$",8` lists
+the directory of any medium mounted there, as a 1541 does. The command
+channel answers `I`, `B-P` and `U1` block reads, which covers loaders
+that read blocks directly. On a disk image it also takes `SAVE` (with
+`@0:` to replace a file), files opened for writing or appending, `S` to
+scratch, `U2` and `B-W` block writes, and `B-A` and `B-F`. Loaders that
+upload their own code to the drive with `M-W` and `M-E`, and copy
+protection that reads raw GCR, won't work there, but do on a true
+drive.
+
+`--true-drive` puts an emulated 1541 on device 8 instead, running its
+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. `--read-only` puts the disk in write-protected. Loading
+runs at the speed of a real 1541, and the drive's red LED lights in the
+bottom right corner of the border. Both executables take it.
 
 `Badline::Media.insert_disk(computer, path)` swaps the disk image or
 directory in device 8 while the machine runs, for software that asks for
 another disk. It takes `read_only: true`, and `Badline::Media.attach`
 takes `disk: { read_only: true }`, to mount a disk image write-protected,
-as the test harnesses under `bin/` do.
+as the test harnesses under `bin/` do. A `.g64` goes in the true 1541,
+and takes out a disk mounted through the traps, so `LOAD` and `SAVE`
+reach the 1541 too. With the 1541 in device 8, a `.d64` goes in its
+drive as well.
 
 ## Playing and rendering SID tunes
 
@@ -139,16 +156,19 @@ badline-ruby --filter-chunk 1 tune.sid --audio-out out.wav   # exact filter, slo
 ```
 
 Both modes take the same options. The window's own, `--no-autostart`,
-`--sound` 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 device for 44.1 kHz and takes whatever rate it
-offers, unless `--rate` says otherwise. Ctrl-C stops it.
+`--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
+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. `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.
+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.
 
 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
@@ -236,6 +256,13 @@ while it's off.
   `Badline::Computer.new(vic_model: :mos8565)` fits the C64C's 8565
   instead, with its grey dots on colour register writes and its own
   timing for mode splits, sprite multicolour splits and the light pen.
+  `Badline::Computer.new(region: Badline::Region::NTSC)` builds an NTSC
+  machine instead: the 6567R8's 65 cycles by 263 lines at 1,022,727 Hz,
+  with its later sprite fetches and its X counter, and TOD clocks on
+  60 Hz mains. `Badline::Region::NTSC_OLD` is the first NTSC C64s'
+  6567R56A, 64 cycles by 262 lines. The stock KERNAL tells them from PAL
+  by the raster, so every region boots the same ROMs. `--ntsc` picks the
+  6567R8.
 - **CIA 1 and 2**: timers, time-of-day clocks with alarms, the serial
   shift register, interrupts, the keyboard matrix with its ghost keys,
   the control ports and the paddle multiplexer. The machine has the
@@ -246,6 +273,11 @@ while it's off.
   and the RC network on the board that removes the DC offset from the
   output. The machine has a 6581 unless a `.sid` tune asks for an 8580
   in its header, and `--sid 6581` or `--sid 8580` overrides either.
+- **REU**: the 1700, 1764 and 1750 RAM Expansion Units, and the bigger
+  units up to 16M built on the same REC chip, with DMA timed against the
+  VIC's bad lines and sprites. `--reu SIZE` plugs one in, and
+  `Badline::Computer.new(reu: 512)` does the same from Ruby. An
+  REU beside a cartridge loses I/O 2 to the cartridge.
 - **Datasette**: `.tap` playback into CIA 1's FLAG line, with the motor
   and sense lines on the 6510 port.
 - **Cartridges**: standard 8K, 16K and Ultimax, Simons' BASIC, Ocean,
@@ -276,11 +308,10 @@ Known gaps:
 - `badline-ruby` runs below real time, so its live audio stutters.
   `badline` plays smoothly, and so do PSID tunes under
   `badline-ruby --headless`.
-- No drive emulation, so fast loaders and anything else that runs code
+- Without `--true-drive`, fast loaders and anything else that runs code
   on the drive won't work (see [Media](#media)). The command channel
-  doesn't rename, copy, format or validate disks, and `LOAD"$",8`
-  doesn't list a disk's directory yet.
-- No NTSC machine and no REU.
+  doesn't rename, copy, format or validate disks.
+- No PAL-N (Drean) machine.
 - The emulator window has no freeze button yet, so a freezer cartridge
   runs its menu but can't freeze a program.
 

data/doc/pinned-behaviour.md

@@ -25,10 +25,15 @@ only catches the rows that happen to move.
 - [VIC phi1 bus](#vic-phi1-bus)
 - [VIC light pen](#vic-light-pen)
 - [VIC-II 8565](#vic-ii-8565)
+- [VIC-II NTSC](#vic-ii-ntsc)
 - [CIA 6526 timer pipeline](#cia-6526-timer-pipeline)
 - [CIA 6526A interrupt register](#cia-6526a-interrupt-register)
 - [CIA serial shift register](#cia-serial-shift-register)
 - [6510 I/O port](#6510-io-port)
+- [RAM power-on pattern](#ram-power-on-pattern)
+- [1541 serial port](#1541-serial-port)
+- [1541 disk mechanism](#1541-disk-mechanism)
+- [REU DMA](#reu-dma)
 - [SID oscillator](#sid-oscillator)
 - [SID register writes](#sid-register-writes)
 - [SID data bus](#sid-data-bus)
@@ -888,6 +893,46 @@ What the 8565 references don't settle, and so what stays as it is:
   6569's idle access, without the 6569's `$38ff` read where a DMA delay
   starts.
 
+## VIC-II NTSC
+
+The 6567R8 (`Region::NTSC`) and the 6567R56A (`Region::NTSC_OLD`) run
+every VIC rule above, on a line of 65 or 64 cycles, except where the
+region moves the sprites. The positions live in `Region::Profile` and
+`VIC::Sprite::Timing`.
+
+- **Sprite fetches.** Sprite 0's p-access runs in cycle 59 instead of
+  58, and everything that hangs off the fetches moves with it: the BA
+  windows (`VIC#layout_columns`), the DMA compares (columns 54 and 55
+  instead of 53 and 54), the phi1 accesses (`VIC#phi1_address`, where the
+  6567R8 idles in cycle 10), the column whose BA a late DMA start misses
+  (`Sprite::Timing#ba_column`), the reload pixels
+  (`Sprite::Timing#reload_x`) and the idle-bus row of sprites 3-7
+  (`Sprite::InternalBus#row`). On the 6567R8 sprite 3's fetch then falls
+  in the last two cycles of the line, so it reloads with the next line's
+  row as sprites 0-2 do. The expansion flip-flop still toggles in column
+  54.
+  - Pinned by `spritesteal_ntsc` and `_ntscold`, `spritex/testsuite_ntsc`
+    and `_ntscold`, `phi1timing_ntsc` and `_ntscold`, and
+    `spriteenable1_ntsc` and `2_ntsc` and their `_ntscold` twins (235 and
+    458 px), all in `testbench-ntsc`: with sprite 0 back in cycle 58 each
+    of them fails, and every other row of the sprite, phi1, dmadelay, vsp
+    and screenpos subsets passes as before.
+  - Spec guard: *sprite DMA cycle stealing on NTSC* and *#phi1_data on
+    NTSC* in [`vic_spec.rb`](../spec/badline/vic_spec.rb), and
+    [`timing_spec.rb`](../spec/badline/vic/sprite/timing_spec.rb).
+- **Display compare and X counter.** The 6567R8 turns a sprite's display
+  on and off in cycle 59 (`sprite_display_cycle`), where the 6567R56A
+  keeps the 6569's cycle 58. Its X counter holds for 8 pixels
+  (`x_hold`), reading $184-$187 three times, so it reaches $1ff on a
+  520-pixel line. The 6567R56A's runs straight through 512 pixels.
+  Neither is pinned yet: moving the 6567R8's display compare to 58, the
+  6567R56A's to 59, or running the 6567R8's counter straight through and
+  wrapping it at 512 fails no row of those subsets.
+- **Blanking and crop.** The blanked lines are the ones VICE's NTSC view
+  leaves out, 12-27 on the 6567R8 and 13-27 on the 6567R56A, so the
+  `testbench-ntsc` screenshots, VICE's 247 lines from line 28 running on
+  into the next frame, see every line they show painted.
+
 ## CIA 6526 timer pipeline
 
 - Start and stop go through two stages. A force load lands one tick after
@@ -1091,6 +1136,182 @@ and each was knocked out: removing it fails the rows named.
   - Spec guard: *when a program writes to the port* in
     [`address_bus_spec.rb`](../spec/badline/address_bus_spec.rb).
 
+## RAM power-on pattern
+
+- RAM powers on in runs of `$00,$00,$ff,$ff,$ff,$ff,$00,$00`, inverted in
+  `$4000-$7fff` and `$c000-$ffff`, on every power cycle. The RAM under
+  `$00`/`$01` follows the pattern like the rest. It is the pattern of a
+  C64C (ASSY 250469 R4) in `C64/raminitpattern/readme.txt`
+  (`-raminitstartvalue 0 -raminitvalueinvert 4 -raminitvalueoffset 2
+  -raminitpatterninvert 16384 -raminitpatterninvertvalue 255`), without
+  that machine's occasional random bytes. `AddressBus::RAM_POWER_ON`
+  holds it.
+  - Pinned by `C64/raminitpattern`: `cyberloadtest` fails when
+    `$f379-$f478` holds one value, `darkstarbbstest` when the first ten
+    bytes of one of the pages `$4000`, `$5000` … `$9000` do, `platoontest`
+    when `$1000-$10ff` holds five equal bytes in a row and 140 or more
+    bytes of one value, and `typicaltest`
+    checks `$3fff` against a table of values the Typical demo survives.
+    All-`$00` fails the first three, and each other pattern the readme
+    lists fails at least one of the four.
+  - Spec guard: *RAM at power-on* in
+    [`address_bus_spec.rb`](../spec/badline/address_bus_spec.rb).
+- The RAM expansions' extra banks still power on at `$00`.
+
+## 1541 serial port
+
+- The drive sees the C64's side of the serial bus a host cycle late. The
+  drive runs after the C64 in each host cycle, so `SerialPort` reads the
+  C64's lines as `latch_host` took them at the end of the previous host
+  cycle, both on VIA 1's port B (DATA IN, CLK IN, ATN IN) and on CA1,
+  which ATN reaches. A CIA 2 write lands for the drive's cycles of the
+  next host cycle, the way the CIA's pins change at the end of the cycle
+  that writes them. The drive's own lines, and what the C64 reads back,
+  stay live.
+- The 2-bit loader that uploads the drive tests' code times its transfer
+  from an ATN edge, and seeing that edge a cycle early loses the first bit
+  pair.
+- Pinned by the `testbench-drive` rows below. Each was checked by having
+  the drive read the live lines (`@bus.atn_low?` and `@bus.low_lines`
+  with no argument) and rerunning the rows:
+  - Fail without the latch (`exit=$ff`): `drive/selftest`,
+    `drive/diskid/diskid1`, `drive/interrupts/timera`, all six
+    `drive/scanner` rows, both `drive/openbus` rows and
+    `drive/viavarious/via1`, `via3a` and `via10`.
+  - Pass either way: `drive/defaults`, `drive/rpm/rpm1` and `rpm2`,
+    `drive/skew/skew1` and `drive/iecdelay/iec-bus-delay-auto`.
+- Spec guard: *sees an assertion from the host cycle after the one it
+  lands in* and *shows the drive the C64's CLK from the host cycle after
+  the write* in [`iec_bus_spec.rb`](../spec/badline/iec_bus_spec.rb).
+
+## 1541 disk mechanism
+
+- A step out against the stop at track 1 slips the stepper's phases: the
+  head stays on half track 2, and the phase that pulled it outwards
+  becomes that half track's. The DOS's bump steps out 92 half tracks, a
+  whole number of phase turns, and then takes the phase it ends on as
+  track 1's: `N:` formats track 1 there and steps in two phases a track.
+  With each half track holding its own phase from power-on instead, the
+  bump ended two half tracks off track 1's phase, the first step in
+  pulled the head against the stop, and the DOS wrote track 2 over track
+  1 and every later track one track out, at half track 2n - 2.
+  - The DOS reads its own format back either way, since each header
+    carries the track the DOS thought it was on: `drive/format` passes
+    without the slip, and so doesn't pin it. Reading the disk back into a
+    D64 does, since each header has to name the track the image holds it
+    on.
+  - Spec guard: *steps in from the stop with the first phase after the
+    bump* in
+    [`mechanism_spec.rb`](../spec/badline/drive1541/mechanism_spec.rb),
+    and *lists it through the traps* (`:slow`) in
+    [`drive1541_spec.rb`](../spec/badline/drive1541_spec.rb).
+- The disk turns at 300 rpm whatever bit rate VIA 2's PB5-6 select: a
+  turn is 200,000 drive cycles over every track and over a half track
+  without data. Each track's bits pass under the head at the rate they
+  were written at: spread evenly over the turn, so a track as long as a
+  turn holds at its zone's rate passes at that rate and a `.g64` track
+  longer or shorter than that passes faster or slower, and a `.g64`
+  speed map widens each byte's cells by its zone. The read clock runs at
+  the selected rate and each flux transition brings it back into step,
+  so a track read in its own zone reads clean and one read far enough
+  off garbles (zone 0 against zone 3). With the rate selected turning
+  the disk instead, a zone 3 track read in zone 0 read clean and took
+  246 ms a turn, and a `.g64` track turned in its length of bytes.
+  - Pinned by `drive/rpm` (`rpm1`, `rpm2` and `rpm3`, on the `.d64` and
+    the `.g64`): each times a turn and passes within 297 to 303 rpm.
+  - Pinned by `drive/skew/skew2`, on a `.g64` whose tracks all start
+    sector 0 at the same angle: the head keeps the disk's angle across
+    the tracks and half tracks it steps over only while every track
+    turns in the same time.
+  - Pinned by `drive/scanner` (all six programs, on the `.d64` and the
+    `.g64`), which reads every track and each track's error map.
+  - Spec guard: the *at 300 rpm* examples and *turns once in 200 ms* in
+    [`mechanism_spec.rb`](../spec/badline/drive1541/mechanism_spec.rb),
+    and *#cell_at* in
+    [`track_spec.rb`](../spec/badline/drive1541/track_spec.rb).
+- A write lays its bits one to a cell from the cell under the head. A
+  half track without data gets a blank track first, as long as a turn at
+  the rate the drive writes at, not at the rate of the track's own zone,
+  and a track written in another zone is laid out again as a turn at the
+  rate written, its flux kept at its angle to within a cell. A track
+  written in the selected zone keeps its length, so a `.g64` track
+  longer or shorter than a turn keeps the sectors around the one written.
+  - Pinned by `drive/rpm/rpm3`, which writes track 36, past a 35-track
+    D64, at the zone 2 rate the DOS leaves selected there: a turn and a
+    half of SYNC and five bytes, and times a turn by reading it back.
+    With a zone 0 track of 6250 bytes a turn took 175,001 cycles
+    (342.86 rpm, `exit=$ff`). With the last byte's leftover part of a
+    cell widening the track's last cell, instead of the cells spread
+    evenly over the turn, the SYNC broke there and the turn read as
+    194,728 cycles (`exit=$ff`).
+  - Spec guard: *gives a half track a blank track 7142 bytes around,
+    written in zone 2* in
+    [`disk_spec.rb`](../spec/badline/drive1541/disk_spec.rb), and *lays
+    a track written in another zone out again as a turn at the zone
+    written* and *writes a turn of SYNC that reads back without a break*
+    in [`mechanism_spec.rb`](../spec/badline/drive1541/mechanism_spec.rb).
+- A disk made from a `.d64` starts sector 0 of each track where the DOS's
+  `N:` leaves it: track 1 at the index angle, and each track after it
+  round from the last by the skew `N:` leaves in its zone, 0.6869 of a
+  turn in zone 3, 0.8915 in zone 2, 0.0897 in zone 1 and 0.2916 in zone
+  0. Those are measured off a disk formatted here with `N:`.
+  - Pinned by `drive/skew/skew1`, which expects a `.d64` to read with
+    the skew a DOS format leaves. With every track starting sector 0 at
+    the same angle it read `kernal format, tracks are aligned`
+    (`exit=$ff`).
+  - The skew moves which block the DOS meets first on each track, and
+    `drive/scanner`'s three error-map rows (`scanner35e`, `40e`, `42e`)
+    read track 4's error 22 only when the header comes first. They pass
+    with this skew at 300 rpm. With the rate selected turning the disk,
+    the same skew made them read track 4 as error 27, which is why
+    `skew1` failed before.
+  - Spec guard: *starts sector 0 of track N where the DOS's N: leaves
+    it* in [`disk_spec.rb`](../spec/badline/drive1541/disk_spec.rb).
+- The CPU sees BYTE READY on SO a cycle late: BYTE READY sets V for the
+  next cycle's instruction step, not the one in the cycle it falls in.
+  - Pinned by `drive/hls-protection`. Its drive code counts the bytes
+    from one SYNC mark to the next, reading `$1C00` for SYNC once per
+    byte, 20 to 22 cycles after each BYTE READY with the delay (19 to 21
+    without). The SYNC marks it has to find follow an `$AF`, whose four
+    trailing 1 bits make SYNC six bits, 19 cycles in zone 3, after its
+    BYTE READY; the ones it has to miss follow a `$2B`, eight bits on.
+    With V set in the same cycle, the read sometimes came a cycle
+    before SYNC, depending on the bit phase: on track 1 two of the 16
+    counts read `$02C8`, two sectors' worth, and the testbench row failed
+    (`exit=$ff`) on track 17. With the delay, tracks 1, 5, 10, 12 and 17
+    (the 4-cycle loop) and 18, 20 and 24 (the 6-cycle loop) all read as
+    the test expects.
+  - Spec guard: *sets V through SO while CA2 is high, a cycle after BYTE
+    READY* in
+    [`mechanism_spec.rb`](../spec/badline/drive1541/mechanism_spec.rb).
+
+## REU DMA
+
+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`.
+- 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 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.
+
 ## SID oscillator
 
 - The phase accumulator powers on at `$555555` (all bits high, with the odd

data/exe/badline-ruby

@@ -6,6 +6,8 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require "badline/options"
 
+$stdout.sync = true
+
 begin
   options = Badline::Options.parse(ARGV)
 rescue Badline::Options::Error => e
@@ -47,12 +49,13 @@ end
 
 begin
   application = Badline::GUI::Application.new(media_path: options.media_path, autostart: options.autostart?,
-                                              song: options.song, sid_model: options.sid_model,
-                                              sound: options.sound?, verbose: options.verbose?,
+                                              song: options.song, sound: options.sound?, verbose: options.verbose?,
+                                              machine: { sid_model: options.sid_model, reu: options.reu,
+                                                         true_drive: options.true_drive?, ntsc: options.ntsc? },
                                               disk: { read_only: options.read_only? })
-rescue Badline::Storage::SIDFile::FormatError, Badline::Storage::T64::FormatError,
+rescue Badline::Media::TrueDrive::Error, Badline::Storage::SIDFile::FormatError, Badline::Storage::T64::FormatError,
        Badline::Storage::TAP::FormatError, Badline::Storage::CRTFile::FormatError,
-       Badline::Cartridge::UnsupportedTypeError => e
+       Badline::Storage::G64Image::FormatError, Badline::Cartridge::UnsupportedTypeError => e
   warn "badline-ruby: #{options.media_path}: #{e.message}"
   exit 1
 end

data/lib/badline/address_bus/ultimax_pages.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Badline
+  class AddressBus
+    # The page tables of an Ultimax cartridge, which AddressBus lays out
+    # in place of the $01 banking while the cartridge holds GAME low and
+    # EXROM high.
+    module UltimaxPages
+      private
+
+      # Ultimax cartridges ignore the $01 lines: 4K of RAM, ROML/ROMH windows,
+      # I/O always visible and open address space everywhere else. The ROML
+      # and ROMH selects fire on writes as well, so cartridge RAM or flash in
+      # either window takes the writes there.
+      def map_ultimax_pages
+        @read_pages.fill(@open_bus, 0x10, 0xf0)
+        @write_pages.fill(@open_bus, 0x10, 0xf0)
+        @read_pages.fill(@cartridge.roml, 0x80, 0x20) if @cartridge.roml
+        map_ultimax_writes(@cartridge.roml, 0x80)
+        @read_pages.fill(@cartridge.romh, 0xe0, 0x20) if @cartridge.romh
+        map_ultimax_writes(@cartridge.romh, 0xe0)
+        map_ultimax_a000
+        map_io_pages
+      end
+
+      def map_ultimax_writes(bank, first_page)
+        @write_pages.fill(bank, first_page, 0x20) if bank.respond_to?(:poke)
+      end
+
+      def map_ultimax_a000
+        return unless (window = @cartridge.ultimax_a000)
+
+        @read_pages.fill(window, 0xa0, 0x20)
+        @write_pages.fill(window, 0xa0, 0x20)
+      end
+    end
+  end
+end

data/lib/badline/address_bus.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "badline/address_bus/ultimax_pages"
+
 module Badline
   # Memory layout:
   #
@@ -28,6 +30,7 @@ module Badline
   # 0xE000-0xFFFF - KERNAL ROM / Cartridge ROM (high) - 8kb
   class AddressBus
     include Addressable
+    include UltimaxPages
 
     # I/O 1 and 2, and the Ultimax holes, with nothing on the bus. A read
     # picks up the byte the VIC fetched in the preceding phi1 half-cycle,
@@ -45,11 +48,15 @@ module Badline
     PORT_FLOATING = 0b1100_1000
     TAPE_SENSE    = 0b0001_0000
 
-    RAM_POWER_ON = [0xff, 0x07].freeze
+    # RAM powers on in runs of $00 $00 $FF $FF $FF $FF $00 $00, inverted in
+    # the second and fourth 16K: a C64C (ASSY 250469 R4) from
+    # C64/raminitpattern/readme.txt, without its occasional random bytes.
+    # See doc/pinned-behaviour.md.
+    RAM_POWER_ON = Array.new(2**16) { |addr| (((addr + 2) / 4) ^ (addr / 0x4000)).odd? ? 0xff : 0x00 }.freeze
 
     attr_reader :io_port, :ram, :basic_rom, :character_rom, :kernal_rom,
                 :vic, :sid, :color_ram, :cia1, :cia2, :keyboard, :joystick1, :joystick2,
-                :control_ports, :cartridge, :ultimax, :phi1_ultimax, :datasette, :region, :video_ram
+                :control_ports, :cartridge, :ultimax, :phi1_ultimax, :datasette, :region, :video_ram, :reu
 
     # ram_expansion fits a +60K (:plus60k) or +256K (:plus256k).
     def initialize(sid_model: :mos6581, cia_model: :mos6526, vic_model: :mos6569, region: Region::PAL,
@@ -57,7 +64,7 @@ module Badline
       @region = region
       @ram = Memory.new(RAM_POWER_ON, length: 2**16, start: 0)
       @ram_expansion = RAMExpansion.build(ram_expansion, @ram) { update_overlays! }
-      @cartridge = nil
+      @cartridge = @reu = nil
       @debug_register = nil
 
       @basic_rom     = ROM.load("basic.rom",     0xa000)
@@ -99,6 +106,13 @@ module Badline
       update_overlays!
     end
 
+    # An REU takes I/O 2 unless a cartridge claims it, and watches writes
+    # to $FF00 for the one that starts an armed transfer.
+    def attach_reu(reu)
+      @reu = reu
+      update_overlays!
+    end
+
     def power_on!
       @ram.clear!(RAM_POWER_ON)
       @ram_expansion.power_on!
@@ -177,6 +191,7 @@ module Badline
       @video_ram = @ram_expansion.video_ram
 
       @ultimax ? map_ultimax_pages : map_banked_pages
+      @write_pages[0xff] = @reu.trigger.wrap(@write_pages[0xff]) if @reu
     end
 
     def map_banked_pages
@@ -216,32 +231,6 @@ module Badline
       @write_pages.fill(bank, first_page, 0x20) if bank.is_a?(Cartridge::RAMBank)
     end
 
-    # Ultimax cartridges ignore the $01 lines: 4K of RAM, ROML/ROMH windows,
-    # I/O always visible and open address space everywhere else. The ROML
-    # and ROMH selects fire on writes as well, so cartridge RAM or flash in
-    # either window takes the writes there.
-    def map_ultimax_pages
-      @read_pages.fill(@open_bus, 0x10, 0xf0)
-      @write_pages.fill(@open_bus, 0x10, 0xf0)
-      @read_pages.fill(@cartridge.roml, 0x80, 0x20) if @cartridge.roml
-      map_ultimax_writes(@cartridge.roml, 0x80)
-      @read_pages.fill(@cartridge.romh, 0xe0, 0x20) if @cartridge.romh
-      map_ultimax_writes(@cartridge.romh, 0xe0)
-      map_ultimax_a000
-      map_io_pages
-    end
-
-    def map_ultimax_writes(bank, first_page)
-      @write_pages.fill(bank, first_page, 0x20) if bank.respond_to?(:poke)
-    end
-
-    def map_ultimax_a000
-      return unless (window = @cartridge.ultimax_a000)
-
-      @read_pages.fill(window, 0xa0, 0x20)
-      @write_pages.fill(window, 0xa0, 0x20)
-    end
-
     def map_io_pages
       {
         vic => 0xd0..0xd3, sid => 0xd4..0xd7, color_ram => 0xd8..0xdb,
@@ -251,6 +240,7 @@ module Badline
       end
       @ram_expansion.map_io(@read_pages, @write_pages)
       @read_pages[0xd7] = @write_pages[0xd7] = @debug_register if @debug_register
+      @read_pages[0xdf] = @write_pages[0xdf] = @reu if @reu
       map_cartridge_io if @cartridge
     end