badline 0.12.1 → 0.14.0

data/lib/badline/chips/cia/keyed_parts.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class CIA
+      class Timer
+        # A timer's fields in a keyed snapshot module (Snapshot::Keyed),
+        # under `prefix`: the counter, the latch and the pipeline between
+        # them. The fast-path flags are worked out again on load.
+        module KeyedState
+          def save_fields(out, prefix)
+            out.int("#{prefix}counter", @counter).int("#{prefix}latch", @latch).int("#{prefix}pipe", @pipe)
+            out.int("#{prefix}load_delay", @load_delay).bool("#{prefix}reload", @reload)
+            out.bool("#{prefix}underflowed", @underflowed).int("#{prefix}oneshot_linger", @oneshot_linger)
+            out.bool("#{prefix}toggle", @toggle)
+          end
+
+          def load_fields(input, prefix)
+            @counter = input.word("#{prefix}counter", @counter)
+            @latch = input.word("#{prefix}latch", @latch)
+            @pipe = input.masked("#{prefix}pipe", @pipe, 0b11)
+            @load_delay = input.int("#{prefix}load_delay", @load_delay)
+            @reload = input.bool("#{prefix}reload", @reload)
+            @underflowed = input.bool("#{prefix}underflowed", @underflowed)
+            @oneshot_linger = input.int("#{prefix}oneshot_linger", @oneshot_linger)
+            @toggle = input.bool("#{prefix}toggle", @toggle)
+          end
+
+          def restored! = settle
+        end
+
+        include KeyedState
+      end
+
+      class InterruptRegister
+        # The interrupt register's fields in a keyed snapshot module, under
+        # `prefix`: the mask, the flags, an assert on its way and the reads
+        # whose acknowledge is still landing.
+        module KeyedState
+          def save_fields(out, prefix)
+            out.int("#{prefix}mask", @mask.value).int("#{prefix}status", @status.value)
+            out.int("#{prefix}pending", @pending)
+            out.optional_int("#{prefix}read", @read).optional_int("#{prefix}read_last_cycle", @read_last_cycle)
+            out.optional_int("#{prefix}read_two_cycles_ago", @read_two_cycles_ago)
+            out.bool("#{prefix}timer_b_bug", @timer_b_bug)
+          end
+
+          def load_fields(input, prefix)
+            @mask.value = input.byte("#{prefix}mask", @mask.value)
+            @status.value = input.byte("#{prefix}status", @status.value)
+            @pending = input.int("#{prefix}pending", @pending)
+            @read = input.optional_int("#{prefix}read")
+            @read_last_cycle = input.optional_int("#{prefix}read_last_cycle")
+            @read_two_cycles_ago = input.optional_int("#{prefix}read_two_cycles_ago")
+            @timer_b_bug = input.bool("#{prefix}timer_b_bug", @timer_b_bug)
+          end
+
+          # Quiet when nothing is due and no read is recent enough to matter.
+          def restored!
+            @quiet = @pending.zero? && @read.nil? && @read_last_cycle.nil? && @read_two_cycles_ago.nil?
+          end
+        end
+
+        include KeyedState
+      end
+
+      class Serial
+        # The serial port's fields in a keyed snapshot module, under
+        # `prefix`: the registers, the bit count, the delay lines, the CNT
+        # and SP levels, and whether the next cycle can be skipped, which
+        # can lag what the delay lines show by a cycle.
+        module KeyedState
+          def save_fields(out, prefix)
+            out.int("#{prefix}data", @data).int("#{prefix}shift", @shift).int("#{prefix}steps", @steps)
+            out.optional_int("#{prefix}empty_in", @empty_in).optional_int("#{prefix}busy_in", @busy_in)
+            out.bool("#{prefix}busy", @busy).bool("#{prefix}abandoned", @abandoned)
+            out.optional_int("#{prefix}pending", @pending).bool("#{prefix}underflow_high", @underflow_high)
+            out.bool("#{prefix}in_flight", @in_flight).int("#{prefix}flight_up", @flight_up)
+            out.int("#{prefix}flight_down", @flight_down).bool("#{prefix}cnt", @cnt).bool("#{prefix}cnt_in", @cnt_in)
+            out.bool("#{prefix}sp_in", @sp_in).bool("#{prefix}sp_out", @sp_out).bool("#{prefix}idle", @idle)
+          end
+
+          def load_fields(input, prefix)
+            @data = input.byte("#{prefix}data", @data)
+            @shift = input.byte("#{prefix}shift", @shift)
+            @steps = input.int("#{prefix}steps", @steps)
+            @empty_in = input.optional_int("#{prefix}empty_in")
+            @busy_in = input.optional_int("#{prefix}busy_in")
+            @busy = input.bool("#{prefix}busy", @busy)
+            @abandoned = input.bool("#{prefix}abandoned", @abandoned)
+            @pending = input.optional_int("#{prefix}pending")
+            load_line_fields(input, prefix)
+          end
+
+          def restored! = nil
+
+          private
+
+          def load_line_fields(input, prefix)
+            @underflow_high = input.bool("#{prefix}underflow_high", @underflow_high)
+            @in_flight = input.bool("#{prefix}in_flight", @in_flight)
+            @flight_up = input.int("#{prefix}flight_up", @flight_up)
+            @flight_down = input.int("#{prefix}flight_down", @flight_down)
+            @cnt = input.bool("#{prefix}cnt", @cnt)
+            @cnt_in = input.bool("#{prefix}cnt_in", @cnt_in)
+            @sp_in = input.bool("#{prefix}sp_in", @sp_in)
+            @sp_out = input.bool("#{prefix}sp_out", @sp_out)
+            @idle = input.bool("#{prefix}idle", @idle)
+          end
+        end
+
+        include KeyedState
+      end
+
+      class TimeOfDay
+        # The TOD clock's fields in a keyed snapshot module, under `prefix`:
+        # the clock, the alarm and a latched read field by field, the
+        # pulses towards the next tenth, and the mains divider's phase in
+        # cycle·Hz (it reaches the clock rate when a pulse arrives). The
+        # 50/60 Hz divider comes from CRA bit 7 on load.
+        module KeyedState
+          def save_fields(out, prefix)
+            out.int("#{prefix}mains_phase", @accumulator).int("#{prefix}pulses", @pulses)
+            out.bool("#{prefix}stopped", @stopped).bool("#{prefix}alarm_pending", @alarm_pending)
+            FIELDS.each do |field|
+              out.int("#{prefix}clock.#{field}", @clock[field]).int("#{prefix}alarm.#{field}", @alarm[field])
+            end
+            latch = @latch
+            FIELDS.each { |field| out.int("#{prefix}latch.#{field}", latch[field]) } if latch
+          end
+
+          def load_fields(input, prefix)
+            @accumulator = input.int("#{prefix}mains_phase", @accumulator)
+            @pulses = input.int("#{prefix}pulses", @pulses)
+            @stopped = input.bool("#{prefix}stopped", @stopped)
+            @alarm_pending = input.bool("#{prefix}alarm_pending", @alarm_pending)
+            FIELDS.each do |field|
+              @clock[field] = input.byte("#{prefix}clock.#{field}", @clock[field])
+              @alarm[field] = input.byte("#{prefix}alarm.#{field}", @alarm[field])
+            end
+            load_latch_fields(input, prefix)
+          end
+
+          def restored!(fifty_hz)
+            self.fifty_hz = fifty_hz
+          end
+
+          private
+
+          def load_latch_fields(input, prefix)
+            return @latch = nil if input.optional_int("#{prefix}latch.hours").nil?
+
+            @latch = FIELDS.to_h { |field| [field, input.byte("#{prefix}latch.#{field}", 0)] }
+          end
+        end
+
+        include KeyedState
+      end
+
+      # The CIA's fields in a keyed snapshot module (Snapshot::Keyed): the
+      # ports, the control registers, the PB4 and CNT levels, and its parts
+      # under ta., tb., icr., sdr. and tod.
+      module KeyedState
+        def save_fields(out)
+          out.int("pra", @data_port_a).int("prb", @data_port_b).int("ddra", @data_dir_a).int("ddrb", @data_dir_b)
+          out.int("cra", @control_a.value).int("crb", @control_b.value)
+          out.bool("pb4_high", @port_b4_high).bool("pb4_driven_high", @port_b4_driven_high)
+          out.bool("cnt_high", @cnt_high).bool("cnt_rise", @cnt_rise)
+          @ta.save_fields(out, "ta.")
+          @tb.save_fields(out, "tb.")
+          @icr.save_fields(out, "icr.")
+          @serial.save_fields(out, "sdr.")
+          @tod.save_fields(out, "tod.")
+          out
+        end
+
+        def load_fields(input)
+          @data_port_a = input.byte("pra", @data_port_a)
+          @data_port_b = input.byte("prb", @data_port_b)
+          @data_dir_a = input.byte("ddra", @data_dir_a)
+          @data_dir_b = input.byte("ddrb", @data_dir_b)
+          @control_a.value = input.byte("cra", @control_a.value)
+          @control_b.value = input.byte("crb", @control_b.value)
+          @port_b4_high = input.bool("pb4_high", @port_b4_high)
+          @port_b4_driven_high = input.bool("pb4_driven_high", @port_b4_driven_high)
+          @cnt_high = input.bool("cnt_high", @cnt_high)
+          @cnt_rise = input.bool("cnt_rise", @cnt_rise)
+          load_part_fields(input)
+        end
+
+        def restored!
+          @ta.restored!
+          @tb.restored!
+          @icr.restored!
+          @serial.restored!
+          @tod.restored!(@control_a.clock_frequency?)
+        end
+
+        private
+
+        def load_part_fields(input)
+          @ta.load_fields(input, "ta.")
+          @tb.load_fields(input, "tb.")
+          @icr.load_fields(input, "icr.")
+          @serial.load_fields(input, "sdr.")
+          @tod.load_fields(input, "tod.")
+        end
+      end
+
+      include KeyedState
+    end
+  end
+end

data/lib/badline/chips/cia/serial.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class CIA
+      # The serial shift register and the CNT line that clocks it.
+      #
+      # With CRA bit 6 clear the port is an input: SP is sampled on every
+      # rising CNT edge, and the byte reaches the data register after eight of
+      # them. With the bit set the CIA drives CNT itself, toggling it on every
+      # timer A underflow, so a byte takes sixteen underflows to go out. CNT falls
+      # as each bit is put on SP, and rises again to clock it in.
+      #
+      # The register counts itself empty as soon as the eighth bit is on SP,
+      # fifteen underflows in: the serial flag follows a few cycles later
+      # rather than waiting for the sixteenth underflow, and a byte written
+      # from that point on goes out on the next one.
+      class Serial
+        BITS = 8
+
+        # A byte written to the data register reaches the shift register one
+        # cycle later. The empty countdown starts on the underflow that puts
+        # the eighth bit on SP and is decremented on that same cycle, so the
+        # flag lands four cycles after it.
+        LOAD_DELAY = 1
+        EMPTY_DELAY = 5
+        BUSY_DELAY = 5
+
+        # The logic watching the shift register runs a few cycles behind it,
+        # so the level saying a bit is still on its way out is scheduled
+        # through a delay line: a bit set at position 7 - n takes effect n
+        # cycles later. Putting a bit on SP raises the level after one cycle
+        # and drops it again after two before raising it for good after
+        # three; the eighth bit skips straight to the last of those. CNT
+        # rising over a bit lowers the level four cycles later.
+        IN_FLIGHT = 0x50
+        LAST_IN_FLIGHT = 0x10
+        BOUNCE = 0x20
+        SETTLED = 0x08
+
+        attr_reader :data, :sp_out, :cnt, :cnt_in, :idle
+        attr_accessor :sp_in
+
+        def initialize(control)
+          @control = control
+          @data = 0x0
+          @shift = 0x0
+          @steps = 0
+          @empty_in = nil
+          @busy_in = nil
+          @busy = false
+          @abandoned = false
+          @pending = nil
+          @underflow_high = false
+          @in_flight = false
+          @flight_up = 0x0
+          @flight_down = 0x0
+          @idle = true
+          # Nothing drives the user port, so both lines float high.
+          @cnt = true
+          @cnt_in = true
+          @sp_in = true
+          @sp_out = true
+        end
+
+        # The bits shifted so far, and the byte waiting to go out after the
+        # one shifting.
+        attr_reader :steps, :pending
+
+        def shift_register = @shift
+
+        # Sets the data register and the shift register, as a VICE snapshot
+        # gives them.
+        def restore_shift(data, shift)
+          @data = data
+          @shift = shift
+        end
+
+        def output?
+          @control.serial_mode?
+        end
+
+        # Whether nothing is counting down or in the delay lines, so only
+        # timer A's underflows reach the register.
+        def drained? = idle?
+
+        # Takes timer A's underflow line as cycle! would have left it, with
+        # +underflowed+ its level on the last cycle, for a CIA run without
+        # the register in use (CIA#fast_forward).
+        def follow_underflow(underflowed)
+          @underflow_high = underflowed
+          @idle = !underflowed
+        end
+
+        def cnt_in=(level)
+          @cnt_in = level
+          @cnt = level unless output?
+        end
+
+        def write(value)
+          @data = value
+          @pending = LOAD_DELAY
+          @idle = false
+        end
+
+        # Clocked every cycle with timer A's underflow line. Yields once the
+        # shift register reports itself empty, which it does without waiting
+        # for the underflow that raises CNT over the eighth bit.
+        def cycle!(underflowed)
+          return if @idle && !underflowed
+
+          shift(underflowed)
+          @pending -= 1 if @pending&.positive?
+          drain_flight
+          count_busy
+          @idle = !underflowed && idle?
+          return if @empty_in.nil?
+
+          @empty_in -= 1
+          return unless @empty_in.zero?
+
+          @empty_in = nil
+          @busy = false
+          yield
+        end
+
+        # Clocked by rising CNT edges while receiving. Yields once a whole
+        # byte has arrived.
+        def rising_edge!
+          return if output?
+
+          @shift = ((@shift << 1) | (@sp_in ? 1 : 0)) & 0xff
+          @steps += 1
+          return unless @steps == BITS
+
+          @steps = 0
+          @data = @shift
+          yield if block_given?
+        end
+
+        # A mode change drops the byte in flight and hands CNT back to
+        # whichever side drives it now, and yields: that byte counts as gone.
+        # Handing the port over as an input tears a transmission down, so a
+        # busy register reports it; the same change latches how far the bit
+        # in flight had got, and taking the port back reports that.
+        def reset!
+          abandoned = output? ? @abandoned : @busy
+          @abandoned = output? ? false : @in_flight
+          @in_flight = false
+          @steps = 0
+          @empty_in = nil
+          @busy_in = nil
+          @busy = false
+          @pending = nil
+          @cnt = output? || @cnt_in
+          yield if abandoned
+        end
+
+        private
+
+        # Without an underflow, a register with nothing counting down and
+        # nothing in the delay lines has nothing to do on a cycle.
+        def idle?
+          !@pending&.positive? && (@flight_up | @flight_down).zero? &&
+            @busy_in.nil? && @empty_in.nil?
+        end
+
+        # The shift register picks up a waiting byte whenever the underflow
+        # line is asserted, but every half-step after that needs a fresh edge
+        # on it. A zero latch holds the line down for good rather than
+        # pulsing it, so such a byte stops after its first bit and never
+        # reaches the data register.
+        def shift(underflowed)
+          edge = underflowed && !@underflow_high
+          @underflow_high = underflowed
+          clock(edge) if underflowed && output?
+        end
+
+        def clock(edge)
+          start if @steps <= 1
+          if @steps.zero?
+            @flight_down |= SETTLED
+          elsif edge || @steps == BITS * 2
+            half_step
+          end
+        end
+
+        def half_step
+          @steps -= 1
+          @cnt = @steps.even?
+          if @cnt
+            @flight_down |= SETTLED
+          else
+            shift_out
+          end
+        end
+
+        # The register reads as busy from a few cycles after the first bit
+        # reaches SP until it reports itself empty over the eighth.
+        def mark_busy
+          case @steps
+          when (BITS * 2) - 1 then @busy_in = BUSY_DELAY
+          when 1
+            @empty_in = EMPTY_DELAY
+            @busy_in = nil
+          end
+        end
+
+        def count_busy
+          return if @busy_in.nil?
+
+          @busy_in -= 1
+          return unless @busy_in.zero?
+
+          @busy_in = nil
+          @busy = true
+        end
+
+        def drain_flight
+          @in_flight = false if @flight_down.anybits?(0x80)
+          @flight_down = (@flight_down << 1) & 0xff
+          @in_flight = true if @flight_up.anybits?(0x80)
+          @flight_up = (@flight_up << 1) & 0xff
+        end
+
+        # A byte only moves out of the data register once the one before it
+        # has put its last bit on SP.
+        def start
+          return unless @pending&.zero?
+
+          @pending = nil
+          @shift = @data
+          @steps = BITS * 2
+        end
+
+        def shift_out
+          @sp_out = @shift.anybits?(0x80)
+          @shift = (@shift << 1) & 0xff
+          mark_busy
+          @flight_up |= @steps == 1 ? LAST_IN_FLIGHT : IN_FLIGHT
+          @flight_down |= BOUNCE
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/cia/time_of_day.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class CIA
+      class TimeOfDay
+        # The TOD pin is fed from the AC supply. A CIA passes its region's
+        # clock and mains frequency, and these are PAL's.
+        CLOCK_HZ = Region::PAL.clock_hz
+        MAINS_HZ = Region::PAL.mains_hz
+
+        FIELDS = %i[tenths seconds minutes hours].freeze
+
+        def initialize(clock_hz: CLOCK_HZ, mains_hz: MAINS_HZ)
+          # The accumulator advances mains_hz per cycle, so a TOD pin pulse has
+          # arrived when it reaches clock_hz. Integer math keeps it exact.
+          @cycles_per_pulse = clock_hz
+          @mains_hz = mains_hz
+          @accumulator = 0
+          @pulses = 0
+          @clock = { tenths: 0x00, seconds: 0x00, minutes: 0x00, hours: 0x01 }
+          @alarm = { tenths: 0x00, seconds: 0x00, minutes: 0x00, hours: 0x00 }
+          @latch = nil
+          @stopped = true
+          @alarm_pending = false
+          self.fifty_hz = false
+        end
+
+        # CRA bit 7 divides the TOD pin by 5 instead of 6. The divider has to
+        # match the pin frequency to keep time, so PAL software selects 50 Hz.
+        def fifty_hz=(enabled)
+          @match = enabled ? 4 : 5
+        end
+
+        # Whether the clock is stopped, or gets no pulses on its pin, with no
+        # alarm to raise, so its cycles move only the divider's phase.
+        def quiet? = (@stopped || @mains_hz.zero?) && !@alarm_pending
+
+        # Runs +cycles+ quiet cycles at once.
+        def fast_forward(cycles)
+          @accumulator = (@accumulator + (cycles * @mains_hz)) % @cycles_per_pulse
+        end
+
+        def cycle!
+          @accumulator += @mains_hz
+          pulse! if @accumulator >= @cycles_per_pulse
+          return unless @alarm_pending
+
+          @alarm_pending = false
+          yield if block_given?
+        end
+
+        def tenths
+          value = (@latch || @clock)[:tenths]
+          @latch = nil
+          value
+        end
+
+        def seconds = (@latch || @clock)[:seconds]
+        def minutes = (@latch || @clock)[:minutes]
+
+        def hours
+          @latch ||= @clock.dup
+          @latch[:hours]
+        end
+
+        attr_reader :pulses
+
+        # The clock as a read of the tenths would see it: the latch while the
+        # clock is latched. In FIELDS order.
+        def latched_fields = FIELDS.map { |field| (@latch || @clock)[field] }
+
+        # The cycles until the clock next steps a tenth, as VICE counts them.
+        def cycles_to_tenth
+          to_pulse = (@cycles_per_pulse - @accumulator + @mains_hz - 1) / @mains_hz
+          to_pulse + ([@match - @pulses, 0].max * @cycles_per_pulse / @mains_hz)
+        end
+
+        # Sets the clock, the alarm and the latch from VICE's fields, in FIELDS
+        # order, the latch nil while unlatched.
+        def restore_fields(clock, alarm, latch)
+          FIELDS.each_with_index do |field, i|
+            @clock[field] = clock[i]
+            @alarm[field] = alarm[i]
+          end
+          @latch = latch && FIELDS.each_with_index.to_h { |field, i| [field, latch[i]] }
+        end
+
+        # Sets whether the clock is stopped, the pulses counted towards the
+        # next tenth and the cycles until it, placing the divider so the tenth
+        # lands then.
+        def restore_divider(stopped, pulses, cycles_to_tenth)
+          @stopped = stopped
+          @pulses = pulses
+          to_pulse = cycles_to_tenth - ([@match - pulses, 0].max * @cycles_per_pulse / @mains_hz)
+          @accumulator = (@cycles_per_pulse - (to_pulse * @mains_hz)).clamp(0, @cycles_per_pulse - 1)
+        end
+
+        # The clock and alarm as stored, read without latching the clock.
+        def registers
+          [@clock[:tenths], @clock[:seconds], @clock[:minutes], @clock[:hours],
+           @alarm[:tenths], @alarm[:seconds], @alarm[:minutes], @alarm[:hours],
+           @stopped ? 1 : 0, @latch ? 1 : 0]
+        end
+
+        def write(field, value, alarm:)
+          # The frequency counter is held clear while the clock is stopped, and
+          # starts counting again from the write to tenths that restarts it.
+          if field == :tenths && !alarm && @stopped
+            @pulses = 0
+            @stopped = false
+          end
+          store(field, value & (field == :tenths ? 0x0f : 0x7f), alarm: alarm)
+        end
+
+        # 12-hour BCD value, bit 7 is the AM/PM flag.
+        def write_hours(value, alarm:)
+          value &= 0x9f
+          # Writing 12 to the hour register flips the AM/PM bit, the same way a
+          # carry into 12 does. Writing the alarm hours does not.
+          value ^= 0x80 if !alarm && (value & 0x1f) == 0x12
+          # Halt the clock when writing hours, so that it doesn't
+          # advance mid-update.
+          @stopped = true unless alarm
+          store(:hours, value, alarm: alarm)
+        end
+
+        private
+
+        def store(field, value, alarm:)
+          target = alarm ? @alarm : @clock
+          return if target[field] == value
+
+          target[field] = value
+          @alarm_pending = true if alarm?
+        end
+
+        def pulse!
+          @accumulator -= @cycles_per_pulse
+          return if @stopped
+
+          # A three-bit ring counter with six states, compared against the
+          # divider on each pin pulse rather than on its way past it.
+          if @pulses == @match
+            @pulses = 0
+            advance
+          else
+            @pulses += 1
+            @pulses = 0 if @pulses > 5
+          end
+        end
+
+        def advance
+          tenths = (@clock[:tenths] + 1) & 0x0f
+          @clock[:tenths] = tenths == 10 ? 0 : tenths
+          carry_seconds if tenths == 10
+          @alarm_pending = true if alarm?
+        end
+
+        def carry_seconds
+          return unless advance_pair(:seconds)
+          return unless advance_pair(:minutes)
+
+          advance_hours
+        end
+
+        # Seconds and minutes hold a four-bit low digit that carries at ten into
+        # a three-bit high digit that carries out at six. Both are plain binary
+        # counters, so out-of-range BCD counts up from where it was written.
+        def advance_pair(field)
+          low = ((@clock[field] & 0x0f) + 1) & 0x0f
+          high = (@clock[field] >> 4) & 0x07
+          carry = false
+
+          if low == 10
+            low = 0
+            high = (high + 1) & 0x07
+            if high == 6
+              high = 0
+              carry = true
+            end
+          end
+
+          @clock[field] = (high << 4) | low
+          carry
+        end
+
+        # The hour runs 9 -> 10 and 12 -> 1 by swapping its two digits, and the
+        # AM/PM bit flips as it passes through 12.
+        def advance_hours
+          pm = @clock[:hours] & 0x80
+          high = (@clock[:hours] >> 4) & 0x01
+          low = @clock[:hours] & 0x0f
+
+          if (high == 1 && low == 2) || (high.zero? && low == 9)
+            low = high
+            high ^= 1
+          else
+            low = (low + 1) & 0x0f
+            pm ^= 0x80 if high == 1 && low == 2
+          end
+
+          @clock[:hours] = pm | (high << 4) | low
+        end
+
+        def alarm? = @clock == @alarm
+      end
+    end
+  end
+end