badline 0.16.1 → 0.18.0

data/lib/badline/cbm2/cpu.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    # The 6509: a 6502 core with four more address lines, which pick one of
+    # the Bus's sixteen segments. Every access goes to the execution
+    # segment, but the ones at the address LDA (zp),Y and STA (zp),Y index,
+    # their data and the dummy read before it, which go to the indirection
+    # segment: the opcode and the zero-page pointer stay in the execution
+    # segment. Interrupts leave both segments alone.
+    class CPU
+      include Badline::Chips::CPU::Core
+
+      def initialize(memory, debug: false)
+        super
+        @indirect = false
+      end
+
+      def reset!
+        super
+        @indirect = false
+      end
+
+      private
+
+      def op_pointer_high_y
+        super
+        @indirect = @operation == :lda || @operation == :sta
+      end
+
+      def op_idx_dummy
+        return super unless @indirect
+
+        @memory.select_indirect!
+        super
+        @memory.select_execute!
+      end
+
+      def op_mem_read
+        return super unless @indirect
+
+        @indirect = false
+        @memory.select_indirect!
+        super
+        @memory.select_execute!
+      end
+
+      def op_mem_write
+        return super unless @indirect
+
+        @indirect = false
+        @memory.select_indirect!
+        super
+        @memory.select_execute!
+      end
+    end
+  end
+end

data/lib/badline/cbm2/crtc_video.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    # What the B series makes of its 6845's outputs. Each character the
+    # CRTC displays reads the 2K screen RAM at its memory address, MA0-MA10,
+    # and the character ROM's 16-line glyph for the screen code's low seven
+    # bits, from the set TPI1's CA picks: the first 128 glyphs while it is
+    # low, the second while it is high. Bit 7 of the screen code reverses
+    # the glyph. The ROM's row is the CRTC's raster line, RA0-RA3, so the
+    # 600's eight lines show the 8x8 glyphs in the first half of each and
+    # the 700's fourteen the 8x16 ones.
+    #
+    # The cursor is the 6845's: on the character at R14:R15, from line
+    # R10's low five bits to line R11, it reverses the dots. R10's bits 5
+    # and 6 pick its blink: 00 steady, 01 no cursor, 10 on for 8 fields and
+    # off for 8, 11 on for 16 and off for 16.
+    #
+    # The picture is a PET::Canvas framed as xcbm2 frames its screenshots:
+    # 704 dots wide, the first displayed character 32 dots in, and 266
+    # lines high with the first row 33 lines down on a 600, or 367 lines
+    # with it 8 down on a 700. Each frame paints its displayed lines from
+    # there down. A frame laid out otherwise than the last, its lines,
+    # rows or sync moved, starts on a black canvas, so nothing the old
+    # layout painted stays.
+    class CRTCVideo
+      LEFT = 32
+      WIDTH = 704
+
+      # The lines of the picture and the line its first row starts on, for
+      # a 600 and a 700.
+      FRAMES = { false => [266, 33], true => [367, 8] }.freeze
+
+      attr_reader :canvas, :frames
+
+      # Whether it paints the characters: a run that never shows the
+      # picture can leave it alone.
+      attr_accessor :render
+
+      # +characters+ is the character ROM's bytes, +screen+ the screen RAM,
+      # +tpi+ TPI1, whose CA picks the set, and +registers+ the CRTC's.
+      def initialize(characters, screen, tpi, registers, high_profile:)
+        @glyphs = characters
+        @screen = screen
+        @tpi = tpi
+        @registers = registers
+        height, @top = FRAMES.fetch(high_profile)
+        @canvas = PET::Canvas.new(WIDTH, height)
+        @frames = 0
+        @line = 0
+        @line_shown = false
+        @origin = LEFT
+        @layout = []
+        @render = true
+        frame_start
+      end
+
+      def character(address, raster, since_hsync)
+        @line_shown = true
+        y = @top + @line
+        return if y >= @canvas.height || !@render
+
+        @canvas.paint(@origin + (since_hsync << 3), y, row_bits(address, raster))
+      end
+
+      def hsync; end
+
+      def line_end
+        @line += 1 if @line_shown
+        @line_shown = false
+      end
+
+      def rows_end; end
+
+      # A frame starts painting from the first row's line again, its
+      # characters placed so the first one the line displays sits LEFT
+      # dots in.
+      def frame_start
+        regs = @registers
+        @frames += 1
+        @line = 0
+        @origin = LEFT - ((regs[0] + 1 - regs[2]) << 3)
+        layout = regs.values_at(0, 1, 2, 4, 5, 6, 9, 12, 13)
+        return if layout == @layout
+
+        @layout = layout
+        @canvas.clear!
+      end
+
+      # The picture under canvas.*, the fields counted, the line the frame
+      # paints next and the layout it was framed by, in a keyed snapshot
+      # module (BL-VIDEO).
+      def save_fields(out)
+        out.int("frames", @frames).int("line", @line).bool("line_shown", @line_shown).int("origin", @origin)
+        out.ints("layout", @layout)
+        @canvas.save_fields(out, "canvas.")
+      end
+
+      def load_fields(input)
+        @frames = input.int("frames", @frames)
+        @line = input.int("line", @line)
+        @line_shown = input.bool("line_shown", @line_shown)
+        @origin = input.int("origin", @origin)
+        @layout = input.ints("layout", @layout).dup
+        @canvas.load_fields(input, "canvas.")
+      end
+
+      private
+
+      def row_bits(address, raster)
+        code = @screen.peek(0xd000 | (address & 0x7ff))
+        glyph = (code & 0x7f) | (@tpi.ca? ? 0x80 : 0)
+        bits = @glyphs[(glyph << 4) | (raster & 0x0f)]
+        bits ^= 0xff if code >= 0x80
+        bits ^= 0xff if cursor?(address, raster)
+        bits
+      end
+
+      def cursor?(address, raster)
+        regs = @registers
+        return false unless address == ((regs[14] << 8) | regs[15])
+        return false if raster < (regs[10] & 0x1f) || raster > regs[11]
+
+        case regs[10] & 0x60
+        when 0x00 then true
+        when 0x20 then false
+        when 0x40 then @frames.nobits?(0x08)
+        else @frames.nobits?(0x10)
+        end
+      end
+    end
+  end
+end

data/lib/badline/cbm2/ieee_drive.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "badline/machine/ieee_drives"
+
+module Badline
+  class CBM2
+    # The CBM-II's true drive, a 2031, 8050 or 8250 on its IEEE-488 bus
+    # (IEEEPorts), as Machine::IEEEDrives has it, at the machine's clock:
+    # 2 MHz on the B series, the VIC-II's on the P500. Both include it.
+    module IEEEDrive
+      include Machine::IEEEDrives
+
+      private
+
+      def ieee_host_clock_hz = timing.clock_hz
+    end
+  end
+end

data/lib/badline/cbm2/ieee_layout.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    # Where the B series KERNALs, 901244-04a and -03b, keep the eight
+    # IEEE-488 primitives, their file variables in segment 15, and the
+    # steps they take on the bus's lines (KernalTrap::IEEELayout). TALK and
+    # LISTEN take the device in A.
+    #
+    # The KERNAL drives the bus from TPI1's port A at $DE00 (PA3 ATN, PA4
+    # DAV, PA5 EOI, PA6 NDAC, PA7 NRFD, PA0-PA2 the transceivers'
+    # directions) and the CIA's port A at $DC00, the data lines inverted.
+    # TALK and LISTEN set both ports' directions for sending and pull ATN
+    # low, TKSA and ACPTR turn NRFD, NDAC and the data lines round for
+    # listening, and each handshake times out on CIA timer B, which the
+    # ROM starts with $FF to $DC07 and $11 to $DC0F and acknowledges by
+    # reading $DC0D. ACPTR leaves port A as TKSA does, without touching
+    # the directions. 901244-03b differs from -04a in setting PA0 where -04a
+    # clears it, at the end of UNTALK, UNLISTEN and ACPTR.
+    module IEEELayout
+      LineStep = KernalTrap::IEEELineStep
+
+      # A write of +value+ to +address+.
+      def self.write(address, value) = LineStep.new(address:, keep: 0, set: value)
+
+      # +address+'s bits in +keep+, ORed with +set+.
+      def self.update(address, keep, set) = LineStep.new(address:, keep:, set:)
+
+      TIMER = [write(0xdc07, 0xff), write(0xdc0f, 0x11),
+               LineStep.new(address: 0xdc0d, keep: KernalTrap::IEEE_LINE_READ, set: 0)].freeze
+      ATTENTION = [write(0xde03, 0x3f), write(0xdc00, 0xff), write(0xdc02, 0xff), write(0xde00, 0xfa),
+                   update(0xde00, 0xf7, 0)].freeze
+      BYTE_SENT = [update(0xde00, 0xff, 0x12), write(0xdc00, 0xff)].freeze
+      RELEASE_ATTENTION = [update(0xde00, 0xff, 0x08)].freeze
+      LISTEN_TO_TALKER = [update(0xde00, 0x39, 0), write(0xde03, 0xc7), write(0xdc02, 0x00)].freeze
+
+      # The end of UNTALK and UNLISTEN, which leaves PA $F8, or $F9 on
+      # 901244-03b, before letting ATN go, and the end of ACPTR, which
+      # leaves PA0 clear, or set on 901244-03b.
+      def self.lines(release)
+        KernalTrap::IEEELines.new(
+          timer: TIMER, attention: ATTENTION, byte_sent: BYTE_SENT, release_attention: RELEASE_ATTENTION,
+          listen_to_talker: LISTEN_TO_TALKER, byte_received: [update(0xde00, 0x39, release & 0x01)].freeze,
+          release: (ATTENTION + BYTE_SENT + [write(0xde00, release)] + LISTEN_TO_TALKER.drop(1) +
+                    RELEASE_ATTENTION).freeze
+        )
+      end
+
+      # The file variables in segment 15's zero page: the file name's
+      # pointer at $90, SAVE's start at $99 and its end at $96, ST at $9C,
+      # FNLEN at $9D, FA at $9F, SA at $A0 and VERIFY at $035F.
+      ZERO_PAGE = KernalTrap::ZeroPage.new(
+        status: 0x9c, verify: 0x035f, start_address: 0x99, end_address: 0x96, filename_length: 0x9d,
+        secondary_address: 0xa0, device: 0x9f, filename_address: 0x90, save_start: 0x99, load_address: 0x99
+      )
+
+      def self.layout(release)
+        KernalTrap::IEEELayout.new(
+          talk: 0xf230, listen: 0xf234, second: 0xf274, tksa: 0xf280, ciout: 0xf297, untalk: 0xf2ab,
+          unlisten: 0xf2af, acptr: 0xf30a, overwrites_device: false, device_in_a: true, zero_page: ZERO_PAGE,
+          lines: lines(release)
+        )
+      end
+
+      # By the KERNAL's name in Model::KERNALS.
+      LAYOUTS = { "04a" => layout(0xf8), "03b" => layout(0xf9) }.freeze
+    end
+  end
+end

data/lib/badline/cbm2/ieee_ports.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    # The CBM-II's side of the IEEE-488 bus (Drives::IEEEBus): the data
+    # lines DIO1-8 on the CIA's port A at $DC00, and the handshake on
+    # TPI1's port A at $DE00:
+    #
+    #   PA3 ATN   PA4 DAV   PA5 EOI   PA6 NDAC   PA7 NRFD
+    #
+    # PA0-PA2 set the transceivers' directions, which follow the ports'
+    # direction registers as the KERNAL sets them. Each line goes through
+    # its transceiver as it is: an output bit at 0 pulls its line low, and
+    # an input bit reads its line, 0 while it is low. It is TPI1's
+    # peripheral, and Data the CIA's.
+    #
+    # The machine pushes the lines it pulls into the bus for the drives on
+    # it once a cycle while a drive is on the bus (#cycle_lines), and only
+    # when they moved.
+    class IEEEPorts
+      ATN = 0x08
+      DAV = 0x10
+      EOI = 0x20
+      NDAC = 0x40
+      NRFD = 0x80
+
+      # The CIA's port A: the data lines.
+      class Data
+        def initialize(ports)
+          @ports = ports
+        end
+
+        def read_a(_port_a, _port_b) = ~@ports.low_lines & 0xff
+
+        def read_b(_port_a, _port_b) = 0xff
+
+        def port_b4_high? = true
+      end
+
+      attr_reader :bus, :data
+
+      def initialize(bus)
+        @bus = bus
+        @data = Data.new(self)
+        @cia = nil
+        @tpi = nil
+        @pushed = 0
+      end
+
+      def connect(cia, tpi)
+        @cia = cia
+        @tpi = tpi
+      end
+
+      # TPI1's port A: the handshake lines and ATN.
+      def read_a(_lines)
+        low = low_lines
+        value = 0xff
+        value &= ~ATN if low.anybits?(Drives::IEEEBus::ATN)
+        value &= ~DAV if low.anybits?(Drives::IEEEBus::DAV)
+        value &= ~EOI if low.anybits?(Drives::IEEEBus::EOI)
+        value &= ~NDAC if low.anybits?(Drives::IEEEBus::NDAC)
+        value &= ~NRFD if low.anybits?(Drives::IEEEBus::NRFD)
+        value & 0xff
+      end
+
+      def read_b(_lines) = 0xff
+
+      def read_c(_lines) = 0xff
+
+      # The lines low on the bus.
+      def low_lines = @bus.low_lines(controller_lines)
+
+      # The drives on the bus see the lines the machine pulls now, if they
+      # moved.
+      def cycle_lines
+        lines = controller_lines
+        push(lines) unless lines == @pushed
+      end
+
+      # The drives on the bus see the lines the machine pulls now.
+      def push_lines = push(controller_lines)
+
+      private
+
+      def push(lines)
+        @pushed = lines
+        @bus.host_lines = lines
+      end
+
+      # The lines the machine pulls low.
+      def controller_lines
+        low = ~@cia.port_a_lines & Drives::IEEEBus::DIO
+        port_a = @tpi.port_a_output
+        low |= Drives::IEEEBus::ATN if port_a.nobits?(ATN)
+        low |= Drives::IEEEBus::DAV if port_a.nobits?(DAV)
+        low |= Drives::IEEEBus::EOI if port_a.nobits?(EOI)
+        low |= Drives::IEEEBus::NDAC if port_a.nobits?(NDAC)
+        low |= Drives::IEEEBus::NRFD if port_a.nobits?(NRFD)
+        low
+      end
+    end
+  end
+end

data/lib/badline/cbm2/ieee_traps.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    # The disk device 8 serves through the traps on the KERNAL's IEEE-488
+    # primitives (KernalTrap::IEEE, IEEELayout), and CHROUT capture. There
+    # is no LOAD or SAVE trap: the ROM's own LOAD and SAVE, which move the
+    # bytes into the segment they name, and BASIC's disk commands run
+    # through the primitives. Other devices find only a true drive on the
+    # bus (IEEEDrive), and the KERNAL reports the rest not present.
+    module IEEETraps
+      # Puts the storage in device 8. Mounting again swaps the disk while
+      # the machine runs, and the drive keeps its RAM and its status. The
+      # traps leave device 8 to a true drive with that number.
+      def mount(storage)
+        return @dos.insert(storage) if @dos
+
+        @dos = dos = KernalTrap::DOS.new(storage, channel_saves: true)
+        @ieee_trap = KernalTrap::IEEE.new(cpu:, bus:, layout: trap_layout, dos:).install
+        @ieee_trap.device = trap_device
+        @ieee_trap
+      end
+
+      # Takes device 8's storage out, and the traps with it.
+      def unmount
+        trap = @ieee_trap
+        return unless trap
+
+        trap.uninstall
+        @ieee_trap = nil
+        @dos = nil
+      end
+
+      # Whether device 8 serves a disk or directory through the traps.
+      def mounted? = !@dos.nil?
+
+      # The path of the disk or directory device 8 serves, or an empty one.
+      def mounted_path = @dos.nil? ? "" : @dos.path
+
+      # Device 8 through the traps in a keyed snapshot module (BL-TRAPDOS):
+      # the storage under storage.*, the DOS, and the IEEE-488 trap under
+      # ieee.*. Nothing mounted writes nothing.
+      def save_trap_dos_fields(out)
+        dos = @dos
+        return unless dos
+
+        Snapshot::StorageSetup.write_fields(dos.storage, out)
+        dos.save_fields(out)
+        @ieee_trap&.save_fields(out, "ieee.")
+      end
+
+      # `detached` mounts a disk image write-protected and no directory.
+      def load_trap_dos_fields(input, detached: false)
+        unmount
+        return if input.missing?
+
+        mount(Snapshot::StorageSetup.read_fields(input, detached:))
+        @dos&.load_fields(input)
+        @ieee_trap&.load_fields(input, "ieee.")
+      end
+
+      # Records what the KERNAL prints through CHROUT (KernalTrap::Chrout).
+      def capture_output
+        @capture_output ||= KernalTrap::Chrout.new(cpu:, bus:, layout: trap_layout).tap do |trap|
+          cpu.install_trap(KernalTrap::Chrout::ADDRESS) { trap.call }
+        end
+      end
+
+      # The IEEELayout of the KERNAL the machine runs.
+      def trap_layout = IEEELayout::LAYOUTS.fetch(@kernal)
+
+      private
+
+      # Device 8, unless a true drive is device 8.
+      def trap_device
+        device = KernalTrap::Routine::DEVICE
+        true_drive&.device == device ? nil : device
+      end
+    end
+  end
+end

data/lib/badline/cbm2/keyboard_ports.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    # What TPI2's ports read from outside the chip: the key matrix and the
+    # board's jumpers. The KERNAL drives the matrix's sixteen column lines
+    # low one at a time from PB0-PB7 and PA0-PA7 and reads its six row
+    # lines on PC0-PC5, a 0 for each key down. PC6 and PC7 read the
+    # jumpers: PC7 high on a 700, whose editor then loads its own CRTC
+    # table, and PC6 high on a 600 at 60 Hz.
+    #
+    # MATRIX lists the keys on each column line, PB0 first, in row order,
+    # :none where no key sits, as the KERNAL's key table at $EA29 places
+    # them, named as the B series' keyboard matrix sheet labels them.
+    class KeyboardPorts
+      MATRIX = [
+        %i[f1 escape tab none shift control],
+        %i[f2 1 q a z none],
+        %i[f3 2 w s x c],
+        %i[f4 3 e d f v],
+        %i[f5 4 r t g b],
+        %i[f6 5 6 y h n],
+        %i[f7 7 u j m space],
+        %i[f8 8 i k , .],
+        %i[f9 9 o l ; /],
+        [:f10, :"0", :-, :p, :"[", :"'"],
+        [:cursor_down, :"=", :left_arrow, :"]", :return, :pi],
+        %i[cursor_up cursor_left cursor_right delete cbm none],
+        %i[clr_home kp_question kp7 kp4 kp1 kp0],
+        %i[off_rvs ce kp8 kp5 kp2 kp_period],
+        %i[norm_graph kp_multiply kp9 kp6 kp3 kp00],
+        %i[run_stop kp_divide kp_minus kp_plus kp_enter none]
+      ].freeze
+
+      attr_reader :keyboard
+
+      # +jumpers+ is PC6 and PC7 as the board's jumpers drive them.
+      def initialize(keyboard, jumpers)
+        @keyboard = keyboard
+        @jumpers = jumpers
+        @tpi = nil
+      end
+
+      # The TPI whose ports drive the column lines.
+      def connect(tpi)
+        @tpi = tpi
+      end
+
+      def read_a(lines) = lines
+
+      def read_b(lines) = lines
+
+      def read_c(lines)
+        columns = (@tpi.port_a_output << 8) | @tpi.port_b_output
+        rows = @keyboard.scan(columns, lines | 0x3f).last
+        (rows & 0x3f) | (@jumpers & lines & 0xc0)
+      end
+    end
+  end
+end

data/lib/badline/cbm2/keyed_modules.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    # The whole machine as keyed snapshot modules (Snapshot::Keyed), in the
+    # order a load applies them: BL-MACHINE with the setup, the RAM with
+    # the segment registers, the CRTC, the picture, the SID, the CIA, the ACIA, both
+    # TPIs, the CPU, device 8 through the traps and a true 2031 on the
+    # IEEE-488 bus.
+    #
+    # A load lays the pages out 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-CPU") { |out| @cpu.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-RAM") { |out| bus.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-CRTC") { |out| @crtc.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-VIDEO") { |out| @video.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-SID") { |out| @sid.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-CIA") { |out| @cia.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-ACIA") { |out| @acia.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-TPI1") { |out| @tpi1.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-TPI2") { |out| @tpi2.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)
+        check_snapshot_setup(Snapshot::CBM2Setup.read_fields(modules.machine))
+        load_machine_fields(modules.machine)
+        @bus.load_fields(modules.required("BL-RAM"))
+        @bus.restored!
+        @crtc.load_fields(modules.required("BL-CRTC"))
+        @video.load_fields(modules.required("BL-VIDEO"))
+        @sid.load_fields(modules.required("BL-SID"))
+        @cia.load_fields(modules.required("BL-CIA"))
+        @acia.load_fields(modules.required("BL-ACIA"))
+        @tpi1.load_fields(modules.required("BL-TPI1"))
+        @tpi2.load_fields(modules.required("BL-TPI2"))
+        @cpu.load_fields(modules.required("BL-CPU"))
+        trap_dos = modules.optional("BL-TRAPDOS")
+        trap_dos ? load_trap_dos_fields(trap_dos, detached: modules.detached?) : unmount
+        load_drive_modules(modules)
+        @cpu.restored!
+        @sid.restored!
+        @cia.restored!
+        @acia.restored!
+        self
+      end
+
+      private
+
+      def check_snapshot_setup(setup)
+        ours = Snapshot::CBM2Setup.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/cbm2/keyed_state.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    class Bus
+      # Segment 15's RAM, the screen RAM, the RAM board's segments, both
+      # segment registers, the last byte on the bus and a cartridge's ROMs
+      # by load address, in a keyed snapshot module (BL-RAM). The pages are
+      # laid out again once loaded (#restored!). The BASIC and KERNAL ROMs
+      # come with the machine.
+      module KeyedState
+        def save_fields(out)
+          @ram.save_fields(out, "system")
+          @screen.save_fields(out, "screen")
+          @segment_ram.each_with_index { |memory, segment| memory&.save_fields(out, "segment#{segment}") }
+          out.int("execution_segment", @execution_segment).int("indirect_segment", @indirect_segment)
+          out.int("data", @data)
+          out.ints("cartridge.addresses", @cartridge.map(&:start))
+          @cartridge.each { |rom| out.bytes("cartridge.#{rom.start}", rom.snapshot) }
+        end
+
+        def load_fields(input)
+          @ram.load_fields(input, "system")
+          @screen.load_fields(input, "screen")
+          @segment_ram.each_with_index { |memory, segment| memory&.load_fields(input, "segment#{segment}") }
+          @execution_segment = input.masked("execution_segment", @execution_segment, 0x0f)
+          @indirect_segment = input.masked("indirect_segment", @indirect_segment, 0x0f)
+          @data = input.byte("data", @data)
+          @cartridge = input.ints("cartridge.addresses", []).filter_map { |address| cartridge_rom(input, address) }
+        end
+
+        def restored! = map_pages
+
+        private
+
+        # The cartridge ROM saved for +address+, in $1000-$7FFF of segment
+        # 15, or nil.
+        def cartridge_rom(input, address)
+          data = input.bytes("cartridge.#{address}", "".b).bytes
+          return nil if data.empty? || address < 0x1000 || address + data.length > 0x8000
+
+          ROM.new(data, length: data.length, start: address)
+        end
+      end
+
+      include KeyedState
+    end
+
+    # The machine's own fields in a keyed snapshot module (Snapshot::Keyed,
+    # BL-MACHINE): the family, its setup by name (Snapshot::CBM2Setup), the
+    # cycle count, where the mains is in its period, the refresh counter,
+    # 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 SID's deferred cycles and writes, run up to this cycle.
+      def settle_chips_for_snapshot = @sid.catch_up!
+
+      def save_machine_fields(out)
+        out.text("family", "cbm2").text("written_by", VERSION)
+        Snapshot::CBM2Setup.of(self).write_fields(out)
+        out.int("cycles", @cycles).int("mains_countdown", @mains_countdown).bool("mains_high", @mains_high)
+        out.int("refresh", @refresh)
+        pending = @pending_keys
+        out.ints("host.pending_keys", pending) if pending
+        save_init_keys(out)
+        out.int("host.init_pending", @cycles <= @init_threshold ? @init_handlers.length : 0)
+        save_ieee_drive_fields(out)
+      end
+
+      def load_machine_fields(input)
+        @cycles = input.int("cycles", @cycles)
+        countdown = input.int("mains_countdown", @mains_countdown)
+        @mains_countdown = countdown.between?(1, @mains_half_period) ? countdown : @mains_half_period
+        @mains_high = input.bool("mains_high", @mains_high)
+        @refresh = input.int("refresh", 0).clamp(0, REFRESH_COUNT)
+        pending = input.ints("host.pending_keys", [])
+        @pending_keys = pending.empty? ? nil : pending.dup
+        load_init_keys(input)
+        @init_handlers_lost = [input.int("host.init_pending", 0) - @init_handlers.length, 0].max
+        load_ieee_drive_fields(input)
+      end
+    end
+
+    include KeyedState
+  end
+end