badline 0.1.0 → 0.2.1

data/lib/badline/storage/disk_image.rb

@@ -6,32 +6,114 @@ module Badline
       SECTOR_SIZE = 256
       ENTRY_SIZE = 32
       ENTRIES_PER_SECTOR = 8
-      FILETYPE_PRG = 0x02
+      FILETYPES = { seq: 0x01, prg: 0x02, usr: 0x03 }.freeze
       NAME_PADDING = 0xa0
 
+      # Error table codes and the DOS errors they stand for: 20 to 29 are
+      # the read, write and ID errors, 74 is DRIVE NOT READY.
+      DOS_ERRORS = (2..11).to_h { |code| [code, code + 18] }.merge(15 => 74).freeze
+
       def initialize(path)
         @bytes = File.binread(path).bytes
+        @errors = split_error_table
       end
 
-      def read_file(name)
-        pattern = Storage.matcher(name)
-        entry = entries.find { |e| pattern.match?(e[:name]) }
+      # A LOAD reads only PRG files. An OPEN names the type it wants, or
+      # takes the first file of any type with a nil `type`.
+      def read_file(name, type: :prg)
+        entry = find_entry(name, type)
         read_chain(entry[:track], entry[:sector]) if entry
       end
 
+      # The first block in a file's chain that the error table marks bad:
+      # its DOS error, its track and sector, and how many of the file's
+      # bytes come before it. Nil when the whole chain reads cleanly.
+      def read_error(name, type: :prg)
+        entry = find_entry(name, type)
+        return unless @errors && entry
+
+        offset = 0
+        each_sector(entry[:track], entry[:sector]) do |data, track, sector|
+          error = block_error(track, sector)
+          return { error:, track:, sector:, offset: } if error
+
+          offset += data[0].zero? ? data[1] - 1 : SECTOR_SIZE - 2
+        end
+        nil
+      end
+
+      # Raw block access for the DOS `U1` command. Returns nil for blocks
+      # outside the image's geometry.
+      def read_block(track, sector)
+        return unless block?(track, sector)
+
+        sector_at(track, sector)
+      end
+
+      # The DOS error a read of the block raises, from the error table an
+      # image can carry after its last block, or nil when it reads cleanly.
+      def block_error(track, sector)
+        return unless @errors && block?(track, sector)
+
+        DOS_ERRORS[@errors[track_offset(track) + sector]]
+      end
+
+      # The block holding the disk name and ID, at the start of the
+      # directory track.
+      def header_block = [directory_track, 0]
+
+      # The directory block a new file's entry goes into: the first with a
+      # free slot, or the last one when every slot is taken.
+      def new_entry_block
+        last = nil
+        each_sector(directory_track, directory_sector) do |data, track, sector|
+          return [track, sector] if (0...ENTRIES_PER_SECTOR).any? { |i| data[(i * ENTRY_SIZE) + 2].zero? }
+
+          last = [track, sector]
+        end
+        last
+      end
+
       private
 
+      # An error table holds one byte per block after the last one. The image
+      # sizes that carry one are listed exactly, since a 40-track D64 with a
+      # table is also a whole number of 256-byte blocks.
+      def split_error_table
+        blocks = error_tables[@bytes.length]
+        @bytes.pop(blocks) if blocks
+      end
+
+      def block?(track, sector)
+        return false unless track.between?(1, 255) &&
+                            sector.between?(0, sectors_in(track) - 1)
+
+        sector_offset(track, sector) + SECTOR_SIZE <= @bytes.length
+      end
+
+      def find_entry(name, type)
+        pattern = Storage.matcher(name)
+        entries.find do |e|
+          (type.nil? || e[:type] == type) && pattern.match?(e[:name])
+        end
+      end
+
       def entries
-        @entries ||= each_sector(directory_track, directory_sector)
-                     .flat_map { |data| parse_entries(data) }
+        @entries ||= begin
+          list = []
+          each_sector(directory_track, directory_sector) { |data| list.concat(parse_entries(data)) }
+          list
+        end
       end
 
       def parse_entries(data)
         (0...ENTRIES_PER_SECTOR).filter_map do |i|
           entry = data[i * ENTRY_SIZE, ENTRY_SIZE]
-          next unless (entry[2] & 0x07) == FILETYPE_PRG
+          type = FILETYPES.key(entry[2] & 0x07)
+          next unless type
 
           { name: decode_name(entry[5, 16]),
+            type:,
             track: entry[3],
             sector: entry[4] }
         end
@@ -42,19 +124,19 @@ module Badline
       end
 
       def read_chain(track, sector)
-        each_sector(track, sector).flat_map do |data|
-          data[0].zero? ? data[2..data[1]] : data[2..]
+        bytes = []
+        each_sector(track, sector) do |data|
+          bytes.concat(data[0].zero? ? data[2..data[1]] : data[2..])
         end
+        bytes
       end
 
       def each_sector(track, sector)
-        return to_enum(:each_sector, track, sector) unless block_given?
-
         visited = {}
         while track != 0 && !visited[[track, sector]]
           visited[[track, sector]] = true
           data = sector_at(track, sector)
-          yield data
+          yield data, track, sector
           track, sector = data[0, 2]
         end
       end
@@ -64,7 +146,11 @@ module Badline
       end
 
       def sector_offset(track, sector)
-        ((1...track).sum { |t| sectors_in(t) } + sector) * SECTOR_SIZE
+        (track_offset(track) + sector) * SECTOR_SIZE
+      end
+
+      def track_offset(track)
+        (1...track).sum { |t| sectors_in(t) }
       end
     end
   end

data/lib/badline/storage/host_directory.rb

@@ -2,22 +2,28 @@
 
 module Badline
   module Storage
+    # A host directory served as a drive: .prg files by their host name,
+    # .p00 and .t64 entries by their embedded names. A host file that can't
+    # be read is left out, and a failed write reports false.
     class HostDirectory
       def initialize(path)
         @path = path
       end
 
-      def read_file(name)
+      def read_file(name, **)
         entry = find(name)
         return unless entry
 
-        bytes = File.binread(File.join(@path, entry[:file])).bytes
-        P00.wraps?(bytes) ? P00.data(bytes) : bytes
+        archive = entry[:archive]
+        archive ? archive.read_file(entry[:name]) : file_bytes(entry[:file])
       end
 
       def write_file(name, bytes)
         host_name = "#{name.downcase.tr('/', '_')}.prg"
         File.binwrite(File.join(@path, host_name), bytes.pack("C*"))
+        true
+      rescue SystemCallError
+        false
       end
 
       private
@@ -28,7 +34,9 @@ module Badline
       end
 
       def entries
-        Dir.children(@path).sort.filter_map { |f| entry_for(f) }
+        Dir.children(@path).sort.flat_map { |f| entry_for(f) }.compact
+      rescue SystemCallError
+        []
       end
 
       def entry_for(file)
@@ -37,12 +45,30 @@ module Badline
           { name: File.basename(file, ".*").downcase, file: }
         when ".p00"
           p00_entry(file)
+        when ".t64"
+          t64_entries(file)
         end
       end
 
       def p00_entry(file)
         header = File.binread(File.join(@path, file), P00::HEADER_SIZE).bytes
         { name: P00.name(header), file: } if P00.wraps?(header)
+      rescue SystemCallError
+        nil
+      end
+
+      def t64_entries(file)
+        archive = T64.new(File.join(@path, file))
+        archive.names.map { |name| { name:, archive: } }
+      rescue T64::FormatError, SystemCallError
+        nil
+      end
+
+      def file_bytes(file)
+        bytes = File.binread(File.join(@path, file)).bytes
+        P00.wraps?(bytes) ? P00.data(bytes) : bytes
+      rescue SystemCallError
+        nil
       end
     end
   end

data/lib/badline/storage/sid_file.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "digest"
+
+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