badline 0.16.0 → 0.17.0

data/lib/badline/snapshot/vice/p500_vicii.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Vice
+      module P500
+        # VIC-II 1.3 as xcbm5x0 writes it, which runs VICE's line-based
+        # VIC-II rather than x64sc's, so the module is laid out otherwise
+        # than x64sc's under the same name: whether bad lines may happen,
+        # whether this line is one, the vertical border, the colour
+        # buffer, colour RAM, whether the sequencer is idle, the light
+        # pen's trigger and position, the video matrix buffer, the sprites
+        # whose DMA starts next line, a word xcbm5x0 keeps at $00100000,
+        # the beam's cycle and line, the registers, the sprite collisions
+        # pending, the sprites' DMA, the VIC's bank, VC, the matrix's
+        # width, VCBASE, then sprite and drawing fields with the bank
+        # again, the line its picture draws next and its size, and the
+        # picture. xcbm5x0's cycle in the line is badline's column.
+        #
+        # Written: the registers, colour RAM, the buffers, the beam with
+        # its counters and the sprites' DMA as badline's VIC has them, the
+        # bank as TPI2's PC6 and PC7 pick it, and the rest as xcbm5x0
+        # leaves it. The picture is left blank, as xcbm5x0 paints it again.
+        #
+        # Read: the registers, colour RAM, the buffers, the beam with VC,
+        # VCBASE and whether the sequencer is idle, the light pen and the
+        # sprites' DMA, through the x64sc module's reader (VICII::Import).
+        # The row counter follows from the line and YSCROLL, and the
+        # sprites' counters and the borders' flip-flops start afresh.
+        # xcbm5x0's VIC isn't x64sc's, so a program badline runs on from its
+        # snapshot reads the raster a cycle or so off now and then.
+        module VICII
+          NAME = Vice::VICII::NAME
+          MAJOR = 1
+          MINOR = 3
+          ALLOW_BAD_LINES = 0x000
+          BAD_LINE = 0x001
+          BLANK = 0x002
+          COLOR_BUFFER = 0x003
+          COLOR_RAM = 0x02b
+          IDLE = 0x42b
+          LIGHT_PEN = 0x42c
+          MATRIX_BUFFER = 0x42f
+          RAM_BASE = 0x458
+          CYCLE = 0x45c
+          LINE = 0x45d
+          REGISTERS = 0x45f
+          SPRITE_DMA = 0x4a0
+          BANK = 0x4a2
+          VC = 0x4a4
+          VC_ADD = 0x4a6
+          VC_BASE = 0x4a7
+          VIDEO_INT = 0x4a9
+          DRAW_FLAGS = 0x4cd
+          FETCH_BANK = 0x4cf
+          DRAWN_LINE = 0x4d1
+          PICTURE = 0x4d5
+          HEADER = 0x4e1
+          # The picture's size: PAL's and NTSC's.
+          SIZES = { 312 => [504, 312], 263 => [520, 275] }.freeze
+
+          module_function
+
+          def reads?(section) = section.major == MAJOR && section.minor == MINOR
+
+          # The lines xcbm5x0's picture has, which name its region.
+          def picture_lines(section) = FieldReader.new(section).skip(PICTURE + 4).dword
+
+          def export(machine)
+            vic = machine.vic
+            width, height = SIZES.fetch(vic.region.lines_per_frame)
+            bytes = Array.new(HEADER + (width * (height + 4)), 0)
+            sequencer(vic, bytes)
+            bytes[COLOR_RAM, 0x400] = Array.new(0x400) { |offset| machine.color_ram.nibble(0xd400 + offset) }
+            beam(vic, bytes)
+            bank = ((machine.tpi2.port_c_output >> 6) & 0x03) << 14
+            [BANK, FETCH_BANK].each { |at| word(bytes, at, bank) }
+            [RAM_BASE + 2, DRAW_FLAGS].each { |at| bytes[at] = 0x10 }
+            bytes[VIDEO_INT] = 1
+            [vic.rasterline, width, height, width].each_with_index do |value, n|
+              dword(bytes, DRAWN_LINE + (4 * n), value)
+            end
+            FieldWriter.new.bytes(bytes).section(NAME, MAJOR, MINOR)
+          end
+
+          # The sequencer's state and the buffers it reads.
+          def sequencer(vic, bytes)
+            state = vic.display_state
+            bytes[ALLOW_BAD_LINES] = state.bad_lines_enabled ? 1 : 0
+            bytes[BAD_LINE] = state.bad_line_condition? ? 1 : 0
+            bytes[BLANK] = vic.sequencer.borders.first ? 1 : 0
+            bytes[COLOR_BUFFER, 40] = vic.color_buffer.map { |value| value || 0 }
+            bytes[IDLE] = state.display? ? 0 : 1
+            bytes[MATRIX_BUFFER, 40] = vic.character_buffer.map { |value| value || 0 }
+          end
+
+          # The beam, the registers and the counters.
+          def beam(vic, bytes)
+            state = vic.display_state
+            bytes[CYCLE] = vic.column
+            word(bytes, LINE, vic.rasterline)
+            bytes[REGISTERS, 0x40] = vic.register_file
+            bytes[SPRITE_DMA] = 8.times.sum { |n| vic.sprites[n].displaying? ? 1 << n : 0 }
+            word(bytes, VC, state.vc)
+            bytes[VC_ADD] = 40
+            word(bytes, VC_BASE, state.vc_base)
+          end
+
+          def word(bytes, at, value) = bytes[at, 2] = [value & 0xffff].pack("v").bytes
+
+          def dword(bytes, at, value) = bytes[at, 4] = [value].pack("V").bytes
+
+          def import(section, vic, color_ram)
+            Import.new(section, vic.region).apply_to(vic, color_ram, 0xd400)
+          end
+
+          # Reads xcbm5x0's module into the fields x64sc's reader puts into
+          # badline's VIC.
+          class Import < Vice::VICII::Import
+            # x64sc's cycle is badline's column plus one, its cycle 0 the
+            # last column of the line before (VICII.vice_cycle).
+            def initialize(section, region)
+              super(nil)
+              bytes = section.data.bytes
+              @registers = bytes[REGISTERS, 0x40]
+              line = bytes[LINE] | (bytes[LINE + 1] << 8)
+              @cycle = (bytes[CYCLE] + 1) % region.cycles_per_line
+              @line = @cycle.zero? ? (line + 1) % region.lines_per_frame : line
+              @frame_start = false
+              @irq_status = @registers[0x19]
+              @raster_match = false
+              @character_buffer = bytes[MATRIX_BUFFER, 40]
+              @color_buffer = bytes[COLOR_BUFFER, 40]
+              read_old_counters(bytes)
+              @color_ram = bytes[COLOR_RAM, 0x400]
+              @sprite_mc = Array.new(8, 0)
+              @sprite_mcbase = Array.new(8, 0)
+              @sprite_exp_ff = 0
+            end
+
+            private
+
+            def read_old_counters(bytes)
+              @bad_lines_enabled = !bytes[ALLOW_BAD_LINES].zero?
+              @collisions = [@registers[0x1e], @registers[0x1f]]
+              @display = bytes[IDLE].zero?
+              @vc_base = bytes[VC_BASE] | (bytes[VC_BASE + 1] << 8)
+              @vc = bytes[VC] | (bytes[VC + 1] << 8)
+              @rc = @display ? (@line - @registers[0x11]) & 0x07 : 7
+              @vmli = 0
+              @lp_low = false
+              @lp_triggered = !bytes[LIGHT_PEN].zero?
+              @fetch_d011 = @registers[0x11]
+              @dma_bits = bytes[SPRITE_DMA]
+              @display_bits = @dma_bits
+              blank = !bytes[BLANK].zero?
+              @vertical_border = blank
+              @vertical_armed = false
+              @main_border = blank
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/vice/pet.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "badline/snapshot/vice/pet_cpu"
+require "badline/snapshot/vice/pet_mem"
+require "badline/snapshot/vice/pet_pias"
+require "badline/snapshot/vice/pet_via"
+require "badline/snapshot/vice/pet_crtc"
+require "badline/snapshot/vice/pet_drive"
+require "badline/snapshot/vice/pet_drive8050"
+require "badline/snapshot/vice/pet_restore"
+
+module Badline
+  module Snapshot
+    module Vice
+      # xpet's modules for the PET: the CPU, the RAM, the CRTC, both PIAs,
+      # the VIA and a true 2031, written from badline's machine and read
+      # into it. Each
+      # module's file says what maps and what is approximated. They go
+      # through the PET's own keyed fields (Keyed), which a save writes and a
+      # load reads, so they read no chip's insides.
+      module PET
+        # The models badline builds by the board PETMEM names (PETMem): the
+        # discrete board is a 2001's where xpet's settings say so, and a
+        # 3032 otherwise.
+        MODELS = { PETMem::CRTC40 => "4032", PETMem::CRTC80 => "8032", PETMem::CBM8096 => "8096",
+                   PETMem::CBM8296 => "8296" }.freeze
+        # The modules xpet resets the machine without, for the parts badline
+        # doesn't model in VICE's terms, each as xpet leaves them with
+        # nothing attached: no file system drive open, both cassette ports
+        # on with a datasette in #1, and nothing in the user port.
+        PERIPHERALS = [
+          ["FSDRIVE", 0, 0, Array.new(258, 0)], ["TAPEPORT", 1, 0, [0x01, 0x01, 0x01]], ["USERPORT", 1, 0, [0x01, 0x00]]
+        ].freeze
+        # The cycles a frame below which a CRTC editor runs at 60 Hz.
+        SIXTY_HZ_FRAME = 18_333
+        # The 8032's 50 Hz editors by the cycles a line they set up: xpet's
+        # own, 901474-04 dated 0283, sets 64.
+        EDITOR_0283_LINE = 64
+
+        module_function
+
+        # The modules xpet 3.10 needs, in its order, describing `machine`,
+        # which Machine::Settling has brought between instructions, from
+        # its keyed modules, `sections`.
+        def export(machine, sections)
+          readers = {}
+          sections.each { |section| readers[section.name] = Keyed::Reader.parse(section) }
+          [MainCPU.export(machine), CPU6809.export(machine), PETMem.export(machine),
+           CRTC.export(machine, reader(readers, "BL-CRTC"), reader(readers, "BL-VIDEO")),
+           PIAs.export("PIA1", machine.pia1, reader(readers, "BL-PIA1")),
+           PIAs.export("PIA2", machine.pia2, reader(readers, "BL-PIA2")), VIA.export(reader(readers, "BL-VIA")),
+           *Drive2031.export(machine, readers), *Drive8050.export(machine, readers)] +
+            PERIPHERALS.map { |name, major, minor, bytes| FieldWriter.new.bytes(bytes).section(name, major, minor) }
+        end
+
+        def reader(readers, name) = readers[name] || Keyed::Reader.missing(name)
+
+        # How the machine xpet saved was built: the model from PETMEM's
+        # board, the RAM, and on a CRTC board the editor's frame rate, and
+        # for an 8032's 50 Hz editor which one, from the CRTC's registers.
+        # xpet doesn't save the keyboard, the ROMs or an 8296's jumpers, so
+        # a discrete board is a 3032 with the graphics keyboard unless it is
+        # a 2001, each model has its own ROMs, and an 8296 none of its
+        # jumpers, as xpet's own has.
+        def setup(container)
+          memory = memory(container)
+          ram_kb = PETMem.ram_kb(memory)
+          name = model_name(memory)
+          profile = Badline::PET::Model.named(name)
+          unless Badline::PET::Model.ram_fits?(profile, ram_kb)
+            raise FormatError, "#{memory}: a #{name} with #{ram_kb}K of RAM, which badline doesn't build"
+          end
+
+          crtc = container[CRTC::NAME]
+          crtc = nil unless crtc.nil? || CRTC.reads?(crtc)
+          refresh_hz = refresh_hz(crtc, profile)
+          profile = Badline::PET::Model.upgraded(profile, nil, editor(crtc, profile, refresh_hz))
+          PETSetup.new(model: name, ram_kb:, refresh_hz:, basic: profile.basic, editor: profile.editor(refresh_hz),
+                       kernal: profile.kernal, characters: profile.characters, jumpers: "")
+        end
+
+        def memory(container)
+          section = container[PETMem::NAME]
+          raise FormatError, "the snapshot has no #{PETMem::NAME} module" if section.nil?
+          raise FormatError, "#{section}: badline doesn't read this version" unless PETMem.reads?(section)
+
+          section
+        end
+
+        def model_name(memory)
+          board = PETMem.board_of(memory)
+          return PETMem.pet2001?(memory) ? "2001" : "3032" if board == PETMem::DISCRETE
+
+          name = MODELS[board]
+          return name unless name.nil?
+
+          what = board == PETMem::SUPERPET ? "a SuperPET" : "board #{board}"
+          raise FormatError, "#{memory}: #{what}, which badline doesn't build"
+        end
+
+        # The editor's frame rate, from the cycles the CRTC's registers set
+        # up a frame.
+        def refresh_hz(crtc, profile)
+          return 60 unless profile.crtc?
+          return 50 if crtc.nil?
+
+          registers = CRTC.registers(crtc)
+          (registers[0] + 1) * CRTC.frame_lines(registers) > SIXTY_HZ_FRAME ? 50 : 60
+        end
+
+        # The editor by ROMSets' name where the model's own doesn't set up
+        # the CRTC's frame, or nil.
+        def editor(crtc, profile, refresh_hz)
+          return nil if crtc.nil? || refresh_hz != 50 || profile.video != :crtc80
+
+          CRTC.registers(crtc)[0] + 1 == EDITOR_0283_LINE ? "4-80-b-50hz-0283" : nil
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/vice/pet_cpu.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Vice
+      module PET
+        # The 6502 as xpet 3.10 saves it, MAINCPU 1.3: the clock, the
+        # registers, the last opcode and two words after it, then the IRQ
+        # and NMI bookkeeping: five clocks, the IRQ and NMI source counts and
+        # the pending interrupts. xpet's MAINCPU has no BA line to save.
+        #
+        # Written: the clock and the registers, which between instructions
+        # are the whole CPU, with the IRQ sources that pull the line and a
+        # pending IRQ. VICE's interrupt clocks are written as long past.
+        #
+        # Read: the clock and the registers. The CPU starts on an
+        # instruction boundary, as xpet's snapshot is taken on one.
+        module MainCPU
+          NAME = "MAINCPU"
+          MAJOR = 1
+          MINOR = 3
+          IK_IRQ = 0x02
+
+          module_function
+
+          def reads?(section) = section.major == MAJOR && section.minor == MINOR
+
+          def export(machine) = write(machine, [machine.pia1.irq?, machine.pia2.irq?, machine.via.irq?].count(true))
+
+          # The module for `machine`, whose CPU's IRQ line `irqs` sources
+          # pull.
+          def write(machine, irqs)
+            cpu = machine.cpu
+            fields = FieldWriter.new.qword(machine.cycles)
+            [cpu.a, cpu.x, cpu.y, cpu.stack_pointer].each { |register| fields.byte(register) }
+            fields.word(cpu.program_counter).byte(cpu.p)
+            fields.dword(0).dword(0).dword(0)
+            5.times { fields.qword(0) }
+            fields.dword(irqs).dword(0).dword(irqs.positive? ? IK_IRQ : 0)
+            fields.section(NAME, MAJOR, MINOR)
+          end
+
+          # The clock, the registers by their BL-CPU keys, in a keyed
+          # module's writer.
+          def import(section, out)
+            fields = FieldReader.new(section)
+            clock = fields.qword
+            out.int("a", fields.byte).int("x", fields.byte).int("y", fields.byte).int("sp", fields.byte)
+            out.int("pc", fields.word).int("p", fields.byte).int("cycles", clock)
+            clock
+          end
+        end
+
+        # The SuperPET's 6809, CPU6809 1.1, which xpet saves on every model
+        # and won't load a snapshot without: the clock and the registers as
+        # an xpet with no SuperPET board leaves them. badline doesn't read
+        # it.
+        module CPU6809
+          NAME = "CPU6809"
+
+          module_function
+
+          def export(machine)
+            FieldWriter.new.qword(machine.cycles).zeros(11).byte(0x04).zeros(7).section(NAME, 1, 1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/vice/pet_crtc.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Vice
+      module PET
+        # CRTC 1.2, which xpet saves on every model, the discrete boards'
+        # video too, as a 6545 with the registers fixed: the board's screen
+        # settings, the registers, the one selected, the beam's character,
+        # row and line in the row, whether the frame is in its vertical
+        # adjust, the row's start in screen RAM, the lines of vertical sync
+        # left, whether the rows show, the picture's size, the lines in the
+        # frame and the line in it, then xpet's picture.
+        #
+        # Written: the registers and the beam as badline's CRTC, or its
+        # discrete video, has them. The picture is left blank, as xpet
+        # paints it again.
+        #
+        # Read: the registers and the beam, with what follows from them: the
+        # memory address, the characters since horizontal sync and whether
+        # the character shows. The picture starts again with the next
+        # frame.
+        module CRTC
+          NAME = "CRTC"
+          MAJOR = 1
+          MINOR = 2
+          # The registers xpet saves, two more than badline's CRTC has.
+          REGISTERS = 20
+          # Where the selected register is in the module, and the beam after
+          # it.
+          SELECTED = 0x23
+          # The board's screen settings xpet saves ahead of the registers:
+          # the screen RAM's masks and the bits of the frame's start address
+          # it latches (BOARD_ATTRIBUTES), then the bytes a character reads
+          # and whether the board is a 2001's.
+          SETTINGS = [0xff, 0x03, 0x00, 0x20, 0x00, 0x20, 0x00, 0x10, 0xff, 0x1f].freeze
+          # The 8296's, whose screen RAM spans 4K.
+          SETTINGS_8296 = [0xff, 0x0f, 0x00, 0x20, 0x00, 0x20, 0xff, 0x0f, 0xff, 0x1f].freeze
+          # The 2001's and 3000 series' video as xpet's CRTC runs it: 64
+          # cycles a line, 32 rows of 8 lines and 4 more, the first 25 rows
+          # shown.
+          DISCRETE_REGISTERS = [0x3f, 0x28, 0x32, 0x08, 0x1f, 0x04, 0x19, 0x1d, 0x00, 0x07, 0x00, 0x00, 0x10, 0x00,
+                                0x00, 0x00, 0x00, 0x00, 0x00, 0x00].freeze
+          DISCRETE_HEIGHT = 216
+          DISCRETE_LINE = 64
+          DISCRETE_FRAME = DISCRETE_LINE * 260
+          # How many cycles badline's beam runs ahead of xpet's, where both
+          # drop the vertical drive line on the same cycle.
+          DISCRETE_LEAD = 20
+          CRTC_LEAD = -3
+          HEIGHT = 272
+          # A byte xpet writes after the picture's size.
+          AFTER_SIZE = 0x20
+          # The memory address's bits that pick a byte of screen RAM.
+          SCREEN_BITS = 0x0fff
+          # The bits above them, which the boards decode as attributes.
+          HIGH_BITS = 0x3000
+
+          # Where the beam is, in xpet's terms: the character, the row and
+          # its line, the lines of vertical sync left, whether the rows show,
+          # the row's start address and the line in the frame.
+          Beam = Data.define(:column, :row, :raster, :vsync, :shown, :start, :frame_line)
+
+          module_function
+
+          def reads?(section) = section.major == MAJOR && section.minor == MINOR
+
+          def width(model) = model.video == :crtc80 ? 704 : 384
+
+          def height(model) = model.video == :discrete ? DISCRETE_HEIGHT : HEIGHT
+
+          def columns(model) = model.video == :crtc80 ? 2 : 1
+
+          # The frame's start address bits xpet latches on the board: MA12,
+          # which inverts the 80-column boards' picture.
+          def attributes(model) = model.video == :crtc80 ? 0x1000 : 0
+
+          def export(machine, crtc_input, video_input)
+            model = machine.model
+            discrete = model.video == :discrete
+            registers = discrete ? DISCRETE_REGISTERS : crtc_registers(crtc_input)
+            beam = if discrete
+                     discrete_beam(video_input)
+                   else
+                     crtc_beam(run_on(fresh_crtc(machine), crtc_input, -CRTC_LEAD % frame_cycles(registers)),
+                               registers)
+                   end
+            fields = FieldWriter.new.bytes(model.cbm8296? ? SETTINGS_8296 : SETTINGS).word(attributes(model))
+            fields.byte(0).byte(columns(model))
+            fields.byte(model.basic1? ? 1 : 0).bytes(registers).byte(discrete ? 0 : crtc_input.int("selected", 0))
+            beam_fields(fields, beam, registers, model)
+            picture(fields, model)
+            fields.section(NAME, MAJOR, MINOR)
+          end
+
+          def crtc_registers(input)
+            registers = input.bytes("registers", "".b).bytes
+            Array.new(REGISTERS) { |index| registers[index] || 0 }
+          end
+
+          def beam_fields(fields, beam, registers, model)
+            fields.byte(beam.column).byte(beam.row).byte(beam.raster).zeros(2).flag(beam.raster.zero?)
+            fields.word(beam.start & attributes(model)).word((beam.start & SCREEN_BITS) * columns(model))
+            fields.byte(beam.vsync).byte(0).flag(beam.shown)
+            fields.word(width(model)).word(height(model)).byte(AFTER_SIZE).zeros(3)
+            shown = registers[6] * (registers[9] + 1)
+            fields.byte([(height(model) - shown) / 2, 0].max).byte(0)
+            fields.word(frame_lines(registers)).word(beam.frame_line).byte(0)
+          end
+
+          # Blank, as xpet paints it again: the line it draws, its size twice
+          # over, and four lines more than it shows.
+          def picture(fields, model)
+            width = width(model)
+            height = height(model)
+            fields.dword(0).dword(width).dword(height).dword(width).zeros(width * (height + 4))
+          end
+
+          def frame_lines(registers) = ((registers[4] + 1) * (registers[9] + 1)) + registers[5]
+
+          def frame_cycles(registers) = (registers[0] + 1) * frame_lines(registers)
+
+          # The CRTC of a machine built as `machine` was, at power-on.
+          def fresh_crtc(machine) = PETSetup.of(machine).build.crtc
+
+          # The BL-CRTC fields of `crtc`, a CRTC of its own, loaded with those
+          # in `input` and run `cycles` cycles.
+          def run_on(crtc, input, cycles)
+            crtc.load_fields(input)
+            cycles.times { crtc.cycle! }
+            Keyed::Reader.parse(Keyed.section("BL-CRTC") { |out| crtc.save_fields(out) })
+          end
+
+          # Writes the BL-CRTC fields `input` holds to `out`.
+          def copy(input, out)
+            out.bytes("registers", input.bytes("registers", "".b)).int("selected", input.int("selected", 0))
+            %w[column since_hsync line row vsync_lines row_start address].each { |key| out.int(key, input.int(key, 0)) }
+            %w[adjusting row_display column_display].each { |key| out.bool(key, input.bool(key, false)) }
+          end
+
+          # Both move a row's start on at R1 of its last line.
+          def crtc_beam(input, registers)
+            column = input.int("column", 0)
+            row = input.int("row", 0)
+            line = input.int("line", 0)
+            adjusting = input.bool("adjusting", false)
+            start = input.int("row_start", 0)
+            rows = registers[4] + 1
+            lines = registers[9] + 1
+            Beam.new(column:, row: adjusting ? rows : row, raster: adjusting ? 0 : line,
+                     vsync: input.int("vsync_lines", 0), shown: input.bool("row_display", true), start:,
+                     frame_line: adjusting ? (rows * lines) + line : (row * lines) + line)
+          end
+
+          # Whether the row's start has moved on by `column` of `line`.
+          def moved?(line, column, registers)
+            line > registers[9] || (line == registers[9] && column > registers[1])
+          end
+
+          # The discrete video's line in the frame, in xpet's fixed rows: the
+          # rows show until line 200, vertical sync runs from row 29 for 16
+          # lines, and the 4 lines past row 31 are the vertical adjust.
+          def discrete_beam(input)
+            cycle = ((input.int("line", 0) * DISCRETE_LINE) + input.int("column", 0) - DISCRETE_LEAD) % DISCRETE_FRAME
+            line = cycle / DISCRETE_LINE
+            row = [line >> 3, 32].min
+            adjusting = row == 32
+            raster = adjusting ? 0 : line & 0x07
+            column = cycle % DISCRETE_LINE
+            sync = line - (DISCRETE_REGISTERS[7] * 8)
+            moved = !adjusting && moved?(raster, column, DISCRETE_REGISTERS)
+            Beam.new(column:, row:, raster:, vsync: sync.between?(0, 15) ? 16 - sync : 0, shown: line < 200,
+                     start: 0x1000 + ((moved ? row + 1 : row) * 40), frame_line: line)
+          end
+
+          # The beam the module holds, with the row's start as the module
+          # has it: the attribute bits latched in the high word and the
+          # offset into screen RAM, in bytes, in the low.
+          def beam(section)
+            fields = FieldReader.new(section).skip(SELECTED + 1)
+            column, row, raster = fields.bytes(3)
+            fields.skip(3)
+            latched = fields.word
+            offset = fields.word
+            vsync = fields.byte
+            fields.skip(1)
+            shown = fields.flag?
+            fields.skip(12)
+            Beam.new(column:, row:, raster:, vsync:, shown:, start: (latched << 16) | offset,
+                     frame_line: fields.word)
+          end
+
+          def registers(section) = FieldReader.new(section).skip(SETTINGS.length + 5).bytes(REGISTERS)
+
+          def selected(section) = FieldReader.new(section).skip(SELECTED).byte
+
+          # How many cycles into its line xpet's beam is. A beam whose line
+          # has moved on a cycle before it starts holds -1.
+          def column_of(section)
+            column = beam(section).column
+            column < 0x80 ? column : column - 0x100
+          end
+
+          # The CRTC's fields by their BL-CRTC keys at the start of the line
+          # the module's beam is in (#column_of), in a keyed module's writer,
+          # for a board that reads `columns` bytes a character with
+          # `attributes` latched from the frame's start.
+          def import(section, out, columns, attributes)
+            registers = registers(section)
+            beam = beam(section)
+            rows = registers[4] + 1
+            adjusting = beam.row >= rows
+            line = adjusting ? beam.frame_line - (rows * (registers[9] + 1)) : beam.raster
+            start = start_address(beam.start, registers, columns, attributes)
+            start = (start - registers[1]) & 0x3fff if !adjusting && moved?(line, column_of(section), registers)
+            out.bytes("registers", registers.first(Chips::CRTC::MASKS.length)).int("selected", selected(section) & 0x1f)
+            out.int("column", 0).int("line", [line, 0].max).int("row", adjusting ? rows - 1 : beam.row)
+            out.int("since_hsync", registers[0] + 1 - registers[2]).int("vsync_lines", beam.vsync)
+            out.bool("adjusting", adjusting).bool("row_display", beam.shown).bool("column_display", true)
+            out.int("row_start", start).int("address", start)
+          end
+
+          # The row's start address from the module's (#beam): the bits
+          # that pick screen RAM from its offset, the attribute bits the
+          # board latches from its high word, and those above from R12.
+          def start_address(start, registers, columns, attributes)
+            high = (registers[12] << 8) & HIGH_BITS & ~attributes
+            high | ((start >> 16) & attributes) | (((start & 0xffff) / columns) & SCREEN_BITS)
+          end
+
+          # The discrete video's fields by their BL-VIDEO keys, in a keyed
+          # module's writer.
+          def import_discrete(section, out)
+            cycle = ((beam(section).frame_line * DISCRETE_LINE) + column_of(section) + DISCRETE_LEAD) % DISCRETE_FRAME
+            out.int("column", cycle % DISCRETE_LINE).int("line", cycle / DISCRETE_LINE)
+          end
+        end
+      end
+    end
+  end
+end