1 LLDB has added new GDB server packets to better support multi-threaded and 2 remote debugging. Why? Normally you need to start the correct GDB and the 3 correct GDB server when debugging. If you have mismatch, then things go wrong 4 very quickly. LLDB makes extensive use of the GDB remote protocol and we 5 wanted to make sure that the experience was a bit more dynamic where we can 6 discover information about a remote target with having to know anything up 7 front. We also ran into performance issues with the existing GDB remote 8 protocol that can be overcome when using a reliable communications layer. 9 Some packets improve performance, others allow for remote process launching 10 (if you have an OS), and others allow us to dynamically figure out what 11 registers a thread might have. Again with GDB, both sides pre-agree on how the 12 registers will look (how many, their register number,name and offsets). We 13 prefer to be able to dynamically determine what kind of architecture, os and 14 vendor we are debugging, as well as how things are laid out when it comes to 15 the thread register contexts. Below are the details on the new packets we have 16 added above and beyond the standard GDB remote protocol packets. 17 18 //---------------------------------------------------------------------- 19 // "QStartNoAckMode" 20 // 21 // BRIEF 22 // Try to enable no ACK mode to skip sending ACKs and NACKs. 23 // 24 // PRIORITY TO IMPLEMENT 25 // High. Any GDB remote server that can implement this should if the 26 // connection is reliable. This improves packet throughput and increases 27 // the performance of the connection. 28 //---------------------------------------------------------------------- 29 Having to send an ACK/NACK after every packet slows things down a bit, so we 30 have a way to disable ACK packets to minimize the traffic for reliable 31 communication interfaces (like sockets). Below GDB or LLDB will send this 32 packet to try and disable ACKs. All lines that start with "send packet: " are 33 from GDB/LLDB, and all lines that start with "read packet: " are from the GDB 34 remote server: 35 36 send packet: $QStartNoAckMode#b0 37 read packet: + 38 read packet: $OK#9a 39 send packet: + 40 41 42 43 //---------------------------------------------------------------------- 44 // "A" - launch args packet 45 // 46 // BRIEF 47 // Launch a program using the supplied arguments 48 // 49 // PRIORITY TO IMPLEMENT 50 // Low. Only needed if the remote target wants to launch a target after 51 // making a connection to a GDB server that isn't already connected to 52 // an inferior process. 53 //---------------------------------------------------------------------- 54 55 We have added support for the "set program arguments" packet where we can 56 startup a connection to a remote server and then later supply the path to the 57 executable and the arguments to use when executing: 58 59 GDB remote docs for this: 60 61 set program arguments(reserved) Aarglen,argnum,arg,... 62 63 Where A is followed by the length in bytes of the hex encoded argument, 64 followed by an argument integer, and followed by the ASCII characters 65 converted into hex bytes foreach arg 66 67 send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00 68 read packet: $OK#00 69 70 The above packet helps when you have remote debugging abilities where you 71 could launch a process on a remote host, this isn't needed for bare board 72 debugging. 73 74 //---------------------------------------------------------------------- 75 // "QEnvironment:NAME=VALUE" 76 // 77 // BRIEF 78 // Setup the environment up for a new child process that will soon be 79 // launched using the "A" packet. 80 // 81 // PRIORITY TO IMPLEMENT 82 // Low. Only needed if the remote target wants to launch a target after 83 // making a connection to a GDB server that isn't already connected to 84 // an inferior process. 85 //---------------------------------------------------------------------- 86 87 Both GDB and LLDB support passing down environment variables. Is it ok to 88 respond with a "$#00" (unimplemented): 89 90 send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00 91 read packet: $OK#00 92 93 This packet can be sent one or more times _prior_ to sending a "A" packet. 94 95 //---------------------------------------------------------------------- 96 // "QSetSTDIN:<ascii-hex-path>" 97 // "QSetSTDOUT:<ascii-hex-path>" 98 // "QSetSTDERR:<ascii-hex-path>" 99 // 100 // BRIEF 101 // Setup where STDIN, STDOUT, and STDERR go prior to sending an "A" 102 // packet. 103 // 104 // PRIORITY TO IMPLEMENT 105 // Low. Only needed if the remote target wants to launch a target after 106 // making a connection to a GDB server that isn't already connected to 107 // an inferior process. 108 //---------------------------------------------------------------------- 109 110 When launching a program through the GDB remote protocol with the "A" packet, 111 you might also want to specify where stdin/out/err go: 112 113 QSetSTDIN:<ascii-hex-path> 114 QSetSTDOUT:<ascii-hex-path> 115 QSetSTDERR:<ascii-hex-path> 116 117 These packets must be sent _prior_ to sending a "A" packet. 118 119 //---------------------------------------------------------------------- 120 // "QSetWorkingDir:<ascii-hex-path>" 121 // 122 // BRIEF 123 // Set the working directory prior to sending an "A" packet. 124 // 125 // PRIORITY TO IMPLEMENT 126 // Low. Only needed if the remote target wants to launch a target after 127 // making a connection to a GDB server that isn't already connected to 128 // an inferior process. 129 //---------------------------------------------------------------------- 130 131 Or specify the working directory: 132 133 QSetWorkingDir:<ascii-hex-path> 134 135 This packet must be sent _prior_ to sending a "A" packet. 136 137 //---------------------------------------------------------------------- 138 // "QSetDisableASLR:<bool>" 139 // 140 // BRIEF 141 // Enable or disable ASLR on the next "A" packet. 142 // 143 // PRIORITY TO IMPLEMENT 144 // Low. Only needed if the remote target wants to launch a target after 145 // making a connection to a GDB server that isn't already connected to 146 // an inferior process and if the target supports disabling ASLR 147 // (Address space layout randomization). 148 //---------------------------------------------------------------------- 149 150 Or control if ASLR is enabled/disabled: 151 152 send packet: QSetDisableASLR:1 153 read packet: OK 154 155 send packet: QSetDisableASLR:0 156 read packet: OK 157 158 This packet must be sent _prior_ to sending a "A" packet. 159 160 //---------------------------------------------------------------------- 161 // "qRegisterInfo<hex-reg-id>" 162 // 163 // BRIEF 164 // Discover register information from the remote GDB server. 165 // 166 // PRIORITY TO IMPLEMENT 167 // High. Any target that can self describe its registers, should do so. 168 // This means if new registers are ever added to a remote target, they 169 // will get picked up automatically, and allows registers to change 170 // depending on the actual CPU type that is used. 171 //---------------------------------------------------------------------- 172 173 With LLDB, for register information, remote GDB servers can add support for 174 the "qRegisterInfoN" packet where "N" is a zero based register number that 175 must start at zero and increase by one for each register that is supported. 176 The response is done in typical GDB remote fashion where a serious of 177 "KEY:VALUE;" pairs are returned. An example for the x86_64 registers is 178 included below: 179 180 send packet: $qRegisterInfo0#00 181 read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00 182 send packet: $qRegisterInfo1#00 183 read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00 184 send packet: $qRegisterInfo2#00 185 read packet: $name:rcx;bitsize:64;offset:16;encoding:uint;format:hex;set:General Purpose Registers;gcc:2;dwarf:2;#00 186 send packet: $qRegisterInfo3#00 187 read packet: $name:rdx;bitsize:64;offset:24;encoding:uint;format:hex;set:General Purpose Registers;gcc:1;dwarf:1;#00 188 send packet: $qRegisterInfo4#00 189 read packet: $name:rdi;bitsize:64;offset:32;encoding:uint;format:hex;set:General Purpose Registers;gcc:5;dwarf:5;#00 190 send packet: $qRegisterInfo5#00 191 read packet: $name:rsi;bitsize:64;offset:40;encoding:uint;format:hex;set:General Purpose Registers;gcc:4;dwarf:4;#00 192 send packet: $qRegisterInfo6#00 193 read packet: $name:rbp;alt-name:fp;bitsize:64;offset:48;encoding:uint;format:hex;set:General Purpose Registers;gcc:6;dwarf:6;generic:fp;#00 194 send packet: $qRegisterInfo7#00 195 read packet: $name:rsp;alt-name:sp;bitsize:64;offset:56;encoding:uint;format:hex;set:General Purpose Registers;gcc:7;dwarf:7;generic:sp;#00 196 send packet: $qRegisterInfo8#00 197 read packet: $name:r8;bitsize:64;offset:64;encoding:uint;format:hex;set:General Purpose Registers;gcc:8;dwarf:8;#00 198 send packet: $qRegisterInfo9#00 199 read packet: $name:r9;bitsize:64;offset:72;encoding:uint;format:hex;set:General Purpose Registers;gcc:9;dwarf:9;#00 200 send packet: $qRegisterInfoa#00 201 read packet: $name:r10;bitsize:64;offset:80;encoding:uint;format:hex;set:General Purpose Registers;gcc:10;dwarf:10;#00 202 send packet: $qRegisterInfob#00 203 read packet: $name:r11;bitsize:64;offset:88;encoding:uint;format:hex;set:General Purpose Registers;gcc:11;dwarf:11;#00 204 send packet: $qRegisterInfoc#00 205 read packet: $name:r12;bitsize:64;offset:96;encoding:uint;format:hex;set:General Purpose Registers;gcc:12;dwarf:12;#00 206 send packet: $qRegisterInfod#00 207 read packet: $name:r13;bitsize:64;offset:104;encoding:uint;format:hex;set:General Purpose Registers;gcc:13;dwarf:13;#00 208 send packet: $qRegisterInfoe#00 209 read packet: $name:r14;bitsize:64;offset:112;encoding:uint;format:hex;set:General Purpose Registers;gcc:14;dwarf:14;#00 210 send packet: $qRegisterInfof#00 211 read packet: $name:r15;bitsize:64;offset:120;encoding:uint;format:hex;set:General Purpose Registers;gcc:15;dwarf:15;#00 212 send packet: $qRegisterInfo10#00 213 read packet: $name:rip;alt-name:pc;bitsize:64;offset:128;encoding:uint;format:hex;set:General Purpose Registers;gcc:16;dwarf:16;generic:pc;#00 214 send packet: $qRegisterInfo11#00 215 read packet: $name:rflags;alt-name:flags;bitsize:64;offset:136;encoding:uint;format:hex;set:General Purpose Registers;#00 216 send packet: $qRegisterInfo12#00 217 read packet: $name:cs;bitsize:64;offset:144;encoding:uint;format:hex;set:General Purpose Registers;#00 218 send packet: $qRegisterInfo13#00 219 read packet: $name:fs;bitsize:64;offset:152;encoding:uint;format:hex;set:General Purpose Registers;#00 220 send packet: $qRegisterInfo14#00 221 read packet: $name:gs;bitsize:64;offset:160;encoding:uint;format:hex;set:General Purpose Registers;#00 222 send packet: $qRegisterInfo15#00 223 read packet: $name:fctrl;bitsize:16;offset:176;encoding:uint;format:hex;set:Floating Point Registers;#00 224 send packet: $qRegisterInfo16#00 225 read packet: $name:fstat;bitsize:16;offset:178;encoding:uint;format:hex;set:Floating Point Registers;#00 226 send packet: $qRegisterInfo17#00 227 read packet: $name:ftag;bitsize:8;offset:180;encoding:uint;format:hex;set:Floating Point Registers;#00 228 send packet: $qRegisterInfo18#00 229 read packet: $name:fop;bitsize:16;offset:182;encoding:uint;format:hex;set:Floating Point Registers;#00 230 send packet: $qRegisterInfo19#00 231 read packet: $name:fioff;bitsize:32;offset:184;encoding:uint;format:hex;set:Floating Point Registers;#00 232 send packet: $qRegisterInfo1a#00 233 read packet: $name:fiseg;bitsize:16;offset:188;encoding:uint;format:hex;set:Floating Point Registers;#00 234 send packet: $qRegisterInfo1b#00 235 read packet: $name:fooff;bitsize:32;offset:192;encoding:uint;format:hex;set:Floating Point Registers;#00 236 send packet: $qRegisterInfo1c#00 237 read packet: $name:foseg;bitsize:16;offset:196;encoding:uint;format:hex;set:Floating Point Registers;#00 238 send packet: $qRegisterInfo1d#00 239 read packet: $name:mxcsr;bitsize:32;offset:200;encoding:uint;format:hex;set:Floating Point Registers;#00 240 send packet: $qRegisterInfo1e#00 241 read packet: $name:mxcsrmask;bitsize:32;offset:204;encoding:uint;format:hex;set:Floating Point Registers;#00 242 send packet: $qRegisterInfo1f#00 243 read packet: $name:stmm0;bitsize:80;offset:208;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:33;dwarf:33;#00 244 send packet: $qRegisterInfo20#00 245 read packet: $name:stmm1;bitsize:80;offset:224;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:34;dwarf:34;#00 246 send packet: $qRegisterInfo21#00 247 read packet: $name:stmm2;bitsize:80;offset:240;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:35;dwarf:35;#00 248 send packet: $qRegisterInfo22#00 249 read packet: $name:stmm3;bitsize:80;offset:256;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:36;dwarf:36;#00 250 send packet: $qRegisterInfo23#00 251 read packet: $name:stmm4;bitsize:80;offset:272;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:37;dwarf:37;#00 252 send packet: $qRegisterInfo24#00 253 read packet: $name:stmm5;bitsize:80;offset:288;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:38;dwarf:38;#00 254 send packet: $qRegisterInfo25#00 255 read packet: $name:stmm6;bitsize:80;offset:304;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:39;dwarf:39;#00 256 send packet: $qRegisterInfo26#00 257 read packet: $name:stmm7;bitsize:80;offset:320;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:40;dwarf:40;#00 258 send packet: $qRegisterInfo27#00 259 read packet: $name:xmm0;bitsize:128;offset:336;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:17;dwarf:17;#00 260 send packet: $qRegisterInfo28#00 261 read packet: $name:xmm1;bitsize:128;offset:352;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:18;dwarf:18;#00 262 send packet: $qRegisterInfo29#00 263 read packet: $name:xmm2;bitsize:128;offset:368;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:19;dwarf:19;#00 264 send packet: $qRegisterInfo2a#00 265 read packet: $name:xmm3;bitsize:128;offset:384;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:20;dwarf:20;#00 266 send packet: $qRegisterInfo2b#00 267 read packet: $name:xmm4;bitsize:128;offset:400;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:21;dwarf:21;#00 268 send packet: $qRegisterInfo2c#00 269 read packet: $name:xmm5;bitsize:128;offset:416;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:22;dwarf:22;#00 270 send packet: $qRegisterInfo2d#00 271 read packet: $name:xmm6;bitsize:128;offset:432;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:23;dwarf:23;#00 272 send packet: $qRegisterInfo2e#00 273 read packet: $name:xmm7;bitsize:128;offset:448;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:24;dwarf:24;#00 274 send packet: $qRegisterInfo2f#00 275 read packet: $name:xmm8;bitsize:128;offset:464;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:25;dwarf:25;#00 276 send packet: $qRegisterInfo30#00 277 read packet: $name:xmm9;bitsize:128;offset:480;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:26;dwarf:26;#00 278 send packet: $qRegisterInfo31#00 279 read packet: $name:xmm10;bitsize:128;offset:496;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:27;dwarf:27;#00 280 send packet: $qRegisterInfo32#00 281 read packet: $name:xmm11;bitsize:128;offset:512;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:28;dwarf:28;#00 282 send packet: $qRegisterInfo33#00 283 read packet: $name:xmm12;bitsize:128;offset:528;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:29;dwarf:29;#00 284 send packet: $qRegisterInfo34#00 285 read packet: $name:xmm13;bitsize:128;offset:544;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:30;dwarf:30;#00 286 send packet: $qRegisterInfo35#00 287 read packet: $name:xmm14;bitsize:128;offset:560;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:31;dwarf:31;#00 288 send packet: $qRegisterInfo36#00 289 read packet: $name:xmm15;bitsize:128;offset:576;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:32;dwarf:32;#00 290 send packet: $qRegisterInfo37#00 291 read packet: $name:trapno;bitsize:32;offset:696;encoding:uint;format:hex;set:Exception State Registers;#00 292 send packet: $qRegisterInfo38#00 293 read packet: $name:err;bitsize:32;offset:700;encoding:uint;format:hex;set:Exception State Registers;#00 294 send packet: $qRegisterInfo39#00 295 read packet: $name:faultvaddr;bitsize:64;offset:704;encoding:uint;format:hex;set:Exception State Registers;#00 296 send packet: $qRegisterInfo3a#00 297 read packet: $E45#00 298 299 As we see above we keep making subsequent calls to the remote server to 300 discover all registers by increasing the number appended to qRegisterInfo and 301 we get a response back that is a series of "key=value;" strings. The keys and 302 values are detailed below: 303 304 Key Value 305 ========== ================================================================ 306 name The primary register name as a string ("rbp" for example) 307 308 alt-name An alternate name for a register as a string ("fp" for example for 309 the above "rbp") 310 311 bitsize Size in bits of a register (32, 64, etc) 312 313 offset The offset within the "g" and "G" packet of the register data for 314 this register 315 316 encoding The encoding type of the register which must be one of: 317 318 uint (unsigned integer) 319 sint (signed integer) 320 ieee754 (IEEE 754 float) 321 vector (vector regsiter) 322 323 format The preferred format for display of this register. The value must 324 be one of: 325 326 binary 327 decimal 328 hex 329 float 330 vector-sint8 331 vector-uint8 332 vector-sint16 333 vector-uint16 334 vector-sint32 335 vector-uint32 336 vector-float32 337 vector-uint128 338 339 set The register set name as a string that this register belongs to. 340 341 gcc The GCC compiler registers number for this register (used for 342 EH frame and other compiler information that is encoded in the 343 executable files). The supplied number will be decoded like a 344 string passed to strtoul() with a base of zero, so the number 345 can be decimal, or hex if it is prefixed with "0x". 346 347 NOTE: If the compiler doesn't have a register number for this 348 register, this key/value pair should be omitted. 349 350 dwarf The DWARF register number for this register that is used for this 351 register in the debug information. The supplied number will be decoded 352 like a string passed to strtoul() with a base of zero, so the number 353 can be decimal, or hex if it is prefixed with "0x". 354 355 NOTE: If the compiler doesn't have a register number for this 356 register, this key/value pair should be omitted. 357 358 generic If the register is a generic register that most CPUs have, classify 359 it correctly so the debugger knows. Valid values are one of: 360 pc (a program counter register. for example "name=eip;" (i386), 361 "name=rip;" (x86_64), "name=r15;" (32 bit arm) would 362 include a "generic=pc;" key value pair) 363 sp (a stack pointer register. for example "name=esp;" (i386), 364 "name=rsp;" (x86_64), "name=r13;" (32 bit arm) would 365 include a "generic=sp;" key value pair) 366 fp (a frame pointer register. for example "name=ebp;" (i386), 367 "name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx 368 ABI) would include a "generic=fp;" key value pair) 369 ra (a return address register. for example "name=lr;" (32 bit ARM) 370 would include a "generic=ra;" key value pair) 371 fp (a CPU flags register. for example "name=eflags;" (i386), 372 "name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM) 373 would include a "generic=flags;" key value pair) 374 arg1 - arg8 (specified for registers that contain function 375 arguments when the argument fits into a register) 376 377 container-regs 378 The value for this key is a comma separated list of raw hex (optional 379 leading "0x") register numbers. 380 381 This specifies that this register is contained in other concrete 382 register values. For example "eax" is in the lower 32 bits of the 383 "rax" register value for x86_64, so "eax" could specify that it is 384 contained in "rax" by specifying the register number for "rax" (whose 385 register number is 0x00) 386 387 "container-regs:00;" 388 389 If a register is comprised of one or more registers, like "d0" is ARM 390 which is a 64 bit register, it might be made up of "s0" and "s1". If 391 the register number for "s0" is 0x20, and the register number of "s1" 392 is "0x21", the "container-regs" key/value pair would be: 393 394 "container-regs:20,21;" 395 396 This is handy for defining what GDB used to call "pseudo" registers. 397 These registers are never requested by LLDB via the register read 398 or write packets, the container registers will be requested on behalf 399 of this register. 400 401 invalidate-regs 402 The value for this key is a comma separated list of raw hex (optional 403 leading "0x") register numbers. 404 405 This specifies which register values should be invalidated when this 406 register is modified. For example if modifying "eax" would cause "rax", 407 "eax", "ax", "ah", and "al" to be modified where rax is 0x0, eax is 0x15, 408 ax is 0x25, ah is 0x35, and al is 0x39, the "invalidate-regs" key/value 409 pair would be: 410 411 "invalidate-regs:0,15,25,35,39;" 412 413 If there is a single register that gets invalidated, then omit the comma 414 and just list a single register: 415 416 "invalidate-regs:0;" 417 418 This is handy when modifying a specific register can cause other 419 register values to change. For example, when debugging an ARM target, 420 modifying the CPSR register can cause the r8 - r14 and cpsr value to 421 change depending on if the mode has changed. 422 423 //---------------------------------------------------------------------- 424 // "qHostInfo" 425 // 426 // BRIEF 427 // Get information about the host we are remotely connected to. 428 // 429 // PRIORITY TO IMPLEMENT 430 // High. This packet is usually very easy to implement and can help 431 // LLDB select the correct plug-ins for the job based on the target 432 // triple information that is suppied. 433 //---------------------------------------------------------------------- 434 435 LLDB supports a host info call that gets all sorts of details of the system 436 that is being debugged: 437 438 send packet: $qHostInfo#00 439 read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00 440 441 Key value pairs are one of: 442 443 cputype: is a number that is the mach-o CPU type that is being debugged 444 cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged 445 ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) 446 vendor: is a string that represents the vendor (apple) 447 endian: is one of "little", "big", or "pdp" 448 ptrsize: is a number that represents how big pointers are in bytes on the debug target 449 450 //---------------------------------------------------------------------- 451 // "qProcessInfo" 452 // 453 // BRIEF 454 // Get information about the process we are currently debugging. 455 // 456 // PRIORITY TO IMPLEMENT 457 // Medium. On systems which can launch multiple different architecture processes, 458 // the qHostInfo may not disambiguate sufficiently to know what kind of 459 // process is being debugged. 460 // e.g. on a 64-bit x86 Mac system both 32-bit and 64-bit user processes are possible, 461 // and with Mach-O universal files, the executable file may contain both 32- and 462 // 64-bit slices so it may be impossible to know until you're attached to a real 463 // process to know what you're working with. 464 // 465 // All numeric fields return base-16 numbers without any "0x" prefix. 466 //---------------------------------------------------------------------- 467 468 An i386 process: 469 470 send packet: $qProcessInfo#00 471 read packet: $pid:42a8;parent-pid:42bf;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:7;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:4;#00 472 473 An x86_64 process: 474 475 send packet: $qProcessInfo#00 476 read packet: $pid:d22c;parent-pid:d34d;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:1000007;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:8;#00 477 478 Key value pairs include: 479 480 pid: the process id 481 parent-pid: the process of the parent process (often debugserver will become the parent when attaching) 482 real-uid: the real user id of the process 483 real-gid: the real group id of the process 484 effective-uid: the effective user id of the process 485 effective-gid: the effective group id of the process 486 cputype: the Mach-O CPU type of the process 487 cpusubtype: the Mach-O CPU subtype of the process 488 ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) 489 vendor: is a string that represents the vendor (apple) 490 endian: is one of "little", "big", or "pdp" 491 ptrsize: is a number that represents how big pointers are in bytes 492 493 494 //---------------------------------------------------------------------- 495 // "qShlibInfoAddr" 496 // 497 // BRIEF 498 // Get an address where the dynamic linker stores information about 499 // where shared libraries are loaded. 500 // 501 // PRIORITY TO IMPLEMENT 502 // High if you have a dynamic loader plug-in in LLDB for your target 503 // triple (see the "qHostInfo" packet) that can use this information. 504 // Many times address load randomization can make it hard to detect 505 // where the dynamic loader binary and data structures are located and 506 // some platforms know, or can find out where this information is. 507 // 508 // Low if you have a debug target where all object and symbol files 509 // contain static load addresses. 510 //---------------------------------------------------------------------- 511 512 LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each 513 debugger as to where to find the dynamic loader information. For darwin 514 binaries that run in user land this is the address of the "all_image_infos" 515 structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO 516 call. The result is returned as big endian hex bytes that are the address 517 value: 518 519 send packet: $qShlibInfoAddr#00 520 read packet: $7fff5fc40040#00 521 522 523 524 //---------------------------------------------------------------------- 525 // "qThreadStopInfo<tid>" 526 // 527 // BRIEF 528 // Get information about why a thread, whose ID is "<tid>", is stopped. 529 // 530 // PRIORITY TO IMPLEMENT 531 // High if you need to support multi-threaded or multi-core debugging. 532 // Many times one thread will hit a breakpoint and while the debugger 533 // is in the process of suspending the other threads, other threads 534 // will also hit a breakpoint. This packet allows LLDB to know why all 535 // threads (live system debug) / cores (JTAG) in your program have 536 // stopped and allows LLDB to display and control your program 537 // correctly. 538 //---------------------------------------------------------------------- 539 540 LLDB tries to use the "qThreadStopInfo" packet which is formatted as 541 "qThreadStopInfo%x" where %x is the hex thread ID. This requests information 542 about why a thread is stopped. The response is the same as the stop reply 543 packets and tells us what happened to the other threads. The standard GDB 544 remote packets love to think that there is only _one_ reason that _one_ thread 545 stops at a time. This allows us to see why all threads stopped and allows us 546 to implement better multi-threaded debugging support. 547 548 //---------------------------------------------------------------------- 549 // "QThreadSuffixSupported" 550 // 551 // BRIEF 552 // Try to enable thread suffix support for the 'g', 'G', 'p', and 'P' 553 // packets. 554 // 555 // PRIORITY TO IMPLEMENT 556 // High. Adding a thread suffix allows us to read and write registers 557 // more efficiently and stops us from having to select a thread with 558 // one packet and then read registers with a second packet. It also 559 // makes sure that no errors can occur where the debugger thinks it 560 // already has a thread selected (see the "Hg" packet from the standard 561 // GDB remote protocol documentation) yet the remote GDB server actually 562 // has another thread selected. 563 //---------------------------------------------------------------------- 564 565 When reading thread registers, you currently need to set the current 566 thread, then read the registers. This is kind of cumbersome, so we added the 567 ability to query if the remote GDB server supports adding a "thread:<tid>;" 568 suffix to all packets that request information for a thread. To test if the 569 remote GDB server supports this feature: 570 571 send packet: $QThreadSuffixSupported#00 572 read packet: OK 573 574 If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a 575 thread suffix. So to send a 'g' packet (read all register values): 576 577 send packet: $g;thread:<tid>;#00 578 read packet: .... 579 580 send packet: $G;thread:<tid>;#00 581 read packet: .... 582 583 send packet: $p1a;thread:<tid>;#00 584 read packet: .... 585 586 send packet: $P1a=1234abcd;thread:<tid>;#00 587 read packet: .... 588 589 590 otherwise, without this you would need to always send two packets: 591 592 send packet: $Hg<tid>#00 593 read packet: .... 594 send packet: $g#00 595 read packet: .... 596 597 We also added support for allocating and deallocating memory. We use this to 598 allocate memory so we can run JITed code. 599 600 //---------------------------------------------------------------------- 601 // "_M<size>,<permissions>" 602 // 603 // BRIEF 604 // Allocate memory on the remote target with the specified size and 605 // permissions. 606 // 607 // PRIORITY TO IMPLEMENT 608 // High if you want LLDB to be able to JIT code and run that code. JIT 609 // code also needs data which is also allocated and tracked. 610 // 611 // Low if you don't support running JIT'ed code. 612 //---------------------------------------------------------------------- 613 614 The allocate memory packet starts with "_M<size>,<permissions>". It returns a 615 raw big endian address value, or "" for unimplemented, or "EXX" for an error 616 code. The packet is formatted as: 617 618 char packet[256]; 619 int packet_len; 620 packet_len = ::snprintf ( 621 packet, 622 sizeof(packet), 623 "_M%zx,%s%s%s", 624 (size_t)size, 625 permissions & lldb::ePermissionsReadable ? "r" : "", 626 permissions & lldb::ePermissionsWritable ? "w" : "", 627 permissions & lldb::ePermissionsExecutable ? "x" : ""); 628 629 You request a size and give the permissions. This packet does NOT need to be 630 implemented if you don't want to support running JITed code. The return value 631 is just the address of the newly allocated memory as raw big endian hex bytes. 632 633 //---------------------------------------------------------------------- 634 // "_m<addr>" 635 // 636 // BRIEF 637 // Deallocate memory that was previously allocated using an allocate 638 // memory pack. 639 // 640 // PRIORITY TO IMPLEMENT 641 // High if you want LLDB to be able to JIT code and run that code. JIT 642 // code also needs data which is also allocated and tracked. 643 // 644 // Low if you don't support running JIT'ed code. 645 //---------------------------------------------------------------------- 646 647 The deallocate memory packet is "_m<addr>" where you pass in the address you 648 got back from a previous call to the allocate memory packet. It returns "OK" 649 if the memory was successfully deallocated, or "EXX" for an error, or "" if 650 not supported. 651 652 //---------------------------------------------------------------------- 653 // "qMemoryRegionInfo:<addr>" 654 // 655 // BRIEF 656 // Get information about the address the range that contains "<addr>" 657 // 658 // PRIORITY TO IMPLEMENT 659 // Medium. This is nice to have, but it isn't necessary. It helps LLDB 660 // do stack unwinding when we branch into memory that isn't executable. 661 // If we can detect that the code we are stopped in isn't executable, 662 // then we can recover registers for stack frames above the current 663 // frame. Otherwise we must assume we are in some JIT'ed code (not JIT 664 // code that LLDB has made) and assume that no registers are available 665 // in higher stack frames. 666 //---------------------------------------------------------------------- 667 668 We added a way to get information for a memory region. The packet is: 669 670 qMemoryRegionInfo:<addr> 671 672 Where <addr> is a big endian hex address. The response is returned in a series 673 of tuples like the data returned in a stop reply packet. The currently valid 674 tuples tp return are: 675 676 start:<start-addr>; // <start-addr> is a big endian hex address that is 677 // the start address of the range that contains <addr> 678 679 size:<size>; // <size> is a big endian hex byte size of the address 680 // of the range that contains <addr> 681 682 permissions:<permissions>; // <permissions> is a string that contains one 683 // or more of the characters from "rwx" 684 685 error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is 686 // a hex encoded string value that 687 // contains an error string 688 689 If the address requested is not in a mapped region (e.g. we've jumped through 690 a NULL pointer and are at 0x0) currently lldb expects to get back the size 691 of the unmapped region -- that is, the distance to the next valid region. 692 For instance, with a Mac OS X process which has nothing mapped in the first 693 4GB of its address space, if we're asking about address 0x2, 694 695 qMemoryRegionInfo:2 696 start:2;size:fffffffe; 697 698 The lack of 'permissions:' indicates that none of read/write/execute are valid 699 for this region. 700 701 //---------------------------------------------------------------------- 702 // Detach and stay stopped: 703 // 704 // We extended the "D" packet to specify that the monitor should keep the 705 // target suspended on detach. The normal behavior is to resume execution 706 // on detach. We will send: 707 // 708 // qSupportsDetachAndStayStopped: 709 // 710 // to query whether the monitor supports the extended detach, and if it does, 711 // when we want the monitor to detach but not resume the target, we will 712 // send: 713 // 714 // D1 715 // 716 // In any case, if we want the normal detach behavior we will just send: 717 // 718 // D 719 //---------------------------------------------------------------------- 720 721 //---------------------------------------------------------------------- 722 // Stop reply packet extensions 723 // 724 // BRIEF 725 // This section describes some of the additional information you can 726 // specify in stop reply packets that help LLDB to know more detailed 727 // information about your threads. 728 // 729 // DESCRIPTION 730 // Standard GDB remote stop reply packets are reply packets sent in 731 // response to a packet that made the program run. They come in the 732 // following forms: 733 // 734 // "SAA" 735 // "S" means signal and "AA" is a hex signal number that describes why 736 // the thread or stopped. It doesn't specify which thread, so the "T" 737 // packet is recommended to use instead of the "S" packet. 738 // 739 // "TAAkey1:value1;key2:value2;..." 740 // "T" means a thread stopped due to a unix signal where "AA" is a hex 741 // signal number that describes why the program stopped. This is 742 // followed by a series of key/value pairs: 743 // - If key is a hex number, it is a register number and value is 744 // the hex value of the register in debuggee endian byte order. 745 // - If key == "thread", then the value is the big endian hex 746 // thread-id of the stopped thread. 747 // - If key == "core", then value is a hex number of the core on 748 // which the stop was detected. 749 // - If key == "watch" or key == "rwatch" or key == "awatch", then 750 // value is the data address in big endian hex 751 // - If key == "library", then value is ignore and "qXfer:libraries:read" 752 // packets should be used to detect any newly loaded shared libraries 753 // 754 // "WAA" 755 // "W" means the process exited and "AA" is the exit status. 756 // 757 // "XAA" 758 // "X" means the process exited and "AA" is signal that caused the program 759 // to exit. 760 // 761 // "O<ascii-hex-string>" 762 // "O" means STDOUT has data that was written to its console and is 763 // being delivered to the debugger. This packet happens asynchronously 764 // and the debugger is expected to continue to way for another stop reply 765 // packet. 766 // 767 // LLDB EXTENSIONS 768 // 769 // We have extended the "T" packet to be able to also understand the 770 // following keys and values: 771 // 772 // KEY VALUE DESCRIPTION 773 // =========== ======== ================================================ 774 // "metype" unsigned mach exception type (the value of the EXC_XXX enumerations) 775 // as an unsigned integer. For targets with mach 776 // kernels only. 777 // 778 // "mecount" unsigned mach exception data count as an unsigned integer 779 // For targets with mach kernels only. 780 // 781 // "medata" unsigned There should be "mecount" of these and it is the data 782 // that goes along with a mach exception (as an unsigned 783 // integer). For targets with mach kernels only. 784 // 785 // "name" string The name of the thread as a plain string. The string 786 // must not contain an special packet characters or 787 // contain a ':' or a ';'. Use "hexname" if the thread 788 // name has special characters. 789 // 790 // "hexname" ascii-hex An ASCII hex string that contains the name of the thread 791 // 792 // "qaddr" hex Big endian hex value that contains the libdispatch 793 // queue address for the queue of the thread. 794 // 795 // "reason" enum The enumeration must be one of: 796 // "trace" the program stopped after a single instruction 797 // was executed on a core. Usually done when single 798 // stepping past a breakpoint 799 // "breakpoint" a breakpoint set using a 'z' packet was hit. 800 // "trap" stopped due to user interruption 801 // "signal" stopped due to an actual unix signal, not 802 // just the debugger using a unix signal to keep 803 // the GDB remote client happy. 804 // "watchpoint". Should be used in conjunction with 805 // the "watch"/"rwatch"/"awatch" key value pairs. 806 // "exception" an exception stop reason. Use with 807 // the "description" key/value pair to describe the 808 // exceptional event the user should see as the stop 809 // reason. 810 // "description" ascii-hex An ASCII hex string that contains a more descriptive 811 // reason that the thread stopped. This is only needed 812 // if none of the key/value pairs are enough to 813 // describe why something stopped. 814 // 815 // BEST PRACTICES: 816 // Since register values can be supplied with this packet, it is often useful 817 // to return the PC, SP, FP, LR (if any), and FLAGS registers so that separate 818 // packets don't need to be sent to read each of these registers from each 819 // thread. 820 // 821 // If a thread is stopped for no reason (like just because another thread 822 // stopped, or because when one core stops all cores should stop), use a 823 // "T" packet with "00" as the signal number and fill in as many key values 824 // and registers as possible. 825 // 826 // LLDB likes to know why a thread stopped since many thread control 827 // operations like stepping over a source line, actually are implemented 828 // by running the process multiple times. If a breakpoint is hit while 829 // trying to step over a source line and LLDB finds out that a breakpoint 830 // is hit in the "reason", we will know to stop trying to do the step 831 // over because something happened that should stop us from trying to 832 // do the step. If we are at a breakpoint and we disable the breakpoint 833 // at the current PC and do an instruction single step, knowing that 834 // we stopped due to a "trace" helps us know that we can continue 835 // running versus stopping due to a "breakpoint" (if we have two 836 // breakpoint instruction on consecutive instructions). So the more info 837 // we can get about the reason a thread stops, the better job LLDB can 838 // do when controlling your process. A typical GDB server behavior is 839 // to send a SIGTRAP for breakpoints _and_ also when instruction single 840 // stepping, in this case the debugger doesn't really know why we 841 // stopped and it can make it hard for the debugger to control your 842 // program correctly. What if a real SIGTRAP was delivered to a thread 843 // while we were trying to single step? We wouldn't know the difference 844 // with a standard GDB remote server and we could do the wrong thing. 845 // 846 // PRIORITY TO IMPLEMENT 847 // High. Having the extra information in your stop reply packets makes 848 // your debug session more reliable and informative. 849 //---------------------------------------------------------------------- 850 851
