badline 0.1.0 → 0.2.0

data/lib/badline/storage/sid_file.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Badline
+  module Storage
+    # PSID/RSID tunes: a memory image plus the addresses of the routines
+    # that initialise it and produce one frame of music.
+    class SIDFile
+      include IntegerHelper
+
+      class FormatError < StandardError; end
+
+      V1_HEADER_SIZE = 0x76
+
+      # The 6502 stub that starts a tune: call init with the song number,
+      # point the KERNAL's IRQ vector at a raster handler that calls play,
+      # and spin. Both calls are wrapped in the `$01` save, bank and restore
+      # that puts the tune's own RAM under the CPU.
+      #
+      # A tune owns all of zero page, so the stub never returns to whatever
+      # SYSed it: BASIC's READY loop reuses `$19-$21` and would overwrite the
+      # tune's variables between init and the first play.
+      #
+      #         jmp boot
+      # irq:    lda #$01
+      #         sta $d019
+      #         lda $01
+      #         pha
+      #         lda #iomap
+      #         sta $01
+      #         jsr play
+      #         pla
+      #         sta $01
+      #         jmp $ea31
+      # boot:   sei
+      #         lda $01
+      #         pha
+      #         lda #iomap
+      #         sta $01
+      #         lda #song
+      #         jsr init
+      #         pla
+      #         sta $01
+      #         lda #$7f
+      #         sta $dc0d
+      #         lda $dc0d
+      #         lda $d011
+      #         and #$7f
+      #         sta $d011
+      #         lda #$00
+      #         sta $d012
+      #         lda #$01
+      #         sta $d019
+      #         sta $d01a
+      #         lda #<irq
+      #         sta $0314
+      #         lda #>irq
+      #         sta $0315
+      #         cli
+      # idle:   jmp idle
+      class Driver
+        include IntegerHelper
+
+        IRQ_VECTOR = 0x0314
+        KERNAL_IRQ = 0xea31
+        CIA1_ICR = 0xdc0d
+        RASTER_IRQ_STATUS = 0xd019
+
+        def initialize(tune, song:, base:)
+          @tune = tune
+          @song = song
+          @base = base
+        end
+
+        def bytes
+          @bytes ||= playing? ? jmp(boot_address) + handler + boot : boot
+        end
+
+        private
+
+        def playing? = @tune.play_address.positive?
+
+        def handler_address = @base + jmp(0).length
+
+        def boot_address = playing? ? handler_address + handler.length : @base
+
+        def handler
+          @handler ||= lda_imm(0x01) + sta_abs(RASTER_IRQ_STATUS) +
+                       banked(@tune.play_address, jsr(@tune.play_address)) +
+                       jmp(KERNAL_IRQ)
+        end
+
+        def boot
+          start = [0x78] +
+                  banked(@tune.init_address, lda_imm(@song) + jsr(@tune.init_address)) +
+                  raster_irq + [0x58]
+          start + jmp(boot_address + start.length)
+        end
+
+        # Tunes live under the ROMs as often as not, so a call has to bank out
+        # whatever covers the routine first. The 6510 port at `$01` is RAM to
+        # nobody, so saving it across the call leaves the caller's banking —
+        # and with it the I/O the rest of the stub writes to — as it was.
+        def banked(address, call)
+          bank = @tune.bank_for(address)
+          return call unless bank
+
+          lda_zp(0x01) + [0x48] + lda_imm(bank) + sta_zp(0x01) +
+            call + [0x68] + sta_zp(0x01)
+        end
+
+        def raster_irq
+          return [] unless playing?
+
+          mask_cia1 + arm_raster + install_vector
+        end
+
+        # Leaves the raster as the only interrupt source.
+        def mask_cia1
+          lda_imm(0x7f) + sta_abs(CIA1_ICR) + lda_abs(CIA1_ICR)
+        end
+
+        def arm_raster
+          lda_abs(0xd011) + [0x29, 0x7f] + sta_abs(0xd011) +
+            lda_imm(0x00) + sta_abs(0xd012) +
+            lda_imm(0x01) + sta_abs(RASTER_IRQ_STATUS) + sta_abs(0xd01a)
+        end
+
+        def install_vector
+          lda_imm(low_byte(handler_address)) + sta_abs(IRQ_VECTOR) +
+            lda_imm(high_byte(handler_address)) + sta_abs(IRQ_VECTOR + 1)
+        end
+
+        def lda_imm(value) = [0xa9, value]
+        def lda_zp(addr) = [0xa5, addr]
+        def sta_zp(addr) = [0x85, addr]
+        def lda_abs(addr) = [0xad, low_byte(addr), high_byte(addr)]
+        def sta_abs(addr) = [0x8d, low_byte(addr), high_byte(addr)]
+        def jsr(addr) = [0x20, low_byte(addr), high_byte(addr)]
+        def jmp(addr) = [0x4c, low_byte(addr), high_byte(addr)]
+      end
+
+      attr_reader :format
+
+      def initialize(path)
+        @bytes = File.binread(path).bytes
+        @format = @bytes[0, 4].pack("C*")
+        raise FormatError, "Missing PSID or RSID signature" unless %w[PSID RSID].include?(@format)
+        raise FormatError, "Truncated header" if truncated?
+        raise FormatError, "No tune data" if data.empty?
+        raise FormatError, "Sidplayer MUS data, which needs a MUS player" if mus?
+        raise FormatError, "Written for #{sids} SIDs; only one is emulated" if sids > 1
+      end
+
+      def version = word(0x04)
+      def data_offset = word(0x06)
+      def play_address = word(0x0c)
+      def songs = [word(0x0e), 1].max
+      def start_song = word(0x10).clamp(1, songs)
+      def speed = (word(0x12) << 16) + word(0x14)
+      def name = text(0x16)
+      def author = text(0x36)
+      def released = text(0x56)
+      def flags = version > 1 ? word(V1_HEADER_SIZE) : 0
+      def init_address = word(0x0a).nonzero? || load_address
+      def end_address = load_address + data.length
+      def psid? = @format == "PSID"
+
+      # Flag bit 0 marks a PSID body as Compute's Sidplayer data rather than
+      # code.
+      def mus? = psid? && flags[0] == 1
+
+      # A v3 header can place a second SID at `$Dxx0` and a v4 header a
+      # third, each given by its middle byte: even, and in `$d420-$d7e0` or
+      # `$de00-$dfe0`. Anything else means the SID isn't there.
+      def sids
+        1 + [0x7a, 0x7b].first([version - 2, 0].max).count do |offset|
+          page = @bytes[offset].to_i
+          page.even? && ((0x42..0x7e).cover?(page) || (0xe0..0xfe).cover?(page))
+        end
+      end
+
+      # Flag bits 4-5 name the SID the tune was written for: 01 the 6581,
+      # 10 the 8580, 11 either and 00 unknown. Only an 8580-only tune gets one.
+      def sid_model = flags[4, 2] == 0b10 ? :mos8580 : :mos6581
+
+      # HVSC keys its song length database on the whole file, header and all.
+      def md5 = @md5 ||= Digest::MD5.hexdigest(@bytes.pack("C*"))
+
+      # The `$01` value a routine at `address` has to run under, following
+      # libsidplayfp's iomap: RAM under BASIC from `$a000`, RAM under both
+      # ROMs and no I/O for a routine in the I/O window itself, RAM under the
+      # KERNAL from `$e000`. An RSID tune banks itself and gets nil.
+      def bank_for(address)
+        return unless psid?
+        return 0x37 if address < 0xa000
+        return 0x36 if address < 0xd000
+        return 0x34 if address < 0xe000
+
+        0x35
+      end
+
+      # A zero load address puts the real one in the first two bytes of
+      # the body, PRG style.
+      def load_address
+        @load_address ||= word(0x08).nonzero? || uint16(body[0].to_i, body[1].to_i)
+      end
+
+      def data
+        @data ||= body.drop(word(0x08).zero? ? 2 : 0).first(0x10000 - load_address)
+      end
+
+      # A set speed bit asks for CIA timer pacing instead of a raster IRQ.
+      # The bare player honours it; the machine driver paces everything off
+      # the raster either way.
+      def cia_timed?(song = start_song)
+        speed[[song - 1, 31].min] == 1
+      end
+
+      def driver_address
+        @driver_address ||= candidates.find { |addr| !overlaps?(addr) } ||
+                            raise(FormatError, "No free RAM for the player")
+      end
+
+      def driver(song: start_song)
+        Driver.new(self, song: song.clamp(1, songs) - 1, base: driver_address).bytes
+      end
+
+      private
+
+      def truncated?
+        @bytes.length < V1_HEADER_SIZE || @bytes.length < data_offset
+      end
+
+      def body
+        @body ||= @bytes[data_offset..] || []
+      end
+
+      # The tape buffer and the free block below the stack page, neither
+      # of which BASIC touches.
+      def candidates
+        [relocation_address, 0x0334, 0x02a7].compact
+      end
+
+      def relocation_address
+        page = version > 1 ? @bytes[0x78].to_i : 0
+        return if page.zero? || page == 0xff
+
+        page << 8
+      end
+
+      def overlaps?(addr)
+        addr < end_address && load_address < addr + driver_size
+      end
+
+      def driver_size
+        @driver_size ||= Driver.new(self, song: 0, base: 0).bytes.length
+      end
+
+      def text(offset)
+        @bytes[offset, 32].take_while(&:positive?)
+                          .pack("C*")
+                          .force_encoding(Encoding::ISO_8859_1)
+                          .encode(Encoding::UTF_8)
+      end
+
+      # Header fields are big-endian, unlike everything else the 6502 sees.
+      def word(offset)
+        uint16(@bytes[offset + 1], @bytes[offset])
+      end
+    end
+  end
+end

data/lib/badline/storage/song_lengths.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Badline
+  module Storage
+    # HVSC's song length database. Each tune gets a comment naming its path
+    # and a line keyed by the MD5 of the whole `.sid` file, holding one
+    # `m:ss` time per song, optionally down to milliseconds:
+    #
+    #   ; /DEMOS/0-9/12th_Sector_Music.sid
+    #   c7c299ce06ec5ccffb2261fb11b42a73=4:33.108
+    #
+    # The file runs to well over a hundred thousand entries, so a lookup
+    # scans for its one key rather than building a table.
+    class SongLengths
+      class << self
+        # The database lives in the DOCUMENTS directory of an HVSC
+        # collection, so look for one above the tune, then wherever
+        # `$HVSC_BASE` points.
+        def locate(tune_path)
+          candidates(tune_path).find { |path| File.file?(path) }
+        end
+
+        private
+
+        def candidates(tune_path)
+          ancestors(File.dirname(File.expand_path(tune_path)))
+            .push(ENV.fetch("HVSC_BASE", nil))
+            .compact
+            .map { |dir| File.join(dir, "DOCUMENTS", "Songlengths.md5") }
+        end
+
+        def ancestors(dir)
+          dirs = []
+          until dirs.last == dir
+            dirs << dir
+            dir = File.dirname(dir)
+          end
+          dirs
+        end
+      end
+
+      def initialize(path)
+        @path = path
+      end
+
+      # The tune's per-song lengths in seconds, or nil when it isn't listed.
+      def lengths(md5)
+        prefix = "#{md5.downcase}="
+        File.foreach(@path) do |line|
+          next unless line.start_with?(prefix)
+
+          return line[prefix.length..].split.map { |time| seconds(time) }
+        end
+        nil
+      end
+
+      private
+
+      def seconds(time)
+        minutes, rest = time.split(":", 2)
+        rest ? (minutes.to_i * 60) + rest.to_f : minutes.to_f
+      end
+    end
+  end
+end

data/lib/badline/storage/t64.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Badline
+  module Storage
+    class T64
+      class FormatError < StandardError; end
+
+      SIGNATURE = "C64".bytes.freeze
+      HEADER_SIZE = 0x40
+      ENTRY_SIZE = 32
+      NORMAL_FILE = 1
+
+      def initialize(path)
+        @bytes = File.binread(path).bytes
+        raise FormatError, "Missing T64 signature" unless @bytes[0, 3] == SIGNATURE
+      end
+
+      def read_file(name, **)
+        pattern = Storage.matcher(name)
+        entry = entries.find { |e| pattern.match?(e[:name]) }
+        return unless entry
+
+        # Stated end addresses are frequently wrong; the slice stops at
+        # the end of the archive either way.
+        entry[:load] + (@bytes[entry[:offset], entry[:length]] || [])
+      end
+
+      def names
+        entries.map { |e| e[:name] }
+      end
+
+      private
+
+      def entries
+        @entries ||= (0...entry_count).filter_map { |i| entry_at(i) }
+      end
+
+      # Directory size ($22) and used count ($24) disagree in the wild.
+      def entry_count
+        [word(0x22), word(0x24)].max
+      end
+
+      def entry_at(index)
+        entry = @bytes[HEADER_SIZE + (index * ENTRY_SIZE), ENTRY_SIZE]
+        return unless entry&.length == ENTRY_SIZE && entry[0] == NORMAL_FILE
+
+        { name: decode_name(entry[16, 16]),
+          load: entry[2, 2],
+          offset: little_endian(entry[8, 4]),
+          length: little_endian(entry[4, 2]) - little_endian(entry[2, 2]) }
+      end
+
+      # Names are padded with spaces, though NUL padding also occurs.
+      def decode_name(bytes)
+        Storage.ascii(bytes).downcase.sub(/[ \0]+\z/, "")
+      end
+
+      def word(offset)
+        little_endian(@bytes[offset, 2])
+      end
+
+      def little_endian(bytes)
+        bytes.each_with_index.sum { |byte, i| byte << (8 * i) }
+      end
+    end
+  end
+end

data/lib/badline/storage/tap.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+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.
+    class TAP
+      class FormatError < StandardError; end
+
+      SIGNATURE = "C64-TAPE-RAW".bytes.freeze
+      HEADER_SIZE = 0x14
+      OVERFLOW = 0x100 * 8
+
+      attr_reader :version
+
+      def initialize(path)
+        @bytes = File.binread(path).bytes
+        raise FormatError, "Missing TAP signature" unless @bytes[0, SIGNATURE.length] == SIGNATURE
+
+        @version = @bytes[0x0c].to_i
+        raise FormatError, "Unsupported TAP version #{@version}" if @version > 1
+
+        @end = tape_end
+        rewind
+      end
+
+      def rewind
+        @pos = HEADER_SIZE
+      end
+
+      def end? = @pos >= @end
+
+      # Cycles until the next falling edge, or nil once the tape has run out.
+      def next_pulse
+        return if end?
+
+        byte = @bytes[@pos]
+        @pos += 1
+        return byte * 8 unless byte.zero?
+
+        # $00 is an overflow in version 0 and a 24-bit cycle count in
+        # version 1.
+        version.zero? ? OVERFLOW : long_pulse
+      end
+
+      private
+
+      # The stated size disagrees with the file in the wild, and a few dumps
+      # leave it zeroed altogether.
+      def tape_end
+        size = little_endian(@bytes[0x10, 4] || [])
+        size.zero? ? @bytes.length : [HEADER_SIZE + size, @bytes.length].min
+      end
+
+      def long_pulse
+        bytes = @bytes[@pos, 3]
+        @pos += 3
+        bytes&.length == 3 ? little_endian(bytes) : OVERFLOW
+      end
+
+      def little_endian(bytes)
+        bytes.each_with_index.sum { |byte, i| byte << (8 * i) }
+      end
+    end
+  end
+end

data/lib/badline/storage.rb

@@ -6,16 +6,35 @@ require "badline/storage/disk_image"
 require "badline/storage/d64_image"
 require "badline/storage/d71_image"
 require "badline/storage/d81_image"
+require "badline/storage/t64"
+require "badline/storage/tap"
 require "badline/storage/crt_file"
+require "badline/storage/sid_file"
+require "badline/storage/song_lengths"
 
 module Badline
   module Storage
+    FILE_TYPES = { "S" => :seq, "P" => :prg, "U" => :usr }.freeze
+
     class << self
       # Folds shifted PETSCII letters to their ASCII equivalents.
       def ascii(bytes)
         bytes.map { |b| b.between?(0xc1, 0xda) ? b - 0x80 : b }.pack("C*")
       end
 
+      # CBM DOS drive prefix: "0:NAME" selects a drive, "@0:NAME" is
+      # save-with-replace
+      def strip_drive_prefix(name)
+        name.sub(/\A@?\d*:/, "")
+      end
+
+      # CBM DOS names read "NAME,TYPE,MODE". Returns the bare name and the
+      # file type it asks for, or nil when it names none.
+      def parse_name(name)
+        base, type = strip_drive_prefix(name).split(",", 3)
+        [base.to_s, FILE_TYPES[type.to_s.strip[0]&.upcase]]
+      end
+
       # CBM-style filename pattern: "*" and "?" wildcards, case-insensitive.
       def matcher(name)
         escaped = Regexp.escape(name.downcase)