badline 0.2.1 → 0.4.0

data/lib/badline/cartridge/geo_ram.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Badline
+  class Cartridge
+    # GEO-RAM: a RAM expansion on the expansion port, seen through a 256-byte
+    # window at $DE00-$DEFF. Two write-only registers pick the page the
+    # window shows: $DFFE selects one of the 64 pages of a 16K block, and
+    # $DFFF selects the block. As in VICE, the registers answer at every
+    # address from $DF80 up, even for $DFFE and odd for $DFFF, and the block
+    # number wraps at the number of blocks the RAM holds. Reads of I/O 2 are
+    # open bus. It leaves EXROM and GAME high, and RES clears both
+    # registers.
+    class GeoRAM < Cartridge
+      SIZES = [64, 128, 256, 512, 1024, 2048, 4096].freeze
+      BLOCK_SIZE = 0x4000
+      PAGE_MASK = 0x3f
+
+      attr_reader :size
+
+      # size is the RAM in kilobytes.
+      def initialize(size: 512)
+        raise ArgumentError, "Unsupported GEO-RAM size #{size}K" unless SIZES.include?(size)
+
+        @size = size
+        @block_mask = ((size * 1024) / BLOCK_SIZE) - 1
+        super(Storage::CRTFile::Image.new(hardware_type: nil, subtype: 0, exrom: 1, game: 1,
+                                          name: "GEO-RAM", chips: []))
+      end
+
+      def readable_io_pages
+        [0xde]
+      end
+
+      def peek(addr)
+        @ram_data[@window + (addr & 0xff)]
+      end
+
+      def poke(addr, value)
+        if addr <= 0xdeff
+          @ram_data[@window + (addr & 0xff)] = value
+        elsif addr >= 0xdf80
+          if addr.odd?
+            @block = value & @block_mask
+          else
+            @page = value & PAGE_MASK
+          end
+          @window = (@block * BLOCK_SIZE) + (@page * 0x100)
+        end
+      end
+
+      def reset
+        @block = @page = @window = 0
+      end
+
+      private
+
+      def install_chips(_chips)
+        @ram_data = Array.new(@size * 1024, 0)
+        reset
+      end
+    end
+  end
+end

data/lib/badline/cartridge/mach5.rb

@@ -26,7 +26,7 @@ module Badline
       private
 
       def install_chips(chips)
-        @roml = banks_from(chips).first.compact.first
+        @roml = banks_from(chips).first.compact.first || EMPTY_BANK
         reset
       end
     end

data/lib/badline/cartridge/magic_desk.rb

@@ -2,12 +2,15 @@
 
 module Badline
   class Cartridge
+    # Magic Desk: up to 128 8K banks. A write to I/O 1 selects the bank from
+    # bits 0-6, masked to the size of the ROM and at least four banks, and
+    # switches the ROM out with bit 7.
     class MagicDesk < Cartridge
       def poke(addr, value)
         return if addr > 0xdeff
 
         @exrom = value.anybits?(0x80) ? 1 : 0
-        @roml = @banks[(value & 0x3f) % @banks.length]
+        @roml = bank(@banks, value & @bank_mask)
         changed!
       end
 
@@ -19,6 +22,7 @@ module Badline
 
       def install_chips(chips)
         @banks = banks_from(chips).first
+        @bank_mask = (bank_mask(@banks) | 0x03) & 0x7f
         reset
       end
     end

data/lib/badline/cartridge/ocean.rb

@@ -2,11 +2,13 @@
 
 module Badline
   class Cartridge
+    # Ocean: up to 64 8K banks. A write to I/O 1 selects the bank from bits
+    # 0-5, masked to the size of the ROM.
     class Ocean < Cartridge
       def poke(addr, value)
         return if addr > 0xdeff
 
-        select_bank((value & 0x3f) % @banks.length)
+        select_bank(value & @bank_mask)
         changed!
       end
 
@@ -19,12 +21,13 @@ module Badline
 
       # In 16K mode the selected bank shows through ROMH as well.
       def select_bank(number)
-        @roml = @banks[number]
+        @roml = bank(@banks, number)
         @romh = @roml if game.zero?
       end
 
       def install_chips(chips)
         @banks = banks_from(chips).first
+        @bank_mask = bank_mask(@banks) & 0x3f
         reset
       end
     end

data/lib/badline/cartridge/rex_utility.rb

@@ -25,7 +25,7 @@ module Badline
       private
 
       def install_chips(chips)
-        @roml = banks_from(chips).first.compact.first
+        @roml = banks_from(chips).first.compact.first || EMPTY_BANK
         reset
       end
     end

data/lib/badline/cartridge/rgcd.rb

@@ -40,7 +40,7 @@ module Badline
 
       def install_chips(chips)
         @banks = banks_from(chips).first
-        @bank_mask = @hucky ? @banks.length - 1 : 0x07
+        @bank_mask = @hucky ? bank_mask(@banks) : 0x07
         reset
       end
     end

data/lib/badline/cartridge/simons_basic.rb

@@ -31,8 +31,8 @@ module Badline
 
       def install_chips(chips)
         roml, romh = banks_from(chips)
-        @roml = roml.first
-        @romh = romh.first
+        @roml = bank(roml, 0)
+        @romh = bank(romh, 0)
         reset
       end
     end

data/lib/badline/cartridge/westermann.rb

@@ -25,8 +25,8 @@ module Badline
 
       def install_chips(chips)
         roml, romh = banks_from(chips)
-        @roml = roml.first
-        @romh = romh.first
+        @roml = bank(roml, 0)
+        @romh = bank(romh, 0)
         reset
       end
     end

data/lib/badline/cartridge.rb

@@ -26,6 +26,7 @@ require "badline/cartridge/atomic_power"
 require "badline/cartridge/final_cartridge3"
 require "badline/cartridge/retro_replay"
 require "badline/cartridge/kcs_power"
+require "badline/cartridge/geo_ram"
 
 module Badline
   class Cartridge
@@ -168,10 +169,18 @@ module Badline
       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)

data/lib/badline/checkpoint.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Badline
+  # A digest of the machine's state at one cycle, for comparing two runs of
+  # the same scenario, on two builds or two revisions. Each component is
+  # hashed on its own with 32-bit FNV-1a, so a mismatch names the part of the
+  # machine that went its own way. Nothing is read through a chip's bus
+  # interface, so taking a checkpoint leaves the machine as it was.
+  #
+  # Colour RAM is digested as the four bits each cell stores: the upper
+  # nibble a CPU read sees comes off the open bus.
+  class Checkpoint
+    COMPONENTS = %w[cpu ram color_ram display vic cia1 cia2 sid].freeze
+
+    FNV_OFFSET = 0x811c9dc5
+    FNV_PRIME = 0x01000193
+
+    attr_reader :cycle, :digests
+
+    class << self
+      def take(computer)
+        new(computer.cycles, [
+              fnv1a(cpu_state(computer.cpu)),
+              fnv1a(ram(computer.ram)),
+              fnv1a(color_ram(computer.address_bus.color_ram)),
+              fnv1a(computer.vic.display),
+              fnv1a(vic_state(computer.vic)),
+              fnv1a(cia_state(computer.cia1)),
+              fnv1a(cia_state(computer.cia2)),
+              fnv1a(Array.new(0x20) { |reg| computer.sid.register(reg) })
+            ])
+      end
+
+      # Reads a line written by #to_s.
+      def parse(line)
+        fields = line.split
+        digests = COMPONENTS.map do |name|
+          field = fields.find { |f| f.start_with?("#{name}=") }
+          raise ArgumentError, "no #{name} digest in #{line.inspect}" unless field
+
+          field.split("=").last.to_i(16)
+        end
+        new(fields.first.to_i, digests)
+      end
+
+      def fnv1a(values)
+        hash = FNV_OFFSET
+        values.each { |value| hash = ((hash ^ (value & 0xffffffff)) * FNV_PRIME) & 0xffffffff }
+        hash
+      end
+
+      private
+
+      def cpu_state(cpu)
+        [cpu.program_counter, cpu.a, cpu.x, cpu.y, cpu.stack_pointer, cpu.p, cpu.cycles]
+      end
+
+      def ram(memory)
+        Array.new(0x10000) { |addr| memory.peek(addr) }
+      end
+
+      def color_ram(memory)
+        Array.new(0x400) { |offset| memory.nibble(0xd800 + offset) }
+      end
+
+      def vic_state(vic)
+        vic.register_file + [vic.rasterline, vic.column]
+      end
+
+      def cia_state(cia)
+        start = cia.start
+        [cia.peek(start), cia.peek(start + 1), cia.peek(start + 2), cia.peek(start + 3),
+         cia.timer_a, cia.timer_a_latch, cia.timer_b, cia.timer_b_latch, cia.serial.data,
+         cia.control_a.value, cia.control_b.value, cia.interrupt_status.value,
+         cia.interrupt_control.value] + cia.time_of_day.registers
+      end
+    end
+
+    def initialize(cycle, digests)
+      @cycle = cycle
+      @digests = digests
+    end
+
+    # The components whose digests differ from `other`'s.
+    def differences(other)
+      COMPONENTS.each_index.reject { |i| digests[i] == other.digests[i] }.map { |i| COMPONENTS[i] }
+    end
+
+    def ==(other)
+      other.is_a?(Checkpoint) && cycle == other.cycle && digests == other.digests
+    end
+
+    def to_s
+      fields = COMPONENTS.each_index.map { |i| "#{COMPONENTS[i]}=#{digests[i].to_s(16).rjust(8, '0')}" }
+      "#{cycle} #{fields.join(' ')}"
+    end
+  end
+end

data/lib/badline/cia/interrupt_register.rb

@@ -8,7 +8,9 @@ module Badline
     class InterruptRegister
       attr_reader :status, :mask, :quiet
 
-      def initialize
+      # The 6526A is the faster of the two: see the rules below.
+      def initialize(model = :mos6526)
+        @fast = model == :mos6526a
         @mask = InterruptFlags.new([:timer_a, :timer_b, :alarm, :serial, :flag, 0, 0, 0])
         @status = InterruptFlags.new([:timer_a, :timer_b, :alarm, :serial, :flag, 0, 0, :interrupt])
         @pending = 0
@@ -32,37 +34,51 @@ module Badline
 
       def interrupted? = status.value >= 0x80
 
+      # Raises IR on this cycle.
+      def assert_now
+        status.interrupt = true
+        @pending = 0
+      end
+
       # Schedules IR to rise after delay cycles, keeping an earlier one.
       def assert!(delay = 1)
         @pending = @pending.positive? ? [@pending, delay].min : delay
         @quiet = false
       end
 
-      # Latch a source, pulling the interrupt line if it is armed.
+      # Latch a source, pulling the interrupt line if it is armed. The 6526
+      # raises IR a cycle after the flag. The 6526A raises it on the flag's
+      # own cycle, unless the ICR was read on the cycle before.
       def flag(source)
         bit = source_bit(source)
         @status.value |= bit
-        assert! if mask.value.anybits?(bit)
+        return unless mask.value.anybits?(bit)
+
+        @fast && @read_last_cycle.nil? ? assert_now : assert!
       end
 
       # The 6526 timer B bug: an underflow on the cycle after a read still
-      # raises the flag, but the next read drops it unseen.
+      # raises the flag, but the next read drops it unseen. The 6526A has
+      # no such bug.
       def timer_b_underflow!
-        @timer_b_bug = !@read_last_cycle.nil?
+        @timer_b_bug = !@fast && !@read_last_cycle.nil?
         flag(:timer_b)
       end
 
       # A read releases the interrupt line at once, and cancels an assert
-      # due on the next cycle, but on the 6526 its IR acknowledge lands a
-      # cycle late: the next cycle still reads IR set if it was set, or
-      # about to be.
+      # due on the next cycle, but its acknowledge lands a cycle late. On
+      # the 6526 that holds only IR: the next cycle still reads IR set if it
+      # was set, or about to be. The 6526A reads an IR about to rise as set
+      # at once, and holds every bit it read: the next cycle reads them all
+      # again, along with anything flagged since.
       def read
         status.timer_b = false if @timer_b_bug
         @timer_b_bug = false
         value = status.value
+        value |= 0x80 if @fast && @pending == 1
         @read = @pending == 1 ? value | 0x80 : value
         @quiet = false
-        value |= 0x80 if @read_last_cycle&.anybits?(0x80)
+        value |= held(@read_last_cycle) if @read_last_cycle
         status.value = 0x0
         @pending = 0
         value
@@ -76,7 +92,7 @@ module Badline
           @mask.value |= (value & 0x1f)
         end
         if mask.value.anybits?(status.value & 0x1f)
-          assert!(2) unless interrupted?
+          assert!(arm_delay) unless interrupted?
         elsif @pending == 1 && @read_two_cycles_ago
           # On the 6526, masking the pending source cancels the assert due
           # on the next cycle only while a read two cycles back is
@@ -87,6 +103,14 @@ module Badline
 
       private
 
+      # Arming a pending source raises IR two cycles later on the 6526,
+      # and one cycle later on the 6526A.
+      def arm_delay = @fast ? 1 : 2
+
+      # What a read on the cycle before still holds: IR on the 6526, and
+      # every bit it read on the 6526A.
+      def held(last) = @fast ? last : last & 0x80
+
       def source_bit(source)
         case source
         when :timer_a then 0x01

data/lib/badline/cia.rb

@@ -9,7 +9,11 @@ module Badline
   class CIA
     include Addressable
 
-    attr_reader :start, :control_a, :control_b, :peripheral, :serial
+    # The original NMOS 6526 of the breadbin C64, and the HMOS 6526A of the
+    # C64C, which differs from it only in its interrupt control register.
+    MODELS = %i[mos6526 mos6526a].freeze
+
+    attr_reader :start, :control_a, :control_b, :peripheral, :serial, :model
 
     def interrupt_status = @icr.status
 
@@ -17,6 +21,8 @@ module Badline
 
     def interrupt!(delay = 1) = @icr.assert!(delay)
 
+    def time_of_day = @tod
+
     def timer_a = @ta.counter
 
     def timer_a=(value)
@@ -41,9 +47,15 @@ module Badline
       @tb.latch = value
     end
 
-    def initialize(start: 0, peripheral: nil)
+    def initialize(start: 0, peripheral: nil, model: :mos6526, region: Region::PAL)
+      raise ArgumentError, "unknown CIA model #{model}" unless MODELS.include?(model)
+
       addressable_at(start, length: 2**8)
 
+      @model = model
+      @clock_hz = region.clock_hz
+      @mains_hz = region.mains_hz
+
       @peripheral = peripheral
       @port_b4_handler = nil
       @port_b4_high = true
@@ -61,8 +73,8 @@ module Badline
       @port_b4_driven_high = true
       @cnt_high = true
       @cnt_rise = false
-      @tod = TimeOfDay.new
-      @icr = InterruptRegister.new
+      @tod = TimeOfDay.new(clock_hz: @clock_hz, mains_hz: @mains_hz)
+      @icr = InterruptRegister.new(@model)
       @icr_status = @icr.status
       @control_a = ControlRegister.new(%i[start output out_mode run_mode load
                                           in_mode serial_mode clock_frequency])
@@ -115,7 +127,7 @@ module Badline
     end
 
     def peek(addr)
-      case index(addr) & 0x0f
+      case offset_of(addr) & 0x0f
       when 0x00 then read_port_a
       when 0x01 then read_port_b
       when 0x02 then @data_dir_a
@@ -136,7 +148,7 @@ module Badline
     end
 
     def poke(addr, value)
-      case index(addr) & 0x0f
+      case offset_of(addr) & 0x0f
       when 0x00 then @data_port_a = value
       when 0x01 then update_port_b { @data_port_b = value }
       when 0x02 then @data_dir_a = value
@@ -221,10 +233,7 @@ module Badline
         else underflowed && @cnt_high
         end
       )
-      if underflowed
-        interrupt_status.timer_a = true
-        interrupt! if interrupt_control.timer_a?
-      end
+      @icr.flag(:timer_a) if underflowed
       @icr.timer_b_underflow! if @tb.underflowed
       underflowed
     end

data/lib/badline/color_memory.rb

@@ -10,7 +10,7 @@ module Badline
     end
 
     def peek(addr)
-      (@vic.phi1_data & 0xf0) | @storage[index(addr)]
+      (@vic.phi1_data & 0xf0) | @storage[offset_of(addr)]
     end
 
     def poke(addr, value)
@@ -19,7 +19,7 @@ module Badline
 
     # The four bits the cell stores, as the VIC's c-access sees them.
     def nibble(addr)
-      @storage[index(addr)]
+      @storage[offset_of(addr)]
     end
   end
 end

data/lib/badline/computer.rb

@@ -7,6 +7,8 @@ module Badline
 
     attr_reader :address_bus, :cpu, :cycles
 
+    def region = address_bus.region
+
     def vic = address_bus.vic
 
     def cia1 = address_bus.cia1
@@ -29,8 +31,12 @@ module Badline
 
     def install_debug_register(&) = address_bus.install_debug_register(&)
 
-    def initialize(debug: false, sid_model: :mos6581)
-      @address_bus = AddressBus.new(sid_model:)
+    # The machine options (sid_model:, cia_model:, vic_model:, region: and
+    # ram_expansion:) configure the AddressBus. The region sets the clock,
+    # the VIC's raster and the mains frequency the CIAs' TOD clocks count.
+    # Only PAL runs as yet.
+    def initialize(debug: false, **machine)
+      @address_bus = AddressBus.new(**machine)
       @cpu = CPU.new(@address_bus, debug:)
       @vic = @address_bus.vic
       @vic.open_bus = -> { @address_bus.ram.peek(@cpu.program_counter) }
@@ -41,10 +47,12 @@ module Badline
       @cycles = 0
       @nmi_asserted = false
       @cartridge_nmi = false
+      @restore_pulse = false
       @freezing = false
       @freeze_writes = 0
       @init_handlers = []
       @pending_keys = nil
+      @drive = nil
     end
 
     INIT_THRESHOLD = 2_500_000
@@ -92,14 +100,16 @@ module Badline
       reset!
     end
 
-    # The RES line reaches the CPU and its port, both CIAs, the SID and the
-    # cartridge port. The VIC has no reset pin.
+    # The RES line reaches the CPU and its port, both CIAs, the SID, the
+    # cartridge port, a RAM expansion and, through the serial bus's RESET
+    # line, the drive. The VIC has no reset pin.
     def reset!
-      address_bus.reset_port!
+      address_bus.reset!
       @cia1.reset!
       @cia2.reset!
       @sid.reset!
       address_bus.cartridge&.reset
+      @drive&.reset!
       @freezing = false
       @nmi_asserted = false
       cpu.reset!
@@ -120,14 +130,23 @@ module Badline
       address_bus.cartridge&.release_button
     end
 
+    # RESTORE isn't in the key matrix. It fires a one-shot that pulses the
+    # NMI line however long the key is held, modelled here as one cycle.
+    def press_restore
+      @restore_pulse = true
+    end
+
+    # Puts the storage in device 8. Mounting again swaps the disk at any
+    # point while the machine runs: the drive keeps its RAM, which only a
+    # drive reset clears, and its status.
     def mount(storage)
-      drive = KernalTrap::Drive.new(storage)
-      load_trap = KernalTrap::Load.new(cpu:, bus: address_bus, drive:)
-      cpu.install_trap(KernalTrap::Load::ADDRESS) { load_trap.call }
-      KernalTrap::Serial.new(cpu:, bus: address_bus, drive:).install
-      return unless storage.respond_to?(:write_file)
+      return @drive.insert(storage) if @drive
 
-      save_trap = KernalTrap::Save.new(cpu:, bus: address_bus, storage:)
+      @drive = KernalTrap::Drive.new(storage)
+      load_trap = KernalTrap::Load.new(cpu:, bus: address_bus, drive: @drive)
+      cpu.install_trap(KernalTrap::Load::ADDRESS) { load_trap.call }
+      KernalTrap::Serial.new(cpu:, bus: address_bus, drive: @drive).install
+      save_trap = KernalTrap::Save.new(cpu:, bus: address_bus, drive: @drive)
       cpu.install_trap(KernalTrap::Save::ADDRESS) { save_trap.call }
     end
 
@@ -151,10 +170,11 @@ module Badline
 
     private
 
-    # The NMI line is wired-OR between CIA 2 and the cartridge, and the CPU
-    # takes an interrupt on its falling edge.
+    # The NMI line is wired-OR between CIA 2, the cartridge and the RESTORE
+    # key, and the CPU takes an interrupt on its falling edge.
     def drive_nmi
-      nmi = @cia2.interrupted? || @cartridge_nmi
+      nmi = @cia2.interrupted? || @cartridge_nmi || @restore_pulse
+      @restore_pulse = false
       @cpu.nmi = true if nmi && !@nmi_asserted
       @nmi_asserted = nmi
     end

data/lib/badline/cpu.rb

@@ -24,10 +24,10 @@ module Badline
 
     # +ane_constant+ is ANE's magic constant, which varies from chip to
     # chip. The default is the C64 6510's.
-    def initialize(memory = nil, debug: false, ane_constant: 0xef)
+    def initialize(memory, debug: false, ane_constant: 0xef)
       @debug = debug
       @ane_constant = ane_constant
-      @memory = memory || Memory.new
+      @memory = memory
       @status = CPUStatus.new(STATUS_FLAGS, value: 0b00100000)
       reset_registers