badline 0.12.1 → 0.14.0

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class VIA
+      # One port's pair of control lines, CA1 and CA2 or CB1 and CB2, set up
+      # by a nibble of the peripheral control register, and their two
+      # interrupt flags. Bit 0 picks the active edge of C1, rising when set.
+      # Bits 3-1 pick the C2 mode:
+      #
+      #   000 input, falling edge    100 handshake output
+      #   001 independent, falling   101 pulse output
+      #   010 input, rising edge     110 low output
+      #   011 independent, rising    111 high output
+      #
+      # A port access clears both flags, but an independent input keeps C2's.
+      # In handshake mode C2 goes low on a port access and back high on the
+      # next active C1 edge. In pulse mode it goes low for the cycle after the
+      # access. Port A handshakes on reads and writes, port B on writes only.
+      class ControlLines
+        attr_reader :control, :c1_high, :c2_high
+
+        # The level driven on C2, high while it is an input.
+        attr_reader :c2_output
+
+        def initialize(interrupts, c1_flag:, c2_flag:, handshake_on_read:)
+          @interrupts = interrupts
+          @c1_flag = c1_flag
+          @c2_flag = c2_flag
+          @handshake_on_read = handshake_on_read
+          @c1_high = @c2_high = true
+          reset!
+        end
+
+        # Back to input mode with both handshake outputs released. The input
+        # levels carry over.
+        def reset!
+          @control = 0
+          @handshake_low = false
+          @pulse = 0
+          drive
+        end
+
+        def control=(nibble)
+          @control = nibble & 0x0f
+          drive
+        end
+
+        # Only the pulse output needs the clock.
+        def pulsing? = @pulse.positive?
+
+        def cycle!
+          @pulse -= 1
+          drive if @pulse.zero?
+        end
+
+        def active_c1_edge?(high) = high == @control.anybits?(0x01)
+
+        # Everything the lines hold, for comparing them at two points.
+        def state = [@control, @c1_high, @c2_high, @handshake_low, @pulse, @c2_output]
+
+        # A new C1 level. An active edge sets the flag and ends a handshake.
+        def c1=(high)
+          return if high == @c1_high
+
+          @c1_high = high
+          return unless active_c1_edge?(high)
+
+          @handshake_low = false
+          drive
+          @interrupts.set(@c1_flag)
+        end
+
+        # A new C2 level. An active edge sets the flag while C2 is an input.
+        def c2=(high)
+          return if high == @c2_high
+
+          @c2_high = high
+          @interrupts.set(@c2_flag) if @control.nobits?(0x08) && high == @control.anybits?(0x04)
+        end
+
+        # A read or write of the handshaking port register.
+        def access!(write)
+          @interrupts.clear(independent? ? @c1_flag : @c1_flag | @c2_flag)
+          return unless write || @handshake_on_read
+
+          case @control >> 1
+          when 4 then @handshake_low = true
+          when 5 then @pulse = 2
+          end
+          drive
+        end
+
+        private
+
+        def independent? = @control & 0x0a == 0x02
+
+        def drive
+          @c2_output = case @control >> 1
+                       when 4 then !@handshake_low
+                       when 5 then @pulse.zero?
+                       when 6 then false
+                       else true
+                       end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class VIA
+      # Running a VIA a stretch of cycles at once while nothing but its
+      # counters would change, for Drives::Engine::Idle.
+      module FastForward
+        # quiet_cycles for a VIA that will never set a flag of its own.
+        QUIET = 1 << 40
+
+        # How many cycles the VIA can run with nothing but its counters
+        # changing: no flag set, no pulse on a control line and no bit
+        # shifted. See Drives::Engine::Idle.
+        def quiet_cycles
+          return 0 if @sr_uses_t2 || @shift_register.clocking? || @ca.pulsing? || @cb.pulsing?
+
+          [@t1.quiet_cycles, @t2.quiet_cycles].min
+        end
+
+        # Runs +cycles+ cycles at once, as many as quiet_cycles allows, which
+        # moves only the counters.
+        def fast_forward(cycles)
+          return if cycles.zero?
+
+          @t1.fast_forward(cycles)
+          @t2.fast_forward(cycles)
+        end
+
+        # The counters an orbit (see Drives::Engine::Idle) has to bring back: those
+        # of the armed timers, and of the timers +touched+ names (bit 0 for
+        # timer 1, bit 1 for timer 2). The others only count.
+        def counter_state(touched)
+          [(@t1.count_state if @t1.armed? || touched.anybits?(1)),
+           (@t2.count_state if @t2.armed? || touched.anybits?(2))]
+        end
+
+        # Runs +cycles+ cycles of whole orbits at once: the counters
+        # counter_state leaves out move on, and the rest come back round.
+        def skip_orbits(cycles, touched)
+          @t1.fast_forward(cycles) unless @t1.armed? || touched.anybits?(1)
+          @t2.fast_forward(cycles) unless @t2.armed? || touched.anybits?(2)
+        end
+
+        # Everything the VIA holds but its counters, for comparing it at two
+        # points. Timer 1's PB7 level counts only while ACR bit 7 puts it on
+        # the pin: nothing reads it otherwise.
+        def idle_state
+          [@ora, @orb, @ddra, @ddrb, @latch_a, @latch_b, @acr, @pcr, @pb6_high, @ifr.flags, @ifr.enable,
+           @acr.anybits?(0x80) && @t1.pb7, *@t1.state, *@t2.state, *@ca.state, *@cb.state, *@shift_register.state]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class VIA
+      # The interrupt flag and enable registers. Each source has a flag bit,
+      # and IRQ is pulled low while any flag is set with its enable bit.
+      class InterruptRegister
+        CA2 = 0x01
+        CA1 = 0x02
+        SR = 0x04
+        CB2 = 0x08
+        CB1 = 0x10
+        TIMER2 = 0x20
+        TIMER1 = 0x40
+
+        attr_reader :flags, :enable
+
+        def initialize
+          reset!
+        end
+
+        def reset!
+          @flags = 0x00
+          @enable = 0x00
+        end
+
+        def set(bits)
+          @flags |= bits
+        end
+
+        def clear(bits)
+          @flags &= ~bits
+        end
+
+        def irq? = @flags.anybits?(@enable)
+
+        # Bit 7 reads the IRQ output.
+        def read = irq? ? @flags | 0x80 : @flags
+
+        # Writing 1s clears the flags; bit 7 is ignored.
+        def write(value)
+          clear(value & 0x7f)
+        end
+
+        # Bit 7 reads as 1.
+        def read_enable = @enable | 0x80
+
+        # Bit 7 picks between setting and clearing the enable bits given.
+        def write_enable(value)
+          if value.anybits?(0x80)
+            @enable |= value & 0x7f
+          else
+            @enable &= ~value & 0x7f
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class VIA
+      class Timer1
+        # Timer 1's fields in a keyed snapshot module, under `prefix`.
+        module KeyedState
+          def save_fields(out, prefix)
+            out.int("#{prefix}counter", @counter).int("#{prefix}latch", @latch).bool("#{prefix}hold", @hold)
+            out.bool("#{prefix}reload", @reload).bool("#{prefix}armed", @armed).bool("#{prefix}pb7", @pb7)
+          end
+
+          def load_fields(input, prefix)
+            @counter = input.word("#{prefix}counter", @counter)
+            @latch = input.word("#{prefix}latch", @latch)
+            @hold = input.bool("#{prefix}hold", @hold)
+            @reload = input.bool("#{prefix}reload", @reload)
+            @armed = input.bool("#{prefix}armed", @armed)
+            @pb7 = input.bool("#{prefix}pb7", @pb7)
+          end
+        end
+
+        include KeyedState
+      end
+
+      class Timer2
+        # Timer 2's fields in a keyed snapshot module, under `prefix`.
+        module KeyedState
+          def save_fields(out, prefix)
+            out.int("#{prefix}counter", @counter).int("#{prefix}latch_low", @latch_low).bool("#{prefix}hold", @hold)
+            out.bool("#{prefix}low_reload", @low_reload).bool("#{prefix}armed", @armed)
+            out.bool("#{prefix}low_underflowed", @low_underflowed).bool("#{prefix}count_pulses", @count_pulses)
+            out.bool("#{prefix}counting_pulses", @counting_pulses)
+          end
+
+          def load_fields(input, prefix)
+            @counter = input.word("#{prefix}counter", @counter)
+            @latch_low = input.byte("#{prefix}latch_low", @latch_low)
+            @hold = input.bool("#{prefix}hold", @hold)
+            @low_reload = input.bool("#{prefix}low_reload", @low_reload)
+            @armed = input.bool("#{prefix}armed", @armed)
+            @low_underflowed = input.bool("#{prefix}low_underflowed", @low_underflowed)
+            @count_pulses = input.bool("#{prefix}count_pulses", @count_pulses)
+            @counting_pulses = input.bool("#{prefix}counting_pulses", @counting_pulses)
+          end
+        end
+
+        include KeyedState
+      end
+
+      class ShiftRegister
+        # The shift register's fields in a keyed snapshot module, under
+        # `prefix`.
+        module KeyedState
+          def save_fields(out, prefix)
+            out.int("#{prefix}mode", @mode).int("#{prefix}data", @data).int("#{prefix}bits", @bits)
+            out.int("#{prefix}delay", @delay).bool("#{prefix}clock", @clock).bool("#{prefix}cb2", @cb2)
+            out.bool("#{prefix}cb2_input", @cb2_input)
+          end
+
+          def load_fields(input, prefix)
+            @mode = input.masked("#{prefix}mode", @mode, 0x07)
+            @data = input.byte("#{prefix}data", @data)
+            @bits = input.int("#{prefix}bits", @bits)
+            @delay = input.int("#{prefix}delay", @delay)
+            @clock = input.bool("#{prefix}clock", @clock)
+            @cb2 = input.bool("#{prefix}cb2", @cb2)
+            @cb2_input = input.bool("#{prefix}cb2_input", @cb2_input)
+          end
+        end
+
+        include KeyedState
+      end
+
+      class InterruptRegister
+        # The flags and the enable mask, under `prefix`.
+        module KeyedState
+          def save_fields(out, prefix)
+            out.int("#{prefix}flags", @flags).int("#{prefix}enable", @enable)
+          end
+
+          def load_fields(input, prefix)
+            @flags = input.masked("#{prefix}flags", @flags, 0x7f)
+            @enable = input.masked("#{prefix}enable", @enable, 0x7f)
+          end
+        end
+
+        include KeyedState
+      end
+
+      class ControlLines
+        # A pair of control lines' fields, under `prefix`.
+        module KeyedState
+          def save_fields(out, prefix)
+            out.int("#{prefix}control", @control).bool("#{prefix}c1_high", @c1_high).bool("#{prefix}c2_high", @c2_high)
+            out.bool("#{prefix}handshake_low", @handshake_low).int("#{prefix}pulse", @pulse)
+            out.bool("#{prefix}c2_output", @c2_output)
+          end
+
+          def load_fields(input, prefix)
+            @control = input.masked("#{prefix}control", @control, 0x0f)
+            @c1_high = input.bool("#{prefix}c1_high", @c1_high)
+            @c2_high = input.bool("#{prefix}c2_high", @c2_high)
+            @handshake_low = input.bool("#{prefix}handshake_low", @handshake_low)
+            @pulse = input.int("#{prefix}pulse", @pulse)
+            @c2_output = input.bool("#{prefix}c2_output", @c2_output)
+          end
+        end
+
+        include KeyedState
+      end
+
+      # The VIA's fields in a keyed snapshot module (Snapshot::Keyed): the
+      # registers and PB6, and its parts under t1., t2., sr., ifr., ca. and
+      # cb. Whether the shift register clocks off timer 2 comes from the
+      # ACR on load. The peripheral restores its own state.
+      module KeyedState
+        def save_fields(out)
+          out.int("ora", @ora).int("orb", @orb).int("ddra", @ddra).int("ddrb", @ddrb).int("latch_a", @latch_a)
+          out.int("latch_b", @latch_b).int("acr", @acr).int("pcr", @pcr).bool("pb6_high", @pb6_high)
+          @t1.save_fields(out, "t1.")
+          @t2.save_fields(out, "t2.")
+          @shift_register.save_fields(out, "sr.")
+          @ifr.save_fields(out, "ifr.")
+          @ca.save_fields(out, "ca.")
+          @cb.save_fields(out, "cb.")
+          out
+        end
+
+        def load_fields(input)
+          @ora = input.byte("ora", @ora)
+          @orb = input.byte("orb", @orb)
+          @ddra = input.byte("ddra", @ddra)
+          @ddrb = input.byte("ddrb", @ddrb)
+          @latch_a = input.byte("latch_a", @latch_a)
+          @latch_b = input.byte("latch_b", @latch_b)
+          @acr = input.byte("acr", @acr)
+          @pcr = input.byte("pcr", @pcr)
+          @pb6_high = input.bool("pb6_high", @pb6_high)
+          load_part_fields(input)
+        end
+
+        def restored!
+          @sr_uses_t2 = [1, 4, 5].include?((@acr >> 2) & 0x07)
+        end
+
+        private
+
+        def load_part_fields(input)
+          @t1.load_fields(input, "t1.")
+          @t2.load_fields(input, "t2.")
+          @shift_register.load_fields(input, "sr.")
+          @ifr.load_fields(input, "ifr.")
+          @ca.load_fields(input, "ca.")
+          @cb.load_fields(input, "cb.")
+        end
+      end
+
+      include KeyedState
+    end
+  end
+end

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

@@ -0,0 +1,168 @@
+# 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?
+
+        # 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,120 @@
+# 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
+
+        # 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