================ @@ -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 `\`. ---------------- hawkinsw wrote:
```suggestion Paths denoting a directory should end with a directory separator (`/` or `\`). ``` https://github.com/llvm/llvm-project/pull/89913 _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
