[lldb][Docs] Make formatting regular in lldb-gdb-remote.txt #89587
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
If someone (aka me) wanted to convert this into another format (aka Markdown), these changes mean you can more easily script that conversion.
|
@llvm/pr-subscribers-lldb Author: David Spickett (DavidSpickett) ChangesIf 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:
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]
|
|
Subsequent PRs will build on this:
So that we:
But my stacked-pr-foo is weak, so doing this one at a time for simplicity. |
|
+1 on making this available on the website. Unless the goal is to preserve both the textual and the markdown format, I'm not sure there's a whole lot of value in landing this. Maybe we can avoid churn and jump straight ahead to the markdown version? |
jasonmolenda
approved these changes
Apr 22, 2024
|
I'll include this as a commit in a larger PR. |
|
Opened #89718 instead, which has all the conversion steps in it. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
If someone (aka me) wanted to convert this into another format (aka Markdown), these changes mean you can more easily script that conversion.