[Lldb-commits] [lldb] [lldb][Docs] Sort documented packets alphabetically (PR #90584)
via lldb-commits
lldb-commits at lists.llvm.org
Tue Apr 30 03:09:44 PDT 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: David Spickett (DavidSpickett)
<details>
<summary>Changes</summary>
For the platform and extension doc.
Also add links in the extension doc to the GDB specs we're extending.
---
Patch is 170.36 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/90584.diff
2 Files Affected:
- (modified) lldb/docs/resources/lldbgdbremote.md (+1623-1618)
- (modified) lldb/docs/resources/lldbplatformpackets.md (+15-15)
``````````diff
diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index aaf903c9a5d13b..1467723fb79dce 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -1,14 +1,19 @@
# GDB Remote Protocol Extensions
LLDB has added new GDB server packets to better support multi-threaded and
-remote debugging.
+remote debugging. These extend the
+[protocol defined by GDB ](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Packets.html#Packets) (and [this page](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Host-I_002fO-Packets.html#Host-I_002fO-Packets) for `vFile` packets).
-Why? Normally you need to start the correct GDB and the
-correct GDB server when debugging. If you have mismatch, then things go wrong
-very quickly. LLDB makes extensive use of the GDB remote protocol and we
-wanted to make sure that the experience was a bit more dynamic where we can
-discover information about a remote target without having to know anything up
-front.
+If a packet is restated here it is because LLDB's version has some behaviour
+difference to GDB's version, or it provides some context for a following LLDB
+extension packet.
+
+Why did we add these? The most common reason is flexibility. Normally you need
+to start the correct GDB and the correct GDB server when debugging. If you have
+mismatch, then things go wrong very quickly. LLDB makes extensive use of the GDB
+remote protocol and we wanted to make sure that the experience was a bit more
+dynamic where we can discover information about a remote target without having
+to know anything up front.
We also ran into performance issues with the existing GDB remote
protocol that can be overcome when using a reliable communications layer.
@@ -22,67 +27,48 @@ We prefer to be able to dynamically determine what kind of architecture, OS and
vendor we are debugging, as well as how things are laid out when it comes to
the thread register contexts.
-Below are the details on the new packets we have added above and beyond the
-standard GDB remote protocol packets.
-
-## QStartNoAckMode
+## _M\<size\>,\<permissions\>
-Try to enable no ACK mode to skip sending ACKs and NACKs.
+Allocate memory on the remote target with the specified size and
+permissions.
-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:
+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
+code. The packet is formatted as:
```
-send packet: $QStartNoAckMode#b0
-read packet: +
-read packet: $OK#9a
-send packet: +
+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" : "");
```
-**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
-
-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.
-They are not all listed here.
-
-An example exchange:
-```
-send packet: qSupported:xmlRegisters=i386,arm,mips,arc;multiprocess+;fork-events+;vfork-events+
+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.
-read packet: qXfer:features:read+;PacketSize=20000;qEcho+;native-signals+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;SupportedWatchpointTypes=aarch64-mask,aarch64-bas;
-```
+**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.
-In the example above, three lldb extensions are shown:
+## _m\<addr\>
- * `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)
+Deallocate memory that was previously allocated using an allocate
+memory pack.
- If nothing is specified, lldb will default to sending power-of-2
- watchpoints, up to a pointer size, `sizeof(void*)`, a reasonable
- baseline assumption.
+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 an
+empty response if not supported.
-**Priority To Implement:** Optional
+**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.
## "A" - launch args packet
@@ -111,194 +97,301 @@ debugging.
a target after making a connection to a GDB server that isn't already connected to
an inferior process.
-## qLaunchSuccess
-
-Check whether launching a process with the `A` packet succeeded.
-
-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.
+## "D" - Detach and stay stopped
-**Priority To Implement:** High, launching processes is a key part of LLDB's
-platform mode.
+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:
+```
-## QEnvironment:NAME=VALUE
+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
+```
+In any case, if we want the normal detach behavior we will just send:
+```
+D
+```
-Setup the environment up for a new child process that will soon be
-launched using the "A" packet.
+## jGetDyldProcessState
-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.
+This packet fetches the process launch state, as reported by libdyld on
+Darwin systems, most importantly to indicate when the system libraries
+have initialized sufficiently to safely call utility functions.
-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
+LLDB SENDS: jGetDyldProcessState
+STUB REPLIES: {"process_state_value":48,"process_state string":"dyld_process_state_libSystem_initialized"}
```
-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
-an inferior process.
+**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
+process startup.
-## QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)
+## jGetLoadedDynamicLibrariesInfos
-Setup the environment up for a new child process that will soon be
-launched using the "A" packet.
+This packet asks the remote debug stub to send the details about libraries
+being added/removed from the process as a performance optimization.
-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.
+There are two ways this packet can be used. Both return a dictionary of
+binary images formatted the same way.
-Both GDB and LLDB support passing down environment variables. Is it ok to
-respond with a `$#00` (unimplemented):
+One requests information on all shared libraries:
```
-send packet: $QEnvironment:41434b5f434f4c4f525f46494c454e414d453d626f6c642379656c6c6f77#00
-read packet: $OK#00
+jGetLoadedDynamicLibrariesInfos:{"fetch_all_solibs":true}
```
-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
-an inferior process.
+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
+commands of each binary, and returns it in the JSON reply.
-## QEnableErrorStrings
+And the second requests information about a list of shared libraries, given their load addresses:
+```
+jGetLoadedDynamicLibrariesInfos:{"solib_addresses":[8382824135,3258302053,830202858503]}
+```
-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 second call is both a performance optimization (instead of having lldb read the mach-o header/load commands
+out of memory with generic read packets) but also adds additional information in the form of the
+filename of the shared libraries (which is not available in the mach-o header/load commands.)
+An example using the OS X 10.11 style call:
```
-send packet: $QEnableErrorStrings
-read packet: $OK#00
+LLDB SENDS: jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128}
+STUB REPLIES: ${"images":[{"load_address":4294967296,"mod_date":0,"pathname":"/tmp/a.out","uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF","mach_header":{"magic":4277009103,"cputype":16777223,"cpusubtype":18446744071562067971,"filetype":2},"segments":{"name":"__PAGEZERO","vmaddr":0,"vmsize":4294967296,"fileoff":0,"filesize":0,"maxprot":0},{"name":"__TEXT","vmaddr":4294967296,"vmsize":4096,"fileoff":0,"filesize":4096,"maxprot":7},{"name":"__LINKEDIT","vmaddr":4294971392,"vmsize":4096,"fileoff":4096,"filesize":152,"maxprot":7}}]}#00
```
-The client can expect the following error replies if this feature is enabled in
-the server:
+Or pretty-printed:
```
-EXX;AAAAAAAAA
+STUB REPLIES: ${"images":
+ [
+ {"load_address":4294967296,
+ "mod_date":0,
+ "pathname":"/tmp/a.out",
+ "uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF",
+ "mach_header":
+ {"magic":4277009103,
+ "cputype":16777223,
+ "cpusubtype":18446744071562067971,
+ "filetype":2
+ },
+ "segments":
+ [
+ {"name":"__PAGEZERO",
+ "vmaddr":0,
+ "vmsize":4294967296,
+ "fileoff":0,
+ "filesize":0,
+ "maxprot":0
+ },
+ {"name":"__TEXT",
+ "vmaddr":4294967296,
+ "vmsize":4096,
+ "fileoff":0,
+ "filesize":4096,
+ "maxprot":7
+ },
+ {"name":"__LINKEDIT",
+ "vmaddr":4294971392,
+ "vmsize":4096,
+ "fileoff":4096,
+ "filesize":152,
+ "maxprot":7
+ }
+ ]
+ }
+ ]
+ }
```
-where `AAAAAAAAA` will be a hex encoded ASCII string.
-`XX`` is hex encoded byte number.
-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.
+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:** Low. Only needed if the remote target wants to
-provide strings that are human readable along with an error code.
+**Priority To Implement:**
-## QSetSTDIN:\<ascii-hex-path\> / QSetSTDOUT:\<ascii-hex-path\> / QSetSTDERR:\<ascii-hex-path\>
+On OS X 10.11, iOS 9, tvOS 9, watchOS 2 and older: Low. If this packet is absent,
+lldb will read the Mach-O headers/load commands out of memory.
+On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer: High. If this packet is absent,
+lldb will not know anything about shared libraries in the inferior, or where the main
+executable loaded.
-Setup where STDIN, STDOUT, and STDERR go prior to sending an "A"
-packet.
+## jGetSharedCacheInfo
+
+This packet asks the remote debug stub to send the details about the inferior's
+shared cache. The shared cache is a collection of common libraries/frameworks that
+are mapped into every process at the same address on Darwin systems, and can be
+identified by a load address and UUID.
-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>
+LLDB SENDS: jGetSharedCacheInfo:{}
+STUB REPLIES: ${"shared_cache_base_address":140735683125248,"shared_cache_uuid":"DDB8D70C-C9A2-3561-B2C8-BE48A4F33F96","no_shared_cache":false,"shared_cache_private_cache":false]}#00
```
-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
-an inferior process.
+**Priority To Implement:** Low
-## QSetWorkingDir:\<ascii-hex-path\>
+When both lldb and the inferior process are running on the same computer, and lldb
+and the inferior process have the same shared cache, lldb may (as an optimization) read
+the shared cache out of its own memory instead of using gdb-remote read packets to read
+them from the inferior process.
-Set the working directory prior to sending an "A" packet.
+## jModulesInfo:[{"file":"...",triple:"..."}, ...]
-Or specify the working directory:
-```
-QSetWorkingDir:<ascii-hex-path>
-```
-This packet must be sent _prior_ to sending a "A" packet.
+Get information for a list of modules by given module path and
+architecture.
-**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.
+The response is a JSON array of dictionaries containing the following keys:
+* `uuid`
+* `triple`
+* `file_path`
+* `file_offset`
+* `file_size`
-## qGetWorkingDir
+The meaning of the fields is the same as in the `qModuleInfo` packet. The server
+signals the failure to retrieve the module info for a file by ommiting the
+corresponding array entry from the response. The server may also
+include entries the client did not ask for, if it has reason to
+the modules will be interesting to the client.
-Get the current working directory of the platform stub in
-ASCII hex encoding.
+**Priority To Implement:** Optional. If not implemented, `qModuleInfo` packet
+will be used, which may be slower if the target contains a large number of modules
+and the communication link has a non-negligible latency.
+
+## jLLDBTraceGetBinaryData
+
+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
+message is returned.
```
-receive: qGetWorkingDir
-send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
+send packet: jLLDBTraceGetBinaryData:{"type":<type>,"kind":<query>,"tid":<tid>,"offset":<offset>,"size":<size>}]
+read packet: <binary data>/E<error code>;AAAAAAAAA
```
-## QSetDisableASLR:\<bool\>
-
-Enable or disable ASLR on the next "A" packet.
+### Schema
-Or control if ASLR is enabled/disabled:
+The schema for the input is:
```
-send packet: QSetDisableASLR:1
-read packet: OK
-
-send packet: QSetDisableASLR:0
-read packet: OK
+{
+ "type": <string>,
+ Tracing technology name, e.g. intel-pt, arm-etm.
+ "kind": <string>,
+ Identifier for the data.
+ "cpuId": <Optional decimal>,
+ Core id in decimal if the data belongs to a CPU core.
+ "tid"?: <Optional decimal>,
+ Tid in decimal if the data belongs to a thread.
+}
```
-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
-an inferior process and if the target supports disabling ASLR
-(Address space layout randomization).
-## QListThreadsInStopReply
+## jLLDBTraceGetState
-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.
+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
+error message is returned.
```
-send packet: QListThreadsInStopReply
-read packet: OK
+send packet: jLLDBTraceGetState:{"type":<type>}]
+read packet: {...object}/E<error code>;AAAAAAAAA
```
-**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.
+### Input Schema
```
-send packet: jLLDBTraceSupported
-read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAAA
+{
+ "type": <string>
+ Tracing technology name, e.g. intel-pt, arm-etm.
+}
```
### Output Schema
```
- {
- "name": <string>,
- Tracing technology name, e.g. intel...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/90584
More information about the lldb-commits
mailing list