[Lldb-commits] [lldb] [lldb][Docs] Convert platform packets doc to Markdown (PR #89913)

[Will Hawkins via lldb-commits]

================
@@ -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.
----------------
hawkinsw wrote:

```suggestion
In this example, `pid` is base 10, `name` is ASCII hex encoded.
```

https://github.com/llvm/llvm-project/pull/89913