badline 0.5.0 → 0.6.0

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Badline
+  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 State
+        # 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

data/lib/badline/sid/waveform.rb

@@ -3,6 +3,7 @@
 require "badline/sid/waveform/combined"
 require "badline/sid/waveform/fast_forward"
 require "badline/sid/waveform/noise_writeback"
+require "badline/sid/waveform/state"
 
 module Badline
   class SID
@@ -27,6 +28,7 @@ module Badline
     class Waveform
       include FastForward
       include NoiseWriteback
+      include State
 
       # All bits high at power up, odd ones stored inverted (SID/oscinit).
       POWER_ON_ACCUMULATOR = 0x555555

data/lib/badline/sid.rb

@@ -125,6 +125,17 @@ module Badline
       @voices
     end
 
+    # Runs the DSP up to the current cycle.
+    def catch_up! = catch_up
+
+    # The byte the data bus holds and the cycles until it fades.
+    def bus_state = [@bus_value, @bus_ttl]
+
+    def restore_bus(value, ttl)
+      @bus_value = value
+      @bus_ttl = ttl
+    end
+
     def filter
       catch_up
       @filter
@@ -178,6 +189,29 @@ module Badline
     # Register contents as written, for save states and debugging.
     def register(reg) = @registers.peek(reg)
 
+    # The registers, the data bus, the voices and the filter, and the span
+    # the DSP has yet to catch up on, as it stands: saving leaves the SID
+    # as it was. Whether it synthesizes or records is the host's.
+    def save_state(out)
+      out.marker("SID")
+      @registers.save_state(out)
+      out.int(@bus_value).int(@bus_ttl).int(@pending_cycles).ints(@deferred_writes)
+      @voices.each { |voice| voice.save_state(out) }
+      @filter.save_state(out)
+    end
+
+    def load_state(input)
+      input.marker("SID")
+      @registers.load_state(input)
+      @bus_value = input.int
+      @bus_ttl = input.int
+      @pending_cycles = input.int
+      input.ints_into(@deferred_writes)
+      @voices.each { |voice| voice.load_state(input) }
+      @filter.load_state(input)
+      update_span_rules
+    end
+
     private
 
     def latch(value)

data/lib/badline/snapshot/container.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Badline
+  module Snapshot
+    # One module of a snapshot: its name, its version and its payload,
+    # without the 22-byte module header.
+    Section = Data.define(:name, :major, :minor, :data) do
+      def version = "#{major}.#{minor}"
+
+      def to_s = "#{name} #{version}"
+    end
+
+    # The .vsf container as the VICE manual describes it: a magic string,
+    # the file format version and a machine name, an optional VICE version
+    # block, then modules one after another, each a 16-byte name, a major
+    # and minor version and a little-endian length that counts the header.
+    # A gzipped file reads as the file inside it, as VICE's own does.
+    class Container
+      MAGIC = "VICE Snapshot File\x1a".b
+      VERSION_MAGIC = "VICE Version\x1a".b
+      NAME_LENGTH = 16
+      MODULE_HEADER = NAME_LENGTH + 6
+      FORMAT_MAJOR = 2
+      FORMAT_MINOR = 0
+      # x64sc names its machine C64SC, and refuses a snapshot naming another.
+      MACHINE = "C64SC"
+      GZIP_MAGIC = "\x1f\x8b".b
+
+      # The VICE version block, when VICE wrote the file: four version
+      # bytes and a revision, kept as read.
+      attr_reader :machine, :sections, :vice_version
+
+      def self.parse(bytes)
+        bytes = bytes.b
+        bytes = gunzip(bytes) if bytes.start_with?(GZIP_MAGIC)
+        raise FormatError, "not a VICE snapshot" unless bytes.start_with?(MAGIC)
+
+        Reader.new(bytes).container
+      end
+
+      def self.gunzip(bytes)
+        Zlib.gunzip(bytes).b
+      rescue Zlib::Error => e
+        raise FormatError, "the gzipped snapshot is damaged: #{e.message}"
+      end
+
+      def initialize(sections = [], machine: MACHINE, vice_version: nil)
+        @machine = machine
+        @sections = sections
+        @vice_version = vice_version
+      end
+
+      def [](name) = @sections.find { |section| section.name == name }
+
+      def to_s
+        header = MAGIC + [FORMAT_MAJOR, FORMAT_MINOR].pack("CC") + padded(@machine)
+        header += VERSION_MAGIC + @vice_version if @vice_version
+        header + @sections.map { |section| encode(section) }.join
+      end
+
+      private
+
+      def padded(name)
+        raise ArgumentError, "#{name} is longer than #{NAME_LENGTH} bytes" if name.bytesize > NAME_LENGTH
+
+        name.b.ljust(NAME_LENGTH, "\0")
+      end
+
+      def encode(section)
+        padded(section.name) + [section.major, section.minor, MODULE_HEADER + section.data.bytesize].pack("CCV") +
+          section.data.b
+      end
+
+      # Splits the bytes of a snapshot into its header and modules.
+      class Reader
+        def initialize(bytes)
+          @bytes = bytes
+          @pos = MAGIC.bytesize + 2
+        end
+
+        def container
+          machine = take(NAME_LENGTH).delete("\0")
+          version = vice_version
+          sections = []
+          sections << section while @pos < @bytes.bytesize
+          Container.new(sections, machine:, vice_version: version)
+        end
+
+        private
+
+        def take(length)
+          raise FormatError, "snapshot ends early, at byte #{@bytes.bytesize}" if @pos + length > @bytes.bytesize
+
+          @bytes.byteslice(@pos, length).tap { @pos += length }
+        end
+
+        # VICE 2.4.30 and later write their version after the machine name.
+        def vice_version
+          return unless @bytes.byteslice(@pos, VERSION_MAGIC.bytesize) == VERSION_MAGIC
+
+          @pos += VERSION_MAGIC.bytesize
+          take(8)
+        end
+
+        def section
+          name = take(NAME_LENGTH).delete("\0")
+          major, minor, length = take(6).unpack("CCV")
+          raise FormatError, "module #{name} has a bad length #{length}" if length < MODULE_HEADER
+
+          Section.new(name:, major:, minor:, data: take(length - MODULE_HEADER))
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/fields.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    # Little-endian fields for VICE modules, written one after another as
+    # VICE's SMW_B, SMW_W, SMW_DW, SMW_QW and SMW_BA write them.
+    class FieldWriter
+      def initialize
+        @out = String.new(encoding: Encoding::BINARY)
+      end
+
+      def byte(value) = tap { @out << [value & 0xff].pack("C") }
+      def word(value) = tap { @out << [value & 0xffff].pack("v") }
+      def dword(value) = tap { @out << [value & 0xffff_ffff].pack("V") }
+      def qword(value) = tap { @out << [value & 0xffff_ffff_ffff_ffff].pack("Q<") }
+      def flag(value) = byte(value ? 1 : 0)
+
+      def bytes(values)
+        tap { @out << (values.is_a?(String) ? values.b : values.map { |v| v & 0xff }.pack("C*")) }
+      end
+
+      def zeros(count) = tap { @out << ("\0".b * count) }
+
+      def section(name, major, minor) = Section.new(name:, major:, minor:, data: @out.dup)
+    end
+
+    # Reads a VICE module's fields in the order they were written.
+    class FieldReader
+      def initialize(section)
+        @section = section
+        @data = section.data
+        @pos = 0
+      end
+
+      def byte = take(1).unpack1("C").to_i
+      def word = take(2).unpack1("v").to_i
+      def dword = take(4).unpack1("V").to_i
+      def qword = take(8).unpack1("Q<").to_i
+      def flag? = !byte.zero?
+      def bytes(count) = take(count).bytes
+      def skip(count) = tap { take(count) }
+
+      private
+
+      def take(count)
+        if @pos + count > @data.bytesize
+          raise FormatError, "#{@section.name} #{@section.version} ends early, at byte #{@data.bytesize}"
+        end
+
+        @data.byteslice(@pos, count).to_s.tap { @pos += count }
+      end
+    end
+  end
+end

data/lib/badline/snapshot/image.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    # What a restore applied and what it left out: module names, and a line
+    # for each thing left out, saying why.
+    Report = Data.define(:applied, :ignored)
+
+    # A snapshot read from a file.
+    class Image
+      attr_reader :container
+
+      def initialize(container)
+        @container = container
+      end
+
+      def sections = @container.sections
+
+      # Whether badline wrote it, with the whole machine in a BADLINE module.
+      def badline? = !section.nil?
+
+      # The State the BADLINE module holds.
+      def state = MachineState.state(section)
+
+      # A new machine, built as the snapshot's was and restored from it. A
+      # badline snapshot restores from its BADLINE module alone, which
+      # carries everything its VICE modules do, and a VICE one through the
+      # modules badline reads. Yields a line for each thing left out, or
+      # warns it without a block.
+      def load(&)
+        computer = badline? ? opening { Computer.restored(state) } : Vice.setup(@container).build
+        tell(badline? ? state_report(computer) : Vice::Restore.apply(@container, computer), &)
+        computer
+      end
+
+      # Restores `computer` from the snapshot, and returns the Report. A
+      # snapshot that fails leaves the machine as it was.
+      def restore(computer, &)
+        report = badline? ? restore_state(computer) : Vice::Restore.import(@container, computer)
+        tell(report, &)
+        report
+      end
+
+      private
+
+      def section = @container[MachineState::NAME]
+
+      def tell(report)
+        report.ignored.each { |line| block_given? ? yield(line) : warn("badline: #{line}") }
+      end
+
+      def restore_state(computer)
+        opening { computer.restore(state) }
+        state_report(computer)
+      end
+
+      def opening
+        yield
+      rescue SystemCallError => e
+        raise FormatError, "a file the snapshot names won't open: #{e.message}"
+      end
+
+      def state_report(computer)
+        lost = computer.init_handlers_lost
+        ignored = lost.positive? ? ["#{lost} on_init handler(s) the saved machine had yet to run, left out"] : []
+        Report.new(applied: [MachineState::NAME], ignored:)
+      end
+    end
+  end
+end

data/lib/badline/snapshot/machine_state.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    # The BADLINE module: a State from Computer#snapshot, which restores the
+    # machine exactly where it was saved. VICE skips a module it doesn't
+    # know.
+    #
+    # The payload is deflated. Inside, a little-endian 32-bit length leads
+    # a run of BER-compressed integers (Ruby's pack "w"): the number of
+    # values and of strings, each string's length, then the values, each
+    # folded to a natural number (0, -1, 1, -2 ... as 0, 1, 2, 3 ...). The
+    # strings follow, one after another.
+    #
+    # A State only restores in the badline version that wrote it, since
+    # each chip writes its fields as it holds them.
+    module MachineState
+      NAME = "BADLINE"
+      MAJOR = 2
+      MINOR = 0
+
+      module_function
+
+      def section(state)
+        Section.new(name: NAME, major: MAJOR, minor: MINOR, data: Zlib.deflate(encode(state)))
+      end
+
+      def state(section)
+        unless section.major == MAJOR
+          raise FormatError, "#{NAME} #{section.version} was written by another badline version, " \
+                             "and this one reads #{MAJOR}.#{MINOR}"
+        end
+
+        decode(Zlib.inflate(section.data))
+      rescue Zlib::Error => e
+        raise FormatError, "#{NAME} is damaged: #{e.message}"
+      end
+
+      def encode(state)
+        values = state.values
+        strings = state.strings
+        numbers = [values.length, strings.length]
+        strings.each { |string| numbers << string.bytesize }
+        values.each { |value| numbers << (value.negative? ? (-2 * value) - 1 : 2 * value) }
+        index = numbers.pack("w*")
+        [index.bytesize].pack("V") + index + strings.join
+      end
+
+      def decode(bytes)
+        raise FormatError, "#{NAME} ends early" if bytes.bytesize < 4
+
+        length = bytes.byteslice(0, 4).unpack1("V").to_i
+        numbers = bytes.byteslice(4, length).to_s.unpack("w*").map(&:to_i)
+        value_count = numbers.fetch(0, 0)
+        string_count = numbers.fetch(1, 0)
+        raise FormatError, "#{NAME} ends early" if numbers.length != 2 + string_count + value_count
+
+        State.new(values(numbers, 2 + string_count), strings(bytes, 4 + length, numbers.slice(2, string_count)))
+      end
+
+      def values(numbers, from)
+        Array.new(numbers.length - from) do |i|
+          folded = numbers[from + i]
+          folded.odd? ? -((folded + 1) / 2) : folded / 2
+        end
+      end
+
+      def strings(bytes, pos, lengths)
+        lengths.map do |length|
+          raise FormatError, "#{NAME} ends early" if pos + length > bytes.bytesize
+
+          bytes.byteslice(pos, length).to_s.tap { pos += length }
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/setup.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    # How a machine was built: its VIC, CIA and SID models, its region, its
+    # RAM expansion and the size of its REU, the arguments Computer.new
+    # takes. A State starts with them, so a machine to restore it into can
+    # be built first.
+    Setup = Data.define(:vic_model, :cia_model, :sid_model, :region, :ram_expansion, :reu)
+
+    class Setup
+      SID_MODELS = %i[mos6581 mos8580].freeze
+      REGIONS = [Region::PAL, Region::NTSC].freeze
+      RAM_EXPANSIONS = [:none, *RAMExpansion::TYPES.keys].freeze
+
+      def self.of(address_bus)
+        new(vic_model: address_bus.vic.model, cia_model: address_bus.cia1.model, sid_model: address_bus.sid.model,
+            region: address_bus.region, ram_expansion: address_bus.ram_expansion.type, reu: address_bus.reu&.size_kb)
+      end
+
+      def self.read(input)
+        new(vic_model: VIC::MODELS.fetch(input.int), cia_model: CIA::MODELS.fetch(input.int),
+            sid_model: SID_MODELS.fetch(input.int), region: REGIONS.fetch(input.int),
+            ram_expansion: ram_expansion(RAM_EXPANSIONS.fetch(input.int)), reu: reu(input.int))
+      rescue IndexError
+        raise FormatError, "the state names a chip model, region or RAM expansion badline doesn't know"
+      end
+
+      def self.ram_expansion(name) = name == :none ? nil : name
+
+      # An REU's size in K, written as 0 for none.
+      def self.reu(size_kb)
+        return nil if size_kb.zero?
+        return size_kb if REU::SIZES_KB.include?(size_kb)
+
+        raise FormatError, "the state names a #{size_kb}K REU, which badline doesn't build"
+      end
+
+      def write(out)
+        out.int(VIC::MODELS.index(vic_model)).int(CIA::MODELS.index(cia_model))
+        out.int(SID_MODELS.index(sid_model)).int(REGIONS.index(region))
+        out.int(RAM_EXPANSIONS.index(ram_expansion || :none)).int(reu || 0)
+      end
+
+      # A machine built this way, at power-on.
+      def build
+        Computer.new(vic_model:, cia_model:, sid_model:, region:, ram_expansion:, reu:)
+      end
+
+      def to_s
+        parts = [vic_model, cia_model, sid_model, region.name]
+        parts << ram_expansion if ram_expansion
+        parts << "a #{reu}K REU" if reu
+        parts.join(", ")
+      end
+    end
+  end
+end

data/lib/badline/snapshot/state.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    # A file that isn't a snapshot badline reads, is cut short, or holds a
+    # state that doesn't line up with the machine reading it.
+    class FormatError < StandardError; end
+
+    # A machine's state, held in memory: the Integers each chip writes in
+    # turn, and the byte strings for memories, names and paths. Booleans
+    # are written as 0 and 1. Computer#snapshot takes one and
+    # Computer#restore puts it back.
+    class State
+      # The layout the chips write their fields in. It goes up whenever a
+      # save_state writes something else, so a State in another layout
+      # fails before anything is read into a machine.
+      SCHEMA = 1
+
+      attr_reader :values, :strings
+
+      def initialize(values, strings)
+        @values = values
+        @strings = strings
+      end
+
+      def ==(other)
+        other.is_a?(State) && values == other.values && strings == other.strings
+      end
+    end
+
+    # Writes a State. Each chip's save_state writes its fields through one
+    # of these, and its load_state reads them back from a StateReader in
+    # the same order.
+    class StateWriter
+      attr_reader :state
+
+      def initialize
+        @values = []
+        @strings = []
+        @state = State.new(@values, @strings)
+      end
+
+      def int(value)
+        raise TypeError, "not an Integer: #{value.inspect}" unless value.is_a?(Integer)
+
+        @values << value.to_i
+        self
+      end
+
+      def boolean(value)
+        @values << (value ? 1 : 0)
+        self
+      end
+
+      def optional_int(value)
+        return boolean(false) if value.nil?
+
+        boolean(true).int(value)
+      end
+
+      def ints(values)
+        int(values.length)
+        values.each { |value| int(value) }
+        self
+      end
+
+      def booleans(values)
+        int(values.length)
+        values.each { |value| boolean(value) }
+        self
+      end
+
+      # Bytes, 0 to 255 each, kept as one string.
+      def blob(values)
+        @strings << values.pack("C*")
+        self
+      end
+
+      def string(value)
+        @strings << value.to_s.b
+        self
+      end
+
+      def optional_string(value)
+        return boolean(false) if value.nil?
+
+        boolean(true).string(value)
+      end
+
+      # A name a reader checks for, so a state that has gone out of step
+      # fails there instead of loading the wrong fields.
+      def marker(name) = string(name)
+
+      # The State's layout and the badline version writing it, which a
+      # reader checks first (StateReader#check_stamp).
+      def stamp = int(State::SCHEMA).string(VERSION)
+    end
+
+    # Reads a State back in the order a StateWriter wrote it.
+    #
+    # A detached reader restores a machine that opens no host file and
+    # writes none, for a copy the machine runs on its own: a disk image
+    # comes from the bytes the state holds, write-protected, a directory
+    # or .t64 archive device 8 serves and a tape are left out, and a true
+    # drive's disk keeps the state's tracks without its image file.
+    class StateReader
+      def initialize(state, detached: false)
+        @values = state.values
+        @strings = state.strings
+        @value = 0
+        @string = 0
+        @detached = detached
+      end
+
+      def detached? = @detached
+
+      def int
+        raise FormatError, "the state ends early, at value #{@value}" if @value >= @values.length
+
+        value = @values[@value]
+        @value += 1
+        value
+      end
+
+      def boolean?
+        value = int
+        raise FormatError, "expected a boolean in the state, found #{value}" unless value.between?(0, 1)
+
+        value == 1
+      end
+
+      def optional_int = boolean? ? int : nil
+
+      def ints = Array.new(int) { int }
+
+      def booleans = Array.new(int) { boolean? }
+
+      # Reads into an existing array, in place, so whatever else holds it
+      # sees the values.
+      def ints_into(array) = array.replace(ints)
+
+      def booleans_into(array) = array.replace(booleans)
+
+      def blob = string.bytes
+
+      def blob_into(array) = array.replace(blob)
+
+      def string
+        raise FormatError, "the state ends early, at string #{@string}" if @string >= @strings.length
+
+        value = @strings[@string]
+        @string += 1
+        value
+      end
+
+      def optional_string = boolean? ? string : nil
+
+      def marker(name)
+        found = string
+        raise FormatError, "expected #{name} in the state, found #{found[0, 20].inspect}" unless found == name
+      end
+
+      # Fails unless the State was written in this layout by this badline
+      # version.
+      def check_stamp
+        schema = int
+        version = string
+        return if schema == State::SCHEMA && version == VERSION
+
+        raise FormatError, "the state was written by badline #{version.inspect} in layout #{schema}, " \
+                           "and this is badline #{VERSION}, layout #{State::SCHEMA}"
+      end
+
+      # Whether every value and string has been read.
+      def finished? = @value == @values.length && @string == @strings.length
+    end
+  end
+end