Architecture

Architecture

Nakagawa turns a user-supplied PSP executable or module into a native host program. The live source, tests, Makefile, and generated build metadata are authoritative when prose disagrees.

Pipeline

flowchart LR
    A["User-supplied<br/>PSP ELF / PRX"] --> B["Program image<br/>relocations + imports"]
    B --> C["Analysis<br/>CFG + ownership + entries"]
    C --> D["Recompiler IR<br/>MIPS / VFPU semantics"]
    D --> E["Generated C<br/>chunked translation units"]
    E --> F["Portable runtime<br/>state + HLE + services"]
    F --> G["Host backends<br/>SDL3 + Vulkan + audio + I/O"]
    G --> H["Native host<br/>executable"]

Loading

The input is a lawful local prerequisite, not a repository artifact. Offline analysis and translation produce generated source; the native runtime supplies guest state, memory, scheduling, HLE services, and platform backends.

Responsibility map

Stage	Primary source	Responsibility
Load and relocate	tools/prxload.py	Rebase modules, apply supported relocations, and build a flat guest image.
Imports and NIDs	tools/imports.py	Reconstruct import metadata used by code generation and HLE dispatch.
Analysis	tools/analyze.py	Discover functions, ownership, entries, and control-flow metadata.
Translation	tools/codegen.py	Emit C that operates on the shared guest-state ABI.
Compilation	Makefile	Build generated translation units with the selected runtime profile.
Execution	src/rt/	Run guest translation and provide HLE, scheduler, memory, graphics, media, filesystem, and input services.
Reference path	src/ref/	Supply a separate verification interpreter; it is not linked into the normal game executable.

Portable semantics vs host backends

flowchart TB
    subgraph Guest["Portable PSP-facing semantics"]
        CPU["CPU / VFPU state"]
        MEM["Guest memory + validation"]
        HLE["HLE returns + errors"]
        SCHED["Scheduler + waits + VBLANK"]
        STREAM["Stream ownership"]
    end

    subgraph Boundary["Explicit host boundary"]
        VFS["Filesystem / VFS"]
        THREAD["Threads / coroutines"]
        TIME["Timing"]
        WINDOW["Window + input"]
        AUDIO["Audio"]
        GPU["Vulkan / presentation"]
        TOOLS["Processes + dynamic libraries"]
    end

    Guest --> Boundary

Loading

Portable guest semantics should not depend on a drive letter, Win32 handle, Windows fiber, or one window API. Windows 11 x64 with PowerShell/MSYS2 UCRT64, SDL3, and Vulkan is the first-class development and validation host today. Linux and macOS are future native targets; a POSIX/ucontext or host-neutral object compile is not an end-to-end port claim.

See the repository's platform-portability plan.

Load-bearing boundaries

Boundary	Contract
Guest state ABI	src/rt/recomp.h defines CpuState: general registers, HI/LO, PC and delay-slot state, FPU/VFPU state, modeled status, and runtime bookkeeping. Generated code and runtime consumers must agree on its layout.
Generated source	build/<game>/*_recomp*.c is reproducible output. Chunk count depends on discovered functions and FUNCS_PER_CHUNK; generated C must not be hand-edited.
HLE handoff	Guest calls cross into registered NID/HLE handlers, scheduler/memory helpers, and host backends. Unknown or generic-success handlers are not equivalent to fully implemented PSP services.
Evidence boundary	A successful local route establishes that a path executed. It does not by itself establish public reproducibility, PSP hardware behavior, or general title support.

Build profiles

The current HST profile uses runtime -O2 and generated code -O1. Generic or unqualified titles remain at -O0/-O0; explicit overrides are supported. This split is a title profile, not a universal recompiler requirement.

Tip

For the conceptual model, read Static Recompilation Architecture and PSP Executable Model. For source ownership, use the Repository Tour.

Next: Static Recompiler → Runtime and HLE