badline 0.5.0 → 0.6.0

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Vice
+      # VIC-II 1.3 as x64sc writes it, and VIC-IISC 1.4, the same fields
+      # under a new name, as VICE's development versions write it: the model, the registers, the beam's
+      # line and cycle, the IRQ latch, the video counters and buffers, the
+      # light pen, the borders, colour RAM and each sprite's counters, then
+      # x64sc's pixel pipeline and its frame buffer.
+      #
+      # Written: what badline's VIC holds in VICE's terms. The pixel
+      # pipeline and frame buffer are left blank, as VICE repaints on
+      # loading.
+      #
+      # Read: the registers, colour RAM, the IRQ latch and collisions, the
+      # video counters and buffers and the sprite counters. The VIC is put
+      # at the start of the snapshot's line and clocked on its own to the
+      # snapshot's cycle, so its fetch and sprite state match the line, then
+      # takes the snapshot's counters. Its pixel pipeline starts empty, so
+      # the first pixels drawn may differ.
+      module VICII
+        NAME = "VIC-II"
+        TRUNK_NAME = "VIC-IISC"
+        MAJOR = 1
+        MINOR = 3
+        VERSIONS = ["VIC-II 1.3", "VIC-IISC 1.4"].freeze
+        MODELS = %i[mos6569 mos8565].freeze
+        FRAME_WIDTH = 384
+        FRAME_HEIGHT = 312
+        # The pixel pipeline x64sc keeps between cycles, in bytes.
+        PIPELINE = 16 + 32 + 6 + 32 + 8 + 3 + 24 + 0x2f + 2 + 4
+
+        module_function
+
+        def export(computer)
+          vic = computer.vic
+          fields = FieldWriter.new.byte(MODELS.index(vic.model)).bytes(vic.register_file)
+          beam(vic, fields)
+          counters(vic, fields)
+          borders(vic, fields)
+          fields.bytes(Array.new(0x400) { |offset| computer.address_bus.color_ram.nibble(0xd800 + offset) })
+          8.times { |n| sprite(vic, n, fields) }
+          pipeline(vic, fields)
+          fields.dword(vic.rasterline).dword(FRAME_WIDTH).dword(FRAME_HEIGHT).dword(FRAME_WIDTH)
+          fields.zeros(FRAME_WIDTH * (FRAME_HEIGHT + 4))
+          fields.section(NAME, MAJOR, MINOR)
+        end
+
+        def beam(vic, fields)
+          registers = vic.registers
+          fields.dword(vic.column).dword(0).dword(vic.rasterline).byte(0)
+          fields.byte((registers[0x19] & 0x0f) | (vic.interrupted? ? 0x80 : 0))
+          fields.dword(registers.raster_target).flag(vic.latch_bits.anybits?(1))
+          [vic.character_buffer, vic.color_buffer].each { |buffer| fields.bytes(buffer.map { |value| value || 0 }) }
+          fields.byte(0).dword(0).zeros(65 * 8) # x64sc's graphics buffer and draw buffer
+        end
+
+        def counters(vic, fields)
+          registers = vic.registers
+          state = vic.display_state
+          fields.dword(registers.yscroll).flag(state.bad_lines_enabled)
+          fields.byte(registers[0x1e]).byte(registers[0x1f]).byte(0)
+          fields.dword(state.display? ? 0 : 1)
+          [state.vc_base, state.vc, state.rc, state.vmli].each { |counter| fields.dword(counter) }
+          fields.dword(state.bad_line_condition? ? 1 : 0)
+          fields.flag(vic.latch_bits.anybits?(2)).flag(vic.latch_bits.anybits?(4))
+          fields.dword(registers[0x13]).dword(registers[0x14]).dword(0).qword(0)
+          fields.byte(vic.fetch_d011).dword(0)
+          fields.dword(sprite_bits(vic, &:display_on)).byte(sprite_bits(vic, &:displaying?))
+        end
+
+        def borders(vic, fields)
+          fields.byte(0xff).byte(0).byte(0).byte(0) # last colour register and value, last bus bytes
+          vic.sequencer.borders.each { |flop| fields.flag(flop) }
+          fields.byte(0xff - (5 * vic.rasterline))
+        end
+
+        def sprite(vic, index, fields)
+          sprite = vic.sprites[index]
+          fields.dword(sprite.sr).byte(sprite.mc).byte(sprite.mcbase).byte(0).flag(sprite.exp_ff).dword(sprite.x)
+        end
+
+        # Blank but for the colour registers and the sprite priority,
+        # multicolour and expansion bits, which x64sc keeps copies of.
+        def pipeline(vic, fields)
+          file = vic.register_file
+          fields.zeros(16 + 32).bytes([file[0x1b], file[0x1c], file[0x1d], 0, 0, 0])
+          fields.zeros(32 + 8 + 3 + 24).bytes(file.first(0x2f)).byte(0xff).byte(0).dword(0)
+        end
+
+        def sprite_bits(vic)
+          8.times.sum { |n| yield(vic.sprites[n]) ? 1 << n : 0 }
+        end
+
+        # The module a snapshot has, under either name.
+        def find(container) = container[NAME] || container[TRUNK_NAME]
+
+        def reads?(section) = VERSIONS.include?(section.to_s)
+
+        # VICE's model numbers: the 6569, the 8565 and the 6569R1 run PAL;
+        # the 6567, 8562 and 6567R56A NTSC, and the 6572 PAL-N, which badline
+        # doesn't run yet.
+        def model(section)
+          number = FieldReader.new(section).byte
+          return :mos8565 if number == 1
+          return :mos6569 if [0, 2].include?(number)
+
+          raise FormatError, "#{section}: an NTSC or PAL-N VIC-II (VICE model #{number}), which badline doesn't run"
+        end
+
+        def import(section, computer)
+          snapshot = Import.new(FieldReader.new(section))
+          snapshot.apply(computer)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module Vice
+      module VICII
+        # Reads a VIC-II module and puts it into badline's VIC.
+        class Import
+          def initialize(fields)
+            @fields = fields
+            read_beam
+            read_counters
+            read_sprites
+          end
+
+          def apply(computer)
+            vic = computer.vic
+            computer.address_bus.color_ram.tap do |ram|
+              @color_ram.each_with_index { |value, offset| ram.poke(0xd800 + offset, value) }
+            end
+            load_registers(vic)
+            position(vic)
+            load_counters(vic)
+            load_sprites(vic)
+            vic.rebuild_sprite_ba
+          end
+
+          private
+
+          def read_beam
+            f = @fields
+            f.skip(1)
+            @registers = f.bytes(0x40)
+            @cycle = f.dword
+            f.skip(4)
+            @line = f.dword
+            f.skip(1)
+            @irq_status = f.byte
+            f.skip(4)
+            @raster_match = f.flag?
+            @character_buffer = f.bytes(40)
+            @color_buffer = f.bytes(40)
+            f.skip(1 + 4 + (65 * 8) + 4)
+          end
+
+          def read_counters
+            f = @fields
+            @bad_lines_enabled = f.flag?
+            @collisions = [f.byte, f.byte]
+            f.skip(1)
+            @display = f.dword.zero?
+            @vc_base, @vc, @rc, @vmli = Array.new(4) { f.dword }
+            f.skip(4)
+            @lp_low = f.flag?
+            @lp_triggered = f.flag?
+            f.skip(4 + 4 + 4 + 8)
+            @fetch_d011 = f.byte
+            f.skip(4)
+            @display_bits = f.dword
+            @dma_bits = f.byte
+            f.skip(4)
+            @vertical_border = f.flag?
+            @vertical_armed = f.flag?
+            @main_border = f.flag?
+            f.skip(1)
+            @color_ram = f.bytes(0x400)
+          end
+
+          # Each sprite's MC and MCBASE, and its expansion flip-flop as a bit.
+          def read_sprites
+            f = @fields
+            @sprite_mc = Array.new(8, 0)
+            @sprite_mcbase = Array.new(8, 0)
+            @sprite_exp_ff = 0
+            8.times do |n|
+              f.skip(4)
+              @sprite_mc[n] = f.byte
+              @sprite_mcbase[n] = f.byte
+              f.skip(1)
+              @sprite_exp_ff |= 1 << n if f.flag?
+              f.skip(4)
+            end
+          end
+
+          def load_registers(vic)
+            registers = vic.registers
+            bytes = registers.bytes
+            0x2f.times { |reg| bytes[reg] = @registers[reg] }
+            bytes[0x19] = @irq_status & 0x0f
+            bytes[0x1a] &= 0x0f
+            bytes[0x1e], bytes[0x1f] = @collisions
+            registers.update_irq_line
+          end
+
+          # Clocks the VIC alone from the start of the line to the cycle,
+          # so the line's fetches and sprite checks have run.
+          def position(vic)
+            vic.restore_line(@line)
+            load_display_state(vic)
+            @cycle.times { vic.cycle! }
+            registers = vic.registers
+            registers.bytes[0x19] = @irq_status & 0x0f
+            registers.bytes[0x1e], registers.bytes[0x1f] = @collisions
+            registers.update_irq_line
+          end
+
+          def load_display_state(vic)
+            vic.display_state.restore_counters([@vc_base, @vc, @rc, @vmli], @display, @bad_lines_enabled)
+          end
+
+          def load_counters(vic)
+            load_display_state(vic)
+            vic.character_buffer.replace(@character_buffer)
+            vic.color_buffer.replace(@color_buffer)
+            vic.restore_latches((@raster_match ? 1 : 0) | (@lp_low ? 2 : 0) | (@lp_triggered ? 4 : 0), @fetch_d011)
+            vic.sequencer.restore_borders(@vertical_border, @vertical_armed, @main_border)
+          end
+
+          def load_sprites(vic)
+            8.times do |n|
+              bit = 1 << n
+              vic.sprites[n].restore_counters(@sprite_mc[n], @sprite_mcbase[n], @sprite_exp_ff.anybits?(bit),
+                                              @dma_bits.anybits?(bit), @display_bits.anybits?(bit))
+            end
+            vic.sprites.update_any_dma
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/vice.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "badline/snapshot/vice/main_cpu"
+require "badline/snapshot/vice/c64_mem"
+require "badline/snapshot/vice/cias"
+require "badline/snapshot/vice/cias_import"
+require "badline/snapshot/vice/sid_registers"
+require "badline/snapshot/vice/sid_extended"
+require "badline/snapshot/vice/peripherals"
+require "badline/snapshot/vice/vicii"
+require "badline/snapshot/vice/vicii_import"
+require "badline/snapshot/vice/restore"
+
+module Badline
+  module Snapshot
+    # VICE's own modules for the chips both emulators model, written from
+    # and read into badline's machine. Each module's file says what maps
+    # and what is approximated. Reading a snapshot from VICE starts from a
+    # machine at power-on with nothing attached, and applies the modules it
+    # has, in the order x64sc writes them.
+    module Vice
+      # Cycles a copy of the machine may run to reach an instruction
+      # boundary: the longest instruction, stretched by the VIC's longest
+      # hold on the bus.
+      BOUNDARY_CYCLES = 100
+
+      # The modules a badline snapshot carries for VICE, in x64sc's order.
+      # They describe a copy of the machine restored from `state`, so saving
+      # leaves the machine itself alone. VICE saves between instructions,
+      # and resumes by fetching an opcode at the program counter, so when
+      # badline's CPU is inside an instruction the copy runs on to its end.
+      # The copy's SID catches up, so its registers and voices stand as of
+      # that cycle. badline writes no VICE module for an REU or an NTSC
+      # VIC-II yet, and fails for a machine with either.
+      def self.export(state)
+        check_exportable(Computer.setup(state))
+        machine = settled(state)
+        [MainCPU.export(machine), C64Mem.export(machine), Peripherals.cartridge_port, *CIAs.export(machine),
+         SIDRegisters.export(machine), SIDExtended.export(machine), Peripherals.drives, VICII.export(machine),
+         Peripherals.glue(machine), *Peripherals.rest]
+      end
+
+      def self.check_exportable(setup)
+        raise FormatError, "badline can't save an REU in VICE's terms yet, so can't save this machine" if setup.reu
+        return if setup.region == Region::PAL
+
+        raise FormatError, "badline can't save an NTSC VIC-II in VICE's terms yet, so can't save this machine"
+      end
+
+      # The copy is detached from the host's files (Snapshot::StateReader),
+      # so it reads none and its traps write none.
+      def self.settled(state)
+        copy = Computer.restored(state, detached: true)
+        BOUNDARY_CYCLES.times do
+          break if copy.cpu.boundary?
+
+          copy.cycle!
+        end
+        copy.sid.catch_up!
+        copy
+      end
+
+      # How the machine the snapshot was saved from was built. VICE doesn't
+      # save the CIA model; the C64C's 8565 VIC-II goes with the 6526A. An
+      # NTSC or PAL-N VIC-II fails, as badline runs PAL only.
+      def self.setup(container)
+        vic = VICII.find(container) ? VICII.model(VICII.find(container)) : :mos6569
+        sid = container[SIDRegisters::NAME] ? SIDRegisters.model(container[SIDRegisters::NAME]) : :mos6581
+        Setup.new(vic_model: vic, cia_model: vic == :mos8565 ? :mos6526a : :mos6526, sid_model: sid,
+                  region: Region::PAL, ram_expansion: nil, reu: nil)
+      end
+    end
+  end
+end

data/lib/badline/snapshot.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "zlib"
+require "badline/snapshot/state"
+require "badline/snapshot/setup"
+require "badline/snapshot/container"
+require "badline/snapshot/fields"
+require "badline/snapshot/machine_state"
+require "badline/snapshot/vice"
+require "badline/snapshot/image"
+
+module Badline
+  # Saves and restores the whole machine in VICE's .vsf snapshot format.
+  #
+  # A snapshot badline writes carries VICE's modules for what both
+  # emulators model, and a BADLINE module holding the State
+  # Computer#snapshot takes, with everything badline needs to carry on
+  # exactly where it stopped. VICE skips modules it doesn't know. Restoring
+  # a badline snapshot uses the BADLINE module alone; a snapshot from VICE
+  # restores through its modules, as far as they map, and reports the
+  # modules badline doesn't take.
+  module Snapshot
+    module_function
+
+    def save(computer, path)
+      File.binwrite(path, dump(computer))
+      path
+    end
+
+    def dump(computer)
+      state = computer.snapshot
+      Container.new(Vice.export(state) + [MachineState.section(state)]).to_s
+    end
+
+    def read(path) = Image.new(Container.parse(File.binread(path)))
+
+    # A new machine, built as the snapshot's was and restored from it.
+    # Yields a line for each thing it leaves out.
+    def load(path, &) = read(path).load(&)
+
+    # Restores `computer` from the snapshot at `path`, and returns what it
+    # applied and left out, yielding a line for each thing left out. A
+    # snapshot that fails leaves the machine as it was.
+    def restore(computer, path, &) = read(path).restore(computer, &)
+  end
+
+  class Computer
+    def save_snapshot(path) = Snapshot.save(self, path)
+
+    def restore_snapshot(path, &) = Snapshot.restore(self, path, &)
+  end
+end

data/lib/badline/storage/crt_file.rb

@@ -18,6 +18,11 @@ module Badline
       Image = Data.define(:hardware_type, :subtype, :exrom, :game, :name, :chips)
 
       def self.write(path, image)
+        File.binwrite(path, encode(image))
+      end
+
+      # The CRT file for an image: a parsed CRTFile or an Image.
+      def self.encode(image)
         header = SIGNATURE +
                  [0x40, 0x0100, image.hardware_type, image.exrom, image.game, image.subtype].pack("NnnCCCx5") +
                  [image.name.to_s.b[0, 32]].pack("a32")
@@ -25,11 +30,12 @@ module Badline
           ["CHIP", CHIP_HEADER_SIZE + chip.data.length, chip.chip_type, chip.bank, chip.address,
            chip.data.length].pack("a4Nn4") + chip.data.pack("C*")
         end
-        File.binwrite(path, header + packets.join)
+        header + packets.join
       end
 
-      def initialize(path)
-        parse(File.binread(path))
+      # `bytes` stands in for the file's contents.
+      def initialize(path = nil, bytes: nil)
+        parse(bytes || File.binread(path))
       end
 
       private

data/lib/badline/storage/d64_image.rb

@@ -15,6 +15,8 @@ module Badline
         count
       end
 
+      def storage_kind = D64
+
       def sectors_in(track)
         case track
         when 1..17 then 21

data/lib/badline/storage/d71_image.rb

@@ -5,6 +5,8 @@ module Badline
     class D71Image < D64Image
       ERROR_TABLES = { 351_062 => 1366 }.freeze
 
+      def storage_kind = D71
+
       private
 
       def error_tables = ERROR_TABLES

data/lib/badline/storage/d81_image.rb

@@ -5,6 +5,8 @@ module Badline
     class D81Image < DiskImage
       ERROR_TABLES = { 822_400 => 3200 }.freeze
 
+      def storage_kind = D81
+
       private
 
       def error_tables = ERROR_TABLES

data/lib/badline/storage/disk_image.rb

@@ -27,16 +27,25 @@ module Badline
       # the read, write and ID errors, 74 is DRIVE NOT READY.
       DOS_ERRORS = (2..11).to_h { |code| [code, code + 18] }.merge(15 => 74).freeze
 
-      def initialize(path, read_only: false)
+      # `bytes` stands in for the host file's contents, as a snapshot
+      # restores the image as it was.
+      def initialize(path, read_only: false, bytes: nil)
         @path = path
         @read_only = read_only
-        @bytes = File.binread(path).bytes
+        @bytes = bytes || File.binread(path).bytes
         @errors = split_error_table
       end
 
       # Whether the image was opened write-protected.
       def read_only? = @read_only
 
+      # What Storage.reopen needs to open the image again as it stands: its
+      # path, whether it is write-protected, and its bytes with the error
+      # table after them.
+      def save_setup(out)
+        out.int(storage_kind).string(::File.expand_path(@path)).boolean(@read_only).blob(@bytes + @errors.to_a)
+      end
+
       # A LOAD reads only PRG files. An OPEN names the type it wants, or
       # takes the first file of any type with a nil `type`.
       def read_file(name, type: :prg)

data/lib/badline/storage/host_directory.rb

@@ -14,6 +14,11 @@ module Badline
         @path = path
       end
 
+      # What Storage.reopen needs to open the directory again.
+      def save_setup(out)
+        out.int(HOST_DIRECTORY).string(::File.expand_path(@path))
+      end
+
       def read_file(name, **)
         entry = find(name)
         return unless entry

data/lib/badline/storage/t64.rb

@@ -13,10 +13,16 @@ module Badline
       ID = "T64".bytes.freeze
 
       def initialize(path)
+        @path = path
         @bytes = File.binread(path).bytes
         raise FormatError, "Missing T64 signature" unless @bytes[0, 3] == SIGNATURE
       end
 
+      # What Storage.reopen needs to open the archive again.
+      def save_setup(out)
+        out.int(T64_ARCHIVE).string(::File.expand_path(@path))
+      end
+
       def read_file(name, **)
         pattern = Storage.matcher(name)
         entry = entries.find { |e| pattern.match?(e[:name]) }

data/lib/badline/storage/tap.rb

@@ -13,9 +13,12 @@ module Badline
       HEADER_SIZE = 0x14
       OVERFLOW = 0x100 * 8
 
-      attr_reader :version
+      # The file it was read from, expanded, and the offset of the next
+      # pulse byte.
+      attr_reader :version, :path
 
       def initialize(path)
+        @path = File.expand_path(path)
         @bytes = File.binread(path).bytes
         raise FormatError, "Missing TAP signature" unless @bytes[0, SIGNATURE.length] == SIGNATURE
 
@@ -30,6 +33,12 @@ module Badline
         @pos = HEADER_SIZE
       end
 
+      def position = @pos
+
+      def position=(offset)
+        @pos = offset
+      end
+
       def end? = @pos >= @end
 
       # Cycles until the next falling edge, or nil once the tape has run out.

data/lib/badline/storage/unavailable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Badline
+  module Storage
+    # Stands in for a directory or archive a detached restore leaves out
+    # (Snapshot::StateReader): it finds no files and refuses every write
+    # as a write-protected disk does.
+    class Unavailable
+      def read_file(_name, **) = nil
+
+      def write_file(_name, _bytes, **)
+        raise WriteError, WriteError::WRITE_PROTECT_ON
+      end
+
+      def append_file(_name, _bytes, **)
+        raise WriteError, WriteError::WRITE_PROTECT_ON
+      end
+    end
+  end
+end

data/lib/badline/storage.rb

@@ -13,6 +13,7 @@ require "badline/storage/tap"
 require "badline/storage/crt_file"
 require "badline/storage/sid_file"
 require "badline/storage/song_lengths"
+require "badline/storage/unavailable"
 
 module Badline
   module Storage
@@ -33,7 +34,29 @@ module Badline
       end
     end
 
+    # The storage a snapshot's device 8 serves, by the number save_setup
+    # writes first.
+    HOST_DIRECTORY = 0
+    D64 = 1
+    D71 = 2
+    D81 = 3
+    T64_ARCHIVE = 4
+
     class << self
+      # Opens the storage a save_setup wrote: the same directory or archive
+      # by its path, or a disk image with the bytes it held, writes and
+      # all. A detached reader gets the image write-protected, and
+      # Unavailable for a directory or archive.
+      def reopen(input)
+        kind = input.int
+        path = input.string
+        case kind
+        when HOST_DIRECTORY then input.detached? ? Unavailable.new : HostDirectory.new(path)
+        when T64_ARCHIVE then input.detached? ? Unavailable.new : T64.new(path)
+        else reopen_image(kind, path, input)
+        end
+      end
+
       # Folds shifted PETSCII letters to their ASCII equivalents.
       def ascii(bytes)
         bytes.map { |b| b.between?(0xc1, 0xda) ? b - 0x80 : b }.pack("C*")
@@ -52,6 +75,17 @@ module Badline
         [base.to_s, FILE_TYPES[type.to_s.strip[0]&.upcase]]
       end
 
+      def reopen_image(kind, path, input)
+        read_only = input.boolean? || input.detached?
+        bytes = input.blob
+        case kind
+        when D64 then D64Image.new(path, read_only:, bytes:)
+        when D71 then D71Image.new(path, read_only:, bytes:)
+        when D81 then D81Image.new(path, read_only:, bytes:)
+        else raise Snapshot::FormatError, "unknown storage #{kind} in the state"
+        end
+      end
+
       # CBM-style filename pattern: "*" and "?" wildcards, case-insensitive.
       # The DOS stops comparing at the first "*", so whatever follows it
       # is ignored.

data/lib/badline/time_of_day.rb

@@ -7,6 +7,8 @@ module Badline
     CLOCK_HZ = Region::PAL.clock_hz
     MAINS_HZ = Region::PAL.mains_hz
 
+    FIELDS = %i[tenths seconds minutes hours].freeze
+
     def initialize(clock_hz: CLOCK_HZ, mains_hz: MAINS_HZ)
       # The accumulator advances mains_hz per cycle, so a TOD pin pulse has
       # arrived when it reaches clock_hz. Integer math keeps it exact.
@@ -28,6 +30,28 @@ module Badline
       @match = enabled ? 4 : 5
     end
 
+    # The clock and the alarm, field by field in FIELDS order, the latch,
+    # and the divider's phase.
+    def save_state(out)
+      out.int(@accumulator).int(@pulses).int(@match).boolean(@stopped).boolean(@alarm_pending)
+      FIELDS.each { |field| out.int(@clock[field]).int(@alarm[field]) }
+      out.boolean(!@latch.nil?)
+      FIELDS.each { |field| out.int(@latch[field]) } if @latch
+    end
+
+    def load_state(input)
+      @accumulator = input.int
+      @pulses = input.int
+      @match = input.int
+      @stopped = input.boolean?
+      @alarm_pending = input.boolean?
+      FIELDS.each do |field|
+        @clock[field] = input.int
+        @alarm[field] = input.int
+      end
+      @latch = input.boolean? ? FIELDS.to_h { |field| [field, input.int] } : nil
+    end
+
     def cycle!
       @accumulator += @mains_hz
       pulse! if @accumulator >= @cycles_per_pulse
@@ -51,6 +75,38 @@ module Badline
       @latch[:hours]
     end
 
+    attr_reader :pulses
+
+    # The clock as a read of the tenths would see it: the latch while the
+    # clock is latched. In FIELDS order.
+    def latched_fields = FIELDS.map { |field| (@latch || @clock)[field] }
+
+    # The cycles until the clock next steps a tenth, as VICE counts them.
+    def cycles_to_tenth
+      to_pulse = (@cycles_per_pulse - @accumulator + @mains_hz - 1) / @mains_hz
+      to_pulse + ([@match - @pulses, 0].max * @cycles_per_pulse / @mains_hz)
+    end
+
+    # Sets the clock, the alarm and the latch from VICE's fields, in FIELDS
+    # order, the latch nil while unlatched.
+    def restore_fields(clock, alarm, latch)
+      FIELDS.each_with_index do |field, i|
+        @clock[field] = clock[i]
+        @alarm[field] = alarm[i]
+      end
+      @latch = latch && FIELDS.each_with_index.to_h { |field, i| [field, latch[i]] }
+    end
+
+    # Sets whether the clock is stopped, the pulses counted towards the
+    # next tenth and the cycles until it, placing the divider so the tenth
+    # lands then.
+    def restore_divider(stopped, pulses, cycles_to_tenth)
+      @stopped = stopped
+      @pulses = pulses
+      to_pulse = cycles_to_tenth - ([@match - pulses, 0].max * @cycles_per_pulse / @mains_hz)
+      @accumulator = (@cycles_per_pulse - (to_pulse * @mains_hz)).clamp(0, @cycles_per_pulse - 1)
+    end
+
     # The clock and alarm as stored, read without latching the clock.
     def registers
       [@clock[:tenths], @clock[:seconds], @clock[:minutes], @clock[:hours],

data/lib/badline/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Badline
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end