badline 0.12.0 → 0.13.0

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    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. The 6581 reads $00 of a
+          # full register (SID/wf12nsr's pulse+noise row) and pulls nothing
+          # while the register holds: wb_testsuite's 8->C and C->C rows run
+          # pulse+noise and leave the register alone. Its lines only land
+          # part way through a shift (#write_back_shift).
+          PULSE_NOISE_READ = { mos6581: 0x000, 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 0x000 if @pulse.zero?
+
+            noise & @pulse_noise_write
+          end
+
+          # What the lines write while the register is part way through a
+          # shift, where the 6581's pulse+noise writes its output as read.
+          def write_back_mid_shift(selected, value)
+            return value if pulse_noise_mid_shift?(selected)
+
+            write_back(selected, value)
+          end
+
+          def pulse_noise_mid_shift?(selected) = @topbit_feedback && selected == 0xc
+
+          def write_shift_register(value)
+            NOISE_TAPS.each { |bit, line| @shift_register &= ~bit if value.nobits?(line) }
+          end
+
+          # The second phase of a shift writes back by the test bit release
+          # rule with the waveform left alone. The 6581's pulse+noise, which
+          # that rule leaves out, writes its lines too (SID/wf12nsr's
+          # pulse+noise row).
+          def write_back_shift
+            return unless pulse_noise_mid_shift?(@selected) || release_writes_back?(@selected, @selected)
+
+            write_shift_register(write_back_mid_shift(@selected, @output))
+          end
+
+          # Setting the test bit starts the bleed, and stalls the register part
+          # way through a shift, where a noise combination writes its output
+          # back first, from the accumulator it had. SID/noiselfsrinit's
+          # $f8/$80 pairs set the bit onto all four from noise alone, and
+          # SID/wf12nsr's pulse+noise row sets it onto pulse+noise.
+          def raise_test
+            @shift_register_reset = @shift_register_reset_delay
+            return unless @selected.anybits?(0x8) && combined?(@selected) && @shift_pipeline != 1
+
+            write_shift_register(write_back_mid_shift(@selected, shape(@selected)))
+          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.
+          def release_test(previous)
+            value = release_write(previous)
+            write_shift_register(value) if value
+            shift_noise(1)
+          end
+
+          # What the release writes over the taps, or nil. On the 6581, a change
+          # that keeps only pulse+noise of the old waveform writes the lowest
+          # noise lines low. On the 8580, a change from pulse+noise to all four
+          # writes every line low.
+          def release_write(previous)
+            if @topbit_feedback
+              return noise & PULSE_NOISE_RELEASE if previous != 0xc && (previous & @selected) == 0xc
+            elsif previous == 0xc && @selected == 0xf
+              return 0x000
+            end
+            write_back(previous, shape(previous)) if release_writes_back?(previous, @selected)
+          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 combined after. Nothing
+          # is written back on changing to pulse+noise or from pulse+noise to
+          # sawtooth+noise, nor, on the 6581, on trading triangle for sawtooth
+          # or back.
+          def release_writes_back?(previous, selected)
+            return false if previous <= 0x8 || 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
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class SID
+      class Waveform
+        # A snapshot of an oscillator: its phase, the noise register and the
+        # output latch, and the same fields as reSID keeps them, for VICE's
+        # SIDEXTENDED module. The model's tables and the voices it syncs with
+        # are the SID's wiring.
+        module SavedState
+          # The fields reSID keeps for an oscillator between cycles: the phase,
+          # the noise register, its shift pipeline and reset countdown, the
+          # floating output's countdown and the pulse level.
+          def resid_fields
+            [@accumulator, @shift_register, @shift_pipeline, @shift_register_reset, @floating_ttl, @pulse]
+          end
+
+          # Takes the fields resid_fields gives from `fields`, from `at` on.
+          def restore_resid_fields(fields, at)
+            @accumulator = fields[at]
+            @shift_register = fields[at + 1]
+            @shift_pipeline = fields[at + 2]
+            @shift_register_reset = fields[at + 3]
+            @floating_ttl = fields[at + 4]
+            @pulse = fields[at + 5]
+            @stale = true
+          end
+
+          def save_state(out)
+            out.int(@accumulator).int(@delayed_triangle).int(@delayed_sawtooth)
+            out.int(@shift_register).int(@shift_register_reset).int(@shift_pipeline)
+            out.int(@frequency).int(@pulse_width).int(@selected)
+            [@test, @ring, @sync, @msb_rising].each { |flag| out.boolean(flag) }
+            out.int(@floating).int(@floating_ttl).int(@pulse).int(@output).boolean(@stale)
+          end
+
+          def load_state(input)
+            @accumulator = input.int
+            @delayed_triangle = input.int
+            @delayed_sawtooth = input.int
+            @shift_register = input.int
+            @shift_register_reset = input.int
+            @shift_pipeline = input.int
+            @frequency = input.int
+            @pulse_width = input.int
+            @selected = input.int
+            load_latches(input)
+          end
+
+          private
+
+          def load_latches(input)
+            @test = input.boolean?
+            @ring = input.boolean?
+            @sync = input.boolean?
+            @msb_rising = input.boolean?
+            @floating = input.int
+            @floating_ttl = input.int
+            @pulse = input.int
+            @output = input.int
+            @stale = input.boolean?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require "badline/chips/sid/waveform/combined"
+require "badline/chips/sid/waveform/fast_forward"
+require "badline/chips/sid/waveform/noise_writeback"
+require "badline/chips/sid/waveform/saved_state"
+
+module Badline
+  module Chips
+    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
+        include SavedState
+
+        # 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)
+          use_model(model)
+          @tri_saw_delay = model == :mos8580
+          @accumulator = POWER_ON_ACCUMULATOR
+          @sync_source = @sync_dest = self
+          reset!
+        end
+
+        # The running state carries over. A 6581 never delays its shapers, so
+        # the 8580's delayed triangle and sawtooth start from the current phase.
+        def model=(model)
+          use_model(model)
+          if model == :mos8580 && !@tri_saw_delay
+            @delayed_sawtooth = sawtooth
+            @delayed_triangle = triangle
+          end
+          @tri_saw_delay = model == :mos8580
+        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
+            raise_test unless @test
+            @accumulator = 0x000000
+            @pulse = 0xfff
+            @shift_pipeline = 0
+          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 use_model(model)
+          @topbit_feedback = 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)
+        end
+
+        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 & (selected - 1) != 0
+
+        # 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 before the register shifts.
+        def advance
+          previous = @accumulator
+          @accumulator = (previous + @frequency) & 0xffffff
+          @msb_rising = @accumulator & ~previous & MSB != 0
+          if @accumulator & ~previous & 0x080000 != 0
+            @shift_pipeline = 2
+          elsif @shift_pipeline != 0 && (@shift_pipeline -= 1).zero?
+            write_back_shift
+            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 & 0x2 != 0
+
+          msb = @accumulator & MSB != 0
+          return msb unless @ring
+
+          msb == (@sync_source.accumulator & MSB != 0)
+        end
+      end
+    end
+  end
+end