badline 0.9.0 → 0.10.1

data/lib/badline/options.rb

@@ -10,7 +10,9 @@ module Badline
   # The command line of both builds, badline-ruby and the native badline.
   # Either opens the window for any media, or with --headless or
   # --audio-out plays or renders a .sid tune without one. `sid`, given
-  # first, plays .sid tunes and directories of them in the terminal. The
+  # first, plays .sid tunes and directories of them in the terminal.
+  # `c64` or `vic20`, given first, names the machine family, and without
+  # either the family is the C64. The
   # native build adds --no-sound and --version, and badline-ruby adds
   # --disable-jit.
   #
@@ -37,6 +39,13 @@ module Badline
 
     REU_SIZES = %w[128 256 512 1024 2048 4096 8192 16384].freeze
 
+    # The VIC-20's RAM expansions as --ram names them (RAM_NAMES), and the
+    # names Vic20::Bus::RAM_CONFIGURATIONS gives them.
+    RAM_CONFIGURATIONS = {
+      "unexpanded" => :unexpanded, "3k" => :"3k", "8k" => :"8k", "16k" => :"16k", "24k" => :"24k",
+      "32k" => :"32k", "all" => :all
+    }.freeze
+
     # A Float as OptionParser took one: digits with an optional sign,
     # fraction and exponent.
     DECIMAL = /\A[-+]?(\d+(\.\d+)?|\.\d+)([eE][-+]?\d+)?\z/
@@ -46,6 +55,13 @@ module Badline
     attr_reader :program, :media_path, :tune_paths, :subtune, :sid_model, :reu, :frames, :screenshot, :save_snapshot,
                 :audio_out, :seconds, :songlengths, :filter_chunk, :timeline
 
+    # The machine family to build (Badline::Machine), :c64 or :vic20.
+    attr_reader :family
+
+    # The VIC-20's RAM expansion --ram names, a key of
+    # Vic20::Bus::RAM_CONFIGURATIONS, or nil without --ram.
+    attr_reader :ram
+
     def self.parse(argv, native: false) = new(native:).parse(argv)
 
     # The native build plays the SID in the window unless --no-sound says
@@ -55,12 +71,14 @@ module Badline
       @native = native
       @program = native ? "badline" : "badline-ruby"
       @media_path = nil
+      @family = :c64
       @sid_command = false
       @tune_paths = []
       @subtune = nil
       @sid_model = nil
       @models = []
       @reu = nil
+      @ram = nil
       @autostart = true
       @writable = false
       @sound = native
@@ -90,7 +108,7 @@ module Badline
 
     def parse(argv)
       args = argv.dup
-      sid_command(args) if args.first == "sid"
+      subcommand(args)
       argument(args.shift, args) until args.empty?
       play_lone_tune
       validate unless help? || version?
@@ -149,9 +167,9 @@ module Badline
 
     def jit? = @jit
 
-    # The name of the C64 to build (Badline::Model). --ntsc is short for
-    # --model ntsc.
-    def model = @models.empty? ? MODELS.first : @models.first
+    # The name of the model to build: a C64 Badline::Model names, or a
+    # VIC-20 of VIC20_MODELS. --ntsc is short for --model ntsc.
+    def model = @models.first || (@family == :vic20 ? VIC20_MODELS.first : MODELS.first)
 
     def help? = @help
 
@@ -165,15 +183,21 @@ module Badline
       [:both, @native ? :native : :ruby].include?(option.build)
     end
 
-    def sid_command(args)
+    # Takes `sid`, `c64` or `vic20` when given first.
+    def subcommand(args)
+      case args.first
+      when "sid" then @sid_command = true
+      when "c64" then @family = :c64
+      when "vic20" then @family = :vic20
+      else return
+      end
       args.shift
-      @sid_command = true
     end
 
     # A .sid on its own plays in the SID player, as `sid` would, unless an
     # option of the emulator's window asks for the machine.
     def play_lone_tune
-      return if @sid_command || headless? || !@window_only.empty? || @media_path.nil?
+      return if @sid_command || @family == :vic20 || headless? || !@window_only.empty? || @media_path.nil?
 
       @sid_command = File.extname(@media_path).casecmp?(".sid")
     end
@@ -226,6 +250,7 @@ module Badline
       when "--sid" then @sid_model = sid_model_for(value)
       when "--model" then @models << value
       when "--reu" then @reu = reu_size(value)
+      when "--ram" then @ram = ram_configuration(value)
       when "--frames" then @frames = number(flag, value)
       when "--screenshot" then @screenshot = value
       when "--save-snapshot" then @save_snapshot = value
@@ -259,31 +284,6 @@ module Badline
       end
     end
 
-    def sid_model_for(value)
-      return if value == "auto"
-      raise Error, "invalid argument: --sid #{value}" unless SID_MODELS.key?(value)
-
-      SID_MODELS[value]
-    end
-
-    def reu_size(value)
-      raise Error, "invalid argument: --reu #{value}" unless REU_SIZES.include?(value)
-
-      value.to_i
-    end
-
-    def number(flag, value)
-      raise Error, "invalid argument: #{flag} #{value}" unless value.match?(/\A\d+\z/)
-
-      value.to_i
-    end
-
-    def decimal(flag, value)
-      raise Error, "invalid argument: #{flag} #{value}" unless value.match?(DECIMAL)
-
-      value.to_f
-    end
-
     def media_argument(arg)
       raise Error, "unexpected argument: #{arg}" unless @sid_command || @media_path.nil?
 

data/lib/badline/roms/README

@@ -27,6 +27,30 @@ Downloaded from
 https://www.zimmers.net/anonftp/pub/cbm/firmware/computers/c64/kernal.sx.251104-04.bin
 SHA-1 aa136e91ecf3c5ac64f696b3dbcbfc5ba0871c98.
 
+kernal-pet64.rom
+----------------
+The KERNAL of the PET 64, 4064 and Educator 64, 901246-01. It boots
+with the "**** COMMODORE 4064  BASIC V2.0 ****" banner and a white
+cursor, and its interrupt routine keeps the border, background and
+sprite colours black unless bit 7 of $0286 is set. Computer.new(kernal:
+:pet64) fits it, as --model pet64 does.
+
+Downloaded from
+https://www.zimmers.net/anonftp/pub/cbm/firmware/computers/c64/kernal.4064.901246-01.bin
+MD5 da92801e3a03b005b746a4dd0b639c7c.
+
+c64gs.rom
+---------
+The C64GS's BASIC and KERNAL, 390852-01, 16 KB: BASIC for $A000-$BFFF
+followed by the KERNAL for $E000-$FFFF. Its BASIC is 901226-01's but
+for 30 unused bytes. Its KERNAL is 901227-03's with most changes in
+$F72C-$FC92, the cassette routines' place, and many jumps redirected to
+I/O error 5. Computer.new(kernal: :gs) fits both, as --model c64gs does.
+
+Downloaded from
+https://www.zimmers.net/anonftp/pub/cbm/firmware/computers/c64/64gs.390852-01.bin
+MD5 049e657afafbdd802e8c6a4f88f3d730.
+
 dos1541.rom
 -----------
 The 1541 disk drive's DOS 2.6, 16 KB for $C000-$FFFF: 325302-01
@@ -36,3 +60,30 @@ Both halves downloaded from
 https://www.zimmers.net/anonftp/pub/cbm/firmware/drives/new/1541/
 (1541-c000.325302-01.bin and 1541-e000.901229-05.bin) and concatenated.
 SHA-1 ab16f56989b27d89babe5f89c5a8cb3da71a82f0.
+
+Commodore VIC-20 ROMs
+=====================
+
+Downloaded from
+https://www.zimmers.net/anonftp/pub/cbm/firmware/computers/vic20/
+Vic20::Bus maps them.
+
+vic20/basic.rom
+---------------
+VIC-20 BASIC V2, 901486-01, for $C000-$DFFF.
+SHA-1 587d1e90950675ab6b12d91248a3f0d640d02e8d.
+
+vic20/kernal-pal.rom
+--------------------
+The PAL KERNAL, 901486-07, for $E000-$FFFF.
+SHA-1 ce0137ed69f003a299f43538fa9eee27898e621e.
+
+vic20/kernal-ntsc.rom
+---------------------
+The NTSC KERNAL, 901486-06, for $E000-$FFFF.
+SHA-1 06de7ec017a5e78bd6746d89c2ecebb646efeb19.
+
+vic20/character.rom
+-------------------
+The character generator ROM, 901460-03, for $8000-$8FFF.
+SHA-1 4fd85ab6647ee2ac7ba40f729323f2472d35b9b4.

data/lib/badline/snapshot/container.rb

@@ -26,6 +26,8 @@ module Badline
       FORMAT_MINOR = 0
       # x64sc names its machine C64SC, and refuses a snapshot naming another.
       MACHINE = "C64SC"
+      # xvic names its machine VIC20.
+      VIC20 = "VIC20"
       GZIP_MAGIC = "\x1f\x8b".b
 
       # The VICE version block, when VICE wrote the file: four version

data/lib/badline/snapshot/image.rb

@@ -28,11 +28,16 @@ module Badline
       # modules badline reads. Yields a line for each thing left out, or
       # warns it without a block.
       def load(&)
+        return load_vic20(&) if vic20?
+
         computer = badline? ? opening { Computer.restored(state) } : Vice.setup(@container).build
         tell(badline? ? state_report(computer) : Vice::Restore.apply(@container, computer), &)
         computer
       end
 
+      # Whether the machine is a VIC-20, as the container names it.
+      def vic20? = @container.machine == Container::VIC20
+
       # Restores `computer` from the snapshot, and returns the Report. A
       # snapshot that fails leaves the machine as it was.
       def restore(computer, &)
@@ -45,6 +50,16 @@ module Badline
 
       def section = @container[MachineState::NAME]
 
+      # A VIC-20 restores from its BADLINE module alone. xvic's own modules
+      # aren't read.
+      def load_vic20(&)
+        raise FormatError, "badline reads only its own VIC-20 snapshots, not xvic's" unless badline?
+
+        machine = Vic20.restored(state)
+        tell(state_report(machine), &)
+        machine
+      end
+
       def tell(report)
         report.ignored.each { |line| block_given? ? yield(line) : warn("badline: #{line}") }
       end

data/lib/badline/snapshot/setup.rb

@@ -3,32 +3,36 @@
 module Badline
   module Snapshot
     # How a machine was built: its VIC, CIA and SID models, its region, its
-    # RAM expansion, the size of its REU, its KERNAL and whether it has a
-    # datasette, the arguments Computer.new takes. A State starts with them, so a machine to restore it into can
-    # be built first.
-    Setup = Data.define(:vic_model, :cia_model, :sid_model, :region, :ram_expansion, :reu, :kernal, :datasette)
+    # RAM expansion, the size of its REU, its KERNAL, whether it has a
+    # datasette and its board, the arguments Computer.new takes. A State
+    # starts with them, so a machine to restore it into can be built first.
+    Setup = Data.define(:vic_model, :cia_model, :sid_model, :region, :ram_expansion, :reu, :kernal, :datasette,
+                        :board)
 
     class Setup
       SID_MODELS = %i[mos6581 mos8580].freeze
       REGIONS = [Region::PAL, Region::NTSC, Region::NTSC_OLD, Region::DREAN].freeze
       RAM_EXPANSIONS = [:none, *RAMExpansion::TYPES.keys].freeze
       KERNALS = AddressBus::ROMs::KERNALS.keys.freeze
+      BOARDS = AddressBus::Fittings::BOARDS
 
       def self.of(address_bus)
         new(vic_model: address_bus.vic.model, cia_model: address_bus.cia1.model, sid_model: address_bus.sid.model,
             region: address_bus.region, ram_expansion: address_bus.ram_expansion.type, reu: address_bus.reu&.size_kb,
-            kernal: address_bus.kernal, datasette: address_bus.datasette.connected?)
+            kernal: address_bus.kernal, datasette: address_bus.datasette.connected?, board: address_bus.board)
       end
 
-      # Layout 3 has no KERNAL or datasette, and stands for the C64's.
+      # Layout 3 has no KERNAL or datasette, and stands for the C64's, and
+      # layouts before 6 have no board, and stand for the C64's.
       def self.read(input)
         new(vic_model: VIC::MODELS.fetch(input.int), cia_model: 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: input.schema > 3 ? KERNALS.fetch(input.int) : :c64,
-            datasette: input.schema > 3 ? input.boolean? : true)
+            datasette: input.schema > 3 ? input.boolean? : true,
+            board: input.schema > 5 ? BOARDS.fetch(input.int) : :c64)
       rescue IndexError
-        raise FormatError, "the state names a chip model, region, RAM expansion or KERNAL badline doesn't know"
+        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
@@ -45,12 +49,12 @@ module Badline
         out.int(VIC::MODELS.index(vic_model)).int(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)
+        out.int(KERNALS.index(kernal)).boolean(datasette).int(BOARDS.index(board))
       end
 
       # A machine built this way, at power-on.
       def build
-        Computer.new(vic_model:, cia_model:, sid_model:, region:, ram_expansion:, reu:, kernal:, datasette:)
+        Computer.new(vic_model:, cia_model:, sid_model:, region:, ram_expansion:, reu:, kernal:, datasette:, board:)
       end
 
       # The chips, led by the model's name when they make one of
@@ -63,6 +67,7 @@ module Badline
         parts << "a #{reu}K REU" if reu
         parts << "the #{kernal} KERNAL" unless kernal == :c64
         parts << "no datasette" unless datasette
+        parts << "the #{board} board" unless board == :c64
         parts.join(", ")
       end
     end

data/lib/badline/snapshot/state.rb

@@ -14,9 +14,11 @@ module Badline
       # The layout the chips write their fields in. It goes up whenever a
       # save_state writes something else, so a State in another layout
       # fails before anything is read into a machine. Layout 3, without the
-      # KERNAL and datasette in the setup, still reads.
-      SCHEMA = 4
-      READABLE = [3, SCHEMA].freeze
+      # KERNAL and datasette in the setup, layout 4, without the VIA shift
+      # register's clock delay, and layout 5, without the board in the
+      # setup, still read.
+      SCHEMA = 6
+      READABLE = [3, 4, 5, SCHEMA].freeze
 
       attr_reader :values, :strings
 

data/lib/badline/snapshot/vice.rb

@@ -69,7 +69,8 @@ module Badline
         reu = nil unless reu && REU1764.reads?(reu)
         Setup.new(vic_model: model, cia_model: model == :mos8565 ? :mos6526a : :mos6526, sid_model: sid,
                   region: vic ? VICII.region(vic) : Region::PAL, ram_expansion: nil,
-                  reu: reu ? REU1764.size_kb(reu) : nil, kernal: :c64, datasette: true)
+                  reu: reu ? REU1764.size_kb(reu) : nil, kernal: :c64, datasette: true,
+                  board: :c64)
       end
     end
   end

data/lib/badline/snapshot.rb

@@ -27,8 +27,12 @@ module Badline
       path
     end
 
+    # A VIC-20's snapshot holds the BADLINE module alone, in a container
+    # named as xvic names its machine.
     def dump(computer)
       state = computer.snapshot
+      return Container.new([MachineState.section(state)], machine: Container::VIC20).to_s if computer.family == :vic20
+
       Container.new(Vice.export(state) + [MachineState.section(state)]).to_s
     end
 
@@ -49,4 +53,10 @@ module Badline
 
     def restore_snapshot(path, &) = Snapshot.restore(self, path, &)
   end
+
+  class Vic20
+    def save_snapshot(path) = Snapshot.save(self, path)
+
+    def restore_snapshot(path, &) = Snapshot.restore(self, path, &)
+  end
 end

data/lib/badline/storage/crt_file.rb

@@ -6,13 +6,14 @@ module Badline
       class FormatError < StandardError; end
 
       SIGNATURE = "C64 CARTRIDGE   ".b
+      VIC20_SIGNATURE = "VIC20 CARTRIDGE ".b
       CHIP_SIGNATURE = "CHIP".b
       CHIP_HEADER_SIZE = 0x10
       RAM_CHIP = 1
 
       Chip = Data.define(:chip_type, :bank, :address, :data)
 
-      attr_reader :hardware_type, :subtype, :exrom, :game, :name, :chips
+      attr_reader :machine, :hardware_type, :subtype, :exrom, :game, :name, :chips
 
       # What .write needs of an image: the fields a parsed CRTFile reads.
       Image = Data.define(:hardware_type, :subtype, :exrom, :game, :name, :chips)
@@ -33,16 +34,19 @@ module Badline
         header + packets.join
       end
 
-      # `bytes` stands in for the file's contents.
-      def initialize(path = nil, bytes: nil)
+      # `bytes` stands in for the file's contents. `machine` is the one the
+      # image has to be for, :c64 or :vic20, or nil for either.
+      def initialize(path = nil, bytes: nil, machine: :c64)
         parse(bytes || File.binread(path))
+        return if machine.nil? || @machine == machine
+
+        raise FormatError, "Cartridge image is for the #{@machine}, not the #{machine}"
       end
 
       private
 
       def parse(bytes)
-        raise FormatError, "Missing CRT signature" unless bytes.start_with?(SIGNATURE)
-
+        @machine = signed_machine(bytes)
         @hardware_type = bytes[0x16, 2].unpack1("n")
         @exrom = bytes.getbyte(0x18)
         @game = bytes.getbyte(0x19)
@@ -51,6 +55,13 @@ module Badline
         @chips = parse_chips(bytes, bytes[0x10, 4].unpack1("N"))
       end
 
+      def signed_machine(bytes)
+        return :c64 if bytes.start_with?(SIGNATURE)
+        return :vic20 if bytes.start_with?(VIC20_SIGNATURE)
+
+        raise FormatError, "Missing CRT signature"
+      end
+
       # Trailing bytes too short to hold a CHIP header are ignored.
       def parse_chips(bytes, offset)
         chips = []

data/lib/badline/storage/disk_image.rb

@@ -36,6 +36,9 @@ module Badline
         @errors = split_error_table
       end
 
+      # The host file's path, as it was opened.
+      attr_reader :path
+
       # Whether the image was opened write-protected.
       def read_only? = @read_only
 

data/lib/badline/storage/host_directory.rb

@@ -10,6 +10,9 @@ module Badline
       NO_SYNC = 21
       ID = "DIR".bytes.freeze
 
+      # The directory's path, as it was opened.
+      attr_reader :path
+
       def initialize(path)
         @path = path
       end

data/lib/badline/storage/t64.rb

@@ -20,6 +20,9 @@ module Badline
         raise FormatError, "Missing T64 signature" unless @bytes[0, 3] == SIGNATURE
       end
 
+      # The host file's path, as it was opened.
+      attr_reader :path
+
       # What Storage.reopen needs to open the archive again: its path and
       # its bytes.
       def save_setup(out)

data/lib/badline/storage/tap.rb

@@ -3,9 +3,9 @@
 module Badline
   module Storage
     # Raw datasette pulse stream. The header holds the signature, the
-    # version at $0c and the data size at $10; the data runs from $14, every
-    # byte the time to the next falling edge on the tape read line, in units
-    # of 8 cycles.
+    # version at $0c, the platform at $0d (0 C64, 1 VIC-20, 2 C16) and the
+    # data size at $10; the data runs from $14, every byte the time to the
+    # next falling edge on the tape read line, in units of 8 cycles.
     class TAP
       class FormatError < StandardError; end
 
@@ -14,7 +14,14 @@ module Badline
       OVERFLOW = 0x100 * 8
 
       # The file it was read from, expanded, and the file's bytes.
-      attr_reader :version, :path, :bytes
+      attr_reader :version, :platform, :path, :bytes
+
+      # A blank version 1 tape for `platform` (0 C64, 1 VIC-20) at `path`,
+      # written to the host file.
+      def self.create(path, platform:)
+        File.binwrite(path, (SIGNATURE + [1, platform, 0, 0, 0, 0, 0, 0]).pack("C*"))
+        new(path)
+      end
 
       # `bytes` stands in for the host file's contents, as a snapshot
       # restores the tape it holds.
@@ -26,6 +33,8 @@ module Badline
         @version = @bytes[0x0c].to_i
         raise FormatError, "Unsupported TAP version #{@version}" if @version > 1
 
+        @platform = @bytes[0x0d].to_i
+
         @end = tape_end
         rewind
       end
@@ -43,6 +52,31 @@ module Badline
 
       def end? = @pos >= @end
 
+      # Records a pulse `cycles` long at the position, in place of the rest
+      # of the tape: a byte of units of 8 cycles, or a zero and the 24-bit
+      # cycle count for a long one (a lone zero, an overflow, on a version 0
+      # tape).
+      def record_pulse(cycles)
+        units = (cycles + 4) / 8
+        encoded = if units.between?(1, 0xff) then [units]
+                  elsif version.zero? then [0]
+                  else
+                    count = [cycles, 0xffffff].min
+                    [0, count & 0xff, (count >> 8) & 0xff, count >> 16]
+                  end
+        @bytes.slice!(@pos..)
+        @bytes.concat(encoded)
+        @pos = @end = @bytes.length
+      end
+
+      # Writes the tape back to its host file, with the data size the
+      # header states.
+      def save
+        size = @bytes.length - HEADER_SIZE
+        @bytes[0x10, 4] = [size & 0xff, (size >> 8) & 0xff, (size >> 16) & 0xff, size >> 24]
+        File.binwrite(@path, @bytes.pack("C*"))
+      end
+
       # Cycles until the next falling edge, or nil once the tape has run out.
       def next_pulse
         return if end?

data/lib/badline/storage/unavailable.rb

@@ -6,6 +6,8 @@ module Badline
     # (Snapshot::StateReader): it finds no files and refuses every write
     # as a write-protected disk does.
     class Unavailable
+      def path = ""
+
       def read_file(_name, **) = nil
 
       def write_file(_name, _bytes, **)

data/lib/badline/timing.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Badline
+  # = Timing
+  #
+  # What a front end needs to run a machine's frames and show them: the CPU
+  # clock, the raster's cycles per line and lines per frame, and the
+  # [left, top, width, height] of the raster it shows, and how many of the
+  # window's square pixels wide each of its pixels shows. Each machine
+  # derives it from its region.
+  Timing = Data.define(:clock_hz, :cycles_per_line, :lines_per_frame, :crop, :pixel_width)
+end

data/lib/badline/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Badline
-  VERSION = "0.9.0"
+  VERSION = "0.10.1"
 end