badline 0.12.1 → 0.13.0

data/lib/badline/chips/cpu/traps.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class CPU
+      module Traps
+        def install_trap(addr, &handler)
+          (@traps ||= {})[addr] = handler
+        end
+
+        def remove_trap(addr)
+          @traps&.delete(addr)
+        end
+
+        private
+
+        def run_traps
+          @traps[@program_counter]&.call if @traps
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/cpu.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "badline/chips/cpu/core"
+
+module Badline
+  module Chips
+    # The C64's 6510, on the C64::Bus.
+    class CPU
+      include Core
+    end
+  end
+end

data/lib/badline/chips/sid/catch_up.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      # Running the DSP over the cycles that have passed since it last caught
+      # up, in spans that fast-forward the voices and end on a whole cycle.
+      module CatchUp
+        private
+
+        # Runs the cycles that have passed, landing each queued write on the
+        # cycle the CPU wrote it on.
+        def catch_up
+          replayed = 0
+          i = 0
+          while i < @deferred_writes.length
+            cycle = @deferred_writes[i]
+            run(cycle - replayed)
+            replayed = cycle
+            apply_write(@deferred_writes[i + 1], @deferred_writes[i + 2])
+            i += 3
+          end
+          run(@pending_cycles - replayed)
+          @deferred_writes.clear
+          @pending_cycles = 0
+        end
+
+        def run(cycles)
+          while cycles != 0
+            span = span(cycles)
+            fast_forward(span - 1) if span > 1
+            clock!(span)
+            cycles -= span
+          end
+        end
+
+        # The longest stretch that can be fast-forwarded. A combined waveform
+        # feeding back into its own oscillator steps cycle by cycle, and a span
+        # never runs past an MSB rise that hard-syncs the next voice, so both
+        # land on a whole cycle.
+        def span(cycles)
+          return 1 if @stepped
+
+          span = @synthesizing ? synthesis_span(cycles) : cycles
+          return span unless @synced
+
+          span = sync_span(@waveform1, span)
+          span = sync_span(@waveform2, span)
+          sync_span(@waveform3, span)
+        end
+
+        # The filter steps at most @filter_chunk cycles at a time, and never
+        # across the end of a recorded sample.
+        def synthesis_span(cycles)
+          span = [cycles, @filter_chunk].min
+          return span unless @decimator
+
+          [@decimator.cycles_to_close, span].min
+        end
+
+        # Whether a span has to step, or watch for hard sync, only changes with
+        # a voice's control register.
+        def update_span_rules
+          @stepped = @voices.any? { |voice| voice.waveform.stepped?(@synthesizing) }
+          @synced = @voices.any? { |voice| voice.waveform.sync? }
+        end
+
+        def sync_span(waveform, span)
+          return span unless waveform.sync_dest.sync?
+
+          rise = waveform.cycles_to_msb_rise
+          rise && rise < span ? rise : span
+        end
+
+        # Unrolled over the three voices: the per-cycle block calls cost
+        # measurably on the synthesis path.
+        def fast_forward(cycles)
+          @voice1.fast_forward(cycles)
+          @voice2.fast_forward(cycles)
+          @voice3.fast_forward(cycles)
+        end
+
+        # The last cycle of a span, run whole. The filter integrates the span
+        # from the voices' output at its end.
+        def clock!(span)
+          @voice1.cycle!
+          @voice2.cycle!
+          @voice3.cycle!
+          @waveform1.synchronize!
+          @waveform2.synchronize!
+          @waveform3.synchronize!
+          return unless @synthesizing
+
+          @filter.cycle!(@voices, span)
+          record_sample(span) if @decimator
+        end
+
+        def record_sample(span)
+          sample = @decimator.push(current_sample, span)
+          return unless sample
+
+          @samples << sample
+          record_voices if @voice_samples
+        end
+
+        def record_voices
+          voice_samples = @voice_samples
+          voice_samples << (@voice1.output >> 7)
+          voice_samples << (@voice2.output >> 7)
+          voice_samples << (@voice3.output >> 7)
+        end
+
+        def current_sample
+          sample = @filter.output / SAMPLE_DIVISOR
+          return sample unless sample < -0x8000 || sample > 0x7fff
+
+          sample.clamp(-0x8000, 0x7fff)
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/sid/decimator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      # Reduces the SID's one-sample-per-cycle stream to an audio rate by
+      # averaging each window. Point sampling would be cheaper, but the pulse
+      # and noise waveforms carry enough energy above the output Nyquist to
+      # alias audibly.
+      #
+      # A sample can stand for several cycles at once, when the DSP has run
+      # them as one step.
+      class Decimator
+        def initialize(clock_hz:, rate:)
+          @clock_hz = clock_hz
+          @rate = rate
+          @phase = 0
+          @sum = 0
+          @count = 0
+          @cycles_to_close = window_cycles
+        end
+
+        # Cycles until the current window closes, counting the next one as 1.
+        attr_reader :cycles_to_close
+
+        # How far the current window has got. The clock and the rate are the
+        # host's.
+        def save_state(out)
+          out.int(@phase).int(@sum).int(@count).int(@cycles_to_close)
+        end
+
+        def load_state(input)
+          @phase = input.int
+          @sum = input.int
+          @count = input.int
+          @cycles_to_close = input.int
+        end
+
+        # Returns the averaged sample when these cycles close a window, and
+        # nil otherwise. They must not run past the window's end.
+        def push(sample, cycles = 1)
+          @sum += sample * cycles
+          @count += cycles
+          @phase += @rate * cycles
+          @cycles_to_close -= cycles
+          return unless @phase >= @clock_hz
+
+          @phase -= @clock_hz
+          @cycles_to_close = window_cycles
+          average
+        end
+
+        private
+
+        def window_cycles = (@clock_hz - @phase + @rate - 1) / @rate
+
+        def average
+          value = @sum.fdiv(@count).round
+          @sum = 0
+          @count = 0
+          value
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/sid/envelope/saved_state.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      class Envelope
+        # A snapshot of an envelope: its rates, the gate, the state and the
+        # counters and pipelines between them, and the same fields as reSID
+        # keeps them, for VICE's SIDEXTENDED module.
+        module SavedState
+          # The fields reSID keeps for an envelope between cycles: the rate and
+          # exponential counters, the level, the state as an index into STATES,
+          # whether it holds at zero, the two periods and the pipeline.
+          def resid_fields
+            [@rate_counter, @exponential_counter, @counter, STATES.index(@state).to_i, @hold_zero ? 1 : 0,
+             @rate_period, @exponential_period, @envelope_pipeline]
+          end
+
+          # Takes the fields resid_fields gives from `fields`, from `at` on.
+          def restore_resid_fields(fields, at)
+            @rate_counter = fields[at]
+            @exponential_counter = fields[at + 1]
+            @counter = @env3 = fields[at + 2]
+            state = fields[at + 3]
+            @state = @next_state = STATES.fetch(state.clamp(0, STATES.length - 1)).to_sym
+            @hold_zero = fields[at + 4] != 0
+            @rate_period = fields[at + 5]
+            @exponential_period = fields[at + 6]
+            @envelope_pipeline = fields[at + 7]
+          end
+
+          def save_state(out)
+            [@attack, @decay, @sustain, @release].each { |rate| out.int(rate) }
+            out.boolean(@gate).int(STATES.index(@state)).int(STATES.index(@next_state))
+            out.int(@counter).int(@env3).int(@rate_counter).int(@rate_period).boolean(@reset_rate_counter)
+            out.int(@exponential_counter).int(@exponential_period)
+            out.int(@state_pipeline).int(@envelope_pipeline).int(@exponential_pipeline).boolean(@hold_zero)
+          end
+
+          def load_state(input)
+            @attack = input.int
+            @decay = input.int
+            @sustain = input.int
+            @release = input.int
+            @gate = input.boolean?
+            @state = STATES.fetch(input.int).to_sym
+            @next_state = STATES.fetch(input.int).to_sym
+            load_counters(input)
+          end
+
+          private
+
+          def load_counters(input)
+            @counter = input.int
+            @env3 = input.int
+            @rate_counter = input.int
+            @rate_period = input.int
+            @reset_rate_counter = input.boolean?
+            @exponential_counter = input.int
+            @exponential_period = input.int
+            @state_pipeline = input.int
+            @envelope_pipeline = input.int
+            @exponential_pipeline = input.int
+            @hold_zero = input.boolean?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/sid/envelope.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "badline/chips/sid/envelope/saved_state"
+
+module Badline
+  module Chips
+    class SID
+      # ADSR envelope generator.
+      #
+      # A 15-bit rate counter divides the 1 MHz clock down to one envelope step
+      # per period. Attack steps linearly; decay and release run through a
+      # second, level-dependent divider that approximates an exponential
+      # curve.
+      #
+      # Each stage runs a cycle or more behind the one feeding it, after
+      # reSID 1.0's single-cycle pipeline: the rate counter resets the cycle
+      # after it matches, the envelope counter steps two cycles after that,
+      # and a gate edge only switches the rate over on its second cycle.
+      class Envelope
+        # Rate counter comparison values for each ADSR nibble. The counter
+        # takes a cycle to reset, so the period is one cycle longer (2ms to
+        # 8s over the attack range).
+        PERIODS = [8, 31, 62, 94, 148, 219, 266, 312,
+                   391, 976, 1953, 3125, 3906, 11_719, 19_531, 31_250].freeze
+
+        # Envelope levels where the exponential divider changes, and the
+        # divider it changes to.
+        EXPONENTIAL_PERIODS = { 0xff => 1, 0x5d => 2, 0x36 => 4, 0x1a => 8,
+                                0x0e => 16, 0x06 => 30, 0x00 => 1 }.freeze
+
+        # The states a snapshot names by index.
+        STATES = %i[attack decay_sustain release].freeze
+
+        include SavedState
+
+        attr_reader :state, :counter, :env3
+
+        def initialize
+          @attack = @decay = @sustain = @release = 0x0
+          @gate = false
+          @state = @next_state = :release
+          @counter = @env3 = 0x00
+          @rate_counter = 0
+          @rate_period = PERIODS[0]
+          @reset_rate_counter = false
+          @exponential_counter = 0
+          @exponential_period = 1
+          @state_pipeline = @envelope_pipeline = @exponential_pipeline = 0
+          @hold_zero = true
+        end
+
+        def output = @counter
+
+        # The gate edge switches the state over two cycles. Rising, it runs
+        # the decay rate for the first of them. The rate counter is left
+        # running, so the first step lands somewhere inside the current
+        # period.
+        def control=(value)
+          gate = value.anybits?(0x01)
+          return if gate == @gate
+
+          @gate = gate
+          gate ? gate_on : gate_off
+        end
+
+        def attack_decay=(value)
+          @attack = (value >> 4) & 0x0f
+          @decay = value & 0x0f
+          @rate_period = PERIODS[@attack] if @state == :attack
+          @rate_period = PERIODS[@decay] if @state == :decay_sustain
+        end
+
+        def sustain_release=(value)
+          @sustain = (value >> 4) & 0x0f
+          @release = value & 0x0f
+          @rate_period = PERIODS[@release] if @state == :release
+        end
+
+        # ENV3 reads the counter as it stood at the start of the cycle.
+        #
+        # Lowering the rate period below the current counter sends it the long
+        # way round through 2^15 before the envelope can step, the ADSR delay
+        # bug that hard restarts rely on. Counting from 0x7fff wraps to 1.
+        def cycle!
+          @env3 = @counter
+          run_pipeline if pipelined?
+          return @reset_rate_counter = true if @rate_counter == @rate_period
+
+          @rate_counter += 1
+          @rate_counter = 1 if @rate_counter == 0x8000
+        end
+
+        # Runs `cycles` cycles as #cycle! would. Between steps only the rate
+        # counter moves, so it jumps from one match to the next and the cycles
+        # around each step run whole. Frozen at zero, a period changes
+        # nothing, so whole periods are counted off at once.
+        def fast_forward(cycles)
+          while cycles.positive?
+            if pipelined?
+              cycle!
+              cycles -= 1
+              next
+            end
+
+            @env3 = @counter
+            idle = cycles_to_match
+            return advance_rate_counter(cycles) if cycles < idle
+
+            advance_rate_counter(idle)
+            cycles = skip_frozen_periods(cycles - idle)
+          end
+        end
+
+        private
+
+        def land_step
+          @envelope_pipeline -= 1
+          step if @envelope_pipeline.zero? && !@hold_zero
+        end
+
+        def gate_on
+          @next_state = :attack
+          @state = :decay_sustain
+          @rate_period = PERIODS[@decay]
+          @state_pipeline = 2
+          if @reset_rate_counter || @exponential_pipeline == 2
+            @envelope_pipeline = @exponential_period == 1 || @exponential_pipeline == 2 ? 2 : 4
+          elsif @exponential_pipeline == 1
+            @state_pipeline = 3
+          end
+        end
+
+        def gate_off
+          @next_state = :release
+          @state_pipeline = @envelope_pipeline.positive? ? 3 : 2
+        end
+
+        def state_change
+          @state_pipeline -= 1
+          if @next_state == :attack
+            enter_attack if @state_pipeline.zero?
+          elsif (@state == :attack && @state_pipeline.zero?) ||
+                (@state == :decay_sustain && @state_pipeline == 1)
+            @state = :release
+            @rate_period = PERIODS[@release]
+          end
+        end
+
+        def enter_attack
+          @state = :attack
+          @rate_period = PERIODS[@attack]
+          @hold_zero = false
+        end
+
+        # The first attack step also resets the exponential divider.
+        def reset_rate_counter
+          @rate_counter = 0
+          @reset_rate_counter = false
+          if @state == :attack
+            @exponential_counter = 0
+            @envelope_pipeline = 2
+          elsif !@hold_zero && (@exponential_counter += 1) == @exponential_period
+            @exponential_pipeline = @exponential_period == 1 ? 1 : 2
+          end
+        end
+
+        def exponential_step
+          @exponential_counter = 0
+          return unless @state == :release || (@state == :decay_sustain && @counter != sustain_level)
+
+          @envelope_pipeline = 1
+        end
+
+        def pipelined?
+          @reset_rate_counter || (@state_pipeline | @envelope_pipeline | @exponential_pipeline) != 0
+        end
+
+        def run_pipeline
+          state_change if @state_pipeline.positive?
+          land_step if @envelope_pipeline.positive?
+          if @exponential_pipeline.positive? && (@exponential_pipeline -= 1).zero?
+            exponential_step
+          elsif @reset_rate_counter
+            reset_rate_counter
+          end
+        end
+
+        # Cycles that only count before the rate counter matches its period.
+        def cycles_to_match
+          return @rate_period - @rate_counter if @rate_counter <= @rate_period
+
+          0x7fff - @rate_counter + @rate_period
+        end
+
+        def advance_rate_counter(cycles)
+          @rate_counter += cycles
+          @rate_counter -= 0x7fff if @rate_counter > 0x7fff
+        end
+
+        # With the counter on its period, a frozen envelope comes back to the
+        # same state every period plus one cycles. Otherwise the next cycle
+        # starts a step.
+        def skip_frozen_periods(cycles)
+          cycles %= @rate_period + 1 if @hold_zero && @state != :attack
+          return cycles unless cycles.positive?
+
+          cycle!
+          cycles - 1
+        end
+
+        def step
+          if @state == :attack
+            attack_step
+          else
+            @counter = (@counter - 1) & 0xff
+          end
+          set_exponential_period
+        end
+
+        def attack_step
+          @counter = (@counter + 1) & 0xff
+          return unless @counter == 0xff
+
+          @state = :decay_sustain
+          @rate_period = PERIODS[@decay]
+        end
+
+        def sustain_level = (@sustain << 4) | @sustain
+
+        # Reaching zero freezes the envelope until the gate is raised again.
+        def set_exponential_period
+          period = EXPONENTIAL_PERIODS[@counter]
+          return unless period
+
+          @exponential_period = period
+          @hold_zero = true if @counter.zero?
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/sid/filter/saved_state.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      class Filter
+        # The filter's state for a snapshot.
+        module SavedState
+          # The registers as the filter decoded them and its integrators. The
+          # W0 table is the model's.
+          def save_state(out)
+            out.int(@cutoff).int(@routing).int(@mode).int(@volume).boolean(@voice3_off).int(@w0).int(@resonance)
+            [@highpass, @bandpass, @lowpass, @unfiltered, @input].each { |value| out.int(value) }
+            @external.save_state(out)
+          end
+
+          def load_state(input)
+            @cutoff = input.int
+            @routing = input.int
+            @mode = input.int
+            @volume = input.int
+            @voice3_off = input.boolean?
+            @w0 = input.int
+            @resonance = input.int
+            load_integrators(input)
+          end
+
+          private
+
+          def load_integrators(input)
+            @highpass = input.int
+            @bandpass = input.int
+            @lowpass = input.int
+            @unfiltered = input.int
+            @input = input.int
+            @external.load_state(input)
+          end
+        end
+      end
+    end
+  end
+end