PSPRecomp/docs/PROFILE_GUIDE.md

PSPRecomp profile guide

A profile contains everything that is specific to one PSP title. The framework root contains only reusable Allegrex, ELF/PRX, memory, runtime and code-generation infrastructure.

Recommended layout

profiles/<id>/
  CMakeLists.txt
  README.md
  config/          Profile configuration and analysis inputs
  data/            Redistributable profile data generated from compatible sources
  generated/       Checked-in AOT C++ corpus for the supported executable
  host/            HLE, bootstrap, renderer/audio/input integration and patches
  scripts/         Current build, run and benchmark entry points
  tests/           Profile-specific regression tests
  tools/           Profile-specific generation or conversion helpers
  third_party/     Dependencies and their license notices
  progress/        Local development handoffs/history; ignored by Git

Do not put commercial executables, disc images, game assets, decrypted EBOOTs, captures made from copyrighted assets, or local analysis dumps in the repository.

1. Start from a game executable you are allowed to analyze

Keep local inputs under profiles/<id>/game or another ignored directory. PSPRecomp expects an ELF/PRX input that the generic analyzer can read. Decryption/extraction is deliberately outside the framework.

2. Analyze the executable

Build the framework tools and run psp_analyze against the local executable. Keep function maps and temporary analysis output under the profile's ignored analysis directory until they are ready to become stable profile inputs.

3. Generate AOT code

Use the root psp_recomp when ordinary PSPRecomp lowering is sufficient. If a title needs verified, address-specific lowering, keep that code in a profile tool rather than hardcoding the address in tools/codegen_main.cpp or src/runtime.cpp.

The VCS profile demonstrates this split with its own vcs_recomp target while the root psp_recomp remains game-neutral.

4. Implement the host profile

Profile host code owns title-specific HLE behavior, bootstrap rules, display/audio/input integration and compatibility patches. Register guest replacements through Runtime::register_function() and PSP imports through Runtime::register_hle().

For heavily measured guest leaves, a profile may register a native implementation with Runtime::register_native_fast_path(). Generated profile code can enter it through Runtime::invoke_native_fast_path(). The native implementation stays in the profile; the reusable runtime contains no game address.

5. Add CMake integration

Each profile supplies profiles/<id>/CMakeLists.txt. The root build adds only the profile selected through -DPSPRECOMP_PROFILE=<id>. A profile may define its own executable, generators, tests, renderer dependencies and post-build packaging.

A clean framework build must continue to work with:

cmake -S . -B out/framework -DPSPRECOMP_PROFILE=""
cmake --build out/framework

6. Keep generated code reproducible

If generated AOT files are checked in, document:

• executable identity/hash expected by the profile;
• stable function-map/config inputs;
• exact profile generator command;
• any deterministic post-generation optimization passes.

Generated C++ may contain game addresses because it belongs to the profile. Reusable root code should not.

7. Keep progress material out of the public tree

Use profiles/<id>/progress for handoffs, one-off benchmark notes and old stage reports. The root .gitignore excludes every profile's progress directory. Current build/run scripts should have stable names instead of accumulating stage-numbered copies.

8. License boundaries

Keep third-party notices with the profile component that needs them. Do not copy source from a project whose license is incompatible with the intended distribution model. Behavioral observations, hardware specifications and independently written implementations should be documented separately from copied third-party source.