| LLDB has added new GDB server packets to better support multi-threaded and |
| remote debugging. Why? Normally you need to start the correct GDB and the |
| correct GDB server when debugging. If you have mismatch, then things go wrong |
| very quickly. LLDB makes extensive use of the GDB remote protocol and we |
| wanted to make sure that the experience was a bit more dynamic where we can |
| discover information about a remote target with having to know anything up |
| front. We also ran into performance issues with the existing GDB remote |
| protocol that can be overcome when using a reliable communications layer. |
| Some packets improve performance, others allow for remote process launching |
| (if you have an OS), and others allow us to dynamically figure out what |
| registers a thread might have. Again with GDB, both sides pre-agree on how the |
| registers will look (how many, their register number,name and offsets). We |
| prefer to be able to dynamically determine what kind of architecture, os and |
| vendor we are debugging, as well as how things are laid out when it comes to |
| the thread register contexts. Below are the details on the new packets we have |
| added above and beyond the standard GDB remote protocol packets. |
| |
| //---------------------------------------------------------------------- |
| // "QStartNoAckMode" |
| // |
| // BRIEF |
| // Try to enable no ACK mode to skip sending ACKs and NACKs. |
| // |
| // PRIORITY TO IMPLEMENT |
| // High. Any GDB remote server that can implement this should if the |
| // connection is reliable. This improves packet throughput and increases |
| // the performance of the connection. |
| //---------------------------------------------------------------------- |
| Having to send an ACK/NACK after every packet slows things down a bit, so we |
| have a way to disable ACK packets to minimize the traffic for reliable |
| communication interfaces (like sockets). Below GDB or LLDB will send this |
| packet to try and disable ACKs. All lines that start with "send packet: " are |
| from GDB/LLDB, and all lines that start with "read packet: " are from the GDB |
| remote server: |
| |
| send packet: $QStartNoAckMode#b0 |
| read packet: + |
| read packet: $OK#9a |
| send packet: + |
| |
| |
| |
| //---------------------------------------------------------------------- |
| // "A" - launch args packet |
| // |
| // BRIEF |
| // Launch a program using the supplied arguments |
| // |
| // PRIORITY TO IMPLEMENT |
| // Low. Only needed if the remote target wants to launch a target after |
| // making a connection to a GDB server that isn't already connected to |
| // an inferior process. |
| //---------------------------------------------------------------------- |
| |
| We have added support for the "set program arguments" packet where we can |
| startup a connection to a remote server and then later supply the path to the |
| executable and the arguments to use when executing: |
| |
| GDB remote docs for this: |
| |
| set program arguments(reserved) Aarglen,argnum,arg,... |
| |
| Where A is followed by the length in bytes of the hex encoded argument, |
| followed by an argument integer, and followed by the ASCII characters |
| converted into hex bytes foreach arg |
| |
| send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00 |
| read packet: $OK#00 |
| |
| The above packet helps when you have remote debugging abilities where you |
| could launch a process on a remote host, this isn't needed for bare board |
| debugging. |
| |
| //---------------------------------------------------------------------- |
| // "QEnvironment:NAME=VALUE" |
| // |
| // BRIEF |
| // Setup the environment up for a new child process that will soon be |
| // launched using the "A" packet. |
| // |
| // PRIORITY TO IMPLEMENT |
| // Low. Only needed if the remote target wants to launch a target after |
| // making a connection to a GDB server that isn't already connected to |
| // an inferior process. |
| //---------------------------------------------------------------------- |
| |
| Both GDB and LLDB support passing down environment variables. Is it ok to |
| respond with a "$#00" (unimplemented): |
| |
| send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00 |
| read packet: $OK#00 |
| |
| This packet can be sent one or more times _prior_ to sending a "A" packet. |
| |
| //---------------------------------------------------------------------- |
| // "QSetSTDIN:<ascii-hex-path>" |
| // "QSetSTDOUT:<ascii-hex-path>" |
| // "QSetSTDERR:<ascii-hex-path>" |
| // |
| // BRIEF |
| // Setup where STDIN, STDOUT, and STDERR go prior to sending an "A" |
| // packet. |
| // |
| // PRIORITY TO IMPLEMENT |
| // Low. Only needed if the remote target wants to launch a target after |
| // making a connection to a GDB server that isn't already connected to |
| // an inferior process. |
| //---------------------------------------------------------------------- |
| |
| When launching a program through the GDB remote protocol with the "A" packet, |
| you might also want to specify where stdin/out/err go: |
| |
| QSetSTDIN:<ascii-hex-path> |
| QSetSTDOUT:<ascii-hex-path> |
| QSetSTDERR:<ascii-hex-path> |
| |
| These packets must be sent _prior_ to sending a "A" packet. |
| |
| //---------------------------------------------------------------------- |
| // "QSetWorkingDir:<ascii-hex-path>" |
| // |
| // BRIEF |
| // Set the working directory prior to sending an "A" packet. |
| // |
| // PRIORITY TO IMPLEMENT |
| // Low. Only needed if the remote target wants to launch a target after |
| // making a connection to a GDB server that isn't already connected to |
| // an inferior process. |
| //---------------------------------------------------------------------- |
| |
| Or specify the working directory: |
| |
| QSetWorkingDir:<ascii-hex-path> |
| |
| This packet must be sent _prior_ to sending a "A" packet. |
| |
| //---------------------------------------------------------------------- |
| // "QSetDisableASLR:<bool>" |
| // |
| // BRIEF |
| // Enable or disable ASLR on the next "A" packet. |
| // |
| // PRIORITY TO IMPLEMENT |
| // Low. Only needed if the remote target wants to launch a target after |
| // making a connection to a GDB server that isn't already connected to |
| // an inferior process and if the target supports disabling ASLR |
| // (Address space layout randomization). |
| //---------------------------------------------------------------------- |
| |
| Or control if ASLR is enabled/disabled: |
| |
| send packet: QSetDisableASLR:1 |
| read packet: OK |
| |
| send packet: QSetDisableASLR:0 |
| read packet: OK |
| |
| This packet must be sent _prior_ to sending a "A" packet. |
| |
| //---------------------------------------------------------------------- |
| // "qRegisterInfo<hex-reg-id>" |
| // |
| // BRIEF |
| // Discover register information from the remote GDB server. |
| // |
| // PRIORITY TO IMPLEMENT |
| // High. Any target that can self describe its registers, should do so. |
| // This means if new registers are ever added to a remote target, they |
| // will get picked up automatically, and allows registers to change |
| // depending on the actual CPU type that is used. |
| //---------------------------------------------------------------------- |
| |
| With LLDB, for register information, remote GDB servers can add support for |
| the "qRegisterInfoN" packet where "N" is a zero based register number that |
| must start at zero and increase by one for each register that is supported. |
| The response is done in typical GDB remote fashion where a serious of |
| "KEY:VALUE;" pairs are returned. An example for the x86_64 registers is |
| included below: |
| |
| send packet: $qRegisterInfo0#00 |
| read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00 |
| send packet: $qRegisterInfo1#00 |
| read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00 |
| send packet: $qRegisterInfo2#00 |
| read packet: $name:rcx;bitsize:64;offset:16;encoding:uint;format:hex;set:General Purpose Registers;gcc:2;dwarf:2;#00 |
| send packet: $qRegisterInfo3#00 |
| read packet: $name:rdx;bitsize:64;offset:24;encoding:uint;format:hex;set:General Purpose Registers;gcc:1;dwarf:1;#00 |
| send packet: $qRegisterInfo4#00 |
| read packet: $name:rdi;bitsize:64;offset:32;encoding:uint;format:hex;set:General Purpose Registers;gcc:5;dwarf:5;#00 |
| send packet: $qRegisterInfo5#00 |
| read packet: $name:rsi;bitsize:64;offset:40;encoding:uint;format:hex;set:General Purpose Registers;gcc:4;dwarf:4;#00 |
| send packet: $qRegisterInfo6#00 |
| 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 |
| send packet: $qRegisterInfo7#00 |
| 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 |
| send packet: $qRegisterInfo8#00 |
| read packet: $name:r8;bitsize:64;offset:64;encoding:uint;format:hex;set:General Purpose Registers;gcc:8;dwarf:8;#00 |
| send packet: $qRegisterInfo9#00 |
| read packet: $name:r9;bitsize:64;offset:72;encoding:uint;format:hex;set:General Purpose Registers;gcc:9;dwarf:9;#00 |
| send packet: $qRegisterInfoa#00 |
| read packet: $name:r10;bitsize:64;offset:80;encoding:uint;format:hex;set:General Purpose Registers;gcc:10;dwarf:10;#00 |
| send packet: $qRegisterInfob#00 |
| read packet: $name:r11;bitsize:64;offset:88;encoding:uint;format:hex;set:General Purpose Registers;gcc:11;dwarf:11;#00 |
| send packet: $qRegisterInfoc#00 |
| read packet: $name:r12;bitsize:64;offset:96;encoding:uint;format:hex;set:General Purpose Registers;gcc:12;dwarf:12;#00 |
| send packet: $qRegisterInfod#00 |
| read packet: $name:r13;bitsize:64;offset:104;encoding:uint;format:hex;set:General Purpose Registers;gcc:13;dwarf:13;#00 |
| send packet: $qRegisterInfoe#00 |
| read packet: $name:r14;bitsize:64;offset:112;encoding:uint;format:hex;set:General Purpose Registers;gcc:14;dwarf:14;#00 |
| send packet: $qRegisterInfof#00 |
| read packet: $name:r15;bitsize:64;offset:120;encoding:uint;format:hex;set:General Purpose Registers;gcc:15;dwarf:15;#00 |
| send packet: $qRegisterInfo10#00 |
| 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 |
| send packet: $qRegisterInfo11#00 |
| read packet: $name:rflags;alt-name:flags;bitsize:64;offset:136;encoding:uint;format:hex;set:General Purpose Registers;#00 |
| send packet: $qRegisterInfo12#00 |
| read packet: $name:cs;bitsize:64;offset:144;encoding:uint;format:hex;set:General Purpose Registers;#00 |
| send packet: $qRegisterInfo13#00 |
| read packet: $name:fs;bitsize:64;offset:152;encoding:uint;format:hex;set:General Purpose Registers;#00 |
| send packet: $qRegisterInfo14#00 |
| read packet: $name:gs;bitsize:64;offset:160;encoding:uint;format:hex;set:General Purpose Registers;#00 |
| send packet: $qRegisterInfo15#00 |
| read packet: $name:fctrl;bitsize:16;offset:176;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo16#00 |
| read packet: $name:fstat;bitsize:16;offset:178;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo17#00 |
| read packet: $name:ftag;bitsize:8;offset:180;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo18#00 |
| read packet: $name:fop;bitsize:16;offset:182;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo19#00 |
| read packet: $name:fioff;bitsize:32;offset:184;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo1a#00 |
| read packet: $name:fiseg;bitsize:16;offset:188;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo1b#00 |
| read packet: $name:fooff;bitsize:32;offset:192;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo1c#00 |
| read packet: $name:foseg;bitsize:16;offset:196;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo1d#00 |
| read packet: $name:mxcsr;bitsize:32;offset:200;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo1e#00 |
| read packet: $name:mxcsrmask;bitsize:32;offset:204;encoding:uint;format:hex;set:Floating Point Registers;#00 |
| send packet: $qRegisterInfo1f#00 |
| read packet: $name:stmm0;bitsize:80;offset:208;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:33;dwarf:33;#00 |
| send packet: $qRegisterInfo20#00 |
| read packet: $name:stmm1;bitsize:80;offset:224;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:34;dwarf:34;#00 |
| send packet: $qRegisterInfo21#00 |
| read packet: $name:stmm2;bitsize:80;offset:240;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:35;dwarf:35;#00 |
| send packet: $qRegisterInfo22#00 |
| read packet: $name:stmm3;bitsize:80;offset:256;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:36;dwarf:36;#00 |
| send packet: $qRegisterInfo23#00 |
| read packet: $name:stmm4;bitsize:80;offset:272;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:37;dwarf:37;#00 |
| send packet: $qRegisterInfo24#00 |
| read packet: $name:stmm5;bitsize:80;offset:288;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:38;dwarf:38;#00 |
| send packet: $qRegisterInfo25#00 |
| read packet: $name:stmm6;bitsize:80;offset:304;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:39;dwarf:39;#00 |
| send packet: $qRegisterInfo26#00 |
| read packet: $name:stmm7;bitsize:80;offset:320;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:40;dwarf:40;#00 |
| send packet: $qRegisterInfo27#00 |
| read packet: $name:xmm0;bitsize:128;offset:336;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:17;dwarf:17;#00 |
| send packet: $qRegisterInfo28#00 |
| read packet: $name:xmm1;bitsize:128;offset:352;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:18;dwarf:18;#00 |
| send packet: $qRegisterInfo29#00 |
| read packet: $name:xmm2;bitsize:128;offset:368;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:19;dwarf:19;#00 |
| send packet: $qRegisterInfo2a#00 |
| read packet: $name:xmm3;bitsize:128;offset:384;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:20;dwarf:20;#00 |
| send packet: $qRegisterInfo2b#00 |
| read packet: $name:xmm4;bitsize:128;offset:400;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:21;dwarf:21;#00 |
| send packet: $qRegisterInfo2c#00 |
| read packet: $name:xmm5;bitsize:128;offset:416;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:22;dwarf:22;#00 |
| send packet: $qRegisterInfo2d#00 |
| read packet: $name:xmm6;bitsize:128;offset:432;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:23;dwarf:23;#00 |
| send packet: $qRegisterInfo2e#00 |
| read packet: $name:xmm7;bitsize:128;offset:448;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:24;dwarf:24;#00 |
| send packet: $qRegisterInfo2f#00 |
| read packet: $name:xmm8;bitsize:128;offset:464;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:25;dwarf:25;#00 |
| send packet: $qRegisterInfo30#00 |
| read packet: $name:xmm9;bitsize:128;offset:480;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:26;dwarf:26;#00 |
| send packet: $qRegisterInfo31#00 |
| read packet: $name:xmm10;bitsize:128;offset:496;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:27;dwarf:27;#00 |
| send packet: $qRegisterInfo32#00 |
| read packet: $name:xmm11;bitsize:128;offset:512;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:28;dwarf:28;#00 |
| send packet: $qRegisterInfo33#00 |
| read packet: $name:xmm12;bitsize:128;offset:528;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:29;dwarf:29;#00 |
| send packet: $qRegisterInfo34#00 |
| read packet: $name:xmm13;bitsize:128;offset:544;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:30;dwarf:30;#00 |
| send packet: $qRegisterInfo35#00 |
| read packet: $name:xmm14;bitsize:128;offset:560;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:31;dwarf:31;#00 |
| send packet: $qRegisterInfo36#00 |
| read packet: $name:xmm15;bitsize:128;offset:576;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:32;dwarf:32;#00 |
| send packet: $qRegisterInfo37#00 |
| read packet: $name:trapno;bitsize:32;offset:696;encoding:uint;format:hex;set:Exception State Registers;#00 |
| send packet: $qRegisterInfo38#00 |
| read packet: $name:err;bitsize:32;offset:700;encoding:uint;format:hex;set:Exception State Registers;#00 |
| send packet: $qRegisterInfo39#00 |
| read packet: $name:faultvaddr;bitsize:64;offset:704;encoding:uint;format:hex;set:Exception State Registers;#00 |
| send packet: $qRegisterInfo3a#00 |
| read packet: $E45#00 |
| |
| As we see above we keep making subsequent calls to the remote server to |
| discover all registers by increasing the number appended to qRegisterInfo and |
| we get a response back that is a series of "key=value;" strings. The keys and |
| values are detailed below: |
| |
| Key Value |
| ========== ================================================================ |
| name The primary register name as a string ("rbp" for example) |
| |
| alt-name An alternate name for a register as a string ("fp" for example for |
| the above "rbp") |
| |
| bitsize Size in bits of a register (32, 64, etc) |
| |
| offset The offset within the "g" and "G" packet of the register data for |
| this register |
| |
| encoding The encoding type of the register which must be one of: |
| |
| uint (unsigned integer) |
| sint (signed integer) |
| ieee754 (IEEE 754 float) |
| vector (vector regsiter) |
| |
| format The preferred format for display of this register. The value must |
| be one of: |
| |
| binary |
| decimal |
| hex |
| float |
| vector-sint8 |
| vector-uint8 |
| vector-sint16 |
| vector-uint16 |
| vector-sint32 |
| vector-uint32 |
| vector-float32 |
| vector-uint128 |
| |
| set The register set name as a string that this register belongs to. |
| |
| gcc The GCC compiler registers number for this register (used for |
| EH frame and other compiler information that is encoded in the |
| executable files). The supplied number will be decoded like a |
| string passed to strtoul() with a base of zero, so the number |
| can be decimal, or hex if it is prefixed with "0x". |
| |
| NOTE: If the compiler doesn't have a register number for this |
| register, this key/value pair should be omitted. |
| |
| dwarf The DWARF register number for this register that is used for this |
| register in the debug information. The supplied number will be decoded |
| like a string passed to strtoul() with a base of zero, so the number |
| can be decimal, or hex if it is prefixed with "0x". |
| |
| NOTE: If the compiler doesn't have a register number for this |
| register, this key/value pair should be omitted. |
| |
| generic If the register is a generic register that most CPUs have, classify |
| it correctly so the debugger knows. Valid values are one of: |
| pc (a program counter register. for example "name=eip;" (i386), |
| "name=rip;" (x86_64), "name=r15;" (32 bit arm) would |
| include a "generic=pc;" key value pair) |
| sp (a stack pointer register. for example "name=esp;" (i386), |
| "name=rsp;" (x86_64), "name=r13;" (32 bit arm) would |
| include a "generic=sp;" key value pair) |
| fp (a frame pointer register. for example "name=ebp;" (i386), |
| "name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx |
| ABI) would include a "generic=fp;" key value pair) |
| ra (a return address register. for example "name=lr;" (32 bit ARM) |
| would include a "generic=ra;" key value pair) |
| fp (a CPU flags register. for example "name=eflags;" (i386), |
| "name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM) |
| would include a "generic=flags;" key value pair) |
| arg1 - arg8 (specified for registers that contain function |
| arguments when the argument fits into a register) |
| |
| container-regs |
| The value for this key is a comma separated list of raw hex (optional |
| leading "0x") register numbers. |
| |
| This specifies that this register is contained in other concrete |
| register values. For example "eax" is in the lower 32 bits of the |
| "rax" register value for x86_64, so "eax" could specify that it is |
| contained in "rax" by specifying the register number for "rax" (whose |
| register number is 0x00) |
| |
| "container-regs:00;" |
| |
| If a register is comprised of one or more registers, like "d0" is ARM |
| which is a 64 bit register, it might be made up of "s0" and "s1". If |
| the register number for "s0" is 0x20, and the register number of "s1" |
| is "0x21", the "container-regs" key/value pair would be: |
| |
| "container-regs:20,21;" |
| |
| This is handy for defining what GDB used to call "pseudo" registers. |
| These registers are never requested by LLDB via the register read |
| or write packets, the container registers will be requested on behalf |
| of this register. |
| |
| invalidate-regs |
| The value for this key is a comma separated list of raw hex (optional |
| leading "0x") register numbers. |
| |
| This specifies which register values should be invalidated when this |
| register is modified. For example if modifying "eax" would cause "rax", |
| "eax", "ax", "ah", and "al" to be modified where rax is 0x0, eax is 0x15, |
| ax is 0x25, ah is 0x35, and al is 0x39, the "invalidate-regs" key/value |
| pair would be: |
| |
| "invalidate-regs:0,15,25,35,39;" |
| |
| If there is a single register that gets invalidated, then omit the comma |
| and just list a single register: |
| |
| "invalidate-regs:0;" |
| |
| This is handy when modifying a specific register can cause other |
| register values to change. For example, when debugging an ARM target, |
| modifying the CPSR register can cause the r8 - r14 and cpsr value to |
| change depending on if the mode has changed. |
| |
| //---------------------------------------------------------------------- |
| // "qHostInfo" |
| // |
| // BRIEF |
| // Get information about the host we are remotely connected to. |
| // |
| // PRIORITY TO IMPLEMENT |
| // High. This packet is usually very easy to implement and can help |
| // LLDB select the correct plug-ins for the job based on the target |
| // triple information that is suppied. |
| //---------------------------------------------------------------------- |
| |
| LLDB supports a host info call that gets all sorts of details of the system |
| that is being debugged: |
| |
| send packet: $qHostInfo#00 |
| read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00 |
| |
| Key value pairs are one of: |
| |
| cputype: is a number that is the mach-o CPU type that is being debugged |
| cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged |
| ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) |
| vendor: is a string that represents the vendor (apple) |
| endian: is one of "little", "big", or "pdp" |
| ptrsize: is a number that represents how big pointers are in bytes on the debug target |
| |
| //---------------------------------------------------------------------- |
| // "qProcessInfo" |
| // |
| // BRIEF |
| // Get information about the process we are currently debugging. |
| // |
| // PRIORITY TO IMPLEMENT |
| // Medium. On systems which can launch multiple different architecture processes, |
| // the qHostInfo may not disambiguate sufficiently to know what kind of |
| // process is being debugged. |
| // e.g. on a 64-bit x86 Mac system both 32-bit and 64-bit user processes are possible, |
| // and with Mach-O universal files, the executable file may contain both 32- and |
| // 64-bit slices so it may be impossible to know until you're attached to a real |
| // process to know what you're working with. |
| // |
| // All numeric fields return base-16 numbers without any "0x" prefix. |
| //---------------------------------------------------------------------- |
| |
| An i386 process: |
| |
| send packet: $qProcessInfo#00 |
| 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 |
| |
| An x86_64 process: |
| |
| send packet: $qProcessInfo#00 |
| 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 |
| |
| Key value pairs include: |
| |
| pid: the process id |
| parent-pid: the process of the parent process (often debugserver will become the parent when attaching) |
| real-uid: the real user id of the process |
| real-gid: the real group id of the process |
| effective-uid: the effective user id of the process |
| effective-gid: the effective group id of the process |
| cputype: the Mach-O CPU type of the process |
| cpusubtype: the Mach-O CPU subtype of the process |
| ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) |
| vendor: is a string that represents the vendor (apple) |
| endian: is one of "little", "big", or "pdp" |
| ptrsize: is a number that represents how big pointers are in bytes |
| |
| |
| //---------------------------------------------------------------------- |
| // "qShlibInfoAddr" |
| // |
| // BRIEF |
| // Get an address where the dynamic linker stores information about |
| // where shared libraries are loaded. |
| // |
| // PRIORITY TO IMPLEMENT |
| // High if you have a dynamic loader plug-in in LLDB for your target |
| // triple (see the "qHostInfo" packet) that can use this information. |
| // Many times address load randomization can make it hard to detect |
| // where the dynamic loader binary and data structures are located and |
| // some platforms know, or can find out where this information is. |
| // |
| // Low if you have a debug target where all object and symbol files |
| // contain static load addresses. |
| //---------------------------------------------------------------------- |
| |
| LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each |
| debugger as to where to find the dynamic loader information. For darwin |
| binaries that run in user land this is the address of the "all_image_infos" |
| structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO |
| call. The result is returned as big endian hex bytes that are the address |
| value: |
| |
| send packet: $qShlibInfoAddr#00 |
| read packet: $7fff5fc40040#00 |
| |
| |
| |
| //---------------------------------------------------------------------- |
| // "qThreadStopInfo<tid>" |
| // |
| // BRIEF |
| // Get information about why a thread, whose ID is "<tid>", is stopped. |
| // |
| // PRIORITY TO IMPLEMENT |
| // High if you need to support multi-threaded or multi-core debugging. |
| // Many times one thread will hit a breakpoint and while the debugger |
| // is in the process of suspending the other threads, other threads |
| // will also hit a breakpoint. This packet allows LLDB to know why all |
| // threads (live system debug) / cores (JTAG) in your program have |
| // stopped and allows LLDB to display and control your program |
| // correctly. |
| //---------------------------------------------------------------------- |
| |
| LLDB tries to use the "qThreadStopInfo" packet which is formatted as |
| "qThreadStopInfo%x" where %x is the hex thread ID. This requests information |
| about why a thread is stopped. The response is the same as the stop reply |
| packets and tells us what happened to the other threads. The standard GDB |
| remote packets love to think that there is only _one_ reason that _one_ thread |
| stops at a time. This allows us to see why all threads stopped and allows us |
| to implement better multi-threaded debugging support. |
| |
| //---------------------------------------------------------------------- |
| // "QThreadSuffixSupported" |
| // |
| // BRIEF |
| // Try to enable thread suffix support for the 'g', 'G', 'p', and 'P' |
| // packets. |
| // |
| // PRIORITY TO IMPLEMENT |
| // High. Adding a thread suffix allows us to read and write registers |
| // more efficiently and stops us from having to select a thread with |
| // one packet and then read registers with a second packet. It also |
| // makes sure that no errors can occur where the debugger thinks it |
| // already has a thread selected (see the "Hg" packet from the standard |
| // GDB remote protocol documentation) yet the remote GDB server actually |
| // has another thread selected. |
| //---------------------------------------------------------------------- |
| |
| When reading thread registers, you currently need to set the current |
| thread, then read the registers. This is kind of cumbersome, so we added the |
| ability to query if the remote GDB server supports adding a "thread:<tid>;" |
| suffix to all packets that request information for a thread. To test if the |
| remote GDB server supports this feature: |
| |
| send packet: $QThreadSuffixSupported#00 |
| read packet: OK |
| |
| If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a |
| thread suffix. So to send a 'g' packet (read all register values): |
| |
| send packet: $g;thread:<tid>;#00 |
| read packet: .... |
| |
| send packet: $G;thread:<tid>;#00 |
| read packet: .... |
| |
| send packet: $p1a;thread:<tid>;#00 |
| read packet: .... |
| |
| send packet: $P1a=1234abcd;thread:<tid>;#00 |
| read packet: .... |
| |
| |
| otherwise, without this you would need to always send two packets: |
| |
| send packet: $Hg<tid>#00 |
| read packet: .... |
| send packet: $g#00 |
| read packet: .... |
| |
| We also added support for allocating and deallocating memory. We use this to |
| allocate memory so we can run JITed code. |
| |
| //---------------------------------------------------------------------- |
| // "_M<size>,<permissions>" |
| // |
| // BRIEF |
| // Allocate memory on the remote target with the specified size and |
| // permissions. |
| // |
| // PRIORITY TO IMPLEMENT |
| // High if you want LLDB to be able to JIT code and run that code. JIT |
| // code also needs data which is also allocated and tracked. |
| // |
| // Low if you don't support running JIT'ed code. |
| //---------------------------------------------------------------------- |
| |
| The allocate memory packet starts with "_M<size>,<permissions>". It returns a |
| raw big endian address value, or "" for unimplemented, or "EXX" for an error |
| code. The packet is formatted as: |
| |
| char packet[256]; |
| int packet_len; |
| packet_len = ::snprintf ( |
| packet, |
| sizeof(packet), |
| "_M%zx,%s%s%s", |
| (size_t)size, |
| permissions & lldb::ePermissionsReadable ? "r" : "", |
| permissions & lldb::ePermissionsWritable ? "w" : "", |
| permissions & lldb::ePermissionsExecutable ? "x" : ""); |
| |
| You request a size and give the permissions. This packet does NOT need to be |
| implemented if you don't want to support running JITed code. The return value |
| is just the address of the newly allocated memory as raw big endian hex bytes. |
| |
| //---------------------------------------------------------------------- |
| // "_m<addr>" |
| // |
| // BRIEF |
| // Deallocate memory that was previously allocated using an allocate |
| // memory pack. |
| // |
| // PRIORITY TO IMPLEMENT |
| // High if you want LLDB to be able to JIT code and run that code. JIT |
| // code also needs data which is also allocated and tracked. |
| // |
| // Low if you don't support running JIT'ed code. |
| //---------------------------------------------------------------------- |
| |
| The deallocate memory packet is "_m<addr>" where you pass in the address you |
| got back from a previous call to the allocate memory packet. It returns "OK" |
| if the memory was successfully deallocated, or "EXX" for an error, or "" if |
| not supported. |
| |
| //---------------------------------------------------------------------- |
| // "qMemoryRegionInfo:<addr>" |
| // |
| // BRIEF |
| // Get information about the address the range that contains "<addr>" |
| // |
| // PRIORITY TO IMPLEMENT |
| // Medium. This is nice to have, but it isn't necessary. It helps LLDB |
| // do stack unwinding when we branch into memory that isn't executable. |
| // If we can detect that the code we are stopped in isn't executable, |
| // then we can recover registers for stack frames above the current |
| // frame. Otherwise we must assume we are in some JIT'ed code (not JIT |
| // code that LLDB has made) and assume that no registers are available |
| // in higher stack frames. |
| //---------------------------------------------------------------------- |
| |
| We added a way to get information for a memory region. The packet is: |
| |
| qMemoryRegionInfo:<addr> |
| |
| Where <addr> is a big endian hex address. The response is returned in a series |
| of tuples like the data returned in a stop reply packet. The currently valid |
| tuples tp return are: |
| |
| start:<start-addr>; // <start-addr> is a big endian hex address that is |
| // the start address of the range that contains <addr> |
| |
| size:<size>; // <size> is a big endian hex byte size of the address |
| // of the range that contains <addr> |
| |
| permissions:<permissions>; // <permissions> is a string that contains one |
| // or more of the characters from "rwx" |
| |
| error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is |
| // a hex encoded string value that |
| // contains an error string |
| |
| If the address requested is not in a mapped region (e.g. we've jumped through |
| a NULL pointer and are at 0x0) currently lldb expects to get back the size |
| of the unmapped region -- that is, the distance to the next valid region. |
| For instance, with a Mac OS X process which has nothing mapped in the first |
| 4GB of its address space, if we're asking about address 0x2, |
| |
| qMemoryRegionInfo:2 |
| start:2;size:fffffffe; |
| |
| The lack of 'permissions:' indicates that none of read/write/execute are valid |
| for this region. |
| |
| //---------------------------------------------------------------------- |
| // Detach and stay stopped: |
| // |
| // We extended the "D" packet to specify that the monitor should keep the |
| // target suspended on detach. The normal behavior is to resume execution |
| // on detach. We will send: |
| // |
| // qSupportsDetachAndStayStopped: |
| // |
| // to query whether the monitor supports the extended detach, and if it does, |
| // when we want the monitor to detach but not resume the target, we will |
| // send: |
| // |
| // D1 |
| // |
| // In any case, if we want the normal detach behavior we will just send: |
| // |
| // D |
| //---------------------------------------------------------------------- |
| |
| //---------------------------------------------------------------------- |
| // Stop reply packet extensions |
| // |
| // BRIEF |
| // This section describes some of the additional information you can |
| // specify in stop reply packets that help LLDB to know more detailed |
| // information about your threads. |
| // |
| // DESCRIPTION |
| // Standard GDB remote stop reply packets are reply packets sent in |
| // response to a packet that made the program run. They come in the |
| // following forms: |
| // |
| // "SAA" |
| // "S" means signal and "AA" is a hex signal number that describes why |
| // the thread or stopped. It doesn't specify which thread, so the "T" |
| // packet is recommended to use instead of the "S" packet. |
| // |
| // "TAAkey1:value1;key2:value2;..." |
| // "T" means a thread stopped due to a unix signal where "AA" is a hex |
| // signal number that describes why the program stopped. This is |
| // followed by a series of key/value pairs: |
| // - If key is a hex number, it is a register number and value is |
| // the hex value of the register in debuggee endian byte order. |
| // - If key == "thread", then the value is the big endian hex |
| // thread-id of the stopped thread. |
| // - If key == "core", then value is a hex number of the core on |
| // which the stop was detected. |
| // - If key == "watch" or key == "rwatch" or key == "awatch", then |
| // value is the data address in big endian hex |
| // - If key == "library", then value is ignore and "qXfer:libraries:read" |
| // packets should be used to detect any newly loaded shared libraries |
| // |
| // "WAA" |
| // "W" means the process exited and "AA" is the exit status. |
| // |
| // "XAA" |
| // "X" means the process exited and "AA" is signal that caused the program |
| // to exit. |
| // |
| // "O<ascii-hex-string>" |
| // "O" means STDOUT has data that was written to its console and is |
| // being delivered to the debugger. This packet happens asynchronously |
| // and the debugger is expected to continue to way for another stop reply |
| // packet. |
| // |
| // LLDB EXTENSIONS |
| // |
| // We have extended the "T" packet to be able to also understand the |
| // following keys and values: |
| // |
| // KEY VALUE DESCRIPTION |
| // =========== ======== ================================================ |
| // "metype" unsigned mach exception type (the value of the EXC_XXX enumerations) |
| // as an unsigned integer. For targets with mach |
| // kernels only. |
| // |
| // "mecount" unsigned mach exception data count as an unsigned integer |
| // For targets with mach kernels only. |
| // |
| // "medata" unsigned There should be "mecount" of these and it is the data |
| // that goes along with a mach exception (as an unsigned |
| // integer). For targets with mach kernels only. |
| // |
| // "name" string The name of the thread as a plain string. The string |
| // must not contain an special packet characters or |
| // contain a ':' or a ';'. Use "hexname" if the thread |
| // name has special characters. |
| // |
| // "hexname" ascii-hex An ASCII hex string that contains the name of the thread |
| // |
| // "qaddr" hex Big endian hex value that contains the libdispatch |
| // queue address for the queue of the thread. |
| // |
| // "reason" enum The enumeration must be one of: |
| // "trace" the program stopped after a single instruction |
| // was executed on a core. Usually done when single |
| // stepping past a breakpoint |
| // "breakpoint" a breakpoint set using a 'z' packet was hit. |
| // "trap" stopped due to user interruption |
| // "signal" stopped due to an actual unix signal, not |
| // just the debugger using a unix signal to keep |
| // the GDB remote client happy. |
| // "watchpoint". Should be used in conjunction with |
| // the "watch"/"rwatch"/"awatch" key value pairs. |
| // "exception" an exception stop reason. Use with |
| // the "description" key/value pair to describe the |
| // exceptional event the user should see as the stop |
| // reason. |
| // "description" ascii-hex An ASCII hex string that contains a more descriptive |
| // reason that the thread stopped. This is only needed |
| // if none of the key/value pairs are enough to |
| // describe why something stopped. |
| // |
| // BEST PRACTICES: |
| // Since register values can be supplied with this packet, it is often useful |
| // to return the PC, SP, FP, LR (if any), and FLAGS registers so that separate |
| // packets don't need to be sent to read each of these registers from each |
| // thread. |
| // |
| // If a thread is stopped for no reason (like just because another thread |
| // stopped, or because when one core stops all cores should stop), use a |
| // "T" packet with "00" as the signal number and fill in as many key values |
| // and registers as possible. |
| // |
| // LLDB likes to know why a thread stopped since many thread control |
| // operations like stepping over a source line, actually are implemented |
| // by running the process multiple times. If a breakpoint is hit while |
| // trying to step over a source line and LLDB finds out that a breakpoint |
| // is hit in the "reason", we will know to stop trying to do the step |
| // over because something happened that should stop us from trying to |
| // do the step. If we are at a breakpoint and we disable the breakpoint |
| // at the current PC and do an instruction single step, knowing that |
| // we stopped due to a "trace" helps us know that we can continue |
| // running versus stopping due to a "breakpoint" (if we have two |
| // breakpoint instruction on consecutive instructions). So the more info |
| // we can get about the reason a thread stops, the better job LLDB can |
| // do when controlling your process. A typical GDB server behavior is |
| // to send a SIGTRAP for breakpoints _and_ also when instruction single |
| // stepping, in this case the debugger doesn't really know why we |
| // stopped and it can make it hard for the debugger to control your |
| // program correctly. What if a real SIGTRAP was delivered to a thread |
| // while we were trying to single step? We wouldn't know the difference |
| // with a standard GDB remote server and we could do the wrong thing. |
| // |
| // PRIORITY TO IMPLEMENT |
| // High. Having the extra information in your stop reply packets makes |
| // your debug session more reliable and informative. |
| //---------------------------------------------------------------------- |
| |
