# pspdev/pspsdk architecture

> Architecture diagram of the GitHub repository pspdev/pspsdk, 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/pspdev/pspsdk
- Repository: https://github.com/pspdev/pspsdk

## Overview

#### Purpose and Deliverables
PSPSDK is a native C/assembly SDK for Sony PSP software. It installs PSP OS headers, import/stub libraries, runtime code, graphics/audio helpers, build templates, and host-side packaging/link tools. Consumer entry points are the installed headers and Make/CMake integration rather than a single application executable. Core build roots: `configure.ac`, `src/Makefile.am`, `tools/Makefile.am`.

#### Build and Installation Pipeline
GNU Autotools generates the build; `bootstrap` prepares configure support, then `configure` selects the PSPDEV toolchain and install prefix. Recursive Automake targets compile and install SDK libraries and host utilities. `build-and-install.sh` is a convenience entry point. PSP cross-compilation depends on the external PSPDEV Allegrex toolchain; zlib is a build dependency. Container and CI integration live in `Dockerfile`, `.github/workflows/compilation.yml`, and `.github/workflows/docker.yml`.

#### ABI, Startup, and PSP OS Boundary
The SDK’s central boundary is PSP application/module code versus PSP firmware APIs. Public headers declare the API, while assembly stubs bind calls to firmware exports. User-mode and kernel-mode APIs are deliberately separated in `src/user/`, `src/kernel/`, and driver-specific headers. Startup initializes executable or PRX module runtime state through `src/startup/crt0.c`, `src/startup/crt0_prx.c`, and `src/startup/prxexports.c`.

#### Linking and PRX Production
PSP-target build rules support static ELF executables and relocatable PRX modules. Common project integration and PRX linker setup are in `src/base/build.mak`, `src/base/build_prx.mak`, and `src/base/linkfile.prx.in`. Import/export assembly and post-link transformations connect application symbols to PSP firmware modules: `src/base/pspimport.s`, `tools/psp-build-exports.c`, `tools/psp-fixup-imports.c`, and `tools/psp-prxgen.c`.

#### Runtime Compatibility Layer
`libcglue` adapts newlib-facing POSIX-like operations—file descriptors, sockets, locks, pipes, and initialization—to PSP services. It is the key dependency boundary between standard C code and PSP kernel/user APIs. Thread-related portability support is separate in `src/libpthreadglue/osal.c` and `src/libpthreadglue/tls-helper.c`; SDK convenience/runtime functions reside in `src/sdk/pspsdk.h`, `src/sdk/loadmodule.c`, and `src/sdk/threadutils.c`.

#### Hardware and Media Libraries
Subsystems expose PSP firmware functionality through headers plus mostly assembly import stubs: input/display/audio (`src/ctrl/pspctrl.h`, `src/display/pspdisplay.h`, `src/audio/pspaudiolib.c`); networking (`src/net/pspnet.h`, `src/net/psphttp.h`, `src/net/sceNetInet.S`); and media codecs (`src/mpeg/pspmpeg.h`, `src/mp3/pspmp3.h`, `src/atrac3/pspatrac3.h`). Additional groups cover USB, WLAN, power, storage, utility dialogs, and kernel services.

#### Graphics Stack
`libGU` is a concrete implementation layer over the PSP Graphics Engine: it constructs and submits rendering commands, manages VRAM, display buffers, synchronization, and GPU state. Its public interface and internals are in `src/gu/pspgu.h`, `src/gu/guInternal.c`, and `src/gu/vram.c`. `libGUM` supplies matrix manipulation layered for GU usage via `src/gum/pspgum.h`, `src/gum/pspgum.c`, and `src/gum/pspgum_vfpu.c`; VFPU/FPU support is in `src/vfpu/pspvfpu.c` and `src/fpu/pspfpu.c`.

#### Host Tools, Packaging, and Documentation
Host executables transform assets and produce PSP-distributable artifacts: binary converters (`tools/bin2c.c`), PARAM.SFO generators (`tools/mksfo.c`), and PBP pack/unpack tools (`tools/pack-pbp.c`, `tools/unpack-pbp.c`). `tools/psp-config.c` locates installations. The separately licensed PRX encryption utility is `tools/PrxEncrypter/main.c`. Doxygen output is configured by `Doxyfile`; sample programs under `src/samples/` are integration consumers of the installed SDK and build templates.

Main entry points: [`configure.ac`](https://github.com/pspdev/pspsdk/blob/master/configure.ac) (Autotools build roots), [`src/base/pspimport.s`](https://github.com/pspdev/pspsdk/blob/master/src/base/pspimport.s) (Firmware import stubs), [`src/base/build.mak`](https://github.com/pspdev/pspsdk/blob/master/src/base/build.mak) (PSP project rules), [`src/base/build_prx.mak`](https://github.com/pspdev/pspsdk/blob/master/src/base/build_prx.mak) (PRX linker setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build &amp; delivery"]
  node_autotools{{"Autotools build roots<br/>build system<br/>[configure.ac]"}}
  node_build_entry["Build installer<br/>shell entry point"]
  node_cross_toolchain{{"PSPDEV Allegrex toolchain<br/>external toolchain"}}
  node_installed_sdk["Installed SDK<br/>developer distribution"]
  node_project_rules["PSP project rules<br/>Make integration<br/>[build.mak]"]
  node_prx_linking["PRX linker setup<br/>linker template<br/>[build_prx.mak]"]
  node_samples["Sample programs<br/>SDK consumers"]
end

subgraph group_abi["PSP ABI &amp; runtime"]
  node_public_headers["Public PSP headers<br/>C API"]
  node_firmware_stubs["Firmware import stubs<br/>assembly ABI bridge<br/>[pspimport.s]"]
  node_startup["Executable &amp; PRX startup<br/>runtime initialization<br/>[crt0.c]"]
  node_psp_firmware["PSP firmware APIs<br/>platform boundary"]
end

subgraph group_libs["SDK libraries"]
  node_libcglue["libcglue<br/>POSIX compatibility runtime"]
  node_pthreadglue["libpthreadglue<br/>thread portability runtime<br/>[osal.c]"]
  node_sdk_runtime["SDK convenience runtime<br/>SDK runtime library<br/>[pspsdk.h]"]
  node_subsystem_libs["Hardware &amp; media libraries<br/>PSP subsystem APIs<br/>[pspctrl.h]"]
  node_libgu["libGU<br/>graphics engine library<br/>[guInternal.c]"]
  node_libgum["libGUM<br/>graphics math library<br/>[pspgum.c]"]
  node_vfpu_fpu["VFPU &amp; FPU support<br/>math acceleration library<br/>[pspvfpu.c]"]
end

subgraph group_tools["Host tools"]
  node_prx_transform["PRX post-link tools<br/>host linker tools<br/>[psp-prxgen.c]"]
  node_packaging_tools["Packaging &amp; asset tools<br/>host utilities<br/>[pack-pbp.c]"]
end

node_build_entry -->|"prepares and runs"| node_autotools
node_autotools -->|"selects"| node_cross_toolchain
node_autotools -->|"builds and installs"| node_installed_sdk
node_public_headers -->|"declared calls bind through"| node_firmware_stubs
node_firmware_stubs -->|"imports"| node_psp_firmware
node_startup -->|"initializes against"| node_psp_firmware
node_project_rules -->|"selects for modules"| node_prx_linking
node_prx_linking -->|"produces input for"| node_prx_transform
node_prx_transform -->|"creates firmware-compatible PRX"| node_psp_firmware
node_libcglue -->|"adapts C operations to"| node_psp_firmware
node_pthreadglue -->|"uses runtime services"| node_libcglue
node_sdk_runtime -->|"uses"| node_psp_firmware
node_subsystem_libs -->|"implemented largely by"| node_firmware_stubs
node_libgu -->|"uses display services"| node_subsystem_libs
node_libgum -->|"layers matrix operations on"| node_libgu
node_vfpu_fpu -->|"accelerates"| node_libgum
node_installed_sdk -->|"installs"| node_public_headers
node_installed_sdk -->|"provides"| node_project_rules
node_installed_sdk -->|"includes"| node_packaging_tools
node_samples -->|"consumes"| node_installed_sdk

click node_autotools "https://github.com/pspdev/pspsdk/blob/master/configure.ac"
click node_build_entry "https://github.com/pspdev/pspsdk/blob/master/build-and-install.sh"
click node_firmware_stubs "https://github.com/pspdev/pspsdk/blob/master/src/base/pspimport.s"
click node_startup "https://github.com/pspdev/pspsdk/blob/master/src/startup/crt0.c"
click node_project_rules "https://github.com/pspdev/pspsdk/blob/master/src/base/build.mak"
click node_prx_linking "https://github.com/pspdev/pspsdk/blob/master/src/base/build_prx.mak"
click node_prx_transform "https://github.com/pspdev/pspsdk/blob/master/tools/psp-prxgen.c"
click node_pthreadglue "https://github.com/pspdev/pspsdk/blob/master/src/libpthreadglue/osal.c"
click node_sdk_runtime "https://github.com/pspdev/pspsdk/blob/master/src/sdk/pspsdk.h"
click node_subsystem_libs "https://github.com/pspdev/pspsdk/blob/master/src/ctrl/pspctrl.h"
click node_libgu "https://github.com/pspdev/pspsdk/blob/master/src/gu/guInternal.c"
click node_libgum "https://github.com/pspdev/pspsdk/blob/master/src/gum/pspgum.c"
click node_vfpu_fpu "https://github.com/pspdev/pspsdk/blob/master/src/vfpu/pspvfpu.c"
click node_packaging_tools "https://github.com/pspdev/pspsdk/blob/master/tools/pack-pbp.c"

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_autotools,node_build_entry,node_cross_toolchain,node_installed_sdk,node_project_rules,node_prx_linking,node_samples toneBlue
class node_public_headers,node_firmware_stubs,node_startup,node_psp_firmware toneAmber
class node_libcglue,node_pthreadglue,node_sdk_runtime,node_subsystem_libs,node_libgu,node_libgum,node_vfpu_fpu toneMint
class node_prx_transform,node_packaging_tools toneRose
```

## Components

### Build & delivery

- [Autotools build roots](https://github.com/pspdev/pspsdk/blob/master/configure.ac): build system · Configures PSP toolchain, recursive builds, and installation. · `configure.ac`
- [Build installer](https://github.com/pspdev/pspsdk/blob/master/build-and-install.sh): shell entry point · `build-and-install.sh`
- **PSPDEV Allegrex toolchain**: external toolchain
- **Installed SDK**: developer distribution · Headers, libraries, templates, and host utilities consumed by PSP projects.
- [PSP project rules](https://github.com/pspdev/pspsdk/blob/master/src/base/build.mak): Make integration · Builds static ELF applications or relocatable PRX modules. · `src/base/build.mak`
- [PRX linker setup](https://github.com/pspdev/pspsdk/blob/master/src/base/build_prx.mak): linker template · `src/base/build_prx.mak`
- **Sample programs**: SDK consumers · Integration consumers of installed headers and project templates.

### PSP ABI & runtime

- **Public PSP headers**: C API · Declares PSP user, kernel, and subsystem APIs.
- [Firmware import stubs](https://github.com/pspdev/pspsdk/blob/master/src/base/pspimport.s): assembly ABI bridge · Binds application imports to PSP firmware exports. · `src/base/pspimport.s`
- [Executable & PRX startup](https://github.com/pspdev/pspsdk/blob/master/src/startup/crt0.c): runtime initialization · Initializes executable or module runtime state. · `src/startup/crt0.c`
- **PSP firmware APIs**: platform boundary

### SDK libraries

- **libcglue**: POSIX compatibility runtime · Adapts newlib file, socket, lock, pipe, and initialization operations to PSP services.
- [libpthreadglue](https://github.com/pspdev/pspsdk/blob/master/src/libpthreadglue/osal.c): thread portability runtime · `src/libpthreadglue/osal.c`
- [SDK convenience runtime](https://github.com/pspdev/pspsdk/blob/master/src/sdk/pspsdk.h): SDK runtime library · `src/sdk/pspsdk.h`
- [Hardware & media libraries](https://github.com/pspdev/pspsdk/blob/master/src/ctrl/pspctrl.h): PSP subsystem APIs · Input, display, audio, networking, codecs, storage, power, USB, and utility services. · `src/ctrl/pspctrl.h`
- [libGU](https://github.com/pspdev/pspsdk/blob/master/src/gu/guInternal.c): graphics engine library · Builds GPU commands and manages VRAM, buffers, synchronization, and state. · `src/gu/guInternal.c`
- [libGUM](https://github.com/pspdev/pspsdk/blob/master/src/gum/pspgum.c): graphics math library · Matrix operations layered for GU rendering. · `src/gum/pspgum.c`
- [VFPU & FPU support](https://github.com/pspdev/pspsdk/blob/master/src/vfpu/pspvfpu.c): math acceleration library · `src/vfpu/pspvfpu.c`

### Host tools

- [PRX post-link tools](https://github.com/pspdev/pspsdk/blob/master/tools/psp-prxgen.c): host linker tools · Generates exports, fixes imports, and creates PRX output. · `tools/psp-prxgen.c`
- [Packaging & asset tools](https://github.com/pspdev/pspsdk/blob/master/tools/pack-pbp.c): host utilities · Converts assets and creates PARAM.SFO and PBP distributables. · `tools/pack-pbp.c`

## Connections

- Build installer → Autotools build roots: prepares and runs
- Autotools build roots → PSPDEV Allegrex toolchain: selects
- Autotools build roots → Installed SDK: builds and installs
- Public PSP headers → Firmware import stubs: declared calls bind through
- Firmware import stubs → PSP firmware APIs: imports
- Executable & PRX startup → PSP firmware APIs: initializes against
- PSP project rules → PRX linker setup: selects for modules
- PRX linker setup → PRX post-link tools: produces input for
- PRX post-link tools → PSP firmware APIs: creates firmware-compatible PRX
- libcglue → PSP firmware APIs: adapts C operations to
- libpthreadglue → libcglue: uses runtime services
- SDK convenience runtime → PSP firmware APIs: uses
- Hardware & media libraries → Firmware import stubs: implemented largely by
- libGU → Hardware & media libraries: uses display services
- libGUM → libGU: layers matrix operations on
- VFPU & FPU support → libGUM: accelerates
- Installed SDK → Public PSP headers: installs
- Installed SDK → PSP project rules: provides
- Installed SDK → Packaging & asset tools: includes
- Sample programs → Installed SDK: consumes
