badline 0.9.0 → 0.10.1

data/lib/badline/iec_bus.rb

@@ -3,13 +3,14 @@
 module Badline
   # The serial bus between the C64 and its drives: ATN, CLK and DATA, each
   # an open-collector line with a pull-up. A line is low while any device
-  # pulls it (wired-AND), and high otherwise. The bus holds no state of its
-  # own: every read works the levels out from what each side drives now.
+  # pulls it (wired-AND), and high otherwise. Every read works the levels
+  # out from what each side drives now.
   #
   # The C64 drives the lines from CIA 2's port A through 7406 inverters, so
   # an output bit of 1 pulls its line low: PA3 ATN, PA4 CLK and PA5 DATA.
-  # PA6 and PA7 read CLK and DATA directly, 1 for a released line. The bus
-  # stands in as CIA 2's peripheral for those two inputs.
+  # The machine pushes those bits into the bus (host_lines=), which holds
+  # them. PA6 and PA7 read CLK and DATA directly, 1 for a released line.
+  # The bus stands in as CIA 2's peripheral for those two inputs.
   #
   # A drive drives CLK and DATA from VIA 1's PB3 and PB1, the same way. It
   # also pulls DATA while ATN IN differs from its ATN acknowledge on PB4
@@ -33,30 +34,21 @@ module Badline
     CLK = 0x02
     DATA = 0x04
 
-    attr_reader :host, :drives
+    attr_reader :drives, :host_lines
 
-    # +host+ is CIA 2, or nil for a bus with only drives on it.
-    def initialize(host: nil)
-      @host = host
+    def initialize
       @drives = []
-      @notifies = false
+      @host_lines = 0
     end
 
-    # Stands in as the host's peripheral, CIA 2's, and has it say when it
-    # writes port A (see notifies?).
-    def plug_in!
-      @host.peripheral = self
-      @host.on_port_a_write { host_written }
-      @notifies = true
+    # The machine pushes the lines it pulls, as port A bits, whenever they
+    # may have moved: its output bits, with input bits floating high as the
+    # 7406 inputs see them. A bus with only drives on it keeps 0.
+    def host_lines=(lines)
+      @host_lines = lines
+      @drives.each(&:host_written!)
     end
 
-    # Whether the host says when it may have moved a line (see plug_in!).
-    # Without, a drive asleep checks ATN every cycle.
-    def notifies? = @notifies
-
-    # CIA 2 wrote its port A, which may have moved a line.
-    def host_written = @drives.each(&:host_written!)
-
     def attach(drive)
       @drives << drive unless @drives.include?(drive)
     end
@@ -68,7 +60,7 @@ module Badline
     # One pass over everything on the bus, for a reader that wants more
     # than one line. +host+ is the C64's port A lines as the reader sees
     # them, which a drive takes a cycle late (see Drive1541::SerialPort).
-    def low_lines(host = host_lines)
+    def low_lines(host = @host_lines)
       atn = host.anybits?(HOST_ATN_OUT)
       low = atn ? ATN : 0
       low |= CLK if host.anybits?(HOST_CLK_OUT)
@@ -83,7 +75,7 @@ module Badline
       low
     end
 
-    def atn_low?(host = host_lines) = host.anybits?(HOST_ATN_OUT)
+    def atn_low?(host = @host_lines) = host.anybits?(HOST_ATN_OUT)
 
     def clk_low? = low_lines.anybits?(CLK)
 
@@ -101,9 +93,5 @@ module Badline
 
     # Port B goes to the user port, not the serial bus.
     def read_b(_port_a, _port_b) = 0xff
-
-    # What the C64 pulls, as port A bits: its output bits, with input bits
-    # floating high as the 7406 inputs see them.
-    def host_lines = @host ? @host.port_a_lines : 0
   end
 end

data/lib/badline/kernal_trap/drive.rb

@@ -84,6 +84,9 @@ module Badline
         @memory.read_bam
       end
 
+      # The path of the disk or directory in the drive.
+      def path = @storage.path
+
       # Whether the disk takes a SAVE handed over whole.
       def saves? = @storage.respond_to?(:write_file)
 

data/lib/badline/kernal_trap/file.rb

@@ -6,7 +6,7 @@ module Badline
       private
 
       def active?
-        kernal? && @bus.peek(0xba) == DEVICE
+        kernal_mapped? && @bus.peek(0xba) == DEVICE
       end
 
       def filename

data/lib/badline/kernal_trap/layout.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Badline
+  module KernalTrap
+    # Where a machine's KERNAL keeps the routines the traps stand in for,
+    # and the ROM code they hand over to, with the steps that depend on the
+    # machine around it: whether the KERNAL is mapped in, the timer that
+    # times each serial byte and the release of the serial lines.
+    #
+    # +load+ and +save+ are the default ILOAD and ISAVE vector targets.
+    # LOAD hands over to 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. SAVE hands over to the SAVING
+    # message, the two line releases that end UNLISTEN (clock, then data,
+    # leaving A as read from the port), the successful return (CLC, RTS)
+    # and the MISSING FILE NAME exit. The rest are the serial bus
+    # primitives' entry points.
+    #
+    # +banked+ says whether the 6510 port can bank the KERNAL out, and so
+    # whether RAM lies under every ROM and the I/O. Each
+    # serial byte starts a one-shot timer by writing the high byte of its
+    # count to +serial_timer+, and the control value TIMER_ONE_SHOT_START
+    # to +serial_timer_start+ where the timer has a control register to
+    # start it (a CIA's), or nil where the write to the high byte starts it
+    # (a VIA's timer 2). The ROM lets go of each serial line by reading a
+    # port, masking the line's bit off and writing it back: ATN at
+    # +atn_port+ with +atn_mask+, then the clock and the data line.
+    Layout = Data.define(:load, :save, :searching_message, :loading_message, :load_byte_loop, :load_done,
+                         :file_not_found_exit, :missing_file_name_exit, :saving_message, :clock_release,
+                         :data_release, :save_done, :talk, :listen, :second, :tksa, :ciout, :untalk,
+                         :unlisten, :acptr, :banked, :serial_timer, :serial_timer_start, :atn_port, :atn_mask,
+                         :clock_port, :clock_mask, :data_port, :data_mask) do
+      # Whether the CPU reads the KERNAL ROM at the trapped addresses: on a
+      # banked machine, the 6510 port's banking bits select it.
+      def kernal_mapped?(bus)
+        !banked || bus.io_port.kernal?
+      end
+
+      # Stores a loaded file's bytes from +address+ on: on a banked machine
+      # into the RAM under whatever is banked in, and otherwise where the
+      # ROM's byte loop would store them, through the bus.
+      def store_file(bus, address, bytes)
+        return bus.ram.write(address, bytes) if banked
+
+        bytes.each_with_index { |byte, i| bus.poke(address + i, byte) }
+      end
+
+      # Starts the timer the ROM times a serial byte with, its count's high
+      # byte +timer_high+.
+      def time_serial_byte(bus, timer_high)
+        bus.poke(serial_timer, timer_high)
+        start = serial_timer_start
+        bus.poke(start, TIMER_ONE_SHOT_START) if start
+      end
+
+      # The ROM's release of the serial bus: ATN, then the clock, then the
+      # data line, each a read of its port, 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(bus)
+        release_line(bus, atn_port, atn_mask)
+        release_line(bus, clock_port, clock_mask)
+        release_line(bus, data_port, data_mask)
+      end
+
+      private
+
+      def release_line(bus, port, mask)
+        value = bus.peek(port) & mask
+        bus.poke(port, value)
+        value
+      end
+    end
+
+    # A CIA's control value that starts its timer: force load, one-shot,
+    # start.
+    TIMER_ONE_SHOT_START = 0x19
+
+    # The C64 KERNAL, revision 3. The SX-64's, 251104-04, differs from it
+    # only in bytes none of these addresses reach. It times serial bytes
+    # with CIA 1's timer B, and drives the lines from CIA 2's port A
+    # ($EE03: ATN $EDBE, clock $EE85, data $EE97).
+    C64_LAYOUT = Layout.new(
+      load: 0xf4a5, save: 0xf5ed,
+      searching_message: 0xf5af, loading_message: 0xf5d2, load_byte_loop: 0xf4f3, load_done: 0xf5a9,
+      file_not_found_exit: 0xf704, missing_file_name_exit: 0xf710,
+      saving_message: 0xf68f, clock_release: 0xee85, data_release: 0xee97, save_done: 0xf657,
+      talk: 0xed09, listen: 0xed0c, second: 0xedb9, tksa: 0xedc7,
+      ciout: 0xeddd, untalk: 0xedef, unlisten: 0xedfe, acptr: 0xee13,
+      banked: true, serial_timer: 0xdc07, serial_timer_start: 0xdc0f,
+      atn_port: 0xdd00, atn_mask: 0xf7, clock_port: 0xdd00, clock_mask: 0xef, data_port: 0xdd00, data_mask: 0xdf
+    )
+
+    # The VIC-20 KERNAL, 901486-07 (PAL). The NTSC one, 901486-06, differs
+    # from it only at $E475, $EDE4-$EDE5, $FE3F, $FE44 and $FF5C-$FF70,
+    # none of them here. Nothing banks it out. It times serial bytes with
+    # VIA 2's timer 2 ($9129), drives ATN from VIA 1's PA7 ($911F) and the
+    # clock and data lines from VIA 2's CA2 and CB2 ($912C), and UNLISTEN
+    # lets them go at $EF09: ATN $EEC5, clock $EF84, data $E4A0.
+    VIC20_LAYOUT = Layout.new(
+      load: 0xf549, save: 0xf685,
+      searching_message: 0xf647, loading_message: 0xf66a, load_byte_loop: 0xf58a, load_done: 0xf641,
+      file_not_found_exit: 0xf787, missing_file_name_exit: 0xf793,
+      saving_message: 0xf728, clock_release: 0xef84, data_release: 0xe4a0, save_done: 0xf6ef,
+      talk: 0xee14, listen: 0xee17, second: 0xeec0, tksa: 0xeece,
+      ciout: 0xeee4, untalk: 0xeef6, unlisten: 0xef04, acptr: 0xef19,
+      banked: false, serial_timer: 0x9129, serial_timer_start: nil,
+      atn_port: 0x911f, atn_mask: 0x7f, clock_port: 0x912c, clock_mask: 0xfd, data_port: 0x912c, data_mask: 0xdf
+    )
+  end
+end

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,26 +19,40 @@ 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 = matrix
+      @connected = true
+    end
 
-      @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]
-      ]
+    # Whether the machine has a keyboard. The C64GS has none: no key goes
+    # down on it.
+    def connected? = @connected
+
+    def connected=(connected)
+      @connected = connected
+      @keys.clear unless connected
+      @row_masks = nil
     end
 
     def press(key)
-      return unless valid_key?(key)
+      return unless @connected && valid_key?(key)
 
       @keys << key
       @row_masks = nil

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, board: profile.board)
+    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