From 074c8ac5230adb3204971fd3d806ffabbba17e25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Rydg=C3=A5rd?= Date: Sun, 26 Jul 2026 21:17:09 +0200 Subject: [PATCH] Add memory.search and hle.data.* to the WebSocket debugger Reverse-engineering workflows need to (1) find where an unknown value lives in memory and (2) label what's found, neither of which the debugger API could do before: - memory.search (MemorySubscriber.cpp): Cheat-Engine-style scan of a memory range for a u8/u16/u32/float value, or a byte pattern with an optional wildcard mask. - hle.data.list/add/remove/rename (HLESubscriber.cpp): manage ST_DATA symbols (structs, tables, buffers), mirroring the existing hle.func.* commands for functions. Needed a new SymbolMap::RemoveData, since only RemoveFunction existed - added following the same pattern. Verified live against a running PPSSPP instance (game.status, cpu.stepping, memory.search in u32/bytes/masked-bytes modes, and the full add/list/rename/remove data-symbol lifecycle) via Tools/wsdbg. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01XDNwPPuidmNxQGRJxBuRL6 --- Core/Debugger/SymbolMap.cpp | 32 ++++ Core/Debugger/SymbolMap.h | 1 + Core/Debugger/WebSocket/HLESubscriber.cpp | 187 +++++++++++++++++++ Core/Debugger/WebSocket/HLESubscriber.h | 4 + Core/Debugger/WebSocket/MemorySubscriber.cpp | 140 ++++++++++++++ Core/Debugger/WebSocket/MemorySubscriber.h | 1 + docs/WebSocketDebugger.md | 2 + 7 files changed, 367 insertions(+) diff --git a/Core/Debugger/SymbolMap.cpp b/Core/Debugger/SymbolMap.cpp index 9f4b115cd5..4c6948106c 100644 --- a/Core/Debugger/SymbolMap.cpp +++ b/Core/Debugger/SymbolMap.cpp @@ -1109,6 +1109,38 @@ DataType SymbolMap::GetDataType(u32 startAddress) { return it->second.type; } +bool SymbolMap::RemoveData(u32 startAddress, bool removeName) { + if (activeNeedUpdate_) + UpdateActiveSymbols(); + + std::lock_guard guard(lock_); + + auto it = activeData.find(startAddress); + if (it == activeData.end()) + return false; + + auto symbolKey = std::make_pair(it->second.module, it->second.start); + auto it2 = data.find(symbolKey); + if (it2 != data.end()) { + data.erase(it2); + } + activeData.erase(it); + + if (removeName) { + auto labelIt = activeLabels.find(startAddress); + if (labelIt != activeLabels.end()) { + symbolKey = std::make_pair(labelIt->second.module, labelIt->second.addr); + auto labelIt2 = labels.find(symbolKey); + if (labelIt2 != labels.end()) { + labels.erase(labelIt2); + } + activeLabels.erase(labelIt); + } + } + + return true; +} + void SymbolMap::GetLabels(std::vector &dest) { if (activeNeedUpdate_) UpdateActiveSymbols(); diff --git a/Core/Debugger/SymbolMap.h b/Core/Debugger/SymbolMap.h index 77662133e6..4451647686 100644 --- a/Core/Debugger/SymbolMap.h +++ b/Core/Debugger/SymbolMap.h @@ -115,6 +115,7 @@ public: u32 GetDataSize(u32 startAddress); u32 GetDataModuleAddress(u32 startAddress); DataType GetDataType(u32 startAddress); + bool RemoveData(u32 startAddress, bool removeName); static const u32 INVALID_ADDRESS = (u32)-1; diff --git a/Core/Debugger/WebSocket/HLESubscriber.cpp b/Core/Debugger/WebSocket/HLESubscriber.cpp index f50bf6b2a9..dec209244e 100644 --- a/Core/Debugger/WebSocket/HLESubscriber.cpp +++ b/Core/Debugger/WebSocket/HLESubscriber.cpp @@ -47,10 +47,39 @@ DebuggerSubscriber *WebSocketHLEInit(DebuggerEventHandlerMap &map) { map["hle.func.scan"] = &WebSocketHLEFuncScan; map["hle.module.list"] = &WebSocketHLEModuleList; map["hle.backtrace"] = &WebSocketHLEBacktrace; + map["hle.data.list"] = &WebSocketHLEDataList; + map["hle.data.add"] = &WebSocketHLEDataAdd; + map["hle.data.remove"] = &WebSocketHLEDataRemove; + map["hle.data.rename"] = &WebSocketHLEDataRename; return nullptr; } +static const char *DataTypeToString(DataType type) { + switch (type) { + case DATATYPE_BYTE: return "byte"; + case DATATYPE_HALFWORD: return "halfword"; + case DATATYPE_WORD: return "word"; + case DATATYPE_ASCII: return "ascii"; + default: return "unknown"; + } +} + +static bool DataTypeFromString(const std::string &s, DataType *out) { + if (s == "byte") { + *out = DATATYPE_BYTE; + } else if (s == "halfword") { + *out = DATATYPE_HALFWORD; + } else if (s == "word") { + *out = DATATYPE_WORD; + } else if (s == "ascii") { + *out = DATATYPE_ASCII; + } else { + return false; + } + return true; +} + // List all current HLE threads (hle.thread.list) // // No parameters. @@ -620,3 +649,161 @@ void WebSocketHLEBacktrace(DebuggerRequest &req) { } json.pop(); } + +// List all current known data symbols (hle.data.list) +// +// No parameters. +// +// Response (same event name): +// - data: array of objects, each with properties: +// - name: current name of the data symbol. +// - address: unsigned integer start address. +// - size: unsigned integer size in bytes. +// - type: string, one of 'byte', 'halfword', 'word', 'ascii', or 'unknown'. +void WebSocketHLEDataList(DebuggerRequest &req) { + if (!g_symbolMap) + return req.Fail("CPU not active"); + + auto entries = g_symbolMap->GetAllActiveSymbols(ST_DATA); + + JsonWriter &json = req.Respond(); + json.pushArray("data"); + for (auto &d : entries) { + json.pushDict(); + json.writeString("name", d.name); + json.writeUint("address", d.address); + json.writeUint("size", d.size); + json.writeString("type", DataTypeToString(g_symbolMap->GetDataType(d.address))); + json.pop(); + } + json.pop(); +} + +// Add a new data symbol (hle.data.add) +// +// Useful for labeling structures, tables, or buffers found while reverse engineering +// (e.g. after locating something with memory.search.) +// +// Parameters: +// - address: unsigned integer address for the start of the data. +// - size: unsigned integer size in bytes. +// - type: string, one of 'byte', 'halfword', 'word', or 'ascii'. +// - name: string to name the data, optional and defaults to an auto-generated name. +// +// Response (same event name): +// - address: the start address, repeated back. +// - size: the size, repeated back. +// - type: the type, repeated back. +// - name: name of the new data symbol. +void WebSocketHLEDataAdd(DebuggerRequest &req) { + if (!g_symbolMap) + return req.Fail("CPU not active"); + if (!Core_IsStepping()) + return req.Fail("CPU currently running (cpu.stepping first)"); + + u32 addr; + if (!req.ParamU32("address", &addr)) + return; + u32 size; + if (!req.ParamU32("size", &size)) + return; + if (size == 0) + return req.Fail("'size' must not be zero"); + + std::string typeStr; + if (!req.ParamString("type", &typeStr)) + return; + DataType type; + if (!DataTypeFromString(typeStr, &type)) + return req.Fail("Invalid 'type', must be byte, halfword, word, or ascii"); + + if (!Memory::IsValidRange(addr, size)) + return req.Fail("Address or size outside valid memory"); + + std::string name; + if (!req.ParamString("name", &name, DebuggerParamType::OPTIONAL)) + return; + if (name.empty()) + name = StringFromFormat("data_%08x", addr); + + g_symbolMap->AddData(addr, size, type); + g_symbolMap->AddLabel(name.c_str(), addr); + g_symbolMap->SortSymbols(); + + // Clear cache so the disassembly view picks up the new annotation. + g_disassemblyManager.clear(); + + JsonWriter &json = req.Respond(); + json.writeUint("address", addr); + json.writeUint("size", size); + json.writeString("type", typeStr); + json.writeString("name", name); +} + +// Remove a data symbol (hle.data.remove) +// +// Parameters: +// - address: unsigned integer address within the data symbol to remove. +// +// Response (same event name): +// - address: the start address of the removed data symbol. +// - size: the size in bytes of the removed data symbol. +void WebSocketHLEDataRemove(DebuggerRequest &req) { + if (!g_symbolMap) + return req.Fail("CPU not active"); + if (!Core_IsStepping()) + return req.Fail("CPU currently running (cpu.stepping first)"); + + u32 addr; + if (!req.ParamU32("address", &addr)) + return; + + u32 dataBegin = g_symbolMap->GetDataStart(addr); + if (dataBegin == -1) + return req.Fail("No data symbol found at 'address'"); + u32 dataSize = g_symbolMap->GetDataSize(dataBegin); + + g_symbolMap->RemoveData(dataBegin, true); + g_symbolMap->SortSymbols(); + g_disassemblyManager.clear(); + + JsonWriter &json = req.Respond(); + json.writeUint("address", dataBegin); + json.writeUint("size", dataSize); +} + +// Rename a data symbol (hle.data.rename) +// +// Parameters: +// - address: unsigned integer address within the data symbol to rename. +// - name: string, new name for the data symbol. +// +// Response (same event name): +// - address: the start address of the renamed data symbol. +// - size: the size in bytes of the renamed data symbol. +// - name: string, new name repeated back. +void WebSocketHLEDataRename(DebuggerRequest &req) { + if (!g_symbolMap) + return req.Fail("CPU not active"); + if (!Core_IsStepping()) + return req.Fail("CPU currently running (cpu.stepping first)"); + + u32 addr; + if (!req.ParamU32("address", &addr)) + return; + std::string name; + if (!req.ParamString("name", &name)) + return; + + u32 dataBegin = g_symbolMap->GetDataStart(addr); + if (dataBegin == -1) + return req.Fail("No data symbol found at 'address'"); + u32 dataSize = g_symbolMap->GetDataSize(dataBegin); + + g_symbolMap->SetLabelName(name.c_str(), dataBegin); + + JsonWriter &json = req.Respond(); + json.writeUint("address", dataBegin); + json.writeUint("size", dataSize); + json.writeString("name", name); +} diff --git a/Core/Debugger/WebSocket/HLESubscriber.h b/Core/Debugger/WebSocket/HLESubscriber.h index 9ee4bad800..d23479e965 100644 --- a/Core/Debugger/WebSocket/HLESubscriber.h +++ b/Core/Debugger/WebSocket/HLESubscriber.h @@ -32,3 +32,7 @@ void WebSocketHLEFuncRename(DebuggerRequest &req); void WebSocketHLEFuncScan(DebuggerRequest &req); void WebSocketHLEModuleList(DebuggerRequest &req); void WebSocketHLEBacktrace(DebuggerRequest &req); +void WebSocketHLEDataList(DebuggerRequest &req); +void WebSocketHLEDataAdd(DebuggerRequest &req); +void WebSocketHLEDataRemove(DebuggerRequest &req); +void WebSocketHLEDataRename(DebuggerRequest &req); diff --git a/Core/Debugger/WebSocket/MemorySubscriber.cpp b/Core/Debugger/WebSocket/MemorySubscriber.cpp index 14674bd37d..0ad7f9f8e4 100644 --- a/Core/Debugger/WebSocket/MemorySubscriber.cpp +++ b/Core/Debugger/WebSocket/MemorySubscriber.cpp @@ -40,6 +40,7 @@ DebuggerSubscriber *WebSocketMemoryInit(DebuggerEventHandlerMap &map) { map["memory.write_u16"] = &WebSocketMemoryWriteU16; map["memory.write_u32"] = &WebSocketMemoryWriteU32; map["memory.write"] = &WebSocketMemoryWrite; + map["memory.search"] = &WebSocketMemorySearch; return nullptr; } @@ -403,3 +404,142 @@ void WebSocketMemoryWrite(DebuggerRequest &req) { Reporting::NotifyDebugger(); req.Respond(); } + +// Search memory for a value or byte pattern (memory.search) +// +// Useful for reverse engineering - e.g. narrowing down where a known value (health, +// ammo, a position) lives, or finding a byte signature. +// +// Parameters: +// - address: unsigned integer address for the start of the range to search. +// - size: unsigned integer size in bytes of the range to search. +// - type: string, one of 'u8', 'u16', 'u32', 'float', or 'bytes'. +// - value: for 'u8'/'u16'/'u32', an unsigned integer to match exactly. +// For 'float', a JSON string (e.g. "1.5") - use a string so integers aren't confused +// with floats, same convention as cpu.setReg. +// - base64: for 'bytes', the byte pattern to match, base64 encoded. +// - maskBase64: optional for 'bytes', base64 encoded, same length as 'base64'. A 0x00 +// byte means "don't care" at that position, any other byte value means "must match +// exactly" at that position. Defaults to matching every byte of 'base64' exactly. +// - align: optional unsigned integer, only check offsets from 'address' that are a +// multiple of this many bytes. Defaults to the size of 'type' in bytes (or 1 for +// 'bytes'.) +// - maxResults: optional unsigned integer, stop after this many matches (default 1000, +// hard cap 100000.) +// +// Response (same event name): +// - matches: array of unsigned integer addresses where a match was found. +// - truncated: boolean, true if 'maxResults' was hit before the whole range was searched. +void WebSocketMemorySearch(DebuggerRequest &req) { + uint32_t addr; + if (!req.ParamU32("address", &addr)) + return; + uint32_t size; + if (!req.ParamU32("size", &size)) + return; + std::string type; + if (!req.ParamString("type", &type)) + return; + + auto memLock = LockMemoryAndCPU(addr, true); + if (!currentDebugMIPS->isAlive() || !Memory::IsActive()) + return req.Fail("CPU not started"); + if (!Memory::IsValidAddress(addr)) + return req.Fail("Invalid address"); + else if (!Memory::IsValidRange(addr, size)) + return req.Fail("Invalid size"); + + uint32_t align = 1; + uint32_t needleSize = 0; + uint32_t needleValue = 0; + std::vector needleBytes; + std::vector maskBytes; + + if (type == "u8" || type == "u16" || type == "u32") { + needleSize = type == "u8" ? 1 : type == "u16" ? 2 : 4; + align = needleSize; + if (!req.ParamU32("value", &needleValue, false)) + return; + } else if (type == "float") { + needleSize = 4; + align = 4; + // allowFloatBits: accepts a string like "1.5" and gives us its raw bit pattern. + if (!req.ParamU32("value", &needleValue, true)) + return; + } else if (type == "bytes") { + std::string encoded; + if (!req.ParamString("base64", &encoded)) + return; + needleBytes = Base64Decode(&encoded[0], encoded.size()); + if (needleBytes.empty()) + return req.Fail("'base64' must decode to at least one byte"); + needleSize = (uint32_t)needleBytes.size(); + align = 1; + + if (req.HasParam("maskBase64")) { + std::string maskEncoded; + if (!req.ParamString("maskBase64", &maskEncoded)) + return; + maskBytes = Base64Decode(&maskEncoded[0], maskEncoded.size()); + if (maskBytes.size() != needleBytes.size()) + return req.Fail("'maskBase64' must decode to the same length as 'base64'"); + } + } else { + return req.Fail("Invalid 'type', must be u8, u16, u32, float, or bytes"); + } + + if (needleSize > size) + return req.Fail("'size' is smaller than the pattern/value being searched for"); + + if (!req.ParamU32("align", &align, false, DebuggerParamType::OPTIONAL)) + return; + if (align == 0) + return req.Fail("'align' must not be zero"); + + uint32_t maxResults = 1000; + if (!req.ParamU32("maxResults", &maxResults, false, DebuggerParamType::OPTIONAL)) + return; + if (maxResults == 0) + maxResults = 1000; + else if (maxResults > 100000) + maxResults = 100000; + + const uint8_t *base = Memory::GetPointerUnchecked(addr); + std::vector matches; + bool truncated = false; + for (uint32_t offset = 0; offset + needleSize <= size; offset += align) { + bool match; + if (!needleBytes.empty()) { + match = true; + for (uint32_t i = 0; i < needleSize; ++i) { + uint8_t mask = maskBytes.empty() ? 0xFF : maskBytes[i]; + if ((base[offset + i] & mask) != (needleBytes[i] & mask)) { + match = false; + break; + } + } + } else { + uint32_t actual = base[offset]; + if (needleSize >= 2) + actual |= base[offset + 1] << 8; + if (needleSize >= 4) + actual |= (base[offset + 2] << 16) | (base[offset + 3] << 24); + match = actual == needleValue; + } + + if (match) { + if (matches.size() >= maxResults) { + truncated = true; + break; + } + matches.push_back(addr + offset); + } + } + + JsonWriter &json = req.Respond(); + json.pushArray("matches"); + for (uint32_t m : matches) + json.writeUint(m); + json.pop(); + json.writeBool("truncated", truncated); +} diff --git a/Core/Debugger/WebSocket/MemorySubscriber.h b/Core/Debugger/WebSocket/MemorySubscriber.h index 8dfb2ade7a..38656fdb08 100644 --- a/Core/Debugger/WebSocket/MemorySubscriber.h +++ b/Core/Debugger/WebSocket/MemorySubscriber.h @@ -30,3 +30,4 @@ void WebSocketMemoryWriteU8(DebuggerRequest &req); void WebSocketMemoryWriteU16(DebuggerRequest &req); void WebSocketMemoryWriteU32(DebuggerRequest &req); void WebSocketMemoryWrite(DebuggerRequest &req); +void WebSocketMemorySearch(DebuggerRequest &req); diff --git a/docs/WebSocketDebugger.md b/docs/WebSocketDebugger.md index a50dbf0d13..a0f895cd56 100644 --- a/docs/WebSocketDebugger.md +++ b/docs/WebSocketDebugger.md @@ -110,9 +110,11 @@ file - this is just an index. | 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` | `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`, `memory.searchDisasm`, `memory.assemble` | `DisasmSubscriber.cpp` | | HLE | `hle.thread.list/wake/stop`, `hle.func.list/add/remove/removeRange/rename/scan`, `hle.module.list`, `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` | | 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` |