llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-lldb Author: David Spickett (DavidSpickett) <details> <summary>Changes</summary> As before, script did most of the work, hand edits after that. There's a lot more we can do dedupe this and the packets doc, this will come in a follow up PR. --- Patch is 27.19 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/89913.diff 3 Files Affected: - (modified) lldb/docs/index.rst (+1) - (removed) lldb/docs/lldb-platform-packets.txt (-451) - (added) lldb/docs/resources/lldbplatformpackets.md (+482) ``````````diff 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 4cf575e5ee8adb..00000000000000 --- a/lldb/docs/lldb-platform-packets.txt +++ /dev/null @@ -1,451 +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 +| ------------ | ---... [truncated] `````````` </details> 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
