Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:GDB Remote Serial Protocol/LLDB extensions

From ReverseEngineering.wiki

The packets LLDB adds to or uses beside the GDB remote protocol (QStartNoAckMode, qHostInfo, qProcessInfo, qRegisterInfo, qMemoryRegionInfo, jThreadsInfo, jModulesInfo, vFile, platform packets) and the lldb-server / debugserver details useful for writing a stub.

LLDB speaks the GDB remote protocol (Format:GDB Remote Serial Protocol) and adds queries so it can run without XML or prior knowledge of the target. Source: lldb/docs/resources/lldbgdbremote.md in llvm/llvm-project (Apache-2.0 with LLVM exception), which also gives an implementation priority for each packet.

Target discovery

  • qHostInfo returns key:value; pairs: cputype/cpusubtype (decimal Mach-O CPU type, e.g. 16777223 = x86_64), triple (hex-encoded string), ostype, vendor, endian (little, big, pdp), ptrsize, hostname, os_version, os_build, os_kernel, watchpoint_exceptions_received (before/after), vm-page-size, addressing_bits (and low_/high_mem_addressing_bits, needed for AArch64 pointer authentication). Dolphin answers cputype:<MACH_O_POWERPC>;cpusubtype:<750>;ostype:unknown;vendor:unknown;endian:big;ptrsize:4; mGBA also implements it.
  • qProcessInfo (pid, parent pid, uids, triple, endian...), qGDBServerVersion, qSupported, qThreadStopInfo<tid>, qWatchpointSupportInfo, qShlibInfoAddr, qSymbol.
  • qRegisterInfo<hex index>: the index starts at 0 and increases by 1; reply name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;[alt-name:..;generic:pc|sp|fp|ra|arg1..;]. offset is the position of the register in the g packet buffer. The stub ends the list with an error reply. generic: names the architecture-neutral role (pc, sp, fp, ra, flags, arg1...).
  • qMemoryRegionInfo:<addr> replies start:<hex>;size:<hex>;permissions:rwx;name:<hex-encoded path>;flags:mt;type:stack;dirty-pages:...;. For an unmapped address the reply gives the gap to the next mapping, without permissions. A stub that cannot tell should return rwx.

Efficiency and control

  • QStartNoAckMode (the stub replies + then OK, and acks stop), QEnableCompression, QListThreadsInStopReply, QThreadSuffixSupported, QSaveRegisterState/QRestoreRegisterState, QSetDisableASLR, QSetSTDIN/STDOUT/STDERR, QSetWorkingDir, QEnvironment/QEnvironmentHexEncoded, QLaunchArch, A (launch arguments), vAttachName, vAttachWait, vAttachOrWait (qVAttachOrWaitSupported).
  • JSON helpers: jThreadsInfo (all threads with registers and stack memory in one reply), jModulesInfo, jGetLoadedDynamicLibrariesInfos (Darwin dyld image list), jGetSharedCacheInfo, jThreadExtendedInfo, jLLDBTraceStart/Stop/GetState/GetBinaryData (Intel PT), jMultiBreakpoint, MultiMemRead.
  • x binary memory read (stub-side binary), vFile:open/close/pread/pwrite/size/exists/MD5/unlink/symlink/chmod for the remote filesystem, platform packets qPlatform_shell, qPlatform_mkdir, qLaunchGDBServer, qKillSpawnedProcess, qfProcessInfo/qsProcessInfo, and Wasm packets (qWasmCallStack, qWasmLocal, ...).
  • The doc has a section on LLDB extensions to the T stop reply (extra key:value pairs such as thread lists and exception data). Unverified: the individual key names (metype, mecount, medata, threads, thread-pcs, jstopinfo, memory) are recalled, read the "Stop reply packet extensions" section before relying on them.

For stub authors

LLDB expects hex-encoded strings in many values and big-endian hex for addresses and sizes in its own queries. The minimum that makes LLDB usable is qHostInfo (so it picks the right plug-in), qProcessInfo, qRegisterInfo, QStartNoAckMode and the ordinary g/m/c/s/Z set; emulators such as Dolphin and mGBA answer qHostInfo for that reason. Unverified: the exact error text LLDB expects at the end of the qRegisterInfo sequence (the doc says an error reply).

Evidence & references

lldb/docs/resources/lldbgdbremote.md, llvm/llvm-project; Dolphin's WriteHostInfo in Source/Core/Core/PowerPC/GDBStub.cpp.