[Lldb-commits] [lldb] [lldb][Docs] Make formatting regular in lldb-gdb-remote.txt (PR #89587)
David Spickett via lldb-commits
lldb-commits at lists.llvm.org
Mon Apr 22 03:26:27 PDT 2024
https://github.com/DavidSpickett created https://github.com/llvm/llvm-project/pull/89587
If someone (aka me) wanted to convert this into another format (aka Markdown), these changes mean you can more easily script that conversion.
>From fa0c14200772a3644aa009c31ab44ce23778fb64 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 19 Apr 2024 14:53:42 +0100
Subject: [PATCH] [lldb][Docs] Make formatting regular in lldb-gdb-remote.txt
If someone (aka me) wanted to convert this into another format
(aka Markdown), these changes mean you can more easily script
that conversion.
---
lldb/docs/lldb-gdb-remote.txt | 1893 +++++++++++++++++----------------
1 file changed, 960 insertions(+), 933 deletions(-)
diff --git a/lldb/docs/lldb-gdb-remote.txt b/lldb/docs/lldb-gdb-remote.txt
index 6c29de61daba7e..15e32153354962 100644
--- a/lldb/docs/lldb-gdb-remote.txt
+++ b/lldb/docs/lldb-gdb-remote.txt
@@ -25,18 +25,20 @@ added above and beyond the standard GDB remote protocol packets.
// 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.
+//
+// DESCRIPTION
+// 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: +
//----------------------------------------------------------------------
-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: +
//----------------------------------------------------------------------
// "QSupported"
@@ -46,38 +48,39 @@ send packet: +
//
// PRIORITY TO IMPLEMENT
// Optional.
+//
+// DESCRIPTION
+// QSupported is a standard GDB Remote Serial Protocol packet, but
+// there are several additions to the response that lldb can parse.
+// They are not all listed here.
+//
+// An example exchange:
+//
+// send packet: qSupported:xmlRegisters=i386,arm,mips,arc;multiprocess+;fork-events+;vfork-events+
+//
+// read packet: qXfer:features:read+;PacketSize=20000;qEcho+;native-signals+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;SupportedWatchpointTypes=aarch64-mask,aarch64-bas;
+//
+// In the example above, three lldb extensions are shown:
+//
+// PacketSize=20000
+// The base 16 maximum packet size that the stub can handle.
+// SupportedCompressions=<item,item,...>
+// A list of compression types that the stub can use to compress packets
+// when the QEnableCompression packet is used to request one of them.
+// SupportedWatchpointTypes=<item,item,...>
+// A list of watchpoint types that this stub can manage.
+// Currently defined names are:
+// x86_64 64-bit x86-64 watchpoints
+// (1, 2, 4, 8 byte watchpoints aligned to those amounts)
+// aarch64-bas AArch64 Byte Address Select watchpoints
+// (any number of contiguous bytes within a doubleword)
+// aarch64-mask AArch64 MASK watchpoints
+// (any power-of-2 region of memory from 8 to 2GB, aligned)
+// If nothing is specified, lldb will default to sending power-of-2
+// watchpoints, up to a pointer size, `sizeof(void*)`, a reasonable
+// baseline assumption.
//----------------------------------------------------------------------
-QSupported is a standard GDB Remote Serial Protocol packet, but
-there are several additions to the response that lldb can parse.
-They are not all listed here.
-
-An example exchange:
-
-send packet: qSupported:xmlRegisters=i386,arm,mips,arc;multiprocess+;fork-events+;vfork-events+
-
-read packet: qXfer:features:read+;PacketSize=20000;qEcho+;native-signals+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;SupportedWatchpointTypes=aarch64-mask,aarch64-bas;
-
-In the example above, three lldb extensions are shown:
-
- PacketSize=20000
- The base 16 maximum packet size that the stub can handle.
- SupportedCompressions=<item,item,...>
- A list of compression types that the stub can use to compress packets
- when the QEnableCompression packet is used to request one of them.
- SupportedWatchpointTypes=<item,item,...>
- A list of watchpoint types that this stub can manage.
- Currently defined names are:
- x86_64 64-bit x86-64 watchpoints
- (1, 2, 4, 8 byte watchpoints aligned to those amounts)
- aarch64-bas AArch64 Byte Address Select watchpoints
- (any number of contiguous bytes within a doubleword)
- aarch64-mask AArch64 MASK watchpoints
- (any power-of-2 region of memory from 8 to 2GB, aligned)
- If nothing is specified, lldb will default to sending power-of-2
- watchpoints, up to a pointer size, `sizeof(void*)`, a reasonable
- baseline assumption.
-
//----------------------------------------------------------------------
// "A" - launch args packet
//
@@ -88,27 +91,28 @@ In the example above, three lldb extensions are shown:
// 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.
+//
+// DESCRIPTION
+// 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.
//----------------------------------------------------------------------
-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"
//
@@ -116,28 +120,29 @@ debugging.
// 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.
+// 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.
+//
+// DESCRIPTION
+// 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.
//----------------------------------------------------------------------
-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)"
//
@@ -145,24 +150,25 @@ This packet can be sent one or more times _prior_ to sending a "A" packet.
// 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.
+// 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.
+//
+// DESCRIPTION
+// 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.
//----------------------------------------------------------------------
-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"
//
@@ -184,11 +190,12 @@ This packet can be sent one or more times _prior_ to sending a "A" packet.
// PRIORITY TO IMPLEMENT
// Low. Only needed if the remote target wants to provide strings that
// are human readable along with an error code.
+//
+// EXAMPLE
+// send packet: $QEnableErrorStrings
+// read packet: $OK#00
//----------------------------------------------------------------------
-send packet: $QEnableErrorStrings
-read packet: $OK#00
-
//----------------------------------------------------------------------
// "QSetSTDIN:<ascii-hex-path>"
// "QSetSTDOUT:<ascii-hex-path>"
@@ -202,17 +209,18 @@ read packet: $OK#00
// 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.
+//
+// DESCRIPTION
+// 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.
//----------------------------------------------------------------------
-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>"
//
@@ -223,14 +231,15 @@ These packets must be sent _prior_ to sending a "A" packet.
// 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.
+//
+// DESCRIPTION
+// Or specify the working directory:
+//
+// QSetWorkingDir:<ascii-hex-path>
+//
+// This packet must be sent _prior_ to sending a "A" packet.
//----------------------------------------------------------------------
-Or specify the working directory:
-
-QSetWorkingDir:<ascii-hex-path>
-
-This packet must be sent _prior_ to sending a "A" packet.
-
//----------------------------------------------------------------------
// "QSetDisableASLR:<bool>"
//
@@ -242,18 +251,19 @@ This packet must be sent _prior_ to sending a "A" packet.
// 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).
+//
+// DESCRIPTION
+// 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.
//----------------------------------------------------------------------
-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
//
@@ -267,11 +277,12 @@ This packet must be sent _prior_ to sending a "A" packet.
// 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.
+//
+// EXAMPLE
+// send packet: QListThreadsInStopReply
+// read packet: OK
//----------------------------------------------------------------------
-send packet: QListThreadsInStopReply
-read packet: OK
-
//----------------------------------------------------------------------
// jLLDBTraceSupported
//
@@ -295,11 +306,12 @@ read packet: OK
// This packet is used by Trace plug-ins (see lldb_private::Trace.h) to
// do live tracing. Specifically, the name of the plug-in should match the name
// of the tracing technology returned by this packet.
+//
+// EXAMPLE
+// send packet: jLLDBTraceSupported
+// read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAAA
//----------------------------------------------------------------------
-send packet: jLLDBTraceSupported
-read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAAA
-
//----------------------------------------------------------------------
// jLLDBTraceStart
//
@@ -430,16 +442,17 @@ read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAA
// unaffected and the threads not traced twice.
// - If "thread tracing" is attempted on a thread already being traced with
// either "thread tracing" or "process tracing", it fails.
+//
+// EXAMPLES
+// Process tracing:
+// send packet: jLLDBTraceStart:{"type":<type>,...other params}]
+// read packet: OK/E<error code>;AAAAAAAAA
+//
+// Thread tracing:
+// send packet: jLLDBTraceStart:{"type":<type>,"tids":<tids>,...other params}]
+// read packet: OK/E<error code>;AAAAAAAAA
//----------------------------------------------------------------------
-Process tracing:
-send packet: jLLDBTraceStart:{"type":<type>,...other params}]
-read packet: OK/E<error code>;AAAAAAAAA
-
-Thread tracing:
-send packet: jLLDBTraceStart:{"type":<type>,"tids":<tids>,...other params}]
-read packet: OK/E<error code>;AAAAAAAAA
-
//----------------------------------------------------------------------
// jLLDBTraceStop
//
@@ -473,16 +486,17 @@ read packet: OK/E<error code>;AAAAAAAAA
//
// INTEL PT
// Stopping a specific thread trace started with "process tracing" is allowed.
+//
+// EXAMPLES
+// Process trace stopping:
+// send packet: jLLDBTraceStop:{"type":<type>}]
+// read packet: OK/E<error code>;AAAAAAAAA
+//
+// Thread trace stopping:
+// send packet: jLLDBTraceStop:{"type":<type>,"tids":<tids>}]
+// read packet: OK/E<error code>;AAAAAAAAA
//----------------------------------------------------------------------
-Process trace stopping:
-send packet: jLLDBTraceStop:{"type":<type>}]
-read packet: OK/E<error code>;AAAAAAAAA
-
-Thread trace stopping:
-send packet: jLLDBTraceStop:{"type":<type>,"tids":<tids>}]
-read packet: OK/E<error code>;AAAAAAAAA
-
//----------------------------------------------------------------------
// jLLDBTraceGetState
//
@@ -567,7 +581,7 @@ read packet: OK/E<error code>;AAAAAAAAA
// See the documentation of time_zero in
// https://man7.org/linux/man-pages/man2/perf_event_open.2.html for more information about
// the calculation and the meaning of the values in the schema below.
-///
+//
// Schema for this field:
//
// "tscPerfZeroConversion": {
@@ -575,11 +589,12 @@ read packet: OK/E<error code>;AAAAAAAAA
// "timeShift": <decimal integer>,
// "timeZero": <decimal integer>,
// }
+//
+// EXAMPLE
+// send packet: jLLDBTraceGetState:{"type":<type>}]
+// read packet: {...object}/E<error code>;AAAAAAAAA
//----------------------------------------------------------------------
-send packet: jLLDBTraceGetState:{"type":<type>}]
-read packet: {...object}/E<error code>;AAAAAAAAA
-
//----------------------------------------------------------------------
// jLLDBTraceGetBinaryData
//
@@ -602,11 +617,12 @@ read packet: {...object}/E<error code>;AAAAAAAAA
// "tid"?: <Optional decimal>,
// Tid in decimal if the data belongs to a thread.
// }
+//
+// EXAMPLE
+// send packet: jLLDBTraceGetBinaryData:{"type":<type>,"kind":<query>,"tid":<tid>,"offset":<offset>,"size":<size>}]
+// read packet: <binary data>/E<error code>;AAAAAAAAA
//----------------------------------------------------------------------
-send packet: jLLDBTraceGetBinaryData:{"type":<type>,"kind":<query>,"tid":<tid>,"offset":<offset>,"size":<size>}]
-read packet: <binary data>/E<error code>;AAAAAAAAA
-
//----------------------------------------------------------------------
// "qRegisterInfo<hex-reg-id>"
//
@@ -620,7 +636,7 @@ read packet: <binary data>/E<error code>;AAAAAAAAA
// depending on the actual CPU type that is used.
//
// NB: qRegisterInfo is deprecated in favor of the standard gdb remote
-// serial protocol register description method,
+// serial protocol register description method,
// "qXfer:features:read:target.xml".
// If qXfer:features:read:target.xml is supported, qRegisterInfo does
// not need to be implemented. The target.xml format is used by most
@@ -628,278 +644,279 @@ read packet: <binary data>/E<error code>;AAAAAAAAA
// qRegisterInfo requires one packet per register and can have undesirable
// performance costs at the start of a debug session, whereas target.xml
// may be able to describe all registers in a single packet.
+//
+// DESCRIPTION
+// With LLDB, for register information, remote GDB servers can add
+// support for the "qRegisterInfoN" packet where "N" is a zero based
+// base 16 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)
+// flags (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.
//----------------------------------------------------------------------
-With LLDB, for register information, remote GDB servers can add
-support for the "qRegisterInfoN" packet where "N" is a zero based
-base 16 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)
- flags (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"
//
@@ -910,25 +927,25 @@ invalidate-regs
// 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
+// DESCRIPTION
+// 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"
@@ -940,16 +957,16 @@ drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp
// 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
+// DESCRIPTION
+// 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"
@@ -961,16 +978,16 @@ Reply:
// 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
+// DESCRIPTION
+// 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"
@@ -982,53 +999,54 @@ Reply:
// 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.
+//
+// DESCRIPTION
+// 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)
+// vm-page-size: optional, specifies the target system VM page size, base 10.
+// Needed for the "dirty-pages:" list in the qMemoryRegionInfo
+// packet, where a list of dirty pages is sent from the remote
+// stub. This page size tells lldb how large each dirty page is.
+// addressing_bits: optional, specifies how many bits in addresses are
+// significant for addressing, base 10. If bits 38..0
+// in a 64-bit pointer are significant for addressing,
+// then the value is 39. This is needed on e.g. AArch64
+// v8.3 ABIs that use pointer authentication, so lldb
+// knows which bits to clear/set to get the actual
+// addresses.
+// low_mem_addressing_bits: optional, specifies how many bits in
+// addresses in low memory are significant for addressing, base 10.
+// AArch64 can have different page table setups for low and high
+// memory, and therefore a different number of bits used for addressing.
+// high_mem_addressing_bits: optional, specifies how many bits in
+// addresses in high memory are significant for addressing, base 10.
+// AArch64 can have different page table setups for low and high
+// memory, and therefore a different number of bits used for addressing.
//----------------------------------------------------------------------
-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)
-vm-page-size: optional, specifies the target system VM page size, base 10.
- Needed for the "dirty-pages:" list in the qMemoryRegionInfo
- packet, where a list of dirty pages is sent from the remote
- stub. This page size tells lldb how large each dirty page is.
-addressing_bits: optional, specifies how many bits in addresses are
- significant for addressing, base 10. If bits 38..0
- in a 64-bit pointer are significant for addressing,
- then the value is 39. This is needed on e.g. AArch64
- v8.3 ABIs that use pointer authentication, so lldb
- knows which bits to clear/set to get the actual
- addresses.
-low_mem_addressing_bits: optional, specifies how many bits in
- addresses in low memory are significant for addressing, base 10.
- AArch64 can have different page table setups for low and high
- memory, and therefore a different number of bits used for addressing.
-high_mem_addressing_bits: optional, specifies how many bits in
- addresses in high memory are significant for addressing, base 10.
- AArch64 can have different page table setups for low and high
- memory, and therefore a different number of bits used for addressing.
-
//----------------------------------------------------------------------
// "qGDBServerVersion"
//
@@ -1040,42 +1058,43 @@ high_mem_addressing_bits: optional, specifies how many bits in
// 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.
+//
+// DESCRIPTION
+// 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
//----------------------------------------------------------------------
-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"
//
@@ -1092,43 +1111,44 @@ Suggested key names:
// process to know what you're working with.
//
// All numeric fields return base 16 numbers without any "0x" prefix.
+//
+// DESCRIPTION
+// 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
+//
+// main-binary-uuid: is the UUID of a firmware type binary that the gdb stub knows about
+// main-binary-address: is the load address of the firmware type binary
+// main-binary-slide: is the slide of the firmware type binary, if address isn't known
+//
+// binary-addresses: A comma-separated list of binary load addresses base 16.
+// lldb will parse the binaries in memory to get UUIDs, then
+// try to find the binaries & debug info by UUID. Intended for
+// use with a small number of firmware type binaries where the
+// search for binary/debug info may be expensive.
//----------------------------------------------------------------------
-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
-
-main-binary-uuid: is the UUID of a firmware type binary that the gdb stub knows about
-main-binary-address: is the load address of the firmware type binary
-main-binary-slide: is the slide of the firmware type binary, if address isn't known
-
-binary-addresses: A comma-separated list of binary load addresses base 16.
- lldb will parse the binaries in memory to get UUIDs, then
- try to find the binaries & debug info by UUID. Intended for
- use with a small number of firmware type binaries where the
- search for binary/debug info may be expensive.
-
//----------------------------------------------------------------------
// "qShlibInfoAddr"
//
@@ -1145,20 +1165,19 @@ binary-addresses: A comma-separated list of binary load addresses base 16.
//
// Low if you have a debug target where all object and symbol files
// contain static load addresses.
+//
+// DESCRIPTION
+// 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
//----------------------------------------------------------------------
-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>"
//
@@ -1173,16 +1192,17 @@ read packet: $7fff5fc40040#00
// threads (live system debug) / cores (JTAG) in your program have
// stopped and allows LLDB to display and control your program
// correctly.
+//
+// DESCRIPTION
+// 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.
//----------------------------------------------------------------------
-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"
//
@@ -1198,43 +1218,44 @@ to implement better multi-threaded debugging support.
// 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.
+//
+// DESCRIPTION
+// 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.
//----------------------------------------------------------------------
-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>"
//
@@ -1247,27 +1268,28 @@ allocate memory so we can run JITed code.
// code also needs data which is also allocated and tracked.
//
// Low if you don't support running JIT'ed code.
+//
+// DESCRIPTION
+// 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.
//----------------------------------------------------------------------
-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>"
//
@@ -1280,13 +1302,14 @@ is just the address of the newly allocated memory as raw big endian hex bytes.
// code also needs data which is also allocated and tracked.
//
// Low if you don't support running JIT'ed code.
+//
+// DESCRIPTION
+// 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.
//----------------------------------------------------------------------
-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>"
//
@@ -1301,119 +1324,122 @@ not supported.
// 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.
+//
+// DESCRIPTION
+// 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.
+//
+// flags:<flags-string>; // where <flags-string> is a space separated string
+// // of flag names. Currently the only supported flag
+// // is "mt" for AArch64 memory tagging. lldb will
+// // ignore any other flags in this field.
+//
+// type:[<type>][,<type>]; // memory types that apply to this region, e.g.
+// // "stack" for stack memory.
+//
+// error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is
+// // a hex encoded string value that
+// // contains an error string
+//
+// dirty-pages:[<hexaddr>][,<hexaddr]; // A list of memory pages within this
+// // region that are "dirty" -- they have been modified.
+// // Page addresses are in base 16. The size of a page can
+// // be found from the qHostInfo's page-size key-value.
+// //
+// // If the stub supports identifying dirty pages within a
+// // memory region, this key should always be present for all
+// // qMemoryRegionInfo replies. This key with no pages
+// // listed ("dirty-pages:;") indicates no dirty pages in
+// // this memory region. The *absence* of this key means
+// // that this stub cannot determine dirty pages.
+//
+// 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.
//----------------------------------------------------------------------
-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.
-
- flags:<flags-string>; // where <flags-string> is a space separated string
- // of flag names. Currently the only supported flag
- // is "mt" for AArch64 memory tagging. lldb will
- // ignore any other flags in this field.
-
- type:[<type>][,<type>]; // memory types that apply to this region, e.g.
- // "stack" for stack memory.
-
- error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is
- // a hex encoded string value that
- // contains an error string
-
- dirty-pages:[<hexaddr>][,<hexaddr]; // A list of memory pages within this
- // region that are "dirty" -- they have been modified.
- // Page addresses are in base 16. The size of a page can
- // be found from the qHostInfo's page-size key-value.
- //
- // If the stub supports identifying dirty pages within a
- // memory region, this key should always be present for all
- // qMemoryRegionInfo replies. This key with no pages
- // listed ("dirty-pages:;") indicates no dirty pages in
- // this memory region. The *absence* of this key means
- // that this stub cannot determine dirty pages.
-
-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'.
+// BRIEF
+// Like the 'm' (read) and 'M' (write) packets, this is a partner to the
+// 'X' (write binary data) packet, 'x'.
//
-// It is called like
+// It is called like
//
-// xADDRESS,LENGTH
+// xADDRESS,LENGTH
//
-// where both ADDRESS and LENGTH are big-endian base 16 values.
+// where both ADDRESS and LENGTH are big-endian base 16 values.
//
-// To test if this packet is available, send a addr/len of 0:
+// To test if this packet is available, send a addr/len of 0:
//
-// x0,0
+// x0,0
//
-// and you will get an "OK" response.
+// 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.
+// 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
+// A typical use to read 512 bytes at 0x1000 would look like
//
-// x0x1000,0x200
+// 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 "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.
+// The length of the payload is not provided. A reliable, 8-bit clean,
+// transport layer is assumed.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
-// Detach and stay stopped:
+// 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:
+// DESCRIPTION
+// 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:
+// 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:
+// 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
+// D1
//
-// In any case, if we want the normal detach behavior we will just send:
+// In any case, if we want the normal detach behavior we will just send:
//
-// D
+// D
//----------------------------------------------------------------------
//----------------------------------------------------------------------
@@ -1573,7 +1599,6 @@ for this region.
// packet.
//
// LLDB EXTENSIONS
-//
// We have extended the "T" packet to be able to also understand the
// following keys and values:
//
@@ -1609,9 +1634,9 @@ for this region.
// "signal" stopped due to an actual unix signal, not
// just the debugger using a unix signal to keep
// the GDB remote client happy.
-// "watchpoint". Can be used with of the
+// "watchpoint". Can be used with of the
// "watch"/"rwatch"/"awatch" key value pairs.
-// Or can be used *instead* of those keys,
+// Or can be used *instead* of those keys,
// with the specially formatted "description" field.
// "exception" an exception stop reason. Use with
// the "description" key/value pair to describe the
@@ -1626,7 +1651,7 @@ for this region.
// encoded string with between one and three base 10 numbers,
// space separated. The three numbers are
// 1. watchpoint address. This address should always be within
-// a memory region lldb has a watchpoint on.
+// a memory region lldb has a watchpoint on.
// On architectures where the actual reported hit address may
// be outside the watchpoint that was triggered, the remote
// stub should determine which watchpoint was triggered and
@@ -1634,32 +1659,32 @@ for this region.
// 2. watchpoint hardware register index number.
// 3. actual watchpoint trap address, which may be outside
// the range of any watched region of memory. On MIPS, an addr
-// outside a watched range means lldb should disable the wp,
+// outside a watched range means lldb should disable the wp,
// step, re-enable the wp and continue silently.
//
-// On MIPS, the low 3 bits are masked so if a watchpoint is on
-// 0x1004, a 2-byte write to 0x1000 will trigger the watchpoint
-// (a false positive hit), and lldb needs to disable the
+// On MIPS, the low 3 bits are masked so if a watchpoint is on
+// 0x1004, a 2-byte write to 0x1000 will trigger the watchpoint
+// (a false positive hit), and lldb needs to disable the
// watchpoint at 0x1004, inst-step, then re-enable the watchpoint
-// and not make this a user visible event. The description here
+// and not make this a user visible event. The description here
// would be "0x1004 0 0x1000". lldb needs a known watchpoint address
// in the first field, so it can disable it & step.
//
-// On AArch64 we have a related issue, where you watch 4 bytes at
-// 0x1004, an instruction does an 8-byte write starting at
-// 0x1000 (a true watchpoint hit) and the hardware may report the
-// trap address as 0x1000 - before the watched memory region -
-// with the write extending into the watched region. This can
-// be reported as "0x1004 0 0x1000". lldb will use 0x1004 to
-// identify which Watchpoint was triggered, and can report 0x1000
-// to the user. The behavior of silently stepping over the
-// watchpoint, with an 3rd field addr outside the range, is
+// On AArch64 we have a related issue, where you watch 4 bytes at
+// 0x1004, an instruction does an 8-byte write starting at
+// 0x1000 (a true watchpoint hit) and the hardware may report the
+// trap address as 0x1000 - before the watched memory region -
+// with the write extending into the watched region. This can
+// be reported as "0x1004 0 0x1000". lldb will use 0x1004 to
+// identify which Watchpoint was triggered, and can report 0x1000
+// to the user. The behavior of silently stepping over the
+// watchpoint, with an 3rd field addr outside the range, is
// restricted to MIPS.
// There may be false-positive watchpoint hits on AArch64 as well,
-// in the SVE Streaming Mode, but that is less common (see ESR
+// in the SVE Streaming Mode, but that is less common (see ESR
// register flag "WPF", "Watchpoint might be False-Positive") and
// not currently handled by lldb.
-//
+//
// "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
@@ -1686,37 +1711,37 @@ for this region.
// Example:
// thread-pcs:dec14,2cf872b0,2cf8681c,2d02d68c,2cf716a8;
//
-// "addressing_bits" unsigned optional Specifies how many bits in addresses
-// are significant for addressing, base
-// 10. If bits 38..0 in a 64-bit
-// pointer are significant for
-// addressing, then the value is 39.
+// "addressing_bits" unsigned optional Specifies how many bits in addresses
+// are significant for addressing, base
+// 10. If bits 38..0 in a 64-bit
+// pointer are significant for
+// addressing, then the value is 39.
// This is needed on e.g. AArch64
-// v8.3 ABIs that use pointer
+// v8.3 ABIs that use pointer
// authentication in the high bits.
// This value is normally sent in the
// qHostInfo packet response, and if the
// value cannot change during the process
-// lifetime, it does not need to be
+// lifetime, it does not need to be
// duplicated here in the stop packet.
// For a firmware environment with early
// start code that may be changing the
// page table setup, a dynamically set
// value may be needed.
-// "low_mem_addressing_bits" unsigned optional, specifies how many bits in
-// addresses in low memory are significant
-// for addressing, base 10. AArch64 can
-// have different page table setups for low
-// and high memory, and therefore a different
+// "low_mem_addressing_bits" unsigned optional, specifies how many bits in
+// addresses in low memory are significant
+// for addressing, base 10. AArch64 can
+// have different page table setups for low
+// and high memory, and therefore a different
// number of bits used for addressing.
-// "high_mem_addressing_bits" unsigned optional, specifies how many bits in
-// addresses in high memory are significant
-// for addressing, base 10. AArch64 can have
-// different page table setups for low and
-// high memory, and therefore a different
+// "high_mem_addressing_bits" unsigned optional, specifies how many bits in
+// addresses in high memory are significant
+// for addressing, base 10. AArch64 can have
+// different page table setups for low and
+// high memory, and therefore a different
// number of bits used for addressing.
//
-// BEST PRACTICES:
+// 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
@@ -1753,11 +1778,10 @@ for this region.
//----------------------------------------------------------------------
-//----------------------------------------------------------------------
-// PLATFORM EXTENSION - for use as a GDB remote platform
//----------------------------------------------------------------------
// "qfProcessInfo"
// "qsProcessInfo"
+// (Platform Extension)
//
// BRIEF
// Get the first process info (qfProcessInfo) or subsequent process
@@ -1792,25 +1816,23 @@ for this region.
// separated by the character '-', where each argument is
// hex-encoded. It includes argv[0].
//
-// 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.
+// 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
+// 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"
+// (Platform Extension)
//
// BRIEF
// Have the remote platform launch a GDB server.
@@ -1827,26 +1849,25 @@ for this region.
// "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.
+// DESCRIPTION
+// 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
+// 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 "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.
+// 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"
+// (Platform Extension)
//
// BRIEF
// Have the remote platform get detailed information on a process by
@@ -1855,25 +1876,26 @@ for this region.
// 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.
+// DESCRIPTION
+// 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:
+// 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")
+// 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
+// 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
//----------------------------------------------------------------------
//----------------------------------------------------------------------
@@ -1944,50 +1966,51 @@ for this region.
// 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:
+// DESCRIPTION
+// 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}
+// jThreadExtendedInfo:{"thread":612910}
//
-// Because this is a JSON string, the thread number is provided in base 10.
-// 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:
+// Because this is a JSON string, the thread number is provided in base 10.
+// 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}
+// 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:
+// 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":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.
+// 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.
+// 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
+// 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}]
+// jThreadExtendedInfo:{"thread":612910}]
//
-// on the wire.
+// on the wire.
//----------------------------------------------------------------------
//----------------------------------------------------------------------
@@ -2001,7 +2024,7 @@ for this region.
// STUB REPLIES: qXfer:features:read+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;
//
// If lldb knows how to use any of these compression algorithms, it can ask that this
-// compression mode be enabled.
+// compression mode be enabled.
//
// QEnableCompression:type:zlib-deflate;
//
@@ -2066,7 +2089,7 @@ for this region.
// jGetLoadedDynamicLibrariesInfos:{"fetch_all_solibs":true}
// with an optional `"report_load_commands":false` which can be added, asking
// that only the dyld SPI information (load addresses, filenames) be returned.
-// The default behavior is that debugserver scans the mach-o header and load
+// The default behavior is that debugserver scans the mach-o header and load
// commands of each binary, and returns it in the JSON reply.
//
// And the second requests information about a list of shared libraries, given their load addresses:
@@ -2124,13 +2147,14 @@ for this region.
// }
//
//
-// 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.
+// DESCRIPTION
+// 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,
@@ -2150,60 +2174,61 @@ for this region.
// 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.
+//
+// DESCRIPTION
+// 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!
//----------------------------------------------------------------------
-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"
//
@@ -2233,23 +2258,24 @@ iOS now don't require us to read any memory!
// PRIORITY TO IMPLEMENT
// Low. The packet is required to support connecting to gdbserver started
// by the platform instance automatically.
+//
+// DESCRIPTION
+// 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" }
+// ]
//----------------------------------------------------------------------
-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" }
-]
-
//----------------------------------------------------------------------
// "QSetDetachOnError"
//
@@ -2261,18 +2287,19 @@ Example packet:
// PRIORITY TO IMPLEMENT
// Low. Only required if the target wants to keep the inferior process alive
// when the communication channel goes down.
+//
+// DESCRIPTION
+// The data in this packet is a single a character, which should be '0' if the
+// inferior process should be killed, or '1' if the server should remove all
+// breakpoints and detach from the inferior.
//----------------------------------------------------------------------
-The data in this packet is a single a character, which should be '0' if the
-inferior process should be killed, or '1' if the server should remove all
-breakpoints and detach from the inferior.
-
//----------------------------------------------------------------------
// "jGetDyldProcessState"
//
// BRIEF
// This packet fetches the process launch state, as reported by libdyld on
-// Darwin systems, most importantly to indicate when the system libraries
+// Darwin systems, most importantly to indicate when the system libraries
// have initialized sufficiently to safely call utility functions.
//
//
@@ -2281,6 +2308,6 @@ breakpoints and detach from the inferior.
//
// PRIORITY TO IMPLEMENT
// Low. This packet is needed to prevent lldb's utility functions for
-// scanning the Objective-C class list from running very early in
+// scanning the Objective-C class list from running very early in
// process startup.
//----------------------------------------------------------------------
More information about the lldb-commits
mailing list