1LLDB has added new GDB server packets to better support multi-threaded and 2remote debugging. Why? Normally you need to start the correct GDB and the 3correct GDB server when debugging. If you have mismatch, then things go wrong 4very quickly. LLDB makes extensive use of the GDB remote protocol and we 5wanted to make sure that the experience was a bit more dynamic where we can 6discover information about a remote target with having to know anything up 7front. We also ran into performance issues with the existing GDB remote 8protocol that can be overcome when using a reliable communications layer. 9Some packets improve performance, others allow for remote process launching 10(if you have an OS), and others allow us to dynamically figure out what 11registers a thread might have. Again with GDB, both sides pre-agree on how the 12registers will look (how many, their register number,name and offsets). We 13prefer to be able to dynamically determine what kind of architecture, os and 14vendor we are debugging, as well as how things are laid out when it comes to 15the thread register contexts. Below are the details on the new packets we have 16added 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//---------------------------------------------------------------------- 29Having to send an ACK/NACK after every packet slows things down a bit, so we 30have a way to disable ACK packets to minimize the traffic for reliable 31communication interfaces (like sockets). Below GDB or LLDB will send this 32packet to try and disable ACKs. All lines that start with "send packet: " are 33from GDB/LLDB, and all lines that start with "read packet: " are from the GDB 34remote server: 35 36send packet: $QStartNoAckMode#b0 37read packet: + 38read packet: $OK#9a 39send 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 55We have added support for the "set program arguments" packet where we can 56startup a connection to a remote server and then later supply the path to the 57executable and the arguments to use when executing: 58 59GDB remote docs for this: 60 61set program arguments(reserved) Aarglen,argnum,arg,... 62 63Where A is followed by the length in bytes of the hex encoded argument, 64followed by an argument integer, and followed by the ASCII characters 65converted into hex bytes foreach arg 66 67send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00 68read packet: $OK#00 69 70The above packet helps when you have remote debugging abilities where you 71could launch a process on a remote host, this isn't needed for bare board 72debugging. 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 87Both GDB and LLDB support passing down environment variables. Is it ok to 88respond with a "$#00" (unimplemented): 89 90send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00 91read packet: $OK#00 92 93This 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 110When launching a program through the GDB remote protocol with the "A" packet, 111you might also want to specify where stdin/out/err go: 112 113QSetSTDIN:<ascii-hex-path> 114QSetSTDOUT:<ascii-hex-path> 115QSetSTDERR:<ascii-hex-path> 116 117These 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 131Or specify the working directory: 132 133QSetWorkingDir:<ascii-hex-path> 134 135This 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 150Or control if ASLR is enabled/disabled: 151 152send packet: QSetDisableASLR:1 153read packet: OK 154 155send packet: QSetDisableASLR:0 156read packet: OK 157 158This 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 173With LLDB, for register information, remote GDB servers can add support for 174the "qRegisterInfoN" packet where "N" is a zero based register number that 175must start at zero and increase by one for each register that is supported. 176The 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 178included below: 179 180send packet: $qRegisterInfo0#00 181read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00 182send packet: $qRegisterInfo1#00 183read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00 184send packet: $qRegisterInfo2#00 185read packet: $name:rcx;bitsize:64;offset:16;encoding:uint;format:hex;set:General Purpose Registers;gcc:2;dwarf:2;#00 186send packet: $qRegisterInfo3#00 187read packet: $name:rdx;bitsize:64;offset:24;encoding:uint;format:hex;set:General Purpose Registers;gcc:1;dwarf:1;#00 188send packet: $qRegisterInfo4#00 189read packet: $name:rdi;bitsize:64;offset:32;encoding:uint;format:hex;set:General Purpose Registers;gcc:5;dwarf:5;#00 190send packet: $qRegisterInfo5#00 191read packet: $name:rsi;bitsize:64;offset:40;encoding:uint;format:hex;set:General Purpose Registers;gcc:4;dwarf:4;#00 192send packet: $qRegisterInfo6#00 193read 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 194send packet: $qRegisterInfo7#00 195read 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 196send packet: $qRegisterInfo8#00 197read packet: $name:r8;bitsize:64;offset:64;encoding:uint;format:hex;set:General Purpose Registers;gcc:8;dwarf:8;#00 198send packet: $qRegisterInfo9#00 199read packet: $name:r9;bitsize:64;offset:72;encoding:uint;format:hex;set:General Purpose Registers;gcc:9;dwarf:9;#00 200send packet: $qRegisterInfoa#00 201read packet: $name:r10;bitsize:64;offset:80;encoding:uint;format:hex;set:General Purpose Registers;gcc:10;dwarf:10;#00 202send packet: $qRegisterInfob#00 203read packet: $name:r11;bitsize:64;offset:88;encoding:uint;format:hex;set:General Purpose Registers;gcc:11;dwarf:11;#00 204send packet: $qRegisterInfoc#00 205read packet: $name:r12;bitsize:64;offset:96;encoding:uint;format:hex;set:General Purpose Registers;gcc:12;dwarf:12;#00 206send packet: $qRegisterInfod#00 207read packet: $name:r13;bitsize:64;offset:104;encoding:uint;format:hex;set:General Purpose Registers;gcc:13;dwarf:13;#00 208send packet: $qRegisterInfoe#00 209read packet: $name:r14;bitsize:64;offset:112;encoding:uint;format:hex;set:General Purpose Registers;gcc:14;dwarf:14;#00 210send packet: $qRegisterInfof#00 211read packet: $name:r15;bitsize:64;offset:120;encoding:uint;format:hex;set:General Purpose Registers;gcc:15;dwarf:15;#00 212send packet: $qRegisterInfo10#00 213read 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 214send packet: $qRegisterInfo11#00 215read packet: $name:rflags;alt-name:flags;bitsize:64;offset:136;encoding:uint;format:hex;set:General Purpose Registers;#00 216send packet: $qRegisterInfo12#00 217read packet: $name:cs;bitsize:64;offset:144;encoding:uint;format:hex;set:General Purpose Registers;#00 218send packet: $qRegisterInfo13#00 219read packet: $name:fs;bitsize:64;offset:152;encoding:uint;format:hex;set:General Purpose Registers;#00 220send packet: $qRegisterInfo14#00 221read packet: $name:gs;bitsize:64;offset:160;encoding:uint;format:hex;set:General Purpose Registers;#00 222send packet: $qRegisterInfo15#00 223read packet: $name:fctrl;bitsize:16;offset:176;encoding:uint;format:hex;set:Floating Point Registers;#00 224send packet: $qRegisterInfo16#00 225read packet: $name:fstat;bitsize:16;offset:178;encoding:uint;format:hex;set:Floating Point Registers;#00 226send packet: $qRegisterInfo17#00 227read packet: $name:ftag;bitsize:8;offset:180;encoding:uint;format:hex;set:Floating Point Registers;#00 228send packet: $qRegisterInfo18#00 229read packet: $name:fop;bitsize:16;offset:182;encoding:uint;format:hex;set:Floating Point Registers;#00 230send packet: $qRegisterInfo19#00 231read packet: $name:fioff;bitsize:32;offset:184;encoding:uint;format:hex;set:Floating Point Registers;#00 232send packet: $qRegisterInfo1a#00 233read packet: $name:fiseg;bitsize:16;offset:188;encoding:uint;format:hex;set:Floating Point Registers;#00 234send packet: $qRegisterInfo1b#00 235read packet: $name:fooff;bitsize:32;offset:192;encoding:uint;format:hex;set:Floating Point Registers;#00 236send packet: $qRegisterInfo1c#00 237read packet: $name:foseg;bitsize:16;offset:196;encoding:uint;format:hex;set:Floating Point Registers;#00 238send packet: $qRegisterInfo1d#00 239read packet: $name:mxcsr;bitsize:32;offset:200;encoding:uint;format:hex;set:Floating Point Registers;#00 240send packet: $qRegisterInfo1e#00 241read packet: $name:mxcsrmask;bitsize:32;offset:204;encoding:uint;format:hex;set:Floating Point Registers;#00 242send packet: $qRegisterInfo1f#00 243read packet: $name:stmm0;bitsize:80;offset:208;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:33;dwarf:33;#00 244send packet: $qRegisterInfo20#00 245read packet: $name:stmm1;bitsize:80;offset:224;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:34;dwarf:34;#00 246send packet: $qRegisterInfo21#00 247read packet: $name:stmm2;bitsize:80;offset:240;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:35;dwarf:35;#00 248send packet: $qRegisterInfo22#00 249read packet: $name:stmm3;bitsize:80;offset:256;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:36;dwarf:36;#00 250send packet: $qRegisterInfo23#00 251read packet: $name:stmm4;bitsize:80;offset:272;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:37;dwarf:37;#00 252send packet: $qRegisterInfo24#00 253read packet: $name:stmm5;bitsize:80;offset:288;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:38;dwarf:38;#00 254send packet: $qRegisterInfo25#00 255read packet: $name:stmm6;bitsize:80;offset:304;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:39;dwarf:39;#00 256send packet: $qRegisterInfo26#00 257read packet: $name:stmm7;bitsize:80;offset:320;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:40;dwarf:40;#00 258send packet: $qRegisterInfo27#00 259read packet: $name:xmm0;bitsize:128;offset:336;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:17;dwarf:17;#00 260send packet: $qRegisterInfo28#00 261read packet: $name:xmm1;bitsize:128;offset:352;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:18;dwarf:18;#00 262send packet: $qRegisterInfo29#00 263read packet: $name:xmm2;bitsize:128;offset:368;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:19;dwarf:19;#00 264send packet: $qRegisterInfo2a#00 265read packet: $name:xmm3;bitsize:128;offset:384;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:20;dwarf:20;#00 266send packet: $qRegisterInfo2b#00 267read packet: $name:xmm4;bitsize:128;offset:400;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:21;dwarf:21;#00 268send packet: $qRegisterInfo2c#00 269read packet: $name:xmm5;bitsize:128;offset:416;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:22;dwarf:22;#00 270send packet: $qRegisterInfo2d#00 271read packet: $name:xmm6;bitsize:128;offset:432;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:23;dwarf:23;#00 272send packet: $qRegisterInfo2e#00 273read packet: $name:xmm7;bitsize:128;offset:448;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:24;dwarf:24;#00 274send packet: $qRegisterInfo2f#00 275read packet: $name:xmm8;bitsize:128;offset:464;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:25;dwarf:25;#00 276send packet: $qRegisterInfo30#00 277read packet: $name:xmm9;bitsize:128;offset:480;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:26;dwarf:26;#00 278send packet: $qRegisterInfo31#00 279read packet: $name:xmm10;bitsize:128;offset:496;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:27;dwarf:27;#00 280send packet: $qRegisterInfo32#00 281read packet: $name:xmm11;bitsize:128;offset:512;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:28;dwarf:28;#00 282send packet: $qRegisterInfo33#00 283read packet: $name:xmm12;bitsize:128;offset:528;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:29;dwarf:29;#00 284send packet: $qRegisterInfo34#00 285read packet: $name:xmm13;bitsize:128;offset:544;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:30;dwarf:30;#00 286send packet: $qRegisterInfo35#00 287read packet: $name:xmm14;bitsize:128;offset:560;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:31;dwarf:31;#00 288send packet: $qRegisterInfo36#00 289read packet: $name:xmm15;bitsize:128;offset:576;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:32;dwarf:32;#00 290send packet: $qRegisterInfo37#00 291read packet: $name:trapno;bitsize:32;offset:696;encoding:uint;format:hex;set:Exception State Registers;#00 292send packet: $qRegisterInfo38#00 293read packet: $name:err;bitsize:32;offset:700;encoding:uint;format:hex;set:Exception State Registers;#00 294send packet: $qRegisterInfo39#00 295read packet: $name:faultvaddr;bitsize:64;offset:704;encoding:uint;format:hex;set:Exception State Registers;#00 296send packet: $qRegisterInfo3a#00 297read packet: $E45#00 298 299As we see above we keep making subsequent calls to the remote server to 300discover all registers by increasing the number appended to qRegisterInfo and 301we get a response back that is a series of "key=value;" strings. The keys and 302values are detailed below: 303 304Key Value 305========== ================================================================ 306name The primary register name as a string ("rbp" for example) 307 308alt-name An alternate name for a register as a string ("fp" for example for 309 the above "rbp") 310 311bitsize Size in bits of a register (32, 64, etc) 312 313offset The offset within the "g" and "G" packet of the register data for 314 this register 315 316encoding 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 323format 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 339set The register set name as a string that this register belongs to. 340 341gcc 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 350dwarf 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 358generic 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 377container-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 401invalidate-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 435LLDB supports a host info call that gets all sorts of details of the system 436that is being debugged: 437 438send packet: $qHostInfo#00 439read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00 440 441Key value pairs are one of: 442 443cputype: is a number that is the mach-o CPU type that is being debugged 444cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged 445ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) 446vendor: is a string that represents the vendor (apple) 447endian: is one of "little", "big", or "pdp" 448ptrsize: 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 468An i386 process: 469 470send packet: $qProcessInfo#00 471read 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 473An x86_64 process: 474 475send packet: $qProcessInfo#00 476read 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 478Key value pairs include: 479 480pid: the process id 481parent-pid: the process of the parent process (often debugserver will become the parent when attaching) 482real-uid: the real user id of the process 483real-gid: the real group id of the process 484effective-uid: the effective user id of the process 485effective-gid: the effective group id of the process 486cputype: the Mach-O CPU type of the process 487cpusubtype: the Mach-O CPU subtype of the process 488ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) 489vendor: is a string that represents the vendor (apple) 490endian: is one of "little", "big", or "pdp" 491ptrsize: 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 512LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each 513debugger as to where to find the dynamic loader information. For darwin 514binaries that run in user land this is the address of the "all_image_infos" 515structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO 516call. The result is returned as big endian hex bytes that are the address 517value: 518 519send packet: $qShlibInfoAddr#00 520read 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 540LLDB tries to use the "qThreadStopInfo" packet which is formatted as 541"qThreadStopInfo%x" where %x is the hex thread ID. This requests information 542about why a thread is stopped. The response is the same as the stop reply 543packets and tells us what happened to the other threads. The standard GDB 544remote packets love to think that there is only _one_ reason that _one_ thread 545stops at a time. This allows us to see why all threads stopped and allows us 546to 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 565When reading thread registers, you currently need to set the current 566thread, then read the registers. This is kind of cumbersome, so we added the 567ability to query if the remote GDB server supports adding a "thread:<tid>;" 568suffix to all packets that request information for a thread. To test if the 569remote GDB server supports this feature: 570 571send packet: $QThreadSuffixSupported#00 572read packet: OK 573 574If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a 575thread suffix. So to send a 'g' packet (read all register values): 576 577send packet: $g;thread:<tid>;#00 578read packet: .... 579 580send packet: $G;thread:<tid>;#00 581read packet: .... 582 583send packet: $p1a;thread:<tid>;#00 584read packet: .... 585 586send packet: $P1a=1234abcd;thread:<tid>;#00 587read packet: .... 588 589 590otherwise, without this you would need to always send two packets: 591 592send packet: $Hg<tid>#00 593read packet: .... 594send packet: $g#00 595read packet: .... 596 597We also added support for allocating and deallocating memory. We use this to 598allocate 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 614The allocate memory packet starts with "_M<size>,<permissions>". It returns a 615raw big endian address value, or "" for unimplemented, or "EXX" for an error 616code. The packet is formatted as: 617 618char packet[256]; 619int packet_len; 620packet_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 629You request a size and give the permissions. This packet does NOT need to be 630implemented if you don't want to support running JITed code. The return value 631is 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 647The deallocate memory packet is "_m<addr>" where you pass in the address you 648got back from a previous call to the allocate memory packet. It returns "OK" 649if the memory was successfully deallocated, or "EXX" for an error, or "" if 650not 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 668We added a way to get information for a memory region. The packet is: 669 670 qMemoryRegionInfo:<addr> 671 672Where <addr> is a big endian hex address. The response is returned in a series 673of tuples like the data returned in a stop reply packet. The currently valid 674tuples 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 689If the address requested is not in a mapped region (e.g. we've jumped through 690a NULL pointer and are at 0x0) currently lldb expects to get back the size 691of the unmapped region -- that is, the distance to the next valid region. 692For instance, with a Mac OS X process which has nothing mapped in the first 6934GB of its address space, if we're asking about address 0x2, 694 695 qMemoryRegionInfo:2 696 start:2;size:fffffffe; 697 698The lack of 'permissions:' indicates that none of read/write/execute are valid 699for 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