badline 0.12.0 → 0.13.0

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

@@ -0,0 +1,232 @@
+# 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
+
+        # The clock and the alarm, field by field in FIELDS order, the latch,
+        # and the divider's phase.
+        def save_state(out)
+          out.int(@accumulator).int(@pulses).int(@match).boolean(@stopped).boolean(@alarm_pending)
+          FIELDS.each { |field| out.int(@clock[field]).int(@alarm[field]) }
+          out.boolean(!@latch.nil?)
+          FIELDS.each { |field| out.int(@latch[field]) } if @latch
+        end
+
+        def load_state(input)
+          @accumulator = input.int
+          @pulses = input.int
+          @match = input.int
+          @stopped = input.boolean?
+          @alarm_pending = input.boolean?
+          FIELDS.each do |field|
+            @clock[field] = input.int
+            @alarm[field] = input.int
+          end
+          @latch = input.boolean? ? FIELDS.to_h { |field| [field, input.int] } : nil
+        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

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class CIA
+      class Timer
+        attr_accessor :counter, :latch
+        attr_reader :control, :underflowed
+
+        def initialize(control)
+          @control = control
+          @counter = @latch = 0xffff
+          @pipe = 0
+          @load_delay = 0
+          @reload = false
+          @underflowed = false
+          @oneshot_linger = 0
+          @toggle = true
+          settle
+        end
+
+        # The level this timer drives on its port B pin: a square wave that
+        # flips on each underflow, or a single high tick when one happens.
+        def output?
+          control.out_mode? ? @toggle : @underflowed
+        end
+
+        # Whether the timer is stopped with nothing in its pipeline, so a
+        # cycle changes nothing.
+        def idle? = @empty && !started?
+
+        # Whether the timer counts ø2 in continuous mode with nothing pending
+        # but the reload after an underflow, so fast_forward can run it. A
+        # latch below 2 is left out.
+        def free_running?
+          started? && !@control.run_mode? && @control.value.nobits?(0x20) && @latch >= 2 && @pipe == 0b11 &&
+            (@load_delay | @oneshot_linger).zero? && (@settled || @reload)
+        end
+
+        # Runs a free-running timer +cycles+ cycles at once, as cycle! would:
+        # an underflow every latch + 1 cycles, each one followed by the
+        # reload. Returns the underflows.
+        def fast_forward(cycles)
+          return 0 if cycles.zero?
+          return after_underflow(cycles, 0) unless @settled
+
+          if cycles < @counter
+            @counter -= cycles
+            return 0
+          end
+          after_underflow(cycles - @counter, 1)
+        end
+
+        def cycle!(feed)
+          feed &&= @control.value & 0x01 != 0
+          if @settled
+            return @counter -= 1 if feed && @counter > 1
+          elsif @empty
+            enter if feed
+            return
+          end
+          run_tick(feed)
+        end
+
+        def run_tick(feed)
+          @underflowed = false
+          @oneshot_linger -= 1 if @oneshot_linger.positive?
+          tick(feed)
+          settle
+        end
+
+        # The counter, the latch and the pipeline between them. The control
+        # register is the CIA's to save.
+        def save_state(out)
+          out.int(@counter).int(@latch).int(@pipe).int(@load_delay).boolean(@reload).boolean(@underflowed)
+          out.int(@oneshot_linger).boolean(@toggle).boolean(@settled).boolean(@empty)
+        end
+
+        def load_state(input)
+          @counter = input.int
+          @latch = input.int
+          @pipe = input.int
+          @load_delay = input.int
+          @reload = input.boolean?
+          @underflowed = input.boolean?
+          @oneshot_linger = input.int
+          @toggle = input.boolean?
+          @settled = input.boolean?
+          @empty = input.boolean?
+        end
+
+        def write_control(value)
+          @toggle = true if value.anybits?(0x01) && !started?
+          @oneshot_linger = 2 if control.run_mode? && value.nobits?(0x08)
+          control.value = value & ~0x10
+          @load_delay = 3 if value.anybits?(0x10)
+          settle
+        end
+
+        def write_latch_low(value)
+          @latch = (@latch & 0xff00) | value
+        end
+
+        def write_latch_high(value)
+          @latch = (value << 8) | (@latch & 0xff)
+          @counter = @latch unless started?
+        end
+
+        # Whether the timer's PB output toggle is high, and its count pipeline
+        # as two bits, the newer stage high.
+        attr_reader :toggle, :pipe
+
+        # Sets the control register without its load strobe, the toggle and
+        # the count pipeline, as a VICE snapshot gives them.
+        def restore_pipeline(control, toggle, pipe)
+          @control.value = control & ~0x10
+          @toggle = toggle
+          @pipe = pipe
+          settle
+        end
+
+        private
+
+        def started?
+          @control.value & 0x01 != 0
+        end
+
+        # Where fast_forward lands +cycles+ after an underflow, with
+        # +underflows+ underflows counted so far.
+        def after_underflow(cycles, underflows)
+          periods, rest = cycles.divmod(@latch + 1)
+          underflows += periods
+          @toggle = !@toggle if underflows.odd?
+          @underflowed = rest.zero?
+          @reload = rest.zero?
+          @counter = @latch - (rest.zero? ? 0 : rest - 1)
+          settle
+          underflows
+        end
+
+        def enter
+          @pipe = 0b10
+          @empty = false
+        end
+
+        # With no load, reload or one-shot linger pending, a full pipe only
+        # counts and an empty one only waits to be fed.
+        def settle
+          quiet = (@load_delay | @oneshot_linger).zero? && !@reload
+          @settled = quiet && @pipe == 0b11
+          @empty = quiet && @pipe.zero?
+        end
+
+        def tick(feed)
+          counting = @pipe.anybits?(0b01)
+          @pipe = (@pipe >> 1) | (feed ? 0b10 : 0)
+          loading = @reload || @load_delay == 1
+          @reload = false
+
+          if loading
+            reload
+          elsif premature_underflow?
+            underflow
+          elsif counting
+            count
+          end
+
+          forced_load
+        end
+
+        def forced_load
+          return unless @load_delay.positive?
+
+          @load_delay -= 1
+          @counter = @latch if @load_delay == 1
+        end
+
+        # the final pipeline stage, before any pending load lands
+        def premature_underflow?
+          @counter.zero? && @pipe.anybits?(0b01) && started?
+        end
+
+        # A load consumes its tick, so the counter never decrements on it
+        def reload
+          @counter = @latch
+          # A zero latch underflows again on the reload tick while running
+          underflow if @counter.zero? && started? && @pipe.anybits?(0b01)
+        end
+
+        def count
+          @counter -= 1 if @counter.positive?
+          underflow if @counter.zero? && @pipe.anybits?(0b01)
+        end
+
+        def underflow
+          @underflowed = true
+          @reload = true
+          @counter = @latch
+          @toggle = !@toggle
+          return unless control.run_mode? || @oneshot_linger.positive?
+
+          control.start = false
+          @pipe = 0
+        end
+      end
+    end
+  end
+end