psx 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7a1e5da6315c41ee938269c787e81c13431d1bcb6cd97b5122ec612fa8d0c6a
+  data.tar.gz: f16bb2c40428dedd7fa234ef19f250682e2b171f743688ef49595edac095d51a
+SHA512:
+  metadata.gz: b4701b76ec82805ea3ff3a474cfb7c6cc2e42d518c88cc9e81983134171d0360feb6e69863da282102bfadf3ecc76f5a9249b0e66af76d70e2347e6de8284fc4
+  data.tar.gz: c27d4922fcb211752bb804913a9a2cc5ce5f033b65cf79efc1233bf616702f7a4652d1668f14df131a081929ca930c87eba7e595d23acb56f69599fb169d2824

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 — 2026-05-15
+
+Initial release.
+
+- MIPS R3000A CPU with proper delay-slot / exception EPC handling.
+- COP0 and GTE (coprocessor 2) coverage sufficient for the BIOS boot path.
+- Software-rasteriser GPU covering most GP0/GP1 commands, textures (4/8/15
+  bit + CLUT), semi-transparency, mask bit.
+- DMA channels: OTC, GPU (block & linked-list), SPU, CDROM.
+- Interrupt controller, root counters, CD-ROM stub, SPU stub, SIO0 digital
+  pad (slot 1).
+- Boots the SCPH1001 BIOS into the Memory Card / CD-ROM shell menu.
+- `psx` SDL-backed CLI front-end.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Chris Hasiński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+# PSX
+
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](spec/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A work-in-progress PlayStation 1 emulator written in pure Ruby.
+
+It boots the SCPH1001 BIOS into the **Memory Card / CD-ROM shell** and can
+run a chunk of the [JaCzekanski/ps1-tests](https://github.com/JaCzekanski/ps1-tests)
+suite. There is no audio, the CD-ROM is a stub (no disc image loading yet),
+and the GPU is a software rasteriser with rough texture sampling — so don't
+expect to play games. Think of it as an executable spec for the PS1.
+
+![Memory Card menu rendered by the BIOS](docs/shell_menu.png)
+
+## Install
+
+```sh
+gem install psx
+```
+
+You will also need SDL2 on your system (the gem depends on `ruby-sdl2`):
+
+- macOS: `brew install sdl2`
+- Debian / Ubuntu: `sudo apt install libsdl2-dev`
+- Arch: `sudo pacman -S sdl2`
+
+## Usage
+
+You must supply your own BIOS ROM (typically `SCPH1001.BIN`, 512 KB). PSX
+does not ship one — BIOS images are copyrighted.
+
+```sh
+psx path/to/SCPH1001.BIN
+```
+
+Run `psx --help` for the option list. Keyboard controls (slot 1 digital pad):
+
+| Key            | Button   |
+| -------------- | -------- |
+| Arrow keys     | D-pad    |
+| Z              | Cross    |
+| X              | Circle   |
+| A              | Square   |
+| S              | Triangle |
+| Enter          | Start    |
+| Space          | Select   |
+| Q / W          | L1 / R1  |
+| E / R          | L2 / R2  |
+| Escape         | Quit     |
+
+The BIOS shell idles on the Sony logo until you press Triangle, which opens
+the Memory Card / CD-ROM menu.
+
+## Programmatic use
+
+```ruby
+require "psx"
+
+emu = PSX::Emulator.new("SCPH1001.BIN")
+emu.run(steps: 300_000_000)            # boot to shell
+emu.controller_state_proc = -> { 0xEFFF }   # press Triangle
+emu.run(steps: 30_000_000)
+emu.save_screenshot("menu.ppm")
+```
+
+The emulator exposes the major components individually: `emu.cpu`,
+`emu.memory`, `emu.gpu`, `emu.dma`, `emu.cdrom`, `emu.sio0`, `emu.interrupts`,
+`emu.timers`.
+
+## Development
+
+```sh
+git clone https://github.com/khasinski/psx
+cd psx
+bundle install
+bundle exec rake test
+```
+
+The `bin/` directory contains development tools that are *not* shipped with
+the gem:
+
+| Script            | Purpose                                                                 |
+| ----------------- | ----------------------------------------------------------------------- |
+| `bin/psx-ruby`    | Headless boot of the BIOS (no SDL window).                              |
+| `bin/psx-test`    | Run a PS-EXE on top of the BIOS, diff against ps1-tests reference logs. |
+| `bin/psx-smoke`   | Boot the BIOS and dump PPM screenshots at intervals.                    |
+| `bin/psx-trace`   | PC histogram + I_STAT/I_MASK summary at checkpoints.                    |
+| `bin/psx-disasm`  | Disassemble a range of physical addresses after N cycles of boot.       |
+| `bin/psx-biostrace` | Tally A/B/C jump-table calls; dump the last N calls.                   |
+| `bin/psx-puts-trace` | Capture the kernel's debug TTY (`puts2`, `printf`, …).                |
+| `bin/psx-memwatch`| Log reads/writes to specific addresses with the PC that did them.       |
+| `bin/psx-dumpmem` | Hex-dump a range of memory after N cycles of boot.                      |
+
+### Running ps1-tests
+
+The `bin/psx-test` runner expects a local checkout of
+[JaCzekanski/ps1-tests](https://github.com/JaCzekanski/ps1-tests):
+
+```sh
+git clone https://github.com/JaCzekanski/ps1-tests.git .tests
+bundle exec ruby bin/psx-test -e .tests/cpu/cop/psx.log .tests/cpu/cop/cop.exe
+```
+
+## Status
+
+What works:
+
+- MIPS R3000A CPU with delay slots, exceptions, COP0
+- GTE (passes the `gte/test-all` shape, several coverage gaps)
+- GPU: GP0 polygons / lines / rectangles, textured / shaded / semi-transparent
+  primitives, CPU↔VRAM blits, mask bit. Software rasteriser, no PGXP.
+- DMA channels for OTC, GPU (block / linked list), SPU (stub), CDROM (stub)
+- Interrupt controller, root counters
+- CD-ROM stub (responds to BIOS probe; no disc image support)
+- SIO0 digital pad (slot 1)
+- SPU stub (mirrors SPUCNT → SPUSTAT; no actual audio synthesis)
+- Boots SCPH1001 into the Memory Card menu
+
+What doesn't:
+
+- No CD-ROM image loading — can't boot real games
+- No SPU audio synthesis (no sound)
+- Several ps1-tests fail (CD-ROM timing, code-in-IO bus errors)
+- Texture sampling has visible glitches on the shell UI
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/psx

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# PlayStation 1 emulator — graphical front-end. Loads a BIOS image and runs
+# the emulator with an SDL window for display + keyboard controller input.
+
+RubyVM::YJIT.enable if defined?(RubyVM::YJIT.enable)
+
+require "psx"
+
+def usage
+  warn <<~USAGE
+    PSX — PlayStation 1 emulator (#{PSX::VERSION})
+
+    Usage: psx [options] <bios.bin>
+
+    Options:
+      -f, --fps N         Target FPS (default: 60)
+      -n, --no-frameskip  Disable frame skipping
+      -v, --version       Print version and exit
+      -h, --help          Show this help
+
+    Controls (keyboard, slot 1 digital pad):
+      Arrow keys    D-pad
+      Z             Cross (confirm)
+      X             Circle (cancel)
+      A             Square
+      S             Triangle
+      Enter         Start
+      Space         Select
+      Q / W         L1 / R1
+      E / R         L2 / R2
+      Escape        Quit
+
+    A BIOS ROM (e.g. SCPH1001.BIN, 512 KB) is required and must be provided
+    by the user; PSX-Ruby does not ship one.
+  USAGE
+  exit 1
+end
+
+target_fps = 60
+frameskip = true
+bios_path = nil
+
+args = ARGV.dup
+while (arg = args.shift)
+  case arg
+  when "-f", "--fps"
+    target_fps = args.shift&.to_i
+    usage if target_fps.nil? || target_fps <= 0
+  when "-n", "--no-frameskip"
+    frameskip = false
+  when "-v", "--version"
+    puts PSX::VERSION
+    exit 0
+  when "-h", "--help"
+    usage
+  else
+    bios_path = arg
+  end
+end
+
+usage unless bios_path
+
+unless File.exist?(bios_path)
+  warn "Error: BIOS file not found: #{bios_path}"
+  exit 1
+end
+
+puts "PSX-Ruby #{PSX::VERSION}"
+puts "Loading BIOS: #{bios_path}"
+puts "Target FPS: #{target_fps}"
+puts "Frame skip: #{frameskip ? 'enabled' : 'disabled'}"
+puts "YJIT: #{defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled? ? 'enabled' : 'disabled'}"
+puts ""
+
+begin
+  emu = PSX::Emulator.new(bios_path)
+  emu.run_with_display(target_fps: target_fps, frameskip: frameskip)
+rescue Interrupt
+  puts "\nInterrupted by user"
+rescue => e
+  warn "\nError: #{e.message}"
+  warn e.backtrace.first(5).join("\n")
+  exit 1
+end

data/lib/psx/bios.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PSX
+  class BIOS
+    SIZE = 512 * 1024  # 512 KB
+
+    def initialize(path)
+      @data = File.binread(path)
+
+      if @data.bytesize != SIZE
+        raise ArgumentError, "Invalid BIOS size: expected #{SIZE} bytes, got #{@data.bytesize}"
+      end
+
+      # Pre-compute 32-bit word array for fast read32 access
+      # This trades memory for speed (512KB -> 512KB + 128K integers)
+      @words = Array.new(SIZE / 4) do |i|
+        offset = i * 4
+        @data.getbyte(offset) |
+          (@data.getbyte(offset + 1) << 8) |
+          (@data.getbyte(offset + 2) << 16) |
+          (@data.getbyte(offset + 3) << 24)
+      end
+    end
+
+    def read8(offset)
+      @data.getbyte(offset)
+    end
+
+    def read16(offset)
+      @data.getbyte(offset) | (@data.getbyte(offset + 1) << 8)
+    end
+
+    def read32(offset)
+      # Fast path: aligned access from pre-computed array
+      if (offset & 3) == 0
+        @words[offset >> 2]
+      else
+        # Unaligned access (rare)
+        @data.getbyte(offset) |
+          (@data.getbyte(offset + 1) << 8) |
+          (@data.getbyte(offset + 2) << 16) |
+          (@data.getbyte(offset + 3) << 24)
+      end
+    end
+  end
+end

data/lib/psx/cdrom.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module PSX
+  # Minimal CD-ROM controller stub.
+  #
+  # Enough to convince the BIOS that there's a CD subsystem present with no
+  # disc inserted, so it proceeds to the shell screen. Handles the commands
+  # the BIOS issues during boot: GetStat, Init, GetID, Setmode, Test, etc.
+  #
+  # We don't model timing accurately. Responses are queued and delivered one
+  # per tick (called from the emulator's frame loop), respecting that the
+  # previous IRQ must be acknowledged and the previous response FIFO drained
+  # before the next response shows up.
+  class CDROM
+    # Status register (0x1F801800 read) bits
+    STAT_INDEX_MASK              = 0x03
+    STAT_ADPCM_BUSY              = 0x04
+    STAT_PARAMETER_FIFO_EMPTY    = 0x08
+    STAT_PARAMETER_FIFO_NOT_FULL = 0x10
+    STAT_RESPONSE_FIFO_NOT_EMPTY = 0x20
+    STAT_DATA_FIFO_NOT_EMPTY     = 0x40
+    STAT_BUSY                    = 0x80
+
+    # "stat" byte returned in command responses.
+    # Bit 4 = shell open (we say closed); bit 0 = error.
+    # We default to 0x02 (motor on, no error, no disc seek done) for no-disc.
+    DEFAULT_STAT = 0x02
+
+    def initialize(interrupts:)
+      @interrupts = interrupts
+      reset
+    end
+
+    def reset
+      @index = 0
+      @parameters = []
+      @response  = []
+      @irq_enable = 0
+      @irq_flags  = 0          # bits 0-2 = pending INT type (0..7)
+      @pending = []            # [[int_type, [bytes...]], ...]
+      @stat = DEFAULT_STAT
+    end
+
+    # --- Bus interface ------------------------------------------------------
+
+    def read8(reg)
+      case reg & 3
+      when 0 then status
+      when 1
+        # Response FIFO
+        v = @response.shift || 0
+        v & 0xFF
+      when 2
+        # Data FIFO (no data, just return 0)
+        0
+      when 3
+        case @index
+        when 0, 2 then @irq_enable | 0xE0
+        when 1, 3 then @irq_flags | 0xE0
+        end
+      end
+    end
+
+    def write8(reg, value)
+      v = value & 0xFF
+      case reg & 3
+      when 0
+        @index = v & 3
+      when 1
+        case @index
+        when 0 then execute_command(v)
+        # other indices: audio map / right CD audio routing — ignore
+        end
+      when 2
+        case @index
+        when 0
+          @parameters.push(v) if @parameters.size < 16
+        when 1
+          @irq_enable = v & 0x1F
+        # 2/3 = audio routing — ignore
+        end
+      when 3
+        case @index
+        when 0
+          # Request register: bit 7 BFRD enables data buffer read; bit 5 SMEN.
+          # Both unused by our stub.
+        when 1
+          # Ack IRQ flags and optionally reset parameter FIFO (bit 6).
+          @irq_flags &= ~(v & 0x1F)
+          @parameters.clear if (v & 0x40) != 0
+        # 2/3 = audio volume apply — ignore
+        end
+      end
+    end
+
+    # Advance one step in the response queue. Call this periodically (e.g.
+    # once per VBlank). One delivery per call: a response only appears once
+    # the previous one has been acknowledged.
+    def tick
+      return if @pending.empty?
+      return if @irq_flags != 0           # previous IRQ not yet acknowledged
+      return if !@response.empty?         # previous response not yet drained
+
+      type, data = @pending.shift
+      @response.concat(data)
+      @irq_flags = type & 0x07
+      @interrupts.request(Interrupts::IRQ_CDROM) if (@irq_enable & @irq_flags) != 0
+    end
+
+    private
+
+    def status
+      s = @index & STAT_INDEX_MASK
+      s |= STAT_PARAMETER_FIFO_EMPTY    if @parameters.empty?
+      s |= STAT_PARAMETER_FIFO_NOT_FULL if @parameters.size < 16
+      s |= STAT_RESPONSE_FIFO_NOT_EMPTY unless @response.empty?
+      s
+    end
+
+    def execute_command(cmd)
+      # Drain any leftover response bytes from a prior command. Real hardware
+      # has an 8-deep response FIFO that the BIOS may not fully read after an
+      # error (e.g. INT5 on GetID with no disc returns 8 bytes but the BIOS
+      # only consumes a couple). Without this, our `tick` stays blocked
+      # forever waiting for `@response.empty?` and no further commands fire.
+      @response.clear
+      case cmd
+      when 0x01 # Getstat
+        queue(3, [@stat])
+      when 0x02 # Setloc (MM, SS, FF)
+        @parameters.clear
+        queue(3, [@stat])
+      when 0x06 # ReadN
+        queue(3, [@stat])
+        queue(5, [0x11, 0x80])  # no disc -> error
+      when 0x07 # MotorOn
+        queue(3, [@stat])
+        queue(2, [@stat])
+      when 0x08 # Stop
+        queue(3, [@stat])
+        queue(2, [@stat])
+      when 0x09 # Pause
+        queue(3, [@stat])
+        queue(2, [@stat])
+      when 0x0A # Init
+        queue(3, [@stat])
+        queue(2, [@stat])
+      when 0x0B # Mute
+        queue(3, [@stat])
+      when 0x0C # Demute
+        queue(3, [@stat])
+      when 0x0D # Setfilter
+        queue(3, [@stat])
+      when 0x0E # Setmode
+        queue(3, [@stat])
+      when 0x0F # Getparam
+        queue(3, [@stat, 0x00, 0x00, 0x00])
+      when 0x10 # GetlocL
+        queue(3, [0, 0, 0, 0, 0, 0, 0, 0])
+      when 0x11 # GetlocP
+        queue(3, [1, 1, 0, 0, 0, 0, 0, 0])
+      when 0x13 # GetTN (number of tracks)
+        queue(3, [@stat, 0x01, 0x01])
+      when 0x14 # GetTD
+        queue(3, [@stat, 0x00, 0x02])
+      when 0x15 # SeekL
+        queue(3, [@stat])
+        queue(2, [@stat])
+      when 0x16 # SeekP
+        queue(3, [@stat])
+        queue(2, [@stat])
+      when 0x19 # Test
+        sub = @parameters.shift
+        case sub
+        when 0x20 # Get BIOS date/version
+          queue(3, [0x94, 0x09, 0x19, 0xC0])
+        else
+          queue(3, [@stat])
+        end
+      when 0x1A # GetID
+        # No-disc response per nocash spec: INT3(stat) then
+        # INT5(11h, 80h, 00h, 00h, 00h, 00h, 00h, 00h). 0x80 in byte 1 is
+        # the "no disc / not ready" error code.
+        queue(3, [@stat])
+        queue(5, [0x11, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
+      when 0x1B # ReadS
+        queue(3, [@stat])
+        queue(5, [0x11, 0x80])
+      when 0x1E # ReadTOC
+        queue(3, [@stat])
+        queue(2, [@stat])
+      else
+        queue(3, [@stat])  # default ack to keep BIOS moving
+      end
+      @parameters.clear unless cmd == 0x19  # Test consumes its own params
+    end
+
+    def queue(int_type, data)
+      @pending.push([int_type, data])
+    end
+  end
+end

data/lib/psx/cop0.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module PSX
+  # Coprocessor 0 - System Control
+  # Handles exceptions, interrupts, and memory management
+  class COP0
+    # Register indices
+    BPC      = 3   # Breakpoint on execute
+    BDA      = 5   # Breakpoint on data access
+    JUMPDEST = 6   # Jump destination (for branch delay debugging)
+    DCIC     = 7   # Breakpoint control
+    BADVADDR = 8   # Bad virtual address
+    BDAM     = 9   # Data access breakpoint mask
+    BPCM     = 11  # Execute breakpoint mask
+    SR       = 12  # Status register
+    CAUSE    = 13  # Exception cause
+    EPC      = 14  # Exception program counter
+    PRID     = 15  # Processor ID
+
+    # Status register bits
+    SR_IEC  = 0x01       # Interrupt Enable Current
+    SR_KUC  = 0x02       # Kernel/User Mode Current (0=kernel)
+    SR_IEP  = 0x04       # Interrupt Enable Previous
+    SR_KUP  = 0x08       # Kernel/User Mode Previous
+    SR_IEO  = 0x10       # Interrupt Enable Old
+    SR_KUO  = 0x20       # Kernel/User Mode Old
+    SR_IM   = 0xFF00     # Interrupt Mask (bits 8-15)
+    SR_ISC  = 0x1_0000   # Isolate Cache
+    SR_SWC  = 0x2_0000   # Swap Caches
+    SR_PZ   = 0x4_0000   # Parity Zero
+    SR_CM   = 0x8_0000   # Cache Miss
+    SR_PE   = 0x10_0000  # Parity Error
+    SR_TS   = 0x20_0000  # TLB Shutdown
+    SR_BEV  = 0x40_0000  # Boot Exception Vectors
+    SR_RE   = 0x200_0000 # Reverse Endianness
+    SR_CU0  = 0x1000_0000  # COP0 Enable
+    SR_CU1  = 0x2000_0000  # COP1 Enable (no FPU on PSX, but enable bit exists)
+    SR_CU2  = 0x4000_0000  # COP2 (GTE) Enable
+    SR_CU3  = 0x8000_0000  # COP3 Enable
+
+    # Exception codes (for CAUSE register bits 2-6)
+    EXC_INT   = 0x00  # Interrupt
+    EXC_MOD   = 0x01  # TLB modification
+    EXC_TLBL  = 0x02  # TLB load
+    EXC_TLBS  = 0x03  # TLB store
+    EXC_ADEL  = 0x04  # Address error (load/fetch)
+    EXC_ADES  = 0x05  # Address error (store)
+    EXC_IBE   = 0x06  # Bus error (instruction fetch)
+    EXC_DBE   = 0x07  # Bus error (data load/store)
+    EXC_SYS   = 0x08  # Syscall
+    EXC_BP    = 0x09  # Breakpoint
+    EXC_RI    = 0x0A  # Reserved instruction
+    EXC_CPU   = 0x0B  # Coprocessor unusable
+    EXC_OV    = 0x0C  # Arithmetic overflow
+
+    # Interrupt bits in CAUSE (bits 8-15, matches SR mask)
+    IRQ_SOFTWARE0 = 0x0100
+    IRQ_SOFTWARE1 = 0x0200
+    IRQ_HARDWARE  = 0x0400  # External hardware interrupt (active when I_STAT & I_MASK != 0)
+
+    attr_reader :regs
+
+    def initialize
+      @regs = Array.new(32, 0)
+      @regs[PRID] = 0x0000_0002  # R3000A processor ID
+    end
+
+    def read(reg)
+      @regs[reg]
+    end
+
+    def write(reg, value)
+      case reg
+      when SR
+        # Most bits are writable
+        @regs[SR] = value & 0xF4C7_9C3F
+      when CAUSE
+        # Only software interrupt bits (8-9) are writable
+        @regs[CAUSE] = (value & 0x0300) | (@regs[CAUSE] & ~0x0300)
+      when PRID
+        # Read-only
+      else
+        @regs[reg] = value
+      end
+    end
+
+    def sr
+      @regs[SR]
+    end
+
+    def sr=(value)
+      write(SR, value)
+    end
+
+    def cause
+      @regs[CAUSE]
+    end
+
+    def epc
+      @regs[EPC]
+    end
+
+    def cache_isolated?
+      (@regs[SR] & SR_ISC) != 0
+    end
+
+    def bev?
+      (@regs[SR] & SR_BEV) != 0
+    end
+
+    def interrupts_enabled?
+      (@regs[SR] & SR_IEC) != 0
+    end
+
+    def interrupt_pending?
+      # Check if any unmasked interrupt is pending
+      return false unless interrupts_enabled?
+
+      mask = (@regs[SR] >> 8) & 0xFF
+      pending = (@regs[CAUSE] >> 8) & 0xFF
+      (mask & pending) != 0
+    end
+
+    def set_hardware_irq(active)
+      if active
+        @regs[CAUSE] |= IRQ_HARDWARE
+      else
+        @regs[CAUSE] &= ~IRQ_HARDWARE
+      end
+    end
+
+    # Enter exception handler. Returns the exception vector address.
+    # `coprocessor` is the COP number (0-3) reported in CAUSE.CE for
+    # Coprocessor-Unusable exceptions.
+    def enter_exception(code, pc, in_delay_slot: false, bad_addr: nil, coprocessor: nil)
+      @regs[EPC] = in_delay_slot ? pc - 4 : pc
+      @regs[BADVADDR] = bad_addr if bad_addr
+
+      # CAUSE: preserve interrupt-pending bits, set ExcCode, BD, and CE.
+      ce = coprocessor ? ((coprocessor & 0x3) << 28) : 0
+      @regs[CAUSE] = (@regs[CAUSE] & 0x0000_FF00) |
+                     (code << 2) |
+                     ce |
+                     (in_delay_slot ? 0x8000_0000 : 0)
+
+      # Shift IE/KU stack: current -> previous -> old.
+      mode = @regs[SR] & 0x3F
+      @regs[SR] = (@regs[SR] & ~0x3F) | ((mode << 2) & 0x3F)
+
+      bev? ? 0xBFC0_0180 : 0x8000_0080
+    end
+
+    # Return from exception (RFE instruction)
+    def return_from_exception
+      # Shift interrupt enable/kernel mode bits back
+      # Old -> Previous -> Current
+      mode = @regs[SR] & 0x3F
+      @regs[SR] = (@regs[SR] & ~0x0F) | ((mode >> 2) & 0x0F)
+    end
+  end
+end