psx_rt/

lib.rs

// SPDX-License-Identifier: GPL-2.0-or-later
//! PS1 bare-metal runtime.
//!
//! Provides the `_start` entry point that the PSX-EXE loader jumps to,
//! a panic handler, direct i-cache control, a BIOS TTY debug
//! trampoline, and optional heap initialisation. Homebrew crates
//! depend on this crate to get a working `main()` environment without
//! thinking about linker symbols or cache-flushing.
//!
//! # Entry sequence
//!
//! 1. The loader (our emulator or the real BIOS) copies the EXE
//!    payload to `LOAD_ADDR` and jumps to [`_start`].
//! 2. [`_start`] zeroes the `.bss` section using the linker-defined
//!    `__bss_start` / `__bss_end` symbols.
//! 3. With the `alloc` feature, the bump allocator is seeded from
//!    `__heap_start..__heap_end`.
//! 4. `main()` is called. When it returns, we halt.

#![no_std]
#![deny(unsafe_op_in_unsafe_fn)]
#![warn(missing_docs)]
// Required for MIPS `global_asm!` blocks (BIOS trampolines). Suppress
// the "feature is declared but not used" warning that shows on the
// host target where only the panic handler + heap are live.
#![cfg_attr(target_arch = "mips", feature(asm_experimental_arch))]

// Corrected signed 64-bit divide/mod (compiler-builtins' are broken here).
#[cfg(target_arch = "mips")]
mod builtins;
// Hand-scheduled memcpy/memset/memcmp (compiler-builtins' are generic loops).
#[cfg(target_arch = "mips")]
mod mem;

#[cfg(target_arch = "mips")]
pub mod bios;
pub mod cache;
pub mod critical_section;
pub mod interrupts;
mod peripherals;
#[cfg(feature = "present-queue")]
pub mod present;
pub mod scratchpad;
#[cfg(target_arch = "mips")]
pub mod tty;
#[allow(
    dead_code,
    reason = "used by the MIPS waits and the present queue, which a host build lacks"
)]
mod wait;

#[cfg(feature = "alloc")]
pub mod heap;

pub use peripherals::Peripherals;

/// Registers psx-rt's critical section as the `critical-section` crate's
/// implementation, so `critical_section::with` anywhere in the program masks
/// interrupts. Off by default: a program links at most one implementation.
#[cfg(feature = "critical-section")]
mod critical_section_impl {
    struct PsxRt;
    critical_section::set_impl!(PsxRt);

    // SAFETY: psx-rt's acquire/release pair masks interrupts and restores
    // the previous state, nesting like brackets, which is the crate's
    // contract.
    unsafe impl critical_section::Impl for PsxRt {
        unsafe fn acquire() -> critical_section::RawRestoreState {
            // SAFETY: the crate pairs every acquire with one release.
            let state = unsafe { crate::critical_section::acquire() };
            crate::critical_section::RestoreState::was_enabled(state)
        }

        unsafe fn release(restore: critical_section::RawRestoreState) {
            // SAFETY: `restore` came from the matching acquire.
            unsafe {
                crate::critical_section::release(
                    crate::critical_section::RestoreState::from_enabled(restore),
                )
            }
        }
    }
}

/// Post-link home for R3000 load-delay hazard trampolines.
///
/// LLVM's MIPS delay-slot filler leaves loads in branch delay slots whose
/// consumer runs one instruction later, inside the load delay, and so reads
/// the stale register. `hazard-patch` rewrites each such branch to
/// jump through a short trampoline it writes here after the link (magic,
/// capacity, then code words), which the staged guest build runs and verifies
/// instead of disabling the filler's backward search at a cost of tens of
/// kilobytes of nops. Every guest that links psx-rt therefore carries this
/// 392-byte array in `.data` (1,032 bytes with `hazard-trampolines-256`); nothing reads it at runtime except the CPU.
#[no_mangle]
#[used]
static mut HAZARD_TRAMPOLINES: [u32; 2 + HAZARD_TRAMPOLINE_WORDS] = {
    let mut words = [0u32; 2 + HAZARD_TRAMPOLINE_WORDS];
    words[0] = 0x4841_5a54;
    words[1] = HAZARD_TRAMPOLINE_WORDS as u32;
    words
};
// Code words available to the patcher. The default suits every shipped
// guest; a large exe whose link reports "trampoline array full" enables the
// `hazard-trampolines-256` feature and pays 640 more bytes of `.data`.
#[cfg(feature = "hazard-trampolines-256")]
const HAZARD_TRAMPOLINE_WORDS: usize = 256;
#[cfg(not(feature = "hazard-trampolines-256"))]
const HAZARD_TRAMPOLINE_WORDS: usize = 96;

// Symbols emitted by `psoxide.ld`.
extern "C" {
    static mut __bss_start: u8;
    static mut __bss_end: u8;
    #[cfg(feature = "alloc")]
    static __heap_start: u8;
    #[cfg(feature = "alloc")]
    static __heap_end: u8;
}

#[cfg(target_arch = "mips")]
extern "Rust" {
    fn main();
}

#[cfg(target_arch = "mips")]
#[used]
#[link_section = ".region"]
static PSX_EXE_REGION: [u8; 55] = *b"PSoXide SDK homebrew executable                        ";

/// Entry point the PSX-EXE loader jumps to.
///
/// The arguments are the MIPS ABI's first three registers as the loader left
/// them. A BIOS boot leaves garbage there, which is why
/// [`psx_io::disc_base::install`] gates on a magic value rather than trusting
/// them; a multi-program loader passes
/// (`HANDOFF_MAGIC`, disc LBA offset, CD-DA track base) so the SDK can find
/// this program's data on a disc it does not own.
///
/// # Safety
/// Called exactly once at boot by the loader. The caller must
/// have set up a valid stack pointer before branching here -- the
/// PSX-EXE header's `initial_sp_base` + `initial_sp_offset` fields
/// guarantee this.
#[cfg(target_arch = "mips")]
#[no_mangle]
#[link_section = ".text._start"]
pub unsafe extern "C" fn _start(a0: u32, a1: u32, a2: u32) -> ! {
    #[cfg(feature = "boot-trace")]
    tty::println("psx-rt: start");

    // Zero BSS.
    let bss_start = &raw mut __bss_start;
    let bss_end = &raw const __bss_end;
    let bss_len = bss_end as usize - bss_start as usize;
    if bss_len > 0 {
        // SAFETY: [__bss_start, __bss_end) is this image's .bss as psoxide.ld lays it out: writable
        // RAM the program owns. No Rust code has run yet, so nothing reads or references it, and
        // zero is each .bss static's initial value.
        unsafe { core::ptr::write_bytes(bss_start, 0, bss_len) };
    }
    #[cfg(feature = "boot-trace")]
    tty::println("psx-rt: bss ok");

    // Before any game code can replace the exception vector: `wait_vblank` installs lazily only
    // over the word found here.
    interrupts::record_boot_vector();

    // After the zeroing, not before: the bases live in statics.
    // SAFETY: once, at boot, before anything can observe them.
    unsafe { psx_io::disc_base::install(a0, a1, a2) };

    #[cfg(feature = "alloc")]
    {
        let heap_start = &raw const __heap_start as usize;
        let heap_end = &raw const __heap_end as usize;
        // The RAM region ends 0x100 bytes above __heap_end, so a .bss that ends in that window
        // puts __heap_start past __heap_end: that leaves no heap, not a wrapped 4 GiB one.
        let heap_size = heap_end.saturating_sub(heap_start);
        // SAFETY: runs once, before `main` and any allocation. [heap_start, heap_start +
        // heap_size) is the range psoxide.ld leaves between .bss and the stack reserve (empty if
        // they meet), used by nothing else.
        unsafe { heap::init(heap_start, heap_size) };
    }

    #[cfg(feature = "boot-trace")]
    tty::println("psx-rt: main");
    // SAFETY: the game crate defines `#[no_mangle] fn main()` and the link resolves this
    // declaration to it. The signature is not checked across that boundary; a `main` with a
    // different signature would be undefined behaviour.
    unsafe { main() };
    #[cfg(feature = "boot-trace")]
    tty::println("psx-rt: main returned");
    halt();
}

/// Current MIPS stack pointer (`$sp`). No memory or stack side effects.
#[cfg(target_arch = "mips")]
#[inline(always)]
fn stack_pointer() -> usize {
    let sp: usize;
    // SAFETY: a single register move out of `$sp`.
    unsafe {
        // The allocator may pick $at; `.set noat` keeps the assembler quiet.
        core::arch::asm!(".set noat", "move {}, $sp", ".set at", out(reg) sp, options(nomem, nostack, preserves_flags));
    }
    sp
}

/// Trap (loudly, via TTY) if the live stack pointer has descended into
/// the static data region.
///
/// The linker lays out `.text/.data/.bss` from the load address upward
/// and runs the stack downward from the top of RAM. The two are only
/// safe while `$sp` stays above the top of `.bss`. A large
/// stack-resident object (e.g. a multi-hundred-KB struct held in a
/// `main` local) or very deep call frames push `$sp` *below* `__bss_end`;
/// from there a stack write and a write to some `static` alias the same
/// RAM and silently corrupt each other -- the corruption surfaces far
/// from the cause and is brutal to debug. Call this once the deepest
/// expected stack frame is live (e.g. right after constructing the main
/// scene object) to turn that into an immediate, located halt instead.
///
/// Note: this checks against the *actual* top of static data, not the
/// linker's `__heap_end` stack floor, which currently reserves only a
/// nominal slice and would false-positive on any real stack.
#[cfg(target_arch = "mips")]
pub fn assert_stack_headroom() {
    /// Bytes of slack required between `$sp` and the top of `.bss`.
    const GUARD: usize = 0x800;
    let data_top = &raw const __bss_end as usize;
    let sp = stack_pointer();
    if sp <= data_top.saturating_add(GUARD) {
        tty::print("\nSTACK/DATA COLLISION: $sp=0x");
        tty::print_hex_u32(sp as u32);
        tty::print(" is inside static data (top=0x");
        tty::print_hex_u32(data_top as u32);
        tty::print(").\n  A large stack object or deep call frames overran the stack and\n  now alias `static` memory -- this silently corrupts both. Move big\n  objects into .bss, shrink static buffers, or enlarge the stack.\n");
        halt();
    }
}

/// Infinite loop with no useful side effects. Used after `main()`
/// returns or from panic / reset paths.
#[inline(never)]
pub fn halt() -> ! {
    loop {
        core::hint::spin_loop();
    }
}

/// Panic handler. Tries to write the message to TTY so PCSX-Redux
/// (and our emulator's future console hook) shows it, then halts.
///
/// A panic raised on a [`scratchpad::ScratchpadStack`] first moves back to
/// the RAM stack, so reporting (BIOS `putchar` included) never runs on the
/// scratchpad. `stack-guard` counts this function's own frame and
/// nothing below it, which is only sound while the report stays out of line.
///
/// Only registered when targeting PS1 hardware. Host builds of the
/// SDK use `std`'s panic handler -- this avoids the lang-item conflict
/// that would otherwise fire when something on host transitively
/// depends on both `psx-rt` and `std`.
#[cfg(target_arch = "mips")]
#[panic_handler]
fn panic(info: &core::panic::PanicInfo<'_>) -> ! {
    let info = (info as *const core::panic::PanicInfo<'_>).cast::<u8>();
    scratchpad::leave_for_panic(info, report_panic);
    report_panic(info)
}

#[cfg(target_arch = "mips")]
#[inline(never)]
extern "C" fn report_panic(info: *const u8) -> ! {
    // SAFETY: `panic` passes its `&PanicInfo`, alive for the whole panic.
    let info = unsafe { &*info.cast::<core::panic::PanicInfo<'_>>() };
    tty::print("PANIC: ");
    if let Some(msg) = info.message().as_str() {
        tty::print(msg);
    }
    tty::print("\n");
    if let Some(loc) = info.location() {
        tty::print("  at ");
        tty::print(loc.file());
        tty::print(":");
        // Print the line number (no fmt machinery in no_std): up to 8 digits.
        let mut line = loc.line();
        let mut buf = [0u8; 8];
        let mut i = buf.len();
        if line == 0 {
            i -= 1;
            buf[i] = b'0';
        }
        while line > 0 && i > 0 {
            i -= 1;
            buf[i] = b'0' + (line % 10) as u8;
            line /= 10;
        }
        if let Ok(s) = core::str::from_utf8(&buf[i..]) {
            tty::print(s);
        }
        tty::print("\n");
    }
    halt()
}