badline 0.14.0 → 0.15.0

data/lib/badline/plus4/keyboard_port.rb

@@ -2,12 +2,19 @@
 
 module Badline
   class Plus4
-    # The keyboard: the 6529 at $FD30-$FD3F, whose eight outputs drive the
-    # key matrix's lines, and the TED's K0-K7 inputs, which $FF08 latches
-    # (Chips::TED#keyboard_port=). The KERNAL's scan ($DB11) writes each
-    # line's mask to $FD30 and $FF08 and reads the keys back from $FF08,
-    # and its key table at $E026 puts each key at line times 8 plus input
-    # bit.
+    # The keyboard and the joysticks: the 6529 at $FD30-$FD3F, whose eight
+    # outputs drive the key matrix's lines, and the TED's K0-K7 inputs,
+    # which $FF08 latches (Chips::TED#keyboard_port=). The KERNAL's scan
+    # ($DB11) writes each line's mask to $FD30 and $FF08 and reads the keys
+    # back from $FF08, and its key table at $E026 puts each key at line
+    # times 8 plus input bit.
+    #
+    # The joysticks share K0-K7. The byte written to $FF08 selects them,
+    # bit 2 low joystick 1 and bit 1 low joystick 2, as BASIC's JOY does
+    # ($FA and $FD). A selected joystick pulls up, down, left and right
+    # onto K0-K3 and its fire button onto K6 (joystick 1) or K7
+    # (joystick 2), and those lines settle against the matrix with the
+    # keys'.
     #
     # The 6529 is a quasi-bidirectional latch: a read returns what was
     # written to it.
@@ -28,8 +35,10 @@ module Badline
 
       attr_reader :keyboard, :output
 
-      def initialize(keyboard)
+      def initialize(keyboard, joystick1, joystick2)
         @keyboard = keyboard
+        @joystick1 = joystick1
+        @joystick2 = joystick2
         @output = 0xff
       end
 
@@ -43,9 +52,25 @@ module Badline
         @output = value
       end
 
-      # The K0-K7 inputs the TED latches on a write of +_value+ to $FF08:
-      # high but where a held key joins a line the 6529 pulls low.
-      def latch(_value) = @keyboard.scan(@output, 0xff).last
+      # The K0-K7 inputs the TED latches on a write of +value+ to $FF08:
+      # high but where a held key joins a line the 6529 pulls low, or a
+      # joystick +value+ selects holds a switch closed.
+      def latch(value) = @keyboard.scan(@output, joystick_lines(value)).last
+
+      private
+
+      def joystick_lines(value)
+        lines = 0xff
+        lines &= joystick_inputs(@joystick1.port_bits, 0x40) if value.nobits?(0x04)
+        lines &= joystick_inputs(@joystick2.port_bits, 0x80) if value.nobits?(0x02)
+        lines
+      end
+
+      # A joystick's switches, Input::Joystick's bits 0-4, on K0-K7: the
+      # directions on K0-K3 and the fire button on +fire+.
+      def joystick_inputs(bits, fire)
+        bits.anybits?(0x10) ? bits | 0xf0 : (bits | 0xf0) & ~fire & 0xff
+      end
     end
   end
 end

data/lib/badline/plus4/keyed_modules.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Badline
+  class Plus4
+    # The whole machine as keyed snapshot modules (Snapshot::Keyed): BL-MACHINE
+    # with the setup, the cartridges' ROMs by slot, the CPU with its port,
+    # the TED, its sound, the keyboard's 6529, the user port's 6529 and the
+    # ACIA where the model has them, the TCBM interface's TIAs where one is
+    # plugged in, the RAM with the ROM bank latch and the ROM/RAM switch
+    # under bus.*, the datasette, device 8 through the traps and the true
+    # drives.
+    #
+    # A load maps the banks before the chips load, and works out what each
+    # unit derives from its fields once every unit is loaded.
+    module KeyedModules
+      def save_modules
+        bus = @bus
+        sections = [Snapshot::Keyed.section("BL-MACHINE") { |out| save_machine_fields(out) }]
+        sections << Snapshot::Keyed.section("BL-CART") { |out| bus.save_slot_fields(out) } if bus.cartridge?
+        save_chip_modules(sections)
+        sections << Snapshot::Keyed.section("BL-RAM") do |out|
+          bus.ram.save_fields(out, "ram")
+          bus.save_fields(out, "bus.")
+        end
+        sections << Snapshot::Keyed.section("BL-TAPE") { |out| @datasette.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-TRAPDOS") { |out| save_trap_dos_fields(out) } if mounted?
+        save_drive_modules(sections)
+      end
+
+      # Raises Snapshot::FormatError for the modules of a machine built
+      # another way.
+      def load_modules(modules)
+        machine = modules.machine
+        check_snapshot_setup(Snapshot::Plus4Setup.read_fields(machine))
+        load_machine_fields(machine)
+        bus = @bus
+        memory = modules.required("BL-RAM")
+        bus.ram.load_fields(memory, "ram")
+        bus.load_fields(memory, "bus.")
+        bus.load_slot_fields(modules.optional("BL-CART") || Snapshot::Keyed::Reader.new("BL-CART"))
+        bus.restored!
+        load_chip_modules(modules)
+        @datasette.load_fields(modules.required("BL-TAPE"))
+        trap_dos = modules.optional("BL-TRAPDOS")
+        trap_dos ? load_trap_dos_fields(trap_dos, detached: modules.detached?) : unmount
+        load_drive_modules(modules)
+        modules_restored!
+        self
+      end
+
+      private
+
+      def save_chip_modules(sections)
+        sections << Snapshot::Keyed.section("BL-CPU") do |out|
+          @cpu.save_fields(out)
+          @port.save_fields(out, "port.")
+        end
+        sections << Snapshot::Keyed.section("BL-TED") { |out| @ted.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-TEDSOUND") { |out| @sound.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-KEYPORT") { |out| @keyboard_port.save_fields(out) }
+        user_port = @user_port
+        sections << Snapshot::Keyed.section("BL-USERPORT") { |out| user_port.save_fields(out) } if user_port
+        acia = @acia
+        sections << Snapshot::Keyed.section("BL-ACIA") { |out| acia.save_fields(out) } if acia
+        @tias.each_with_index do |tia, index|
+          sections << Snapshot::Keyed.section("BL-TIA#{index + 1}") { |out| tia.save_fields(out) }
+        end
+      end
+
+      def load_chip_modules(modules)
+        cpu = modules.required("BL-CPU")
+        @port.load_fields(cpu, "port.")
+        @ted.load_fields(modules.required("BL-TED"))
+        @sound.load_fields(modules.required("BL-TEDSOUND"))
+        @keyboard_port.load_fields(modules.required("BL-KEYPORT"))
+        @user_port&.load_fields(modules.required("BL-USERPORT"))
+        @acia&.load_fields(modules.required("BL-ACIA"))
+        @tias.each_with_index { |tia, index| tia.load_fields(modules.required("BL-TIA#{index + 1}")) }
+        @cpu.load_fields(cpu)
+      end
+
+      def modules_restored!
+        @cpu.restored!
+        @ted.restored!
+        @sound.restored!(@ted)
+        @port.restored!
+      end
+
+      def check_snapshot_setup(setup)
+        ours = Snapshot::Plus4Setup.of(self)
+        return if setup == ours
+
+        raise Snapshot::FormatError, "the snapshot is of a #{setup}, not a #{ours}"
+      end
+    end
+
+    include KeyedModules
+  end
+end

data/lib/badline/plus4/keyed_parts.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Badline
+  class Plus4
+    class CPUPort
+      # The port's registers in a keyed snapshot module (Snapshot::Keyed),
+      # under `prefix`. The serial bus's lines and the datasette's write
+      # line are driven again from them once everything is loaded
+      # (#restored!), without recording an edge on the tape.
+      module KeyedState
+        def save_fields(out, prefix)
+          out.int("#{prefix}ddr", @ddr).int("#{prefix}data", @data)
+        end
+
+        def load_fields(input, prefix)
+          @ddr = input.byte("#{prefix}ddr", @ddr)
+          @data = input.byte("#{prefix}data", @data)
+        end
+
+        def restored!
+          @serial_bus.host_lines = serial_lines
+          @datasette.write_level = levels.anybits?(CLK_OUT)
+        end
+      end
+
+      include KeyedState
+    end
+
+    class KeyboardPort
+      # The 6529's latch in a keyed snapshot module (BL-KEYPORT).
+      module KeyedState
+        def save_fields(out) = out.int("output", @output)
+
+        def load_fields(input)
+          @output = input.byte("output", @output)
+        end
+      end
+
+      include KeyedState
+    end
+
+    class UserPort
+      # The 6529's latch in a keyed snapshot module (BL-USERPORT).
+      module KeyedState
+        def save_fields(out) = out.int("output", @output)
+
+        def load_fields(input)
+          @output = input.byte("output", @output)
+        end
+      end
+
+      include KeyedState
+    end
+
+    class ACIA
+      # The command and control registers in a keyed snapshot module
+      # (BL-ACIA).
+      module KeyedState
+        def save_fields(out) = out.int("command", @command).int("control", @control)
+
+        def load_fields(input)
+          @command = input.byte("command", @command)
+          @control = input.byte("control", @control)
+        end
+      end
+
+      include KeyedState
+    end
+
+    class Bus
+      # The ROM bank latch, whether ROM is selected and the last byte on the
+      # bus, under `prefix`, and the cartridges' ROMs by slot (#save_slot_fields),
+      # in keyed snapshot modules (Snapshot::Keyed). The TED learns which
+      # memory is selected, and the pages are mapped again, once they are
+      # loaded (#restored!). The BASIC, KERNAL and function ROMs come with
+      # the model.
+      module KeyedState
+        # The cartridge slots, as xplus4 names them: cartridge 1 or 2, the
+        # low ($8000) or the high ($C000) half.
+        SLOTS = %w[c1lo c2lo c1hi c2hi].freeze
+
+        def save_fields(out, prefix)
+          out.int("#{prefix}low_bank", @low_bank).int("#{prefix}high_bank", @high_bank)
+          out.bool("#{prefix}rom_selected", @rom_selected).int("#{prefix}data", @data)
+        end
+
+        def load_fields(input, prefix)
+          @low_bank = input.masked("#{prefix}low_bank", @low_bank, 0x03)
+          @high_bank = input.masked("#{prefix}high_bank", @high_bank, 0x03)
+          @rom_selected = input.bool("#{prefix}rom_selected", @rom_selected)
+          @data = input.byte("#{prefix}data", @data)
+        end
+
+        # Whether a cartridge's ROM is in any slot.
+        def cartridge?
+          index = 0
+          while index < SLOTS.length
+            return true unless slot_rom(index).nil?
+
+            index += 1
+          end
+          false
+        end
+
+        # Each slot's ROM, 16K, under its name. An empty slot writes
+        # nothing.
+        def save_slot_fields(out)
+          SLOTS.each_with_index do |name, index|
+            rom = slot_rom(index)
+            rom&.save_fields(out, name)
+          end
+          out
+        end
+
+        # A slot the module holds nothing for is left empty.
+        def load_slot_fields(input)
+          SLOTS.each_with_index do |name, index|
+            bytes = input.bytes(name, "".b).bytes
+            if index < 2
+              @low_roms[2 + index] = slot(bytes, 0x8000)
+            else
+              @high_roms[index] = slot(bytes, 0xc000)
+            end
+          end
+        end
+
+        def restored!
+          @ted.rom_selected = @rom_selected
+          map_reads
+        end
+
+        private
+
+        def slot_rom(index) = index < 2 ? @low_roms[2 + index] : @high_roms[index]
+
+        # A slot's ROM from its bytes at `start`, or none.
+        def slot(bytes, start) = bytes.empty? ? nil : ROM.new(bytes, length: bytes.length, start:)
+      end
+
+      include KeyedState
+    end
+  end
+end

data/lib/badline/plus4/keyed_state.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Badline
+  class Plus4
+    # The machine's own fields in a keyed snapshot module (Snapshot::Keyed,
+    # BL-MACHINE): the family, its setup by name (Snapshot::Plus4Setup), the
+    # cycle count, and the host's typing still to feed and on_init handlers
+    # still to run under host.*. The badline version that wrote it is
+    # written for reports and never read.
+    module KeyedState
+      # How many more on_init handlers the machine a snapshot was taken of had
+      # yet to run than this one has. Nil until the machine is restored.
+      attr_reader :init_handlers_lost
+
+      # Whether a snapshot saves now (Machine::Settling): the CPU between
+      # instructions or jammed.
+      def settled_for_snapshot? = @cpu.boundary? || @cpu.jammed?
+
+      # The sound's voices, run up to this cycle.
+      def settle_chips_for_snapshot = @sound.catch_up!
+
+      def save_machine_fields(out)
+        out.text("family", "plus4").text("written_by", VERSION)
+        Snapshot::Plus4Setup.of(self).write_fields(out)
+        out.int("cycles", @cycles)
+        pending = @pending_keys
+        out.ints("host.pending_keys", pending) if pending
+        out.int("host.init_pending", booting? ? @init_handlers.length : 0)
+      end
+
+      def load_machine_fields(input)
+        @cycles = input.int("cycles", @cycles)
+        pending = input.ints("host.pending_keys", [])
+        @pending_keys = pending.empty? ? nil : pending.dup
+        @init_handlers_lost = [input.int("host.init_pending", 0) - @init_handlers.length, 0].max
+      end
+    end
+
+    include KeyedState
+  end
+end

data/lib/badline/plus4.rb

@@ -7,8 +7,13 @@ 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/bus"
+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
@@ -17,13 +22,17 @@ module Badline
   # 6529. Only the TED pulls 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 does (C64::TrueDrives), 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.
   class Plus4
     include IntegerHelper
     include Machine::KeyboardBuffer
     include Machine::Clocking
+    include Machine::Settling
+    include C64::TrueDrives
     include C64::KernalTraps
 
     # The cycle by which the KERNAL has booted and BASIC printed READY,
@@ -31,15 +40,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
 
     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.
+    def sound_source = @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)
 
@@ -56,7 +92,9 @@ module Badline
 
       @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)
@@ -64,24 +102,31 @@ module Badline
       plus4_parts = @model.plus4_parts
       @acia = plus4_parts ? ACIA.new : nil
       @user_port = plus4_parts ? UserPort.new(@datasette) : nil
-      io = Bus::IOPage.new(keyboard_port: @keyboard_port, acia: @acia, user_port: @user_port)
+      io = Bus::IOPage.new(keyboard_port: @keyboard_port, acia: @acia, user_port: @user_port,
+                           cassette_sense: plus4_parts ? nil : CassetteSense.new(@datasette))
       @bus = Bus.new(ted: @ted, port: @port, io:, model: @model, ram_kb: @ram_kb)
+      @ted.connect(@bus)
       @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
       @init_handlers = []
       @pending_keys = nil
       @dos = nil
       @serial_trap = nil
       @save_trap = nil
       @capture_output = nil
+      @drive1541 = nil
+      @drive1581 = nil
+      @init_threshold = INIT_THRESHOLD
     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_init if @cycles == @init_threshold
       feed_keyboard if @pending_keys
 
       ted = @ted
@@ -95,35 +140,41 @@ module Badline
         clock_cpu(ted)
         clock_cpu(ted) if slots == 2
       end
+      @drive1541&.host_cycle!
+      @drive1581&.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, 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!
       @acia&.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
 
     # 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 +183,24 @@ 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
+
     # Stores a PRG's bytes from its load address on, into RAM, and returns
     # that address.
     def load_prg(data)
@@ -152,9 +221,16 @@ 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
 
     # BA stops the CPU at a read, and a write goes ahead.
     def clock_cpu(ted)

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)