2 releases
0.1.6 | Jun 7, 2022 |
---|---|
0.1.5 | Jun 4, 2022 |
0.1.4 |
|
#426 in Embedded development
180KB
4K
SLoC
psx-sdk-rs
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 2022-06-03
. Use
rustup
to install the rust toolchain as follows.
rustup update nightly
rustup component add rust-src --toolchain nightly
Installing cargo-psx
cargo-psx
is an optional wrapper for cargo that sets some commonly required
flags and arguments and copies the target JSON to the crate's target directory. Basically this lets you just run cargo psx run
instead of
RUSTFLAGS="-Ccodegen-units=1 \
-Clink-arg=-Tpsexe.ld -Clink-arg=--oformat=binary" \
cargo run +psx -Zbuild-std=core \
-Zbuild-std-features=compiler-builtins-mem \
--target /path/to/mipsel-sony-psx.json
which has the minimum number of flags required to create and run an exe.
To install:
cargo install cargo-psx
To uninstall:
cargo uninstall cargo-psx
For more options:
cargo psx --help
Usage
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
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
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
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
.
Program template
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 !
.
Documentation
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.
Testing
Use the following to run the tests in the psx crate.
cd psx/
cargo psx test