[Lldb-commits] [lldb] [lldb][Docs] Remove more subtitles from packets doc (PR #90443)
via lldb-commits
lldb-commits at lists.llvm.org
Mon Apr 29 02:52:01 PDT 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: David Spickett (DavidSpickett)
<details>
<summary>Changes</summary>
This removes various subtitles or converts them to bold text so that the table of contents is less cluttered.
This includes "Example", "Notes", "Priority To Implement" and "Response".
---
Patch is 32.23 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/90443.diff
1 Files Affected:
- (modified) lldb/docs/resources/lldbgdbremote.md (+146-274)
``````````diff
diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index a9fa2a432b7009..aaf903c9a5d13b 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -42,10 +42,8 @@ read packet: $OK#9a
send packet: +
```
-### Priority To Implement
-
-High. Any GDB remote server that can implement this should if the
-connection is reliable. This improves packet throughput and increases
+**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.
## QSupported
@@ -84,9 +82,7 @@ In the example above, three lldb extensions are shown:
watchpoints, up to a pointer size, `sizeof(void*)`, a reasonable
baseline assumption.
-### Priority To Implement
-
-Optional.
+**Priority To Implement:** Optional
## "A" - launch args packet
@@ -111,10 +107,8 @@ 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.
-### 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
+**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.
## qLaunchSuccess
@@ -125,9 +119,8 @@ 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.
-### Priority To Implement
-
-High, launching processes is a key part of LLDB's platform mode.
+**Priority To Implement:** High, launching processes is a key part of LLDB's
+platform mode.
## QEnvironment:NAME=VALUE
@@ -150,10 +143,8 @@ read packet: $OK#00
```
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 launch a target after
-making a connection to a GDB server that isn't already connected to
+**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.
## QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)
@@ -173,18 +164,23 @@ read packet: $OK#00
```
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 launch a target after
-making a connection to a GDB server that isn't already connected to
+**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.
## QEnableErrorStrings
This packet enables reporting of Error strings in remote packet
replies from the server to client. If the server supports this
-feature, it should send an OK response. The client can expect the
-following error replies if this feature is enabled in the server:
+feature, it should send an OK response.
+
+```
+send packet: $QEnableErrorStrings
+read packet: $OK#00
+```
+
+The client can expect the following error replies if this feature is enabled in
+the server:
```
EXX;AAAAAAAAA
```
@@ -195,17 +191,8 @@ It must be noted that even if the client has enabled reporting
strings in error replies, it must not expect error strings to all
error replies.
-### 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
-```
+**Priority To Implement:** Low. Only needed if the remote target wants to
+provide strings that are human readable along with an error code.
## QSetSTDIN:\<ascii-hex-path\> / QSetSTDOUT:\<ascii-hex-path\> / QSetSTDERR:\<ascii-hex-path\>
@@ -221,13 +208,10 @@ QSetSTDERR:<ascii-hex-path>
```
These packets must be sent _prior_ to sending a "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
+**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.
-
## QSetWorkingDir:\<ascii-hex-path\>
Set the working directory prior to sending an "A" packet.
@@ -238,10 +222,8 @@ QSetWorkingDir:<ascii-hex-path>
```
This packet must be sent _prior_ to sending a "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
+**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.
## qGetWorkingDir
@@ -249,8 +231,6 @@ an inferior process.
Get the current working directory of the platform stub in
ASCII hex encoding.
-### Example
-
```
receive: qGetWorkingDir
send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
@@ -270,10 +250,8 @@ read packet: OK
```
This packet must be sent _prior_ to sending a "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
+**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).
@@ -283,26 +261,27 @@ Enable the `threads:` and `thread-pcs:` data in the question-mark packet
("T packet") responses when the stub reports that a program has
stopped executing.
-### Priority To Implement
-
-Performance. This is a performance benefit to lldb if the thread id's
-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
```
+**Priority To Implement:** Performance. This is a performance benefit to lldb
+if the thread id's 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.
+
## jLLDBTraceSupported
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.
+```
+send packet: jLLDBTraceSupported
+read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAAA
+```
+
### Output Schema
```
@@ -317,19 +296,10 @@ capabilities of the underlying OS.
If no tracing technology is supported for the inferior, or no process is
running, then an error message is returned.
-### Note
-
-This packet is used by Trace plug-ins (see `lldb_private::Trace.h`) to
+**Note:** 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
-```
-
## jLLDBTraceStart
Start tracing a process or its threads using a provided tracing technology.
@@ -341,10 +311,20 @@ response is returned, or an error otherwise.
This traces existing and future threads of the current process. An error is
returned if the process is already being traced.
+```
+send packet: jLLDBTraceStart:{"type":<type>,...other params}]
+read packet: OK/E<error code>;AAAAAAAAA
+```
+
### Thread Tracing
This traces specific threads.
+```
+send packet: jLLDBTraceStart:{"type":<type>,"tids":<tids>,...other params}]
+read packet: OK/E<error code>;AAAAAAAAA
+```
+
### Input Schema
```
@@ -360,8 +340,7 @@ This traces specific threads.
}
```
-### Notes
-
+**Notes:**
- If "tids" is not provided, then the operation is "process tracing",
otherwise it's "thread tracing".
- Each tracing technology can have different levels of support for "thread
@@ -468,20 +447,6 @@ Notes:
- 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
-```
-
## jLLDBTraceStop
Stop tracing a process or its threads using a provided tracing technology.
@@ -493,11 +458,21 @@ response is returned, or an error otherwise.
Stopping a process trace stops the active traces initiated with
"thread tracing".
+```
+send packet: jLLDBTraceStop:{"type":<type>}]
+read packet: OK/E<error code>;AAAAAAAAA
+```
+
### Thread Trace Stopping
This is a best effort request, which tries to stop as many traces as
possible.
+```
+send packet: jLLDBTraceStop:{"type":<type>,"tids":<tids>}]
+read packet: OK/E<error code>;AAAAAAAAA
+```
+
### Input Schema
The schema for the input is
@@ -512,27 +487,12 @@ The schema for the input is
}
```
-### Notes
-
-- If "tids" is not provided, then the operation is "process trace stopping".
+**Note:** If `tids` is not provided, then the operation is "process trace stopping".
### 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
-```
-
## jLLDBTraceGetState
Get the current state of the process and its threads being traced by
@@ -540,6 +500,11 @@ a given trace technology. The response is a JSON object with custom
information depending on the trace technology. In case of errors, an
error message is returned.
+```
+send packet: jLLDBTraceGetState:{"type":<type>}]
+read packet: {...object}/E<error code>;AAAAAAAAA
+```
+
### Input Schema
```
@@ -594,10 +559,8 @@ error message is returned.
}
```
-### Notes
-
- - "traceThreads" includes all thread traced by both "process tracing" and
- "thread tracing".
+**Note:** `tracedThreads` includes all threads traced by both "process tracing"
+and "thread tracing".
### Intel Pt
@@ -631,13 +594,6 @@ Additional attributes:
}
```
-### Example
-
-```
-send packet: jLLDBTraceGetState:{"type":<type>}]
-read packet: {...object}/E<error code>;AAAAAAAAA
-```
-
## jLLDBTraceGetBinaryData
Get binary data given a trace technology and a data identifier.
@@ -645,6 +601,11 @@ 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
message is returned.
+```
+send packet: jLLDBTraceGetBinaryData:{"type":<type>,"kind":<query>,"tid":<tid>,"offset":<offset>,"size":<size>}]
+read packet: <binary data>/E<error code>;AAAAAAAAA
+```
+
### Schema
The schema for the input is:
@@ -661,13 +622,6 @@ The schema for the input is:
}
```
-### Example
-
-```
-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\>
Discover register information from the remote GDB server.
@@ -937,16 +891,13 @@ 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
-
-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
+**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`.
+**Note:** `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.
@@ -977,10 +928,7 @@ drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp
-rw-r--r-- 1 username groupname 3190 Aug 12 16:46 Makefile
```
-### Priority To Implement
-
-High. This command allows LLDB clients to run arbitrary shell
-commands on a remote host.
+**Priority To Implement:** High
## qPlatform_mkdir
@@ -997,10 +945,7 @@ Reply:
(mkdir called successfully and returned with the given return code)
* `Exx` (An error occurred)
-### Priority To Implement
-
-Low. This command allows LLDB clients to create new directories on
-a remote host.
+**Priority To Implement:** Low
## vFile:chmod / qPlatform_chmod
@@ -1013,9 +958,7 @@ Reply:
(chmod called successfully and returned with the given return code)
* `Exx` (An error occurred)
-### Priority To Implement
-
-Low.
+**Priority To Implement:** Low
## qHostInfo
@@ -1066,10 +1009,8 @@ 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.
-### 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
+**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.
## qGDBServerVersion
@@ -1107,19 +1048,17 @@ Suggested key names:
* `major_version`: major version number
* `minor_version`: minor version number
-### 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
+**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.
## qProcessInfo
Get information about the process we are currently debugging.
-### Priority To Implement
+**Priority To Implement:** Medium
-Medium. On systems which can launch multiple different architecture processes,
+On systems which can launch multiple different architecture processes,
the qHostInfo may not disambiguate sufficiently to know what kind of
process is being debugged.
@@ -1180,9 +1119,9 @@ send packet: $qShlibInfoAddr#00
read packet: $7fff5fc40040#00
```
-### Priority To Implement
+**Priority To Implement:** High
-High if you have a dynamic loader plug-in in LLDB for your target
+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
@@ -1203,9 +1142,9 @@ 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
+**Priority To Implement:** High
-High if you need to support multi-threaded or multi-core debugging.
+If you need to support multi-threaded or multi-core debugging.
Many times one thread will hit a breakpoint and while the debugger
is in the process of suspending the other threads, other threads
will also hit a breakpoint. This packet allows LLDB to know why all
@@ -1254,9 +1193,9 @@ read packet: ....
We also added support for allocating and deallocating memory. We use this to
allocate memory so we can run JITed code.
-### Priority To Implement
+**Priority To Implement:** High
-High. Adding a thread suffix allows us to read and write registers
+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
@@ -1289,12 +1228,9 @@ 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.
-### Priority To Implement
-
-High if you want LLDB to be able to JIT code and run that code. JIT
-code also needs data which is also allocated and tracked.
-
-Low if you don't support running JIT'ed code.
+**Priority To Implement:** High if you want LLDB to be able to JIT code and run
+that code. JIT code also needs data which is also allocated and tracked. Low if
+you don't support running JIT'ed code.
## _m\<addr\>
@@ -1306,12 +1242,9 @@ 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 an
empty response if not supported.
-### Priority To Implement
-
-High if you want LLDB to be able to JIT code and run that code. JIT
-code also needs data which is also allocated and tracked.
-
-Low if you don't support running JIT'ed code.
+**Priority To Implement:** High if you want LLDB to be able to JIT code and run
+that code. JIT code also needs data which is also allocated and tracked. Low if
+you don't support running JIT'ed code.
## qMemoryRegionInfo:\<addr\>
@@ -1371,9 +1304,9 @@ For instance, with a macOS process which has nothing mapped in the first
The lack of `permissions:` indicates that none of read/write/execute are valid
for this region.
-### Priority To Implement
+**Priority To Implement:** Medium
-Medium. This is nice to have, but it isn't necessary. It helps LLDB
+This is nice to have, but it isn't necessary. It helps LLDB
do stack unwinding when we branch into memory that isn't executable.
If we can detect that the code we are stopped in isn't executable,
then we can recover registers for stack frames above the current
@@ -1446,8 +1379,7 @@ involves calling `thread_abort_safely(mach_port_t thread)` to
ensure we get the correct registers for a thread in case it is
currently having code run on its behalf in the kernel.
-### Response
-
+The response is either:
* `<unsigned int>` - The save_id result is a non-zero unsigned integer value
that can be passed back to the GDB server using a
`QRestoreRegisterState` packet to restore the registers
@@ -1455,11 +1387,9 @@ currently having code run on its behalf in the kernel.
* `EXX` - or an error code in the form of `EXX` where `XX` is a
hex error code.
-### Priority To Implement
-
-Low, this is mostly a convenience packet to avoid having to send all
-registers with a `g` packet. It should only be implemented if support
-for the `QRestoreRegisterState` is added.
+**Priority To Implement:** Low, this is mostly a convenience packet to avoid
+having to send all registers with a `g` packet. It should only be implemented if
+support for the `QRestoreRegisterState` is added.
## QRestoreRegisterState:\<save_id\> / QRestoreRegisterState:\<save_id\>;thread:XXXX;
@@ -1473,16 +1403,13 @@ completion of the `...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/90443
More information about the lldb-commits
mailing list