psx 0.1.0

data/lib/psx.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require_relative "psx/version"
+require_relative "psx/bios"
+require_relative "psx/ram"
+require_relative "psx/cop0"
+require_relative "psx/interrupts"
+require_relative "psx/dma"
+require_relative "psx/gpu"
+require_relative "psx/timers"
+require_relative "psx/cdrom"
+require_relative "psx/sio0"
+require_relative "psx/spu"
+require_relative "psx/memory"
+require_relative "psx/cpu"
+require_relative "psx/disasm"
+require_relative "psx/display"
+
+module PSX
+  class Emulator
+    attr_reader :cpu, :memory, :interrupts, :dma, :gpu, :timers, :cdrom, :sio0
+    attr_accessor :controller_state_proc
+
+    # Timing constants
+    CPU_FREQ = 33_868_800  # 33.8688 MHz
+    CYCLES_PER_FRAME = CPU_FREQ / 60  # ~560K cycles per frame at 60Hz
+    CYCLES_PER_SCANLINE = CYCLES_PER_FRAME / 263  # NTSC has 263 scanlines
+
+    def initialize(bios_path)
+      bios = BIOS.new(bios_path)
+      ram = RAM.new
+      @interrupts = Interrupts.new
+      @spu = SPU.new
+      @dma = DMA.new(interrupts: @interrupts, spu: @spu)
+      @gpu = GPU.new(interrupts: @interrupts)
+      @timers = Timers.new(interrupts: @interrupts)
+      @cdrom = CDROM.new(interrupts: @interrupts)
+      @controller_state_proc = -> { 0xFFFF }
+      @sio0 = SIO0.new(interrupts: @interrupts, controller_state: -> { @controller_state_proc.call })
+      @memory = Memory.new(
+        bios: bios, ram: ram, interrupts: @interrupts,
+        dma: @dma, timers: @timers, cdrom: @cdrom, sio0: @sio0, spu: @spu
+      )
+      @memory.gpu = @gpu
+      @cpu = CPU.new(@memory, interrupts: @interrupts)
+
+      @cycle_count = 0
+      @frame_count = 0
+    end
+
+    def run(steps: nil, debug: false)
+      if debug
+        run_debug(steps)
+      elsif steps
+        run_fast(steps)
+      else
+        run_forever
+      end
+    rescue CPU::ExecutionError => e
+      puts "Execution error: #{e.message}"
+      puts @cpu.dump_registers
+      raise
+    end
+
+    # Fast path for Ruby CPU: known number of steps, no debug
+    def run_fast(steps)
+      cpu = @cpu
+      cycle_count = @cycle_count
+      frame_count = @frame_count
+      timers = @timers
+      interrupts = @interrupts
+      gpu = @gpu
+      remaining = steps
+
+      sio0 = @sio0
+      dma = @dma
+      tick_threshold = 64
+      while remaining > 0
+        remaining -= 1
+        cpu.step
+
+        # Inlined tick_devices. cpu.step_cycles is the effective cycle cost
+        # of the instruction we just ran (1 for ALU, 2 for loads). Using it
+        # instead of a constant 1 keeps the VBlank period in line with the
+        # BIOS' own timing expectations, so VSync waits don't time out.
+        cycles = cpu.step_cycles
+        cycle_count += cycles
+        if cycle_count >= tick_threshold
+          tick_threshold = cycle_count + 64
+          timers.tick(64)
+          sio0.tick(64)
+          dma.tick_cycles(64)
+        end
+        if cycle_count >= CYCLES_PER_FRAME
+          cycle_count = 0
+          tick_threshold = 64
+          frame_count += 1
+          interrupts.request(Interrupts::IRQ_VBLANK)
+          gpu.vblank
+          @cdrom.tick
+        end
+      end
+
+      @cycle_count = cycle_count
+      @frame_count = frame_count
+    end
+
+    def run_forever
+      loop do
+        @cpu.step
+        tick_devices
+      end
+    end
+
+    def run_debug(steps)
+      count = 0
+      loop do
+        puts @cpu.disassemble_current
+        puts @cpu.dump_registers if count % 10 == 0
+        @cpu.step
+        tick_devices
+        count += 1
+        break if steps && count >= steps
+      end
+    end
+
+    # Run for specified number of frames
+    def run_frames(frames)
+      frames.times do |f|
+        run(steps: CYCLES_PER_FRAME)
+        @interrupts.request(Interrupts::IRQ_VBLANK)
+        @frame_count += 1
+      end
+    end
+
+    # Run with graphical display (threaded: emulation in background)
+    def run_with_display(target_fps: 60, frameskip: true)
+      display = Display.new(title: "PSX-Ruby - Loading BIOS...")
+      @controller_state_proc = -> { display.controller_state }
+      render_interval = 1.0 / target_fps
+
+      # Run many cycles between renders for speed
+      cycles_per_chunk = 100_000  # Smaller chunks for better responsiveness
+
+      puts "Starting emulation with display (threaded)..."
+      puts "Note: BIOS takes ~40 seconds to show Sony logo"
+      puts "Controls: Arrow keys=D-pad, Z=Cross, X=Circle, A=Square, S=Triangle"
+      puts "          Enter=Start, Space=Select, Q/W=L1/R1, Escape=Quit"
+      puts ""
+
+      # Shared state
+      @emu_mutex = Mutex.new
+      @quit_flag = false
+      @emu_error = nil
+      @total_cycles = 0
+
+      # Emulation thread
+      emu_thread = Thread.new do
+        loop do
+          break if @quit_flag
+
+          begin
+            @emu_mutex.synchronize do
+              run(steps: cycles_per_chunk)
+              @total_cycles += cycles_per_chunk
+            end
+          rescue CPU::ExecutionError => e
+            @emu_error = e
+            break
+          end
+
+          # Small yield to let main thread get lock
+          Thread.pass if @total_cycles % 500_000 == 0
+        end
+      end
+
+      # Main thread: SDL events and rendering
+      last_render = Time.now
+      last_status = Time.now
+      last_status_cycles = 0
+      loop do
+        # Poll SDL events (must be on main thread on macOS)
+        display.poll_events
+        if display.quit_requested?
+          @quit_flag = true
+          break
+        end
+
+        # Check for emulation errors
+        if @emu_error
+          puts "CPU Error: #{@emu_error.message}"
+          @emu_mutex.synchronize { puts @cpu.dump_registers }
+          @quit_flag = true
+          break
+        end
+
+        # Render at target FPS. Important: do NOT toggle @gpu.vblank here.
+        # The emulator's run loop is the authoritative driver of vblank
+        # (CYCLES_PER_FRAME boundaries). Toggling here at wall-clock 60 Hz on
+        # top of that confuses BIOS-side vsync counters and trips
+        # SystemErrorUnresolvedException.
+        now = Time.now
+        elapsed = now - last_render
+        if elapsed >= render_interval
+          @emu_mutex.synchronize do
+            @frame_count += 1
+            display.update(@gpu.framebuffer)
+          end
+          last_render = now
+        else
+          # Sleep for remaining time to hit target FPS
+          sleep_time = render_interval - elapsed
+          sleep(sleep_time * 0.8) if sleep_time > 0.001  # Don't oversleep
+        end
+
+        # Periodic status line so progress is visible from the console.
+        if now - last_status >= 2.0
+          delta = @total_cycles - last_status_cycles
+          ips = delta.to_f / (now - last_status)
+          printf "frames=%5d  cycles=%10d  %.1f Mips  PC=%08X\n",
+                 @frame_count, @total_cycles, ips / 1_000_000.0, @cpu.pc
+          $stdout.flush
+          last_status = now
+          last_status_cycles = @total_cycles
+        end
+      end
+
+      # Wait for emulation thread to finish
+      emu_thread.join(1.0)  # Wait up to 1 second
+
+      display.close
+      puts "\nEmulation ended after #{@frame_count} frames (#{@total_cycles} cycles)"
+    end
+
+    # Load a PS-EXE executable into RAM and prepare the CPU to run it.
+    # Standard PSX EXE format: 2048-byte header (magic "PS-X EXE"), followed
+    # by the text/data section that must be copied to dest_addr. After load
+    # the CPU is positioned at the executable's entry point with GP and SP
+    # set per the header (or the conventional defaults if zero).
+    def load_psexe(path)
+      data = File.binread(path)
+      raise "PS-EXE smaller than header: #{data.bytesize} bytes" if data.bytesize < 0x800
+      magic = data.byteslice(0, 8)
+      raise "Not a PS-EXE (magic=#{magic.inspect})" unless magic == "PS-X EXE"
+
+      initial_pc    = data.byteslice(0x10, 4).unpack1("V")
+      initial_gp    = data.byteslice(0x14, 4).unpack1("V")
+      dest_addr     = data.byteslice(0x18, 4).unpack1("V")
+      file_size     = data.byteslice(0x1C, 4).unpack1("V")
+      memfill_start = data.byteslice(0x20, 4).unpack1("V")
+      memfill_size  = data.byteslice(0x24, 4).unpack1("V")
+      stack_addr    = data.byteslice(0x28, 4).unpack1("V")
+      _stack_size   = data.byteslice(0x2C, 4).unpack1("V")
+
+      payload = data.byteslice(0x800, file_size) || ""
+      payload.each_byte.with_index do |b, i|
+        @memory.write8((dest_addr + i) & 0xFFFF_FFFF, b)
+      end
+
+      if memfill_size.positive?
+        memfill_size.times do |i|
+          @memory.write8((memfill_start + i) & 0xFFFF_FFFF, 0)
+        end
+      end
+
+      sp = stack_addr.zero? ? 0x801F_FFF0 : stack_addr
+      @cpu.regs[28] = initial_gp & 0xFFFF_FFFF
+      @cpu.regs[29] = sp & 0xFFFF_FFFF
+      @cpu.regs[30] = sp & 0xFFFF_FFFF
+      @cpu.regs[31] = 0 # return-to-zero on exit
+      @cpu.pc = initial_pc
+
+      {
+        entry: initial_pc, gp: initial_gp, sp: sp, dest: dest_addr,
+        size: file_size, memfill: [memfill_start, memfill_size]
+      }
+    end
+
+    # Save framebuffer as PPM image
+    def save_screenshot(filename)
+      fb = @gpu.framebuffer
+      rgba = fb[:rgba]
+      width = fb[:width]
+      height = fb[:height]
+
+      # Extract RGB from RGBA (skip alpha bytes)
+      rgb_data = String.new(capacity: width * height * 3)
+      i = 0
+      (width * height).times do
+        rgb_data << rgba.getbyte(i).chr << rgba.getbyte(i + 1).chr << rgba.getbyte(i + 2).chr
+        i += 4
+      end
+
+      File.open(filename, "wb") do |f|
+        f.puts "P6"
+        f.puts "#{width} #{height}"
+        f.puts "255"
+        f.write rgb_data
+      end
+      puts "Saved screenshot to #{filename} (#{width}x#{height})"
+    end
+
+    # Save framebuffer as ASCII art (for terminal)
+    def ascii_screenshot(width: 80)
+      fb = @gpu.framebuffer
+      rgba = fb[:rgba]
+      scale_x = fb[:width].to_f / width
+      height = (fb[:height] / scale_x / 2).to_i  # /2 because terminal chars are ~2x tall
+
+      chars = " .:-=+*#%@"
+
+      lines = []
+      height.times do |y|
+        line = +""  # Unfrozen string
+        width.times do |x|
+          src_x = (x * scale_x).to_i
+          src_y = (y * scale_x * 2).to_i
+          # RGBA format: 4 bytes per pixel
+          idx = (src_y * fb[:width] + src_x) * 4
+          r = rgba.getbyte(idx) || 0
+          g = rgba.getbyte(idx + 1) || 0
+          b = rgba.getbyte(idx + 2) || 0
+          brightness = (r + g + b) / 3.0 / 255.0
+          char_idx = (brightness * (chars.length - 1)).to_i
+          line << chars[char_idx]
+        end
+        lines << line
+      end
+      lines.join("\n")
+    end
+
+    private
+
+    def tick_devices
+      @cycle_count += 1
+
+      # Tick timers less frequently for performance
+      if @cycle_count % 64 == 0
+        @timers.tick(64)
+        @sio0.tick(64)
+        @dma.tick_cycles(64)
+      end
+
+      # VBlank every frame
+      if @cycle_count >= CYCLES_PER_FRAME
+        @cycle_count = 0
+        @frame_count += 1
+        @interrupts.request(Interrupts::IRQ_VBLANK)
+        @gpu.vblank  # Toggle interlace field
+        @cdrom.tick
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: psx
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Hasiński
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-sdl2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+description: |
+  A work-in-progress PlayStation 1 emulator written entirely in Ruby.
+  Implements the MIPS R3000A CPU, GTE, GPU (software rasteriser), DMA,
+  interrupts, timers, CD-ROM stub, SIO0 controller, and a minimal SPU —
+  enough to boot the SCPH1001 BIOS into the Memory Card / CD-ROM shell.
+  Ships an SDL2-backed front-end via the `psx` command. A BIOS image is
+  not included and must be supplied by the user.
+email:
+- krzysztof.hasinski@gmail.com
+executables:
+- psx
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/psx
+- lib/psx.rb
+- lib/psx/bios.rb
+- lib/psx/cdrom.rb
+- lib/psx/cop0.rb
+- lib/psx/cpu.rb
+- lib/psx/disasm.rb
+- lib/psx/display.rb
+- lib/psx/dma.rb
+- lib/psx/gpu.rb
+- lib/psx/gte.rb
+- lib/psx/interrupts.rb
+- lib/psx/memory.rb
+- lib/psx/ram.rb
+- lib/psx/sio0.rb
+- lib/psx/spu.rb
+- lib/psx/timers.rb
+- lib/psx/version.rb
+homepage: https://github.com/khasinski/psx
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/khasinski/psx
+  bug_tracker_uri: https://github.com/khasinski/psx/issues
+  changelog_uri: https://github.com/khasinski/psx/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: PlayStation 1 emulator written in pure Ruby
+test_files: []