badline 0.12.1 → 0.13.0

data/lib/badline/chips/via/shift_register.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class VIA
+      # The 6522's shift register, with the CB1 clock and CB2 data lines it
+      # takes over in every mode but the first.
+      #
+      # ACR bits 4-2 pick the mode. Modes 1 to 3 shift in, left, with the new
+      # bit taken from CB2 into bit 0 on each rising CB1 edge. Modes 4 to 7
+      # shift out: each falling CB1 edge puts bit 7 on CB2 and rotates it back
+      # round into bit 0, so after eight bits the byte is back where it
+      # started. Modes 1, 4 and 5 clock off timer 2, modes 2 and 6 off φ2, and
+      # modes 3 and 7 off whatever drives CB1 from outside.
+      #
+      # Under its own clock the register drives CB1, idling high. Reading or
+      # writing the data register starts a byte, but only while the register
+      # is idle and enabled: an access in mode 0, or one before the eighth bit
+      # is in, leaves the count alone. CB1 falls on the first clock tick of
+      # the byte and rises on the second, and so on, so a byte is eight pulses
+      # over sixteen ticks. The interrupt flag is set on the tick that raises
+      # CB1 over the eighth bit, and CB1 then stays high until the next
+      # access.
+      #
+      # In modes 2 and 6 a tick is a φ2 cycle, from the second cycle after
+      # the access on, which makes a byte sixteen cycles. In modes 1, 4 and 5
+      # it comes two cycles after each timer 2 low byte underflow, on the
+      # cycle after the low byte reloads, which makes a byte sixteen
+      # underflows. Mode 4 never stops and never interrupts: its counter is
+      # disabled, and the byte goes round and round.
+      #
+      # Under an external clock the register shifts on every CB1 edge, access
+      # or not. The access only arms the counter: the flag is set on the eighth
+      # rising edge after it, and the counter then waits for the next access.
+      class ShiftRegister
+        DISABLED = 0
+        IN_T2 = 1
+        IN_PHI2 = 2
+        IN_EXTERNAL = 3
+        OUT_FREE_RUNNING = 4
+        OUT_T2 = 5
+        OUT_PHI2 = 6
+        OUT_EXTERNAL = 7
+
+        attr_reader :mode, :data
+        attr_accessor :cb2_input
+
+        def initialize
+          @mode = DISABLED
+          @data = 0x00
+          # Bits still to count before the flag, zero when the counter is idle.
+          @bits = 0
+          # The clock's last two cycles, newest in bit 0: timer 2 low byte
+          # underflows in modes 1, 4 and 5, and whether the byte has started
+          # in modes 2 and 6.
+          @delay = 0
+          @clock = true
+          @cb2 = true
+          # Nothing drives CB2 from outside, so it floats high.
+          @cb2_input = true
+        end
+
+        def mode=(value)
+          @mode = value & 0x07
+        end
+
+        def data=(value)
+          @data = value & 0xff
+        end
+
+        # A read or write of the data register, which starts a byte if the
+        # register is idle and enabled.
+        def access!
+          return if @mode == DISABLED || @bits.nonzero?
+
+          @bits = 8
+          @delay = 0 if @mode == IN_PHI2 || @mode == OUT_PHI2
+        end
+
+        # Whether the register is counting bits off its own clock, which
+        # changes it from cycle to cycle.
+        def clocking? = @bits.nonzero? && internal_clock?
+
+        def save_state(out)
+          out.int(@mode).int(@data).int(@bits).int(@delay).boolean(@clock).boolean(@cb2).boolean(@cb2_input)
+        end
+
+        def load_state(input)
+          @mode = input.int
+          @data = input.int
+          @bits = input.int
+          @delay = input.int
+          @clock = input.boolean?
+          @cb2 = input.boolean?
+          @cb2_input = input.boolean?
+        end
+
+        # Everything the register holds, for comparing it at two points.
+        def state = [@mode, @data, @bits, @delay, @clock, @cb2, @cb2_input]
+
+        # The CB1 level the register drives, or nil when CB1 is an input.
+        def cb1_output
+          internal_clock? ? @clock : nil
+        end
+
+        # The CB2 level the register drives, or nil when it doesn't.
+        def cb2_output
+          @mode >= OUT_FREE_RUNNING ? @cb2 : nil
+        end
+
+        # Clocked once per φ2 cycle, with whether timer 2's low byte underflowed
+        # on it. Returns true on the cycle that sets the interrupt flag.
+        def cycle!(t2_low_underflow)
+          case @mode
+          when IN_PHI2, OUT_PHI2 then @bits.nonzero? && phi2_tick
+          when IN_T2, OUT_T2, OUT_FREE_RUNNING then t2_tick(t2_low_underflow)
+          else false
+          end
+        end
+
+        # A level change on CB1 from outside. Only the external clock modes
+        # listen: shifting in samples CB2 as CB1 rises, and shifting out puts
+        # the next bit on CB2 as it falls. Returns true when the edge sets the
+        # interrupt flag.
+        def cb1_edge!(rising)
+          return false unless @mode == IN_EXTERNAL || @mode == OUT_EXTERNAL
+
+          shift_in if rising && @mode == IN_EXTERNAL
+          shift_out if !rising && @mode == OUT_EXTERNAL
+          rising && eighth_bit?
+        end
+
+        private
+
+        def internal_clock?
+          @mode != DISABLED && @mode != IN_EXTERNAL && @mode != OUT_EXTERNAL
+        end
+
+        # A φ2 cycle of a byte: every one but the first ticks.
+        def phi2_tick
+          started = @delay.nonzero?
+          @delay = 1
+          started && tick
+        end
+
+        # Ticks on the underflow from two cycles back, while a byte is under
+        # way.
+        def t2_tick(underflow)
+          due = @delay.anybits?(2)
+          @delay = ((@delay << 1) & 2) | (underflow ? 1 : 0)
+          due && @bits.nonzero? && tick
+        end
+
+        # One half period of the register's own clock: a falling edge puts a
+        # bit out, and a rising one takes a bit in and counts it.
+        def tick
+          @clock = !@clock
+          shift_out if !@clock && @mode >= OUT_FREE_RUNNING
+          shift_in if @clock && @mode < IN_EXTERNAL
+          @clock && @mode != OUT_FREE_RUNNING && eighth_bit?
+        end
+
+        # Counts a bit, and says whether it was the eighth since the access.
+        def eighth_bit?
+          return false if @bits.zero?
+
+          @bits -= 1
+          @bits.zero?
+        end
+
+        def shift_in
+          @data = ((@data << 1) | (@cb2_input ? 1 : 0)) & 0xff
+        end
+
+        def shift_out
+          @cb2 = @data.anybits?(0x80)
+          @data = ((@data << 1) | (@cb2 ? 1 : 0)) & 0xff
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/via/timer1.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class VIA
+      # Timer 1: a 16-bit counter that decrements on every φ2 cycle, with a
+      # latch it reloads from on every timeout and the PB7 output.
+      #
+      # Writing the high counter byte loads the counter on the cycle after,
+      # so a timer loaded with N reads N, N-1, ... 0 and then $FFFF, which is
+      # the cycle its interrupt flag sets: N + 1.5 cycles after the write in
+      # the datasheet's terms. The counter then reloads from the latch on the
+      # next cycle, which makes the period N + 2 cycles. It does so in one-shot
+      # mode too, unlike timer 2.
+      #
+      # Only a write of the high counter byte arms the timer. An armed timeout
+      # sets the flag and inverts PB7, and in one-shot mode disarms it, so the
+      # first timeout after the load alone does. Free-running keeps it armed,
+      # but switching to free-running doesn't arm it: an unarmed timer counts
+      # and reloads without touching the flag or PB7. The load pulls PB7 low,
+      # and ACR bit 7 turning on drives it high, so a timer loaded before its
+      # PB7 output is enabled reads high until the timeout pulls it low.
+      class Timer1
+        attr_accessor :counter, :latch
+
+        # The level the timer drives on PB7 when ACR bit 7 hands it the pin.
+        attr_reader :pb7
+
+        # ACR bit 7 turning on hands PB7 to the timer high.
+        def pb7_enabled!
+          @pb7 = true
+        end
+
+        def initialize
+          @counter = @latch = 0xffff
+          @reload = @hold = false
+          @armed = false
+          @pb7 = true
+        end
+
+        def write_latch_low(value)
+          @latch = (@latch & 0xff00) | value
+        end
+
+        def write_latch_high(value)
+          @latch = (value << 8) | (@latch & 0xff)
+        end
+
+        # The high counter byte write: load from the latch, hold the count
+        # for a cycle, arm the interrupt and pull PB7 low.
+        def start!
+          @counter = @latch
+          @hold = true
+          @reload = false
+          @armed = true
+          @pb7 = false
+        end
+
+        # One φ2 cycle. Returns true on the cycle that sets the interrupt flag.
+        def cycle!(free_run)
+          if @hold || @reload
+            @counter = @latch if @reload
+            @hold = @reload = false
+            return false
+          end
+          @counter = (@counter - 1) & 0xffff
+          @counter == 0xffff && timeout(free_run)
+        end
+
+        # How many cycles the timer can run without setting its flag: until
+        # an armed timer's timeout, and forever for an unarmed one, whose
+        # timeouts only reload the counter. None while an armed timer loads
+        # or reloads.
+        def quiet_cycles
+          return FastForward::QUIET unless @armed
+          return 0 if @hold || @reload
+
+          @counter
+        end
+
+        # Runs +cycles+ cycles at once, as many as quiet_cycles allows. An
+        # unarmed timer goes round its period of latch + 2 cycles: the
+        # timeout at $FFFF, the reload, and latch down to 0.
+        def fast_forward(cycles)
+          if @hold || @reload
+            cycle!(false)
+            cycles -= 1
+          end
+          return @counter -= cycles if cycles <= @counter
+
+          phase = (cycles - @counter - 1) % (@latch + 2)
+          @reload = phase.zero?
+          @counter = @reload ? 0xffff : @latch - phase + 1
+        end
+
+        def save_state(out)
+          out.int(@counter).int(@latch).boolean(@hold).boolean(@reload).boolean(@armed).boolean(@pb7)
+        end
+
+        def load_state(input)
+          @counter = input.int
+          @latch = input.int
+          @hold = input.boolean?
+          @reload = input.boolean?
+          @armed = input.boolean?
+          @pb7 = input.boolean?
+        end
+
+        # What the counter and PB7 don't hold, for comparing the timer at two
+        # points.
+        def state = [@latch, @armed]
+
+        # Whether a timeout sets the flag.
+        def armed? = @armed
+
+        # The count, for comparing the timer at two points where it matters.
+        def count_state = [@counter, @hold, @reload]
+
+        private
+
+        # The counter reloads either way. Armed, PB7 inverts and the flag
+        # sets, and one-shot mode disarms. Returns whether the flag sets.
+        def timeout(free_run)
+          interrupt = @armed
+          @reload = true
+          @pb7 = !@pb7 if @armed
+          @armed &&= free_run
+          interrupt
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/via/timer2.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class VIA
+      # Timer 2: a one-shot 16-bit counter that decrements on every φ2 cycle,
+      # or on every falling edge of PB6 when ACR bit 5 sets it counting pulses.
+      # Only its low byte has a latch.
+      #
+      # Timed, it follows timer 1's one-shot timing: loaded with N it reads N
+      # on the cycle after the write, and sets its flag on the cycle it rolls
+      # from 0 to $FFFF. Where timer 1 would reload, it rolls on down without
+      # further interrupts until the next load. Counting pulses, the flag sets
+      # on the pulse that takes it past zero, the N + 1st: the datasheet's
+      # "reaches zero" is the same underflow it means in timed mode.
+      #
+      # While the shift register clocks off it, the low byte also counts as
+      # an 8-bit timer of its own: on each low byte underflow it reloads from
+      # the latch on the next cycle, which makes the shift clock's half period
+      # N + 2 cycles. The borrow still reaches the high byte.
+      #
+      # ACR bit 5 reaches the count input a cycle after the write, so the
+      # counter takes one more step in the mode it leaves.
+      class Timer2
+        attr_accessor :counter, :latch_low
+
+        # ACR bit 5, which picks PB6 pulses over φ2.
+        attr_writer :count_pulses
+
+        # Whether the low byte underflowed on the last cycle.
+        attr_reader :low_underflowed
+
+        def initialize
+          @counter = 0xffff
+          @latch_low = 0xff
+          @hold = false
+          @low_reload = false
+          @armed = false
+          @low_underflowed = false
+          @count_pulses = @counting_pulses = false
+        end
+
+        # The high counter byte write: load the counter with it and the low
+        # latch, arm the interrupt and hold the count for a cycle.
+        def load(high)
+          @counter = (high << 8) | @latch_low
+          @hold = true
+          @low_reload = false
+          @armed = true
+        end
+
+        # One φ2 cycle, with whether the shift register clocks off the low
+        # byte. Returns true on the cycle that sets the flag.
+        def cycle!(sr_service)
+          pulses = @counting_pulses
+          @counting_pulses = @count_pulses
+          return idle! if pulses || @hold
+
+          @low_underflowed = @counter.nobits?(0xff)
+          @hold = @low_reload = sr_service && @low_underflowed
+          decrement
+        end
+
+        # A falling edge on PB6. Returns true when it sets the flag.
+        def pulse! = @counting_pulses && decrement
+
+        # How many cycles the timer can run without setting its flag, taken
+        # without the shift register clocking off it: until an armed timer
+        # underflows, and forever for one counting pulses or unarmed, which
+        # only rolls on. None while a load or a switch of mode is under way.
+        def quiet_cycles
+          return 0 if @hold || @counting_pulses != @count_pulses
+          return FastForward::QUIET if @counting_pulses || !@armed
+
+          @counter
+        end
+
+        # Runs +cycles+ cycles at once, as many as quiet_cycles allows. The
+        # low byte's underflow is set when the last cycle took it from $00.
+        def fast_forward(cycles)
+          @low_underflowed = false
+          return if @counting_pulses
+
+          @counter = (@counter - cycles) & 0xffff
+          @low_underflowed = @counter.allbits?(0xff)
+        end
+
+        def save_state(out)
+          out.int(@counter).int(@latch_low)
+          [@hold, @low_reload, @armed, @low_underflowed, @count_pulses, @counting_pulses].each do |flag|
+            out.boolean(flag)
+          end
+        end
+
+        def load_state(input)
+          @counter = input.int
+          @latch_low = input.int
+          @hold = input.boolean?
+          @low_reload = input.boolean?
+          @armed = input.boolean?
+          @low_underflowed = input.boolean?
+          @count_pulses = input.boolean?
+          @counting_pulses = input.boolean?
+        end
+
+        # What the counter and the low byte's underflow don't hold, for
+        # comparing the timer at two points.
+        def state = [@latch_low, @armed, @hold, @low_reload, @count_pulses, @counting_pulses]
+
+        # Whether the next underflow sets the flag.
+        def armed? = @armed
+
+        # The count, for comparing the timer at two points where it matters.
+        def count_state = [@counter, @low_underflowed]
+
+        private
+
+        # A cycle while counting pulses, or held after a load or a low byte
+        # underflow: the counter stands still, but the hold still ends, so
+        # none carries over into timed mode.
+        def idle!
+          @counter = (@counter & 0xff00) | @latch_low if @low_reload
+          @hold = @low_reload = @low_underflowed = false
+        end
+
+        def decrement
+          @counter = (@counter - 1) & 0xffff
+          interrupt = @armed && @counter == 0xffff
+          @armed = false if interrupt
+          interrupt
+        end
+      end
+    end
+  end
+end