badline 0.1.0 → 0.2.0

data/lib/badline/cpu/microcode.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Badline
+  class CPU
+    class InvalidOpcodeError < StandardError; end
+
+    # Steps that write to memory. The CPU keeps running through BA on
+    # cycles that write, so Computer#cycle! asks before each cycle whether
+    # the next step is one of these.
+    WRITE_STEPS = %i[
+      op_mem_write op_rmw_write_original op_rmw_write_result op_push_exec op_jsr_push_high op_jsr_push_low
+      op_int_push_pch op_int_push_pcl op_int_push_status
+    ].freeze
+
+    # The steps each addressing mode takes to work out the address an
+    # instruction operates on. They run after the opcode fetch.
+    ADDRESSING_STEPS = {
+      zeropage: %i[op_zp],
+      zeropage_x: %i[op_zp op_zp_x],
+      zeropage_y: %i[op_zp op_zp_y],
+      absolute: %i[op_abs_low op_abs_high],
+      absolute_x: %i[op_abs_low op_abs_high_x op_idx_dummy],
+      absolute_y: %i[op_abs_low op_abs_high_y op_idx_dummy],
+      indirect_x: %i[op_zp_pointer op_pointer_x op_pointer_low op_pointer_high],
+      indirect_y: %i[op_zp_pointer op_pointer_low op_pointer_high_y op_idx_dummy]
+    }.freeze
+
+    # The steps that read or write that address, once it is known.
+    OPERATION_STEPS = {
+      read: %i[op_mem_read],
+      write: %i[op_mem_write],
+      rmw: %i[op_rmw_read op_rmw_write_original op_rmw_write_result]
+    }.freeze
+
+    STORES = %i[sta stx sty sax sha shx shy tas].freeze
+    READ_MODIFY_WRITES = %i[asl lsr rol ror inc dec slo sre rla rra isc dcp].freeze
+    BRANCHES = %i[bcc bcs beq bmi bne bpl bvc bvs].freeze
+
+    # The addresses a 6502 reads after a JAM opcode, before it settles into
+    # JAMMED_PLAN.
+    JAM_ADDRESSES = [0xffff, 0xfffe, 0xfffe].freeze
+
+    # The plan between instructions: the next cycle fetches an opcode.
+    FETCH_PLAN = %i[op_fetch].freeze
+
+    IMPLIED_PLAN = %i[op_fetch op_implied_exec].freeze
+    ACCUMULATOR_PLAN = %i[op_fetch op_accumulator_exec].freeze
+    IMMEDIATE_PLAN = %i[op_fetch op_immediate_read].freeze
+
+    # $10, $30, $50, $70, $90, $B0, $D0, $F0 - relative - 2+ cycles.
+    # A branch that is not taken takes 2 cycles. A taken branch takes 3,
+    # or 4 when the target is on another page.
+    BRANCH_PLAN = %i[op_fetch op_relative op_branch op_branch_fixup].freeze
+
+    # $4C - absolute - 3 cycles
+    JMP_ABSOLUTE_PLAN = %i[op_fetch op_abs_low op_jmp_high].freeze
+
+    # $6C - indirect - 5 cycles
+    JMP_INDIRECT_PLAN = %i[op_fetch op_abs_low op_abs_high op_indirect_low op_indirect_high].freeze
+
+    # $20 - absolute - 6 cycles
+    JSR_PLAN = %i[op_fetch op_jsr_low op_jsr_dummy op_jsr_push_high op_jsr_push_low op_jsr_high].freeze
+
+    # $60 - implied - 6 cycles
+    RTS_PLAN = %i[op_fetch op_implied_dummy op_pull_dummy op_pull_low op_pull_high op_rts_fixup].freeze
+
+    # $40 - implied - 6 cycles
+    RTI_PLAN = %i[op_fetch op_implied_dummy op_pull_dummy op_rti_pull_status op_pull_low op_rti_pull_high].freeze
+
+    # $08, $48 - implied - 3 cycles
+    PUSH_PLAN = %i[op_fetch op_implied_dummy op_push_exec].freeze
+
+    # $28, $68 - implied - 4 cycles
+    PULL_PLAN = %i[op_fetch op_implied_dummy op_pull_dummy op_pull_exec].freeze
+
+    # $02, $12, $22, $32, $42, $52, $62, $72, $92, $B2, $D2, $F2 - illegal
+    JAM_PLAN = [:op_fetch, :op_implied_dummy, *Array.new(JAM_ADDRESSES.length, :op_jam)].freeze
+
+    # A jammed CPU reads $FFFF on every cycle until reset. It never reaches
+    # an instruction boundary, so a pending IRQ or NMI never starts.
+    JAMMED_PLAN = %i[op_jammed].freeze
+
+    # BRK and hardware interrupts push the return address and status, then
+    # read the new PC from a vector. Only the second step differs: BRK's
+    # selects the IRQ vector and sets the break flag it pushes.
+    #
+    # $00 - implied - 7 cycles (BRK)
+    INTERRUPT_PLAN = %i[
+      op_fetch op_implied_dummy op_int_push_pch op_int_push_pcl op_int_push_status
+      op_int_vector_low op_int_vector_high
+    ].freeze
+    BRK_PLAN = %i[
+      op_fetch op_brk_dummy op_int_push_pch op_int_push_pcl op_int_push_status
+      op_int_vector_low op_int_vector_high
+    ].freeze
+
+    SPECIAL_PLANS = {
+      brk: BRK_PLAN, jam: JAM_PLAN, jsr: JSR_PLAN, rts: RTS_PLAN,
+      rti: RTI_PLAN, pha: PUSH_PLAN, php: PUSH_PLAN,
+      pla: PULL_PLAN, plp: PULL_PLAN
+    }.freeze
+
+    # Everything the CPU needs to run one opcode:
+    # - +operation+: the instruction method to call, such as :lda
+    # - +plan+: the step to run on each cycle
+    # - +writes+: which of those steps write to memory
+    # - +optional_dummy+: true for indexed reads, which skip the extra
+    #   cycle unless indexing crosses a page
+    Microcode = Struct.new(:operation, :plan, :writes, :optional_dummy) do
+      class << self
+        def table
+          Array.new(256) do |opcode|
+            instruction = Instruction.find(opcode)
+            raise InvalidOpcodeError, format("$%02x", opcode) unless instruction
+
+            build(instruction)
+          end.freeze
+        end
+
+        def write_mask(plan)
+          plan.map { |step| WRITE_STEPS.include?(step) }.freeze
+        end
+
+        private
+
+        def build(instruction)
+          plan = plan_for(instruction)
+          new(instruction.name, plan, write_mask(plan),
+              instruction.boundary_cycle?)
+        end
+
+        def plan_for(instruction)
+          case instruction.name
+          when :jmp
+            if instruction.addressing_mode == :indirect
+              JMP_INDIRECT_PLAN
+            else
+              JMP_ABSOLUTE_PLAN
+            end
+          when *BRANCHES then BRANCH_PLAN
+          else SPECIAL_PLANS[instruction.name] || addressed_plan(instruction)
+          end
+        end
+
+        def addressed_plan(instruction)
+          mode = instruction.addressing_mode
+          case mode
+          when :implied then IMPLIED_PLAN
+          when :accumulator then ACCUMULATOR_PLAN
+          when :immediate then IMMEDIATE_PLAN
+          else
+            [:op_fetch, *ADDRESSING_STEPS.fetch(mode),
+             *OPERATION_STEPS.fetch(operation_kind(instruction.name))].freeze
+          end
+        end
+
+        def operation_kind(name)
+          return :write if STORES.include?(name)
+          return :rmw if READ_MODIFY_WRITES.include?(name)
+
+          :read
+        end
+      end
+    end
+
+    FETCH_WRITES = Microcode.write_mask(FETCH_PLAN)
+    INTERRUPT_WRITES = Microcode.write_mask(INTERRUPT_PLAN)
+    JAMMED_WRITES = Microcode.write_mask(JAMMED_PLAN)
+    MICROCODE = Microcode.table
+  end
+end

data/lib/badline/cpu/operations.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Badline
+  class CPU
+    # Steps that read or write an instruction's operand once its address is
+    # known, plus the branch and JAM steps.
+    module Operations
+      private
+
+      def op_mem_read
+        send(@operation, @address, @memory.peek(@address))
+        end_instruction
+      end
+
+      def op_mem_write
+        send(@operation, @address, nil)
+        end_instruction
+      end
+
+      # Read-modify-write instructions (ASL, INC and the like) take three
+      # cycles here: read the value and compute the result, write the
+      # original value back, then write the result. The instruction method
+      # hands the result over through #write_modified.
+      def op_rmw_read
+        @value = @memory.peek(@address)
+        send(@operation, @address, @value)
+      end
+
+      def op_rmw_write_original
+        @memory.poke(@address, @value)
+      end
+
+      def op_rmw_write_result
+        @memory.poke(@address, @rmw_result)
+        end_instruction
+      end
+
+      def op_relative
+        offset = @memory.peek(@program_counter)
+        @program_counter = (@program_counter + 1) & 0xffff
+        @address = (@program_counter + signed_int8(offset)) & 0xffff
+        @branch_taken = false
+        send(@operation, @address, nil)
+        if @branch_taken
+          # A taken branch within the same page doesn't poll on its last cycle.
+          @skip_poll = true if same_page?
+        else
+          end_instruction
+        end
+      end
+
+      def op_branch
+        @memory.peek(@program_counter)
+        return unless same_page?
+
+        @program_counter = @address
+        end_instruction
+      end
+
+      # A branch to another page spends an extra cycle reading from the target's low byte on the old page.
+      def op_branch_fixup
+        @memory.peek((@program_counter & 0xff00) | (@address & 0xff))
+        @program_counter = @address
+        end_instruction
+      end
+
+      def same_page?
+        @address >> 8 == @program_counter >> 8
+      end
+
+      # Runs once for each address in JAM_ADDRESSES. By the time a step runs, @index already points at the next one.
+      def op_jam
+        position = @index - 2
+        @memory.peek(JAM_ADDRESSES[position - 1])
+        return unless position == JAM_ADDRESSES.length
+
+        @plan = JAMMED_PLAN
+        @writes = JAMMED_WRITES
+        @index = 0
+      end
+
+      def op_jammed
+        @index = 0
+        @memory.peek(0xffff)
+      end
+    end
+  end
+end

data/lib/badline/cpu/stack_operations.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Badline
+  class CPU
+    # Steps that use the stack: PHA, PHP, PLA, PLP, JSR, RTS and RTI.
+    module StackOperations
+      private
+
+      def op_push_exec
+        send(@operation, nil, nil)
+        end_instruction
+      end
+
+      def op_pull_dummy
+        @memory.peek(stack_address)
+      end
+
+      def op_pull_exec
+        send(@operation, nil, nil)
+        end_instruction
+      end
+
+      def op_pull_low
+        @stack_pointer = (@stack_pointer + 1) & 0xff
+        @address = @memory.peek(stack_address)
+      end
+
+      def op_pull_high
+        @stack_pointer = (@stack_pointer + 1) & 0xff
+        @address |= @memory.peek(stack_address) << 8
+      end
+
+      def op_rts_fixup
+        @memory.peek(@address)
+        @program_counter = (@address + 1) & 0xffff
+        end_instruction
+      end
+
+      def op_rti_pull_status
+        @stack_pointer = (@stack_pointer + 1) & 0xff
+        @status.value = @memory.peek(stack_address)
+        @status.break = false
+      end
+
+      def op_rti_pull_high
+        @stack_pointer = (@stack_pointer + 1) & 0xff
+        @program_counter = @address | (@memory.peek(stack_address) << 8)
+        end_instruction
+      end
+
+      def op_jsr_low
+        @address = @memory.peek(@program_counter)
+        @program_counter = (@program_counter + 2) & 0xffff
+      end
+
+      def op_jsr_dummy
+        @memory.peek(stack_address)
+      end
+
+      def op_jsr_push_high
+        @memory.poke(stack_address, high_byte(return_address))
+      end
+
+      def op_jsr_push_low
+        @memory.poke(stack_address(-1), low_byte(return_address))
+        @stack_pointer = (@stack_pointer - 2) & 0xff
+      end
+
+      # JSR reads its target's high byte after pushing the return address.
+      # A JSR running from the stack page can overwrite its own operand
+      # with that push, and then jumps to the overwritten address.
+      def op_jsr_high
+        @program_counter = @address | (@memory.peek(return_address) << 8)
+        end_instruction
+      end
+
+      def return_address
+        (@program_counter - 1) & 0xffff
+      end
+    end
+  end
+end

data/lib/badline/cpu.rb

@@ -1,35 +1,61 @@
 # frozen_string_literal: true
 
+require "badline/cpu/microcode"
+require "badline/cpu/addressing"
+require "badline/cpu/operations"
+require "badline/cpu/stack_operations"
+
 module Badline
-  class CPU < Cycleable
-    STATUS_FLAGS = [:carry, :zero, :interrupt, :decimal, :break, 1,
-                    :overflow, :negative].freeze
+  class CPU
+    STATUS_FLAGS = [:carry, :zero, :interrupt, :decimal, :break, 1, :overflow, :negative].freeze
 
-    class InvalidOpcodeError < StandardError; end
     include IntegerHelper
     include InstructionSet
+    include Interrupts
     include Traps
+    include Addressing
+    include Operations
+    include StackOperations
+
+    attr_reader :memory, :instructions, :boundary_crossed, :cycles, :pending_write
+    attr_accessor :program_counter, :stack_pointer, :status, :a, :x, :y, :nmi, :irq
 
-    attr_reader :memory, :instructions, :boundary_crossed
-    attr_accessor :program_counter, :stack_pointer, :status, :a, :x, :y,
-                  :nmi, :irq
+    alias pending_write? pending_write
 
-    def initialize(memory = nil, debug: false)
+    # +ane_constant+ is ANE's magic constant, which varies from chip to
+    # chip. The default is the C64 6510's.
+    def initialize(memory = nil, debug: false, ane_constant: 0xef)
       @debug = debug
+      @ane_constant = ane_constant
       @memory = memory || Memory.new
       @status = Status.new(STATUS_FLAGS, value: 0b00100000)
       reset_registers
 
       @nmi = @irq = false
+      @irq_sample = @irq_pending = false
+      @nmi_sample = @nmi_pending = false
+      @skip_poll = false
+      @boundary_crossed = false
+      @interrupt = nil
+      @brk = false
+      @pending_write = false
+      @stalled_at = nil
 
+      @cycles = 0
       @instructions = 0
       @traps = nil
-      super()
+      end_sequence
     end
 
     def reset!
       status.interrupt = true
       reset_registers
+      @nmi = false
+      @irq_sample = @irq_pending = false
+      @nmi_sample = @nmi_pending = false
+      @skip_poll = false
+      @pending_write = false
+      end_sequence
     end
 
     def p
@@ -40,9 +66,37 @@ module Badline
       status.value = new_value
     end
 
+    def cycle!
+      poll # the interrupt lines
+
+      # Run the next step
+      index = @index
+      @index = index + 1
+      send(@plan[index])
+      @cycles += 1
+
+      # Record if the next step writes to memory
+      @pending_write = @writes[@index]
+      nil
+    end
+
+    # Called instead of #cycle! on a cycle the VIC holds the CPU through
+    # BA. Records which cycle the CPU was stalled before, and keeps
+    # sampling the interrupt lines.
+    def stall!
+      @stalled_at = @cycles
+      sample_while_stalled
+    end
+
+    def jammed?
+      @plan.equal?(JAMMED_PLAN)
+    end
+
+    # Runs to the end of the instruction, or until the CPU jams.
     def step!
-      @loop.resume unless @instruction || @interrupt
-      cycle! while @instruction || @interrupt
+      cycle!
+      cycle! until @plan.equal?(FETCH_PLAN) || jammed?
+      nil
     end
 
     def inspect
@@ -53,66 +107,58 @@ module Badline
 
     private
 
-    def extra_cycle(instruction)
-      return cycle unless instruction.boundary_cycle?
-
-      boundary_crossed && cycle
-    end
-
-    def handle_interrupt(vector, brk: false, pre_cycles: 2)
-      pre_cycles.times { cycle }
-
-      pc = program_counter
-      pc = (pc + 1) & 0xffff if brk
+    # The first cycle of every instruction. Starts an interrupt if one was
+    # pending when the previous instruction ended. Otherwise reads the
+    # opcode and switches to its plan.
+    def op_fetch
+      return start_interrupt if @boundary_nmi || @boundary_irq
 
-      write_byte(stack_address, high_byte(pc))
-      @stack_pointer = (@stack_pointer - 1) & 0xff
-      write_byte(stack_address, low_byte(pc))
-      @stack_pointer = (@stack_pointer - 1) & 0xff
-      write_byte(stack_address,
-                 status.clone.tap { |s| s.break = brk }.value)
-      @stack_pointer = (@stack_pointer - 1) & 0xff
-      status.interrupt = true
-      @program_counter = read_word(vector)
+      run_traps
+      opcode = @memory.peek(@program_counter)
+      log(opcode) if @debug
+      micro = MICROCODE[opcode]
+      @operation = micro.operation
+      @plan = micro.plan
+      @writes = micro.writes
+      @optional_dummy = micro.optional_dummy
+      @index = 1
+      @boundary_crossed = false
+      @program_counter = (@program_counter + 1) & 0xffff
     end
 
-    def handle_interrupts
-      @interrupt = if nmi
-                     0xfffa
-                   elsif irq && !status.interrupt?
-                     0xfffe
-                   end
-
-      handle_interrupt(@interrupt) if @interrupt
-      @interrupt = nil
-      @nmi = @irq = false
+    def end_instruction
+      @instructions += 1
+      end_sequence
     end
 
-    def read_byte(addr)
-      cycle { @memory.peek(addr) }
+    # Makes the next cycle an opcode fetch, and saves the pending interrupt
+    # flags for op_fetch. The next cycle polls before op_fetch runs, which
+    # updates the live flags.
+    def end_sequence
+      @plan = FETCH_PLAN
+      @writes = FETCH_WRITES
+      @index = 0
+      @boundary_irq = @irq_pending
+      @boundary_nmi = @nmi_pending
     end
 
-    def read_word(addr)
-      uint16(read_byte(addr),
-             read_byte((addr + 1) & 0xffff))
+    # True when the CPU was stalled right before this cycle.
+    def stalled_before_this_cycle?
+      @stalled_at == @cycles
     end
 
-    def read_zeropage_word(addr)
-      uint16(read_byte(addr & 0xff),
-             read_byte((addr + 1) & 0xff))
+    # True when the CPU was stalled right before the cycle that preceded
+    # this one.
+    def stalled_before_previous_cycle?
+      @stalled_at == @cycles - 1
     end
 
-    def read_instruction
-      Instruction.find(@memory.peek(@program_counter))
+    def write_byte(addr, value)
+      @memory.poke(addr, value)
     end
 
-    def read_operand(instruction)
-      return nil unless instruction.operand?
-      # JSR fetches its operand high byte late (see Stack#jsr).
-      return read_byte(program_counter) if instruction.name == :jsr
-      return read_word(program_counter) if instruction.operand_length == 2
-
-      read_byte(program_counter)
+    def stack_address(offset = 0)
+      0x0100 | ((@stack_pointer + offset) & 0xff)
     end
 
     def reset_registers
@@ -123,117 +169,12 @@ module Badline
       @a = @x = @y = 0x0
     end
 
-    def read_address(instruction, operand)
-      case instruction.addressing_mode
-      when :implied, :immediate
-        nil
-      when :accumulator
-        :accumulator
-      when :relative
-        (@program_counter + signed_int8(operand) + 1) & 0xffff
-      when :zeropage, :absolute
-        operand
-      when :zeropage_x
-        cycle { (operand + @x) & 0xff }
-      when :zeropage_y
-        cycle { (operand + @y) & 0xff }
-      when :absolute_x
-        # Do an extra cycle if page boundary is crossed
-        @boundary_crossed = high_byte(operand + @x) != high_byte(operand)
-        extra_cycle(instruction)
-        (operand + @x) & 0xffff
-      when :absolute_y
-        @boundary_crossed = high_byte(operand + @y) != high_byte(operand)
-        # Do an extra cycle if page boundary is crossed
-        extra_cycle(instruction)
-        (operand + @y) & 0xffff
-      when :indirect
-        # This is only used for JMP. There's no carry associated, so an
-        # indirect jump to $30FF will wrap around on the same page and read
-        # from [0x30ff, 0x3000].
-        uint16(
-          read_byte(operand),
-          read_byte(uint16(
-                      (low_byte(operand) + 1) & 0xff, # Wrap around low byte
-                      high_byte(operand)
-                    ))
-        )
-      when :indirect_x
-        cycle
-        read_zeropage_word(operand + @x)
-      when :indirect_y
-        value = read_zeropage_word(operand)
-        @boundary_crossed = ((value & 0xff) + y) > 0xff
-        # Do an extra cycle if page boundary is crossed
-        extra_cycle(instruction)
-        (value + y) & 0xffff
-      end
-    end
-
-    def realize_value(instruction, operand, address)
-      case instruction.addressing_mode
-      when :implied
-        raise "Implied value can't be realized"
-      when :accumulator
-        @a
-      when :immediate
-        operand
-      else
-        read_byte(address)
-      end
-    end
-
-    def stack_address(offset = 0)
-      uint16((stack_pointer + offset) & 0xff, 0x01)
-    end
-
-    def log(instruction, operand, address)
-      return unless @debug
-
-      pc = (@program_counter - 1) - instruction.operand_length
+    def log(opcode)
+      instruction = Instruction.find(opcode)
       puts(
-        "#{@cycles}: " \
-        "PC: #{pc.to_s(16)} - " \
-        "#{@instruction.name.upcase} #{@instruction.addressing_mode} " \
-        "Operand: #{operand.inspect} Address: #{address.inspect}"
+        "#{@cycles}: PC: #{format16(@program_counter)} - " \
+        "#{instruction.name.upcase} #{instruction.addressing_mode}"
       )
     end
-
-    def main_loop
-      if nmi || (irq && !status.interrupt?)
-        handle_interrupts
-      else
-        run_traps
-        @boundary_crossed = false
-        @instruction = read_instruction
-        raise InvalidOpcodeError unless @instruction
-
-        @program_counter = (@program_counter + 1) & 0xffff
-        @cycles += 1
-
-        @operand = operand = read_operand(@instruction)
-        @address = address = read_address(@instruction, operand)
-
-        @program_counter = (@program_counter + @instruction.operand_length) &
-                           0xffff
-
-        log(@instruction, operand, address)
-
-        # Run the instruction; :lazy realizes the value through #resolve
-        send(@instruction.name, address, :lazy)
-
-        @instructions += 1
-        @instruction = nil
-      end
-      Fiber.yield
-    end
-
-    def write_byte(addr, value)
-      if addr == :accumulator
-        @a = value
-      else
-        cycle(write: true) { @memory.poke(addr, value) }
-      end
-    end
   end
 end

data/lib/badline/cycleable.rb

@@ -22,12 +22,15 @@ module Badline
     def cycle(write: false)
       @pending_write = write
       Fiber.yield
+      poll
       result = yield if block_given?
       @cycles += 1
       @pending_write = false
       result
     end
 
+    def poll; end
+
     def main_loop
       Fiber.yield
     end