[Lldb-commits] [lldb] [lldb][Docs] Convert platform packets doc to Markdown (PR #89913)
via lldb-commits
lldb-commits at lists.llvm.org
Wed Apr 24 03:53:10 PDT 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: David Spickett (DavidSpickett)
<details>
<summary>Changes</summary>
As before, script did most of the work, hand edits after that.
There's a lot more we can do dedupe this and the packets doc, this will come in a follow up PR.
---
Patch is 27.19 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/89913.diff
3 Files Affected:
- (modified) lldb/docs/index.rst (+1)
- (removed) lldb/docs/lldb-platform-packets.txt (-451)
- (added) lldb/docs/resources/lldbplatformpackets.md (+482)
``````````diff
diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst
index 6906566ea55e58..7a27f6914fa89d 100644
--- a/lldb/docs/index.rst
+++ b/lldb/docs/index.rst
@@ -158,6 +158,7 @@ interesting areas to contribute to lldb.
resources/dataformatters
resources/extensions
resources/lldbgdbremote
+ resources/lldbplatformpackets
resources/caveats
resources/projects
Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html>
diff --git a/lldb/docs/lldb-platform-packets.txt b/lldb/docs/lldb-platform-packets.txt
deleted file mode 100644
index 4cf575e5ee8adb..00000000000000
--- a/lldb/docs/lldb-platform-packets.txt
+++ /dev/null
@@ -1,451 +0,0 @@
-Here is a brief overview of the packets that an lldb platform server
-needs to implement for the lldb testsuite to be run on a remote
-target device/system.
-
-These are almost all lldb extensions to the gdb-remote serial
-protocol. Many of the vFile: packets are described to the "Host
-I/O Packets" detailed in the gdb-remote protocol documentation,
-although the lldb platform extensions include packets that are not
-defined there (vFile:size:, vFile:mode:, vFile:symlink, vFile:chmod:).
-Most importantly, the flags that lldb passes to vFile:open: are
-incompatible with the flags that gdb specifies.
-
-
-//----------------------------------------------------------------------
-// QStartNoAckMode
-//
-// BRIEF
-// A request to stop sending ACK packets for each properly formatted packet.
-//
-// EXAMPLE
-// A platform session will typically start like this:
-//
-// receive: +$QStartNoAckMode#b0
-// send: + <-- ACKing the properly formatted QStartNoAckMode packet
-// send: $OK#9a
-// receive: + <-- Our OK packet getting ACKed
-//
-// ACK mode is now disabled.
-
-//----------------------------------------------------------------------
-// qHostInfo
-//
-// BRIEF
-// Describe the hardware and OS of the target system
-//
-// EXAMPLE
-//
-// receive: qHostInfo
-// send: cputype:16777228;cpusubtype:1;ostype:ios;watchpoint_exceptions_received:before;os_version:12.1;vendor:apple;default_packet_timeout:5;
-//
-// All numbers are base 10, os_version is a string that will be parsed as major.minor.patch.
-
-//----------------------------------------------------------------------
-// qModuleInfo
-//
-// BRIEF
-// Report information about a binary on the target system
-//
-// EXAMPLE
-// receive: qModuleInfo:2f62696e2f6c73;
-//
-// FIXME finish this packet description, v. GDBRemoteCommunicationServerCommon::Handle_qModuleInfo
-
-
-//----------------------------------------------------------------------
-// qGetWorkingDir
-//
-// BRIEF
-// Get the current working directory of the platform stub in
-// ASCII hex encoding.
-//
-// EXAMPLE
-//
-// receive: qGetWorkingDir
-// send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
-
-
-
-//----------------------------------------------------------------------
-// QSetWorkingDir:
-//
-// BRIEF
-// Set the current working directory of the platform stub in
-// ASCII hex encoding.
-//
-// EXAMPLE
-//
-// receive: QSetWorkingDir:2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
-// send: OK
-
-//----------------------------------------------------------------------
-// qPlatform_mkdir:
-//
-// BRIEF
-// Create a directory on the target system.
-//
-// EXAMPLE
-//
-// receive: qPlatform_mkdir:000001fd,2f746d702f6131
-// send: F0
-//
-// request packet has the fields:
-// 1. mode bits in base 16
-// 2. file path in ascii-hex encoding
-//
-// response is F followed by the return value of the mkdir() call,
-// base 16 encoded.
-
-//----------------------------------------------------------------------
-// qPlatform_shell:
-//
-// BRIEF
-// Run a shell command on the target system, return the output.
-//
-// EXAMPLE
-//
-// receive: qPlatform_shell:6c73202f746d702f,0000000a
-// send: F,0,0,<OUTPUT>
-//
-// request packet has the fields:
-// 1. shell command ascii-hex encoded
-// 2. timeout
-// 3. {optional} working directory ascii-hex encoded
-//
-// Response is F followed by the return value of the command (base 16),
-// followed by another number, followed by the output of the command
-/ in binary-escaped-data encoding.
-
-//----------------------------------------------------------------------
-// qLaunchGDBServer
-//
-// BRIEF
-// Start a gdbserver process (gdbserver, debugserver, lldb-server)
-// on the target system.
-//
-// EXAMPLE
-//
-// receive: qLaunchGDBServer;host:<HOSTNAME_LLDB_IS_ON>;
-// send: pid:1337;port:43001;
-//
-// request packet hostname field is not ascii-hex encoded. Hostnames
-// don't have $ or # characters in them.
-//
-// response to the packet is the pid of the newly launched gdbserver,
-// and the port it is listening for a connection on.
-//
-// When the testsuite is running, lldb may use the pid to kill off a
-// debugserver that doesn't seem to be responding, etc.
-
-//----------------------------------------------------------------------
-// qKillSpawnedProcess:
-//
-// BRIEF
-// Kill a process running on the target system.
-//
-// EXAMPLE
-//
-// receive: qKillSpawnedProcess:1337
-// send: OK
-//
-// The request packet has the process ID in base 10.
-
-//----------------------------------------------------------------------
-// qProcessInfoPID:
-//
-// BRIEF
-// Gather information about a process running on the target
-//
-// EXAMPLE
-//
-// receive: qProcessInfoPID:71964
-// send: pid:71964;name:612e6f7574;
-//
-// The request packet has the pid encoded in base 10.
-//
-// The reply has semicolon-separated name:value fields, two are
-// shown here. pid is base 10 encoded. name is ascii hex encoded.
-// lldb-server can reply with many additional fields, but I think
-// this is enough for the testsuite.
-
-//----------------------------------------------------------------------
-// qfProcessInfo:
-//
-// BRIEF
-// Search the process table for processes matching criteria,
-// respond with them in multiple packets.
-//
-// EXAMPLE
-//
-// receive: qfProcessInfo:name_match:equals;name:6e6f70726f6365737365786973747377697468746869736e616d65;
-// send: pid:3500;name:612e6f7574;
-//
-// The request packet has a criteria to search for, followed by
-// a specific name.
-//
-// KEY VALUE DESCRIPTION
-// =========== ======== ================================================
-// "name" ascii-hex An ASCII hex string that contains the name of
-// the process that will be matched.
-// "name_match" enum One of: "equals", "starts_with", "ends_with",
-// "contains" or "regex"
-// "pid" integer A string value containing the decimal process ID
-// "parent_pid" integer A string value containing the decimal parent
-// process ID
-// "uid" integer A string value containing the decimal user ID
-// "gid" integer A string value containing the decimal group ID
-// "euid" integer A string value containing the decimal effective user ID
-// "egid" integer A string value containing the decimal effective group ID
-// "all_users" bool A boolean value that specifies if processes should
-// be listed for all users, not just the user that the
-// platform is running as
-// "triple" ascii-hex An ASCII hex target triple string ("x86_64",
-// "x86_64-apple-macosx", "armv7-apple-ios")
-//
-// If no criteria is given, qfProcessInfo will request a list of every process.
-//
-// The lldb testsuite currently only uses name_match:equals and the
-// no-criteria mode to list every process.
-//
-// The response should include any information about the process that
-// can be retrieved in semicolon-separated name:value fields.
-// In this example, pid is base 10, name is ascii-hex encoded.
-// The testsuite seems to only require these two.
-//
-// This packet only responds with one process. To get further matches to
-// the search, qsProcessInfo should be sent.
-//
-// If no process match is found, Exx should be returned.
-//
-// Sample packet/response:
-// send packet: $qfProcessInfo#00
-// read packet: $pid:60001;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:7838365f36342d6170706c652d6d61636f7378;#00
-// send packet: $qsProcessInfo#00
-// read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:7838365f36342d6170706c652d6d61636f7378;#00
-// send packet: $qsProcessInfo#00
-// read packet: $E04#00
-
-//----------------------------------------------------------------------
-// qsProcessInfo
-//
-// BRIEF
-// Return the next process info found by the most recent qfProcessInfo:
-// packet.
-//
-// EXAMPLE
-//
-// Continues to return the results of the qfProcessInfo. Once all matches
-// have been sent, Exx is returned to indicate end of matches.
-
-//----------------------------------------------------------------------
-// qPathComplete
-//
-// BRIEF
-// Get a list of matched disk files/directories by passing a boolean flag
-// and a partial path.
-//
-// EXAMPLE
-//
-// receive: qPathComplete:0,6d61696e
-// send: M6d61696e2e637070
-// receive: qPathComplete:1,746573
-// send: M746573742f,74657374732f
-//
-// If the first argument is zero, the result should contain all
-// files (including directories) starting with the given path. If the
-// argument is one, the result should contain only directories.
-//
-// The result should be a comma-separated list of hex-encoded paths.
-// Paths denoting a directory should end with a directory separator ('/' or '\').
-
-//----------------------------------------------------------------------
-// vFile:size:
-//
-// BRIEF
-// Get the size of a file on the target system, filename in ASCII hex.
-//
-// EXAMPLE
-//
-// receive: vFile:size:2f746d702f61
-// send: Fc008
-//
-// response is "F" followed by the file size in base 16.
-// "F-1,errno" with the errno if an error occurs, base 16.
-
-
-//----------------------------------------------------------------------
-// vFile:mode:
-//
-// BRIEF
-// Get the mode bits of a file on the target system, filename in ASCII hex.
-//
-// EXAMPLE
-//
-// receive: vFile:mode:2f746d702f61
-// send: F1ed
-//
-// response is "F" followed by the mode bits in base 16, this 0x1ed would
-// correspond to 0755 in octal.
-// "F-1,errno" with the errno if an error occurs, base 16.
-
-//----------------------------------------------------------------------
-// vFile:unlink:
-//
-// BRIEF
-// Remove a file on the target system.
-//
-// EXAMPLE
-//
-// receive: vFile:unlink:2f746d702f61
-// send: F0
-//
-// Argument is a file path in ascii-hex encoding.
-// Response is "F" plus the return value of unlink(), base 16 encoding.
-// Return value may optionally be followed by a comma and the base16
-// value of errno if unlink failed.
-
-//----------------------------------------------------------------------
-// vFile:symlink:
-//
-// BRIEF
-// Create a symbolic link (symlink, soft-link) on the target system.
-//
-// EXAMPLE
-//
-// receive: vFile:symlink:<SRC-FILE>,<DST-NAME>
-// send: F0,0
-//
-// Argument file paths are in ascii-hex encoding.
-// Response is "F" plus the return value of symlink(), base 16 encoding,
-// optionally followed by the value of errno if it failed, also base 16.
-
-//----------------------------------------------------------------------
-// vFile:chmod:
-// qPlatform_chmod:
-//
-// BRIEF
-// Change the permission mode bits on a file on the target
-//
-// EXAMPLE
-//
-// receive: vFile:chmod:180,2f746d702f61
-// send: F0
-//
-// Arguments are the mode bits to set, base 16, and a file path in
-// ascii-hex encoding.
-// Response is "F" plus the return value of chmod(), base 16 encoding.
-//
-// I don't know why there are two packets for the same thing, v.
-// vFile:chmod:.
-
-//----------------------------------------------------------------------
-// vFile:chmod:
-//
-// BRIEF
-// Change the permission mode bits on a file on the target
-//
-// EXAMPLE
-//
-// receive: vFile:chmod:180,2f746d702f61
-// send: F0
-//
-// Arguments are the mode bits to set, base 16, and a file path in
-// ascii-hex encoding.
-// Response is "F" plus the return value of chmod(), base 10 encoding.
-
-
-//----------------------------------------------------------------------
-// vFile:open:
-//
-// BRIEF
-// Open a file on the remote system and return the file descriptor of it.
-//
-// EXAMPLE
-//
-// receive: vFile:open:2f746d702f61,00000001,00000180
-// send: F8
-//
-// request packet has the fields:
-// 1. ASCII hex encoded filename
-// 2. flags passed to the open call, base 16.
-// Note that these are not the oflags that open(2) takes, but
-// are the constant values in enum OpenOptions from lldb's File.h
-// 3. mode bits, base 16
-//
-// response is F followed by the opened file descriptor in base 16.
-// "F-1,errno" with the errno if an error occurs, base 16.
-//
-//----------------------------------------------------------------------
-// vFile:close:
-//
-// BRIEF
-// Close a previously opened file descriptor.
-//
-// EXAMPLE
-//
-// receive: vFile:close:7
-// send: F0
-//
-// File descriptor is in base 16.
-// "F-1,errno" with the errno if an error occurs,
-// errno is base 16.
-
-
-//----------------------------------------------------------------------
-// vFile:pread:
-//
-// BRIEF
-// Read data from an opened file descriptor.
-//
-// EXAMPLE
-//
-// receive: vFile:pread:7,1024,0
-// send: F4;a'b\00
-//
-// request packet has the fields:
-// 1. file descriptor, base 16
-// 2. number of bytes to be read, base 16
-// 3. offset into file to start from, base 16
-//
-// Response is F, followed by the number of bytes read (base 16), a
-// semicolon, followed by the data in the binary-escaped-data encoding.
-
-
-//----------------------------------------------------------------------
-// vFile:pwrite:
-//
-// BRIEF
-// Write data to a previously opened file descriptor.
-//
-// EXAMPLE
-//
-// receive: vFile:pwrite:8,0,\cf\fa\ed\fe\0c\00\00
-// send: F1024
-//
-// request packet has the fields:
-// 1. file descriptor, base 16
-// 2. offset into file to start from, base 16
-// 3. binary-escaped-data to be written
-//
-// Response is F, followed by the number of bytes written (base 16)
-
-
-
-
-
-Finally, the platform must be able to launch processes so that debugserver
-can attach to them. To do this, the following packets should be handled:
-
-QSetDisableASLR
-QSetDetachOnError
-QSetSTDOUT
-QSetSTDERR
-QSetSTDIN
-QEnvironment
-QEnvironmentHexEncoded
-A
-qLaunchSuccess
-qProcessInfo
-
-Most of these are documented in the standard gdb-remote protocol
-and/or the lldb-gdb-remote.txt documentation.
diff --git a/lldb/docs/resources/lldbplatformpackets.md b/lldb/docs/resources/lldbplatformpackets.md
new file mode 100644
index 00000000000000..bebc6618fb68ac
--- /dev/null
+++ b/lldb/docs/resources/lldbplatformpackets.md
@@ -0,0 +1,482 @@
+# LLDB Platform Packets
+Here is a brief overview of the packets that an lldb platform server
+needs to implement for the lldb testsuite to be run on a remote
+target device/system.
+
+These are almost all lldb extensions to the gdb-remote serial
+protocol. Many of the `vFile:` packets are also described in the "Host
+I/O Packets" detailed in the gdb-remote protocol documentation,
+although the lldb platform extensions include packets that are not
+defined there (`vFile:size:`, `vFile:mode:`, `vFile:symlink`, `vFile:chmod:`).
+
+Most importantly, the flags that lldb passes to `vFile:open:` are
+incompatible with the flags that gdb specifies.
+
+## QStartNoAckMode
+
+### Brief
+
+A request to stop sending ACK packets for each properly formatted packet.
+
+### Example
+
+A platform session will typically start like this:
+```
+receive: +$QStartNoAckMode#b0
+send: + <-- ACKing the properly formatted QStartNoAckMode packet
+send: $OK#9a
+receive: + <-- Our OK packet getting ACKed
+```
+
+ACK mode is now disabled.
+
+## qHostInfo
+
+### Brief
+
+Describe the hardware and OS of the target system
+
+### Example
+
+```
+receive: qHostInfo
+send: cputype:16777228;cpusubtype:1;ostype:ios;watchpoint_exceptions_received:before;os_version:12.1;vendor:apple;default_packet_timeout:5;
+```
+
+All numbers are base 10, `os_version` is a string that will be parsed as major.minor.patch.
+
+## qModuleInfo
+
+### Brief
+
+Get information for a module by given module path and architecture.
+
+The response is:
+* `(uuid|md5):...;triple:...;file_offset:...;file_size...;` or
+* `EXX` - for any errors
+
+### Example
+
+```
+receive: qModuleInfo:2f62696e2f6c73;
+```
+
+## qGetWorkingDir
+
+### Brief
+
+Get the current working directory of the platform stub in
+ASCII hex encoding.
+
+### Example
+
+```
+receive: qGetWorkingDir
+send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
+```
+
+## QSetWorkingDir
+
+### Brief
+
+Set the current working directory of the platform stub in
+ASCII hex encoding.
+
+### Example
+
+```
+receive: QSetWorkingDir:2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
+send: OK
+```
+
+## qPlatform_mkdir
+
+### Brief
+
+Create a directory on the target system.
+
+### Example
+
+```
+receive: qPlatform_mkdir:000001fd,2f746d702f6131
+send: F0
+```
+
+request packet has the fields:
+ 1. mode bits in base 16
+ 2. file path in ascii-hex encoding
+
+response is F followed by the return value of the `mkdir()` call,
+base 16 encoded.
+
+## qPlatform_shell
+
+### Brief
+
+Run a shell command on the target system, return the output.
+
+### Example
+
+```
+receive: qPlatform_shell:6c73202f746d702f,0000000a
+send: F,0,0,<OUTPUT>
+```
+
+request packet has the fields:
+ 1. shell command ascii-hex encoded
+ 2. timeout
+ 3. working directory ascii-hex encoded (optional)
+
+Response is `F` followed by the return value of the command (base 16),
+followed by another number, followed by the output of the command
+in binary-escaped-data encoding.
+
+## qLaunchGDBServer
+
+### Brief
+
+Start a gdbserver process (`gdbserver`, `debugserver`, `lldb-server`)
+on the target system.
+
+### Example
+
+```
+receive: qLaunchGDBServer;host:<HOSTNAME_LLDB_IS_ON>;
+send: pid:1337;port:43001;
+```
+
+Request packet hostname field is not ascii-hex encoded. Hostnames
+don't have `$` or `#` characters in them.
+
+Response to the packet is the pid of the newly launched gdbserver,
+and the port it is listening for a connection on.
+
+When the testsuite is running, lldb may use the pid to kill off a
+debugserver that doesn't seem to be responding, etc.
+
+## qKillSpawnedProcess
+
+### Brief
+
+Kill a process running on the target system.
+
+### Example
+
+```
+receive: qKillSpawnedProcess:1337
+send: OK
+```
+The request packet has the process ID in base 10.
+
+## qProcessInfoPID:
+
+### Brief
+
+Gather information about a process running on the target
+
+### Example
+
+```
+receive: qProcessInfoPID:71964
+send: pid:71964;name:612e6f7574;
+```
+
+The request packet has the pid encoded in base 10.
+
+The reply has semicolon-separated `name:value` fields, two are
+shown here. `pid` is base 10 encoded. `name` is ascii hex encoded.
+lldb-server can reply with many additional fields, but this is probably
+enough for the testsuite.
+
+## qfProcessInfo
+
+### Brief
+
+Search the process table for processes matching criteria,
+respond with them in multiple packets.
+
+### Example
+
+```
+receive: qfProcessInfo:name_match:equals;name:6e6f70726f6365737365786973747377697468746869736e616d65;
+send: pid:3500;name:612e6f7574;
+```
+
+The request packet has a criteria to search for, followed by
+a specific name.
+
+| Key | Value | Description
+| ------------ | ---...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/89913
More information about the lldb-commits
mailing list