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 |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 30 | have a way to disable ACK packets to minimize the traffic for reliable |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 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 | |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 339 | set The register 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 |
Greg Clayton | cc464d3 | 2013-03-12 00:14:38 +0000 | [diff] [blame] | 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". |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 346 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 347 | NOTE: If the compiler doesn't have a register number for this |
| 348 | register, this key/value pair should be omitted. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 349 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 350 | dwarf The DWARF register number for this register that is used for this |
Greg Clayton | cc464d3 | 2013-03-12 00:14:38 +0000 | [diff] [blame] | 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". |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 354 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 355 | NOTE: If the compiler doesn't have a register number for this |
| 356 | register, this key/value pair should be omitted. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 357 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 358 | generic If the register is a generic register that most CPUs have, classify |
| 359 | it correctly so the debugger knows. Valid values are one of: |
| 360 | pc (a program counter register. for example "name=eip;" (i386), |
| 361 | "name=rip;" (x86_64), "name=r15;" (32 bit arm) would |
| 362 | include a "generic=pc;" key value pair) |
| 363 | sp (a stack pointer register. for example "name=esp;" (i386), |
| 364 | "name=rsp;" (x86_64), "name=r13;" (32 bit arm) would |
| 365 | include a "generic=sp;" key value pair) |
| 366 | fp (a frame pointer register. for example "name=ebp;" (i386), |
| 367 | "name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx |
| 368 | ABI) would include a "generic=fp;" key value pair) |
| 369 | ra (a return address register. for example "name=lr;" (32 bit ARM) |
| 370 | would include a "generic=ra;" key value pair) |
| 371 | fp (a CPU flags register. for example "name=eflags;" (i386), |
| 372 | "name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM) |
| 373 | would include a "generic=flags;" key value pair) |
| 374 | arg1 - arg8 (specified for registers that contain function |
| 375 | arguments when the argument fits into a register) |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 376 | |
Greg Clayton | 1218c9f | 2013-01-21 23:18:28 +0000 | [diff] [blame] | 377 | container-regs |
Greg Clayton | cc464d3 | 2013-03-12 00:14:38 +0000 | [diff] [blame] | 378 | The value for this key is a comma separated list of raw hex (optional |
Jason Molenda | b5ebe11 | 2013-01-23 04:38:32 +0000 | [diff] [blame] | 379 | leading "0x") register numbers. |
Greg Clayton | 1218c9f | 2013-01-21 23:18:28 +0000 | [diff] [blame] | 380 | |
Jason Molenda | b5ebe11 | 2013-01-23 04:38:32 +0000 | [diff] [blame] | 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 | |
Greg Clayton | 1218c9f | 2013-01-21 23:18:28 +0000 | [diff] [blame] | 401 | invalidate-regs |
Greg Clayton | cc464d3 | 2013-03-12 00:14:38 +0000 | [diff] [blame] | 402 | The value for this key is a comma separated list of raw hex (optional |
Jason Molenda | b5ebe11 | 2013-01-23 04:38:32 +0000 | [diff] [blame] | 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: |
Greg Clayton | 1218c9f | 2013-01-21 23:18:28 +0000 | [diff] [blame] | 410 | |
Jason Molenda | b5ebe11 | 2013-01-23 04:38:32 +0000 | [diff] [blame] | 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. |
Greg Clayton | 1218c9f | 2013-01-21 23:18:28 +0000 | [diff] [blame] | 422 | |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 423 | //---------------------------------------------------------------------- |
| 424 | // "qHostInfo" |
| 425 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 433 | //---------------------------------------------------------------------- |
| 434 | |
| 435 | LLDB supports a host info call that gets all sorts of details of the system |
| 436 | that is being debugged: |
| 437 | |
| 438 | send packet: $qHostInfo#00 |
| 439 | read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00 |
| 440 | |
| 441 | Key value pairs are one of: |
| 442 | |
| 443 | cputype: is a number that is the mach-o CPU type that is being debugged |
| 444 | cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 445 | ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 446 | vendor: is a string that represents the vendor (apple) |
| 447 | endian: is one of "little", "big", or "pdp" |
| 448 | ptrsize: is a number that represents how big pointers are in bytes on the debug target |
| 449 | |
| 450 | //---------------------------------------------------------------------- |
Jason Molenda | 2b67961 | 2012-12-18 04:39:43 +0000 | [diff] [blame] | 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. |
Jason Molenda | fe55567 | 2012-12-19 02:54:03 +0000 | [diff] [blame] | 460 | // e.g. on a 64-bit x86 Mac system both 32-bit and 64-bit user processes are possible, |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 461 | // and with Mach-O universal files, the executable file may contain both 32- and |
Jason Molenda | 2b67961 | 2012-12-18 04:39:43 +0000 | [diff] [blame] | 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. |
Jason Molenda | fe55567 | 2012-12-19 02:54:03 +0000 | [diff] [blame] | 464 | // |
| 465 | // All numeric fields return base-16 numbers without any "0x" prefix. |
Jason Molenda | 2b67961 | 2012-12-18 04:39:43 +0000 | [diff] [blame] | 466 | //---------------------------------------------------------------------- |
| 467 | |
Jason Molenda | fe55567 | 2012-12-19 02:54:03 +0000 | [diff] [blame] | 468 | An i386 process: |
| 469 | |
Jason Molenda | 2b67961 | 2012-12-18 04:39:43 +0000 | [diff] [blame] | 470 | send packet: $qProcessInfo#00 |
Jason Molenda | fe55567 | 2012-12-19 02:54:03 +0000 | [diff] [blame] | 471 | read packet: $pid:42a8;parent-pid:42bf;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:7;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:4;#00 |
| 472 | |
| 473 | An x86_64 process: |
| 474 | |
| 475 | send packet: $qProcessInfo#00 |
| 476 | read packet: $pid:d22c;parent-pid:d34d;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:1000007;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:8;#00 |
Jason Molenda | 2b67961 | 2012-12-18 04:39:43 +0000 | [diff] [blame] | 477 | |
| 478 | Key value pairs include: |
| 479 | |
| 480 | pid: the process id |
| 481 | parent-pid: the process of the parent process (often debugserver will become the parent when attaching) |
| 482 | real-uid: the real user id of the process |
| 483 | real-gid: the real group id of the process |
| 484 | effective-uid: the effective user id of the process |
| 485 | effective-gid: the effective group id of the process |
| 486 | cputype: the Mach-O CPU type of the process |
Jason Molenda | fe55567 | 2012-12-19 02:54:03 +0000 | [diff] [blame] | 487 | cpusubtype: the Mach-O CPU subtype of the process |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 488 | ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) |
Jason Molenda | fe55567 | 2012-12-19 02:54:03 +0000 | [diff] [blame] | 489 | vendor: is a string that represents the vendor (apple) |
| 490 | endian: is one of "little", "big", or "pdp" |
Jason Molenda | 2b67961 | 2012-12-18 04:39:43 +0000 | [diff] [blame] | 491 | ptrsize: is a number that represents how big pointers are in bytes |
| 492 | |
| 493 | |
| 494 | //---------------------------------------------------------------------- |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 495 | // "qShlibInfoAddr" |
| 496 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 510 | //---------------------------------------------------------------------- |
| 511 | |
| 512 | LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each |
| 513 | debugger as to where to find the dynamic loader information. For darwin |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 514 | binaries that run in user land this is the address of the "all_image_infos" |
| 515 | structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 516 | call. The result is returned as big endian hex bytes that are the address |
| 517 | value: |
| 518 | |
| 519 | send packet: $qShlibInfoAddr#00 |
| 520 | read packet: $7fff5fc40040#00 |
| 521 | |
| 522 | |
| 523 | |
| 524 | //---------------------------------------------------------------------- |
| 525 | // "qThreadStopInfo<tid>" |
| 526 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 538 | //---------------------------------------------------------------------- |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 539 | |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 540 | LLDB tries to use the "qThreadStopInfo" packet which is formatted as |
| 541 | "qThreadStopInfo%x" where %x is the hex thread ID. This requests information |
| 542 | about why a thread is stopped. The response is the same as the stop reply |
| 543 | packets and tells us what happened to the other threads. The standard GDB |
| 544 | remote packets love to think that there is only _one_ reason that _one_ thread |
| 545 | stops at a time. This allows us to see why all threads stopped and allows us |
| 546 | to implement better multi-threaded debugging support. |
| 547 | |
| 548 | //---------------------------------------------------------------------- |
| 549 | // "QThreadSuffixSupported" |
| 550 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 563 | //---------------------------------------------------------------------- |
| 564 | |
| 565 | When reading thread registers, you currently need to set the current |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 566 | thread, then read the registers. This is kind of cumbersome, so we added the |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 567 | ability to query if the remote GDB server supports adding a "thread:<tid>;" |
| 568 | suffix to all packets that request information for a thread. To test if the |
| 569 | remote GDB server supports this feature: |
| 570 | |
| 571 | send packet: $QThreadSuffixSupported#00 |
| 572 | read packet: OK |
| 573 | |
| 574 | If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a |
| 575 | thread suffix. So to send a 'g' packet (read all register values): |
| 576 | |
| 577 | send packet: $g;thread:<tid>;#00 |
| 578 | read packet: .... |
| 579 | |
| 580 | send packet: $G;thread:<tid>;#00 |
| 581 | read packet: .... |
| 582 | |
| 583 | send packet: $p1a;thread:<tid>;#00 |
| 584 | read packet: .... |
| 585 | |
| 586 | send packet: $P1a=1234abcd;thread:<tid>;#00 |
| 587 | read packet: .... |
| 588 | |
| 589 | |
| 590 | otherwise, without this you would need to always send two packets: |
| 591 | |
| 592 | send packet: $Hg<tid>#00 |
| 593 | read packet: .... |
| 594 | send packet: $g#00 |
| 595 | read packet: .... |
| 596 | |
| 597 | We also added support for allocating and deallocating memory. We use this to |
| 598 | allocate memory so we can run JITed code. |
| 599 | |
| 600 | //---------------------------------------------------------------------- |
| 601 | // "_M<size>,<permissions>" |
| 602 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 612 | //---------------------------------------------------------------------- |
| 613 | |
| 614 | The allocate memory packet starts with "_M<size>,<permissions>". It returns a |
| 615 | raw big endian address value, or "" for unimplemented, or "EXX" for an error |
| 616 | code. The packet is formatted as: |
| 617 | |
| 618 | char packet[256]; |
| 619 | int packet_len; |
| 620 | packet_len = ::snprintf ( |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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" : ""); |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 628 | |
| 629 | You request a size and give the permissions. This packet does NOT need to be |
| 630 | implemented if you don't want to support running JITed code. The return value |
| 631 | is just the address of the newly allocated memory as raw big endian hex bytes. |
| 632 | |
| 633 | //---------------------------------------------------------------------- |
| 634 | // "_m<addr>" |
| 635 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 645 | //---------------------------------------------------------------------- |
| 646 | |
| 647 | The deallocate memory packet is "_m<addr>" where you pass in the address you |
| 648 | got back from a previous call to the allocate memory packet. It returns "OK" |
| 649 | if the memory was successfully deallocated, or "EXX" for an error, or "" if |
| 650 | not supported. |
| 651 | |
| 652 | //---------------------------------------------------------------------- |
| 653 | // "qMemoryRegionInfo:<addr>" |
| 654 | // |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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. |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 666 | //---------------------------------------------------------------------- |
| 667 | |
| 668 | We added a way to get information for a memory region. The packet is: |
| 669 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 670 | qMemoryRegionInfo:<addr> |
| 671 | |
Greg Clayton | 8e276bd | 2011-11-28 23:30:42 +0000 | [diff] [blame] | 672 | Where <addr> is a big endian hex address. The response is returned in a series |
| 673 | of tuples like the data returned in a stop reply packet. The currently valid |
| 674 | tuples tp return are: |
| 675 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 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 | |
Jason Molenda | 1f9c39c | 2011-12-13 05:39:38 +0000 | [diff] [blame] | 689 | If the address requested is not in a mapped region (e.g. we've jumped through |
| 690 | a NULL pointer and are at 0x0) currently lldb expects to get back the size |
| 691 | of the unmapped region -- that is, the distance to the next valid region. |
| 692 | For instance, with a Mac OS X process which has nothing mapped in the first |
| 693 | 4GB of its address space, if we're asking about address 0x2, |
| 694 | |
| 695 | qMemoryRegionInfo:2 |
| 696 | start:2;size:fffffffe; |
| 697 | |
| 698 | The lack of 'permissions:' indicates that none of read/write/execute are valid |
| 699 | for this region. |
| 700 | |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 701 | //---------------------------------------------------------------------- |
| 702 | // Stop reply packet extensions |
| 703 | // |
| 704 | // BRIEF |
| 705 | // This section describes some of the additional information you can |
| 706 | // specify in stop reply packets that help LLDB to know more detailed |
| 707 | // information about your threads. |
| 708 | // |
| 709 | // DESCRIPTION |
| 710 | // Standard GDB remote stop reply packets are reply packets sent in |
| 711 | // response to a packet that made the program run. They come in the |
| 712 | // following forms: |
| 713 | // |
| 714 | // "SAA" |
| 715 | // "S" means signal and "AA" is a hex signal number that describes why |
| 716 | // the thread or stopped. It doesn't specify which thread, so the "T" |
| 717 | // packet is recommended to use instead of the "S" packet. |
| 718 | // |
| 719 | // "TAAkey1:value1;key2:value2;..." |
| 720 | // "T" means a thread stopped due to a unix signal where "AA" is a hex |
| 721 | // signal number that describes why the program stopped. This is |
| 722 | // followed by a series of key/value pairs: |
| 723 | // - If key is a hex number, it is a register number and value is |
| 724 | // the hex value of the register in debuggee endian byte order. |
| 725 | // - If key == "thread", then the value is the big endian hex |
| 726 | // thread-id of the stopped thread. |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 727 | // - If key == "core", then value is a hex number of the core on |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 728 | // which the stop was detected. |
| 729 | // - If key == "watch" or key == "rwatch" or key == "awatch", then |
| 730 | // value is the data address in big endian hex |
| 731 | // - If key == "library", then value is ignore and "qXfer:libraries:read" |
| 732 | // packets should be used to detect any newly loaded shared libraries |
| 733 | // |
| 734 | // "WAA" |
| 735 | // "W" means the process exited and "AA" is the exit status. |
| 736 | // |
| 737 | // "XAA" |
| 738 | // "X" means the process exited and "AA" is signal that caused the program |
| 739 | // to exit. |
| 740 | // |
| 741 | // "O<ascii-hex-string>" |
| 742 | // "O" means STDOUT has data that was written to its console and is |
| 743 | // being delivered to the debugger. This packet happens asynchronously |
| 744 | // and the debugger is expected to continue to way for another stop reply |
| 745 | // packet. |
| 746 | // |
| 747 | // LLDB EXTENSIONS |
| 748 | // |
| 749 | // We have extended the "T" packet to be able to also understand the |
| 750 | // following keys and values: |
| 751 | // |
| 752 | // KEY VALUE DESCRIPTION |
| 753 | // =========== ======== ================================================ |
| 754 | // "metype" unsigned mach exception type (the value of the EXC_XXX enumerations) |
| 755 | // as an unsigned integer. For targets with mach |
| 756 | // kernels only. |
| 757 | // |
| 758 | // "mecount" unsigned mach exception data count as an unsigned integer |
| 759 | // For targets with mach kernels only. |
| 760 | // |
| 761 | // "medata" unsigned There should be "mecount" of these and it is the data |
| 762 | // that goes along with a mach exception (as an unsigned |
| 763 | // integer). For targets with mach kernels only. |
| 764 | // |
| 765 | // "name" string The name of the thread as a plain string. The string |
| 766 | // must not contain an special packet characters or |
| 767 | // contain a ':' or a ';'. Use "hexname" if the thread |
| 768 | // name has special characters. |
| 769 | // |
| 770 | // "hexname" ascii-hex An ASCII hex string that contains the name of the thread |
| 771 | // |
| 772 | // "qaddr" hex Big endian hex value that contains the libdispatch |
| 773 | // queue address for the queue of the thread. |
| 774 | // |
| 775 | // "reason" enum The enumeration must be one of: |
| 776 | // "trace" the program stopped after a single instruction |
| 777 | // was executed on a core. Usually done when single |
| 778 | // stepping past a breakpoint |
| 779 | // "breakpoint" a breakpoint set using a 'z' packet was hit. |
| 780 | // "trap" stopped due to user interruption |
| 781 | // "signal" stopped due to an actual unix signal, not |
| 782 | // just the debugger using a unix signal to keep |
| 783 | // the GDB remote client happy. |
| 784 | // "watchpoint". Should be used in conjunction with |
| 785 | // the "watch"/"rwatch"/"awatch" key value pairs. |
| 786 | // "exception" an exception stop reason. Use with |
| 787 | // the "description" key/value pair to describe the |
| 788 | // exceptional event the user should see as the stop |
| 789 | // reason. |
| 790 | // "description" ascii-hex An ASCII hex string that contains a more descriptive |
| 791 | // reason that the thread stopped. This is only needed |
| 792 | // if none of the key/value pairs are enough to |
| 793 | // describe why something stopped. |
| 794 | // |
| 795 | // BEST PRACTICES: |
| 796 | // Since register values can be supplied with this packet, it is often useful |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 797 | // to return the PC, SP, FP, LR (if any), and FLAGS registers so that separate |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 798 | // packets don't need to be sent to read each of these registers from each |
| 799 | // thread. |
| 800 | // |
| 801 | // If a thread is stopped for no reason (like just because another thread |
| 802 | // stopped, or because when one core stops all cores should stop), use a |
| 803 | // "T" packet with "00" as the signal number and fill in as many key values |
| 804 | // and registers as possible. |
| 805 | // |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 806 | // LLDB likes to know why a thread stopped since many thread control |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 807 | // operations like stepping over a source line, actually are implemented |
| 808 | // by running the process multiple times. If a breakpoint is hit while |
| 809 | // trying to step over a source line and LLDB finds out that a breakpoint |
| 810 | // is hit in the "reason", we will know to stop trying to do the step |
| 811 | // over because something happened that should stop us from trying to |
| 812 | // do the step. If we are at a breakpoint and we disable the breakpoint |
| 813 | // at the current PC and do an instruction single step, knowing that |
| 814 | // we stopped due to a "trace" helps us know that we can continue |
| 815 | // running versus stopping due to a "breakpoint" (if we have two |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 816 | // breakpoint instruction on consecutive instructions). So the more info |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 817 | // we can get about the reason a thread stops, the better job LLDB can |
| 818 | // do when controlling your process. A typical GDB server behavior is |
| 819 | // to send a SIGTRAP for breakpoints _and_ also when instruction single |
| 820 | // stepping, in this case the debugger doesn't really know why we |
| 821 | // stopped and it can make it hard for the debugger to control your |
| 822 | // program correctly. What if a real SIGTRAP was delivered to a thread |
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 823 | // while we were trying to single step? We wouldn't know the difference |
Greg Clayton | 9a181f4 | 2011-11-29 01:44:07 +0000 | [diff] [blame] | 824 | // with a standard GDB remote server and we could do the wrong thing. |
| 825 | // |
| 826 | // PRIORITY TO IMPLEMENT |
| 827 | // High. Having the extra information in your stop reply packets makes |
| 828 | // your debug session more reliable and informative. |
| 829 | //---------------------------------------------------------------------- |
| 830 | |