badline 0.12.0 → 0.13.0

data/lib/badline/drives/model1541/mechanism.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "badline/drives/model1541/rotation"
+require "badline/drives/model1541/mechanism/saved_state"
+require "badline/drives/model1541/byte_ready"
+
+module Badline
+  module Drives
+    class Model1541
+      # The disk mechanism behind VIA 2: the spindle motor, the head on its
+      # stepper, the LED, the read and write electronics and the
+      # write-protect sensor.
+      #
+      # Port B drives it and reads it back:
+      #
+      #   PB0-1  stepper phase (out)    PB4    write protect (in, 1 = writable)
+      #   PB2    motor on (out)         PB5-6  bit rate, speed zone 0-3 (out)
+      #   PB3    LED on (out)           PB7    SYNC (in, 0 while in a SYNC mark)
+      #
+      # Port A reads the read shift register's low eight bits, which CA1
+      # latches on BYTE READY. In write mode it drives the write shift
+      # register, and the read shift register takes the bits written.
+      #
+      # The disk turns at 300 rpm under the head, and a read clock at the
+      # bit rate PB5-6 select clocks the bits off it (see Rotation).
+      #
+      # Ten 1 bits in a row are a SYNC mark while CB2 selects reading: PB7
+      # reads it, and it holds the bit counter at zero, so the first 0 bit
+      # after it starts a byte. Every eighth bit after that is BYTE READY,
+      # which pulls VIA 2's CA1 low until the next bit and reaches the CPU's
+      # SO pin (see byte_ready!).
+      #
+      # CB2 low selects write mode, where SYNC detection and the flux are
+      # off and the clock runs on at the selected rate. At each BYTE READY
+      # the write shift register loads what the VIA drives on port A, and
+      # the next eight clocks put that byte's bits on the track, most
+      # significant first, in place of what it held. While reading, the load
+      # takes the byte just read, so a switch to writing mid-byte writes the
+      # rest of it. A write lays its bits one to a cell from the cell under
+      # the head, so on a track written at the selected rate each bit fills
+      # the cell it passes over. A write to a half track without data gives
+      # it a blank track first, a turn long at the selected rate, and a
+      # write to a track written at another rate lays the whole track out
+      # again as a turn at the selected rate first (Track#relaid).
+      #
+      # PB4 reads the write-protect sensor: high with no disk in, or with
+      # the notch of a writable one open. With the disk write-protected the
+      # write gate stays shut: the bits and BYTE READY go on, and nothing
+      # reaches the disk. The DOS reads PB4 first and refuses to write, so
+      # only a program that writes without asking finds that out.
+      #
+      # The motor stopping flushes what was written to the disk's image
+      # (see Disk#flush), which is when the DOS is done with a job, and so
+      # does taking the disk out.
+      #
+      # The stepper moves the head a half track each time the phase steps
+      # by one, inwards for +1 and outwards for -1. Each half track has a
+      # phase of its own, from power-on the low two bits of its number, so
+      # the head sits on a whole track when phase 0 or 2 holds it. The
+      # stepper's coils are powered only while PB2 runs the motor, as VICE
+      # reads the 1541's schematic, so a phase set with the motor off moves
+      # nothing until the motor comes on and it pulls the head. Tracks run
+      # from half track 2 (track 1), where the head stops against the end of
+      # its rail, to Disk::MAX_HALF_TRACK. A step out against the stop slips:
+      # the head stays on track 1 and the phase that tried to pull it out
+      # becomes track 1's, so the DOS's bump leaves the head on track 1 in
+      # line with the phase it ends on, and its first step in reaches the
+      # half track after it.
+      #
+      # The 1571's stepper is lined up so that phase 0 holds track 1, where
+      # its track 0 sensor looks for the head (Mechanism.new's +slip+).
+      class Mechanism
+        include Rotation
+        include SavedState
+        include ByteReady
+
+        MOTOR = 0x04
+        LED = 0x08
+        WRITE_PROTECT = 0x10
+        SYNC = 0x80
+
+        MIN_HALF_TRACK = 2
+        # Where the head sits at power-on: track 18, the directory.
+        START_HALF_TRACK = 36
+
+        SYNC_BITS = 10
+
+        attr_reader :disk, :half_track, :zone
+
+        # +slip+ is the stepper's phase offset at power-on: 0, where each half
+        # track's phase is the low two bits of its number, or 2 for track 1
+        # on phase 0.
+        def initialize(slip: 0)
+          @via = nil
+          @so_pending = false
+          @disk = nil
+          @half_track = START_HALF_TRACK
+          @slip = slip
+          @motor = false
+          @led = false
+          @zone = 0
+          @clock = Track.cell(0)
+          @time = 0
+          @clock_at = @clock / 2
+          @clocks = 0
+          @shift = 0
+          @ones = 0
+          @bits = 0
+          @sync = false
+          @byte_ready = false
+          @byte_latched = false
+          @writing = false
+          @write_shift = 0
+          @write_gate = false
+          @protected = false
+          @side_base = 0
+          @cycle_ticks = CYCLE
+          load_track
+        end
+
+        # The drive's clock rate: the disk turns on by fewer ticks each
+        # cycle at 2 MHz.
+        def clock_hz=(clock_hz)
+          @cycle_ticks = CYCLE * CLOCK_HZ / clock_hz
+        end
+
+        # The head that reads, 0 or 1, on a drive with two (Disk::SIDE).
+        def side = @side_base.zero? ? 0 : 1
+
+        def side=(side)
+          side_base = side * Disk::SIDE
+          return if side_base == @side_base
+
+          @side_base = side_base
+          load_track
+        end
+
+        def motor_on? = @motor
+
+        def led_on? = @led
+
+        def sync? = @sync
+
+        def writing? = @writing
+
+        # What port B and CB2 can change with the motor off: the motor, the
+        # LED, the zone and the clock's rate, the stepper, write mode and
+        # where a write starts, and the track and cell under the head. The
+        # rest moves only while the motor turns, or as a disk goes in (see
+        # Drives::Engine::Idle).
+        def idle_state
+          [@motor, @led, @zone, @clock, @half_track, @slip, @side_base, @disk, @track, @index, @mask, @cell_end,
+           @time, @writing, @write_index, @sync, @byte_latched]
+        end
+
+        # Puts a Disk in, or takes it out with nil, flushing the disk that
+        # was in. The head goes on from the same point in the turn.
+        def insert(disk)
+          flush
+          @disk = disk
+          @protected = disk&.write_protected? || false
+          @write_gate = !disk.nil? && !@protected
+          load_track
+        end
+
+        # Stores what the head wrote in the disk's image.
+        def flush
+          @disk.flush if @disk&.written?
+        rescue Storage::WriteError => e
+          warn "1541: couldn't write the disk back: #{e.message}"
+        end
+
+        # VIA 2 drives CB2 to +high+: low selects write mode, which stops
+        # SYNC detection at once.
+        def cb2_written(high)
+          @write_index = nil if high || !@writing
+          @writing = !high
+          @sync = !@writing && @ones >= SYNC_BITS
+        end
+
+        # VIA 2 drives port B's lines to +lines+.
+        def port_b_written(lines)
+          motor = @motor
+          @motor = lines.anybits?(MOTOR)
+          flush if motor && !@motor
+          @led = lines.anybits?(LED)
+          zone = (lines >> 5) & 0x03
+          if zone != @zone
+            @zone = zone
+            @clock = Track.cell(zone)
+            @track_written = false
+          end
+          step(lines & 0x03) if @motor
+        end
+
+        # Port A is the read shift register.
+        def read_a(_lines) = @shift & 0xff
+
+        # SYNC low in a SYNC mark, and write protect low for a protected
+        # disk.
+        def read_b(_lines)
+          lines = @sync ? 0xff & ~SYNC : 0xff
+          @protected ? lines & ~WRITE_PROTECT : lines
+        end
+
+        private
+
+        def read_bit(one)
+          if @byte_ready
+            @byte_ready = false
+            byte_ready_ended!
+          end
+          @shift = ((@shift << 1) & 0x3fe) | (one ? 1 : 0)
+          if one
+            @ones += 1
+            @sync = true if @ones >= SYNC_BITS
+          else
+            @ones = 0
+            @sync = false
+          end
+          count_bit
+        end
+
+        # The write shift register's top bit goes onto the track through the
+        # write gate, and into the read shift register, as the head's own
+        # signal.
+        def write_bit(at)
+          if @byte_ready
+            @byte_ready = false
+            byte_ready_ended!
+          end
+          one = @write_shift.anybits?(0x80)
+          @write_shift = (@write_shift << 1) & 0xff
+          store_bit(one, at) if @write_gate
+          @shift = ((@shift << 1) & 0x3fe) | (one ? 1 : 0)
+          @ones = one ? @ones + 1 : 0
+          count_bit
+        end
+
+        # Each bit written goes in the cell after the last one's, from the
+        # cell under the head when the write started.
+        def store_bit(one, at)
+          track_written(at) unless @track_written
+          @write_index ||= (@index * 8) + 8 - @mask.bit_length
+          index = @write_index >> 3
+          mask = 0x80 >> (@write_index & 7)
+          if one
+            @bytes[index] |= mask
+          else
+            @bytes[index] &= ~mask
+          end
+          @write_index += 1
+          @write_index = 0 if @write_index == @length * 8
+        end
+
+        # The first write to the track since the head came to it or the rate
+        # changed: a half track without data gets a blank track, and a track
+        # written at another rate is laid out again at this one.
+        def track_written(at)
+          surface = self.surface
+          track = @disk.writable_track(surface, @zone)
+          @disk.write(surface, track.relaid(@zone)) unless track.written_at?(@zone)
+          load_track(at)
+          @disk.written(surface)
+          @track_written = true
+        end
+
+        # Every eighth bit outside a SYNC mark is BYTE READY, which loads the
+        # write shift register: from what the VIA drives on port A in write
+        # mode, and with the byte just read otherwise.
+        def count_bit
+          if @sync
+            @bits = 0
+            return
+          end
+          @bits += 1
+          return unless @bits == 8
+
+          @bits = 0
+          @write_shift = @writing ? @via.port_a_output : @shift & 0xff
+          @byte_ready = true
+          byte_ready!
+        end
+
+        # The stepper's rotor turns with the head, a phase to each half
+        # track, so the energized phase pulls the head to the neighbouring
+        # half track it belongs to. A phase two away pulls both ways, and the
+        # head stays. Against the stop at track 1 the head can't follow, and
+        # the phases slip round to where the head is.
+        def step(phase)
+          move = (phase - @half_track - @slip) & 0x03
+          if move == 1
+            seek(@half_track + 1)
+          elsif move == 3 && @half_track == MIN_HALF_TRACK
+            @slip = (phase - MIN_HALF_TRACK) & 0x03
+          elsif move == 3
+            seek(@half_track - 1)
+          end
+        end
+
+        # The half track under the head that reads, numbered on the disk
+        # (see Disk::SIDE).
+        def surface = @half_track + @side_base
+
+        def seek(half_track)
+          half_track = half_track.clamp(MIN_HALF_TRACK, Disk::MAX_HALF_TRACK)
+          return if half_track == @half_track
+
+          @half_track = half_track
+          load_track
+        end
+      end
+    end
+  end
+end

data/lib/badline/drives/model1541/rotation.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    class Model1541
+      # The disk turning under the Mechanism's head, and its read clock.
+      #
+      # The disk turns at 300 rpm, whatever the bit rate: once in 200 ms, or
+      # 200,000 drive cycles. Each track's bits pass under the head at the
+      # rate they were written at (see Track), and a 1 bit is a flux
+      # transition at the start of its cell.
+      #
+      # The read circuit clocks bits out at the rate PB5-6 select, from a
+      # counter the 16 MHz crystal steps every 16 - zone ticks. A flux
+      # transition clears the counter. The counter clocks a bit into the
+      # read shift register as it reaches 2 and every four steps after
+      # that, and the bit is a 1 only for the first clock after the counter
+      # passed 0. A bit is 4 * (16 - zone) ticks, so a byte takes 32, 30, 28
+      # or 26 drive cycles in zones 0 to 3, and each transition brings the
+      # clock back into step with the flux. A track read at the rate it was
+      # written reads its bits. At another rate the clock and the cells
+      # drift apart between transitions: a faster clock slips an extra 0
+      # bit into some runs of 0 bits, a slower one drops one from some, and
+      # the bytes come out garbled. Without flux the counter runs round on
+      # its own and reads a 1 bit in every four.
+      module Rotation
+        CYCLE = 16 * Track::TICK
+
+        # What the head reads with no disk in, or off the tracks a disk has:
+        # no flux.
+        BLANK = Track.new(Array.new(Disk::TRACK_LENGTHS[0], 0).freeze, 0)
+
+        # One drive cycle: nothing with the motor off, and otherwise the
+        # disk turns on by a cycle's ticks, 16 at 1 MHz and 8 at 2 MHz,
+        # through whatever cells and clocks fall in them.
+        def cycle!
+          return unless @motor
+
+          @time += @cycle_ticks
+          pass_time if @time >= @next
+        end
+
+        private
+
+        # The cell edges and clocks up to now, in the order they come. A
+        # clock that falls on a cell edge comes after it.
+        def pass_time
+          while @cell_end <= @time || @clock_at <= @time
+            if @cell_end <= @clock_at
+              next_cell
+            else
+              clock
+            end
+          end
+          @next = [@cell_end, @clock_at].min
+        end
+
+        # The head comes to the next cell, and a 1 bit's flux clears the
+        # read clock while reading.
+        def next_cell
+          start = @cell_end
+          @mask >>= 1
+          start = next_byte(start) if @mask.zero?
+          @cell_end = @index == @last && @mask == 1 ? Track::TURN : start + @width
+          return if @writing || @bytes[@index].nobits?(@mask)
+
+          @clock_at = start + (@clock / 2)
+          @clocks = 0
+        end
+
+        # The head comes to the next byte, and at the end of the track back
+        # round to the first, where the turn starts over.
+        def next_byte(start)
+          @mask = 0x80
+          @index += 1
+          if @index == @length
+            @index = 0
+            @time -= Track::TURN
+            @clock_at -= Track::TURN
+            start = 0
+          end
+          @width = @widths[@index] if @widths
+          start
+        end
+
+        # The read clock ticks a bit into the shift register: a 1 the first
+        # time after a flux transition or the counter's wrap.
+        def clock
+          at = @clock_at
+          one = @clocks.zero?
+          @clocks = (@clocks + 1) & 3
+          @clock_at = at + @clock
+          @writing ? write_bit(at) : read_bit(one)
+        end
+
+        # The track under the head and its layout, leaving the head's place
+        # on it as it stands.
+        def head_on_track
+          @track = @disk&.track(surface) || BLANK
+          @bytes = @track.bytes
+          @widths = @track.widths
+          @length = @track.length
+          @last = @length - 1
+        end
+
+        # The track under the head, from the cell that's under it +time+
+        # into the turn.
+        def load_track(time = @time)
+          @track = @disk&.track(surface) || BLANK
+          @bytes = @track.bytes
+          @widths = @track.widths
+          @length = @track.length
+          @last = @length - 1
+          @index, @mask, @cell_end = @track.cell_at(time)
+          @width = @widths ? @widths[@index] : @track.width
+          @write_index = nil
+          @track_written = false
+          @next = [@cell_end, @clock_at].min
+        end
+      end
+    end
+  end
+end

data/lib/badline/drives/model1541/saved_state.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    class Model1541
+      # The drive's state for a snapshot.
+      module SavedState
+        # The drive's whole state: its clock phase, the CPU, RAM, both VIAs,
+        # the serial port's latch of the C64's lines and the mechanism with its
+        # disk. The drive settles first, so it is awake and not recording a
+        # pass, and a restored drive starts the same way, its orbits forgotten
+        # from the state it takes: Idle's and Orbit's bookkeeping
+        # isn't stored. The device number, the host's clock rate and whether
+        # the drive may sleep are the machine's wiring.
+        def save_state(out)
+          settle!
+          out.marker("DRIVE1541")
+          out.int(@phase).int(@cycles).boolean(@mechanism.so_pending)
+          @serial_port.save_state(out)
+          @via1.save_state(out)
+          @via2.save_state(out)
+          @bus.save_state(out)
+          @cpu.save_state(out)
+          @mechanism.save_state(out)
+        end
+
+        def load_state(input)
+          settle!
+          input.marker("DRIVE1541")
+          @phase = input.int
+          @cycles = input.int
+          @mechanism.so_pending = input.boolean?
+          @serial_port.load_state(input)
+          @via1.load_state(input)
+          @via2.load_state(input)
+          @bus.load_state(input)
+          @cpu.load_state(input)
+          @mechanism.load_state(input)
+          forget_orbits
+        end
+      end
+    end
+  end
+end

data/lib/badline/drives/model1541/sector_reader.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    class Model1541
+      # Reads a track's blocks back out of its GCR, as the DOS finds them:
+      # each SYNC mark is ten or more 1 bits, and the block after it starts
+      # at the first 0 bit. Writes land wherever the head was, so a block
+      # can start at any bit of the stored bytes, and the reader works on
+      # the bits.
+      #
+      # A header block starts with $08, and the next block after a header is
+      # that sector's data block, whatever it holds.
+      module SectorReader
+        HEADER_BITS = 10 * 8
+        DATA_BITS = 325 * 8
+        SYNC = /1{10,}/
+
+        # A sector as read: its decoded header, [ID, checksum, sector, track,
+        # the second ID byte, the first, ...], and its decoded data block,
+        # [ID, 256 data bytes, checksum, ...], nil when there isn't one that
+        # decodes.
+        Sector = Struct.new(:header, :data)
+
+        module_function
+
+        # The sectors found on the track's bytes, by sector number. Headers
+        # for another track are left out.
+        def read(bytes, track)
+          ring = ring(bytes)
+          return {} unless ring
+
+          sectors = {}
+          each_block(ring) do |header, data|
+            next unless header[3] == track
+
+            sectors[header[2]] ||= Sector.new(header, data)
+          end
+          sectors
+        end
+
+        # The track's bits, starting at a 0 bit so no SYNC mark straddles the
+        # start, twice over so a block can run on past the end. Nil for a
+        # track without a 0 bit.
+        def ring(bytes)
+          bits = bytes.pack("C*").unpack1("B*")
+          zero = bits.index("0")
+          return unless zero
+
+          bits = bits[zero..] + bits[0, zero]
+          [bits * 2, bits.length]
+        end
+
+        # Yields each header whose SYNC mark starts in the first turn, with
+        # the data block after it.
+        def each_block(ring)
+          bits, length = ring
+          pos = 0
+          while (sync = SYNC.match(bits, pos)) && sync.begin(0) < length
+            pos = sync.end(0)
+            header = decode(bits, pos, HEADER_BITS)
+            next unless header && header[0] == Disk::HEADER_ID
+
+            data_sync = SYNC.match(bits, pos + HEADER_BITS)
+            yield header, data_sync && decode(bits, data_sync.end(0), DATA_BITS)
+          end
+        end
+
+        def decode(bits, pos, count)
+          slice = bits[pos, count]
+          return unless slice.length == count
+
+          GCR.decode([slice].pack("B*").bytes)
+        end
+      end
+    end
+  end
+end

data/lib/badline/drives/model1541/serial_port.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    class Model1541
+      # What VIA 1's ports read from outside the chip. Port B carries the
+      # serial bus inputs and the device number jumpers (Drives::Engine::SerialLines);
+      # port A goes to the unused parallel header and floats high.
+      class SerialPort
+        include Engine::SerialLines
+
+        def initialize(device: 8, bus: SerialBus.new)
+          init_serial_lines(device, bus)
+        end
+
+        def read_a(_lines) = 0xff
+      end
+    end
+  end
+end

data/lib/badline/drives/model1541/track.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Badline
+  module Drives
+    class Model1541
+      # One ring of flux on the disk, as the GCR bytes the head reads from it,
+      # most significant bit first, and the speed zone it was written in
+      # (0-3). The bytes wrap around: the last one's bits run into the
+      # first's. A track is as long as its bytes, which is what a .g64 image
+      # stores for each half track.
+      #
+      # The disk turns at 300 rpm, so every track passes under the head in
+      # the same 200 ms, and its bits pass at the rate they were written at.
+      # Each bit is a cell of time, starting at the track's index angle with
+      # the first byte's top bit, and a 1 bit is a flux transition at the
+      # start of its cell. The cells are spread evenly over the turn, so a
+      # track as long as a turn holds at its zone's rate
+      # (Disk::TRACK_LENGTHS) passes at that rate, within the part of a byte
+      # the length rounds off, and a longer or shorter one faster or slower.
+      # A .g64 speed map gives each byte the zone it was written in, and the
+      # cells of each byte are as wide as their zone's, scaled together to
+      # fill the turn.
+      #
+      # Times are in TICKs, 1/65536 of a tick of the drive's 16 MHz crystal,
+      # so the cells add up to a turn within a tick.
+      class Track
+        TICK = 1 << 16
+        TURN = 200_000 * 16 * TICK
+
+        # A bit cell at the zone's rate, in TICKs.
+        def self.cell(zone) = 4 * (16 - zone) * TICK
+
+        attr_reader :bytes, :zone, :speeds, :width, :widths
+
+        # +speeds+ holds each byte's zone, where the track's rate changes
+        # along it.
+        def initialize(bytes, zone, speeds = nil)
+          @bytes = bytes
+          @zone = zone
+          @speeds = speeds
+          @widths = speeds && scaled_widths(speeds)
+          @width = speeds ? @widths[0] : TURN / (bytes.length * 8)
+        end
+
+        def length = @bytes.length
+
+        # Whether the whole track was written at the +zone+'s rate.
+        def written_at?(zone) = @widths.nil? && @zone == zone
+
+        # The bit cell under the head +time+ TICKs into the turn, as
+        # [byte, mask, the time the cell ends].
+        def cell_at(time)
+          start = 0
+          index = 0
+          if @widths
+            while index < length - 1 && time >= start + (@widths[index] * 8)
+              start += @widths[index] * 8
+              index += 1
+            end
+          else
+            index = [time / (@width * 8), length - 1].min
+            start = index * @width * 8
+          end
+          width = @widths ? @widths[index] : @width
+          bit = [(time - start) / width, 7].min
+          cell_end = index == length - 1 && bit == 7 ? TURN : start + ((bit + 1) * width)
+          [index, 0x80 >> bit, cell_end]
+        end
+
+        # The track laid out again as one turn at the +zone+'s rate, each
+        # flux transition in the cell under it.
+        def relaid(zone)
+          bits = Disk::TRACK_LENGTHS[zone] * 8
+          cell = TURN / bits
+          relaid = Array.new(bits / 8, 0)
+          time = 0
+          @bytes.each_with_index do |byte, index|
+            width = @widths ? @widths[index] : @width
+            8.times do |bit|
+              if byte.anybits?(0x80 >> bit)
+                cell_index = [time / cell, bits - 1].min
+                relaid[cell_index >> 3] |= 0x80 >> (cell_index & 7)
+              end
+              time += width
+            end
+          end
+          Track.new(relaid, zone)
+        end
+
+        private
+
+        def scaled_widths(speeds)
+          units = 0
+          speeds.each { |zone| units += 16 - zone }
+          speeds.map { |zone| TURN * (16 - zone) / (units * 8) }
+        end
+      end
+    end
+  end
+end