badline 0.9.0 → 0.10.1

data/lib/badline/vic20/bus.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module Badline
+  class Vic20
+    # The CPU's bus:
+    #
+    # $0000-$03FF - 1K of RAM
+    # $0400-$0FFF - RAM1-3, 3K of expansion RAM, or nothing
+    # $1000-$1FFF - 4K of RAM
+    # $2000-$7FFF - BLK1, BLK2 and BLK3, 8K of expansion RAM each, or nothing
+    # $8000-$8FFF - the character ROM
+    # $9000-$93FF - I/O 0: the VIC and both VIAs (see IO0)
+    # $9400-$97FF - colour RAM, 1K by four bits
+    # $9800-$9FFF - I/O 2 and I/O 3, for cartridges
+    # $A000-$BFFF - BLK5, 8K of expansion RAM, or nothing
+    # $C000-$DFFF - the BASIC ROM
+    # $E000-$FFFF - the KERNAL ROM
+    #
+    # The VIC reaches $0000-$1FFF and $8000-$9FFF, the pages where A13 and
+    # A14 are both low, over the V-bus, and the CPU reaches them through it
+    # too. Elsewhere the CPU is on its own side of the bus.
+    #
+    # Each side's data lines hold the last byte they carried, so a read
+    # from an empty spot finds that byte: the V-bus's in the 3K hole, and
+    # the CPU's own in the empty blocks, I/O 2 and I/O 3. Colour RAM drives
+    # the low four lines only, and the V-bus's high four come through.
+    # Writes to ROM and to empty spots go nowhere.
+    class Bus
+      include Addressable
+
+      # The pages each expansion block covers, as [first page, count].
+      BLOCKS = {
+        ram123: [0x04, 0x0c], blk1: [0x20, 0x20], blk2: [0x40, 0x20], blk3: [0x60, 0x20], blk5: [0xa0, 0x20]
+      }.freeze
+
+      # The blocks each of the usual RAM expansions fills, and every block,
+      # which is what xvic's -memory all fits.
+      RAM_CONFIGURATIONS = {
+        unexpanded: [],
+        "3k": %i[ram123],
+        "8k": %i[blk1],
+        "16k": %i[blk1 blk2],
+        "24k": %i[blk1 blk2 blk3],
+        "32k": %i[blk1 blk2 blk3 blk5],
+        all: %i[ram123 blk1 blk2 blk3 blk5]
+      }.freeze
+
+      # RAM, internal and expansion alike, powers on in alternating $FF
+      # and $00 bytes, $FF at the even addresses, the alternation most of
+      # the machines in VIC20/raminitpattern/readme.txt show. Colour RAM
+      # powers on at zero. See doc/pinned-behaviour.md.
+      RAM_POWER_ON = Array.new(0xc000) { |addr| addr.even? ? 0xff : 0x00 }.freeze
+
+      # The last byte on the V-bus's data lines, which an empty spot on
+      # the VIC's side reads back.
+      class VideoOpenBus
+        def initialize(bus)
+          @bus = bus
+        end
+
+        def peek(_addr) = @bus.video_data
+        def poke(_addr, _value); end
+      end
+
+      # The last byte the CPU moved, which an empty spot on the CPU's side
+      # reads back.
+      class OpenBus
+        def initialize(bus)
+          @bus = bus
+        end
+
+        def peek(_addr) = @bus.data
+        def poke(_addr, _value); end
+      end
+
+      # Colour RAM: four bits a cell, under the V-bus's high four lines.
+      class ColorRAM
+        # The 1,024 cells, which the VIC reads its colour nibbles from.
+        attr_reader :cells
+
+        def initialize(bus)
+          @bus = bus
+          @cells = Array.new(0x400, 0)
+        end
+
+        def peek(addr) = (@bus.video_data & 0xf0) | @cells[addr & 0x3ff]
+
+        def poke(addr, value)
+          @cells[addr & 0x3ff] = value & 0x0f
+        end
+
+        # The four bits the cell at +addr+ stores.
+        def nibble(addr) = @cells[addr & 0x3ff]
+      end
+
+      # I/O 0, $9000-$93FF. The VIC answers in $9000-$90FF, its sixteen
+      # registers repeated. The VIAs answer all through I/O 0, on the
+      # address lines alone: A4 selects VIA 1 and A5 selects VIA 2. Where
+      # more than one chip answers a read, each pulls the lines it drives
+      # low, so the CPU reads the AND of them, and a write reaches them
+      # all. Where none answers, the CPU reads the V-bus's last byte: the
+      # VIC's fetch in a cycle it fetches in, as the real 6561E's dump of
+      # VIC20/split-tests/timing shows at $9100 and $9200.
+      class IO0
+        def initialize(bus, vic:, via1:, via2:)
+          @bus = bus
+          @vic = vic
+          @via1 = via1
+          @via2 = via2
+        end
+
+        def peek(addr)
+          vic = addr < 0x9100
+          return @bus.video_data unless vic || addr.anybits?(0x30)
+
+          value = vic ? @vic.peek(addr) : 0xff
+          value &= @via1.peek(addr) if addr.anybits?(0x10)
+          value &= @via2.peek(addr) if addr.anybits?(0x20)
+          value
+        end
+
+        def poke(addr, value)
+          @vic.poke(addr, value) if addr < 0x9100
+          return unless addr.anybits?(0x30)
+
+          @via1.poke(addr, value) if addr.anybits?(0x10)
+          @via2.poke(addr, value) if addr.anybits?(0x20)
+          @bus.via_written
+        end
+      end
+
+      # VICE's debug cartridge register at $910F, a spot in I/O 0 that
+      # nothing answers. A write there calls the handler with the byte, the
+      # exit code the VICE testprogs report. Every other access falls
+      # through to I/O 0.
+      class DebugRegister
+        ADDRESS = 0x910f
+
+        def initialize(io0, &handler)
+          @io0 = io0
+          @handler = handler
+        end
+
+        def peek(addr) = @io0.peek(addr)
+
+        def poke(addr, value)
+          return @handler.call(value) if addr == ADDRESS
+
+          @io0.poke(addr, value)
+        end
+      end
+
+      attr_reader :ram, :color_ram, :blocks
+
+      # The last byte the CPU read or wrote.
+      attr_reader :data
+
+      # The last byte on the V-bus.
+      attr_reader :video_data
+
+      # +vic+, +via1+ and +via2+ are the chips in I/O 0, each answering
+      # peek and poke with the CPU's address. +blocks+ names the expansion
+      # blocks that hold RAM (BLOCKS), and +kernal+ the KERNAL ROM's file.
+      def initialize(vic:, via1:, via2:, blocks: [], kernal: "vic20/kernal-pal.rom")
+        addressable_at(0, length: 2**16)
+        @ram = Memory.new(RAM_POWER_ON, length: 0xc000, start: 0)
+        @color_ram = ColorRAM.new(self)
+        @character_rom = ROM.load("vic20/character.rom", 0x8000)
+        @basic_rom = ROM.load("vic20/basic.rom", 0xc000)
+        @kernal_rom = ROM.load(kernal, 0xe000)
+        @io0 = IO0.new(self, vic:, via1:, via2:)
+        @open_bus = OpenBus.new(self)
+        @video_open_bus = VideoOpenBus.new(self)
+        @data = @video_data = 0
+        @read_pages = Array.new(256, @open_bus)
+        @write_pages = Array.new(256, @open_bus)
+        @roms = []
+        @debug_register = nil
+        @via_write_handler = nil
+        self.blocks = blocks
+      end
+
+      # Puts a cartridge's ROM chip of +bytes+, whole pages of them, at
+      # +address+. It answers reads on the pages it covers in place of
+      # whatever was there, and writes to them go nowhere.
+      def map_rom(address, bytes)
+        @roms << ROM.new(bytes, length: bytes.length, start: address)
+        map_pages
+      end
+
+      # Calls the block after each write to a VIA, which may have moved the
+      # lines its ports drive.
+      def on_via_write(&handler)
+        @via_write_handler = handler
+      end
+
+      def via_written
+        @via_write_handler&.call
+      end
+
+      # Calls the block with each byte written to $910F (DebugRegister).
+      def install_debug_register(&)
+        @debug_register = DebugRegister.new(@io0, &)
+        map_pages
+      end
+
+      # Fills the expansion blocks named in +names+ with RAM and empties
+      # the rest.
+      def blocks=(names)
+        @blocks = names.dup.freeze
+        map_pages
+      end
+
+      def power_on!
+        @ram.clear!(RAM_POWER_ON)
+      end
+
+      # The RAM, the colour RAM, the byte each side's data lines hold and the
+      # cartridge's ROM chips, for a snapshot. The expansion blocks are how
+      # the machine was built.
+      def save_state(out)
+        out.marker("VIC20 BUS")
+        @ram.save_state(out)
+        out.blob(@color_ram.cells).int(@data).int(@video_data).int(@roms.length)
+        @roms.each do |rom|
+          out.int(rom.start)
+          rom.save_state(out)
+        end
+      end
+
+      def load_state(input)
+        input.marker("VIC20 BUS")
+        @ram.load_state(input)
+        input.blob_into(@color_ram.cells)
+        @data = input.int
+        @video_data = input.int
+        chips = Array.new(input.int) { [input.int, input.blob] }
+        @roms = []
+        chips.each { |chip| @roms << ROM.new(chip[1], length: chip[1].length, start: chip[0]) }
+        map_pages
+      end
+
+      # Whether +block+ (BLOCKS) holds RAM.
+      def ram?(block) = @blocks.include?(block)
+
+      # The VIC's fetch from +address+, its own 14-bit address, which leaves
+      # the byte on the V-bus. The VIC's A13 is the CPU's A15 inverted, so
+      # $2000-$3FFF are the CPU's $0000-$1FFF and $0000-$1FFF its
+      # $8000-$9FFF. It reaches the internal RAM and the character ROM, and
+      # no expansion RAM. Elsewhere nothing drives the V-bus's data lines,
+      # and the VIC reads the byte they hold, as does a fetch from colour
+      # RAM, which drives only the colour bus while the VIC fetches.
+      def video_fetch(address)
+        value =
+          if address >= 0x2000
+            internal = address & 0x1fff
+            internal < 0x0400 || internal >= 0x1000 ? @ram.peek(internal) : @video_data
+          elsif address < 0x1000
+            @character_rom.peek(address | 0x8000)
+          else
+            @video_data
+          end
+        @video_data = value
+      end
+
+      def peek(addr)
+        value = @read_pages[addr >> 8].peek(addr)
+        @video_data = value if addr.nobits?(0x6000)
+        @data = value
+      end
+
+      def poke(addr, value)
+        @data = value
+        @video_data = value if addr.nobits?(0x6000)
+        @write_pages[addr >> 8].poke(addr, value)
+      end
+
+      private
+
+      def map_pages
+        map(@open_bus, 0x00, 0x100)
+        @read_pages.fill(@video_open_bus, 0x04, 0x0c)
+        map(@ram, 0x00, 0x04)
+        map(@ram, 0x10, 0x10)
+        BLOCKS.each { |block, pages| map(@ram, pages[0], pages[1]) if ram?(block) }
+        @read_pages.fill(@character_rom, 0x80, 0x10)
+        map(@io0, 0x90, 0x04)
+        map(@color_ram, 0x94, 0x04)
+        @read_pages.fill(@basic_rom, 0xc0, 0x20)
+        @read_pages.fill(@kernal_rom, 0xe0, 0x20)
+        @roms.each { |rom| map_rom_pages(rom) }
+        @write_pages[0x91] = @debug_register if @debug_register
+      end
+
+      def map_rom_pages(rom)
+        first = rom.start >> 8
+        count = rom.length >> 8
+        @read_pages.fill(rom, first, count)
+        @write_pages.fill(@open_bus, first, count)
+      end
+
+      def map(chip, first, count)
+        @read_pages.fill(chip, first, count)
+        @write_pages.fill(chip, first, count)
+      end
+    end
+  end
+end

data/lib/badline/vic20/cpu.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Badline
+  class Vic20
+    # The VIC-20's 6502, on the Vic20::Bus.
+    class CPU
+      include Badline::CPU::Core
+    end
+  end
+end

data/lib/badline/vic20/keyboard_via_ports.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Badline
+  class Vic20
+    # What VIA 2's ports read from outside the chip: the key matrix, with
+    # port B driving its columns and port A reading its rows. The KERNAL's
+    # SCNKEY ($EB1E) writes a column pattern to $9120 and reads the rows
+    # back from $9121, and its key table ($EC5E) puts each key at column
+    # times 8 plus row.
+    #
+    # PB7 is also the joystick's right switch. A held switch pulls that
+    # column line low before the matrix settles, so it reads as a key down
+    # in every row whose key in column 7 is held too. PB3 doubles as the
+    # cassette write line, which only the datasette listens to.
+    class KeyboardVIAPorts
+      # One row of keys per port A line, in port B column order. The keys
+      # are the C64's, under the same names, wired to other lines.
+      MATRIX = [
+        %i[1 left control run_stop space cbm q 2],
+        %i[3 w a lshift z s e 4],
+        %i[5 r d x c f t 6],
+        %i[7 y g v b h u 8],
+        %i[9 i j n m k o 0],
+        %i[+ p l , . : @ -],
+        %i[£ * ; / rshift = up clr_home],
+        %i[delete return cursor_h cursor_v f1 f3 f5 f7]
+      ].freeze
+
+      attr_reader :keyboard, :joystick
+
+      def initialize(keyboard:, joystick:)
+        @keyboard = keyboard
+        @joystick = joystick
+        @via = nil
+      end
+
+      # The VIA these ports hang off, whose other port's output the matrix
+      # settles against.
+      def connect(via)
+        @via = via
+      end
+
+      def read_a(lines) = @keyboard.scan(lines, columns(@via.port_b_output)).first
+
+      def read_b(lines) = @keyboard.scan(@via.port_a_output, columns(lines)).last
+
+      private
+
+      # The joystick's right switch is bit 3 of its port bits, and pulls PB7.
+      def columns(lines) = lines & (0x7f | ((@joystick.port_bits & 0x08) << 4))
+    end
+  end
+end

data/lib/badline/vic20/port_wiring.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Badline
+  class Vic20
+    # The datasette and the serial bus, wired to the VIAs.
+    #
+    # The serial bus's lines go out through inverters, so an output that
+    # drives high pulls its line low: ATN from VIA 1's PA7, the clock from
+    # VIA 2's CA2 and the data line from VIA 2's CB2. An output left as an
+    # input floats high, and pulls its line too, as after a reset. CLK and
+    # DATA come back on VIA 1's PA0 and PA1 (UserVIAPorts). The machine
+    # pushes the lines it pulls into the bus, as the C64's CIA 2 port A
+    # bits, after each write to a VIA that moves them.
+    #
+    # The datasette's read line pulses VIA 2's CA1, its sense switch reads
+    # on VIA 1's PA6, its motor runs while VIA 1's CA2 is low, and VIA 2's
+    # PB3 drives its write line, the same pin as a keyboard column.
+    module PortWiring
+      # The lines the machine pulls, as IECBus host lines.
+      def serial_lines
+        lines = 0
+        lines |= IECBus::HOST_ATN_OUT if @via1.port_a_output.anybits?(0x80)
+        lines |= IECBus::HOST_CLK_OUT if @via2.ca2_output
+        lines |= IECBus::HOST_DATA_OUT if @via2.cb2_output
+        lines
+      end
+
+      private
+
+      def wire_ports
+        @datasette.on_flag { tape_pulse }
+        @bus.on_via_write { via_written }
+        via_written
+      end
+
+      def via_written
+        lines = serial_lines
+        @iec_bus.host_lines = lines unless lines == @iec_bus.host_lines
+        @datasette.motor = !@via1.ca2_output
+        @datasette.write_line = @via2.port_b_output.anybits?(0x08)
+      end
+
+      # A falling edge on the read line, and the line back up.
+      def tape_pulse
+        @via2.ca1 = false
+        @via2.ca1 = true
+      end
+    end
+  end
+end

data/lib/badline/vic20/saved_state.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Badline
+  class Vic20
+    MARKER = "VIC20"
+
+    # The RAM expansion of the machine a State from #snapshot was taken
+    # of, a key of Bus::RAM_CONFIGURATIONS.
+    def self.setup(state)
+      input = Snapshot::StateReader.new(state)
+      input.marker(MARKER)
+      input.check_stamp
+      SavedState.read_ram(input)
+    end
+
+    # A new machine, built as the one a State from #snapshot was taken of,
+    # at that state.
+    def self.restored(state) = new(ram: setup(state)).apply_state(state)
+
+    # The whole machine's state for a snapshot, as Computer's: the
+    # machine's own latches, the bus with its RAM and cartridge ROM, the
+    # VIC with its sound, both VIAs, the CPU, the datasette and its tape,
+    # the disk device 8 serves through the traps, and a true 1541. The
+    # serial lines go back into the bus from the restored VIAs. What the
+    # host holds stays out: the keyboard, the joystick, RESTORE, the traps
+    # and callbacks, whether the display renders, whether the sound
+    # records, and whether the datasette records.
+    module SavedState
+      RAM_CONFIGURATIONS = Bus::RAM_CONFIGURATIONS.keys.freeze
+
+      def self.read_ram(input)
+        RAM_CONFIGURATIONS.fetch(input.int)
+      rescue IndexError
+        raise Snapshot::FormatError, "the state names a VIC-20 RAM expansion badline doesn't know"
+      end
+
+      # How many more on_init handlers the machine a State was taken of had
+      # yet to run than this one has. Nil until the machine is restored.
+      attr_reader :init_handlers_lost
+
+      def snapshot
+        out = Snapshot::StateWriter.new
+        save_state(out)
+        out.state
+      end
+
+      # Takes the machine back to a State from #snapshot, trying it on a new
+      # machine first, so one that fails leaves this machine as it was.
+      # Raises Snapshot::FormatError for a state of another machine or RAM
+      # expansion.
+      def restore(state)
+        check_ram(Vic20.setup(state))
+        Vic20.restored(state)
+        apply_state(state)
+      end
+
+      # Puts a State into the machine without trying it on a new one first.
+      def apply_state(state)
+        input = Snapshot::StateReader.new(state)
+        load_state(input)
+        raise Snapshot::FormatError, "the state goes on past the machine" unless input.finished?
+
+        self
+      end
+
+      def save_state(out)
+        out.marker(MARKER).stamp
+        out.int(RAM_CONFIGURATIONS.index(@ram_configuration))
+        out.int(@cycles).boolean(@nmi_asserted).boolean(!@pending_keys.nil?)
+        out.ints(@pending_keys) if @pending_keys
+        out.int(@cycles <= @init_threshold ? @init_handlers.length : 0)
+        @bus.save_state(out)
+        @vic.save_state(out)
+        @sound.save_state(out)
+        @via1.save_state(out)
+        @via2.save_state(out)
+        @cpu.save_state(out)
+        @datasette.save_state(out)
+        save_trap_drive(out)
+        save_drive1541(out)
+      end
+
+      def load_state(input)
+        input.marker(MARKER)
+        input.check_stamp
+        check_ram(SavedState.read_ram(input))
+        @cycles = input.int
+        @nmi_asserted = input.boolean?
+        @pending_keys = nil
+        @pending_keys = input.ints if input.boolean?
+        @init_handlers_lost = [input.int - @init_handlers.length, 0].max
+        @bus.load_state(input)
+        @vic.load_state(input)
+        @sound.load_state(input)
+        @via1.load_state(input)
+        @via2.load_state(input)
+        @cpu.load_state(input)
+        via_written
+        @datasette.load_state(input)
+        load_trap_drive(input)
+        load_drive1541(input)
+      end
+
+      private
+
+      # The disk device 8 serves through the traps, with its channels.
+      def save_trap_drive(out)
+        out.boolean(!@drive.nil?)
+        return unless @drive
+
+        @drive.save_state(out)
+        @serial_trap.save_state(out)
+        @save_trap.save_state(out)
+      end
+
+      def load_trap_drive(input)
+        return unmount unless input.boolean?
+
+        storage = Storage.reopen(input)
+        unmount
+        mount(storage)
+        @drive.load_state(input)
+        @serial_trap.load_state(input)
+        @save_trap.load_state(input)
+      end
+
+      # A true 1541 on the serial bus, with its device number.
+      def save_drive1541(out)
+        out.boolean(!@drive1541.nil?)
+        return unless @drive1541
+
+        out.int(@drive1541.device)
+        @drive1541.save_state(out)
+      end
+
+      def load_drive1541(input)
+        return detach_drive1541 unless input.boolean?
+
+        device = input.int
+        detach_drive1541 if @drive1541 && @drive1541.device != device
+        attach_drive1541(Drive1541.new(device:)) unless @drive1541
+        @drive1541.load_state(input)
+      end
+
+      def check_ram(ram)
+        return if ram == @ram_configuration
+
+        raise Snapshot::FormatError, "the state is of a VIC-20 with #{ram} RAM, not #{@ram_configuration}"
+      end
+    end
+  end
+end

data/lib/badline/vic20/sound/output.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Badline
+  class Vic20
+    class Sound
+      # The sound's level averaged over each sample of the audio rate, then
+      # through the machine's output stage: a one-pole low-pass at 1,420 Hz
+      # and a one-pole high-pass at 158 Hz, both run at the audio rate.
+      #
+      # The two corners are fitted to xvic's step response: a voice turned
+      # on at volume 15 rises and decays back to the line as those two RC
+      # stages do, within 6 parts in 11,000.
+      class Output
+        LOW_PASS_HZ = 1_420
+        HIGH_PASS_HZ = 158
+
+        # Scales the loudest level, four voices high at volume 15, to the
+        # top of a signed 16-bit sample.
+        SCALE = 32_767.0 / 570
+
+        attr_reader :samples
+
+        # `level` is the sound's level as the recording starts, which the
+        # stage takes as settled.
+        def initialize(clock_hz:, rate:, level:)
+          @clock_hz = clock_hz
+          @rate = rate
+          @remainder = 0
+          @window = next_window
+          @left = @window
+          @sum = 0
+          @low = @drift = level.to_f
+          @low_pass = 1.0 - Math.exp(-2.0 * Math::PI * LOW_PASS_HZ / rate)
+          @high_pass = 1.0 - Math.exp(-2.0 * Math::PI * HIGH_PASS_HZ / rate)
+          @samples = []
+        end
+
+        # Adds `cycles` cycles at `level`, closing every sample they finish.
+        def hold(level, cycles)
+          left = @left
+          while cycles >= left
+            @sum += level * left
+            cycles -= left
+            close
+            left = @left
+          end
+          @sum += level * cycles
+          @left = left - cycles
+        end
+
+        # The samples closed since the last drain.
+        def drain
+          samples = @samples
+          @samples = []
+          samples
+        end
+
+        private
+
+        def close
+          @low += @low_pass * (@sum.fdiv(@window) - @low)
+          @drift += @high_pass * (@low - @drift)
+          sample = ((@low - @drift) * SCALE).round
+          sample = 32_767 if sample > 32_767
+          sample = -32_768 if sample < -32_768
+          @samples << sample
+          @sum = 0
+          @window = next_window
+          @left = @window
+        end
+
+        # Each window is a whole number of cycles, and they add up to the
+        # clock's cycles over a second.
+        def next_window
+          @remainder += @clock_hz
+          cycles = @remainder / @rate
+          @remainder -= cycles * @rate
+          cycles
+        end
+      end
+    end
+  end
+end