badline 0.1.0 → 0.2.1

data/lib/badline/sid/waveform/fast_forward.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Badline
+  class SID
+    class Waveform
+      # Running an oscillator many cycles in one step, for the catch-ups that
+      # fast-forward the voices between whole cycles.
+      module FastForward
+        # Runs `cycles` cycles as #cycle! would, for an oscillator that is not
+        # feeding back. What those cycles latch onto the output is left to the
+        # whole cycle that follows, which latches over it.
+        def fast_forward(cycles)
+          drain_floating(cycles) if @selected.zero?
+          if @test
+            bleed_shift_register(cycles)
+          else
+            while @shift_pipeline.positive? && cycles.positive?
+              advance
+              cycles -= 1
+            end
+            skip_ahead(cycles) if cycles.positive?
+            compare_pulse(((@accumulator - @frequency) & 0xffffff) >> 12)
+          end
+          @stale = true
+        end
+
+        # The cycle on which the accumulator MSB next rises, counting the next
+        # one as 1, or nil if it never will. The test bit leaves the last
+        # rise standing for as long as it is held.
+        def cycles_to_msb_rise
+          return (@msb_rising ? 1 : nil) if @test
+          return if @frequency.zero?
+
+          distance = (MSB - @accumulator) & 0xffffff
+          distance = 0x1000000 if distance.zero?
+          (distance + @frequency - 1) / @frequency
+        end
+
+        # A combined waveform with sawtooth (on the 6581) or noise in the mix
+        # writes back into the oscillator every cycle, so it cannot be
+        # fast-forwarded. Triangle and pulse alone write nothing back.
+        def feedback?
+          combined_waveform? && (@selected.anybits?(0x8) || (@topbit_feedback && @selected.anybits?(0x2)))
+        end
+
+        # Whether a catch-up has to run this oscillator a cycle at a time.
+        # While synthesizing, every combined waveform does, so the filter
+        # integrates it a cycle at a time.
+        def stepped?(synthesizing) = synthesizing ? combined_waveform? : feedback?
+
+        private
+
+        def combined_waveform? = !@test && combined?(@selected)
+
+        # Advances an accumulator with no shift in flight. Each rise of bit 19
+        # shifts the LFSR two cycles on, so a rise in the last two cycles
+        # leaves its shift pending for the cycles after.
+        def skip_ahead(cycles)
+          previous = @accumulator
+          @accumulator += @frequency * cycles
+          rises = bit19_rises(previous, @accumulator)
+          if rises.positive?
+            @shift_pipeline = pipeline_after(cycles)
+            rises -= 1 if @shift_pipeline.positive?
+            rises.times { shift_noise }
+          end
+          @accumulator &= 0xffffff
+        end
+
+        # Bit 19 rises at most once a cycle, on each odd multiple of 2^19,
+        # and at most once in any eight.
+        def bit19_rises(from, to) = ((to + 0x80000) >> 20) - ((from + 0x80000) >> 20)
+
+        # How far a rise on one of the last two cycles has come.
+        def pipeline_after(cycles)
+          last = @accumulator - @frequency
+          return 2 if bit19_rises(last, @accumulator).positive?
+          return 1 if cycles > 1 && bit19_rises(last - @frequency, last).positive?
+
+          0
+        end
+
+        def drain_floating(cycles)
+          return unless @floating_ttl.positive?
+
+          @floating_ttl -= cycles
+          return if @floating_ttl.positive?
+
+          @floating_ttl = 0
+          @floating = 0x000
+        end
+
+        def bleed_shift_register(cycles = 1)
+          return unless @shift_register_reset.positive?
+
+          @shift_register_reset -= cycles
+          return if @shift_register_reset.positive?
+
+          @shift_register_reset = 0
+          @shift_register = SHIFT_REGISTER_RESET
+        end
+      end
+    end
+  end
+end

data/lib/badline/sid/waveform/noise_writeback.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Badline
+  class SID
+    class Waveform
+      # Noise combined with other waveforms: the output lines write back into
+      # the LFSR, and what they write is not always what OSC3 reads.
+      module NoiseWriteback
+        # The LFSR bits the noise shaper reads, paired with the output bit each
+        # one drives (Dag Lem's diagram in SID/noise-reset_new). A combined
+        # waveform drives the same lines, so a bit held low there is written
+        # back into the register.
+        NOISE_TAPS = [[0x100000, 0x800], [0x040000, 0x400], [0x004000, 0x200],
+                      [0x000800, 0x100], [0x000200, 0x080], [0x000020, 0x040],
+                      [0x000004, 0x020], [0x000001, 0x010]].freeze
+
+        # Pulse+noise with the pulse high: the noise lines next to the four
+        # below them, which nothing drives, are pulled low. The OSC3 read and
+        # the LFSR writeback see the same lines against different thresholds,
+        # so they lose a different number of bits. The 8580's pair is the one
+        # that reproduces SID/wf12nsr's pulse+noise row (it reads $f8, and the
+        # writeback leaves $fc behind), and SID/wb_testsuite's C->9 and C->E
+        # rows need that same $fc written at release. On the 6581 the read is
+        # the $fc of SID/wf12nsr's readme (VICE bug #1037), and the writeback
+        # pulls nothing: wb_testsuite's 8/9/A/B->C rows run pulse+noise and
+        # leave the register alone.
+        PULSE_NOISE_READ = { mos6581: 0xfc0, mos8580: 0xf80 }.freeze
+        PULSE_NOISE_WRITE = { mos6581: 0xff0, mos8580: 0xfc0 }.freeze
+
+        # What a 6581 writes back when the test bit falls with only pulse+noise
+        # common to the old waveform and the new one (SID/wb_testsuite's D->C,
+        # E->C, F->C and D->E rows).
+        PULSE_NOISE_RELEASE = 0xf80
+
+        private
+
+        # What the lines write into the LFSR, against a lower threshold than
+        # OSC3 reads them by: a line left high between two low ones reads high
+        # (SID/noisewriteback's noise_writeback_test2) but is written low
+        # (SID/wf12nsr's noise+triangle and noise+sawtooth rows).
+        def write_back(selected, value)
+          return value & ((value << 1) | (value >> 1)) unless selected == 0xc
+          return value if value.zero?
+
+          noise & @pulse_noise_write
+        end
+
+        def write_shift_register(value)
+          NOISE_TAPS.each { |bit, line| @shift_register &= ~bit if value.nobits?(line) }
+        end
+
+        # Releasing the test bit finishes the shift it interrupted: the old
+        # waveform's output may be written back first, then a bit clocks in
+        # over the forced-high bit 22. On the 6581, a change that keeps only
+        # pulse+noise of the old waveform writes the lowest noise lines low.
+        def release_test(previous)
+          if @topbit_feedback && previous != 0xc && (previous & @selected) == 0xc
+            write_shift_register(noise & PULSE_NOISE_RELEASE)
+          elsif release_writes_back?(previous, @selected)
+            write_shift_register(write_back(previous, shape(previous)))
+          end
+          shift_noise(1)
+        end
+
+        # Which waveform changes write the old output back as the test bit
+        # falls (SID/wb_testsuite, after libresidfp's do_writeback). Noise has
+        # to have been combined before and still be selected after. Dropping
+        # to noise alone writes nothing back unless all four were selected,
+        # nor does changing to pulse+noise or from pulse+noise to
+        # sawtooth+noise, nor, on the 6581, trading triangle for sawtooth or
+        # back.
+        def release_writes_back?(previous, selected)
+          return false if previous <= 0x8 || selected < 0x8
+          return previous == 0xf if selected == 0x8
+          return false if selected == 0xc || (previous == 0xc && selected == 0xa)
+
+          !(@topbit_feedback && [previous & 0x3, selected & 0x3].sort == [0x1, 0x2])
+        end
+      end
+    end
+  end
+end

data/lib/badline/sid/waveform.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "badline/sid/waveform/combined"
+require "badline/sid/waveform/fast_forward"
+require "badline/sid/waveform/noise_writeback"
+
+module Badline
+  class SID
+    # Waveform generator: a 24-bit phase accumulator and the shapers that
+    # read it.
+    #
+    # The accumulator advances by the 16-bit frequency every cycle, so every
+    # waveform is a pure function of the phase. Bit 23 drives hard sync and
+    # the triangle fold, bit 19 clocks the noise LFSR.
+    #
+    # Selecting more than one waveform shorts the shapers onto the lines the
+    # oscillator itself reads back, so a combined waveform is not only a
+    # shape: a low top bit reaches the accumulator MSB through the sawtooth
+    # switch, and noise in the mix is written back into the LFSR. The shape
+    # itself comes from Combined's model of the lines pulling on each other.
+    #
+    # The pulse comparator's output reaches the lines a cycle after the
+    # accumulator it compared.
+    #
+    # With nothing selected the DAC input floats, holding the last value
+    # driven onto it until the charge drains away.
+    class Waveform
+      include FastForward
+      include NoiseWriteback
+
+      # All bits high at power up, odd ones stored inverted (SID/oscinit).
+      POWER_ON_ACCUMULATOR = 0x555555
+
+      # Holding the test bit bleeds every LFSR bit high; the power-on state is
+      # one shift further on, which is what releasing the bit leaves behind.
+      SHIFT_REGISTER_RESET = 0x7fffff
+      NOISE_SEED = 0x7ffffe
+
+      # Cycles the test bit needs to bleed the LFSR high. SID/bitfade's
+      # delaynoise measures ~$950000 on a real 8580. Nothing measures the
+      # 6581: SID/resid-test's oscsample dumps show it holding its bits
+      # through the ~$8800 cycles between runs, and the slow reset
+      # (SID/noise-reset_old) allows it a second.
+      SHIFT_REGISTER_RESET_DELAY = { mos6581: 0x80000, mos8580: 0x950000 }.freeze
+
+      # Cycles the floating DAC input holds its charge (SID/osc3-wave0).
+      FLOATING_OUTPUT_TTL = 0x4000
+
+      MSB = 0x800000
+
+      attr_accessor :sync_source, :sync_dest
+      attr_reader :accumulator, :shift_register, :frequency, :pulse_width, :pulse
+
+      def initialize(model: :mos6581)
+        @topbit_feedback = model != :mos8580
+        @tri_saw_delay = model == :mos8580
+        @pulse_noise_read = PULSE_NOISE_READ.fetch(model)
+        @pulse_noise_write = PULSE_NOISE_WRITE.fetch(model)
+        @combined = Combined.tables(model)
+        @shift_register_reset_delay = SHIFT_REGISTER_RESET_DELAY.fetch(model)
+        @accumulator = POWER_ON_ACCUMULATOR
+        @sync_source = @sync_dest = self
+        reset!
+      end
+
+      # The RES line clears the registers and reseeds the LFSR, but leaves
+      # the accumulator alone (SID/oscinit).
+      def reset!
+        @delayed_sawtooth = @delayed_triangle = 0x000
+        @shift_register = NOISE_SEED
+        @shift_register_reset = 0
+        @shift_pipeline = 0
+        @frequency = 0x0000
+        @pulse_width = 0x000
+        @selected = 0x0
+        @test = false
+        @ring = false
+        @sync = false
+        @msb_rising = false
+        @floating = 0x000
+        @floating_ttl = 0
+        @pulse = 0xfff
+        @output = 0x000
+        @stale = true
+      end
+
+      def sync? = @sync
+      def msb_rising? = @msb_rising
+
+      def frequency_low=(value)
+        @frequency = (@frequency & 0xff00) | value
+      end
+
+      def frequency_high=(value)
+        @frequency = (value << 8) | (@frequency & 0x00ff)
+      end
+
+      def pulse_width_low=(value)
+        @pulse_width = (@pulse_width & 0xf00) | value
+        @stale = true
+      end
+
+      def pulse_width_high=(value)
+        @pulse_width = ((value & 0x0f) << 8) | (@pulse_width & 0x0ff)
+        @stale = true
+      end
+
+      # The test bit clears the accumulator and stalls the LFSR half way
+      # through a shift, holding bit 22 high while its bits bleed up.
+      def control=(value)
+        previous = @selected
+        @selected = (value >> 4) & 0x0f
+        @ring = value.anybits?(0x04)
+        @sync = value.anybits?(0x02)
+        test = value.anybits?(0x08)
+        if test
+          @accumulator = 0x000000
+          @pulse = 0xfff
+          @shift_pipeline = 0
+          @shift_register_reset = @shift_register_reset_delay unless @test
+        elsif @test
+          release_test(previous)
+        end
+        @test = test
+        @stale = true
+      end
+
+      def cycle!
+        latch_output
+        compare_pulse
+        @test ? bleed_shift_register : advance
+        @stale = true
+      end
+
+      # Hard sync resets the next voice's accumulator when ours wraps. A
+      # source that is itself synced on the cycle its own MSB rises does not
+      # pass the sync on.
+      def synchronize!
+        return unless @msb_rising && @sync_dest.sync? &&
+                      !(@sync && @sync_source.msb_rising?)
+
+        @sync_dest.reset_accumulator
+      end
+
+      def reset_accumulator
+        @accumulator = 0x000000
+        @stale = true
+      end
+
+      # Held for the rest of the cycle once computed, so the filter, OSC3 and
+      # the oscillator's own feedback all see one value per cycle.
+      def output
+        return @output unless @stale
+
+        @stale = false
+        @output = @selected.zero? ? @floating : shape(@selected)
+      end
+
+      # What OSC3 reads. The 8580 delays the triangle and sawtooth shapers
+      # by half a cycle, which OSC3 latches as a whole cycle late; pulse and
+      # noise still reach the lines on time.
+      def osc3
+        return output unless @tri_saw_delay && @selected.anybits?(0x3)
+
+        shape(@selected, @delayed_sawtooth, @delayed_triangle)
+      end
+
+      def sawtooth = @accumulator >> 12
+
+      # The upper half of the ramp is folded back down, shifted left one bit
+      # to keep the full 12-bit range.
+      def triangle(selected = @selected)
+        folded = inverted?(selected) ? @accumulator ^ 0xffffff : @accumulator
+        (folded >> 11) & 0xfff
+      end
+
+      # Eight taps off the 23-bit LFSR, gathered into a 12-bit sample.
+      def noise
+        ((@shift_register & 0x100000) >> 9) |
+          ((@shift_register & 0x040000) >> 8) |
+          ((@shift_register & 0x004000) >> 5) |
+          ((@shift_register & 0x000800) >> 3) |
+          ((@shift_register & 0x000200) >> 2) |
+          ((@shift_register & 0x000020) << 1) |
+          ((@shift_register & 0x000004) << 3) |
+          ((@shift_register & 0x000001) << 4)
+      end
+
+      private
+
+      def shape(selected, saw = sawtooth, tri = triangle(selected))
+        case selected
+        when 0x1 then tri
+        when 0x2 then saw
+        when 0x4 then @pulse
+        when 0x8 then noise
+        else combined(selected, saw, tri)
+        end
+      end
+
+      # A low pulse grounds every line. Noise with pulse alone loses its
+      # lowest lines; noise with triangle or sawtooth is ANDed over the rest
+      # of the mix.
+      def combined(selected, saw, tri)
+        return 0x000 if selected.anybits?(0x4) && @pulse.zero?
+        return noise & @pulse_noise_read if selected == 0xc
+
+        rest = selected & 0x7
+        value = case rest
+                when 0x1 then tri
+                when 0x2 then saw
+                when 0x4 then 0xfff
+                else @combined[rest][rest == 0x5 ? tri : saw]
+                end
+        selected.anybits?(0x8) ? value & noise : value
+      end
+
+      def compare_pulse(phase = @accumulator >> 12) = (@pulse = @test || phase >= @pulse_width ? 0xfff : 0x000)
+
+      # More than one bit set in the selection.
+      def combined?(selected) = selected.anybits?(selected - 1)
+
+      # The one point in the cycle where the waveform selector drives the DAC:
+      # either it latches a fresh value, or nothing drives the line and the
+      # charge already on it drains a little further.
+      def latch_output
+        value = output
+        if @tri_saw_delay
+          @delayed_sawtooth = sawtooth
+          @delayed_triangle = triangle
+        end
+        if @selected.zero?
+          drain_floating(1)
+          return
+        end
+
+        @floating = value
+        @floating_ttl = FLOATING_OUTPUT_TTL
+        feed_back(value) if combined?(@selected) && !@test
+      end
+
+      # A zero on the shared output lines travels back into the oscillator:
+      # through the sawtooth switch it clears the accumulator MSB on the next
+      # cycle, and with noise selected it lands in the LFSR, where a bit
+      # pulled low can never come back. The 8580 buffers the top bit behind a
+      # flip-flop before the sawtooth switch, so only the LFSR sees it. In the
+      # first phase of a shift the register bits float, so nothing is pulled
+      # down: the output is latched instead, for the second phase to write.
+      def feed_back(value)
+        @accumulator &= ~MSB if @topbit_feedback && @selected.anybits?(0x2) && value.nobits?(0x800)
+        write_shift_register(write_back(@selected, value)) if @selected.anybits?(0x8) && @shift_pipeline != 1
+      end
+
+      # A rise of bit 19 starts a shift that takes two more cycles
+      # (SID/noisewriteback's noise_writeback_test2, after libresidfp's shift
+      # pipeline). The first phase latches the output, and the second writes
+      # it over the taps, by the test bit release rule with the waveform left
+      # alone, before the register shifts.
+      def advance
+        previous = @accumulator
+        @accumulator = (previous + @frequency) & 0xffffff
+        @msb_rising = previous.nobits?(MSB) && @accumulator.anybits?(MSB)
+        if previous.nobits?(0x080000) && @accumulator.anybits?(0x080000)
+          @shift_pipeline = 2
+        elsif @shift_pipeline.positive? && (@shift_pipeline -= 1).zero?
+          write_shift_register(write_back(@selected, @output)) if release_writes_back?(@selected, @selected)
+          shift_noise
+        end
+      end
+
+      # Bit 0 feeds back bits 22 and 17, with the test bit forcing bit 22 high.
+      def shift_noise(forced = 0)
+        bit0 = ((@shift_register >> 22) | forced) ^ (@shift_register >> 17)
+        @shift_register = ((@shift_register << 1) & 0x7fffff) | (bit0 & 0x1)
+      end
+
+      # TriXOR = !Saw & ((!V3 & Ring) ^ bit23), where V3 is the modulating
+      # voice's MSB (SID/ringmod).
+      def inverted?(selected)
+        return false if selected.anybits?(0x2)
+
+        msb = @accumulator.anybits?(MSB)
+        return msb unless @ring
+
+        msb != @sync_source.accumulator.nobits?(MSB)
+      end
+    end
+  end
+end