# overdrivenpotato/rust-psp architecture

> Architecture diagram of the GitHub repository overdrivenpotato/rust-psp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/overdrivenpotato/rust-psp
- Repository: https://github.com/overdrivenpotato/rust-psp

## Overview

#### Purpose and Workspace Shape
`rust-psp` is a Rust SDK for producing PlayStation Portable homebrew applications and PRX plugins without PSPSDK. The root workspace centers on the target runtime crate and a Cargo subcommand that builds/package PSP artifacts: `Cargo.toml`, `psp/Cargo.toml`, and `cargo-psp/Cargo.toml`.

#### Application-Facing PSP Runtime
The `psp` crate is the primary consumer API for `#![no_std]` PSP binaries. Its module macro establishes PSP module metadata and the expected `psp_main`-style program boundary; the crate also exports allocation, panic, debugging, math, graphics, VFPU, and test support. Core integration is concentrated in `psp/src/lib.rs`, `psp/src/alloc_impl.rs`, and `psp/src/panic.rs`.

#### System ABI and PSP Services
Low-level bindings expose PSP firmware services through a structured `sys` namespace. This is the boundary between safe/higher-level Rust APIs and PSP kernel/user-mode ABI calls, covering input, display, graphics engine, audio, I/O, networking, power, threads, and utility dialogs. Key aggregation and graphics/control surfaces are `psp/src/sys/mod.rs`, `psp/src/sys/ge.rs`, and `psp/src/sys/kernel/thread.rs`.

#### Graphics, Memory, and Vector Processing
The SDK provides direct graphics-engine APIs plus higher-level GU/GUM wrappers, VRAM allocation, screenshots, embedded-graphics adaptation, and a VFPU interface/assembler-oriented layer. Applications issue rendering work through these APIs against PSP display/VRAM constraints. Architecture-defining paths are `psp/src/sys/gu.rs`, `psp/src/vram_alloc.rs`, and `psp/src/vfpu.rs`.

#### Build and Packaging Pipeline
`cargo-psp` is the principal host-side entry point, invoked as `cargo psp`. It orchestrates Cargo builds for the PSP MIPS target, produces PRX/module output, repairs imports where needed, creates metadata, and packages an installable `EBOOT.PBP`. Main command behavior and metadata schema reside in `cargo-psp/src/main.rs`; standalone packaging stages are `cargo-psp/src/bin/prxgen.rs`, `cargo-psp/src/bin/pack-pbp.rs`, and `cargo-psp/src/bin/mksfo.rs`.

#### Native Unwinding Boundary
Unwinding support depends on bundled PSP-specific `libunwind` static archives, integrated by the runtime build script. This is a native build/link boundary required for `panic = "unwind"` rather than a normal Rust-only dependency. Relevant assets are `psp/build.rs`, `psp/libunwind.a`, and `libunwind/Makefile`.

#### Delivery, Examples, and Verification
Example crates are executable integration clients of the SDK and packaging command, ranging from minimal modules to graphics and networking workloads: `examples/hello-world/src/main.rs`, `examples/cube/src/main.rs`, and `examples/paint-mode/src/main.rs`. CI builds and validates binaries, including PPSSPP-oriented test execution and screenshot/graphics checks, through `ci/concourse/concourse.yml`, `ci/Dockerfile-ppsspp`, and `ci/tests/src/main.rs`. External runtime targets are custom-firmware PSP hardware or PPSSPP; optional developer tooling includes PSPLink, pspsh, and GDB.

Main entry points: [`psp/src/lib.rs`](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/lib.rs) (Runtime core), [`cargo-psp/src/main.rs`](https://github.com/overdrivenpotato/rust-psp/blob/master/cargo-psp/src/main.rs) (cargo psp), [`psp/Cargo.toml`](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/Cargo.toml) (psp crate), [`psp/src/sys/mod.rs`](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/sys/mod.rs) (sys namespace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["PSP Runtime"]
  node_psp["psp crate<br/>no_std runtime<br/>[Cargo.toml]"]
  node_runtime_core["Runtime core<br/>Rust module<br/>[lib.rs]"]
  node_allocation["Allocation support<br/>runtime module<br/>[alloc_impl.rs]"]
  node_panic["Panic support<br/>runtime module<br/>[panic.rs]"]
end

subgraph group_abi["PSP ABI &amp; Graphics"]
  node_sys{{"sys namespace<br/>PSP ABI bindings<br/>[mod.rs]"}}
  node_threading["Kernel threads<br/>PSP ABI module<br/>[thread.rs]"]
  node_graphics_engine["GE services<br/>PSP ABI module<br/>[ge.rs]"]
  node_gu["GU rendering API<br/>graphics API<br/>[gu.rs]"]
  node_vram["VRAM allocator<br/>memory API<br/>[vram_alloc.rs]"]
  node_vfpu["VFPU layer<br/>vector API<br/>[vfpu.rs]"]
end

subgraph group_tooling["Build &amp; Packaging"]
  node_cargo_psp["cargo psp<br/>Cargo subcommand<br/>[main.rs]"]
  node_prxgen["PRX generation<br/>packaging stage<br/>[prxgen.rs]"]
  node_mksfo["SFO metadata<br/>packaging stage<br/>[mksfo.rs]"]
  node_pack_pbp["EBOOT.PBP packer<br/>packaging stage<br/>[pack-pbp.rs]"]
end

subgraph group_native["Native Unwinding"]
  node_psp_build{{"Runtime build script<br/>native build boundary<br/>[build.rs]"}}
  node_libunwind[("Bundled libunwind<br/>static archive<br/>[libunwind.a]")]
  node_unwind_build["libunwind build<br/>Make build"]
end

subgraph group_delivery["Examples &amp; CI"]
  node_examples["Example applications<br/>integration clients<br/>[main.rs]"]
  node_ci["CI validation<br/>CI pipeline<br/>[concourse.yml]"]
  node_ppsspp["PPSSPP tests<br/>test runtime<br/>[main.rs]"]
  node_psp_target(("PSP hardware / PPSSPP<br/>runtime target"))
end

node_workspace["Cargo workspace<br/>Rust workspace<br/>[Cargo.toml]"]

node_workspace -->|"includes"| node_psp
node_workspace -->|"includes"| node_cargo_psp
node_psp -->|"exposes"| node_runtime_core
node_runtime_core -->|"uses"| node_allocation
node_runtime_core -->|"uses"| node_panic
node_runtime_core -->|"wraps"| node_sys
node_sys -->|"contains"| node_threading
node_sys -->|"contains"| node_graphics_engine
node_runtime_core -->|"provides"| node_gu
node_gu -->|"submits commands to"| node_graphics_engine
node_gu -->|"uses"| node_vram
node_runtime_core -->|"provides"| node_vfpu
node_psp_build -->|"links"| node_libunwind
node_unwind_build -->|"builds"| node_libunwind
node_psp -.->|"runs"| node_psp_build
node_examples -->|"uses SDK"| node_psp
node_cargo_psp -->|"generates PRX"| node_prxgen
node_cargo_psp -->|"creates metadata"| node_mksfo
node_prxgen -->|"supplies module"| node_pack_pbp
node_mksfo -->|"supplies metadata"| node_pack_pbp
node_examples -->|"built by"| node_cargo_psp
node_pack_pbp -->|"deploys EBOOT.PBP"| node_psp_target
node_ci -->|"builds with"| node_cargo_psp
node_ci -->|"runs"| node_ppsspp
node_ppsspp -.->|"executes on emulator"| node_psp_target

click node_workspace "https://github.com/overdrivenpotato/rust-psp/blob/master/Cargo.toml"
click node_psp "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/Cargo.toml"
click node_runtime_core "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/lib.rs"
click node_allocation "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/alloc_impl.rs"
click node_panic "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/panic.rs"
click node_sys "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/sys/mod.rs"
click node_threading "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/sys/kernel/thread.rs"
click node_graphics_engine "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/sys/ge.rs"
click node_gu "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/sys/gu.rs"
click node_vram "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/vram_alloc.rs"
click node_vfpu "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/vfpu.rs"
click node_cargo_psp "https://github.com/overdrivenpotato/rust-psp/blob/master/cargo-psp/src/main.rs"
click node_prxgen "https://github.com/overdrivenpotato/rust-psp/blob/master/cargo-psp/src/bin/prxgen.rs"
click node_mksfo "https://github.com/overdrivenpotato/rust-psp/blob/master/cargo-psp/src/bin/mksfo.rs"
click node_pack_pbp "https://github.com/overdrivenpotato/rust-psp/blob/master/cargo-psp/src/bin/pack-pbp.rs"
click node_psp_build "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/build.rs"
click node_libunwind "https://github.com/overdrivenpotato/rust-psp/blob/master/psp/libunwind.a"
click node_unwind_build "https://github.com/overdrivenpotato/rust-psp/blob/master/libunwind/Makefile"
click node_examples "https://github.com/overdrivenpotato/rust-psp/blob/master/examples/hello-world/src/main.rs"
click node_ci "https://github.com/overdrivenpotato/rust-psp/blob/master/ci/concourse/concourse.yml"
click node_ppsspp "https://github.com/overdrivenpotato/rust-psp/blob/master/ci/tests/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_psp,node_runtime_core,node_allocation,node_panic toneBlue
class node_sys,node_threading,node_graphics_engine,node_gu,node_vram,node_vfpu toneAmber
class node_cargo_psp,node_prxgen,node_mksfo,node_pack_pbp toneMint
class node_psp_build,node_libunwind,node_unwind_build toneRose
class node_examples,node_ci,node_ppsspp,node_psp_target toneIndigo
class node_workspace toneNeutral
```

## Components

### PSP Runtime

Target-side no_std SDK.

- [psp crate](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/Cargo.toml): no_std runtime · Application-facing SDK for PSP binaries and plugins. · `psp/Cargo.toml`
- [Runtime core](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/lib.rs): Rust module · Exports module, debug, math, graphics, and test APIs. · `psp/src/lib.rs`
- [Allocation support](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/alloc_impl.rs): runtime module · `psp/src/alloc_impl.rs`
- [Panic support](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/panic.rs): runtime module · `psp/src/panic.rs`

### PSP ABI & Graphics

Firmware bindings and rendering facilities.

- [sys namespace](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/sys/mod.rs): PSP ABI bindings · Low-level firmware service boundary. · `psp/src/sys/mod.rs`
- [Kernel threads](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/sys/kernel/thread.rs): PSP ABI module · `psp/src/sys/kernel/thread.rs`
- [GE services](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/sys/ge.rs): PSP ABI module · `psp/src/sys/ge.rs`
- [GU rendering API](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/sys/gu.rs): graphics API · Direct graphics-unit command interface. · `psp/src/sys/gu.rs`
- [VRAM allocator](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/vram_alloc.rs): memory API · Manages PSP display memory constraints. · `psp/src/vram_alloc.rs`
- [VFPU layer](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/src/vfpu.rs): vector API · Vector processor interface and assembler support. · `psp/src/vfpu.rs`

### Build & Packaging

Host-side Cargo subcommand pipeline.

- [cargo psp](https://github.com/overdrivenpotato/rust-psp/blob/master/cargo-psp/src/main.rs): Cargo subcommand · Builds PSP targets and orchestrates artifact generation. · `cargo-psp/src/main.rs`
- [PRX generation](https://github.com/overdrivenpotato/rust-psp/blob/master/cargo-psp/src/bin/prxgen.rs): packaging stage · Produces module/PRX output and repairs imports. · `cargo-psp/src/bin/prxgen.rs`
- [SFO metadata](https://github.com/overdrivenpotato/rust-psp/blob/master/cargo-psp/src/bin/mksfo.rs): packaging stage · `cargo-psp/src/bin/mksfo.rs`
- [EBOOT.PBP packer](https://github.com/overdrivenpotato/rust-psp/blob/master/cargo-psp/src/bin/pack-pbp.rs): packaging stage · Creates installable PSP packages. · `cargo-psp/src/bin/pack-pbp.rs`

### Native Unwinding

Bundled PSP native link support.

- [Runtime build script](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/build.rs): native build boundary · Links PSP-specific unwinding archives. · `psp/build.rs`
- [Bundled libunwind](https://github.com/overdrivenpotato/rust-psp/blob/master/psp/libunwind.a): static archive · Required for panic unwinding. · `psp/libunwind.a`
- [libunwind build](https://github.com/overdrivenpotato/rust-psp/blob/master/libunwind/Makefile): Make build · `libunwind/Makefile`

### Examples & CI

Integration clients and validation.

- [Example applications](https://github.com/overdrivenpotato/rust-psp/blob/master/examples/hello-world/src/main.rs): integration clients · Hello-world, cube, and paint-mode PSP programs. · `examples/hello-world/src/main.rs`
- [CI validation](https://github.com/overdrivenpotato/rust-psp/blob/master/ci/concourse/concourse.yml): CI pipeline · Builds binaries and runs PPSSPP-oriented graphics checks. · `ci/concourse/concourse.yml`
- [PPSSPP tests](https://github.com/overdrivenpotato/rust-psp/blob/master/ci/tests/src/main.rs): test runtime · Emulator-driven validation client. · `ci/tests/src/main.rs`
- **PSP hardware / PPSSPP**: runtime target · Custom-firmware hardware or emulator execution environment.

### Other components

- [Cargo workspace](https://github.com/overdrivenpotato/rust-psp/blob/master/Cargo.toml): Rust workspace · Coordinates runtime and cargo subcommand crates. · `Cargo.toml`

## Connections

- Cargo workspace → psp crate: includes
- Cargo workspace → cargo psp: includes
- psp crate → Runtime core: exposes
- Runtime core → Allocation support: uses
- Runtime core → Panic support: uses
- Runtime core → sys namespace: wraps
- sys namespace → Kernel threads: contains
- sys namespace → GE services: contains
- Runtime core → GU rendering API: provides
- GU rendering API → GE services: submits commands to
- GU rendering API → VRAM allocator: uses
- Runtime core → VFPU layer: provides
- Runtime build script → Bundled libunwind: links
- libunwind build → Bundled libunwind: builds
- psp crate → Runtime build script: runs
- Example applications → psp crate: uses SDK
- cargo psp → PRX generation: generates PRX
- cargo psp → SFO metadata: creates metadata
- PRX generation → EBOOT.PBP packer: supplies module
- SFO metadata → EBOOT.PBP packer: supplies metadata
- Example applications → cargo psp: built by
- EBOOT.PBP packer → PSP hardware / PPSSPP: deploys EBOOT.PBP
- CI validation → cargo psp: builds with
- CI validation → PPSSPP tests: runs
- PPSSPP tests → PSP hardware / PPSSPP: executes on emulator