ppsspp Documentation

Technical Documentation: hrydgard/ppsspp

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

PPSSPP - a fast and portable PSP emulator

Created by Henrik Rydgård

Additional code by many contributors, see the Credits screen

Originally released under the GPL 2.0 (and later) in November 2012

Official website: https://www.ppsspp.org/

Discord: https://discord.gg/5NJB6dD

No BIOS file required to play, PPSSPP is an "HLE" emulator. Default settings balance good compatibility and speed.

To contribute, see Introduction to development. This page also includes our new AI policy.

Help with testing, investigating, or fixing bugs is always welcome. See the list of issues.

For the latest source code, see our GitHub page.

For documentation of all kinds (usage, reference, development), see the documentation on the main website

For build instructions and other development tutorials, see the wiki.

To download fresh development builds for Android, Windows and Mac, go to the /devbuilds page

For game compatibility, see community compatibility feedback.

What's new in 1.20.4 Copy Chapter

1.20.4 is an unusually big followup release, but given the new multiplayer developments, we need something to cover the longer gap to 1.21.
During this cycle, I've mostly focused on UX improvements.

• Ad-hoc

  • Support for "data.json" live status from adhoc relay servers (#21496, #21526)
  • RetroAchievements UI improvements around subsets (#21536)
  • Assorted ad-hoc UI improvements (#21530, #21510)
  • Fixes for The Warriors (#21464) and Street Riders (#21460) in relay mode

• Texture upscaling

  • Fix old bug causing some textures to get stuck unscales on some hardware when using GPU texture upscaling (#21533)
  • Improved performance of MMPX-adv upscaler (#21555)
  • NNEDI3 and Spline36 GPU texture scaling (#21527)

• Rendering fixes

  • Fix a bug in lens flare occlusion for the Syphon Filter games (#21511)
  • Fix a bug in the software renderer (#21648)

• Misc UI improvements

  • Instant type-to-search in game browser (#21559, #21565, #21630)
  • Fix file picker problems on some Android devices (regression) (#21614, #21656)
  • Fix crash in text edit fields on Mac/iOS (#21601)
  • PSP DVD prototypes can now load directly (#21599, #21601)
  • Cheat UI has been cleaned up and supports titles and comments natively (#21590)
  • RetroAchievements subset display improvements (#21536)
  • Basic deep link support on iOS (#21615)
  • Soft keyboard has more symbols (#21625)

• Other

  • Fix important (but mostly rare) crash bug affecting games that draw a lot (#21669)
  • More plugin zip files can now auto-install (#21556)
  • Pause on lost-focus on Linux (#21517)
  • Frameskipping no longer breaks analog stick auto-rotation in GoW, however manual rotation still broken (#21508)
  • Android: Restore "Landscape Auto" (#21482), the "Auto" screen rotation mode now overrides the user rotation lock (#21507)
  • Contribution by lrzlin: Loongarch improvements (#21499, #21595)
  • Basic support for extracting ISO from 7zip files (#21493)
  • Fix a bug that prevented loading certain texture packs (#21491)
  • Fix music looping in Death JR (#21490)
  • Hide the save-load indicator in the corner by default (#21528)
  • Fix crash in the remote debugger, by Nemoumbra (#21652)
  • Fix screenshot cropping bug (#21665)
  • mfplat.dll is no longer required on Windows unless you need camera/microphone (#21660)

What's new in 1.20.3 Copy Chapter

• Fix issue preventing ad hoc relay servers from working when RetroAchievements are enabled on Windows (#21420)
• Some ad hoc UI improvements (#21432, #21433)
• Fix crash/failure setting the background on iOS (#21409)
• Fix logging to file (#21412)
• Networking settings cleanup (#21418)
• Some fixes for assorted rare crashes (#21422)
• Fix issues when unpausing using a controller binding (#21424), DualSense Edge detection on Windows (#21426)
• Fix missing savestate undo button (#21425)
• MMPX texture upscaling algorithm has been restored, the new one has been improved (#21376) and renamed MMPX Advanced (#21421)
• Fix support for custom game config for homebrew apps (#21434)
• Improve insets handling on Android (#21437)

What's new in 1.20.2 Copy Chapter

• Improved server list for ad hoc multiplayer, dynamically updated and you can now add/remove entries (#21326, #21389, #21351)
• Fix broken multitouch on iOS with OpenGL (#21350)
• Ad hoc relay connection improvements (#21352)
• Fix a lot of minor UI issues (#21400, #21362)
• Fix background image selection on Android and iOS (#21345, #21384, #21371)
• Fix file permission issue on iOS (#21374)
• Add a "hold" version of axis swap toggle (#21357)
• Fix regression in Gripshift (#21377)
• Fix crash on audio device switch on Windows (#21341)
• Fix timing glitches in gamepad input on Windows (#21393)
• And other assorted fixes.

What's new in 1.20 Copy Chapter

• User interface

  • New feature: Proper support for Portrait Mode UI - you can now rotate your phone to vertical mode, and things will mostly work fine! (#21185, #21044...)
  • New feature: Separate touch controls and display layout configs for landscape/portrait, new default touch control layout for portrait mode
  • New feature: Upload files via HTTP from devices on the same network
  • Savestate count limit can now be configured (#21112)
  • UI icons are now vector-based, making them look sharper on high-DPI screens (#20824, #20870)
  • Better handling of unsupported ISOs (#21169, #21166)
  • Misc: Improved text rendering, chat box improvements (#20653), PIC0 is now visible on the game screen (#20686), (#20611), rotation fixes (#21145), input fixes (#21248), fixes for XBox FullScreen Experience, background stretch (#21211), handle savedata in main game browser (#21277), Discord Presence improvement (#21246)
  • Show ICON1.PMF on the game info screen (#21303)

• Regression fixes

  • In 7th Dragon, voice-related crashes are fixed (#20837)
  • Soundtrack is working again in Tony Hawk's Project 8 (#20775)
  • Fix crash in StormBasic homebrew apps (#20715)
  • Built-in songs in Beats work again (#20662)
  • Fix adhoc in Syphon Filter games (#20642)
  • Fix strange cutscene speedups in Power Stone 2 (Power Stone Collection) (#2124)
  • Work around game bug to help more custom songs play again in GTA LCS (#20692)

• Multiplayer

  • Support aemu relay servers for AdHoc multiplayer (#21116, #21271)

• Controller and touch screen input

  • Native support for DualSense (#20580, #20620, #21191), DualShock and Switch Pro (#20647) controllers on Windows - including tilt controls for DualSense and Switch Pro
  • Misc touch screen and controller mapping improvements (#21195, #21197, #21258, #21325)
  • Add simple virtual keyboard for text input for platforms that don't have one (#21306)

• Graphics

  • Fixed multiple graphical effects in Tales of Phantasia X
  • Reworked the VSync setting to be more intuitive. It's now pretty much never a bad idea to turn it on.
  • Fixes for various glitches in Tales of Phantasia X (#21173, #21141, #21205)
  • Some more framebuffer readback workarounds (#20640, #20631, #20632)
  • MMPX upscaling enhancements by crashGG (#20622, #20541)
  • Huge rendering speedup in Brave Story (#21151)
  • Fix rendering bug caused by CPU emulation bug in ATV Offroad Fury: Blazing Trails (#21238)
  • Partially fix rendering problem in Mahjong Artifacts (#21244) and The Mystery of the Crystal Portal (#21236)
  • Boost the GPU in Outrun 2006 to avoid unnecessary slowdowns (#21304)

• Other game fixes

  • Fix savedata problem in Silent Hill: Shattered Memories (#21294)

• Audio

  • Added "Smooth" playback mode, which evens out glitches (while adding a very small amount of latency)
  • Remove DirectSound support (#20533), add support for ultra-low-latency streams on WASAPI, available on some devices (#20535)

• Platform support

  • Windows
    • D3D9 support has been removed (#19951, #20490)
    • ARM64 is now officially supported, and works great (#20863)
    • Correct fullscreen mode in Xbox Fullscreen Experience (#21189)
    • Assorted improvements (#20778, #20774)
  • Android
    • The minimum Android version has been raised for technical reasons, KitKat is no longer supported (#19658)
    • Support for Android devices with 16KB page size. This is a technical change, required by Google Play, that unfortunately forced us to drop compatibility with the very oldest devices (Android < 5). (#20788)
    • Shortcut widgets can now be created even if the app isn't running (#20798)
    • Removed support for classic Moga controllers, these were only a thing on early Android (#20762)
  • iOS
    • Add support for screen rotation
  • Linux
    • Loongarch improvements by lrzlin (#20683, #20644) and KatyushaScarlet (#20599, #20594), text rendering improvements (#21163)
    • SDL fullscreen problems fixed (#21300, more)
  • UWP
    • Migrate code base to C++/WinRT (#21100)

• Debugger

  • ImDebugger improvements (#20861, #20779, #20657, #20637, #20550, #20523)
  • Websocket debugger fixes (#20749)

• Other

  • RetroAchievements: Upgrade the support library with perf fixes (#21081), various fixes and improvements
  • Add workaround for infamous God of War crash (#21148)
  • Fix assorted minor UI bugs (#21042, ...)

What's new in 1.19.3 Copy Chapter

• Fixed crash on startup in Tony Hawk's Underground 2 (#20573)
• Fixed crash/hang when accessing the menu in FFII if readbacks were configured to copy-to-tex (#20573)
• Fix issue with detection of some types of saving, for the save reminders on exit (#20623)
• Fixed music and other audio in modded games (various football games, Crazy Taxi w/ original soundtrack, etc) (#20566, #20571)
• Fix exiting not functioning correctly on Windows in some circumstances (#20607)
• Minor UI and key binding fixes (#20604)
• Fix crash/blackscreen when switching from skip buffer effects to auto-frameskip rendering (#20605)
• Fix bug in Mac/Linux builds where the mouse got hidden and stuck if you enabled mouse input mapping (#20612)
• Fix black screen on save/load in the Football Manager Handheld games (#20616)
• Translation improvements

What's new in 1.19.2 Copy Chapter

• In-game save/load not properly detected for saving reminder (#20500)
• Install savedata from ZIP was partially broken (#20498)
• Fixed module loader bug affecting a few games (#20513)
• Fixed some hangs in the Windows debugger (#20510)
• Fix performance problem in texture replacement (#20520)
• Assorted fixes (#20518, #20514, #20502, #20515)

What's new in 1.19.1 Copy Chapter

• Fix selecting background image on Android (#20477)
• Fix RetroAchievements regression for multi-executable games (#20469)
• Possible fix for Mac audio device selection issue (#20482)
• Add workaround for Dragon's Lair not working with LLE scePsmf (#20468)
• Prevent trying to load obviously-corrupt CSO/CHD files (#20466)
• Fix regression for homebrew apps that request extra memory (#20457)
• Fix grid drawing in the various Robot Taisen games (#20456)
• Fix crash in UI when viewing a directory with multiple NPDRM ISOs (#20453)

What's new in 1.19 Copy Chapter

• Audio

  • Brand new sceAtrac implementation, fixing Flatout and multiple other long-standing issues! (#20098, #20136, #20138, #20162)
  • More correctly implemented sceAtrac-through-sceSas functionality, fixing voice in Sol Trigger and multiple minis (#20156)
  • Better support for using sceAudiocodec directly, fixing music in some homebrew apps (#20199, #20246, #20253, #20209)
  • Volume control improvement (#19969, #19971)

• Rendering fixes and performance

  • Important: This will be the last major version with D3D9 support. D3D11 will of course continue to be supported, along with Vulkan and OpenGL.
  • Fix smoke effects in Jak'n'Daxter by re-using the fix from Ratchet & Clank (#20032)
  • Software depth buffer rendering added to fix lens flares in multiple games efficiently (Midnight Club LA, Wipeout, Syphon Filter etc) (#19748, #19764, #20231, #19955, etc)
  • Multiple rendering-related crash fixes (#20270, #20346, #20344)
  • Texture replacement load speed corrected and can now be controlled (#20286), regression fix for zipped packs (#19860)
  • Additional assorted compatibility and other fixes (#20376, #20070, #19685)
  • Persona 1/2 readback fixes (#20067, #20068)
  • Other correctness fixes (#20233, #20255, #19686)

• General emulation

  • Allow disabling HLE on a per-module basis (if games ship the module so we can load it). Enabled for sceCcc (#20218), and more importantly scePsmf (#20208), fixing multiple issues.
  • Additional module loading improvements (#20114)
  • More precise sleep function on Windows (#20054)
  • More replacement texture improvements, allow replacing game icons (#19975, #19978)
  • Disable certain features like fast-forward when networking is on, to avoid de-syncs (#20311)
  • Fixes mono Atrac3 as video soundtrack (#19800)
  • Improvements to RISC-V support (#20352)

• Control and input

  • Touch gliding support added (#19983)
  • Allow simultaneous DInput and XInput input (#20347)

• New "Dear ImGui"-based PSP debugger: ImDebugger

  • Allows very rapid development of debugging features as-needed, and also implements a pretty good Ge debugger for stepping through draws.
  • Unlike the old Win32 debugger (but similar to the unmaintained web debugger), works on all platforms (though cumbersome on touchscreens)
  • Major commits (though there are many more): (#20242, #20240, #20294)

• Multiplayer

  • Added Infrastructure multiplayer support, with automatic DNS configuration (#19865, #19869, #20221, #20220, #19875)
    • Note: Only games that people have made "revival servers" for will work. See here.
  • Implement more of sceNet (prerequisite for the former feature).
  • Socket re-mapping implemented (#19827)
  • Assorted bugfixes, thanks ANR2ME (#20247, #20245, #19843, #19849, #19836)

• UI

  • Loading spinner now actually spins properly, the app no longer appears to hang (#20341)
  • Minor features: Asks for confirmation on exit in most scenarios (#19996, #20023), DPI scaling (#20013), can pause without menu (#19883)
  • As usual a lot of tweaks, perf fixes, and fixes for hangs and crashes (#20343, #20332, #20305, #20303, #20299, #20163, #20152, #20143, #20079, #20137, #20374)
  • Two new color themes (#20334, #20335), related themability fixes (#19984, #19995, #20308)
  • Improvements and bug fixes in the savedata manager (#19771, #20170)
  • Add "Move to trash" deletion functionality to multiple platforms (#20230, #20261)
  • Add ability to take "raw" screenshots of gameplay (#20029)
  • More files can be loaded directly from ZIP (#20243)
  • Developer Settings are now tabbed for easier access (#20228)
  • Switch to the full libpng API so we can disable gamma correction, like the real PSP (#20033)
  • Support displaying the battery percentage on more platforms (#19973, #19967)
  • Allow picking a background image on iOS (#20370)

• Platform compatibility

  • Exclude older Macs from using Vulkan (too many black screens, hangs) (#20236)
  • Use portable-file-dialogs to provide file-open dialogs on Linux (#20175)
  • "Cache full ISO in RAM" is now correctly hidden where it doesn't work (#20165)
  • Now rendering at proper resolution on newer Macs (#20011)
  • Mouse input improved on Android, including separate button mapping (#19915)
  • Use the correct font again on Mac/iOS (#19874)
  • Multiple file access optimizations made to make the most out of the flawed foundation called Android Scoped Storage (#19668)

What's new in earlier versions Copy Chapter

See history.md.

Overview (`headless/README.md`) Copy Section

PPSSPPHeadless

Non-interactive, headless build of PPSSPP. It boots a PSP executable, PRX, or GE frame dump (.ppdmp) without a GUI, forwards what the program prints to the console, optionally captures and compares text output or screenshots, and exits.

Primarily intended for:

• Automated regression testing (via pspautotests)
• Replaying GE frame dumps (.ppdmp) to compare rendering output across GPU backends or settings
• CI pipelines that need to verify emulation correctness

Building Copy Chapter

Windows (Visual Studio) Copy Section

The PPSSPPHeadless project is part of the Windows/PPSSPP.sln solution. Build the PPSSPPHeadless target in your preferred configuration.

Example:

msbuild Windows\PPSSPP.sln /p:Configuration=Debug /p:Platform=x64 /t:PPSSPPHeadless

Linux / macOS (CMake) Copy Section

cmake -DHEADLESS=ON -B build-headless
cmake --build build-headless

Usage Copy Chapter

PPSSPPHeadless file.elf|file.prx|file.ppdmp [...] [options]

Options Copy Section

Program Output Copy Chapter

Running a homebrew with no options at all prints what it prints, and nothing else. Two separate
channels feed the console, both on by default:

• The emulated program's stdout and stderr - sceIoWrite() to fd 1 and 2 (which is where a
  PSPSDK printf() ends up), and writes to a tty device. These go to our stdout and stderr
  respectively, byte for byte, with no prefix or sanitization.
• The emulator: devctl channel - sceIoDevctl("emulator:", SEND_OUTPUT, ...), a PPSSPP
  extension. This goes to stdout. pspautotests uses this channel exclusively, and it is what
  --compare compares against the .expected file.

--compare and --bench turn both off, so the only thing a test run prints is the comparison
result. Emulator log output is separate again, and stays off unless you pass -l.

GPU Backends Copy Chapter

The --graphics option selects the rendering backend:

The software backend produces deterministic output across runs and is the default. Hardware backends may produce slightly different pixels due to precision differences in shaders and rasterization.

Frame Dump Replay (`.ppdmp`) Copy Chapter

GE frame dumps are recordings of a single frame's GE graphics commands. When a .ppdmp file is passed:

1. The file is identified by the PPSSPPGE magic header.
2. The GE commands are replayed through the selected GPU backend.
3. The framebuffer is captured automatically (512×272 stride, 480×272 visible).
4. A screenshot is sent for comparison/saving via --compare, --screenshot, or --screenshot-save.

For batch rendering tests over sets of frame dumps, see docs/frametest.md (the frametests.py runner).

Example: Generate a reference screenshot Copy Section

# BMP:
PPSSPPHeadless.exe --graphics=software --screenshot-save=reference.bmp frame.ppdmp
# PNG (lossless, recommended for storing references):
PPSSPPHeadless.exe --graphics=software --screenshot-save=reference.png frame.ppdmp

The BMP output is 512×272 with 32-bit BGRA pixel data. The file size is always 557,110 bytes (54-byte header + 512 × 272 × 4 bytes). PNG output is 512×272 RGBA.

Example: Compare against a reference Copy Section

# With --compare, auto-derives the screenshot path:
#   frame.ppdmp  →  looks for  frame.png  (next to the .ppdmp)
PPSSPPHeadless.exe --graphics=software --compare frame.ppdmp

# Explicit reference file (saves a visual comparison to diff.png):
PPSSPPHeadless.exe --graphics=software --screenshot=reference.bmp --screenshot-diff=diff.png --max-mse=0.5 frame.ppdmp

When the MSE exceeds --max-mse, the following files are saved in the working directory:

Screenshot Comparison Details Copy Chapter

• Resolution: Always 480×272 display captured from a 512-pixel-wide framebuffer.
• Format: MSE (Mean Squared Error) calculated per-pixel across R, G, B channels (alpha ignored).
• MSE formula: MSE = sum((actual - reference)^2) / (width × height × 3)
• Reference formats: BMP (32-bit BGRA) or PNG (auto-detected by header).
• --compare auto-path: For .ppdmp files, it replaces the extension with .png. For .prx/.elf files, it appends .expected.bmp.
• Failure output: Off by default in GitHub Actions CI; controllable via SetWriteFailureScreenshot().

Text Output Comparison Copy Chapter

The --compare flag also compares emulated debug output (printf / sceIoWrite to the emulator channel) against a .expected text file:

• For .prx files: same path with .expected extension.
• The comparison is line-based with a diff algorithm that highlights mismatches and insertions/deletions, although the support for the
  latter is limited, it's not a full-on diff.

If only a screenshot reference exists and no .expected file, the test passes as long as there is no unexpected text output.

Batch Testing Copy Chapter

Tests can be listed in a text file or piped via stdin:

# List file
PPSSPPHeadless.exe --compare --timeout=5 @testlist.txt

# Stdin
echo "test1.prx test2.prx test3.ppdmp" | PPSSPPHeadless.exe --compare --timeout=5 @-

# Recursive directory scan (append /...)
PPSSPPHeadless.exe --compare tests/cpu/...

Exit code is 0 if all tests pass, 1 if any fail.

CI Integration Copy Chapter

GitHub Actions is auto-detected via the GITHUB_ACTIONS environment variable and will print error annotations inline.

Example workflow step:

- name: Headless tests
  run: |
    PPSSPPHeadless.exe --graphics=software --compare --timeout=10 @testlist.txt

Configuration Copy Chapter

The following configuration is hardcoded for headless mode (config file is never saved):

(For actual up-to-date hardcoded config, see the headless.cpp file).

Overview (`ios/README.md`) Copy Section

Updating with a self-built MoltenVK

Probably won't be needed again.

cp -r ../dev/build-molten/MoltenVK/Package/Release/MoltenVK/static/MoltenVK.xcframework ios/MoltenVK

The Old iOS Build Instructions

Important Notes Copy Chapter

These instructions have not been updated for a long time and may be outdated.

Prerequisites: Copy Chapter

• Xcode (from the Mac App Store) with command line tools installed
• MacPorts (from macports.org); easiest to install with their package installers
• cmake build system (from MacPorts); run "sudo port install cmake" from the command line

If you need to build ffmpeg yourself too, then you'll also need:

• gas-preprocessor; download the zip from https://github.com/mansr/gas-preprocessor, unzip and from the command line run:

  text Copy

  sudo cp gas-preprocessor.pl /usr/bin/
    sudo chmod +rw /usr/bin/gas-preprocessor.pl

• you may need pkg-config (from MacPorts); run "sudo port install pkgconfig" from the command line

Most of this is done from the command line: Copy Chapter

Change directory to wherever you want to install ppsspp (eg. "cd ~"), and then clone the main ppsspp repository:

git clone https://github.com/hrydgard/ppsspp.git

Change directory to the newly created ppsspp directory and run:

git submodule update --init

The above command will pull in the submodules required by PPSSPP, including the native, ffmpeg, and lang directories. Included in the ffmpeg directory should be the necessary libs and includes for ffmpeg, so most people can skip the next command. However, if you need to recompile ffmpeg for some reason, change directory into ffmpeg and run (this will take a while):

./ios-build.sh

Change directory back up to the main ppsspp directory and do the following:

mkdir build-ios
cd build-ios
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/ios.cmake -GXcode ..

You now should have an Xcode project file in the build-ios directory named PPSSPP.xcodeproj. Open it up in Xcode and do Product->Build to build the debug version, or Product->Build For->Archiving to build the release version (which is much faster). If your iOS device is plugged in, you may be able to just Run in Xcode to install and test it. Otherwise, copy the PPSSPP app from build-ios/Debug-iphoneos/PPSSPP.app or build-ios/Release-iphoneos/PPSSPP.app to the /Applications directory on your device and from ssh or MobileTerminal do a "chmod +x PPSSPP" inside the PPSSPP.app directory. If this is the first time you've installed the PPSSPP app, you'll have to respring or restart your device for the icon to show up.

Overview (`macOS/README.md`) Copy Section

MacOS notes

Entitlements.plist is to be used for code signing on macOS.

We enable "hardened runtime" in order to make notarization happy, but we need some exceptions.

MoltenVK on Mac Copy Chapter

To update MoltenVK, download the latest version and get the files from dylib/macOS and put them in ext/vulkan/macOS/Frameworks.

Overview (`Tools/langtool/README.md`) Copy Section

Language ini file processor tool

To install Rust and cargo, go here.

To run, with rust installed, change to this Tools/langtool directory, then:

cargo run

(Or just move the binary out of target/ and run it directly).

To see command line usage, type:

cargo run -- --help

Validating Copy Chapter

cargo run -- validate

Checks every translated string in every language file against the English one it came from:
placeholders (%1, %d, ...) must survive translation, no line breaks or stray quotes, nothing
empty. Exits with a non-zero code if it finds anything, so it can be used as a check in a script.

The same checks run on anything the AI produces, before it gets written to a file.

AI translation Copy Chapter

Some commands (add-new-key-ai, add-new-key-value-ai, finish-language-with-ai) use an LLM to
generate translations. Two providers are supported, pick one by setting its API key in the
environment:

• Claude (Anthropic): ANTHROPIC_API_KEY
• OpenAI: OPENAI_API_KEY

If both are set, Claude is used unless you say otherwise with --provider openai. To pick a
specific model, use --model, for example:

cargo run -- --model claude-sonnet-5 finish-language-with-ai sv_SE
cargo run -- --model gpt-4o finish-language-with-ai sv_SE

The provider is inferred from the model name, so --provider is only needed to disambiguate.

Strings that are deliberately the same as the English one (terms like "Vsync") are marked with a
# same as English comment. finish-language-with-ai skips those instead of paying to have them
"translated" again on every run, and writes the comment itself when the AI hands the English string
back unchanged. Delete the comment if you disagree with it and it'll be picked up again next time.

To autoformat the code, use:

cargo fmt

or set up your IDE to do that (it's already pre-set-up for VS Code, if you open the langtool folder directly).

Overview (`Tools/wsdbg/README.md`) Copy Section

wsdbg - WebSocket debugger CLI

A small standalone client for talking directly to PPSSPP's WebSocket debugger
interface (see docs/WebSocketDebugger.md in the root of the repo for the
full protocol reference and event catalog).

To install Rust and cargo, go here.

To run, with rust installed, change to this Tools/wsdbg directory, then:

cargo run -- <port>

(Or build once with cargo build --release and run the binary directly from
target/release/.)

Usage Copy Chapter

Start PPSSPP with the remote debugger enabled (--debugger on the command
line, or Settings > Tools > Developer Tools > Allow remote debugger) and note
the port it's listening on (shown in that same settings screen, and logged at
startup).

Letting wsdbg start PPSSPP Copy Section

For headless scripting, --launch removes all of that. It starts PPSSPP, learns the debugger port
from its output, connects once the socket accepts, and kills it again on the way out:

wsdbg --sync --compact --quiet --launch ./PPSSPPHeadless.exe --vsh --cpu=interpreter --graphics=vulkan < script.txt

--launch takes the executable and all of its arguments, so it has to come last - everything after
it belongs to PPSSPP, and wsdbg's own flags go before it. --debugger=0 is appended unless the
arguments already ask for a debugger port, so the OS picks a free one and nothing has to agree on a
port number in advance. PPSSPP's output is forwarded to wsdbg's stderr, separate from the protocol
messages on stdout, so 2>emu.log keeps them apart.

This replaces the wrapper script the same job used to need: no launching in the background, no
polling a log file for the port (a race - you can attach to a previous run that still holds one),
no fixed sleep before connecting, and no leftover emulator processes, which --timeout's
wall-clock budget otherwise leaves running for as long as it says.

Interactive REPL - type an event name and key=value params, get responses
and broadcasts (log messages, stepping notifications, etc.) printed as they
arrive:

cargo run -- 12345
> game.status
-> (ticket 2) {"event":"game.status","ticket":2}

<- {
  "event": "game.status",
  "game": null,
  "paused": false
}

One-shot mode - send a single event and exit as soon as its reply arrives, handy
for scripting:

cargo run -- 12345 gpu.stats.get
cargo run -- 12345 cpu.setReg thread=0 name=4 value=1000
cargo run -- 12345 --raw '{"event":"cpu.evaluate","expression":"pc"}'

The reply is matched by ticket, so this returns in milliseconds rather than
padding every invocation with a fixed sleep. --wait (default 10s) is only the
upper bound before it gives up and exits non-zero. Pass --wait-all to go back
to "print everything that arrives for --wait seconds", which is what you want
when watching broadcasts (log lines, gpu.stats.feed) rather than asking a
question.

An error reply carrying the request's ticket makes it exit non-zero too (with --wait-all,
once the interval is up).

Type :help in the REPL for a quick reminder, :quit to disconnect.

Scripting a multi-step sequence Copy Chapter

Piping several commands into the REPL ((echo cmd1; echo cmd2; ...) | wsdbg PORT) sends them all
immediately by default - nothing waits for a response before moving to the next line, so scripts
traditionally needed sleep N between commands to guess how long each one takes. Pass --sync
to remove the guessing: each line blocks until its own response arrives (matched by ticket) before
the next line is read, and for cpu.resume/cpu.stepInto/cpu.stepOver/cpu.stepOut/
cpu.runUntil/cpu.runUntilTime/cpu.nextHLE it also waits for the following cpu.stepping
broadcast - the actual "the CPU stopped again" signal those commands imply. Everything still
prints as it arrives; this only changes when the next line gets sent. A breakpoint that never
trips would otherwise hang the script forever, so it gives up after --sync-timeout seconds
(default 30), reports it, and makes the run exit non-zero.

An error reply to a line doesn't stop the script, but makes the run exit non-zero at the end.

Matching is by ticket, always - --sync never waits for "whatever message arrives next", which is
what used to quietly desynchronise a script. So prefer the key=value form for nested parameters
too: values are parsed as JSON, and single quotes keep the inner double quotes intact, as in
input.buttons.send buttons='{"cross":true}'. A raw JSON line is sent exactly as written, so it's
waited for only if you gave it a ticket;
without one there is nothing to match and --sync moves straight on to the next line. Raw lines
are rejected up front, rather than sent and left to fail somewhere downstream, if they aren't valid
JSON, aren't an object, have no string event, or carry a ticket that isn't an integer.

(
  echo 'cpu.breakpoint.add address=134348800 enabled=true'
  echo 'cpu.resume'
  echo 'cpu.getAllRegs'
) | cargo run -- 12345 --sync

Script directives Copy Section

A script often needs to wait for something that isn't a direct response to the line before it.
Doing that by splitting the script across several wsdbg invocations costs a process, a TCP
connection and a handshake per pause, which is slow enough to matter - a polling loop built that
way took minutes per run. These run inside the one session instead:

--compact prints one line per message (<- event {json}) instead of pretty-printed JSON, and
drops the banner and prompt - much easier for a shell to grep. wsdbg exits non-zero if a :wait
timed out, so a script can be checked without parsing its output at all.

A complete repro - boot, get several seconds in, step, inspect - in one file and one connection:

# hand this to: wsdbg PORT --sync --compact --quiet < script.txt
:echo === run to 1.5s of emulated time ===
cpu.runUntilTime us=1500000
cpu.status
:echo === step twice ===
cpu.stepInto
cpu.stepInto
:quit

Don't add :wait cpu.stepping after cpu.runUntilTime there (an earlier version of this
example did). Under --sync those commands already wait for the cpu.stepping that follows, so an
explicit :wait blocks for a second one that never arrives and burns the entire
--sync-timeout. It is a nasty failure to diagnose, because the emulator has already stopped
exactly where you asked: the run just sits there, and a script written with --sync-timeout 400
takes seven minutes instead of three seconds while looking like a slow boot. :wait is for events
nothing else is waiting on - a breakpoint hit during a free run, say.

For the same reason, never put "stepping":true in broadcast.config.set's disallowed:
cpu.stepping is a broadcast with no ticket of its own, and muting it means nothing can ever
observe that a run finished. --quiet above is the safe way to get the same noise reduction - it
disables logger and input only, and wsdbg warns if a hand-written broadcast.config.set mutes
stepping.

cpu.runUntilTime (see docs/WebSocketDebugger.md) is what makes that reproducible: it stops on
the requested emulated microsecond, so the same script reaches the same instruction every run.
Polling cpu.status in a loop instead lands somewhere different each time.

Overview (`assets/lang/README.md`) Copy Section

lang

PPSSPP language ini repository

Thanks for your interest in translating PPSSPP!

• Simply copy en_US.ini file to a new ini file with your language code, or use it to update an existing file with that name.
• To see a list of codes, view this page.

Please note, while translating:

• Ampersands & on the RIGHT side of an equals sign denote an underlined keyboard hotkey.
• The hotkeys are only supported currently in the DesktopUI section, however.
• Example: &File. This will make it so when you press ALT + F on Windows, it'll open the File menu.

Tools

• To remove a translation, use the following (where KeyWord is the key):

  find . -type f -print0 | xargs -0 sed -i /^KeyWord/d

• To change a translation key, use something like this:

  find . -type f -print0 | xargs -0 sed -i /^Key/NewKey

• Before you commit, use git diff to check that you don't delete too much
  or some unrelated key with the same prefix.

Happy translating! Copy Section

Overview (`docs/emu-api/README.md`) Copy Section

PPSSPP Emulator API

ppsspp_emu_api.h is a small, header-only C wrapper around the emulator-only tricks PPSSPP exposes
to homebrew through the "emulator:" device of sceIoDevctl (implemented in Core/HLE/sceIo.cpp,
search for "emulator:").

None of this works on real PSP hardware - always check ppsspp_is_emulator() before relying on
anything else in the header, and keep a working fallback path for real hardware.

C API documentation: https://www.ppsspp.org/docs/development/ppsspp-internals/emu-api/

Raw sceIoDevctl protocol (commands, layouts, quirks): see protocol.md.

Usage Copy Chapter

Just copy ppsspp_emu_api.h into a PSPSDK-based homebrew project and #include it. It's entirely
static inline functions over sceIoDevctl, so there's no library to build or link.

#include "ppsspp_emu_api.h"

if (ppsspp_is_emulator()) {
    ppsspp_send_output_str("Hello from homebrew, running under PPSSPP!\n");
}

Overview (`ext/jpge/README.md`) Copy Section

jpeg-compressor

This directory contains code from
https://github.com/richgel999/jpeg-compressor/tree/aeb7d3b463aa8228b87a28013c15ee50a7e6fcf3
with the following patches:

• https://github.com/richgel999/jpeg-compressor/pull/18

License Copy Chapter

The license of jpgd.cpp/.h and jpge.cpp/.h is either Public Domain or Apache 2.0. Choose whatever you want.

The license for the optional file jpgd_idct.h (and ONLY this file) is Copyright 2009 Intel Corporation:

Permission is granted to use, copy, distribute and prepare derivative works of
this software for any purpose and without fee, provided, that the above
copyright notice and this statement appear in all copies. Intel makes no
representations about the suitability of this software for any purpose. THIS
SOFTWARE IS PROVIDED "AS IS." INTEL SPECIFICALLY DISCLAIMS ALL WARRANTIES,
EXPRESS OR IMPLIED, AND ALL LIABILITY, INCLUDING CONSEQUENTIAL AND OTHER
INDIRECT DAMAGES, FOR THE USE OF THIS SOFTWARE, INCLUDING LIABILITY FOR
INFRINGEMENT OF ANY PROPRIETARY RIGHTS, AND INCLUDING THE WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Intel does not assume any
responsibility for any errors which may appear in this software nor any
responsibility to update it.

Overview (`ext/naett-lib/README.md`) Copy Section

naett /nɛt:/

Tiny HTTP client library in C.

Wraps native HTTP client functionality on macOS, Windows, Linux, iOS and Android in a single, simple non-blocking API.

Using `naett` Copy Chapter

Get the naett.c and naett.h files and throw them into your project. Check out the example for a basic Makefile - based setup.

The library needs to be initialized by a call to naettInit(). On Android, you need to provide a JavaVM* handle in the call to naettInit().
On the other platforms, call with NULL.

See naett.h for reference docs.

Platform implementations Copy Chapter

naett uses the following HTTP client libraries on each platform:

Example Copy Section

#include "naett.h"
#include <unistd.h>
#include <stdio.h>

int main(int argc, char** argv) {
    naettInit(NULL);

    naettReq* req =
        naettRequest("https://foo.site.net", naettMethod("GET"), naettHeader("accept", "application/json"));

    naettRes* res = naettMake(req);

    while (!naettComplete(res)) {
        usleep(100 * 1000);
    }

    if (naettGetStatus(res) < 0) {
        printf("Request failed\n");
        return 1;
    }

    int bodyLength = 0;
    const char* body = naettGetBody(res, &bodyLength);

    printf("Got %d bytes of type '%s':\n", bodyLength, naettGetHeader(res, "Content-Type"));
    printf("%.100s\n...\n", body);
}

CodeWarriorMangling (`docs/CodeWarriorMangling.md`) Copy Section

Metrowerks CodeWarrior C++ symbol mangling (PSP)

Some PSP titles were built with Metrowerks CodeWarrior rather than the SDK's GCC, so their
symbols aren't Itanium-mangled and _Z-based demanglers do nothing with them. PPSSPP
demangles them in Common/Data/Text/Demangle.cpp (DemangleCodeWarrior), which is what makes
the symbol map readable for those games.

The scheme is a descendant of the AT&T cfront mangling, and the basics match the Macintosh C++
ABI. It deviates in enough places that following that document alone produces wrong answers, so
this is a description of what PSP binaries actually contain.

How this was worked out Copy Chapter

From two PSP executables that shipped with intact symbol tables - one small C++ test program,
one large application of about 10,000 symbols - by demangling every symbol and checking the
result against the disassembly and against the bytes each data symbol points at.

Constructs the corpus did not contain are marked (inferred) below. They come from the cfront
scheme, are implemented, and are believed right, but nothing here proves them.

Overall shape Copy Chapter

A mangled symbol is:

<basename> __ [<class>] [<cv>] F <parameters> [_ <return type>]

with the class, the cv-qualifiers, the F and everything after it all optional. A few examples,
building up:

The last one has no F, so it isn't a function at all - it's a static data member, and there is
no parameter list to print. A name with neither a class nor an F is not mangled.

Finding the separator Copy Section

The __ separator is genuinely ambiguous. A base name can itself start with underscores
(__SetupFrameInfo__FP12ThrowContext...), contain a __ of its own
(__TableUnit__SetValue__5shTbbF...), and plain C code in the same binary is full of names
like I3dCacheManager__GarbageCollect that are not mangled at all.

There is no way to resolve this from the grammar; PPSSPP tries every __ in the symbol and keeps
the first split whose right-hand side parses completely. Only if none does will it accept a split
whose parameters didn't decode - and then only when a class qualifier is present, because
otherwise every C name with a double underscore in it decodes as a garbage function signature.

Names Copy Chapter

An identifier is written as its length in decimal followed by its characters: 6KzUtil.

A qualified name is Q<count> followed by that many identifiers: Q23std9exception is
std::exception (2 components, 3std and 9exception). The count is a single digit; ten or
more components are written Q_<count>_ (inferred).

Template arguments Copy Section

Template arguments are written literally between < and >, inside the length-prefixed name -
the length covers the whole thing, brackets included. (The Macintosh ABI document describes a
__PT prefix instead. PSP binaries do not use it.)

39CList<Q38hlScreen5Brwsr13CContentsUnit>     shList::CList<hlScreen::Brwsr::CContentsUnit>

Here 39 is the length of CList<Q38hlScreen5Brwsr13CContentsUnit>. Each argument is either a
mangled type, or a plain integer for a non-type parameter, separated by commas:

They nest, so a parser must match brackets rather than scanning for the next >, and split
arguments only on top-level commas.

A function template puts its arguments in the base name instead, and - unlike a normal function -
encodes its return type after a trailing _:

sort<Pf>__3stdFPfPf_v          void std::sort<float *>(float *, float *)

Special base names Copy Section

Operator codes are the cfront set: nw dl nwa dla for new/delete, pl mi ml dv
md for arithmetic, apl ami amu adv amd aad aor aer als ars for the compound
assignments, eq ne lt gt le ge for comparisons, aa oo nt for logic, ad or
er co ls rs for bitwise, and as pp mm cl vc rf rm cm for
= ++ -- () [] -> ->* ,.

So __as__9ANIMEDataFRC9ANIMEData is ANIMEData::operator=(const ANIMEData &).

Types Copy Chapter

Type codes are read left to right, each one modifying what follows.

PCc is const char *; CPc is char * const. A pointer to a function or an array needs the
declarator wrapped rather than a * appended - PFi_i is int (*)(int), and PPFv_v is
void (**)().

Two forms back-reference an earlier parameter of the same function (inferred):

So foo__FPCcUiN21 is foo(const char *, unsigned int, const char *, const char *).

cv-qualifiers on the function Copy Section

A C or V sits between the class and the F, and qualifies the member function rather than a
parameter: InitRun__Q28shCamera11TStillParamVFv is
shCamera::TStillParam::InitRun() volatile.

Compiler-generated symbols Copy Chapter

CodeWarrior emits a family of symbols for things with no C++ name of their own. These wrap a
mangled name rather than being one, and none of them are described in the ABI document.

The trailing @<n> on @STRING@ and @LOCAL@ is a discriminator, present only when a function
has more than one of them - so a parser has to treat it as optional, and must not mistake the
@ before a @LOCAL@ variable name for it.

@<n>@ thunks really are thunks: the one above is 8 bytes of code that does addiu a0, a0, -12
and jumps, i.e. adjusts this for a secondary base. @STRING@ symbols point at ordinary string
data - usually the __FILE__ an assertion expanded to.

Other decorations Copy Chapter

Two more show up inside otherwise ordinary names. Neither needs decoding, but both are worth
recognising:

• <name>$<digits><file> - a class or variable with internal linkage, tagged with where it was
  declared: ClutScreen$11229hl_cplayer_effect_renderer_cpp. These make for very long symbols,
  since the tag repeats everywhere the type appears.
• <len>@unnamed@<file>@ - used as a qualifier for file-scope statics, i.e. an unnamed namespace.
  ARWMENU_MODEL_NAME__34@unnamed@hl_editor_arrow_menu_cpp@ is a data symbol in one.

The hidden destructor parameter Copy Chapter

The mangling describes the source-level signature, not the generated one. __dt__3SonFv
demangles to Son::~Son(), and that is the right answer for a demangler - but the function the
compiler emitted takes a second argument, and anything that turns a demangled name into a
function signature (a decompiler, a debugger's parameter view) will be wrong about it.

CodeWarrior emits one destructor per class rather than the two or three the Itanium ABI clones,
and distinguishes the cases with a flag. On PSP that flag is a short in a1, and the
destructor returns this in v0. So the real signature is:

Son *__dt__3SonFv(Son *this, short flag);

Decompiled from a real one, the body is:

Son *__dt__3SonFv(Son *this, short flag) {
    if (this) {                       // destructors are null-safe
        ... restore vtable pointers, destroy members ...
        __dt__3DadFv(this + 12, 0);   // base subobjects get 0
        __dt__3MomFv(this, 0);
        if (flag > 0)                 // "blez" - only a positive flag frees
            __dl__FPv(this);          // operator delete
    }
    return this;
}

The values that actually get passed, counted over the call sites in a retail binary:

0 and -1 are a caller-side distinction: the destructors examined here only test the sign, so
both simply mean "don't free", but the compiler still passes 0 specifically when destroying a
base subobject and -1 everywhere else. Treat 0 as "this call is destroying me as somebody's
base" when reading a call site, even though the callee can't tell.

Constructors in these binaries take only this (and also return it).

Note that the vtable slot holds this same function, flag and all, which is how CodeWarrior gets
away without separate deleting and non-deleting destructors: a virtual delete passes 1 through
the vtable.

Hazards Copy Chapter

• A truncated name is unrecoverable. Some symbol tables cap names (127 characters is a common
  limit), and templates blow past that easily. Once a name is cut, the length prefixes no longer
  match what's left and nothing after the cut can be trusted - better to reject the symbol than
  to print a plausible-looking guess.
• Not everything with a __ is mangled. C code linked into the same binary uses __ as a
  word separator freely. Requiring a class qualifier before accepting a partial parse is what
  keeps I3dClut__FlushCache from turning into I3dClut(long, ...).
• e is a real parameter, not a parse failure. Printf__Q26shFont4FontFiiPCce ends in
  varargs; (int, int, const char *, ...) is the correct answer, not a partial one.

DebuggerThreading (`docs/DebuggerThreading.md`) Copy Section

Debugger threading model (Core_RunOnCPUThread / g_frameMutex)

Which thread may touch CPU-thread-owned debugger state (breakpoints, symbol map, registers, memory,
kernel threads), and in which order the locks have to be taken. Read this before touching
Windows/Debugger/*, Core/Debugger/WebSocket* or anything else that reaches into core state from
outside the CPU thread.

CPU-thread-owned debugger state (g_breakpoints, g_symbolMap, g_disassemblyManager, registers,
memory, kernel threads) used to be touched directly from other threads (the WebSocket handler
thread, and the legacy Win32 debugger's message-pump thread) with no synchronization. Two
mechanisms now exist for doing this safely - pick based on whether you're mutating or just reading:

• Core_RunOnCPUThread(func) (Core.h/Core.cpp) - queues func to run on the CPU thread,
  blocking the caller until it's done. Use for mutations (breakpoint add/remove, register/memory
  writes, symbol map edits, stepping requests, thread wake/kill). Drained at the top of every
  Core_RunLoopUntil() iteration, so it's reached whether the CPU is running or stepping/paused;
  runs immediately if already called from the CPU thread. Two hard rules learned the hard way:
  never put a modal Win32 dialog call (MessageBox, DialogBoxParam, InputBox_GetString,
  SomeDialog::exec()) inside the queued lambda - it would block the CPU thread on user input, so
  split the function into "read/decide", "show modal", "mutate" pieces instead. And never call
  SendMessage() targeting one of your own GUI-thread windows from inside the lambda - the calling
  GUI thread is blocked waiting on the CPU thread rather than pumping messages, so a cross-thread
  SendMessage() back to it deadlocks; keep such calls outside the lambda instead.
• g_frameMutex (Core.h/Core.cpp) - a plain std::mutex, held by NativeFrame()
  (UI/NativeApp.cpp) only across the span where it actually touches that state
  (g_breakpoints.Frame() through g_screenManager->render() - where Core_RunLoopUntil()/actual
  CPU stepping happens - through runImDebugger/renderImDebugger), not across input handling or
  the present/frame-pacing waits. Use for reads invoked very frequently (WM_PAINT, a list
  reload triggered on every debugger-state-changed notification) where routing through
  Core_RunOnCPUThread would be too slow/heavy. The legacy Win32 debugger windows do this now -
  see CtrlRegisterList::onPaint, CtrlDisAsmView::onPaint, CtrlMemView::onPaint,
  CtrlBreakpointList::reloadBreakpoints, CtrlThreadList::reloadThreads, etc. in
  Windows/Debugger/*.cpp.

Architecture fact that makes g_frameMutex correct: regardless of graphics backend, NativeFrame()
(and thus CPU emulation via Core_RunLoopUntil(), and the Dear ImGui debugger) always runs on the
same thread - see RunGraphicsLoop() in Core/EmuThread.cpp, which every platform goes through
(Windows and headless via MainThreadFunc(), Android from its render loop thread). When a backend
needs its own thread for actual graphics API calls (GraphicsContext::NeedsSeparateEmuThread() -
true for OpenGL, SDL, headless, libretro, Qt; false for D3D11/Vulkan on Windows), the original
thread stays behind purely to pump graphicsContext->ThreadFrame() (i.e. just executes queued
graphics API calls), and a newly spawned thread takes over NativeFrame()/game logic/CPU duty. So UI/ImDebugger/*.cpp is always
safe to read/write this state directly, without either mechanism - it's always on the same thread
as Core_RunLoopUntil(). The legacy Win32 debugger is different: its dialogs are pumped by the
original WinMain message-loop thread, which is a genuinely separate OS thread from whichever
thread ends up running NativeFrame()/CPU, regardless of backend (this split happens one level
above the NeedsSeparateEmuThread() branch) - that's the whole reason it needed this mechanism.

Update (2026-08-08): both BreakpointManager's and SymbolMap's internal mutexes have been
removed after auditing every touchpoint across the codebase (WebSocket subscribers,
Windows/Debugger/*.cpp, Windows/MainWindowMenu.cpp/Windows/MainWindow.cpp main-window menu
items, Core/Core.cpp's free-threaded Core_Break/Core_Resume, UI/ImDebugger/*.cpp,
JIT/interpreter backends, Core/Debugger/MemBlockInfo.cpp) and confirming each is covered by one of
the two mechanisms above or is already on the CPU/NativeFrame thread. Notably, Windows/main.cpp's
SortSymbols() calls (fired from System_Notify(BOOT_DONE)/System_Notify(SYMBOL_MAP_UPDATED))
turned out to already be safe without any change - both notifications are only ever fired from the
CPU/NativeFrame thread (UI/EmuScreen.cpp, Core/HLE/sceKernelModule.cpp), despite an old comment
there claiming reliance on the (now-removed) internal lock. Qt/mainwindow.cpp/Qt/QtMain.cpp
still poke at g_symbolMap directly and unguarded on the Qt UI thread - a pre-existing issue,
deliberately left alone since Qt isn't a maintained backend and is slated for removal; removing the
lock doesn't change SymbolMap's public API, so Qt still builds, just without that safety net.
GPU/Common/GPUDebugInterface.cpp (GE debugger expression evaluation) and Core/MemFault.cpp
(crash-time diagnostics) also touch g_symbolMap and were deliberately not audited this round -
different subsystem / best-effort-by-nature respectively, follow up if they ever come up.

Two more things found while doing this:

• Core_RunOnCPUThread()'s queue is only drained where Core_RunLoopUntil() runs, which requires
  a game to be loaded (it's called from EmuScreen::render()). Calling Core_RunOnCPUThread()
  while at the main menu with nothing loaded used to hang forever. Fixed by also calling the
  (now public) Core_ProcessCPUQueue() directly from NativeFrame(), right before
  g_screenManager->render(), inside the same g_frameMutex-locked span - so it always runs, not
  just while a game is active.
• Lock-ordering rule: because Core_ProcessCPUQueue() is called from inside NativeFrame()'s
  g_frameMutex-locked span, any Core_RunOnCPUThread() lambda that itself tries to lock
  g_frameMutex (directly, or indirectly - e.g. by calling something like
  CDisasm::NotifyMapLoaded(), which locks it internally) will deadlock. Keep such calls outside
  the queued lambda, same as the modal-dialog and SendMessage() rules above.

Lock ordering: `g_frameMutex` before `Core_LockAgainstShutdown()`, always Copy Chapter

Core_LockAgainstShutdown() / CoreShutdownLock (a recursive_mutex, g_shutdownLock in
Core/Core.cpp) is held across CPU_Shutdown() and Memory::Reinit(), i.e. while the core is
going away. Take it on any thread other than the CPU thread before reading core state - emulated
memory, the symbol map, kernel objects - so none of it is freed mid-read. It was called
Memory::Lock() and only covered the memory map; the name misled people into thinking it was about
memory access. When a function needs both it and g_frameMutex, take g_frameMutex first.

The CPU thread's order is structural and can't be changed: NativeFrame() wraps everything below it
in g_frameMutex, and several things under there lock memory - Core_ProcessCPUQueue() running a
queued WebSocket handler, and runImDebugger() -> ImMemView -> DisassembleRange(). So the
GUI-thread side is the one that has to match. (Getting it backwards deadlocked for real: a paint
handler held the memory lock and waited for g_frameMutex while the CPU thread did the reverse.)

Also: a Core_RunOnCPUThread() callback does not need Core_LockAgainstShutdown() - teardown only happens
on the CPU thread itself (Memory::Shutdown() via CPU_Shutdown() <- PSP_Shutdown(), all callers
on that thread; Memory::Reinit() from Memory::DoState() on savestate load). Don't add one.

The general rule behind both of these: never make the CPU thread wait for a thread that is (or may
be) waiting on the CPU thread. Core_RunOnCPUThread() blocks until the CPU thread drains the
queue, so anything the CPU thread might block on must not be held across such a call. The WebSocket
debugger's lifecycleLock hit exactly this - it was held across a whole event handler, and the CPU
thread took it in Core_NotifyLifecycle(STOPPING), so stopping a game with a debugger request in
flight hung both threads. That lock is gone now; the rule is what's left of it.

The WebSocket debugger no longer has any lock guarding it against startup/shutdown, and must not
grow one back. The invariant instead is: a handler either does its emulator-state access inside
Core_RunOnCPUThread() - which serializes it against startup and teardown, since those run on the
CPU thread too - or touches only state that carries its own lock (the log ring buffer, ctrlMutex,
GPUStepping's pause-action rendezvous). When adding a subscriber, put the core access in the
queued callback, including the isAlive()/IsValidAddress() checks: answering those outside it
just means acting on an answer that may already be stale.

game.* and cpu.stepping/cpu.resume are pushed rather than polled - WebSocketDebuggerTick()
(called from Core_ProcessCPUQueue()) notices the transition on the CPU thread, formats the event
there, and drops it in a per-connection mailbox. Don't add a broadcaster that reads emulator state
from the connection's own thread; produce the event on the CPU thread and push it instead.

The Win32 debugger's GUI-thread readers do still need it, so don't "simplify" those away:
teardown is not yet fully inside the g_frameMutex span. EmuScreen::render()'s PSP_Shutdown() is
inside it, but the ones in EmuScreen::sendMessage() (REQUEST_GAME_RESET, loading a new game) run
from g_screenManager->sendMessage() in NativeFrame(), which sits above where the guard is
taken. Closing that hole - moving those shutdowns inside the span, or deferring them to render time -
is the prerequisite for dropping the shutdown lock from the debugger entirely.

Painting-problem design history, in case a similar tradeoff comes up elsewhere: routing every paint
through Core_RunOnCPUThread was rejected as too slow for something invoked continuously. A
per-window snapshot/cache with a per-row-rechecked Core_IsStepping() guard was tried first and
worked, but still had a narrow TOCTOU race (the CPU could resume between the check and that row's
reads) and the per-row-recheck pattern itself wasn't liked. Settled on g_frameMutex instead -
simpler, and actually race-free rather than just lower-risk. CtrlRegisterList shows live values
always now, grayed out by color alone (not cached) while the core is running, since a
constantly-moving value isn't meaningful to read closely anyway.

HLEModules (`docs/HLEModules.md`) Copy Section

Adding HLE modules

How the HLE module tables work, the savestate-compatibility rules for adding to them, and the list of
build files a new source file has to be added to.

HLE module implementations live in Core/HLE/sce<ModuleName>.cpp / .h (e.g. sceOpenPSID.cpp, scePauth.cpp are good
small examples to copy from). A module is a const HLEFunction <name>[] table of
{nid, &WrapX_YYY<func>, "funcName", retChar, argString} entries, registered via
RegisterHLEModule("<name>", ARRAY_SIZE(table), table) inside a Register_<name>() function declared in the header.

• FunctionWrappers.h has generic WrapX_YYY<func> templates for common signatures (return type X, args YYY) - add new
  wrappers there if you need a new signature.

• A function that needs the CPU (registers beyond its arguments, the PC for a log line, PARAM()/RETURN()) takes
  MIPSState *mips as an extra first parameter, and the wrapper passes in the state the syscall runs on. Use that
  rather than currentMIPS. Calling such a function directly, or through hleCall, means passing a state yourself.

• Format string legend for the retmask/argmask chars: x = u32 (shown as hex), i = int/s32, f = float, X = u64,
  I = s64, v = void.

• For functions of genuinely unknown purpose (only known by NID), name them <moduleName>_<NID> and stub them with
  return hleLogError(Log::HLE, 0, "UNIMPL"); - an established pattern (see scePauth.cpp, sceOpenPSID.cpp).

• New modules must be registered at the very end of the registration function in Core/HLE/HLETables.cpp (look for
  the // add new modules here. comment near the end of that function) - not inserted alphabetically/logically among
  the existing Register_*() calls. Module registration order affects numeric IDs used in savestates, so inserting a
  new module earlier in that list would break save-state compatibility for saves made with older builds.

• The same rule applies one level down: new entries in an existing module's const HLEFunction <name>[] table must
  go at the very end of that array too, never inserted alphabetically or next to a "related" existing entry. A
  resolved import gets written directly into guest RAM as a syscall opcode that encodes the entry's array position
  (modulenum<<18 | funcindex<<6, see GetSyscallOp() in Core/HLE/HLE.cpp), and a savestate captures that opcode
  verbatim - inserting a new entry before an existing one shifts every later entry's index, so loading an older
  savestate after such a change resolves those later entries to the wrong function. Adding an all-new table (a new
  module, including a new alias-module ..._driver[] variant of an existing one) is unaffected, since no old
  savestate could reference indices into a table that didn't exist yet - only existing tables need this care.

• Remember to add any new .cpp/.c file to seven places: Core/CMakeLists.txt, Core/Core.vcxproj,
  Core/Core.vcxproj.filters, UWP/CoreUWP/CoreUWP.vcxproj, UWP/CoreUWP/CoreUWP.vcxproj.filters,
  android/jni/Android.mk, and libretro/Makefile.common. New .h files need the first five (everything except
  Android.mk/Makefile.common, which are plain compiled-source lists so headers don't go in them). Double check
  each by hand against how an existing neighboring file (e.g. sceVaudio.cpp) is listed. Forgetting the UWP entries
  is easy to miss - the CMake and MSBuild (Core.vcxproj) builds both succeed silently, and it only surfaces as a
  UWP-only build failure (this has happened for real: Core/MIPS/InterpreterDispatch.cpp landed without its UWP
  entries, and the omission wasn't caught until someone actually built the UWP project). Note: New files in the
  unittest project have to be updated in the unittest part in android/jni/Android.mk.

  Both the CMakeLists.txt change (via a Linux/Mac build) and the Core.vcxproj/UWP changes (via MSBuild on Windows)
  can actually be build-tested, not just eyeballed - see Building and testing for the main Windows solution,
  and for UWP specifically:

  powershell Copy

  $installPath = & "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe" -latest -property installationPath
  $msbuild = "$installPath\MSBuild\Current\Bin\MSBuild.exe"
  & $msbuild "UWP\PPSSPP_UWP.sln" /t:CoreUWP /p:Configuration=Debug /p:Platform=x64 /m

  (only android/jni/Android.mk and libretro/Makefile.common genuinely can't be build-tested here - see
  Building and testing for what verification is possible for those.)

POPS (`docs/POPS.md`) Copy Section

PS1 EBOOTs (POPS)

PS1 games on the PSP are EBOOT.PBPs run by the firmware's PS1 emulator. PPSSPP runs the firmware's own
modules for them, so it needs an installed 6.60 or 6.61 firmware (flash0:/kd/popsman.prx); without
one, booting a PS1 EBOOT fails with a message saying so. --unpack-updater DIR EBOOT.PBP installs one from an
official updater.

The code is Core/HLE/PopsBoot.cpp (the boot, the ME, the patches) and Core/HW/PopsMMIO.cpp (the
hardware registers the manager uses). The patches are for the 6.60 and 6.61 popsman.prx and pops_0Xg.prx,
whose code is the same (and the same at the patched places for the PSP-1000 and PSP-2000 models). The
manager's is checked when it's loaded. Offsets below are from the module's base.

The boot Copy Chapter

On hardware the kernel reboots into its POPS configuration, which starts the POPS manager
(popsman.prx) and a few user modules, and the kernel's init then calls scePopsManLoadModule(path, 0),
which loads pops_0Xg.prx (the emulator) for the PSP model. Load_PSP_POPS does the same without the
reboot: it loads the manager, the user modules (libfont_hv, pafmini, libpspvmc) and a helper thread
that makes the init's call. InitForKernel reports a memory stick boot in the POPS key configuration.

The emulator draws through the GE and plays through the Media Engine. The manager drives both directly:

• GE. The emulator keeps one display list stalled and the manager extends it each frame by writing
  the stall register (0xBD40010C), then waits for the FINISH interrupt. These map onto the HLE GPU's
  current list.
• ME. A PS1 boot always gets the emulated Media Engine (Core/MIPS/MeCore.cpp), which runs the
  manager's code as the PSP does. The manager copies a bootstrap into the boot page (0xBFC00040),
  releases the ME's reset through sceSysreg_driver and waits for an acknowledgement in the mailbox
  (0xBFC007F0). Sony's own ME firmware isn't booted for it. The ME loop (+2F88) sets up the audio block
  (0xBE000000) and then, once per sample, sleeps in halt until the FIFO has room (interrupt source 12,
  a level: the loop never enables interrupts nor acks them), calls the emulator's mixer (on the ME) and
  writes the sample. The FIFO plays at 44.1kHz in emulated time, and its samples are mixed into the
  output (MeMMIO::AudioMix). The loop's calls to the cache functions do nothing on the ME.

Neither the lock the emulator shares with the ME (pops +5C) nor its SPU interrupt pacing is patched: with
two CPUs they should work as on hardware. Vib-Ribbon, which streams its stage music through the SPU's
capture buffers and asserts when those interrupts come at the wrong PS1 time, hasn't been tried.

Unresolved imports remain, mostly sceSyscon_driver and power management. The manager carries on
without them.

Rendering Copy Chapter

The emulator keeps the PS1's 1024x512 VRAM at 0x04000000 as one 16-bit framebuffer, and reads and writes
it outside where it draws. It's a fixed framebuffer: created whole, from memory, and uploaded without
filtering. Its 24-bit video is unpacked three bytes per pixel into 0x04100000, which is kept at 1x. It
draws sprites on pixel centers, which above 1x read their neighbours' texels, so those are moved back half a
pixel. And it builds video frames by ORing passes together, so draws whose logic op is done in the shader
are drawn one at a time.

Store and converted games Copy Chapter

A store game's disc image is a PGD. The manager's license check (+266C) needs the game's license and
activation, so it's replaced: the version key comes from the PGD header, as CFW's popcorn plugin does.
The MACs are checked with the real algorithms (sceAmctrl_driver, on libkirk).

A converted EBOOT (popstation and similar) has a plain disc image of DEFLATE blocks and no MACs. As popcorn
does, the emulator's decoder calls go to an inflate, its CD audio index check takes the full-length branch,
and the two MAC checks (+0A28, +0AB8) pass.

For any EBOOT, also as popcorn does: the manual's name check passes, and an ICON0 the emulator can't use
(anything but an 80x80 PNG, such as a missing one or a PSP game's 144x80 one, which crashes it) reads as a
blank 80x80 one.

Testing Copy Chapter

PPSSPPHeadless --memstick=MEMSTICK --graphics=vulkan --timeout-wall=60 --timeout-emulated=60 \
    --press=30:0x8,40:0x4000 --screenshot-at=55:shot.png --dump-audio=out.wav EBOOT.PBP

The HOME button opens the emulator's menu. Savestates work.

Not done Copy Chapter

• Other firmware versions. CFW's popsloader runs POPS from 3.02 to 6.60, and its tables show what differs
  between them: the offsets patched here, and the kernel NIDs the modules import.
• The anti-LibCrypt word some PAL games need in a converted image (PSISOIMG + 0x12B0). ARK-4's popcorn has
  a table of them by disc ID, switched off. Converting tools can patch the image instead.
• ARK-4's per-game CONFIG.BIN next to the EBOOT, copied over the image's config (PSISOIMG + 0x420).
• A byte popcorn changes in reads of converted images (0x41B, from 0x27 to 0x55 when 0x41B-0x41E read
  27 19 22 41) without knowing why.

PsarFileFormat (`docs/PsarFileFormat.md`) Copy Section

The PSAR archive format (PSP firmware updaters)

An official PSP firmware updater carries the whole firmware image in a PSAR archive. PPSSPP can
walk one and extract the files out of it without emulating the updater, which is what
Core/Util/PSARUnpack.cpp does. The main use is getting flash0:/font - the PGF system fonts -
out of an updater the user already has, since most UMDs carry one.

This document is what was learned reading 43 different firmware versions, from 1.50 to 6.61. It's
a description of the format rather than of the code; the code is the same shape but has the error
handling.

Where an updater lives Copy Chapter

The archive turns up in three shapes, all of them the same bytes once you find them:

A disc updater directory also holds EBOOT.BIN (the updater executable, a bare ~PSP PRX, of no
use to us) and PARAM.SFO. That SFO is worth knowing about: its TITLE reads
"PSP™ Update ver 3.95", so the firmware version can be read without decrypting anything,
which is cheap enough to check a whole game library with. DISC_ID is MSTKUPDATE and CATEGORY
is MG.

Of 589 discs scanned across two libraries, 473 carried an updater.

Archive header Copy Chapter

+0x00  u32   "PSAR" magic (0x52415350)
+0x04  u8    version. 1 = "oldschool" (see below), 2 and 3 are the common ones
+0x08  u32   total length of the records
+0x20  u32   0x2C333333 if this archive is already decrypted, otherwise part of the ciphertext

The length at +0x08 matters: archives have a few bytes of padding after the last record (16 and 32
bytes in the two checked), and a walk that goes by file size instead will try to decode that
padding as a record and report a spurious failure at the very end.

The marker at +0x20 only appears in archives some other tool has already decrypted. In an original
updater those bytes are ciphertext and will not match.

Records Copy Chapter

The archive is a flat sequence of records starting at +0x10. There is no index - you find entry
n+1 by decoding entry n and adding up its sizes. Each record is:

[ 0x150 bytes  encryption header ]     <- absent if the archive is pre-decrypted
[ 0x110 bytes  entry description  ]
[ variable     file contents      ]    <- has its own 0x150 header, same as above

Call the header size overhead: 0x150 normally, 0 for a pre-decrypted archive.

Decoding a block Copy Section

Every encrypted block - entry descriptions and file contents alike - is decoded the same way:

1. Demangle. The 0x130 bytes at block+0x20 are AES-128-CBC encrypted on top of everything
   else. Decrypt them with KIRK command 7 (KIRK_CMD_DECRYPT_IV_0), key seed 0x55, IV zero,
   writing the result back over block+0x20. This step is skipped for version 1 archives.

   The point of it is that it hides the PRX tag: you cannot tell how to decrypt the block until
   you have done this.

2. PRX decrypt. The block is now an ordinary PRX blob, with its tag at block+0xD0. Run it
   through the normal PRX decrypter (pspDecryptPRX). The tag official updaters use is
   0x0E000000; 0x06000000 also appears in the wild.

   Note that 0x0E000000's key is stored unscrambled, unlike almost every other key in
   PPSSPP's tag table, so it needs the kirk7 pass applied before use - that's what the
   scrambleKey flag on TAG_INFO is for.

One wrinkle worth knowing: the decrypter reads a little past the end of the block and uses what
it finds there, so a decoder should hand it about 16 bytes of slack from the archive. The last
record ends flush with the end of the archive and has no slack to give; zero-filling it there is
fine, but zero-filling it everywhere breaks every archive that does have those bytes.

Entry description Copy Section

0x110 bytes once decoded:

+0x004  char[]  entry name, NUL padded (see "Naming" below)
+0x100  u32     always zero. If it isn't, you've lost your place in the archive
+0x104  u32     size of the contents block that follows, including its 0x150 header
+0x108  u32     uncompressed size of the file. 0 means this entry is a directory

A directory entry still has a contents block to skip over - advance by +0x104 either way.

The first two records Copy Section

The first record (at +0x10) is not a file. Decoded, it holds a text string at +0x10 whose last
comma-separated field is the firmware version, e.g. ...,6.61. That's the authoritative version
for choosing decryption keys further down.

There is a second record after it whose length isn't recorded anywhere. In practice it is
overhead + 100, or overhead + 144 on 2.7x, or overhead + u16 at +0x90 of the first record.
Try them in that order and take the first that decodes. Round the result up to a multiple of 16
before advancing. Version 1 archives don't have this record at all.

Contents Copy Chapter

The contents block decodes to a compressed stream. Sniff the first bytes:

Across all 43 firmware versions examined, every file in every archive was zlib. KL4E does turn
up on the PSP, but a layer further in: two kernel modules (memlmd_01g.prx and loadexec_01g.prx)
are themselves KL4E-compressed inside their own PRX, which is a separate problem from this one.

Naming Copy Chapter

This is the part that changed most across firmware generations, and the part most likely to catch
out an implementation tested against only one updater.

1.x and 2.x - real paths Copy Section

Entries are named outright: flash0:/vsh/resource/opening_plugin.rco, flash1:/registry,
ipl:/psp_nandipl.bin. Nothing else is needed. Note ipl: - it is not enough to recognise
flash0: and flash1:; better to treat any <device>:/ shape as a real path.

3.x - grouped short names Copy Section

Entries are named <group>:<5 digits>, where the group is com for files every model gets, or
01g, 02g, ... for one model's. <group>:00000 is that group's file list, and the rest of
that group's entries are looked up in it by their number alone (entry com:00004 is key 00004).

5.x and 6.x - flat short names with per-model lists Copy Section

Entries are a bare 5-digit number. The low numbers are file lists, one per PSP model
(00001 = 01g, 00002 = 02g, ...) and the rest are files that any of the lists may name.

Which numbers are lists is not fixed. 6.61 uses 1-11; 6.00 has real files at 00010-00012.
Since a list always decrypts successfully (the PRX layer inside validates a hash), the robust rule
is: try to decrypt a candidate as a list, and if that fails, treat it as an ordinary file.

File lists Copy Section

A list decodes to plain text, one shortname<separator>path per line. Both the separator and the
path style depend on the generation:

Worth normalising to one form early - otherwise a filter like flash0:/font/ silently matches
nothing on a 3.x archive.

List encryption Copy Section

The lists are encrypted on top of everything else, with DES - the tables in the reference
implementations are DES's own: a 56-entry PC-1, a 48-entry PC-2, eight 64-entry 4-bit S-boxes, a
32-entry P permutation, and textbook IP/FP bit-shuffling constants.

It is DES-CBC decrypt, with the key assembled from two 32-bit words as (high << 32) | low in
big-endian byte order, and an IV alongside them. There is one such set per firmware series, and
which one applies is chosen from the version string in the archive's first record:

A sixth set exists that nothing selects by version. The values themselves are in kTableKeys in
Core/Util/PSARUnpack.cpp and aren't repeated here.

Underneath the DES layer is an ordinary PRX blob, so run the result through pspDecryptPRX as
well; what comes out of that is the text.

A good check while implementing: after the DES pass but before the PRX pass, the u32 at +0xD0
should be a recognisable PRX tag. A wrong key gives a random value there, so that single word
tells you whether the cipher is right before anything else has to work.

What the archives look like in practice Copy Chapter

Three structural eras, visible in the shape of the output:

A 6.61 archive holds 435 records: 411 files, 17 directories and 7 file lists. Among the files are
295 ~PSP modules, 61 PRF files, 7 encrypted XMB indices (PSPsysGP), and 21 files in
flash0:/font - 19 of them PGF, plus gb3s1518.bwfon and imagefont.bin.

The "Fonts" column above counts files in flash0:/font, not PGFs specifically.

Gotchas, collected Copy Chapter

• Walk by the length at +0x08, not the file size, or the trailing padding decodes as a bad record.
• Stop when fewer than overhead + 0x110 bytes remain rather than when the position passes the
  end - the two differ by exactly one spurious record.
• Give the block decrypter its 16 bytes of slack, but don't require them for the last record.
• Don't assume which entry numbers are file lists; find out by trying.
• Don't assume there are file lists at all - 1.x and 2.x have none.
• ipl: is a device too.
• A 3.x path has no colon; a 6.x path does.

See also Copy Chapter

• Core/Util/PSARUnpack.{cpp,h} - the implementation, and the only consumer of most of this.
• Core/ELF/PrxDecrypter.cpp - the PRX layer every block goes through.
• ext/libkirk - kirk7() is the demangle step.
• PPSSPPHeadless --unpack-updater=DIR unpacks one from the command line;
  --unpack-updater-model=01g..12g picks a model.

SNSystemsMangling (`docs/SNSystemsMangling.md`) Copy Section

SN Systems (SNC / ProDG) C++ symbol mangling (PSP)

A number of PSP titles were built with SN Systems' compiler rather than the SDK's GCC. Its C++
symbols look nothing like the Itanium mangling, and nothing like the cfront-derived one
CodeWarrior uses either - they are much more compact, and encode lengths as letters rather than
digits. PPSSPP demangles them in Common/Data/Text/Demangle.cpp (DemangleSNSystems).

How this was worked out Copy Chapter

From a single PSP executable that shipped with its symbol table intact: 4,662 mangled symbols
out of 11,338, covering an application, an STL, a JPEG decoder and a sound library. Everything
below is attested there except where marked (inferred), which means the code implements it
by analogy with the codes that are attested and nothing in that binary proves it.

The description is complete enough to decode 4,661 of the 4,662. The one holdout is an STL
symbol whose template argument is a reference to a member of another template.

Overall shape Copy Chapter

__0 <kind> <name…> <parameters> [_ <return type>] [<qualifier>]

The kind character says what the symbol is, and - importantly - how many name components to
read, since nothing else delimits them:

__0fLCHeapMemoryFAlloci          CHeapMemory::Alloc(int)
__0FHGetRandv                    GetRand()
__0oLCHeapMemorydtv              CHeapMemory::~CHeapMemory()
__0OnwUi                         operator new(unsigned int)
__0dLCHeapMemoryG__vtbl          CHeapMemory::__vtbl

Names Copy Chapter

An identifier is a letter giving its length, then that many characters. A is 0, so F is
5 and L is 11; lowercase continues the run, with a = 26 up to z = 51.

LCHeapMemory   ->  L = 11  ->  "CHeapMemory"
FAlloc         ->  F = 5   ->  "Alloc"
bMatrixScaleRotationXZYTrans  ->  b = 27

A 5 before a component makes it an enclosing scope, and any number of them can stack up
before the component the kind character called for:

__0f5FsoundMCSoundPlayerPGetPlayerObjectUi
       ^ namespace "sound", class "CSoundPlayer", function "GetPlayerObject"
   sound::CSoundPlayer::GetPlayerObject(unsigned int)

Template arguments Copy Section

7 opens a template argument list and _ closes it. Each argument is a type, or 4 and an
integer for a non-type parameter. They nest.

6KTFixString748D512_                 TFixString<512>
6FTRect7f_                           TRect<float>
6KTFixVector76KTFixString7400Y_4g_   TFixVector<TFixString<128>, 32>

9A refers back to one of the enclosing name's template arguments, 1-based, so 9BA is
the first. The trailing letter appears to be a nesting level and is always A in practice.

__0FDmax7f_RC9BATB_RC9BA    const float & max<float>(const float &, const float &)

Integers Copy Section

Non-type template arguments and array bounds use a compact encoding: a run of 0s, each worth
52, followed by a letter for the remainder.

Values that would need too many 0s switch to an escape: 8, a length letter, then that many
decimal digits. 8D512 is 512 and 8E1024 is 1024.

Operators Copy Section

For kinds o and O the name ends with a two-letter code instead of a length-prefixed
identifier. ct and dt are the constructor and destructor - the class name isn't repeated,
so it has to be taken from the qualifier. nw and dl take an optional trailing a for the
array forms.

Attested: ct dt as eq ne ls nw nwa dl dla. The rest of the usual set
(pl mi ml dv md, the compound assignments, comparisons, cl, vc, rf, …) is
implemented by analogy (inferred).

Types Copy Chapter

Note that a class type in a parameter is introduced by 6, while the symbol's own name isn't -
the kind character has already said a name is coming.

Declarators need wrapping rather than suffixing: PFv_v is void (*)(), PPA0Ms is
short (**)[64], and PM<class>F…_… is ret (Class::*)(args).

Parameter back-references Copy Section

Two forms repeat an earlier parameter of the same function, both indexed 1-based with letters:

__0FKRadixSortSPUiNCBUi
   RadixSortS(unsigned int *, unsigned int *, unsigned int *, unsigned int)

NCB is "two more of parameter 1". Note that T is also the static marker below, so a T
whose following letter isn't a valid parameter index ends the list rather than repeating one.

Return types and qualifiers Copy Chapter

A _ after the parameters introduces the return type. Only templates carry one - the same rule
as the other manglings, since two instantiations can differ in return type alone.

After that, a trailing K marks a const member function. A trailing T marks a static
member function: it appears only on kinds f and o, never on a free function (which wouldn't
need marking), and every member operator new/operator delete in the corpus carries it,
which is exactly the set of member functions that are implicitly static.

One more marker, __S, turns up between the name and the parameters on a couple of template
members. What it means is unknown; it doesn't affect the name, so the demangler skips it.

Compiler-generated symbols Copy Chapter

__TID_ and __T_ are the two halves of the RTTI for one class, and which is which is
inferred from their sizes rather than from anything that names them. Both take a type rather
than a symbol, and - unlike everything above - spell an enclosing namespace as just another
component instead of marking it with a 5:

__TID_DstdIbad_cast    type id for std::bad_cast
__TID_v                type id for void

Secondary vtables for multiple inheritance use a different scheme again, with decimal lengths:
__vtbl___10CRefObject__5FsoundNCSoundRequest. Only a handful exist and PPSSPP leaves them
alone.

Hazards Copy Chapter

• A lot of C runtime code links into the same binary, and much of it starts with a double
  underscore (__adddf3, __malloc_lock, __sti). Rejecting a symbol that doesn't parse
  completely is what keeps those intact.
• The kind character is the only thing that says where the name ends. There is no separator
  between the last name component and the first parameter, and uppercase letters are both
  lengths and type codes, so a parser that guesses will read the wrong thing and still consume
  a plausible number of characters.
• T is overloaded - a parameter back-reference in the middle of the list, and the static
  marker at the end.

VSHBootInvestigation (`docs/VSHBootInvestigation.md`) Copy Section

VSH Boot Investigation

Notes on booting the PSP's Visual Shell (VSH / vshmain.prx) in PPSSPP via the direct HLE boot
path (--vsh), using a real Sony firmware dump (not checked into the repo - placed locally under
assets/flash0/, with assets/flash1/ alongside it if you have one). This is exploratory
reverse-engineering of Sony's shipped, undocumented System Software, not a supported PPSSPP
feature - treat conclusions here as best-effort, not verified against hardware.

Start here Copy Chapter

One command boots VSH, runs to a fixed point, and tells you where it got. It starts the emulator,
finds the debugger port, connects, and cleans up after itself - no wrapper script needed:

printf 'cpu.runUntilTime us=6000000\ncpu.status\n:quit\n' | \
  Tools/wsdbg/target/release/wsdbg.exe --sync --compact --quiet \
    --launch Windows/x64/Debug/PPSSPPHeadless.exe --vsh --cpu=interpreter --graphics=vulkan --loglevel=3 2>emu.log

That takes a few seconds. Protocol replies come back on stdout, the emulator's log on stderr.
Put more commands in the script to inspect state once it stops. Three things to know:

1. Don't add :wait cpu.stepping after cpu.runUntilTime (or any resume/step command).
   --sync already waits for it; a second one never arrives and burns the whole timeout. This is
   the single most likely reason a run seems to take minutes - emulation itself is ~real time.
2. --cpu=interpreter is what this path is known to work with, and breakpoints are most
   reliable there.
3. Boot needs a real firmware dump in assets/flash0/ (and optionally assets/flash1/), neither
   of which is in the repo.

Why it opens on a disc error Copy Chapter

The shell reaches the interactive XMB, but first shows "This disc cannot be started. The region
code is not correct." Cancel it with circle and the menu is there and usable.

Two separate things:

• It thought a disc was inserted, because nothing in PPSSPP modelled an empty drive. Now a shell
  booted without a game starts with an empty drive: sceUmdActivate tells the shell's drive callback
  (SceVshMediaDetectUMD) there's no disc, and sceIoDevctl 0x01F20001 (get disc type) answers 0,
  as JPCSP does. Activation used to report a readable disc regardless, so the shell asked for its type,
  got nothing it knew, and showed "The disc could not be read."

  A disc goes in with the WebSocket debugger's game.umd.insert (path), which mounts the image
  and calls the drive callback the way a PSP does when a disc is inserted, and comes out with
  game.umd.eject. The shell then lists the disc in the Game column with its icon, background and
  animated preview, and launching it boots the game through sceKernelLoadExecVSHDisc (Daxter on
  6.61, to its title menu). In the app, the pause screen offers "Insert UMD" and "Eject UMD" while
  the XMB is running.

  UMD Video discs work too: the disc type comes from what's on the disc (PSP_GAME, UMD_VIDEO,
  UMD_AUDIO), the shell lists a video disc in the Video column, and selecting it hands it to the
  firmware's own player (video_plugin, video_main_plugin, with mpeg_vsh.prx). Bourne Supremacy
  and the Spider-Man 2 trailer on the EUR Video Demo Disc play with sound. What that player needed
  from our Media Engine HLE (per-picture SEI records, keyframe flags, field conversion in
  sceMpegBaseCscAvc) is in pspautotests video/mpeg/avcdetail and video/mpeg/cscavc.

• It then asked whether the region matched and we didn't answer. sceIoDevctl 0x01E18030 is
  the region check, and unusually it answers through the return value (1 matches, 0 doesn't)
  rather than an output buffer. It was unimplemented, so the VSH read the failure as a mismatch and
  retried 12 times. Implemented now - PPSSPP has no region-locked discs, so anything it can load is
  something it should run - and the call drops to one.

Around the XMB (6.61) Copy Chapter

• Game: the memory stick list shows PSP games, PS1 EBOOTs and homebrew with icons and info.
  Homebrew and PS1 games launch from it; PSN titles stop at "The copyright protection information
  is invalid (8010850E)", since there's no licence (PSP/LICENSE/*.RIF). A game that exits goes
  back to the XMB, as on a PSP. The Saved Data Utility lists saves: it needed the raw stick device
  msstor0p1:/ (pspautotests io/msstor/msstor) and sceSdGetLastIndex without a key.
• Photo: folders under PICTURE/ list with thumbnails, and JPEG and PNG open full screen (R
  for the next one).
• Music: MP3 plays. SensMe stops at 8002013A.
• Settings: the menus open. System Information shows "-" for the MAC address: wlan.prx reads it
  from IdStorage key 0x44, and IdStorage is left failing on purpose (see below).
• Network: the browser and the online manuals reach their Network Connection screen once
  sceNetApctl_lib is there, then stop at 8002013A on sceHttp functions only the NetFront browser
  uses (06488A1C, 2C3C82CF, 3A67F306, 739C2D79, 77EE5319, 8046E250, A461A167, B0257723).

Current status Copy Chapter

--vsh boots VSH and renders real XMB frames. Measured on the GE command stream after 25
emulated seconds: 8 draw commands (two DRAW SPLINE 16x9, a DRAW BEZIER 4x4, four textured
DRAW PRIM TRI_STRIP - the wave background and icon quads), 41 texture binds, and full
PROJECTION/World/VIEW transform setup. opening_plugin_module, sceMpegVsh_library and
impose_plugin_module load and start.

It reaches the interactive XMB. Up to 2026-08-19 it showed the logo and wave animation and then
a full-screen red error screen, which turned out to be the XMB index failing to decrypt (below).
With that fixed, and with the disc region check answered (above), the shell opens on a dismissable
disc error and the menu behind it works.

Note that framebuffer readback does not work under headless on either backend -
gpu.buffer.screenshot and gpu.buffer.renderColor both answer "Could not download output" - so
checking what is actually on screen means running the app build. From headless, the useful proxy is
the per-frame display list signature (see the red error screen section): a screen that is finished
changing repeats byte-identically, and a live menu does not.

Which firmware versions work Copy Chapter

All 40 of them. Every version that ships on a UMD - 1.50, 1.52, 2.00, 2.50, 2.60, 2.71, 2.80,
2.81, 2.82, 3.03, 3.11, 3.30, 3.40, 3.50, 3.51, 3.52, 3.71, 3.72, 3.73, 3.80, 3.90, 3.95, 3.96,
4.01, 4.05, 5.01, 5.02, 5.03, 5.50, 5.55, 6.00, 6.10, 6.20, 6.30, 6.31, 6.35, 6.37, 6.39, 6.60 -
plus the download-only 6.61, reaches an interactive XMB with no error on screen.

An earlier pass through this also concluded "all of them", but what it measured was that the shell
renders, and several versions did that while showing nothing but the wallpaper or a full-screen
error. The check now is a picture: boot with --vsh --graphics=software --screenshot-save and look
at it. Two things about that:

• --timeout is wall-clock seconds, not emulated ones. A shell drawing a full XMB runs far
  slower than one stuck on a flat background, so a short timeout makes a working version look
  stuck. 120 seconds is comfortable for all of them.
• Judge by the image, not the file size - though the failure modes do have recognisable sizes,
  and none of them is subtle.

What was in the way, in the order it was found Copy Section

Five distinct causes, each of which stopped a whole band of versions:

• Three kernel calls under NIDs we didn't have. sceKernelLoadModuleVSH is how the shell loads
  its own plugins, so without it nothing drawable ever loads and the screen stays black; it has six
  NIDs across the range. Same story for sceKernelGetModel (seven) and sceImposeSetStatus (five).
  An unresolved GetModel meant the shell read a garbage model number and went looking for PSP-3000
  resources on a dump that has none.

  Finding them is mechanical, and worth writing down because it generalises. For each firmware,
  disassemble the module that exports the function and look for the body you already know from
  6.61: sceKernelLoadModuleVSH is the modulemgr.prx export whose callees are
  sceKernelIsIntrContext, sceIoOpen/Ioctl/Close and sceKernelGetUserLevel;
  sceKernelGetModel is whatever vshbridge.prx wraps in a sceKernelGetUserLevel() < 4 check
  and re-exports. Several exports share that shape, so cross-check against the boot log: the one
  that matters is the import the shell actually calls, which the "Unknown syscall (run)" lines name.

• Missing sceResmgr keys. flash0:/vsh/etc/index_XXg.dat is the index of what the XMB shows
  and is encrypted; a shell whose key is missing loads every resource successfully and still has
  nothing to put in the menu, so it gives up with the red error screen. Each generation has its own
  tag, one per PSP model from 5.03 on and a single unsuffixed index.dat before that. 1.50 through
  2.50 don't use it at all.

  The keys are in each firmware's own mesg_led*.prx, in a table of 24-byte entries - 4-byte tag,
  16-byte key, 4 bytes of padding. Search the decrypted module for the tag as a little-endian word
  and read the next 16 bytes. Validate the hit before believing it: locate a tag that
  PrxDecrypter.cpp already has a key for and check it matches byte for byte. Extracting the 6.6x
  triple this way reproduces keys_9DC14891_1/2/3 exactly, which is what established the layout in
  the first place. Don't try to walk the table blind - guessing the grid alignment produces
  plausible-looking garbage out of ordinary MIPS code, and the 2.5x-era table isn't on that grid
  at all.

• sceImposeGetParam(0x40000000). A real setting in every impose.prx from 1.50 to 5.55, which
  we rejected as not a parameter at all. 3.11's shell read the error back, blanked the display with
  sceDisplaySetFrameBuf(0, 0, 0) and never turned it on again - so the screen kept whatever
  uninitialised VRAM held while a perfectly healthy frame loop ran behind it. 2.00, 3.03 and 3.11
  all turned on this one value.

• category_version in the registry. Our sceReg serves a compiled-in snapshot of a 6.6x PSP's
  registry, /REGISTRY/category_version included. Every shell checks it and treats a version higher
  than the schema it knows as a corrupt registry, offering to reset your settings instead of
  booting - which is what 1.50 through 5.50 did. The check is one-directional, older is always
  accepted, and nothing tried to migrate anything, so we report 1.

• sceRegCloseRegistry dropping categories another opener still owned. See sceReg.cpp; the
  VSH's alarm scan nests registry opens and this cost it its own open category.

Sony renumbered the kernel NIDs, and that is what blocked everything below 6.60 Copy Section

Not offsets - NIDs. A function PPSSPP HLEs under its 6.6x *_driver NID is unrecognized on an
older build, so the import resolves to the real firmware module instead, and the real module
goes places the emulator can't follow.

The rtc one is the interesting failure. Without the HLE, the VSH's alarm call ran the real
rtc.prx, which called on into syscon.prx and blocked forever on a SceSysconSync semaphore.
The symptom was a boot where every thread was parked and idle0 was running, and the tell was a
fourth SceSysconSync waiter that a healthy boot doesn't have (there are three, one each for
sceSYSCON_Driver, sceRTC_Service and SceWlanMac - that's their normal idle state).
hle.backtrace thread=<SCE_VSH_GRAPHICS> named the whole chain: vsh_module -> vshbridge -> rtc ->
syscon -> wait. The hprm one is only a performance bug, but a loud one: the VSH reads the latch
once a frame, so an older firmware's 12-second boot logged ~20000 lines of the same import.

Two more of the same shape, for 1.50-2.xx: sceImpose_driver exports sceImposeGetParam as
0x531C9778 and sceImposeChanges as 0xB415FC59 there, with no user-mode alias. Changes runs
once a frame too. And ModuleMgrForKernel numbers sceKernelLoadModuleVSH 0xA4370E7C on 1.x -
that's how the VSH loads its own plugins, so unresolved it got module id 0 back and the
sceKernelStartModule after it failed, exactly the way 0xD5DDAB1F did on 6.61 before it was
implemented.

How to map a NID between versions. Disassemble the same module from both firmwares with
--re-module and match by address. Don't compare raw addresses - the builds move code - anchor on
the plain user-mode export whose NID never changed (sceRtc/0x7D1FBED3 for SetAlarmTick,
sceHprm/0x40D2F9F0 for ReadLatch) and read off the *_driver NID at the same address. Below
3.95 sceRtcSetAlarmTick isn't in the user-mode library at all, so anchor on a neighbour instead:
it is the driver export immediately below sceRtcIsAlarmed. Where even that fails, match the
function body - that is how the two impose calls and the 1.x LoadModuleVSH were identified.

sceRtcIsAlarmed also had to be implemented (it returns 0, as in JPCSP). Left as a null entry it
returned SCE_KERNEL_ERROR_LIBRARY_NOT_YET_LINKED, and the 3.0x-3.5x VSH read that as "ask the
hardware instead" and went back to blocking on syscon.

The scePaf heap pool, and the order modules start in Copy Section

scePaf's allocator wants a pool base already written into one of its BSS slots. The module that
owns the allocator fills that slot in itself, from its own module_start. The kernel's bootstrap
starts modules one at a time and waits for each module_start to return, so on hardware that has
happened long before vshmain runs. We used to start all the modules as threads side by side, and
vshmain's start thread ran first: the pointer was still null and the shell wrote through it. For a
while the slot was pre-filled with an 8.3MB block (the compiled-in default size) to get past that.

The pre-fill made the boot work but not the game icons. vshmain's start asks paf for one block
for game_plugin's surface pools, 12MB when sceKernelTotalMemSize says more than 36MB (8MB
otherwise). paf's own start would have set up a 0xC50000 long-life heap that holds it, but hadn't
run yet, so the request went to the 8.3MB pre-filled heap and failed. game_plugin then made
surfaces with no memory behind them, decoded every ICON0 and PIC1 correctly, and threw them away
(white tiles on 3.80-5.05, grey placeholders from 5.50).

LoadVshKernelModules() now starts the shell's own modules (heaparea1 where it exists, vshbridge,
paf, common_gui, common_util) one at a time, each when the previous module_start returns, and
vshmain waits for the last. The kd/ drivers still start side by side: syscon's module_start blocks
on a semaphore its hardware interrupt would signal. With the order right the pre-fill went away,
and every version from 1.50 to 6.61 shows game icons.

Which module owns the allocator moved. Up to 4.05 it is a separate flash0:/vsh/module/heaparea1.prx,
which paf imports as scePafHeaparea and cannot allocate a byte without; from 5.01 it is compiled
into paf.prx and heaparea1 is gone. Loading heaparea1 when it's present was the missing piece for
every 3.x and 4.x version - without it scePafHeaparea_ACCE25B2 was an unresolved import, paf
built a heap out of an uninitialized stack pair, and vshmain died storing the null the allocator
handed back.

In both modules the slot is filled by the one function that calls sceKernelTotalMemSize: a
> 0x2400000 test picks 0xA00000/0xC50000 pool sizes over the compiled-in defaults, then two
sceKernelCreateFpl + sceKernelTryAllocateFpl pairs write to adjacent slots.

1.50 declares no module attributes Copy Section

g_runningVSH was set from PSP_MODULE_VSH_MODE in the module's attribute word. 1.50's
vshmain.prx has attribute 0000 - Sony only started setting the flag in 1.52 - so the entire VSH
bootstrap was skipped and the shell ran with none of its support modules loaded. The check also
accepts the module name vsh_module now.

The vsh_module alarm-category patch only 6.6x needed Copy Section

6.60 and 6.61 used to crash in vsh_module's alarm-task scan on a "count" in rodata that nothing
initialized, and a patch zeroed it (only when the word was the 0x3F666666 it was derived from).
It was another effect of the start order above: with the shell's modules started in order, 6.60
and 6.61 reach the XMB without it, and it's gone.

Kernel modules with per-model builds Copy Section

LoadVshKernelModules() asked for memlmd_01g.prx, loadexec_01g.prx and
wlanfirm_01g.prx by name. A firmware unpacked for one model ships only that model's build, and
PPSSPP's own updater unpack defaults to 02g, so all three failed to load. ResolveVshModelModule()
now substitutes the emulated model's suffix when that file exists, falling back to _01g for a
dump unpacked with model any (which has every model's). Firmwares older than about 3.60 predate
the PSP-2000 and have no per-model split at all, so they are unaffected.

5.55 needed two PRX keys Copy Section

Its flash0:/kd modules are tagged 0x4C941AF0/0x4C941BF0, and those two were the only entries
of JPCSP's PRX tag table PPSSPP was missing. The shell came up anyway - vshmain and paf are user
modules - but with not a single driver behind it.

The red error screen Copy Chapter

What is known, all measured from a 40-emulated-second --vsh boot:

• Nothing fails to load. Every sceIoOpen in the whole boot succeeds: flash0:/font/*.pgf,
  opening_plugin.rco, system_plugin.rco / _bg / _fg, topmenu_plugin.rco,
  topmenu_icon.rco, impose_plugin.rco, and flash0:/vsh/etc/index_02g.dat. The only I/O
  failure in the entire trace is flash1:/registry/init.dat, which is correct (see above). So VSH
  genuinely gets as far as building the top menu before giving up.
• Where it freezes. Grouping sceGeListUpdateStallAddr by display list id gives a per-frame
  signature of what is being drawn. It grows 6 -> 10 -> 11 -> 15 -> 19 -> 33 -> 34 -> 38 stall
  points (the dialog and its text being composed) and then repeats byte-identically for the
  remaining ~2016 frames. That is the error screen locking in; everything before it is animation.
• Nothing logs an error in the run-up. The window before the freeze is just the startup jingle
  decoding (sceAtracDecodeData + sceAudioOutputPannedBlocking), vshCtrlReadBufferPositive,
  scePowerIsSuspendRequired, sceKernelGetUserLevel and sceImposeChanges. So the trigger is a
  wrong return value we hand back, not a missing call - which makes it much harder to spot than
  the sceKernelLoadModuleVSH bug was.
• sceImposeChanges is not a symptom of the error. It runs once a frame regardless; the
  ~10000 calls per boot are just the indicator refresh, and they start after the frame loop is
  already steady. Don't read into it.

What actually triggers it: the XMB index can't be decrypted Copy Section

Found by raising log channels for a narrow window around the transition (5.8s to 6.7s emulated,
~12K lines - log.channel.set, not a full-boot log). The frame loop's calls before and after the
transition differ sharply: before it there is resource loading, module starting and registry
access, after it only the clock and battery indicators. Inside that window:

sceIoOpen(flash0:/vsh/etc/index_02g.dat)   -> fd 8
sceIoRead(8, 092a2d40, 496)                -> the whole file
sceIoClose(8)
unresolved import sceResmgr/9dc14891, called from 'vsh_module'    <- traps here
sceKernelExitDeleteThread(1)               <- the ScePafJob building the menu gives up

index_02g.dat is the index of what the XMB shows, and it is encrypted (it starts PSPsysGP, not
the release: of an already-plaintext one). sceResmgr_9DC14891 is what decrypts it. With that
import unresolved the call trapped, the index stayed encrypted, and the job thread quit - hence a
shell that has loaded every resource successfully and still has nothing to show.

Fixed. Core/HLE/sceResmgr.cpp implements the call, the three tags it needs
(0x0B2B90F0/91F0/92F0, keys and code 0x5C from JPCSP) are in Core/ELF/PrxDecrypter.cpp, and
pspDecryptType9() there decrypts it - 496 bytes in, 159 out, starting release:, which is the
check sceResmgr logs on every call.

Type 9 turned out to be type 6 with three differences, all because a type 9 file carries a real
ECDSA signature at 0x104..0x12C where type 6 has nothing:

• The "this region must be empty" check has to stop at 0x104 rather than 0x10C, or the first
  8 bytes of the signature fail it (this was the original -2).
• The signature is excluded from the hashed header rather than fed into it - JPCSP zeroes
  buf2[0x34..0x5C), which is the same range after its header rearrangement, so PRXType9 simply
  leaves that field zero.
• ecdsa_hash in the KIRK CMD1 header stays 0. Type 6/7 set it; the branch type 9 takes writes
  only the mode word. Setting it was the final -4.

The SHA1 check inside the decrypt is a good progress signal while porting: reaching -4 means the
header reconstruction and hash inputs were already right and only the KIRK call was wrong.

The root cause of the long-standing blank screen Copy Chapter

ModuleMgrForKernel/0xD5DDAB1F (sceKernelLoadModuleVSH) was unimplemented. That is how VSH
loads its own plugins: the XMB's UI lives in flash0:/vsh/module/*_plugin.prx and vshmain
pulls those in through this kernel call, not the user-mode sceKernelLoadModule. The import went
unresolved, vshmain got no module id back, and the sceKernelStartModule that followed was called
with id 0 and failed with 0x8002012E UNKNOWN_MODULE. No plugin ever ran, so the scene had
its containers but nothing drawable in them - which is exactly the "render state set up 6 times
per frame, zero draws" symptom this investigation chased for a long time.

Implemented along with 0xD86DD11B sceKernelSearchModuleByName, the other unresolved
ModuleMgrForKernel import.

Found by scanning a whole boot for any HLE call returning an error. Exactly one mattered, and it
had been missed on two earlier passes because it logs as : error 8002012e rather than as a
8xxxxxxx=sceSomething( return value. Grep both shapes.

Solved along the way Copy Chapter

• Real kernel driver modules running as genuine MIPS code needed scratchpad RAM kernel-mode
  address mirrors (Core/MemMap.cpp), dummy COP0 instructions (Core/MIPS/Interpreter.cpp), and
  a GPIO + Syscon serial MMIO model (Core/HW/GpioMMIO.{h,cpp}) so kd/syscon.prx's real
  handshake completes instead of spinning.
• vsh_module alarm-task SIGSEGV: was a targeted data patch zeroing an "alarm category count"
  field nothing else initialized. Removed once the shell's modules started in order, which made
  it unnecessary.
• SCE_KERNEL_ERROR_NO_MEMORY in the app build: the 4MB kernel pool was exhausted by PPGe's
  ~2MB overlay texture (now skipped when booting VSH) plus 11 driver modules each asking for a
  256KB thread stack (now given 32KB).
• sceHprm_driver/sceHprmReadLatch (0xE9B776BE) implemented and its output struct actually
  zeroed, matching JPCSP. Correct, but did not affect the blank screen.
• flash1 is now mounted when a dump sits next to the flash0 one. sceReg serves a compiled-in
  snapshot of some real PSP's registry (Core/HLE/sceReg.cpp) rather than reading the volume, and
  a genuine dump has only registry/system.dreg and .ireg. flash1:/registry/init.dat must
  stay absent - an earlier note here said creating one "changes nothing", which is wrong. VSH
  stats it twice during startup, and finding it means "reinitialize the registry": it then calls
  sceRegRemoveRegistry and sceIoDevctl("flashfat1:", 0x5802), both UNIMPL, and the boot dies
  without starting a single plugin module. Its absence is the healthy path, and the resulting
  FILE NOT FOUND in the log is expected, not a lead.
• A diagnostic-tooling bug that produced a phantom lead. The "unresolved import" reporter
  encoded identity in a 55-slot ring buffer, but a VSH boot registers ~1000 unresolved imports, so
  the ring wrapped ~18 times and every report named whatever most recently reused that slot. It
  made sceMgVideo_driver look like one massively hot call when it was the misattributed sum of
  many. Fixed by recovering stubAddr via g_lastSyscallPC and looking identity up in
  module->importedFuncs, which already tracked exactly this (interpreter-only, matching the
  original limitation). Lesson: when identity has to be recovered later by address, check
  whether something already tracks it before adding a cache. Breakpoints were never at fault -
  if one doesn't fire, suspect the address first.

Imports that must stay unresolved Copy Chapter

Counterintuitive but repeatedly measured: implementing more of what the VSH imports can make the
boot worse, because a correct implementation lets a real flash0 driver finish its init and walk
on into hardware PPSSPP does not emulate. Leaving the import unresolved makes the driver fail early
and the boot continues. All three are commented in the source at the point where they'd be added:

• ThreadManForKernel mutex NIDs (0xB7D098C6 sceKernelCreateMutex, 0xB011B11F
sceKernelLockMutex, 0x6B30100F sceKernelUnlockMutex) - we implement all three for user
  mode already. Resolve them and the NAND and ID storage drivers init successfully, then
  sceIdStorage_Service polls the NAND controller at 0xbd101300 forever (470k reads in 25
  emulated seconds), and only 4 modules start. sceKernelAllocateFpl (0xD979E9BF) used to be on
  this list, but it's the mutexes that do it: with only the FPL resolved, sceIdStorage_Service
  allocates from its pool and the boot still reaches the XMB.
• InterruptManagerForKernel interrupt registration (0x58DD8978, 0xF987B1F0, 0x4D6E7305,
  0xD774BA45) - JPCSP can honour these because it emulates the interrupt controller as MMIO. We
  dispatch the few interrupts we emulate ourselves (__RegisterIntrHandler), so success is a lie
  the drivers act on. Measured: 31 such calls (interrupts 4, 12, 15-18, 20-24, 31), then a stall in
  GE list execution with no plugin module started.

73 unresolved import hits over 37 distinct module/NID pairs remain in a boot. Most of the rest are
sceSysEventForKernel, sceSuspendForKernel and *_driver modules that would need real hardware
behind them. Note the runtime ones log as Unknown syscall (run) at ...: unresolved import ...
(HLE.cpp:905) - a different string from the load-time Unknown syscall from known HLE module,
so grep for both or you will undercount badly.

How this boot path works Copy Chapter

Real hardware boots VSH through the kernel's own module bootstrap, launched from
flash0:/reboot.bin. PPSSPP doesn't emulate that chain. --vsh loads
flash0:/vsh/module/vshmain.prx through the normal PRX loader, and
LoadVshKernelModules() (Core/HLE/sceKernelModule.cpp) approximates the missing
bootstrap by loading and starting vshbridge.prx, paf.prx, common_gui.prx, common_util.prx
and 11 real kd/ drivers first, in the order JPCSP's own --vsh shortcut uses.

JPCSP's --vsh turns out to use the same shortcut rather than a real reboot.bin LLE path, so this
is a legitimate if approximate route to a working VSH.

Known differences from JPCSP's --vsh that have not been tried: it preloads
PSP_MODULE_AV_VAUDIO, AV_ATRAC3PLUS and AV_AVCODEC, and sets the io filepath to
ms0:/PSP/GAME. Its trick of forcing the root thread to kernel mode at priority 0x7E was
tried and reverted - it reorders scheduling enough that sceVshBridge_Driver runs before a
precondition is ready. Firmware version already matches (660 both sides).

Thread structure Copy Chapter

There is no vsh_main thread and there shouldn't be. vshmain.prx's module_start runs on the
root thread, creates and starts SCE_VSH_GRAPHICS (entry 08818d14) and returns from module -
visible in the log as Context switch: root -> ... (returned from module) right after the
sceKernelStartThread. SCE_VSH_GRAPHICS is VSH's main thread, and its entry is the
outermost frame of every render backtrace.

Steady state is 8 threads: SCE_VSH_GRAPHICS, ScePafThread, SceWaveMain, SceWlanMac,
sceRTC_Service, sceSYSCON_Driver, idle0, idle1, plus transient ScePafJob threads that
load the .rco resources and exit. The frame loop is healthy: poll ScePafSyncCall,
vshCtrlReadBufferPositive, render, sceDisplaySetFrameBuf, wait SceVblankSync.

The render call chain Copy Chapter

Still worth having if individual widgets misbehave. Traced with a write memcheck on a display
list word (memory.breakpoint.add address=... write=true), which stops with a structured hit
and lets hle.backtrace name the whole chain - minutes of work, and the technique to reach for
first next time:

08818d14   SCE_VSH_GRAPHICS thread entry
  08895544   6-iteration loop
    08963cfc   container: sets base render state, walks children at [obj+0x550], count [obj+0x554]
      08950754   per-child render
        089a1cdc / 089a36e4 / 089a38c0 ...   GE state helpers

08950754 gates on z_un_089501cc(child+0x450) == 1 and on [child+0x438] != 0, then computes
the scissor by intersecting [child+0x43c..+0x448] with a parent clip rect.

Tools and methodology Copy Chapter

• Everything useful works on a live session: hle.thread.list, hle.eventflag.list,
  hle.backtrace, memory.disasm, memory.readString, gpu.displaylist.disasm, cpu.evaluate
  (expressions like [s0+0x438] read guest memory), and memory breakpoints. See
  docs/WebSocketDebugger.md for the catalog.
• cpu.runUntilTime us=N is what makes a script reproducible - it stops on the requested emulated
  microsecond, so every run reaches the same instruction. Ask for the time you need and no more;
  the red screen locks in around 6 emulated seconds.
• Raise log channels for a short window only - sceGe/G3D at debug produce ~200K lines in
  three seconds of boot. log.channel.set is session-only, never persisted. --loglevel=3 is a
  good default for the whole run: bare --log on a VSH boot writes ~2.3GB, level 3 writes ~66KB.
• Diffing against JPCSP (../JPCSP, Java source, NIDs searchable by hex) repeatedly beat guessing
  at missing HLE functions. assets/flash0 has the decrypted PRXs if a NID needs disassembling.
• Headless is preferred over the app build - the app's Debug config blocks on a Windows crash
  dialog with no console output.

Emulation is not the slow part. A VSH boot runs at roughly real time even in a Debug build
(1 emulated second in a 2.5s run that includes process startup). If a scripted run takes minutes,
it is waiting, not emulating - and the usual cause is an explicit :wait cpu.stepping after a
cpu.runUntil*/cpu.resume/cpu.step*, which --sync already waits for. The redundant one waits
for a second cpu.stepping that never comes and burns the whole --sync-timeout. See
Tools/wsdbg/README.md.

Not included on this branch Copy Chapter

The separate --vsh-reboot experiment (loading flash0:/reboot.bin for a real LLE kernel boot,
with NAND/KIRK/system-control MMIO emulation) lives on vsh-experiments. The direct HLE path here
reaches much further without any of it.

WebSocketDebugger (`docs/WebSocketDebugger.md`) Copy Section

PPSSPP WebSocket Debugger

PPSSPP has a JSON/WebSocket-based debugger and automation API, served from the
same HTTP server used for "Remote ISO" disc sharing and file upload. It lets
an external tool (a script, a web page, another editor/IDE) inspect and
control a running emulation session: read/write memory, set breakpoints,
step the CPU, read GE/GPU state, send fake input, tail the log, etc.

This doc is a local reference, the user-facing documentation is on the website.

Where the code lives Copy Chapter

• Core/WebServer.cpp / Core/WebServer.h - the shared HTTP server (also
  used for Remote ISO and file upload). It owns the listening socket and
  dispatches /debugger requests.
• Core/Debugger/WebSocket.cpp - upgrades the HTTP request to a WebSocket and
  runs the per-connection event loop (HandleDebuggerRequest).
• Core/Debugger/WebSocket/*.cpp/.h - one "subscriber" or "broadcaster" per
  feature area (CPU, memory, GPU, HLE, input, breakpoints, ...). Each file's
  top comment documents its events in detail - this doc gives the overview
  and an index into those files.
• Core/Debugger/WebSocket/WebSocketUtils.h - shared DebuggerRequest
  helper (parameter parsing, response/error helpers) and DebuggerSubscriber
  base class.
• Common/Net/WebsocketServer.h/.cpp - the low-level WebSocket framing.

Transport Copy Chapter

• Runs on the same port as Remote ISO sharing (g_Config.iRemoteISOPort; 0
  means "pick a free port automatically" - the actual bound port is written
  back to that config value and logged: Listening on port N).
• URL path: /debugger.
• WebSocket subprotocol: debugger.ppsspp.org (required - a plain HTTP GET
  to /debugger without a websocket Upgrade just redirects to the bundled
  web UI at /debugger/index.html).
• Messages are JSON, both directions, always shaped as {"event": "NAME", ...}.
• One WebSocket connection = one client; PPSSPP does not limit the number of
  simultaneous debugger connections.
• The debugger only actually does anything while WebServerFlags::DEBUGGER
  is enabled (see "Enabling it" below) - the HTTP server itself may also be
  running for other reasons (Remote ISO, upload).

Message protocol Copy Chapter

Requests you send:

{ "event": "cpu.status" }

Optionally include a "ticket" field (any JSON value) - PPSSPP echoes it
back verbatim in the response/error, so you can correlate requests and
responses when firing several at once. Tools/wsdbg (see below) assigns an
incrementing integer ticket automatically.

Responses use the same event name as the request:

{ "event": "cpu.status", "ticket": 1, ... }

The ticket convention: send one whenever you care about the answer. Since
a response reuses the request's event name, a ticket is the only thing that
distinguishes your answer from an unsolicited broadcast of the same name, or
from the answer to an identical request you sent a moment earlier. Conversely,
for a request that doesn't answer immediately (below), leaving the ticket off
says you aren't waiting for anything.

Responses are not always immediate. cpu.resume, cpu.stepInto,
cpu.stepOver, cpu.stepOut, cpu.runUntil, cpu.runUntilTime,
cpu.nextHLE, cpu.stepping and gpu.stats.feed send nothing back at the
time of the request; what follows later is the broadcast that reports the
actual outcome (cpu.stepping / cpu.resume), which carries no ticket.
input.buttons.press is the odd one out - it answers with the request's own
event name and ticket, but only once the button has been held for the
requested number of frames.

If you would rather not track which those are, ask to be told explicitly:

-> { "event": "client.config.set", "acknowledgeDeferred": true }
-> { "event": "cpu.resume", "ticket": 7 }
<- { "event": "deferred", "for": "cpu.resume", "ticket": 7 }
<- { "event": "cpu.resume" }

With that on, every request draws exactly one immediate reply - a response, an
error, or a deferred - so a client can correlate without a hardcoded list,
including for events added in future versions. It is off by default and must
stay that way: an extra message would break a client that correlates purely by
ticket, and it can't reuse the request's event name because for
input.buttons.press that is exactly what the real, later answer looks like.

Errors look like this:

{ "event": "error", "message": "...", "level": 2, "ticket": 1 }

level is a LogLevel (1=NOTICE, 2=ERROR, 3=WARN, 4=INFO, 5=DEBUG, 6=VERBOSE).

PPSSPP also sends unsolicited ("broadcast") events with no request - see
below.

By convention, send a version event right after connecting (see
WebSocket/GameSubscriber.cpp):

{ "event": "version", "name": "my-tool", "version": "1.0" }

PPSSPP responds with its own name/version, and remembers yours (currently
just for internal bookkeeping/future logging). The response also carries
pid (OS process id) and path (the executable/disc currently loaded, or
null), so an automation client can confirm it attached to the instance it
meant to - a port alone doesn't prove that, since a leftover process may still
be holding the port you asked for.

Broadcast (unsolicited) events Copy Chapter

Sent without you asking, whenever the underlying state changes:

A client can opt out of specific broadcast categories with
broadcast.config.set ({"disallowed": {"logger": true, "game": true, "stepping": true, "input": true, "breakpoint": true}}),
see ClientConfigSubscriber.cpp. gpu.stats.feed (see below) works the same
way for periodic GPU stats. client.config.set in the same file carries
per-connection settings that aren't about broadcasts - currently just
acknowledgeDeferred, described under "Message protocol" above.

Source line info Copy Section

Where a game shipped an unstripped ELF, PPSSPP decodes its DWARF .debug_line
and can map an address to a source file and line. cpu.breakpoint.hit and
cpu.stepping carry file/line in the hit object, and hle.backtrace
carries them per frame - which is where it pays off most:

08841f98  move sp,fp          mesh.zig:163
0883afa4  li v0,0x0           MenuState.zig:821
088260d8  andi at,v0,0xFFFF   State.zig:40
0882a27c  andi at,v0,0xFFFF   engine.zig:468

Both fields are null when there's no line info for that address, which is the
common case: PRX conversion strips every .debug section, so this never
applies to a commercial game. In practice it means homebrew that ships its
app.elf next to the EBOOT - the same file the companion symbol loader uses -
or a plain .elf you built yourself. It follows bAutoSaveLoadSymbols along
with the symbols.

DWARF 2, 3 and 4 are decoded; version 5 units are skipped with a log line rather
than mis-parsed, since it re-encoded the file table. Nothing targeting the PSP
emits it today (psp-gcc produces 2, Zig 4).

Emulation speed Copy Section

game.speed.set drives two independent things:

-> { "event": "game.speed.set", "fastForward": true }        // unlimited
-> { "event": "game.speed.set", "percent": 200 }             // double speed
-> { "event": "game.speed.set", "percent": 25 }              // quarter speed
-> { "event": "game.speed.set", "percent": null }            // drop the override
<- { "event": "game.speed.set", "fastForward": false, "percent": 200, "limitFps": 120 }

Percentages are relative to 60 FPS, matching how the in-app settings present the
alternative speeds - so 200 means the same thing in both places. percent
must be at least 1; use fastForward for unlimited rather than 0, so there's
only one way to say it. fastForward wins while it is on, and percent is
remembered underneath it.

limitFps in the response is the frame rate throttling is actually aiming for
once everything - fast-forward, this override, the user's own alternative-speed
hotkeys - has been taken into account, with 0 meaning unlimited. It comes
straight from the function the frame timing itself consumes, so prefer reading
it over inferring the result from the other two fields.

This is a separate channel from the user's own alternative speeds. It
deliberately never touches g_Config, whose speed settings are persisted per
game, so a debugger session can't permanently change what the user configured.
Clearing the override also only stands down from a limit set through this event,
never from one the user set themselves. It resets on every game boot.

The request fails rather than being silently ignored when something else
owns the speed: RetroAchievements hardcore mode, or being connected to a network
game without "allow speed control while connected".

Headless sets fast-forward at startup and never turns it off on its own, so
game.speed.set works there too - turning fast-forward off makes headless
throttle to real time, which is occasionally useful for a wall-clock repro.

Breakpoint hits Copy Section

cpu.breakpoint.hit fires every time a breakpoint's condition passes and it has
some action set - including log-only breakpoints, which never stop the CPU.
That's what makes them usable for automation: before this event existed, a
log-only breakpoint's only trace was a line in the log stream.

{
  "event": "cpu.breakpoint.hit",
  "sequence": 1,
  "hit": {
    "kind": "exec",
    "pc": 142876568,
    "address": 142876568,
    "hits": 1,
    "logged": true,
    "paused": false,
    "condition": null,
    "symbol": "rendering.mesh.Mesh(rendering.Vertex.PspVertex).draw",
    "breakpoint": { "start": 142876568, "end": 142876568 }
  }
}

The same hit object is attached to cpu.stepping when a breakpoint is what
stopped the CPU, so both can be parsed the same way. It is absent when the
break came from something else (the user pausing, a savestate load, an
exception), so test for its presence rather than for a kind.

Fields common to every kind:

Extra fields for "memory":

Extra fields for "register": register (GPR index) and registerName
(e.g. "a0").

Note address and breakpoint.start are not the same thing for a memory
breakpoint watching a range - the first is the byte touched, the second is the
range being watched. On cpu.stepping the legacy relatedAddress field keeps
reporting the range start; hit.address is the accurate one.

sequence counts hits produced, not delivered. A connection whose queue backs
up (easy to do with a log-only breakpoint in a hot loop - one can produce tens
of thousands of hits per second) drops hits rather than growing without bound,
so a gap in sequence tells a client exactly how many it missed. Game and
stepping events are never dropped. Turning the
breakpoint category off via broadcast.config.set avoids the traffic
entirely.

Request/response event catalog Copy Chapter

Full details (parameters, response shape) are documented as comments above
each handler in the corresponding Core/Debugger/WebSocket/*Subscriber.cpp
file - this is just an index.

Enabling it Copy Chapter

• UI: Settings > Tools > Developer Tools > "Allow remote debugger"
  checkbox (UI/DeveloperToolsScreen.cpp). The "Local Server Port" slider on
  the Networking screen sets the port (shared with Remote ISO sharing; 0 =
  auto-pick).
• Config: RemoteDebuggerOnStartup=true in ppsspp.ini
  (g_Config.bRemoteDebuggerOnStartup) starts it automatically on launch
  (UI/NativeApp.cpp).
• Command line (both application and headless builds): --debugger=PORT
  (0 = pick a port automatically) - a shared auto-param in
  Core/CmdLine.cpp/.h (CmdLineMode::Both). ApplyToConfig() sets
  iRemoteISOPort/bRemoteDebuggerOnStartup for that run without persisting
  them to the config file.
  • A non-zero PORT is treated as mandatory (WebServerSetRequireExactPort()):
    if it can't be bound, the server does not silently fall back to some other
    free port the way the "Local Server Port" preference does, because a client
    was told to connect there. Headless exits non-zero; the application build
    logs an error and shows an OSD message but keeps running. Use --debugger=0
    and read the actual port from the Listening on port N log line if you'd
    rather not care which port you get.
  • On the application build this is exactly like ticking "Allow remote
    debugger" - the game boots and runs normally, debugger listening
    alongside it.
  • On the headless build (headless/Headless.cpp) it additionally
    forces coreParameter.startBreak = true, so the CPU halts before
    running anything - useful for setting breakpoints before launch.

Discovery Copy Chapter

For LAN auto-discovery (mainly useful for mobile), the server periodically
reports its (local ip, port) to report.ppsspp.org/match/update (see RegisterServer() in
Core/WebServer.cpp). Clients can query report.ppsspp.org/match/list to
get a list of candidate endpoints on the same network and try connecting to
each in turn.

The bundled web-based JS debugger Copy Chapter

assets/debugger/ is a git submodule
(https://github.com/unknownbrackets/ppsspp-debugger.git, bundled branch -
see .gitmodules) containing a prebuilt React app. PPSSPP serves it directly
at /debugger/ (Core/WebServer.cpp's HandleFallback/ServeAssetFile),
so opening http://:/debugger/ in a browser gets you a full GUI
debugger for free. The actual editable source lives in a different branch of
that same repo (the bundled branch only holds the built output that gets
checked in here).

From reading the minified bundle (assets/debugger/static/js/main.*.js),
it connects like this:

• Manual connect: new WebSocket("ws://ip:port/debugger", "debugger.ppsspp.org").
• Auto connect: fetch("//report.ppsspp.org/match/list") for a list of
  {ip, port} candidates (as registered by RegisterServer() above), then
  tries each with the same WebSocket call until one succeeds.

Talking to it yourself Copy Chapter

• scripts/websocket-test.py - old minimal Python one-shot script (needs the
  websocket-client pip package).
• Tools/wsdbg/ - a small Rust CLI/REPL client for this session's work (see
  Tools/wsdbg/README.md): connects, does the version handshake, and lets
  you fire off events by hand or from a one-shot command line, printing
  responses and broadcasts as they arrive. Built and smoke-tested against a
  live PPSSPP instance while writing this doc.

Android Device Testing (`docs/android-device-testing.md`) Copy Section

Testing an Android build on a device

Notes from driving real devices over adb. Most of what follows is not about Android being hard, but
about ways the tooling quietly answers a question you did not ask - you measure the wrong build, or
measure garbage that has not been collected yet, and get a confident wrong answer.

Install the build you think you are testing Copy Chapter

versionCode is derived from the git commit count (see gitVersionCode in
android/build.gradle.kts), so a feature branch has a lower code than a longer branch. Installing
one over the other fails:

adb: failed to install ...: Failure [INSTALL_FAILED_VERSION_DOWNGRADE]

-r does not permit downgrades; -d does. Use adb install -r -d <apk>.

Do not pipe the install through tail -1 or grep Success and move on. The failure is a single
line and easy to swallow, and the device then keeps running whatever was there before - every
measurement afterwards describes the wrong binary, including A/B comparisons where both arms end up
being the same build and therefore agree with each other.

Verify after every install, not just when something looks odd:

adb shell dumpsys package org.ppsspp.ppsspp | grep versionName

A second, independent check is worth it when a result is surprising: grep the log for a symbol that
exists only on the branch under test (a renamed class or log tag, say).

The version string itself can also lie. The Android build regenerates git-version.cpp but does not
always recompile it, so the APK can carry the previous build's string while containing current code.
When the version matters:

find android/.cxx -name git-version.cpp.o -delete

Forcing an activity recreate without touching the device Copy Chapter

• adb shell settings put system font_scale 1.15, then back. fontScale is not in the activity's
  configChanges, so each change destroys and recreates the activity. Independent of orientation.
• adb shell wm density <n> also recreates - but only while density is absent from
  configChanges.
• adb shell settings put system user_rotation 1 does not rotate PPSSPP. The activity follows
  the sensor, so this needs a physical rotation (or a cooperative device).

Put back whatever you changed: font_scale, accelerometer_rotation, user_rotation.

wm density reset is actively wrong on a device with a resolution override - a Galaxy S8 running
1080x2220 on a 1440x2960 panel resets to the physical panel's density and leaves the UI oversized.
Read the original with wm density first and set it back explicitly.

Measuring retained activities Copy Chapter

adb shell dumpsys meminfo prints an Objects block with Activities and AppContexts.

The counts include objects that are garbage but not yet collected. Read it straight after N
recreates and you will see roughly N whether or not anything leaks, which looks exactly like a leak.
Force collection instead:

adb shell am send-trim-memory org.ppsspp.ppsspp COMPLETE

then wait around eight seconds and read. Repeat until two readings agree - three or four rounds is
normal, and a single trim is not enough.

The protocol that gives an answer you can trust: cold start and read the baseline, do N recreates,
trim until stable, compare. A sound build returns to the baseline; a leaking one sits at baseline+N
and stays there.

Worked example, Galaxy S8 on Android 9, same device and protocol, both builds confirmed by
versionName. Before the activity handover fix: 13 recreates left 13 Activities and 18 AppContexts,
stable across repeated trims. After: the same 13 recreates settled back to 1 and 6.

A JNI global reference is a GC root, so an activity pinned by one shows up here. This is a usable
check for JNI ownership bugs, not only Java ones.

logcat on a noisy device Copy Chapter

Filter to the process, since the tag alone is not enough:

adb logcat -d --pid=$(adb shell pidof org.ppsspp.ppsspp)

On a device with a chatty system - a Quest especially - the ring buffer can rotate the app's lines
away within seconds, which reads as "logging stopped" rather than "logging was lost". Start a stream
before launching the app instead:

adb logcat -c && adb logcat -s PPSSPP:V PpssppActivity:V   # in the background, then start the app

VR (Quest) Copy Chapter

• The VR flavor is a separate package: ./gradlew :android:assembleVrDebug, installing as
  org.ppsspp.ppssppvr. It can sit alongside the normal build.
• adb exec-out screencap returns solid black for an immersive app - it captures the 2D panel
  layer, which such an app does not have. Use the runtime's own line instead: a logcat entry like
  VrApi: FPS=73/72 ... App=2.67ms proves frames are being submitted and how much GPU time the app
  spent on them. Zero app time means the render loop is not producing.
• am start makes the activity topResumedActivity, but the shell keeps focus, so the app never
  gets a surface and the render loop does not restart. Re-entering an immersive app has to be done
  from inside the headset. A fresh am start -S after a force-stop does work.
• debuggerd -b <tid> needs root, so no native stacks from a retail headset.

Check which paths the device actually exercises Copy Chapter

Before concluding that a test covered something:

adb shell grep -E '^(MemStickDirectory|GraphicsBackend)' /storage/emulated/0/PSP/SYSTEM/ppsspp.ini

A plain filesystem path for the memstick means the SAF/content-URI code
(Common/File/AndroidStorage.cpp, ContentUri.java) is never entered, so a run on that device says
nothing about it - a recents list full of plain paths says the same. The VR flavor reads
ppssppvr.ini, not ppsspp.ini.

Async Savestates (`docs/async-savestates.md`) Copy Section

Async savestates

How savestate compression and file I/O were taken off the emulation thread, so saving and loading
don't stall the game long enough to glitch the audio. The worker and the operation queue are in
Core/SaveState.cpp, rewind in Core/SaveStateRewind.cpp, and the file format code in
Common/Serialize/Serializer.cpp. Written 2026-10-19; file references will drift.

Keep memory use low. A state is about 38 MB uncompressed, and much of the hardware we run on is
short of memory. So don't waste it: no full-size buffers beyond what an operation needs, freed when
it's done. Within reason, though; a brief extra buffer in a rare case is fine. See Memory.

Where the time goes Copy Chapter

Measured with Release headless on desktop x64, local disk, three commercial games:

The waits at the start of SaveStart::DoState (utility IO, sas mix, async IO, pending GPU drawing)
were under 0.2 ms. Phones are several times slower, and their storage can be much slower again, so
the worker column is the part that hurts. The emu thread keeps only the snapshot and the apply.

Structure Copy Chapter

Each operation splits into the part that touches emulator state (emu thread) and the part that
doesn't (worker).

• One savestate worker thread, with a FIFO job queue. Not g_threadManager: file work on a slot
  has to happen in order. On Android it holds an AndroidJNIThreadContext for its lifetime, since
  storage access can need JNI.
• Callbacks still run on the emu thread, from SaveState::Process(). The worker posts results to
  a completion queue that Process() drains, so callers see the same threading as before, only
  later.
• An operation goes through: queued, emu phase, worker phase, completion, callback. A load does its
  worker phase (reading) before its emu phase (applying).

Save Copy Chapter

1. Emu thread, in Process(): SaveStart::DoState into a fresh buffer (the snapshot). The waits
   and FlushPendingDrawing() stay here, and so does the saveStateGeneration bump.
2. Worker: compress (see Memory) and write the file, to <file>.tmp for a slot save, then for a slot save the rotation that SaveSlot's
   renameCallback does today (old file to .undo, .tmp to the real name), including the
   g_Config.Save() for the undo bookkeeping. Then set g_filesStale.
3. Completion: the callback, with "Saved State" or the failure. The message appears when the file
   is on disk, not at snapshot time, so a failed write is reported honestly. A failed write leaves
   the previous file in place (it only ever wrote the .tmp).

The thumbnail screenshot is already asynchronous and doesn't change.

A save to a path that already has a save queued, and not yet snapshotted, is a duplicate
keypress. It isn't queued again. Its callback is attached to the queued save and called with that
save's status and an empty message (so it shows nothing, and the queued save's own callback shows
the result once). Once the snapshot is taken, another save to the path is a new save: the game may
have moved on, or a load been applied, since.

A save to a different path is queued, and takes its snapshot right away like any other. At most two
save snapshots exist at once: a third save, while two are still being written, waits for the
older of them before taking its snapshot. Two quick saves to different slots are rare and briefly
cost one extra buffer; more than that isn't worth holding 38 MB each for.

Load Copy Chapter

1. Worker: read the header and check it, then stream the file through the zstd decompressor into
   the state buffer, while the game keeps running.
2. Emu thread, in the first Process() after the read completes:
   • For a slot load, snapshot the current state for load undo. This has to happen here, at the
     moment the game actually leaves that state, not when the load was asked for.
   • Apply the loaded state (LoadPtr), with everything Process() does around it today
     (hasLoadedState, Core_ResetException(), AV dump restarts, g_lastSaveTime).
3. Worker: compress and write the load undo snapshot to load_undo.ppst, and update
   sStateLoadUndoGame. This happens even when the apply failed: that's when the undo is most
   useful, since a failed load resets the game.
4. Completion: the callback, after the apply.

The game runs a frame or two longer before the loaded state takes over. That isn't observable,
since the load replaces all of it.

Ordering Copy Chapter

Operations still take effect in the order they were asked for:

• Emu phases run in queue order. A save queued after a load waits until that load is applied,
  and snapshots the loaded state, as it does today when both run in the same Process(). A load
  waiting for its file holds up only the emu phases queued behind it.
• Worker jobs run in queue order, so a save to a slot followed by a load of it writes before it
  reads.
• UI-thread file operations on slots wait for the worker (WaitForWorker(), for all jobs, since
  it's rare and short): UndoSaveSlot and DeleteSlot. UndoLoad is a load, so it's queued behind
  the load undo write like anything else. LoadSlot's existence check counts a slot with a save
  pending as existing. The thumbnail screenshot isn't the worker's, so its rotation doesn't wait.

What stays synchronous Copy Chapter

There's one code path. Waiting for it is WaitForWorker(), which simply blocks: worker jobs never
need the emu thread, so it can't deadlock.

• libretro: retro_serialize/retro_unserialize are in memory with no file I/O, and stay as
  they are. So does the freeze-frame feature (SaveToRam/LoadFromRam every frame).
• Verify stays synchronous.
• Shutdown and game switch (SaveState::Shutdown(), from the kernel's shutdown, which app exit
  goes through too): wait for the worker, so a save whose snapshot was taken is written. Then run the
  completions' bookkeeping (the undo slot in the config) without their callbacks, which can refer to
  an EmuScreen that's going away, and drop whatever is still queued, as before. A save still queued
  at that point (asked for in the pause menu, which doesn't run Process(), then quitting) is lost
  like it always was: by then most of the kernel has shut down, too late to take a snapshot.
• Loads at boot (auto-load, --state, opening a .ppst) and the debugger's game.state.* with
  wait already work through callbacks, and need no special handling. The game already ran at least
  a frame before a boot-time load applied.

Rewind Copy Chapter

Rewind snapshots used to compress on a std::thread per snapshot, which the next snapshot joined
(stalling if it was still running), and the whole restore ran on the emu thread: wait for the
compressor, decode (rebuild the full ~38 MB state from the base and the changed blocks), apply. The
snapshot itself (2-5 ms, mostly copying RAM and VRAM, already a ParallelMemcpy) stays on the emu
thread.

Now:

• The emu thread owns the ring itself (which slots hold what); compressing and decoding are jobs on
  the savestate worker, and the emu thread leaves the buffers a job uses alone until it's done.
• Compression runs on the worker. If the previous snapshot's job is still running, the snapshot
  is skipped and retried next frame rather than waited for: snapshots are best effort.
• The deltas get zstd on top (level 1: higher levels shrink them a little for a lot more time).
  The changed blocks still compress about 3x, so the ring takes about a third of the memory.
• Restore is an async load from memory: StartRestore() picks the state and has the worker
  decode it (queued behind the newest snapshot's compression, if that's still going), and
  FinishRestore() applies it on the emu thread. No snapshots are taken in between. No prefetching
  (see Memory).

Memory Copy Chapter

What each operation holds at its peak, against today:

Rules:

• No pools and no buffers kept between operations. Allocate a buffer when the operation starts
  and free it when it ends. A 38 MB allocation costs far less than the stall this design removes,
  and an idle emulator then holds nothing for savestates (rewind aside, which is opt-in and labelled
  a memory hog in the settings).
• At most two save snapshots at a time (see Save), and one load buffer at a time: a
  second load queued behind a first doesn't start reading until the first is applied.
• Stream compression in both directions. Saving, ZSTD_compressStream2 into a buffer that grows
  with its output, instead of allocating the worst case up front. It isn't streamed straight to the
  file, since the header holds the compressed size and seeking back to patch it in isn't safe on
  every kind of storage (Android's content URIs). Loading, ZSTD_decompressStream reads the file in
  chunks, so the compressed data never sits in memory in full. The file format doesn't change.
• Rewind adds nothing. The worker reuses rewind's existing buffers. There's no prefetching
  (decoding a likely target before the rewind is pressed), which would need a spare full-size buffer.

Later, if phone measurements call for it Copy Chapter

• MeasureAndSavePtr traverses the state twice (measure, then write). Writing into a buffer sized
  from the previous measurement plus slack would skip the measure pass, but needs bounds checks in
  the write pass.
• The apply is mostly DoState logic rather than copying; leave it unless it shows up.

Results Copy Chapter

Measured the same way as above (Release headless, desktop x64), on the emu thread:

Rewind deltas went from 4-13 MB to 1.3-3.8 MB each, at 10-24 ms of worker time.

Testing Copy Chapter

Headless, wsdbg and the game.state.* debugger commands cover all of it. game.state.save and
game.state.load take a slot instead of a path, which goes through the slot code like the save
and load keys: undo rotation, load undo, repeats. Use a scratch --memstick for that, not the app's,
or the tests overwrite real slots. wsdbg's --sync moves on when a request is acknowledged, not when
a wait result arrives, so put a :sleep between steps whose order matters, and one at the end.

Building (`docs/building.md`) Copy Section

Building and testing PPSSPP

Agent-oriented notes on the various build systems and test suites. This is the long version of the
"Build and validation" / "Testing" sections in AGENTS.md.

Build and Validation Copy Chapter

To verify that things build on Linux/Mac, use ./b.sh --debug. For Windows, use the Visual Studio solution in the Windows subdirectory
(Windows/PPSSPP.sln) - always build through it, even if a stray CMake-generated build/ directory exists at the repo root (e.g.
left over from WSL/MSYS2 experimentation); that directory is not the supported Windows build path and may not have a working
compiler toolchain wired up.

An agent can drive the VS solution non-interactively with MSBuild.exe instead of opening the devenv GUI. Locate it via
vswhere.exe (same tool/gotchas as described in the libretro section below) and build a specific project with /t:, e.g.:

$installPath = & "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe" -latest -property installationPath
$msbuild = "$installPath\MSBuild\Current\Bin\MSBuild.exe"
& $msbuild "Windows\PPSSPP.sln" /t:UnitTest /p:Configuration=Debug /p:Platform=<platform> /m

(swap /t:UnitTest for /t:PPSSPPWindows or another project name as needed; drop it entirely to build the whole solution).

On an ARM64 host, use $installPath\MSBuild\Current\Bin\arm64\MSBuild.exe instead. The MSBuild in
Bin\ itself runs emulated and picks the 32-bit x86-hosted compiler (bin\HostX86\arm64\CL.exe),
which can't always map the precompiled headers into its address space. Builds then fail
intermittently, every file of a project at line 1, with C3859: Failed to create virtual memory for PCH and C1076: compiler limit: internal heap limit reached. That looks like running out of
memory, but lowering /m or CL_MPCount doesn't help, and /p:PreferredToolArchitecture=arm64
has no effect. The build log's CL.exe path shows which host compiler ran.

`` is ARM64 or x64 - whichever the machine actually is, so look it up rather than
picking a default. The output directory follows it (Windows\\<configuration>\), which
makes building one and running the other an easy mistake. It is easiest to make on Windows-on-ARM,
where an x64 build runs anyway under emulation: everything appears to work, but it is slower than
the native build and any performance measurement from it describes the emulator rather than the
code. platform.machine() in Python reports the host; $PROCESSOR_ARCHITECTURE reports the shell,
which is AMD64 in an emulated shell even on an ARM64 machine.

In addition to the pspautotests runner (test.py), there is a separate binary with C++ unit tests
in the /unittest subdirectory. After substantial changes (at the end of a chunk of work, not
necessarily after every edit), run these too:

• Windows: build the UnitTest project (unittest/UnitTests.vcxproj), then run Windows//Debug/UnitTest.exe all (`` being ARM64 or x64, whichever you built)
• Linux/Mac: configure with -DUNITTEST=ON, then run build/PPSSPPUnitTest all

This runs all tests in availableTests in unittest/UnitTest.cpp. You can run one or more
specific tests by passing their names instead of all (space-separated, e.g. UnitTest.exe CmdLine Path Utf8); no arguments lists the available tests.

After a git stash/git stash pop that touches a header, do a /t:Rebuild rather than trusting
the incremental build. Stashing rewrites files with timestamps that can leave objects looking newer
than the header they were compiled against, so adding or removing a class member produces a binary
where translation units disagree on the object layout. That shows up as UnitTest.exe segfaulting
before it prints anything, for every test including ones unrelated to the change - which looks like
a catastrophic code bug and is not one. If a build starts crashing inexplicably right after a stash
cycle, rebuild before investigating anything else.

More generally, when you are bisecting a behavioural change, confirm the binary actually changed
before you believe the result - check the executable's mtime, or have the code you just added log
something you can grep for. A stale binary is indistinguishable from a real regression, and it lies
consistently, so a bisect on top of one produces a confident, entirely fictional answer. This cost
several hours once: a link that silently failed left a stale PPSSPPHeadless.exe in place, every
subsequent "revert this and retest" step reported the same failure, and a change was blamed that a
later clean rebuild proved innocent. The LNK1168: cannot open ... for writing case (a still-running
instance holding the exe, see Debugging) is the most common way to get there, which
is why killing leftover processes before building is worth doing unconditionally rather than only
when a build complains.

Known environment-specific issue: in at least one sandboxed dev environment, the Jit test
(unittest/JitHarness.cpp) hangs indefinitely specifically during the CPUCore::JIT_IR
phase - confirmed unrelated to source changes (reproduces identically on unmodified checkouts)
and not a memory-access fault (Memory::HandleFault is never entered). Root cause wasn't
pinned down further (would need a native debugger attached to the hung process, not available
in that environment) but is very likely specific to that sandbox rather than a real PPSSPP
bug, since CI runs the equivalent of UnitTest.exe all on every commit across multiple
platforms without apparent issue. If all/Jit hangs in your environment, run every other
test by name instead (skip Jit) to still get real coverage.

UWP build Copy Chapter

UWP has its own solution, UWP\PPSSPP_UWP.sln. Build the app with /t:PPSSPP_UWP (or a single
library such as /t:CoreUWP), same MSBuild setup as above:

& $msbuild "UWP\PPSSPP_UWP.sln" /t:PPSSPP_UWP /p:Configuration=Debug /p:Platform=<platform> /m

Android assets Copy Chapter

The APK's assets/ directory is the repo-root assets/ directory, wired up by
assets.directories.add("../assets") in android/build.gradle.kts. There's no copy step, so a file dropped
in assets/ ships as-is. ndk-build doesn't read assets at all, and nothing populates android/assets/ -
if you have one, it's a leftover from the old Ant/Eclipse build and is ignored.

Legacy Android build (android/jni) Copy Chapter

There is a legacy Android build using the raw NDK build system (android/jni/Android.mk + ndk-build), separate from the
gradle build in android/. It's hooked up on CI (see .github/workflows/build.yml, the android matrix entries) and is
useful for quick test builds (it can build ppsspp_headless and the unit tests for Android). You do not need to build it
by default, but if you want to test-build it locally:

• The NDK path is hardcoded in android/ab.cmd (Windows) or passed via the NDK env var to android/ab.sh (POSIX).
  It should match the ndkVersion in android/build.gradle.kts. The scripts just run ndk-build with a core count
  derived from the machine (nproc / %NUMBER_OF_PROCESSORS%).
• Example (POSIX): cd android && NDK=/path/to/ndk ./ab.sh APP_ABI=arm64-v8a HEADLESS=1
• The ppsspp_headless executable ends up in android/libs/<abi>/.

tvOS Copy Chapter

The tvOS app is the iOS app with the iPhone-only parts compiled out, checked with
PPSSPP_PLATFORM(TVOS) (tvOS also gets PPSSPP_PLATFORM(IOS)). The CMake side is the iOS toolchain
with -DIOS_PLATFORM=TVOS, which sets TVOS.

• ./b-tvos.sh builds an unsigned app into build-tvos-xcode/Release-appletvos/.
  DEVELOPMENT_TEAM=<team> DEVICE= ./b-tvos.sh signs it, registers the Apple TV with the team
  if needed, installs it and launches it with the console attached.
• To pair an Apple TV, put it on Settings > Remotes and Devices > Remote App and Devices. It doesn't
  show in xcrun devicectl list devices until paired; find it with
  dns-sd -B _remotepairing-manual-pairing._tcp and xcrun devicectl device info details --device <name>,
  then xcrun devicectl manage pair --device and enter the code it shows.
• ./b.sh --tvos --libretro (and ./b.sh --ios --libretro) build the libretro cores. tvOS has no
  sigaltstack, among other things, so this is the build that catches it.
• There's no tvOS simulator build: FFmpeg has no tvOS simulator libraries.
• tvOS apps have no persistent storage except about 500 KB of NSUserDefaults. Anything else may be
  purged, so the memory stick is in Caches for now.

libretro core build (Windows) Copy Chapter

Canonical instructions are in libretro/README_WINDOWS.txt - read that first, this is a summary plus
agent-specific gotchas. The libretro core (ppsspp_libretro.dll) is built with a real make, not the
Visual Studio solution, even on Windows - it uses cl.exe/link.exe as the compiler/linker (via
platform=windows_msvc2019_desktop_x64), but orchestrated through GNU Make running inside an MSYS2
shell (a plain MSYS2 install, not "Git Bash" - typically at C:\msys64, needs pacman -S make).

cd libretro
make DEBUG=1 platform=windows_msvc2019_desktop_x64 -j32

(drop DEBUG=1 for a release build; -j count doesn't need to match logical CPUs exactly). To test the
result, copy ppsspp_libretro.* into wherever the local RetroArch install reads cores from (e.g. its
cores/ directory) and load it from within RetroArch.

An agent can drive this non-interactively by invoking C:\msys64\usr\bin\bash.exe -lc "..." directly
as a subprocess (the -l login-shell flag matters - it's what sets up MSYS2's own PATH, make,
cygpath, etc. correctly). In a sandboxed/agentic invocation (as opposed to a normal interactive MSYS2
terminal a human opens), two Windows environment variables the Makefile's VS-detection logic depends on
may not be inherited by the spawned process - COMSPEC (breaks the cmd //c "bash VSWhere.sh ..." call
used to locate Visual Studio) and ProgramFiles(x86) (which VSWhere.sh itself needs to find
vswhere.exe). If VS auto-detection fails this way, skip it by overriding VsInstallRoot directly on
the make command line (GNU Make command-line variables take precedence over the Makefile's own :=
assignment of the same name):

make VsInstallRoot="/c/Program Files/Microsoft Visual Studio/<year>/<edition>" DEBUG=1 platform=windows_msvc2019_desktop_x64 -j32

(path in MSYS2/cygpath POSIX form, not a raw Windows path; find the real value via vswhere -latest -property installationPath if unsure of <year>/<edition>). This is a real full compile+link - prefer
it over trying to syntax-check libretro-specific files with a standalone cl.exe /Zs invocation, which
can miss real bugs (e.g. an include-order issue that leaves a platform macro like
VK_USE_PLATFORM_WIN32_KHR undefined before vulkan.h's first, include-guarded inclusion, since a
narrower manual include-path/define set used for a syntax-only check may not reproduce the actual build
step's ordering).

Headless and unittest builds Copy Chapter

We have additional PPSSPPHeadless and unit test builds (/headless and /unittest), that have their own separate
main functions (and also stub out most of the System_ functions as needed). Take these into account
when making cross platform changes.

New unit tests are added by listing them in availableTests in unittest.cpp. If they are large, put them in
separate files in the unittest subdirectory. A new file has to be listed in three build files, not two:
CMakeLists.txt, unittest/UnitTests.vcxproj (and its .filters), and android/jni/Android.mk, which
builds a unit test executable of its own. The Android one is the easiest to forget, since missing it builds
fine everywhere you are likely to try it and only fails on Android CI.

A unit test is often the first thing to call a given function from outside its own .cpp, which makes the
ppsspp_unittest target in the legacy Android build (android/jni/Android.mk, see above) the strictest check
we have: MSVC links an inline function defined in a .cpp anyway, clang correctly does not. So a test can
build and pass on Windows and fail to link only on Android CI, with an undefined symbol pointing at a header
line. Fix it by dropping the bogus inline from the definition, not by avoiding the call.

The compilers also disagree about floating point contraction, which matters for any test asserting that a JIT
is bit-identical to its C++ reference. Clang folds a * b + c into a single fused multiply-add by default;
MSVC never does, under /fp:precise, in Debug or Release. So on arm64, where the JITs emit FMLA, a
reference written as a * b + c matches on Mac, Linux and Android and is off by one ULP on Windows on ARM.
Don't leave it to the compiler: write fmaf(a, b, c) when the fused result is wanted (MSVC compiles it to a
single fmadd), and a * b + c when it isn't. PrescaleUV in GPU/Common/VertexDecoderCommon.cpp picks per
architecture, matching what each JIT does. x86 doesn't have the problem, since the SSE2 baseline has no FMA
instruction to contract into.

pspautotests are a large set of tests of the PSP OS's API surface, and thus tests our HLE implementation.

To check for regressions, run them exactly the way CI does (see .github/workflows/build.yml):

python test.py -g --graphics=software

The -g matters. test.py keeps two lists: tests_good (the regression set - these pass and must keep
passing, ~314 of them) and tests_next (work-in-progress tests that are expected to fail, i.e. the to-do list).
-g runs only tests_good; with no flag you get tests_next + tests_good and around a hundred failures that mean
nothing is wrong. Don't go hunting those, and don't report them as regressions - the only meaningful result from
-g is 0 tests failed. (-b runs only tests_next; -m prefix-filters whichever list is selected.)

Note the runner prints a debug-CRT "Detected memory leaks!" dump after the summary line on Windows debug builds.
That's normal and not a test failure - read the N tests passed, N tests failed line, which comes before it.

See docs/pspautotests.md for a workflow for running pspautotests and improving PPSSPP with the results.

LoongArch64 and RISC-V JITs under qemu Copy Section

CI tests these JITs by cross-building headless and running pspautotests under qemu-user, and you can do the
same on Linux (packages: gcc-14-loongarch64-linux-gnu g++-14-loongarch64-linux-gnu qemu-user, or the riscv64
equivalents):

./b.sh --loongarch64 PPSSPPHeadless     # builds into build-loongarch64/
mkdir -p build-qemu
printf '#!/bin/bash\nexec qemu-loongarch64 -L /usr/loongarch64-linux-gnu "$(dirname "$0")/../build-loongarch64/PPSSPPHeadless" "$@"\n' > build-qemu/PPSSPPHeadless
chmod +x build-qemu/PPSSPPHeadless
python3 test.py -g --graphics=software --cpu=jit-ir --timeout=60 --known-failures=loongarch64

test.py runs the most recently modified build*/PPSSPPHeadless, so touch the shim after rebuilding the real
binary, or it runs your native build instead. The full suite takes a couple of minutes.

qemu reports LSX and LASX as present, so CI only exercises the LoongArch vector paths.
The scalar fallbacks never run here, so passing tells you nothing about them.

The 32-bit ARM JIT works the same way with ./b.sh --armhf (into build-armhf/) and qemu-arm -L /usr/arm-linux-gnueabihf. The cross packages are gcc-14-arm-linux-gnueabihf g++-14-arm-linux-gnueabihf, and
sudo cmake/scripts/setup-cross.sh armhf adds the GL and EGL stubs the link needs. Without root, apt-get download
the packages, dpkg-deb -x them into one directory, and point CROSS_ARMHF at it: the toolchain file then takes
the sysroot from $CROSS_ARMHF/usr/arm-linux-gnueabihf. The binutils need LD_LIBRARY_PATH to include
$CROSS_ARMHF/usr/lib/x86_64-linux-gnu, glibc's libc.so linker script names absolute paths that have to be
rewritten to the new root, and the stubs are copied in by hand. For a debugger, run qemu-arm -g PORT and attach
gdb-multiarch to it.

hash/hash dies with a bus error under qemu-arm on every CPU core, so it's not a JIT problem, but it takes the rest
of its batch down with it: pass --known-failures=armhf.

Without a cross toolchain (on macOS, say) two things still help:

• A syntax check of the other JITs. The RISC-V and LoongArch backends (Core/MIPS/RiscV,
  Core/MIPS/LoongArch64 and their emitters) have no architecture guards, so the host compiler can check
  them: clang++ -fsyntax-only per file, with the -I/-D/-std/-isystem flags of any Core file from
  compile_commands.json, plus -I<repo> -I<repo>/ext -I<repo>/Common (the database's include paths are
  relative to the build directory). Check that a copy with a deliberate syntax error does report errors: zsh
  doesn't word-split a $FLAGS variable, which once made a broken check look clean. This proves the code
  compiles, nothing about its output.
• The portable software-renderer paths. riscv64 and loongarch64 run the software renderer's non-SSE,
  non-NEON C++ paths, so their test failures reproduce natively: wrap the two NEON defines in the
  __aarch64__ block of ppsspp_config.h in #ifndef PPSSPP_TEST_NO_SIMD, configure a separate
  build-nosimd with -DHEADLESS=ON and -DPPSSPP_TEST_NO_SIMD in CMAKE_C_FLAGS and CMAKE_CXX_FLAGS,
  and build PPSSPPHeadless there. Delete it and revert ppsspp_config.h afterwards, since test.py keeps
  picking the newest binary. A failure that's the same on both architectures points at the portable path, not
  the JITs.

Quick rebuild on Linux Copy Chapter

You don't need to do ./b.sh --debug to verify every single little change, instead use this shortcut:

cd build ; make -j32; cd ..

Command Line (`docs/command-line.md`) Copy Section

Command-line parsing

All command-line parsing for both the main app and the headless build belongs in Core/CmdLine.cpp /
Core/CmdLine.h (CommandLineOptions), not in the platform entry points (Windows/main.cpp,
headless/Headless.cpp, UI/NativeApp.cpp, etc.). Don't re-parse argv in those files - add a field
to CommandLineOptions instead.

Declaring an option Copy Chapter

Most options are declared in the g_autoParams table in CmdLine.cpp as:

{offsetof(...), type, longName, shortName, docString, mode}

mode gates the option to CmdLineMode::Application, ::Headless, or ::Both (the default if the
field is omitted from the initializer).

The same long name can be reused for both modes with different types and meanings, because a given
Parse() call only matches params whose mode is Both or equal to the current mode. --log is the
example to know: a String "log to FILE" option in Application mode, a Bool "full log output" option
in Headless mode. They don't collide.

Options that can be repeated (e.g. --ignore TESTNAME, collected into a std::vector<std::string>), or
that don't fit the generic single-value table, need manual handling in the else if chain inside
CommandLineOptions::Parse() - the same way --graphics= and the boot filenames are handled.

Getting a parsed option into the emulator Copy Chapter

ApplyToConfig() is where parsed options are pushed into g_Config / g_logManager. Prefer wiring a
new option through there, so every platform gets it for free, rather than reading CommandLineOptions
fields ad-hoc at each call site.

NativeInit() in UI/NativeApp.cpp still takes argc/argv, because several platform entry points
pass them in, but it shouldn't read them directly: by the time NativeInit() runs,
CommandLineOptions should already hold everything.

Cpu Equivalence (`docs/cpu-equivalence.md`) Copy Section

CPU core equivalence

The goal: every CPU core (interpreter, IR interpreter, JIT, IR JIT) produces the same bits on every
host (x86-64 and ARM64), NaN payloads (and possibly NaN signs) aside. Where the cores disagree, the
hardware decides which one is right, so several items below need a test on a real PSP before they
can be fixed.

The fuzzer Copy Chapter

UnitTest CPUEquivalence (in unittest/JitHarness.cpp) generates random code (ALU, immediate,
FPU, VFPU, loads and stores, optionally forward branches) and a random start state, runs it on every core, and
compares the full end state against the interpreter: GPRs, FPRs, VFPU registers and control
registers, hi/lo, fcr31 (bit 23 aside, which some cores sync from fpcond and some don't), fpcond,
llBit, 1KB of scratch memory, and the cycles charged up to the terminating syscall. NaNs compare
equal to each other. Loads and stores go through k0, which points at the scratch memory and is
never written.

Each differing case is minimized (instructions dropped while it still differs, or turned into nops
when the code has branches, so none moves its target) and printed with its inputs. It ends with a count of the reported cases by their last instruction, which is usually the
one at fault. By default only a crash fails the test, as known differences remain.

Environment variables:

For quick rounds while working on some instructions, fuzz just those, on every core of the machine:
PPSSPP_CPUFUZZ_OPS=dot Tools/cpu_fuzz_parallel.py build/PPSSPPUnitTest --count 2000 splits the seeds
over several processes and sums up the results.

Once a block ends with a prefix uneaten, the IR frontend stops assuming that blocks start with the
default prefixes (startDefaultPrefix), for as long as the JIT exists. In a run, the first case that
leaves a prefix does this, so whether a later case compiles one way or the other depends on the
cases before it, and a difference may not reproduce with that seed alone.
PPSSPP_CPUFUZZ_UNKNOWNPREFIX puts every core into that mode first.

Always set CI=1 when running it from a script on Windows. Otherwise a JIT assert opens a message
box and the run hangs until someone clicks it.

Tools/cpu_fuzz_reduce.py runs the fuzzer and, if a case crashes (usually a JIT emitter assert),
finds it and reduces it to the instructions still needed for the crash. A crash that only happens
after other cases have run usually means uninitialized or stale state, not the reduced code.

To compare hosts: run with the same seed and count and PPSSPP_CPUFUZZ_DUMP on each, and diff the
files. Each line starts with the core and the seed. A Windows-on-ARM machine can run the x64 build
under emulation, which is enough for the host-dependent float behavior of the cores. It isn't for
timing, of course.

Fixed Copy Chapter

Crashes (JIT emitter asserts) and wrong code found by the fuzzer. Entries for the "ARM64 JIT", the
"x86 JIT" and "both JITs" are about the legacy JITs, which have since been removed. Every JIT is now
IR-based (the "IR JIT" and "native IR backend" entries).

• ARM64 JIT: ext with pos + size past 32, and ins with msb below pos, asserted in UBFX/BFI.
• ARM64 JIT: ApplyPrefixST read an uninitialized register for a swizzle naming a lane past the
  op's size. The ARM64 JIT now gates its VFPU ops on prefixes the way the IR frontend does (vdot,
  vcmp, vi2f, vi2x, vocp, vhdp, vcmov, the matrix inits), and the x86 JIT got the gates it was
  missing too (vdot, vhdp, vcmp, vf2i, vh2f, vi2f, vi2x, vocp, vsgn, the color conversions, the
  matrix inits, vmmov, vmscl).
• ARM64 JIT: vdot, vhdp, vmmul and vqmul used fused multiply-add, which rounds differently from
  every other core. They now multiply and add separately, in the interpreter's order.
• vcmov in both JITs ignored a T prefix, which the interpreter applies to D (read as T).
• IR: vmmul, vmscl, vmidt/vmzero/vmone and vmmov on a 1x1 matrix flipped the transposed bit, which
  for 1x1 selects a different register. vmmul's fallback never wrote a 1x1 result at all.
• IR: vmmul, vtfm, vmscl, vmmov and the matrix inits took a matrix that isn't a plain Vec4 layout to
  be a transposed one, so a 4x4 matrix with a row/column offset (like E723 or M212) produced
  Vec4 ops on unaligned registers. Native IR backends asserted, the IR interpreter computed garbage.
• IR: with every lane write-masked by the D prefix, the destination lanes were all D temps, which
  looked like a Vec4, and the mask blend then went into an unaligned destination.
• x86 JIT: sc into $zero wrote its result to an immediate and asserted. vmmul's SIMD path
  crashed on vmmul.s and on matrices that wrap around (MatrixWrapsAround()), which now go to
  the interpreter and the scalar path.
• Native IR backends (all four): ll into $zero mapped $zero for writing and asserted.
• ARM64 and x86-64 IR JITs: sc didn't mark rt dirty, so its 0/1 result was lost.
• IR interpreter: never applied the guest's rounding mode or flush-to-zero (fcr31) on block entry,
  only after a ctc1 in the same block. It now does what the native dispatchers do, and leaves the
  host's mode in place around syscalls and replacement functions.
• JITs: the mode was only taken into account once a ctc1 had been compiled (js.hasSetRounding),
  so a mode from a savestate made on another core, a core or thread switch, or an interpreted
  ctc1 was ignored, and syscalls then ran in the guest's mode. UpdateFCR31() now sets the flag
  and throws away the blocks compiled before. Ops left to the interpreter run in the guest's mode,
  except syscalls, and an interpreted ctc1 takes effect at once. CPURoundingMode tests all of
  this on every core, with and without JitDisableFlags.
• ARM64 JIT: mfhi/mflo into $zero wrote the host register holding zero.
• x86-64 IR JIT: helper calls (vsin, vrsq and the like) didn't flush RCX and RDX outside Windows,
  where the System V ABI doesn't preserve them.
• MIPSAnalyst: ctc1/cfc1 of a control register other than 31 counted as touching the FPU
  condition, so the x86 JIT's register cache dropped a dirty fpcond before one.
• x86 JIT: fpcond held the compare's all-ones mask instead of 1.
• ARM JITs: vmfvc of a control register past the defined ones mapped the dest without
  MAP_DIRTY, so its 0 was never written.
• IR: vmmov between transposed matrices whose rows wrap around (like E020) produced unaligned
  Vec4 moves, which crashed the x86 IR interpreter.
• RISC-V and LoongArch64 JITs: see below.
• The legacy JITs' Comp_Generic ran the interpreted instruction in the host's default rounding
  mode instead of the guest's.
• IR: vmscl and the matrix inits of two transposed matrices flipped the transposed bit to get
  Vec4s, which for a matrix with an offset (one that wraps around) names other registers. vmscl
  also took its Vec4 path before checking that the matrices don't partly overlap.
• IR: vc2i and vuc2i read their source as a single, not as the first lane at the size encoded.
• IR: vf2i and vi2f wrote each lane straight to a destination that could hold a later lane's source.
• IR: vcmov under a saturating D prefix left lanes that didn't move with whatever the D temp held.
• IR: vmtvc to a control register that masks its value read the VFPU register numbered like the
  control register.
• IR OptimizeFPMoves: propagated a copy into a multi-lane result covering the copied register,
  and into the src3 of ops where it's also the destination (FCmovVfpuCC), moving the result.
• IR OptimizeLoadsAfterStores: compared offsets as unsigned, so a store at -16 of 16 bytes didn't
  cover a load at -12, which reused the value from before the store.
• Native IR backends: flushing a host register that cached $zero left it mapped, so after a call
  that clobbered it (the dot product routine), a store of $zero stored garbage.
• The IR frontend continues past conditional branches, so a block can now leave with a prefix
  pending at a mid-block exit. It doesn't continue then, as only the end of a block checks that.
• Hardware answers 1, 2 (host agreement), 5, 7 (the interpreter and vcmov), 8, 9 and 10 below.

Timing, which decides when interrupts, thread switches and other events happen, so a difference
sends a game down a different path on each core:

• IR: j, jal, bc1t and bc1f didn't charge their delay slot.
• IR: a syscall charged itself before running, or, in a delay slot, never. It now sees every
  earlier instruction charged and is charged once it returns, as in the interpreter.
• Interpreter: a skipped likely delay slot cost 1 cycle, the IR cores charge what it would cost.
• Interpreter: it checked downcount after every instruction, the IR cores only between blocks. It
  now runs to the same block ends (branches and jumps after their delay slot, syscalls, breaks,
  replacements), so events happen at the same instruction. Its fast loop also charged a branch
  and its delay slot together after both, so a syscall in the slot didn't see the branch.

The interpreter also follows the IR frontend on past a conditional branch that isn't taken
(IR_CONTINUE_BRANCHES), with the same limits, except in one case it can't see: the IR takes a
prefix register written by mtvc or vmtvc, or by a VFPU op it interprets that doesn't consume
prefixes, as unknown, where the interpreter goes by the value. Games set prefixes with vpfx.
The fuzzer only compares cycles at the end, so it doesn't see where a block ends; a trace of
syscalls and thread switches from a game does (God of War, Tekken 6 and Daxter agree on all three
cores).

Open differences Copy Chapter

The goal, in order: every core gives the same result on both hosts, and then that result is the
PSP's. Where matching the PSP is expensive, agreeing with each other comes first.

Answered on hardware Copy Section

Each of these has a pspautotests test recorded on a PSP (6.61). Distinct outputs across the eight
configurations (four cores, ARM64 and x86-64 under Rosetta), and lines that differ from the PSP.
The jit columns were measured with the legacy JITs, since removed; jit is now jit-ir on both.

Before the fixes, shift_encodings had 2 outputs and fcr31 7. nan_gen, fpu_nan and
denormal still come out as each host's own NaNs (item 6). What's left of fcr31 is items 3 and
vdot's summation, and of undefined the horizontal ops and matrix registers with an offset that doesn't fit the size. Rosetta behaves as an x86 CPU here: the x86-64 interpreter made
0xFFC00000 NaNs and flushed denormal results but not inputs under FS (FTZ without DAZ).

The fuzzer agrees: integer, FPU and memory code (PPSSPP_CPUFUZZ_CLASSES=aaiiffm) gives the same
end state on every core and on both hosts in 20000 cases, apart from item 11 below. With VFPU code
mixed in, the interpreter differs between the hosts in 7 of 20000 cases, each a host NaN out of a
horizontal op (vmmul, vtfm, vdot, vdet) that vmin, vmax or vf2i then orders or converts by its
sign.

1. srl/srlv with stray bits (shift_encodings, fixed). Only the low bit of the unused field
   counts: srl rotates when bit 21 is set and shifts when it is clear, whatever bits 22-25 hold,
   and srlv the same with bit 6. sll/sra/sllv/srav ignore the field. The Allegrex bit ops
   (allegrex_encodings, fixed) decode only part of their op field too, so every value is one of
   wsbh, wsbw, seb, seh and bitrev (see AllegrexBitOp()), and special3 function 0x18 is a no-op.

2. Flush-to-zero (FS) (denormal). With FS clear the PSP handles denormals in full, which
   both hosts match. With FS set it flushes denormal results to zero, with tininess decided before
   rounding (a product that rounds up to FLT_MIN is still flushed), but never flushes inputs: sqrt,
   div and the compares see a denormal as it is. One exception: add/sub with a zero operand
   returns the other operand, denormal or not. x86 FTZ gets all of it but that exception (16
   lines). ARM64's FZ also flushes inputs (54 lines). The x86 cores now set DAZ along with FTZ, so
   both hosts flush inputs and agree, 54 lines away from the PSP. Matching the PSP needs either
   the x86-like mode where ARM64 has it (FEAT_AFP: FPCR.AH with FIZ clear, not on every device),
   or flushing results in software when FS is set.

3. fcr31 doesn't affect the VFPU (fcr31). All six fcr31 settings give identical results.
   The VFPU always rounds to nearest, and always flushes denormal inputs and outputs to zero
   (vf2iu of a denormal is 0, a denormal times 1 is 0). The cores should run VFPU ops in
   round-to-nearest without guest FS, and flush denormals themselves, rather than inheriting the
   FPU's mode. Some of the remaining lines are vdot's exact summation (1.5u + 1.5u + 3 - 3 is 0
   on the PSP). The cores agree with each other here (they all follow fcr31), so this is about
   matching the PSP. A check on every VFPU op would cost too much. Since games run VFPU ops in
   clumps, switching the host into round-to-nearest with flush-to-zero (inputs too) around a clump
   and back afterwards may be cheap enough; not tried yet. The ops that move to the accurate dot
   product get this right by themselves.

4. Signed zero from sums (signed_zero). Every summing op returns +0 for a zero sum,
   whatever the signs of the products: vdot, vhdp, vfad, vavg, vdet, vcrsp, vqmul, vmmul, vtfm,
   vhtfm, at every size, including vfad of all -0. vcrs (a product per lane) and plain vadd keep
   -0. The interpreter is right apart from vcrsp, vqmul and vtfm/vhtfm.

5. vmin/vmax and denormals (fcr31). Denormals compare equal to zero, a tie returns the
   second operand, and the result keeps the operand's bits (a denormal comes out unflushed). Fixed
   on every core with vfpu_minmax_key(), an integer key compared instead of the floats
   (minmax_zero and minmax_tie pass everywhere).

6. Generated NaNs (nan_gen). VFPU arithmetic never keeps a payload: every NaN it produces is
   0x7F800001 or 0xFF800001. The sign is + for add, sub and every summing op, the XOR of the
   operand signs for mul, div and vscl, the input's sign for vrcp, vrsq, vsin and vasin, and + for
   vsqrt, vlog2 and vexp2. vsat0/vsat1, vabs and vneg pass NaN bits through. The cores make the
   host's NaN instead, so x86-64 and ARM disagree. The
   branch cpu-equiv-4 fixes the single-lane ops (vadd, vsub, vmul, vdiv, vscl, vcrs, vsat0/1, vbfy,
   vocp, vsocp) on every core, through four new IR ops and checks in the legacy JITs, and is held
   back until its cost on every multiplication is measured. The horizontal ops wait for the
   accurate dot product.

   The FPU makes the positive quiet NaN 0x7FC00000 from operands that aren't NaN
   (cpu/fpu/fpu_nan), which ARM64 does and x86 doesn't for add, sub and div. Also fixed on
   cpu-equiv-4.

7. Undefined VFPU encodings (undefined). The interpreter matches the PSP on all of them
   (single-lane vdot/vhdp, vdet at every size, vcrsp/vqmul at .s/.p, matrix registers that wrap
   around, vtfm/vhtfm size mismatches, vmfvc past register 15 reading 0, vcmov with bit 20 set),
   now including vcmov with imm3 = 7, which tests a CC bit that is always clear: vcmovt never
   moves and vcmovf always does (fixed on every core). The JITs still differ on the single-lane
   dot products and vcrsp/vqmul at .s/.p (for the accurate dot product). The IR cores now match on
   matrix registers whose offset doesn't fit the size (see Fixed).

8. Loads and a pending D prefix (prefix_load, fixed). lv.q, lv.s, lvl.q, lvr.q and mtv write
   every lane, ignoring the D prefix's mask and saturation, and leave it pending. The interpreter
   applied the mask to lv.q, lvl.q and lvr.q (and the IR cores, which hand lvl.q and lvr.q to it).

9. vfim (vfim, fixed). The half float converts like vh2f: denormal halves give a signed zero,
   inf and NaN keep their mantissa bits in place. The interpreter halved denormals, the IR made
   them IEEE.

10. bltzal and friends with rs = ra (branch_link_ra, fixed). The branch tests ra's value from
    before the link. Every core linked first.

Known, no hardware test needed Copy Section

11. Divide-by-zero flags. Only the interpreter sets the cause and flag bits for div.s by zero
    (see Int_FPU3op). The other cores leave fcr31 alone. Making the others match needs a new IR op
    or an interpreter fallback for div.s, and the latter costs every division.

ARM32 Copy Section

Measured on a Galaxy S8+ and A21 with the armeabi-v7a build (android/ab.sh APP_ABI=armeabi-v7a HEADLESS=1 UNITTEST=1 SKIPAPP=1, run over adb). These measurements predate the IR-based ARM32 JIT, when
CreateNativeJit returned the legacy ArmJit (since removed). The IR JIT gives the IR interpreter's
end state in every fuzz case under qemu-arm (./b.sh --armhf, see building.md).

• The interpreter gives the same end state as on ARM64 in all 20000 integer/FPU/memory fuzz
  cases, and in all but 3 of 20000 mixed ones (horizontal-op NaNs into vmin/vmax, as on x86-64).
• All three cores match the Mac's same core on every cpu/ pspautotest, apart from horizontal ops
  and NaNs: signed_zero (vdet, vqmul in the JIT), nan_gen, and in the JIT the NaNs out of vsat
  (prefix_sat) and vbfy (specials). Those wait for the accurate dot product and item 6.
• What it took: the interpreters apply the guest's FPSCR (rounding mode and FZ); the IR
  interpreter's NEON Vec4 paths are ARM64-only, since ARMv7 NEON always flushes and rounds to
  nearest; ARM32's libm ceilf/floorf don't flush a denormal input, so FlushForConversion()
  does that under FS; and the ARM JIT got the other JITs' prefix gates, mtvc masking, and fixes to ins/ext/max/min, round.w.s of NaN, and vsgn. vh2f and vasin go to the
  interpreter (the hardware half conversion quiets NaNs).
• Before these JIT fixes, the fuzzer on the S8+ had the JIT differ from the interpreter in 1298
  of 20000 mixed cases (the IR interpreter in 1446), not broken down. It crashes on the A21 in its
  memory setup, so it hasn't been rerun since.

RISC-V and LoongArch64 Copy Section

Run under qemu-user on x86-64 Linux (cross toolchains from Ubuntu's gcc-15-riscv64-linux-gnu and
gcc-15-loongarch64-linux-gnu, configured with -DHEADLESS=ON -DUNITTEST=ON). Each has three
cores, and the JIT is the IR JIT. RISC-V detection only reports Zba/Zbb/Zbs/Zicond for two SoCs and
never Zcb or Zfa, so the fuzzer forces them with PPSSPP_CPUFUZZ_HOSTEXT=+ (under
QEMU_CPU=max); LoongArch runs both with LSX (qemu's la464) and without (-).

Fixed:

• RISC-V emitter: c.lbu/c.sb (Zcb) had their two offset bits swapped, so byte loads and
  stores at offset 1 or 2 went to the wrong byte.
• RISC-V emitter: CanFLI took any NaN for FLI's canonical one, so vfim of a NaN lost its
  sign (Zfa).
• LoongArch JIT: vsat0/vsat1 turned a NaN into the bound (FMIN/FMAX return the non-NaN
  operand), and vcmp NE was false for a NaN.
• Both JITs: Vec4Dot (vdot, vhdp, vtfm, vmmul) used fused multiply-add. Without SIMD it now
  multiplies and adds in the IR interpreter's order; LoongArch's LSX path adds pairwise, like
  the x86 and ARM64 JITs.
• Interpreter: vsgn of a negative NaN gave 1 on RISC-V, whose subtraction always makes the
  positive canonical NaN.
• RISC-V emitter: vmv.s.x and vfmv.s.f were encoded as vmv.x.s and vfmv.f.s, writing the
  scalar register instead of the vector (nothing used them before the dot product routine).

The accurate dot product (Vec4VfpuDot) runs through a routine both JITs generate at startup and
call, like the ARM64 and x86-64 ones (RiscVVfpuDot.h, LoongArch64VfpuDot.h). RISC-V has a
scalar version, which uses Zbb and Zicond where it has them, and an RVV one used when the V
extension is detected. LoongArch has an LSX version and a scalar one. Inf and NaN go to
vfpu_dot_reference(). In the interpreters, vfpu_dot() is vfpu_dot_scalar() on RISC-V and
vfpu_dot_lsx() on LoongArch. The VFPUDotJit unit test runs every variant the host can run
against the reference on VFPUDot's inputs. Whether the RVV version beats the scalar one on real
hardware hasn't been measured: it moves values between the vector and scalar units three times,
which costs more on some cores than on others.

Neither JIT has Vec4VfpuMultiDot, so the frontend leaves runs of dots as single
Vec4VfpuDots for them (IROptions::vfpuMultiDot). Both have the Vec4 vmin, vmax, vslt, vsge and
vi2f ops (IROptions::moreVec4Ops), lane by lane on RISC-V and on LoongArch without LSX.

Before the accurate dot product, the JIT gave the same end state as the IR interpreter in 20000
VFPU-heavy cases (vvvf), 20000 mixed and 10000 integer/memory ones, on RISC-V with and without
the extensions and on LoongArch without LSX. What was left were host NaNs out of a horizontal op
that something then orders by sign (item 6), and with LSX the summation order of the dot product.
With it, the JIT matches the IR interpreter bit for bit in 20000 default cases on LoongArch with
and without LSX, and in 6000 on RISC-V with RVV, without V and the extensions, and with the
extensions. The same holds in at least 4000 dot product cases (PPSSPP_CPUFUZZ_OPS=dot) in each of
those, and with unknown prefixes.

Against the other hosts:

• Neither ISA can flush denormals, so FS does nothing (cpu/fpu/fpu and cpu/fpu/denormal fail,
  63 lines from the PSP where x86 and ARM64 have 54). Both are in known_failures in test.py.
• RISC-V never propagates a NaN operand: every NaN it makes is 0x7FC00000, which matches the
  PSP's FPU (cpu/fpu/fpu_nan passes) but loses a NaN's sign and payload (cpu/fpu/roundmode).
  LoongArch propagates operands like x86 and makes the positive default NaN like ARM64, and also
  passes fpu_nan.
• Every core gives the same results as on x86-64 in 20000 integer/FPU/memory cases but one, a
  div.s of a denormal under FS. With VFPU code, the interpreters differ by host NaNs from
  horizontal ops into vsbn, vmin, vmax or vscmp.

Not looked into yet Copy Section

• In 32000 default cases, the IR cores now differ from the interpreter only in item 11, on ARM64.
• Backward branches and loops: the generated branches only go forward. Prefixes across blocks only
  as far as a forward branch carries them.

Unrelated Copy Chapter

Headless used to take -r for the IR interpreter, but --root (whose short form is -r) won and took
the next argument as a directory. The short cpu core flags are gone now; use --cpu=ir.

Debugging (`docs/debugging.md`) Copy Section

Debugging PPSSPP (agent notes)

How to drive PPSSPP's debugger facilities from a script or agent session, and the traps around them.
The WebSocket protocol reference itself is in WebSocketDebugger.md; the
threading rules for debugger code are in DebuggerThreading.md.

WebSocket debugger Copy Chapter

PPSSPP has a JSON/WebSocket debugger and automation API (connect, read/write memory, search memory for values or byte
patterns, set breakpoints, step the CPU, label data symbols, read GPU state, inject input, tail logs, etc.), served on
the same port as Remote ISO sharing at /debugger with subprotocol debugger.ppsspp.org. Implementation is in
Core/Debugger/WebSocket.cpp and Core/Debugger/WebSocket/*Subscriber.cpp (one file per feature area, each
documented at the top). Enable it via Settings > Tools > Developer Tools > "Allow remote debugger",
RemoteDebuggerOnStartup in the config, or --debugger=PORT on the command line (0 = pick a port automatically) -
works on both the application and headless builds. On headless it also forces a break at start (startBreak), so the
CPU halts before anything runs. The bundled web GUI at /debugger/ comes from the assets/debugger submodule
(unknownbrackets/ppsspp-debugger, bundled branch).

The bundled branch only holds built output, so assets/debugger/static/js/main.*.js in this tree is minified -
don't try to answer "does the web GUI use this event/parameter?" by reading it, the identifiers are mangled and you
will guess wrong. The unminified source is at https://github.com/unknownbrackets/ppsspp-debugger (default branch,
not bundled) - fetch or grep that when you need to know what the official client actually sends, e.g. before
changing or removing part of the protocol.

Before touching this interface, read docs/WebSocketDebugger.md - it has the full protocol reference and event
catalog (including which events are read-only vs. require cpu.stepping first). Don't guess event names or
parameters from memory; the doc (and each *Subscriber.cpp file's per-handler comments) is the source of truth, and
new events get added over time (e.g. memory.search, hle.data.*).

When adding new commands, don't forget to update docs/WebSocketDebugger.md,

To quickly get a live session going for manual testing (e.g. after adding/changing an event): build PPSSPPWindows
(see Building and testing), then run it with --debugger=PORT and something that keeps running/looping so the
CPU stays alive, so requests get a response instead of "CPU not started"/"CPU not active" errors. Any homebrew or
game works; PSP homebrew isn't checked into this repo, so if you don't already have something installed under
memstick/PSP/GAME/, ask the user for a .iso/.cso/.elf/EBOOT.PBP to boot, or to install one via the in-app
Homebrew Store. Watch the log output (--log=somefile.log) for the line Listening on port N, then point
Tools/wsdbg/ at that port (cargo run -- N <event> [key=value...] for one-shot, or cargo run -- N for a REPL).
Most mutating events (hle.func.*, hle.data.*, memory writes while paused, etc.) require the CPU to be stopped
first - send cpu.stepping and cpu.resume to pause/unpause.

Alternatively use the headless build, Windows/{arch}/Debug/PPSSPPHeadless.exe or build/PPSSPPHeadless on CMake-based
platforms. Where arch is x64 or ARM64.

Driving a headless debugger session (gotchas) Copy Section

A working invocation, and the traps around it:

./Windows/x64/Debug/PPSSPPHeadless.exe --cpu=interpreter --debugger=34567 --timeout-wall=100000 --graphics=software --log \
    --root pspautotests/tests/../ pspautotests/tests/cpu/cpu_alu/cpu_alu.prx > hl.log 2>&1 &
# wait for "Listening on port" in hl.log, then:
./Tools/wsdbg/target/release/wsdbg.exe 34567 --sync --sync-timeout 15 < script.txt

• The timeouts apply to the whole session, not per test. --timeout-wall=N is real seconds and
  --timeout-emulated=N is emulated ones; both default to infinity, both can be set at once, and whichever
  is reached first ends the run (TIMEOUT or TIMEOUT (emulated)). With --state=, emulated time counts
  from when the state has loaded: until then the game boots for however long the load takes on the host, so
  counting from boot made runs end on different frames. --timeout is the old name for
  --timeout-wall. As soon as you pass one it applies to your whole interactive debugging session too, so
  pass something huge (--timeout-wall=100000) or the process exits out from under you mid-session. The
  wall-clock check is skipped while IsDebuggerPresent(); the emulated one doesn't need that escape hatch,
  since sitting at a native breakpoint burns no emulated time.

• Which one you want depends on the question. Wall-clock is what stops a hang from hanging the machine.
  Emulated is what you want for "has the game had long enough to get somewhere" - a heavy scene runs many
  times slower than real time and a near-idle one much faster, so the same wall-clock budget means very
  different amounts of game time. Booting a firmware VSH to its XMB is a good example: 10 emulated seconds
  is about 25 real ones on 6.61 and about 7 on 2.00.

• Prefer --debugger=0 and scrape Listening on port N from that run's own log over hardcoding a port. Also
  taskkill //F //IM PPSSPPHeadless.exe between runs for hygiene (Git Bash here has no pkill) - leftover
  instances are easy to accumulate when a script leaves the CPU stopped at a breakpoint.

• On Linux, kill leftovers with pkill -x PPSSPPHeadless, never pkill -f PPSSPPHeadless. -f matches full
  command lines, and the shell running your pkill has "PPSSPPHeadless" in its own command line, so it kills
  itself (exit 144) and the emulator instances you meant to clear survive into the next run.

• Attaching gdb to a running instance fails under WSL/Ubuntu (ptrace_scope: "Could not attach to process"),
  so a hang has to be caught by starting the run under gdb. Interrupting a batch-mode gdb from another shell with
  pkill -INT never got as far as the backtrace in the 2026-09-22 attempts. Before reaching for gdb, first rule out
  the cheap explanations below (backend, flags) by diffing a good and a bad command line.

  Some history, because it silently produced a round of bogus results before it was fixed: Common/Net/HTTPServer.cpp
  used to set SO_REUSEADDR, which on Winsock means "allow binding a port someone else is already listening on"
  (unlike POSIX, where it only covers TIME_WAIT). Two instances would both bind the same explicit port and both
  log Entering web server loop. Listening on port 34567, with the winner of any given connection undefined - so a
  client aimed at a fixed port could end up driving a leftover process running a different binary, CPU backend, or
  game. It's SO_EXCLUSIVEADDRUSE on Windows now, so the second bind fails honestly, and a non-zero --debugger=PORT
  that can't be honored is fatal in headless (exit 1) instead of falling back to a random port. If you still suspect
  you're talking to the wrong process, the version response carries pid and path - check them.

• The headless build defaults to JIT (Headless.cpp, CPUCore cpuCore = CPUCore::JIT), despite
  g_Config.iCpuCore being force-set to INTERPRETER just above - ApplyToConfig() has the final say. Pass
  --cpu=interpreter for the interpreter. (-r is --root, which eats the next argument as the root path.)

• When a test finishes, headless exits and the WebSocket connection closes (CloseFrame { code: Away }). So "the
  connection just closed" after a cpu.resume normally means the breakpoint you were counting on never tripped
  and the game ran to completion - not a transport problem.

• Some events deliberately never respond while the CPU is stepping, so --sync will burn its full timeout on them:
  gpu.stats.get and gpu.stats.feed (documented - they answer after the next flip), gpu.record.dump, and
  input.buttons.press (waits for N frames). Send them with wsdbg's :nowait, and let the next line
  (a cpu.runUntilTime) run the CPU:
  :nowait input.buttons.press button=circle duration=4. duration counts vblanks, not seconds.

• Don't send a bare cpu.resume in a --sync script. --sync waits for the CPU to stop again, which
  a free run never does, so it burns the whole --sync-timeout while headless runs unthrottled, which can
  be hundreds of emulated seconds. Use cpu.runUntilTime.

• Log broadcasts drown scripted output. Pass --quiet to wsdbg, which turns them off.

• Nested parameters work in wsdbg's key=value shorthand: values are parsed as JSON, and single quotes keep
  the inner double quotes, e.g. input.buttons.send buttons='{"cross":true}'. Prefer that over a raw JSON line,
  which gets no ticket (see below).

• Keep wsdbg scripts in files and pipe them in, rather than building JSON inline in a shell command - inline
  {"event":...} in a bash heredoc trips Claude Code's command analyzer ("brace with quote character") and forces a
  manual approval prompt for every single invocation.

• --sync can only match a response to a request that carries a ticket, and wsdbg only assigns tickets to its
  key=value shorthand. A raw JSON line without a ticket isn't waited for at all, so use the shorthand (nested
  values included, see above). Hex works there: memory.disasm address=0x08804000.

• To see the screen from a script, use wsdbg's :screenshot <file.png> while the CPU is stopped, e.g. after a
  cpu.runUntilTime. With headless, run --graphics=software for it: headless Vulkan has no output image to read
  back and asserts. Give a native path on Windows (C:/..., not /c/...).

• Headless reports SYSPROP_HAS_DEBUGGER as false (only Windows/main.cpp implements it), so anything gated on
  it does nothing there - LoadSymbolsIfSupported() in Core/System.cpp, for instance, doesn't load .ppmap/.sym
  at all under headless. Gate new debugger-adjacent features on their own config flag, not on that property.

• Headless defaults its memstick to memstick next to the executable (Headless.cpp). Pass --memstick=DIR to
  point it at a real one instead - e.g. the same directory the app build uses - rather than copying a game in.

• Kill leftover instances (taskkill //F //IM PPSSPPHeadless.exe) before building - a running one makes the link
  step fail with LNK1168: cannot open ... for writing, which looks like a build problem and isn't.

• Don't wrap a script that starts headless in timeout - when it fires it takes the emulator down with it, and if
  the emulator was stopped at the crash you were investigating, that state is gone. Let the launcher exit and leave
  the process running; wsdbg can reconnect to the same port as many times as you like.

• Response field names are not uniform: memory.read_u32 answers with value, while cpu.getReg answers with
  uintValue. A parser defaulting a missing key to 0 will quietly report zeroes - read the handler's comment in
  Core/Debugger/WebSocket/*Subscriber.cpp rather than guessing.

• broadcast.config.set accepts all five categories now (logger, input, game, stepping, breakpoint);
  it used to reject game and stepping until each had happened to fire once.

• A script has to keep the connection open long enough for what it asked for to happen. cpu.runUntilTime
  followed immediately by :quit disconnects before the run even starts, and it looks exactly like the feature
  not working. End with a :wait cpu.stepping <seconds>.

• Exception and crash messages do not reach the log in headless. It registers its own debug-output listener
  (SendDebugOutput in headless/Headless.cpp) that fwrites to stdout, which is block-buffered when you
  redirect it to a file - so the output sits in the CRT buffer while the process runs, and taskkill //F throws
  it away rather than flushing. To actually read a crash trace, give that run a short --timeout-wall and wait for
  the process to exit on its own.

• 0xFFFFFFFF is not an invalid instruction - it decodes to vflush, a real Allegrex VFPU op, so writing it
  over code to test illegal-instruction handling just runs it. Check what an encoding actually is with
  memory.disasm before assuming it's garbage; the interpreter raises ExecExceptionType::ILLEGAL only when
  MIPSGetInstruction has no interpreter for it (tge/tlt/teq and friends).

• To line input injection up with a wall-clock repro, use cpu.status's us field (emulated microseconds), not
  ticks. The PSP's clock frequency is changeable and games do change it - CrossCraft Classic runs at 333MHz, so
  ticks / 222000000 is off by a factor of 1.5. clockHz is reported alongside.

• --graphics=software cannot see "the screen stops updating" bugs. When HLE writes pixels straight into a
  display buffer - video decoding, sceJpeg, sceMpegAvcCsc - the hardware backends only find out because the HLE
  calls gpu->PerformWriteFormattedFromMemory(). The software renderer reads that memory directly and so renders
  the frame whether or not anything was notified. A missing notification therefore looks perfect under
  --graphics=software and shows up as a frozen screen on every real backend, while the decode logs keep scrolling
  past as if all were well. Reproduce display bugs on a hardware backend (see "Choosing a GPU backend" below;
  directx9 is not a valid value) and compare --screenshot-save= output, not the log.

• wsdbg --launch only works with the headless build. The app build is a GUI-subsystem exe with no stdout, so
  the Listening on port N line never reaches the launcher and it gives up. Start it yourself with an explicit
  --debugger=PORT and point wsdbg at that port. Note also that --debugger-run is CmdLineMode::Headless; the
  app takes plain --debugger=PORT.

• --launch needs --log to find the port. Without it, headless prints only emulated printfs, so the
  Listening on port N NOTICE never appears and --launch fails with "PPSSPP never reported a debugger port".
  --log --loglevel=3 keeps the port line while cutting the debug flood - full --log at the default level costs
  a lot of emulation speed (a 25-second run of a game playing video wrote 450k lines and ran several times slower
  than real time, which on its own looks like the stall you're hunting).

Measuring a commercial game with headless Copy Chapter

Headless will happily run a game and print nothing, or run a different configuration than the one you asked
for, and both look like a clean pass if you are counting log lines. Four traps, each of which silently
produced a round of bogus results here:

• --log is required for any log output at all, and the log goes to stderr. Without it you get only
  headless's own lines (Loaded State, TIMEOUT); -d/-v set the level but don't turn the printf logger
  on. So folding stderr in isn't optional if you're grepping, which is what makes the third trap bite.
• Headless's memory stick is not the app's. It defaults to <exe dir>/memstick (headless/Headless.cpp),
  so Windows//<config>/memstick, while the app derives its own from installed.txt or Documents
  (InitMemstickDirectory in Windows/main.cpp, which carries a TODO about sharing the derivation). Headless
  creates that directory, empty PSP/NAND/flash0 and all, so firmware installed through the app is invisible
  and every LLE module quietly falls back to HLE - at which point you are measuring the HLE you were trying to
  compare against. Pass --memstick= explicitly; it resolves relative to the CWD, not the exe.
• Check the exit code. An unrecognised parameter prints Error: ... to stderr and exits 1, which is
  correct and easy to throw away: fold stderr into stdout (which the first trap forces), count grep hits, and a
  run that never started reports the same all-zero line as a clean one.
• Zero is not a pass. Measuring by log-grepping needs a positive precondition asserted separately ("did
  this run reach the code at all"), or "0 errors" also means "0 anything" - which is equally what a failed
  boot, a savestate that never reaches the cutscene, and a silent HLE fallback produce.

The last three compound: the fix is to treat the run's exit code and a positive "we got here" counter as
preconditions, and only then believe the error counts.

Rather than silently falling back to HLE, headless refuses the run: an explicit
--disable-hle= whose firmware module isn't there names the module, prints the flash0:/kd and memory stick
it looked in (usually enough to spot that it's the one beside the exe), and exits 1. Only an explicit
--disable-hle binds - sceMpeg and sceMp4 are LLE by default and still fall back quietly, or every run on a
machine with no firmware would fail. So when a measurement depends on the real module, pass the flag
explicitly even though it's on by default, and the run will tell you if it didn't get it.

--force-hle= is the other direction, and the one to reach for when deciding whether something is
our fault: it puts our HLE back for libraries that now run the real module by default, so the same
repro can be run both ways and the logs diffed. That is how the leftover warnings in Tekken 6 were
sorted - three appeared identically with --force-hle=16, which made them the game's own, and the
fourth only under the real module, which made it ours. Neither --nand= pointing somewhere empty
nor --appendconfig does this job: the firmware gets found anyway and the setting is per-game.

Choosing a GPU backend Copy Section

• --graphics=software (the default) needs no GPU at all, and matches the GPU pspautotests' reference
  screenshots (taken on a PSP) best. It's slow for games, though: it runs display lists synchronously inside
  sceGeListEnQueue, which then dominates any profile of the emulator thread.
• --graphics=vulkan renders offscreen, into images of its own with no window or swapchain, so it needs no
  display. On macOS it goes through MoltenVK.
• --graphics=opengl renders offscreen on macOS (a CGL context with a framebuffer object of its own), and
  through a hidden SDL window elsewhere.
• --graphics=d3d11 (Windows) renders through a hidden window.

For game runs, prefer a hardware backend: 30 emulated seconds of God of War take 3-4 seconds instead of a minute.
The pspautotests pass on Vulkan and OpenGL except for 17 GPU tests, whose references are hardware screenshots
that the hardware backends don't match exactly.

To smoke-test a CPU or GPU change on real games, run the old and the new binary on the same games with
--timeout-emulated and --screenshot-save=, and compare the screenshots. Most games are deterministic from
run to run, so a different screenshot means different behaviour. God of War: Chains of Olympus isn't: its menu
animation follows wall-clock time, so even the same binary lands on different frames.

To check that a game keeps running after --state= loads, pass --frame-stats: at the end of the run it prints
the flips in each emulated second since the load. A stuck or crashed game shows as zeros or a short list, and a
steady game as a flat 30 or 60. The state's load result is printed too, and a failed load exits 1.

To get past menus, --press=SECONDS:MASK[:DURATION],... holds buttons at emulated times (MASK is a sceCtrl
mask, 0x8 START and 0x4000 CROSS, held 0.15 seconds by default), and --screenshot-at=SECONDS:FILE,... saves
screenshots along the way.

For audio, --dump-audio=FILE.wav records the mixed output (before the game volume setting) for the whole run.
An audio glitch you can hear usually shows in the waveform: a click is a jump between neighbouring samples, and
a repeated or dropped mixer block is two identical 64-sample runs in a row.

Pass --graphics explicitly even when you want the default, so a copied command line doesn't depend on it. If a
run goes silent with no CPU use, a host thread is blocked, and neither --timeout-wall nor --timeout-emulated
will end it, as both are only checked when the emulation loop comes around.

Measuring speed Copy Section

Tools/headless_bench.py compares the speed of headless binaries on savestates or frame dumps. It alternates
the binaries from round to round and reports medians of four numbers per binary:

• Wall time is what a player sees, but it swings by several percent between identical runs (heat, the
  scheduler moving threads between performance and efficiency cores).
• CPU time (all threads) says how much work was done. A change that keeps it but cuts wall time spreads
  the work better, and one that cuts it while wall time stays has left the threads waiting.
• Instructions retired vary by well under 0.1% between identical runs, so they show changes too small for
  wall time.
• Cycles also count stalls (a division, a missed cache line) that instructions don't.

The last two come from /usr/bin/time -l on macOS and perf stat on Linux. The tool checks for mains power
first: on battery (or in macOS low power mode) the clock speed varies and the numbers aren't comparable. Stop
anything else that uses the CPU, including a forgotten usbhostfs_pc, which can spin a core indefinitely. A run
that exits with an error, misses TIMEOUT (emulated) or doesn't load its savestate stops the tool rather than
passing as a fast run.

To measure the CPU emulation alone, use --graphics=null (headless only, GPU/Null/GPU_Null.cpp). It runs
display lists, bounding boxes, matrix loads and block transfers, moves the vertex and index pointers past
each draw, and charges the same GE time per draw, but draws nothing and creates no draw context. Games flip
the same frames as with Vulkan, in roughly half the host instructions. Nothing is rendered, so screenshots
and anything that reads a framebuffer back through the GPU (rather than from PSP memory) get nothing.

Headless decodes vertices with the JIT like the app, where the host can (--vertex-jit=false for the C++
decoder, which the tests don't need either).

Profiling the CPU cores Copy Section

--jit-profile=FILE (app and headless) samples the emulator thread's host PC every 50 µs and, when the JIT
goes away or clears its cache, appends a report to FILE:

• the share of samples in JIT blocks, in the fixed routines they call (like the dot product routines), in
  the dispatcher, and outside JIT code by host function (with symbols where dladdr finds them);
• the 30 hottest blocks, each with its MIPS code, its IR, and its host code with the share of samples per
  host instruction, the IR instruction each comes from, and the samples in routines charged to the call;
• the hot fixed-code routines, per instruction.

It costs nothing when off. The native JITs (macOS, Linux and Android by signal, Windows by
SuspendThread; RISC-V and LoongArch on Linux only) sample the host PC; the IR interpreter instead times every block, which used to be the
IR_PROFILING define. Short runs from a savestate include compiling everything after the load, which
shows as emitter and IR pass functions; profile 20 emulated seconds or more to see the game itself.
To compare two builds by where the time goes, profile one game at a time: several at once wait on each
other's GPU work, which moves the shares.

Debugging and breakpoint considerations Copy Chapter

It might be worth trying the interpreter - all types of breakpoints are the most reliable with this CPU backend.
The JITs are much, much faster and in theory also support breakpoints, and we're trying to make the JITs
as reliable, but are maybe not quite there.

Concretely, as measured against the headless build (2026-08-16), per CPU backend:

Native debuggers and the memory fault handler Copy Chapter

With fast memory on, a bad guest access from JIT code is a real host SIGSEGV/SIGBUS (an access violation on
Windows), which Memory::HandleFault (Core/MemFault.cpp) catches and turns into a clean emulator-side
exception. A native debugger sees the fault first and stops there, so a run that would have reported
Read Word: SIGSEGV at ... looks like a crash instead. Continuing hands the fault to the handler, like a
first-chance exception in Visual Studio. To keep the debugger out of the way when the faults are expected:

• lldb (macOS/iOS) needs both of these, verified 2026-09-28 against pspautotests/tests/cpu/crash. The
  first skips the stop on the Mach-level EXC_BAD_ACCESS, the second the stop on the signal it turns into:

  text Copy

  settings set platform.plugin.darwin.ignored-exceptions EXC_BAD_ACCESS
  process launch --stop-at-entry
  process handle SIGSEGV SIGBUS -s false -n false -p true
  continue

  (process handle needs a live process, hence the --stop-at-entry.) The catch is that a genuine host crash
  then kills the process without stopping in the debugger.

• gdb (Linux/Android): handle SIGSEGV nostop noprint pass.

The pspautotests/tests/cpu/crash/crash_*.prx binaries each make one bad access (read, write, float, bad jump),
which makes them the quickest check that the handler works on a platform: run one with --cpu=jit in headless. They
should print the guest exception and exit 0, not die with signal 11.

Debugging a game that works on hardware but not in PPSSPP Copy Chapter

First, turn on bAutoSaveLoadSymbols (--auto-save-load-symbols in headless): when homebrew ships its
unstripped ELF next to the EBOOT (app.elf alongside app.prx, common for Zig/Rust/SDK homebrew), PPSSPP loads
the function and data names out of it, so the disassembly reads world.init_empty instead of z_un_088c00f0.
prxgen strips the symbol table on the way to the PRX, which is why the loaded module has none of its own.

The same flag also loads DWARF line info from that ELF (Core/Debugger/LineInfo.h), so addresses turn into
mesh.zig:163 in backtraces, crash traces, breakpoint hits and log lines, both call stack views, and the
disassembly status bar. Availability is narrow and worth knowing before relying on it: PRX conversion strips
every .debug section, verified across all 437 pspautotests .prx and CrossCraft's own app.prx, and of 24
installed homebrew EBOOTs none carry debug info - CrossCraft only does because it ships app.elf separately.
So it's there for homebrew you're developing (or a plain .elf you built), never for a commercial game. DWARF 2
through 4 are decoded (psp-gcc emits 2, Zig 4); v5 re-encoded the file table and its units are skipped with a
warning rather than mis-parsed.

That same file is also a ground-truth oracle for anything the loader computes. It still has the symbol table (so
an address can be turned into a
function name) and the full .rel.* sections with symbol indices, which the PRX format throws away. That makes it
possible to check the emulator's work exhaustively offline - for the HI16/LO16 relocation bug, "does the address
this pairing produces land inside the section its symbol belongs to" turned a guess into a measurement over 8589
relocations, and immediately showed that the first fix attempt scored worse than the code it replaced.

Reach for that before trying to reason a fix out of a disassembly. A few dozen lines of Python over the ELF beats
re-running the game.

Finding a game function to replace by hash Copy Chapter

The tell is a game that's right on the software renderer and stale on the hardware backends, usually a video
that sticks on its first frame while the audio plays on. The game is writing pixels into VRAM with the CPU, and
the hardware backends only see that when it goes through something we hook. Games ship their own memcpy,
memset and so on, and we recognise known ones by a hash of their code: the hardcodedHashes table in
Core/MIPS/MIPSAnalyst.cpp names them, and Core/HLE/ReplaceTables.cpp swaps in a replacement
(Replace_memcpy hands VRAM copies to gpu->PerformMemoryCopy). SSX On Tour's videos were fixed this way.

Finding the function:

1. Get to the right moment. Confirm the thing is actually happening before breaking on it - SSX's
   videos only start 11.5s in, and a screenshot from earlier just shows the paper background. memory.read of
   the decode buffer at a few cpu.runUntilTime points tells you when it starts changing.
2. Break on the write, under the interpreter (--cpu=interpreter), since JIT memory breakpoints only work for constant
   addresses: memory.breakpoint.add address=<a pixel mid-framebuffer> size=4 write=true enabled=true, then
   cpu.resume. Pick a pixel in the middle of the frame, not the first one, which clears also hit.
3. hle.backtrace gives the function's entry address. Addresses come back
   as decimal in JSON; convert carefully (145311076 is 08a94564, not 08ab1564).
4. memory.disasm the whole function and check that it really is what you're going to call it: argument
   order (a0 dest, a1 src, a2 size for memcpy), and no side effects the replacement wouldn't have. A
   replacement that doesn't match the original is a much worse bug than the one it fixes.

Steps 2 and 3 as one script (the SSX run, so 12s in and a pixel at 240,136 of each 8888 stride-512
framebuffer). Parameters take hex as well as decimal; replies are always decimal:

cpu.runUntilTime us=12000000
memory.breakpoint.add address=0x040443c0 size=4 write=true enabled=true
memory.breakpoint.add address=0x040cc3c0 size=4 write=true enabled=true
cpu.resume
hle.backtrace
:quit

Tools/wsdbg/target/release/wsdbg.exe --sync --compact --quiet --launch \
    Windows/x64/Release/PPSSPPHeadless.exe GAME.iso --memstick=memstick --cpu=interpreter --graphics=vulkan \
    --timeout-wall=240 < script.txt 2>/dev/null | grep -v '^<- log'

The first hle.backtrace frame is the writer: entry is the function's start, code the store that hit.
Follow up with memory.disasm address=<entry> count=64 and hle.func.hash address=<entry> in the same
session. Once a replacement is in place, the same script shows it working: the hit's source reads
GPUMemcpy/..., its pc is the function's entry, and the backtrace starts at the caller.

Getting the hash: hle.func.hash address=<anywhere in the function> returns what the table entry needs:

<- hle.func.hash {"address":145310976,"hash":"3966eef670a93781","known":null,"size":188}

known names the entry that already matches, if any (it read memcpy once SSX's was added). The hash is the
one HashFunctions() in MIPSAnalyst.cpp takes when the code is scanned (CityHash64 over the
instructions with immediates masked out), so it doesn't depend on where the function was loaded.

Add the entry to hardcodedHashes in hash order, with a comment naming the game. Then check that it took
effect: with --log --loglevel=4 the loader prints Replaced memcpy at 08a94500 with hash 3966eef670a93781.
Check other regions of the game too. Since the hash doesn't depend on address, they usually match the same
entry (SSX's Korean release has the function at 08a94200).

Dnas Patches (`docs/dnas-patches.md`) Copy Section

Game patches installed on a PSP (DNAS)

Some early games shipped their updates and DLC as an "installer" package that the PSP's install
utility turns into a module only that PSP can load. Killzone: Liberation's Chapter 5 DLC is the known
case (issues #12343, #12344). PPSSPP installs the EU Killzone download itself when the game boots,
and can also load a patch that was installed on a real PSP, given that PSP's Fuse ID.

What the download is Copy Chapter

PSP/GAME/UCES00279/ (UCUS98646 for the US game) gets two files:

• EBOOT.PBP, 8.5 MB, CATEGORY=MG, BOOTABLE=0, title "Killzone: Liberation Installer". Its
  DATA.PSP is the encrypted package the install utility unpacks. The XMB refuses to start it.
• CHAPTER5.BIN, 68 MB, the chapter's data. The patched game module reads it as it is.

Installing it on a PSP Copy Chapter

The install is done by the game's own boot program (disc0:/PSP_GAME/SYSDIR/EBOOT.BIN), which
imports sceUtilityInstall*. It only installs when started with the argument -i, and then only if
ms0:/PSP/GAME/UCES00279/EBOOT.PBP is larger than 1 MB. The game passes -i itself, after the
online download in its menus (from kzl.killzone.com, long gone), so there's no way to trigger it
from inside the game today.

Starting the boot program with -i from PSPLink works. modexec doesn't (the LoadExec is refused),
but a tiny kernel-mode PRX calling the CFW's sctrlKernelLoadExecVSHDisc (SystemCtrlForKernel,
NID 0x577AF198) with key = "game" and the argument block "disc0:/PSP_GAME/SYSDIR/EBOOT.BIN\0-i\0"
brings up the system's install screen. Afterwards the folder holds KZL.PRX (8.6 MB, the patch),
and the 8.5 MB EBOOT.PBP has been replaced by a 10 KB one for the XMB.

The Fuse ID is the two words at 0xBC100090 and 0xBC100094, which only kernel code can read.
PSP tools show it as 12 hex digits, the 0x94 word first.

Installing it in PPSSPP Copy Chapter

InstallDrmBBPackage() in Core/PSPLoaders.cpp runs when one of the games it lists boots (those
g_kirk2Results covers) and PSP/GAME/<DISC_ID>/EBOOT.PBP is over 1 MB. It does what psheet does, with no console in the
picture: it writes the package's files next to it and replaces the installer with the package's own
EBOOT.PBP. It only does this if it can decrypt every .PRX in the package, so otherwise the download is
left alone.

The package is the PBP's DATA.PSP, read by pspReadDrmBBPackage() (layout from psheet's
bbox_access.c functions). Everything in it uses sceDrmBB MAC and cipher type 1, so known keys only:

• The whole PBP is MACed with a fixed key from psheet's data segment, in its last 16 bytes.
• DATA.PSP +0x00: a 0x50-byte header MACed (at +0x50) with the secure install ID, which means the
  ID can be recovered from the MAC (bbmac_getkey). The EU and US downloads use the same one. Its
  bytes 0x10-0x50 decrypt with the fixed key (header key: bytes 0-0x10, seed 0) to two 16-byte keys,
  then version 1, flags, 1, 0, the parameter table's offset and count, and the file table's offset.
• Parameters are (id, value) pairs, decrypted with the first key and the secure install ID. 0x01010100
  is the number of files.
• File entries are 16 bytes (u16 name offset, u16 name length, u32 data offset, u32 size, relative
  to the file table), and their names and data are decrypted with the second key and the secure install ID.
  The seed is always the 16-byte block number.

A .PRX comes out as a type 3 module whose first step (the 0x50 bytes at 0x80-0xB0, 0xC0-0xD0 and
0x12C-0x13C, with the KIRK header at 0xEC) is encrypted for KIRK command 2. The install sends the
first 0x400 bytes through sceMesgIns_driver_D062B635 (uofw's sceUtilsPrepareGetLoadModuleRLength),
which runs command 2 in place and re-encrypts that block for the console. The rest of the module is
the same before and after. Command 2's key is unknown, but its result is the same on every PSP, so
g_kirk2Results in PrxDecrypter.cpp stores it for each module we know, keyed by the 16 bytes at
0xEC. pspDecryptType3() uses it in place of the first step.

To get the result for another package, run --re-decrypt on it, which then writes the module as
the package has it to <out>.module. Then either decrypt a PSP
install of it with KIRK command 3 and that PSP's Fuse ID, or run sceMesgIns_driver_D062B635 on its
first 0x400 bytes on a PSP and decrypt that output with command 3 there.

Loading it Copy Chapter

The boot program calls sceKernelLoadModuleDNAS(path, secureId, 0, 0) with a 16-byte secure
install ID from its data (81A19A6F0FA9CFBAE378F73FFD504C7F for UCES00279), and treats any negative
result as "no patch", falling back to disc0:/PSP_GAME/USRDIR/KZL.PRX. Two layers:

1. A PGD (key index 1, DRM type 0), opened by amctrl with the secure install ID and the "flag 1"
   DNAS key. Its MAC and cipher use KIRK commands 5 and 8, which are AES under the per-console key
   with seed 1.
2. A type 3 PRX, decrypt mode 18, tag 0x89742B04. This is type 5 with the first step done by
   KIRK command 3 instead of 7: a small command 3 block whose header is at 0xEC and whose 0x50-byte
   body is the usual kirk header + SHA1 pieces, XORed with the tag's key and the secure install ID.
   The install produced that block with KIRK command 2, re-encrypting under the per-console key with
   seed 0. Command 2's own key (AES keyslot 3) isn't known, which is why the download can't be
   installed here.

The per-console keys come from the Fuse ID: the key mesh on psdevwiki's Kirk page, and the final
step from the KIRK ROM's aes_set_perconsole_key (uofw src/kirk/kirk-rom.c). The type 3 layout is
JPCSP's crypto/PRX.java. The tag's key and XOR are in its KeyVault.java, and uofw's mesgled.h
documents the decrypt mode.

In PPSSPP:

• kirk_individual_key(), kirk_CMD3/5/8 in ext/libkirk/kirk_engine.c.
• pspDecryptType3() and pspUnwrapDNASPGD() in Core/ELF/PrxDecrypter.cpp.
• sceKernelLoadModuleDNAS() in Core/HLE/sceKernelModule.cpp takes the Fuse ID from the FuseID
  setting ([SystemParam] in ppsspp.ini) or --fuse-id.