badline 0.12.1 → 0.14.0

data/lib/badline/snapshot/image.rb

@@ -2,37 +2,109 @@
 
 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)
+    # What a restore applied and what it left out: module names and a line
+    # for each thing left out or changed, saying why. For a badline
+    # snapshot, `modules` holds each BL-* module's Keyed::Report, which
+    # give the fields per module this badline doesn't know, the modules it
+    # expected and didn't find, and the values it read other than as
+    # written, and `written_by` the badline version that saved it.
+    class Report
+      attr_reader :applied, :ignored, :written_by
+
+      def initialize(applied:, ignored:, modules: [], written_by: "")
+        @applied = applied
+        @ignored = ignored
+        @modules = modules
+        @written_by = written_by
+      end
+
+      # The keys nothing read, by module, for the modules that had any.
+      def unknown
+        @modules.reject { |report| report.unknown.empty? }.to_h { |report| [report.name, report.unknown] }
+      end
+
+      # The modules the snapshot didn't have.
+      def missing = @modules.select(&:missing).map(&:name)
+
+      # A line for each value read other than as written.
+      def adjusted = @modules.flat_map { |report| report.adjusted.map { |line| "#{report.name}: #{line}" } }
+    end
 
-    # A snapshot read from a file.
+    # A snapshot: the container and its modules, read from a file or taken
+    # of a machine in memory (.of).
     class Image
+      MACHINE = "BL-MACHINE"
+      FAMILIES = { "c64" => "C64", "vic20" => "VIC-20", "c128" => "C128" }.freeze
+
       attr_reader :container
 
-      def initialize(container)
+      # `name` is what a refusal calls the snapshot, such as its file's name.
+      def initialize(container, name: "the snapshot")
         @container = container
+        @name = name
+      end
+
+      # The machine's snapshot, saved as a file saves it: the machine runs
+      # on to the end of the instruction its CPU is in, and of an REU
+      # transfer under way (Machine::Settling), then writes its BL-*
+      # modules.
+      def self.of(computer)
+        computer.settle_for_snapshot!
+        new(Container.new(computer.save_modules, machine: machine_name(computer)))
+      end
+
+      # The snapshot with VICE's modules ahead of the BL-* ones for a C64,
+      # so x64sc opens it too.
+      def self.exported(computer)
+        computer.settle_for_snapshot!
+        sections = computer.save_modules
+        sections = Vice.export(computer) + sections if computer.family == :c64
+        new(Container.new(sections, machine: machine_name(computer)))
+      end
+
+      # The machine as VICE's emulators name it.
+      def self.machine_name(computer)
+        case computer.family
+        when :vic20 then Container::VIC20
+        when :c128 then Container::C128
+        else Container::MACHINE
+        end
+      end
+
+      # How the machine was built, from the family BL-MACHINE, read by
+      # `machine`, names.
+      def self.setup(machine)
+        case machine.choice("family", FAMILIES.keys, "c64")
+        when "vic20" then Vic20Setup.read_fields(machine)
+        when "c128" then C128Setup.read_fields(machine)
+        else C64Setup.read_fields(machine)
+        end
       end
 
       def sections = @container.sections
 
-      # Whether badline wrote it, with the whole machine in a BADLINE module.
-      def badline? = !section.nil?
+      def to_s = @container.to_s
+
+      def ==(other) = other.is_a?(Image) && to_s == other.to_s
 
-      # The State the BADLINE module holds.
-      def state = MachineState.state(section)
+      # Whether badline wrote it, with the whole machine in BL-* modules.
+      def badline? = !@container[MACHINE].nil?
 
       # 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(&)
-        return load_vic20(&) if vic20?
-        return load_c128(&) if c128?
-
-        computer = badline? ? opening { Computer.restored(state) } : Vice.setup(@container).build
-        tell(badline? ? state_report(computer) : Vice::Restore.apply(@container, computer), &)
+      # badline snapshot restores from its BL-* modules alone, and a VICE
+      # one through the modules badline reads. xvic's and x128's own
+      # modules aren't read. Yields a line for each thing left out, or
+      # warns it without a block. `detached` restores it without the host's
+      # files (Keyed::Modules).
+      def load(detached: false, &)
+        refuse_old_layout
+        raise FormatError, "badline reads only its own VIC-20 snapshots, not xvic's" if vic20? && !badline?
+        raise FormatError, "badline reads only its own C128 snapshots, not x128's" if c128? && !badline?
+        return load_vice(&) unless badline?
+
+        modules = Keyed::Modules.new(sections, detached:)
+        computer = opening { Image.setup(modules.machine).build.load_modules(modules) }
+        tell(report(modules, computer), &)
         computer
       end
 
@@ -42,57 +114,71 @@ module Badline
       # Whether the machine is a C128, as the container names it.
       def c128? = @container.machine == Container::C128
 
-      # Restores `computer` from the snapshot, and returns the Report. A
-      # snapshot that fails leaves the machine as it was.
+      # Restores `computer` from the snapshot, and returns the Report. The
+      # snapshot goes into a new machine first, so one that fails, or is of
+      # a machine built another way, leaves `computer` as it was.
       def restore(computer, &)
-        report = badline? ? restore_state(computer) : Vice::Restore.import(@container, computer)
+        refuse_old_layout
+        report = badline? ? restore_modules(computer) : Vice::Restore.import(@container, computer)
         tell(report, &)
         report
       end
 
       private
 
-      def section = @container[MachineState::NAME]
-
-      # A VIC-20 restores from its BADLINE module alone. xvic's own modules
-      # aren't read.
-      def load_vic20(&)
-        raise FormatError, "badline reads only its own VIC-20 snapshots, not xvic's" unless badline?
+      def load_vice(&)
+        computer = Vice.setup(@container).build
+        tell(Vice::Restore.apply(@container, computer), &)
+        computer
+      end
 
-        machine = Vic20.restored(state)
-        tell(state_report(machine), &)
-        machine
+      # The snapshot goes into a new machine first, so one that fails
+      # leaves `computer` as it was.
+      def restore_modules(computer)
+        modules = Keyed::Modules.new(sections)
+        family = modules.machine.choice("family", FAMILIES.keys, "c64")
+        unless family == computer.family.to_s
+          raise FormatError, "the snapshot is of a #{FAMILIES.fetch(family, family)}, " \
+                             "not a #{FAMILIES.fetch(computer.family.to_s)}"
+        end
+
+        trial = Keyed::Modules.new(sections)
+        opening { Image.setup(trial.machine).build.load_modules(trial) }
+        opening { computer.load_modules(modules) }
+        report(modules, computer)
       end
 
-      # A C128 restores from its BADLINE module alone. x128's own modules
-      # aren't read.
-      def load_c128(&)
-        raise FormatError, "badline reads only its own C128 snapshots, not x128's" unless badline?
+      # A snapshot from a badline before the keyed modules, which only the
+      # version that saved it reads.
+      def refuse_old_layout
+        old = @container[MachineState::NAME]
+        return if old.nil? || badline?
+
+        version = MachineState.written_by(old)
+        layout = "in the old snapshot layout, which this badline can't read."
+        raise FormatError, "#{@name} was saved by an earlier badline #{layout}" if version.empty?
 
-        machine = C128.restored(state)
-        tell(state_report(machine), &)
-        machine
+        raise FormatError, "#{@name} was saved by badline #{version} #{layout} It still opens in badline #{version}."
       end
 
       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)
+      def report(modules, computer)
+        written_by = modules.machine.text("written_by", "")
+        reports = modules.readers.map(&:report)
+        ignored = reports.flat_map(&:lines)
+        ignored.concat(modules.unread.map { |name| "#{name}: badline doesn't read this module, left out" })
         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:)
+        ignored << "#{lost} on_init handler(s) the saved machine had yet to run, left out" if lost.positive?
+        Report.new(applied: reports.reject(&:missing).map(&:name), ignored:, modules: reports, written_by:)
       end
     end
   end

data/lib/badline/snapshot/keyed/cursor.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # Reads BER numbers and byte runs from a module's payload, or from one
+      # record's value, failing on anything cut short.
+      class Cursor
+        def initialize(bytes, name)
+          @bytes = bytes
+          @name = name
+          @pos = 0
+        end
+
+        def done? = @pos >= @bytes.bytesize
+
+        def remaining = @bytes.bytesize - @pos
+
+        def ber
+          value = 0
+          loop do
+            raise FormatError, "#{@name} holds a number too large for a snapshot" if value >= (1 << 56)
+
+            byte = take(1).getbyte(0).to_i
+            value = (value << 7) | (byte & 0x7f)
+            return value if byte < 0x80
+          end
+        end
+
+        def int = Keyed.unzigzag(ber)
+
+        def take(count)
+          raise FormatError, "#{@name} ends early, at byte #{@bytes.bytesize}" if count > remaining
+
+          @bytes.byteslice(@pos, count).to_s.tap { @pos += count }
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed/modules.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # A snapshot's BL-* modules by name, which a family reads in its own
+      # fixed order, whatever order the file has them in. Each module is
+      # parsed once, and its Reader kept for the Report.
+      #
+      # A `detached` load restores a machine that opens no host file and
+      # writes none: a disk image comes from the bytes the snapshot holds,
+      # write-protected, and a directory device 8 serves is left out.
+      class Modules
+        attr_reader :readers
+
+        def initialize(sections, detached: false)
+          @sections = {}
+          sections.each { |section| @sections[section.name] = section }
+          @parsed = {}
+          @readers = []
+          @detached = detached
+        end
+
+        def detached? = @detached
+
+        # BL-MACHINE, which every family writes first.
+        def machine = required("BL-MACHINE")
+
+        # The module a family always writes, or a Reader standing in for it,
+        # reported missing.
+        def required(name)
+          reader = @parsed[name]
+          return reader if reader
+
+          section = @sections[name]
+          keep(name, section.nil? ? missing(name) : parse(section))
+        end
+
+        # The module, or nil when the snapshot has none, as it has none for a
+        # cartridge or a drive that isn't there.
+        def optional(name)
+          reader = @parsed[name]
+          return reader if reader
+
+          section = @sections[name]
+          section.nil? ? nil : keep(name, parse(section))
+        end
+
+        # The BL-* modules no family read, from a later badline.
+        def unread = @sections.keys.select { |name| name.start_with?("BL-") && !@parsed.key?(name) }
+
+        private
+
+        def parse(section) = Reader.parse(section)
+
+        def missing(name) = Reader.missing(name)
+
+        def keep(name, reader)
+          @parsed[name] = reader
+          @readers << reader
+          reader
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed/reader.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # Parses a module's records into one Hash per type, so every value
+      # read has a single type in Spinel. Each read takes the current value
+      # as its default, which in a machine built for the load is power-on,
+      # and returns it when the record is missing or of another type.
+      #
+      # A Reader with no records stands in for a module the snapshot
+      # doesn't have, so every load takes the same path.
+      class Reader
+        # The tag of each key the module's records hold.
+        attr_reader :name, :tags
+
+        # Whether it stands in for a module the snapshot doesn't have.
+        def missing? = @missing
+
+        # The records in `section`, which must be in this encoding.
+        def self.parse(section)
+          unless section.major == MAJOR
+            raise FormatError, "#{section.name} #{section.version} was written by a newer badline's encoding, " \
+                               "and this one reads #{MAJOR}.#{MINOR}"
+          end
+
+          new(section.name, Zlib.inflate(section.data))
+        rescue Zlib::Error => e
+          raise FormatError, "#{section.name} is damaged: #{e.message}"
+        end
+
+        # Stands in for a module the snapshot doesn't have.
+        def self.missing(name) = new(name, "".b, missing: true)
+
+        def initialize(name, payload = "".b, missing: false)
+          @name = name
+          @missing = missing
+          @ints = {}
+          @bools = {}
+          @bytes = {}
+          @lists = {}
+          @texts = {}
+          @tags = {}
+          @read = {}
+          @adjusted = []
+          @unknown_tags = 0
+          parse(Cursor.new(payload, name))
+        end
+
+        def int(key, default) = fetch_int(key, default)
+
+        def word(key, default) = fetch_masked(key, default, 0xffff)
+
+        def byte(key, default) = fetch_masked(key, default, 0xff)
+
+        # An int cut to the bits a latch holds, reported if it was wider.
+        def masked(key, default, mask) = fetch_masked(key, default, mask)
+
+        def bool(key, default) = present?(key, "a bool", @bools.key?(key)) ? @bools.fetch(key) : default
+
+        # Nil when the record is missing.
+        def optional_int(key) = present?(key, "an int", @ints.key?(key)) ? @ints.fetch(key) : nil
+
+        def ints(key, default) = present?(key, "a list of ints", @lists.key?(key)) ? @lists.fetch(key) : default
+
+        # A binary String.
+        def bytes(key, default) = fetch_bytes(key, default)
+
+        # Reads a hardware array into `array` in place. A shorter list
+        # leaves the rest as it was and a longer one is cut, and both are
+        # reported.
+        def ints_into(key, array)
+          return array unless present?(key, "a list of ints", @lists.key?(key))
+
+          fill(key, array, @lists.fetch(key))
+        end
+
+        def bytes_into(key, array)
+          return array unless present?(key, "bytes", @bytes.key?(key))
+
+          fill(key, array, @bytes.fetch(key).bytes)
+        end
+
+        def text(key, default) = fetch_text(key, default)
+
+        # The text, if it is one of `names`, and otherwise `default`,
+        # reported.
+        def choice(key, names, default)
+          value = fetch_text(key, default)
+          return value if names.include?(value)
+
+          @adjusted << "#{key} #{value.inspect} is not one of #{names.join(', ')}, left at #{default}"
+          default
+        end
+
+        # Reports something a unit's load left out or changed beyond one
+        # field, such as a line batch from another renderer.
+        def adjust(line)
+          @adjusted << line
+          self
+        end
+
+        # The keys of records nothing read.
+        def unknown = @tags.keys.reject { |key| @read.key?(key) }
+
+        def report
+          Report.new(name:, missing: @missing, unknown:, adjusted: @adjusted.dup, unknown_tags: @unknown_tags)
+        end
+
+        private
+
+        def fetch_int(key, default) = present?(key, "an int", @ints.key?(key)) ? @ints.fetch(key) : default
+
+        def fetch_masked(key, default, mask)
+          value = fetch_int(key, default)
+          return value if value & mask == value
+
+          @adjusted << "#{key} #{value} is wider than its latch, masked to #{value & mask}"
+          value & mask
+        end
+
+        def fetch_bytes(key, default) = present?(key, "bytes", @bytes.key?(key)) ? @bytes.fetch(key) : default
+
+        def fetch_text(key, default) = present?(key, "text", @texts.key?(key)) ? @texts.fetch(key) : default
+
+        # Whether the key has a record of the type read, `there`. A record
+        # of another type counts as missing, and is reported.
+        def present?(key, type, there)
+          @read[key] = true if there || @tags.key?(key)
+          @adjusted << "#{key} is not #{type}, left at its default" if !there && @tags.key?(key)
+          there
+        end
+
+        def fill(key, array, values)
+          unless values.length == array.length
+            what = values.length < array.length ? "the rest left as they were" : "the rest cut"
+            @adjusted << "#{key} holds #{values.length} values where #{array.length} fit, #{what}"
+          end
+          [values.length, array.length].min.times { |index| array[index] = values[index] }
+          array
+        end
+
+        def parse(cursor)
+          until cursor.done?
+            key = cursor.take(cursor.ber)
+            tag = cursor.take(1).getbyte(0).to_i
+            store(key, tag, cursor.take(cursor.ber))
+          end
+        end
+
+        def store(key, tag, value)
+          unless tag.between?(INT, TEXT)
+            @unknown_tags += 1
+            return
+          end
+
+          forget(key)
+          @tags[key] = tag
+          case tag
+          when INT then @ints[key] = Cursor.new(value, "#{@name} #{key}").int
+          when BOOL then @bools[key] = value.getbyte(0).to_i != 0
+          when BYTES then @bytes[key] = value
+          when INTS then @lists[key] = list(Cursor.new(value, "#{@name} #{key}"))
+          else @texts[key] = value.force_encoding(Encoding::UTF_8)
+          end
+        end
+
+        def forget(key)
+          return unless @tags.key?(key)
+
+          @adjusted << "#{key} appears more than once, the last one counts"
+          @ints.delete(key)
+          @bools.delete(key)
+          @bytes.delete(key)
+          @lists.delete(key)
+          @texts.delete(key)
+        end
+
+        def list(cursor)
+          count = cursor.ber
+          raise FormatError, "#{@name} ends early, in a list of #{count}" if count > cursor.remaining
+
+          Array.new(count) { cursor.int }
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed/recorder.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # A Reader that notes every read: the module, the key, the type read
+      # and the default passed. Loading a machine at power-on through
+      # Recorders lists each module's fields with their power-on values
+      # (FieldDoc).
+      class Recorder < Reader
+        Field = Data.define(:module_name, :key, :type, :default)
+
+        attr_reader :fields
+
+        def initialize(name, payload = "".b, missing: false)
+          super
+          @fields = []
+        end
+
+        def int(key, default)
+          note(key, "int", default)
+          super
+        end
+
+        def word(key, default)
+          note(key, "word", default)
+          super
+        end
+
+        def byte(key, default)
+          note(key, "byte", default)
+          super
+        end
+
+        def masked(key, default, mask)
+          note(key, "int & 0x#{mask.to_s(16)}", default)
+          super
+        end
+
+        def bool(key, default)
+          note(key, "bool", default)
+          super
+        end
+
+        def optional_int(key)
+          note(key, "int, optional", nil)
+          super
+        end
+
+        def ints(key, default)
+          note(key, "ints", default.dup)
+          super
+        end
+
+        def bytes(key, default)
+          note(key, "bytes", default.dup)
+          super
+        end
+
+        def ints_into(key, array)
+          note(key, "ints", array.dup)
+          super
+        end
+
+        def bytes_into(key, array)
+          note(key, "bytes", array.dup)
+          super
+        end
+
+        def text(key, default)
+          note(key, "text", default)
+          super
+        end
+
+        def choice(key, names, default)
+          note(key, "text: #{names.join(' ')}", default)
+          super
+        end
+
+        private
+
+        def note(key, type, default)
+          @fields << Field.new(module_name: name, key:, type:, default:)
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/keyed/report.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Keyed
+      # What reading a module left out or changed: whether the snapshot
+      # had the module at all, the keys nothing read, a line for each value
+      # read other than as written, and how many records had a tag this
+      # badline doesn't know.
+      Report = Data.define(:name, :missing, :unknown, :adjusted, :unknown_tags) do
+        # Lines for the user. A missing module and adjusted values always
+        # get one, and unknown keys and tags only when `verbose`, since a
+        # snapshot from a later badline has them on every load.
+        def lines(verbose: false)
+          lines = missing ? ["#{name} is missing, left at power-on"] : []
+          lines.concat(adjusted.map { |line| "#{name}: #{line}" })
+          return lines unless verbose
+
+          lines << "#{name}: #{unknown.length} unknown field(s): #{unknown.join(', ')}" unless unknown.empty?
+          lines << "#{name}: #{unknown_tags} field(s) of an unknown type, skipped" if unknown_tags.positive?
+          lines
+        end
+      end
+    end
+  end
+end