mos6502-workbench 1.0.0

data/lib/mos6502/workbench/bus.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require_relative 'memory'
+
+module MOS6502
+  # Address-decoding bus for the 6502's 16-bit address space.
+  #
+  # Devices are mapped into fixed address ranges. Reads and writes are routed to
+  # the mapped device with the appropriate device-local offset. Unmapped reads
+  # return the configured open-bus value and unmapped writes are ignored.
+  class Bus
+    # Internal mapping descriptor tying an address range to a concrete device.
+    Mapping = Struct.new(:start_address, :end_address, :device, :device_offset) do
+      # Returns the size of the mapped range in bytes.
+      #
+      # @return [Integer] the number of mapped bytes
+      def length
+        end_address - start_address + 1
+      end
+
+      # Tests whether the supplied bus address falls inside the mapped range.
+      #
+      # @param address [Integer] the bus address to test
+      # @return [Boolean] true when the mapping covers the address
+      def cover?(address)
+        address.between?(start_address, end_address)
+      end
+
+      # Reads a byte from the mapped device.
+      #
+      # @param address [Integer] the bus address being accessed
+      # @return [Integer] the device byte value
+      def read_byte(address)
+        device.read_byte(offset_for(address))
+      end
+
+      # Writes a byte into the mapped device.
+      #
+      # @param address [Integer] the bus address being accessed
+      # @param value [Integer] the value to store
+      # @return [Integer] the stored device byte value
+      def write_byte(address, value)
+        device.write_byte(offset_for(address), value)
+      end
+
+      # Tests whether this mapping overlaps another mapping.
+      #
+      # @param other [Mapping] another mapped range
+      # @return [Boolean] true when the ranges overlap
+      def overlaps?(other)
+        start_address <= other.end_address && other.start_address <= end_address
+      end
+
+      private
+
+      # Converts a bus address into a device-local offset.
+      #
+      # @param address [Integer] the bus address being accessed
+      # @return [Integer] the corresponding device-local byte offset
+      def offset_for(address)
+        device_offset + address - start_address
+      end
+    end
+
+    # @return [Array<Mapping>] the installed address mappings
+    attr_reader :mappings
+
+    # Builds the default standalone 6502 memory map: 64 KiB of RAM.
+    #
+    # @return [Bus] a bus with a single full-address-space RAM mapping
+    def self.default
+      new.tap do |bus|
+        bus.map(RAM.new, start_address: 0x0000, end_address: 0xffff)
+      end
+    end
+
+    # Creates a new empty bus.
+    #
+    # @param open_bus_value [Integer] the value returned for unmapped reads
+    def initialize(open_bus_value: 0x00)
+      @open_bus_value = open_bus_value & 0xff
+      @mappings = []
+      @access_subscribers = []
+    end
+
+    # Maps a device into an address range.
+    #
+    # @param device [#read_byte, #write_byte] the device to map
+    # @param start_address [Integer] the first bus address handled by the mapping
+    # @param end_address [Integer] the last bus address handled by the mapping
+    # @param device_offset [Integer] the first device-local byte exposed by the mapping
+    # @return [Object] the mapped device
+    # @raise [ArgumentError] if the range is invalid, overlaps, or exceeds device size
+    def map(device, start_address:, end_address:, device_offset: 0)
+      validate_range!(start_address, end_address, device_offset)
+
+      mapping = Mapping.new(start_address, end_address, device, device_offset)
+
+      raise ArgumentError, 'Mapped address ranges must not overlap' if mappings.any? { |existing| existing.overlaps?(mapping) }
+
+      ensure_device_capacity!(mapping)
+
+      @mappings << mapping
+      @mappings.sort_by!(&:start_address)
+      device
+    end
+
+    # Registers a callback for every bus read and write.
+    #
+    # Subscribers receive a hash with:
+    #
+    # - `:operation` - `:read` or `:write`
+    # - `:address` - the normalized bus address
+    # - `:value` - the transferred byte
+    # - `:device` - the mapped device, or `nil` for open bus
+    # - `:mapped` - whether the access hit a mapped device
+    #
+    # @yieldparam event [Hash] the bus access event
+    # @return [Proc] the registered callback
+    def subscribe_accesses(&block)
+      raise ArgumentError, 'A block is required' unless block
+
+      @access_subscribers << block
+      block
+    end
+
+    # Removes a previously registered access callback.
+    #
+    # @param subscriber [Proc] the callback returned by {#subscribe_accesses}
+    # @return [Proc, nil] the removed callback
+    def unsubscribe_accesses(subscriber)
+      @access_subscribers.delete(subscriber)
+    end
+
+    # Resets every uniquely mapped device that responds to `reset`.
+    #
+    # @return [Bus] the bus
+    def reset
+      mappings.map(&:device).uniq.each do |device|
+        device.reset if device.respond_to?(:reset)
+      end
+      self
+    end
+
+    # Advances every uniquely mapped device by a number of CPU cycles.
+    #
+    # @param cycles [Integer] the number of elapsed CPU cycles
+    # @return [Bus] the bus
+    def tick(cycles)
+      mappings.map(&:device).uniq.each do |device|
+        device.tick(cycles) if device.respond_to?(:tick)
+      end
+      self
+    end
+
+    # Reads a byte from the mapped address space.
+    #
+    # @param address [Integer] the bus address to read
+    # @return [Integer] the routed byte value or the open-bus value
+    def read_byte(address)
+      normalized = normalize_address(address)
+      mapping = mapping_for(normalized)
+      unless mapping
+        emit_access(operation: :read, address: normalized, value: @open_bus_value, device: nil, mapped: false)
+        return @open_bus_value
+      end
+
+      value = mapping.read_byte(normalized)
+      emit_access(operation: :read, address: normalized, value:, device: mapping.device, mapped: true)
+      value
+    end
+
+    # Writes a byte into the mapped address space.
+    #
+    # @param address [Integer] the bus address to write
+    # @param value [Integer] the value to store
+    # @return [Integer] the stored byte value
+    def write_byte(address, value)
+      normalized = normalize_address(address)
+      mapping = mapping_for(normalized)
+      unless mapping
+        masked_value = value & 0xff
+        emit_access(operation: :write, address: normalized, value: masked_value, device: nil, mapped: false)
+        return masked_value
+      end
+
+      written = mapping.write_byte(normalized, value)
+      emit_access(operation: :write, address: normalized, value: written, device: mapping.device, mapped: true)
+      written
+    end
+
+    # Reads a little-endian 16-bit word from the address space.
+    #
+    # @param address [Integer] the starting bus address
+    # @return [Integer] the reconstructed 16-bit value
+    def read_word(address)
+      read_byte(address) | (read_byte(address + 1) << 8)
+    end
+
+    # Writes a little-endian 16-bit word into the address space.
+    #
+    # @param address [Integer] the starting bus address
+    # @param value [Integer] the 16-bit value to store
+    # @return [Integer] the written 16-bit value
+    def write_word(address, value)
+      write_byte(address, value)
+      write_byte(address + 1, value >> 8)
+      value & 0xffff
+    end
+
+    private
+
+    # Locates the mapping responsible for a normalized bus address.
+    #
+    # @param address [Integer] the wrapped 16-bit bus address
+    # @return [Mapping, nil] the matching mapping, if any
+    def mapping_for(address)
+      mappings.find { |mapping| mapping.cover?(address) }
+    end
+
+    # Wraps an address to the 6502's 16-bit bus width.
+    #
+    # @param address [Integer] the input address
+    # @return [Integer] the wrapped 16-bit address
+    def normalize_address(address)
+      address & 0xffff
+    end
+
+    # Validates a mapping range before installation.
+    #
+    # @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 offset
+    # @return [void]
+    # @raise [ArgumentError] if the arguments are invalid
+    def validate_range!(start_address, end_address, device_offset)
+      raise ArgumentError, 'Mapped addresses must be within 0x0000..0xFFFF' unless start_address.between?(0x0000, 0xffff) && end_address.between?(0x0000, 0xffff)
+      raise ArgumentError, 'Mapped address ranges must be ascending' if end_address < start_address
+      raise ArgumentError, 'Device offsets must be zero or positive' if device_offset.negative?
+    end
+
+    # Ensures that a mapping does not expose more bytes than the device provides.
+    #
+    # @param mapping [Mapping] the mapping being installed
+    # @return [void]
+    # @raise [ArgumentError] if the device is too small for the requested mapping
+    def ensure_device_capacity!(mapping)
+      return unless mapping.device.respond_to?(:size)
+
+      available = mapping.device.size - mapping.device_offset
+      return if available >= mapping.length
+
+      raise ArgumentError, 'Mapped range exceeds device capacity'
+    end
+
+    # Broadcasts a bus access event to registered subscribers.
+    #
+    # @param event [Hash] the event payload
+    # @return [void]
+    def emit_access(event)
+      @access_subscribers.each { |subscriber| subscriber.call(event) }
+    end
+  end
+end