badline 0.4.2 → 0.5.1

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
 

data/lib/badline/audio/jukebox.rb

@@ -3,8 +3,9 @@
 module Badline
   module Audio
     # Plays a tune's songs interactively: the console's keys step between
-    # songs, pause and quit, and the status line follows along. It stops
-    # when a song ends, on q, or on Ctrl-C.
+    # songs, pause and quit, and the status line follows along. A song that
+    # plays to its end moves on to the next one. It stops after the last
+    # song, on q, or on Ctrl-C.
     #
     # `renderer` builds the renderer for a song at the sink's rate, and
     # `length` gives a song's length in seconds.
@@ -23,7 +24,7 @@ module Badline
         loop do
           @action = nil
           result = play(song)
-          song = following(song)
+          song = following(song, result)
           return result unless song
         end
       end
@@ -43,10 +44,11 @@ module Badline
         end
       end
 
-      def following(song)
+      def following(song, result)
         case @action
         when :next then song + 1
         when :previous then song - 1
+        else song + 1 if result == :finished && song < @songs
         end
       end
 

data/lib/badline/audio/machine_player.rb

@@ -5,7 +5,9 @@ module Badline
     # Runs a tune on the whole machine, for the RSID tunes that install their
     # own interrupts and expect a booted C64 underneath. The tune goes in
     # the way `Media` puts it in: BASIC SYSes the driver stub, or RUNs a
-    # BASIC tune. Rendering starts when the CPU gets there.
+    # BASIC tune. Rendering starts when the CPU gets there. The machine is
+    # PAL whatever the tune asks for, and the frames and the clock follow
+    # its region.
     class MachinePlayer
       FRAME_CYCLES = BarePlayer::FRAME_CYCLES
 
@@ -16,6 +18,8 @@ module Badline
         @tune = tune
         @song = song || tune.start_song
         @computer = Computer.new(sid_model:)
+        region = @computer.region
+        @frame_cycles = region.cycles_per_line * region.lines_per_frame
         @injected = false
         @started = false
       end
@@ -28,13 +32,13 @@ module Badline
 
       def sid = @computer.sid
 
-      # The machine is PAL whatever the tune asks for.
-      def clock_hz = TimeOfDay::CLOCK_HZ
+      def clock_hz = @computer.region.clock_hz
 
-      # Advances one PAL frame, or `budget` cycles if that is shorter, then
-      # yields whatever the SID recorded over it. Returns the cycles advanced.
+      # Advances one frame of the machine, or `budget` cycles if that is
+      # shorter, then yields whatever the SID recorded over it. Returns the
+      # cycles advanced.
       def frame(budget, &)
-        cycles = [budget, FRAME_CYCLES].min
+        cycles = [budget, @frame_cycles].min
         cycles.times { @computer.cycle! }
         sid.drain_samples.each(&)
         cycles

data/lib/badline/cartridge/kcs_power.rb

@@ -31,7 +31,7 @@ module Badline
         elsif addr.anybits?(0x80)
           (@exrom << 7) | (@game << 6) | (open_bus(addr) & 0x3f)
         else
-          @ram[addr & 0x7f]
+          @io_ram[addr & 0x7f]
         end
       end
 
@@ -39,7 +39,7 @@ module Badline
         if addr < 0xdf00
           switch(addr.anybits?(0x02) ? :ultimax : :rom16k)
         elsif addr.nobits?(0x80)
-          @ram[addr & 0x7f] = value
+          @io_ram[addr & 0x7f] = value
         end
       end
 
@@ -64,7 +64,7 @@ module Badline
         roml, romh = banks_from(chips)
         @roml = roml.first || EMPTY_BANK
         @romh = romh.first || EMPTY_BANK
-        @ram = Array.new(0x80, 0xff)
+        @io_ram = Array.new(0x80, 0xff)
         reset
       end
     end

data/lib/badline/cia.rb

@@ -13,7 +13,11 @@ module Badline
     # C64C, which differs from it only in its interrupt control register.
     MODELS = %i[mos6526 mos6526a].freeze
 
-    attr_reader :start, :control_a, :control_b, :peripheral, :serial, :model
+    attr_reader :start, :control_a, :control_b, :serial, :model
+
+    # What's on the ports outside the chip. It pulls port lines low through
+    # read_a and read_b, and on CIA 1 drives PB4 through port_b4_high?.
+    attr_accessor :peripheral
 
     def interrupt_status = @icr.status
 
@@ -58,6 +62,7 @@ module Badline
 
       @peripheral = peripheral
       @port_b4_handler = nil
+      @port_a_handler = nil
       @port_b4_high = true
       reset!
     end
@@ -83,6 +88,7 @@ module Badline
       @ta = Timer.new(@control_a)
       @tb = Timer.new(@control_b)
       @serial = Serial.new(@control_a)
+      @port_a_handler&.call
     end
 
     # Register a change handler on the PB4 line. On CIA 1, this feeds the
@@ -91,6 +97,13 @@ module Badline
       @port_b4_handler = handler
     end
 
+    # Register a handler for writes that can move port A's lines: to the
+    # data register or DDR, and the reset. On CIA 2, this tells the drives
+    # on the serial bus that the C64 may have moved a line.
+    def on_port_a_write(&handler)
+      @port_a_handler = handler
+    end
+
     # A falling edge on the FLAG pin. On CIA 1 the datasette's tape read
     # line drives it, on CIA 2 the serial bus SRQ.
     def flag! = raise_interrupt(:flag)
@@ -149,9 +162,9 @@ module Badline
 
     def poke(addr, value)
       case offset_of(addr) & 0x0f
-      when 0x00 then @data_port_a = value
+      when 0x00 then update_port_a { @data_port_a = value }
       when 0x01 then update_port_b { @data_port_b = value }
-      when 0x02 then @data_dir_a = value
+      when 0x02 then update_port_a { @data_dir_a = value }
       when 0x03 then update_port_b { @data_dir_b = value }
       when 0x04 then @ta.write_latch_low(value)
       when 0x05 then @ta.write_latch_high(value)
@@ -170,6 +183,11 @@ module Badline
 
     private
 
+    def update_port_a
+      yield
+      @port_a_handler&.call
+    end
+
     def update_port_b
       yield
       @port_b4_driven_high = driven_lines(@data_port_b, @data_dir_b).anybits?(0x10)

data/lib/badline/computer.rb

@@ -5,7 +5,7 @@ module Badline
     include IntegerHelper
     include KeyboardBuffer
 
-    attr_reader :address_bus, :cpu, :cycles
+    attr_reader :address_bus, :cpu, :cycles, :drive1541
 
     def region = address_bus.region
 
@@ -33,9 +33,12 @@ module Badline
 
     # The machine options (sid_model:, cia_model:, vic_model:, region: and
     # ram_expansion:) configure the AddressBus. The region sets the clock,
-    # the VIC's raster and the mains frequency the CIAs' TOD clocks count.
-    # Only PAL runs as yet.
-    def initialize(debug: false, **machine)
+    # the VIC's raster and sprite timing, and the mains frequency the CIAs'
+    # TOD clocks count. The KERNAL tells PAL from NTSC by the raster, so
+    # every region boots the same ROMs. reu plugs an REU of that many K
+    # into the expansion port, where it drives the IRQ line and takes the
+    # bus for its transfers.
+    def initialize(debug: false, reu: nil, **machine)
       @address_bus = AddressBus.new(**machine)
       @cpu = CPU.new(@address_bus, debug:)
       @vic = @address_bus.vic
@@ -48,11 +51,17 @@ module Badline
       @nmi_asserted = false
       @cartridge_nmi = false
       @restore_pulse = false
+      @reu_irq = false
+      @dma = false
       @freezing = false
       @freeze_writes = 0
       @init_handlers = []
       @pending_keys = nil
       @drive = nil
+      @serial_trap = nil
+      @drive1541 = nil
+      @iec_bus = nil
+      @reu = reu ? plug_reu(reu) : nil
     end
 
     INIT_THRESHOLD = 2_500_000
@@ -69,11 +78,12 @@ module Badline
       @sid.cycle!
       @datasette.cycle!
 
-      @cpu.irq = @cia1.interrupted? || @vic.interrupted?
+      @cpu.irq = @cia1.interrupted? || @vic.interrupted? || @reu_irq
 
       drive_nmi
       watch_freeze if @freezing
-      @cpu.pending_write? || !@vic.ba_low? ? @cpu.cycle! : @cpu.stall!
+      clock_cpu
+      @drive1541&.host_cycle!
 
       @cycles += 1
     end
@@ -91,6 +101,8 @@ module Badline
       power_cycle!
     end
 
+    def reu = address_bus.reu
+
     # A cartridge goes in with the power off, so attaching one switches the
     # machine off and on: the VIC and RAM start from their power-on state,
     # and the RES line resets everything else.
@@ -109,7 +121,10 @@ module Badline
       @cia2.reset!
       @sid.reset!
       address_bus.cartridge&.reset
+      @reu&.reset!
+      @dma = false
       @drive&.reset!
+      @drive1541&.reset!
       @freezing = false
       @nmi_asserted = false
       cpu.reset!
@@ -145,11 +160,44 @@ module Badline
       @drive = KernalTrap::Drive.new(storage)
       load_trap = KernalTrap::Load.new(cpu:, bus: address_bus, drive: @drive)
       cpu.install_trap(KernalTrap::Load::ADDRESS) { load_trap.call }
-      KernalTrap::Serial.new(cpu:, bus: address_bus, drive: @drive).install
+      @serial_trap = KernalTrap::Serial.new(cpu:, bus: address_bus, drive: @drive, device: serial_trap_device).install
       save_trap = KernalTrap::Save.new(cpu:, bus: address_bus, drive: @drive)
       cpu.install_trap(KernalTrap::Save::ADDRESS) { save_trap.call }
     end
 
+    # Takes device 8's mounted storage out, and with it the LOAD, SAVE and
+    # serial traps, so the KERNAL's routines go out over the serial bus.
+    # Mounting again starts a new drive, with its RAM cleared.
+    def unmount
+      return unless @drive
+
+      cpu.remove_trap(KernalTrap::Load::ADDRESS)
+      cpu.remove_trap(KernalTrap::Save::ADDRESS)
+      @serial_trap.device = nil
+      @serial_trap = nil
+      @drive = nil
+    end
+
+    # Plugs in a Drive1541, which then runs alongside the C64 on its own
+    # clock and talks to it over the serial bus. The serial traps stop
+    # answering the drive's device number, so the KERNAL's TALK, LISTEN and
+    # byte transfers reach the drive. The LOAD and SAVE traps stay, and
+    # still serve a mounted image.
+    def attach_drive1541(drive)
+      @iec_bus.detach(@drive1541) if @iec_bus && @drive1541
+      drive.host_clock_hz = region.clock_hz
+      @drive1541 = drive
+      drive.connect(iec_bus)
+      @serial_trap&.device = serial_trap_device
+    end
+
+    # The serial bus. CIA 2's port A joins it the first time it's asked
+    # for, which plugging in a drive does. Until then port A's serial
+    # inputs float high.
+    def iec_bus
+      @iec_bus ||= IECBus.new(host: @cia2).tap(&:plug_in!)
+    end
+
     def capture_output
       @capture_output ||= ChroutTrap.new(cpu:, bus: address_bus).tap do |trap|
         cpu.install_trap(ChroutTrap::ADDRESS) { trap.call }
@@ -170,6 +218,12 @@ module Badline
 
     private
 
+    # The device number the serial traps answer: device 8, unless a true
+    # drive is on the bus as device 8.
+    def serial_trap_device
+      @drive1541&.device == KernalTrap::Routine::DEVICE ? nil : KernalTrap::Routine::DEVICE
+    end
+
     # The NMI line is wired-OR between CIA 2, the cartridge and the RESTORE
     # key, and the CPU takes an interrupt on its falling edge.
     def drive_nmi
@@ -179,6 +233,31 @@ module Badline
       @nmi_asserted = nmi
     end
 
+    def plug_reu(size_kb)
+      reu = REU.new(size_kb, bus: @address_bus, vic: @vic)
+      reu.on_irq_change { |level| @reu_irq = level }
+      reu.on_dma { @dma = true }
+      @address_bus.attach_reu(reu)
+      reu
+    end
+
+    # BA halts the CPU on a read cycle, and so does an REU holding the bus
+    # for a transfer.
+    def clock_cpu
+      return dma_cycle! if @dma
+
+      @cpu.pending_write? || !@vic.ba_low? ? @cpu.cycle! : @cpu.stall!
+    end
+
+    def dma_cycle!
+      writing = @cpu.pending_write?
+      @reu.dma_cycle!(@vic.reu_ba_low?, writing)
+      return @cpu.stall! if @reu.holds_bus?
+
+      @dma = @reu.dma?
+      writing || !@vic.ba_low? ? @cpu.cycle! : @cpu.stall!
+    end
+
     # A freezer counts the CPU's write cycles once it pulls NMI and switches
     # to Ultimax on the third in a row, the last push of the interrupt
     # sequence, so the vector fetch that follows reads the cartridge.

data/lib/badline/cpu.rb

@@ -40,6 +40,7 @@ module Badline
       @brk = false
       @pending_write = false
       @stalled_at = nil
+      @so_high = true
 
       @cycles = 0
       @instructions = 0
@@ -88,6 +89,20 @@ module Badline
       sample_while_stalled
     end
 
+    # The 6502's SO (set overflow) pin, which the 6510 leaves out, so the
+    # C64 never drives it. A falling edge sets V and a held level does
+    # nothing more.
+    def so=(high)
+      @status.overflow = true if @so_high && !high
+      @so_high = high
+    end
+
+    # Pulses SO: pulls it low, which sets V, and releases it.
+    def so!
+      @status.overflow = true
+      @so_high = true
+    end
+
     def jammed?
       @plan.equal?(JAMMED_PLAN)
     end
@@ -99,6 +114,30 @@ module Badline
       nil
     end
 
+    # Whether the next cycle fetches an opcode.
+    def boundary? = @index.zero? && @plan.equal?(FETCH_PLAN)
+
+    def trapped? = !@traps.nil?
+
+    # Everything the CPU holds but its cycle and instruction counts: the
+    # registers, the interrupt lines and pipeline, and what the last
+    # instruction left in its working registers. Drive1541::Idle compares
+    # it at two instruction boundaries.
+    def idle_state
+      [@program_counter, @stack_pointer, @a, @x, @y, @status.value,
+       @irq, @nmi, @irq_sample, @irq_pending, @nmi_sample, @nmi_pending, @skip_poll,
+       @boundary_irq, @boundary_nmi, @so_high, @interrupt, @brk, @pending_write, @stalled_at, @traps,
+       @operation, @optional_dummy, @boundary_crossed, @branch_taken,
+       @address, @pointer, @dummy_address, @value, @rmw_result]
+    end
+
+    # Counts +cycles+ cycles and +instructions+ instructions that ran
+    # without changing anything idle_state holds.
+    def fast_forward(cycles, instructions)
+      @cycles += cycles
+      @instructions += instructions
+    end
+
     def inspect
       "Cycles: #{@cycles}, PC: #{format16(program_counter)}, " \
         "SP: #{format8(stack_pointer)}, A: #{format8(a)}, X: #{format8(x)}, " \

data/lib/badline/drive1541/bus.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Badline
+  class Drive1541
+    # The drive CPU's bus. The decoder looks at A15, A12, A11 and A10 only:
+    #
+    # $0000-$07FF - 2 KB of RAM
+    # $0800-$17FF - nothing: open bus
+    # $1800-$1BFF - VIA 1, its sixteen registers mirrored
+    # $1C00-$1FFF - VIA 2, its sixteen registers mirrored
+    # $2000-$7FFF - $0000-$1FFF again, since A13 and A14 aren't decoded
+    # $8000-$BFFF - the ROM again, since A14 isn't decoded
+    # $C000-$FFFF - the DOS ROM
+    #
+    # Writes to the ROM and to open bus go nowhere. A read from open bus
+    # finds the last byte on the data bus, which for LDA abs or LDA (zp),Y
+    # is the address's high byte, and for an indexed read that crosses a
+    # page is what its dummy read found. VICE-testprogs drive/openbus pins
+    # both on a real 1541.
+    #
+    # While Idle records a pass of the DOS's idle loop, the bus watches it
+    # (see watch!). While Idle looks for an orbit, the bus guards the drive
+    # (see guard!).
+    class Bus
+      include Addressable
+
+      # VIA registers, as bits by offset, whose access makes a watched
+      # stretch volatile: reads of either VIA's counters and shift register
+      # and of VIA 1's port B, and writes to VIA 2's timers, shift register
+      # and ACR. Any write to VIA 1 does too (watch_write).
+      VOLATILE_VIA1_READS = 0x0731
+      VOLATILE_VIA2_READS = 0x0730
+      VOLATILE_VIA2_WRITES = 0x0ff0
+
+      # The timer each VIA register reaches, by offset, as bits: 1 for
+      # timer 1 and 2 for timer 2.
+      TIMER_REGISTERS = [0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 0, 0, 0, 0, 0, 0].freeze
+
+      attr_reader :ram, :rom, :via1, :via2, :data
+
+      # Whether a watched stretch did something that makes it unrepeatable.
+      attr_reader :volatile
+
+      # The RAM a watched stretch read or wrote, as each address's value
+      # from before the first access.
+      attr_reader :touched
+
+      # Whether the drive did something since guard! that reached outside
+      # it, or took something in from outside.
+      attr_reader :tainted
+
+      # The timers the drive read or wrote since guard!, as bits: VIA 1's
+      # timer 1 and timer 2 in bits 0 and 1, and VIA 2's in bits 2 and 3.
+      attr_reader :touched_timers
+
+      def initialize(rom:, via1:, via2:)
+        addressable_at(0, length: 2**16)
+        @ram = Memory.new([], length: 0x0800, start: 0)
+        @rom = rom
+        @via1 = via1
+        @via2 = via2
+        @data = 0
+        @recording = @guarding = @watching = false
+        @volatile = @tainted = false
+        @touched = {}
+        @touched_timers = 0
+        @led = 0
+      end
+
+      # Starts watching: see volatile and touched. The bus stops watching
+      # once the stretch turns volatile.
+      def watch!
+        @recording = true
+        @volatile = false
+        @touched = {}
+        watching!
+      end
+
+      def unwatch!
+        @recording = false
+        watching!
+      end
+
+      # Starts guarding: see tainted and touched_timers. Reading VIA 1's
+      # port B, which reads the serial bus, taints the drive, and so do
+      # any write to VIA 1, whose port B drives the serial bus, a write to
+      # VIA 2's shift register or ACR, and VIA 2 turning the motor on or
+      # changing the LED. The bus stops guarding once the drive is tainted.
+      def guard!
+        @guarding = true
+        @tainted = false
+        @touched_timers = 0
+        @led = @via2.port_b_output & Mechanism::LED
+        watching!
+      end
+
+      def peek(addr)
+        return @data = @rom.peek(addr | 0x4000) if addr >= 0x8000
+
+        addr &= 0x1fff
+        watch_read(addr) if @watching
+        @data = if addr < 0x0800
+                  @ram.peek(addr)
+                elsif addr < 0x1800
+                  @data
+                elsif addr < 0x1c00
+                  @via1.peek(addr)
+                else
+                  @via2.peek(addr)
+                end
+      end
+
+      def poke(addr, value)
+        @data = value
+        return if addr >= 0x8000
+
+        addr &= 0x1fff
+        if addr < 0x0800
+          touch(addr) if @recording
+          @ram.poke(addr, value)
+        elsif addr >= 0x1c00
+          @via2.poke(addr, value)
+        elsif addr >= 0x1800
+          @via1.poke(addr, value)
+        end
+        watch_write(addr) if @watching
+      end
+
+      private
+
+      def watching!
+        @watching = @recording || @guarding
+      end
+
+      def touch(addr)
+        @touched[addr] = @ram.peek(addr) unless @touched.key?(addr)
+      end
+
+      def watch_read(addr)
+        if addr < 0x0800
+          touch(addr) if @recording
+        elsif addr >= 0x1800
+          via1 = addr < 0x1c00
+          watch(via1 ? VOLATILE_VIA1_READS : VOLATILE_VIA2_READS, addr) if @recording
+          guard_read(via1, addr & 0x0f) if @guarding
+        end
+      end
+
+      def watch_write(addr)
+        if addr >= 0x1c00
+          watch_via2_write(addr) if @recording
+          guard_via2_write(addr & 0x0f) if @guarding
+        elsif addr >= 0x1800
+          volatile! if @recording
+          taint! if @guarding
+        end
+      end
+
+      # Any write to VIA 1 makes the stretch volatile (watch_write), and so
+      # does a write to VIA 2 that leaves the motor on.
+      def watch_via2_write(addr)
+        watch(VOLATILE_VIA2_WRITES, addr)
+        volatile! if @recording && @via2.port_b_output.anybits?(Mechanism::MOTOR)
+      end
+
+      def watch(volatile, addr)
+        volatile! if volatile.anybits?(1 << (addr & 0x0f))
+      end
+
+      def volatile!
+        @volatile = true
+        @recording = false
+        watching!
+      end
+
+      def guard_read(via1, offset)
+        return taint! if via1 && offset.zero?
+
+        @touched_timers |= via1 ? TIMER_REGISTERS[offset] : TIMER_REGISTERS[offset] << 2
+      end
+
+      def guard_via2_write(offset)
+        return taint! if offset.between?(0x0a, 0x0b)
+
+        @touched_timers |= TIMER_REGISTERS[offset] << 2
+        lines = @via2.port_b_output
+        taint! if lines.anybits?(Mechanism::MOTOR) || (lines & Mechanism::LED) != @led
+      end
+
+      def taint!
+        @tainted = true
+        @guarding = false
+        watching!
+      end
+    end
+  end
+end