forked from OSchip/llvm-project
1916 lines
88 KiB
Plaintext
1916 lines
88 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
|
|
start 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.
|
|
|
|
//----------------------------------------------------------------------
|
|
// "QEnableErrorStrings"
|
|
//
|
|
// BRIEF
|
|
// This packet enables reporting of Error strings in remote packet
|
|
// replies from the server to client. If the server supports this
|
|
// feature, it should send an OK response. The client can expect the
|
|
// following error replies if this feature is enabled in the server ->
|
|
//
|
|
// EXX;AAAAAAAAA
|
|
//
|
|
// where AAAAAAAAA will be a hex encoded ASCII string.
|
|
// XX is hex encoded byte number.
|
|
//
|
|
// It must be noted that even if the client has enabled reporting
|
|
// strings in error replies, it must not expect error strings to all
|
|
// error replies.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. Only needed if the remote target wants to provide strings that
|
|
// are human readable along with an error code.
|
|
//----------------------------------------------------------------------
|
|
|
|
send packet: $QEnableErrorStrings
|
|
read packet: $OK#00
|
|
|
|
//----------------------------------------------------------------------
|
|
// "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.
|
|
|
|
//----------------------------------------------------------------------
|
|
// QListThreadsInStopReply
|
|
//
|
|
// BRIEF
|
|
// Enable the threads: and thread-pcs: data in the question-mark packet
|
|
// ("T packet") responses when the stub reports that a program has
|
|
// stopped executing.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Performance. This is a performance benefit to lldb if the thread id's
|
|
// and thread pc values are provided to lldb in the T stop packet -- if
|
|
// they are not provided to lldb, lldb will likely need to send one to
|
|
// two packets per thread to fetch the data at every private stop.
|
|
//----------------------------------------------------------------------
|
|
|
|
send packet: QListThreadsInStopReply
|
|
read packet: OK
|
|
|
|
//----------------------------------------------------------------------
|
|
// jTraceStart:
|
|
//
|
|
// BRIEF
|
|
// Packet for starting trace of type lldb::TraceType. The following
|
|
// parameters should be appended to the packet formatted as a JSON
|
|
// dictionary, where the schematic for the JSON dictionary in terms of
|
|
// the recognized Keys is given below in the table.
|
|
// Different tracing types could require different custom parameters.
|
|
// Such custom tracing parameters if needed should be collectively
|
|
// specified in a JSON dictionary and the dictionary can be appended
|
|
// to this packet (as Value corresponding to "params"). Since sending
|
|
// JSON data over gdb-remote protocol has certain limitations, binary
|
|
// escaping convention should be used.
|
|
//
|
|
// Following is the list of parameters -
|
|
//
|
|
// Key Value (Integer) (O)Optional/
|
|
// (except params which should be a (M)Mandatory
|
|
// JSON dictionary)
|
|
// ========== ====================================================
|
|
//
|
|
// type The type of trace to start (see M
|
|
// lldb-enumerations for TraceType)
|
|
//
|
|
// buffersize The size of the buffer to allocate M
|
|
// for trace gathering.
|
|
//
|
|
// threadid The id of the thread to start tracing O
|
|
// on.
|
|
//
|
|
// metabuffersize The size of buffer to hold meta data O
|
|
// used for decoding the trace data.
|
|
//
|
|
// params Any parameters that are specific to O
|
|
// certain trace technologies should be
|
|
// collectively specified as a JSON
|
|
// dictionary
|
|
// ========== ====================================================
|
|
//
|
|
// Each tracing instance is identified by a trace id which is returned
|
|
// as the reply to this packet. In case the tracing failed to begin an
|
|
// error code along with a hex encoded ASCII message is returned
|
|
// instead.
|
|
//----------------------------------------------------------------------
|
|
|
|
send packet: jTraceStart:{"type":<type>,"buffersize":<buffersize>}]
|
|
read packet: <trace id>/E<error code>;AAAAAAAAA
|
|
|
|
//----------------------------------------------------------------------
|
|
// jTraceStop:
|
|
//
|
|
// BRIEF
|
|
// Stop tracing instance with trace id <trace id>, of course trace
|
|
// needs to be started before. The following parameters should be
|
|
// formatted as a JSON dictionary to the packet. Since sending
|
|
// JSON data over gdb-remote protocol has certain limitations, binary
|
|
// escaping convention should be used.
|
|
//
|
|
// Following is the list of parameters -
|
|
//
|
|
// Key Value (Integer) (O)Optional/
|
|
// (M)Mandatory
|
|
// ========== ====================================================
|
|
//
|
|
// traceid The trace id of the tracing instance M
|
|
//
|
|
// threadid The id of the thread to stop tracing O
|
|
// on. Since <trace id> could map to
|
|
// multiple trace instances (in case it
|
|
// maps to the complete process), the
|
|
// threadid of a particular thread could
|
|
// be appended as "threadid:<thread id>;"
|
|
// to stop tracing on that thread.
|
|
// ========== ====================================================
|
|
//
|
|
// An OK response is sent in case of success else an error code along
|
|
// with a hex encoded ASCII message is returned.
|
|
//----------------------------------------------------------------------
|
|
|
|
send packet: jTraceStop:{"traceid":<trace id>}]
|
|
read packet: <OK response>/E<error code>;AAAAAAAAA
|
|
|
|
//----------------------------------------------------------------------
|
|
// jTraceBufferRead:
|
|
//
|
|
// BRIEF
|
|
// Packet for reading the trace for tracing instance <trace id>, i.e the
|
|
// id obtained from StartTrace API. The following parameters should be
|
|
// formatted as a JSON dictionary to the packet. Since sending
|
|
// JSON data over gdb-remote protocol has certain limitations, binary
|
|
// escaping convention should be used.
|
|
//
|
|
// Following is the list of parameters -
|
|
//
|
|
// Key Value (Integer) (O)Optional/
|
|
// (M)Mandatory
|
|
// ========== ====================================================
|
|
// traceid The trace id of the tracing instance M
|
|
//
|
|
// offset The offset to start reading the data M
|
|
// from.
|
|
//
|
|
// buffersize The size of the data intended to read. M
|
|
//
|
|
// threadid The id of the thread to retrieve data O
|
|
// from.
|
|
// ========== ====================================================
|
|
//
|
|
// The trace data is sent as raw binary data if the read was successful
|
|
// else an error code along with a hex encoded ASCII message is sent.
|
|
//----------------------------------------------------------------------
|
|
|
|
send packet: jTraceBufferRead:{"traceid":<trace id>,"offset":<byteoffset>,"buffersize":<byte_count>}]
|
|
read packet: <binary trace data>/E<error code>;AAAAAAAAA
|
|
|
|
//----------------------------------------------------------------------
|
|
// jTraceMetaRead:
|
|
//
|
|
// BRIEF
|
|
// Similar Packet as above except it reads meta data.
|
|
//----------------------------------------------------------------------
|
|
|
|
/----------------------------------------------------------------------
|
|
// jTraceConfigRead:
|
|
//
|
|
// BRIEF
|
|
// Request the trace configuration for the tracing instance with id
|
|
// <trace id>.
|
|
//
|
|
// Following is the list of parameters -
|
|
//
|
|
// Key Value (Integer) (O)Optional/
|
|
// (M)Mandatory
|
|
// ========== ====================================================
|
|
// traceid The trace id of the tracing instance M
|
|
//
|
|
// threadid The id of the thread to obtain trace O
|
|
// configuration from. Since <trace id>
|
|
// could map to multiple trace instances
|
|
// (in case it maps to the complete
|
|
// process), the threadid of a particular
|
|
// thread could be appended as
|
|
// "threadid:<thread id>;" to obtain the
|
|
// trace configuration of that thread.
|
|
// ========== ====================================================
|
|
//
|
|
// In the response packet the trace configuration is sent as text,
|
|
// formatted as a JSON dictionary. Since sending JSON data over
|
|
// gdb-remote protocol has certain limitations, binary escaping
|
|
// convention is used.
|
|
// In case the trace instance with the <trace id> was not found, an
|
|
// error code along with a hex encoded ASCII message is returned.
|
|
//----------------------------------------------------------------------
|
|
|
|
send packet: jTraceConfigRead:{"traceid":<trace id>}
|
|
read packet: {"conf1":<conf1>,"conf2":<conf2>,"params":{"paramName":paramValue}]}];/E<error code>;AAAAAAAAA
|
|
|
|
//----------------------------------------------------------------------
|
|
// "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.
|
|
//
|
|
// NB: As of summer 2015, lldb can get register information from the
|
|
// "qXfer:features:read:target.xml" FSF gdb standard register packet
|
|
// where the stub provides register definitions in an XML file.
|
|
// If qXfer:features:read:target.xml is supported, qRegisterInfo does
|
|
// not need to be implemented.
|
|
//----------------------------------------------------------------------
|
|
|
|
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 series 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 register)
|
|
|
|
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_shell"
|
|
//
|
|
// 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_shell: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
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qPlatform_mkdir"
|
|
//
|
|
// BRIEF
|
|
// Creates a new directory on the connected remote machine.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. This command allows LLDB clients to create new directories on
|
|
// a remote host.
|
|
//
|
|
/----------------------------------------------------------------------
|
|
|
|
Request:
|
|
qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path>
|
|
|
|
Reply:
|
|
F<mkdir-return-code>
|
|
mkdir called successfully and returned with the given return code
|
|
Exx
|
|
An error occurred
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qPlatform_chmod"
|
|
//
|
|
// BRIEF
|
|
// Change the permissions of a file on the connected remote machine.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. This command allows LLDB clients to change the permissions of
|
|
// a file on the remote host.
|
|
//
|
|
/----------------------------------------------------------------------
|
|
|
|
Request:
|
|
qPlatform_chmod:<hex-file-mode>,<ascii-hex-path>
|
|
|
|
Reply:
|
|
F<chmod-return-code>
|
|
chmod called successfully and returned with the given return code
|
|
Exx
|
|
An error occurred
|
|
|
|
//----------------------------------------------------------------------
|
|
// "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 supplied.
|
|
//----------------------------------------------------------------------
|
|
|
|
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 (macosx, linux, freebsd, ios, watchos), 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 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.)
|
|
osmajor: optional, specifies the major version number of the OS (e.g. for macOS 10.12.2, it would be 10)
|
|
osminor: optional, specifies the minor version number of the OS (e.g. for macOS 10.12.2, it would be 12)
|
|
ospatch: optional, specifies the patch level number of the OS (e.g. for macOS 10.12.2, it would be 2)
|
|
|
|
//----------------------------------------------------------------------
|
|
// "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 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 to 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"
|
|
|
|
name:<name>; // <name> is a hex encoded string that contains the name of
|
|
// the memory region mapped at the given address. In case of
|
|
// regions backed by a file it have to be the absolute path of
|
|
// the file while for anonymous regions it have to be the name
|
|
// associated to the region if that is available.
|
|
|
|
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 macOS 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 macOS 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.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// qFileLoadAddress:<file_path>
|
|
//
|
|
// BRIEF
|
|
// Get the load address of a memory mapped file.
|
|
// The load address is defined as the address of the first memory
|
|
// region what contains data mapped from the specified file.
|
|
//
|
|
// RESPONSE
|
|
// <unsigned-hex64> - Load address of the file in big endian encoding
|
|
// "E01" - the requested file isn't loaded
|
|
// "EXX" - for any other errors
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low, required if dynamic linker don't fill in the load address of
|
|
// some object file in the rendezvous data structure.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// qModuleInfo:<module_path>;<arch triple>
|
|
//
|
|
// BRIEF
|
|
// Get information for a module by given module path and architecture.
|
|
//
|
|
// RESPONSE
|
|
// "(uuid|md5):...;triple:...;file_offset:...;file_size...;"
|
|
// "EXX" - for any errors
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Optional, required if dynamic loader cannot fetch module's information like
|
|
// UUID directly from inferior's memory.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// jModulesInfo:[{"file":"...",triple:"..."}, ...]
|
|
//
|
|
// BRIEF
|
|
// Get information for a list of modules by given module path and
|
|
// architecture.
|
|
//
|
|
// RESPONSE
|
|
// A JSON array of dictionaries containing the following keys: uuid,
|
|
// triple, file_path, file_offset, file_size. The meaning of the fields
|
|
// is the same as in the qModuleInfo packet. The server signals the
|
|
// failure to retrieve the module info for a file by ommiting the
|
|
// corresponding array entry from the response. The server may also
|
|
// include entries the client did not ask for, if it has reason to
|
|
// the modules will be interesting to the client.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Optional. If not implemented, qModuleInfo packet will be used, which
|
|
// may be slower if the target contains a large number of modules and
|
|
// the communication link has a non-negligible latency.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// 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 wait 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.
|
|
//
|
|
// "threads" comma-sep-base16 A list of thread ids for all threads (including
|
|
// the thread that we're reporting as stopped) that
|
|
// are live in the process right now. lldb may
|
|
// request that this be included in the T packet via
|
|
// the QListThreadsInStopReply packet earlier in
|
|
// the debug session.
|
|
//
|
|
// Example:
|
|
// threads:63387,633b2,63424,63462,63486;
|
|
//
|
|
// "thread-pcs" comma-sep-base16 A list of pc values for all threads that currently
|
|
// exist in the process, including the thread that
|
|
// this T packet is reporting as stopped.
|
|
// This key-value pair will only be emitted when the
|
|
// "threads" key is already included in the T packet.
|
|
// The pc values correspond to the threads reported
|
|
// in the "threads" list. The number of pcs in the
|
|
// "thread-pcs" list will be the same as the number of
|
|
// threads in the "threads" list.
|
|
// lldb may request that this be included in the T
|
|
// packet via the QListThreadsInStopReply packet
|
|
// earlier in the debug session.
|
|
//
|
|
// Example:
|
|
// thread-pcs:dec14,2cf872b0,2cf8681c,2d02d68c,2cf716a8;
|
|
//
|
|
// 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 process
|
|
// 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" string An ASCII 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:x86_64-apple-macosx;#00
|
|
// send packet: $qsProcessInfo#00
|
|
// read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:x86_64-apple-macosx;#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" string 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:x86_64-apple-macosx;#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.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// "jThreadExtendedInfo"
|
|
//
|
|
// BRIEF
|
|
// This packet, which takes its arguments as JSON and sends its reply as
|
|
// JSON, allows the gdb remote stub to provide additional information
|
|
// about a given thread.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. This packet is only needed if the gdb remote stub wants to
|
|
// provide interesting additional information about a thread for the
|
|
// user.
|
|
//
|
|
// This packet takes its arguments in JSON form ( http://www.json.org ).
|
|
// At a minimum, a thread must be specified, for example:
|
|
//
|
|
// jThreadExtendedInfo:{"thread":612910}
|
|
//
|
|
// Because this is a JSON string, the thread number is provided in base10.
|
|
// Additional key-value pairs may be provided by lldb to the gdb remote
|
|
// stub. For instance, on some versions of macOS, lldb can read offset
|
|
// information out of the system libraries. Using those offsets, debugserver
|
|
// is able to find the Thread Specific Address (TSD) for a thread and include
|
|
// that in the return information. So lldb will send these additional fields
|
|
// like so:
|
|
//
|
|
// jThreadExtendedInfo:{"plo_pthread_tsd_base_address_offset":0,"plo_pthread_tsd_base_offset":224,"plo_pthread_tsd_entry_size":8,"thread":612910}
|
|
//
|
|
// There are no requirements for what is included in the response. A simple
|
|
// reply on a OS X Yosemite / iOS 8 may include the pthread_t value, the
|
|
// Thread Specific Data (TSD) address, the dispatch_queue_t value if the thread
|
|
// is associated with a GCD queue, and the requested Quality of Service (QoS)
|
|
// information about that thread. For instance, a reply may look like:
|
|
//
|
|
// {"tsd_address":4371349728,"requested_qos":{"enum_value":33,"constant_name":"QOS_CLASS_USER_INTERACTIVE","printable_name":"User Interactive"},"pthread_t":4371349504,"dispatch_queue_t":140735087127872}
|
|
//
|
|
// tsd_address, pthread_t, and dispatch_queue_t are all simple key-value pairs.
|
|
// The JSON standard requires that numbers be expressed in base 10 - so all of
|
|
// these are. requested_qos is a dictionary with three key-value pairs in it -
|
|
// so the UI layer may choose the form most appropriate for displaying to the user.
|
|
//
|
|
// Sending JSON over gdb-remote protocol introduces some problems. We may be
|
|
// sending strings with arbitrary contents in them, including the '#', '$', and '*'
|
|
// characters that have special meaning in gdb-remote protocol and cannot occur
|
|
// in the middle of the string. The standard solution for this would be to require
|
|
// ascii-hex encoding of all strings, or ascii-hex encode the entire JSON payload.
|
|
//
|
|
// Instead, the binary escaping convention is used for JSON data. This convention
|
|
// (e.g. used for the X packet) says that if '#', '$', '*', or '}' are to occur in
|
|
// the payload, the character '}' (0x7d) is emitted, then the metacharacter is emitted
|
|
// xor'ed by 0x20. The '}' character occurs in every JSON payload at least once, and
|
|
// '}' ^ 0x20 happens to be ']' so the raw packet characters for a request will look
|
|
// like
|
|
//
|
|
// jThreadExtendedInfo:{"thread":612910}]
|
|
//
|
|
// on the wire.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// "QEnableCompression"
|
|
//
|
|
// BRIEF
|
|
// This packet enables compression of the packets that the debug stub sends to lldb.
|
|
// If the debug stub can support compression, it indictes this in the reply of the
|
|
// "qSupported" packet. e.g.
|
|
// LLDB SENDS: qSupported:xmlRegisters=i386,arm,mips
|
|
// STUB REPLIES: qXfer:features:read+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;DefaultCompressionMinSize=384
|
|
//
|
|
// If lldb knows how to use any of these compression algorithms, it can ask that this
|
|
// compression mode be enabled. It may optionally change the minimum packet size
|
|
// where compression is used. Typically small packets do not benefit from compression,
|
|
// as well as compression headers -- compression is most beneficial with larger packets.
|
|
//
|
|
// QEnableCompression:type:zlib-deflate;
|
|
// or
|
|
// QEnableCompression:type:zlib-deflate;minsize:512;
|
|
//
|
|
// The debug stub should reply with an uncompressed "OK" packet to indicate that the
|
|
// request was accepted. All further packets the stub sends will use this compression.
|
|
//
|
|
// Packets are compressed as the last step before they are sent from the stub, and
|
|
// decompressed as the first step after they are received. The packet format in compressed
|
|
// mode becomes one of two:
|
|
//
|
|
// $N<uncompressed payload>#00
|
|
//
|
|
// $C<size of uncompressed payload in base10>:<compressed payload>#00
|
|
//
|
|
// Where "#00" is the actual checksum value if noack mode is not enabled. The checksum
|
|
// value is for the "N<uncompressed payload>" or
|
|
// "C<size of uncompressed payload in base10>:<compressed payload>" bytes in the packet.
|
|
//
|
|
// The size of the uncompressed payload in base10 is provided because it will simplify
|
|
// decompression if the final buffer size needed is known ahead of time.
|
|
//
|
|
// Compression on low-latency connections is unlikely to be an improvement. Particularly
|
|
// when the debug stub and lldb are running on the same host. It should only be used
|
|
// for slow connections, and likely only for larger packets.
|
|
//
|
|
// Example compression algorithsm that may be used include
|
|
//
|
|
// zlib-deflate
|
|
// The raw DEFLATE format as described in IETF RFC 1951. With the ZLIB library, you
|
|
// can compress to this format with an initialization like
|
|
// deflateInit2 (&stream, 5, Z_DEFLATED, -15, 8, Z_DEFAULT_STRATEGY)
|
|
// and you can decompress with an initialization like
|
|
// inflateInit2 (&stream, -15)
|
|
//
|
|
// lz4
|
|
// https://en.wikipedia.org/wiki/LZ4_(compression_algorithm)
|
|
// https://github.com/Cyan4973/lz4
|
|
// The libcompression APIs on darwin systems call this COMPRESSION_LZ4_RAW.
|
|
//
|
|
// lzfse
|
|
// An Apple proprietary compression algorithm implemented in libcompression.
|
|
//
|
|
// lzma
|
|
// libcompression implements "LZMA level 6", the default compression for the
|
|
// open source LZMA implementation.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// "jGetLoadedDynamicLibrariesInfos"
|
|
//
|
|
// BRIEF
|
|
// This packet asks the remote debug stub to send the details about libraries
|
|
// being added/removed from the process as a performance optimization.
|
|
//
|
|
// There are three ways this packet can be used. All three return a dictionary of
|
|
// binary images formatted the same way.
|
|
//
|
|
// On OS X 10.11, iOS 9, tvOS 9, watchOS 2 and earlier, the packet is used like
|
|
// jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128}
|
|
// where the image_list_address is an array of {void* load_addr, void* mod_date, void* pathname}
|
|
// in the inferior process memory (and image_count is the number of elements in this array).
|
|
// lldb is using information from the dyld_all_image_infos structure to make these requests to
|
|
// debugserver. This use is not supported on macOS 10.12, iOS 10, tvOS 10, watchOS 3 or newer.
|
|
//
|
|
// On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer, there are two calls. One requests information
|
|
// on all shared libraries:
|
|
// jGetLoadedDynamicLibrariesInfos:{"fetch_all_solibs":true}
|
|
// And the second requests information about a list of shared libraries, given their load addresses:
|
|
// jGetLoadedDynamicLibrariesInfos:{"solib_addresses":[8382824135,3258302053,830202858503]}
|
|
//
|
|
// The second call is both a performance optimization (instead of having lldb read the mach-o header/load commands
|
|
// out of memory with generic read packets) but also adds additional information in the form of the
|
|
// filename of the shared libraries (which is not available in the mach-o header/load commands.)
|
|
//
|
|
// An example using the OS X 10.11 style call:
|
|
//
|
|
// LLDB SENDS: jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128}
|
|
// STUB REPLIES: ${"images":[{"load_address":4294967296,"mod_date":0,"pathname":"/tmp/a.out","uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF","mach_header":{"magic":4277009103,"cputype":16777223,"cpusubtype":18446744071562067971,"filetype":2},"segments":{"name":"__PAGEZERO","vmaddr":0,"vmsize":4294967296,"fileoff":0,"filesize":0,"maxprot":0},{"name":"__TEXT","vmaddr":4294967296,"vmsize":4096,"fileoff":0,"filesize":4096,"maxprot":7},{"name":"__LINKEDIT","vmaddr":4294971392,"vmsize":4096,"fileoff":4096,"filesize":152,"maxprot":7}}]}#00
|
|
//
|
|
// Or pretty-printed,
|
|
//
|
|
// STUB REPLIES: ${"images":
|
|
// [
|
|
// {"load_address":4294967296,
|
|
// "mod_date":0,
|
|
// "pathname":"/tmp/a.out",
|
|
// "uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF",
|
|
// "mach_header":
|
|
// {"magic":4277009103,
|
|
// "cputype":16777223,
|
|
// "cpusubtype":18446744071562067971,
|
|
// "filetype":2
|
|
// },
|
|
// "segments":
|
|
// [
|
|
// {"name":"__PAGEZERO",
|
|
// "vmaddr":0,
|
|
// "vmsize":4294967296,
|
|
// "fileoff":0,
|
|
// "filesize":0,
|
|
// "maxprot":0
|
|
// },
|
|
// {"name":"__TEXT",
|
|
// "vmaddr":4294967296,
|
|
// "vmsize":4096,
|
|
// "fileoff":0,
|
|
// "filesize":4096,
|
|
// "maxprot":7
|
|
// },
|
|
// {"name":"__LINKEDIT",
|
|
// "vmaddr":4294971392,
|
|
// "vmsize":4096,
|
|
// "fileoff":4096,
|
|
// "filesize":152,
|
|
// "maxprot":7
|
|
// }
|
|
// ]
|
|
// }
|
|
// ]
|
|
// }
|
|
//
|
|
//
|
|
// This is similar to the qXfer:libraries:read packet, and it could
|
|
// be argued that it should be merged into that packet. A separate
|
|
// packet was created primarily because lldb needs to specify the
|
|
// number of images to be read and the address from which the initial
|
|
// information is read. Also the XML DTD would need to be extended
|
|
// quite a bit to provide all the information that the DynamicLoaderMacOSX
|
|
// would need to work correctly on this platform.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// On OS X 10.11, iOS 9, tvOS 9, watchOS 2 and older: Low. If this packet is absent,
|
|
// lldb will read the Mach-O headers/load commands out of memory.
|
|
// On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer: High. If this packet is absent,
|
|
// lldb will not know anything about shared libraries in the inferior, or where the main
|
|
// executable loaded.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// "jThreadsInfo"
|
|
//
|
|
// BRIEF
|
|
// Ask for the server for thread stop information of all threads.
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. This is a performance optimization, which speeds up debugging by avoiding
|
|
// multiple round-trips for retrieving thread information. The information from this
|
|
// packet can be retrieved using a combination of qThreadStopInfo and m packets.
|
|
//----------------------------------------------------------------------
|
|
|
|
The data in this packet is very similar to the stop reply packets, but is packaged in
|
|
JSON and uses JSON arrays where applicable. The JSON output looks like:
|
|
[
|
|
{ "tid":1580681,
|
|
"metype":6,
|
|
"medata":[2,0],
|
|
"reason":"exception",
|
|
"qaddr":140735118423168,
|
|
"registers": {
|
|
"0":"8000000000000000",
|
|
"1":"0000000000000000",
|
|
"2":"20fabf5fff7f0000",
|
|
"3":"e8f8bf5fff7f0000",
|
|
"4":"0100000000000000",
|
|
"5":"d8f8bf5fff7f0000",
|
|
"6":"b0f8bf5fff7f0000",
|
|
"7":"20f4bf5fff7f0000",
|
|
"8":"8000000000000000",
|
|
"9":"61a8db78a61500db",
|
|
"10":"3200000000000000",
|
|
"11":"4602000000000000",
|
|
"12":"0000000000000000",
|
|
"13":"0000000000000000",
|
|
"14":"0000000000000000",
|
|
"15":"0000000000000000",
|
|
"16":"960b000001000000",
|
|
"17":"0202000000000000",
|
|
"18":"2b00000000000000",
|
|
"19":"0000000000000000",
|
|
"20":"0000000000000000"
|
|
},
|
|
"memory":[
|
|
{"address":140734799804592,"bytes":"c8f8bf5fff7f0000c9a59e8cff7f0000"},
|
|
{"address":140734799804616,"bytes":"00000000000000000100000000000000"}
|
|
]
|
|
}
|
|
]
|
|
|
|
It contains an array of dictionaries with all of the key value pairs that are
|
|
normally in the stop reply packet, including the expedited registers. The registers are
|
|
passed as hex-encoded JSON string in debuggee-endian byte order. Note that the register
|
|
numbers are decimal numbers, unlike the stop-reply packet, where they are written in
|
|
hex. The packet also contains expedited memory in the "memory" key. This allows the
|
|
server to expedite memory that the client is likely to use (e.g., areas around the
|
|
stack pointer, which are needed for computing backtraces) and it reduces the packet
|
|
count.
|
|
|
|
On macOS with debugserver, we expedite the frame pointer backchain for a thread
|
|
(up to 256 entries) by reading 2 pointers worth of bytes at the frame pointer (for
|
|
the previous FP and PC), and follow the backchain. Most backtraces on macOS and
|
|
iOS now don't require us to read any memory!
|
|
|
|
//----------------------------------------------------------------------
|
|
// "jGetSharedCacheInfo"
|
|
//
|
|
// BRIEF
|
|
// This packet asks the remote debug stub to send the details about the inferior's
|
|
// shared cache. The shared cache is a collection of common libraries/frameworks that
|
|
// are mapped into every process at the same address on Darwin systems, and can be
|
|
// identified by a load address and UUID.
|
|
//
|
|
//
|
|
// LLDB SENDS: jGetSharedCacheInfo:{}
|
|
// STUB REPLIES: ${"shared_cache_base_address":140735683125248,"shared_cache_uuid":"DDB8D70C-C9A2-3561-B2C8-BE48A4F33F96","no_shared_cache":false,"shared_cache_private_cache":false]}#00
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. When both lldb and the inferior process are running on the same computer, and lldb
|
|
// and the inferior process have the same shared cache, lldb may (as an optimization) read
|
|
// the shared cache out of its own memory instead of using gdb-remote read packets to read
|
|
// them from the inferior process.
|
|
//----------------------------------------------------------------------
|
|
|
|
//----------------------------------------------------------------------
|
|
// "qQueryGDBServer"
|
|
//
|
|
// BRIEF
|
|
// Ask the platform for the list of gdbservers we have to connect
|
|
//
|
|
// PRIORITY TO IMPLEMENT
|
|
// Low. The packet is required to support connecting to gdbserver started
|
|
// by the platform instance automatically.
|
|
//----------------------------------------------------------------------
|
|
|
|
If the remote platform automatically started one or more gdbserver instance (without
|
|
lldb asking it) then it have to return the list of port number or socket name for
|
|
each of them what can be used by lldb to connect to those instances.
|
|
|
|
The data in this packet is a JSON array of JSON objects with the following keys:
|
|
"port": <the port number to connect> (optional)
|
|
"socket_name": <the name of the socket to connect> (optional)
|
|
|
|
Example packet:
|
|
[
|
|
{ "port": 1234 },
|
|
{ "port": 5432 },
|
|
{ "socket_name": "foo" }
|
|
]
|