badline 0.16.1 → 0.18.0

data/doc/snapshots.md

@@ -17,7 +17,7 @@ autosave that fails warns once and stops autosaving.
 
 The pause menu's Snapshots page quicksaves, saves under a name in the
 `saves` folder and loads a named save. The name starts as the game's,
-from its cartridge, disk or tape, or BASIC, with the next free number,
+from its cartridge, disk or tape, or BASIC, or KIM-1 on a KIM-1, with the next free number,
 and saving over a name already taken asks first. Below those, the
 newest quicksaves and autosaves, with the time each was saved, load
 with a press.
@@ -149,9 +149,14 @@ port lines the 8296's RAM follows, both PIAs, the VIA, the CPU, the
 CRTC on the boards that have one, the picture with where the video is
 in its frame, the tapes in both datasettes with their places on them,
 and the disk or directory device 8 serves through the IEEE-488 traps.
-It restores into a machine of the same model with the same RAM, the
-same editor frame rate, the same ROMs, which come with the model, and
-an 8296's same jumpers. Its file names its machine `PET`, as xpet's do,
+A SuperPET's also holds its board's latches and 64K of bank RAM, the
+6702, the ACIA, the 6809 and the traps on the Waterloo ROM's IEEE-488
+routines, in 6502 mode and in 6809 mode alike, and saves once the CPU
+that has the bus is between instructions. It restores into a machine of
+the same model with the same RAM, the same editor frame rate, the same
+ROMs, which come with the model, an 8296's same jumpers and a SuperPET's
+CPU and RAM switches at the same positions. Its file names its machine
+`PET`, as xpet's do,
 and holds only badline's modules, so xpet doesn't open it unless it is
 saved with `--vice` (see [xpet](#xpet)).
 
@@ -160,40 +165,203 @@ saved with `--vice` (see [xpet](#xpet)).
 A PET snapshot saved with `--vice`, or `computer.export_snapshot(path)`,
 also holds xpet's modules for the CPU, the RAM with the screen RAM, or
 an 8296's 32K from `$8000`, an 8096's or 8296's board and its control
-register, the CRTC, both PIAs and the VIA, and the ones xpet 3.10 needs
-to open the file, with nothing open on the file system drive and
-nothing on the user port. The CRTC module carries the discrete boards'
-video too, in xpet's terms. The file says it is in VICE's snapshot
-format 1.0, the only one xpet reads.
+register, a SuperPET's board, its bank and its `$EFFE` bit, the CRTC
+with the character set VIA CA2 picks, both PIAs and the VIA, a
+SuperPET's 6809 and ACIA, a true 2031's CPU, RAM, VIAs and head, or the
+interface processor of a true 8050, 8250, SFD-1001, 4040, 3040, 2040,
+D9060 or D9090, with its RAM and 6532s and the heads' tracks, and the
+ones xpet 3.10 needs to open
+the file, with nothing open on the file system drive and nothing on the
+user port. The CRTC module carries the discrete boards' video too, in
+xpet's terms. The file says it is in VICE's snapshot format 1.0, the
+only one xpet reads.
 
 xpet 3.10 opens those snapshots as long as its model and editor match:
-`-model 2001`, `3032`, `3032B`, `4032`, `8032`, `8096` or `8296`, and
-for a badline editor other than xpet's own, `-editor` naming badline's
-ROM. xpet's 8296 runs the 8032's editor, 901474-04 dated 0283, so an
+`-model 2001`, `3032`, `3032B`, `4032`, `8032`, `8096`, `8296` or
+`SuperPET`, and for a badline editor other than xpet's own, `-editor`
+naming badline's ROM. xpet runs a SuperPET's 6809 when the snapshot
+says it has the bus, whatever its own CPU switch, and has no system
+latch, write protect or 6702 to take from it. xpet's 8296 runs the 8032's editor, 901474-04 dated 0283, so an
 8296 saved for it has to run that editor (`--editor 4-80-b-50hz-0283`),
 and xpet takes the 8296's jumpers from its own settings. It keeps its
-own drives and datasettes and leaves out badline's tapes and disk. Its
-CRTC loses a few lines on opening any snapshot, its own too, so a
-program it runs on from one finds the vertical sync a few hundred
-cycles later than one it ran without stopping.
+own datasettes and leaves out badline's tapes and disks. A true drive
+needs `-drive8type 2031`, `8050`, `8250`, `1001`, `4040`, `3040`,
+`2040`, or `9000` for either hard disk, with `-drive8truedrive` and the
+disk attached as `-8`. Its snapshot is settled with the 2031's CPU
+between instructions too, and one saved while the 2031 talks on the bus
+can stall there in xpet, as xpet's own snapshots saved while it searches
+for a file do. xpet runs an 8050's floppy controller, and a hard disk's
+SASI host, at a high level, so a snapshot for it is settled until
+badline's controller, or host, sits in its idle loop with both
+processors between instructions, and xpet's controller
+starts from idle there, taking up any job the interface processor has
+left it. A unit that doesn't reach its idle loop within about 262,000
+cycles, such as one still starting up, is left out of xpet's modules,
+and badline's own modules keep it. Its CRTC loses a few lines on
+opening any snapshot, its own too, so a program it runs on from one
+finds the vertical sync a few hundred cycles later than one it ran
+without stopping.
 
 Snapshots xpet saves open in badline through the same modules: the CPU
 at its instruction boundary, the RAM, the screen RAM, an 8096's or
 8296's board, the CRTC's registers and beam, both PIAs' registers and
-flags, and the VIA's registers, timers and shift register. A program
+flags, the VIA's registers, timers and shift register, a true 2031's
+CPU, RAM, VIAs and head, which go on the bus with the disk badline's
+2031 had in it, and the interface processor of a true 8050, 8250,
+SFD-1001, 4040, 3040, 2040, D9060 or D9090, its RAM and both 6532s,
+which go on the bus with the disks badline's unit of the same model had
+in it. xpet's type 9000 stands for both hard disks, and the hard disk
+badline's had in it, of either, makes it a D9090 for an image of six
+heads and otherwise a D9060. Its floppy controller comes back as a unit
+switched on has it, in its idle loop with the heads on track 1: its next
+job steps them out to the track, and a job xpet's controller had under
+way starts again from there. A hard disk's SASI host comes back in its
+job loop the same way. A program
 badline runs on from xpet's snapshot finds the vertical sync on the
 cycle xpet does, so the two run on alike, cycle for cycle. The picture
 starts again with the next frame. xpet doesn't save its ROMs, which
 keyboard it has or an 8296's jumpers, so the board, the RAM and the
 CRTC's frame build the machine: a 2001, a 3032 for any other discrete
 board, a 4032, an 8032, an 8096 or an 8296 with none of its jumpers
-fitted, at 50 or 60 Hz, and an 8032, 8096 or 8296 whose CRTC lines are
-64 cycles long runs xpet's own 50 Hz editor, 901474-04 dated 0283. A
-SuperPET's snapshot fails. It reports the modules it leaves out, such
-as the drives, the datasettes and the keyboard, and carries on without
-them. Restored into a running PET, an xpet snapshot fails for a PET
-built another way, such as a 3032B, and otherwise switches the machine
-off and on, keeping its tapes and the disk device 8 serves.
+fitted, or a SuperPET, at 50 or 60 Hz, and an 8032, 8096 or 8296 whose
+CRTC lines are 64 cycles long runs xpet's own 50 Hz editor, 901474-04
+dated 0283. A SuperPET comes with its bank RAM, its bank, its `$EFFE`
+bit and its ACIA, its CPU switch at the CPU that had the bus, and while
+that is the 6809, the 6809's registers. Its RAM switch is at R/W, the
+only position xpet has, its system latch is clear and its 6702 is as the
+RES line leaves it, since xpet saves none of them, and in 6809 mode its
+frame rate is the one the Waterloo ROM's CRTC table sets. It reports the modules it leaves out, such
+as the drives past device 8, the datasettes and the keyboard, and
+carries on without them, and a snapshot without a true drive takes
+badline's off the bus and says so.
+Restored into a running PET, an xpet snapshot fails for a PET built
+another way, such as a 3032B, and otherwise switches the machine off
+and on, keeping its tapes and the disk device 8 serves.
+
+## The CBM-II
+
+The B series, the 610, 620, 710 and 720, saves and restores the same
+way. A snapshot of one holds segment 15's RAM, the screen RAM, the RAM
+board's segments, both segment registers, a cartridge's ROMs, the CPU,
+the CRTC with the picture, the SID, the CIA, the ACIA, both TPIs with
+their priority stacks, the mains' place in its period, and the disk or
+directory device 8 serves through the IEEE-488 traps. It restores into
+a machine of the same model with the same KERNAL and mains. Its file
+names its machine `CBM-II`, as xcbm2's do, and holds only badline's
+modules, so xcbm2 doesn't open it unless it is saved with `--vice` (see
+[xcbm2](#xcbm2)).
+
+### xcbm2
+
+A CBM-II snapshot saved with `--vice`, or `computer.export_snapshot(path)`, also holds
+xcbm2's modules for the CPU, the RAM with both segment registers, the
+CRTC, the CIA, both TPIs, the ACIA and the SID, a true 2031, 8050 or
+8250 as xpet's are written (see [xpet](#xpet)), or with no true drive,
+none on any device, and the ones xcbm2 3.10 needs to open the file, with
+no cartridge, nothing open on the file system drive and nothing on the
+user port. The file says it is in
+VICE's snapshot format 1.0, the only one xcbm2 reads.
+
+xcbm2 3.10 opens those snapshots as long as its model matches: `-model
+610`, `620`, `710` or `720`. It takes a 600's 60 Hz from the snapshot
+and leaves out badline's cartridge and disks. A true drive needs
+`-drive8type 2031`, `8050` or `8250` with `-drive8truedrive` and the
+disk attached as `-8`, and with no true drive in the snapshot xcbm2
+takes its own off the bus. It
+runs on from badline's snapshot just as it runs on from one it saved
+itself, cycle for cycle. Opening any snapshot, its own too, costs it a
+couple of hundred cycles of its CRTC, so the mains ticks that much later
+than in a run that didn't stop.
+
+xcbm2 saves no mains. It ticks the mains once a frame of its CRTC, as
+vertical sync ends, whatever its mains is set to, so its ticks come a
+frame apart: 40,064 cycles on a 600 at 50 Hz, where badline's come
+40,000 apart, and its 700 has no 60 Hz. A snapshot saved for xcbm2 ticks
+where xcbm2's CRTC says, not where badline's mains had it. Neither
+does xcbm2 save a TPI's priority stack, so the interrupts in service are
+lost both ways. Its cursor blinks 32 fields on and 32 off, where the
+6845 blinks 16 and 16, so it comes back showing or hidden as it was,
+with its place in the blink scaled.
+
+Snapshots xcbm2 saves open in badline through the same modules: the CPU
+at its instruction boundary, the RAM and both segment registers, the
+CRTC's registers and beam, the CIA's registers, timers and clock, both
+TPIs' registers, latches, mask, AIR, CA and CB, the ACIA's registers and
+the byte it waits to send, and the SID's registers and reSID voice
+state. The mains' next falling edge comes where xcbm2 would tick it, and
+the ones after at badline's 50 or 60 Hz, so the two part from the
+second tick on. xcbm2 has no DRAM refresh, so a program badline runs
+on from xcbm2's snapshot runs about 5% slower than in xcbm2, as the
+refresh takes a cycle from the CPU about every 21. On a machine built
+with `refresh: false` it reads the mains, the CIA and the rest as xcbm2
+does until that second tick, cycle for cycle. The picture starts again with the next frame. xcbm2 doesn't
+save its ROMs, so the RAM board and the model line build the machine:
+a 610, 620, 710 or 720 with xcbm2's KERNAL, 901244-04a, at 60 Hz for a
+600 whose model line says so and at 50 Hz otherwise. A board of 512K or
+more, or RAM mapped into segment 15, fails. A true 2031, 8050 or 8250
+goes on the bus as xpet's does, with the disks badline's drive of that
+model had, and xcbm2 runs a true 2031 on device 8 unless told otherwise,
+so its snapshots mostly put one there. One saved part way into a `LOAD`
+from xcbm2's true drive goes on with it in badline. A snapshot without
+a true drive takes badline's off the bus and says so. It reports the
+modules it leaves out, such as the datasette and the keyboard, and
+carries on without them. Restored into a running CBM-II, an xcbm2
+snapshot fails for a CBM-II built another way, and otherwise switches
+the machine off and on, keeping the disk device 8 serves through the
+traps.
+
+### xcbm5x0
+
+The P500, the 510 on PAL and NTSC, saves and restores as the B series
+does, with the VIC-II and its colour RAM in place of the CRTC. Its file
+names its machine `CBM-II-5x0`, as xcbm5x0's do. Saved with `--vice`,
+or `computer.export_snapshot(path)`, it also holds xcbm5x0's modules
+for the CPU, the RAM with the video matrix, the colour RAM and both
+segment registers, the CIA, both TPIs, the ACIA, the SID, a true drive
+or none as for the B series, the VIC-II and the mains, and the ones
+xcbm5x0 3.10 needs to open the file, with
+no cartridge, nothing open on the file system drive and the joysticks
+released. The file says it is in VICE's snapshot format 0.0, as
+xcbm5x0 writes it.
+
+xcbm5x0 3.10 opens those snapshots with `-model 510`, and `-ntsc` for
+an NTSC 510, takes the true drive as xcbm2 does and leaves out badline's
+cartridge and disks. It runs on from badline's snapshot as it runs on from its own,
+cycle for cycle. xcbm5x0 runs VICE's line-based VIC-II, not x64sc's, and
+its module is laid out otherwise: it carries the registers, colour RAM,
+the beam, VC, VCBASE, whether the sequencer is idle, the buffers and
+the sprites' DMA, and badline writes the rest as xcbm5x0 leaves it.
+xcbm5x0 saves the cycles to the mains' next tick, which badline reads
+and writes. It ticks the mains every 19,656 cycles, a PAL frame, on
+NTSC too, about 52 Hz there, where badline's NTSC 510 runs at 60 Hz, so
+a tick more than a 60 Hz period away comes back sooner.
+
+Snapshots xcbm5x0 saves open in badline through the same modules, as
+xcbm2's do, with the VIC-II's registers, beam, counters and colour RAM,
+and the mains' next tick on xcbm5x0's cycle. The row counter follows
+from the line, and the sprites' counters, the borders' flip-flops and
+the pixel pipeline start afresh. xcbm5x0's VIC isn't cycle exact as
+x64sc's is, so a program badline runs on from its snapshot reads the
+raster a cycle off now and then, and its cycles drift from xcbm5x0's by
+a few over a second. The picture starts again with the next frame. The
+RAM's size and the VIC's picture build the machine: a 510, on NTSC for
+NTSC's picture. More RAM fails. A true drive goes on the bus as from
+xcbm2's snapshots. Restored into a running P500, an
+xcbm5x0 snapshot fails for a P500 built another way, and otherwise
+switches the machine off and on, keeping the disk device 8 serves.
+
+## The KIM-1
+
+A KIM-1 saves and restores as the others do. A snapshot of one holds
+its RAM, the expansion's too, the CPU, both 6530s with their 64 bytes,
+ports and timers, the timer's interrupt flag among them, the panel with
+the TTY/KB jumper, the key held down and how long each LED segment has
+been lit, the teletype with the character on its way in or out, what
+it has queued and all it has printed, the SST switch, U3's wiring to
+IRQ and the speaker, and the keys `type_keys` has still to press. It
+restores into a KIM-1 with the same RAM. Its file names its machine
+`KIM1`, since VICE has no KIM-1, so no VICE emulator opens it, and
+`--vice` fails for it.
 
 ## VICE
 

data/exe/badline-ruby

@@ -34,6 +34,11 @@ def load_sdl
   require "badline/frontend"
 end
 
+if options.kim1_terminal?
+  require "badline/audio/console"
+  exit Badline::KIM1::HostTerminal.start(options, Badline::Audio::Console.new(input: $stdin, output: $stdout))
+end
+
 if options.headless?
   require "badline/audio/console"
   console = if options.player_window?

data/lib/badline/audio/terminal.rb

@@ -4,8 +4,9 @@ module Badline
   module Audio
     # The terminal face of `--headless`: the tune's header, a status line
     # redrawn in place, and single keypresses read without waiting for
-    # Return. Ctrl-C still interrupts. A subclass puts the terminal in raw
-    # mode with #raw! and #restore and waits for keys with #readable?:
+    # Return, or for the KIM-1, the text typed and printed (#typing).
+    # Ctrl-C still interrupts. A subclass puts the terminal in raw mode
+    # with #raw! and #restore and waits for keys with #readable?:
     # Console with io/console for badline-ruby, and Native::Console with
     # stty and poll(2) for the native badline.
     class Terminal
@@ -50,6 +51,37 @@ module Badline
         end
       end
 
+      # Raw input for the length of the block, the cursor showing, for a
+      # session that types and prints text, as the KIM-1's teletype does.
+      def typing
+        mode = raw! if @input.tty?
+        yield
+      ensure
+        restore(mode) if mode
+        @output.print "\r\n"
+      end
+
+      # Waits up to `seconds` for keys and returns what they typed, as raw
+      # mode reads it, or an empty string.
+      def read_text(seconds)
+        if @closed
+          sleep(seconds)
+          return ""
+        end
+        return "" unless readable?(seconds)
+
+        text = @input.read_nonblock(64, exception: false)
+        return "" if text == :wait_readable
+
+        @closed = true if text.nil?
+        text.nil? ? "" : text
+      end
+
+      def print_text(text)
+        @output.print(text)
+        @output.flush
+      end
+
       def header(lines)
         lines.each { |line| @output.print "#{line}\r\n" }
         @output.print "←/→ subtune  n/p tune  ,/. seek  space pause  s shuffle  l loop  a all subtunes  q quit\r\n"

data/lib/badline/c128/keyed_state.rb

@@ -39,6 +39,7 @@ module Badline
         pending = @pending_keys
         out.ints("host.pending_keys", pending) if pending
         out.bool("host.typing", !pending.nil?)
+        save_init_keys(out)
         out.int("host.init_pending", @cycles <= init_threshold ? @init_handlers.length : 0)
         out.bool("host.holding_commodore", @holding_commodore)
         @typist.save_fields(out, "host.typist.")
@@ -55,6 +56,7 @@ module Badline
         @cpu_reset_pending = input.bool("cpu_reset_pending", @cpu_reset_pending)
         pending = input.ints("host.pending_keys", [])
         @pending_keys = input.bool("host.typing", !pending.empty?) ? pending.dup : nil
+        load_init_keys(input)
         @init_handlers_lost = [input.int("host.init_pending", 0) - @init_handlers.length, 0].max
         load_holding_fields(input)
         @typist.load_fields(input, "host.typist.")

data/lib/badline/c128.rb

@@ -139,6 +139,7 @@ module Badline
       @restore_pulse = false
       @init_handlers = []
       @pending_keys = nil
+      @init_keys = nil
       @typist = Input::MatrixTypist.new(@bus.keyboard)
       @capture_output = nil
       init_drives

data/lib/badline/c64/keyed_state.rb

@@ -39,6 +39,7 @@ module Badline
         out.bool("dma", @dma)
         pending = @pending_keys
         out.ints("host.pending_keys", pending) if pending
+        save_init_keys(out)
         out.int("host.init_pending", booting? ? @init_handlers.length : 0)
       end
 
@@ -52,6 +53,7 @@ module Badline
         @dma = input.bool("dma", @dma)
         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
       end
 

data/lib/badline/c64.rb

@@ -80,6 +80,7 @@ module Badline
       @freeze_writes = 0
       @init_handlers = []
       @pending_keys = nil
+      @init_keys = nil
       @dos = nil
       @serial_trap = nil
       @save_trap = nil

data/lib/badline/cbm2/acia.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    # The B series' 6551 at $DD00, the RS-232 port's, whose IRQ reaches
+    # TPI1's I4.
+    class ACIA < Chips::ACIA
+    end
+  end
+end

data/lib/badline/cbm2/bus.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Badline
+  class CBM2
+    # The 6509's bus: sixteen segments of 64K, which the CPU's four extra
+    # address lines pick from the execution register at $0000 or, for the
+    # data of LDA (zp),Y and STA (zp),Y, the indirection register at $0001
+    # (CPU). Both registers answer at $0000 and $0001 in every segment.
+    #
+    # Segment 15 is the system's:
+    #
+    # $0000-$07FF - 2K of static RAM
+    # $0800-$0FFF - nothing: the buffer RAM socket
+    # $1000-$7FFF - the disk ROM's socket and the cartridge's three 8K
+    #               selects, nothing until a ROM is in (#attach_cartridge)
+    # $8000-$BFFF - BASIC
+    # $C000-$CFFF - nothing
+    # $D000-$D7FF - the screen RAM
+    # $D800-$DFFF - I/O, a chip a page (#map_io), nothing where none is
+    # $E000-$FFFF - the KERNAL
+    #
+    # The RAM board fills the segments +ram_segments+ names, and the rest
+    # hold nothing. The data lines hold the last byte they carried, which
+    # a read from nothing finds, and a write to ROM or to nothing goes
+    # nowhere.
+    #
+    # Each segment is a pair of page tables, one read and one write. The
+    # CPU reads and writes through the execution segment's (#peek and
+    # #poke), and a write to $0000 switches them, so an access pays
+    # nothing for the banking. For an indirect access the CPU switches to
+    # the indirection segment's tables and back (#select_indirect! and
+    # #select_execute!).
+    class Bus
+      include Addressable
+
+      SEGMENTS = 16
+      SYSTEM = 15
+
+      # The last byte the CPU moved, which nothing reads back.
+      class OpenBus
+        def initialize(bus)
+          @bus = bus
+        end
+
+        def peek(_addr) = @bus.data
+        def poke(_addr, _value); end
+      end
+
+      # A segment's page 0: the execution register at $0000 and the
+      # indirection register at $0001, whose reads return the register in
+      # the low four bits and 0 in the high four, over what the page holds.
+      class Registers
+        def initialize(bus, under)
+          @bus = bus
+          @under = under
+        end
+
+        def peek(addr)
+          case addr
+          when 0 then @bus.execution_segment
+          when 1 then @bus.indirect_segment
+          else @under.peek(addr)
+          end
+        end
+
+        def poke(addr, value)
+          case addr
+          when 0 then @bus.execution_segment = value & 0x0f
+          when 1 then @bus.indirect_segment = value & 0x0f
+          else @under.poke(addr, value)
+          end
+        end
+      end
+
+      # VICE's debug cartridge register at $DAFF in segment 15, which a
+      # write calls the handler with, the exit code the VICE testprogs
+      # report. Every other write to its page passes to the chip there.
+      class DebugRegister
+        ADDRESS = 0xdaff
+
+        attr_accessor :under
+
+        def initialize(&handler)
+          @handler = handler
+          @under = nil
+        end
+
+        def poke(addr, value)
+          return @handler.call(value) if addr == ADDRESS
+
+          @under.poke(addr, value)
+        end
+      end
+
+      attr_reader :ram, :screen, :segment_ram, :execution_segment
+      attr_accessor :indirect_segment
+
+      # The last byte the CPU read or wrote.
+      attr_reader :data
+
+      # +basic+ and +kernal+ are ROM files for $8000-$BFFF and
+      # $E000-$FFFF, +ram_segments+ the segments the RAM board fills, and
+      # +screen_length+ the bytes of screen RAM from $D000 on.
+      def initialize(basic:, kernal:, ram_segments:, screen_length: 0x800)
+        addressable_at(0, length: 2**16)
+        @ram = Memory.new([], length: 0x800, start: 0)
+        @screen = Memory.new([], length: screen_length, start: 0xd000)
+        @screen_pages = screen_length >> 8
+        @basic_rom = ROM.load(basic, 0x8000)
+        @kernal_rom = ROM.load(kernal, 0xe000)
+        @open_bus = OpenBus.new(self)
+        @data = 0
+        @segment_ram = Array.new(SEGMENTS) do |segment|
+          ram_segments.include?(segment) ? Memory.new([], length: 0x10000, start: 0) : nil
+        end
+        @io = Array.new(8, @open_bus)
+        @cartridge = []
+        @video = Array.new(0x18, nil)
+        @video_writable = Array.new(0x18, false)
+        @debug_register = nil
+        @reads = Array.new(SEGMENTS) { Array.new(256, @open_bus) }
+        @writes = Array.new(SEGMENTS) { Array.new(256, @open_bus) }
+        reset!
+        map_pages
+      end
+
+      # The RES line sets both registers to 15.
+      def reset!
+        self.execution_segment = SYSTEM
+        @indirect_segment = SYSTEM
+      end
+
+      def power_on!
+        @ram.clear!
+        @screen.clear!
+        @segment_ram.each { |memory| memory&.clear! }
+      end
+
+      def execution_segment=(segment)
+        @execution_segment = segment
+        select_execute!
+      end
+
+      # Switches the CPU's accesses to the indirection segment, for the one
+      # access LDA (zp),Y or STA (zp),Y moves its data with.
+      def select_indirect!
+        @read_pages = @reads[@indirect_segment]
+        @write_pages = @writes[@indirect_segment]
+      end
+
+      # Switches them back to the execution segment.
+      def select_execute!
+        @read_pages = @reads[@execution_segment]
+        @write_pages = @writes[@execution_segment]
+      end
+
+      def peek(addr)
+        @data = @read_pages[addr >> 8].peek(addr)
+      end
+
+      def poke(addr, value)
+        @data = value
+        @write_pages[addr >> 8].poke(addr, value)
+      end
+
+      # Reads and writes +segment+ as the CPU would, wherever it executes.
+      def peek_bank(segment, addr) = @reads[segment][addr >> 8].peek(addr)
+
+      def poke_bank(segment, addr, value)
+        @writes[segment][addr >> 8].poke(addr, value)
+      end
+
+      # Whether the CPU runs the KERNAL: it executes in segment 15.
+      def kernal_mapped? = @execution_segment == SYSTEM
+
+      # Puts +chip+ at I/O page +page+, $D8 to $DF of segment 15. The chip
+      # hears the whole address.
+      def map_io(page, chip)
+        @io[page - 0xd8] = chip
+        map_pages
+      end
+
+      # Puts +chip+ at +count+ pages of segment 15 from +page+ on, between
+      # $C000 and $D7FF, over what was there: the P500's character ROM, and
+      # its colour RAM, which takes writes as well (+writable+). The chip
+      # hears the whole address.
+      def map_video(chip, page, count, writable: false)
+        count.times do |i|
+          @video[page + i - 0xc0] = chip
+          @video_writable[page + i - 0xc0] = writable
+        end
+        map_pages
+      end
+
+      # Puts the cartridge's ROM chips, Storage::CRTFile::Chips, at their
+      # load addresses in segment 15, from $1000 to $7FFF, in place of what
+      # was there.
+      def attach_cartridge(chips)
+        @cartridge = chips.map { |chip| ROM.new(chip.data, length: chip.data.length, start: chip.address) }
+        map_pages
+      end
+
+      def detach_cartridge
+        @cartridge = []
+        map_pages
+      end
+
+      # Calls the block with each byte written to $DAFF (DebugRegister).
+      def install_debug_register(&)
+        @debug_register = DebugRegister.new(&)
+        map_pages
+      end
+
+      private
+
+      def map_pages
+        SEGMENTS.times do |segment|
+          memory = @segment_ram[segment]
+          if memory
+            map(segment, memory, 0x00, 0x100)
+          else
+            map(segment, @open_bus, 0x00, 0x100)
+          end
+        end
+        map_system
+        SEGMENTS.times { |segment| map_registers(segment) }
+        select_execute!
+      end
+
+      def map_system
+        map(SYSTEM, @open_bus, 0x00, 0x100)
+        map(SYSTEM, @ram, 0x00, 0x08)
+        @cartridge.each { |rom| @reads[SYSTEM].fill(rom, rom.start >> 8, rom.length >> 8) }
+        @reads[SYSTEM].fill(@basic_rom, 0x80, 0x40)
+        map(SYSTEM, @screen, 0xd0, @screen_pages)
+        @video.each_with_index { |chip, i| map_video_page(chip, 0xc0 + i, @video_writable[i]) if chip }
+        @io.each_with_index { |chip, i| map(SYSTEM, chip, 0xd8 + i, 1) }
+        @reads[SYSTEM].fill(@kernal_rom, 0xe0, 0x20)
+        map_debug_register if @debug_register
+      end
+
+      def map_video_page(chip, page, writable)
+        @reads[SYSTEM][page] = chip
+        @writes[SYSTEM][page] = writable ? chip : @open_bus
+      end
+
+      def map_registers(segment)
+        @reads[segment][0] = Registers.new(self, @reads[segment][0])
+        @writes[segment][0] = Registers.new(self, @writes[segment][0])
+      end
+
+      def map_debug_register
+        @debug_register.under = @writes[SYSTEM][0xda]
+        @writes[SYSTEM][0xda] = @debug_register
+      end
+
+      def map(segment, chip, first, count)
+        @reads[segment].fill(chip, first, count)
+        @writes[segment].fill(chip, first, count)
+      end
+    end
+  end
+end