badline 0.14.0 → 0.15.1

data/lib/badline/plus4.rb

@@ -2,28 +2,53 @@
 
 require "badline/chips/ted"
 require "badline/chips/tia"
+require "badline/drives/model1551"
 require "badline/plus4/model"
 require "badline/plus4/cpu"
 require "badline/plus4/cpu_port"
 require "badline/plus4/keyboard_port"
 require "badline/plus4/user_port"
+require "badline/plus4/cassette_sense"
 require "badline/plus4/acia"
+require "badline/plus4/sid_card"
+require "badline/plus4/sound_mix"
+require "badline/plus4/ram_expansion"
 require "badline/plus4/bus"
+require "badline/plus4/tcbm_drive"
+require "badline/snapshot/plus4_setup"
+require "badline/plus4/keyed_parts"
+require "badline/plus4/keyed_state"
+require "badline/plus4/keyed_modules"
 
 module Badline
   # The Commodore 264 series: the Plus/4, the C16 and the C116. A 7501 on
   # the TED's clock, which runs it once or twice a TED cycle (Chips::TED's
   # Beam), the TED and, on the Plus/4, a 6551 ACIA and the user port's
-  # 6529. Only the TED pulls IRQ, and nothing pulls NMI, which the 7501
-  # doesn't have.
+  # 6529. The TED and the ACIA pull IRQ, and nothing pulls NMI, which the
+  # 7501 doesn't have.
   #
-  # It runs headless only: the TED paints no picture yet. Device 8
-  # serves disks through the KERNAL traps (C64::KernalTraps), and
-  # cartridges go in cartridge 1's slots.
+  # The TED paints the picture a front end shows (#video, #timing). Device 8
+  # serves disks through the KERNAL traps (C64::KernalTraps), or a true
+  # 1541 or 1581 on the serial bus or a 1551 on TCBM does (TCBMDrive),
+  # cartridges go
+  # in the two cartridges' slots, and tapes play on the datasette, whose read
+  # line's level the KERNAL times with the TED's timers.
+  #
+  # A SID card, as third parties built for the 264s, puts a SID at
+  # $FD40-$FD5F, or at $FE80-$FE9F as Csory's does. The cards clock it from the TED's single clock, one SID
+  # cycle a TED cycle, 886,724 Hz on PAL, below the C64's 985,248 Hz, so a
+  # C64 tune plays about a semitone flat (plus4world forum threads 38287
+  # and 20130).
+  #
+  # A RAM expansion, Hannes's 256K or 1M or Csory's 256K, banks more RAM
+  # in through a register at $FD16 (RAMExpansion).
   class Plus4
     include IntegerHelper
     include Machine::KeyboardBuffer
     include Machine::Clocking
+    include Machine::Settling
+    include C64::TrueDrives
+    include TCBMDrive
     include C64::KernalTraps
 
     # The cycle by which the KERNAL has booted and BASIC printed READY,
@@ -31,15 +56,42 @@ module Badline
     # Plus/4, 126,000 on an NTSC one and sooner on a C16.
     INIT_THRESHOLD = 200_000
 
-    attr_reader :model, :bus, :cpu, :ted, :port, :keyboard, :keyboard_port, :acia, :user_port, :datasette, :tias,
-                :iec_bus, :cycles, :ram_kb
+    # The cycle by which a 1541 switched on with the machine has run its
+    # DOS's reset, the RAM test and the ROM checksum, and waits on the
+    # bus, with a margin, in TED cycles.
+    DRIVE_BOOT_CYCLES = 1_200_000
+
+    attr_reader :model, :bus, :cpu, :ted, :sound, :port, :keyboard, :keyboard_port, :joystick1, :joystick2, :acia,
+                :user_port, :datasette, :tias, :iec_bus, :cycles, :ram_kb, :drive1541, :init_threshold, :sid_card
 
     def family = :plus4
 
-    def init_threshold = INIT_THRESHOLD
+    # The joysticks reach the TED's keyboard latch, so there are no C64
+    # control ports to plug a pot device into.
+    def control_ports = nil
 
     def ram = @bus.ram
 
+    # What a front end plays: the TED's sound, which answers #record and
+    # #drain_samples, mixed with the SID card's where one is fitted.
+    def sound_source = @sound_mix || @sound
+
+    # The chip whose #display a front end shows.
+    def video = @ted
+
+    # The TED's clock and raster, and the part of its picture xplus4 shows:
+    # all 384 pixels of a line, and 288 lines from line 276 on PAL or 242
+    # from line 248 on NTSC, running on past the frame's last line to its
+    # first, as the top border is the end of the frame. The TED draws 8
+    # pixels a cycle, so each shows one window pixel wide, as on the C64.
+    def timing
+      profile = @ted.profile
+      ntsc = profile == Chips::TED::NTSC
+      Timing.new(clock_hz: profile.clock_hz, cycles_per_line: Chips::TED::Beam::CYCLES_PER_LINE,
+                 lines_per_frame: ntsc ? 262 : 312, crop: ntsc ? [0, 248, 384, 242] : [0, 276, 384, 288],
+                 pixel_width: 1)
+    end
+
     # Reads and writes memory as the CPU sees it, through the bus.
     def peek(addr) = @bus.peek(addr)
 
@@ -48,46 +100,66 @@ module Badline
     # +model+ names one of Model::ALL, or c116 for the C16, and +ram+ the
     # RAM in K, one of Model::RAM_SIZES, when not the model's own. +tcbm+
     # plugs in a 1551's TCBM interface, the TIAs at $FEC0-$FEFF, with no
-    # drive answering on the other side.
-    def initialize(model: "plus4", ram: nil, tcbm: false, debug: false)
+    # drive answering on the other side. +true_drive_model+ names the drive
+    # plug_true_drive plugs in, "1541" or "1551". +sid_card+ fits a SID
+    # card with a SID of that model, :mos6581 or :mos8580, at
+    # +sid_card_address+, $FD40 or $FE80. +ram_expansion+
+    # fits a RAMExpansion of that kind, :hannes256, :hannes1m or
+    # :csory256, over 64K of the machine's own.
+    def initialize(model: "plus4", ram: nil, tcbm: false, true_drive_model: "1551", sid_card: nil,
+                   sid_card_address: SIDCard::ADDRESSES.first, ram_expansion: nil, debug: false)
       @model = Model.named(model)
-      @ram_kb = ram || @model.ram_kb
-      raise ArgumentError, "no Plus/4 RAM size of #{@ram_kb}K" unless Model::RAM_SIZES.include?(@ram_kb)
+      @ram_kb = fitted_ram(ram, ram_expansion)
 
       @ted = Chips::TED.new(@model.ted)
       @keyboard = Input::Keyboard.new(matrix: KeyboardPort::MATRIX)
-      @keyboard_port = KeyboardPort.new(@keyboard)
+      @joystick1 = Input::Joystick.new
+      @joystick2 = Input::Joystick.new
+      @keyboard_port = KeyboardPort.new(@keyboard, @joystick1, @joystick2)
       @ted.keyboard_port = @keyboard_port
       @iec_bus = Drives::SerialBus.new
       @datasette = Drives::Datasette.new(level: true)
       @port = CPUPort.new(serial_bus: @iec_bus, datasette: @datasette)
       plus4_parts = @model.plus4_parts
-      @acia = plus4_parts ? ACIA.new : nil
+      @cycles = 0
+      @init_threshold = INIT_THRESHOLD
+      @acia_irq = false
+      @acia_due = ACIA::NEVER
+      @due = INIT_THRESHOLD
+      @sid_card = sid_card ? SIDCard.new(self, sid_card, sid_card_address) : nil
+      @acia = plus4_parts ? ACIA.new(self, @model.ted.clock_hz) : nil
       @user_port = plus4_parts ? UserPort.new(@datasette) : nil
-      io = Bus::IOPage.new(keyboard_port: @keyboard_port, acia: @acia, user_port: @user_port)
-      @bus = Bus.new(ted: @ted, port: @port, io:, model: @model, ram_kb: @ram_kb)
+      io = Bus::IOPage.new(keyboard_port: @keyboard_port, acia: @acia, user_port: @user_port,
+                           cassette_sense: plus4_parts ? nil : CassetteSense.new(@datasette),
+                           sid_card: sid_card_at(0xfd40))
+      @bus = Bus.new(ted: @ted, port: @port, io:, model: @model, ram_kb: @ram_kb, ram_expansion:)
+      @ted.connect(@bus)
+      @bus.plug_sid_card(sid_card_at(0xfe80))
       @tias = tcbm ? [Chips::TIA.new, Chips::TIA.new] : []
       @bus.plug_tcbm(drive8: @tias[0], drive9: @tias[1]) if tcbm
       @cpu = CPU.new(@bus, debug:)
-      @cycles = 0
+      @sound = Chips::TED::Sound.new(self, @model.ted.clock_hz)
+      @ted.sound = @sound
+      @sound_mix = @sid_card ? SoundMix.new(@sound, @sid_card) : nil
       @init_handlers = []
       @pending_keys = nil
       @dos = nil
       @serial_trap = nil
       @save_trap = nil
       @capture_output = nil
+      init_drives(true_drive_model)
     end
 
     # One TED cycle: the TED moves on and decides the CPU's clock, then the
     # CPU runs its cycles in it, none while the TED holds the bus.
     def cycle!
-      handle_init if @cycles == INIT_THRESHOLD
+      handle_due if @cycles >= @due
       feed_keyboard if @pending_keys
 
       ted = @ted
       ted.cycle!
       @datasette.cycle!
-      @cpu.irq = ted.irq?
+      @cpu.irq = ted.irq? || @acia_irq
       slots = ted.cpu_slots
       if slots.zero?
         @cpu.stall!
@@ -95,35 +167,52 @@ module Badline
         clock_cpu(ted)
         clock_cpu(ted) if slots == 2
       end
+      @drive1541&.host_cycle!
+      @drive1581&.host_cycle!
+      @drive1551&.host_cycle!
 
       @cycles += 1
     end
 
     # The RESET line: the CPU, the port, the 6529s, the ACIA, the bank
-    # latch and ROM selection. The TED has no reset pin.
+    # latch and ROM selection, a RAM expansion's register, the SID card,
+    # and through the serial bus's RESET line, the drives. The TED has no
+    # reset pin.
     def reset!
       @port.reset!
       @keyboard_port.reset!
       @user_port&.reset!
       @dos&.reset!
+      @drive1541&.reset!
+      @drive1581&.reset!
+      @drive1551&.reset!
       @acia&.reset!
+      @sid_card&.reset!
       @tias.each(&:reset!)
       @bus.reset!
       @cpu.reset!
     end
 
-    # Switches the machine off and on: RAM and the TED start from their
-    # power-on state, and the RES line resets everything else.
+    # Switches the machine off and on: RAM, the TED and its sound start
+    # from their power-on state, and the RES line resets everything else.
     def power_cycle!
       @bus.power_on!
       @ted.power_on!
+      @sound.power_on!
       reset!
     end
 
+    # The ACIA's IRQ line, and the cycle it next has something to do at.
+    def acia_changed(irq, due)
+      @acia_irq = irq
+      @acia_due = due
+      schedule
+    end
+
     # Calls the block with the exit code a VICE testprog writes to $FDCF.
     def install_debug_register(&) = @bus.install_debug_register(&)
 
-    # Puts a cartridge's ROM chips in cartridge 1's slots (Bus#attach_cartridge)
+    # Puts a cartridge's ROM chips in their slots (Bus#attach_cartridge)
     # and switches the machine off and on, as a cartridge goes in with the
     # power off. The KERNAL starts it at reset when it signs itself with CBM
     # at $8007.
@@ -132,6 +221,36 @@ module Badline
       power_cycle!
     end
 
+    # Takes both cartridges out (Bus#detach_cartridges) and switches the
+    # machine off and on.
+    def detach_cartridges
+      @bus.detach_cartridges
+      power_cycle!
+    end
+
+    # The cartridge slots with a ROM in them (Bus#cartridge_slots).
+    def cartridge_slots = @bus.cartridge_slots
+
+    # The model and its RAM as the pause menu names them, such as
+    # "PLUS/4 PAL, 64K RAM".
+    def model_label
+      name = @model.plus4_parts ? "PLUS/4" : "C16"
+      standard = @model.ted == Chips::TED::NTSC ? "NTSC" : "PAL"
+      "#{name} #{standard}, #{@ram_kb}K RAM"
+    end
+
+    # The RAMExpansion fitted, or nil.
+    def ram_expansion = @bus.ram_expansion
+
+    # The RAM expansion as the pause menu names it, such as "HANNES, 256
+    # KB", or nil without one.
+    def ram_expansion_label
+      expansion = @bus.ram_expansion
+      return if expansion.nil?
+
+      "#{RAMExpansion::NAMES.fetch(expansion.kind)}, #{expansion.size_kb} KB"
+    end
+
     # Stores a PRG's bytes from its load address on, into RAM, and returns
     # that address.
     def load_prg(data)
@@ -144,6 +263,22 @@ module Badline
 
     private
 
+    # The SID card if it is at +address+, or nil.
+    def sid_card_at(address)
+      card = @sid_card
+      card if card && card.address == address
+    end
+
+    # The RAM in K: +ram+, or the model's own, or 64K under a RAM
+    # expansion, which needs that much.
+    def fitted_ram(ram, ram_expansion)
+      ram_kb = ram || (ram_expansion ? 64 : @model.ram_kb)
+      raise ArgumentError, "no Plus/4 RAM size of #{ram_kb}K" unless Model::RAM_SIZES.include?(ram_kb)
+      raise ArgumentError, "a RAM expansion needs 64K, not #{ram_kb}K" if ram_expansion && ram_kb != 64
+
+      ram_kb
+    end
+
     # The 264 KERNAL's keyboard buffer.
     def keyboard_buffer = Machine::KeyboardBuffer::PLUS4_LAYOUT
 
@@ -152,9 +287,32 @@ module Badline
 
     def trap_bus = @bus
 
-    # Device 8, which the serial traps answer for, with no true drive on
-    # the bus to take it.
-    def serial_trap_device = KernalTrap::Routine::DEVICE
+    # A drive that powers on with the machine takes longer to boot than
+    # the KERNAL, and doesn't answer the bus until it has, so the
+    # machine's on_init handlers wait for it too.
+    def drive1541_attached
+      @init_threshold = [@init_threshold, DRIVE_BOOT_CYCLES].max if @cycles < @init_threshold
+    end
+
+    def drive1581_attached
+      @init_threshold = [@init_threshold, Drives::Model1581::BOOT_CYCLES].max if @cycles < @init_threshold
+    end
+
+    # What falls due at the start of a cycle: the on_init handlers at the
+    # init threshold, and the ACIA's next character.
+    def handle_due
+      handle_init if @cycles == @init_threshold
+      acia = @acia
+      acia.run!(@cycles) if acia && @cycles >= @acia_due
+      schedule
+    end
+
+    # The next cycle anything falls due at. A drive that raises the init
+    # threshold leaves it early, and handle_due looks again then.
+    def schedule
+      init = @cycles < @init_threshold ? @init_threshold : ACIA::NEVER
+      @due = [@acia_due, init].min
+    end
 
     # BA stops the CPU at a read, and a write goes ahead.
     def clock_cpu(ted)

data/lib/badline/roms/README

@@ -79,6 +79,15 @@ Downloaded from
 https://www.zimmers.net/anonftp/pub/cbm/firmware/drives/new/1581/1581-rom.318045-02.bin
 SHA-1 01228eae6f066bd9b7b2b6a7fa3f667e41dad393.
 
+dos1551.rom
+-----------
+The 1551 disk drive's DOS 2.6, 318008-01, 16 KB for $C000-$FFFF.
+Drives::Model1551 loads it.
+
+Downloaded from
+https://www.zimmers.net/anonftp/pub/cbm/firmware/drives/new/1551/1551.318008-01.bin
+SHA-1 fae3c788ad9a6cc2dbdfbcf6c0264b2ca921d55e.
+
 Commodore VIC-20 ROMs
 =====================
 

data/lib/badline/snapshot/container.rb

@@ -34,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

@@ -7,7 +7,7 @@ module Badline
       # 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" }.freeze
+        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
 
@@ -31,11 +31,12 @@ module Badline
           `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`. 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.
+          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)

data/lib/badline/snapshot/field_doc.rb

@@ -2,6 +2,7 @@
 
 require "badline"
 require "badline/c128"
+require "badline/plus4"
 
 module Badline
   module Snapshot
@@ -27,29 +28,47 @@ module Badline
       # each module the keys its records hold, with their tags, and the fields the load read.
       Load = Data.define(:family, :written, :fields)
 
-      # The machines the doc is made from: each family at power-on, and the
-      # C64 with each kind of expansion, cartridge and media.
+      # 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 drives, the 1541 and the 1551.
       def self.machines
         {
-          "c64" => [C64.new, C64.new(ram_expansion: :plus256k), C64.new(reu: 512), with_cartridge, with_trap_dos,
-                    with_tape, with_drive(:d64), with_drive(:d81)],
+          "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)]
+          "c128" => [C128.new(mode: :c128), with_drive(:d71)],
+          "plus4" => [Plus4.new, Plus4.new(model: "c16"), Plus4.new(tcbm: true), Plus4.new(sid_card: :mos6581),
+                      Plus4.new(sid_card: :mos8580, sid_card_address: 0xfe80),
+                      Plus4.new(ram_expansion: :csory256),
+                      plus4_with_cartridge, plus4_with_tape, plus4_with_drive, plus4_with_drive("1551")]
         }
       end
 
       def self.blank(length) = Array.new(length, 0)
 
-      def self.with_cartridge
+      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: 32, subtype: 0, exrom: 1, game: 0, name: "DOC", chips:)
+        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
@@ -78,6 +97,28 @@ module Badline
         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(model = "1541")
+        Plus4.new(true_drive_model: model).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

data/lib/badline/snapshot/image.rb

@@ -34,7 +34,7 @@ module Badline
     # of a machine in memory (.of).
     class Image
       MACHINE = "BL-MACHINE"
-      FAMILIES = { "c64" => "C64", "vic20" => "VIC-20", "c128" => "C128" }.freeze
+      FAMILIES = { "c64" => "C64", "vic20" => "VIC-20", "c128" => "C128", "plus4" => "Plus/4" }.freeze
 
       attr_reader :container
 
@@ -54,8 +54,11 @@ module Badline
       end
 
       # The snapshot with VICE's modules ahead of the BL-* ones for a C64,
-      # so x64sc opens it too.
+      # 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
@@ -67,6 +70,7 @@ module Badline
         case computer.family
         when :vic20 then Container::VIC20
         when :c128 then Container::C128
+        when :plus4 then Container::PLUS4
         else Container::MACHINE
         end
       end
@@ -77,6 +81,7 @@ module Badline
         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
@@ -92,7 +97,7 @@ module Badline
 
       # A new machine, built as the snapshot's was and restored from it. A
       # badline snapshot restores from its BL-* modules alone, and a VICE
-      # one through the modules badline reads. xvic's and x128's own
+      # 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).
@@ -100,6 +105,7 @@ module Badline
         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?
 
         modules = Keyed::Modules.new(sections, detached:)
@@ -114,6 +120,9 @@ module Badline
       # Whether the machine is a C128, as the container names it.
       def c128? = @container.machine == Container::C128
 
+      # 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.

data/lib/badline/snapshot/plus4_setup.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    # How a 264 series machine was built: its model's name, one of
+    # Plus4::Model::ALL, which also says whether the Plus/4's function ROMs
+    # are fitted, its RAM in K, whether a 1551's TCBM interface is plugged
+    # in, the SID card's SID model, or nil without one, and its address,
+    # and the RAM expansion's kind, or nil without one, the arguments
+    # Plus4.new takes.
+    Plus4Setup = Data.define(:model, :ram_kb, :tcbm, :sid_card, :sid_card_address, :ram_expansion)
+
+    class Plus4Setup
+      MODELS = Plus4::Model::ALL.map(&:name).freeze
+
+      SID_CARDS = %w[none mos6581 mos8580].freeze
+
+      RAM_EXPANSIONS = ["none", *Plus4::RAMExpansion::KINDS.keys.map(&:to_s)].freeze
+
+      # The setup of `machine`.
+      def self.of(machine)
+        card = machine.sid_card
+        new(model: machine.model.name, ram_kb: machine.ram_kb, tcbm: !machine.tias.empty?, sid_card: card&.model,
+            sid_card_address: card ? card.address : Plus4::SIDCard::ADDRESSES.first,
+            ram_expansion: machine.ram_expansion&.kind)
+      end
+
+      # The model by name, the RAM, the TCBM interface, the SID card's
+      # model and address and the RAM expansion's kind, "none" without
+      # them, in a keyed snapshot module.
+      def write_fields(out)
+        out.text("model", model).int("ram_kb", ram_kb).bool("tcbm", tcbm).text("sid_card", (sid_card || :none).to_s)
+        out.int("sid_card_address", sid_card_address).text("ram_expansion", (ram_expansion || :none).to_s)
+      end
+
+      def self.read_fields(input)
+        model = input.choice("model", MODELS, "plus4")
+        ram_kb = input.int("ram_kb", Plus4::Model.named(model).ram_kb)
+        unless Plus4::Model::RAM_SIZES.include?(ram_kb)
+          raise FormatError, "the snapshot is of a Plus/4 with #{ram_kb}K of RAM, which badline doesn't build"
+        end
+
+        sid_card = named(input.choice("sid_card", SID_CARDS, "none"))
+        ram_expansion = named(input.choice("ram_expansion", RAM_EXPANSIONS, "none"))
+        new(model:, ram_kb:, tcbm: input.bool("tcbm", false), sid_card:, sid_card_address: sid_card_address(input),
+            ram_expansion:)
+      end
+
+      # A choice's name as a Symbol, or nil for "none".
+      def self.named(name) = name == "none" ? nil : name.to_sym
+
+      def self.sid_card_address(input)
+        address = input.int("sid_card_address", Plus4::SIDCard::ADDRESSES.first)
+        return address if Plus4::SIDCard::ADDRESSES.include?(address)
+
+        raise FormatError, format("the snapshot is of a Plus/4 with a SID card at $%<address>04X, " \
+                                  "which badline doesn't build", address:)
+      end
+      private_class_method :named, :sid_card_address
+
+      # A machine built this way, at power-on.
+      def build = Plus4.new(model:, ram: ram_kb, tcbm:, sid_card:, sid_card_address:, ram_expansion:)
+
+      def to_s
+        parts = ["#{ram_kb}K"]
+        parts << "a TCBM interface" if tcbm
+        parts << sid_card_part if sid_card
+        parts << "a #{ram_expansion} RAM expansion" if ram_expansion
+        "#{model} with #{parts.join(' and ')}"
+      end
+
+      private
+
+      def sid_card_part
+        format("%<article>s %<model>s SID card at $%<address>04X", article: sid_card == :mos8580 ? "an" : "a",
+                                                                   model: sid_card.to_s.delete_prefix("mos"),
+                                                                   address: sid_card_address)
+      end
+    end
+  end
+end

data/lib/badline/snapshot.rb

@@ -35,8 +35,9 @@ module Badline
     # The machine's snapshot file. Saving first runs the machine on to the
     # end of the instruction its CPU is in, and of an REU transfer under
     # way (Machine::Settling), so a save advances it by a few cycles, and a
-    # second save straight after runs none. A VIC-20's or a C128's snapshot
-    # is in a container named as xvic or x128 names its machine.
+    # second save straight after runs none. A VIC-20's, a C128's or a
+    # Plus/4's snapshot is in a container named as xvic, x128 or xplus4
+    # names its machine.
     def dump(computer) = Image.of(computer).to_s
 
     def read(path) = Image.new(Container.parse(File.binread(path)), name: File.basename(path))
@@ -50,8 +51,8 @@ module Badline
     # snapshot that fails leaves the machine as it was.
     def restore(computer, path, &) = read(path).restore(computer, &)
 
-    # A machine's snapshots, as .vsf files and in memory. C64, Vic20 and
-    # C128 each include it.
+    # A machine's snapshots, as .vsf files and in memory. C64, Vic20, C128
+    # and Plus4 each include it.
     module Files
       def save_snapshot(path) = Snapshot.save(self, path)
 
@@ -90,4 +91,8 @@ module Badline
   class C128
     include Snapshot::Files
   end
+
+  class Plus4
+    include Snapshot::Files
+  end
 end