badline 0.12.0 → 0.13.0

data/lib/badline/chips/cpu/interrupts.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class CPU
+      module Interrupts
+        BREAK_MASK = 0x10
+
+        private
+
+        # Samples the IRQ line and the NMI latch once per cycle. An instruction
+        # boundary commits the sample taken on its second-to-last cycle.
+        def poll
+          if @skip_poll
+            @skip_poll = false
+            return
+          end
+          @irq_pending = @irq_sample
+          @nmi_pending = @nmi_sample
+          @irq_sample = @irq && !@status.interrupt?
+          @nmi_sample = @nmi
+        end
+
+        # A cycle the VIC stalls through BA keeps sampling the lines, OR-ed with
+        # the sample it already holds, but the boundary pipeline doesn't advance
+        # and a skipped poll stays owed to the next real cycle.
+        def sample_while_stalled
+          @irq_sample ||= @irq && !interrupt_disabled_after_stall?
+          @nmi_sample = true if @nmi
+        end
+
+        # A stalled CLI or SEI execute cycle masks with the I it is about to
+        # set. Every other step masks with the current I, PLP included: its
+        # pulled I only arrives with the stalled stack read.
+        def interrupt_disabled_after_stall?
+          return @status.interrupt? unless @plan.equal?(CPU::IMPLIED_PLAN)
+
+          case @operation
+          when :cli then false
+          when :sei then true
+          else @status.interrupt?
+          end
+        end
+
+        # Runs in the opcode fetch cycle in place of the fetch, with no bus
+        # access, and switches to the interrupt plan.
+        def start_interrupt
+          @interrupt = @boundary_nmi ? 0xfffa : 0xfffe
+          @brk = false
+          @plan = CPU::INTERRUPT_PLAN
+          @writes = CPU::INTERRUPT_WRITES
+          @index = 1
+        end
+
+        # BRK reads the byte after its opcode and ignores it, and selects the
+        # IRQ vector.
+        def op_brk_dummy
+          @memory.peek(@program_counter)
+          @interrupt = 0xfffe
+          @brk = true
+        end
+
+        def op_int_push_pch
+          @address = @brk ? (@program_counter + 1) & 0xffff : @program_counter
+          @memory.poke(stack_address, high_byte(@address))
+          @stack_pointer = (@stack_pointer - 1) & 0xff
+        end
+
+        def op_int_push_pcl
+          @memory.poke(stack_address, low_byte(@address))
+          @stack_pointer = (@stack_pointer - 1) & 0xff
+        end
+
+        def op_int_push_status
+          value = @brk ? @status.value | BREAK_MASK : @status.value & ~BREAK_MASK
+          @memory.poke(stack_address, value)
+          @stack_pointer = (@stack_pointer - 1) & 0xff
+          @status.interrupt = true
+          # An NMI that arrives before cycle 4 of a BRK or IRQ takes it over:
+          # the sequence finishes with the NMI vector.
+          @interrupt = 0xfffa if @interrupt == 0xfffe && @nmi_pending
+          @nmi = false if @interrupt == 0xfffa
+        end
+
+        def op_int_vector_low
+          @address = @memory.peek(@interrupt)
+        end
+
+        # Clears any interrupt that is pending, so the handler's first
+        # instruction always runs before the next interrupt. This applies to
+        # BRK too.
+        def op_int_vector_high
+          high = @memory.peek((@interrupt + 1) & 0xffff)
+          @program_counter = @address | (high << 8)
+          @irq_sample = @irq_pending = false
+          @nmi_sample = @nmi_pending = false
+          @interrupt = nil
+          if @brk
+            @status.break = false
+            end_instruction
+          else
+            end_sequence
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/cpu/microcode.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class CPU
+      class InvalidOpcodeError < StandardError; end
+
+      # Steps that write to memory. The CPU keeps running through BA on
+      # cycles that write, so C64#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
+        def self.table
+          Array.new(256) do |opcode|
+            instruction = Instruction.find(opcode)
+            raise InvalidOpcodeError, format("$%02x", opcode) unless instruction
+
+            build(instruction)
+          end.freeze
+        end
+
+        def self.write_mask(plan)
+          plan.map { |step| WRITE_STEPS.include?(step) }.freeze
+        end
+
+        def self.build(instruction)
+          plan = plan_for(instruction)
+          new(instruction.name, plan, write_mask(plan),
+              instruction.boundary_cycle?)
+        end
+
+        def self.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 self.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 self.operation_kind(name)
+          return :write if STORES.include?(name)
+          return :rmw if READ_MODIFY_WRITES.include?(name)
+
+          :read
+        end
+
+        private_class_method :build, :plan_for, :addressed_plan, :operation_kind
+      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
+
+      # The instruction methods, in a fixed order a snapshot names them by.
+      OPERATIONS = MICROCODE.map(&:operation).uniq.freeze
+
+      # The plans a snapshot names that aren't an opcode's.
+      FETCH = -1
+      INTERRUPT = -2
+      JAMMED = -3
+    end
+  end
+end

data/lib/badline/chips/cpu/operations.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    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
+end

data/lib/badline/chips/cpu/port.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class CPU
+      # The I/O port of the 6510 and the 8502 at $00 (direction) and $01
+      # (data). An input pin reads its pull-up, P4 reads the datasette's sense
+      # line, and a pin without a pull-up holds the charge last driven onto
+      # it. P5 drives the datasette motor through an inverter: low runs it.
+      #
+      # The 6510 has pull-ups on P0-P2 and P4 and leaves P3, P6 and P7
+      # floating. The 8502 adds a CAPS LOCK pin on P6, high while the key is
+      # up.
+      class Port
+        TAPE_SENSE = 0b0001_0000
+
+        # The direction and output registers, and the charge on the floating
+        # pins.
+        attr_reader :ddr, :data, :floating
+
+        # The port as the banking logic reads it (PortStatus).
+        attr_reader :status
+
+        # Whether CAPS LOCK is down, holding its pin low.
+        attr_reader :caps_lock
+
+        # +pullups+ and +floating+ are the masks of the pins with a pull-up and
+        # of the floating ones, and +caps_lock+ the CAPS LOCK pin's, 0 where
+        # there is none.
+        def initialize(datasette, pullups:, floating:, caps_lock: 0)
+          @datasette = datasette
+          @pullups = pullups
+          @floating_mask = floating
+          @caps_lock_pin = caps_lock
+          @caps_lock = false
+          @ddr = 0x00
+          @data = 0x00
+          @floating = 0x00
+          @change_handler = nil
+          @status = PortStatus.new(%i[basic kernal io tape_out tape_switch tape_motor], value: input_value)
+        end
+
+        # Calls the block after every write to the port, for the bus to remap
+        # its banks.
+        def on_change(&handler)
+          @change_handler = handler
+        end
+
+        # What a read of $01 sees.
+        def value = @status.value
+
+        def write_ddr(value)
+          @ddr = value
+          update
+        end
+
+        def write_data(value)
+          @data = value
+          update
+        end
+
+        # The RES line clears the direction and output registers. The floating
+        # pins keep their charge.
+        def reset!
+          @ddr = 0x00
+          @data = 0x00
+          update
+        end
+
+        # Sets the registers and the charge, as a snapshot restores them, and
+        # drives the motor and calls the change handler as a write does.
+        def restore(ddr, data, floating)
+          load(ddr, data, floating)
+          update
+        end
+
+        # Sets the registers and the charge, as a snapshot loads them, without
+        # driving the motor or calling the change handler.
+        def load(ddr, data, floating)
+          @ddr = ddr
+          @data = data
+          @floating = floating
+          refresh
+        end
+
+        # Holds CAPS LOCK down, or lets it up.
+        def caps_lock=(down)
+          @caps_lock = down
+          refresh
+        end
+
+        # Reads the inputs again, after the datasette's sense line changes.
+        def refresh
+          @status.value = input_value
+        end
+
+        private
+
+        def update
+          driven = @ddr & @floating_mask
+          @floating = (@floating & ~driven) | (@data & driven)
+          refresh
+          @datasette.motor = !@status.tape_motor?
+          @change_handler&.call
+        end
+
+        def input_value
+          input = @pullups | (@floating & @floating_mask)
+          input |= @caps_lock_pin unless @caps_lock
+          input &= ~TAPE_SENSE if @datasette.sense_low?
+          (@data & @ddr) | (input & ~@ddr & 0xff)
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/cpu/saved_state.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    class CPU
+      # The CPU's state for a snapshot: the registers, the interrupt lines and
+      # their pipeline, and the step of the instruction in flight, named by
+      # where its plan comes from.
+      module SavedState
+        # Writes everything the CPU holds, down to the step of the instruction
+        # it is in, for load_state to put back. The interrupt lines, BA stalls
+        # and SO are state too; the traps and the debug flag belong to the host.
+        def save_state(out)
+          out.marker("CPU")
+          out.int(@program_counter).int(@stack_pointer).int(@a).int(@x).int(@y).int(@status.value)
+          [@irq, @nmi, @irq_sample, @irq_pending, @nmi_sample, @nmi_pending, @skip_poll, @boundary_irq,
+           @boundary_nmi, @boundary_crossed, @brk, @pending_write, @so_high, @optional_dummy,
+           @branch_taken].each { |flag| out.boolean(flag) }
+          out.optional_int(@interrupt).optional_int(@stalled_at).int(@cycles).int(@instructions)
+          out.int(plan_source).int(@index).int(OPERATIONS.index(@operation) || -1)
+          [@address, @dummy_address, @value, @rmw_result, @pointer].each { |register| out.optional_int(register) }
+        end
+
+        def load_state(input)
+          input.marker("CPU")
+          @program_counter = input.int
+          @stack_pointer = input.int
+          @a = input.int
+          @x = input.int
+          @y = input.int
+          @status.value = input.int
+          load_flags(input)
+          @interrupt = input.optional_int
+          @stalled_at = input.optional_int
+          @cycles = input.int
+          @instructions = input.int
+          load_plan(input.int)
+          @index = input.int
+          operation = input.int
+          @operation = operation.negative? ? nil : OPERATIONS.fetch(operation)
+          load_working_registers(input)
+        end
+
+        # Drops the instruction or interrupt sequence in flight and the
+        # interrupt lines' pipeline, so the next cycle fetches an opcode at the
+        # program counter, and sets the cycle count. A snapshot taken between
+        # instructions, as VICE's are, restores through here.
+        def resume(cycles)
+          @irq_sample = @irq_pending = false
+          @nmi_sample = @nmi_pending = false
+          @skip_poll = false
+          @interrupt = nil
+          @brk = false
+          @stalled_at = nil
+          @cycles = cycles
+          end_sequence
+          @pending_write = false
+        end
+
+        private
+
+        # Where the plan running comes from: an opcode's microcode, or FETCH,
+        # INTERRUPT or JAMMED below it.
+        def plan_source
+          return FETCH if @plan.equal?(FETCH_PLAN)
+          return INTERRUPT if @plan.equal?(INTERRUPT_PLAN)
+          return JAMMED if @plan.equal?(JAMMED_PLAN)
+
+          MICROCODE.index { |micro| micro.plan.equal?(@plan) && micro.operation == @operation } ||
+            MICROCODE.index { |micro| micro.plan.equal?(@plan) }
+        end
+
+        def load_plan(source)
+          case source
+          when FETCH then use_plan(FETCH_PLAN, FETCH_WRITES)
+          when INTERRUPT then use_plan(INTERRUPT_PLAN, INTERRUPT_WRITES)
+          when JAMMED then use_plan(JAMMED_PLAN, JAMMED_WRITES)
+          else
+            micro = MICROCODE.fetch(source)
+            use_plan(micro.plan, micro.writes)
+          end
+        end
+
+        def use_plan(plan, writes)
+          @plan = plan
+          @writes = writes
+        end
+
+        def load_flags(input)
+          @irq = input.boolean?
+          @nmi = input.boolean?
+          @irq_sample = input.boolean?
+          @irq_pending = input.boolean?
+          @nmi_sample = input.boolean?
+          @nmi_pending = input.boolean?
+          @skip_poll = input.boolean?
+          @boundary_irq = input.boolean?
+          @boundary_nmi = input.boolean?
+          @boundary_crossed = input.boolean?
+          @brk = input.boolean?
+          @pending_write = input.boolean?
+          @so_high = input.boolean?
+          @optional_dummy = input.boolean?
+          @branch_taken = input.boolean?
+        end
+
+        def load_working_registers(input)
+          @address = input.optional_int
+          @dummy_address = input.optional_int
+          @value = input.optional_int
+          @rmw_result = input.optional_int
+          @pointer = input.optional_int
+        end
+      end
+    end
+  end
+end

data/lib/badline/chips/cpu/stack_operations.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Badline
+  module Chips
+    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
+end