psx_rt/

interrupts.rs

//! Minimal interrupt support used by engine-level clocks.
//!
//! The first consumer is a monotonic VBlank counter. We install a
//! tiny exception-vector trampoline that handles VBlank IRQs itself,
//! increments a volatile counter, acknowledges the IRQ, then returns
//! with `rfe`. The handler deliberately uses only the MIPS kernel
//! registers `$k0/$k1`, so it does not need a stack frame.

#[cfg(target_arch = "mips")]
use psx_hw::{cop0, dma, gpu, gte, memory};
#[cfg(target_arch = "mips")]
use psx_io::irq;

#[cfg(target_arch = "mips")]
core::arch::global_asm!(
    r#"
    .set noreorder
    .section .text.psx_rt_exception
    .globl __psx_rt_exception_handler
__psx_rt_exception_handler:
    lui   $26, {io_hi}
    lw    $27, {i_stat}($26)
    lw    $26, {i_mask}($26)
    nop
    and   $27, $27, $26
    andi  $27, $27, {vblank_mask}
    beqz  $27, 9f
    nop

    lui   $26, %hi(__psx_rt_vblank_count)
    lw    $27, %lo(__psx_rt_vblank_count)($26)
    nop
    addiu $27, $27, 1
    sw    $27, %lo(__psx_rt_vblank_count)($26)

    # Present queue (`crate::present`, `present-queue` feature only). One
    # published chain waits in __psx_rt_present_head (0 = empty). Kick it on
    # the first edge where the previous chain's closing GP0(1Fh) has run
    # (GPUSTAT bit 24) and DMA channel 2 is idle: flip to the finished frame,
    # acknowledge the flag with GP1(02h) (the new chain raises it again at its
    # own end), point GP0 DMA at the CPU with GP1(04h)=2, enable channel 2 in
    # DPCR and start the linked-list walk. Ported from quake-psx 3ca915c.
    # With the slot empty this costs one load.
    .if {present}
    lui   $26, %hi(__psx_rt_present_head)
    lw    $27, %lo(__psx_rt_present_head)($26)
    nop
    beqz  $27, 8f
    nop
    lui   $26, {io_hi}
    lw    $27, {gp1}($26)
    nop
    srl   $27, $27, {gpustat_irq1_shift}
    andi  $27, $27, 1
    beqz  $27, 7f
    nop
    lw    $27, {gpu_chcr}($26)
    nop
    srl   $27, $27, {chcr_start_shift}
    andi  $27, $27, 1
    bnez  $27, 7f
    nop
    lui   $27, %hi(__psx_rt_present_display)
    lw    $27, %lo(__psx_rt_present_display)($27)
    nop
    beqz  $27, 6f
    nop
    sw    $27, {gp1}($26)
6:
    lui   $27, {ack_irq_hi}
    sw    $27, {gp1}($26)
    lui   $27, {dma_dir_hi}
    ori   $27, $27, {dma_dir_lo}
    sw    $27, {gp1}($26)
    lw    $27, {dpcr}($26)
    nop
    ori   $27, $27, {gpu_dpcr_enable}
    sw    $27, {dpcr}($26)
    lui   $27, %hi(__psx_rt_present_head)
    lw    $27, %lo(__psx_rt_present_head)($27)
    nop
    sw    $27, {gpu_madr}($26)
    sw    $zero, {gpu_bcr}($26)
    lui   $27, {chcr_hi}
    ori   $27, $27, {chcr_lo}
    sw    $27, {gpu_chcr}($26)
    lui   $26, %hi(__psx_rt_present_head)
    sw    $zero, %lo(__psx_rt_present_head)($26)
    lui   $26, %hi(__psx_rt_present_kick_count)
    lw    $27, %lo(__psx_rt_present_kick_count)($26)
    nop
    addiu $27, $27, 1
    b     8f
    sw    $27, %lo(__psx_rt_present_kick_count)($26)
7:
    lui   $26, %hi(__psx_rt_present_skip_count)
    lw    $27, %lo(__psx_rt_present_skip_count)($26)
    nop
    addiu $27, $27, 1
    sw    $27, %lo(__psx_rt_present_skip_count)($26)
8:
    .endif

    # Apply one queued GP1 word exactly at the blank edge (deferred display
    # flip). Zero means no request; a display-start word is never zero.
    # Only apply once GPUSTAT bit 24 is set: the frame's work ends with
    # GP0(1Fh), which sets it when the GPU reaches it, i.e. when everything
    # before it has been drawn, and the game acknowledged the flag with
    # GP1(02h) when it kicked that work. Until then the word stays queued for
    # a later edge, so a flip never exposes a partial buffer and the CPU never
    # blocks on the GPU. Bit 28 is not a drawing-complete test: on silicon it
    # rises when the DMA has pushed the last packet, about one large
    # primitive before the drawing ends (hardware-tests v1.24 cases 219-226);
    # the v1.24 present probe flipped on bit 24 with 120 of 120 frames right.
    lui   $26, %hi(__psx_rt_pending_gp1)
    lw    $27, %lo(__psx_rt_pending_gp1)($26)
    nop
    beqz  $27, 2f
    nop
    lui   $26, {io_hi}
    lw    $26, {gp1}($26)
    nop
    srl   $26, $26, {gpustat_irq1_shift}
    andi  $26, $26, 1
    beqz  $26, 2f
    nop
    lui   $26, %hi(__psx_rt_pending_gp1)
    sw    $zero, %lo(__psx_rt_pending_gp1)($26)
    lui   $26, {io_hi}
    sw    $27, {gp1}($26)

2:
    lui   $26, {io_hi}
    addiu $27, $zero, {ack_vblank}
    sw    $27, {i_stat}($26)

1:
    mfc0  $27, $13
    nop
    andi  $27, $27, 0x007c
    beqz  $27, 2f
    nop

    # Preserve a compact unexpected-exception signature before deciding
    # whether this fault is recoverable. Immediate-abort panics compile to
    # BREAK, so Cause + EPC are the only reliable shipping diagnostics.
    lui   $26, %hi(__psx_rt_fault_cause)
    mfc0  $27, $13
    nop
    sw    $27, %lo(__psx_rt_fault_cause)($26)
    lui   $26, %hi(__psx_rt_fault_epc)
    mfc0  $27, $14
    nop
    sw    $27, %lo(__psx_rt_fault_epc)($26)
    lui   $26, %hi(__psx_rt_fault_badvaddr)
    mfc0  $27, $8
    nop
    sw    $27, %lo(__psx_rt_fault_badvaddr)($26)

    lui   $26, %hi(__psx_rt_fault_count)
    lw    $27, %lo(__psx_rt_fault_count)($26)
    nop
    addiu $27, $27, 1
    sw    $27, %lo(__psx_rt_fault_count)($26)

    # Never advance EPC for fatal instruction-side faults. BREAK (ExcCode 9,
    # 0x24) marks panic=immediate-abort; IBE (ExcCode 6, 0x18) cannot become
    # executable by skipping one word. For AdEL (ExcCode 4, 0x10), halt only
    # when BadVAddr == EPC, which identifies a misaligned instruction fetch;
    # retain the historical skip-and-count policy for data-side AdEL.
    mfc0  $27, $13
    nop
    andi  $27, $27, 0x007c
    addiu $26, $zero, 0x0024
    beq   $27, $26, 3f
    nop
    addiu $26, $zero, 0x0018
    beq   $27, $26, 3f
    nop
    addiu $26, $zero, 0x0010
    bne   $27, $26, 4f
    nop
    mfc0  $26, $8
    mfc0  $27, $14
    nop
    beq   $26, $27, 3f
    nop

    # Step over the faulting instruction: resume at EPC + 4. Not with
    # Cause.BD set: then it sat in the delay slot of the branch at EPC, and
    # EPC + 4 would re-run it as if the branch had fallen through. Resuming
    # correctly means evaluating that branch, which costs every game code
    # for a path only a bug reaches, so halt on it like a fatal fault, with
    # Cause, EPC and BadVAddr recorded. With the `strict-faults` feature
    # nothing is stepped over: every fault halts here. `fault_resume_pc`
    # below is the same decision in Rust, unit-tested on host.
4:
    .if {strict}
    b     3f
    nop
    .endif
    mfc0  $27, $13
    mfc0  $26, $14
    nop
    bltz  $27, 3f
    nop
    addiu $26, $26, 4
    jr    $26
    .word {rfe}

    # Interrupt return: EPC, or EPC + 4 when the word at EPC is a GTE
    # command (top seven bits 0100101). An interrupt taken on a GTE command
    # lets the command run and still leaves EPC on it, so returning to EPC
    # runs it a second time (hardware-tests v1.24 on silicon: case 0xC9,
    # 38 of 38 such interrupts ran an RTPS twice; with this step, case 0xCB,
    # 61 skips, none doubled or lost). This is psx-spx's fix and the Sony
    # kernel's. With Cause.BD set EPC holds the branch, never a GTE command,
    # so a GTE command in a delay slot is not stepped over and does run twice:
    # psx-spx's answer is to keep GTE commands out of delay slots, and
    # hazard-scan warns about any it finds. `interrupt_resume_pc`
    # below is the same decision in Rust, unit-tested on host.
2:
    mfc0  $26, $14
    nop
    lw    $27, 0($26)
    nop
    srl   $27, $27, {gte_prefix_shift}
    xori  $27, $27, {gte_prefix}
    bnez  $27, 5f
    nop
    lui   $27, %hi(__psx_rt_gte_skip_count)
    lw    $26, %lo(__psx_rt_gte_skip_count)($27)
    nop
    addiu $26, $26, 1
    sw    $26, %lo(__psx_rt_gte_skip_count)($27)
    mfc0  $26, $14
    nop
    addiu $26, $26, 4
5:
    jr    $26
    .word {rfe}
3:
    b     3b
    nop

    # No VBlank pending. An interrupt (ExcCode 0) with an enabled source
    # pending here is one nothing in this handler owns, and returning without
    # acknowledging it re-enters at once, forever. Record it, acknowledge it
    # (writing a 0 to an I_STAT bit clears it, a 1 leaves it) and count it,
    # then go on to the common return. Not done when VBlank is pending too:
    # a game's own handler chains here for VBlank, and a source it services
    # itself must stay in I_STAT until it does. `stray_interrupt_sources`
    # below is the same decision in Rust, unit-tested on host.
9:
    mfc0  $27, $13
    nop
    andi  $27, $27, 0x007c
    bnez  $27, 1b
    nop
    lui   $26, {io_hi}
    lw    $27, {i_stat}($26)
    lw    $26, {i_mask}($26)
    nop
    and   $27, $27, $26
    beqz  $27, 1b
    nop
    lui   $26, %hi(__psx_rt_stray_irq_last)
    sw    $27, %lo(__psx_rt_stray_irq_last)($26)
    nor   $27, $27, $zero
    lui   $26, {io_hi}
    sw    $27, {i_stat}($26)
    lui   $26, %hi(__psx_rt_stray_irq_count)
    lw    $27, %lo(__psx_rt_stray_irq_count)($26)
    nop
    addiu $27, $27, 1
    b     1b
    sw    $27, %lo(__psx_rt_stray_irq_count)($26)
    .set reorder
    "#,
    strict = const STRICT_FAULTS as u32,
    present = const PRESENT_QUEUE as u32,
    // Every register the handler touches is in the I/O window, so one `lui`
    // of the window's high half reaches them all and the offsets are the low
    // halves (checked by the assertions below the block).
    io_hi = const memory::io::BASE >> 16,
    i_stat = const psx_hw::irq::I_STAT & 0xFFFF,
    i_mask = const psx_hw::irq::I_MASK & 0xFFFF,
    vblank_mask = const 1u32 << psx_hw::irq::source::VBLANK,
    ack_vblank = const !(1u32 << psx_hw::irq::source::VBLANK) as i32,
    gp1 = const gpu::GP1 & 0xFFFF,
    gpustat_irq1_shift = const gpu::GpuStat::IRQ1.bits().trailing_zeros(),
    ack_irq_hi = const gpu::gp1::ACK_IRQ >> 16,
    dma_dir_hi = const gpu::gp1::dma_direction(gpu::DmaDirection::CpuToGp0 as u32) >> 16,
    dma_dir_lo = const gpu::gp1::dma_direction(gpu::DmaDirection::CpuToGp0 as u32) & 0xFFFF,
    gpu_madr = const (dma::CHANNEL_BASE + dma::CHANNEL_STRIDE * dma::channel::GPU + dma::MADR) & 0xFFFF,
    gpu_bcr = const (dma::CHANNEL_BASE + dma::CHANNEL_STRIDE * dma::channel::GPU + dma::BCR) & 0xFFFF,
    gpu_chcr = const (dma::CHANNEL_BASE + dma::CHANNEL_STRIDE * dma::channel::GPU + dma::CHCR) & 0xFFFF,
    chcr_start_shift = const dma::CHCR_START.trailing_zeros(),
    chcr_hi = const dma::CHCR_LINKED_LIST_TO_DEVICE >> 16,
    chcr_lo = const dma::CHCR_LINKED_LIST_TO_DEVICE & 0xFFFF,
    dpcr = const dma::DPCR & 0xFFFF,
    gpu_dpcr_enable = const dma::dpcr_enable(dma::channel::GPU),
    rfe = const cop0::RFE,
    gte_prefix_shift = const gte::PREFIX_SHIFT,
    gte_prefix = const gte::COMMAND >> gte::PREFIX_SHIFT,
);
// The handler reaches every register through one `lui` of the I/O window's
// high half plus a signed 16-bit offset, and builds its GP1 and CHCR words
// from immediates; check each the way the template spells them.
#[cfg(target_arch = "mips")]
const _: () = {
    let window = memory::io::BASE >> 16;
    assert!(psx_hw::irq::I_STAT >> 16 == window && psx_hw::irq::I_MASK >> 16 == window);
    assert!(gpu::GP1 >> 16 == window && dma::DPCR >> 16 == window);
    let gpu_block = dma::CHANNEL_BASE + dma::CHANNEL_STRIDE * dma::channel::GPU;
    assert!(gpu_block >> 16 == window && (gpu_block + dma::CHCR) & 0xFFFF < 0x8000);
    // `lui` of a GP1 word with an empty low half.
    assert!(gpu::gp1::ACK_IRQ & 0xFFFF == 0);
    // `ori` takes an unsigned 16-bit immediate.
    assert!(dma::dpcr_enable(dma::channel::GPU) <= 0xFFFF);
};

/// True when psx-rt was built with the `present-queue` feature: the VBlank
/// handler kicks frames published through [`crate::present`].
pub const PRESENT_QUEUE: bool = cfg!(feature = "present-queue");

/// Present-queue slot: the chain head the VBlank handler kicks at the next
/// ready edge, 0 when empty. Owned by [`crate::present`].
#[cfg(feature = "present-queue")]
#[no_mangle]
pub(crate) static mut __psx_rt_present_head: u32 = 0;

/// GP1(05h) word the handler writes just before kicking the slot's chain;
/// 0 = no flip.
#[cfg(feature = "present-queue")]
#[no_mangle]
pub(crate) static mut __psx_rt_present_display: u32 = 0;

/// Chains the handler has kicked.
#[cfg(feature = "present-queue")]
#[no_mangle]
pub(crate) static mut __psx_rt_present_kick_count: u32 = 0;

/// Edges on which a published chain found the previous one undrawn or DMA
/// channel 2 still busy.
#[cfg(feature = "present-queue")]
#[no_mangle]
pub(crate) static mut __psx_rt_present_skip_count: u32 = 0;

/// True when psx-rt was built with the `strict-faults` feature: the
/// exception handler halts on every fault instead of stepping over the
/// faulting instruction (see [`fault_resume_pc`]).
pub const STRICT_FAULTS: bool = cfg!(feature = "strict-faults");

/// Monotonic VBlank IRQ count.
#[no_mangle]
static mut __psx_rt_vblank_count: u32 = 0;

/// Count of exceptions that were NOT interrupts: bus errors, address
/// errors, reserved instructions.
///
/// The handler used to return straight to EPC for these, which
/// re-executes the faulting instruction and loops forever: a silent
/// freeze with no diagnostic, indistinguishable from a hung spin. It now
/// steps over the faulting instruction and counts it here, so a bad
/// access costs one wrong value instead of the whole program, and the
/// count says it happened. Fatal instruction-side faults are deliberately
/// different: BREAK is the shipping representation of
/// `panic=immediate-abort`, while IBE and instruction-side AdEL cannot be
/// repaired by skipping one word. The handler records Cause/EPC and halts for
/// all three instead of entering unreachable or non-executable code. It also
/// halts on any fault in a branch delay slot, where skipping one word would
/// drop the branch (see [`fault_resume_pc`]).
///
/// Stepping over hides bugs: a misaligned store that is skipped leaves the
/// program running on a wrong value, and only this count says so (one such
/// store in WipEout drew wrong geometry in one build and, landing in a delay
/// slot, hung another). Build development and test discs with the
/// `strict-faults` feature to halt on the first fault instead.
#[no_mangle]
static mut __psx_rt_fault_count: u32 = 0;

/// Interrupts the handler returned from at EPC + 4 because the word at EPC
/// was a GTE command (see [`interrupt_resume_pc`]).
#[no_mangle]
static mut __psx_rt_gte_skip_count: u32 = 0;

/// Raw COP0 Cause captured for the latest unexpected exception.
#[no_mangle]
static mut __psx_rt_fault_cause: u32 = 0;

/// COP0 EPC captured for the latest unexpected exception.
#[no_mangle]
static mut __psx_rt_fault_epc: u32 = 0;

/// COP0 BadVAddr captured for the latest unexpected exception. Only
/// meaningful for an address error; other faults leave a stale value in the
/// register.
#[no_mangle]
static mut __psx_rt_fault_badvaddr: u32 = 0;

/// One queued GP1 word the VBlank handler writes to the GPU at the first
/// blank edge on which GPUSTAT bit 24 is set, then clears. Zero = empty.
/// Written by [`queue_display_control_at_vblank`].
#[no_mangle]
static mut __psx_rt_pending_gp1: u32 = 0;

/// Interrupts other than VBlank the handler acknowledged because nothing
/// owned them (see [`stray_interrupt_sources`]).
#[no_mangle]
static mut __psx_rt_stray_irq_count: u32 = 0;

/// The `I_STAT & I_MASK` sources of the latest stray interrupt.
#[no_mangle]
static mut __psx_rt_stray_irq_last: u32 = 0;

/// Stray interrupts acknowledged so far. psx-rt's handler owns VBlank only;
/// any other source enabled in `I_MASK` that fires while no VBlank is
/// pending, and that no handler in front of this one claimed, is
/// acknowledged and counted here instead of re-entering forever. Non-zero
/// means something enabled a source nothing services.
#[inline]
pub fn stray_interrupt_count() -> u32 {
    // SAFETY: a volatile aligned u32 read through a raw pointer, so no reference is formed. Only
    // the asm exception handler writes it, and an aligned word load cannot tear.
    unsafe { core::ptr::read_volatile(&raw const __psx_rt_stray_irq_count) }
}

/// The `I_STAT & I_MASK` bits of the latest stray interrupt
/// ([`stray_interrupt_count`]); zero before the first.
#[inline]
pub fn last_stray_interrupt_sources() -> u32 {
    // SAFETY: a volatile aligned u32 read through a raw pointer, so no reference is formed. Only
    // the asm exception handler writes it, and an aligned word load cannot tear.
    unsafe { core::ptr::read_volatile(&raw const __psx_rt_stray_irq_last) }
}

/// The sources psx-rt's handler acknowledges as strays for one entry, given
/// `I_STAT`, `I_MASK` and COP0 Cause; zero when it leaves them alone.
///
/// It acts only on an interrupt (Cause.ExcCode 0) with no VBlank pending: a
/// pending VBlank means a game's own handler may have chained here with a
/// source of its own still waiting for it, which must stay in `I_STAT`. The
/// handler's assembly makes exactly this decision.
pub const fn stray_interrupt_sources(status: u32, mask: u32, cause: u32) -> u32 {
    let pending = status & mask;
    let is_interrupt = (cause >> 2) & 0x1F == 0;
    if is_interrupt && pending & (1 << psx_hw::irq::source::VBLANK) == 0 {
        pending
    } else {
        0
    }
}

/// Set once [`install_vblank_counter`] has run, so [`wait_vblank`] can
/// install lazily without resetting a counter the game is already using.
#[cfg(target_arch = "mips")]
static mut INSTALLED: bool = false;

/// The first word of the exception vector as `_start` found it, before any
/// game code ran: the BIOS's own, or whatever a previous program left.
#[cfg(target_arch = "mips")]
static mut BOOT_VECTOR_WORD: u32 = 0;

/// Set once `_start` has stored [`BOOT_VECTOR_WORD`].
#[cfg(target_arch = "mips")]
static mut BOOT_VECTOR_RECORDED: bool = false;

/// Remember the vector word as the program found it. Called once from
/// `_start`, after `.bss` is zeroed and before `main`.
#[cfg(target_arch = "mips")]
pub(crate) fn record_boot_vector() {
    // SAFETY: two private statics written once at boot, before `main` and before any code that
    // reads them runs; volatile aligned stores through raw pointers.
    unsafe {
        core::ptr::write_volatile(&raw mut BOOT_VECTOR_WORD, vector_word());
        core::ptr::write_volatile(&raw mut BOOT_VECTOR_RECORDED, true);
    }
}

/// Whether [`wait_vblank`] may install psx-rt's handler on first use.
///
/// It may when the vector still holds what the program booted with (nobody
/// has taken it) or already jumps to psx-rt's handler. A different word
/// means the game put its own handler there (hk-psx and cs-psx wrap psx-rt's
/// to service CD interrupts), and a safe wait must not overwrite it. An
/// entry that never recorded the boot word keeps the old rule: install.
#[cfg(any(target_arch = "mips", test))]
const fn may_install_lazily(boot_word: Option<u32>, vector: u32, handler_jump: u32) -> bool {
    match boot_word {
        None => true,
        Some(boot) => vector == boot || vector == handler_jump,
    }
}

#[cfg(target_arch = "mips")]
extern "C" {
    fn __psx_rt_exception_handler();
}

/// Install and enable the VBlank counter interrupt path.
///
/// This writes a branch into the MIPS general exception vector,
/// enables the VBlank source in `I_MASK`, and sets the COP0 interrupt
/// enable bits used by the R3000A. The operation is idempotent for
/// the current runtime: reinstalling simply resets the software
/// counter and refreshes the vector.
///
/// The handler owns VBlank only. Another source enabled in `I_MASK` that
/// fires while no VBlank is pending is acknowledged and counted
/// ([`stray_interrupt_count`]) rather than re-entering forever, so a source a
/// game needs must be serviced by the game's own handler ahead of this one
/// (which then chains here), not left to this handler.
#[cfg(target_arch = "mips")]
pub fn install_vblank_counter() {
    const EXCEPTION_VECTOR: *mut u32 = 0x8000_0080 as *mut u32;
    const J_OPCODE: u32 = 0x0800_0000;

    // SAFETY: 0x8000_0080 is the R3000 general exception vector in KSEG0 kernel RAM, two aligned
    // words written here as `j handler` plus a nop delay slot, then the I-cache is flushed so the
    // CPU fetches them. The counter and INSTALLED are psx-rt-private statics written through raw
    // pointers, so no reference aliases them. `enable_cpu_interrupts` runs only after the vector
    // points at psx-rt's handler. Assumes nothing still depends on the vector this replaces (a game
    // wrapper installed earlier is overwritten).
    unsafe {
        let handler = __psx_rt_exception_handler as *const () as usize as u32;
        core::ptr::write_volatile(EXCEPTION_VECTOR, J_OPCODE | ((handler >> 2) & 0x03ff_ffff));
        core::ptr::write_volatile(EXCEPTION_VECTOR.add(1), 0);
        crate::cache::flush_instruction_cache();

        core::ptr::write_volatile(&raw mut __psx_rt_vblank_count, 0);
        irq::acknowledge(1 << psx_hw::irq::source::VBLANK);
        // This handler services VBlank only. After a BIOS disc boot, do not
        // preserve CD-ROM/DMA/etc. bits the BIOS may have left enabled.
        irq::set_mask(1 << psx_hw::irq::source::VBLANK);
        enable_cpu_interrupts();
        core::ptr::write_volatile(&raw mut INSTALLED, true);
    }
}

/// Install and enable the VBlank counter interrupt path.
#[cfg(not(target_arch = "mips"))]
pub fn install_vblank_counter() {}

/// Unexpected exceptions survived so far. Non-zero means some access
/// faulted and was stepped over; the value it read or wrote is garbage.
#[inline]
pub fn fault_count() -> u32 {
    // SAFETY: a volatile aligned u32 read through a raw pointer, so no reference is formed. Only
    // the asm exception handler writes it, and an aligned word load cannot tear.
    unsafe { core::ptr::read_volatile(&raw const __psx_rt_fault_count) }
}

/// Interrupts that landed on a GTE command, whose return the handler moved
/// to EPC + 4 so the command did not run twice.
#[inline]
pub fn gte_skip_count() -> u32 {
    // SAFETY: a volatile aligned u32 read through a raw pointer, so no reference is formed. Only
    // the asm exception handler writes it, and an aligned word load cannot tear.
    unsafe { core::ptr::read_volatile(&raw const __psx_rt_gte_skip_count) }
}

/// True when `word` is a GTE command (a COP2 `cofun`: opcode 0x12 with bit
/// 25 set, so the top seven bits are `0100101`). psx-spx's test is
/// `(word & 0xFE00_0000) == 0x4A00_0000`. GTE register moves (`mfc2`,
/// `mtc2`, `cfc2`, `ctc2`), `lwc2`/`swc2` and the `bc2` branches are not
/// commands: an interrupt on them is taken before they run.
#[inline]
pub const fn is_gte_command(word: u32) -> bool {
    psx_hw::gte::is_command(word)
}

/// Where psx-rt's exception handler resumes after an interrupt: `epc`, or
/// `epc + 4` when `word_at_epc` is a GTE command.
///
/// On silicon an interrupt taken on a GTE command lets the command run and
/// still reports EPC at it, so resuming at EPC runs it twice
/// (hardware-tests v1.24, case 0xC9: 38 of 38; with this rule, case 0xCB:
/// 61 skips, none doubled or lost). The handler's assembly makes exactly
/// this decision.
///
/// With Cause.BD set, EPC is the branch whose delay slot was interrupted,
/// so `word_at_epc` is a branch and the result is `epc`: the branch and a
/// GTE command in its delay slot both run again. psx-spx documents that
/// the fix cannot cover delay slots; keep GTE commands out of them
/// (`hazard-scan` warns about any in an image).
#[inline]
pub const fn interrupt_resume_pc(epc: u32, word_at_epc: u32) -> u32 {
    if is_gte_command(word_at_epc) {
        epc.wrapping_add(4)
    } else {
        epc
    }
}

/// Where psx-rt's exception handler resumes after a fault (any exception
/// but an interrupt), or `None` where it halts. `badvaddr` is COP0
/// BadVAddr.
///
/// BREAK (the shipping form of `panic=immediate-abort`), an instruction bus
/// error and a misaligned instruction fetch (AdEL with BadVAddr == EPC)
/// halt. So does any fault with [`psx_hw::cop0::CAUSE_BD`] set: the faulting instruction
/// sat in the delay slot of the branch at EPC, which has already run, so
/// `epc + 4` would run the faulting instruction again as if the branch had
/// fallen through, and resuming where the branch goes would take decoding
/// it, handler code every game carries for a path only a bug reaches.
/// Every other fault is stepped over (`epc + 4`) and counted, unless
/// [`STRICT_FAULTS`] is set, in which case every fault halts. The
/// handler's assembly makes exactly this decision; before halting it
/// records Cause, EPC and BadVAddr ([`fault_cause`], [`fault_pc`],
/// [`fault_bad_address`]).
pub const fn fault_resume_pc(cause: u32, epc: u32, badvaddr: u32) -> Option<u32> {
    resume_after_fault(STRICT_FAULTS, cause, epc, badvaddr)
}

/// [`fault_resume_pc`] for either policy, so host tests cover both.
const fn resume_after_fault(strict: bool, cause: u32, epc: u32, badvaddr: u32) -> Option<u32> {
    if strict {
        return None;
    }
    match (cause >> 2) & 0x1F {
        // Break, IBE
        9 | 6 => return None,
        // AdEL on the fetch itself
        4 if badvaddr == epc => return None,
        _ => {}
    }
    if cause & psx_hw::cop0::CAUSE_BD != 0 {
        None
    } else {
        Some(epc.wrapping_add(4))
    }
}

/// COP0 BadVAddr captured for the latest unexpected exception.
#[inline]
#[doc(alias = "BadVAddr")]
pub fn fault_bad_address() -> u32 {
    // SAFETY: a volatile aligned u32 read through a raw pointer, so no reference is formed. Only
    // the asm exception handler writes it, and an aligned word load cannot tear.
    unsafe { core::ptr::read_volatile(&raw const __psx_rt_fault_badvaddr) }
}

/// Raw COP0 Cause captured for the latest unexpected exception.
#[inline]
pub fn fault_cause() -> u32 {
    // SAFETY: a volatile aligned u32 read through a raw pointer, so no reference is formed. Only
    // the asm exception handler writes it, and an aligned word load cannot tear.
    unsafe { core::ptr::read_volatile(&raw const __psx_rt_fault_cause) }
}

/// COP0 EPC captured for the latest unexpected exception.
#[inline]
#[doc(alias = "EPC")]
pub fn fault_pc() -> u32 {
    // SAFETY: a volatile aligned u32 read through a raw pointer, so no reference is formed. Only
    // the asm exception handler writes it, and an aligned word load cannot tear.
    unsafe { core::ptr::read_volatile(&raw const __psx_rt_fault_epc) }
}

/// Current monotonic VBlank count.
#[inline]
#[doc(alias = "VSync")]
pub fn vblank_count() -> u32 {
    // SAFETY: a volatile aligned u32 read through a raw pointer, so no reference is formed. The
    // asm handler and `install_vblank_counter` are the only writers, and an aligned word load
    // cannot tear.
    unsafe { core::ptr::read_volatile(&raw const __psx_rt_vblank_count) }
}

/// Queue one GP1 word for the VBlank handler to apply at a blank edge
/// (deferred tear-free display flip). Overwrites any unapplied word.
///
/// The handler applies the word at the first VBlank edge on which GPUSTAT
/// bit 24 (the GPU's IRQ1 flag) is set, so the frame must signal its own
/// end:
///
/// 1. acknowledge the flag with GP1(02h) before kicking the frame's work
///    (`psx_gpu::arm_draw_done`), after the previous flip has landed;
/// 2. end that work with GP0(1Fh): as the last node of the DMA chain
///    (`psx_gpu::OrderingTable::end_with_draw_done`, or a one-word packet
///    in an ordered stream) or, after drawing through the ports,
///    `psx_gpu::signal_draw_done`;
/// 3. queue the display-start word here.
///
/// The flag stays set until the next acknowledge, so a word queued while
/// the GPU is idle after such a frame (a display enable, say) applies at
/// the next edge. A game that never sends GP0(1Fh) never flips: before this
/// handler tested bit 24 it tested GPUSTAT bit 28, which on silicon rises
/// about one large primitive before the drawing ends (hardware-tests v1.24
/// cases 219-226), so a flip could expose a frame one primitive short.
/// Keep interrupt source 1 (GPU) masked in `I_MASK`: this handler owns VBlank
/// only, so a GPU interrupt it finds is acknowledged as a stray and counted
/// ([`stray_interrupt_count`]), which costs a handler entry per frame.
#[cfg(target_arch = "mips")]
#[inline]
#[doc(alias = "GP1")]
pub fn queue_display_control_at_vblank(word: u32) {
    // SAFETY: a volatile aligned u32 store through a raw pointer, so no reference is formed. The
    // VBlank handler is the only other accessor, and an aligned word store cannot tear.
    unsafe { core::ptr::write_volatile(&raw mut __psx_rt_pending_gp1, word) }
}

/// Host no-op: no IRQ exists to consume the queue off-target.
#[cfg(not(target_arch = "mips"))]
#[inline]
#[doc(alias = "GP1")]
pub fn queue_display_control_at_vblank(_word: u32) {}

/// Renamed to [`queue_display_control_at_vblank`].
#[deprecated(note = "renamed to `queue_display_control_at_vblank`")]
#[inline(always)]
pub fn queue_gp1_at_vblank(word: u32) {
    queue_display_control_at_vblank(word)
}

/// True while a word queued by [`queue_display_control_at_vblank`] has not
/// yet been applied by the VBlank handler.
#[cfg(target_arch = "mips")]
#[inline]
#[doc(alias = "GP1")]
pub fn is_display_control_queued() -> bool {
    // SAFETY: a volatile aligned u32 read through a raw pointer, so no reference is formed. The
    // VBlank handler is the only other accessor, and an aligned word load cannot tear.
    unsafe { core::ptr::read_volatile(&raw const __psx_rt_pending_gp1) != 0 }
}

/// Empty the queue and hand back the word the handler has not applied, so
/// the caller can write it to GP1 itself. Returns 0 when nothing was queued.
///
/// The handler only applies its word at a blank edge on which GPUSTAT
/// bit 24 is set (see [`queue_display_control_at_vblank`]), so a long enough frame, or
/// one that never sends GP0(1Fh), leaves it queued indefinitely. A caller that has given up waiting must take the word
/// rather than leave it: the next [`queue_display_control_at_vblank`] overwrites the
/// slot, and a display start that never reaches the GPU desynchronises the
/// display side from the draw side for the rest of the session.
///
/// Racing the handler is harmless. If the IRQ lands between the read and
/// the clear, the handler applies the word and the caller writes the same
/// value again; GP1(05h) is idempotent.
#[cfg(target_arch = "mips")]
#[inline]
#[doc(alias = "GP1")]
pub fn take_queued_display_control() -> u32 {
    // SAFETY: volatile aligned u32 accesses through a raw pointer, so no reference is formed. A
    // handler run between the read and the clear is harmless (see above).
    unsafe {
        let word = core::ptr::read_volatile(&raw const __psx_rt_pending_gp1);
        if word != 0 {
            core::ptr::write_volatile(&raw mut __psx_rt_pending_gp1, 0);
        }
        word
    }
}

/// Host: nothing is ever queued, so nothing can be taken.
#[cfg(not(target_arch = "mips"))]
#[inline]
#[doc(alias = "GP1")]
pub fn take_queued_display_control() -> u32 {
    0
}

/// Renamed to [`take_queued_display_control`].
#[deprecated(note = "renamed to `take_queued_display_control`")]
#[inline(always)]
pub fn take_pending_gp1() -> u32 {
    take_queued_display_control()
}

/// Host no-op: nothing is ever pending off-target.
#[cfg(not(target_arch = "mips"))]
#[inline]
#[doc(alias = "GP1")]
pub fn is_display_control_queued() -> bool {
    false
}

/// Renamed to [`is_display_control_queued`].
#[deprecated(note = "renamed to `is_display_control_queued`")]
#[inline(always)]
pub fn gp1_queue_pending() -> bool {
    is_display_control_queued()
}

/// Block until the next VBlank IRQ.
///
/// This is the display-sync primitive: a frame that finishes early sleeps
/// until the blank, and a slow frame snaps to the next one, so presentation
/// quantizes to whole display periods. (`psx_gpu::vsync()` cannot do this:
/// it reconfigures Timer 1 on every call, and a mode write resets the
/// counter, so it busy-waits a fixed 242 HBlanks from the call site
/// instead of syncing to the display.)
///
/// Installs the VBlank counter on first use if the game has not already
/// called [`install_vblank_counter`], but only while the exception vector is
/// still the one the program booted with. A game that has put its own
/// handler there keeps it: this function never overwrites it. Such a game
/// calls [`install_vblank_counter`] first and then wraps psx-rt's handler,
/// or its handler chains to psx-rt's, which is what advances the count this
/// waits on. The wait is bounded: after about four million reads
/// without the count moving it returns (and asserts in a debug build) instead
/// of hanging, as it would inside a critical section or without the handler.
/// [`try_wait_vblank`] takes the bound.
#[cfg(target_arch = "mips")]
#[doc(alias = "VSync")]
pub fn wait_vblank() {
    // SAFETY: volatile reads of private flags through raw pointers; only `install_vblank_counter`
    // and `record_boot_vector` write them, on this same single thread.
    unsafe {
        if !core::ptr::read_volatile(&raw const INSTALLED) {
            let boot = core::ptr::read_volatile(&raw const BOOT_VECTOR_RECORDED)
                .then(|| core::ptr::read_volatile(&raw const BOOT_VECTOR_WORD));
            let handler = __psx_rt_exception_handler as *const () as usize as u32;
            if may_install_lazily(boot, vector_word(), jump_word(handler)) {
                install_vblank_counter();
            }
        }
    }
    if !try_wait_vblank(crate::wait::SPIN_LIMIT) {
        debug_assert!(
            false,
            "wait_vblank: the VBlank count never advanced; psx-rt's handler is not running"
        );
    }
}

/// [`wait_vblank`] with its own bound: `true` once the count has advanced,
/// `false` after `spins` reads of it without a change. A `false` means no
/// VBlank interrupt reached psx-rt's handler: interrupts are masked (inside a
/// [`critical_section`](crate::critical_section)), the counter was never
/// installed, or a game's handler does not chain to psx-rt's. Does not
/// install the counter; [`wait_vblank`] does that first.
#[cfg(target_arch = "mips")]
pub fn try_wait_vblank(spins: u32) -> bool {
    let start = vblank_count();
    crate::wait::wait_while(|| vblank_count() == start, || false, || {}, spins)
}

/// Block until the next VBlank IRQ. Host no-op: the counter never
/// advances off-target, so waiting would hang.
#[cfg(not(target_arch = "mips"))]
#[doc(alias = "VSync")]
pub fn wait_vblank() {}

/// True when the general exception vector jumps to psx-rt's handler, the
/// one that never touches `$sp` (so interrupts are safe on any stack).
#[cfg(target_arch = "mips")]
pub fn is_handler_installed() -> bool {
    let handler = __psx_rt_exception_handler as *const () as usize as u32;
    vector_word() == jump_word(handler)
}

/// The vector word of a game's exception handler declared with
/// [`declare_stack_safe_handler`]; zero when none is.
#[cfg(target_arch = "mips")]
static mut STACK_SAFE_HANDLER: u32 = 0;

/// Declare that the game's own exception handler at `handler` is safe to
/// take an interrupt on any stack, including a
/// [`ScratchpadStack`](crate::scratchpad::ScratchpadStack).
///
/// With the `scratchpad-stack-check` feature, a stack switch traps when
/// interrupts are on and the general exception vector jumps anywhere but
/// psx-rt's handler, because a handler that pushes onto the interrupted
/// stack would write below the scratchpad stack's frames. A game that
/// installs its own vector (hk-psx wraps psx-rt's handler to service CD
/// interrupts, then jumps to it) calls this once with the address it puts
/// in the vector; the check then accepts exactly that vector word, and
/// still traps any other handler, such as a BIOS vector restored behind the
/// game's back. Declaring does not install anything.
///
/// ```no_run
/// unsafe extern "C" fn game_exception_wrapper() {}
/// // SAFETY: game_exception_wrapper switches to its own stack before it
/// // stores anything and restores $sp before it hands back.
/// unsafe { psx_rt::interrupts::declare_stack_safe_handler(game_exception_wrapper) };
/// ```
///
/// # Safety
///
/// `handler`, and everything it calls or jumps to, must leave `$sp` and the
/// memory below it alone: it uses only `$k0`/`$k1` or saves state to memory
/// of its own and runs on a stack of its own, and it returns (or chains to
/// psx-rt's handler) with `$sp` unchanged.
#[cfg(target_arch = "mips")]
pub unsafe fn declare_stack_safe_handler(handler: unsafe extern "C" fn()) {
    // SAFETY: a plain store; nothing reads it from an interrupt.
    unsafe {
        core::ptr::write_volatile(
            &raw mut STACK_SAFE_HANDLER,
            jump_word(handler as *const () as usize as u32),
        )
    }
}

/// Declare a stack-safe exception handler. Host no-op: there are no
/// exception vectors off-target.
///
/// # Safety
///
/// As on the target.
#[cfg(not(target_arch = "mips"))]
pub unsafe fn declare_stack_safe_handler(_handler: unsafe extern "C" fn()) {}

/// True when the general exception vector jumps to psx-rt's handler or to
/// the one declared with [`declare_stack_safe_handler`].
#[cfg(target_arch = "mips")]
pub fn is_stack_safe_handler_installed() -> bool {
    // SAFETY: a plain read of a word only this module writes.
    let declared = unsafe { core::ptr::read_volatile(&raw const STACK_SAFE_HANDLER) };
    is_handler_installed() || (declared != 0 && vector_word() == declared)
}

/// The `j handler` word psx-rt writes into the vector.
#[cfg(target_arch = "mips")]
fn jump_word(handler: u32) -> u32 {
    0x0800_0000 | ((handler >> 2) & 0x03ff_ffff)
}

/// The first word of the general exception vector.
#[cfg(target_arch = "mips")]
fn vector_word() -> u32 {
    const EXCEPTION_VECTOR: *const u32 = 0x8000_0080 as *const u32;
    // SAFETY: a read of the kernel's vector word.
    unsafe { core::ptr::read_volatile(EXCEPTION_VECTOR) }
}

/// True when COP0 SR has interrupts enabled (IEc).
#[cfg(target_arch = "mips")]
pub fn are_interrupts_enabled() -> bool {
    let sr: u32;
    // The nop covers MFC0's load delay.
    // SAFETY: reads COP0 SR into $8, declared as the output, and the nop covers MFC0's load delay.
    // No memory or stack is touched, as the options state.
    unsafe { core::arch::asm!("mfc0 $8, $12", "nop", lateout("$8") sr, options(nomem, nostack)) };
    sr & 1 != 0
}

#[cfg(target_arch = "mips")]
unsafe fn enable_cpu_interrupts() {
    const STATUS_IE: u32 = 1 << 0;
    const STATUS_IM2: u32 = 1 << 10;
    const STATUS_CU2: u32 = 1 << 30;

    let mut sr: u32;
    // MFC0 has a one-instruction load-delay hazard on the R3000: without the
    // nop the asm block hands back the STALE $8, and whatever garbage it held
    // gets OR'd into SR (seen in the wild as BEV set -> exceptions vectoring
    // into ROM -> pc walking off the end of the BIOS).
    // SAFETY: reads COP0 SR into $8, declared as the output, and the nop covers MFC0's load delay.
    // No other register or memory is touched.
    unsafe { core::arch::asm!("mfc0 $8, $12", "nop", lateout("$8") sr) };
    sr |= STATUS_IE | STATUS_IM2 | STATUS_CU2;
    // SAFETY: writes SR back with IEc, IM2 and CU2 set and every other bit as read above. The only
    // caller, `install_vblank_counter`, has already pointed the exception vector at psx-rt's
    // handler, so the interrupts this enables land there.
    unsafe { core::arch::asm!("mtc0 $8, $12", in("$8") sr) };
}

#[cfg(test)]
mod tests {
    use super::*;

    const EPC: u32 = 0x8001_2340;

    /// GTE commands the SDK issues, as their encoded words.
    const RTPS: u32 = 0x4A18_0001;
    const RTPT: u32 = 0x4A28_0030;
    const NCLIP: u32 = 0x4B40_0006;
    const MVMVA: u32 = 0x4A48_6012;
    const AVSZ3: u32 = 0x4B58_002D;
    const GPF: u32 = 0x4B90_003D;

    #[test]
    fn an_interrupt_on_a_gte_command_resumes_after_it() {
        for word in [RTPS, RTPT, NCLIP, MVMVA, AVSZ3, GPF] {
            assert!(is_gte_command(word), "{word:#010x}");
            assert_eq!(interrupt_resume_pc(EPC, word), EPC + 4, "{word:#010x}");
        }
    }

    #[test]
    fn psx_spx_mask_and_seven_bit_test_agree() {
        // Every top byte, with the rest of the word set both ways.
        for top in 0u32..=0xFF {
            for low in [0, 0x00FF_FFFF] {
                let word = (top << 24) | low;
                assert_eq!(
                    is_gte_command(word),
                    word & 0xFE00_0000 == 0x4A00_0000,
                    "{word:#010x}"
                );
            }
        }
    }

    #[test]
    fn gte_register_moves_and_loads_resume_at_epc() {
        let not_commands = [
            0x480C_6000, // mfc2 $12, SXY0
            0x4889_6000, // mtc2 $9, SXY0
            0x4842_F800, // cfc2 $2, FLAG
            0x48C2_C000, // ctc2 $2, OFX
            0xC885_0000, // lwc2 $5, 0($4)
            0xE8AC_0000, // swc2 $12, 0($5)
            0x4900_0003, // bc2f
            0x4901_0003, // bc2t
            0x4080_6000, // mtc0 $0, SR
            0x0000_0000, // nop
            0x8C82_0000, // lw $2, 0($4)
            0x03E0_0008, // jr $ra
        ];
        for word in not_commands {
            assert!(!is_gte_command(word), "{word:#010x}");
            assert_eq!(interrupt_resume_pc(EPC, word), EPC, "{word:#010x}");
        }
    }

    #[test]
    fn a_gte_command_in_a_delay_slot_is_not_stepped_over() {
        // Cause.BD set: EPC names the branch, the RTPS sits at EPC + 4. The
        // handler reads the branch, so it resumes at EPC and the branch and
        // its RTPS both run again (psx-spx: the fix does not cover delay
        // slots). Stepping to EPC + 4 would drop the branch instead, and
        // EPC + 8 would drop the branch target; neither is safe, which is
        // why the answer is to keep GTE commands out of delay slots.
        let branches = [
            0x1509_FFF0, // bne $8, $9, back
            0x1000_0004, // b forward
            0x0C00_4000, // jal
            0x0800_4000, // j
            0x0100_F809, // jalr $8
            0x03E0_0008, // jr $ra
        ];
        for branch in branches {
            assert_eq!(interrupt_resume_pc(EPC, branch), EPC, "{branch:#010x}");
        }
    }

    #[test]
    fn the_resume_address_wraps_like_the_hardware_add() {
        assert_eq!(interrupt_resume_pc(0xFFFF_FFFC, RTPS), 0);
        assert_eq!(resume_after_fault(false, DBE, 0xFFFF_FFFC, 0), Some(0));
    }

    // Fault path. Cause values are ExcCode << 2, plus CAUSE_BD.
    const ADEL: u32 = 4 << 2;
    const ADES: u32 = 5 << 2;
    const IBE: u32 = 6 << 2;
    const DBE: u32 = 7 << 2;
    const BREAK: u32 = 9 << 2;
    const RI: u32 = 10 << 2;
    const CPU: u32 = 11 << 2;
    const OV: u32 = 12 << 2;

    /// A misaligned data address: never equal to an (aligned) EPC.
    const BAD_DATA: u32 = 0x8001_0001;

    #[test]
    fn a_fault_outside_a_delay_slot_resumes_after_it() {
        for cause in [ADEL, ADES, DBE, RI, CPU, OV] {
            assert_eq!(
                resume_after_fault(false, cause, EPC, BAD_DATA),
                Some(EPC + 4),
                "{cause:#x}"
            );
        }
    }

    #[test]
    fn a_fault_in_a_delay_slot_halts() {
        // Cause.BD: the faulting word is at EPC + 4, behind the branch at
        // EPC. EPC + 4 would re-run it with the branch dropped (a taken
        // branch would fall through), so the handler halts instead.
        for cause in [ADEL, ADES, DBE, RI, CPU, OV] {
            assert_eq!(
                resume_after_fault(false, cause | psx_hw::cop0::CAUSE_BD, EPC, BAD_DATA),
                None,
                "{cause:#x}"
            );
        }
    }

    #[test]
    fn fatal_faults_halt_in_or_out_of_a_delay_slot() {
        for bd in [0, psx_hw::cop0::CAUSE_BD] {
            assert_eq!(resume_after_fault(false, BREAK | bd, EPC, 0), None);
            assert_eq!(resume_after_fault(false, IBE | bd, EPC, 0), None);
            assert_eq!(resume_after_fault(false, ADEL | bd, EPC, EPC), None);
        }
    }

    #[test]
    fn a_gte_command_in_a_delay_slot_interrupt_versus_fault() {
        // bne $8, $9, -4 at EPC with an RTPS in its slot. An interrupt there
        // resumes at the branch, so both run again (documented above); a
        // fault there (Coprocessor Unusable with SR.CU2 clear, say) halts.
        let bne = 0x1509_FFFC;
        assert_eq!(interrupt_resume_pc(EPC, bne), EPC);
        assert_eq!(
            resume_after_fault(false, CPU | psx_hw::cop0::CAUSE_BD, EPC, 0),
            None
        );
        // Outside a delay slot the same fault steps over the RTPS.
        assert_eq!(resume_after_fault(false, CPU, EPC, 0), Some(EPC + 4));
    }

    #[test]
    fn strict_faults_halt_on_every_fault() {
        for bd in [0, psx_hw::cop0::CAUSE_BD] {
            for cause in [ADEL, ADES, IBE, DBE, BREAK, RI, CPU, OV] {
                assert_eq!(
                    resume_after_fault(true, cause | bd, EPC, BAD_DATA),
                    None,
                    "{cause:#x} {bd:#x}"
                );
            }
        }
    }

    // Vector words: a BIOS stub, psx-rt's jump, and a game wrapper's jump.
    const BIOS_STUB: u32 = 0x3C1A_0000;
    const RT_JUMP: u32 = 0x0800_4000;
    const GAME_JUMP: u32 = 0x0800_8000;

    #[test]
    fn a_safe_wait_installs_only_over_the_boot_vector_or_its_own() {
        // Untouched since boot, or already psx-rt's: install.
        assert!(may_install_lazily(Some(BIOS_STUB), BIOS_STUB, RT_JUMP));
        assert!(may_install_lazily(Some(BIOS_STUB), RT_JUMP, RT_JUMP));
        // A game's own handler is never overwritten.
        assert!(!may_install_lazily(Some(BIOS_STUB), GAME_JUMP, RT_JUMP));
        // The boot word was itself another program's handler: still "untouched".
        assert!(may_install_lazily(Some(GAME_JUMP), GAME_JUMP, RT_JUMP));
        // No recorded boot word: the entry predates the rule, keep installing.
        assert!(may_install_lazily(None, GAME_JUMP, RT_JUMP));
    }

    // I_STAT / I_MASK bits (psx-spx): VBlank 0, GPU 1, CDROM 2, DMA 3.
    const VBLANK_BIT: u32 = 1 << 0;
    const GPU_BIT: u32 = 1 << 1;
    const CDROM_BIT: u32 = 1 << 2;
    const INTERRUPT: u32 = 0;

    #[test]
    fn an_enabled_source_nothing_owns_is_acknowledged() {
        // CD enabled and firing with no VBlank: the case that re-entered forever.
        assert_eq!(
            stray_interrupt_sources(CDROM_BIT, VBLANK_BIT | CDROM_BIT, INTERRUPT),
            CDROM_BIT
        );
        // Only enabled sources count.
        assert_eq!(
            stray_interrupt_sources(CDROM_BIT | GPU_BIT, VBLANK_BIT | GPU_BIT, INTERRUPT),
            GPU_BIT
        );
        assert_eq!(stray_interrupt_sources(CDROM_BIT, VBLANK_BIT, INTERRUPT), 0);
    }

    #[test]
    fn a_chained_vblank_leaves_other_sources_for_their_owner() {
        // A game's handler services CD itself and chains here for VBlank; a CD
        // flag that latched in between must stay in I_STAT for it.
        let mask = VBLANK_BIT | CDROM_BIT;
        assert_eq!(
            stray_interrupt_sources(VBLANK_BIT | CDROM_BIT, mask, INTERRUPT),
            0
        );
    }

    #[test]
    fn only_interrupts_are_acknowledged() {
        for cause in [ADEL, ADES, IBE, DBE, BREAK, RI, CPU, OV] {
            assert_eq!(
                stray_interrupt_sources(CDROM_BIT, CDROM_BIT, cause),
                0,
                "{cause:#x}"
            );
        }
        // Cause bits above ExcCode (BD, pending lines) do not hide an interrupt.
        let busy = psx_hw::cop0::CAUSE_BD | 0x0400;
        assert_eq!(
            stray_interrupt_sources(CDROM_BIT, CDROM_BIT, busy),
            CDROM_BIT
        );
    }

    #[test]
    fn the_public_decision_follows_the_feature() {
        for cause in [ADEL, ADES, DBE, RI, CPU, OV] {
            assert_eq!(
                fault_resume_pc(cause, EPC, BAD_DATA),
                resume_after_fault(STRICT_FAULTS, cause, EPC, BAD_DATA),
                "{cause:#x}"
            );
        }
    }
}