1Here is a brief overview of the packets that an lldb platform server 2needs to implement for the lldb testsuite to be run on a remote 3target device/system. 4 5These are almost all lldb extensions to the gdb-remote serial 6protocol. Many of the vFile: packets are described to the "Host 7I/O Packets" detailed in the gdb-remote protocol documentation, 8although the lldb platform extensions include packets that are not 9defined there (vFile:size:, vFile:mode:, vFile:symlink, vFile:chmod:). 10Most importantly, the flags that lldb passes to vFile:open: are 11incompatible with the flags that gdb specifies. 12 13 14//---------------------------------------------------------------------- 15// QStartNoAckMode 16// 17// BRIEF 18// A request to stop sending ACK packets for each properly formatted packet. 19// 20// EXAMPLE 21// A platform session will typically start like this: 22// 23// receive: +$QStartNoAckMode#b0 24// send: + <-- ACKing the properly formatted QStartNoAckMode packet 25// send: $OK#9a 26// receive: + <-- Our OK packet getting ACKed 27// 28// ACK mode is now disabled. 29 30//---------------------------------------------------------------------- 31// qHostInfo 32// 33// BRIEF 34// Describe the hardware and OS of the target system 35// 36// EXAMPLE 37// 38// receive: qHostInfo 39// send: cputype:16777228;cpusubtype:1;ostype:ios;watchpoint_exceptions_received:before;os_version:12.1;vendor:apple;default_packet_timeout:5; 40// 41// All numbers are base 10, os_version is a string that will be parsed as major.minor.patch. 42 43//---------------------------------------------------------------------- 44// qModuleInfo 45// 46// BRIEF 47// Report information about a binary on the target system 48// 49// EXAMPLE 50// receive: qModuleInfo:2f62696e2f6c73; 51// 52// FIXME finish this packet description, v. GDBRemoteCommunicationServerCommon::Handle_qModuleInfo 53 54 55//---------------------------------------------------------------------- 56// qGetWorkingDir 57// 58// BRIEF 59// Get the current working directory of the platform stub in 60// ASCII hex encoding. 61// 62// EXAMPLE 63// 64// receive: qGetWorkingDir 65// send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773 66 67 68 69//---------------------------------------------------------------------- 70// QSetWorkingDir: 71// 72// BRIEF 73// Set the current working directory of the platform stub in 74// ASCII hex encoding. 75// 76// EXAMPLE 77// 78// receive: QSetWorkingDir:2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773 79// send: OK 80 81//---------------------------------------------------------------------- 82// qPlatform_mkdir: 83// 84// BRIEF 85// Create a directory on the target system. 86// 87// EXAMPLE 88// 89// receive: qPlatform_mkdir:000001fd,2f746d702f6131 90// send: F0 91// 92// request packet has the fields: 93// 1. mode bits in base 16 94// 2. file path in ascii-hex encoding 95// 96// response is F followed by the return value of the mkdir() call, 97// base 16 encoded. 98 99//---------------------------------------------------------------------- 100// qPlatform_shell: 101// 102// BRIEF 103// Run a shell command on the target system, return the output. 104// 105// EXAMPLE 106// 107// receive: qPlatform_shell:6c73202f746d702f,0000000a 108// send: F,0,0,<OUTPUT> 109// 110// request packet has the fields: 111// 1. shell command ascii-hex encoded 112// 2. timeout 113// 3. {optional} working directory ascii-hex encoded 114// 115// Response is F followed by the return value of the command (base 16), 116// followed by another number, followed by the output of the command 117/ in binary-escaped-data encoding. 118 119//---------------------------------------------------------------------- 120// qLaunchGDBServer 121// 122// BRIEF 123// Start a gdbserver process (gdbserver, debugserver, lldb-server) 124// on the target system. 125// 126// EXAMPLE 127// 128// receive: qLaunchGDBServer;host:<HOSTNAME_LLDB_IS_ON>; 129// send: pid:1337;port:43001; 130// 131// request packet hostname field is not ascii-hex encoded. Hostnames 132// don't have $ or # characters in them. 133// 134// response to the packet is the pid of the newly launched gdbserver, 135// and the port it is listening for a connection on. 136// 137// When the testsuite is running, lldb may use the pid to kill off a 138// debugserver that doesn't seem to be responding, etc. 139 140//---------------------------------------------------------------------- 141// qKillSpawnedProcess: 142// 143// BRIEF 144// Kill a process running on the target system. 145// 146// EXAMPLE 147// 148// receive: qKillSpawnedProcess:1337 149// send: OK 150// 151// The request packet has the process ID in base 10. 152 153//---------------------------------------------------------------------- 154// qProcessInfoPID: 155// 156// BRIEF 157// Gather information about a process running on the target 158// 159// EXAMPLE 160// 161// receive: qProcessInfoPID:71964 162// send: pid:71964;name:612e6f7574; 163// 164// The request packet has the pid encoded in base 10. 165// 166// The reply has semicolon-separated name:value fields, two are 167// shown here. pid is base 10 encoded. name is ascii hex encoded. 168// lldb-server can reply with many additional fields, but I think 169// this is enough for the testsuite. 170 171//---------------------------------------------------------------------- 172// qfProcessInfo: 173// 174// BRIEF 175// Search the process table for processes matching criteria, 176// respond with them in multiple packets. 177// 178// EXAMPLE 179// 180// receive: qfProcessInfo:name_match:equals;name:6e6f70726f6365737365786973747377697468746869736e616d65; 181// send: pid:3500;name:612e6f7574; 182// 183// The request packet has a criteria to search for, followed by 184// a specific name. 185// 186// KEY VALUE DESCRIPTION 187// =========== ======== ================================================ 188// "name" ascii-hex An ASCII hex string that contains the name of 189// the process that will be matched. 190// "name_match" enum One of: "equals", "starts_with", "ends_with", 191// "contains" or "regex" 192// "pid" integer A string value containing the decimal process ID 193// "parent_pid" integer A string value containing the decimal parent 194// process ID 195// "uid" integer A string value containing the decimal user ID 196// "gid" integer A string value containing the decimal group ID 197// "euid" integer A string value containing the decimal effective user ID 198// "egid" integer A string value containing the decimal effective group ID 199// "all_users" bool A boolean value that specifies if processes should 200// be listed for all users, not just the user that the 201// platform is running as 202// "triple" ascii-hex An ASCII hex target triple string ("x86_64", 203// "x86_64-apple-macosx", "armv7-apple-ios") 204// 205// If no criteria is given, qfProcessInfo will request a list of every process. 206// 207// The lldb testsuite currently only uses name_match:equals and the 208// no-criteria mode to list every process. 209// 210// The response should include any information about the process that 211// can be retrieved in semicolon-separated name:value fields. 212// In this example, pid is base 10, name is ascii-hex encoded. 213// The testsuite seems to only require these two. 214// 215// This packet only responds with one process. To get further matches to 216// the search, qsProcessInfo should be sent. 217// 218// If no process match is found, Exx should be returned. 219// 220// Sample packet/response: 221// send packet: $qfProcessInfo#00 222// read packet: $pid:60001;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:7838365f36342d6170706c652d6d61636f7378;#00 223// send packet: $qsProcessInfo#00 224// read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:7838365f36342d6170706c652d6d61636f7378;#00 225// send packet: $qsProcessInfo#00 226// read packet: $E04#00 227 228//---------------------------------------------------------------------- 229// qsProcessInfo 230// 231// BRIEF 232// Return the next process info found by the most recent qfProcessInfo: 233// packet. 234// 235// EXAMPLE 236// 237// Continues to return the results of the qfProcessInfo. Once all matches 238// have been sent, Exx is returned to indicate end of matches. 239 240//---------------------------------------------------------------------- 241// qPathComplete 242// 243// BRIEF 244// Get a list of matched disk files/directories by passing a boolean flag 245// and a partial path. 246// 247// EXAMPLE 248// 249// receive: qPathComplete:0,6d61696e 250// send: M6d61696e2e637070 251// receive: qPathComplete:1,746573 252// send: M746573742f,74657374732f 253// 254// If the first argument is zero, the result should contain all 255// files (including directories) starting with the given path. If the 256// argument is one, the result should contain only directories. 257// 258// The result should be a comma-separated list of hex-encoded paths. 259// Paths denoting a directory should end with a directory separator ('/' or '\'). 260 261//---------------------------------------------------------------------- 262// vFile:size: 263// 264// BRIEF 265// Get the size of a file on the target system, filename in ASCII hex. 266// 267// EXAMPLE 268// 269// receive: vFile:size:2f746d702f61 270// send: Fc008 271// 272// response is "F" followed by the file size in base 16. 273// "F-1,errno" with the errno if an error occurs, base 16. 274 275 276//---------------------------------------------------------------------- 277// vFile:mode: 278// 279// BRIEF 280// Get the mode bits of a file on the target system, filename in ASCII hex. 281// 282// EXAMPLE 283// 284// receive: vFile:mode:2f746d702f61 285// send: F1ed 286// 287// response is "F" followed by the mode bits in base 16, this 0x1ed would 288// correspond to 0755 in octal. 289// "F-1,errno" with the errno if an error occurs, base 16. 290 291//---------------------------------------------------------------------- 292// vFile:unlink: 293// 294// BRIEF 295// Remove a file on the target system. 296// 297// EXAMPLE 298// 299// receive: vFile:unlink:2f746d702f61 300// send: F0 301// 302// Argument is a file path in ascii-hex encoding. 303// Response is "F" plus the return value of unlink(), base 16 encoding. 304// Return value may optionally be followed by a comma and the base16 305// value of errno if unlink failed. 306 307//---------------------------------------------------------------------- 308// vFile:symlink: 309// 310// BRIEF 311// Create a symbolic link (symlink, soft-link) on the target system. 312// 313// EXAMPLE 314// 315// receive: vFile:symlink:<SRC-FILE>,<DST-NAME> 316// send: F0,0 317// 318// Argument file paths are in ascii-hex encoding. 319// Response is "F" plus the return value of symlink(), base 16 encoding, 320// optionally followed by the value of errno if it failed, also base 16. 321 322//---------------------------------------------------------------------- 323// vFile:chmod: 324// qPlatform_chmod: 325// 326// BRIEF 327// Change the permission mode bits on a file on the target 328// 329// EXAMPLE 330// 331// receive: vFile:chmod:180,2f746d702f61 332// send: F0 333// 334// Arguments are the mode bits to set, base 16, and a file path in 335// ascii-hex encoding. 336// Response is "F" plus the return value of chmod(), base 16 encoding. 337// 338// I don't know why there are two packets for the same thing, v. 339// vFile:chmod:. 340 341//---------------------------------------------------------------------- 342// vFile:chmod: 343// 344// BRIEF 345// Change the permission mode bits on a file on the target 346// 347// EXAMPLE 348// 349// receive: vFile:chmod:180,2f746d702f61 350// send: F0 351// 352// Arguments are the mode bits to set, base 16, and a file path in 353// ascii-hex encoding. 354// Response is "F" plus the return value of chmod(), base 10 encoding. 355 356 357//---------------------------------------------------------------------- 358// vFile:open: 359// 360// BRIEF 361// Open a file on the remote system and return the file descriptor of it. 362// 363// EXAMPLE 364// 365// receive: vFile:open:2f746d702f61,00000001,00000180 366// send: F8 367// 368// request packet has the fields: 369// 1. ASCII hex encoded filename 370// 2. flags passed to the open call, base 16. 371// Note that these are not the oflags that open(2) takes, but 372// are the constant values in enum OpenOptions from lldb's File.h 373// 3. mode bits, base 16 374// 375// response is F followed by the opened file descriptor in base 16. 376// "F-1,errno" with the errno if an error occurs, base 16. 377// 378//---------------------------------------------------------------------- 379// vFile:close: 380// 381// BRIEF 382// Close a previously opened file descriptor. 383// 384// EXAMPLE 385// 386// receive: vFile:close:7 387// send: F0 388// 389// File descriptor is in base 16. 390// "F-1,errno" with the errno if an error occurs, 391// errno is base 16. 392 393 394//---------------------------------------------------------------------- 395// vFile:pread: 396// 397// BRIEF 398// Read data from an opened file descriptor. 399// 400// EXAMPLE 401// 402// receive: vFile:pread:7,1024,0 403// send: F4;a'b\00 404// 405// request packet has the fields: 406// 1. file descriptor, base 16 407// 2. number of bytes to be read, base 16 408// 3. offset into file to start from, base 16 409// 410// Response is F, followed by the number of bytes read (base 16), a 411// semicolon, followed by the data in the binary-escaped-data encoding. 412 413 414//---------------------------------------------------------------------- 415// vFile:pwrite: 416// 417// BRIEF 418// Write data to a previously opened file descriptor. 419// 420// EXAMPLE 421// 422// receive: vFile:pwrite:8,0,\cf\fa\ed\fe\0c\00\00 423// send: F1024 424// 425// request packet has the fields: 426// 1. file descriptor, base 16 427// 2. offset into file to start from, base 16 428// 3. binary-escaped-data to be written 429// 430// Response is F, followed by the number of bytes written (base 16) 431 432 433 434 435 436Finally, the platform must be able to launch processes so that debugserver 437can attach to them. To do this, the following packets should be handled: 438 439QSetDisableASLR 440QSetDetachOnError 441QSetSTDOUT 442QSetSTDERR 443QSetSTDIN 444QEnvironment 445QEnvironmentHexEncoded 446A 447qLaunchSuccess 448qProcessInfo 449 450Most of these are documented in the standard gdb-remote protocol 451and/or the lldb-gdb-remote.txt documentation. 452