[Lldb-commits] [lldb] [lldb][Docs] Make formatting regular in lldb-gdb-remote.txt (PR #89587)
via lldb-commits
lldb-commits at lists.llvm.org
Mon Apr 22 03:26:57 PDT 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: David Spickett (DavidSpickett)
<details>
<summary>Changes</summary>
If someone (aka me) wanted to convert this into another format (aka Markdown), these changes mean you can more easily script that conversion.
---
Patch is 118.87 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/89587.diff
1 Files Affected:
- (modified) lldb/docs/lldb-gdb-remote.txt (+960-933)
``````````diff
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
+// ...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/89587
More information about the lldb-commits
mailing list