badline 0.12.0 → 0.13.0

data/lib/badline/c64/cartridge/flash.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require "badline/c64/cartridge/flash/saved_state"
+
+module Badline
+  class C64
+    class Cartridge
+      # An AMD 29F0x0 flash chip, driven through the JEDEC command set in the
+      # AMD datasheets. Each command opens with two unlock cycles, $AA to the
+      # first unlock address and $55 to the second, and a third write picks
+      # the command:
+      #
+      #   $90 autoselect: offset 0 reads the manufacturer, 1 the device and 2
+      #       the sector protection, until a reset
+      #   $F0 reset to reading the array, which a lone $F0 also does
+      #   $A0 byte program: the next write clears bits of the array, which
+      #       only an erase sets again
+      #   $80 erase, after two more unlock cycles: $10 to the first unlock
+      #       address erases the chip, and $30 to a sector erases the sector.
+      #       Further sectors can follow within the 50 us window.
+      #
+      # While a program or erase runs, a read returns status: DQ7 the
+      # complement of the programmed bit (0 while erasing), DQ6 toggling on
+      # every read, DQ5 set when a program failed and DQ3 set once an erase
+      # has left its window. $B0 suspends a sector erase and $30 resumes it.
+      #
+      # The cartridge reads the array through windows, and the chip swaps
+      # them for status windows while it is busy or in autoselect.
+      class Flash
+        Model = Data.define(:size, :sector_size, :unlock1, :unlock2, :unlock_mask, :manufacturer, :device)
+
+        AM29F040 = Model.new(size: 0x80000, sector_size: 0x10000, unlock1: 0x5555, unlock2: 0x2aaa,
+                             unlock_mask: 0x7fff, manufacturer: 0x01, device: 0xa4)
+        AM29F040B = Model.new(size: 0x80000, sector_size: 0x10000, unlock1: 0x555, unlock2: 0x2aa,
+                              unlock_mask: 0x7ff, manufacturer: 0x01, device: 0xa4)
+        AM29F010 = Model.new(size: 0x20000, sector_size: 0x4000, unlock1: 0x5555, unlock2: 0x2aaa,
+                             unlock_mask: 0x7fff, manufacturer: 0x01, device: 0x20)
+
+        # The datasheet's typical times, in cycles at 1 MHz.
+        PROGRAM_CYCLES = 7
+        ERASE_WINDOW_CYCLES = 50
+        SECTOR_ERASE_CYCLES = 1_000_000
+        CHIP_ERASE_CYCLES = 8_000_000
+
+        # The array, read directly while the chip reads it.
+        class Window
+          def initialize(flash, base)
+            @flash = flash
+            @data = flash.data
+            @base = base
+          end
+
+          def peek(addr)
+            @data[@base | (addr & 0x1fff)]
+          end
+          alias [] peek
+
+          def poke(addr, value)
+            @flash.write(@base | (addr & 0x1fff), value)
+          end
+          alias []= poke
+        end
+
+        # Reads through the chip, for its status and autoselect codes.
+        class StatusWindow < Window
+          def peek(addr)
+            @flash.read(@base | (addr & 0x1fff))
+          end
+          alias [] peek
+        end
+
+        include SavedState
+
+        attr_reader :data, :state
+        attr_writer :clock
+
+        def initialize(data, model: AM29F040B, clock: -> { 0 })
+          @model = model
+          @data = data + ([0xff] * (model.size - data.length))
+          @clock = clock
+          @windows = {}
+          @status_windows = {}
+          @on_change = nil
+          @state = :read
+          @base_state = :read
+          @cycle = 0
+          @toggle = 0
+        end
+
+        # Called when the chip starts or stops answering reads from the array.
+        def on_change(&block)
+          @on_change = block
+        end
+
+        def window(base)
+          if array_mode?
+            @windows[base] ||= Window.new(self, base)
+          else
+            @status_windows[base] ||= StatusWindow.new(self, base)
+          end
+        end
+
+        # Hands out new windows at the bases given, as #window would have.
+        def rebuild_windows(bases, status_bases)
+          @windows = {}
+          @status_windows = {}
+          bases.each { |base| @windows[base] = Window.new(self, base) }
+          status_bases.each { |base| @status_windows[base] = StatusWindow.new(self, base) }
+        end
+
+        def array_mode?
+          @state == :read || @state == :program_setup
+        end
+
+        def read(offset)
+          settle
+          case @state
+          when :read then @data[offset]
+          when :autoselect then autoselect_code(offset)
+          when :suspended then suspended_read(offset)
+          else status
+          end
+        end
+
+        def write(offset, value)
+          settle
+          case @state
+          when :program_setup then program(offset, value)
+          when :erase_window then extend_erase(offset, value)
+          when :erasing then suspend if value == 0xb0
+          when :suspended then resume if value == 0x30
+          when :program_error then enter(:read, base: :read) if value == 0xf0
+          when :programming, :chip_erase then nil
+          else command(offset, value)
+          end
+        end
+
+        private
+
+        def command(offset, value)
+          if value == 0xf0
+            @cycle = 0
+            return enter(:read, base: :read)
+          end
+
+          address = offset & @model.unlock_mask
+          @cycle = case @cycle
+                   when 0, 3 then address == @model.unlock1 && value == 0xaa ? @cycle + 1 : 0
+                   when 1, 4 then address == @model.unlock2 && value == 0x55 ? @cycle + 1 : 0
+                   when 2 then command_cycle(address, value)
+                   when 5 then erase_command(offset, address, value)
+                   end
+        end
+
+        def command_cycle(address, value)
+          return 0 unless address == @model.unlock1
+
+          case value
+          when 0x90 then enter(:autoselect, base: :autoselect)
+          when 0xa0 then @state = :program_setup
+          when 0x80 then return 3
+          end
+          0
+        end
+
+        def erase_command(offset, address, value)
+          if value == 0x10 && address == @model.unlock1
+            start_busy(:chip_erase, CHIP_ERASE_CYCLES)
+          elsif value == 0x30
+            @erasing_sectors = [sector(offset)]
+            start_busy(:erase_window, ERASE_WINDOW_CYCLES)
+          end
+          0
+        end
+
+        def program(offset, value)
+          @programmed = value
+          @data[offset] &= value
+          if @data[offset] == value
+            start_busy(:programming, PROGRAM_CYCLES)
+          else
+            enter(:program_error)
+          end
+        end
+
+        def extend_erase(offset, value)
+          case value
+          when 0x30
+            @erasing_sectors |= [sector(offset)]
+            @done_at = now + ERASE_WINDOW_CYCLES
+          when 0xb0
+            @remaining = @erasing_sectors.length * SECTOR_ERASE_CYCLES
+            enter(:suspended)
+          else
+            @erasing_sectors = nil
+            enter(@base_state)
+          end
+        end
+
+        def suspend
+          @remaining = @done_at - now
+          enter(:suspended)
+        end
+
+        def resume
+          start_busy(:erasing, @remaining)
+        end
+
+        # Moves a timed operation on once the clock has passed its end.
+        def settle
+          return unless @done_at && now >= @done_at
+
+          case @state
+          when :erase_window
+            start_busy(:erasing, @done_at - now + (@erasing_sectors.length * SECTOR_ERASE_CYCLES))
+            settle
+          when :erasing
+            @erasing_sectors.each { |s| @data.fill(0xff, s * @model.sector_size, @model.sector_size) }
+            @erasing_sectors = nil
+            finish
+          when :chip_erase
+            @data.fill(0xff)
+            finish
+          else
+            finish
+          end
+        end
+
+        def finish
+          @done_at = nil
+          enter(@base_state)
+        end
+
+        def start_busy(state, cycles)
+          @done_at = now + cycles
+          @programmed = 0xff unless state == :programming
+          enter(state)
+        end
+
+        def enter(state, base: @base_state)
+          was_array = array_mode?
+          @state = state
+          @base_state = base
+          @done_at = nil unless %i[programming erase_window erasing chip_erase].include?(state)
+          @on_change&.call if was_array != array_mode?
+        end
+
+        def status
+          @toggle ^= 0x40
+          value = (~@programmed & 0x80) | @toggle
+          value |= 0x20 if @state == :program_error
+          value |= 0x08 if @state == :erasing || @state == :chip_erase
+          value
+        end
+
+        def suspended_read(offset)
+          @erasing_sectors.include?(sector(offset)) ? 0x80 : @data[offset]
+        end
+
+        def autoselect_code(offset)
+          case offset & 0x43
+          when 0 then @model.manufacturer
+          when 1 then @model.device
+          when 2 then 0x00
+          else @data[offset]
+          end
+        end
+
+        def sector(offset)
+          offset / @model.sector_size
+        end
+
+        def now
+          @clock.call
+        end
+      end
+    end
+  end
+end

data/lib/badline/c64/cartridge/freezer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    class Cartridge
+      # The freeze button of a freezer cartridge. A press pulls NMI, and the
+      # computer calls #freeze! once the CPU has pushed the return address and
+      # status of the interrupt, so the vector fetch that follows reads the
+      # cartridge ROM in Ultimax mode. The cartridge lets go of NMI when its
+      # software acknowledges the freeze.
+      module Freezer
+        def freezer? = true
+
+        def press_button
+          @button = true
+          self.nmi = true if freeze_allowed?
+        end
+
+        def release_button
+          @button = false
+        end
+
+        private
+
+        def freeze_allowed?
+          true
+        end
+
+        def button_pressed?
+          @button == true
+        end
+      end
+    end
+  end
+end

data/lib/badline/c64/cartridge/fun_play.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    class Cartridge
+      # Fun Play / Power Play: up to 16 8K banks. A write to I/O 1 selects the
+      # bank from bits 3-5 and 0, and either 8K mode ($00 in bits 7, 6, 2 and 1)
+      # or no ROM ($86 in those bits).
+      class FunPlay < Cartridge
+        def poke(addr, value)
+          return if addr > 0xdeff
+
+          @roml = bank(@banks, self.class.bank_number(value))
+          case value & 0xc6
+          when 0x00 then self.mode = :rom8k
+          when 0x86 then self.mode = :off
+          end
+          changed!
+        end
+
+        # The CRT file numbers each bank by the register value that selects it.
+        def reset
+          poke(0xde00, 0)
+        end
+
+        def self.bank_number(value)
+          ((value >> 3) & 0x07) | ((value & 0x01) << 3)
+        end
+
+        private
+
+        def install_chips(chips)
+          @banks = []
+          chips.each { |chip| @banks[self.class.bank_number(chip.bank)] = rom_bank(chip.data) }
+          reset
+        end
+      end
+    end
+  end
+end

data/lib/badline/c64/cartridge/g_mod2.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    class Cartridge
+      # GMod2: an Am29F040 flash chip of 64 8K banks at ROML. A write to I/O 1
+      # selects the bank from bits 0-5. Bit 6 selects the EEPROM, which
+      # switches the ROM out, and bits 6 and 7 together enable flash writes:
+      # the cartridge then asserts Ultimax on write cycles only, so reads see
+      # the C64's memory and writes to $E000-$FFFF reach the flash. The EEPROM
+      # isn't emulated.
+      class GMod2 < Cartridge
+        BANKS = 64
+
+        attr_reader :flash
+
+        def clock=(clock)
+          super
+          @flash.clock = clock
+        end
+
+        def poke(addr, value)
+          return if addr > 0xdeff
+
+          @bank = value & 0x3f
+          @flash_writes = value.allbits?(0xc0)
+          self.mode = value.anybits?(0x40) ? :off : :rom8k
+          select_bank
+        end
+
+        def romh_writes
+          @roml if @flash_writes
+        end
+
+        # Reset selects the first bank in 8K mode, and leaves the flash as it
+        # is.
+        def reset
+          @bank = 0
+          @flash_writes = false
+          self.mode = :rom8k
+          select_bank
+        end
+
+        private
+
+        def select_bank
+          @roml = @flash.window(@bank * BANK_SIZE)
+          changed!
+        end
+
+        def save_mapper(out)
+          out.int(@bank).boolean(@flash_writes)
+          @flash.save_state(out)
+        end
+
+        def load_mapper(input)
+          @bank = input.int
+          @flash_writes = input.boolean?
+          @flash.load_state(input)
+          @roml = @flash.window(@bank * BANK_SIZE)
+        end
+
+        def install_chips(chips)
+          data = Array.new(BANKS * BANK_SIZE, 0xff)
+          chips.each do |chip|
+            bytes = chip.data.first(BANK_SIZE)
+            data[(chip.bank & 0x3f) * BANK_SIZE, bytes.length] = bytes
+          end
+          @flash = Flash.new(data, model: Flash::AM29F040)
+          @flash.on_change { select_bank }
+          reset
+        end
+      end
+    end
+  end
+end

data/lib/badline/c64/cartridge/game_system.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    class Cartridge
+      # C64 Game System / System 3: up to 64 8K banks. Any access to
+      # $DE00-$DEFF selects the bank from the low six address bits; the data
+      # is ignored.
+      class GameSystem < Cartridge
+        def readable_io_pages
+          [0xde]
+        end
+
+        def peek(addr)
+          select(addr) if addr < 0xdf00
+          open_bus(addr)
+        end
+
+        def poke(addr, _value)
+          select(addr) if addr < 0xdf00
+        end
+
+        def reset
+          select(0)
+        end
+
+        private
+
+        def select(addr)
+          @roml = bank(@banks, addr & 0x3f)
+          changed!
+        end
+
+        def install_chips(chips)
+          @banks = banks_from(chips).first
+          self.mode = :rom8k
+          reset
+        end
+      end
+    end
+  end
+end

data/lib/badline/c64/cartridge/geo_ram.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    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
+
+        # A GEO-RAM is built from its size alone.
+        def save_setup(out)
+          out.int(GEO_RAM_SETUP).int(@size)
+        end
+
+        private
+
+        def save_mapper(out)
+          out.blob(@ram_data).int(@block).int(@page).int(@window)
+        end
+
+        def load_mapper(input)
+          input.blob_into(@ram_data)
+          @block = input.int
+          @page = input.int
+          @window = input.int
+        end
+
+        def install_chips(_chips)
+          @ram_data = Array.new(@size * 1024, 0)
+          reset
+        end
+      end
+    end
+  end
+end

data/lib/badline/c64/cartridge/kcs_power.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    class Cartridge
+      # The KCS Power Cartridge: 16K of ROM, 128 bytes of RAM and a freeze
+      # button. It boots in 16K mode, and any access to I/O 1 sets the lines
+      # from address bit 1 and the direction:
+      #
+      #   read,  bit 1 clear  8K
+      #   read,  bit 1 set    off
+      #   write, bit 1 clear  16K
+      #   write, bit 1 set    Ultimax
+      #
+      # A read of I/O 1 returns the second last page of ROML. I/O 2 holds the
+      # RAM in its lower half, and the upper half reads the EXROM line in bit 7
+      # and GAME in bit 6, which the freezer checks to find the mode it
+      # interrupted. A freeze switches to Ultimax and lets go of NMI.
+      class KCSPower < Cartridge
+        include Freezer
+
+        IO1_ROM_PAGE = 0x1e00
+
+        def readable_io_pages
+          [0xde, 0xdf]
+        end
+
+        def peek(addr)
+          if addr < 0xdf00
+            select_mode(addr.anybits?(0x02) ? :off : :rom8k)
+            @roml.peek(IO1_ROM_PAGE | (addr & 0xff))
+          elsif addr.anybits?(0x80)
+            (@exrom << 7) | (@game << 6) | (open_bus(addr) & 0x3f)
+          else
+            @io_ram[addr & 0x7f]
+          end
+        end
+
+        def poke(addr, value)
+          if addr < 0xdf00
+            select_mode(addr.anybits?(0x02) ? :ultimax : :rom16k)
+          elsif addr.nobits?(0x80)
+            @io_ram[addr & 0x7f] = value
+          end
+        end
+
+        def reset
+          self.nmi = false
+          select_mode(:rom16k)
+        end
+
+        def freeze!
+          self.nmi = false
+          select_mode(:ultimax)
+        end
+
+        private
+
+        def save_mapper(out)
+          out.blob(@io_ram)
+        end
+
+        def load_mapper(input)
+          input.blob_into(@io_ram)
+        end
+
+        def install_chips(chips)
+          roml, romh = banks_from(chips)
+          @roml = roml.first || EMPTY_BANK
+          @romh = romh.first || EMPTY_BANK
+          @io_ram = Array.new(0x80, 0xff)
+          reset
+        end
+      end
+    end
+  end
+end

data/lib/badline/c64/cartridge/mach5.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    class Cartridge
+      # 8K. Writing I/O 1 switches the ROM in, writing I/O 2 switches it out.
+      # Both I/O pages read the last 512 bytes of the ROM.
+      class Mach5 < Cartridge
+        def readable_io_pages
+          [0xde, 0xdf]
+        end
+
+        def peek(addr)
+          @roml.peek(addr)
+        end
+
+        def poke(addr, _value)
+          select_mode(addr < 0xdf00 ? :rom8k : :off)
+        end
+
+        def reset
+          select_mode(:rom8k)
+        end
+
+        private
+
+        def install_chips(chips)
+          @roml = banks_from(chips).first.compact.first || EMPTY_BANK
+          reset
+        end
+      end
+    end
+  end
+end

data/lib/badline/c64/cartridge/magic_desk.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Badline
+  class C64
+    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 = bank(@banks, value & @bank_mask)
+          changed!
+        end
+
+        def reset
+          poke(0xde00, 0)
+        end
+
+        private
+
+        def install_chips(chips)
+          @banks = banks_from(chips).first
+          @bank_mask = (bank_mask(@banks) | 0x03) & 0x7f
+          reset
+        end
+      end
+    end
+  end
+end