badline 0.9.0 → 0.10.0

data/lib/badline/kernal_trap/load.rb

@@ -2,29 +2,17 @@
 
 module Badline
   module KernalTrap
-    # PC trap on the KERNAL serial LOAD routine ($F4A5, the default ILOAD
-    # vector target). Reads device 8 requests from the virtual drive's
-    # channel 0, then hands over to the ROM's own tail so it prints
-    # SEARCHING FOR and LOADING (or VERIFYING) in direct mode, reports
-    # errors and returns with the routine's register/zeropage contract;
-    # other devices fall through to the ROM. So does a load that reaches
+    # PC trap on the KERNAL serial LOAD routine (the default ILOAD vector
+    # target, $F4A5 on the C64, $F549 on the VIC-20). Reads device 8
+    # requests from the virtual drive's channel 0, then hands over to the
+    # ROM's own tail so it prints SEARCHING FOR and LOADING (or VERIFYING)
+    # in direct mode, reports errors and returns with the routine's
+    # register/zeropage contract; other devices fall through to the ROM.
+    # So does a load that reaches
     # below $0334, into the zero page, the stack or the KERNAL vectors: the
     # ROM's byte loop then loads it through the serial traps, and a loader
     # that overwrites ISTOP takes over mid-load as it does on a real drive.
     class Load < File
-      ADDRESS = 0xf4a5
-
-      # ROM entry points: the SEARCHING FOR and LOADING/VERIFYING messages,
-      # the byte loop that retries a timed-out byte until RUN/STOP, the
-      # successful return (CLC, LDX $AE, LDY $AF, RTS) and the
-      # FILE NOT FOUND and MISSING FILE NAME error exits
-      SEARCHING_MESSAGE = 0xf5af
-      LOADING_MESSAGE = 0xf5d2
-      BYTE_LOOP = 0xf4f3
-      LOAD_DONE = 0xf5a9
-      FILE_NOT_FOUND_EXIT = 0xf704
-      MISSING_FILE_NAME_EXIT = 0xf710
-
       # ST bits at $90
       EOI = 0x40
       VERIFY_MISMATCH = 0x10
@@ -35,8 +23,8 @@ module Badline
       # address even when the first one relocated.
       LOAD_SECONDARY = 0x60
 
-      def initialize(cpu:, bus:, drive:)
-        super(cpu:, bus:)
+      def initialize(cpu:, bus:, layout:, drive:)
+        super(cpu:, bus:, layout:)
         @drive = drive
       end
 
@@ -46,7 +34,7 @@ module Badline
         @bus.poke(0x93, @cpu.a)
         @bus.poke(0x90, 0x00)
         name = filename
-        return @cpu.program_counter = MISSING_FILE_NAME_EXIT if Storage.parse_name(name).first.empty?
+        return @cpu.program_counter = @layout.missing_file_name_exit if Storage.parse_name(name).first.empty?
 
         data, complete = receive(name)
         if low_memory?(data)
@@ -80,22 +68,23 @@ module Badline
         if data.empty?
           @bus.poke(0x90, EOI | READ_TIMEOUT)
           leave_bus(ACPTR_TIMEOUT)
-          continue_with(SEARCHING_MESSAGE, FILE_NOT_FOUND_EXIT)
+          continue_with(@layout.searching_message, @layout.file_not_found_exit)
         else
           deliver(data)
           @bus.poke(0x90, @bus.peek(0x90) & ~EOI) unless complete
           leave_bus(ISOUR_TIMEOUT)
-          continue_with(SEARCHING_MESSAGE, LOADING_MESSAGE, complete ? LOAD_DONE : BYTE_LOOP)
+          continue_with(@layout.searching_message, @layout.loading_message,
+                        complete ? @layout.load_done : @layout.load_byte_loop)
         end
         @bus.poke(0xb9, LOAD_SECONDARY)
       end
 
       # A load ends with the UNLISTEN that closes the file, a byte sent,
       # and a missing file with the ACPTR that timed out. Either way it
-      # releases ATN, the clock and the data line on CIA 2's port A.
+      # releases ATN, the clock and the data line.
       def leave_bus(timer_high)
         time_serial_byte(timer_high)
-        release_serial_lines
+        @layout.release_serial_lines(@bus)
       end
 
       def low_memory?(data)
@@ -112,7 +101,7 @@ module Badline
         payload = data[2..] || []
         payload = payload[0, 0x10000 - addr] if addr + payload.length > 0x10000
         if load?
-          @bus.ram.write(addr, payload)
+          @layout.store_file(@bus, addr, payload)
           @bus.poke(0x90, EOI)
         else
           verify(addr, payload)

data/lib/badline/kernal_trap/routine.rb

@@ -3,50 +3,34 @@
 module Badline
   module KernalTrap
     # Base class for the PC traps on KERNAL routines. Holds the device
-    # number they answer for and the return that stands in for the trapped
-    # routine's RTS.
+    # number they answer for, the layout of the KERNAL they trap, and the
+    # return that stands in for the trapped routine's RTS.
     class Routine
       include IntegerHelper
 
       DEVICE = 8
 
-      # Timer B's latch high byte as ISOUR and ACPTR set it, and the
-      # control value both start it with: force load, one-shot, start.
+      # The serial timer's high byte as ISOUR and ACPTR set it.
       ISOUR_TIMEOUT = 0x04
       ACPTR_TIMEOUT = 0x01
-      TIMER_ONE_SHOT_START = 0x19
 
-      def initialize(cpu:, bus:)
+      def initialize(cpu:, bus:, layout:)
         @cpu = cpu
         @bus = bus
+        @layout = layout
       end
 
       private
 
-      def kernal?
-        @bus.io_port.kernal?
+      def kernal_mapped?
+        @layout.kernal_mapped?(@bus)
       end
 
-      # The ROM times each byte on the serial bus with CIA 1's timer B,
-      # started one-shot with the high byte of its latch set: ISOUR_TIMEOUT
-      # for a byte sent, ACPTR_TIMEOUT for one received.
+      # The ROM times each byte on the serial bus with a one-shot timer
+      # (Layout#time_serial_byte): ISOUR_TIMEOUT for a byte sent,
+      # ACPTR_TIMEOUT for one received.
       def time_serial_byte(timer_high)
-        @bus.poke(0xdc07, timer_high)
-        @bus.poke(0xdc0f, TIMER_ONE_SHOT_START)
-      end
-
-      # The ROM's release of the serial bus ($EE03): ATN ($EDBE), then the
-      # clock ($EE85), then the data line ($EE97), each a read of CIA 2's
-      # port A, a mask and a write back, so the input bits written back
-      # follow the lines as each one is let go. Returns the last value
-      # written, which the ROM leaves in A.
-      def release_serial_lines
-        value = 0
-        [0xf7, 0xef, 0xdf].each do |mask|
-          value = @bus.peek(0xdd00) & mask
-          @bus.poke(0xdd00, value)
-        end
-        value
+        @layout.time_serial_byte(@bus, timer_high)
       end
 
       def return_to_caller

data/lib/badline/kernal_trap/save.rb

@@ -2,37 +2,27 @@
 
 module Badline
   module KernalTrap
-    # PC trap on the KERNAL serial SAVE routine ($F5ED, the default ISAVE
-    # vector target). Hands device 8 saves to the virtual drive as a PRG
-    # (load address followed by the memory range); other devices fall
-    # through to the ROM, and so do saves to a disk that doesn't take them
-    # whole. The ROM prints SAVING in direct mode and returns
-    # into the trap, which then writes the file and leaves through the
-    # ROM's own tail with the registers its UNLISTEN and return leave. A
+    # PC trap on the KERNAL serial SAVE routine (the default ISAVE vector
+    # target, $F5ED on the C64, $F685 on the VIC-20). Hands device 8 saves
+    # to the virtual drive as a PRG (load address followed by the memory
+    # range); other devices fall through to the ROM, and so do saves to a
+    # disk that doesn't take them whole. The ROM prints SAVING in direct
+    # mode and returns into the trap, which then writes the file and leaves
+    # through the ROM's own tail with the registers its UNLISTEN and return
+    # leave. A
     # write that fails, to a full disk, a name already on it or a host file
     # that can't be written, ends the way a 1541 ends a SAVE it can't
     # write: the drive stops listening, so ST reads DEVICE NOT PRESENT,
     # and the ROM returns without an error. A "@" before the drive prefix
     # writes over a file of the same name.
     class Save < File
-      ADDRESS = 0xf5ed
-
-      # ROM entry points: the SAVING message, the two line releases that
-      # end UNLISTEN (clock, then data, leaving A as read from $DD00), the
-      # successful return (CLC, RTS) and the MISSING FILE NAME error exit
-      SAVING_MESSAGE = 0xf68f
-      CLOCK_RELEASE = 0xee85
-      DATA_RELEASE = 0xee97
-      SAVE_DONE = 0xf657
-      MISSING_FILE_NAME_EXIT = 0xf710
-
       SECONDARY = 0x61
 
       # ST bit at $90
       DEVICE_NOT_PRESENT = 0x80
 
-      def initialize(cpu:, bus:, drive:)
-        super(cpu:, bus:)
+      def initialize(cpu:, bus:, layout:, drive:)
+        super(cpu:, bus:, layout:)
         @drive = drive
         @saving = false
       end
@@ -51,11 +41,11 @@ module Badline
         return unless @drive.saves?
 
         @bus.poke(0xb9, SECONDARY)
-        return @cpu.program_counter = MISSING_FILE_NAME_EXIT if name.empty?
+        return @cpu.program_counter = @layout.missing_file_name_exit if name.empty?
 
         @bus.poke(0x90, 0x00)
         @saving = true
-        continue_with(SAVING_MESSAGE, ADDRESS)
+        continue_with(@layout.saving_message, @layout.save)
       end
 
       private
@@ -72,7 +62,7 @@ module Badline
         @bus.poke(0xad, @bus.peek(0xaf))
         @cpu.y = 0
         @cpu.status.overflow = true
-        continue_with(CLOCK_RELEASE, DATA_RELEASE, SAVE_DONE)
+        continue_with(@layout.clock_release, @layout.data_release, @layout.save_done)
       end
 
       # Start address at $C1/$C2 (STAL), end address (exclusive) at

data/lib/badline/kernal_trap/serial.rb

@@ -12,17 +12,6 @@ module Badline
     class Serial < Routine
       attr_accessor :device
 
-      ROUTINES = {
-        0xed09 => :talk,
-        0xed0c => :listen,
-        0xedb9 => :second,
-        0xedc7 => :tksa,
-        0xeddd => :ciout,
-        0xedef => :untalk,
-        0xedfe => :unlisten,
-        0xee13 => :acptr
-      }.freeze
-
       # Frame type in the high nibble of the secondary address
       OPEN = 0xf0
       CLOSE = 0xe0
@@ -34,8 +23,8 @@ module Badline
 
       NO_DATA = [0x0d, EOI | READ_TIMEOUT].freeze
 
-      def initialize(cpu:, bus:, drive:, device: DEVICE)
-        super(cpu:, bus:)
+      def initialize(cpu:, bus:, layout:, drive:, device: DEVICE)
+        super(cpu:, bus:, layout:)
         @drive = drive
         @device = device
         @listening = false
@@ -63,14 +52,27 @@ module Badline
       end
 
       def install
-        ROUTINES.each do |address, routine|
-          @cpu.install_trap(address) { call_routine(routine) if kernal? }
+        routines.each do |address, routine|
+          @cpu.install_trap(address) { call_routine(routine) if kernal_mapped? }
         end
         self
       end
 
       private
 
+      def routines
+        {
+          @layout.talk => :talk,
+          @layout.listen => :listen,
+          @layout.second => :second,
+          @layout.tksa => :tksa,
+          @layout.ciout => :ciout,
+          @layout.untalk => :untalk,
+          @layout.unlisten => :unlisten,
+          @layout.acptr => :acptr
+        }
+      end
+
       def call_routine(routine)
         case routine
         when :talk then talk
@@ -86,7 +88,7 @@ module Badline
 
       # Addressing the bus starts a new frame. The channel number arrives
       # in the secondary address that follows. Each byte sent under ATN,
-      # and each byte of a frame, times its handshake with CIA 1's timer B
+      # and each byte of a frame, times its handshake with the serial timer
       # as ISOUR does.
       def talk
         @talk_channel = nil
@@ -157,10 +159,10 @@ module Badline
         release_bus
       end
 
-      # UNLSN and UNTLK end by releasing ATN, the clock and the data line on
-      # CIA 2's port A, and leave the port's last read in the accumulator.
+      # UNLSN and UNTLK end by releasing ATN, the clock and the data line,
+      # and leave the port's last read in the accumulator.
       def release_bus
-        @cpu.a = release_serial_lines
+        @cpu.a = @layout.release_serial_lines(@bus)
         @cpu.status.negative = @cpu.a.anybits?(0x80)
         @cpu.status.zero = @cpu.a.zero?
         return_to_caller

data/lib/badline/kernal_trap.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "badline/kernal_trap/layout"
 require "badline/kernal_trap/routine"
 require "badline/kernal_trap/channel"
 require "badline/kernal_trap/drive"

data/lib/badline/keyboard.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Badline
-  # The 8x8 key matrix spanning CIA 1's two ports: rows on port A, columns on
-  # port B.
+  # The key matrix spanning CIA 1's two ports: rows on port A, columns on
+  # port B. Row lines beyond the eighth sit above port A's bits in +rows+.
   #
   # A pressed key shorts its row line to its column line, so whichever side is
   # pulled low drags the other down with it. Scanning works in either
@@ -19,22 +19,25 @@ module Badline
       cursor_left: %i[lshift cursor_h]
     }.freeze
 
+    # The C64's wiring: one row of keys per port A line, in port B column
+    # order.
+    C64_MATRIX = [
+      %i[delete return cursor_h f7 f1 f3 f5 cursor_v],
+      %i[3 w a 4 z s e lshift],
+      %i[5 r d 6 c f t x],
+      %i[7 y g 8 b h u v],
+      %i[9 i j 0 m k o n],
+      %i[+ p l - . : @ ,],
+      %i[£ * ; clr_home rshift = up /],
+      %i[1 left control 2 space cbm q run_stop]
+    ].freeze
+
     attr_reader :keys, :matrix
 
-    def initialize
+    def initialize(matrix: C64_MATRIX)
       @keys = []
       @row_masks = nil
-
-      @matrix = [
-        %i[delete return cursor_h f7 f1 f3 f5 cursor_v],
-        %i[3 w a 4 z s e lshift],
-        %i[5 r d 6 c f t x],
-        %i[7 y g 8 b h u v],
-        %i[9 i j 0 m k o n],
-        %i[+ p l - . : @ ,],
-        %i[£ * ; clr_home rshift = up /],
-        %i[1 left control 2 space cbm q run_stop]
-      ]
+      @matrix = matrix
     end
 
     def press(key)

data/lib/badline/machine.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Badline
+  # = Machine
+  #
+  # The machines badline builds by family, as the command line's
+  # subcommand names them: the C64, Computer, and the VIC-20, Vic20.
+  #
+  # A machine answers what the front end, Media, the runners and the
+  # snapshots call on it:
+  #
+  # - Identity: +family+, the family it was built as.
+  # - Clocking: +run_cycles(n)+, +run_until(limit) { ... }+, +cycles+,
+  #   +on_init+ and +init_threshold+, the cycle its handlers run at.
+  # - Lifecycle: +reset!+ and +power_cycle!+.
+  # - Video: +video+, the chip the screen reads (+display+, +width+,
+  #   +dirty_lines+, +clear_dirty_lines!+ and +palette+), and +timing+, a
+  #   Timing.
+  # - Sound: +sound_source+, which answers +record(rate:)+,
+  #   +drain_samples+ and +model+.
+  # - Input: +keyboard+, +joystick1+, +joystick2+, +control_ports+,
+  #   +press_restore+ and +release_restore+.
+  # - Media: +ram+, +load_prg+, +type_text+, +mount+, +unmount+,
+  #   +mounted?+, +datasette+, +attach_cartridge+,
+  #   +press_cartridge_button+, +release_cartridge_button+,
+  #   +attach_drive1541+, +drive1541+, and +address_bus+ for its
+  #   +cartridge+ and +detach_cartridge+.
+  # - Snapshots and tests: +snapshot+, +restore+, +save_snapshot+,
+  #   +install_debug_register+ and +capture_output+.
+  #
+  # The VIC-20 answers the identity, clocking, lifecycle, video, sound and
+  # input parts, with its one joystick as both +joystick1+ and +joystick2+
+  # and nil for +control_ports+, and of the rest +ram+, +load_prg+,
+  # +type_text+, +mount+, +unmount+, +mounted?+, +datasette+, +attach_cartridge+,
+  # +attach_drive1541+, +drive1541+, +install_debug_register+ and
+  # +capture_output+.
+  module Machine
+    # A new machine of `family`, :c64 or :vic20, the model of it `model`
+    # names. A C64's model is one of Model::ALL, with its SID `sid_model`
+    # when not nil and an REU of `reu` K when not nil. A VIC-20's is "pal",
+    # with the RAM expansion `ram` names (Vic20::Bus::RAM_CONFIGURATIONS),
+    # unexpanded when nil.
+    def self.build(family, model:, sid_model: nil, reu: nil, ram: nil)
+      return vic20(model, ram) if family == :vic20
+      raise ArgumentError, "no machine family named #{family}" unless family == :c64
+
+      profile = Model.named(model)
+      Computer.new(vic_model: profile.vic_model, cia_model: profile.cia_model,
+                   sid_model: sid_model || profile.sid_model, region: profile.region, reu:,
+                   kernal: profile.kernal, datasette: profile.datasette)
+    end
+
+    def self.vic20(model, ram)
+      raise ArgumentError, "no VIC-20 model named #{model}" unless model == "pal"
+
+      Vic20.new(ram: ram || :unexpanded)
+    end
+    private_class_method :vic20
+  end
+end

data/lib/badline/media/vic20_basic.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Badline
+  module Media
+    # A program loading into a VIC-20 once it has booted (Vic20Media).
+    module Vic20Basic
+      # Where BASIC starts with each RAM expansion it can start in, as
+      # TXTTAB holds it.
+      BASIC_STARTS = { 0x1001 => :unexpanded, 0x0401 => :"3k", 0x1201 => :"8k" }.freeze
+
+      class << self
+        # A BASIC program, one that loads at a start of BASIC or a byte
+        # ahead of it, goes to this machine's start of BASIC. Anything else
+        # goes where it says, and doesn't RUN.
+        def load_program(machine, data, autostart:)
+          load_addr = data[0] | (data[1] << 8)
+          basic_start = machine.basic_start
+          ahead = [0, 1].find { |offset| BASIC_STARTS.key?(load_addr + offset) || load_addr + offset == basic_start }
+          return machine.load_prg(data) unless ahead
+
+          load_basic(machine, data, basic_start - ahead, load_addr)
+          machine.type_text("run\r") if autostart
+        end
+
+        private
+
+        # Puts a BASIC program at `address`, relinking its lines when that
+        # isn't where it was saved from, as BASIC's LOAD does, and sets the
+        # end of the program, where BASIC's variables start, and the end
+        # address the KERNAL's LOAD leaves.
+        def load_basic(machine, data, address, saved_at)
+          ram = machine.ram
+          ram.write(address, data[2..])
+          end_addr = address + data.length - 2
+          relink(ram, machine.basic_start, end_addr) unless address == saved_at
+          [0x2d, 0xae].each { |pointer| ram.write(pointer, [end_addr & 0xff, end_addr >> 8]) }
+        end
+
+        # Points each line's link at the line after it, as BASIC's LINKPRG
+        # does: past the zero that ends the line's text. A link with a zero
+        # high byte ends the program.
+        def relink(ram, line, end_addr)
+          while line + 4 < end_addr && ram.peek(line + 1).positive?
+            following = line + 4
+            following += 1 while following < end_addr && ram.peek(following).positive?
+            following += 1
+            ram.write(line, [following & 0xff, following >> 8])
+            line = following
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badline/media/vic20_cartridge.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Badline
+  module Media
+    # A VIC-20 cartridge kept as programs, one per ROM chip, each loading
+    # at the block the chip goes in. The chip in BLK5 at $A000 starts the
+    # cartridge, and a bigger cartridge has more in BLK1 to BLK3. The files
+    # of one cartridge share a name, with each block's address in its
+    # extension (game.a0, game.60) or its name (game-a000.prg,
+    # game-6000.prg).
+    module Vic20Cartridge
+      BLOCKS = [0xa000, 0x2000, 0x4000, 0x6000].freeze
+
+      class << self
+        # The ROM chips, as CRTFile::Chips, of the cartridge `data`, the
+        # program at `path`, is a part of, or nil when it isn't one: a
+        # program loading at $A000, or one loading at the start of BLK1 to
+        # BLK3 with an $A000 part beside it.
+        def chips(path, data)
+          own = load_address(data)
+          return unless BLOCKS.include?(own)
+
+          parts = BLOCKS.filter_map { |address| address == own ? data : part(path, own, address) }
+          return unless parts.any? { |part| load_address(part) == 0xa000 }
+
+          parts.map { |part| rom_chip(part) }
+        end
+
+        # A program's bytes, unwrapped from a .p00.
+        def program_bytes(path)
+          bytes = File.binread(path).bytes
+          Storage::P00.wraps?(bytes) ? Storage::P00.data(bytes) : bytes
+        end
+
+        private
+
+        def load_address(data)
+          data[0] | (data[1] << 8) if data.length > 2
+        end
+
+        def part(path, own, address)
+          name = part_names(path, own, address).find { |candidate| File.file?(candidate) }
+          return unless name
+
+          part = program_bytes(name)
+          part if load_address(part) == address
+        end
+
+        # `path` with the block at `own` in its extension or its name
+        # swapped for the one at `address`, its letters in either case.
+        def part_names(path, own, address)
+          extension = File.extname(path)
+          base = path[0, path.length - extension.length]
+          own_tag = own.to_s(16)
+          tags = [address.to_s(16), address.to_s(16).upcase].uniq
+          return tags.map { |tag| "#{base}.#{tag[0, 2]}" } if extension.downcase == ".#{own_tag[0, 2]}"
+
+          name = File.basename(base)
+          at = name.downcase.index(own_tag)
+          return [] unless at
+
+          tags.map { |tag| File.join(File.dirname(base), name[0, at] + tag + name[(at + 4)..]) + extension }
+        end
+
+        # A ROM chip of whole pages, the last padded with $FF.
+        def rom_chip(part)
+          data = part[2..]
+          data += [0xff] * (-data.length % 0x100)
+          Storage::CRTFile::Chip.new(chip_type: 0, bank: 0, address: load_address(part), data:)
+        end
+      end
+    end
+  end
+end