forked from OSchip/llvm-project
1253 lines
58 KiB
Plaintext
1253 lines
58 KiB
Plaintext
LLDB has added new GDB server packets to better support multi-threaded and
|
|
remote debugging. Why? Normally you need to start the correct GDB and the
|
|
correct GDB server when debugging. If you have mismatch, then things go wrong
|
|
very quickly. LLDB makes extensive use of the GDB remote protocol and we
|
|
wanted to make sure that the experience was a bit more dynamic where we can
|
|
discover information about a remote target with having to know anything up
|
|
front. We also ran into performance issues with the existing GDB remote
|
|
protocol that can be overcome when using a reliable communications layer.
|
|
Some packets improve performance, others allow for remote process launching
|
|
(if you have an OS), and others allow us to dynamically figure out what
|
|
registers a thread might have. Again with GDB, both sides pre-agree on how the
|
|
registers will look (how many, their register number,name and offsets). We
|
|
prefer to be able to dynamically determine what kind of architecture, OS and
|
|
vendor we are debugging, as well as how things are laid out when it comes to
|
|
the thread register contexts. Below are the details on the new packets we have
|
|
added above and beyond the standard GDB remote protocol packets.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "QStartNoAckMode"
|
|
//
|
|
// BRIEF
|
|
// Try to enable no ACK mode to skip sending ACKs and NACKs.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High. Any GDB remote server that can implement this should if the
|
|
// connection is reliable. This improves packet throughput and increases
|
|
// the performance of the connection.
|
|
//----------------------------------------------------------------------
|
|
Having to send an ACK/NACK after every packet slows things down a bit, so we
|
|
have a way to disable ACK packets to minimize the traffic for reliable
|
|
communication interfaces (like sockets). Below GDB or LLDB will send this
|
|
packet to try and disable ACKs. All lines that start with "send packet: " are
|
|
from GDB/LLDB, and all lines that start with "read packet: " are from the GDB
|
|
remote server:
|
|
|
|
send packet: $QStartNoAckMode#b0
|
|
read packet: +
|
|
read packet: $OK#9a
|
|
send packet: +
|
|
|
|
|
|
|
|
//----------------------------------------------------------------------
|
|
// "A" - launch args packet
|
|
//
|
|
// BRIEF
|
|
// Launch a program using the supplied arguments
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed if the remote target wants to launch a target after
|
|
// making a connection to a GDB server that isn't already connected to
|
|
// an inferior process.
|
|
//----------------------------------------------------------------------
|
|
|
|
We have added support for the "set program arguments" packet where we can
|
|
startup a connection to a remote server and then later supply the path to the
|
|
executable and the arguments to use when executing:
|
|
|
|
GDB remote docs for this:
|
|
|
|
set program arguments(reserved) Aarglen,argnum,arg,...
|
|
|
|
Where A is followed by the length in bytes of the hex encoded argument,
|
|
followed by an argument integer, and followed by the ASCII characters
|
|
converted into hex bytes foreach arg
|
|
|
|
send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00
|
|
read packet: $OK#00
|
|
|
|
The above packet helps when you have remote debugging abilities where you
|
|
could launch a process on a remote host, this isn't needed for bare board
|
|
debugging.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "QEnvironment:NAME=VALUE"
|
|
//
|
|
// BRIEF
|
|
// Setup the environment up for a new child process that will soon be
|
|
// launched using the "A" packet.
|
|
//
|
|
// NB: key/value pairs are sent as-is so gdb-remote protocol meta characters
|
|
// (e.g. '#' or '$') are not acceptable. If any non-printable or
|
|
// metacharacters are present in the strings, QEnvironmentHexEncoded
|
|
// should be used instead if it is available. If you don't want to
|
|
// scan the environment strings before sending, prefer
|
|
// the QEnvironmentHexEncoded packet over QEnvironment, if it is
|
|
// available.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed if the remote target wants to launch a target after
|
|
// making a connection to a GDB server that isn't already connected to
|
|
// an inferior process.
|
|
//----------------------------------------------------------------------
|
|
|
|
Both GDB and LLDB support passing down environment variables. Is it ok to
|
|
respond with a "$#00" (unimplemented):
|
|
|
|
send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00
|
|
read packet: $OK#00
|
|
|
|
This packet can be sent one or more times _prior_ to sending a "A" packet.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)"
|
|
//
|
|
// BRIEF
|
|
// Setup the environment up for a new child process that will soon be
|
|
// launched using the "A" packet.
|
|
//
|
|
// The only difference between this packet and QEnvironment is that the
|
|
// environment key-value pair is ascii hex encoded for transmission.
|
|
// This allows values with gdb-remote metacharacters like '#' to be sent.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed if the remote target wants to launch a target after
|
|
// making a connection to a GDB server that isn't already connected to
|
|
// an inferior process.
|
|
//----------------------------------------------------------------------
|
|
|
|
Both GDB and LLDB support passing down environment variables. Is it ok to
|
|
respond with a "$#00" (unimplemented):
|
|
|
|
send packet: $QEnvironment:41434b5f434f4c4f525f46494c454e414d453d626f6c642379656c6c6f77#00
|
|
read packet: $OK#00
|
|
|
|
This packet can be sent one or more times _prior_ to sending a "A" packet.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "QSetSTDIN:<ascii-hex-path>"
|
|
// "QSetSTDOUT:<ascii-hex-path>"
|
|
// "QSetSTDERR:<ascii-hex-path>"
|
|
//
|
|
// BRIEF
|
|
// Setup where STDIN, STDOUT, and STDERR go prior to sending an "A"
|
|
// packet.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed if the remote target wants to launch a target after
|
|
// making a connection to a GDB server that isn't already connected to
|
|
// an inferior process.
|
|
//----------------------------------------------------------------------
|
|
|
|
When launching a program through the GDB remote protocol with the "A" packet,
|
|
you might also want to specify where stdin/out/err go:
|
|
|
|
QSetSTDIN:<ascii-hex-path>
|
|
QSetSTDOUT:<ascii-hex-path>
|
|
QSetSTDERR:<ascii-hex-path>
|
|
|
|
These packets must be sent _prior_ to sending a "A" packet.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "QSetWorkingDir:<ascii-hex-path>"
|
|
//
|
|
// BRIEF
|
|
// Set the working directory prior to sending an "A" packet.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed if the remote target wants to launch a target after
|
|
// making a connection to a GDB server that isn't already connected to
|
|
// an inferior process.
|
|
//----------------------------------------------------------------------
|
|
|
|
Or specify the working directory:
|
|
|
|
QSetWorkingDir:<ascii-hex-path>
|
|
|
|
This packet must be sent _prior_ to sending a "A" packet.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "QSetDisableASLR:<bool>"
|
|
//
|
|
// BRIEF
|
|
// Enable or disable ASLR on the next "A" packet.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed if the remote target wants to launch a target after
|
|
// making a connection to a GDB server that isn't already connected to
|
|
// an inferior process and if the target supports disabling ASLR
|
|
// (Address space layout randomization).
|
|
//----------------------------------------------------------------------
|
|
|
|
Or control if ASLR is enabled/disabled:
|
|
|
|
send packet: QSetDisableASLR:1
|
|
read packet: OK
|
|
|
|
send packet: QSetDisableASLR:0
|
|
read packet: OK
|
|
|
|
This packet must be sent _prior_ to sending a "A" packet.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qRegisterInfo<hex-reg-id>"
|
|
//
|
|
// BRIEF
|
|
// Discover register information from the remote GDB server.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High. Any target that can self describe its registers, should do so.
|
|
// This means if new registers are ever added to a remote target, they
|
|
// will get picked up automatically, and allows registers to change
|
|
// depending on the actual CPU type that is used.
|
|
//----------------------------------------------------------------------
|
|
|
|
With LLDB, for register information, remote GDB servers can add
|
|
support for the "qRegisterInfoN" packet where "N" is a zero based
|
|
base16 register number that must start at zero and increase by one
|
|
for each register that is supported. The response is done in typical
|
|
GDB remote fashion where a serious of "KEY:VALUE;" pairs are returned.
|
|
An example for the x86_64 registers is included below:
|
|
|
|
send packet: $qRegisterInfo0#00
|
|
read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00
|
|
send packet: $qRegisterInfo1#00
|
|
read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00
|
|
send packet: $qRegisterInfo2#00
|
|
read packet: $name:rcx;bitsize:64;offset:16;encoding:uint;format:hex;set:General Purpose Registers;gcc:2;dwarf:2;#00
|
|
send packet: $qRegisterInfo3#00
|
|
read packet: $name:rdx;bitsize:64;offset:24;encoding:uint;format:hex;set:General Purpose Registers;gcc:1;dwarf:1;#00
|
|
send packet: $qRegisterInfo4#00
|
|
read packet: $name:rdi;bitsize:64;offset:32;encoding:uint;format:hex;set:General Purpose Registers;gcc:5;dwarf:5;#00
|
|
send packet: $qRegisterInfo5#00
|
|
read packet: $name:rsi;bitsize:64;offset:40;encoding:uint;format:hex;set:General Purpose Registers;gcc:4;dwarf:4;#00
|
|
send packet: $qRegisterInfo6#00
|
|
read packet: $name:rbp;alt-name:fp;bitsize:64;offset:48;encoding:uint;format:hex;set:General Purpose Registers;gcc:6;dwarf:6;generic:fp;#00
|
|
send packet: $qRegisterInfo7#00
|
|
read packet: $name:rsp;alt-name:sp;bitsize:64;offset:56;encoding:uint;format:hex;set:General Purpose Registers;gcc:7;dwarf:7;generic:sp;#00
|
|
send packet: $qRegisterInfo8#00
|
|
read packet: $name:r8;bitsize:64;offset:64;encoding:uint;format:hex;set:General Purpose Registers;gcc:8;dwarf:8;#00
|
|
send packet: $qRegisterInfo9#00
|
|
read packet: $name:r9;bitsize:64;offset:72;encoding:uint;format:hex;set:General Purpose Registers;gcc:9;dwarf:9;#00
|
|
send packet: $qRegisterInfoa#00
|
|
read packet: $name:r10;bitsize:64;offset:80;encoding:uint;format:hex;set:General Purpose Registers;gcc:10;dwarf:10;#00
|
|
send packet: $qRegisterInfob#00
|
|
read packet: $name:r11;bitsize:64;offset:88;encoding:uint;format:hex;set:General Purpose Registers;gcc:11;dwarf:11;#00
|
|
send packet: $qRegisterInfoc#00
|
|
read packet: $name:r12;bitsize:64;offset:96;encoding:uint;format:hex;set:General Purpose Registers;gcc:12;dwarf:12;#00
|
|
send packet: $qRegisterInfod#00
|
|
read packet: $name:r13;bitsize:64;offset:104;encoding:uint;format:hex;set:General Purpose Registers;gcc:13;dwarf:13;#00
|
|
send packet: $qRegisterInfoe#00
|
|
read packet: $name:r14;bitsize:64;offset:112;encoding:uint;format:hex;set:General Purpose Registers;gcc:14;dwarf:14;#00
|
|
send packet: $qRegisterInfof#00
|
|
read packet: $name:r15;bitsize:64;offset:120;encoding:uint;format:hex;set:General Purpose Registers;gcc:15;dwarf:15;#00
|
|
send packet: $qRegisterInfo10#00
|
|
read packet: $name:rip;alt-name:pc;bitsize:64;offset:128;encoding:uint;format:hex;set:General Purpose Registers;gcc:16;dwarf:16;generic:pc;#00
|
|
send packet: $qRegisterInfo11#00
|
|
read packet: $name:rflags;alt-name:flags;bitsize:64;offset:136;encoding:uint;format:hex;set:General Purpose Registers;#00
|
|
send packet: $qRegisterInfo12#00
|
|
read packet: $name:cs;bitsize:64;offset:144;encoding:uint;format:hex;set:General Purpose Registers;#00
|
|
send packet: $qRegisterInfo13#00
|
|
read packet: $name:fs;bitsize:64;offset:152;encoding:uint;format:hex;set:General Purpose Registers;#00
|
|
send packet: $qRegisterInfo14#00
|
|
read packet: $name:gs;bitsize:64;offset:160;encoding:uint;format:hex;set:General Purpose Registers;#00
|
|
send packet: $qRegisterInfo15#00
|
|
read packet: $name:fctrl;bitsize:16;offset:176;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo16#00
|
|
read packet: $name:fstat;bitsize:16;offset:178;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo17#00
|
|
read packet: $name:ftag;bitsize:8;offset:180;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo18#00
|
|
read packet: $name:fop;bitsize:16;offset:182;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo19#00
|
|
read packet: $name:fioff;bitsize:32;offset:184;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo1a#00
|
|
read packet: $name:fiseg;bitsize:16;offset:188;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo1b#00
|
|
read packet: $name:fooff;bitsize:32;offset:192;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo1c#00
|
|
read packet: $name:foseg;bitsize:16;offset:196;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo1d#00
|
|
read packet: $name:mxcsr;bitsize:32;offset:200;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo1e#00
|
|
read packet: $name:mxcsrmask;bitsize:32;offset:204;encoding:uint;format:hex;set:Floating Point Registers;#00
|
|
send packet: $qRegisterInfo1f#00
|
|
read packet: $name:stmm0;bitsize:80;offset:208;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:33;dwarf:33;#00
|
|
send packet: $qRegisterInfo20#00
|
|
read packet: $name:stmm1;bitsize:80;offset:224;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:34;dwarf:34;#00
|
|
send packet: $qRegisterInfo21#00
|
|
read packet: $name:stmm2;bitsize:80;offset:240;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:35;dwarf:35;#00
|
|
send packet: $qRegisterInfo22#00
|
|
read packet: $name:stmm3;bitsize:80;offset:256;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:36;dwarf:36;#00
|
|
send packet: $qRegisterInfo23#00
|
|
read packet: $name:stmm4;bitsize:80;offset:272;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:37;dwarf:37;#00
|
|
send packet: $qRegisterInfo24#00
|
|
read packet: $name:stmm5;bitsize:80;offset:288;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:38;dwarf:38;#00
|
|
send packet: $qRegisterInfo25#00
|
|
read packet: $name:stmm6;bitsize:80;offset:304;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:39;dwarf:39;#00
|
|
send packet: $qRegisterInfo26#00
|
|
read packet: $name:stmm7;bitsize:80;offset:320;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:40;dwarf:40;#00
|
|
send packet: $qRegisterInfo27#00
|
|
read packet: $name:xmm0;bitsize:128;offset:336;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:17;dwarf:17;#00
|
|
send packet: $qRegisterInfo28#00
|
|
read packet: $name:xmm1;bitsize:128;offset:352;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:18;dwarf:18;#00
|
|
send packet: $qRegisterInfo29#00
|
|
read packet: $name:xmm2;bitsize:128;offset:368;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:19;dwarf:19;#00
|
|
send packet: $qRegisterInfo2a#00
|
|
read packet: $name:xmm3;bitsize:128;offset:384;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:20;dwarf:20;#00
|
|
send packet: $qRegisterInfo2b#00
|
|
read packet: $name:xmm4;bitsize:128;offset:400;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:21;dwarf:21;#00
|
|
send packet: $qRegisterInfo2c#00
|
|
read packet: $name:xmm5;bitsize:128;offset:416;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:22;dwarf:22;#00
|
|
send packet: $qRegisterInfo2d#00
|
|
read packet: $name:xmm6;bitsize:128;offset:432;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:23;dwarf:23;#00
|
|
send packet: $qRegisterInfo2e#00
|
|
read packet: $name:xmm7;bitsize:128;offset:448;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:24;dwarf:24;#00
|
|
send packet: $qRegisterInfo2f#00
|
|
read packet: $name:xmm8;bitsize:128;offset:464;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:25;dwarf:25;#00
|
|
send packet: $qRegisterInfo30#00
|
|
read packet: $name:xmm9;bitsize:128;offset:480;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:26;dwarf:26;#00
|
|
send packet: $qRegisterInfo31#00
|
|
read packet: $name:xmm10;bitsize:128;offset:496;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:27;dwarf:27;#00
|
|
send packet: $qRegisterInfo32#00
|
|
read packet: $name:xmm11;bitsize:128;offset:512;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:28;dwarf:28;#00
|
|
send packet: $qRegisterInfo33#00
|
|
read packet: $name:xmm12;bitsize:128;offset:528;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:29;dwarf:29;#00
|
|
send packet: $qRegisterInfo34#00
|
|
read packet: $name:xmm13;bitsize:128;offset:544;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:30;dwarf:30;#00
|
|
send packet: $qRegisterInfo35#00
|
|
read packet: $name:xmm14;bitsize:128;offset:560;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:31;dwarf:31;#00
|
|
send packet: $qRegisterInfo36#00
|
|
read packet: $name:xmm15;bitsize:128;offset:576;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:32;dwarf:32;#00
|
|
send packet: $qRegisterInfo37#00
|
|
read packet: $name:trapno;bitsize:32;offset:696;encoding:uint;format:hex;set:Exception State Registers;#00
|
|
send packet: $qRegisterInfo38#00
|
|
read packet: $name:err;bitsize:32;offset:700;encoding:uint;format:hex;set:Exception State Registers;#00
|
|
send packet: $qRegisterInfo39#00
|
|
read packet: $name:faultvaddr;bitsize:64;offset:704;encoding:uint;format:hex;set:Exception State Registers;#00
|
|
send packet: $qRegisterInfo3a#00
|
|
read packet: $E45#00
|
|
|
|
As we see above we keep making subsequent calls to the remote server to
|
|
discover all registers by increasing the number appended to qRegisterInfo and
|
|
we get a response back that is a series of "key=value;" strings.
|
|
|
|
The offset: fields should not leave a gap anywhere in the g/G packet -- the
|
|
register values should be appended one after another. For instance, if the
|
|
register context for a thread looks like
|
|
|
|
struct rctx {
|
|
uint32_t gpr1; // offset 0
|
|
uint32_t gpr2; // offset 4
|
|
uint32_t gpr3; // offset 8
|
|
uint64_t fp1; // offset 16
|
|
};
|
|
|
|
You may end up with a 4-byte gap between gpr3 and fp1 on architectures
|
|
that align values like this. The correct offset: value for fp1 is 12 -
|
|
in the g/G packet fp1 will immediately follow gpr3, even though the
|
|
in-memory thread structure has an empty 4 bytes for alignment between
|
|
these two registers.
|
|
|
|
The keys and values are detailed below:
|
|
|
|
Key Value
|
|
========== ================================================================
|
|
name The primary register name as a string ("rbp" for example)
|
|
|
|
alt-name An alternate name for a register as a string ("fp" for example for
|
|
the above "rbp")
|
|
|
|
bitsize Size in bits of a register (32, 64, etc). Base 10.
|
|
|
|
offset The offset within the "g" and "G" packet of the register data for
|
|
this register. This is the byte offset once the data has been
|
|
transformed into binary, not the character offset into the g/G
|
|
packet. Base 10.
|
|
|
|
encoding The encoding type of the register which must be one of:
|
|
|
|
uint (unsigned integer)
|
|
sint (signed integer)
|
|
ieee754 (IEEE 754 float)
|
|
vector (vector regsiter)
|
|
|
|
format The preferred format for display of this register. The value must
|
|
be one of:
|
|
|
|
binary
|
|
decimal
|
|
hex
|
|
float
|
|
vector-sint8
|
|
vector-uint8
|
|
vector-sint16
|
|
vector-uint16
|
|
vector-sint32
|
|
vector-uint32
|
|
vector-float32
|
|
vector-uint128
|
|
|
|
set The register set name as a string that this register belongs to.
|
|
|
|
gcc The GCC compiler registers number for this register (used for
|
|
EH frame and other compiler information that is encoded in the
|
|
executable files). The supplied number will be decoded like a
|
|
string passed to strtoul() with a base of zero, so the number
|
|
can be decimal, or hex if it is prefixed with "0x".
|
|
|
|
NOTE: If the compiler doesn't have a register number for this
|
|
register, this key/value pair should be omitted.
|
|
|
|
dwarf The DWARF register number for this register that is used for this
|
|
register in the debug information. The supplied number will be decoded
|
|
like a string passed to strtoul() with a base of zero, so the number
|
|
can be decimal, or hex if it is prefixed with "0x".
|
|
|
|
NOTE: If the compiler doesn't have a register number for this
|
|
register, this key/value pair should be omitted.
|
|
|
|
generic If the register is a generic register that most CPUs have, classify
|
|
it correctly so the debugger knows. Valid values are one of:
|
|
pc (a program counter register. for example "name=eip;" (i386),
|
|
"name=rip;" (x86_64), "name=r15;" (32 bit arm) would
|
|
include a "generic=pc;" key value pair)
|
|
sp (a stack pointer register. for example "name=esp;" (i386),
|
|
"name=rsp;" (x86_64), "name=r13;" (32 bit arm) would
|
|
include a "generic=sp;" key value pair)
|
|
fp (a frame pointer register. for example "name=ebp;" (i386),
|
|
"name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx
|
|
ABI) would include a "generic=fp;" key value pair)
|
|
ra (a return address register. for example "name=lr;" (32 bit ARM)
|
|
would include a "generic=ra;" key value pair)
|
|
fp (a CPU flags register. for example "name=eflags;" (i386),
|
|
"name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM)
|
|
would include a "generic=flags;" key value pair)
|
|
arg1 - arg8 (specified for registers that contain function
|
|
arguments when the argument fits into a register)
|
|
|
|
container-regs
|
|
The value for this key is a comma separated list of raw hex (optional
|
|
leading "0x") register numbers.
|
|
|
|
This specifies that this register is contained in other concrete
|
|
register values. For example "eax" is in the lower 32 bits of the
|
|
"rax" register value for x86_64, so "eax" could specify that it is
|
|
contained in "rax" by specifying the register number for "rax" (whose
|
|
register number is 0x00)
|
|
|
|
"container-regs:00;"
|
|
|
|
If a register is comprised of one or more registers, like "d0" is ARM
|
|
which is a 64 bit register, it might be made up of "s0" and "s1". If
|
|
the register number for "s0" is 0x20, and the register number of "s1"
|
|
is "0x21", the "container-regs" key/value pair would be:
|
|
|
|
"container-regs:20,21;"
|
|
|
|
This is handy for defining what GDB used to call "pseudo" registers.
|
|
These registers are never requested by LLDB via the register read
|
|
or write packets, the container registers will be requested on behalf
|
|
of this register.
|
|
|
|
invalidate-regs
|
|
The value for this key is a comma separated list of raw hex (optional
|
|
leading "0x") register numbers.
|
|
|
|
This specifies which register values should be invalidated when this
|
|
register is modified. For example if modifying "eax" would cause "rax",
|
|
"eax", "ax", "ah", and "al" to be modified where rax is 0x0, eax is 0x15,
|
|
ax is 0x25, ah is 0x35, and al is 0x39, the "invalidate-regs" key/value
|
|
pair would be:
|
|
|
|
"invalidate-regs:0,15,25,35,39;"
|
|
|
|
If there is a single register that gets invalidated, then omit the comma
|
|
and just list a single register:
|
|
|
|
"invalidate-regs:0;"
|
|
|
|
This is handy when modifying a specific register can cause other
|
|
register values to change. For example, when debugging an ARM target,
|
|
modifying the CPSR register can cause the r8 - r14 and cpsr value to
|
|
change depending on if the mode has changed.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qPlatform_RunCommand"
|
|
//
|
|
// BRIEF
|
|
// Run a command in a shell on the connected remote machine.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High. This command allows LLDB clients to run arbitrary shell
|
|
// commands on a remote host.
|
|
//
|
|
/----------------------------------------------------------------------
|
|
|
|
The request consists of the command to be executed encoded in ASCII characters
|
|
converted into hex bytes.
|
|
|
|
The response to this packet consists of the letter F followed by the return code,
|
|
followed by the signal number (or 0 if no signal was delivered), and escaped bytes
|
|
of captured program output.
|
|
|
|
Below is an example communication from a client sending an "ls -la" command:
|
|
|
|
send packet: $qPlatform_RunCommand:6c73202d6c61,00000002#ec
|
|
read packet: $F,00000000,00000000,total 4736
|
|
drwxrwxr-x 16 username groupname 4096 Aug 15 21:36 .
|
|
drwxr-xr-x 17 username groupname 4096 Aug 10 16:39 ..
|
|
-rw-rw-r-- 1 username groupname 73875 Aug 12 16:46 notes.txt
|
|
drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp
|
|
-rw-r--r-- 1 username groupname 2792 Aug 12 16:46 a.out
|
|
-rw-r--r-- 1 username groupname 3190 Aug 12 16:46 Makefile
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qHostInfo"
|
|
//
|
|
// BRIEF
|
|
// Get information about the host we are remotely connected to.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High. This packet is usually very easy to implement and can help
|
|
// LLDB select the correct plug-ins for the job based on the target
|
|
// triple information that is suppied.
|
|
//----------------------------------------------------------------------
|
|
|
|
LLDB supports a host info call that gets all sorts of details of the system
|
|
that is being debugged:
|
|
|
|
send packet: $qHostInfo#00
|
|
read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00
|
|
|
|
Key value pairs are one of:
|
|
|
|
cputype: is a number that is the mach-o CPU type that is being debugged (base 10)
|
|
cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged (base 10)
|
|
triple: a string for the target triple (x86_64-apple-macosx) that can be used to specify arch + vendor + os in one entry
|
|
vendor: a string for the vendor (apple), not needed if "triple" is specified
|
|
ostype: a string for the OS being debugged (darwin, linux, freebsd), not needed if "triple" is specified
|
|
endian: is one of "little", "big", or "pdp"
|
|
ptrsize: an unsigned number that represents how big pointers are in bytes on the debug target
|
|
hostname: the hostname of the host that is running the GDB server if available
|
|
os_build: a string for the the OS build for the remote host as a string value
|
|
os_kernel: a string describing the kernel version
|
|
os_version: a version string that represents the current OS version (10.8.2)
|
|
watchpoint_exceptions_received: one of "before" or "after" to specify if a watchpoint is triggered before or after the pc when it stops
|
|
default_packet_timeout: an unsigned number that specifies the default timeout in seconds
|
|
distribution_id: optional. For linux, specifies distribution id (e.g. ubuntu, fedora, etc.)
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qGDBServerVersion"
|
|
//
|
|
// BRIEF
|
|
// Get version information about this implementation of the gdb-remote
|
|
// protocol.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High. This packet is usually very easy to implement and can help
|
|
// LLDB to work around bugs in a server's implementation when they
|
|
// are found.
|
|
//----------------------------------------------------------------------
|
|
|
|
The goal of this packet is to provide enough information about an
|
|
implementation of the gdb-remote-protocol server that lldb can
|
|
work around implementation problems that are discovered after the
|
|
version has been released/deployed. The name and version number
|
|
should be sufficiently unique that lldb can unambiguously identify
|
|
the origin of the program (for instance, debugserver from lldb) and
|
|
the version/submission number/patch level of the program - whatever
|
|
is appropriate for your server implementation.
|
|
|
|
The packet follows the key-value pair model, semicolon separated.
|
|
|
|
send packet: $qGDBServerVersion#00
|
|
read packet: $name:debugserver;version:310.2;#00
|
|
|
|
Other clients may find other key-value pairs to be useful for identifying
|
|
a gdb stub. Patch level, release name, build number may all be keys that
|
|
better describe your implementation's version.
|
|
Suggested key names:
|
|
|
|
name : the name of your remote server - "debugserver" is the lldb standard
|
|
implementation
|
|
|
|
version : identifies the version number of this server
|
|
|
|
patch_level : the patch level of this server
|
|
|
|
release_name : the name of this release, if your project uses names
|
|
|
|
build_number : if you use a build system with increasing build numbers,
|
|
this may be the right key name for your server
|
|
|
|
major_version : major version number
|
|
minor_version : minor version number
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qProcessInfo"
|
|
//
|
|
// BRIEF
|
|
// Get information about the process we are currently debugging.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Medium. On systems which can launch multiple different architecture processes,
|
|
// the qHostInfo may not disambiguate sufficiently to know what kind of
|
|
// process is being debugged.
|
|
// e.g. on a 64-bit x86 Mac system both 32-bit and 64-bit user processes are possible,
|
|
// and with Mach-O universal files, the executable file may contain both 32- and
|
|
// 64-bit slices so it may be impossible to know until you're attached to a real
|
|
// process to know what you're working with.
|
|
//
|
|
// All numeric fields return base-16 numbers without any "0x" prefix.
|
|
//----------------------------------------------------------------------
|
|
|
|
An i386 process:
|
|
|
|
send packet: $qProcessInfo#00
|
|
read packet: $pid:42a8;parent-pid:42bf;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:7;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:4;#00
|
|
|
|
An x86_64 process:
|
|
|
|
send packet: $qProcessInfo#00
|
|
read packet: $pid:d22c;parent-pid:d34d;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:1000007;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:8;#00
|
|
|
|
Key value pairs include:
|
|
|
|
pid: the process id
|
|
parent-pid: the process of the parent process (often debugserver will become the parent when attaching)
|
|
real-uid: the real user id of the process
|
|
real-gid: the real group id of the process
|
|
effective-uid: the effective user id of the process
|
|
effective-gid: the effective group id of the process
|
|
cputype: the Mach-O CPU type of the process (base 16)
|
|
cpusubtype: the Mach-O CPU subtype of the process (base 16)
|
|
ostype: is a string the represents the OS being debugged (darwin, linux, freebsd)
|
|
vendor: is a string that represents the vendor (apple)
|
|
endian: is one of "little", "big", or "pdp"
|
|
ptrsize: is a number that represents how big pointers are in bytes
|
|
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qShlibInfoAddr"
|
|
//
|
|
// BRIEF
|
|
// Get an address where the dynamic linker stores information about
|
|
// where shared libraries are loaded.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High if you have a dynamic loader plug-in in LLDB for your target
|
|
// triple (see the "qHostInfo" packet) that can use this information.
|
|
// Many times address load randomization can make it hard to detect
|
|
// where the dynamic loader binary and data structures are located and
|
|
// some platforms know, or can find out where this information is.
|
|
//
|
|
// Low if you have a debug target where all object and symbol files
|
|
// contain static load addresses.
|
|
//----------------------------------------------------------------------
|
|
|
|
LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each
|
|
debugger as to where to find the dynamic loader information. For darwin
|
|
binaries that run in user land this is the address of the "all_image_infos"
|
|
structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO
|
|
call. The result is returned as big endian hex bytes that are the address
|
|
value:
|
|
|
|
send packet: $qShlibInfoAddr#00
|
|
read packet: $7fff5fc40040#00
|
|
|
|
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qThreadStopInfo<tid>"
|
|
//
|
|
// BRIEF
|
|
// Get information about why a thread, whose ID is "<tid>", is stopped.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High if you need to support multi-threaded or multi-core debugging.
|
|
// Many times one thread will hit a breakpoint and while the debugger
|
|
// is in the process of suspending the other threads, other threads
|
|
// will also hit a breakpoint. This packet allows LLDB to know why all
|
|
// threads (live system debug) / cores (JTAG) in your program have
|
|
// stopped and allows LLDB to display and control your program
|
|
// correctly.
|
|
//----------------------------------------------------------------------
|
|
|
|
LLDB tries to use the "qThreadStopInfo" packet which is formatted as
|
|
"qThreadStopInfo%x" where %x is the hex thread ID. This requests information
|
|
about why a thread is stopped. The response is the same as the stop reply
|
|
packets and tells us what happened to the other threads. The standard GDB
|
|
remote packets love to think that there is only _one_ reason that _one_ thread
|
|
stops at a time. This allows us to see why all threads stopped and allows us
|
|
to implement better multi-threaded debugging support.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "QThreadSuffixSupported"
|
|
//
|
|
// BRIEF
|
|
// Try to enable thread suffix support for the 'g', 'G', 'p', and 'P'
|
|
// packets.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High. Adding a thread suffix allows us to read and write registers
|
|
// more efficiently and stops us from having to select a thread with
|
|
// one packet and then read registers with a second packet. It also
|
|
// makes sure that no errors can occur where the debugger thinks it
|
|
// already has a thread selected (see the "Hg" packet from the standard
|
|
// GDB remote protocol documentation) yet the remote GDB server actually
|
|
// has another thread selected.
|
|
//----------------------------------------------------------------------
|
|
|
|
When reading thread registers, you currently need to set the current
|
|
thread, then read the registers. This is kind of cumbersome, so we added the
|
|
ability to query if the remote GDB server supports adding a "thread:<tid>;"
|
|
suffix to all packets that request information for a thread. To test if the
|
|
remote GDB server supports this feature:
|
|
|
|
send packet: $QThreadSuffixSupported#00
|
|
read packet: OK
|
|
|
|
If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a
|
|
thread suffix. So to send a 'g' packet (read all register values):
|
|
|
|
send packet: $g;thread:<tid>;#00
|
|
read packet: ....
|
|
|
|
send packet: $G;thread:<tid>;#00
|
|
read packet: ....
|
|
|
|
send packet: $p1a;thread:<tid>;#00
|
|
read packet: ....
|
|
|
|
send packet: $P1a=1234abcd;thread:<tid>;#00
|
|
read packet: ....
|
|
|
|
|
|
otherwise, without this you would need to always send two packets:
|
|
|
|
send packet: $Hg<tid>#00
|
|
read packet: ....
|
|
send packet: $g#00
|
|
read packet: ....
|
|
|
|
We also added support for allocating and deallocating memory. We use this to
|
|
allocate memory so we can run JITed code.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "_M<size>,<permissions>"
|
|
//
|
|
// BRIEF
|
|
// Allocate memory on the remote target with the specified size and
|
|
// permissions.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High if you want LLDB to be able to JIT code and run that code. JIT
|
|
// code also needs data which is also allocated and tracked.
|
|
//
|
|
// Low if you don't support running JIT'ed code.
|
|
//----------------------------------------------------------------------
|
|
|
|
The allocate memory packet starts with "_M<size>,<permissions>". It returns a
|
|
raw big endian address value, or "" for unimplemented, or "EXX" for an error
|
|
code. The packet is formatted as:
|
|
|
|
char packet[256];
|
|
int packet_len;
|
|
packet_len = ::snprintf (
|
|
packet,
|
|
sizeof(packet),
|
|
"_M%zx,%s%s%s",
|
|
(size_t)size,
|
|
permissions & lldb::ePermissionsReadable ? "r" : "",
|
|
permissions & lldb::ePermissionsWritable ? "w" : "",
|
|
permissions & lldb::ePermissionsExecutable ? "x" : "");
|
|
|
|
You request a size and give the permissions. This packet does NOT need to be
|
|
implemented if you don't want to support running JITed code. The return value
|
|
is just the address of the newly allocated memory as raw big endian hex bytes.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "_m<addr>"
|
|
//
|
|
// BRIEF
|
|
// Deallocate memory that was previously allocated using an allocate
|
|
// memory pack.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High if you want LLDB to be able to JIT code and run that code. JIT
|
|
// code also needs data which is also allocated and tracked.
|
|
//
|
|
// Low if you don't support running JIT'ed code.
|
|
//----------------------------------------------------------------------
|
|
|
|
The deallocate memory packet is "_m<addr>" where you pass in the address you
|
|
got back from a previous call to the allocate memory packet. It returns "OK"
|
|
if the memory was successfully deallocated, or "EXX" for an error, or "" if
|
|
not supported.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qMemoryRegionInfo:<addr>"
|
|
//
|
|
// BRIEF
|
|
// Get information about the address the range that contains "<addr>"
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Medium. This is nice to have, but it isn't necessary. It helps LLDB
|
|
// do stack unwinding when we branch into memory that isn't executable.
|
|
// If we can detect that the code we are stopped in isn't executable,
|
|
// then we can recover registers for stack frames above the current
|
|
// frame. Otherwise we must assume we are in some JIT'ed code (not JIT
|
|
// code that LLDB has made) and assume that no registers are available
|
|
// in higher stack frames.
|
|
//----------------------------------------------------------------------
|
|
|
|
We added a way to get information for a memory region. The packet is:
|
|
|
|
qMemoryRegionInfo:<addr>
|
|
|
|
Where <addr> is a big endian hex address. The response is returned in a series
|
|
of tuples like the data returned in a stop reply packet. The currently valid
|
|
tuples tp return are:
|
|
|
|
start:<start-addr>; // <start-addr> is a big endian hex address that is
|
|
// the start address of the range that contains <addr>
|
|
|
|
size:<size>; // <size> is a big endian hex byte size of the address
|
|
// of the range that contains <addr>
|
|
|
|
permissions:<permissions>; // <permissions> is a string that contains one
|
|
// or more of the characters from "rwx"
|
|
|
|
error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is
|
|
// a hex encoded string value that
|
|
// contains an error string
|
|
|
|
If the address requested is not in a mapped region (e.g. we've jumped through
|
|
a NULL pointer and are at 0x0) currently lldb expects to get back the size
|
|
of the unmapped region -- that is, the distance to the next valid region.
|
|
For instance, with a Mac OS X process which has nothing mapped in the first
|
|
4GB of its address space, if we're asking about address 0x2,
|
|
|
|
qMemoryRegionInfo:2
|
|
start:2;size:fffffffe;
|
|
|
|
The lack of 'permissions:' indicates that none of read/write/execute are valid
|
|
for this region.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "x" - Binary memory read
|
|
//
|
|
// Like the 'm' (read) and 'M' (write) packets, this is a partner to the
|
|
// 'X' (write binary data) packet, 'x'.
|
|
//
|
|
// It is called like
|
|
//
|
|
// xADDRESS,LENGTH
|
|
//
|
|
// where both ADDRESS and LENGTH are big-endian base 16 values.
|
|
//
|
|
// To test if this packet is available, send a addr/len of 0:
|
|
//
|
|
// x0,0
|
|
//
|
|
// and you will get an "OK" response.
|
|
//
|
|
// The reply will be the data requested in 8-bit binary data format.
|
|
// The standard quoting is applied to the payload -- characters
|
|
// } # $ *
|
|
// will all be escaped with '}' (0x7d) character and then XOR'ed with 0x20.
|
|
//
|
|
// A typical use to read 512 bytes at 0x1000 would look like
|
|
//
|
|
// x0x1000,0x200
|
|
//
|
|
// The "0x" prefixes are optional - like most of the gdb-remote packets,
|
|
// omitting them will work fine; these numbers are always base 16.
|
|
//
|
|
// The length of the payload is not provided. A reliable, 8-bit clean,
|
|
// transport layer is assumed.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// Detach and stay stopped:
|
|
//
|
|
// We extended the "D" packet to specify that the monitor should keep the
|
|
// target suspended on detach. The normal behavior is to resume execution
|
|
// on detach. We will send:
|
|
//
|
|
// qSupportsDetachAndStayStopped:
|
|
//
|
|
// to query whether the monitor supports the extended detach, and if it does,
|
|
// when we want the monitor to detach but not resume the target, we will
|
|
// send:
|
|
//
|
|
// D1
|
|
//
|
|
// In any case, if we want the normal detach behavior we will just send:
|
|
//
|
|
// D
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// QSaveRegisterState
|
|
// QSaveRegisterState;thread:XXXX;
|
|
//
|
|
// BRIEF
|
|
// The QSaveRegisterState packet tells the remote debugserver to save
|
|
// all registers and return a non-zero unique integer ID that
|
|
// represents these save registers. If thread suffixes are enabled the
|
|
// second form of this packet is used, otherwise the first form is
|
|
// used. This packet is called prior to executing an expression, so
|
|
// the remote GDB server should do anything it needs to in order to
|
|
// ensure the registers that are saved are correct. On MacOSX this
|
|
// involves calling "thread_abort_safely(mach_port_t thread)" to
|
|
// ensure we get the correct registers for a thread in case it is
|
|
// currently having code run on its behalf in the kernel.
|
|
//
|
|
// RESPONSE
|
|
// unsigned - The save_id result is a non-zero unsigned integer value
|
|
// that can be passed back to the GDB server using a
|
|
// QRestoreRegisterState packet to restore the registers
|
|
// one time.
|
|
// "EXX" - or an error code in the form of EXX where XX is a
|
|
// hex error code.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low, this is mostly a convenience packet to avoid having to send all
|
|
// registers via a g packet. It should only be implemented if support
|
|
// for the QRestoreRegisterState is added.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// QRestoreRegisterState:<save_id>
|
|
// QRestoreRegisterState:<save_id>;thread:XXXX;
|
|
//
|
|
// BRIEF
|
|
// The QRestoreRegisterState packet tells the remote debugserver to
|
|
// restore all registers using the "save_id" which is an unsigned
|
|
// integer that was returned from a previous call to
|
|
// QSaveRegisterState. The restoration process can only be done once
|
|
// as the data backing the register state will be freed upon the
|
|
// completion of the QRestoreRegisterState command.
|
|
//
|
|
// If thread suffixes are enabled the second form of this packet is
|
|
// used, otherwise the first form is used.
|
|
//
|
|
// RESPONSE
|
|
// "OK" - if all registers were successfully restored
|
|
// "EXX" - for any errors
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low, this is mostly a convenience packet to avoid having to send all
|
|
// registers via a g packet. It should only be implemented if support
|
|
// for the QSaveRegisterState is added.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// Stop reply packet extensions
|
|
//
|
|
// BRIEF
|
|
// This section describes some of the additional information you can
|
|
// specify in stop reply packets that help LLDB to know more detailed
|
|
// information about your threads.
|
|
//
|
|
// DESCRIPTION
|
|
// Standard GDB remote stop reply packets are reply packets sent in
|
|
// response to a packet that made the program run. They come in the
|
|
// following forms:
|
|
//
|
|
// "SAA"
|
|
// "S" means signal and "AA" is a hex signal number that describes why
|
|
// the thread or stopped. It doesn't specify which thread, so the "T"
|
|
// packet is recommended to use instead of the "S" packet.
|
|
//
|
|
// "TAAkey1:value1;key2:value2;..."
|
|
// "T" means a thread stopped due to a unix signal where "AA" is a hex
|
|
// signal number that describes why the program stopped. This is
|
|
// followed by a series of key/value pairs:
|
|
// - If key is a hex number, it is a register number and value is
|
|
// the hex value of the register in debuggee endian byte order.
|
|
// - If key == "thread", then the value is the big endian hex
|
|
// thread-id of the stopped thread.
|
|
// - If key == "core", then value is a hex number of the core on
|
|
// which the stop was detected.
|
|
// - If key == "watch" or key == "rwatch" or key == "awatch", then
|
|
// value is the data address in big endian hex
|
|
// - If key == "library", then value is ignore and "qXfer:libraries:read"
|
|
// packets should be used to detect any newly loaded shared libraries
|
|
//
|
|
// "WAA"
|
|
// "W" means the process exited and "AA" is the exit status.
|
|
//
|
|
// "XAA"
|
|
// "X" means the process exited and "AA" is signal that caused the program
|
|
// to exit.
|
|
//
|
|
// "O<ascii-hex-string>"
|
|
// "O" means STDOUT has data that was written to its console and is
|
|
// being delivered to the debugger. This packet happens asynchronously
|
|
// and the debugger is expected to continue to way for another stop reply
|
|
// packet.
|
|
//
|
|
// LLDB EXTENSIONS
|
|
//
|
|
// We have extended the "T" packet to be able to also understand the
|
|
// following keys and values:
|
|
//
|
|
// KEY VALUE DESCRIPTION
|
|
// =========== ======== ================================================
|
|
// "metype" unsigned mach exception type (the value of the EXC_XXX enumerations)
|
|
// as an unsigned integer. For targets with mach
|
|
// kernels only.
|
|
//
|
|
// "mecount" unsigned mach exception data count as an unsigned integer
|
|
// For targets with mach kernels only.
|
|
//
|
|
// "medata" unsigned There should be "mecount" of these and it is the data
|
|
// that goes along with a mach exception (as an unsigned
|
|
// integer). For targets with mach kernels only.
|
|
//
|
|
// "name" string The name of the thread as a plain string. The string
|
|
// must not contain an special packet characters or
|
|
// contain a ':' or a ';'. Use "hexname" if the thread
|
|
// name has special characters.
|
|
//
|
|
// "hexname" ascii-hex An ASCII hex string that contains the name of the thread
|
|
//
|
|
// "qaddr" hex Big endian hex value that contains the libdispatch
|
|
// queue address for the queue of the thread.
|
|
//
|
|
// "reason" enum The enumeration must be one of:
|
|
// "trace" the program stopped after a single instruction
|
|
// was executed on a core. Usually done when single
|
|
// stepping past a breakpoint
|
|
// "breakpoint" a breakpoint set using a 'z' packet was hit.
|
|
// "trap" stopped due to user interruption
|
|
// "signal" stopped due to an actual unix signal, not
|
|
// just the debugger using a unix signal to keep
|
|
// the GDB remote client happy.
|
|
// "watchpoint". Should be used in conjunction with
|
|
// the "watch"/"rwatch"/"awatch" key value pairs.
|
|
// "exception" an exception stop reason. Use with
|
|
// the "description" key/value pair to describe the
|
|
// exceptional event the user should see as the stop
|
|
// reason.
|
|
// "description" ascii-hex An ASCII hex string that contains a more descriptive
|
|
// reason that the thread stopped. This is only needed
|
|
// if none of the key/value pairs are enough to
|
|
// describe why something stopped.
|
|
//
|
|
// BEST PRACTICES:
|
|
// Since register values can be supplied with this packet, it is often useful
|
|
// to return the PC, SP, FP, LR (if any), and FLAGS registers so that separate
|
|
// packets don't need to be sent to read each of these registers from each
|
|
// thread.
|
|
//
|
|
// If a thread is stopped for no reason (like just because another thread
|
|
// stopped, or because when one core stops all cores should stop), use a
|
|
// "T" packet with "00" as the signal number and fill in as many key values
|
|
// and registers as possible.
|
|
//
|
|
// LLDB likes to know why a thread stopped since many thread control
|
|
// operations like stepping over a source line, actually are implemented
|
|
// by running the process multiple times. If a breakpoint is hit while
|
|
// trying to step over a source line and LLDB finds out that a breakpoint
|
|
// is hit in the "reason", we will know to stop trying to do the step
|
|
// over because something happened that should stop us from trying to
|
|
// do the step. If we are at a breakpoint and we disable the breakpoint
|
|
// at the current PC and do an instruction single step, knowing that
|
|
// we stopped due to a "trace" helps us know that we can continue
|
|
// running versus stopping due to a "breakpoint" (if we have two
|
|
// breakpoint instruction on consecutive instructions). So the more info
|
|
// we can get about the reason a thread stops, the better job LLDB can
|
|
// do when controlling your process. A typical GDB server behavior is
|
|
// to send a SIGTRAP for breakpoints _and_ also when instruction single
|
|
// stepping, in this case the debugger doesn't really know why we
|
|
// stopped and it can make it hard for the debugger to control your
|
|
// program correctly. What if a real SIGTRAP was delivered to a thread
|
|
// while we were trying to single step? We wouldn't know the difference
|
|
// with a standard GDB remote server and we could do the wrong thing.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// High. Having the extra information in your stop reply packets makes
|
|
// your debug session more reliable and informative.
|
|
//----------------------------------------------------------------------
|
|
|
|
|
|
//----------------------------------------------------------------------
|
|
// PLATFORM EXTENSION - for use as a GDB remote platform
|
|
//----------------------------------------------------------------------
|
|
// "qfProcessInfo"
|
|
// "qsProcessInfo"
|
|
//
|
|
// BRIEF
|
|
// Get the first process info (qfProcessInfo) or subsequent processs
|
|
// info (qsProcessInfo) for one or more processes on the remote
|
|
// platform. The first call gets the first match and subsequent calls
|
|
// to qsProcessInfo gets the subsequent matches. Return an error EXX,
|
|
// where XX are two hex digits, when no more matches are available.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Required. The qfProcessInfo packet can be followed by a ':' and
|
|
// some key value pairs. The key value pairs in the command are:
|
|
//
|
|
// KEY VALUE DESCRIPTION
|
|
// =========== ======== ================================================
|
|
// "name" ascii-hex An ASCII hex string that contains the name of
|
|
// the process that will be matched.
|
|
// "name_match" enum One of: "equals", "starts_with", "ends_with",
|
|
// "contains" or "regex"
|
|
// "pid" integer A string value containing the decimal process ID
|
|
// "parent_pid" integer A string value containing the decimal parent
|
|
// process ID
|
|
// "uid" integer A string value containing the decimal user ID
|
|
// "gid" integer A string value containing the decimal group ID
|
|
// "euid" integer A string value containing the decimal effective user ID
|
|
// "egid" integer A string value containing the decimal effective group ID
|
|
// "all_users" bool A boolean value that specifies if processes should
|
|
// be listed for all users, not just the user that the
|
|
// platform is running as
|
|
// "triple" ascii-hex An ASCII hex target triple string ("x86_64",
|
|
// "x86_64-apple-macosx", "armv7-apple-ios")
|
|
//
|
|
// The response consists of key/value pairs where the key is separated from the
|
|
// values with colons and each pair is terminated with a semi colon. For a list
|
|
// of the key/value pairs in the response see the "qProcessInfoPID" packet
|
|
// documentation.
|
|
//
|
|
// Sample packet/response:
|
|
// send packet: $qfProcessInfo#00
|
|
// read packet: $pid:60001;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:7838365f36342d6170706c652d6d61636f7378;#00
|
|
// send packet: $qsProcessInfo#00
|
|
// read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:7838365f36342d6170706c652d6d61636f7378;#00
|
|
// send packet: $qsProcessInfo#00
|
|
// read packet: $E04#00
|
|
//----------------------------------------------------------------------
|
|
|
|
|
|
//----------------------------------------------------------------------
|
|
// PLATFORM EXTENSION - for use as a GDB remote platform
|
|
//----------------------------------------------------------------------
|
|
// "qLaunchGDBServer"
|
|
//
|
|
// BRIEF
|
|
// Have the remote platform launch a GDB server.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Required. The qLaunchGDBServer packet must be followed by a ':' and
|
|
// some key value pairs. The key value pairs in the command are:
|
|
//
|
|
// KEY VALUE DESCRIPTION
|
|
// =========== ======== ================================================
|
|
// "port" integer A string value containing the decimal port ID or
|
|
// zero if the port should be bound and returned
|
|
//
|
|
// "host" integer The host that connections should be limited to
|
|
// when the GDB server is connected to.
|
|
//
|
|
// The response consists of key/value pairs where the key is separated from the
|
|
// values with colons and each pair is terminated with a semi colon.
|
|
//
|
|
// Sample packet/response:
|
|
// send packet: $qLaunchGDBServer:port:0;host:lldb.apple.com;#00
|
|
// read packet: $pid:60025;port:50776;#00
|
|
//
|
|
// The "pid" key/value pair is only specified if the remote platform launched
|
|
// a separate process for the GDB remote server and can be omitted if no
|
|
// process was separately launched.
|
|
//
|
|
// The "port" key/value pair in the response lets clients know what port number
|
|
// to attach to in case zero was specified as the "port" in the sent command.
|
|
//----------------------------------------------------------------------
|
|
|
|
|
|
//----------------------------------------------------------------------
|
|
// PLATFORM EXTENSION - for use as a GDB remote platform
|
|
//----------------------------------------------------------------------
|
|
// "qProcessInfoPID:PID"
|
|
//
|
|
// BRIEF
|
|
// Have the remote platform get detailed information on a process by
|
|
// ID. PID is specified as a decimal integer.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Optional.
|
|
//
|
|
// The response consists of key/value pairs where the key is separated from the
|
|
// values with colons and each pair is terminated with a semi colon.
|
|
//
|
|
// The key value pairs in the response are:
|
|
//
|
|
// KEY VALUE DESCRIPTION
|
|
// =========== ======== ================================================
|
|
// "pid" integer Process ID as a decimal integer string
|
|
// "ppid" integer Parent process ID as a decimal integer string
|
|
// "uid" integer A string value containing the decimal user ID
|
|
// "gid" integer A string value containing the decimal group ID
|
|
// "euid" integer A string value containing the decimal effective user ID
|
|
// "egid" integer A string value containing the decimal effective group ID
|
|
// "name" ascii-hex An ASCII hex string that contains the name of the process
|
|
// "triple" ascii-hex A target triple ("x86_64-apple-macosx", "armv7-apple-ios")
|
|
//
|
|
// Sample packet/response:
|
|
// send packet: $qProcessInfoPID:60050#00
|
|
// read packet: $pid:60050;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:7838365f36342d6170706c652d6d61636f7378;#00
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// "vAttachName"
|
|
//
|
|
// BRIEF
|
|
// Same as vAttach, except instead of a "pid" you send a process name.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed for "process attach -n". If the packet isn't supported
|
|
// then "process attach -n" will fail gracefully. So you need only to support
|
|
// it if attaching to a process by name makes sense for your environment.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// "vAttachWait"
|
|
//
|
|
// BRIEF
|
|
// Same as vAttachName, except that the stub should wait for the next instance
|
|
// of a process by that name to be launched and attach to that.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed to support "process attach -w -n" which will fail
|
|
// gracefully if the packet is not supported.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qAttachOrWaitSupported"
|
|
//
|
|
// BRIEF
|
|
// This is a binary "is it supported" query. Return OK if you support
|
|
// vAttachOrWait
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. This is required if you support vAttachOrWait, otherwise no support
|
|
// is needed since the standard "I don't recognize this packet" response
|
|
// will do the right thing.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// "vAttachOrWait"
|
|
//
|
|
// BRIEF
|
|
// Same as vAttachWait, except that the stub will attach to a process
|
|
// by name if it exists, and if it does not, it will wait for a process
|
|
// of that name to appear and attach to it.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed to implement "process attach -w -i false -n". If
|
|
// you don't implement it but do implement -n AND lldb can somehow get
|
|
// a process list from your device, it will fall back on scanning the
|
|
// process list, and sending vAttach or vAttachWait depending on
|
|
// whether the requested process exists already. This is racy,
|
|
// however, so if you want to support this behavior it is better to
|
|
// support this packet.
|
|
//----------------------------------------------------------------------
|