mirror of
https://github.com/hrydgard/ppsspp.git
synced 2026-09-01 02:05:21 +02:00
Henrik RydgårdandClaude Opus 5
59eb8a9a81
cpu.status only reported raw CPU ticks, which a client can't turn into a time: the PSP's clock frequency is changeable and games do change it, so the ticks-per-second ratio isn't fixed over a run. CrossCraft Classic runs at 333MHz, so assuming the default 222MHz reads 9.1s where the truth is 6.3s - enough to put scripted input injection in the wrong place entirely. Adds "us" (emulated microseconds) and "clockHz" alongside "ticks". CoreTiming::GetGlobalTimeUs() can't be used directly for this: it rebases its own internal counters as a side effect, and cpu.status is deliberately served straight from the WebSocket thread rather than queued to the CPU thread (it's meant to be cheap and frequently pollable). So PeekGlobalTimeUs() computes the same value without the rebasing. AGENTS.md picks up the things that cost time while driving headless over the websocket API: --sync silently desynchronises on raw JSON lines because only wsdbg's key=value shorthand gets a ticket; headless reports HAS_DEBUGGER as false so anything gated on it silently does nothing there; the memstick is hardcoded next to the executable; a leftover headless process turns a build into an LNK1168 that looks like a compile error; wrapping the launcher in `timeout` kills the emulator along with it, losing the crash you stopped at; response field names aren't uniform (value vs uintValue); broadcast.config.set rejects two of the four keys the docs list. Also writes down the ELF-as-oracle technique that cracked the relocation bug - when homebrew ships app.elf next to app.prx, the pre-link ELF still has the symbols and the relocation symbol indices the PRX format discards, so the loader's output can be checked exhaustively offline instead of by re-running. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GZq8ZtJmFY7bkX5FVkr3P9
193 lines
12 KiB
Markdown
193 lines
12 KiB
Markdown
# 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
|
|
|
|
- `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
|
|
|
|
- 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
|
|
|
|
Requests you send:
|
|
```json
|
|
{ "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:
|
|
```json
|
|
{ "event": "cpu.status", "ticket": 1, ... }
|
|
```
|
|
Responses are not always immediate - some handlers respond asynchronously.
|
|
|
|
Errors look like this:
|
|
```json
|
|
{ "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`):
|
|
```json
|
|
{ "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
|
|
|
|
Sent without you asking, whenever the underlying state changes:
|
|
|
|
| Event | Sent when | Source |
|
|
|---|---|---|
|
|
| `log` | A new log line is emitted | `LogBroadcaster.cpp` |
|
|
| `game.start` | A game finishes booting | `GameBroadcaster.cpp` |
|
|
| `game.quit` | The game is closed/reset | `GameBroadcaster.cpp` |
|
|
| `game.pause` / `game.resume` | User opens/leaves the pause menu | `GameBroadcaster.cpp` |
|
|
| `cpu.stepping` | CPU enters a stepping/break state | `SteppingBroadcaster.cpp` |
|
|
| `cpu.resume` | CPU resumes from stepping | `SteppingBroadcaster.cpp` |
|
|
| `input.buttons` | Any emulated button changes state | `InputBroadcaster.cpp` |
|
|
| `input.analog` | An analog stick position changes | `InputBroadcaster.cpp` |
|
|
|
|
A client can opt out of specific broadcast categories with
|
|
`broadcast.config.set` (`{"disallowed": {"logger": true, "game": true, "stepping": true, "input": true}}`),
|
|
see `ClientConfigSubscriber.cpp`. `gpu.stats.feed` (see below) works the same
|
|
way for periodic GPU stats.
|
|
|
|
## Request/response event catalog
|
|
|
|
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.
|
|
|
|
| Category | Events | File |
|
|
|---|---|---|
|
|
| Game/version | `game.reset`, `game.status`, `version` | `GameSubscriber.cpp` |
|
|
| CPU core | `cpu.stepping`, `cpu.resume`, `cpu.status` (reports `ticks` plus `us`, emulated microseconds, and `clockHz` - use `us` to line up with wall-clock timings, since games change the clock frequency and the ticks-per-second ratio isn't fixed), `cpu.getAllRegs`, `cpu.getReg`, `cpu.setReg`, `cpu.evaluate` | `CPUCoreSubscriber.cpp` |
|
|
| Stepping | `cpu.stepInto`, `cpu.stepOver`, `cpu.stepOut`, `cpu.runUntil`, `cpu.nextHLE` | `SteppingSubscriber.cpp` |
|
|
| Breakpoints | `cpu.breakpoint.add/update/remove/list`, `memory.breakpoint.add/update/remove/list`, `cpu.regBreakpoint.add/update/remove/list` (break when a register is written to, by any instruction anywhere - currently GPRs only; interpreter-only, no effect under a JIT backend) | `BreakpointSubscriber.cpp` |
|
|
| Memory read/write | `memory.read_u8/u16/u32`, `memory.read`, `memory.readString`, `memory.write_u8/u16/u32`, `memory.write` | `MemorySubscriber.cpp` |
|
|
| Memory search | `memory.search` - scan a range for a `u8`/`u16`/`u32`/`float` value or a `bytes` pattern (with an optional wildcard mask), for narrowing down where an unknown value lives (Cheat Engine style) | `MemorySubscriber.cpp` |
|
|
| Memory info/annotations | `memory.mapping`, `memory.info.config/set/list/search` | `MemoryInfoSubscriber.cpp` |
|
|
| Disassembly | `memory.base`, `memory.disasm` (add `compact=true` for plain-text lines instead of full per-field objects), `memory.searchDisasm` (add `findAll=true` for every match instead of just the first - e.g. "every caller of this address"), `memory.assemble` | `DisasmSubscriber.cpp` |
|
|
| GE display list disassembly | `gpu.displaylist.disasm` - like `memory.disasm` but for GE command words (`CLEARMODE`, `PRIM`, etc.) instead of CPU instructions; also supports `compact=true` | `GPUDisasmSubscriber.cpp` |
|
|
| HLE | `hle.thread.list/wake/stop`, `hle.func.list/add/remove/removeRange/rename/scan`, `hle.module.list`, `hle.module.saveSymbols/loadSymbols` (save/load one module's symbols to/from its standard `PSP/SYSTEM/SYMBOLS/<moduleName>_<crc>.ppsym` file, shared across any game that loads the same module - see `SymbolMap::GetModuleSymbolsPath`), `hle.game.saveSymbols/loadSymbols` (the same for symbols that aren't inside any module - heap, stack, scratchpad, hardware registers - which describe one game's memory layout and so go to a per-game `PSP/SYSTEM/SYMBOLS/<gameID>_syms.ppsym` instead; see `SymbolMap::GetGameSymbolsPath`), `hle.backtrace` | `HLESubscriber.cpp` |
|
|
| Data symbols | `hle.data.list/add/remove/rename` - label discovered data (structs, tables, buffers) with a name/type, same idea as `hle.func.*` but for `ST_DATA` symbols | `HLESubscriber.cpp` |
|
|
| Kernel objects | `hle.object.list` (every live kernel object of every type at once, with an optional `type` filter - uid/type/name/one-line summary only); `hle.eventflag.list/info`, `hle.mutex.list/info`, `hle.semaphore.list/info`, `hle.msgpipe.list/info`, `hle.callback.list/info` (per-type full detail, including waiting-thread lists) - all read-only, never mutate kernel state | `HLEKernelObjectSubscriber.cpp` |
|
|
| GPU stats | `gpu.stats.get`, `gpu.stats.feed` | `GPUStatsSubscriber.cpp` |
|
|
| GPU recording | `gpu.record.dump` | `GPURecordSubscriber.cpp` |
|
|
| GPU buffers | `gpu.buffer.screenshot`, `gpu.buffer.renderColor/renderDepth/renderStencil`, `gpu.buffer.texture`, `gpu.buffer.clut` | `GPUBufferSubscriber.cpp` |
|
|
| Input injection | `input.buttons.send`, `input.buttons.press`, `input.analog.send` | `InputSubscriber.cpp` |
|
|
| Replay | `replay.begin/abort/flush/execute/status`, `replay.time.get/set` | `ReplaySubscriber.cpp` |
|
|
| Client config | `broadcast.config.get/set` | `ClientConfigSubscriber.cpp` |
|
|
| Log channels | `log.channels.list`, `log.channel.set` - query/change a log channel's level (string: `notice`/`error`/`warning`/`info`/`debug`/`verbose`) and/or enabled state; the `log` event itself (the passive message stream, unaffected by this) keeps its existing numeric `level`, see `LogBroadcaster.cpp` | `LogConfigSubscriber.cpp` |
|
|
|
|
## Enabling it
|
|
|
|
- **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
|
|
|
|
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
|
|
|
|
`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://<ip>:<port>/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
|
|
|
|
- `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.
|