badline 0.12.1 → 0.14.0

data/lib/badline/c64/cartridge.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "badline/c64/cartridge/bank"
+require "badline/c64/cartridge/flash"
+require "badline/c64/cartridge/standard"
+require "badline/c64/cartridge/simons_basic"
+require "badline/c64/cartridge/ocean"
+require "badline/c64/cartridge/fun_play"
+require "badline/c64/cartridge/super_games"
+require "badline/c64/cartridge/epyx_fastload"
+require "badline/c64/cartridge/westermann"
+require "badline/c64/cartridge/rex_utility"
+require "badline/c64/cartridge/game_system"
+require "badline/c64/cartridge/dinamic"
+require "badline/c64/cartridge/zaxxon"
+require "badline/c64/cartridge/magic_desk"
+require "badline/c64/cartridge/comal80"
+require "badline/c64/cartridge/easy_flash"
+require "badline/c64/cartridge/mach5"
+require "badline/c64/cartridge/pagefox"
+require "badline/c64/cartridge/rgcd"
+require "badline/c64/cartridge/g_mod2"
+require "badline/c64/cartridge/freezer"
+require "badline/c64/cartridge/action_replay"
+require "badline/c64/cartridge/atomic_power"
+require "badline/c64/cartridge/final_cartridge3"
+require "badline/c64/cartridge/retro_replay"
+require "badline/c64/cartridge/kcs_power"
+require "badline/c64/cartridge/geo_ram"
+
+module Badline
+  class C64
+    class Cartridge
+      class UnsupportedTypeError < StandardError; end
+      ROMH_START = 0xa000
+      BANK_SIZE = 0x2000
+
+      HARDWARE_TYPES = {
+        0 => Standard, 1 => ActionReplay, 2 => KCSPower, 3 => FinalCartridge3,
+        4 => SimonsBasic, 5 => Ocean, 7 => FunPlay, 8 => SuperGames,
+        9 => AtomicPower, 10 => EpyxFastload, 11 => Westermann,
+        12 => RexUtility, 15 => GameSystem, 17 => Dinamic, 18 => Zaxxon,
+        19 => MagicDesk, 21 => Comal80, 32 => EasyFlash, 36 => RetroReplay,
+        51 => Mach5, 53 => Pagefox, 57 => RGCD, 60 => GMod2
+      }.freeze
+
+      # The EXROM and GAME line levels of each memory configuration. The lines
+      # are active low.
+      MODES = {
+        rom8k: [0, 1].freeze, rom16k: [0, 0].freeze,
+        ultimax: [1, 0].freeze, off: [1, 1].freeze
+      }.freeze
+
+      attr_reader :name, :exrom, :game, :roml, :romh
+
+      # A callable returning the current cycle, for mappers with timed state.
+      attr_writer :clock
+
+      class << self
+        # Options set the cartridge's jumpers, for the mappers that have them.
+        def from_file(path, **)
+          from_crt(Storage::CRTFile.new(path), **)
+        end
+
+        def from_crt(crt, **)
+          mapper_for(crt).new(crt, **)
+        end
+
+        def mapper_for(crt)
+          HARDWARE_TYPES.fetch(crt.hardware_type) do
+            raise UnsupportedTypeError,
+                  "Unsupported cartridge hardware type #{crt.hardware_type}"
+          end
+        end
+      end
+
+      # Keeps the image it was built from, so a snapshot's machine can build
+      # the same cartridge before the snapshot's state goes into it.
+      def initialize(crt)
+        @crt = crt
+        @name = crt.name
+        @exrom = crt.exrom
+        @game = crt.game
+        @roml = @romh = nil
+        @banks = nil
+        @on_change = nil
+        @on_nmi_change = nil
+        @nmi = false
+        @open_bus = nil
+        @clock = nil
+        install_chips(crt.chips)
+      end
+
+      def on_change(&block)
+        @on_change = block
+      end
+
+      # Called with the level of the cartridge's pull on the NMI line when it
+      # changes. The line is wired-OR with CIA 2's.
+      def on_nmi_change(&block)
+        @on_nmi_change = block
+      end
+
+      def nmi?
+        @nmi
+      end
+
+      # The address bus hands over the C64's RAM, for mappers that write
+      # through to it, and the open bus, for I/O reads the cartridge doesn't
+      # drive.
+      def connect(ram:, open_bus:)
+        @ram = ram
+        @open_bus = open_bus
+      end
+
+      def ultimax?
+        @game.zero? && @exrom == 1
+      end
+
+      # Whether the first half of the cycle, where the VIC does most of its
+      # fetching, sees Ultimax mode. Some cartridges drive GAME and EXROM
+      # differently in the two halves; #ultimax? is the second, the CPU's.
+      def phi1_ultimax?
+        ultimax?
+      end
+
+      # The I/O pages ($de, $df) whose reads the mapper drives. Reads of the
+      # others are open bus.
+      def readable_io_pages
+        []
+      end
+
+      def poke(_addr, _value); end
+
+      # A window taking writes to $E000-$FFFF while reads there see the C64's
+      # memory, for a cartridge that asserts Ultimax on write cycles only.
+      def romh_writes; end
+
+      # A window at $A000-$BFFF in Ultimax mode, where the C64 maps nothing.
+      def ultimax_a000; end
+
+      # The RES line on the expansion port.
+      def reset; end
+
+      # Whether the cartridge has a freeze button.
+      def freezer? = false
+
+      # The freeze button, which cartridges without one ignore.
+      def press_button; end
+
+      def release_button; end
+
+      private
+
+      # The banks and views ROML and ROMH can point at, which a snapshot
+      # names them by: the mapper's banks, or nothing for a mapper whose
+      # windows stay where install_chips put them.
+      def windows
+        [*@banks, EMPTY_BANK] if @banks
+      end
+
+      def window_index(window, windows)
+        return -1 if window.nil?
+
+        windows.index { |candidate| candidate.equal?(window) } ||
+          raise(ArgumentError, "#{self.class.name}: a window that isn't among its banks")
+      end
+
+      def nmi=(level)
+        return if @nmi == level
+
+        @nmi = level
+        @on_nmi_change&.call(level)
+      end
+
+      def changed!
+        @on_change&.call
+      end
+
+      def mode=(mode)
+        @exrom, @game = MODES.fetch(mode)
+      end
+
+      # Sets the lines and tells the machine to map the cartridge again.
+      def select_mode(mode)
+        self.mode = mode
+        changed!
+      end
+
+      def open_bus(addr)
+        @open_bus ? @open_bus.peek(addr) : 0xff
+      end
+
+      def install_chips(_chips)
+        raise NotImplementedError
+      end
+
+      def rom_bank(data)
+        Bank.new(data)
+      end
+
+      # A bank the image leaves out reads as erased ROM.
+      def bank(banks, number)
+        banks[number] || EMPTY_BANK
+      end
+
+      # The bank register bits a ROM decodes. The ROM holds the highest bank
+      # in the image, and has address lines for the power of two that covers
+      # it; the register bits above those lines are ignored.
+      def bank_mask(banks)
+        (1 << (banks.length - 1).bit_length) - 1
+      end
+
+      # Sorts the CHIP packets into ROML and ROMH banks by load address. A 16K
+      # chip at $8000 spans both.
+      def banks_from(chips)
+        roml = []
+        romh = []
+        chips.each do |chip|
+          if chip.address >= ROMH_START
+            romh[chip.bank] = rom_bank(chip.data)
+          else
+            roml[chip.bank] = rom_bank(chip.data[0, BANK_SIZE])
+            romh[chip.bank] = rom_bank(chip.data[BANK_SIZE, BANK_SIZE]) if chip.data.length > BANK_SIZE
+          end
+        end
+        [roml, romh]
+      end
+    end
+  end
+end
+require "badline/c64/cartridge/keyed_state"

data/lib/badline/c64/color_memory.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    # Colour RAM is four bits wide. A CPU read takes the upper nibble off the
+    # open data bus, which still holds the byte the VIC fetched in phi1.
+    class ColorMemory < Memory
+      def initialize(vic, start: 0xd800, length: 2**10)
+        super(start:, length:)
+        @vic = vic
+      end
+
+      def peek(addr)
+        (@vic.phi1_data & 0xf0) | @storage[offset_of(addr)]
+      end
+
+      def poke(addr, value)
+        super(addr, value & 0x0f)
+      end
+
+      # The four bits the cell stores, as the VIC's c-access sees them.
+      def nibble(addr)
+        @storage[offset_of(addr)]
+      end
+    end
+  end
+end

data/lib/badline/{computer → c64}/common.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Badline
-  class Computer
+  class C64
     # What the C128 does as the C64 does: the NMI line, a PRG put into RAM
-    # and the region's timing. Computer and C128 each include it.
+    # and the region's timing. C64 and C128 each include it.
     module Common
       # The clock, the raster and the crop of the machine's region, a pixel
       # to a window pixel.

data/lib/badline/{computer → c64}/kernal_traps.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Badline
-  class Computer
+  class C64
     # The disk device 8 serves through the LOAD, SAVE and serial traps, and
-    # CHROUT capture, on the KERNAL the machine runs. Computer, Vic20 and
+    # CHROUT capture, on the KERNAL the machine runs. C64, Vic20 and
     # C128 each include it and answer two private methods: #trap_layout,
     # the KernalTrap::Layout of that KERNAL, and #trap_bus, the bus the
     # traps read and write through.
@@ -13,9 +13,9 @@ module Badline
       # drive reset clears, and its status. The traps go on the KERNAL the
       # machine runs (#trap_layout).
       def mount(storage)
-        return @drive.insert(storage) if @drive
+        return @dos.insert(storage) if @dos
 
-        @drive = KernalTrap::Drive.new(storage)
+        @dos = KernalTrap::DOS.new(storage)
         install_kernal_traps(trap_layout)
       end
 
@@ -23,35 +23,60 @@ module Badline
       # serial traps, so the KERNAL's routines go out over the serial bus.
       # Mounting again starts a new drive, with its RAM cleared.
       def unmount
-        return unless @drive
+        return unless @dos
 
         remove_kernal_traps
-        @drive = nil
+        @dos = nil
       end
 
       # Whether device 8 serves a disk or directory through the traps.
-      def mounted? = !@drive.nil?
+      def mounted? = !@dos.nil?
 
       # The path of the disk or directory device 8 serves through the
       # traps, or an empty one.
-      def mounted_path = @drive.nil? ? "" : @drive.path
+      def mounted_path = @dos.nil? ? "" : @dos.path
 
-      # Records what the KERNAL prints through CHROUT (ChroutTrap).
+      # Records what the KERNAL prints through CHROUT (KernalTrap::Chrout).
       def capture_output
-        @capture_output ||= ChroutTrap.new(cpu:, bus: trap_bus, layout: trap_layout).tap do |trap|
-          cpu.install_trap(ChroutTrap::ADDRESS) { trap.call }
+        @capture_output ||= KernalTrap::Chrout.new(cpu:, bus: trap_bus, layout: trap_layout).tap do |trap|
+          cpu.install_trap(KernalTrap::Chrout::ADDRESS) { trap.call }
         end
       end
 
+      # Device 8 through the KERNAL traps in a keyed snapshot module
+      # (BL-TRAPDOS): the storage under storage.*, the DOS, the serial
+      # trap under serial.* and the SAVE trap under save.*. 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)
+        @serial_trap&.save_fields(out, "serial.")
+        @save_trap&.save_fields(out, "save.")
+      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)
+        @serial_trap&.load_fields(input, "serial.")
+        @save_trap&.load_fields(input, "save.")
+      end
+
       private
 
       def install_kernal_traps(layout)
         @trap_layout = layout
-        load_trap = KernalTrap::Load.new(cpu:, bus: trap_bus, layout:, drive: @drive)
+        load_trap = KernalTrap::Load.new(cpu:, bus: trap_bus, layout:, dos: @dos)
         cpu.install_trap(layout.load) { load_trap.call }
-        @serial_trap = KernalTrap::Serial.new(cpu:, bus: trap_bus, layout:, drive: @drive,
+        @serial_trap = KernalTrap::Serial.new(cpu:, bus: trap_bus, layout:, dos: @dos,
                                               device: serial_trap_device).install
-        save_trap = @save_trap = KernalTrap::Save.new(cpu:, bus: trap_bus, layout:, drive: @drive)
+        save_trap = @save_trap = KernalTrap::Save.new(cpu:, bus: trap_bus, layout:, dos: @dos)
         cpu.install_trap(layout.save) { save_trap.call }
       end
 
@@ -62,28 +87,6 @@ module Badline
         @serial_trap = nil
         @save_trap = nil
       end
-
-      # The disk device 8 serves through the traps, with the traps' own
-      # state: open channels, the drive's status and RAM, a SAVE under way.
-      def save_trap_drive(out)
-        out.boolean(!@drive.nil?)
-        return unless @drive
-
-        @drive.save_state(out)
-        @serial_trap.save_state(out)
-        @save_trap.save_state(out)
-      end
-
-      def load_trap_drive(input)
-        return unmount unless input.boolean?
-
-        storage = Storage.reopen(input)
-        unmount
-        mount(storage)
-        @drive.load_state(input)
-        @serial_trap.load_state(input)
-        @save_trap.load_state(input)
-      end
     end
   end
 end

data/lib/badline/c64/keyed_modules.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    # The whole machine as keyed snapshot modules (Snapshot::Keyed), in the
+    # order a load applies them: BL-MACHINE with the setup, the memories,
+    # the cartridge, the CPU with its port, the chips, an REU, the
+    # datasette, device 8 through the traps and the true drives. A load
+    # reads the CPU's port before the chips, so the banks are mapped as the
+    # chips load, and the CPU's own fields after them. What each unit works
+    # out again from its fields comes last, once every unit is loaded.
+    module KeyedModules
+      def save_modules
+        bus = address_bus
+        sections = [Snapshot::Keyed.section("BL-MACHINE") { |out| save_machine_fields(out) },
+                    Snapshot::Keyed.section("BL-RAM") { |out| bus.ram.save_fields(out, "ram") }]
+        expansion = bus.ram_expansion
+        sections << Snapshot::Keyed.section("BL-RAMEXP") { |out| expansion.save_fields(out) } if expansion.type
+        sections << Snapshot::Keyed.section("BL-COLORRAM") { |out| bus.color_ram.save_fields(out, "ram") }
+        cartridge = bus.cartridge
+        sections << Snapshot::Keyed.section("BL-CART") { |out| cartridge.save_fields(out) } if cartridge
+        save_chip_modules(sections, bus)
+        reu = @reu
+        sections << Snapshot::Keyed.section("BL-REU") { |out| reu.save_fields(out) } if reu
+        sections << Snapshot::Keyed.section("BL-TAPE") { |out| bus.datasette.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-TRAPDOS") { |out| save_trap_dos_fields(out) } if mounted?
+        save_drive_modules(sections)
+      end
+
+      # Raises Snapshot::FormatError for the modules of a machine built
+      # another way.
+      def load_modules(modules)
+        machine = modules.machine
+        check_snapshot_setup(Snapshot::C64Setup.read_fields(machine))
+        load_machine_fields(machine)
+        bus = address_bus
+        bus.ram.load_fields(modules.required("BL-RAM"), "ram")
+        bus.ram_expansion.load_fields(modules.required("BL-RAMEXP")) if bus.ram_expansion.type
+        bus.color_ram.load_fields(modules.required("BL-COLORRAM"), "ram")
+        load_cartridge_module(modules.optional("BL-CART"))
+        cpu = modules.required("BL-CPU")
+        bus.load_port_fields(cpu)
+        bus.restored!
+        load_chip_modules(modules, cpu)
+        bus.datasette.load_fields(modules.required("BL-TAPE"))
+        load_trap_dos_module(modules)
+        load_drive_modules(modules)
+        modules_restored!
+        self
+      end
+
+      private
+
+      def save_chip_modules(sections, bus)
+        sections << Snapshot::Keyed.section("BL-CPU") do |out|
+          @cpu.save_fields(out)
+          bus.save_port_fields(out)
+        end
+        sections << Snapshot::Keyed.section("BL-VIC") { |out| @vic.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-CIA1") { |out| @cia1.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-CIA2") { |out| @cia2.save_fields(out) }
+        sections << Snapshot::Keyed.section("BL-SID") { |out| @sid.save_fields(out) }
+      end
+
+      def load_chip_modules(modules, cpu)
+        @vic.load_fields(modules.required("BL-VIC"))
+        @cia1.load_fields(modules.required("BL-CIA1"))
+        @cia2.load_fields(modules.required("BL-CIA2"))
+        @sid.load_fields(modules.required("BL-SID"))
+        @reu&.load_fields(modules.required("BL-REU"))
+        @cpu.load_fields(cpu)
+      end
+
+      # The cartridge comes back built afresh from the CRT image the module
+      # holds, before its state goes in. No module means no cartridge.
+      def load_cartridge_module(input)
+        if input
+          cartridge = Cartridge.from_fields(input)
+          connect_cartridge(cartridge)
+          cartridge.load_fields(input)
+        elsif address_bus.cartridge
+          address_bus.detach_cartridge
+        end
+      end
+
+      def load_trap_dos_module(modules)
+        input = modules.optional("BL-TRAPDOS")
+        input ? load_trap_dos_fields(input, detached: modules.detached?) : unmount
+      end
+
+      def modules_restored!
+        @cpu.restored!
+        @vic.restored!
+        @cia1.restored!
+        @cia2.restored!
+        @sid.restored!
+        @reu&.restored!
+        machine_restored!
+      end
+
+      def check_snapshot_setup(setup)
+        ours = Snapshot::C64Setup.of(address_bus)
+        return if setup == ours
+
+        raise Snapshot::FormatError, "the snapshot is of a machine with #{setup}, not #{ours}"
+      end
+    end
+
+    include KeyedModules
+  end
+end

data/lib/badline/c64/keyed_state.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    # The machine's own fields in a keyed snapshot module (Snapshot::Keyed,
+    # BL-MACHINE): the family, its setup by name, the cycle count, the NMI
+    # glue, the freezer's write count and the REU's hold on the bus, 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: they are the host's blocks, which a
+      # snapshot can't hold. Nil until the machine is restored.
+      attr_reader :init_handlers_lost
+
+      # Sets the machine's cycle count, for a snapshot from VICE, which
+      # counts from its own clock.
+      def resume_at(cycles)
+        @cycles = cycles
+      end
+
+      # Whether a snapshot saves now (Machine::Settling): the CPU between
+      # instructions or jammed, and no REU transfer under way.
+      def settled_for_snapshot? = (@cpu.boundary? || @cpu.jammed?) && !reu&.dma?
+
+      # The SID's deferred cycles and writes, run up to this cycle, and the
+      # VIC's sprite collisions latched up to the beam.
+      def settle_chips_for_snapshot
+        sid.catch_up!
+        @vic.fold_collisions!
+      end
+
+      def save_machine_fields(out)
+        out.text("family", "c64").text("written_by", VERSION)
+        Snapshot::C64Setup.of(address_bus).write_fields(out)
+        out.int("cycles", @cycles).bool("nmi_asserted", @nmi_asserted).bool("cartridge_nmi", @cartridge_nmi)
+        out.bool("restore_pulse", @restore_pulse).bool("freezing", @freezing).int("freeze_writes", @freeze_writes)
+        out.bool("dma", @dma)
+        pending = @pending_keys
+        out.ints("host.pending_keys", pending) if pending
+        out.int("host.init_pending", booting? ? @init_handlers.length : 0)
+      end
+
+      def load_machine_fields(input)
+        @cycles = input.int("cycles", @cycles)
+        @nmi_asserted = input.bool("nmi_asserted", @nmi_asserted)
+        @cartridge_nmi = input.bool("cartridge_nmi", @cartridge_nmi)
+        @restore_pulse = input.bool("restore_pulse", @restore_pulse)
+        @freezing = input.bool("freezing", @freezing)
+        @freeze_writes = input.int("freeze_writes", @freeze_writes)
+        @dma = input.bool("dma", @dma)
+        pending = input.ints("host.pending_keys", [])
+        @pending_keys = pending.empty? ? nil : pending.dup
+        @init_handlers_lost = [input.int("host.init_pending", 0) - @init_handlers.length, 0].max
+      end
+
+      # The REU's IRQ line and the serial bus's lines from CIA 2, once the
+      # chips are loaded.
+      def machine_restored!
+        @reu_irq = @reu.nil? ? false : @reu.irq?
+        push_serial_lines
+      end
+    end
+
+    include KeyedState
+  end
+end