badline 0.6.0 → 0.7.0

data/lib/badline/options.rb

@@ -1,102 +1,137 @@
 # frozen_string_literal: true
 
-require "optparse"
+require "badline/options/option"
+require "badline/options/event"
+require "badline/options/table"
+require "badline/options/help"
+require "badline/options/validation"
 
 module Badline
-  # The command line of `badline-ruby`. It opens the window for any media,
-  # or with --headless or --audio-out plays or renders a .sid tune without
-  # one. It loads nothing else from badline, so the executable can parse
-  # and reject its arguments before paying for the emulator.
+  # 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
+  # native build adds --no-sound and --version, and badline-ruby adds
+  # --disable-jit.
+  #
+  # TABLE lists the options, and both the parser and the help read it. It
+  # parses by hand, inside the subset of Ruby Spinel compiles. Values come
+  # as `--subtune 2` or `--subtune=2`, and `--` ends the options. It loads
+  # nothing else from badline, so badline-ruby can parse and reject its
+  # arguments before paying for the emulator.
   class Options
+    include Validation
+
     class Error < StandardError; end
 
     FALLBACK_SECONDS = 60.0
 
-    DEFAULT_RATE = 44_100
+    # A tune on the fallback length ends sooner once it has been silent
+    # this long.
+    SILENCE_SECONDS = 5.0
 
     SID_MODELS = { "6581" => :mos6581, "8580" => :mos8580 }.freeze
 
-    BANNER = <<~BANNER.freeze
-      Usage: badline-ruby [options] [media]
-             badline-ruby --headless [options] tune.sid
-             badline-ruby [options] tune.sid --audio-out FILE
-
-      Media can be a .prg/.p00 program, a .d64/.d71/.d81 disk image, a
-      .g64 disk image for the true 1541, a .t64 tape archive, a .tap
-      tape, a .crt cartridge, a .sid tune, a .vsf snapshot, or a directory
-      to mount as device 8. It opens in the emulator window, where F11
-      saves a snapshot and F12 restores it. Device 8 answers through
-      traps on the KERNAL's disk routines, unless --true-drive puts an
-      emulated 1541 there, which runs its own DOS and reads .d64 and .g64
-      images only.
-
-      --headless plays a .sid tune on the host's audio device without the
-      window, and --audio-out renders it to 16-bit PCM instead. The
-      container follows the file's extension, .wav or .aiff. Played on a
-      terminal, n or → skips to the next song, p or ← to the previous one,
-      space pauses and q quits.
-
-      A .sid file carries no length of its own. Without --seconds the tune is
-      looked up by MD5 in HVSC's Songlengths.md5, taken from --songlengths, from
-      the DOCUMENTS directory of an HVSC collection above the tune, or from
-      $HVSC_BASE. Failing all of those it runs for #{FALLBACK_SECONDS.to_i} seconds.
-
-      Without the window, PSID tunes run on a bare CPU and SID, faster than
-      real time. RSID tunes boot the whole machine and run at about half
-      real time, so they stutter when played. --filter-chunk 1 runs the
-      filter cycle by cycle, which is exact but takes about twice as long.
-
-    BANNER
-
-    attr_reader :media_path, :audio_out, :song, :seconds, :songlengths, :sid_model, :filter_chunk, :reu
-
-    alias tune_path media_path
-
-    def self.parse(argv) = new.parse(argv)
-
-    def initialize
+    # What `sid` leaves out besides the window's options.
+    NOT_FOR_SID = %w[--audio-out].freeze
+
+    REU_SIZES = %w[128 256 512 1024 2048 4096 8192 16384].freeze
+
+    # A Float as OptionParser took one: digits with an optional sign,
+    # fraction and exponent.
+    DECIMAL = /\A[-+]?(\d+(\.\d+)?|\.\d+)([eE][-+]?\d+)?\z/
+
+    # tune_paths holds the media given, which `sid` takes more than one of:
+    # tunes and directories of tunes, in the order given.
+    attr_reader :program, :media_path, :tune_paths, :subtune, :sid_model, :reu, :frames, :screenshot, :save_snapshot,
+                :audio_out, :seconds, :songlengths, :filter_chunk, :timeline
+
+    def self.parse(argv, native: false) = new(native:).parse(argv)
+
+    # The native build plays the SID in the window unless --no-sound says
+    # otherwise, and badline-ruby, which runs below real time, only with
+    # --sound.
+    def initialize(native: false)
+      @native = native
+      @program = native ? "badline" : "badline-ruby"
+      @media_path = nil
+      @sid_command = false
+      @tune_paths = []
+      @subtune = nil
+      @sid_model = nil
+      @reu = nil
       @autostart = true
       @read_only = false
-      @sound = false
+      @sound = native
+      @frames = 0
+      @paced = true
+      @vsync = true
       @verbose = false
       @true_drive = false
       @ntsc = false
-      @headless = false
+      @screenshot = ""
+      @save_snapshot = ""
+      @timeline = []
       @jit = true
+      @help = false
+      @version = false
+      @headless = false
+      @audio_out = nil
+      @seconds = nil
+      @songlengths = nil
+      @rate = nil
+      @filter_chunk = nil
       @quiet = false
       @tui = true
-      @help = false
+      @all_subtunes = false
       @window_only = []
       @headless_only = []
     end
 
     def parse(argv)
-      @media_path, *extra = parser.parse(argv)
-      raise Error, "unexpected argument: #{extra.first}" if extra.any?
-
-      validate unless help?
+      args = argv.dup
+      sid_command(args) if args.first == "sid"
+      argument(args.shift, args) until args.empty?
+      play_lone_tune
+      validate unless help? || version?
       self
-    rescue OptionParser::ParseError => e
-      raise Error, e.message
     end
 
+    # Whether the media is a .vsf snapshot to restore.
+    def snapshot? = !@media_path.nil? && File.extname(@media_path).casecmp?(".vsf")
+
     # Plays or renders a .sid tune without the window.
-    def headless? = @headless || render?
+    def headless? = @headless || render? || @sid_command
+
+    # Whether `sid` came first, to play the tunes and directories given.
+    def sid_command? = @sid_command
+
+    # Whether `sid` plays in the SID player's window rather than the
+    # terminal.
+    def player_window? = @sid_command && !@headless
 
     def window? = !headless?
 
-    def render? = !audio_out.nil?
+    def render? = !@audio_out.nil?
 
-    def rate = @rate || DEFAULT_RATE
+    # The tune --headless and --audio-out play, for Audio::CLI.
+    def tune_path = @media_path
 
     # How long to play a tune whose length nothing gives.
     def fallback_seconds = FALLBACK_SECONDS
 
+    # How long a tune playing for fallback_seconds may stay silent.
+    def silence_seconds = SILENCE_SECONDS
+
+    def rate = @rate.nil? ? DEFAULT_RATE : @rate
+
     def rate_given? = !@rate.nil?
 
-    def help = parser.help
+    def quiet? = @quiet
 
-    def help? = @help
+    def tui? = @tui
+
+    def all_subtunes? = @all_subtunes
 
     def autostart? = @autostart
 
@@ -104,133 +139,153 @@ module Badline
 
     def sound? = @sound
 
+    def paced? = @paced
+
+    def vsync? = @vsync
+
     def verbose? = @verbose
 
     def true_drive? = @true_drive
 
     def ntsc? = @ntsc
 
-    def quiet? = @quiet
+    def jit? = @jit
 
-    def tui? = @tui
+    def help? = @help
 
-    def jit? = @jit
+    def version? = @version
 
     private
 
-    def validate
-      validate_mode
-      validate_numbers
-      validate_paths
+    def takes?(option)
+      return false if @sid_command && (option.needs == :window || NOT_FOR_SID.include?(option.name))
+
+      [:both, @native ? :native : :ruby].include?(option.build)
     end
 
-    def validate_mode
-      if headless?
-        raise Error, "#{@window_only.first} needs the window" if @window_only.any?
-        raise Error, "no tune given" unless media_path
-        raise Error, "not a .sid tune: #{media_path}" unless File.extname(media_path).casecmp?(".sid")
-      elsif @headless_only.any?
-        raise Error, "#{@headless_only.first} needs --headless or --audio-out"
-      end
+    def sid_command(args)
+      args.shift
+      @sid_command = true
     end
 
-    def validate_numbers
-      raise Error, "invalid argument: --song #{song}" if song&.< 1
-      raise Error, "invalid argument: --seconds #{seconds}" unless seconds.nil? || seconds.positive?
-      raise Error, "invalid argument: --rate #{rate}" unless rate.positive?
-      raise Error, "invalid argument: --filter-chunk #{filter_chunk}" if filter_chunk&.< 1
+    # 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?
+
+      @sid_command = File.extname(@media_path).casecmp?(".sid")
     end
 
-    def validate_paths
-      [media_path, songlengths].compact.each do |path|
-        raise Error, "no such file or directory: #{path}" unless File.exist?(path)
+    def argument(arg, args)
+      if arg == "--"
+        media_argument(args.shift) until args.empty?
+      elsif arg.start_with?("-") && arg != "-"
+        option(arg, args)
+      else
+        media_argument(arg)
       end
     end
 
-    def parser
-      @parser ||= OptionParser.new do |opts|
-        opts.banner = BANNER
-        opts.separator "Options:"
-        define_media_options(opts)
-        opts.separator ""
-        opts.separator "Window options:"
-        define_window_options(opts)
-        opts.separator ""
-        opts.separator "Options without the window:"
-        define_headless_options(opts)
+    def option(arg, args)
+      flag = arg.start_with?("--") && arg.include?("=") ? arg[0, arg.index("=")] : arg
+      option = find(flag)
+      restrict(option, flag)
+      if flag == arg
+        option.valued? ? valued_option(option.name, flag, take_value(flag, args)) : switch(option.name)
+      elsif option.valued?
+        valued_option(option.name, flag, arg[flag.size + 1, arg.size - flag.size - 1])
+      else
+        raise Error, "needless argument: #{arg}"
       end
     end
 
-    def define_media_options(opts)
-      opts.on("-s", "--song N", Integer, "Subtune of a .sid, from 1 (default: the tune's own)") { |n| @song = n }
-      opts.on("--sid MODEL", SID_MODELS,
-              "SID to fit: 6581 or 8580 (default: a .sid tune's own, else 6581)") { |model| @sid_model = model }
-      opts.on("--disable-jit", "Run without enabling YJIT") { @jit = false }
-      opts.on("-h", "--help", "Show this help") { @help = true }
+    def find(flag)
+      option = TABLE.find { |candidate| candidate.named?(flag) && takes?(candidate) }
+      raise Error, "invalid option: #{flag}" if option.nil?
+
+      option
     end
 
-    def define_window_options(opts)
-      opts.on("--no-autostart", "Boot to READY. instead of running the program") do
-        window_only("--no-autostart") { @autostart = false }
-      end
-      opts.on("--read-only", "Mount a disk image write-protected, leaving its file unchanged") do
-        window_only("--read-only") { @read_only = true }
-      end
-      opts.on("--sound", "Play the SID through the host's audio device (F10 mutes)") do
-        window_only("--sound") { @sound = true }
-      end
-      opts.on("--true-drive", "Put a true 1541 on device 8 instead of the KERNAL traps") do
-        window_only("--true-drive") { @true_drive = true }
-      end
-      opts.on("--reu SIZE", %w[128 256 512 1024 2048 4096 8192 16384],
-              "Plug in an REU of SIZE K: 128, 256, 512 (a 1750) or up to 16384") do |size|
-        window_only("--reu") { @reu = size.to_i }
-      end
-      opts.on("--ntsc", "Run an NTSC C64, with the 6567R8 VIC-II, instead of a PAL one") do
-        window_only("--ntsc") { @ntsc = true }
-      end
-      opts.on("--verbose", "Print the display, sound and gamepad setup and the frame timing") do
-        window_only("--verbose") { @verbose = true }
-      end
+    # Notes an option only the window or only the headless player takes.
+    def restrict(option, flag)
+      @window_only << flag if option.needs == :window
+      @headless_only << flag if option.needs == :headless
     end
 
-    def define_headless_options(opts)
-      opts.on("--headless", "Play a .sid tune in the terminal instead of the window") { @headless = true }
-      opts.on("--audio-out FILE", "Render a .sid tune to a .wav or .aiff file") { |path| @audio_out = path }
-      define_length_options(opts)
-      define_rendering_options(opts)
-      opts.on("--quiet", "Don't report progress") { headless_only("--quiet") { @quiet = true } }
-      opts.on("--no-tui", "Play without the interactive display, even on a terminal") do
-        headless_only("--no-tui") { @tui = false }
-      end
+    def take_value(flag, args)
+      raise Error, "missing argument: #{flag}" if args.empty?
+
+      args.shift
     end
 
-    def define_length_options(opts)
-      opts.on("--seconds N", Float, "Length to play (default: the tune's own)") do |n|
-        headless_only("--seconds") { @seconds = n }
-      end
-      opts.on("--songlengths PATH", "HVSC Songlengths.md5 to take the length from") do |path|
-        headless_only("--songlengths") { @songlengths = path }
+    def valued_option(name, flag, value)
+      case name
+      when "--subtune" then @subtune = number(flag, value)
+      when "--sid" then @sid_model = sid_model_for(value)
+      when "--reu" then @reu = reu_size(value)
+      when "--frames" then @frames = number(flag, value)
+      when "--screenshot" then @screenshot = value
+      when "--save-snapshot" then @save_snapshot = value
+      when "--at", "--script" then @timeline.concat(Event.given(name, value))
+      when "--audio-out" then @audio_out = value
+      when "--seconds" then @seconds = decimal(flag, value)
+      when "--songlengths" then @songlengths = value
+      when "--rate" then @rate = number(flag, value)
+      else @filter_chunk = number(flag, value)
       end
     end
 
-    def define_rendering_options(opts)
-      opts.on("--rate HZ", Integer, "Sample rate (default: #{DEFAULT_RATE}, or the audio device's own)") do |n|
-        headless_only("--rate") { @rate = n }
-      end
-      opts.on("--filter-chunk N", Integer, "Filter step in cycles, 1 is exact (default: 4)") do |n|
-        headless_only("--filter-chunk") { @filter_chunk = n }
+    def switch(name)
+      case name
+      when "--no-autostart" then @autostart = false
+      when "--read-only" then @read_only = true
+      when "--sound" then @sound = true
+      when "--no-sound" then @sound = false
+      when "--no-vsync" then @vsync = false
+      when "--verbose" then @verbose = true
+      when "--true-drive" then @true_drive = true
+      when "--ntsc" then @ntsc = true
+      when "--unpaced" then @paced = false
+      when "--disable-jit" then @jit = false
+      when "--help" then @help = true
+      when "--version" then @version = true
+      when "--headless" then @headless = true
+      when "--quiet" then @quiet = true
+      when "--all-subtunes" then @all_subtunes = true
+      else @tui = false
       end
     end
 
-    def window_only(flag)
-      @window_only << flag
-      yield
+    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 headless_only(flag)
-      @headless_only << flag
-      yield
+    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?
+
+      @media_path = arg if @media_path.nil?
+      @tune_paths << arg
     end
   end
 end

data/lib/badline/reu/dma/saved_state.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Badline
+  class REU
+    class DMA
+      # A transfer's state for a snapshot (REU::SavedState).
+      module SavedState
+        # Everything a transfer holds between cycles. Before the first
+        # transfer, the fields it sets on starting are empty.
+        def save_state(out)
+          out.int(@c64).int(@expansion).int(@length).int(@events)
+          [@type, @c64_step, @expansion_step, @last, @ba_low_after_writes, @swap_byte, @held_read].each do |value|
+            out.optional_int(value)
+          end
+          [@holding, @waiting, @stopped_after_write, @swap_write_due, @swap_read_again, @moved_all,
+           @extra_cycle].each do |flag|
+            out.boolean(flag)
+          end
+        end
+
+        def load_state(input)
+          @c64 = input.int
+          @expansion = input.int
+          @length = input.int
+          @events = input.int
+          load_steps(input)
+          @holding = input.boolean?
+          @waiting = input.boolean?
+          @stopped_after_write = input.boolean?
+          @swap_write_due = input.boolean?
+          @swap_read_again = input.boolean?
+          @moved_all = input.boolean?
+          @extra_cycle = input.boolean?
+        end
+
+        private
+
+        def load_steps(input)
+          @type = input.optional_int
+          @c64_step = input.optional_int
+          @expansion_step = input.optional_int
+          @last = input.optional_int
+          @ba_low_after_writes = input.optional_int
+          @swap_byte = input.optional_int
+          @held_read = input.optional_int
+        end
+      end
+    end
+  end
+end

data/lib/badline/reu/dma.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "badline/reu/dma/saved_state"
+
 module Badline
   class REU
     # One transfer between the C64 and the REU's RAM, clocked a cycle at a
@@ -8,6 +10,8 @@ module Badline
     # After a write it goes on through the first BA-low cycle and stops at
     # the second. See doc/pinned-behaviour.md, REU DMA.
     class DMA
+      include SavedState
+
       # Transfer types, as the command register's bottom two bits give
       # them.
       STASH = 0
@@ -52,16 +56,32 @@ module Badline
         @ba_low_after_writes = 0
         @stopped_after_write = false
         @swap_write_due = false
+        @swap_read_again = false
         @swap_byte = 0
         @held_read = 0
         @moved_all = false
         @extra_cycle = false
       end
 
+      # Writes the byte a fetch from these addresses starts with, without
+      # counting it. Other transfers start with a read.
+      def write_ahead(type, c64, expansion)
+        return unless type == FETCH
+
+        @c64 = c64
+        byte = @ram.peek(expansion)
+        @ram.latch = byte
+        write_c64(byte)
+      end
+
       # One cycle of the transfer. The cycle the REC lets go of the bus on
-      # is the CPU's.
-      def cycle!(ba_low)
-        note_ba(ba_low)
+      # is the CPU's. late says BA fell on this cycle but a REC that moved a
+      # byte on the last one doesn't see it yet (VIC#reu_ba_late?), and
+      # handed_on that BA runs on from a bad line's DMA into a sprite's
+      # here (VIC#reu_ba_handed_on?).
+      def cycle!(ba_low, late, handed_on)
+        note_ba(ba_low, late)
+        @swap_read_again ||= handed_on && @swap_write_due
         settle_held_read(ba_low) if @held_read.positive?
         return if @waiting && ba_low
 
@@ -69,60 +89,38 @@ module Badline
         @moved_all ? wind_down : move(ba_low)
       end
 
-      # Everything a transfer holds between cycles. Before the first
-      # transfer, the fields it sets on starting are empty.
-      def save_state(out)
-        out.int(@c64).int(@expansion).int(@length).int(@events)
-        [@type, @c64_step, @expansion_step, @last, @ba_low_after_writes, @swap_byte, @held_read].each do |value|
-          out.optional_int(value)
-        end
-        [@holding, @waiting, @stopped_after_write, @swap_write_due, @moved_all, @extra_cycle].each do |flag|
-          out.boolean(flag)
-        end
-      end
-
-      def load_state(input)
-        @c64 = input.int
-        @expansion = input.int
-        @length = input.int
-        @events = input.int
-        load_steps(input)
-        @holding = input.boolean?
-        @waiting = input.boolean?
-        @stopped_after_write = input.boolean?
-        @swap_write_due = input.boolean?
-        @moved_all = input.boolean?
-        @extra_cycle = input.boolean?
-      end
-
       private
 
-      def load_steps(input)
-        @type = input.optional_int
-        @c64_step = input.optional_int
-        @expansion_step = input.optional_int
-        @last = input.optional_int
-        @ba_low_after_writes = input.optional_int
-        @swap_byte = input.optional_int
-        @held_read = input.optional_int
-      end
-
       # The second BA-low cycle in a row after writes stops the REC, and so
       # does any BA-low cycle after a read. It then waits for BA to rise.
-      def note_ba(ba_low)
+      def note_ba(ba_low, late)
+        seen = ba_low && !late
         if @last == READ
-          @waiting = ba_low
+          note_ba_after_read(seen)
         elsif @last == WRITE
-          @ba_low_after_writes = ba_low ? @ba_low_after_writes + 1 : 0
-          @stopped_after_write = @ba_low_after_writes == 2
-          if @stopped_after_write
-            @waiting = true
-            @ba_low_after_writes = 0
-          end
+          note_ba_after_write(seen)
         end
         @last = IDLE
       end
 
+      # A swap's read that BA stops before its write is made again.
+      def note_ba_after_read(ba_low)
+        @waiting = ba_low
+        @ba_low_after_writes = 0
+        @swap_read_again = ba_low && @swap_write_due && @held_read.zero?
+      end
+
+      # A fetch's last write doesn't go through the first BA-low cycle.
+      # Pinned by REU/reutiming2/d and d2.
+      def note_ba_after_write(ba_low)
+        @ba_low_after_writes = ba_low ? @ba_low_after_writes + 1 : 0
+        @stopped_after_write = @ba_low_after_writes == 2 || (ba_low && @type == FETCH && @length == 1)
+        return unless @stopped_after_write
+
+        @waiting = true
+        @ba_low_after_writes = 0
+      end
+
       # A fetch or a swap whose last write ran into BA, or a verify that
       # found a difference before its last byte, takes one more cycle before
       # the REC lets go of the bus.
@@ -166,6 +164,8 @@ module Badline
       # Two cycles a byte: the C64's byte is read and stored while the
       # REU's is fetched, and the REU's is written to the C64 on the next.
       def swap(ba_low)
+        return read_swap_again if @swap_read_again
+
         if @swap_write_due
           @swap_write_due = false
           write_c64(@swap_byte)
@@ -196,6 +196,15 @@ module Badline
         @ba_low_after_writes = 0
       end
 
+      # A swap's read that BA cut off from its write is made again when BA
+      # rises, and the write follows it. Pinned by REU/reutiming2/e4-m2,
+      # e6-m2 and g3-m2.
+      def read_swap_again
+        @swap_read_again = false
+        @ram.poke(@expansion, read_c64)
+        @last = READ
+      end
+
       def settle_held_read(ba_low)
         @held_read -= 1
         return if @held_read.positive? && ba_low

data/lib/badline/reu/saved_state.rb

@@ -13,7 +13,7 @@ module Badline
         out.marker("REU")
         [@status, @command, @c64, @c64_start, @expansion, @expansion_start, @bank, @bank_start, @length,
          @length_start, @interrupt_mask, @address_control].each { |value| out.int(value) }
-        out.boolean(@armed).boolean(@requested).boolean(@running).boolean(@irq)
+        out.boolean(@armed).boolean(@requested).boolean(@running).boolean(@irq).boolean(@ba_was_low)
         @dma.save_state(out)
         @ram.save_state(out)
       end
@@ -27,6 +27,7 @@ module Badline
         @requested = input.boolean?
         @running = input.boolean?
         @irq = input.boolean?
+        @ba_was_low = input.boolean?
         @dma.load_state(input)
         @ram.load_state(input)
       end