Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 mimize 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 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 61 | set program arguments(reserved) Aarglen,argnum,arg,... |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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). |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 318 | uint (unsigned integer) |
| 319 | sint (signed integer) |
| 320 | ieee754 (IEEE 754 float) |
| 321 | vector (vector regsiter) |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 322 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 323 | format The preferred format for display of this register. The value must |
| 324 | be one of: |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 325 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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 |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 338 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 339 | set The regiter set name as a string that this register belongs to. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 340 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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). |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 344 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 345 | NOTE: If the compiler doesn't have a register number for this |
| 346 | register, this key/value pair should be omitted. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 347 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 348 | dwarf The DWARF register number for this register that is used for this |
| 349 | register in the debug information. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 350 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 351 | NOTE: If the compiler doesn't have a register number for this |
| 352 | register, this key/value pair should be omitted. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 353 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 354 | generic If the register is a generic register that most CPUs have, classify |
| 355 | it correctly so the debugger knows. Valid values are one of: |
| 356 | pc (a program counter register. for example "name=eip;" (i386), |
| 357 | "name=rip;" (x86_64), "name=r15;" (32 bit arm) would |
| 358 | include a "generic=pc;" key value pair) |
| 359 | sp (a stack pointer register. for example "name=esp;" (i386), |
| 360 | "name=rsp;" (x86_64), "name=r13;" (32 bit arm) would |
| 361 | include a "generic=sp;" key value pair) |
| 362 | fp (a frame pointer register. for example "name=ebp;" (i386), |
| 363 | "name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx |
| 364 | ABI) would include a "generic=fp;" key value pair) |
| 365 | ra (a return address register. for example "name=lr;" (32 bit ARM) |
| 366 | would include a "generic=ra;" key value pair) |
| 367 | fp (a CPU flags register. for example "name=eflags;" (i386), |
| 368 | "name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM) |
| 369 | would include a "generic=flags;" key value pair) |
| 370 | arg1 - arg8 (specified for registers that contain function |
| 371 | arguments when the argument fits into a register) |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 372 | |
| 373 | //---------------------------------------------------------------------- |
| 374 | // "qHostInfo" |
| 375 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 376 | // BRIEF |
| 377 | // Get information about the host we are remotely connected to. |
| 378 | // |
| 379 | // PRIORITY TO IMPLEMENT |
| 380 | // High. This packet is usually very easy to implement and can help |
| 381 | // LLDB select the correct plug-ins for the job based on the target |
| 382 | // triple information that is suppied. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 383 | //---------------------------------------------------------------------- |
| 384 | |
| 385 | LLDB supports a host info call that gets all sorts of details of the system |
| 386 | that is being debugged: |
| 387 | |
| 388 | send packet: $qHostInfo#00 |
| 389 | read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00 |
| 390 | |
| 391 | Key value pairs are one of: |
| 392 | |
| 393 | cputype: is a number that is the mach-o CPU type that is being debugged |
| 394 | cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged |
| 395 | ostype: is a string the represents the OS being debugged (darwin, lunix, freebsd) |
| 396 | vendor: is a string that represents the vendor (apple) |
| 397 | endian: is one of "little", "big", or "pdp" |
| 398 | ptrsize: is a number that represents how big pointers are in bytes on the debug target |
| 399 | |
| 400 | //---------------------------------------------------------------------- |
| 401 | // "qShlibInfoAddr" |
| 402 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 403 | // BRIEF |
| 404 | // Get an address where the dynamic linker stores information about |
| 405 | // where shared libraries are loaded. |
| 406 | // |
| 407 | // PRIORITY TO IMPLEMENT |
| 408 | // High if you have a dynamic loader plug-in in LLDB for your target |
| 409 | // triple (see the "qHostInfo" packet) that can use this information. |
| 410 | // Many times address load randomization can make it hard to detect |
| 411 | // where the dynamic loader binary and data structures are located and |
| 412 | // some platforms know, or can find out where this information is. |
| 413 | // |
| 414 | // Low if you have a debug target where all object and symbol files |
| 415 | // contain static load addresses. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 416 | //---------------------------------------------------------------------- |
| 417 | |
| 418 | LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each |
| 419 | debugger as to where to find the dynamic loader information. For darwin |
| 420 | binaires that run in user land this is the address of the "all_image_infos" |
| 421 | stucture in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO |
| 422 | call. The result is returned as big endian hex bytes that are the address |
| 423 | value: |
| 424 | |
| 425 | send packet: $qShlibInfoAddr#00 |
| 426 | read packet: $7fff5fc40040#00 |
| 427 | |
| 428 | |
| 429 | |
| 430 | //---------------------------------------------------------------------- |
| 431 | // "qThreadStopInfo<tid>" |
| 432 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 433 | // BRIEF |
| 434 | // Get information about why a thread, whose ID is "<tid>", is stopped. |
| 435 | // |
| 436 | // PRIORITY TO IMPLEMENT |
| 437 | // High if you need to support multi-threaded or multi-core debugging. |
| 438 | // Many times one thread will hit a breakpoint and while the debugger |
| 439 | // is in the process of suspending the other threads, other threads |
| 440 | // will also hit a breakpoint. This packet allows LLDB to know why all |
| 441 | // threads (live system debug) / cores (JTAG) in your program have |
| 442 | // stopped and allows LLDB to display and control your program |
| 443 | // correctly. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 444 | //---------------------------------------------------------------------- |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 445 | |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 446 | LLDB tries to use the "qThreadStopInfo" packet which is formatted as |
| 447 | "qThreadStopInfo%x" where %x is the hex thread ID. This requests information |
| 448 | about why a thread is stopped. The response is the same as the stop reply |
| 449 | packets and tells us what happened to the other threads. The standard GDB |
| 450 | remote packets love to think that there is only _one_ reason that _one_ thread |
| 451 | stops at a time. This allows us to see why all threads stopped and allows us |
| 452 | to implement better multi-threaded debugging support. |
| 453 | |
| 454 | //---------------------------------------------------------------------- |
| 455 | // "QThreadSuffixSupported" |
| 456 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 457 | // BRIEF |
| 458 | // Try to enable thread suffix support for the 'g', 'G', 'p', and 'P' |
| 459 | // packets. |
| 460 | // |
| 461 | // PRIORITY TO IMPLEMENT |
| 462 | // High. Adding a thread suffix allows us to read and write registers |
| 463 | // more efficiently and stops us from having to select a thread with |
| 464 | // one packet and then read registers with a second packet. It also |
| 465 | // makes sure that no errors can occur where the debugger thinks it |
| 466 | // already has a thread selected (see the "Hg" packet from the standard |
| 467 | // GDB remote protocol documentation) yet the remote GDB server actually |
| 468 | // has another thread selected. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 469 | //---------------------------------------------------------------------- |
| 470 | |
| 471 | When reading thread registers, you currently need to set the current |
| 472 | thread,then read the registers. This is kind of cumbersome, so we added the |
| 473 | ability to query if the remote GDB server supports adding a "thread:<tid>;" |
| 474 | suffix to all packets that request information for a thread. To test if the |
| 475 | remote GDB server supports this feature: |
| 476 | |
| 477 | send packet: $QThreadSuffixSupported#00 |
| 478 | read packet: OK |
| 479 | |
| 480 | If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a |
| 481 | thread suffix. So to send a 'g' packet (read all register values): |
| 482 | |
| 483 | send packet: $g;thread:<tid>;#00 |
| 484 | read packet: .... |
| 485 | |
| 486 | send packet: $G;thread:<tid>;#00 |
| 487 | read packet: .... |
| 488 | |
| 489 | send packet: $p1a;thread:<tid>;#00 |
| 490 | read packet: .... |
| 491 | |
| 492 | send packet: $P1a=1234abcd;thread:<tid>;#00 |
| 493 | read packet: .... |
| 494 | |
| 495 | |
| 496 | otherwise, without this you would need to always send two packets: |
| 497 | |
| 498 | send packet: $Hg<tid>#00 |
| 499 | read packet: .... |
| 500 | send packet: $g#00 |
| 501 | read packet: .... |
| 502 | |
| 503 | We also added support for allocating and deallocating memory. We use this to |
| 504 | allocate memory so we can run JITed code. |
| 505 | |
| 506 | //---------------------------------------------------------------------- |
| 507 | // "_M<size>,<permissions>" |
| 508 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 509 | // BRIEF |
| 510 | // Allocate memory on the remote target with the specified size and |
| 511 | // permissions. |
| 512 | // |
| 513 | // PRIORITY TO IMPLEMENT |
| 514 | // High if you want LLDB to be able to JIT code and run that code. JIT |
| 515 | // code also needs data which is also allocated and tracked. |
| 516 | // |
| 517 | // Low if you don't support running JIT'ed code. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 518 | //---------------------------------------------------------------------- |
| 519 | |
| 520 | The allocate memory packet starts with "_M<size>,<permissions>". It returns a |
| 521 | raw big endian address value, or "" for unimplemented, or "EXX" for an error |
| 522 | code. The packet is formatted as: |
| 523 | |
| 524 | char packet[256]; |
| 525 | int packet_len; |
| 526 | packet_len = ::snprintf ( |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 527 | packet, |
| 528 | sizeof(packet), |
| 529 | "_M%zx,%s%s%s", |
| 530 | (size_t)size, |
| 531 | permissions & lldb::ePermissionsReadable ? "r" : "", |
| 532 | permissions & lldb::ePermissionsWritable ? "w" : "", |
| 533 | permissions & lldb::ePermissionsExecutable ? "x" : ""); |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 534 | |
| 535 | You request a size and give the permissions. This packet does NOT need to be |
| 536 | implemented if you don't want to support running JITed code. The return value |
| 537 | is just the address of the newly allocated memory as raw big endian hex bytes. |
| 538 | |
| 539 | //---------------------------------------------------------------------- |
| 540 | // "_m<addr>" |
| 541 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 542 | // BRIEF |
| 543 | // Deallocate memory that was previously allocated using an allocate |
| 544 | // memory pack. |
| 545 | // |
| 546 | // PRIORITY TO IMPLEMENT |
| 547 | // High if you want LLDB to be able to JIT code and run that code. JIT |
| 548 | // code also needs data which is also allocated and tracked. |
| 549 | // |
| 550 | // Low if you don't support running JIT'ed code. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 551 | //---------------------------------------------------------------------- |
| 552 | |
| 553 | The deallocate memory packet is "_m<addr>" where you pass in the address you |
| 554 | got back from a previous call to the allocate memory packet. It returns "OK" |
| 555 | if the memory was successfully deallocated, or "EXX" for an error, or "" if |
| 556 | not supported. |
| 557 | |
| 558 | //---------------------------------------------------------------------- |
| 559 | // "qMemoryRegionInfo:<addr>" |
| 560 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 561 | // BRIEF |
| 562 | // Get information about the address the range that contains "<addr>" |
| 563 | // |
| 564 | // PRIORITY TO IMPLEMENT |
| 565 | // Medium. This is nice to have, but it isn't necessary. It helps LLDB |
| 566 | // do stack unwinding when we branch into memory that isn't executable. |
| 567 | // If we can detect that the code we are stopped in isn't executable, |
| 568 | // then we can recover registers for stack frames above the current |
| 569 | // frame. Otherwise we must assume we are in some JIT'ed code (not JIT |
| 570 | // code that LLDB has made) and assume that no registers are available |
| 571 | // in higher stack frames. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 572 | //---------------------------------------------------------------------- |
| 573 | |
| 574 | We added a way to get information for a memory region. The packet is: |
| 575 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 576 | qMemoryRegionInfo:<addr> |
| 577 | |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 578 | Where <addr> is a big endian hex address. The response is returned in a series |
| 579 | of tuples like the data returned in a stop reply packet. The currently valid |
| 580 | tuples tp return are: |
| 581 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 582 | start:<start-addr>; // <start-addr> is a big endian hex address that is |
| 583 | // the start address of the range that contains <addr> |
| 584 | |
| 585 | size:<size>; // <size> is a big endian hex byte size of the address |
| 586 | // of the range that contains <addr> |
| 587 | |
| 588 | permissions:<permissions>; // <permissions> is a string that contains one |
| 589 | // or more of the characters from "rwx" |
| 590 | |
| 591 | error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is |
| 592 | // a hex encoded string value that |
| 593 | // contains an error string |
| 594 | |
Jason Molenda | 1f9c39c | 2011-12-13 05:39:38 +0000 | [diff] [blame] | 595 | If the address requested is not in a mapped region (e.g. we've jumped through |
| 596 | a NULL pointer and are at 0x0) currently lldb expects to get back the size |
| 597 | of the unmapped region -- that is, the distance to the next valid region. |
| 598 | For instance, with a Mac OS X process which has nothing mapped in the first |
| 599 | 4GB of its address space, if we're asking about address 0x2, |
| 600 | |
| 601 | qMemoryRegionInfo:2 |
| 602 | start:2;size:fffffffe; |
| 603 | |
| 604 | The lack of 'permissions:' indicates that none of read/write/execute are valid |
| 605 | for this region. |
| 606 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 607 | //---------------------------------------------------------------------- |
| 608 | // Stop reply packet extensions |
| 609 | // |
| 610 | // BRIEF |
| 611 | // This section describes some of the additional information you can |
| 612 | // specify in stop reply packets that help LLDB to know more detailed |
| 613 | // information about your threads. |
| 614 | // |
| 615 | // DESCRIPTION |
| 616 | // Standard GDB remote stop reply packets are reply packets sent in |
| 617 | // response to a packet that made the program run. They come in the |
| 618 | // following forms: |
| 619 | // |
| 620 | // "SAA" |
| 621 | // "S" means signal and "AA" is a hex signal number that describes why |
| 622 | // the thread or stopped. It doesn't specify which thread, so the "T" |
| 623 | // packet is recommended to use instead of the "S" packet. |
| 624 | // |
| 625 | // "TAAkey1:value1;key2:value2;..." |
| 626 | // "T" means a thread stopped due to a unix signal where "AA" is a hex |
| 627 | // signal number that describes why the program stopped. This is |
| 628 | // followed by a series of key/value pairs: |
| 629 | // - If key is a hex number, it is a register number and value is |
| 630 | // the hex value of the register in debuggee endian byte order. |
| 631 | // - If key == "thread", then the value is the big endian hex |
| 632 | // thread-id of the stopped thread. |
| 633 | // - If key == "core", then value is a hex nujber of the core on |
| 634 | // which the stop was detected. |
| 635 | // - If key == "watch" or key == "rwatch" or key == "awatch", then |
| 636 | // value is the data address in big endian hex |
| 637 | // - If key == "library", then value is ignore and "qXfer:libraries:read" |
| 638 | // packets should be used to detect any newly loaded shared libraries |
| 639 | // |
| 640 | // "WAA" |
| 641 | // "W" means the process exited and "AA" is the exit status. |
| 642 | // |
| 643 | // "XAA" |
| 644 | // "X" means the process exited and "AA" is signal that caused the program |
| 645 | // to exit. |
| 646 | // |
| 647 | // "O<ascii-hex-string>" |
| 648 | // "O" means STDOUT has data that was written to its console and is |
| 649 | // being delivered to the debugger. This packet happens asynchronously |
| 650 | // and the debugger is expected to continue to way for another stop reply |
| 651 | // packet. |
| 652 | // |
| 653 | // LLDB EXTENSIONS |
| 654 | // |
| 655 | // We have extended the "T" packet to be able to also understand the |
| 656 | // following keys and values: |
| 657 | // |
| 658 | // KEY VALUE DESCRIPTION |
| 659 | // =========== ======== ================================================ |
| 660 | // "metype" unsigned mach exception type (the value of the EXC_XXX enumerations) |
| 661 | // as an unsigned integer. For targets with mach |
| 662 | // kernels only. |
| 663 | // |
| 664 | // "mecount" unsigned mach exception data count as an unsigned integer |
| 665 | // For targets with mach kernels only. |
| 666 | // |
| 667 | // "medata" unsigned There should be "mecount" of these and it is the data |
| 668 | // that goes along with a mach exception (as an unsigned |
| 669 | // integer). For targets with mach kernels only. |
| 670 | // |
| 671 | // "name" string The name of the thread as a plain string. The string |
| 672 | // must not contain an special packet characters or |
| 673 | // contain a ':' or a ';'. Use "hexname" if the thread |
| 674 | // name has special characters. |
| 675 | // |
| 676 | // "hexname" ascii-hex An ASCII hex string that contains the name of the thread |
| 677 | // |
| 678 | // "qaddr" hex Big endian hex value that contains the libdispatch |
| 679 | // queue address for the queue of the thread. |
| 680 | // |
| 681 | // "reason" enum The enumeration must be one of: |
| 682 | // "trace" the program stopped after a single instruction |
| 683 | // was executed on a core. Usually done when single |
| 684 | // stepping past a breakpoint |
| 685 | // "breakpoint" a breakpoint set using a 'z' packet was hit. |
| 686 | // "trap" stopped due to user interruption |
| 687 | // "signal" stopped due to an actual unix signal, not |
| 688 | // just the debugger using a unix signal to keep |
| 689 | // the GDB remote client happy. |
| 690 | // "watchpoint". Should be used in conjunction with |
| 691 | // the "watch"/"rwatch"/"awatch" key value pairs. |
| 692 | // "exception" an exception stop reason. Use with |
| 693 | // the "description" key/value pair to describe the |
| 694 | // exceptional event the user should see as the stop |
| 695 | // reason. |
| 696 | // "description" ascii-hex An ASCII hex string that contains a more descriptive |
| 697 | // reason that the thread stopped. This is only needed |
| 698 | // if none of the key/value pairs are enough to |
| 699 | // describe why something stopped. |
| 700 | // |
| 701 | // BEST PRACTICES: |
| 702 | // Since register values can be supplied with this packet, it is often useful |
| 703 | // to return the PC, SP, FP, LR (if any), and FLAGS regsiters so that separate |
| 704 | // packets don't need to be sent to read each of these registers from each |
| 705 | // thread. |
| 706 | // |
| 707 | // If a thread is stopped for no reason (like just because another thread |
| 708 | // stopped, or because when one core stops all cores should stop), use a |
| 709 | // "T" packet with "00" as the signal number and fill in as many key values |
| 710 | // and registers as possible. |
| 711 | // |
| 712 | // LLDB likes to know why a thread stopped since many thread contol |
| 713 | // operations like stepping over a source line, actually are implemented |
| 714 | // by running the process multiple times. If a breakpoint is hit while |
| 715 | // trying to step over a source line and LLDB finds out that a breakpoint |
| 716 | // is hit in the "reason", we will know to stop trying to do the step |
| 717 | // over because something happened that should stop us from trying to |
| 718 | // do the step. If we are at a breakpoint and we disable the breakpoint |
| 719 | // at the current PC and do an instruction single step, knowing that |
| 720 | // we stopped due to a "trace" helps us know that we can continue |
| 721 | // running versus stopping due to a "breakpoint" (if we have two |
| 722 | // breakpoint instruction on consucutive instructions). So the more info |
| 723 | // we can get about the reason a thread stops, the better job LLDB can |
| 724 | // do when controlling your process. A typical GDB server behavior is |
| 725 | // to send a SIGTRAP for breakpoints _and_ also when instruction single |
| 726 | // stepping, in this case the debugger doesn't really know why we |
| 727 | // stopped and it can make it hard for the debugger to control your |
| 728 | // program correctly. What if a real SIGTRAP was delivered to a thread |
| 729 | // while we were trying to single step? We woudn't know the difference |
| 730 | // with a standard GDB remote server and we could do the wrong thing. |
| 731 | // |
| 732 | // PRIORITY TO IMPLEMENT |
| 733 | // High. Having the extra information in your stop reply packets makes |
| 734 | // your debug session more reliable and informative. |
| 735 | //---------------------------------------------------------------------- |
| 736 | |