badline 0.13.0 → 0.14.0

data/lib/badline/plus4.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "badline/chips/ted"
+require "badline/chips/tia"
+require "badline/plus4/model"
+require "badline/plus4/cpu"
+require "badline/plus4/cpu_port"
+require "badline/plus4/keyboard_port"
+require "badline/plus4/user_port"
+require "badline/plus4/acia"
+require "badline/plus4/bus"
+
+module Badline
+  # The Commodore 264 series: the Plus/4, the C16 and the C116. A 7501 on
+  # the TED's clock, which runs it once or twice a TED cycle (Chips::TED's
+  # Beam), the TED and, on the Plus/4, a 6551 ACIA and the user port's
+  # 6529. Only the TED pulls IRQ, and nothing pulls NMI, which the 7501
+  # doesn't have.
+  #
+  # It runs headless only: the TED paints no picture yet. Device 8
+  # serves disks through the KERNAL traps (C64::KernalTraps), and
+  # cartridges go in cartridge 1's slots.
+  class Plus4
+    include IntegerHelper
+    include Machine::KeyboardBuffer
+    include Machine::Clocking
+    include C64::KernalTraps
+
+    # The cycle by which the KERNAL has booted and BASIC printed READY,
+    # with a margin, in TED cycles. READY is up by about 116,000 on a PAL
+    # Plus/4, 126,000 on an NTSC one and sooner on a C16.
+    INIT_THRESHOLD = 200_000
+
+    attr_reader :model, :bus, :cpu, :ted, :port, :keyboard, :keyboard_port, :acia, :user_port, :datasette, :tias,
+                :iec_bus, :cycles, :ram_kb
+
+    def family = :plus4
+
+    def init_threshold = INIT_THRESHOLD
+
+    def ram = @bus.ram
+
+    # Reads and writes memory as the CPU sees it, through the bus.
+    def peek(addr) = @bus.peek(addr)
+
+    def poke(addr, value) = @bus.poke(addr, value)
+
+    # +model+ names one of Model::ALL, or c116 for the C16, and +ram+ the
+    # RAM in K, one of Model::RAM_SIZES, when not the model's own. +tcbm+
+    # plugs in a 1551's TCBM interface, the TIAs at $FEC0-$FEFF, with no
+    # drive answering on the other side.
+    def initialize(model: "plus4", ram: nil, tcbm: false, debug: false)
+      @model = Model.named(model)
+      @ram_kb = ram || @model.ram_kb
+      raise ArgumentError, "no Plus/4 RAM size of #{@ram_kb}K" unless Model::RAM_SIZES.include?(@ram_kb)
+
+      @ted = Chips::TED.new(@model.ted)
+      @keyboard = Input::Keyboard.new(matrix: KeyboardPort::MATRIX)
+      @keyboard_port = KeyboardPort.new(@keyboard)
+      @ted.keyboard_port = @keyboard_port
+      @iec_bus = Drives::SerialBus.new
+      @datasette = Drives::Datasette.new(level: true)
+      @port = CPUPort.new(serial_bus: @iec_bus, datasette: @datasette)
+      plus4_parts = @model.plus4_parts
+      @acia = plus4_parts ? ACIA.new : nil
+      @user_port = plus4_parts ? UserPort.new(@datasette) : nil
+      io = Bus::IOPage.new(keyboard_port: @keyboard_port, acia: @acia, user_port: @user_port)
+      @bus = Bus.new(ted: @ted, port: @port, io:, model: @model, ram_kb: @ram_kb)
+      @tias = tcbm ? [Chips::TIA.new, Chips::TIA.new] : []
+      @bus.plug_tcbm(drive8: @tias[0], drive9: @tias[1]) if tcbm
+      @cpu = CPU.new(@bus, debug:)
+      @cycles = 0
+      @init_handlers = []
+      @pending_keys = nil
+      @dos = nil
+      @serial_trap = nil
+      @save_trap = nil
+      @capture_output = nil
+    end
+
+    # One TED cycle: the TED moves on and decides the CPU's clock, then the
+    # CPU runs its cycles in it, none while the TED holds the bus.
+    def cycle!
+      handle_init if @cycles == INIT_THRESHOLD
+      feed_keyboard if @pending_keys
+
+      ted = @ted
+      ted.cycle!
+      @datasette.cycle!
+      @cpu.irq = ted.irq?
+      slots = ted.cpu_slots
+      if slots.zero?
+        @cpu.stall!
+      else
+        clock_cpu(ted)
+        clock_cpu(ted) if slots == 2
+      end
+
+      @cycles += 1
+    end
+
+    # The RESET line: the CPU, the port, the 6529s, the ACIA, the bank
+    # latch and ROM selection. The TED has no reset pin.
+    def reset!
+      @port.reset!
+      @keyboard_port.reset!
+      @user_port&.reset!
+      @dos&.reset!
+      @acia&.reset!
+      @tias.each(&:reset!)
+      @bus.reset!
+      @cpu.reset!
+    end
+
+    # Switches the machine off and on: RAM and the TED start from their
+    # power-on state, and the RES line resets everything else.
+    def power_cycle!
+      @bus.power_on!
+      @ted.power_on!
+      reset!
+    end
+
+    # Calls the block with the exit code a VICE testprog writes to $FDCF.
+    def install_debug_register(&) = @bus.install_debug_register(&)
+
+    # Puts a cartridge's ROM chips in cartridge 1's slots (Bus#attach_cartridge)
+    # and switches the machine off and on, as a cartridge goes in with the
+    # power off. The KERNAL starts it at reset when it signs itself with CBM
+    # at $8007.
+    def attach_cartridge(chips)
+      @bus.attach_cartridge(chips)
+      power_cycle!
+    end
+
+    # Stores a PRG's bytes from its load address on, into RAM, and returns
+    # that address.
+    def load_prg(data)
+      load_addr = uint16(data[0], data[1])
+      bytes = data[2..] || []
+      bytes = bytes[0, 0x10000 - load_addr] if load_addr + bytes.length > 0x10000
+      bytes.each_with_index { |byte, i| @bus.ram_view.poke(load_addr + i, byte) }
+      load_addr
+    end
+
+    private
+
+    # The 264 KERNAL's keyboard buffer.
+    def keyboard_buffer = Machine::KeyboardBuffer::PLUS4_LAYOUT
+
+    # The 264 KERNAL, which the traps stand in for.
+    def trap_layout = KernalTrap::PLUS4_LAYOUT
+
+    def trap_bus = @bus
+
+    # Device 8, which the serial traps answer for, with no true drive on
+    # the bus to take it.
+    def serial_trap_device = KernalTrap::Routine::DEVICE
+
+    # BA stops the CPU at a read, and a write goes ahead.
+    def clock_cpu(ted)
+      ted.ba_low? && !@cpu.pending_write? ? @cpu.stall! : @cpu.cycle!
+    end
+  end
+end

data/lib/badline/roms/README

@@ -132,3 +132,41 @@ c128/character.rom
 The character generator ROM, 390059-01 (characters.390059-01.bin),
 8 KB: the C64's set, the same as character.rom, followed by the C128's.
 SHA-1 29ed066d513f2d5c09ff26d9166ba23c2afb2b3f.
+
+Commodore 264 series ROMs
+=========================
+
+Downloaded from
+https://www.zimmers.net/anonftp/pub/cbm/firmware/computers/plus4/
+for the Plus/4, the C16 and the C116, which share BASIC and the KERNAL.
+Nothing maps them yet.
+
+plus4/basic.rom
+---------------
+BASIC 3.5, 318006-01 (basic.318006-01.bin), for $8000-$BFFF in ROM
+bank 0.
+SHA-1 161c96b4ad20f3a4f2321808e37a5ded26a135dd.
+
+plus4/kernal-pal.rom
+--------------------
+The PAL KERNAL, 318004-05 (kernal.318004-05.bin), for $C000-$FFFF in
+ROM bank 0, with the character set from $D000.
+SHA-1 7c7e07f016391174a557e790c4ef1cbe33512cdb.
+
+plus4/kernal-ntsc.rom
+---------------------
+The NTSC KERNAL, 318005-05 (kernal.318005-05.bin), for $C000-$FFFF in
+ROM bank 0.
+SHA-1 a3d9e5be091b98de39a046ab167fb7632d053682.
+
+plus4/function-low.rom
+----------------------
+The Plus/4's 3-plus-1 function ROM, low half, 317053-01
+(3-plus-1.317053-01.bin), for $8000-$BFFF in ROM bank 1.
+SHA-1 3b69f6e7cb4c18bb08e203fb18b7dabfa853390f.
+
+plus4/function-high.rom
+-----------------------
+The Plus/4's 3-plus-1 function ROM, high half, 317054-01
+(3-plus-1.317054-01.bin), for $C000-$FFFF in ROM bank 1.
+SHA-1 0ad7ac2db7da692d972e586ca0dfd747d82c7693.

data/lib/badline/snapshot/c128_setup.rb

@@ -7,31 +7,20 @@ module Badline
     C128Setup = Data.define(:model, :sid_model, :mode)
 
     class C128Setup
-      MARKER = "C128"
       SID_MODELS = %i[mos6581 mos8580].freeze
       MODES = %i[c64 c128].freeze
 
-      # The setup a C128's State starts with.
-      def self.from(state)
-        input = StateReader.new(state)
-        input.marker(MARKER)
-        input.check_stamp
-        read(input)
+      # The model, the SID and the mode by name, in a keyed snapshot module.
+      def write_fields(out)
+        out.text("model", model).text("sid_model", sid_model.to_s).text("mode", mode.to_s)
       end
 
-      def self.read(input)
-        model = input.string
-        known = C128::Model::ALL.any? { |candidate| candidate.name == model }
-        raise FormatError, "the state names a C128 model badline doesn't know" unless known
-
-        sid_model = SID_MODELS.fetch(input.int)
-        new(model:, sid_model:, mode: MODES.fetch(input.int))
-      rescue IndexError
-        raise FormatError, "the state names a SID or a mode badline doesn't know"
-      end
-
-      def write(out)
-        out.string(model).int(SID_MODELS.index(sid_model)).int(MODES.index(mode))
+      def self.read_fields(input)
+        model = input.choice("model", C128::Model::ALL.map(&:name), "c128")
+        sid = input.choice("sid_model", SID_MODELS.map(&:to_s), "mos6581")
+        mode = input.choice("mode", MODES.map(&:to_s), "c64")
+        new(model:, sid_model: SID_MODELS.find { |name| name.to_s == sid } || :mos6581,
+            mode: MODES.find { |name| name.to_s == mode } || :c64)
       end
 
       # A machine built this way, at power-on.

data/lib/badline/snapshot/c64_setup.rb

@@ -9,7 +9,6 @@ module Badline
                            :board)
 
     class C64Setup
-      MARKER = "COMPUTER"
       SID_MODELS = %i[mos6581 mos8580].freeze
       REGIONS = [Region::PAL, Region::NTSC, Region::NTSC_OLD, Region::DREAN].freeze
       RAM_EXPANSIONS = [:none, *C64::BankedRAM::TYPES.keys].freeze
@@ -22,23 +21,6 @@ module Badline
             kernal: address_bus.kernal, datasette: address_bus.datasette.connected?, board: address_bus.board)
       end
 
-      # The setup a C64's State starts with.
-      def self.from(state)
-        input = StateReader.new(state)
-        input.marker(MARKER)
-        input.check_stamp
-        read(input)
-      end
-
-      def self.read(input)
-        new(vic_model: Chips::VIC::MODELS.fetch(input.int), cia_model: Chips::CIA::MODELS.fetch(input.int),
-            sid_model: SID_MODELS.fetch(input.int), region: REGIONS.fetch(input.int),
-            ram_expansion: ram_expansion(RAM_EXPANSIONS.fetch(input.int)), reu: reu(input.int),
-            kernal: KERNALS.fetch(input.int), datasette: input.boolean?, board: BOARDS.fetch(input.int))
-      rescue IndexError
-        raise FormatError, "the state names a chip model, region, RAM expansion, KERNAL or board badline doesn't know"
-      end
-
       def self.ram_expansion(name) = name == :none ? nil : name
 
       # An REU's size in K, written as 0 for none.
@@ -46,14 +28,36 @@ module Badline
         return nil if size_kb.zero?
         return size_kb if C64::REU::SIZES_KB.include?(size_kb)
 
-        raise FormatError, "the state names a #{size_kb}K REU, which badline doesn't build"
+        raise FormatError, "the snapshot names a #{size_kb}K REU, which badline doesn't build"
+      end
+
+      # The setup in a keyed snapshot module (Snapshot::Keyed), with each
+      # model, the region, the RAM expansion, the KERNAL and the board by
+      # name.
+      def write_fields(out)
+        out.text("vic_model", vic_model.to_s).text("cia_model", cia_model.to_s).text("sid_model", sid_model.to_s)
+        out.text("region", region.name.to_s).text("ram_expansion", (ram_expansion || :none).to_s)
+        out.int("reu_kb", reu || 0).text("kernal", kernal.to_s).bool("datasette", datasette)
+        out.text("board", board.to_s)
+      end
+
+      # The setup a keyed snapshot module names, a C64's at power-on for
+      # anything it leaves out or names that badline doesn't build.
+      def self.read_fields(input)
+        region = named(input, "region", REGIONS.map(&:name), :pal)
+        new(vic_model: named(input, "vic_model", Chips::VIC::MODELS, :mos6569),
+            cia_model: named(input, "cia_model", Chips::CIA::MODELS, :mos6526),
+            sid_model: named(input, "sid_model", SID_MODELS, :mos6581),
+            region: REGIONS.find { |each| each.name == region } || Region::PAL,
+            ram_expansion: ram_expansion(named(input, "ram_expansion", RAM_EXPANSIONS, :none)),
+            reu: reu(input.int("reu_kb", 0)), kernal: named(input, "kernal", KERNALS, :c64),
+            datasette: input.bool("datasette", true), board: named(input, "board", BOARDS, :c64))
       end
 
-      def write(out)
-        out.int(Chips::VIC::MODELS.index(vic_model)).int(Chips::CIA::MODELS.index(cia_model))
-        out.int(SID_MODELS.index(sid_model)).int(REGIONS.index(region))
-        out.int(RAM_EXPANSIONS.index(ram_expansion || :none)).int(reu || 0)
-        out.int(KERNALS.index(kernal)).boolean(datasette).int(BOARDS.index(board))
+      # The Symbol of `names` the text at `key` names.
+      def self.named(input, key, names, default)
+        text = input.choice(key, names.map(&:to_s), default.to_s)
+        names.find { |name| name.to_s == text } || default
       end
 
       # A machine built this way, at power-on.

data/lib/badline/snapshot/container.rb

@@ -4,6 +4,10 @@ require "zlib"
 
 module Badline
   module Snapshot
+    # A file that isn't a snapshot badline reads, is cut short, or is of a
+    # machine built another way.
+    class FormatError < StandardError; end
+
     # One module of a snapshot: its name, its version and its payload,
     # without the 22-byte module header.
     Section = Data.define(:name, :major, :minor, :data) do

data/lib/badline/snapshot/field_doc/markdown.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Badline
+  module Snapshot
+    module FieldDoc
+      # The doc's markdown: one table per module, of each key, its type and
+      # its default, with keys that differ only in a unit's number, such as
+      # voice1 to voice3, on one row.
+      class Markdown
+        NAMES = { "c64" => "C64", "vic20" => "VIC-20", "c128" => "C128" }.freeze
+        TAG_TYPES = { Keyed::INT => "int", Keyed::BOOL => "bool", Keyed::BYTES => "bytes", Keyed::INTS => "ints",
+                      Keyed::TEXT => "text" }.freeze
+
+        # A row: the key, the type, and the defaults each family whose
+        # machines read or write it reads it with.
+        Row = Struct.new(:key, :type, :defaults)
+
+        INTRO = <<~MARKDOWN
+          # Snapshot format
+
+          This file is generated by `rake snapshot:fields` from the code that
+          loads a snapshot. Don't edit it by hand. doc/snapshots.md covers
+          what a snapshot holds and which versions load.
+
+          A snapshot is a VICE `.vsf` container. The machine is in modules
+          named `BL-` plus a unit, each a deflated list of records: a key, a
+          type and a value. The types are `int` (a zigzag BER integer), `bool`,
+          `bytes`, `ints` (a list of integers) and `text`. A load skips a key
+          it doesn't know, and a key that isn't there leaves the value a
+          machine built afresh has: the default below. `word`, `byte` and
+          `int & 0x..` are ints cut to the latch's width. A text that lists
+          its values takes one of them. An optional int is absent when the
+          latch holds nothing. A true drive's modules are named from its
+          device number, `BL-D8` to `BL-D11`. Keys with `<N>` stand for each
+          numbered unit. A default of "written only" is a key the load
+          doesn't read, or reads only when the snapshot has it. Where the
+          machines differ, the default is given for each, and a key only
+          some of them have names them.
+        MARKDOWN
+
+        def initialize(loads)
+          @modules = {}
+          loads.each { |load| add(load) }
+        end
+
+        def to_s
+          sections = @modules.map do |name, rows|
+            families = rows.values.flat_map { |row| row.defaults.keys }.uniq
+            ["## #{name}", "", "Written by the #{families.map { |family| NAMES.fetch(family) }.join(', ')}.", "",
+             "| Key | Type | Default |", "| --- | --- | --- |",
+             *rows.values.map { |row| line(row, families) }].join("\n")
+          end
+          "#{INTRO}\n#{sections.join("\n\n")}\n"
+        end
+
+        private
+
+        def add(load)
+          load.fields.each do |name, fields|
+            numbered = numbered_keys(load.written[name].keys + fields.map(&:key))
+            fields.each { |field| note(name, numbered.fetch(field.key, field.key), field.type, load.family, field) }
+            read = fields.to_set(&:key)
+            load.written[name].each do |key, tag|
+              next if read.include?(key)
+
+              note(name, numbered.fetch(key, key), TAG_TYPES.fetch(tag, "?"), load.family, nil)
+            end
+          end
+        end
+
+        def note(name, key, type, family, field)
+          row = (@modules[name] ||= {})[key] ||= Row.new(key, type, {})
+          (row.defaults[family] ||= []) << (field ? brief(field.default, field.type) : "written only")
+        end
+
+        # Keys that differ only in a number, as the same key with <N>: each
+        # key whose number another key in the module shares the rest of.
+        def numbered_keys(keys)
+          groups = keys.uniq.group_by { |key| key.gsub(/(?<=[a-z])\d+(?=\.|\z)/, "<N>") }
+          groups.each_with_object({}) do |(general, members), numbered|
+            members.each { |key| numbered[key] = general } if members.length > 1
+          end
+        end
+
+        def line(row, families)
+          each = row.defaults.transform_values { |defaults| summary(defaults.uniq) }
+          default = if each.values.uniq.length == 1 && each.length == families.length then each.values.first
+                    else each.map { |family, value| "#{NAMES.fetch(family)}: #{value}" }.join("; ")
+                    end
+          "| `#{row.key}` | #{row.type} | #{default} |"
+        end
+
+        def summary(defaults) = defaults.length > 3 ? "varies" : defaults.join(" or ")
+
+        def brief(value, type)
+          case value
+          when nil then "absent"
+          when Array then list(value)
+          when String then type.start_with?("bytes") ? list(value.bytes) : value.inspect
+          else value.to_s
+          end
+        end
+
+        def list(values)
+          return values.inspect if values.length <= 8
+
+          values.uniq.length == 1 ? "#{values.length} × #{values.first}" : "#{values.length} values"
+        end
+      end
+    end
+  end
+end

data/lib/badline/snapshot/field_doc.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "badline"
+require "badline/c128"
+
+module Badline
+  module Snapshot
+    # doc/snapshot-format.md, written by running the code: each family's
+    # machine is saved with its attachments, and its modules loaded into a
+    # machine built the same way at power-on through Keyed::Recorders,
+    # which note every key read with its type and the value the new machine
+    # had, its default. `rake snapshot:fields` writes it, and a spec checks
+    # that the file matches.
+    module FieldDoc
+      PATH = File.expand_path("../../../doc/snapshot-format.md", __dir__)
+
+      # Modules read through Recorders.
+      class RecordingModules < Keyed::Modules
+        private
+
+        def parse(section) = Keyed::Recorder.parse(section)
+
+        def missing(name) = Keyed::Recorder.missing(name)
+      end
+
+      # One machine saved and loaded: the family it belongs to, and for
+      # each module the keys its records hold, with their tags, and the fields the load read.
+      Load = Data.define(:family, :written, :fields)
+
+      # The machines the doc is made from: each family at power-on, and the
+      # C64 with each kind of expansion, cartridge and media.
+      def self.machines
+        {
+          "c64" => [C64.new, C64.new(ram_expansion: :plus256k), C64.new(reu: 512), with_cartridge, with_trap_dos,
+                    with_tape, with_drive(:d64), with_drive(:d81)],
+          "vic20" => [Vic20.new, with_rom],
+          "c128" => [C128.new(mode: :c128), with_drive(:d71)]
+        }
+      end
+
+      def self.blank(length) = Array.new(length, 0)
+
+      def self.with_cartridge
+        chips = [0x8000, 0xa000].map do |address|
+          Storage::CRTFile::Chip.new(chip_type: 2, bank: 0, address:, data: blank(0x2000))
+        end
+        image = Storage::CRTFile::Image.new(hardware_type: 32, subtype: 0, exrom: 1, game: 0, name: "DOC", chips:)
+        C64.new.tap do |machine|
+          machine.attach_cartridge(C64::Cartridge.from_crt(Storage::CRTFile.new(bytes: Storage::CRTFile.encode(image))))
+        end
+      end
+
+      def self.with_trap_dos
+        C64.new.tap { |machine| machine.mount(Storage::D64Image.new("", read_only: true, bytes: blank(174_848))) }
+      end
+
+      def self.with_tape
+        bytes = "C64-TAPE-RAW".bytes + [1, 0, 0, 0, 4, 0, 0, 0, 0x30, 0x30, 0x30, 0x30]
+        C64.new.tap { |machine| machine.datasette.insert(Storage::TAP.new("", bytes:)) }
+      end
+
+      def self.with_drive(kind)
+        case kind
+        when :d81
+          C64.new.tap do |machine|
+            machine.plug_drive1581.insert(Drives::Model1581::Disk.new(Storage::D81Image.new("", bytes: blank(819_200))))
+          end
+        when :d71
+          C128.new(mode: :c128).tap do |machine|
+            image = Storage::D71Image.new("", bytes: blank(349_696))
+            machine.plug_true_drive.insert(Drives::Model1541::Disk.decode(image))
+          end
+        else
+          C64.new.tap do |machine|
+            image = Storage::D64Image.new("", bytes: blank(174_848))
+            machine.plug_true_drive.insert(Drives::Model1541::Disk.decode(image))
+          end
+        end
+      end
+
+      def self.with_rom
+        Vic20.new.tap { |machine| machine.bus.map_rom(0xa000, blank(0x2000)) }
+      end
+
+      # Saves `machine` and loads it into a new one through Recorders.
+      def self.load(family, machine)
+        modules = RecordingModules.new(Image.of(machine).sections)
+        Image.setup(modules.machine).build.load_modules(modules)
+        modules.machine.text("written_by", "")
+        written = {}
+        fields = {}
+        modules.readers.each do |reader|
+          written[reader.name] = reader.tags
+          fields[reader.name] = reader.fields
+        end
+        Load.new(family:, written:, fields:)
+      end
+
+      def self.loads = machines.flat_map { |family, list| list.map { |machine| load(family, machine) } }
+
+      # The doc, as markdown.
+      def self.markdown(loads = self.loads) = Markdown.new(loads).to_s
+
+      def self.write(path = PATH) = File.write(path, markdown)
+    end
+  end
+end
+
+require "badline/snapshot/field_doc/markdown"