[Lldb-commits] [lldb] [lldb[Docs] Reduce title noise in packets doc (PR #90183)
via lldb-commits
lldb-commits at lists.llvm.org
Fri Apr 26 02:14:38 PDT 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: David Spickett (DavidSpickett)
<details>
<summary>Changes</summary>
This removes the "Brief" and "Description" subtitles and merges the text of both so that the contents listing is clearer.
---
Patch is 35.11 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/90183.diff
1 Files Affected:
- (modified) lldb/docs/resources/lldbgdbremote.md (+168-361)
``````````diff
diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index 05e4f714f7f704..a9fa2a432b7009 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -27,18 +27,8 @@ standard GDB remote protocol packets.
## QStartNoAckMode
-### Brief
-
Try to enable no ACK mode to skip sending ACKs and NACKs.
-### Priority To Implement
-
-High. Any GDB remote server that can implement this should if the
-connection is reliable. This improves packet throughput and increases
-the performance of the connection.
-
-### 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
@@ -52,17 +42,15 @@ read packet: $OK#9a
send packet: +
```
-## QSupported
-
-### Brief
-
-Query the GDB remote server for features it supports
-
### Priority To Implement
-Optional.
+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
+## QSupported
+
+Query the GDB remote server for features it supports
QSupported is a standard GDB Remote Serial Protocol packet, but
there are several additions to the response that lldb can parse.
@@ -96,21 +84,14 @@ In the example above, three lldb extensions are shown:
watchpoints, up to a pointer size, `sizeof(void*)`, a reasonable
baseline assumption.
+### Priority To Implement
-## "A" - launch args packet
+Optional.
-### Brief
+## "A" - launch args packet
Launch a program using the supplied arguments
-### Priority To Implement
-
-Low. Only needed if the remote target wants to launch a target after
-making a connection to a GDB server that isn't already connected to
-an inferior process.
-
-### 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:
@@ -130,14 +111,16 @@ 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.
-## qLaunchSuccess
+### 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.
-### Brief
+## qLaunchSuccess
Check whether launching a process with the `A` packet succeeded.
-### Description
-
Returns the status of the last attempt to launch a process.
Either `OK` if no error ocurred, or `E` followed by a string
describing the error.
@@ -148,8 +131,6 @@ High, launching processes is a key part of LLDB's platform mode.
## QEnvironment:NAME=VALUE
-### Brief
-
Setup the environment up for a new child process that will soon be
launched using the "A" packet.
@@ -161,14 +142,6 @@ 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):
```
@@ -177,9 +150,13 @@ read packet: $OK#00
```
This packet can be sent one or more times _prior_ to sending a "A" packet.
-## QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)
+### 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.
-### Brief
+## QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)
Setup the environment up for a new child process that will soon be
launched using the "A" packet.
@@ -188,14 +165,6 @@ 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):
```
@@ -204,9 +173,13 @@ read packet: $OK#00
```
This packet can be sent one or more times _prior_ to sending a "A" packet.
-## QEnableErrorStrings
+### Priority To Implement
-### Brief
+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.
+
+## QEnableErrorStrings
This packet enables reporting of Error strings in remote packet
replies from the server to client. If the server supports this
@@ -236,19 +209,9 @@ read packet: $OK#00
## QSetSTDIN:\<ascii-hex-path\> / QSetSTDOUT:\<ascii-hex-path\> / QSetSTDERR:\<ascii-hex-path\>
-### Brief
-
Setup where STDIN, STDOUT, and STDERR go prior to sending an "A"
packet.
-### Priority To Implement
-
-Low. Only needed if the remote target wants to launch a target after
-making a connection to a GDB server that isn't already connected to
-an inferior process.
-
-### 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:
```
@@ -258,19 +221,16 @@ QSetSTDERR:<ascii-hex-path>
```
These packets must be sent _prior_ to sending a "A" packet.
-## QSetWorkingDir:\<ascii-hex-path\>
-
-### Brief
-
-Set the working directory prior to sending an "A" packet.
-
### Priority To Implement
Low. Only needed if the remote target wants to launch a target after
making a connection to a GDB server that isn't already connected to
an inferior process.
-### Description
+
+## QSetWorkingDir:\<ascii-hex-path\>
+
+Set the working directory prior to sending an "A" packet.
Or specify the working directory:
```
@@ -278,9 +238,13 @@ QSetWorkingDir:<ascii-hex-path>
```
This packet must be sent _prior_ to sending a "A" packet.
-## qGetWorkingDir
+### Priority To Implement
-### Brief
+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.
+
+## qGetWorkingDir
Get the current working directory of the platform stub in
ASCII hex encoding.
@@ -294,19 +258,8 @@ send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f546573745
## QSetDisableASLR:\<bool\>
-### Brief
-
Enable or disable ASLR on the next "A" packet.
-### Priority To Implement
-
-Low. Only needed if the remote target wants to launch a target after
-making a connection to a GDB server that isn't already connected to
-an inferior process and if the target supports disabling ASLR
-(Address space layout randomization).
-
-### Description
-
Or control if ASLR is enabled/disabled:
```
send packet: QSetDisableASLR:1
@@ -317,9 +270,14 @@ read packet: OK
```
This packet must be sent _prior_ to sending a "A" packet.
-## QListThreadsInStopReply
+### Priority To Implement
-### Brief
+Low. Only needed if the remote target wants to launch a target after
+making a connection to a GDB server that isn't already connected to
+an inferior process and if the target supports disabling ASLR
+(Address space layout randomization).
+
+## QListThreadsInStopReply
Enable the `threads:` and `thread-pcs:` data in the question-mark packet
("T packet") responses when the stub reports that a program has
@@ -341,8 +299,6 @@ read packet: OK
## jLLDBTraceSupported
-### Brief
-
Get the processor tracing type supported by the gdb-server for the current
inferior. Responses might be different depending on the architecture and
capabilities of the underlying OS.
@@ -376,8 +332,6 @@ read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAA
## jLLDBTraceStart
-### Brief
-
Start tracing a process or its threads using a provided tracing technology.
The input and output are specified as JSON objects. In case of success, an OK
response is returned, or an error otherwise.
@@ -530,8 +484,6 @@ read packet: OK/E<error code>;AAAAAAAAA
## jLLDBTraceStop
-### Brief
-
Stop tracing a process or its threads using a provided tracing technology.
The input and output are specified as JSON objects. In case of success, an OK
response is returned, or an error otherwise.
@@ -583,8 +535,6 @@ read packet: OK/E<error code>;AAAAAAAAA
## jLLDBTraceGetState
-### Brief
-
Get the current state of the process and its threads being traced by
a given trace technology. The response is a JSON object with custom
information depending on the trace technology. In case of errors, an
@@ -690,8 +640,6 @@ read packet: {...object}/E<error code>;AAAAAAAAA
## jLLDBTraceGetBinaryData
-### Brief
-
Get binary data given a trace technology and a data identifier.
The input is specified as a JSON object and the response has the same format
as the "binary memory read" (aka "x") packet. In case of failures, an error
@@ -722,29 +670,8 @@ read packet: <binary data>/E<error code>;AAAAAAAAA
## qRegisterInfo\<hex-reg-id\>
-### Brief
-
Discover register information from the remote GDB server.
-### Priority To Implement
-
-High. Any target that can self describe its registers, should do so.
-This means if new registers are ever added to a remote target, they
-will get picked up automatically, and allows registers to change
-depending on the actual CPU type that is used.
-
-NB: `qRegisterInfo` is deprecated in favor of the standard gdb remote
-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
-gdb RSP stubs whereas `qRegisterInfo` was an lldb-only design.
-`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
@@ -1010,19 +937,26 @@ The keys and values are detailed below:
modifying the CPSR register can cause the r8 - r14 and cpsr value to
change depending on if the mode has changed.
+### Priority To Implement
-## qPlatform_shell
-
-### Brief
-
-Run a command in a shell on the connected remote machine.
+High. Any target that can self describe its registers, should do so.
+This means if new registers are ever added to a remote target, they
+will get picked up automatically, and allows registers to change
+depending on the actual CPU type that is used.
-### Priority To Implement
+NB: `qRegisterInfo` is deprecated in favor of the standard gdb remote
+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
+gdb RSP stubs whereas `qRegisterInfo` was an lldb-only design.
+`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.
-High. This command allows LLDB clients to run arbitrary shell
-commands on a remote host.
+## qPlatform_shell
-### Description
+Run a command in a shell on the connected remote machine.
The request consists of the command to be executed encoded in ASCII characters
converted into hex bytes.
@@ -1043,18 +977,14 @@ drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp
-rw-r--r-- 1 username groupname 3190 Aug 12 16:46 Makefile
```
-## qPlatform_mkdir
-
-### Brief
-
-Creates a new directory on the connected remote machine.
-
### Priority To Implement
-Low. This command allows LLDB clients to create new directories on
-a remote host.
+High. This command allows LLDB clients to run arbitrary shell
+commands on a remote host.
+
+## qPlatform_mkdir
-### Description
+Creates a new directory on the connected remote machine.
Request: `qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path>`
@@ -1067,20 +997,15 @@ Reply:
(mkdir called successfully and returned with the given return code)
* `Exx` (An error occurred)
+### Priority To Implement
-## vFile:chmod / qPlatform_chmod
+Low. This command allows LLDB clients to create new directories on
+a remote host.
-### Brief
+## vFile:chmod / qPlatform_chmod
Change the permissions of a file on the connected remote machine.
-### Priority To Implement
-
-Low. This command allows LLDB clients to change the permissions of
-a file on the remote host.
-
-### Description
-
Request: `qPlatform_chmod:<hex-file-mode>,<ascii-hex-path>`
Reply:
@@ -1088,19 +1013,13 @@ Reply:
(chmod called successfully and returned with the given return code)
* `Exx` (An error occurred)
-## qHostInfo
-
-### Brief
-
-Get information about the host we are remotely connected to.
-
### Priority To Implement
-High. This packet is usually very easy to implement and can help
-LLDB select the correct plug-ins for the job based on the target
-triple information that is supplied.
+Low.
-### Description
+## qHostInfo
+
+Get information about the host we are remotely connected to.
LLDB supports a host info call that gets all sorts of details of the system
that is being debugged:
@@ -1147,20 +1066,16 @@ Key value pairs are one of:
AArch64 can have different page table setups for low and high
memory, and therefore a different number of bits used for addressing.
-## qGDBServerVersion
-
-### Brief
-
-Get version information about this implementation of the gdb-remote
-protocol.
-
### Priority To Implement
High. This packet is usually very easy to implement and can help
-LLDB to work around bugs in a server's implementation when they
-are found.
+LLDB select the correct plug-ins for the job based on the target
+triple information that is supplied.
+
+## qGDBServerVersion
-### Description
+Get version information about this implementation of the gdb-remote
+protocol.
The goal of this packet is to provide enough information about an
implementation of the gdb-remote-protocol server that lldb can
@@ -1192,9 +1107,13 @@ Suggested key names:
* `major_version`: major version number
* `minor_version`: minor version number
-## qProcessInfo
+### Priority To Implement
-### Brief
+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.
+
+## qProcessInfo
Get information about the process we are currently debugging.
@@ -1211,8 +1130,6 @@ 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
@@ -1249,24 +1166,9 @@ Key value pairs include:
## qShlibInfoAddr
-### Brief
-
Get an address where the dynamic linker stores information about
where shared libraries are loaded.
-### Priority To Implement
-
-High if you have a dynamic loader plug-in in LLDB for your target
-triple (see the "qHostInfo" packet) that can use this information.
-Many times address load randomization can make it hard to detect
-where the dynamic loader binary and data structures are located and
-some platforms know, or can find out where this information is.
-
-Low if you have a debug target where all object and symbol files
-contain static load addresses.
-
-### 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`
@@ -1278,12 +1180,29 @@ send packet: $qShlibInfoAddr#00
read packet: $7fff5fc40040#00
```
-## qThreadStopInfo\<tid\>
+### Priority To Implement
-### Brief
+High if you have a dynamic loader plug-in in LLDB for your target
+triple (see the "qHostInfo" packet) that can use this information.
+Many times address load randomization can make it hard to detect
+where the dynamic loader binary and data structures are located and
+some platforms know, or can find out where this information is.
+
+Low if you have a debug target where all object and symbol files
+contain static load addresses.
+
+## qThreadStopInfo\<tid\>
Get information about why a thread, whose ID is `<tid>`, is stopped.
+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.
+
### Priority To Implement
High if you need to support multi-threaded or multi-core debugging.
@@ -1294,34 +1213,10 @@ 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.
-
## QThreadSuffixSupported
-### Brief
-
Try to enable thread suffix support for the `g`, `G`, `p`, and `P` packets.
-### Priority To Implement
-
-High. Adding a thread suffix allows us to read and write registers
-more efficiently and stops us from having to select a thread with
-one packet and then read registers with a second packet. It also
-makes sure that no errors can occur where the debugger thinks it
-already has a thread selected (see the `Hg` packet from the standard
-GDB remote protocol documentation) yet the remote GDB server actually
-has another thread selected.
-
-### 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>;`
@@ -1359,21 +1254,20 @@ read packet: ....
We also added support for allocating and deallocating memory. We use this to
allocate memory so we can run JITed code.
-## _M\<size\>,\<permissions\>
-
-### Brief
-
-Allocate memory on the remote target with the specified size and
-permissions.
-
### Priority To Implement
-High if you want LLDB to be able to JIT code and run that code. JIT
-code also needs data which is also allocated and tracked.
+High. Adding a thread suffix allows us to read and write registers
+more efficiently and stops us from having to select a thread with
+one packet and then read registers with a second packet. It also
+makes sure that no errors can occur where the debugger thinks it
+already has a thread selected (see the `Hg` packet from the standard
+GDB remote protocol documentation) yet the remote GDB server actually
+has another thread selected.
-Low if you don't support running JIT'ed code.
+## _M\<size\>,\<permissions\>
-### Description
+Allocate memory on the remote target with the specified size and
+permissions.
The allocate memory packet starts with `_M<size>,<permissions>`. It returns a
raw big endian address value, or an empty response for unimplemented, or `EXX` for an error
@@ -13...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/90183
More information about the lldb-commits
mailing list