mos6502-workbench 1.0.0

data/lib/mos6502/workbench/device.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module MOS6502
+  # Base class for memory-mapped peripherals and storage devices.
+  #
+  # Device implementations are expected to respond to:
+  #
+  # - {#read_byte} for bus reads
+  # - {#write_byte} for bus writes
+  # - {#reset} for power-on style reinitialisation
+  # - {#tick} for advancing time in cycle-driven machines
+  #
+  # Subclasses can expose an optional `size` reader when the bus should validate
+  # the mapped range against the device capacity.
+  class Device
+    # Creates a new device.
+    #
+    # The base implementation exists so subclasses can call `super()` cleanly in
+    # their own initializers.
+    #
+    # @return [void]
+    def initialize; end
+
+    # Resets the device to its power-on state.
+    #
+    # The base implementation is a no-op so simple devices only need to override
+    # it when they maintain internal state.
+    #
+    # @return [Device] the device
+    def reset
+      self
+    end
+
+    # Advances the device clock by a number of CPU cycles.
+    #
+    # The base implementation is a no-op. Timed peripherals can override this to
+    # model timers, serial shifting, video scan-out, or similar behaviour.
+    #
+    # @param _cycles [Integer] the number of CPU cycles elapsed
+    # @return [Device] the device
+    def tick(_cycles)
+      self
+    end
+
+    # Reads a byte from the device-local address space.
+    #
+    # @param _address [Integer] the device-local byte offset
+    # @return [Integer] the device byte value
+    # @raise [NotImplementedError] unless a subclass implements the method
+    def read_byte(_address)
+      raise NotImplementedError, "#{self.class} must implement #read_byte"
+    end
+
+    # Writes a byte into the device-local address space.
+    #
+    # @param _address [Integer] the device-local byte offset
+    # @param _value [Integer] the value to store
+    # @return [Integer] the stored byte value
+    # @raise [NotImplementedError] unless a subclass implements the method
+    def write_byte(_address, _value)
+      raise NotImplementedError, "#{self.class} must implement #write_byte"
+    end
+  end
+end

data/lib/mos6502/workbench/disassembler.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module MOS6502
+  # Raised when bytes cannot be disassembled because the decode metadata is invalid.
+  class DisassemblyError < StandardError; end
+
+  # A small disassembler for the implemented NMOS 6502 opcode table.
+  #
+  # The disassembler intentionally derives its decode information from
+  # {CPU::OPCODES} so the emulator and listing output stay in sync.
+  class Disassembler
+    # A single decoded instruction or raw data byte.
+    Line = Struct.new(
+      :address,
+      :bytes,
+      :opcode,
+      :mnemonic,
+      :mode,
+      :operand,
+      :byte_size,
+      :target_address,
+      :text
+    )
+
+    # The number of bytes occupied by each supported addressing mode.
+    #
+    # @return [Hash{Symbol => Integer}]
+    INSTRUCTION_SIZES = {
+      implied: 1,
+      accumulator: 1,
+      immediate: 2,
+      zero_page: 2,
+      zero_page_x: 2,
+      zero_page_y: 2,
+      relative: 2,
+      indirect_x: 2,
+      indirect_y: 2,
+      absolute: 3,
+      absolute_x: 3,
+      absolute_y: 3,
+      indirect: 3
+    }.freeze
+
+    # @param opcodes [Hash{Integer => Array<Symbol>}] the opcode table to use
+    def initialize(opcodes: CPU::OPCODES)
+      @opcodes = opcodes
+    end
+
+    # Disassembles a byte stream into line objects.
+    #
+    # Unknown opcodes are rendered as `.byte` directives so arbitrary binaries can
+    # still be listed without raising.
+    #
+    # @param bytes [String, #to_a] the raw bytes to decode
+    # @param start_address [Integer] the load address of the first byte
+    # @param max_instructions [Integer, nil] an optional instruction limit
+    # @return [Array<Line>] the decoded listing
+    def disassemble(bytes, start_address: CPU::DEFAULT_LOAD_ADDRESS, max_instructions: nil)
+      stream = bytes.is_a?(String) ? bytes.bytes : bytes.to_a
+      lines = []
+      offset = 0
+
+      while offset < stream.length && within_instruction_budget?(lines.length, max_instructions)
+        address = (start_address + offset) & 0xffff
+        opcode = stream[offset]
+        mnemonic, mode = @opcodes[opcode]
+
+        if mnemonic.nil?
+          lines << data_line(address, opcode)
+          offset += 1
+          next
+        end
+
+        size = instruction_size(mode)
+        instruction_bytes = stream.slice(offset, size) || []
+        operand_bytes = instruction_bytes.drop(1)
+        operand, target_address = format_operand(mode, operand_bytes, address)
+
+        lines << Line.new(
+          address:,
+          bytes: instruction_bytes,
+          opcode:,
+          mnemonic:,
+          mode:,
+          operand:,
+          byte_size: size,
+          target_address:,
+          text: join_instruction_text(mnemonic, operand)
+        )
+
+        offset += size
+      end
+
+      lines
+    end
+
+    # Formats a decoded listing into a column-aligned string.
+    #
+    # @param lines [Array<Line>] the lines to render
+    # @return [String] the formatted listing text
+    def format_listing(lines)
+      lines.map do |line|
+        bytes = line.bytes.map { |byte| format('%02X', byte) }.join(' ').ljust(8)
+        "$#{format('%04X', line.address)}: #{bytes} #{line.text}"
+      end.join("\n")
+    end
+
+    private
+
+    # @param count [Integer] how many instructions have already been emitted
+    # @param max_instructions [Integer, nil] the optional instruction limit
+    # @return [Boolean] whether another instruction may be decoded
+    def within_instruction_budget?(count, max_instructions)
+      max_instructions.nil? || count < max_instructions
+    end
+
+    # Builds a `.byte` line for an unknown opcode.
+    #
+    # @param address [Integer] where the byte lives
+    # @param opcode [Integer] the unknown opcode value
+    # @return [Line] the formatted data line
+    def data_line(address, opcode)
+      operand = format('$%02X', opcode)
+      Line.new(
+        address:,
+        bytes: [opcode],
+        opcode:,
+        mnemonic: nil,
+        mode: nil,
+        operand:,
+        byte_size: 1,
+        target_address: nil,
+        text: ".byte #{operand}"
+      )
+    end
+
+    # Joins mnemonic and operand text into a single listing field.
+    #
+    # @param mnemonic [Symbol] the decoded mnemonic
+    # @param operand [String, nil] the formatted operand
+    # @return [String] the combined text
+    def join_instruction_text(mnemonic, operand)
+      operand ? "#{mnemonic} #{operand}" : mnemonic.to_s
+    end
+
+    # Returns the width of the decoded instruction.
+    #
+    # @param mode [Symbol] the addressing mode
+    # @return [Integer] the instruction size in bytes
+    # @raise [DisassemblyError] if the mode is unknown
+    def instruction_size(mode)
+      INSTRUCTION_SIZES.fetch(mode)
+    rescue KeyError
+      raise DisassemblyError, "Unknown instruction size for #{mode}"
+    end
+
+    # Formats an operand for listing output.
+    #
+    # @param mode [Symbol] the addressing mode
+    # @param bytes [Array<Integer>] the operand bytes
+    # @param address [Integer] the instruction address
+    # @return [Array<(String, Integer, nil)>] the operand text and optional target
+    # @raise [DisassemblyError] if the mode cannot be rendered
+    def format_operand(mode, bytes, address)
+      case mode
+      when :implied
+        [nil, nil]
+      when :accumulator
+        ['A', nil]
+      when :immediate
+        ["#$#{hex_byte(bytes[0])}", nil]
+      when :zero_page
+        ["$#{hex_byte(bytes[0])}", nil]
+      when :zero_page_x
+        ["$#{hex_byte(bytes[0])}, X", nil]
+      when :zero_page_y
+        ["$#{hex_byte(bytes[0])}, Y", nil]
+      when :absolute
+        ["$#{hex_word(bytes[0], bytes[1])}", nil]
+      when :absolute_x
+        ["$#{hex_word(bytes[0], bytes[1])}, X", nil]
+      when :absolute_y
+        ["$#{hex_word(bytes[0], bytes[1])}, Y", nil]
+      when :indirect
+        ["($#{hex_word(bytes[0], bytes[1])})", nil]
+      when :indirect_x
+        ["($#{hex_byte(bytes[0])}, X)", nil]
+      when :indirect_y
+        ["($#{hex_byte(bytes[0])}), Y", nil]
+      when :relative
+        target = branch_target(bytes[0], address)
+        [target ? format('$%04X', target) : '$????', target]
+      else
+        raise DisassemblyError, "Cannot format operand for #{mode}"
+      end
+    end
+
+    # Formats a byte as uppercase hex, using `??` for missing data.
+    #
+    # @param value [Integer, nil] the raw byte
+    # @return [String] the formatted byte
+    def hex_byte(value)
+      value.nil? ? '??' : format('%02X', value & 0xff)
+    end
+
+    # Formats a little-endian word as uppercase hex, preserving missing bytes.
+    #
+    # @param low [Integer, nil] the low byte
+    # @param high [Integer, nil] the high byte
+    # @return [String] the formatted word
+    def hex_word(low, high)
+      "#{hex_byte(high)}#{hex_byte(low)}"
+    end
+
+    # Resolves a relative branch target from an 8-bit signed displacement.
+    #
+    # @param offset [Integer, nil] the raw branch displacement
+    # @param address [Integer] the instruction address
+    # @return [Integer, nil] the absolute branch target
+    def branch_target(offset, address)
+      return nil if offset.nil?
+
+      ((address + 2 + signed_byte(offset)) & 0xffff)
+    end
+
+    # Converts an unsigned byte to a signed relative displacement.
+    #
+    # @param value [Integer] the raw byte
+    # @return [Integer] the signed offset
+    def signed_byte(value)
+      value >= 0x80 ? value - 0x100 : value
+    end
+  end
+end

data/lib/mos6502/workbench/flags.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module MOS6502
+  # Status register helpers for the processor flags.
+  #
+  # The bit order matches the packed 6502 status register:
+  # `N V 1 B D I Z C`.
+  module Flags
+    FLAGS = %w[negative overflow high break decimal interrupt zero carry].freeze
+    FLAG_MASKS = {
+      'negative' => 0b1000_0000,
+      'overflow' => 0b0100_0000,
+      'break' => 0b0001_0000,
+      'decimal' => 0b0000_1000,
+      'interrupt' => 0b0000_0100,
+      'zero' => 0b0000_0010,
+      'carry' => 0b0000_0001
+    }.freeze
+    # Clears all mutable processor-status flags.
+    #
+    # Bit 5 (`high`) is implicit in the packed status register and is therefore
+    # not exposed as a mutable Ruby accessor.
+    #
+    # @return [void]
+    def flags_reset
+      FLAGS.each { |flag_name| instance_variable_set("@#{flag_name}", false) }
+    end
+
+    # Defines predicate and writer methods for each mutable flag when included.
+    #
+    # @param base [Class] the including class
+    # @return [void]
+    def self.included(base)
+      FLAGS.each do |flag_name|
+        next if flag_name == 'high'
+
+        base.define_method(:"#{flag_name}?") { instance_variable_get("@#{flag_name}") }
+        base.define_method(:"#{flag_name}=") { |value| instance_variable_set("@#{flag_name}", value) }
+      end
+    end
+
+    # Packs the current flags into an 8-bit processor-status value.
+    #
+    # @return [Integer] the encoded processor status register
+    def flags_encode
+      FLAGS.reduce(0) do |memo, flag_name|
+        bit = if flag_name == 'high'
+                1
+              else
+                bit_value(instance_variable_get("@#{flag_name}"))
+              end
+        (memo << 1) + bit
+      end
+    end
+
+    # Unpacks an 8-bit processor-status value into the individual flags.
+    #
+    # @param value [Integer] the packed processor status register
+    # @return [void]
+    def flags_decode(value)
+      FLAG_MASKS.each do |flag_name, mask|
+        instance_variable_set("@#{flag_name}", value.anybits?(mask))
+      end
+    end
+
+    # Converts a Ruby boolean into the bit value used by the status register.
+    #
+    # @param bool [Boolean] the flag value
+    # @return [Integer] `1` when true, otherwise `0`
+    def bit_value(bool)
+      bool ? 1 : 0
+    end
+  end
+end

data/lib/mos6502/workbench/intel_hex.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module MOS6502
+  # Raised when Intel HEX text is malformed or unsupported.
+  class IntelHexError < StandardError; end
+
+  # A minimal Intel HEX parser and loader for 16-bit 6502 address space.
+  #
+  # The current implementation supports:
+  # - data records (`00`)
+  # - end-of-file records (`01`)
+  #
+  # Extended address records are intentionally rejected for now because the
+  # emulator only exposes a 16-bit address bus.
+  class IntelHex
+    # A single parsed Intel HEX record.
+    Record = Struct.new(:address, :record_type, :data)
+
+    # A parsed Intel HEX document ready to load into a CPU.
+    Document = Struct.new(:records) do
+      # Returns only the data-bearing records in the document.
+      #
+      # @return [Array<Record>] the parsed data records
+      def data_records
+        records.select { |record| record.record_type.zero? }
+      end
+
+      # Returns the lowest data address present in the document.
+      #
+      # @return [Integer, nil] the first occupied address, if any
+      def start_address
+        data_records.map(&:address).min
+      end
+
+      # Loads the parsed records into a CPU.
+      #
+      # @param cpu [CPU] the destination CPU
+      # @param set_reset_vector [Boolean] whether to update the reset vector
+      # @return [Integer, nil] the lowest loaded address
+      def load_into(cpu, set_reset_vector: true)
+        first_address = start_address
+
+        data_records.each do |record|
+          cpu.load(record.data, start_address: record.address, set_reset_vector: false)
+        end
+
+        cpu.write_word(CPU::RESET_VECTOR, first_address) if set_reset_vector && first_address
+        first_address
+      end
+    end
+
+    # Parses Intel HEX text into a loadable document.
+    #
+    # @param source [String] the Intel HEX text
+    # @return [Document] the parsed document
+    def parse(source)
+      records = []
+      seen_eof = false
+
+      source.each_line.with_index(1) do |line, line_number|
+        stripped = line.strip
+        next if stripped.empty?
+
+        raise IntelHexError, "Unexpected data after EOF record on line #{line_number}" if seen_eof
+
+        record = parse_record(stripped, line_number)
+        records << record
+        seen_eof = true if record.record_type == 0x01
+      end
+
+      raise IntelHexError, 'Intel HEX document is missing an EOF record' unless seen_eof
+
+      Document.new(records:)
+    end
+
+    private
+
+    # Parses a single Intel HEX line and validates its checksum.
+    #
+    # @param line [String] the raw line content
+    # @param line_number [Integer] the source line number
+    # @return [Record] the parsed record
+    def parse_record(line, line_number)
+      raise IntelHexError, "Intel HEX line #{line_number} must start with ':'" unless line.start_with?(':')
+
+      hex = line[1..]
+      raise IntelHexError, "Intel HEX line #{line_number} has an odd number of hex digits" if hex.length.odd?
+
+      bytes = hex.scan(/../).map do |pair|
+        Integer(pair, 16)
+      rescue ArgumentError
+        raise IntelHexError, "Intel HEX line #{line_number} contains invalid hex"
+      end
+
+      raise IntelHexError, "Intel HEX line #{line_number} is too short" if bytes.length < 5
+
+      byte_count = bytes[0]
+      address = (bytes[1] << 8) | bytes[2]
+      record_type = bytes[3]
+      data = bytes[4...-1]
+      checksum = bytes[-1]
+
+      expected_length = byte_count + 5
+      raise IntelHexError, "Intel HEX line #{line_number} length does not match byte count" if bytes.length != expected_length
+
+      expected_checksum = ((-bytes[0...-1].sum) & 0xff)
+      raise IntelHexError, "Intel HEX line #{line_number} has an invalid checksum" if checksum != expected_checksum
+
+      raise IntelHexError, format('Intel HEX line %d uses unsupported record type 0x%02X', line_number, record_type) unless [0x00, 0x01].include?(record_type)
+
+      raise IntelHexError, "Intel HEX EOF record on line #{line_number} must not contain data" if record_type == 0x01 && !data.empty?
+
+      Record.new(address:, record_type:, data:)
+    end
+  end
+end

data/lib/mos6502/workbench/machine.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative 'bus'
+require_relative 'cpu'
+
+module MOS6502
+  # Small composition root for building a 6502-based computer.
+  #
+  # A machine owns a {Bus}, a {CPU}, and any mapped devices. It provides a
+  # cleaner place than {CPU} to describe whole-system memory maps such as
+  # "RAM here, ROM there, I/O in the middle".
+  class Machine
+    # @return [Bus] the machine address bus
+    attr_reader :bus
+    # @return [CPU] the attached CPU core
+    attr_reader :cpu
+
+    # Creates a new machine around a bus and CPU.
+    #
+    # @param bus [Bus] the machine bus
+    # @param cpu [CPU, nil] an optional pre-built CPU
+    # @param install_default_reset_vector [Boolean] whether to install the CPU's standalone reset vector
+    def initialize(bus: Bus.new, cpu: nil, install_default_reset_vector: false)
+      @bus = bus
+      @cpu = cpu || CPU.new(bus:, install_default_reset_vector:)
+    end
+
+    # Maps a RAM device into the machine address space.
+    #
+    # @param start_address [Integer] the first mapped address
+    # @param end_address [Integer] the last mapped address
+    # @param fill_byte [Integer] the byte used on RAM reset
+    # @param size [Integer, nil] an optional explicit RAM size
+    # @param device_offset [Integer] the first exposed device-local byte
+    # @return [RAM] the mapped RAM device
+    def map_ram(start_address:, end_address:, fill_byte: 0x00, size: nil, device_offset: 0)
+      length = end_address - start_address + 1
+      ram = RAM.new(size || length, fill_byte:)
+      bus.map(ram, start_address:, end_address:, device_offset:)
+    end
+
+    # Maps an arbitrary device into the machine address space.
+    #
+    # @param device [Device] the device to map
+    # @param start_address [Integer] the first mapped address
+    # @param end_address [Integer] the last mapped address
+    # @param device_offset [Integer] the first exposed device-local byte
+    # @return [Device] the mapped device
+    def map_device(device, start_address:, end_address:, device_offset: 0)
+      bus.map(device, start_address:, end_address:, device_offset:)
+    end
+
+    # Maps a ROM image into the machine address space.
+    #
+    # @param bytes [String, #to_a] the ROM image
+    # @param start_address [Integer] the first mapped address
+    # @param end_address [Integer, nil] the last mapped address
+    # @param device_offset [Integer] the first exposed device-local byte
+    # @param fill_byte [Integer] the byte returned for padded reads
+    # @return [ROM] the mapped ROM device
+    def map_rom(bytes, start_address:, end_address: nil, device_offset: 0, fill_byte: 0xff)
+      rom = ROM.new(bytes, fill_byte:)
+      end_address ||= start_address + rom.size - 1
+      bus.map(rom, start_address:, end_address:, device_offset:)
+    end
+
+    # Resets the CPU without erasing machine memory.
+    #
+    # @param program_counter [Integer, nil] an optional explicit reset address
+    # @return [Machine] the machine
+    def reset(program_counter: nil)
+      cpu.reset(program_counter:)
+      self
+    end
+
+    # Performs a full power-on sequence for the machine.
+    #
+    # Unlike the standalone CPU default, this does not install a synthetic reset
+    # vector, which allows ROM-mapped systems to boot from their real vectors.
+    #
+    # @return [Machine] the machine
+    def power_on
+      cpu.power_on(install_default_reset_vector: false)
+      self
+    end
+
+    # Loads raw bytes into the machine through the CPU convenience API.
+    #
+    # @param program [String, #to_a] the bytes to load
+    # @param start_address [Integer] where to place the first byte
+    # @param set_reset_vector [Boolean] whether to update the reset vector
+    # @return [Integer] the start address used for the load
+    def load(program, start_address: CPU::DEFAULT_LOAD_ADDRESS, set_reset_vector: true)
+      cpu.load(program, start_address:, set_reset_vector:)
+    end
+
+    # Loads Intel HEX text into the machine.
+    #
+    # @param source [String] the Intel HEX text to parse
+    # @param set_reset_vector [Boolean] whether to update the reset vector
+    # @return [Integer, nil] the lowest loaded address
+    def load_intel_hex(source, set_reset_vector: true)
+      cpu.load_intel_hex(source, set_reset_vector:)
+    end
+
+    # Executes one CPU instruction.
+    #
+    # @return [Integer] the executed opcode byte
+    def step
+      opcode = cpu.step
+      bus.tick(cpu.last_cycles)
+      opcode
+    end
+
+    # Executes a fixed number of CPU instructions.
+    #
+    # @param max_instructions [Integer] the number of instructions to execute
+    # @return [Machine] the machine
+    def run(max_instructions:)
+      max_instructions.times { step }
+      self
+    end
+
+    # Services a maskable interrupt and ticks mapped devices when taken.
+    #
+    # @return [Boolean] true when the IRQ was taken
+    def irq
+      taken = cpu.irq
+      bus.tick(7) if taken
+      taken
+    end
+
+    # Services a non-maskable interrupt and ticks mapped devices.
+    #
+    # @return [Boolean] always true
+    def nmi
+      cpu.nmi.tap { bus.tick(7) }
+    end
+  end
+end