amaterasu 0.6.0

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    class Ppu
+      # Models the behavior of the PPU registers.
+      class Registers
+        attr_reader :lcdc,
+                    :stat,
+                    :scy,
+                    :scx,
+                    :ly,
+                    :lyc,
+                    :bgp,
+                    :obp0,
+                    :obp1,
+                    :wy,
+                    :wx,
+                    :bg_palettes,
+                    :sprite_palettes0,
+                    :sprite_palettes1
+
+        # @param skip_boot_rom [Boolean]
+        def initialize(interrupts, skip_boot_rom: true)
+          @lcdc = LcdControl.new(skip_boot_rom:)
+          @stat = LcdStatus.new(interrupts, skip_boot_rom:)
+          @scy  = 0x00
+          @scx  = 0x00
+          @ly   = 0x00
+          @lyc  = 0x00
+          @bgp  = skip_boot_rom ? 0xFC : 0x00
+          @obp0 = 0x00
+          @obp1 = 0x00
+          @wy   = 0x00
+          @wx   = 0x00
+
+          @bg_palettes = [
+            @bgp & 0b11,
+            (@bgp >> 2) & 0b11,
+            (@bgp >> 4) & 0b11,
+            (@bgp >> 6) & 0b11
+          ]
+
+          @sprite_palettes0 = [
+            @obp0 & 0b11,
+            (@obp0 >> 2) & 0b11,
+            (@obp0 >> 4) & 0b11,
+            (@obp0 >> 6) & 0b11
+          ]
+
+          @sprite_palettes1 = [
+            @obp1 & 0b11,
+            (@obp1 >> 2) & 0b11,
+            (@obp1 >> 4) & 0b11,
+            (@obp1 >> 6) & 0b11
+          ]
+        end
+
+        # @param value [Integer]
+        def lcdc=(value)
+          @lcdc.value = value
+        end
+
+        # @param value [Integer]
+        def stat=(value)
+          @stat.value = value
+        end
+
+        # @param value [Integer]
+        def scy=(value)
+          @scy = value & 0xFF
+        end
+
+        # @param value [Integer]
+        def scx=(value)
+          @scx = value & 0xFF
+        end
+
+        # @param value [Integer]
+        def ly=(value)
+          @ly = value & 0xFF
+        end
+
+        # @param value [Integer]
+        def lyc=(value)
+          @lyc = value & 0xFF
+        end
+
+        # @param value [Integer]
+        def bgp=(value)
+          @bgp = value & 0xFF
+
+          @bg_palettes[0] = @bgp & 0b11
+          @bg_palettes[1] = (@bgp >> 2) & 0b11
+          @bg_palettes[2] = (@bgp >> 4) & 0b11
+          @bg_palettes[3] = (@bgp >> 6) & 0b11
+        end
+
+        # @param value [Integer]
+        def obp0=(value)
+          @obp0 = value & 0xFF
+
+          @sprite_palettes0[0] = @obp0 & 0b11
+          @sprite_palettes0[1] = (@obp0 >> 2) & 0b11
+          @sprite_palettes0[2] = (@obp0 >> 4) & 0b11
+          @sprite_palettes0[3] = (@obp0 >> 6) & 0b11
+        end
+
+        # @param value [Integer]
+        def obp1=(value)
+          @obp1 = value & 0xFF
+
+          @sprite_palettes1[0] = @obp1 & 0b11
+          @sprite_palettes1[1] = (@obp1 >> 2) & 0b11
+          @sprite_palettes1[2] = (@obp1 >> 4) & 0b11
+          @sprite_palettes1[3] = (@obp1 >> 6) & 0b11
+        end
+
+        # @param value [Integer]
+        def wy=(value)
+          @wy = value & 0xFF
+        end
+
+        # @param value [Integer]
+        def wx=(value)
+          @wx = value & 0xFF
+        end
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/ppu.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # This class models the Pixel Processing Unit from the Original Game Boy.
+    #
+    # The Ppu outputs a 160x144 pixel framebuffer each frame.
+    # This framebuffer will be used by the chosen Renderer to display the graphics.
+    # The Ppu should not care about how the pixels are rendered, just output them.
+    #
+    # Specifications:
+    # - The frame consists of 154 scanlines, 144 visible + 10 vblank (Cpu can access VRAM).
+    # - Scanlines are drawn from top to bottom, left to right.
+    # - Updating registers mid-frame can cause effects since the pixels are still being drawn.
+    # - Dots per scanline = 456 t-cycles (114 m-cycles) -> Hardware spec.
+    # - Dots per frame = 154 * 456 = 70_224 t-cycles (17_556 m-cycles).
+    # - OAM search takes 80 dots (20 m-cycles) -> 40 sprites, 2 dots each.
+    class Ppu
+      include Utils::BitOps
+
+      PIXELS_PER_SCANLINE = 160
+      VISIBLE_SCANLINES = 144
+      TOTAL_SCANLINES = 154
+      DOTS_PER_SCANLINE = 456
+      MAX_SPRITES_PER_SCANLINE = 10
+
+      attr_accessor :wy_eq_ly, :window_y_count
+
+      attr_reader :registers,
+                  :dots,
+                  :framebuffer,
+                  :sprite_buffer
+
+      def initialize(
+        vram,
+        oam,
+        display,
+        interrupts,
+        skip_boot_rom: true,
+        trace_ppu: false
+      )
+        @vram = vram
+        @oam = oam
+        @display = display
+        @interrupts = interrupts
+        @trace_ppu = trace_ppu
+
+        @registers     = Registers.new(interrupts, skip_boot_rom:)
+        @framebuffer   = Array.new
+        @sprite_buffer = Array.new(MAX_SPRITES_PER_SCANLINE).clear
+
+        @modes = Modes.build_hash(self)
+        @mode  = set_mode(:disabled)
+        @wy_eq_ly = false
+        @window_y_count = 0
+        @dots = 0
+      end
+
+      # Core PPU state machine.
+      #
+      # Each mode is responsible for its own logic and
+      # also switching to the next mode.
+      def tick
+        @mode.tick
+        log_state if @trace_ppu
+        @dots += 1
+      end
+
+      # Sets the current PPU mode to be ticked.
+      # Updates STAT Bits 1-0 that reads the current PPU mode.
+      #
+      # @param mode [Symbol]
+      def set_mode(mode)
+        @mode = @modes[mode]
+        @registers.stat.set_mode_bits(@mode.number)
+        # request_interrupt(:lcd_stat) if @registers.stat.rising_edge?
+
+        @mode
+      end
+
+      def reset_for_scanline
+        @dots = 0
+        @sprite_buffer.clear unless @sprite_buffer.empty?
+      end
+
+      # Restarts the rendering pipeline state.
+      def reset_states
+        reset_for_scanline
+        @registers.ly = 0x00
+        @wy_eq_ly = false # here?
+        @window_y_count = 0
+        @framebuffer.clear
+
+        ly_compare
+      end
+
+      # Delegates the draw to the chosen Renderer.
+      def draw_frame
+        @display&.draw(@framebuffer)
+      end
+
+      def request_interrupt(interrupt_type)
+        @interrupts.request(interrupt_type)
+      end
+
+      def increment_ly
+        @registers.ly += 1
+
+        ly_compare
+      end
+
+      def ly_compare
+        if @registers.ly == @registers.lyc
+          @registers.stat.set_lyc_bit
+        else
+          @registers.stat.clear_lyc_bit
+        end
+
+        # request_interrupt(:lcd_stat) if @registers.stat.rising_edge?
+      end
+
+      # Returns a 8-bit value stored in VRAM in a given address.
+      #
+      # @param address [Integer]
+      # @return [Integer]
+      def read_vram(address:)
+        return 0xFF if @mode == @modes[:rendering]
+
+        @vram.read_byte(address:)
+      end
+
+      # Stores a 8-bit value in VRAM in a given address.
+      #
+      # @param address [Integer]
+      # @param value [Integer]
+      def write_vram(address:, value:)
+        @vram.write_byte(address:, value:)
+      end
+
+      # Returns a 8-bit value stored in OAM in a given address.
+      def read_oam(address:)
+        return 0xFF if [@modes[:oam_scan], @modes[:rendering]].include?(@mode)
+
+        @oam.read_byte(address:)
+      end
+
+      # Stores a 8-bit value in OAM in a given address.
+      def write_oam(address:, value:)
+        @oam.write_byte(address:, value:)
+      end
+
+      def fetch_sprite_at(index)
+        @oam.sprite(index)
+      end
+
+      # @return [TileMap]
+      def window_tile_map
+        return @vram.tile_map_high if @registers.lcdc.window_tile_map_high?
+
+        @vram.tile_map_low
+      end
+
+      # @return [TileMap]
+      def bg_tile_map
+        return @vram.tile_map_high if @registers.lcdc.bg_tile_map_high?
+
+        @vram.tile_map_low
+      end
+
+      # @return [TileData]
+      def bg_win_tile_data
+        @vram.tile_data.addressing_mode =
+          if @registers.lcdc.tile_data_at_0x8000?
+            :unsigned
+          else
+            :signed
+          end
+
+        @vram.tile_data
+      end
+
+      # @return [TileData]
+      def obj_tile_data
+        @vram.tile_data.addressing_mode = :unsigned
+        @vram.tile_data
+      end
+
+      private
+
+      # Prints the current state of the PPU into the console for debugging.
+      def log_state
+        $stdout.printf(
+          '#%<dots>03d | ' \
+          'LY: $%<ly>02X (%<ly>d) | ' \
+          'LCDC: $%<lcdc>02X | ' \
+          'STAT: $%<stat>02X | ' \
+          "MODE: %<mode>s\n",
+          dots: @dots,
+          ly: @registers.ly,
+          lcdc: @registers.lcdc.value,
+          stat: @registers.stat.value,
+          mode: @mode.to_s
+        )
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/ram.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # Models the RAM chip within the Game Boy.
+    class Ram
+      # Memory size in bytes.
+      attr_reader :size
+
+      # Creates a new Ram object.
+      #
+      # @param size [Integer] Memory size in bytes.
+      # @param offset [Integer] Address offset based on the Bus memory map.
+      def initialize(size:, offset:)
+        @size = size
+        @offset = offset
+
+        @data = Array.new(size, 0x00)
+        @backup = nil
+        @backed_up = false
+      end
+
+      # Returns a 8-bit value from a given address in memory.
+      def read_byte(address:)
+        @data[address - @offset]
+      end
+
+      # Stores a 8-bit value into a given address in memory.
+      def write_byte(address:, value:)
+        @data[address - @offset] = value & 0xFF
+      end
+
+      # Provides an interface to read backup data.
+      def read_backup(address:)
+        return 0xFF unless @backed_up
+
+        @backup[address - @offset]
+      end
+
+      # Returns a readable string in B or KiB based on memory size.
+      def disk_size
+        return "#{@size} B" if @size < 1024
+
+        "#{@size / 1024} KiB"
+      end
+
+      # Creates a copy of the current state of memory.
+      def save_data
+        @backup = @data.dup
+        @backed_up = true
+      end
+
+      # Restores a previously backed up memory state.
+      def restore_data
+        @data = @backup.dup
+      end
+
+      # Clears all previously set memory values.
+      def wipe_data
+        @data = Array.new(@size, 0x00)
+      end
+
+      # Clears all previously set backup values.
+      def wipe_backup
+        @backup = Array.new
+        @backed_up = false
+      end
+    end
+  end
+end

data/lib/amaterasu/game_boy/serial.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Amaterasu
+  module GameBoy
+    # Models the Serial Port present in the Game Boy.
+    #
+    # - Very useful for performing community accuracy tests, they use the serial to output results.
+    class Serial
+      # Returns the 8-bit value stored in the SB (Serial Transfer Data) register.
+      attr_reader :sb
+
+      # Returns an Array with all the bytes from the serial transfer.
+      attr_reader :message_buffer
+
+      # Creates a serial port instance.
+      #
+      # - Needs to hold an instance of interrupts to request a :serial interrupt.
+      # - Holds the state of the Transfer Data and Control registers.
+      def initialize(interrupts, trace_serial: false)
+        @interrupts = interrupts
+        @trace_serial = trace_serial
+
+        @sb = 0x00
+        @sc = 0xFF
+
+        @message_buffer = Array.new
+      end
+
+      # Returns the 8-bit value stored in the SC (Serial Transfer Control) register.
+      #
+      # - In the actual hardware only Bit 7 and Bit 0 are wired.
+      # - Bits 6-1 always return 1 when read.
+      def sc
+        @sc | 0b01111110
+      end
+
+      # Sets a 8-bit value into the SB register.
+      def sb=(value)
+        @sb = value & 0xFF
+      end
+
+      # Sets a 8-bit value into the SC register.
+      #
+      # - Bits 6-1 are ignored since they are not wired to anything.
+      # - If bit 7 goes from 0 -> 1, a transfer is started.
+      def sc=(value)
+        @sc = value & 0b10000001
+
+        start_transfer if transfer_enabled?
+      end
+
+      private
+
+      # Bit 7 from the SC register determines if the transfer is enabled.
+      def transfer_enabled?
+        (@sc >> 7).allbits?(1)
+      end
+
+      # Bit 0 from the SC register determines which clock controls the transfer.
+      #
+      # - If Bit 0 is set, the internal clock from the receiving Game Boy controls the transfer.
+      # - If Bit 0 is cleared, the Game Boy waits for an external clock pulse.
+      def clock_bit
+        @sc & 1
+      end
+
+      # Transfers the byte from the SB register.
+      #
+      # - For the transfer to actually begin bits 7 and 0 need to be set.
+      # - Internal clock must be selected, otherwise it just waits.
+      def start_transfer
+        return if clock_bit.zero?
+
+        @message_buffer << @sb
+        @sb = 0xFF
+
+        complete_transfer
+      end
+
+      # Completes the transfer immediately after.
+      #
+      # - Transfer enable flag (Bit 7) is cleared.
+      # - Requests a :serial interrupt.
+      def complete_transfer
+        @sc &= 0b01111111
+        puts @message_buffer.pack('C*') if @trace_serial
+        @interrupts.request(:serial)
+      end
+    end
+  end
+end