This is a basic SDK to run custom Rust code on a PlayStation 1. It works with
Rust nightly version equal to or later than 2024-08-23
. Use
rustup
to install the rust toolchain as follows.
rustup update nightly
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