[Lldb-commits] [lldb] [lldb][Docs] Convert platform packets doc to Markdown (PR #89913)
David Spickett via lldb-commits
lldb-commits at lists.llvm.org
Thu Apr 25 00:48:50 PDT 2024
https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/89913
>From d9b8ee42dfb753012f2f7032d7fb2dfde3e440f0 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 24 Apr 2024 10:21:08 +0100
Subject: [PATCH 1/3] [lldb][Docs] Make formatting in platform packet doc
regular
---
lldb/docs/lldb-platform-packets.txt | 66 ++++++++++++++++++-----------
1 file changed, 42 insertions(+), 24 deletions(-)
diff --git a/lldb/docs/lldb-platform-packets.txt b/lldb/docs/lldb-platform-packets.txt
index 4cf575e5ee8adb..62c3e38d9521ac 100644
--- a/lldb/docs/lldb-platform-packets.txt
+++ b/lldb/docs/lldb-platform-packets.txt
@@ -26,6 +26,7 @@ incompatible with the flags that gdb specifies.
// receive: + <-- Our OK packet getting ACKed
//
// ACK mode is now disabled.
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
// qHostInfo
@@ -39,6 +40,7 @@ incompatible with the flags that gdb specifies.
// 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
@@ -50,6 +52,7 @@ incompatible with the flags that gdb specifies.
// receive: qModuleInfo:2f62696e2f6c73;
//
// FIXME finish this packet description, v. GDBRemoteCommunicationServerCommon::Handle_qModuleInfo
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
@@ -63,11 +66,12 @@ incompatible with the flags that gdb specifies.
//
// receive: qGetWorkingDir
// send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
-// QSetWorkingDir:
+// QSetWorkingDir
//
// BRIEF
// Set the current working directory of the platform stub in
@@ -77,9 +81,10 @@ incompatible with the flags that gdb specifies.
//
// receive: QSetWorkingDir:2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
// send: OK
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
-// qPlatform_mkdir:
+// qPlatform_mkdir
//
// BRIEF
// Create a directory on the target system.
@@ -95,9 +100,10 @@ incompatible with the flags that gdb specifies.
//
// response is F followed by the return value of the mkdir() call,
// base 16 encoded.
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
-// qPlatform_shell:
+// qPlatform_shell
//
// BRIEF
// Run a shell command on the target system, return the output.
@@ -114,7 +120,8 @@ incompatible with the flags that gdb specifies.
//
// 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.
+// in binary-escaped-data encoding.
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
// qLaunchGDBServer
@@ -136,9 +143,10 @@ incompatible with the flags that gdb specifies.
//
// When the testsuite is running, lldb may use the pid to kill off a
// debugserver that doesn't seem to be responding, etc.
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
-// qKillSpawnedProcess:
+// qKillSpawnedProcess
//
// BRIEF
// Kill a process running on the target system.
@@ -149,6 +157,7 @@ incompatible with the flags that gdb specifies.
// send: OK
//
// The request packet has the process ID in base 10.
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
// qProcessInfoPID:
@@ -167,9 +176,10 @@ incompatible with the flags that gdb specifies.
// 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:
+// qfProcessInfo
//
// BRIEF
// Search the process table for processes matching criteria,
@@ -224,6 +234,7 @@ incompatible with the flags that gdb specifies.
// 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
@@ -236,6 +247,7 @@ incompatible with the flags that gdb specifies.
//
// Continues to return the results of the qfProcessInfo. Once all matches
// have been sent, Exx is returned to indicate end of matches.
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
// qPathComplete
@@ -257,9 +269,10 @@ incompatible with the flags that gdb specifies.
//
// 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:
+// vFile:size
//
// BRIEF
// Get the size of a file on the target system, filename in ASCII hex.
@@ -271,10 +284,11 @@ incompatible with the flags that gdb specifies.
//
// 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:
+// vFile:mode
//
// BRIEF
// Get the mode bits of a file on the target system, filename in ASCII hex.
@@ -287,9 +301,10 @@ incompatible with the flags that gdb specifies.
// 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:
+// vFile:unlink
//
// BRIEF
// Remove a file on the target system.
@@ -303,9 +318,10 @@ incompatible with the flags that gdb specifies.
// 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:
+// vFile:symlink
//
// BRIEF
// Create a symbolic link (symlink, soft-link) on the target system.
@@ -318,10 +334,11 @@ incompatible with the flags that gdb specifies.
// 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:
+// vFile:chmod
+// qPlatform_chmod
//
// BRIEF
// Change the permission mode bits on a file on the target
@@ -337,9 +354,10 @@ incompatible with the flags that gdb specifies.
//
// I don't know why there are two packets for the same thing, v.
// vFile:chmod:.
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
-// vFile:chmod:
+// vFile:chmod
//
// BRIEF
// Change the permission mode bits on a file on the target
@@ -352,10 +370,10 @@ incompatible with the flags that gdb specifies.
// 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:
+// vFile:open
//
// BRIEF
// Open a file on the remote system and return the file descriptor of it.
@@ -376,7 +394,10 @@ incompatible with the flags that gdb specifies.
// "F-1,errno" with the errno if an error occurs, base 16.
//
//----------------------------------------------------------------------
-// vFile:close:
+
+
+//----------------------------------------------------------------------
+// vFile:close
//
// BRIEF
// Close a previously opened file descriptor.
@@ -389,10 +410,10 @@ incompatible with the flags that gdb specifies.
// File descriptor is in base 16.
// "F-1,errno" with the errno if an error occurs,
// errno is base 16.
-
+//----------------------------------------------------------------------
//----------------------------------------------------------------------
-// vFile:pread:
+// vFile:pread
//
// BRIEF
// Read data from an opened file descriptor.
@@ -409,10 +430,10 @@ incompatible with the flags that gdb specifies.
//
// 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:
+// vFile:pwrite
//
// BRIEF
// Write data to a previously opened file descriptor.
@@ -428,10 +449,7 @@ incompatible with the flags that gdb specifies.
// 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:
>From e7c789360390b05af27321e7f0e23502a5fdbae7 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 24 Apr 2024 10:25:01 +0100
Subject: [PATCH 2/3] [lldb][Docs] Convert platform packets doc to Markdown
And add it to the website.
This is mostly a script conversion, with hand editing added
after.
---
lldb/docs/index.rst | 1 +
lldb/docs/lldb-platform-packets.txt | 469 --------------------
lldb/docs/resources/lldbplatformpackets.md | 482 +++++++++++++++++++++
3 files changed, 483 insertions(+), 469 deletions(-)
delete mode 100644 lldb/docs/lldb-platform-packets.txt
create mode 100644 lldb/docs/resources/lldbplatformpackets.md
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 62c3e38d9521ac..00000000000000
--- a/lldb/docs/lldb-platform-packets.txt
+++ /dev/null
@@ -1,469 +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
+| ------------ | --------- | -----------
+| `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.
+
+These 2 packets do the same thing, it is not known why we ended up with 2.
+
+## 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`](https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Host/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).
+
+## Launching Processes
+
+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 LLDB's [GDB Remote Protocol Extensions](lldbgdbremote).
>From a176697907c8c57e3d4acfc62283718ceefeec1e Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Thu, 25 Apr 2024 08:48:14 +0100
Subject: [PATCH 3/3] misc corrections from Will Hawkins
---
lldb/docs/resources/lldbplatformpackets.md | 30 ++++++++++++----------
1 file changed, 16 insertions(+), 14 deletions(-)
diff --git a/lldb/docs/resources/lldbplatformpackets.md b/lldb/docs/resources/lldbplatformpackets.md
index bebc6618fb68ac..326dd5669f7914 100644
--- a/lldb/docs/resources/lldbplatformpackets.md
+++ b/lldb/docs/resources/lldbplatformpackets.md
@@ -1,4 +1,5 @@
# 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.
@@ -104,7 +105,7 @@ send: F0
request packet has the fields:
1. mode bits in base 16
- 2. file path in ascii-hex encoding
+ 2. file path in ASCII hex encoding
response is F followed by the return value of the `mkdir()` call,
base 16 encoded.
@@ -123,9 +124,9 @@ send: F,0,0,<OUTPUT>
```
request packet has the fields:
- 1. shell command ascii-hex encoded
+ 1. shell command in ASCII hex encoding
2. timeout
- 3. working directory ascii-hex encoded (optional)
+ 3. working directory in ASCII hex encoding (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
@@ -145,8 +146,8 @@ 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.
+Request packet hostname field is not ASCII hex encoded. Hostnames
+do not 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.
@@ -172,7 +173,7 @@ The request packet has the process ID in base 10.
### Brief
-Gather information about a process running on the target
+Gather information about a process running on the target.
### Example
@@ -225,7 +226,7 @@ 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.
+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
@@ -276,13 +277,13 @@ 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 `\`.
+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.
+Get the size of a file on the target system, filename in ASCII hex encoding.
### Example
@@ -325,9 +326,10 @@ 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.
+
+Response is `F` plus the return value of `unlink()` in base 16 encoding.
+If unlink failed, the return value may be followed by a comma and the value of
+errno in base 16 encoding.
## vFile:symlink
@@ -440,7 +442,7 @@ Request packet has the fields:
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
+Response is `F`, followed by the number of bytes read (base 16 encoded), a
semicolon, followed by the data in the binary-escaped-data encoding.
## vFile:pwrite
@@ -461,7 +463,7 @@ Request packet has the fields:
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).
+Response is `F`, followed by the number of bytes written (base 16 encoded).
## Launching Processes
More information about the lldb-commits
mailing list