mos6502-workbench 1.0.0

data/lib/mos6502/workbench/memory.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative 'device'
+
+module MOS6502
+  # Shared CPU memory helpers backed by an external bus.
+  #
+  # The CPU still exposes convenient `read_byte`, `write_byte`, `read_word`, and
+  # `write_word` helpers, but the actual storage and address decoding now live in
+  # {Bus} and mapped devices such as {RAM} and {ROM}.
+  module Memory
+    MEMORY_SIZE = 0x10000
+
+    # Resets the attached bus and any mapped devices.
+    #
+    # @return [Bus] the reset bus
+    def memory_reset
+      @bus.reset
+    end
+
+    # Reads a single byte from the current bus.
+    #
+    # @param addr [Integer] the address to read from
+    # @return [Integer] the byte stored at the wrapped address
+    def read_byte(addr)
+      @bus.read_byte(addr)
+    end
+
+    # Writes a single byte to the current bus.
+    #
+    # @param addr [Integer] the address to write to
+    # @param value [Integer] the value to store
+    # @return [Integer] the stored byte value
+    def write_byte(addr, value)
+      @bus.write_byte(addr, value)
+    end
+
+    # Writes a 16-bit little-endian word through the bus.
+    #
+    # @param addr [Integer] the starting address
+    # @param value [Integer] the 16-bit value to write
+    # @return [Integer] the written word value
+    def write_word(addr, value)
+      write_byte(addr, value)
+      write_byte(addr + 1, value >> 8)
+    end
+
+    # Reads a 16-bit little-endian word through the bus.
+    #
+    # @param addr [Integer] the starting address
+    # @return [Integer] the reconstructed 16-bit value
+    def read_word(addr)
+      read_byte(addr) | (read_byte(addr + 1) << 8)
+    end
+  end
+
+  # Simple read-write memory device.
+  #
+  # RAM stores a fixed-size byte array and wraps offsets to the configured device
+  # size, which makes it suitable for use either as full system RAM or as a
+  # smaller device window mapped into a subset of the address space.
+  class RAM < Device
+    # @return [Integer] the size of the device in bytes
+    attr_reader :size
+
+    # Creates a new RAM device.
+    #
+    # @param size [Integer] the size of the device in bytes
+    # @param fill_byte [Integer] the byte used to initialise memory on reset
+    # @raise [ArgumentError] if the size is not positive
+    def initialize(size = Memory::MEMORY_SIZE, fill_byte: 0x00)
+      super()
+      raise ArgumentError, 'RAM size must be positive' unless size.positive?
+
+      @size = size
+      @fill_byte = fill_byte & 0xff
+      reset
+    end
+
+    # Resets every byte in the RAM device to its fill byte.
+    #
+    # @return [RAM] the RAM device
+    def reset
+      @bytes = Array.new(size, @fill_byte)
+      self
+    end
+
+    # Reads a byte from the RAM device.
+    #
+    # @param address [Integer] the device-local byte offset
+    # @return [Integer] the stored byte value
+    def read_byte(address)
+      @bytes.fetch(normalize_offset(address))
+    end
+
+    # Writes a byte into the RAM device.
+    #
+    # @param address [Integer] the device-local byte offset
+    # @param value [Integer] the value to store
+    # @return [Integer] the stored byte value
+    def write_byte(address, value)
+      @bytes[normalize_offset(address)] = value & 0xff
+    end
+
+    private
+
+    # Wraps an address to the size of the RAM device.
+    #
+    # @param address [Integer] the device-local byte offset
+    # @return [Integer] the wrapped device-local offset
+    def normalize_offset(address)
+      address % size
+    end
+  end
+
+  # Read-only memory device.
+  #
+  # Writes are ignored, matching the common emulator convention for ROM-backed
+  # regions.
+  class ROM < Device
+    # @return [Integer] the size of the ROM image in bytes
+    attr_reader :size
+
+    # Creates a new ROM device from raw bytes.
+    #
+    # @param bytes [String, #to_a] the ROM image
+    # @param fill_byte [Integer] the byte returned for padded reads
+    def initialize(bytes, fill_byte: 0xff)
+      super()
+      @bytes = bytes.is_a?(String) ? bytes.bytes : bytes.to_a
+      @fill_byte = fill_byte & 0xff
+      @size = @bytes.length
+    end
+
+    # ROM reset is a no-op because the contents are immutable.
+    #
+    # @return [ROM] the ROM device
+    def reset
+      self
+    end
+
+    # Reads a byte from the ROM image.
+    #
+    # @param address [Integer] the device-local byte offset
+    # @return [Integer] the stored byte, or the fill byte for padded reads
+    def read_byte(address)
+      @bytes.fetch(address, @fill_byte)
+    end
+
+    # Ignores writes to the ROM image.
+    #
+    # @param _address [Integer] the device-local byte offset
+    # @param value [Integer] the attempted write value
+    # @return [Integer] the masked attempted write value
+    def write_byte(_address, value)
+      value & 0xff
+    end
+  end
+end

data/lib/mos6502/workbench/registers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module MOS6502
+  # Register helpers shared by the CPU implementation.
+  module Registers
+    # The 6502 general-purpose registers:
+    # accumulator (`A`), index register X, and index register Y.
+    attr_accessor :register_x, :register_y, :accumulator
+
+    # Restores the programmer-visible data registers to their reset state.
+    #
+    # @return [void]
+    def registers_reset
+      @register_x = 0
+      @register_y = 0
+      @accumulator = 0
+    end
+  end
+end

data/lib/mos6502/workbench/tui.rb

@@ -0,0 +1,537 @@
+# frozen_string_literal: true
+
+require 'ratatui_ruby'
+
+module MOS6502
+  # Interactive terminal visualizer for the 6502 CPU state.
+  #
+  # The TUI is intentionally optional. The rest of the toolchain still works in
+  # plain CLI mode, while this class provides a richer execution cockpit when
+  # launched explicitly.
+  class TUI
+    HistoryEntry = Data.define(:instruction_count, :address, :opcode, :text)
+
+    DEFAULT_STEP_DELAYS = [0.40, 0.20, 0.10, 0.05, 0.02].freeze
+    DEFAULT_WATCH_BASE = 0x0000
+    DEFAULT_THEME = :classic
+    DISASSEMBLY_WINDOW_SIZE = 18
+    HISTORY_LIMIT = 18
+    TRACE_LIMIT = 48
+
+    THEMES = {
+      classic: {
+        surface: 235,
+        panel_header: 236,
+        panel_program: 235,
+        panel_registers: 236,
+        panel_trace: 235,
+        panel_history: 235,
+        panel_status: 236,
+        panel_pc: 235,
+        panel_watch: 236,
+        panel_stack: 235,
+        panel_footer: 234,
+        text: 255,
+        muted: 245,
+        accent: 45,
+        accent_alt: 78,
+        warm: 221,
+        danger: 203,
+        highlight: 250
+      }.freeze,
+      vivid: {
+        surface: 17,
+        panel_header: 19,
+        panel_program: 23,
+        panel_registers: 54,
+        panel_trace: 22,
+        panel_history: 58,
+        panel_status: 28,
+        panel_pc: 53,
+        panel_watch: 52,
+        panel_stack: 18,
+        panel_footer: 17,
+        text: 255,
+        muted: 250,
+        accent: 51,
+        accent_alt: 83,
+        warm: 227,
+        danger: 204,
+        highlight: 230
+      }.freeze,
+      mono: {
+        surface: 235,
+        panel_header: 236,
+        panel_program: 235,
+        panel_registers: 236,
+        panel_trace: 235,
+        panel_history: 235,
+        panel_status: 236,
+        panel_pc: 235,
+        panel_watch: 236,
+        panel_stack: 235,
+        panel_footer: 234,
+        text: 255,
+        muted: 247,
+        accent: 252,
+        accent_alt: 250,
+        warm: 252,
+        danger: 255,
+        highlight: 248
+      }.freeze
+    }.freeze
+
+    attr_reader :cpu, :program, :title, :history, :error_message, :watch_base, :paused, :running, :step_delays, :speed_index, :theme_name
+
+    # @return [Array<Symbol>] the supported theme names
+    def self.theme_names
+      THEMES.keys
+    end
+
+    # @param cpu [CPU] the CPU instance being visualized
+    # @param program [Assembler::Program] the loaded program metadata
+    # @param title [String] the title shown in the header
+    # @param step_delays [Array<Float>] available autoplay speeds in seconds per instruction
+    # @param start_paused [Boolean] whether to begin in paused mode
+    # @param watch_base [Integer, nil] the start address of the adjustable memory panel
+    # @param theme [String, Symbol] the visual theme name
+    def initialize(cpu:, program:, title:, step_delays: DEFAULT_STEP_DELAYS, start_paused: true, watch_base: nil, theme: DEFAULT_THEME)
+      @cpu = cpu
+      @program = program
+      @title = title
+      @step_delays = step_delays
+      @paused = start_paused
+      @running = true
+      @watch_base = resolve_watch_base(watch_base)
+      @speed_index = [step_delays.length / 2, step_delays.length - 1].min
+      @theme_name, @palette = resolve_theme(theme)
+      @error_message = nil
+      @status_message = start_paused ? 'Paused at reset vector. Press n to step or space to run.' : 'Running.'
+      @history = []
+      @accumulator_trace = [cpu.accumulator]
+      @listing = build_listing
+    end
+
+    # Starts the interactive terminal session.
+    #
+    # @return [TUI] the TUI instance
+    def run
+      RatatuiRuby.run do
+        while running
+          RatatuiRuby.draw { |frame| render(frame) }
+          event = RatatuiRuby.poll_event(timeout: paused ? 0.10 : current_step_delay)
+          process_event_loop(event)
+        end
+      end
+
+      self
+    end
+
+    # Renders a single frame.
+    #
+    # @param frame [RatatuiRuby::Frame] the current frame
+    # @return [void]
+    def render(frame)
+      header_area, body_area, footer_area = split(frame.area, :vertical, [
+                                                    constraint(:length, 3),
+                                                    constraint(:fill, 1),
+                                                    constraint(:length, 3)
+                                                  ])
+
+      left_area, right_area = split(body_area, :horizontal, [
+                                      constraint(:fill, 1),
+                                      constraint(:length, 38)
+                                    ])
+
+      disassembly_area, history_area = split(left_area, :vertical, [
+                                               constraint(:fill, 1),
+                                               constraint(:length, 10)
+                                             ])
+
+      metrics_area, status_area, memory_area = split(right_area, :vertical, [
+                                                       constraint(:length, 8),
+                                                       constraint(:length, 5),
+                                                       constraint(:fill, 1)
+                                                     ])
+
+      registers_area, trace_area = split(metrics_area, :vertical, [
+                                           constraint(:length, 4),
+                                           constraint(:fill, 1)
+                                         ])
+
+      current_page_area, watch_area, stack_area = split(memory_area, :vertical, [
+                                                          constraint(:fill, 1),
+                                                          constraint(:length, 8),
+                                                          constraint(:length, 8)
+                                                        ])
+
+      pc_rows = 6
+      pc_cols = memory_columns(current_page_area)
+      watch_rows = 4
+      watch_cols = memory_columns(watch_area)
+
+      frame.render_widget(header_widget, header_area)
+      frame.render_widget(disassembly_widget, disassembly_area)
+      frame.render_widget(history_widget, history_area)
+      frame.render_widget(registers_widget, registers_area)
+      frame.render_widget(trace_widget, trace_area)
+      frame.render_widget(status_widget, status_area)
+      frame.render_widget(
+        memory_widget('PC Window', pc_window_base(rows: pc_rows, cols: pc_cols), rows: pc_rows, cols: pc_cols,
+                                                                                 highlight: cpu.program_counter), current_page_area
+      )
+      frame.render_widget(memory_widget("Watch $#{format('%04X', watch_base)}", watch_base, rows: watch_rows, cols: watch_cols), watch_area)
+      frame.render_widget(stack_widget, stack_area)
+      frame.render_widget(footer_widget, footer_area)
+    end
+
+    # Handles a single event.
+    #
+    # @param event [RatatuiRuby::Event] the event to process
+    # @return [void]
+    def handle_event(event)
+      if event.resize?
+        @status_message = "Resized to #{event.width}x#{event.height}."
+        return
+      end
+
+      return unless event.key?
+
+      case event.code
+      when 'q', 'esc'
+        @running = false
+      when ' '
+        toggle_pause
+      when 'n'
+        step_once if paused
+      when 'r'
+        reset_cpu
+      when '['
+        adjust_speed(-1)
+      when ']'
+        adjust_speed(1)
+      when 'h'
+        move_watch(-0x20)
+      when 'l'
+        move_watch(0x20)
+      end
+    end
+
+    # Executes a single instruction and records it for the UI.
+    #
+    # @return [Integer, nil] the opcode that was stepped, if any
+    def step_once
+      line = current_line
+      opcode = cpu.step
+      append_history(line, opcode)
+      @error_message = nil
+      @status_message = "Stepped #{line&.text || format('.byte $%02X', opcode)}."
+      opcode
+    rescue StandardError => e
+      @paused = true
+      @error_message = e.message
+      @status_message = 'Execution paused due to an error.'
+      nil
+    ensure
+      trim_accumulator_trace
+    end
+
+    # Resets the CPU and clears transient view state.
+    #
+    # @return [void]
+    def reset_cpu
+      cpu.reset
+      @history.clear
+      @accumulator_trace = [cpu.accumulator]
+      @error_message = nil
+      @paused = true
+      @status_message = 'CPU reset. Press n to step or space to run.'
+    end
+
+    private
+
+    attr_reader :palette
+
+    def resolve_theme(theme)
+      name = theme.to_sym
+      palette = THEMES[name]
+      raise ArgumentError, "Unknown TUI theme #{theme.inspect}. Available themes: #{THEMES.keys.join(', ')}" unless palette
+
+      [name, palette]
+    end
+
+    def resolve_watch_base(watch_base)
+      return watch_base & 0xffff unless watch_base.nil?
+
+      default_watch_base
+    end
+
+    def default_watch_base
+      (program.entry_point || program.start_address || DEFAULT_WATCH_BASE) & 0xffff
+    end
+
+    def process_event_loop(event)
+      if event.none?
+        step_once unless paused
+      else
+        handle_event(event)
+      end
+    end
+
+    def build_listing
+      program.segments.sort_by(&:start_address).flat_map do |segment|
+        Disassembler.new.disassemble(segment.bytes, start_address: segment.start_address)
+      end
+    end
+
+    def current_line
+      @listing.find { |line| line.address == cpu.program_counter }
+    end
+
+    def current_listing_index
+      @listing.index { |line| line.address == cpu.program_counter } || 0
+    end
+
+    def current_step_delay
+      step_delays.fetch(speed_index)
+    end
+
+    def toggle_pause
+      @paused = !paused
+      @status_message = paused ? 'Paused.' : format('Running at %.2fs per instruction.', current_step_delay)
+    end
+
+    def adjust_speed(delta)
+      @speed_index = (speed_index + delta).clamp(0, step_delays.length - 1)
+      @status_message = format('Speed set to %.2fs per instruction.', current_step_delay)
+    end
+
+    def move_watch(delta)
+      @watch_base = (watch_base + delta) & 0xffff
+      @status_message = format('Watch window moved to $%04X.', watch_base)
+    end
+
+    def append_history(line, opcode)
+      entry = HistoryEntry.new(
+        instruction_count: cpu.instruction_count,
+        address: line&.address || cpu.program_counter,
+        opcode: opcode,
+        text: line&.text || format('.byte $%02X', opcode)
+      )
+      @history.unshift(entry)
+      @history.slice!(HISTORY_LIMIT, @history.length)
+      @accumulator_trace << cpu.accumulator
+    end
+
+    def trim_accumulator_trace
+      @accumulator_trace = @accumulator_trace.last(TRACE_LIMIT)
+    end
+
+    def pc_window_base(rows:, cols:)
+      window_size = rows * cols
+      centered_base = (cpu.program_counter - (window_size / 2)) & 0xffff
+      (centered_base - (centered_base % cols)) & 0xffff
+    end
+
+    def memory_columns(area, max_cols: 8)
+      inner_width = [area.width - 2, 1].max
+      usable_width = [inner_width - 7, 1].max
+      (usable_width / 4).clamp(1, max_cols)
+    end
+
+    def split(area, direction, constraints)
+      RatatuiRuby::Layout::Layout.split(area, direction:, constraints:)
+    end
+
+    def constraint(kind, value)
+      RatatuiRuby::Layout::Constraint.public_send(kind, value)
+    end
+
+    def panel_block(title, color:, background: palette[:surface])
+      RatatuiRuby::Widgets::Block.new(
+        title:,
+        borders: %i[top right bottom left],
+        border_style: style(fg: color, bg: background, modifiers: [:bold]),
+        style: style(bg: background)
+      )
+    end
+
+    def style(fg: nil, bg: nil, modifiers: [])
+      RatatuiRuby::Style::Style.new(fg:, bg:, modifiers:)
+    end
+
+    def header_widget
+      RatatuiRuby::Widgets::Paragraph.new(
+        text: [
+          "MOS 6502 Studio  #{title}",
+          format('PC $%04X  OP %s  Mode %s', cpu.program_counter, last_opcode_text, paused ? 'PAUSED' : 'RUNNING')
+        ].join("\n"),
+        block: panel_block('Live Session', color: palette[:accent], background: palette[:panel_header]),
+        style: style(fg: palette[:text], bg: palette[:panel_header], modifiers: %i[bold])
+      )
+    end
+
+    def disassembly_widget
+      current_index = current_listing_index
+      window_start = disassembly_window_start(current_index)
+      window_end = [window_start + DISASSEMBLY_WINDOW_SIZE, @listing.length].min
+      visible = @listing[window_start...window_end]
+      selected = visible.index { |line| line.address == cpu.program_counter } || 0
+
+      items = if visible.empty?
+                ['No decoded instructions available.']
+              else
+                visible.map do |line|
+                  bytes = line.bytes.map { |byte| format('%02X', byte) }.join(' ').ljust(8)
+                  format('$%04X  %-8s %s', line.address, bytes, line.text)
+                end
+              end
+
+      RatatuiRuby::Widgets::List.new(
+        items:,
+        selected_index: selected,
+        highlight_symbol: '>> ',
+        highlight_style: style(fg: 232, bg: palette[:highlight], modifiers: %i[bold]),
+        block: panel_block('Program', color: palette[:accent], background: palette[:panel_program]),
+        style: style(fg: palette[:text], bg: palette[:panel_program])
+      )
+    end
+
+    def disassembly_window_start(current_index)
+      max_start = [@listing.length - DISASSEMBLY_WINDOW_SIZE, 0].max
+      preferred_start = current_index - (DISASSEMBLY_WINDOW_SIZE / 2)
+
+      preferred_start.clamp(0, max_start)
+    end
+
+    def history_widget
+      items = if history.empty?
+                ['No instructions executed yet.']
+              else
+                history.map do |entry|
+                  format('#%04d  $%04X  %s', entry.instruction_count, entry.address, entry.text)
+                end
+              end
+
+      RatatuiRuby::Widgets::List.new(
+        items:,
+        block: panel_block('Recent Instructions', color: palette[:warm], background: palette[:panel_history]),
+        style: style(fg: palette[:text], bg: palette[:panel_history])
+      )
+    end
+
+    def registers_widget
+      RatatuiRuby::Widgets::Paragraph.new(
+        text: [
+          format('A  $%02X    X  $%02X    Y  $%02X', cpu.accumulator, cpu.register_x, cpu.register_y),
+          format('PC $%04X   SP $%02X   OP %s', cpu.program_counter, cpu.stack_pointer, last_opcode_text)
+        ].join("\n"),
+        block: panel_block('Registers', color: palette[:accent], background: palette[:panel_registers]),
+        style: style(fg: palette[:text], bg: palette[:panel_registers], modifiers: %i[bold])
+      )
+    end
+
+    def trace_widget
+      RatatuiRuby::Widgets::Sparkline.new(
+        data: @accumulator_trace,
+        max: 255,
+        block: panel_block('Accumulator Trace', color: palette[:accent_alt], background: palette[:panel_trace]),
+        style: style(fg: palette[:accent_alt], bg: palette[:panel_trace])
+      )
+    end
+
+    def status_widget
+      RatatuiRuby::Widgets::Paragraph.new(
+        text: [
+          format('STATUS $%02X    COUNT %d', cpu.flags_encode, cpu.instruction_count),
+          flag_summary,
+          format('Speed %.2fs    Watch $%04X', current_step_delay, watch_base)
+        ].join("\n"),
+        block: panel_block('CPU State', color: palette[:accent_alt], background: palette[:panel_status]),
+        style: style(fg: palette[:text], bg: palette[:panel_status])
+      )
+    end
+
+    def flag_summary
+      [
+        flag_chip('N', cpu.negative?),
+        flag_chip('V', cpu.overflow?),
+        flag_chip('B', cpu.break?),
+        flag_chip('D', cpu.decimal?),
+        flag_chip('I', cpu.interrupt?),
+        flag_chip('Z', cpu.zero?),
+        flag_chip('C', cpu.carry?)
+      ].join(' ')
+    end
+
+    def flag_chip(label, active)
+      active ? "[#{label}]" : " #{label} "
+    end
+
+    def memory_widget(title, base, rows:, cols:, highlight: nil)
+      background = case title
+                   when 'PC Window' then palette[:panel_pc]
+                   when /\AWatch/ then palette[:panel_watch]
+                   else palette[:surface]
+                   end
+      RatatuiRuby::Widgets::Paragraph.new(
+        text: memory_dump(base, rows:, cols:, highlight:),
+        block: panel_block(title, color: palette[:warm], background:),
+        style: style(fg: palette[:text], bg: background)
+      )
+    end
+
+    def stack_widget
+      RatatuiRuby::Widgets::Paragraph.new(
+        text: stack_dump,
+        block: panel_block('Stack', color: palette[:accent], background: palette[:panel_stack]),
+        style: style(fg: palette[:text], bg: palette[:panel_stack])
+      )
+    end
+
+    def footer_widget
+      color = error_message ? palette[:danger] : palette[:muted]
+      message = error_message || @status_message
+
+      RatatuiRuby::Widgets::Paragraph.new(
+        text: [
+          'Controls: space run/pause  n step  r reset  [ ] speed  h l memory  q quit',
+          message
+        ].join("\n"),
+        block: panel_block('Command Deck', color:, background: palette[:panel_footer]),
+        style: style(fg: palette[:text], bg: palette[:panel_footer], modifiers: %i[bold])
+      )
+    end
+
+    def memory_dump(base, rows:, cols:, highlight: nil)
+      rows.times.map do |row|
+        address = (base + (row * cols)) & 0xffff
+        bytes = cols.times.map do |offset|
+          cell_address = (address + offset) & 0xffff
+          token = format('%02X', cpu.read_byte(cell_address))
+          cell_address == highlight ? ">#{token}<" : " #{token} "
+        end.join
+        format('$%04X: %s', address, bytes)
+      end.join("\n")
+    end
+
+    def stack_dump
+      stack_top = (cpu.stack_pointer + 1) & 0xff
+      lines = [
+        format('SP $%02X  next pop $%04X', cpu.stack_pointer, 0x0100 | stack_top)
+      ]
+
+      5.times do |index|
+        address = 0x0100 | ((stack_top + index) & 0xff)
+        marker = index.zero? ? ' <- top' : ''
+        lines << format('$%04X: %02X%s', address, cpu.read_byte(address), marker)
+      end
+
+      lines.join("\n")
+    end
+
+    def last_opcode_text
+      cpu.last_opcode.nil? ? '--' : format('$%02X', cpu.last_opcode)
+    end
+  end
+end