rust-psp

A Modern Rust SDK for Sony PSP Homebrew Development

Edition 2024 · Safety Hardened · Kernel Mode Support

829 Syscalls 33 SDK Modules 30 Examples

Why rust-psp?

Everything you need to write modern, safe homebrew for the PSP.

📡

Complete Syscall Coverage

829 bindings across 33 modules covering every PSP subsystem — graphics, audio, networking, I/O, threading, and more.

🛡

Safe Rust Abstractions

33 high-level modules with RAII resource management, Result types, and zero panics in allocators or VRAM code.

🔑

Kernel Mode Support

Privileged APIs for NAND flash, IR remote, ME coprocessor, syscall hooking, and hardware register I/O.

🔧

Full Build Toolchain

cargo-psp wraps the entire pipeline: Rust source to ELF to PRX to EBOOT.PBP with a single command.

📚

Experimental std Support

Use String, Vec, HashMap, and the full Rust standard library on PSP for familiar, productive development.

CI-Tested in Emulator

Automated integration tests run in PPSSPPHeadless via Docker, ensuring code works on real PSP hardware.

Quick Start

Get from zero to running PSP homebrew in minutes.

1

Install Prerequisites

You'll need Rust nightly and the source component for cross-compilation.

bash
rustup default nightly
rustup component add rust-src
2

Install cargo-psp

Download a prebuilt binary from Releases, or build from source.

bash
# From crates.io (or GitHub Releases for prebuilt binaries)
cargo install cargo-psp
3

Create a PSP Project

Set up a new Cargo project and write your first PSP module.

bash
cargo new hello-psp && cd hello-psp

Add psp to your Cargo.toml, then write your entry point:

rust
#![no_std]
#![no_main]

use psp;

psp::module!("hello_psp", 1, 1);

fn psp_main() {
    psp::dprintln!("Hello from the PSP!");
}
4

Build

Build your project into an EBOOT.PBP that the PSP can run.

bash
cargo +nightly psp --release
# Output: target/mipsel-sony-psp/release/EBOOT.PBP
5

Run

Copy the EBOOT.PBP to your PSP's ms0:/PSP/GAME/hello_psp/ folder, or open it in PPSSPP.

SDK Modules

33 high-level modules organized by domain. Click a category to explore.

System & Lifecycle 8

callback
Exit callback registration and lifecycle management
setup_exit_callback, register_exit_callback
power
CPU/bus clock control, battery info, power event callbacks
ClockFrequency, get_clock, set_clock, on_power_event
display
Framebuffer configuration and VBlank synchronization
wait_vblank, set_framebuf, get_framebuf
time
High-resolution timing with Instant, Duration, and DateTime
Instant, Duration, DateTime, FrameTimer
timer
One-shot alarms and virtual timers with microsecond precision
Alarm, VTimer
dialog
System message, confirm, and error dialogs via utility API
message_dialog, confirm_dialog, MessageDialogBuilder
system_param
System parameter queries (language, timezone, date format)
SystemParamLanguage, SystemParamDateFormat
rtc
Real-time clock with date/time arithmetic operations
RtcTime, get_current_tick

Threading & Synchronization 2

thread
Thread spawning with builder pattern, join handles, and sleep
ThreadBuilder, JoinHandle, spawn, sleep_ms
sync
Spinlock mutex/rwlock, SPSC queue, semaphore, event flags
SpinMutex, SpinRwLock, SpscQueue, Semaphore, EventFlag

Input 2

input
Controller polling with press/release detection and analog deadzone
Controller, ButtonState, AnalogStick
osk
On-screen keyboard for text input via system utility
show_osk, OskBuilder

File I/O & Configuration 3

io
RAII file handles, directory iteration, read/write helpers
File, ReadDir, read_to_vec, write_bytes
config
Key-value store with typed values and binary RCFG persistence
Config, load, save
savedata
Game save/load via PSP savedata utility with metadata
SaveDataBuilder, save, load

Audio 3

audio
RAII audio channel with reserve/output/release lifecycle
AudioChannel, reserve, output_blocking
audio_mixer
Multi-channel PCM mixer with volume control
AudioMixer, MixerChannel
audiocodec
Hardware audio codec access (MP3, AAC, ATRAC3)
AudioCodec

Graphics & Rendering 5

framebuffer
Double-buffered rendering with dirty rect tracking and layer compositing
DoubleBuffer, DirtyRect, LayerCompositor
gu_ext
GU state snapshots, 2D setup helpers, and sprite batching
GuStateSnapshot, setup_2d, SpriteBatch
simd
VFPU-accelerated Vec4/Mat4, easing functions, color operations
Vec4, Mat4, vec4_length, vec4_distance
image
JPEG hardware decode and BMP 24/32-bit decode with auto-detection
decode_jpeg, decode_bmp, load_image
font
System font rendering with VRAM glyph atlas and CLUT alpha ramp
FontLib, Font, FontRenderer, GlyphAtlas

Networking 3

net
WiFi connection, RAII TCP/UDP sockets, DNS resolution
TcpStream, UdpSocket, connect_ap, resolve_hostname
http
High-level HTTP client with GET/POST and response parsing
HttpClient, HttpResponse
wlan
WLAN chip status, power state, and MAC address queries
WlanStatus, is_available, status

Hardware & Memory 4

dma
DMA memory transfer and VRAM blitting
DmaResult, memcpy_dma, vram_blit_dma
cache
Cached/uncached pointer wrappers and data cache helpers
CachedPtr, UncachedPtr, dcache_flush
mem
Typed kernel memory partition allocators
Partition2Alloc, Partition3Alloc
usb
USB bus control and RAII storage mode
UsbStorageMode, start_bus, is_connected

Kernel-Only 3

me
Media Engine coprocessor boot and task submission
MeExecutor, MeSharedState
hw
Hardware register I/O for direct peripheral access
read_reg, write_reg
hook
CFW syscall hooking for kernel module development
SyscallHook

Example Gallery

30 working examples covering graphics, audio, networking, input, and more.

audio-tone

Audio

Generates and plays a 440Hz sine wave tone for 3 seconds using the PSP audio subsystem.

View Source →

clock-speed

System

Reads and sets PSP CPU/bus clock frequencies to maximum speed.

View Source →

config-save

Storage

Saves and loads key-value configuration settings with multiple data types to binary RCFG format.

View Source →

cube

GraphicsMath

Renders a rotating 3D textured cube using the GU graphics engine with matrix transforms and depth testing.

View Source →

embedded-graphics

GraphicsText

Draws shapes and text using the embedded-graphics library including triangles, rectangles, and circles.

View Source →

file-io

Storage

Demonstrates basic file I/O operations writing and reading text files to the host filesystem.

View Source →

fontdue-scrolltext

GraphicsText

Renders scrolling text with fontdue library using sine wave animation and VRAM sprite batching.

View Source →

gu-background

Graphics

Basic GU graphics initialization and display setup showing a colored background.

View Source →

gu-debug-print

GraphicsText

Uses GU debug print functionality to render text directly to the graphics display.

View Source →

hello-world

System

Minimal example that prints a hello message to the debug output.

View Source →

http-client

Networking

High-level HTTP GET requests via psp::http::HttpClient with WiFi connectivity.

View Source →

input-analog

Input

Reads analog stick input with deadzone normalization and button press detection.

View Source →

kernel-mode

KernelSystem

Demonstrates kernel-mode privileged APIs including ME clock, volatile memory, NAND flash, and hardware registers.

View Source →

msg-dialog

GraphicsInput

Displays a message dialog box using the GU-rendered system dialog utility.

View Source →

net-http

Networking

Connects via WiFi and performs HTTP GET requests using raw TCP sockets.

View Source →

osk-input

InputText

Text input via on-screen keyboard (OSK) utility with both convenience function and builder pattern.

View Source →

paint-mode

GraphicsInput

Simple drawing application with analog stick control and button-based tool selection.

View Source →

rainbow

Graphics

Animated rainbow color transitions filling the screen via direct framebuffer manipulation.

View Source →

ratatui

GraphicsText

Terminal UI rendering using ratatui library with styled text, borders, and layout widgets.

View Source →

rtc-sysinfo

System

Reads RTC date/time with arithmetic and queries system parameters like language and timezone.

View Source →

rust-std-hello-world

System

Uses Rust standard library with String, Vec, and format! macros in no_std PSP environment.

View Source →

savedata

StorageGraphics

Saves and loads game data with metadata using the PSP savedata utility with GU rendering.

View Source →

screenshot

GraphicsStorage

Captures the framebuffer as a BMP image and writes it to file.

View Source →

system-font

GraphicsText

Renders system fonts with glyph atlas caching using PSP FontLib and FontRenderer API.

View Source →

thread-sync

Threading

Spawns multiple threads sharing a SpinMutex counter with thread synchronization and join.

View Source →

time

System

Reads and displays the current date and time from the PSP real-time clock.

View Source →

timer-alarm

Threading

Sets one-shot alarm callbacks and virtual timers with microsecond precision time measurement.

View Source →

vfpu-addition

Math

Performs integer addition using VFPU (Vector FPU) inline assembly with float conversion.

View Source →

vfpu-context-switching

Math

Demonstrates VFPU context save/restore with matrix operations preserving register state.

View Source →

wlan

NetworkingSystem

Queries WLAN chip status including power state, switch state, and MAC address.

View Source →

Architecture Overview

How rust-psp is structured and how your code becomes a PSP executable.

Two-Workspace Layout

Root Workspace
psp crate, examples, CI tests
Target: mipsel-sony-psp
  &  
cargo-psp Workspace
Build tools (cargo-psp, prxgen, etc.)
Target: host architecture

Build Pipeline

Rust Source
cargo build
ELF
prxgen
PRX
pack-pbp
EBOOT.PBP

PSP Crate Layer Cake

Your Code
SDK Modules (33 high-level APIs)
sys/ Bindings (829 syscall stubs via psp_extern!)
PSP OS Kernel (NID resolution at load time)

Module System

PSP executables require specific ELF sections: .rodata.sceModuleInfo for module metadata, .lib.stub for import stubs, and .lib.ent for exports. The psp_extern! macro generates syscall stubs with NIDs (Numeric IDs) — the first 4 bytes of SHA-1(function_name) in little-endian — which the PSP OS resolves at load time. Module flags 0x0000 for user-mode, 0x1000 for kernel-mode.

Build Tools

The cargo-psp suite handles every step from Rust source to PSP executable.

cargo-psp

The main build command. Wraps cargo build, invokes prxgen and pack-pbp automatically, and reads project metadata from Psp.toml. Supports --release, --features, and custom target directories.

prxgen

Converts a MIPS ELF binary into PSP's PRX (relocatable module) format. Processes import/export tables and fixes up relocations for the PSP loader.

pack-pbp

Creates PBP archives — the PSP's executable package format. Bundles the PRX with SFO metadata, optional icons (ICON0.PNG), backgrounds, and startup sounds.

mksfo

Generates SFO (System File Object) metadata files containing the game title, disc ID, firmware version requirements, and parental control level.

prxmin

Minimizes PRX files by stripping debug sections and unnecessary ELF data, reducing the final binary size for distribution.

Psp.toml Configuration

toml
# Project metadata for pack-pbp
[metadata]
title = "My PSP Game"
disc_id = "RUST00001"
disc_version = "1.00"
firmware_version = "6.60"

# Optional assets
icon0 = "assets/icon.png"
pic1 = "assets/background.png"

# Localized titles
[metadata.titles]
japanese = "PSPゲーム"
english = "My PSP Game"