[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
----------------
hawkinsw wrote:

```suggestion
Request packet hostname field is not ASCII hex encoded. Hostnames
```

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