amaterasu 0.6.0

data/lib/amaterasu/game_boy/cpu/registers.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    class Cpu
+      # Models the behavior of the SM83 CPU registers.
+      #
+      # - Contains 8 8-bit core registers.
+      # - 8-bit registers can be combined into 16-bit register pair.
+      class Registers
+        include Utils::BitOps
+
+        # Returns the 8-bit value stored in the A (Accumulator) register.
+        attr_reader :a
+
+        # Returns the 8-bit value stored in the F (Flags) register.
+        attr_reader :f
+
+        # Returns the 8-bit value stored in the B register.
+        attr_reader :b
+
+        # Returns the 8-bit value stored in the C register.
+        attr_reader :c
+
+        # Returns the 8-bit value stored in the D register.
+        attr_reader :d
+
+        # Returns the 8-bit value stored in the E register.
+        attr_reader :e
+
+        # Returns the 8-bit value stored in the H register.
+        attr_reader :h
+
+        # Returns the 8-bit value stored in the L register.
+        attr_reader :l
+
+        # Returns the 16-bit value stored in the SP (Stack Pointer) register.
+        attr_reader :sp
+
+        # Returns the 16-bit value stored in the PC (Program Counter) register.
+        attr_reader :pc
+
+        # Sets the initial state of the CPU registers.
+        #
+        # - The values can change based on the Boot ROM implementation.
+        # - If the Boot ROM is not skipped, all values should start as 0.
+        def initialize(skip_boot_rom: true)
+          @a = skip_boot_rom ? 0x01 : 0x00
+          @f = skip_boot_rom ? 0b10110000 : 0b00000000
+          @b = 0x00
+          @c = skip_boot_rom ? 0x13 : 0x00
+          @d = 0x00
+          @e = skip_boot_rom ? 0xD8 : 0x00
+          @h = skip_boot_rom ? 0x01 : 0x00
+          @l = skip_boot_rom ? 0x4D : 0x00
+
+          @sp = skip_boot_rom ? 0xFFFE : 0x0000
+          @pc = skip_boot_rom ? 0x0100 : 0x0000
+        end
+
+        # Stores a 8-bit value into the A (Accumulator) register.
+        #
+        # - CPU ignores any value larger than 255 (0xFF).
+        def a=(value)
+          @a = value & 0xFF
+        end
+
+        # Stores a 8-bit value into the F (Flags) register.
+        #
+        # - CPU ignores any value larger than 255 (0xFF).
+        # - The lower nibble is always ignored by the CPU.
+        def f=(value)
+          @f = value & 0b11110000
+        end
+
+        # Stores a 8-bit value into the B register.
+        #
+        # - CPU ignores any value larger than 255 (0xFF).
+        def b=(value)
+          @b = value & 0xFF
+        end
+
+        # Stores a 8-bit value into the C register.
+        #
+        # - CPU ignores any value larger than 255 (0xFF).
+        def c=(value)
+          @c = value & 0xFF
+        end
+
+        # Stores a 8-bit value into the D register.
+        #
+        # - CPU ignores any value larger than 255 (0xFF).
+        def d=(value)
+          @d = value & 0xFF
+        end
+
+        # Stores a 8-bit value into the E register.
+        #
+        # - CPU ignores any value larger than 255 (0xFF).
+        def e=(value)
+          @e = value & 0xFF
+        end
+
+        # Stores a 8-bit value into the H register.
+        #
+        # - CPU ignores any value larger than 255 (0xFF).
+        def h=(value)
+          @h = value & 0xFF
+        end
+
+        # Stores a 8-bit value into the L register.
+        #
+        # - CPU ignores any value larger than 255 (0xFF).
+        def l=(value)
+          @l = value & 0xFF
+        end
+
+        # Sets the value of the AF combined 16-bit register.
+        #
+        # - Higher byte is set into the A register.
+        # - Lower byte is set into the F register.
+        # - CPU ignores bits 0-3 of the F register.
+        def af=(value)
+          value &= 0xFFFF
+          @a = (value >> 8) & 0xFF
+          @f = value & 0xF0
+        end
+
+        # Sets the value of the BC combined 16-bit register.
+        #
+        # - Higher byte is set into the B register.
+        # - Lower byte is set into the C register.
+        def bc=(value)
+          value &= 0xFFFF
+          @b = (value >> 8) & 0xFF
+          @c = value & 0xFF
+        end
+
+        # Sets the value of the DE combined 16-bit register.
+        #
+        # - Higher byte is set into the D register.
+        # - Lower byte is set into the E register.
+        def de=(value)
+          value &= 0xFFFF
+          @d = (value >> 8) & 0xFF
+          @e = value & 0xFF
+        end
+
+        # Sets the value of the HL combined 16-bit register.
+        #
+        # - Higher byte is set into the H register.
+        # - Lower byte is set into the L register.
+        def hl=(value)
+          value &= 0xFFFF
+          @h = (value >> 8) & 0xFF
+          @l = value & 0xFF
+        end
+
+        # Sets the value of the SP (Stack Pointer) register.
+        #
+        # - Points to the memory address in which the Stack is currently located.
+        # - If something is pushed into the Stack, the SP is decreased
+        # - If something is popped from the Stack, the SP is increased
+        def sp=(value)
+          @sp = value & 0xFFFF
+        end
+
+        # Sets the value of the PC (Program Counter) register.
+        #
+        # This register points to where in memory is the current instruction.
+        # Every time a instruction is fetched and executed,
+        # the PC is incremented to fetch the next one.
+        def pc=(value)
+          @pc = value & 0xFFFF
+        end
+
+        # Returns a 16-bit value stored in the combined AF register.
+        #
+        # - Shifts the byte stored in the A register 8 bits to the left to get the higher byte.
+        # - Performs a bitwise OR with the F register value to add the lower byte.
+        def af
+          (@a << 8) | @f
+        end
+
+        # Returns a 16-bit value stored in the combined BC register.
+        #
+        # - Shifts the byte stored in the B register 8 bits to the left to get the higher byte.
+        # - Performs a bitwise OR with the C register value to add the lower byte.
+        def bc
+          (@b << 8) | @c
+        end
+
+        # Returns a 16-bit value stored in the combined DE register.
+        #
+        # - Shifts the byte stored in the D register 8 bits to the left to get the higher byte.
+        # - Performs a bitwise OR with the E register value to add the lower byte.
+        def de
+          (@d << 8) | @e
+        end
+
+        # Returns a 16-bit value stored in the combined HL register.
+        #
+        # - Shifts the byte stored in the H register 8 bits to the left to get the higher byte.
+        # - Performs a bitwise OR with the L register value to add the lower byte.
+        def hl
+          (@h << 8) | @l
+        end
+
+        # Returns the current value of the Zero bit flag.
+        #
+        # - The Zero flag is Bit 7 of the Flags register.
+        def z_flag
+          bit(@f, 7)
+        end
+
+        # Returns the current value of the Subtraction bit flag.
+        #
+        # - The Subtraction flag is Bit 6 of the Flags register.
+        def n_flag
+          bit(@f, 6)
+        end
+
+        # Returns the current value of the Half Carry bit flag.
+        #
+        # - The Half Carry flag is Bit 5 of the Flags register.
+        def h_flag
+          bit(@f, 5)
+        end
+
+        # Returns the current value of the Carry bit flag.
+        #
+        # - The Carry flag is Bit 4 of the Flags register.
+        def c_flag
+          bit(@f, 4)
+        end
+
+        # Either sets or clears the value of the Zero flag (Bit 7).
+        def z_flag=(set)
+          @f = set ? set_bit(@f, 7) : clear_bit(@f, 7)
+        end
+
+        # Either sets or clears the value of the Subtraction flag (Bit 6).
+        def n_flag=(set)
+          @f = set ? set_bit(@f, 6) : clear_bit(@f, 6)
+        end
+
+        # Either sets or clears the value of the Half Carry flag (Bit 5).
+        def h_flag=(set)
+          @f = set ? set_bit(@f, 5) : clear_bit(@f, 5)
+        end
+
+        # Either sets or clears the value of the Carry flag (Bit 4).
+        def c_flag=(set)
+          @f = set ? set_bit(@f, 4) : clear_bit(@f, 4)
+        end
+
+        # Clears all 4 flags.
+        def clear_flags
+          @f = 0x00
+        end
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/cpu.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # Models the CPU behavior from the Game Boy.
+    class Cpu
+      attr_reader :registers, :m_cycles
+
+      def initialize(bus, hram, interrupts, advance_cycle, trace_cpu: false)
+        @bus = bus
+        @hram = hram
+        @interrupts = interrupts
+        @advance_cycle = advance_cycle
+        @trace_cpu = trace_cpu
+
+        @registers = Registers.new
+        @ime = false
+        @ime_scheduled = false
+        @halted = false
+        @opcode = nil
+        @instruction = nil
+
+        @m_cycles = 0
+
+        @instructions = Instructions.load_base_instructions(cpu: self)
+        @cb_instructions = Instructions.load_cb_instructions(cpu: self)
+      end
+
+      # Core CPU loop:
+      #
+      # - Checks IME and any interrupts pending to be serviced.
+      # - Fetches the current Opcode at the Program Counter.
+      # - Decodes which instruction based on the Opcode fetched.
+      # - Executes the instruction.
+      def step
+        if @interrupts.any_pending?
+          @halted = false if @halted
+
+          if @ime
+            handle_interrupts
+            return
+          end
+        end
+
+        if @ime_scheduled
+          @ime = true
+          @ime_scheduled = false
+        end
+
+        if @halted
+          @m_cycles = @advance_cycle.call
+          return
+        end
+
+        old_pc = @registers.pc
+        old_cycles = @m_cycles
+        @opcode = fetch_next_byte
+        decode_instruction
+        execute_instruction
+        log_state(old_pc, old_cycles, @instruction)
+      end
+
+      # Reads a byte from the Bus at a given address.
+      def bus_read(address:)
+        byte = @bus.read_byte(address:, caller: self)
+        @m_cycles = @advance_cycle.call
+
+        byte
+      end
+
+      # Requests a Bus write at a given address with a given value.
+      def bus_write(address:, value:)
+        @bus.write_byte(address:, value:, caller: self)
+        @m_cycles = @advance_cycle.call
+      end
+
+      # Fetches the next immediate byte from memory pointed to by the Program Counter.
+      # Every time a byte is fetched, the PC is incremented by 1.
+      def fetch_next_byte
+        byte = bus_read(address: @registers.pc)
+        @registers.pc += 1
+
+        byte
+      end
+
+      # Fetches the next 2 immediate bytes from memory.
+      #
+      # - The Game Boy uses little endian format.
+      # - This means that the first byte fetched is the least significant one.
+      # - So if the memory has these next 2 bytes: $50 $01, the word is: $0150
+      def fetch_next_word
+        lsb = fetch_next_byte
+        msb = fetch_next_byte
+
+        (msb << 8) | lsb
+      end
+
+      # Pushes a 16-bit value into the Stack.
+      #
+      # @param value [Integer] 16-bit value to be stored in the Stack.
+      def stack_push(value:)
+        @registers.sp -= 1
+        bus_write(address: @registers.sp, value: (value >> 8) & 0xFF)
+        @registers.sp -= 1
+        bus_write(address: @registers.sp, value: value & 0xFF)
+      end
+
+      # Pops a 16-bit value from the Stack.
+      def stack_pop
+        lsb = bus_read(address: @registers.sp)
+        @registers.sp += 1
+        msb = bus_read(address: @registers.sp)
+        @registers.sp += 1
+
+        (msb << 8) | lsb
+      end
+
+      # Jumps execution to a given address by setting the address value into the PC.
+      #
+      # @param address [Integer] 16-bit memory address value.
+      def jump_to(address:)
+        @registers.pc = address
+        internal_processing
+      end
+
+      # Converts an unsigned byte into a value between -128 to 127 to use as an offset.
+      #
+      # @param byte [Integer] 8-bit unsigned value.
+      def sign_value(byte)
+        byte >= 128 ? (byte - 256) : byte
+      end
+
+      # Performs an addition envolving a 16-bit value,
+      # CPU consumes an additional cycle to handle 16-bit values.
+      def add16(value1, value2)
+        result = value1 + value2
+        internal_processing
+
+        result
+      end
+
+      # Performs a subtraction envolving a 16-bit value,
+      # CPU consumes an additional cycle to handle 16-bit values.
+      def sub16(value1, value2)
+        result = value1 - value2
+        internal_processing
+
+        result
+      end
+
+      # Used by the DI instruction.
+      def disable_interrupts
+        @ime = false
+      end
+
+      # Used by the EI instruction.
+      def enable_interrupts
+        @ime_scheduled = true
+      end
+
+      def halt
+        @halted = true
+      end
+
+      # Emulates CPU internal processing which advance cycles without Bus access.
+      def internal_processing
+        @m_cycles = @advance_cycle.call
+      end
+
+      private
+
+      # Is only called if IME and any interrupt is pending.
+      # Takes 5 cycles to complete.
+      def handle_interrupts
+        @m_cycles = @advance_cycle.call
+        @m_cycles = @advance_cycle.call
+        @ime = false
+        stack_push(value: @registers.pc)
+        address_vector = @interrupts.priority_vector
+        @interrupts.priority_service
+        jump_to(address: address_vector)
+      end
+
+      # Determines which instruction should be executed for each Opcode.
+      def decode_instruction
+        if @opcode == 0xCB
+          @opcode = fetch_next_byte
+          @instruction = @cb_instructions[@opcode]
+        else
+          @instruction = @instructions[@opcode]
+        end
+      end
+
+      # Executes the logic for the current instruction.
+      def execute_instruction
+        @instruction.execute
+      end
+
+      def log_state(old_pc, old_cycles, instruction)
+        return unless @trace_cpu
+
+        $stdout.printf(
+          '%<cycles>04d | PC: $%<pc>04X | %<im>-14s (took %<ic>d) | ' \
+          '$%<b1>02X $%<b2>02X $%<b3>02X | F: %<f>04b | ' \
+          "A: $%<a>02X BC: $%<bc>04X DE: $%<de>04X HL: $%<hl>04X | [HL]: $%<mem_hl>02X\n",
+          cycles: @m_cycles,
+          pc: old_pc,
+          im: instruction.mnemonic,
+          ic: @m_cycles - old_cycles,
+          b1: @bus.read_byte(address: old_pc),
+          b2: @bus.read_byte(address: old_pc + 1),
+          b3: @bus.read_byte(address: old_pc + 2),
+          f: @registers.f >> 4,
+          a: @registers.a,
+          bc: @registers.bc,
+          de: @registers.de,
+          hl: @registers.hl,
+          mem_hl: @bus.read_byte(address: @registers.hl)
+        )
+      end
+
+      # Custom inspect method to facilitate debugging, prevents circular references
+      # since all instructions hold the Cpu object and the Cpu holds instruction objects.
+      def inspect
+        '#<Amaterasu::GameBoy::Cpu ' \
+          "@pc=$#{@registers.pc} " \
+          "@instructions_size=#{@instructions.compact.size} " \
+          "@cb_instructions_size=#{@cb_instructions.compact.size}>"
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/dma.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # Models the RAM chip within the Game Boy.
+    #
+    # On the real Game Boy, the CPU and DMA share the same physical bus.
+    # During DMA, the DMA controller physically takes over the bus lines — the CPU is
+    # electrically disconnected from the bus (except HRAM, which is on a separate internal path).
+    class Dma
+      OAM_START_ADDRESS = 0xFE00
+      DMA_START_DELAY = 1
+      DMA_TOTAL_CYCLES = 160 + DMA_START_DELAY
+
+      attr_reader :internal_latch
+
+      def initialize(bus, trace_dma: false)
+        @bus = bus
+        @trace_dma = trace_dma
+
+        @internal_latch = 0xFF
+        @source_address = nil
+        @target_address = OAM_START_ADDRESS
+        @status = :inactive
+        @active = false
+        @cycles = 0
+      end
+
+      # This method is called once per M-cycle, CPU drives this.
+      #
+      # - DMA transfer 1 byte per M-cycle, totalling 160 bytes.
+      # - It fills the OAM memory range from 0xFE00 - 0xFE9F.
+      def tick
+        case @status
+        when :inactive then nil
+        when :pending
+          log_state if @trace_dma
+          @cycles += 1
+          start_transfer
+        when :transferring
+          @active = true
+          source_byte = bus_read(address: @source_address)
+          bus_write(address: @target_address, value: source_byte)
+
+          log_state if @trace_dma
+
+          @source_address += 1
+          @target_address += 1
+          @cycles += 1
+
+          complete_transfer if @cycles == DMA_TOTAL_CYCLES
+        when :completed
+          @cycles = 0
+          @source_address = nil
+          @target_address = OAM_START_ADDRESS
+          @status = :inactive
+          @active = false
+        end
+      end
+
+      # When a value is written to 0xFF46, it means a DMA transfer was requested.
+      # The value represents the upper byte of the source address.
+      # This value is saved (latched), if there is a read from 0xFF46, it should return this value.
+      # Requesting a transfer with value 0x80, means the source address is 0x8000.
+      # You can multiple the given value by 0x100 to get the source address.
+      #
+      # @param source_value [Integer] A 8-bit value that represents the upper byte of the source address.
+      def request_transfer(source_value:)
+        @internal_latch = source_value
+        @source_address = source_value * 0x100
+        @status = :pending
+        @cycles = 0
+      end
+
+      # @return [Boolean] Checks if the DMA transfer is in progress.
+      def active?
+        @active
+      end
+
+      private
+
+      def start_transfer
+        @status = :transferring
+      end
+
+      def complete_transfer
+        @status = :completed
+      end
+
+      def bus_read(address:)
+        @bus.read_byte(address:)
+      end
+
+      def bus_write(address:, value:)
+        @bus.write_byte(address:, value:)
+      end
+
+      def log_state
+        if @cycles.zero?
+          puts 'DMA: #000 || START DELAY'
+        else
+          $stdout.printf(
+            "DMA: #%<n>03d || $%<sa>04X ($%<sb>02X) -> $%<ta>04X ($%<tb>02X)\n",
+            n: @cycles,
+            sa: @source_address,
+            sb: @bus.read_byte(address: @source_address),
+            ta: @target_address,
+            tb: @bus.read_byte(address: @target_address)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/interrupts.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # Models the Interrupts Controller inside the Game Boy
+    class Interrupts
+      # Interrupt types sorted by highest to lowest priority.
+      TYPES = {
+        v_blank: 0,
+        lcd_stat: 1,
+        timer: 2,
+        serial: 3,
+        joypad: 4
+      }.freeze
+
+      # Address vectors to jump to for each interrupt type.
+      VECTORS = {
+        v_blank: 0x0040,
+        lcd_stat: 0x0048,
+        timer: 0x0050,
+        serial: 0x0058,
+        joypad: 0x0060
+      }.freeze
+
+      # Creates a new interrupts object holding the registers state.
+      #
+      # - IF register value changes based on the Boot ROM being skipped.
+      def initialize(skip_boot_rom: true)
+        @if = skip_boot_rom ? 0xE1 : 0x00
+        @ie = 0x00
+      end
+
+      # Returns the 8-bit value of the IF (Interrupt Flag) register.
+      #
+      # - When read, it always returns 1 for Bits 7, 6 and 5.
+      def if_register
+        @if | 0b11100000
+      end
+
+      # TODO: convert to attr_reader
+      # Returns the 8-bit value of the IE (Interrupt Enable) register.
+      def ie_register
+        @ie
+      end
+
+      # Sets a 8-bit value into the IF register.
+      #
+      # - Bits 7, 6 and 5 are set to 0 when writing to it.
+      # - Components are responsible for requesting their own interrupts.
+      # - Controls whether or not a given interrupt is currently requested.
+      def if_register=(value)
+        @if = value & 0b00011111
+      end
+
+      # Sets a 8-bit value into the IE register.
+      #
+      # - Values are set by the game's code during CPU fetch-decode.
+      # - Controls whether or not a given interrupt is enabled and can be serviced.
+      def ie_register=(value)
+        @ie = value & 0xFF
+      end
+
+      # Checks if any interrupt is requested and enabled at the same time.
+      #
+      # - Ignores the 3 upper bits that are not bound to any interrupt type.
+      def any_pending?
+        (@if & @ie).anybits?(0b00011111)
+      end
+
+      # Returns which interrupt is currently requested and enabled, sorted by priority.
+      def highest_pending
+        TYPES.each_key do |type|
+          return type if pending?(type)
+        end
+
+        raise ArgumentError, 'No interrupts found for highest pending'
+      end
+
+      # Sets the correct Bit in the IF register based on the interrupt type.
+      def request(type)
+        set_mask = 1 << TYPES[type]
+        @if |= set_mask
+      end
+
+      # Clears the correct Bit in the IF register based on the interrupt type.
+      def service(type)
+        clear_mask = ~(1 << TYPES[type])
+        @if &= clear_mask
+      end
+
+      def priority_service
+        service(highest_pending)
+      end
+
+      def priority_vector
+        VECTORS[highest_pending]
+      end
+
+      private
+
+      # Checks if a given interrupt is requested and enabled at the same time.
+      def pending?(type)
+        set_mask = (1 << TYPES[type])
+        ((@if & set_mask) & (@ie & set_mask)).anybits?(0b00011111)
+      end
+    end
+  end
+end