amaterasu 0.6.0

data/lib/amaterasu/cartridge/rom.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  class Cartridge
+    # models the ROM inside the Game Boy cartridge.
+    class Rom
+      CARTRIDGE_TYPES = {
+        0x00 => 'ROM ONLY',
+        0x01 => 'MBC1',
+        0x02 => 'MBC1+RAM',
+        0x03 => 'MBC1+RAM+BATTERY',
+        0x05 => 'MBC2'
+      }.freeze
+
+      ROM_SIZES = {
+        0x00 => 32 * 1024,
+        0x01 => 64 * 1024,
+        0x02 => 128 * 1024,
+        0x03 => 256 * 1024,
+        0x04 => 512 * 1024,
+        0x05 => 1024 * 1024,
+        0x06 => 2 * 1024 * 1024,
+        0x07 => 4 * 1024 * 1024,
+        0x08 => 8 * 1024 * 1024
+      }.freeze
+
+      RAM_SIZES = {
+        0x00 => 0,
+        0x02 => 8 * 1024,
+        0x03 => 32 * 1024,
+        0x04 => 128 * 1024,
+        0x05 => 64 * 1024
+      }.freeze
+
+      def self.from_file(file_path)
+        new(File.binread(file_path).bytes)
+      end
+
+      # Creates a ROM object given the bytes array and freezes it (read-only).
+      def initialize(data)
+        @data = data
+        @data.freeze
+      end
+
+      # Returns a 8-bit value stored in the given address/offset.
+      def read_byte(offset)
+        @data[offset]
+      end
+
+      def header
+        @data[0x0100..0x014F]
+      end
+
+      # Returns a string containing the ROM title.
+      def title
+        @data[0x0134..0x0143].pack('C*').strip
+      end
+
+      def manufacturer_code
+        @data[0x013F..0x0142]
+      end
+
+      def cgb_flag
+        @data[0x0143]
+      end
+
+      def new_licensee_code
+        @data[0x0144..0x0145]
+      end
+
+      def sgb_flag
+        @data[0x0146]
+      end
+
+      # Returns a symbol for the cartridge type (:rom_only, :mbc1, ...).
+      def cartridge_type
+        CARTRIDGE_TYPES[@data[0x0147]]
+      end
+
+      # Returns an Integer indicating the ROM size.
+      def rom_size
+        ROM_SIZES[@data[0x0148]]
+      end
+
+      # Returns an Integer indicating the RAM size.
+      def ram_size
+        RAM_SIZES[@data[0x0149]]
+      end
+
+      def destination_code
+        @data[0x014A]
+      end
+
+      def old_licensee_code
+        @data[0x014B]
+      end
+
+      def mask_rom_version
+        @data[0x014C]
+      end
+
+      # Returns a 8-bit value for the header checksum.
+      def header_checksum
+        @data[0x014D]
+      end
+
+      # Calculates the checksum and returns true if it matches.
+      def valid_checksum?
+        checksum = 0
+        (0x0134..0x014C).each do |address|
+          checksum = checksum - @data[address] - 1
+        end
+
+        (checksum & 0xFF) == header_checksum
+      end
+    end
+  end
+end

data/lib/amaterasu/cartridge.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  # Models a Game Boy cartridge.
+  class Cartridge
+    ROM_BANK_SIZE = 16 * 1024
+    RAM_BANK_SIZE = 8 * 1024
+
+    # Loads a Rom from a file path.
+    def self.load_rom(file_path, trace_rom:)
+      rom = Rom.from_file(file_path)
+
+      raise ArgumentError, 'Invalid ROM' unless rom.valid_checksum?
+
+      if trace_rom
+        puts rom.title
+        puts rom.cartridge_type
+        puts rom.rom_size
+        puts rom.ram_size
+      end
+
+      new(rom: rom)
+    end
+
+    # Creates a cartridge object based on the cartridge type.
+    def initialize(rom:, mbc: nil, ram: nil)
+      @rom = rom
+      @ram = ram
+      @mbc = mbc
+
+      add_ram if rom.cartridge_type.include?('RAM')
+      add_mbc(Mbc1.new(@rom, @ram)) if rom.cartridge_type.include?('MBC1')
+    end
+
+    def add_mbc(mbc)
+      @mbc = mbc
+    end
+
+    def add_ram
+      @ram = GameBoy::Ram.new(size: @rom.ram_size, offset: 0xA000)
+    end
+
+    # Delegates the read byte to either the ROM or the MBC (Not implemented yet).
+    def read_rom(address)
+      @mbc.nil? ? @rom.read_byte(address) : @mbc.read_byte(address)
+    end
+
+    # Delegates the read byte to the MBC (Not implemented yet).
+    def write_rom(address, value)
+      return unless @mbc
+
+      @mbc.write_byte(address, value)
+    end
+
+    def read_ram(address)
+      return 0xFF if @ram.nil?
+
+      @mbc.nil? ? @ram.read_byte(address) : @mbc.read_byte(address)
+    end
+
+    # Delegates the write byte to the MBC (Not implemented yet).
+    def write_ram(address, value)
+      return unless @mbc
+
+      @mbc.write_byte(address, value)
+    end
+  end
+end

data/lib/amaterasu/cli.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Amaterasu
+  # Handles arguments parsing when launching the emulator.
+  class CLI
+    def self.parse(arguments)
+      # @type var options: emulator_options
+      options = {
+        audio: nil,
+        cycles: nil,
+        profiling: nil,
+        steps: nil,
+        trace: nil,
+        video: nil,
+        rom_path: nil
+      }
+
+      opt_parser = OptionParser.new do |parser|
+        parser.banner = 'Usage: amaterasu [options] ROM_PATH'
+
+        parser.on('-a', '--audio=AUDIO', 'Define the audio backend') do |audio|
+          options[:audio] = audio
+        end
+
+        parser.on('-c', '--cycles=n', Integer, 'Amount of dots to tick') do |n|
+          options[:cycles] = n
+        end
+
+        parser.on(
+          '-p',
+          '--profiling=MODE',
+          %w[cpu object wall],
+          'Enable Stackprof profiling (cpu, object, wall)'
+        ) do |mode|
+          options[:profiling] = mode.to_sym
+        end
+
+        parser.on('-s', '--steps=n', Integer, 'Amount of CPU steps to run') do |n|
+          options[:steps] = n
+        end
+
+        parser.on('-t', '--trace=COMPONENT', 'Enable logging for specific component') do |component|
+          options[:trace] = component
+        end
+
+        parser.on('-v', '--video=VIDEO', 'Define the video backend') do |video|
+          options[:video] = video
+        end
+      end
+
+      opt_parser.parse!(arguments)
+      options[:rom_path] = arguments.first
+      raise ArgumentError, 'ROM_PATH must be provided' unless options[:rom_path]
+
+      options
+    end
+  end
+end

data/lib/amaterasu/emulator.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  # Handles the core emulation loop.
+  class Emulator
+    CYCLES_PER_FRAME = 17_556
+
+    def initialize(
+      audio:,
+      cycles:,
+      profiling:,
+      steps:,
+      trace:,
+      video:,
+      rom_path:
+    )
+      @audio = audio
+      @video = video
+      @stop_cycles = cycles
+      @stop_steps = steps
+      @profiling_mode = profiling
+      @trace = trace
+      @rom_path = rom_path
+
+      @cycles = 0
+      @steps = 0
+    end
+
+    def start
+      @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      load_cartridge
+      load_memory
+      load_components
+
+      Kernel.loop do
+        stop if @stop_steps && @steps == @stop_steps
+
+        @cpu.step
+        @steps += 1
+      end
+    end
+
+    # This method is called every time the CPU spends
+    # exactly 1 M-cycle to advance other components.
+    def advance_cycle
+      stop if @stop_cycles && @cycles == @stop_cycles
+
+      @timer.tick
+      @apu.tick
+      @dma.tick
+
+      i = 0
+
+      while i < 4
+        @ppu.tick
+        i += 1
+      end
+
+      @cycles += 1
+    end
+
+    private
+
+    def load_cartridge
+      @cartridge = Cartridge.load_rom(@rom_path, trace_rom: @trace == 'rom')
+    end
+
+    def load_memory
+      @wram = GameBoy::Ram.new(size: 8192, offset: 0xC000)
+      @hram = GameBoy::Ram.new(size: 127, offset: 0xFF80)
+      @vram = GameBoy::Vram.new
+      @oam  = GameBoy::Oam.new
+    end
+
+    def load_components
+      @bus = GameBoy::Bus.new
+      @sdl2 = HAL::SDL2.new unless @video == 'null'
+      @apu = GameBoy::Apu.new
+      @dma = GameBoy::Dma.new(@bus, trace_dma: @trace == 'dma')
+      @interrupts = GameBoy::Interrupts.new
+      @ppu = GameBoy::Ppu.new(@vram, @oam, @sdl2, @interrupts, trace_ppu: @trace == 'ppu')
+      @timer = GameBoy::Timer.new(@interrupts, trace_timer: @trace == 'timer')
+      @serial = GameBoy::Serial.new(@interrupts, trace_serial: @trace == 'serial')
+      @joypad = GameBoy::Joypad.new(@interrupts)
+      @sdl2.joypad = @joypad
+      @bus.wire_components(
+        cartridge: @cartridge,
+        ppu: @ppu,
+        wram: @wram,
+        hram: @hram,
+        interrupts: @interrupts,
+        apu: @apu,
+        timer: @timer,
+        serial: @serial,
+        joypad: @joypad,
+        dma: @dma
+      )
+      @cpu = GameBoy::Cpu.new(
+        @bus,
+        @hram,
+        @interrupts,
+        -> { advance_cycle },
+        trace_cpu: @trace == 'cpu'
+      )
+    end
+
+    def stop
+      @elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+
+      frames = @cycles.to_f / 17_556
+      fps = frames / @elapsed_time
+
+      puts "#{@steps} steps / #{@cycles} cycles in #{@elapsed_time.round(2)}s"
+      puts "#{fps.round(2)} FPS (Target: 59.73)"
+      puts "#{(fps / 59.73).round(2)}x real-time Game Boy"
+
+      exit
+    end
+  end
+end

data/lib/amaterasu/game_boy/apu.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # Models the APU behavior from the Game Boy.
+    class Apu
+      def tick
+        # tick logic
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/bus.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # | 0x0000-0x7FFF | 32 KiB | Cartridge ROM    | Bank 0 fixed, Bank N switchable |
+    # | 0x8000-0x9FFF | 8 KiB  | Video RAM (VRAM) | Tile data + tile maps           |
+    # | 0xA000-0xBFFF | 8 KiB  | External RAM     | Cartridge RAM, battery-backed   |
+    # | 0xC000-0xDFFF | 8 KiB  | Work RAM (WRAM)  | General purpose                 |
+    # | 0xE000-0xFDFF | ~8 KiB | Echo RAM         | Mirror of WRAM (0xC000-0xDDFF)  |
+    # | 0xFE00-0xFE9F | 160 B  | OAM              | Sprite attribute table          |
+    # | 0xFEA0-0xFEFF | 96 B   | Unusable         | Prohibited area                 |
+    # | 0xFF00-0xFF7F | 128 B  | I/O Registers    | Hardware control                |
+    # | 0xFF80-0xFFFE | 127 B  | High RAM (HRAM)  | Fast RAM, accessible during DMA |
+    # | 0xFFFF        | 1 B    | IE Register      | Interrupt Enable                |
+    class Bus
+      def wire_components(
+        cartridge:,
+        ppu:,
+        wram:,
+        hram:,
+        interrupts:,
+        apu:,
+        timer:,
+        serial:,
+        joypad:,
+        dma:
+      )
+        @cartridge = cartridge
+        @ppu = ppu
+        @wram = wram
+        @hram = hram
+        @interrupts = interrupts
+        @apu = apu
+        @timer = timer
+        @serial = serial
+        @joypad = joypad
+        @dma = dma
+      end
+
+      # Delegates the read to the proper component based on the address
+      # and returns the 8-bit value that was stored there.
+      def read_byte(address:, caller: nil)
+        return 0xFF if @dma.active?
+          && caller.is_a?(Cpu)
+          && address < 0xFF00
+
+        if address <= 0x7FFF
+          @cartridge.read_rom(address)
+        elsif address <= 0x9FFF
+          @ppu.read_vram(address:)
+        elsif address <= 0xBFFF
+          @cartridge.read_ram(address)
+        elsif address <= 0xDFFF
+          @wram.read_byte(address:)
+        elsif address <= 0xFDFF
+          @wram.read_byte(address: address - 0x2000)
+        elsif address <= 0xFE9F
+          @ppu.read_oam(address:)
+        elsif address <= 0xFEFF
+          0xFF
+        elsif address <= 0xFF7F
+          read_io(address)
+        elsif address <= 0xFFFE
+          @hram.read_byte(address:)
+        elsif address == 0xFFFF
+          @interrupts.ie_register
+        else
+          raise "Not implemented bus read at $#{address.to_s(16)}"
+        end
+      end
+
+      # Delegates the write to the proper component based on the address
+      # and stores a 8-bit value at that location.
+      def write_byte(address:, value:, caller: nil)
+        return if @dma.active?
+          && caller.is_a?(Cpu)
+          && address < 0xFF00
+
+        if address <= 0x7FFF
+          @cartridge.write_rom(address, value)
+        elsif address <= 0x9FFF
+          @ppu.write_vram(address:, value:)
+        elsif address <= 0xBFFF
+          @cartridge.write_ram(address - 0xA000, value)
+        elsif address <= 0xDFFF
+          @wram.write_byte(address:, value:)
+        elsif address <= 0xFDFF
+          @wram.write_byte(address: address - 0x2000, value:)
+        elsif address <= 0xFE9F
+          @ppu.write_oam(address:, value:)
+        elsif address <= 0xFEFF
+          nil
+        elsif address <= 0xFF7F
+          write_io(address, value)
+        elsif address <= 0xFFFE
+          @hram.write_byte(address:, value:)
+        elsif address == 0xFFFF
+          @interrupts.ie_register = value
+        else
+          raise "Not implemented bus write at $#{address.to_s(16)}"
+        end
+      end
+
+      private
+
+      # Extracts the IO registers read logic for organization.
+      def read_io(address)
+        case address
+        when 0xFF00 then @joypad.p1
+        when 0xFF01 then @serial.sb
+        when 0xFF02 then @serial.sc
+        when 0xFF04 then @timer.div
+        when 0xFF05 then @timer.tima
+        when 0xFF06 then @timer.tma
+        when 0xFF07 then @timer.tac
+        when 0xFF0F then @interrupts.if_register
+        when 0xFF40 then @ppu.registers.lcdc.value
+        when 0xFF41 then @ppu.registers.stat.value
+        when 0xFF42 then @ppu.registers.scy
+        when 0xFF43 then @ppu.registers.scx
+        when 0xFF44 then @ppu.registers.ly
+        when 0xFF45 then @ppu.registers.lyc
+        when 0xFF46 then @dma.internal_latch
+        when 0xFF47 then @ppu.registers.bgp
+        when 0xFF48 then @ppu.registers.obp0
+        when 0xFF49 then @ppu.registers.obp1
+        when 0xFF4A then @ppu.registers.wy
+        when 0xFF4B then @ppu.registers.wx
+        else
+          0xFF
+        end
+      end
+
+      # Extracts the IO registers write logic for organization.
+      def write_io(address, value)
+        case address
+        when 0xFF00 then @joypad.p1 = value
+        when 0xFF01 then @serial.sb = value
+        when 0xFF02 then @serial.sc = value
+        when 0xFF04 then @timer.div = value
+        when 0xFF05 then @timer.tima = value
+        when 0xFF06 then @timer.tma = value
+        when 0xFF07 then @timer.tac = value
+        when 0xFF0F then @interrupts.if_register = value
+        when 0xFF40 then @ppu.registers.lcdc = value
+        when 0xFF41 then @ppu.registers.stat = value
+        when 0xFF42 then @ppu.registers.scy = value
+        when 0xFF43 then @ppu.registers.scx = value
+        when 0xFF44 then nil # @ppu.registers.ly = value -> read-only
+        when 0xFF45 then @ppu.registers.lyc = value
+        when 0xFF46 then @dma.request_transfer(source_value: value)
+        when 0xFF47 then @ppu.registers.bgp = value
+        when 0xFF48 then @ppu.registers.obp0 = value
+        when 0xFF49 then @ppu.registers.obp1 = value
+        when 0xFF4A then @ppu.registers.wy = value
+        when 0xFF4B then @ppu.registers.wx = value
+        end
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/cpu/instructions/adc.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    class Cpu
+      module Instructions
+        # Handles the logic related to all possible ADC instructions
+        #
+        # - ADC A, r8
+        # - ADC A, [HL]
+        # - ADC A, n8
+        class Adc < Base
+          # @param cpu [Cpu] Holds a direct reference to the main Cpu object.
+          # @param source [Symbol] Operator, can be a register, :mem_hl, :imm8.
+          def initialize(cpu:, source:)
+            super(cpu:)
+
+            @mnemonic = "ADC A, #{source}"
+            @logic    = build_logic(source)
+          end
+
+          private
+
+          # Builds the logic for all ADC instructions.
+          # Returns a lambda object to be called by the CPU.
+          def build_logic(source)
+            case source
+            when :a      then -> { adc_a(@registers.a) }
+            when :b      then -> { adc_a(@registers.b) }
+            when :c      then -> { adc_a(@registers.c) }
+            when :d      then -> { adc_a(@registers.d) }
+            when :e      then -> { adc_a(@registers.e) }
+            when :h      then -> { adc_a(@registers.h) }
+            when :l      then -> { adc_a(@registers.l) }
+            when :mem_hl then -> { adc_a(@cpu.bus_read(address: @registers.hl)) }
+            when :imm8   then -> { adc_a(@cpu.fetch_next_byte) }
+            else
+              raise ArgumentError, 'Unknown Adc source'
+            end
+          end
+
+          # ADCs a given value plus the Carry flag into register A.
+          #
+          # - Sets the Zero flag if the result is zero, otherwise clears it.
+          # - Sets the Subtraction flag to zero.
+          # - Sets the Half Carry flag if there was overflow from Bit 3, otherwise clears it.
+          # - Sets the Carry flag if there was overflow from Bit 7, otherwise clears it.
+          def adc_a(value)
+            acc = @registers.a
+            carry_in = @registers.c_flag
+            result = @registers.a + value + carry_in
+
+            @registers.z_flag = result.nobits?(0xFF)
+            @registers.n_flag = false
+            @registers.h_flag = (acc & 0x0F) + (value & 0x0F) + carry_in > 0x0F
+            @registers.c_flag = result > 0xFF
+
+            @registers.a = result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/cpu/instructions/add16.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    class Cpu
+      module Instructions
+        # Handles the logic related to all possible ADD 16-bit instructions.
+        #
+        # - ADD HL, BC
+        # - ADD HL, DE
+        # - ADD HL, HL
+        # - ADD HL, SP
+        # - ADD SP, sig8
+        class Add16 < Base
+          def initialize(cpu:, source:, target:)
+            super(cpu:)
+
+            @mnemonic = "ADD #{format_operand(source)}, #{format_operand(target)}"
+            @logic    = build_logic(source, target)
+          end
+
+          private
+
+          # Builds the logic for each ADD 16-bit instruction.
+          # @return [Proc] A lambda object to be called by the CPU.
+          def build_logic(source, target)
+            return -> { add16_sig8 } if target == :sp
+
+            case source
+            when :bc     then -> { add16(@registers.bc) }
+            when :de     then -> { add16(@registers.de) }
+            when :hl     then -> { add16(@registers.hl) }
+            when :sp     then -> { add16(@registers.sp) }
+            else
+              raise ArgumentError, 'Unknown Add16 source'
+            end
+          end
+
+          # M-cycle 1: Fetches the instruction opcode.
+          # M-cycle 2: 16-bit add operation + flag logic + set result.
+          def add16(reg16_value)
+            hl_value = @registers.hl
+            result = @cpu.add16(@registers.hl, reg16_value)
+
+            @registers.n_flag = false
+            @registers.h_flag = (hl_value & 0x0FFF) + (reg16_value & 0x0FFF) > 0x0FFF
+            @registers.c_flag = result > 0xFFFF
+
+            @registers.hl = result
+          end
+
+          # M-cycle 1: Fetches the instruction opcode.
+          # M-cycle 2: Fetches the next byte in the PC.
+          # M-cycle 3: Signs the value + internal processing.
+          # M-cycle 4: 16-bit Add operation + flag logic + set result.
+          def add16_sig8
+            sp = @registers.sp
+            unsigned_byte = @cpu.fetch_next_byte
+            offset = @cpu.sign_value(unsigned_byte)
+            @cpu.internal_processing
+            result = @cpu.add16(@registers.sp, offset)
+
+            @registers.clear_flags
+            @registers.h_flag = (sp & 0x0F) + (unsigned_byte & 0x0F) > 0x0F
+            @registers.c_flag = (sp & 0xFF) + (unsigned_byte & 0xFF) > 0xFF
+
+            @registers.sp = result
+          end
+        end
+      end
+    end
+  end
+end