llvm-project/lldb/docs/lldb-gdb-remote.txt

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 mimize 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.
//
// 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.

//----------------------------------------------------------------------
// "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 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 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)

offset      The offset within the "g" and "G" packet of the register data for
            this register

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 regiter 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). 

            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. 

            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)

//----------------------------------------------------------------------
// "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
cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged
ostype: is a string the represents the OS being debugged (darwin, lunix, 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 on the debug target

//----------------------------------------------------------------------
// "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 univeral 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
cpusubtype: the Mach-O CPU subtype of the process
ostype: is a string the represents the OS being debugged (darwin, lunix, 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
binaires that run in user land this is the address of the "all_image_infos"
stucture 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.

//----------------------------------------------------------------------
// 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 nujber 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 regsiters 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 contol 
//  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 consucutive 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 woudn'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.
//----------------------------------------------------------------------