badline 0.13.0 → 0.15.0

data/lib/badline/roms/README

@@ -132,3 +132,41 @@ c128/character.rom
 The character generator ROM, 390059-01 (characters.390059-01.bin),
 8 KB: the C64's set, the same as character.rom, followed by the C128's.
 SHA-1 29ed066d513f2d5c09ff26d9166ba23c2afb2b3f.
+
+Commodore 264 series ROMs
+=========================
+
+Downloaded from
+https://www.zimmers.net/anonftp/pub/cbm/firmware/computers/plus4/
+for the Plus/4, the C16 and the C116, which share BASIC and the KERNAL.
+Nothing maps them yet.
+
+plus4/basic.rom
+---------------
+BASIC 3.5, 318006-01 (basic.318006-01.bin), for $8000-$BFFF in ROM
+bank 0.
+SHA-1 161c96b4ad20f3a4f2321808e37a5ded26a135dd.
+
+plus4/kernal-pal.rom
+--------------------
+The PAL KERNAL, 318004-05 (kernal.318004-05.bin), for $C000-$FFFF in
+ROM bank 0, with the character set from $D000.
+SHA-1 7c7e07f016391174a557e790c4ef1cbe33512cdb.
+
+plus4/kernal-ntsc.rom
+---------------------
+The NTSC KERNAL, 318005-05 (kernal.318005-05.bin), for $C000-$FFFF in
+ROM bank 0.
+SHA-1 a3d9e5be091b98de39a046ab167fb7632d053682.
+
+plus4/function-low.rom
+----------------------
+The Plus/4's 3-plus-1 function ROM, low half, 317053-01
+(3-plus-1.317053-01.bin), for $8000-$BFFF in ROM bank 1.
+SHA-1 3b69f6e7cb4c18bb08e203fb18b7dabfa853390f.
+
+plus4/function-high.rom
+-----------------------
+The Plus/4's 3-plus-1 function ROM, high half, 317054-01
+(3-plus-1.317054-01.bin), for $C000-$FFFF in ROM bank 1.
+SHA-1 0ad7ac2db7da692d972e586ca0dfd747d82c7693.

data/lib/badline/snapshot/c128_setup.rb

@@ -7,31 +7,20 @@ module Badline
     C128Setup = Data.define(:model, :sid_model, :mode)
 
     class C128Setup
-      MARKER = "C128"
       SID_MODELS = %i[mos6581 mos8580].freeze
       MODES = %i[c64 c128].freeze
 
-      # The setup a C128's State starts with.
-      def self.from(state)
-        input = StateReader.new(state)
-        input.marker(MARKER)
-        input.check_stamp
-        read(input)
+      # The model, the SID and the mode by name, in a keyed snapshot module.
+      def write_fields(out)
+        out.text("model", model).text("sid_model", sid_model.to_s).text("mode", mode.to_s)
       end
 
-      def self.read(input)
-        model = input.string
-        known = C128::Model::ALL.any? { |candidate| candidate.name == model }
-        raise FormatError, "the state names a C128 model badline doesn't know" unless known
-
-        sid_model = SID_MODELS.fetch(input.int)
-        new(model:, sid_model:, mode: MODES.fetch(input.int))
-      rescue IndexError
-        raise FormatError, "the state names a SID or a mode badline doesn't know"
-      end
-
-      def write(out)
-        out.string(model).int(SID_MODELS.index(sid_model)).int(MODES.index(mode))
+      def self.read_fields(input)
+        model = input.choice("model", C128::Model::ALL.map(&:name), "c128")
+        sid = input.choice("sid_model", SID_MODELS.map(&:to_s), "mos6581")
+        mode = input.choice("mode", MODES.map(&:to_s), "c64")
+        new(model:, sid_model: SID_MODELS.find { |name| name.to_s == sid } || :mos6581,
+            mode: MODES.find { |name| name.to_s == mode } || :c64)
       end
 
       # A machine built this way, at power-on.

data/lib/badline/snapshot/c64_setup.rb

@@ -9,7 +9,6 @@ module Badline
                            :board)
 
     class C64Setup
-      MARKER = "COMPUTER"
       SID_MODELS = %i[mos6581 mos8580].freeze
       REGIONS = [Region::PAL, Region::NTSC, Region::NTSC_OLD, Region::DREAN].freeze
       RAM_EXPANSIONS = [:none, *C64::BankedRAM::TYPES.keys].freeze
@@ -22,23 +21,6 @@ module Badline
             kernal: address_bus.kernal, datasette: address_bus.datasette.connected?, board: address_bus.board)
       end
 
-      # The setup a C64's State starts with.
-      def self.from(state)
-        input = StateReader.new(state)
-        input.marker(MARKER)
-        input.check_stamp
-        read(input)
-      end
-
-      def self.read(input)
-        new(vic_model: Chips::VIC::MODELS.fetch(input.int), cia_model: Chips::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),
-            kernal: KERNALS.fetch(input.int), datasette: input.boolean?, board: BOARDS.fetch(input.int))
-      rescue IndexError
-        raise FormatError, "the state names a chip model, region, RAM expansion, KERNAL or board 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.
@@ -46,14 +28,36 @@ module Badline
         return nil if size_kb.zero?
         return size_kb if C64::REU::SIZES_KB.include?(size_kb)
 
-        raise FormatError, "the state names a #{size_kb}K REU, which badline doesn't build"
+        raise FormatError, "the snapshot names a #{size_kb}K REU, which badline doesn't build"
+      end
+
+      # The setup in a keyed snapshot module (Snapshot::Keyed), with each
+      # model, the region, the RAM expansion, the KERNAL and the board by
+      # name.
+      def write_fields(out)
+        out.text("vic_model", vic_model.to_s).text("cia_model", cia_model.to_s).text("sid_model", sid_model.to_s)
+        out.text("region", region.name.to_s).text("ram_expansion", (ram_expansion || :none).to_s)
+        out.int("reu_kb", reu || 0).text("kernal", kernal.to_s).bool("datasette", datasette)
+        out.text("board", board.to_s)
+      end
+
+      # The setup a keyed snapshot module names, a C64's at power-on for
+      # anything it leaves out or names that badline doesn't build.
+      def self.read_fields(input)
+        region = named(input, "region", REGIONS.map(&:name), :pal)
+        new(vic_model: named(input, "vic_model", Chips::VIC::MODELS, :mos6569),
+            cia_model: named(input, "cia_model", Chips::CIA::MODELS, :mos6526),
+            sid_model: named(input, "sid_model", SID_MODELS, :mos6581),
+            region: REGIONS.find { |each| each.name == region } || Region::PAL,
+            ram_expansion: ram_expansion(named(input, "ram_expansion", RAM_EXPANSIONS, :none)),
+            reu: reu(input.int("reu_kb", 0)), kernal: named(input, "kernal", KERNALS, :c64),
+            datasette: input.bool("datasette", true), board: named(input, "board", BOARDS, :c64))
       end
 
-      def write(out)
-        out.int(Chips::VIC::MODELS.index(vic_model)).int(Chips::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)
-        out.int(KERNALS.index(kernal)).boolean(datasette).int(BOARDS.index(board))
+      # The Symbol of `names` the text at `key` names.
+      def self.named(input, key, names, default)
+        text = input.choice(key, names.map(&:to_s), default.to_s)
+        names.find { |name| name.to_s == text } || default
       end
 
       # A machine built this way, at power-on.

data/lib/badline/snapshot/container.rb

@@ -4,6 +4,10 @@ require "zlib"
 
 module Badline
   module Snapshot
+    # A file that isn't a snapshot badline reads, is cut short, or is of a
+    # machine built another way.
+    class FormatError < StandardError; end
+
     # 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
@@ -30,6 +34,8 @@ module Badline
       VIC20 = "VIC20"
       # x128 names its machine C128.
       C128 = "C128"
+      # xplus4 names its machine PLUS4, for the C16 too.
+      PLUS4 = "PLUS4"
       GZIP_MAGIC = "\x1f\x8b".b
 
       # The VICE version block, when VICE wrote the file: four version

data/lib/badline/snapshot/field_doc/markdown.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module FieldDoc
+      # The doc's markdown: one table per module, of each key, its type and
+      # its default, with keys that differ only in a unit's number, such as
+      # voice1 to voice3, on one row.
+      class Markdown
+        NAMES = { "c64" => "C64", "vic20" => "VIC-20", "c128" => "C128", "plus4" => "Plus/4" }.freeze
+        TAG_TYPES = { Keyed::INT => "int", Keyed::BOOL => "bool", Keyed::BYTES => "bytes", Keyed::INTS => "ints",
+                      Keyed::TEXT => "text" }.freeze
+
+        # A row: the key, the type, and the defaults each family whose
+        # machines read or write it reads it with.
+        Row = Struct.new(:key, :type, :defaults)
+
+        INTRO = <<~MARKDOWN
+          # Snapshot format
+
+          This file is generated by `rake snapshot:fields` from the code that
+          loads a snapshot. Don't edit it by hand. doc/snapshots.md covers
+          what a snapshot holds and which versions load.
+
+          A snapshot is a VICE `.vsf` container. The machine is in modules
+          named `BL-` plus a unit, each a deflated list of records: a key, a
+          type and a value. The types are `int` (a zigzag BER integer), `bool`,
+          `bytes`, `ints` (a list of integers) and `text`. A load skips a key
+          it doesn't know, and a key that isn't there leaves the value a
+          machine built afresh has: the default below. `word`, `byte` and
+          `int & 0x..` are ints cut to the latch's width. A text that lists
+          its values takes one of them. An optional int is absent when the
+          latch holds nothing. A true drive's modules are named from its
+          device number, `BL-D8` to `BL-D11`, and the SIDs past the first
+          are `BL-SID2` onwards, in the order they were fitted. Keys with
+          `<N>` stand for each numbered unit. A default of "written only" is
+          a key the load doesn't read, or reads only when the snapshot has
+          it. Where the machines differ, the default is given for each, and a
+          key only some of them have names them.
+        MARKDOWN
+
+        def initialize(loads)
+          @modules = {}
+          loads.each { |load| add(load) }
+        end
+
+        def to_s
+          sections = @modules.map do |name, rows|
+            families = rows.values.flat_map { |row| row.defaults.keys }.uniq
+            ["## #{name}", "", "Written by the #{families.map { |family| NAMES.fetch(family) }.join(', ')}.", "",
+             "| Key | Type | Default |", "| --- | --- | --- |",
+             *rows.values.map { |row| line(row, families) }].join("\n")
+          end
+          "#{INTRO}\n#{sections.join("\n\n")}\n"
+        end
+
+        private
+
+        def add(load)
+          load.fields.each do |name, fields|
+            numbered = numbered_keys(load.written[name].keys + fields.map(&:key))
+            fields.each { |field| note(name, numbered.fetch(field.key, field.key), field.type, load.family, field) }
+            read = fields.to_set(&:key)
+            load.written[name].each do |key, tag|
+              next if read.include?(key)
+
+              note(name, numbered.fetch(key, key), TAG_TYPES.fetch(tag, "?"), load.family, nil)
+            end
+          end
+        end
+
+        def note(name, key, type, family, field)
+          row = (@modules[name] ||= {})[key] ||= Row.new(key, type, {})
+          (row.defaults[family] ||= []) << (field ? brief(field.default, field.type) : "written only")
+        end
+
+        # Keys that differ only in a number, as the same key with <N>: each
+        # key whose number another key in the module shares the rest of.
+        def numbered_keys(keys)
+          groups = keys.uniq.group_by { |key| key.gsub(/(?<=[a-z])\d+(?=\.|\z)/, "<N>") }
+          groups.each_with_object({}) do |(general, members), numbered|
+            members.each { |key| numbered[key] = general } if members.length > 1
+          end
+        end
+
+        def line(row, families)
+          each = row.defaults.transform_values { |defaults| summary(defaults.uniq) }
+          default = if each.values.uniq.length == 1 && each.length == families.length then each.values.first
+                    else each.map { |family, value| "#{NAMES.fetch(family)}: #{value}" }.join("; ")
+                    end
+          "| `#{row.key}` | #{row.type} | #{default} |"
+        end
+
+        def summary(defaults) = defaults.length > 3 ? "varies" : defaults.join(" or ")
+
+        def brief(value, type)
+          case value
+          when nil then "absent"
+          when Array then list(value)
+          when String then type.start_with?("bytes") ? list(value.bytes) : value.inspect
+          else value.to_s
+          end
+        end
+
+        def list(values)
+          return values.inspect if values.length <= 8
+
+          values.uniq.length == 1 ? "#{values.length} × #{values.first}" : "#{values.length} values"
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/field_doc.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "badline"
+require "badline/c128"
+require "badline/plus4"
+
+module Badline
+  module Snapshot
+    # doc/snapshot-format.md, written by running the code: each family's
+    # machine is saved with its attachments, and its modules loaded into a
+    # machine built the same way at power-on through Keyed::Recorders,
+    # which note every key read with its type and the value the new machine
+    # had, its default. `rake snapshot:fields` writes it, and a spec checks
+    # that the file matches.
+    module FieldDoc
+      PATH = File.expand_path("../../../doc/snapshot-format.md", __dir__)
+
+      # Modules read through Recorders.
+      class RecordingModules < Keyed::Modules
+        private
+
+        def parse(section) = Keyed::Recorder.parse(section)
+
+        def missing(name) = Keyed::Recorder.missing(name)
+      end
+
+      # One machine saved and loaded: the family it belongs to, and for
+      # each module the keys its records hold, with their tags, and the fields the load read.
+      Load = Data.define(:family, :written, :fields)
+
+      # The cartridges by CRT hardware type: EasyFlash, then a mapper of
+      # each kind of register: Ocean's bank, Comal-80's bank for both
+      # windows, Zaxxon's ROMH bank, and the Action Replay's and the
+      # Pagefox's control registers.
+      CARTRIDGES = [32, 5, 21, 18, 1, 53].freeze
+
+      # The machines the doc is made from: each family at power-on, the C64
+      # with each kind of expansion, cartridge and media, and a second SID,
+      # and the 264 series' models, its TCBM interface, cartridge, tape and
+      # true drive.
+      def self.machines
+        {
+          "c64" => [C64.new, C64.new(ram_expansion: :plus256k), C64.new(reu: 512),
+                    *CARTRIDGES.map { |type| with_cartridge(type) }, with_trap_dos, with_tape, with_drive(:d64),
+                    with_drive(:d81), with_extra_sids],
+          "vic20" => [Vic20.new, with_rom],
+          "c128" => [C128.new(mode: :c128), with_drive(:d71)],
+          "plus4" => [Plus4.new, Plus4.new(model: "c16"), Plus4.new(tcbm: true), plus4_with_cartridge,
+                      plus4_with_tape, plus4_with_drive]
+        }
+      end
+
+      def self.blank(length) = Array.new(length, 0)
+
+      def self.with_cartridge(type)
+        chips = [0x8000, 0xa000].map do |address|
+          Storage::CRTFile::Chip.new(chip_type: 2, bank: 0, address:, data: blank(0x2000))
+        end
+        image = Storage::CRTFile::Image.new(hardware_type: type, subtype: 0, exrom: 1, game: 0, name: "DOC", chips:)
+        C64.new.tap do |machine|
+          machine.attach_cartridge(C64::Cartridge.from_crt(Storage::CRTFile.new(bytes: Storage::CRTFile.encode(image))))
+        end
+      end
+
+      # The SID player's machine for a tune on two SIDs.
+      def self.with_extra_sids
+        C64.new.tap { |machine| machine.address_bus.add_sid(Chips::SID.new(at: 0xd420)) }
+      end
+
+      def self.with_trap_dos
+        C64.new.tap { |machine| machine.mount(Storage::D64Image.new("", read_only: true, bytes: blank(174_848))) }
+      end
+
+      def self.with_tape
+        bytes = "C64-TAPE-RAW".bytes + [1, 0, 0, 0, 4, 0, 0, 0, 0x30, 0x30, 0x30, 0x30]
+        C64.new.tap { |machine| machine.datasette.insert(Storage::TAP.new("", bytes:)) }
+      end
+
+      def self.with_drive(kind)
+        case kind
+        when :d81
+          C64.new.tap do |machine|
+            machine.plug_drive1581.insert(Drives::Model1581::Disk.new(Storage::D81Image.new("", bytes: blank(819_200))))
+          end
+        when :d71
+          C128.new(mode: :c128).tap do |machine|
+            image = Storage::D71Image.new("", bytes: blank(349_696))
+            machine.plug_true_drive.insert(Drives::Model1541::Disk.decode(image))
+          end
+        else
+          C64.new.tap do |machine|
+            image = Storage::D64Image.new("", bytes: blank(174_848))
+            machine.plug_true_drive.insert(Drives::Model1541::Disk.decode(image))
+          end
+        end
+      end
+
+      # A Plus/4 with a cartridge in each of cartridge 1's slots.
+      def self.plus4_with_cartridge
+        chips = [0x8000, 0xc000].map do |address|
+          Storage::CRTFile::Chip.new(chip_type: 0, bank: 0, address:, data: blank(0x4000))
+        end
+        Plus4.new.tap { |machine| machine.attach_cartridge(chips) }
+      end
+
+      # A C16 with a version 2 tape in its datasette, which times the read
+      # line's level.
+      def self.plus4_with_tape
+        bytes = "C16-TAPE-RAW".bytes + [2, 2, 0, 0, 4, 0, 0, 0, 0x30, 0x30, 0x30, 0x30]
+        Plus4.new(model: "c16").tap { |machine| machine.datasette.insert(Storage::TAP.new("", bytes:)) }
+      end
+
+      def self.plus4_with_drive
+        Plus4.new.tap do |machine|
+          image = Storage::D64Image.new("", bytes: blank(174_848))
+          machine.plug_true_drive.insert(Drives::Model1541::Disk.decode(image))
+        end
+      end
+
+      def self.with_rom
+        Vic20.new.tap { |machine| machine.bus.map_rom(0xa000, blank(0x2000)) }
+      end
+
+      # Saves `machine` and loads it into a new one through Recorders.
+      def self.load(family, machine)
+        modules = RecordingModules.new(Image.of(machine).sections)
+        Image.setup(modules.machine).build.load_modules(modules)
+        modules.machine.text("written_by", "")
+        written = {}
+        fields = {}
+        modules.readers.each do |reader|
+          written[reader.name] = reader.tags
+          fields[reader.name] = reader.fields
+        end
+        Load.new(family:, written:, fields:)
+      end
+
+      def self.loads = machines.flat_map { |family, list| list.map { |machine| load(family, machine) } }
+
+      # The doc, as markdown.
+      def self.markdown(loads = self.loads) = Markdown.new(loads).to_s
+
+      def self.write(path = PATH) = File.write(path, markdown)
+    end
+  end
+end
+
+require "badline/snapshot/field_doc/markdown"

data/lib/badline/snapshot/image.rb

@@ -2,37 +2,115 @@
 
 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 snapshot read from a file.
+      # 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: 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", "plus4" => "Plus/4" }.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. Raises FormatError for a Plus/4, whose
+      # snapshots badline doesn't write for xplus4.
+      def self.exported(computer)
+        raise FormatError, "badline doesn't export a Plus/4's snapshot for VICE" if computer.family == :plus4
+
+        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
+        when :plus4 then Container::PLUS4
+        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)
+        when "plus4" then Plus4Setup.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
 
-      # The State the BADLINE module holds.
-      def state = MachineState.state(section)
+      def ==(other) = other.is_a?(Image) && to_s == other.to_s
+
+      # 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. xvic's and x128's own modules aren't read.
-      # Yields a line for each thing left out, or warns it without a block.
-      def load(&)
+      # badline snapshot restores from its BL-* modules alone, and a VICE
+      # one through the modules badline reads. xvic's, x128's and xplus4'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?
+        raise FormatError, "badline reads only its own Plus/4 snapshots, not xplus4's" if plus4? && !badline?
+        return load_vice(&) unless badline?
 
-        computer = badline? ? opening { Setup.restored(state) } : Vice.setup(@container).build
-        tell(badline? ? state_report(computer) : Vice::Restore.apply(@container, computer), &)
+        modules = Keyed::Modules.new(sections, detached:)
+        computer = opening { Image.setup(modules.machine).build.load_modules(modules) }
+        tell(report(modules, computer), &)
         computer
       end
 
@@ -42,25 +120,58 @@ 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.
+      # Whether the machine is of the 264 series, as the container names it.
+      def plus4? = @container.machine == Container::PLUS4
+
+      # 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]
+      def load_vice(&)
+        computer = Vice.setup(@container).build
+        tell(Vice::Restore.apply(@container, computer), &)
+        computer
+      end
 
-      def tell(report)
-        report.ignored.each { |line| block_given? ? yield(line) : warn("badline: #{line}") }
+      # 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
 
-      def restore_state(computer)
-        opening { computer.restore(state) }
-        state_report(computer)
+      # 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?
+
+        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 opening
@@ -69,10 +180,14 @@ module Badline
         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