mos6502-workbench 1.0.0

data/lib/mos6502/workbench/cpu.rb

@@ -0,0 +1,1292 @@
+# frozen_string_literal: true
+
+require_relative 'flags'
+require_relative 'bus'
+require_relative 'device'
+require_relative 'memory'
+require_relative 'registers'
+
+module MOS6502
+  # Raised when the CPU encounters an opcode that is not present in the decode table.
+  class UnsupportedOpcode < StandardError; end
+
+  # A MOS 6502 CPU core with memory, registers, flags, and opcode dispatch.
+  #
+  # The implementation is intentionally stateful so it can be stepped instruction
+  # by instruction, which makes it a good fit for future tracing, disassembly,
+  # assembler integration, and TUI visualisation.
+  class CPU
+    include Registers
+    include Flags
+    include Memory
+
+    # Default address used for raw program loading when no reset vector is supplied.
+    DEFAULT_LOAD_ADDRESS = 0x0600
+    # Base address of the 6502 hardware stack.
+    STACK_BASE = 0x0100
+    # Vector used for non-maskable interrupts.
+    NMI_VECTOR = 0xfffa
+    # Vector read on reset.
+    RESET_VECTOR = 0xfffc
+    # Vector used for IRQ and BRK.
+    IRQ_VECTOR = 0xfffe
+
+    # Official opcode table mapping each supported byte to a mnemonic and
+    # addressing mode.
+    #
+    # @return [Hash{Integer => Array<Symbol>}]
+    OPCODES = {
+      0x00 => %i[brk implied],
+      0x01 => %i[ora indirect_x],
+      0x05 => %i[ora zero_page],
+      0x06 => %i[asl zero_page],
+      0x08 => %i[php implied],
+      0x09 => %i[ora immediate],
+      0x0a => %i[asl accumulator],
+      0x0d => %i[ora absolute],
+      0x0e => %i[asl absolute],
+      0x10 => %i[bpl relative],
+      0x11 => %i[ora indirect_y],
+      0x15 => %i[ora zero_page_x],
+      0x16 => %i[asl zero_page_x],
+      0x18 => %i[clc implied],
+      0x19 => %i[ora absolute_y],
+      0x1d => %i[ora absolute_x],
+      0x1e => %i[asl absolute_x],
+      0x20 => %i[jsr absolute],
+      0x21 => %i[and indirect_x],
+      0x24 => %i[bit zero_page],
+      0x25 => %i[and zero_page],
+      0x26 => %i[rol zero_page],
+      0x28 => %i[plp implied],
+      0x29 => %i[and immediate],
+      0x2a => %i[rol accumulator],
+      0x2c => %i[bit absolute],
+      0x2d => %i[and absolute],
+      0x2e => %i[rol absolute],
+      0x30 => %i[bmi relative],
+      0x31 => %i[and indirect_y],
+      0x35 => %i[and zero_page_x],
+      0x36 => %i[rol zero_page_x],
+      0x38 => %i[sec implied],
+      0x39 => %i[and absolute_y],
+      0x3d => %i[and absolute_x],
+      0x3e => %i[rol absolute_x],
+      0x40 => %i[rti implied],
+      0x41 => %i[eor indirect_x],
+      0x45 => %i[eor zero_page],
+      0x46 => %i[lsr zero_page],
+      0x48 => %i[pha implied],
+      0x49 => %i[eor immediate],
+      0x4a => %i[lsr accumulator],
+      0x4c => %i[jmp absolute],
+      0x4d => %i[eor absolute],
+      0x4e => %i[lsr absolute],
+      0x50 => %i[bvc relative],
+      0x51 => %i[eor indirect_y],
+      0x55 => %i[eor zero_page_x],
+      0x56 => %i[lsr zero_page_x],
+      0x58 => %i[cli implied],
+      0x59 => %i[eor absolute_y],
+      0x5d => %i[eor absolute_x],
+      0x5e => %i[lsr absolute_x],
+      0x60 => %i[rts implied],
+      0x61 => %i[adc indirect_x],
+      0x65 => %i[adc zero_page],
+      0x66 => %i[ror zero_page],
+      0x68 => %i[pla implied],
+      0x69 => %i[adc immediate],
+      0x6a => %i[ror accumulator],
+      0x6c => %i[jmp indirect],
+      0x6d => %i[adc absolute],
+      0x6e => %i[ror absolute],
+      0x70 => %i[bvs relative],
+      0x71 => %i[adc indirect_y],
+      0x75 => %i[adc zero_page_x],
+      0x76 => %i[ror zero_page_x],
+      0x78 => %i[sei implied],
+      0x79 => %i[adc absolute_y],
+      0x7d => %i[adc absolute_x],
+      0x7e => %i[ror absolute_x],
+      0x81 => %i[sta indirect_x],
+      0x84 => %i[sty zero_page],
+      0x85 => %i[sta zero_page],
+      0x86 => %i[stx zero_page],
+      0x88 => %i[dey implied],
+      0x8a => %i[txa implied],
+      0x8c => %i[sty absolute],
+      0x8d => %i[sta absolute],
+      0x8e => %i[stx absolute],
+      0x90 => %i[bcc relative],
+      0x91 => %i[sta indirect_y],
+      0x94 => %i[sty zero_page_x],
+      0x95 => %i[sta zero_page_x],
+      0x96 => %i[stx zero_page_y],
+      0x98 => %i[tya implied],
+      0x99 => %i[sta absolute_y],
+      0x9a => %i[txs implied],
+      0x9d => %i[sta absolute_x],
+      0xa0 => %i[ldy immediate],
+      0xa1 => %i[lda indirect_x],
+      0xa2 => %i[ldx immediate],
+      0xa4 => %i[ldy zero_page],
+      0xa5 => %i[lda zero_page],
+      0xa6 => %i[ldx zero_page],
+      0xa8 => %i[tay implied],
+      0xa9 => %i[lda immediate],
+      0xaa => %i[tax implied],
+      0xac => %i[ldy absolute],
+      0xad => %i[lda absolute],
+      0xae => %i[ldx absolute],
+      0xb0 => %i[bcs relative],
+      0xb1 => %i[lda indirect_y],
+      0xb4 => %i[ldy zero_page_x],
+      0xb5 => %i[lda zero_page_x],
+      0xb6 => %i[ldx zero_page_y],
+      0xb8 => %i[clv implied],
+      0xb9 => %i[lda absolute_y],
+      0xba => %i[tsx implied],
+      0xbc => %i[ldy absolute_x],
+      0xbd => %i[lda absolute_x],
+      0xbe => %i[ldx absolute_y],
+      0xc0 => %i[cpy immediate],
+      0xc1 => %i[cmp indirect_x],
+      0xc4 => %i[cpy zero_page],
+      0xc5 => %i[cmp zero_page],
+      0xc6 => %i[dec zero_page],
+      0xc8 => %i[iny implied],
+      0xc9 => %i[cmp immediate],
+      0xca => %i[dex implied],
+      0xcc => %i[cpy absolute],
+      0xcd => %i[cmp absolute],
+      0xce => %i[dec absolute],
+      0xd0 => %i[bne relative],
+      0xd1 => %i[cmp indirect_y],
+      0xd5 => %i[cmp zero_page_x],
+      0xd6 => %i[dec zero_page_x],
+      0xd8 => %i[cld implied],
+      0xd9 => %i[cmp absolute_y],
+      0xdd => %i[cmp absolute_x],
+      0xde => %i[dec absolute_x],
+      0xe0 => %i[cpx immediate],
+      0xe1 => %i[sbc indirect_x],
+      0xe4 => %i[cpx zero_page],
+      0xe5 => %i[sbc zero_page],
+      0xe6 => %i[inc zero_page],
+      0xe8 => %i[inx implied],
+      0xe9 => %i[sbc immediate],
+      0xea => %i[nop implied],
+      0xec => %i[cpx absolute],
+      0xed => %i[sbc absolute],
+      0xee => %i[inc absolute],
+      0xf0 => %i[beq relative],
+      0xf1 => %i[sbc indirect_y],
+      0xf5 => %i[sbc zero_page_x],
+      0xf6 => %i[inc zero_page_x],
+      0xf8 => %i[sed implied],
+      0xf9 => %i[sbc absolute_y],
+      0xfd => %i[sbc absolute_x],
+      0xfe => %i[inc absolute_x]
+    }.freeze
+
+    # @return [Integer] the number of instructions executed since the last reset
+    attr_reader :instruction_count
+    # @return [Integer] the number of base CPU cycles observed since the last reset
+    attr_reader :cycle_count
+    # @return [Integer, nil] the most recently executed opcode byte
+    attr_reader :last_opcode
+    # @return [Integer] the base cycle cost of the most recent instruction
+    attr_reader :last_cycles
+    # @return [Integer] the current program counter
+    attr_reader :program_counter
+    # @return [Integer] the current stack pointer offset within page `0x0100`
+    attr_reader :stack_pointer
+    # @return [Bus] the address bus used for all memory access
+    attr_reader :bus
+
+    BRANCH_MNEMONICS = %i[bpl bmi bvc bvs bcc bcs bne beq].freeze
+    TWO_CYCLE_IMPLIED_MNEMONICS = %i[
+      clc cld cli clv
+      sec sed sei
+      dex dey inx iny
+      nop
+      tax tay tsx txa txs tya
+    ].freeze
+
+    # Creates a new CPU instance and powers it on.
+    #
+    # When no bus is supplied, the CPU installs a default standalone memory map
+    # consisting of 64 KiB of RAM and a synthetic reset vector pointing at
+    # {DEFAULT_LOAD_ADDRESS}. When a custom bus is supplied, callers can disable
+    # that convenience vector so a ROM-mapped machine can boot from real vectors.
+    #
+    # @param bus [Bus, nil] the address bus used by the CPU
+    # @param install_default_reset_vector [Boolean, nil] whether to install the standalone reset vector
+    # @return [void]
+    def initialize(bus: nil, install_default_reset_vector: nil)
+      @bus = bus || Bus.default
+      @step_subscribers = []
+      install_default_reset_vector = bus.nil? if install_default_reset_vector.nil?
+      power_on(install_default_reset_vector:)
+    end
+
+    # Performs a full power-on sequence.
+    #
+    # Unlike {#reset}, this also clears RAM and installs the default reset vector.
+    #
+    # @param install_default_reset_vector [Boolean] whether to install the standalone reset vector
+    # @return [CPU] the CPU instance
+    def power_on(install_default_reset_vector: true)
+      memory_reset
+      write_word(RESET_VECTOR, DEFAULT_LOAD_ADDRESS) if install_default_reset_vector
+      reset
+    end
+
+    # Resets the CPU registers and control state without clearing memory.
+    #
+    # This mirrors real 6502 usage more closely than erasing RAM on every reset,
+    # which is important once programs are loaded from binaries or an assembler.
+    #
+    # @param program_counter [Integer, nil] an optional explicit reset address
+    # @return [CPU] the CPU instance
+    def reset(program_counter: nil)
+      registers_reset
+      flags_reset
+      @stack_pointer = 0xfd
+      @instruction_count = 0
+      @cycle_count = 0
+      @last_opcode = nil
+      @last_cycles = 0
+      self.interrupt = true
+      @program_counter = program_counter || read_word(RESET_VECTOR)
+      @program_counter &= 0xffff
+      self
+    end
+
+    # Loads program bytes into memory.
+    #
+    # @param program [String, #to_a] the raw bytes to write
+    # @param start_address [Integer] where to place the first byte
+    # @param set_reset_vector [Boolean] whether to point the reset vector at the program
+    # @return [Integer] the start address used for the load
+    def load(program, start_address: DEFAULT_LOAD_ADDRESS, set_reset_vector: true)
+      bytes = program.is_a?(String) ? program.bytes : program.to_a
+      bytes.each_with_index do |byte, offset|
+        write_byte(start_address + offset, byte)
+      end
+      write_word(RESET_VECTOR, start_address) if set_reset_vector
+      start_address
+    end
+
+    # Loads an Intel HEX document directly into memory.
+    #
+    # The reset vector is pointed at the lowest loaded address by default, which
+    # matches the most common "load and run" workflow for assembled programs.
+    #
+    # @param source [String] the Intel HEX text to parse
+    # @param set_reset_vector [Boolean] whether to point the reset vector at the first record
+    # @return [Integer, nil] the lowest loaded address
+    # @raise [IntelHexError] if the document is malformed or unsupported
+    def load_intel_hex(source, set_reset_vector: true)
+      IntelHex.new.parse(source).load_into(self, set_reset_vector:)
+    end
+
+    # Fetches, decodes, and executes a single instruction.
+    #
+    # @return [Integer] the executed opcode byte
+    # @raise [UnsupportedOpcode] if the opcode is not present in {OPCODES}
+    def step
+      instruction_address = @program_counter
+      @last_opcode = fetch_byte
+      instruction = OPCODES[@last_opcode]
+      raise UnsupportedOpcode, format('Opcode 0x%02X is not implemented', @last_opcode) unless instruction
+
+      mnemonic, mode = instruction
+      send(mnemonic, mode)
+      @instruction_count += 1
+      @last_cycles = base_cycles_for(mnemonic, mode)
+      @cycle_count += @last_cycles
+      emit_step(
+        address: instruction_address,
+        opcode: @last_opcode,
+        mnemonic:,
+        mode:,
+        cycles: @last_cycles,
+        snapshot: snapshot
+      )
+      @last_opcode
+    end
+
+    # Executes a fixed number of instructions.
+    #
+    # @param max_instructions [Integer] how many instructions to execute
+    # @return [CPU] the CPU instance
+    def run(max_instructions:)
+      max_instructions.times { step }
+      self
+    end
+
+    # Services a maskable interrupt request.
+    #
+    # If the interrupt-disable flag is set, the IRQ is ignored.
+    #
+    # @return [Boolean] true when the IRQ was taken, false when it was masked
+    def irq
+      return false if interrupt?
+
+      interrupt_sequence(vector: IRQ_VECTOR, break_flag: false)
+      @cycle_count += 7
+      true
+    end
+
+    # Services a non-maskable interrupt.
+    #
+    # @return [Boolean] always true
+    def nmi
+      interrupt_sequence(vector: NMI_VECTOR, break_flag: false)
+      @cycle_count += 7
+      true
+    end
+
+    # Captures the externally visible CPU state as a hash.
+    #
+    # This is intended as a convenient integration point for tracers, tests,
+    # and future UI layers.
+    #
+    # @return [Hash<Symbol, Integer, nil>] a snapshot of the current CPU state
+    def snapshot
+      {
+        accumulator: accumulator,
+        register_x: register_x,
+        register_y: register_y,
+        stack_pointer: stack_pointer,
+        program_counter: program_counter,
+        status: flags_encode,
+        instruction_count: instruction_count,
+        cycle_count: cycle_count,
+        last_cycles: last_cycles,
+        last_opcode: last_opcode
+      }
+    end
+
+    # Registers a callback for each executed instruction.
+    #
+    # Subscribers receive a hash with the executed address, opcode, mnemonic,
+    # addressing mode, base cycles, and a post-instruction snapshot.
+    #
+    # @yieldparam event [Hash] the instruction event
+    # @return [Proc] the registered callback
+    def subscribe_steps(&block)
+      raise ArgumentError, 'A block is required' unless block
+
+      @step_subscribers << block
+      block
+    end
+
+    # Removes a previously registered step callback.
+    #
+    # @param subscriber [Proc] the callback returned by {#subscribe_steps}
+    # @return [Proc, nil] the removed callback
+    def unsubscribe_steps(subscriber)
+      @step_subscribers.delete(subscriber)
+    end
+
+    private
+
+    # Returns the base cycle cost for an opcode without dynamic penalties.
+    #
+    # These values intentionally exclude page-crossing and taken-branch penalties.
+    # They are useful for coarse timing and device ticking, but they are not yet a
+    # full cycle-accurate timing model.
+    #
+    # @param mnemonic [Symbol] the decoded mnemonic
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the base cycle count
+    def base_cycles_for(mnemonic, mode)
+      return 7 if mnemonic == :brk
+      return 6 if %i[jsr rts rti].include?(mnemonic)
+      return { absolute: 3, indirect: 5 }.fetch(mode) if mnemonic == :jmp
+      return 3 if %i[pha php].include?(mnemonic)
+      return 4 if %i[pla plp].include?(mnemonic)
+      return shift_cycles(mode) if %i[asl lsr rol ror].include?(mnemonic)
+      return inc_dec_cycles(mode) if %i[inc dec].include?(mnemonic)
+      return store_cycles(mnemonic, mode) if %i[sta stx sty].include?(mnemonic)
+      return bit_cycles(mode) if mnemonic == :bit
+      return ldy_cycles(mode) if mnemonic == :ldy
+      return ldx_cycles(mode) if mnemonic == :ldx
+      return compare_register_cycles(mode) if %i[cpy cpx].include?(mnemonic)
+      return 2 if BRANCH_MNEMONICS.include?(mnemonic)
+      return 2 if TWO_CYCLE_IMPLIED_MNEMONICS.include?(mnemonic)
+
+      default_mode_cycles(mnemonic, mode)
+    end
+
+    # Broadcasts an executed-instruction event to registered subscribers.
+    #
+    # @param event [Hash] the instruction event payload
+    # @return [void]
+    def emit_step(event)
+      @step_subscribers.each { |subscriber| subscriber.call(event) }
+    end
+
+    # Returns the base timing for shift and rotate operations.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the base cycle count
+    def shift_cycles(mode)
+      {
+        accumulator: 2,
+        zero_page: 5,
+        zero_page_x: 6,
+        absolute: 6,
+        absolute_x: 7
+      }.fetch(mode)
+    end
+
+    # Returns the base timing for increment and decrement memory operations.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the base cycle count
+    def inc_dec_cycles(mode)
+      {
+        zero_page: 5,
+        zero_page_x: 6,
+        absolute: 6,
+        absolute_x: 7
+      }.fetch(mode)
+    end
+
+    # Returns the base timing for store instructions.
+    #
+    # @param mnemonic [Symbol] the decoded mnemonic
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the base cycle count
+    def store_cycles(mnemonic, mode)
+      {
+        sta: {
+          zero_page: 3,
+          zero_page_x: 4,
+          absolute: 4,
+          absolute_x: 5,
+          absolute_y: 5,
+          indirect_x: 6,
+          indirect_y: 6
+        },
+        stx: {
+          zero_page: 3,
+          zero_page_y: 4,
+          absolute: 4
+        },
+        sty: {
+          zero_page: 3,
+          zero_page_x: 4,
+          absolute: 4
+        }
+      }.fetch(mnemonic).fetch(mode)
+    end
+
+    # Returns the base timing for `BIT`.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the base cycle count
+    def bit_cycles(mode)
+      { zero_page: 3, absolute: 4 }.fetch(mode)
+    end
+
+    # Returns the base timing for `LDY`.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the base cycle count
+    def ldy_cycles(mode)
+      {
+        immediate: 2,
+        zero_page: 3,
+        zero_page_x: 4,
+        absolute: 4,
+        absolute_x: 4
+      }.fetch(mode)
+    end
+
+    # Returns the base timing for `LDX`.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the base cycle count
+    def ldx_cycles(mode)
+      {
+        immediate: 2,
+        zero_page: 3,
+        zero_page_y: 4,
+        absolute: 4,
+        absolute_y: 4
+      }.fetch(mode)
+    end
+
+    # Returns the base timing for `CPX` and `CPY`.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the base cycle count
+    def compare_register_cycles(mode)
+      {
+        immediate: 2,
+        zero_page: 3,
+        absolute: 4
+      }.fetch(mode)
+    end
+
+    # Returns the default base timing for operand-reading instructions.
+    #
+    # @param mnemonic [Symbol] the decoded mnemonic
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the base cycle count
+    # @raise [ArgumentError] when no timing is defined for the mnemonic/mode pair
+    def default_mode_cycles(mnemonic, mode)
+      {
+        immediate: 2,
+        zero_page: 3,
+        zero_page_x: 4,
+        zero_page_y: 4,
+        absolute: 4,
+        absolute_x: 4,
+        absolute_y: 4,
+        indirect_x: 6,
+        indirect_y: 5
+      }.fetch(mode)
+    rescue KeyError
+      raise ArgumentError, "No base cycle timing is defined for #{mnemonic} #{mode}"
+    end
+
+    # Adds the operand and carry flag into the accumulator.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def adc(mode)
+      add_with_carry(read_operand(mode))
+    end
+
+    # Performs a bitwise AND between the accumulator and the operand.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def and(mode)
+      self.accumulator = set_zero_and_negative(accumulator & read_operand(mode))
+    end
+
+    # Arithmetic shift left.
+    #
+    # The top bit moves into carry and the result is shifted left by one.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def asl(mode)
+      shift(mode) do |value|
+        self.carry = value.anybits?(0x80)
+        (value << 1) & 0xff
+      end
+    end
+
+    # Branches when the carry flag is clear.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def bcc(mode)
+      branch_if(mode) { !carry? }
+    end
+
+    # Branches when the carry flag is set.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def bcs(mode)
+      branch_if(mode) { carry? }
+    end
+
+    # Branches when the zero flag is set.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def beq(mode)
+      branch_if(mode) { zero? }
+    end
+
+    # Tests bits in memory against the accumulator.
+    #
+    # `BIT` does not store a result; it updates zero from `A & M`, and copies
+    # bits 7 and 6 of the operand into negative and overflow.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def bit(mode)
+      value = read_operand(mode)
+      self.zero = accumulator.nobits?(value)
+      self.overflow = value.anybits?(0x40)
+      self.negative = value.anybits?(0x80)
+    end
+
+    # Branches when the negative flag is set.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def bmi(mode)
+      branch_if(mode) { negative? }
+    end
+
+    # Branches when the zero flag is clear.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def bne(mode)
+      branch_if(mode) { !zero? }
+    end
+
+    # Branches when the negative flag is clear.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def bpl(mode)
+      branch_if(mode) { !negative? }
+    end
+
+    # Software interrupt.
+    #
+    # `BRK` pushes the return address and status register, sets interrupt disable,
+    # and loads the IRQ/BRK vector.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def brk(_mode)
+      @program_counter = (@program_counter + 1) & 0xffff
+      interrupt_sequence(vector: IRQ_VECTOR, break_flag: true)
+    end
+
+    # Branches when the overflow flag is clear.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def bvc(mode)
+      branch_if(mode) { !overflow? }
+    end
+
+    # Branches when the overflow flag is set.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def bvs(mode)
+      branch_if(mode) { overflow? }
+    end
+
+    # Clears the carry flag.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def clc(_mode)
+      self.carry = false
+    end
+
+    # Clears the decimal mode flag.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def cld(_mode)
+      self.decimal = false
+    end
+
+    # Clears the interrupt-disable flag.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def cli(_mode)
+      self.interrupt = false
+    end
+
+    # Clears the overflow flag.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def clv(_mode)
+      self.overflow = false
+    end
+
+    # Compares the accumulator with the operand.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def cmp(mode)
+      compare(accumulator, read_operand(mode))
+    end
+
+    # Compares the X register with the operand.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def cpx(mode)
+      compare(register_x, read_operand(mode))
+    end
+
+    # Compares the Y register with the operand.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def cpy(mode)
+      compare(register_y, read_operand(mode))
+    end
+
+    # Decrements a memory location by one.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def dec(mode)
+      write_operand(mode) { |value| set_zero_and_negative((value - 1) & 0xff) }
+    end
+
+    # Decrements the X register by one.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def dex(_mode)
+      self.register_x = set_zero_and_negative((register_x - 1) & 0xff)
+    end
+
+    # Decrements the Y register by one.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def dey(_mode)
+      self.register_y = set_zero_and_negative((register_y - 1) & 0xff)
+    end
+
+    # Performs a bitwise exclusive OR with the accumulator.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def eor(mode)
+      self.accumulator = set_zero_and_negative(accumulator ^ read_operand(mode))
+    end
+
+    # Increments a memory location by one.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def inc(mode)
+      write_operand(mode) { |value| set_zero_and_negative((value + 1) & 0xff) }
+    end
+
+    # Increments the X register by one.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def inx(_mode)
+      self.register_x = set_zero_and_negative((register_x + 1) & 0xff)
+    end
+
+    # Increments the Y register by one.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def iny(_mode)
+      self.register_y = set_zero_and_negative((register_y + 1) & 0xff)
+    end
+
+    # Jumps to a new program counter.
+    #
+    # `JMP` supports both absolute and indirect addressing. The indirect form
+    # preserves the original 6502 page-wrap bug.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def jmp(mode)
+      @program_counter = if mode == :indirect
+                           read_indirect_word(fetch_word)
+                         else
+                           fetch_word
+                         end
+    end
+
+    # Jumps to a subroutine after pushing the return address.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def jsr(_mode)
+      target = fetch_word
+      push_word((@program_counter - 1) & 0xffff)
+      @program_counter = target
+    end
+
+    # Loads the accumulator from memory or an immediate operand.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def lda(mode)
+      self.accumulator = set_zero_and_negative(read_operand(mode))
+    end
+
+    # Loads the X register from memory or an immediate operand.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def ldx(mode)
+      self.register_x = set_zero_and_negative(read_operand(mode))
+    end
+
+    # Loads the Y register from memory or an immediate operand.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def ldy(mode)
+      self.register_y = set_zero_and_negative(read_operand(mode))
+    end
+
+    # Logical shift right.
+    #
+    # The low bit moves into carry and zero is shifted into bit 7.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def lsr(mode)
+      shift(mode) do |value|
+        self.carry = value.anybits?(0x01)
+        (value >> 1) & 0xff
+      end
+    end
+
+    # No operation.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def nop(_mode); end
+
+    # Performs a bitwise OR with the accumulator.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def ora(mode)
+      self.accumulator = set_zero_and_negative(accumulator | read_operand(mode))
+    end
+
+    # Pushes the accumulator onto the hardware stack.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def pha(_mode)
+      push_byte(accumulator)
+    end
+
+    # Pushes the processor status register onto the hardware stack.
+    #
+    # `PHP` always pushes the break and high bits set, matching 6502 behaviour.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def php(_mode)
+      push_byte((flags_encode & 0xef) | 0x30)
+    end
+
+    # Pulls the accumulator from the hardware stack.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def pla(_mode)
+      self.accumulator = set_zero_and_negative(pull_byte)
+    end
+
+    # Pulls the processor status register from the hardware stack.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def plp(_mode)
+      flags_decode(pull_byte | 0x20)
+    end
+
+    # Rotate left through the carry flag.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def rol(mode)
+      shift(mode) do |value|
+        new_value = ((value << 1) | bit_value(carry?)) & 0xff
+        self.carry = value.anybits?(0x80)
+        new_value
+      end
+    end
+
+    # Rotate right through the carry flag.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def ror(mode)
+      shift(mode) do |value|
+        new_value = ((bit_value(carry?) << 7) | (value >> 1)) & 0xff
+        self.carry = value.anybits?(0x01)
+        new_value
+      end
+    end
+
+    # Returns from an interrupt by restoring status and program counter.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def rti(_mode)
+      flags_decode(pull_byte | 0x20)
+      @program_counter = pull_word
+    end
+
+    # Returns from a subroutine.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def rts(_mode)
+      @program_counter = (pull_word + 1) & 0xffff
+    end
+
+    # Subtracts the operand and the inverted carry from the accumulator.
+    #
+    # On the 6502, `SBC` interprets the carry flag as "no borrow".
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def sbc(mode)
+      subtract_with_carry(read_operand(mode))
+    end
+
+    # Sets the carry flag.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def sec(_mode)
+      self.carry = true
+    end
+
+    # Sets the decimal mode flag.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def sed(_mode)
+      self.decimal = true
+    end
+
+    # Sets the interrupt-disable flag.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def sei(_mode)
+      self.interrupt = true
+    end
+
+    # Stores the accumulator into memory.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def sta(mode)
+      write_byte(resolve_address(mode), accumulator)
+    end
+
+    # Stores the X register into memory.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def stx(mode)
+      write_byte(resolve_address(mode), register_x)
+    end
+
+    # Stores the Y register into memory.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def sty(mode)
+      write_byte(resolve_address(mode), register_y)
+    end
+
+    # Transfers the accumulator into X.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def tax(_mode)
+      self.register_x = set_zero_and_negative(accumulator)
+    end
+
+    # Transfers the accumulator into Y.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def tay(_mode)
+      self.register_y = set_zero_and_negative(accumulator)
+    end
+
+    # Transfers the stack pointer into X.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def tsx(_mode)
+      self.register_x = set_zero_and_negative(stack_pointer)
+    end
+
+    # Transfers X into the accumulator.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def txa(_mode)
+      self.accumulator = set_zero_and_negative(register_x)
+    end
+
+    # Transfers X into the stack pointer.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def txs(_mode)
+      @stack_pointer = register_x
+    end
+
+    # Transfers Y into the accumulator.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @return [void]
+    def tya(_mode)
+      self.accumulator = set_zero_and_negative(register_y)
+    end
+
+    # Core implementation for `ADC`.
+    #
+    # This supports both binary and decimal arithmetic, while computing carry,
+    # overflow, zero, and negative according to 6502 conventions.
+    #
+    # @param value [Integer] the operand to add
+    # @return [void]
+    def add_with_carry(value)
+      a = accumulator
+      carry_in = bit_value(carry?)
+      binary_sum = a + value + carry_in
+      self.overflow = (~(a ^ value) & (a ^ binary_sum)).anybits?(0x80)
+
+      result = if decimal?
+                 decimal_sum = binary_sum
+                 decimal_sum += 0x06 if ((a & 0x0f) + (value & 0x0f) + carry_in) > 0x09
+                 decimal_sum += 0x60 if decimal_sum > 0x99
+                 self.carry = decimal_sum > 0x99
+                 decimal_sum & 0xff
+               else
+                 self.carry = binary_sum > 0xff
+                 binary_sum & 0xff
+               end
+
+      self.accumulator = set_zero_and_negative(result)
+    end
+
+    # Core implementation for `SBC`.
+    #
+    # @param value [Integer] the operand to subtract
+    # @return [void]
+    def subtract_with_carry(value)
+      a = accumulator
+      borrow = carry? ? 0 : 1
+      binary_difference = a - value - borrow
+      self.overflow = ((a ^ binary_difference) & (a ^ value)).anybits?(0x80)
+      self.carry = binary_difference >= 0
+
+      result = if decimal?
+                 low = (a & 0x0f) - (value & 0x0f) - borrow
+                 high = (a >> 4) - (value >> 4)
+                 if low.negative?
+                   low -= 0x06
+                   high -= 1
+                 end
+                 high -= 0x06 if high.negative?
+                 ((high << 4) | (low & 0x0f)) & 0xff
+               else
+                 binary_difference & 0xff
+               end
+
+      self.accumulator = set_zero_and_negative(result)
+    end
+
+    # Applies a relative branch offset when the supplied condition is true.
+    #
+    # @param _mode [Symbol] the decoded addressing mode
+    # @yieldreturn [Boolean] whether the branch should be taken
+    # @return [void]
+    def branch_if(_mode)
+      offset = signed_byte(fetch_byte)
+      @program_counter = (@program_counter + offset) & 0xffff if yield
+    end
+
+    # Shared implementation for compare instructions.
+    #
+    # `CMP`, `CPX`, and `CPY` set carry on `register >= operand` and update
+    # zero and negative from the subtraction result without storing it.
+    #
+    # @param register_value [Integer] the register to compare
+    # @param operand [Integer] the operand to compare against
+    # @return [Integer] the 8-bit subtraction result
+    def compare(register_value, operand)
+      result = (register_value - operand) & 0xff
+      self.carry = register_value >= operand
+      self.zero = result.zero?
+      self.negative = result.anybits?(0x80)
+      result
+    end
+
+    # Reads the byte at the program counter and advances it.
+    #
+    # @return [Integer] the fetched byte
+    def fetch_byte
+      byte = read_byte(@program_counter)
+      @program_counter = (@program_counter + 1) & 0xffff
+      byte
+    end
+
+    # Reads a little-endian word at the program counter and advances it.
+    #
+    # @return [Integer] the fetched 16-bit value
+    def fetch_word
+      low = fetch_byte
+      high = fetch_byte
+      low | (high << 8)
+    end
+
+    # Pushes interrupt state and transfers control to the supplied vector.
+    #
+    # @param vector [Integer] the interrupt vector address
+    # @param break_flag [Boolean] whether the pushed status should include the break bit
+    # @return [void]
+    def interrupt_sequence(vector:, break_flag:)
+      push_word(@program_counter)
+      status = flags_encode & 0xef
+      status |= 0x10 if break_flag
+      push_byte(status | 0x20)
+      self.interrupt = true
+      self.break = break_flag
+      @program_counter = read_word(vector)
+    end
+
+    # Pulls a byte from the hardware stack.
+    #
+    # @return [Integer] the byte restored from the stack
+    def pull_byte
+      @stack_pointer = (@stack_pointer + 1) & 0xff
+      read_byte(STACK_BASE + @stack_pointer)
+    end
+
+    # Pulls a 16-bit return address from the hardware stack.
+    #
+    # @return [Integer] the restored word value
+    def pull_word
+      low = pull_byte
+      high = pull_byte
+      low | (high << 8)
+    end
+
+    # Pushes a byte onto the hardware stack.
+    #
+    # @param value [Integer] the value to push
+    # @return [void]
+    def push_byte(value)
+      write_byte(STACK_BASE + @stack_pointer, value)
+      @stack_pointer = (@stack_pointer - 1) & 0xff
+    end
+
+    # Pushes a 16-bit value onto the hardware stack, high byte first.
+    #
+    # @param value [Integer] the word to push
+    # @return [void]
+    def push_word(value)
+      push_byte(value >> 8)
+      push_byte(value)
+    end
+
+    # Reads a word through the indirect `JMP` page-wrap bug.
+    #
+    # On a real 6502, when the indirect pointer ends at `xxFF`, the high byte is
+    # fetched from `xx00` rather than the next page.
+    #
+    # @param address [Integer] the indirect pointer location
+    # @return [Integer] the resolved target address
+    def read_indirect_word(address)
+      low = read_byte(address)
+      high_address = (address & 0xff00) | ((address + 1) & 0x00ff)
+      high = read_byte(high_address)
+      low | (high << 8)
+    end
+
+    # Reads an operand value according to its addressing mode.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the fetched operand byte
+    def read_operand(mode)
+      return fetch_byte if mode == :immediate
+
+      read_byte(resolve_address(mode))
+    end
+
+    # Resolves an addressing mode into a concrete memory address.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @return [Integer] the resolved memory address
+    # @raise [ArgumentError] if the mode does not point to memory
+    def resolve_address(mode)
+      case mode
+      when :zero_page
+        fetch_byte
+      when :zero_page_x
+        (fetch_byte + register_x) & 0xff
+      when :zero_page_y
+        (fetch_byte + register_y) & 0xff
+      when :absolute
+        fetch_word
+      when :absolute_x
+        (fetch_word + register_x) & 0xffff
+      when :absolute_y
+        (fetch_word + register_y) & 0xffff
+      when :indirect_x
+        pointer = (fetch_byte + register_x) & 0xff
+        read_byte(pointer) | (read_byte((pointer + 1) & 0xff) << 8)
+      when :indirect_y
+        pointer = fetch_byte
+        ((read_byte(pointer) | (read_byte((pointer + 1) & 0xff) << 8)) + register_y) & 0xffff
+      else
+        raise ArgumentError, "Address mode #{mode} does not resolve to a memory location"
+      end
+    end
+
+    # Applies zero and negative flag updates to an 8-bit value.
+    #
+    # @param value [Integer] the raw arithmetic or logic result
+    # @return [Integer] the masked 8-bit result
+    def set_zero_and_negative(value)
+      result = value & 0xff
+      self.zero = result.zero?
+      self.negative = result.anybits?(0x80)
+      result
+    end
+
+    # Shared implementation for accumulator and memory shifts or rotates.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @yieldparam value [Integer] the current value to transform
+    # @yieldreturn [Integer] the transformed value
+    # @return [void]
+    def shift(mode)
+      if mode == :accumulator
+        self.accumulator = set_zero_and_negative(yield(accumulator))
+      else
+        write_operand(mode) { |value| set_zero_and_negative(yield(value)) }
+      end
+    end
+
+    # Interprets a byte as a signed 8-bit relative offset.
+    #
+    # @param value [Integer] the raw branch displacement byte
+    # @return [Integer] the signed offset
+    def signed_byte(value)
+      value >= 0x80 ? value - 0x100 : value
+    end
+
+    # Writes a transformed value back to the addressed memory operand.
+    #
+    # @param mode [Symbol] the decoded addressing mode
+    # @yieldparam value [Integer] the current memory value
+    # @yieldreturn [Integer] the new memory value
+    # @return [void]
+    def write_operand(mode)
+      address = resolve_address(mode)
+      write_byte(address, yield(read_byte(address)))
+    end
+  end
+end