badline 0.3.0 → 0.4.1

data/doc/pinned-behaviour.md

@@ -24,7 +24,9 @@ only catches the rows that happen to move.
 - [VIC graphics pipeline](#vic-graphics-pipeline)
 - [VIC phi1 bus](#vic-phi1-bus)
 - [VIC light pen](#vic-light-pen)
+- [VIC-II 8565](#vic-ii-8565)
 - [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)
 - [SID oscillator](#sid-oscillator)
@@ -400,6 +402,14 @@ only catches the rows that happen to move.
 - Spec guard: *#collide_upto* in
   [`vic/sprites_spec.rb`](../spec/badline/vic/sprites_spec.rb). Its first
   four examples each fail on a one-pixel change.
+- $D01E and $D01F are read-only. A write, including the write-back of a
+  read-modify-write such as `LSR $D01E`, changes neither register.
+  - Pinned by `general/fuxxortest/ef2-inst4a`, which shifts each frame's
+    collision out of $D01E with `LSR`. Storing the shifted value back
+    leaves bit 0 set for the next frame, which reads as a collision one
+    pixel to the right of every real one.
+  - Spec guard: *with a collision register* in
+    [`vic/registers_spec.rb`](../spec/badline/vic/registers_spec.rb).
 
 ## VIC border and idle state
 
@@ -576,6 +586,31 @@ only catches the rows that happen to move.
     cells take their colour from the halted opcode.
   - Spec guard: *an FLI match in column 13* in
     [`vic_spec.rb`](../spec/badline/vic_spec.rb).
+- On the 6569, a match that opens display state in a g-access column, which
+  is a DMA delay out of idle state, moves that column's idle g-access from
+  `$3fff` (or `$39ff`) to `$38ff`, but only when YSCROLL is nonzero, so
+  only when the trigger line's low three bits are nonzero. The address wins over
+  ECM's `$39ff`. Nothing else enters the condition: not the column, BMM,
+  RC, VC or the previous fetch. The column is the one just before the
+  first display-state g-access. This rule is empirical and fitted to the
+  two tests below. It is the same condition the Denise emulator converged
+  on, and no hardware explanation for the YSCROLL gate is known. The
+  readme lists `$38ff` for every 6569 it measured. Among 8565s it lists
+  `$3807`, `$38c7`, `$38d7` and `$38ff`, varying from chip to chip, and no
+  testbench row pins one, so the 8565 keeps `$3fff` there.
+  `VIC::DMA_DELAY_IDLE_ADDRESS` holds the 6569's address.
+  - Pinned by `vsp-tester`, which triggers on raster `$32` with YSCROLL 2
+    and reads the address back through sprite collisions. It passes on
+    `$38ff`, `$3807`, `$38c7` or `$38d7`, and reports `$3fff` (exit `$ff`)
+    without this rule.
+  - Pinned by `colorfetchbug/main`, whose only idle trigger is on raster
+    `$30` with YSCROLL 0 and whose reference shows `$3fff` there. Without
+    the YSCROLL gate it fails by 7 px. `sequencer-bug` (YSCROLL 3) reads
+    `$38ff` and passes either way.
+  - Spec guard: *reads the idle byte at $38ff when YSCROLL is nonzero* and
+    *reads the idle byte at $3fff when YSCROLL is 0*, plus the 8565's
+    *reads the idle byte at $3fff when YSCROLL is nonzero*, in
+    [`vic_spec.rb`](../spec/badline/vic_spec.rb).
 - These rows can't be read as pixel counts. The sweep became readable by
   OCRing each reference PNG against `lib/badline/roms/character.rom` and
   matching every display row back to its offset in screen memory, so a diff
@@ -734,12 +769,125 @@ VICE x64sc's `vicii_fetch_graphics` and `draw_graphics8` for the 6569.
   reference, as `makeref` corrects it: the test fixes up the tail bytes of
   pre-R03 dumps before comparing. All five pages match, the raster-read
   pages included (see [VIC raster IRQ phase](#vic-raster-irq-phase)).
-- The 6569's offset is 2 half-pixels and the 8565's is 1, so
-  `lp-trigger/test2new`, which wants the 8565, would fail by design.
-  badline models only the 6569, and `bin/testbench` skips `vicii-new` rows.
+- The 6569's offset is 2 half-pixels and the 8565's is 1 (see
+  [VIC-II 8565](#vic-ii-8565)).
 - Pinned by `lplatency`, `lp-trigger`, and the `fldscroll` tests, which sync
   through the light pen instead of the double IRQ.
 
+## VIC-II 8565
+
+The 8565 (`VIC.new(model: :mos8565)`, `Computer.new(vic_model:
+:mos8565)`), fitted to the C64C, runs every rule above except the ones
+below. They follow VICE x64sc's model checks (`color_latency` clear), and
+each is gated on the model and was knocked out: removing it fails the rows
+named, all in `testbench-vicii-new`, and moves no 6569 row. Pixel counts
+are the row's diff with the rule removed.
+
+- **Grey dots.** Where the 6569 still shows a colour register's old value
+  on the first pixel after a write, the 8565 shows light grey
+  (`VIC::GREY_DOT`, `$f`), for the border, the background registers
+  (`VIC::ColorPatches`) and the sprite colours (`VIC#log_sprite_change`).
+  A write that leaves the value as it was shows its dot too.
+  - The background and border dot is pinned by `rmwtest` (1655 px), every
+    spritesplit row whose `$d021` staircase it crosses (60 px each) and
+    `vicii_reg_timing` (275 px, 282/289 for `-a5`/`-ff`). The sprite dot
+    by `ss-hires-color` and `ss-mc-color0`/`1`/`2` (44 px each) and
+    `vicii_reg_timing` (136 px). The same-value dot by `rmwtest` (775 px)
+    and `vicii_reg_timing` (22 px), whose read-modify-write instructions
+    store each value twice.
+  - Spec guard: the *on the 8565* group in
+    [`color_patches_spec.rb`](../spec/badline/vic/color_patches_spec.rb),
+    *shows a grey dot on the pixel before a new sprite color* in
+    [`sprites_spec.rb`](../spec/badline/vic/sprites_spec.rb) and *shows a
+    grey dot for a background write of the same color* in
+    [`vic_spec.rb`](../spec/badline/vic_spec.rb).
+- **Sprite multicolour.** `$d01c` reaches the sprite sequencers a pixel
+  sooner, 6 pixels on instead of 7, and works on the multicolour
+  flip-flop (VICE `update_sprite_mc_bits_8565`). The X match leaves the
+  flip-flop set in hi-res as well as clear after the first multicolour
+  pixel. A change flips it only when it lands between the two halves of
+  an expanded pixel, where a switch to hi-res sets it instead. A hi-res
+  pixel with the flip-flop clear sets it and loads nothing, so the latch
+  holds its last pixel.
+  - The delay is pinned by `ss-hires-mc`, `ss-mc-hires` and their `-exp`
+    twins (528/88/1452/88 px at 7). The flip-flop after the X match by
+    `ss-hires-mc`, `ss-pri`, `ss-unexp-exp-hires` (168 px each) and
+    `ss-hires-mc-exp`, `ss-pri-exp`, `ss-exp-unexp-hires` (336 px each).
+    The flip on a change by `ss-hires-mc-exp` (1364 px) and
+    `ss-mc-hires-exp` (44 px), and the hi-res hold by `ss-mc-hires` and
+    `ss-mc-hires-exp` (44 px each).
+  - Spec guard: *reaches the multicolor flip-flop six pixels on* in
+    [`sprites_spec.rb`](../spec/badline/vic/sprites_spec.rb) and the *with
+    an 8565* group of *mid-line writes* in
+    [`sprite_spec.rb`](../spec/badline/vic/sprite_spec.rb).
+- **The g-access addresses with the `$d011` of the column before**,
+  whole, instead of the 6569's hold of BMM and, on the character ROM, ECM.
+  - Pinned by `modesplit` (598 px), `vicii_reg_timing` (92, 99/106 px),
+    `fetchsplit` (180 px) and every videomode row but `videomode1` (3 to
+    16 px).
+  - Spec guard: *addresses with the $d011 of the column before* in
+    [`vic_spec.rb`](../spec/badline/vic_spec.rb).
+- **ECM and BMM take hold at the next group's pixel 0**, rising or
+  falling, where the 6569 takes them at pixel 4 as they rise and 5 or 6 as
+  they fall. MCM keeps the 6569's timing, but an MCM that falls out of
+  ECM+MCM does so on time instead of a pixel late.
+  - The pixel 0 is pinned by `modesplit` (916 px), `vicii_reg_timing` (86,
+    100/114 px) and every videomode row (6 to 13 px). The on-time MCM by
+    `videomode1` and `videomode-z` (2 px each).
+  - Spec guard: the *on the 8565* group in
+    [`graphics_shifter_spec.rb`](../spec/badline/vic/graphics_shifter_spec.rb).
+- **Out of an invalid mode into multicolour bitmap, a background pixel 0
+  is still black, and into hi-res text any pixel 0 is.** Into multicolour
+  text and ECM text it shows on time.
+  - The multicolour bitmap case is pinned by `videomode-v` and `videomode2`
+    (1 px each) and `modesplit` (92 → 124 px), whose `%00` and `%01` pairs
+    after an ECM+MCM or ECM+BMM+MCM split keep their first pixel black.
+    `videomode-y` shows a `%01` pair on time into multicolour text.
+  - The hi-res text case is empirical, pinned by the E+B row of
+    `vicii_reg_timing-a5` and `-ff` (pass and 7 px, 7 and 14 px without
+    it), which drops ECM+BMM back to text. All three `vicii_reg_timing`
+    references keep that pixel 0 black, a foreground pixel in `-a5` and
+    `-ff`. `$d021` is black there, so no reference tells a background
+    pixel 0 apart, and the rule blackens both.
+  - `videomode-w` shows ECM+BMM into ECM text on time (1 px if it goes
+    black), while `modesplit`'s section 1 keeps the same move black (48 of
+    its 92 px). The two references disagree about the same move, and the
+    videomode one is kept.
+  - Spec guard: *keeps a background pixel 0 black out of an invalid mode
+    into multicolour bitmap*, *keeps pixel 0 black out of an invalid mode
+    into hi-res text*, *shows pixel 0 on time out of an invalid mode into
+    multicolour text* and *shows pixel 0 on time out of an invalid mode into
+    ECM text* in
+    [`graphics_shifter_spec.rb`](../spec/badline/vic/graphics_shifter_spec.rb).
+- **The light pen latches one extra half-pixel**, where the 6569 adds two.
+  - Pinned by `lp-trigger/test2new`, which measures the trigger delay and
+    fails with two.
+  - Spec guard: *adds one extra half-pixel on the 8565* in
+    [`vic_spec.rb`](../spec/badline/vic_spec.rb).
+
+What the 8565 references don't settle, and so what stays as it is:
+
+- The pixel 0 of a group that leaves ECM or BMM is not consistent across
+  the references. Moving every falling edge to pixel 1 passes `modesplit`
+  but fails every videomode row but `videomode1` and all three
+  `vicii_reg_timing` rows, and the same move out of hi-res bitmap into
+  text is the new mode in `vicii_reg_timing-a5` and the old one in `-ff`.
+  The videomode readme says these delays "may depend on the type of VICII,
+  and the temperature of the chip". So `modesplit` (92 px) and
+  `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.
+- 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
+  starts.
+
 ## CIA 6526 timer pipeline
 
 - Start and stop go through two stages. A force load lands one tick after
@@ -771,13 +919,17 @@ VICE x64sc's `vicii_fetch_graphics` and `draw_graphics8` for the 6569.
   `CIA/ciavarious/cia3` K/L, `cia3a` D/H, `cia4` X, `cia8` A/C/F/J/L
   (the readme's old-versus-new CIA cells) and `CIA/cia-timer/cia-timer-oldcias`,
   and ported from VICE's `CIA_IM_TBB`.
-- The modelled revision is the **6526**, not the 6526A, matching
-  `Lorenz.d81`. That is all the `(*1)` cells of `cia1ta`/`cia1tb` measure,
-  and it is an ICR difference, not a counter one. Those cells read the ICR
-  on the very cycle the underflow flag rises, so the source bit is up while
-  IR is not: they read `$01`/`$02`, where a 6526A reads `$81`/`$82`. Counter
-  readback is identical on both revisions. `Lorenznew.d81` expects the
-  6526A and must not be mixed in.
+- Every rule in this section is the **6526**'s, the chip `CIA.new`
+  builds unless given `model: :mos6526a`, and the one `Lorenz.d81`
+  expects. That is all the `(*1)` cells of `cia1ta`/`cia1tb` measure, and
+  it is an ICR difference, not a counter one. Those cells read the ICR on
+  the very cycle the underflow flag rises, so the source bit is up while
+  IR is not: they read `$01`/`$02`, where a 6526A reads `$81`/`$82`.
+  Counter readback is identical on both revisions. `Lorenznew.d81` expects
+  the 6526A and must not be mixed into the `lorenz` chain. Its tests run
+  one at a time on a 6526A machine in `testbench-cia-new` instead. See
+  [CIA 6526A interrupt register](#cia-6526a-interrupt-register) for what
+  changes.
 - Timer B's cascade decodes CRB, not CRA. Every count source (ø2, a CNT
   edge, a cascaded timer A underflow) drives the same two-stage
   count-enable pipeline, so a timer A underflow decrements timer B two
@@ -805,6 +957,65 @@ VICE x64sc's `vicii_fetch_graphics` and `draw_graphics8` for the 6569.
   acknowledge* and *6526 timer B bug* groups guard the three ICR rules
   above, on a bare CIA.
 
+## CIA 6526A interrupt register
+
+The 6526A (`CIA.new(model: :mos6526a)`, `Computer.new(cia_model:
+:mos6526a)`), fitted to the C64C, differs from the 6526 only in its
+interrupt control register. Its timers and shift register run the rules
+above unchanged: every `testbench-cia-new` row passes on the 6526's
+timer and serial code, the long counter sweeps `cia1tanew`, `cia1tbnew`,
+`cia2tanew` and `cia2tbnew` included. VICE's `ciatimer.c` has no model
+check either. Each rule below is gated on the model in
+[`cia/interrupt_register.rb`](../lib/badline/cia/interrupt_register.rb),
+and each was knocked out: removing it fails the rows named.
+
+- **IR on the flag's cycle.** A source flag whose mask bit is set raises
+  IR on the cycle the flag rises, not a cycle later. The exception is a
+  flag that rises on the cycle after an ICR read: that one raises IR a
+  cycle later, as on the 6526 (VICE's `rdi + 1 == rclk`).
+  - The early IR is pinned by `CIA/irqdelay/irqdelay-new`,
+    `irqdelay-oneshot-new`, `irqdelay2-new`, `irqdelay-cia1-4-new` and
+    `irqdelay-cia1-oneshot-4-new`, `interrupts/branchquirk/branchquirk-new`
+    and `branchquirk-nminew`, `interrupts/cia-int/cia-int-irq-new` and
+    `cia-int-nmi-new`, `interrupts/irq-ackn-bug/cia1new` and `cia2new`,
+    `interrupts/irqnmi/irqnmi-new`, `CIA/CIA-AcountsB/cmp-b-counts-a-new`,
+    `CIA/cia-timer/cia-timer-newcias`, `CIA/timerbasics/timer_test1_new`
+    and `CIA/dd0dtest/dd0dtest`.
+  - The exception after a read is pinned by `cia-int-irq-new`,
+    `cia-int-nmi-new` and `dd0dtest` test 17, which fail when every flag
+    raises IR at once.
+- **A read sees an IR about to rise.** A read on the cycle before IR is
+  due returns IR set, and cancels the assert as on the 6526. On the 6526,
+  only a read on the next cycle sees it.
+  - Pinned by `dd0dtest` test 17. The two reads of `inc $dd0d,x` land on
+    the cycles before and of timer A's flag, so the second sees `$81` and
+    the RMW writes `$81`/`$82` back, arming timer B, whose NMI handler
+    then reads `$82`. Without the rule the second read sees `$01`, timer B
+    stays masked and no NMI comes.
+- **The acknowledge holds every bit.** A read releases the interrupt line
+  at once, but the bits it read, sources and IR alike, stay readable on
+  the next cycle, along with anything flagged since. They clear the cycle
+  after that. The 6526 holds only IR (see *Old-CIA acknowledge* above).
+  - Pinned by `dd0dtest` tests 18 and 19. Their `inc $dd0d,x` reads `$81`
+    on the flag cycle and again on the next cycle, where a 6526 reads
+    `$80`, so the RMW writes `$82` and arms timer B.
+- **A mask write raises IR a cycle later**, where the 6526 takes two.
+  - Pinned by Lorenz `imrnew`.
+- **No timer B bug.** An underflow on the cycle after an ICR read keeps
+  its flag.
+  - Pinned by `CIA/ciavarious/cia3new`, `cia3anew`, `cia4new` and
+    `cia8new` (the readme's old-versus-new cells) and
+    `CIA/cia-timer/cia-timer-newcias`.
+- Two of VICE's model checks are left out, because no testprog tells
+  them apart. VICE stops a mask write from raising IR on the cycle after
+  an ICR read, and applies the 6526's mask cancel (*Old-CIA mask cancel*
+  above) only to the 6526. Adding the first, or dropping the second for
+  the 6526A, passes every `testbench-cia-new` row, so the 6526A keeps the
+  6526's behaviour on both.
+- Spec guard: *the 6526A interrupt register* in
+  [`cia_spec.rb`](../spec/badline/cia_spec.rb), one example per rule,
+  each failing when its rule is knocked out.
+
 ## CIA serial shift register
 
 - The register counts itself empty on the 15th timer A underflow, when the
@@ -870,6 +1081,15 @@ VICE x64sc's `vicii_fetch_graphics` and `draw_graphics8` for the 6569.
     before the KERNAL does.
   - Spec guard: *when powered on* in
     [`address_bus_spec.rb`](../spec/badline/address_bus_spec.rb).
+- A write to `$00` or `$01` goes to the port, and the RAM below takes the
+  byte the VIC fetched in the phi1 half of the same cycle, as in VICE's
+  `zero_store`. Only the VIC reads that RAM.
+  - Pinned by `general/ram0001/test1`, which puts the byte in `$3fff` for
+    the idle fetch, and `general/fuxxortest/ef2-inst4a`, which uses two
+    sprite pointer fetches. Both read the RAM back through sprite
+    collisions.
+  - Spec guard: *when a program writes to the port* in
+    [`address_bus_spec.rb`](../spec/badline/address_bus_spec.rb).
 
 ## SID oscillator
 
@@ -914,6 +1134,15 @@ VICE x64sc's `vicii_fetch_graphics` and `draw_graphics8` for the 6569.
     [`sid_spec.rb`](../spec/badline/sid_spec.rb): a catch-up that
     fast-forwards across a rise carries the shift still in flight into the
     next span.
+- Setting the test bit onto noise combined with another waveform writes
+  that combination's output back into the LFSR first, from the accumulator
+  it had, before the bit clears it.
+  - Pinned by `SID/noiselfsrinit`'s `simple` and `scan` (both chips). Their
+    `$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).
+  - 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
   shift with bit 22 forced high. While the bit is held, every bit bleeds up
   to `$7fffff`: after `$950000` cycles on the 8580 (`SID/bitfade`'s
@@ -933,28 +1162,33 @@ VICE x64sc's `vicii_fetch_graphics` and `draw_graphics8` for the 6569.
     that varies with the chip's temperature (`SID/wf12nsr`'s
     `quicktest.prg` on a 6581), which nothing scored depends on.
   - Spec guard: *bleeding through a held test bit* in
-    [`sid/waveform_spec.rb`](../spec/badline/sid/waveform_spec.rb). Before it does, the old waveform's output is
+    [`sid/waveform_spec.rb`](../spec/badline/sid/waveform_spec.rb).
+- Before the bit clocks in on release, the old waveform's output is
   written back only for some waveform changes. Noise has to have been
-  combined before the release and still be selected after it. A change to
-  noise alone writes nothing back unless all four waveforms were selected
-  before. A change to pulse+noise writes nothing back, nor does a change
-  from pulse+noise to sawtooth+noise. On the 6581, trading triangle for
-  sawtooth or back writes nothing back. The rule follows libresidfp's
-  `do_writeback`. What is written is the writeback shape below, not the
-  OSC3 read. One more case is not in that rule: on the 6581, a change that
-  keeps only pulse+noise of the old waveform (`D`/`E`/`F`→`C`, `D`→`E`)
-  writes the three lowest noise lines low (`$f8`).
-  - Pinned by `SID/wb_testsuite` (the `9`/`A`/`D`/`E`→`8` rows on both
+  combined before the release and still be combined after it, so a change
+  to noise alone writes nothing back. A change to pulse+noise writes
+  nothing back, nor does a change from pulse+noise to sawtooth+noise. On
+  the 6581, trading triangle for sawtooth or back writes nothing back. The
+  rule follows libresidfp's `do_writeback`. What is written is the
+  writeback shape below, not the OSC3 read. Two more cases are not in that
+  rule. On the 6581, a change that keeps only pulse+noise of the old
+  waveform (`D`/`E`/`F`→`C`, `D`→`E`) writes the three lowest noise lines
+  low (`$f8`). On the 8580, a change from pulse+noise to all four
+  (`C`→`F`) writes every line low.
+  - Pinned by `SID/wb_testsuite` (the `9`/`A`/`D`/`E`/`F`→`8` rows on both
     chips, and the 6581's `9`↔`A`, `9`/`A`→`C` and `D`→`A` rows) and by
     `SID/noisewriteback`'s `noise_writeback_test1`. The 6581's `$f8` case
     is pinned by its `D`→`C`, `D`→`E`, `E`→`C` and `F`→`C` rows, and
     dropping it fails all four. The 8580's `C`→`A` row pins the
     pulse+noise to sawtooth+noise exception: without it the release writes
-    the 8580's `$fc` and the row fails.
-  - Known conflict: the 6581's `F`→`8` row expects no writeback, but
-    `SID/noiselfsrinit`'s `simple` and `scan` zero the register with
-    `$f8`/`$80` pairs, which needs `F`→`8` to write back. The row stays
-    failing.
+    the 8580's `$fc` and the row fails. The 8580's `C`→`F` row pins the
+    all-low case: writing the old waveform's `$fc` back makes the first read
+    `$fc`, where the row expects the `$6c` that `F`→`F` reads. Both 8580
+    samplings in `SID/wb_testsuite/samplings` read `$6c` for `C`→`F`.
+  - `F`→`8` wrote back until the test bit's rise (above) took over
+    zeroing the register for `SID/noiselfsrinit`. Every sampling in
+    `SID/wb_testsuite/samplings`, both chips, reads `F`→`8` as a plain
+    shift.
   - Spec guard: *as the test bit falls* in
     [`sid/waveform_spec.rb`](../spec/badline/sid/waveform_spec.rb).
 - A combined waveform shorts the shapers onto the lines the oscillator reads
@@ -998,11 +1232,15 @@ VICE x64sc's `vicii_fetch_graphics` and `draw_graphics8` for the 6569.
     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.
-  - Not fitted: the 6581's pulse+noise row of `SID/wf12nsr`. The program
-    never sets voice 3's pulse width, and the 6581 reference reads as if
-    the pulse was low when the test bit fell, grounding every line. From
-    power-on the width is zero and the pulse high. Forcing a width of
-    `$800` before the row makes it pass.
+  - 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.
   - 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
     [`sid/waveform_spec.rb`](../spec/badline/sid/waveform_spec.rb).
@@ -1110,9 +1348,13 @@ VICE x64sc's `vicii_fetch_graphics` and `draw_graphics8` for the 6569.
 - A tune's init and play routines must run with the ROMs banked to match
   the address they live at, following libsidplayfp's iomap: `$37` below
   `$a000`, `$36` under BASIC, `$34` in the `$d000` I/O window, `$35` under
-  the KERNAL. Restore `$01` afterwards so the caller's banking survives.
-  This entry is the rule, and it should outlive whichever code carries it.
+  the KERNAL. A routine below `$a000` gets `$36` too when the tune's image
+  reaches under BASIC, as VSID does, since it may call into that part.
+  Restore `$01` afterwards so the caller's banking survives. This entry is
+  the rule, and it should outlive whichever code carries it.
 - Derived against six OneLoad64 tunes (Galway, Tel, Gray, Dunn, Cooksey).
+  Green Beret's init sits at `$9fe3` and calls its own code at `$aaca`,
+  which forces the `$36` below `$a000`.
   `SIDFile#bank_for` is the one copy of the map: `Driver` wraps both calls
   in a `$01` save/bank/restore, and `BarePlayer#dispatch` pokes it before
   handing the CPU the stub.

data/exe/badline-ruby

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "badline/options"
+
+begin
+  options = Badline::Options.parse(ARGV)
+rescue Badline::Options::Error => e
+  warn "badline-ruby: #{e.message}"
+  warn "Try 'badline-ruby --help' for more information."
+  exit 1
+end
+
+if options.help?
+  puts options.help
+  exit
+end
+
+jit_available = defined?(RubyVM::YJIT) && !RubyVM::YJIT.enabled?
+RubyVM::YJIT.enable if options.jit? && jit_available
+
+require "badline"
+
+if options.headless?
+  begin
+    Badline::Audio::CLI.new(options, sink: Badline::Audio::SDLSink.method(:new),
+                                     console: Badline::Audio::Console.method(:new)).run
+  rescue Badline::Audio::CLI::Error => e
+    warn "badline-ruby: #{e.message}"
+    exit 1
+  rescue Interrupt
+    exit 130
+  end
+  exit
+end
+
+begin
+  require "badline/gui"
+rescue Badline::SDL::Error => e
+  warn "badline-ruby: can't open the window: #{e.message}. " \
+       "Install SDL2 with 'brew install sdl2' or 'apt install libsdl2-2.0-0'."
+  exit 1
+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?, disk: { read_only: options.read_only? })
+rescue Badline::Storage::SIDFile::FormatError, Badline::Storage::T64::FormatError,
+       Badline::Storage::TAP::FormatError, Badline::Storage::CRTFile::FormatError,
+       Badline::Cartridge::UnsupportedTypeError => e
+  warn "badline-ruby: #{options.media_path}: #{e.message}"
+  exit 1
+end
+
+application.run

data/lib/badline/address_bus.rb

@@ -49,10 +49,14 @@ module Badline
 
     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
+                :control_ports, :cartridge, :ultimax, :phi1_ultimax, :datasette, :region, :video_ram
 
-    def initialize(sid_model: :mos6581)
+    # ram_expansion fits a +60K (:plus60k) or +256K (:plus256k).
+    def initialize(sid_model: :mos6581, cia_model: :mos6526, vic_model: :mos6569, region: Region::PAL,
+                   ram_expansion: nil)
+      @region = region
       @ram = Memory.new(RAM_POWER_ON, length: 2**16, start: 0)
+      @ram_expansion = RAMExpansion.build(ram_expansion, @ram) { update_overlays! }
       @cartridge = nil
       @debug_register = nil
 
@@ -64,9 +68,9 @@ module Badline
       @joystick1 = Joystick.new
       @joystick2 = Joystick.new
       @control_ports = ControlPorts.new(keyboard: @keyboard, joystick1: @joystick1, joystick2: @joystick2)
-      @vic  = VIC.new(self)
-      @cia1 = CIA.new(start: 0xdc00, peripheral: @control_ports)
-      @cia2 = CIA.new(start: 0xdd00)
+      @vic  = VIC.new(self, model: vic_model, region:)
+      @cia1 = CIA.new(start: 0xdc00, peripheral: @control_ports, model: cia_model, region:)
+      @cia2 = CIA.new(start: 0xdd00, model: cia_model, region:)
       @control_ports.port_a_source = @cia1
       @cia1.on_port_b4_change { |high| @vic.lightpen_level(high) }
       @sid = SID.new(model: sid_model, pots: @control_ports)
@@ -97,11 +101,14 @@ module Badline
 
     def power_on!
       @ram.clear!(RAM_POWER_ON)
+      @ram_expansion.power_on!
     end
 
-    # The 6510's RES line clears the port's direction and output registers.
-    # The floating bits keep their charge.
-    def reset_port!
+    # The RES line clears the 6510 port's direction and output registers,
+    # and a RAM expansion's bank register. The port's floating bits keep
+    # their charge.
+    def reset!
+      @ram_expansion.reset!
       @port_ddr = 0x00
       @port_out = 0x00
       update_port!
@@ -124,8 +131,12 @@ module Badline
       @read_pages[addr >> 8].peek(addr)
     end
 
+    # A write to $00 or $01 goes to the port, but the RAM below is still
+    # write-enabled, and takes whatever is left on the bus: the byte the VIC
+    # fetched in the phi1 half of the cycle.
     def poke(addr, value)
       if addr < 0x02
+        @ram.poke(addr, @vic.phi1_data)
         addr.zero? ? @port_ddr = value : @port_out = value
         update_port!
       else
@@ -162,8 +173,8 @@ module Badline
     def update_overlays!
       @ultimax = @cartridge ? @cartridge.ultimax? : false
       @phi1_ultimax = @cartridge ? @cartridge.phi1_ultimax? : false
-      @read_pages.fill(@ram)
-      @write_pages.fill(@ram)
+      @ram_expansion.map(@read_pages, @write_pages)
+      @video_ram = @ram_expansion.video_ram
 
       @ultimax ? map_ultimax_pages : map_banked_pages
     end
@@ -238,6 +249,7 @@ module Badline
       }.each do |chip, pages|
         pages.each { |p| @read_pages[p] = @write_pages[p] = chip }
       end
+      @ram_expansion.map_io(@read_pages, @write_pages)
       @read_pages[0xd7] = @write_pages[0xd7] = @debug_register if @debug_register
       map_cartridge_io if @cartridge
     end

data/lib/badline/audio/aiff.rb

@@ -25,11 +25,16 @@ module Badline
       end
 
       # Sign bit, 15-bit biased exponent, then a 64-bit mantissa that keeps
-      # its leading one rather than hiding it.
+      # its leading one rather than hiding it, packed as two 32-bit halves.
       def extended(value)
         exponent = EXPONENT_BIAS + value.bit_length - 1
-        mantissa = value << (64 - value.bit_length)
-        [exponent, mantissa >> 32, mantissa & 0xffff_ffff].pack("nNN")
+        [exponent, *mantissa(value, 64 - value.bit_length)].pack("nNN")
+      end
+
+      def mantissa(value, shift)
+        return [value << (shift - 32), 0] if shift >= 32
+
+        [value >> (32 - shift), (value & ((1 << (32 - shift)) - 1)) << shift]
       end
     end
   end

data/lib/badline/audio/cli.rb

@@ -2,19 +2,24 @@
 
 module Badline
   module Audio
-    # Runs `badline-sid` once its options have parsed: picks the song and
-    # its length, then plays it or renders it to a file. Played on a
-    # terminal, the console lets the listener step between songs.
+    # Runs `badline-ruby --headless` or `--audio-out` once its options have
+    # parsed: picks the song and its length, then plays it or renders it
+    # to a file. Played on a terminal, the console lets the listener step
+    # between songs.
     class CLI
       class Error < StandardError; end
 
-      # `sink` builds the audio device for playback, given the rate to ask
-      # for and whether it has to be exact.
-      def initialize(options, out: $stdout, input: $stdin, sink: SDLSink.method(:new))
+      # Playing needs `sink`, which builds the audio device given the rate
+      # to ask for and whether it has to be exact, and, on a terminal,
+      # `console`, which builds the terminal to play on given the input and
+      # output. The front end hands them in, so the native badline can hand
+      # in its own: badline-ruby's are SDLSink and Console.
+      def initialize(options, sink: nil, console: nil, out: $stdout, input: $stdin)
         @options = options
         @out = out
         @input = input
         @sink = sink
+        @console = console
         @lengths = {}
       end
 
@@ -39,7 +44,7 @@ module Badline
       def seconds = length(song)
 
       def length(song)
-        @lengths[song] ||= @options.seconds || songlength(song) || Options::FALLBACK_SECONDS
+        @lengths[song] ||= @options.seconds || songlength(song) || @options.fallback_seconds
       end
 
       def sid_model = @options.sid_model || tune.sid_model
@@ -57,9 +62,9 @@ module Badline
       def render
         renderer = renderer(song, @options.rate)
         @out.puts describe
-        @out.puts "Rendering #{seconds}s for the #{model_name} to #{@options.output} at #{@options.rate} Hz..."
+        @out.puts "Rendering #{seconds}s for the #{model_name} to #{@options.audio_out} at #{@options.rate} Hz..."
         started = now
-        renderer.render(@options.output) { |done| progress(done) }
+        renderer.render(@options.audio_out) { |done| progress(done) }
         report(now - started)
       end
 
@@ -81,7 +86,7 @@ module Badline
       end
 
       def play_interactively(sink)
-        console = Console.new(input: @input, output: @out)
+        console = @console.call(input: @input, output: @out)
         jukebox = Jukebox.new(sink, console, songs: tune.songs, renderer: method(:renderer), length: method(:length))
         console.session do
           console.header([tune.name, tune.author, tune.released].reject(&:empty?) +
@@ -92,7 +97,7 @@ module Badline
 
       def open_sink
         @sink.call(rate: @options.rate, exact_rate: @options.rate_given?)
-      rescue SDLSink::Error => e
+      rescue Playback::DeviceError => e
         raise Error, "can't open the audio device: #{e.message}"
       end
 
@@ -124,7 +129,7 @@ module Badline
       def report(elapsed)
         @out.print "\r" unless @options.quiet?
         @out.puts format("Wrote %<path>s in %<elapsed>.1fs (%<speed>.2fx real time).",
-                         path: @options.output, elapsed:, speed: seconds / elapsed)
+                         path: @options.audio_out, elapsed:, speed: seconds / elapsed)
       end
 
       def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)