This is a basic SDK to run custom Rust code on a PlayStation 1. It works with
Rust nightly version equal to 2024-12-21. Newer nightly versions may or may
not work depending on changes to unstable features. The
github repo may be more up-to-date
with unstable feature usage so consider using a
git dependency
to use the newest nightly versions. Use rustup
to install the rust toolchain as follows.
rustup update nightly-2024-12-21
rustup component add rust-src --toolchain nightly
cargo-psx is an optional wrapper for cargo (similar to cargo-psp)
that sets commonly required flags and arguments. Basically this lets you just
run
cargo psx run
instead of
RUSTFLAGS="-Clink-arg=-Tpsexe.ld \
-Clink-arg=--oformat=binary" \
cargo run +nightly -Zbuild-std=core \
-Zbuild-std-features=compiler-builtins-mem \
--target mipsel-sony-psx
which has the minimum number of flags required to create and run an exe.
To install:
cd cargo-psx
cargo install --path .
To uninstall:
cargo uninstall cargo-psx
For more options see the its README.
The examples directory has some demos which have been tested with the SCPH7001
NA BIOS in mednafen,
pcsx-redux and/or
duckstation. Other BIOS
versions/regions may work but have not been tested. To try out a demo first
check that you have the emulator in examples/$DEMO/.cargo/config.toml
installed, then run cargo psx run from its directory.
To manually select the executable in your emulator, first build with cargo psx build then open the .exe in /path/to/crate/target/mipsel-sony-psx/release/.
To use cargo psx run with other emulators change the
runner for the
mipsel-sony-psx target. To package the executable into an ISO (e.g. to use the
CD-ROM filesystem) use mkpsxiso or
similar.
Mednafen tends to just work with the following .cargo/config.toml. Getting
stdout may require setting psx.dbg_level in mednafen.cfg to at least 2. When
loading ISOs there doesn't seem to be a fastboot (skip BIOS) option, so ISOs
must be licensed properly since the BIOS validates some checksums.
[target.mipsel-sony-psx]
runner = "mednafen"
PCSX-Redux works with the following .cargo/config.toml. Note that -loadexe
must be the last option since cargo psx run passes the executable filename at
the end. See this page for more
command line options.
[target.mipsel-sony-psx]
runner = ["pcsx-redux", "-stdout", "-run", "-loadexe"]
To run an ISO from the command line use pcsx-redux -stdout -run -iso $ISO_FILENAME.
DuckStation works and is extremely useful for debugging, but it doesn't work
with cargo psx run. The issue is that the command passes the runner a relative
path to the executable, but DuckStation only accepts absolute paths on the
command line. To use DuckStation, build with cargo psx build then open the
executable manually. To run an ISO use duckstation-qt -fastboot /full/path/to/$ISO_FILENAME.
To create a new program just use cargo init and add psx = "*" or
psx = { path = "/path/to/psx/crate" } to Cargo.toml under [dependencies].
Then replace src/main.rs with the following template
#![no_std]
#![no_main]
// This can be any import from the `psx` crate
// but there must be at least one.
use psx;
#[no_mangle]
fn main() {
}no_std
is required to link the core crate instead of std. no_main tells rustc to
make no assumption about the program's entry point.
The attribute on main is required since the entry point defined in the psx
crate expects to call an unmangled function.
The main function should not return, but the return type can be either omitted
(i.e. ()) or !.
See docs.rs for documentation. To regenerate documentation for the latest version of psx:
cd psx
cargo doc --target mipsel-unknown-linux-gnu
Then open target/mipsel-unknown-linux-gnu/doc/psx/index.html in a browser.
For documentation on PlayStation internals see the nocash specs.
Use the following to run the tests in the psx crate.
cd psx
cargo psx test