[lldb][Docs] Link from platform doc to extensions doc

[DavidSpickett]

So we aren't describing the same packets twice. Basically turning the platform doc into a list of cross links.

qLaunchSuccess was missing a description so I added one.

[llvmbot]

@llvm/pr-subscribers-lldb

Author: David Spickett (DavidSpickett)

Changes

So we aren't describing the same packets twice. Basically turning the platform doc into a list of cross links.

qLaunchSuccess was missing a description so I added one.

The links will have text generated from the link title, though they may not show up in GitHub's preview. Easier than writing out all the names again though.

---

Patch is 20.60 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/90029.diff

2 Files Affected:

• (modified) lldb/docs/resources/lldbgdbremote.md (+226-1)
• (modified) lldb/docs/resources/lldbplatformpackets.md (+40-474)

diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index cbe5c766d61eef..9a1032818af021 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -130,6 +130,21 @@ The above packet helps when you have remote debugging abilities where you
 could launch a process on a remote host, this isn't needed for bare board
 debugging.
 
+## qLaunchSuccess
+
+### Brief
+
+Check whether launching a process with the `A` packet succeeded.
+
+### Description
+
+Returns the status of the last attempt to launch a process.
+Either `OK` if no error ocurred, or `E` followed by a string
+describing the error.
+
+### Priority To Implement
+
+High, launching processes is a key part of LLDB's platform mode.
 
 ## QEnvironment:NAME=VALUE
 
@@ -263,6 +278,20 @@ QSetWorkingDir:<ascii-hex-path>
 ```
 This packet must be sent  _prior_ to sending a "A" packet.
 
+## qGetWorkingDir
+
+### Brief
+
+Get the current working directory of the platform stub in
+ASCII hex encoding.
+
+### Example
+
+```
+receive: qGetWorkingDir
+send:    2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
+```
+
 ## QSetDisableASLR:\<bool\>
 
 ### Brief
@@ -1029,13 +1058,17 @@ a remote host.
 
 Request: `qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path>`
 
+The request packet has the fields:
+   1. mode bits in base 16
+   2. file path in ascii-hex encoding
+
 Reply: 
   * `F<mkdir-return-code>`
     (mkdir called successfully and returned with the given return code)
   * `Exx` (An error occurred)
 
 
-## qPlatform_chmod
+## vFile:chmod / qPlatform_chmod
 
 ### Brief
 
@@ -1900,6 +1933,43 @@ send packet: $qsProcessInfo#00
 read packet: $E04#00
 ```
 
+## qPathComplete (Platform Extension)
+
+### 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 `\`.
+
+## qKillSpawnedProcess (Platform Extension)
+
+### 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.
+
 ## qLaunchGDBServer (Platform Extension)
 
 ### Brief
@@ -2397,3 +2467,158 @@ STUB REPLIES: {"process_state_value":48,"process_state string":"dyld_process_sta
 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.
+
+## vFile Packets
+
+Though some of these may match the ones described in GDB's protocol
+documentation, we include our own expectations here in case of
+mismatches or extensions.
+
+### 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: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).
\ No newline at end of file
diff --git a/lldb/docs/resources/lldbplatformpackets.md b/lldb/docs/resources/lldbplatformpackets.md
index 326dd5669f7914..91a488a1a6a4b5 100644
--- a/lldb/docs/resources/lldbplatformpackets.md
+++ b/lldb/docs/resources/lldbplatformpackets.md
@@ -1,484 +1,50 @@
 # LLDB Platform Packets
 
-Here is a brief overview of the packets that an lldb platform server
+This is a list 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
+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 in ASCII hex encoding
-   2. timeout
-   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
-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
-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.
-
-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 encoding.
-
-### 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()` 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
-
-### 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 encoded), 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 encoded).
-
-## 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).
+Most importantly, the flags that LLDB passes to `vFile:open:` are
+incompatible with the flags that GDB specifies.
+
+* [](./lldbgdbremote.md#qstartnoackmode)
+* [](./lldbgdbremote.md#qhostinfo)
+* [](./lldbgdbremote.md#qmoduleinfo-module-path-arch-triple)
+* [](./lldbgdbremote.md#qgetworkingdir)
+* [](./lldbgdbremote.md#qsetworkingdir-ascii-hex-path)
+* [](./lldbgdbremote.md#qplatform-mkdir)
+* [](./lldbgdbremote.md#qplatform-shell)
+* [](./lldbgdbremote.md#qlaunchgdbserver-platform-extension)
+* [](./lldbgdbremote.md#qkillspawnedprocess-platform-extension)
+* [](./lldbgdbremote.md#qprocessinfopid-pid-platform-extension)
+  * It is likely that you only need to support the `pid` and `name` fields.
+* [](./lldbgdbremote.md#qprocessinfopid-pid-platform-extension)
+  * The lldb test suite currently only uses `name_match:equals` and the no-criteria mode to list every process.
+* [](./lldbgdbremote.md#qprocessinfopid-pid-platform-extension)
+* [](./lldbgdbremote.md#vfile-chmod-qplatform-chmod)
+* [](./lldbgdbremote.md#qpathcomplete-platform-extension)
+* [](./lldbgdbremote.md#vfile-size)
+* [](./lldbgdbremote.md#vfile-mode)
+* [](./lldbgdbremote.md#vfile-unlink)
+* [](./lldbgdbremote.md#vfile-symlink)
+* [](./lldbgdbremote.md#vfile-open)
+* [](./lldbgdbremote.md#vfile-close)
+* [](./lldbgdbremote.md#vfile-pread)...
[truncated]

[DavidSpickett]

I'll remove the "Brief" subtitles after this.

[DavidSpickett]

You can leave titles to be automatic by doing [](... but then Github leaves them blank which defeats the point of Markdown being nice to edit on Github.