badline 0.12.1 → 0.14.0

data/lib/badline/drives/datasette/keyed_state.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    class Datasette
+      # The datasette's fields in a keyed snapshot module (Snapshot::Keyed,
+      # BL-TAPE): the keys, the motor, the countdown to the next pulse, and
+      # a tape in it under tape.*: its path, its bytes and how far it has
+      # played. A tape that isn't in leaves tape.* out. The sense and flag
+      # handlers don't fire on load.
+      module KeyedState
+        def save_fields(out)
+          out.bool("playing", @playing).bool("motor", @motor).int("countdown", @countdown)
+          tape = @tape
+          return out unless tape
+
+          out.text("tape.path", tape.path.to_s).bytes("tape.bytes", tape.bytes).int("tape.position", tape.position)
+        end
+
+        # The tape goes back in from the bytes the module holds, without its
+        # host file, unless the tape in is the same one.
+        def load_fields(input)
+          @playing = input.bool("playing", @playing)
+          @motor = input.bool("motor", @motor)
+          @countdown = input.int("countdown", @countdown)
+          bytes = input.bytes("tape.bytes", "".b).bytes
+          return @tape = nil if bytes.empty?
+
+          path = input.text("tape.path", "")
+          @tape = Storage::TAP.new(path, bytes:) unless @tape&.path.to_s == path && @tape&.bytes == bytes
+          @tape&.position = input.int("tape.position", 0)
+        end
+      end
+
+      include KeyedState
+    end
+  end
+end

data/lib/badline/drives/datasette.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "badline/drives/datasette/keyed_state"
+
+module Badline
+  module Drives
+    # The 1530 datasette. Plays a pulse stream into CIA 1's FLAG pin while the
+    # motor runs with a key pressed, and reports the keys through the cassette
+    # sense line on the $01 port. With RECORD down too, it records the
+    # machine's write line onto the tape instead. Built with +level: true+,
+    # it also times the read line's level, for a machine that reads that
+    # (#read_high?) rather than the falling edges.
+    class Datasette
+      # What inserting a tape raises on a machine without a cassette port.
+      class Missing < ArgumentError; end
+      attr_reader :tape
+      attr_writer :motor
+
+      def initialize(tape = nil, level: false)
+        @tape = tape
+        @level = level
+        @connected = true
+        @playing = false
+        @recording = false
+        @write_high = true
+        @since = 0
+        @motor = false
+        @countdown = 0
+        @rise_at = 0
+        @flag_handler = nil
+        @sense_handler = nil
+      end
+
+      # Falling edges on the tape read line.
+      def on_flag(&handler)
+        @flag_handler = handler
+      end
+
+      # The cassette sense line, which the $01 port reads back.
+      def on_sense_change(&handler)
+        @sense_handler = handler
+      end
+
+      # Whether the machine has a datasette at its cassette port. The SX-64
+      # has none: its keys stay up and it takes no tape.
+      def connected? = @connected
+
+      def disconnect!
+        eject
+        @connected = false
+      end
+
+      def insert(tape)
+        raise Missing, "this machine has no datasette" unless @connected
+
+        @tape = tape
+        rewind
+      end
+
+      def eject
+        stop!
+        @tape = nil
+      end
+
+      def rewind
+        @tape&.rewind
+        @countdown = 0
+        @rise_at = 0
+      end
+
+      def play! = press(true)
+      def stop! = press(false)
+
+      # Presses RECORD and PLAY together.
+      def record!
+        return if !@connected || @tape.nil?
+
+        press(true)
+        @recording = true
+        @since = 0
+      end
+
+      def recording? = @recording
+
+      # The machine's tape write line. While the deck records with its motor
+      # running, each rising edge ends a pulse on the tape, as long as the
+      # time since the edge before, and plays back as a falling edge on the
+      # read line.
+      def write_line=(high)
+        rose = high && !@write_high
+        @write_high = high
+        return unless rose && @recording && running?
+
+        @tape.record_pulse(@since)
+        @since = 0
+      end
+
+      # Sets the write line's level without recording an edge, as a
+      # snapshot loads it.
+      def write_level=(high)
+        @write_high = high
+      end
+
+      def playing? = @playing
+
+      # Sense reads low while a key is down on the deck.
+      def sense_low? = @playing
+
+      def motor? = @motor
+
+      def running? = @playing && @motor && !@tape.nil?
+
+      # The tape read line's level, on a datasette built with +level: true+.
+      # Each pulse holds it low for its first half and high for its second,
+      # up to the falling edge that ends it. A version 2 tape times each
+      # half, and a version 0 or 1 tape's pulse plays as two equal halves.
+      # It reads high while the tape isn't playing.
+      def read_high?
+        return true unless running? && !@recording
+
+        @countdown.positive? && @countdown <= @rise_at
+      end
+
+      def cycle!
+        return unless running?
+        return @since += 1 if @recording
+
+        next_pulse if @countdown.zero?
+        return if @countdown.zero?
+
+        @countdown -= 1
+        @flag_handler&.call if @countdown.zero?
+      end
+
+      def inspect
+        "#<#{self.class.name} tape=#{@tape ? @tape.class.name : 'none'} " \
+          "playing=#{@playing} motor=#{@motor}>"
+      end
+
+      private
+
+      def next_pulse
+        return @countdown = @tape.next_pulse.to_i unless @level
+        return next_half_waves if @tape.half_waves?
+
+        @countdown = @tape.next_pulse.to_i
+        @rise_at = @countdown / 2
+      end
+
+      def next_half_waves
+        first = @tape.next_half_wave.to_i
+        @rise_at = @tape.next_half_wave.to_i
+        @countdown = first + @rise_at
+      end
+
+      def press(down)
+        return if down == @playing || !@connected
+
+        finish_recording unless down
+        @playing = down
+        @sense_handler&.call
+      end
+
+      # Releasing the keys ends a recording, and writes the tape out.
+      def finish_recording
+        return unless @recording
+
+        @recording = false
+        @tape.save
+      end
+    end
+  end
+end

data/lib/badline/drives/engine/core.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    module Engine
+      # What every Commodore disk drive here shares: a 6502 running the DOS
+      # ROM, with chips on its bus facing the serial bus and the disk
+      # mechanism, on a clock of its own.
+      #
+      # The drive runs on its own crystal, so it clocks against the host's
+      # clock through a fractional accumulator: each host cycle adds the
+      # drive's clock rate worth of phase, and every whole host period in it
+      # runs a drive cycle. Against the PAL C64's 985,248 Hz a drive at
+      # 1 MHz runs one drive cycle per host cycle and a second one about
+      # every 67. The host sets its clock on attaching the drive, and until
+      # then a 1 MHz drive runs one cycle per host cycle.
+      #
+      # The Mechanism reads a Disk put in with insert.
+      #
+      # While the DOS idles, host_cycle! skips the drive's cycles and catches
+      # up on them later, exactly (see Idle). The readers of the drive's parts
+      # catch up first, so they find the drive as running every cycle would
+      # have left it. Once the DOS's timer interrupts come round, the drive
+      # sleeps through them too (see Orbit).
+      #
+      # A model includes Core and builds its parts, sets @clock_hz and
+      # @idle_loop, and runs one drive cycle in step. It hears ATN on
+      # connecting (hear_atn), drives the serial bus (serial_output), and
+      # answers Idle's and Orbit's questions about its chips, as VIAs does
+      # for the 1541 and the 1571.
+      module Core
+        include Sleep
+        include Idle
+        include Orbit
+
+        attr_reader :device, :serial_bus
+
+        def cpu
+          settle!
+          @cpu
+        end
+
+        def bus
+          settle!
+          @bus
+        end
+
+        def mechanism
+          settle!
+          @mechanism
+        end
+
+        def cycles
+          settle!
+          @cycles
+        end
+
+        def ram = bus.ram
+
+        def host_clock_hz=(clock_hz)
+          settle!
+          @host_clock_hz = clock_hz
+        end
+
+        # Plugs the drive into a serial bus, leaving the one it was on. A drive
+        # starts out on a bus of its own, with nothing else on it.
+        def connect(serial_bus)
+          settle!
+          @serial_bus&.detach(self)
+          @serial_bus = serial_bus
+          @serial_port.bus = serial_bus
+          serial_bus.attach(self)
+          hear_atn
+        end
+
+        # Puts a Disk in the drive (Disk.from_d64 makes one from an image).
+        # Nil takes the disk out.
+        def insert(disk)
+          settle!
+          @mechanism.insert(disk)
+        end
+
+        def disk = mechanism.disk
+
+        # Whether the LED is lit. Reading it leaves the drive asleep: the LED
+        # is the same at the end of every pass the drive sleeps through.
+        def led_on? = @mechanism.led_on?
+
+        # The power LED, which stays lit.
+        def power_led_on? = true
+
+        # Stores what the head wrote since the motor last stopped in the
+        # disk's image, as the motor stopping does.
+        def flush
+          settle!
+          @mechanism.flush
+        end
+
+        # Runs the drive cycles that fall in one host cycle: none, one or two.
+        # The host has run this cycle already, and the drive sees what it did
+        # from the next one on (see SerialPort). Asleep, the drive owes the
+        # cycles instead, until ATN moves or its counters are due (see Idle).
+        # It looks at ATN only after the machine pushed its lines into the bus
+        # (see host_written!).
+        def host_cycle!
+          if @asleep
+            return if (@slept += 1) != @wake_at && @host_still
+
+            return doze
+          end
+
+          phase = @phase + @clock_hz
+          while phase >= @host_clock_hz
+            @asleep ? @owed += 1 : run_cycle
+            phase -= @host_clock_hz
+          end
+          @phase = phase
+          settle! if @serial_port.atn_moved?
+          @serial_port.latch_host
+          plan_wake if @asleep
+        end
+
+        # The machine pushed its lines into the bus, so ATN may have moved.
+        def host_written!
+          @host_still = false
+        end
+
+        # The host moved its fast serial pins, which a 1541 has none to hear.
+        def fast_lines_moved = nil
+
+        # Runs one drive cycle, catching up first on any the drive owes (see
+        # step).
+        def cycle!
+          settle!
+          step
+        end
+
+        def inspect
+          "#<#{self.class.name} cycles=#{cycles} cpu=(#{cpu.inspect})>"
+        end
+
+        private
+
+        # A drive cycle from host_cycle!, which may find the idle loop.
+        def run_cycle
+          step
+          idle_loop_reached if @cpu.program_counter == @idle_loop && @idle_skip
+        end
+      end
+    end
+  end
+end

data/lib/badline/drives/engine/fast_serial.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    module Engine
+      # Fast serial on a drive with a CIA, the 1571's 6526 or the 1581's
+      # 8520: through buffers a port line turns round, the CIA's CNT drives
+      # SRQ and its SP drives DATA, or it hears them. The drive pushes its
+      # pins into the bus as they move, and hears the host's as the host
+      # pushes them, pin by pin, so each byte goes through both shift
+      # registers bit by bit. The CIA takes no part in a pass of the idle
+      # loop, and any access to it, or the host moving its fast serial pins,
+      # wakes the drive.
+      #
+      # A model includes it beside Core, and calls turn_fast_serial when its
+      # direction line moves and drive_fast_serial each cycle the buffers
+      # face out. Its serial_output carries @fast_output above its port.
+      module FastSerial
+        # Whether the buffers face out, the drive's CIA driving DATA and SRQ.
+        attr_reader :fast_serial_out
+
+        # The host moved its fast serial pins: the CIA hears SRQ on CNT and
+        # DATA on SP while the buffers face in.
+        def fast_lines_moved
+          settle!
+          hear_fast_serial unless @fast_serial_out
+        end
+
+        private
+
+        def init_fast_serial
+          @fast_serial_out = false
+          @fast_output = 0
+        end
+
+        # The buffers turned round: outwards the CIA's pins drive the lines,
+        # and inwards they let go and hear them.
+        def turn_fast_serial(out)
+          @fast_serial_out = out
+          return unless @serial_bus
+
+          push_fast_output(out ? fast_pins : 0)
+          hear_fast_serial unless out
+        end
+
+        def drive_fast_serial
+          low = fast_pins
+          push_fast_output(low) if low != @fast_output
+        end
+
+        # The lines the CIA's CNT and SP pull while its serial port drives
+        # them.
+        def fast_pins
+          serial = @cia.serial
+          return 0 unless serial.output?
+
+          low = serial.cnt ? 0 : SerialBus::DRIVE_FAST_SRQ
+          serial.sp_out ? low : low | SerialBus::DRIVE_FAST_DATA
+        end
+
+        def push_fast_output(low)
+          @fast_output = low
+          @serial_bus&.drives_fast_moved!
+        end
+
+        def hear_fast_serial
+          low = @serial_bus.low_lines
+          serial = @cia.serial
+          serial.cnt_in = low.nobits?(SerialBus::SRQ)
+          serial.sp_in = low.nobits?(SerialBus::DATA)
+        end
+      end
+    end
+  end
+end

data/lib/badline/drives/engine/idle.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    module Engine
+      # Skipping the drive's cycles while the DOS idles, exactly.
+      #
+      # With nothing to do, the DOS goes round its idle loop from the
+      # model's @idle_loop ($EBFF in the 1541, 446 cycles a pass), until VIA
+      # 2's timer 1 interrupts it every 14,850 cycles for the job loop, or
+      # ATN interrupts it through VIA 1's CA1. A pass writes RAM and VIA 2's
+      # port B, but puts back what it found, so the drive comes round to the
+      # loop's start as it left it. Only the timers' counters and the cycle
+      # counts move.
+      #
+      # Each time the CPU comes to the loop's start, the drive records the
+      # pass that follows. At the next it checks that the pass
+      #
+      # - left the CPU, both VIAs but for their counters, the bus's last
+      #   byte, the SO pin, the mechanism (Mechanism#idle_state) and what
+      #   the ports read from it, and every byte of RAM it read or wrote as
+      #   it found them (Bus#watch!)
+      # - read nothing that changes from pass to pass: no counter, no shift
+      #   register, and not VIA 1's port B, which reads the serial bus
+      # - wrote nothing that reaches outside the drive: not VIA 1, whose port
+      #   B drives the serial bus, and not the motor on
+      # - ran while no counter could set a flag (VIA#quiet_cycles), with the
+      #   motor off, no interrupt pulled and no trap on the CPU.
+      #
+      # Such a pass runs the same way again from where it ended, for as
+      # long as ATN holds still and no counter sets a flag, so the drive
+      # sleeps: host_cycle! only counts the host cycles that go by (see
+      # Sleep). It wakes
+      # when ATN moves, when a counter is due to set a flag, or when something
+      # outside reads or changes the drive (the readers in Core call
+      # settle!). Waking counts off the whole passes it owes in bulk,
+      # moving the counters on, and runs the rest cycle by cycle.
+      #
+      # The loop reads neither CLK nor DATA, so the drive sleeps through them
+      # moving and takes the C64's lines as they stand once it wakes. Its
+      # own lines hold still while it sleeps, so the C64 reads them without
+      # waking it (serial_output).
+      #
+      # A pass starts at the loop's start, where the CPU always comes from
+      # the loop's last instruction, a JMP, so what that leaves in the CPU's
+      # working registers is the same each time round.
+      #
+      # The timer's interrupts come round too, and once they do, the drive
+      # sleeps on through them (see Orbit).
+      module Idle
+        # Whether the drive may sleep through its idle loop. On by default,
+        # but for a drive whose CPU logs each instruction.
+        attr_reader :idle_skip
+
+        def idle_skip=(on)
+          settle!
+          @idle_skip = on
+        end
+
+        private
+
+        def init_idle(debug)
+          @idle_skip = !debug
+          @recording = false
+          @pass_cycles = 0
+          @pass_instructions = 0
+          init_sleep
+          init_orbits
+        end
+
+        # The CPU is at the loop's start. At an instruction boundary, the
+        # drive sleeps if the pass it recorded can repeat, and otherwise
+        # records the next.
+        def idle_loop_reached
+          return unless @cpu.boundary?
+
+          if @recording
+            stop_recording
+            return fall_asleep if repeatable_pass? && room_for_pass?
+          end
+          start_recording
+        end
+
+        def start_recording
+          return if busy_for_pass? || @cpu.trapped?
+
+          @recording = true
+          @record_state = idle_state
+          @record_cycles = @cycles
+          @record_instructions = @cpu.instructions
+          @record_quiet = quiet_cycles
+          @bus.watch!
+        end
+
+        def stop_recording
+          @recording = false
+          @bus.unwatch!
+        end
+
+        # Whether the pass just recorded can repeat.
+        def repeatable_pass?
+          !@bus.volatile && @cycles - @record_cycles <= @record_quiet && idle_state == @record_state &&
+            ram_as_found?
+        end
+
+        # Whether the counters leave room for a whole pass.
+        def room_for_pass? = quiet_cycles >= @cycles - @record_cycles
+
+        # Sleeps through the pass just recorded, over and over.
+        def fall_asleep
+          @pass_cycles = @cycles - @record_cycles
+          @pass_instructions = @cpu.instructions - @record_instructions
+          @asleep = true
+          @host_still = false
+          @owed = 0
+          @budget = quiet_cycles
+          anchor
+        end
+
+        def ram_as_found?
+          ram = @bus.ram
+          @bus.touched.all? { |addr, value| ram.peek(addr) == value }
+        end
+      end
+    end
+  end
+end

data/lib/badline/drives/engine/idle_cpu.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    module Engine
+      # What Idle needs of a drive's 6502, which includes it beside
+      # CPU::Core.
+      module IdleCPU
+        # 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. Drives::Engine::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
+      end
+    end
+  end
+end

data/lib/badline/drives/engine/orbit.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    module Engine
+      # Sleeping through the DOS's timer interrupts, exactly, once they come
+      # round.
+      #
+      # VIA 2's timer 1 interrupts the idle loop for the job loop, which
+      # finds no job, restarts the timer and returns into the pass it cut
+      # into, 14,998 cycles and more apart. The interrupts land at a
+      # different point in the pass each time, until, six of them on, the
+      # whole drive is back where it was: an orbit of 90,044 cycles.
+      #
+      # Each place the drive falls asleep (see Idle) is an anchor, and the
+      # drive keeps everything it holds at each one: RAM, the counters of
+      # the timers that are armed or that it read or wrote since, and the
+      # rest as Idle compares a pass. It keeps them only while it keeps to
+      # itself, with Bus#guard! checking that it doesn't read the serial
+      # bus, write VIA 1, turn the motor on or change the LED. ATN moving,
+      # or a reader settling the drive, forgets them.
+      #
+      # Coming to an anchor it kept before closes an orbit, which runs the
+      # same way again from here for as long as ATN holds still, so the
+      # drive sleeps on without waking for its counters. Waking counts off
+      # the whole orbits it owes in bulk, moving on only the counters it
+      # never touched, and runs the rest as Idle does.
+      module Orbit
+        # How many anchors the drive keeps while it looks for an orbit.
+        ANCHORS = 32
+
+        private
+
+        def init_orbits
+          @anchors = {}
+          @orbit_cycles = nil
+          @orbit_instructions = 0
+          @bus.guard!
+        end
+
+        # The drive falls asleep at an anchor. One it came to before closes
+        # an orbit: everything from there to here runs the same way again.
+        def anchor
+          forget_orbits if @bus.tainted || @anchors.size >= ANCHORS
+          key = anchor_state
+          if (seen = @anchors[key])
+            @orbit_cycles = @cycles - seen[0]
+            @orbit_instructions = @cpu.instructions - seen[1]
+          else
+            @anchors[key] = [@cycles, @cpu.instructions]
+          end
+        end
+
+        def forget_orbits
+          @anchors.clear
+          @orbit_cycles = nil
+          @bus.guard!
+        end
+
+        # Runs whole orbits, which bring the drive back to the anchor it
+        # sleeps at but for the counters it never touched. Returns the
+        # cycles.
+        def skip_orbits(orbits)
+          cycles = orbits * @orbit_cycles
+          touched = @bus.touched_timers
+          @cpu.fast_forward(cycles, orbits * @orbit_instructions)
+          skip_chip_orbits(cycles, touched)
+          @cycles += cycles
+          cycles
+        end
+
+        # Everything the drive holds at an anchor, but for the counters of
+        # the unarmed timers it hasn't touched since it was last tainted.
+        def anchor_state
+          touched = @bus.touched_timers
+          [*idle_state, *counter_state(touched), @bus.ram.snapshot]
+        end
+      end
+    end
+  end
+end