docs/lldb-gdb-remote.txt

   1 LLDB has added new GDB server packets to better support multi-threaded and
   2 remote debugging. Why? Normally you need to start the correct GDB and the
   3 correct GDB server when debugging. If you have mismatch, then things go wrong
   4 very quickly. LLDB makes extensive use of the GDB remote protocol and we
   5 wanted to make sure that the experience was a bit more dynamic where we can
   6 discover information about a remote target with having to know anything up
   7 front. We also ran into performance issues with the existing GDB remote
   8 protocol that can be overcome when using a reliable communications layer.
   9 Some packets improve performance, others allow for remote process launching
  10 (if you have an OS), and others allow us to dynamically figure out what
  11 registers a thread might have. Again with GDB, both sides pre-agree on how the
  12 registers will look (how many, their register number,name and offsets). We
  13 prefer to be able to dynamically determine what kind of architecture, OS and
  14 vendor we are debugging, as well as how things are laid out when it comes to
  15 the thread register contexts. Below are the details on the new packets we have
  16 added above and beyond the standard GDB remote protocol packets.
  17
  18 //----------------------------------------------------------------------
  19 // "QStartNoAckMode"
  20 //
  21 // BRIEF
  22 //  Try to enable no ACK mode to skip sending ACKs and NACKs.
  23 //
  24 // PRIORITY TO IMPLEMENT
  25 //  High. Any GDB remote server that can implement this should if the
  26 //  connection is reliable. This improves packet throughput and increases
  27 //  the performance of the connection.
  28 //----------------------------------------------------------------------
  29 Having to send an ACK/NACK after every packet slows things down a bit, so we
  30 have a way to disable ACK packets to minimize the traffic for reliable
  31 communication interfaces (like sockets). Below GDB or LLDB will send this
  32 packet to try and disable ACKs. All lines that start with "send packet: " are
  33 from GDB/LLDB, and all lines that start with "read packet: " are from the GDB
  34 remote server:
  35
  36 send packet: $QStartNoAckMode#b0
  37 read packet: +
  38 read packet: $OK#9a
  39 send packet: +
  40
  41
  42
  43 //----------------------------------------------------------------------
  44 // "A" - launch args packet
  45 //
  46 // BRIEF
  47 //  Launch a program using the supplied arguments
  48 //
  49 // PRIORITY TO IMPLEMENT
  50 //  Low. Only needed if the remote target wants to launch a target after
  51 //  making a connection to a GDB server that isn't already connected to
  52 //  an inferior process.
  53 //----------------------------------------------------------------------
  54
  55 We have added support for the "set program arguments" packet where we can
  56 start a connection to a remote server and then later supply the path to the
  57 executable and the arguments to use when executing:
  58
  59 GDB remote docs for this:
  60
  61 set program arguments(reserved) Aarglen,argnum,arg,...
  62
  63 Where A is followed by the length in bytes of the hex encoded argument,
  64 followed by an argument integer, and followed by the ASCII characters
  65 converted into hex bytes foreach arg
  66
  67 send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00
  68 read packet: $OK#00
  69
  70 The above packet helps when you have remote debugging abilities where you
  71 could launch a process on a remote host, this isn't needed for bare board
  72 debugging.
  73
  74 //----------------------------------------------------------------------
  75 // "QEnvironment:NAME=VALUE"
  76 //
  77 // BRIEF
  78 //  Setup the environment up for a new child process that will soon be
  79 //  launched using the "A" packet.
  80 //
  81 // NB: key/value pairs are sent as-is so gdb-remote protocol meta characters
  82 //     (e.g. '#' or '$') are not acceptable.  If any non-printable or
  83 //     metacharacters are present in the strings, QEnvironmentHexEncoded
  84 //     should be used instead if it is available.  If you don't want to
  85 //     scan the environment strings before sending, prefer
  86 //     the QEnvironmentHexEncoded packet over QEnvironment, if it is
  87 //     available.
  88 //
  89 // PRIORITY TO IMPLEMENT
  90 //  Low. Only needed if the remote target wants to launch a target after
  91 //  making a connection to a GDB server that isn't already connected to
  92 //  an inferior process.
  93 //----------------------------------------------------------------------
  94
  95 Both GDB and LLDB support passing down environment variables. Is it ok to
  96 respond with a "$#00" (unimplemented):
  97
  98 send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00
  99 read packet: $OK#00
 100
 101 This packet can be sent one or more times _prior_ to sending a "A" packet.
 102
 103 //----------------------------------------------------------------------
 104 // "QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)"
 105 //
 106 // BRIEF
 107 //  Setup the environment up for a new child process that will soon be
 108 //  launched using the "A" packet.
 109 //
 110 // The only difference between this packet and QEnvironment is that the
 111 // environment key-value pair is ascii hex encoded for transmission.
 112 // This allows values with gdb-remote metacharacters like '#' to be sent.
 113 //
 114 // PRIORITY TO IMPLEMENT
 115 //  Low. Only needed if the remote target wants to launch a target after
 116 //  making a connection to a GDB server that isn't already connected to
 117 //  an inferior process.
 118 //----------------------------------------------------------------------
 119
 120 Both GDB and LLDB support passing down environment variables. Is it ok to
 121 respond with a "$#00" (unimplemented):
 122
 123 send packet: $QEnvironment:41434b5f434f4c4f525f46494c454e414d453d626f6c642379656c6c6f77#00
 124 read packet: $OK#00
 125
 126 This packet can be sent one or more times _prior_ to sending a "A" packet.
 127
 128 //----------------------------------------------------------------------
 129 // "QSetSTDIN:<ascii-hex-path>"
 130 // "QSetSTDOUT:<ascii-hex-path>"
 131 // "QSetSTDERR:<ascii-hex-path>"
 132 //
 133 // BRIEF
 134 //  Setup where STDIN, STDOUT, and STDERR go prior to sending an "A"
 135 //  packet.
 136 //
 137 // PRIORITY TO IMPLEMENT
 138 //  Low. Only needed if the remote target wants to launch a target after
 139 //  making a connection to a GDB server that isn't already connected to
 140 //  an inferior process.
 141 //----------------------------------------------------------------------
 142
 143 When launching a program through the GDB remote protocol with the "A" packet,
 144 you might also want to specify where stdin/out/err go:
 145
 146 QSetSTDIN:<ascii-hex-path>
 147 QSetSTDOUT:<ascii-hex-path>
 148 QSetSTDERR:<ascii-hex-path>
 149
 150 These packets must be sent  _prior_ to sending a "A" packet.
 151
 152 //----------------------------------------------------------------------
 153 // "QSetWorkingDir:<ascii-hex-path>"
 154 //
 155 // BRIEF
 156 //  Set the working directory prior to sending an "A" packet.
 157 //
 158 // PRIORITY TO IMPLEMENT
 159 //  Low. Only needed if the remote target wants to launch a target after
 160 //  making a connection to a GDB server that isn't already connected to
 161 //  an inferior process.
 162 //----------------------------------------------------------------------
 163
 164 Or specify the working directory:
 165
 166 QSetWorkingDir:<ascii-hex-path>
 167
 168 This packet must be sent  _prior_ to sending a "A" packet.
 169
 170 //----------------------------------------------------------------------
 171 // "QSetDisableASLR:<bool>"
 172 //
 173 // BRIEF
 174 //  Enable or disable ASLR on the next "A" packet.
 175 //
 176 // PRIORITY TO IMPLEMENT
 177 //  Low. Only needed if the remote target wants to launch a target after
 178 //  making a connection to a GDB server that isn't already connected to
 179 //  an inferior process and if the target supports disabling ASLR
 180 //  (Address space layout randomization).
 181 //----------------------------------------------------------------------
 182
 183 Or control if ASLR is enabled/disabled:
 184
 185 send packet: QSetDisableASLR:1
 186 read packet: OK
 187
 188 send packet: QSetDisableASLR:0
 189 read packet: OK
 190
 191 This packet must be sent  _prior_ to sending a "A" packet.
 192
 193 //----------------------------------------------------------------------
 194 // QListThreadsInStopReply
 195 //
 196 // BRIEF
 197 //  Enable the threads: and thread-pcs: data in the question-mark packet
 198 //  ("T packet") responses when the stub reports that a program has
 199 //  stopped executing.
 200 //
 201 // PRIORITY TO IMPLEMENT
 202 //  Performance.  This is a performance benefit to lldb if the thread id's
 203 //  and thread pc values are provided to lldb in the T stop packet -- if
 204 //  they are not provided to lldb, lldb will likely need to send one to
 205 //  two packets per thread to fetch the data at every private stop.
 206 //----------------------------------------------------------------------
 207
 208 send packet: QListThreadsInStopReply
 209 read packet: OK
 210
 211 //----------------------------------------------------------------------
 212 // "qRegisterInfo<hex-reg-id>"
 213 //
 214 // BRIEF
 215 //  Discover register information from the remote GDB server.
 216 //
 217 // PRIORITY TO IMPLEMENT
 218 //  High. Any target that can self describe its registers, should do so.
 219 //  This means if new registers are ever added to a remote target, they
 220 //  will get picked up automatically, and allows registers to change
 221 //  depending on the actual CPU type that is used.
 222 //
 223 //  NB: As of summer 2015, lldb can get register information from the
 224 //  "qXfer:features:read:target.xml" FSF gdb standard register packet
 225 //  where the stub provides register definitions in an XML file.
 226 //  If qXfer:features:read:target.xml is supported, qRegisterInfo does
 227 //  not need to be implemented.
 228 //----------------------------------------------------------------------
 229
 230 With LLDB, for register information, remote GDB servers can add
 231 support for the "qRegisterInfoN" packet where "N" is a zero based
 232 base16 register number that must start at zero and increase by one
 233 for each register that is supported.  The response is done in typical
 234 GDB remote fashion where a series of "KEY:VALUE;" pairs are returned.
 235 An example for the x86_64 registers is included below:
 236
 237 send packet: $qRegisterInfo0#00
 238 read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00
 239 send packet: $qRegisterInfo1#00
 240 read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00
 241 send packet: $qRegisterInfo2#00
 242 read packet: $name:rcx;bitsize:64;offset:16;encoding:uint;format:hex;set:General Purpose Registers;gcc:2;dwarf:2;#00
 243 send packet: $qRegisterInfo3#00
 244 read packet: $name:rdx;bitsize:64;offset:24;encoding:uint;format:hex;set:General Purpose Registers;gcc:1;dwarf:1;#00
 245 send packet: $qRegisterInfo4#00
 246 read packet: $name:rdi;bitsize:64;offset:32;encoding:uint;format:hex;set:General Purpose Registers;gcc:5;dwarf:5;#00
 247 send packet: $qRegisterInfo5#00
 248 read packet: $name:rsi;bitsize:64;offset:40;encoding:uint;format:hex;set:General Purpose Registers;gcc:4;dwarf:4;#00
 249 send packet: $qRegisterInfo6#00
 250 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
 251 send packet: $qRegisterInfo7#00
 252 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
 253 send packet: $qRegisterInfo8#00
 254 read packet: $name:r8;bitsize:64;offset:64;encoding:uint;format:hex;set:General Purpose Registers;gcc:8;dwarf:8;#00
 255 send packet: $qRegisterInfo9#00
 256 read packet: $name:r9;bitsize:64;offset:72;encoding:uint;format:hex;set:General Purpose Registers;gcc:9;dwarf:9;#00
 257 send packet: $qRegisterInfoa#00
 258 read packet: $name:r10;bitsize:64;offset:80;encoding:uint;format:hex;set:General Purpose Registers;gcc:10;dwarf:10;#00
 259 send packet: $qRegisterInfob#00
 260 read packet: $name:r11;bitsize:64;offset:88;encoding:uint;format:hex;set:General Purpose Registers;gcc:11;dwarf:11;#00
 261 send packet: $qRegisterInfoc#00
 262 read packet: $name:r12;bitsize:64;offset:96;encoding:uint;format:hex;set:General Purpose Registers;gcc:12;dwarf:12;#00
 263 send packet: $qRegisterInfod#00
 264 read packet: $name:r13;bitsize:64;offset:104;encoding:uint;format:hex;set:General Purpose Registers;gcc:13;dwarf:13;#00
 265 send packet: $qRegisterInfoe#00
 266 read packet: $name:r14;bitsize:64;offset:112;encoding:uint;format:hex;set:General Purpose Registers;gcc:14;dwarf:14;#00
 267 send packet: $qRegisterInfof#00
 268 read packet: $name:r15;bitsize:64;offset:120;encoding:uint;format:hex;set:General Purpose Registers;gcc:15;dwarf:15;#00
 269 send packet: $qRegisterInfo10#00
 270 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
 271 send packet: $qRegisterInfo11#00
 272 read packet: $name:rflags;alt-name:flags;bitsize:64;offset:136;encoding:uint;format:hex;set:General Purpose Registers;#00
 273 send packet: $qRegisterInfo12#00
 274 read packet: $name:cs;bitsize:64;offset:144;encoding:uint;format:hex;set:General Purpose Registers;#00
 275 send packet: $qRegisterInfo13#00
 276 read packet: $name:fs;bitsize:64;offset:152;encoding:uint;format:hex;set:General Purpose Registers;#00
 277 send packet: $qRegisterInfo14#00
 278 read packet: $name:gs;bitsize:64;offset:160;encoding:uint;format:hex;set:General Purpose Registers;#00
 279 send packet: $qRegisterInfo15#00
 280 read packet: $name:fctrl;bitsize:16;offset:176;encoding:uint;format:hex;set:Floating Point Registers;#00
 281 send packet: $qRegisterInfo16#00
 282 read packet: $name:fstat;bitsize:16;offset:178;encoding:uint;format:hex;set:Floating Point Registers;#00
 283 send packet: $qRegisterInfo17#00
 284 read packet: $name:ftag;bitsize:8;offset:180;encoding:uint;format:hex;set:Floating Point Registers;#00
 285 send packet: $qRegisterInfo18#00
 286 read packet: $name:fop;bitsize:16;offset:182;encoding:uint;format:hex;set:Floating Point Registers;#00
 287 send packet: $qRegisterInfo19#00
 288 read packet: $name:fioff;bitsize:32;offset:184;encoding:uint;format:hex;set:Floating Point Registers;#00
 289 send packet: $qRegisterInfo1a#00
 290 read packet: $name:fiseg;bitsize:16;offset:188;encoding:uint;format:hex;set:Floating Point Registers;#00
 291 send packet: $qRegisterInfo1b#00
 292 read packet: $name:fooff;bitsize:32;offset:192;encoding:uint;format:hex;set:Floating Point Registers;#00
 293 send packet: $qRegisterInfo1c#00
 294 read packet: $name:foseg;bitsize:16;offset:196;encoding:uint;format:hex;set:Floating Point Registers;#00
 295 send packet: $qRegisterInfo1d#00
 296 read packet: $name:mxcsr;bitsize:32;offset:200;encoding:uint;format:hex;set:Floating Point Registers;#00
 297 send packet: $qRegisterInfo1e#00
 298 read packet: $name:mxcsrmask;bitsize:32;offset:204;encoding:uint;format:hex;set:Floating Point Registers;#00
 299 send packet: $qRegisterInfo1f#00
 300 read packet: $name:stmm0;bitsize:80;offset:208;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:33;dwarf:33;#00
 301 send packet: $qRegisterInfo20#00
 302 read packet: $name:stmm1;bitsize:80;offset:224;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:34;dwarf:34;#00
 303 send packet: $qRegisterInfo21#00
 304 read packet: $name:stmm2;bitsize:80;offset:240;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:35;dwarf:35;#00
 305 send packet: $qRegisterInfo22#00
 306 read packet: $name:stmm3;bitsize:80;offset:256;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:36;dwarf:36;#00
 307 send packet: $qRegisterInfo23#00
 308 read packet: $name:stmm4;bitsize:80;offset:272;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:37;dwarf:37;#00
 309 send packet: $qRegisterInfo24#00
 310 read packet: $name:stmm5;bitsize:80;offset:288;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:38;dwarf:38;#00
 311 send packet: $qRegisterInfo25#00
 312 read packet: $name:stmm6;bitsize:80;offset:304;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:39;dwarf:39;#00
 313 send packet: $qRegisterInfo26#00
 314 read packet: $name:stmm7;bitsize:80;offset:320;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:40;dwarf:40;#00
 315 send packet: $qRegisterInfo27#00
 316 read packet: $name:xmm0;bitsize:128;offset:336;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:17;dwarf:17;#00
 317 send packet: $qRegisterInfo28#00
 318 read packet: $name:xmm1;bitsize:128;offset:352;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:18;dwarf:18;#00
 319 send packet: $qRegisterInfo29#00
 320 read packet: $name:xmm2;bitsize:128;offset:368;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:19;dwarf:19;#00
 321 send packet: $qRegisterInfo2a#00
 322 read packet: $name:xmm3;bitsize:128;offset:384;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:20;dwarf:20;#00
 323 send packet: $qRegisterInfo2b#00
 324 read packet: $name:xmm4;bitsize:128;offset:400;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:21;dwarf:21;#00
 325 send packet: $qRegisterInfo2c#00
 326 read packet: $name:xmm5;bitsize:128;offset:416;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:22;dwarf:22;#00
 327 send packet: $qRegisterInfo2d#00
 328 read packet: $name:xmm6;bitsize:128;offset:432;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:23;dwarf:23;#00
 329 send packet: $qRegisterInfo2e#00
 330 read packet: $name:xmm7;bitsize:128;offset:448;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:24;dwarf:24;#00
 331 send packet: $qRegisterInfo2f#00
 332 read packet: $name:xmm8;bitsize:128;offset:464;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:25;dwarf:25;#00
 333 send packet: $qRegisterInfo30#00
 334 read packet: $name:xmm9;bitsize:128;offset:480;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:26;dwarf:26;#00
 335 send packet: $qRegisterInfo31#00
 336 read packet: $name:xmm10;bitsize:128;offset:496;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:27;dwarf:27;#00
 337 send packet: $qRegisterInfo32#00
 338 read packet: $name:xmm11;bitsize:128;offset:512;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:28;dwarf:28;#00
 339 send packet: $qRegisterInfo33#00
 340 read packet: $name:xmm12;bitsize:128;offset:528;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:29;dwarf:29;#00
 341 send packet: $qRegisterInfo34#00
 342 read packet: $name:xmm13;bitsize:128;offset:544;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:30;dwarf:30;#00
 343 send packet: $qRegisterInfo35#00
 344 read packet: $name:xmm14;bitsize:128;offset:560;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:31;dwarf:31;#00
 345 send packet: $qRegisterInfo36#00
 346 read packet: $name:xmm15;bitsize:128;offset:576;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:32;dwarf:32;#00
 347 send packet: $qRegisterInfo37#00
 348 read packet: $name:trapno;bitsize:32;offset:696;encoding:uint;format:hex;set:Exception State Registers;#00
 349 send packet: $qRegisterInfo38#00
 350 read packet: $name:err;bitsize:32;offset:700;encoding:uint;format:hex;set:Exception State Registers;#00
 351 send packet: $qRegisterInfo39#00
 352 read packet: $name:faultvaddr;bitsize:64;offset:704;encoding:uint;format:hex;set:Exception State Registers;#00
 353 send packet: $qRegisterInfo3a#00
 354 read packet: $E45#00
 355
 356 As we see above we keep making subsequent calls to the remote server to
 357 discover all registers by increasing the number appended to qRegisterInfo and
 358 we get a response back that is a series of "key=value;" strings.
 359
 360 The offset: fields should not leave a gap anywhere in the g/G packet -- the
 361 register values should be appended one after another.  For instance, if the
 362 register context for a thread looks like
 363
 364 struct rctx {
 365     uint32_t gpr1;  // offset 0
 366     uint32_t gpr2;  // offset 4
 367     uint32_t gpr3;  // offset 8
 368     uint64_t fp1;   // offset 16
 369 };
 370
 371 You may end up with a 4-byte gap between gpr3 and fp1 on architectures
 372 that align values like this.  The correct offset: value for fp1 is 12 -
 373 in the g/G packet fp1 will immediately follow gpr3, even though the
 374 in-memory thread structure has an empty 4 bytes for alignment between
 375 these two registers.
 376
 377 The keys and values are detailed below:
 378
 379 Key         Value
 380 ==========  ================================================================
 381 name        The primary register name as a string ("rbp" for example)
 382
 383 alt-name    An alternate name for a register as a string ("fp" for example for
 384             the above "rbp")
 385
 386 bitsize     Size in bits of a register (32, 64, etc).  Base 10.
 387
 388 offset      The offset within the "g" and "G" packet of the register data for
 389             this register.  This is the byte offset once the data has been
 390             transformed into binary, not the character offset into the g/G
 391             packet.  Base 10.
 392
 393 encoding    The encoding type of the register which must be one of:
 394
 395                  uint (unsigned integer)
 396                  sint (signed integer)
 397                  ieee754 (IEEE 754 float)
 398                  vector (vector register)
 399
 400 format      The preferred format for display of this register. The value must
 401             be one of:
 402
 403                 binary
 404                 decimal
 405                 hex
 406                 float
 407                 vector-sint8
 408                 vector-uint8
 409                 vector-sint16
 410                 vector-uint16
 411                 vector-sint32
 412                 vector-uint32
 413                 vector-float32
 414                 vector-uint128
 415
 416 set         The register set name as a string that this register belongs to.
 417
 418 gcc         The GCC compiler registers number for this register (used for
 419             EH frame and other compiler information that is encoded in the
 420             executable files). The supplied number will be decoded like a
 421             string passed to strtoul() with a base of zero, so the number
 422             can be decimal, or hex if it is prefixed with "0x".
 423
 424             NOTE: If the compiler doesn't have a register number for this
 425             register, this key/value pair should be omitted.
 426
 427 dwarf       The DWARF register number for this register that is used for this
 428             register in the debug information. The supplied number will be decoded
 429             like a string passed to strtoul() with a base of zero, so the number
 430             can be decimal, or hex if it is prefixed with "0x".
 431
 432             NOTE: If the compiler doesn't have a register number for this
 433             register, this key/value pair should be omitted.
 434
 435 generic     If the register is a generic register that most CPUs have, classify
 436             it correctly so the debugger knows. Valid values are one of:
 437              pc  (a program counter register. for example "name=eip;" (i386),
 438                   "name=rip;" (x86_64), "name=r15;" (32 bit arm) would
 439                   include a "generic=pc;" key value pair)
 440              sp  (a stack pointer register. for example "name=esp;" (i386),
 441                   "name=rsp;" (x86_64), "name=r13;" (32 bit arm) would
 442                   include a "generic=sp;" key value pair)
 443              fp  (a frame pointer register. for example "name=ebp;" (i386),
 444                    "name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx
 445                    ABI) would include a "generic=fp;" key value pair)
 446              ra  (a return address register. for example "name=lr;" (32 bit ARM)
 447                   would include a "generic=ra;" key value pair)
 448              fp  (a CPU flags register. for example "name=eflags;" (i386),
 449                   "name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM)
 450                   would include a "generic=flags;" key value pair)
 451              arg1 - arg8 (specified for registers that contain function
 452                       arguments when the argument fits into a register)
 453
 454 container-regs
 455             The value for this key is a comma separated list of raw hex (optional
 456             leading "0x") register numbers.
 457
 458             This specifies that this register is contained in other concrete
 459             register values. For example "eax" is in the lower 32 bits of the
 460             "rax" register value for x86_64, so "eax" could specify that it is
 461             contained in "rax" by specifying the register number for "rax" (whose
 462             register number is 0x00)
 463
 464             "container-regs:00;"
 465
 466             If a register is comprised of one or more registers, like "d0" is ARM
 467             which is a 64 bit register, it might be made up of "s0" and "s1". If
 468             the register number for "s0" is 0x20, and the register number of "s1"
 469             is "0x21", the "container-regs" key/value pair would be:
 470
 471             "container-regs:20,21;"
 472
 473             This is handy for defining what GDB used to call "pseudo" registers.
 474             These registers are never requested by LLDB via the register read
 475             or write packets, the container registers will be requested on behalf
 476             of this register.
 477
 478 invalidate-regs
 479             The value for this key is a comma separated list of raw hex (optional
 480             leading "0x") register numbers.
 481
 482             This specifies which register values should be invalidated when this
 483             register is modified. For example if modifying "eax" would cause "rax",
 484             "eax", "ax", "ah", and "al" to be modified where rax is 0x0, eax is 0x15,
 485             ax is 0x25, ah is 0x35, and al is 0x39, the "invalidate-regs" key/value
 486             pair would be:
 487
 488             "invalidate-regs:0,15,25,35,39;"
 489
 490             If there is a single register that gets invalidated, then omit the comma
 491             and just list a single register:
 492
 493             "invalidate-regs:0;"
 494
 495             This is handy when modifying a specific register can cause other
 496             register values to change. For example, when debugging an ARM target,
 497             modifying the CPSR register can cause the r8 - r14 and cpsr value to
 498             change depending on if the mode has changed.
 499
 500 //----------------------------------------------------------------------
 501 // "qPlatform_shell"
 502 //
 503 // BRIEF
 504 //  Run a command in a shell on the connected remote machine.
 505 //
 506 // PRIORITY TO IMPLEMENT
 507 //  High. This command allows LLDB clients to run arbitrary shell
 508 //  commands on a remote host.
 509 //
 510 /----------------------------------------------------------------------
 511
 512 The request consists of the command to be executed encoded in ASCII characters
 513 converted into hex bytes.
 514
 515 The response to this packet consists of the letter F followed by the return code,
 516 followed by the signal number (or 0 if no signal was delivered), and escaped bytes
 517 of captured program output.
 518
 519 Below is an example communication from a client sending an "ls -la" command:
 520
 521 send packet: $qPlatform_shell:6c73202d6c61,00000002#ec
 522 read packet: $F,00000000,00000000,total 4736
 523 drwxrwxr-x 16 username groupname    4096 Aug 15 21:36 .
 524 drwxr-xr-x 17 username groupname    4096 Aug 10 16:39 ..
 525 -rw-rw-r--  1 username groupname   73875 Aug 12 16:46 notes.txt
 526 drwxrwxr-x  5 username groupname    4096 Aug 15 21:36 source.cpp
 527 -rw-r--r--  1 username groupname    2792 Aug 12 16:46 a.out
 528 -rw-r--r--  1 username groupname    3190 Aug 12 16:46 Makefile
 529
 530 //----------------------------------------------------------------------
 531 // "qPlatform_mkdir"
 532 //
 533 // BRIEF
 534 //  Creates a new directory on the connected remote machine.
 535 //
 536 // PRIORITY TO IMPLEMENT
 537 //  Low. This command allows LLDB clients to create new directories on
 538 //  a remote host.
 539 //
 540 /----------------------------------------------------------------------
 541
 542 Request:
 543     qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path>
 544
 545 Reply:
 546     F<mkdir-return-code>
 547         mkdir called successfully and returned with the given return code
 548     Exx
 549         An error occurred
 550
 551 //----------------------------------------------------------------------
 552 // "qPlatform_chmod"
 553 //
 554 // BRIEF
 555 //  Change the permissions of a file on the connected remote machine.
 556 //
 557 // PRIORITY TO IMPLEMENT
 558 //  Low. This command allows LLDB clients to change the permissions of
 559 //  a file on the remote host.
 560 //
 561 /----------------------------------------------------------------------
 562
 563 Request:
 564     qPlatform_chmod:<hex-file-mode>,<ascii-hex-path>
 565
 566 Reply:
 567     F<chmod-return-code>
 568         chmod called successfully and returned with the given return code
 569     Exx
 570         An error occurred
 571
 572 //----------------------------------------------------------------------
 573 // "qHostInfo"
 574 //
 575 // BRIEF
 576 //  Get information about the host we are remotely connected to.
 577 //
 578 // PRIORITY TO IMPLEMENT
 579 //  High. This packet is usually very easy to implement and can help
 580 //  LLDB select the correct plug-ins for the job based on the target
 581 //  triple information that is supplied.
 582 //----------------------------------------------------------------------
 583
 584 LLDB supports a host info call that gets all sorts of details of the system
 585 that is being debugged:
 586
 587 send packet: $qHostInfo#00
 588 read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00
 589
 590 Key value pairs are one of:
 591
 592 cputype: is a number that is the mach-o CPU type that is being debugged (base 10)
 593 cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged (base 10)
 594 triple: a string for the target triple (x86_64-apple-macosx) that can be used to specify arch + vendor + os in one entry
 595 vendor: a string for the vendor (apple), not needed if "triple" is specified
 596 ostype: a string for the OS being debugged (macosx, linux, freebsd, ios, watchos), not needed if "triple" is specified
 597 endian: is one of "little", "big", or "pdp"
 598 ptrsize: an unsigned number that represents how big pointers are in bytes on the debug target
 599 hostname: the hostname of the host that is running the GDB server if available
 600 os_build: a string for the OS build for the remote host as a string value
 601 os_kernel: a string describing the kernel version
 602 os_version: a version string that represents the current OS version (10.8.2)
 603 watchpoint_exceptions_received: one of "before" or "after" to specify if a watchpoint is triggered before or after the pc when it stops
 604 default_packet_timeout: an unsigned number that specifies the default timeout in seconds
 605 distribution_id: optional. For linux, specifies distribution id (e.g. ubuntu, fedora, etc.)
 606 osmajor: optional, specifies the major version number of the OS (e.g. for Mac OS X 10.11.2, it would be 10)
 607 osminor: optional, specifies the minor version number of the OS (e.g. for Mac OS X 10.11.2, it would be 11)
 608 ospatch: optional, specifies the patch level number of the OS (e.g. for Mac OS X 10.11.2, it would be 2)
 609
 610 //----------------------------------------------------------------------
 611 // "qGDBServerVersion"
 612 //
 613 // BRIEF
 614 //  Get version information about this implementation of the gdb-remote
 615 //  protocol.
 616 //
 617 // PRIORITY TO IMPLEMENT
 618 //  High. This packet is usually very easy to implement and can help
 619 //  LLDB to work around bugs in a server's implementation when they
 620 //  are found.
 621 //----------------------------------------------------------------------
 622
 623 The goal of this packet is to provide enough information about an
 624 implementation of the gdb-remote-protocol server that lldb can
 625 work around implementation problems that are discovered after the
 626 version has been released/deployed.  The name and version number
 627 should be sufficiently unique that lldb can unambiguously identify
 628 the origin of the program (for instance, debugserver from lldb) and
 629 the version/submission number/patch level of the program - whatever
 630 is appropriate for your server implementation.
 631
 632 The packet follows the key-value pair model, semicolon separated.
 633
 634 send packet: $qGDBServerVersion#00
 635 read packet: $name:debugserver;version:310.2;#00
 636
 637 Other clients may find other key-value pairs to be useful for identifying
 638 a gdb stub.  Patch level, release name, build number may all be keys that
 639 better describe your implementation's version.
 640 Suggested key names:
 641
 642   name   : the name of your remote server - "debugserver" is the lldb standard
 643            implementation
 644
 645   version : identifies the version number of this server
 646
 647   patch_level : the patch level of this server
 648
 649   release_name : the name of this release, if your project uses names
 650
 651   build_number : if you use a build system with increasing build numbers,
 652                  this may be the right key name for your server
 653
 654   major_version : major version number
 655   minor_version : minor version number
 656
 657 //----------------------------------------------------------------------
 658 // "qProcessInfo"
 659 //
 660 // BRIEF
 661 //  Get information about the process we are currently debugging.
 662 //
 663 // PRIORITY TO IMPLEMENT
 664 //  Medium.  On systems which can launch multiple different architecture processes,
 665 //  the qHostInfo may not disambiguate sufficiently to know what kind of
 666 //  process is being debugged.
 667 //  e.g. on a 64-bit x86 Mac system both 32-bit and 64-bit user processes are possible,
 668 //  and with Mach-O universal files, the executable file may contain both 32- and
 669 //  64-bit slices so it may be impossible to know until you're attached to a real
 670 //  process to know what you're working with.
 671 //
 672 //  All numeric fields return base-16 numbers without any "0x" prefix.
 673 //----------------------------------------------------------------------
 674
 675 An i386 process:
 676
 677 send packet: $qProcessInfo#00
 678 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
 679
 680 An x86_64 process:
 681
 682 send packet: $qProcessInfo#00
 683 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
 684
 685 Key value pairs include:
 686
 687 pid: the process id
 688 parent-pid: the process of the parent process (often debugserver will become the parent when attaching)
 689 real-uid: the real user id of the process
 690 real-gid: the real group id of the process
 691 effective-uid: the effective user id of the process
 692 effective-gid: the effective group id of the process
 693 cputype: the Mach-O CPU type of the process  (base 16)
 694 cpusubtype: the Mach-O CPU subtype of the process  (base 16)
 695 ostype: is a string the represents the OS being debugged (darwin, linux, freebsd)
 696 vendor: is a string that represents the vendor (apple)
 697 endian: is one of "little", "big", or "pdp"
 698 ptrsize: is a number that represents how big pointers are in bytes
 699
 700
 701 //----------------------------------------------------------------------
 702 // "qShlibInfoAddr"
 703 //
 704 // BRIEF
 705 //  Get an address where the dynamic linker stores information about
 706 //  where shared libraries are loaded.
 707 //
 708 // PRIORITY TO IMPLEMENT
 709 //  High if you have a dynamic loader plug-in in LLDB for your target
 710 //  triple (see the "qHostInfo" packet) that can use this information.
 711 //  Many times address load randomization can make it hard to detect
 712 //  where the dynamic loader binary and data structures are located and
 713 //  some platforms know, or can find out where this information is.
 714 //
 715 //  Low if you have a debug target where all object and symbol files
 716 //  contain static load addresses.
 717 //----------------------------------------------------------------------
 718
 719 LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each
 720 debugger as to where to find the dynamic loader information. For darwin
 721 binaries that run in user land this is the address of the "all_image_infos"
 722 structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO
 723 call. The result is returned as big endian hex bytes that are the address
 724 value:
 725
 726 send packet: $qShlibInfoAddr#00
 727 read packet: $7fff5fc40040#00
 728
 729
 730
 731 //----------------------------------------------------------------------
 732 // "qThreadStopInfo<tid>"
 733 //
 734 // BRIEF
 735 //  Get information about why a thread, whose ID is "<tid>", is stopped.
 736 //
 737 // PRIORITY TO IMPLEMENT
 738 //  High if you need to support multi-threaded or multi-core debugging.
 739 //  Many times one thread will hit a breakpoint and while the debugger
 740 //  is in the process of suspending the other threads, other threads
 741 //  will also hit a breakpoint. This packet allows LLDB to know why all
 742 //  threads (live system debug) / cores (JTAG) in your program have
 743 //  stopped and allows LLDB to display and control your program
 744 //  correctly.
 745 //----------------------------------------------------------------------
 746
 747 LLDB tries to use the "qThreadStopInfo" packet which is formatted as
 748 "qThreadStopInfo%x" where %x is the hex thread ID. This requests information
 749 about why a thread is stopped. The response is the same as the stop reply
 750 packets and tells us what happened to the other threads. The standard GDB
 751 remote packets love to think that there is only _one_ reason that _one_ thread
 752 stops at a time. This allows us to see why all threads stopped and allows us
 753 to implement better multi-threaded debugging support.
 754
 755 //----------------------------------------------------------------------
 756 // "QThreadSuffixSupported"
 757 //
 758 // BRIEF
 759 //  Try to enable thread suffix support for the 'g', 'G', 'p', and 'P'
 760 //  packets.
 761 //
 762 // PRIORITY TO IMPLEMENT
 763 //  High. Adding a thread suffix allows us to read and write registers
 764 //  more efficiently and stops us from having to select a thread with
 765 //  one packet and then read registers with a second packet. It also
 766 //  makes sure that no errors can occur where the debugger thinks it
 767 //  already has a thread selected (see the "Hg" packet from the standard
 768 //  GDB remote protocol documentation) yet the remote GDB server actually
 769 //  has another thread selected.
 770 //----------------------------------------------------------------------
 771
 772 When reading thread registers, you currently need to set the current
 773 thread, then read the registers. This is kind of cumbersome, so we added the
 774 ability to query if the remote GDB server supports adding a "thread:<tid>;"
 775 suffix to all packets that request information for a thread. To test if the
 776 remote GDB server supports this feature:
 777
 778 send packet: $QThreadSuffixSupported#00
 779 read packet: OK
 780
 781 If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a
 782 thread suffix. So to send a 'g' packet (read all register values):
 783
 784 send packet: $g;thread:<tid>;#00
 785 read packet: ....
 786
 787 send packet: $G;thread:<tid>;#00
 788 read packet: ....
 789
 790 send packet: $p1a;thread:<tid>;#00
 791 read packet: ....
 792
 793 send packet: $P1a=1234abcd;thread:<tid>;#00
 794 read packet: ....
 795
 796
 797 otherwise, without this you would need to always send two packets:
 798
 799 send packet: $Hg<tid>#00
 800 read packet: ....
 801 send packet: $g#00
 802 read packet: ....
 803
 804 We also added support for allocating and deallocating memory. We use this to
 805 allocate memory so we can run JITed code.
 806
 807 //----------------------------------------------------------------------
 808 // "_M<size>,<permissions>"
 809 //
 810 // BRIEF
 811 //  Allocate memory on the remote target with the specified size and
 812 //  permissions.
 813 //
 814 // PRIORITY TO IMPLEMENT
 815 //  High if you want LLDB to be able to JIT code and run that code. JIT
 816 //  code also needs data which is also allocated and tracked.
 817 //
 818 //  Low if you don't support running JIT'ed code.
 819 //----------------------------------------------------------------------
 820
 821 The allocate memory packet starts with "_M<size>,<permissions>". It returns a
 822 raw big endian address value, or "" for unimplemented, or "EXX" for an error
 823 code. The packet is formatted as:
 824
 825 char packet[256];
 826 int packet_len;
 827 packet_len = ::snprintf (
 828     packet,
 829     sizeof(packet),
 830     "_M%zx,%s%s%s",
 831     (size_t)size,
 832     permissions & lldb::ePermissionsReadable ? "r" : "",
 833     permissions & lldb::ePermissionsWritable ? "w" : "",
 834     permissions & lldb::ePermissionsExecutable ? "x" : "");
 835
 836 You request a size and give the permissions. This packet does NOT need to be
 837 implemented if you don't want to support running JITed code. The return value
 838 is just the address of the newly allocated memory as raw big endian hex bytes.
 839
 840 //----------------------------------------------------------------------
 841 // "_m<addr>"
 842 //
 843 // BRIEF
 844 //  Deallocate memory that was previously allocated using an allocate
 845 //  memory pack.
 846 //
 847 // PRIORITY TO IMPLEMENT
 848 //  High if you want LLDB to be able to JIT code and run that code. JIT
 849 //  code also needs data which is also allocated and tracked.
 850 //
 851 //  Low if you don't support running JIT'ed code.
 852 //----------------------------------------------------------------------
 853
 854 The deallocate memory packet is "_m<addr>" where you pass in the address you
 855 got back from a previous call to the allocate memory packet. It returns "OK"
 856 if the memory was successfully deallocated, or "EXX" for an error, or "" if
 857 not supported.
 858
 859 //----------------------------------------------------------------------
 860 // "qMemoryRegionInfo:<addr>"
 861 //
 862 // BRIEF
 863 //  Get information about the address range that contains "<addr>"
 864 //
 865 // PRIORITY TO IMPLEMENT
 866 //  Medium. This is nice to have, but it isn't necessary. It helps LLDB
 867 //  do stack unwinding when we branch into memory that isn't executable.
 868 //  If we can detect that the code we are stopped in isn't executable,
 869 //  then we can recover registers for stack frames above the current
 870 //  frame. Otherwise we must assume we are in some JIT'ed code (not JIT
 871 //  code that LLDB has made) and assume that no registers are available
 872 //  in higher stack frames.
 873 //----------------------------------------------------------------------
 874
 875 We added a way to get information for a memory region. The packet is:
 876
 877     qMemoryRegionInfo:<addr>
 878
 879 Where <addr> is a big endian hex address. The response is returned in a series
 880 of tuples like the data returned in a stop reply packet. The currently valid
 881 tuples to return are:
 882
 883     start:<start-addr>; // <start-addr> is a big endian hex address that is
 884                         // the start address of the range that contains <addr>
 885
 886     size:<size>;    // <size> is a big endian hex byte size of the address
 887                     // of the range that contains <addr>
 888
 889     permissions:<permissions>;  // <permissions> is a string that contains one
 890                                 // or more of the characters from "rwx"
 891
 892     name:<name>; // <name> is a hex encoded string that contains the name of
 893                  // the memory region mapped at the given address. In case of
 894                  // regions backed by a file it have to be the absolute path of
 895                  // the file while for anonymous regions it have to be the name
 896                  // associated to the region if that is available.
 897
 898     error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is
 899                                      // a hex encoded string value that
 900                                      // contains an error string
 901
 902 If the address requested is not in a mapped region (e.g. we've jumped through
 903 a NULL pointer and are at 0x0) currently lldb expects to get back the size
 904 of the unmapped region -- that is, the distance to the next valid region.
 905 For instance, with a Mac OS X process which has nothing mapped in the first
 906 4GB of its address space, if we're asking about address 0x2,
 907
 908   qMemoryRegionInfo:2
 909   start:2;size:fffffffe;
 910
 911 The lack of 'permissions:' indicates that none of read/write/execute are valid
 912 for this region.
 913
 914 //----------------------------------------------------------------------
 915 // "x" - Binary memory read
 916 //
 917 // Like the 'm' (read) and 'M' (write) packets, this is a partner to the
 918 // 'X' (write binary data) packet, 'x'.
 919 //
 920 // It is called like
 921 //
 922 // xADDRESS,LENGTH
 923 //
 924 // where both ADDRESS and LENGTH are big-endian base 16 values.
 925 //
 926 // To test if this packet is available, send a addr/len of 0:
 927 //
 928 // x0,0
 929 //
 930 // and you will get an "OK" response.
 931 //
 932 // The reply will be the data requested in 8-bit binary data format.
 933 // The standard quoting is applied to the payload -- characters
 934 //   }  #  $  *
 935 // will all be escaped with '}' (0x7d) character and then XOR'ed with 0x20.
 936 //
 937 // A typical use to read 512 bytes at 0x1000 would look like
 938 //
 939 // x0x1000,0x200
 940 //
 941 // The "0x" prefixes are optional - like most of the gdb-remote packets,
 942 // omitting them will work fine; these numbers are always base 16.
 943 //
 944 // The length of the payload is not provided.  A reliable, 8-bit clean,
 945 // transport layer is assumed.
 946 //----------------------------------------------------------------------
 947
 948 //----------------------------------------------------------------------
 949 // Detach and stay stopped:
 950 //
 951 // We extended the "D" packet to specify that the monitor should keep the
 952 // target suspended on detach.  The normal behavior is to resume execution
 953 // on detach.  We will send:
 954 //
 955 //  qSupportsDetachAndStayStopped:
 956 //
 957 // to query whether the monitor supports the extended detach, and if it does,
 958 // when we want the monitor to detach but not resume the target, we will
 959 // send:
 960 //
 961 //   D1
 962 //
 963 // In any case, if we want the normal detach behavior we will just send:
 964 //
 965 //   D
 966 //----------------------------------------------------------------------
 967
 968 //----------------------------------------------------------------------
 969 // QSaveRegisterState
 970 // QSaveRegisterState;thread:XXXX;
 971 //
 972 // BRIEF
 973 //  The QSaveRegisterState packet tells the remote debugserver to save
 974 //  all registers and return a non-zero unique integer ID that
 975 //  represents these save registers. If thread suffixes are enabled the
 976 //  second form of this packet is used, otherwise the first form is
 977 //  used. This packet is called prior to executing an expression, so
 978 //  the remote GDB server should do anything it needs to in order to
 979 //  ensure the registers that are saved are correct. On MacOSX this
 980 //  involves calling "thread_abort_safely(mach_port_t thread)" to
 981 //  ensure we get the correct registers for a thread in case it is
 982 //  currently having code run on its behalf in the kernel.
 983 //
 984 // RESPONSE
 985 //  unsigned - The save_id result is a non-zero unsigned integer value
 986 //             that can be passed back to the GDB server using a
 987 //             QRestoreRegisterState packet to restore the registers
 988 //             one time.
 989 //  "EXX" - or an error code in the form of EXX where XX is a
 990 //  hex error code.
 991 //
 992 // PRIORITY TO IMPLEMENT
 993 //  Low, this is mostly a convenience packet to avoid having to send all
 994 //  registers via a g packet. It should only be implemented if support
 995 //  for the QRestoreRegisterState is added.
 996 //----------------------------------------------------------------------
 997
 998 //----------------------------------------------------------------------
 999 // QRestoreRegisterState:<save_id>
1000 // QRestoreRegisterState:<save_id>;thread:XXXX;
1001 //
1002 // BRIEF
1003 //  The QRestoreRegisterState packet tells the remote debugserver to
1004 //  restore all registers using the "save_id" which is an unsigned
1005 //  integer that was returned from a previous call to
1006 //  QSaveRegisterState. The restoration process can only be done once
1007 //  as the data backing the register state will be freed upon the
1008 //  completion of the QRestoreRegisterState command.
1009 //
1010 //  If thread suffixes are enabled the second form of this packet is
1011 //  used, otherwise the first form is used.
1012 //
1013 // RESPONSE
1014 //  "OK" - if all registers were successfully restored
1015 //  "EXX" - for any errors
1016 //
1017 // PRIORITY TO IMPLEMENT
1018 //  Low, this is mostly a convenience packet to avoid having to send all
1019 //  registers via a g packet. It should only be implemented if support
1020 //  for the QSaveRegisterState is added.
1021 //----------------------------------------------------------------------
1022
1023 //----------------------------------------------------------------------
1024 // qFileLoadAddress:<file_path>
1025 //
1026 // BRIEF
1027 //  Get the load address of a memory mapped file.
1028 //  The load address is defined as the address of the first memory
1029 //  region what contains data mapped from the specified file.
1030 //
1031 // RESPONSE
1032 //  <unsinged-hex64> - Load address of the file in big endian encoding
1033 //  "E01" - the requested file isn't loaded
1034 //  "EXX" - for any other errors
1035 //
1036 // PRIORITY TO IMPLEMENT
1037 //  Low, required if dynamic linker don't fill in the load address of
1038 //  some object file in the rendezvous data structure.
1039 //----------------------------------------------------------------------
1040
1041 //----------------------------------------------------------------------
1042 // qModuleInfo:<module_path>;<arch triple>
1043 //
1044 // BRIEF
1045 //  Get information for a module by given module path and architecture.
1046 //
1047 // RESPONSE
1048 //  "(uuid|md5):...;triple:...;file_offset:...;file_size...;"
1049 //  "EXX" - for any errors
1050 //
1051 // PRIORITY TO IMPLEMENT
1052 //  Optional, required if dynamic loader cannot fetch module's information like
1053 //  UUID directly from inferior's memory.
1054 //----------------------------------------------------------------------
1055
1056 //----------------------------------------------------------------------
1057 // jModulesInfo:[{"file":"...",triple:"..."}, ...]
1058 //
1059 // BRIEF
1060 //  Get information for a list of modules by given module path and
1061 //  architecture.
1062 //
1063 // RESPONSE
1064 //  A JSON array of dictionaries containing the following keys: uuid,
1065 //  triple, file_path, file_offset, file_size. The meaning of the fields
1066 //  is the same as in the qModuleInfo packet. The server signals the
1067 //  failure to retrieve the module info for a file by ommiting the
1068 //  corresponding array entry from the response. The server may also
1069 //  include entries the client did not ask for, if it has reason to
1070 //  the modules will be interesting to the client.
1071 //
1072 // PRIORITY TO IMPLEMENT
1073 //  Optional. If not implemented, qModuleInfo packet will be used, which
1074 //  may be slower if the target contains a large number of modules and
1075 //  the communication link has a non-negligible latency.
1076 //----------------------------------------------------------------------
1077
1078 //----------------------------------------------------------------------
1079 // Stop reply packet extensions
1080 //
1081 // BRIEF
1082 //  This section describes some of the additional information you can
1083 //  specify in stop reply packets that help LLDB to know more detailed
1084 //  information about your threads.
1085 //
1086 // DESCRIPTION
1087 //  Standard GDB remote stop reply packets are reply packets sent in
1088 //  response to a packet  that made the program run. They come in the
1089 //  following forms:
1090 //
1091 //  "SAA"
1092 //  "S" means signal and "AA" is a hex signal number that describes why
1093 //  the thread or stopped. It doesn't specify which thread, so the "T"
1094 //  packet is recommended to use instead of the "S" packet.
1095 //
1096 //  "TAAkey1:value1;key2:value2;..."
1097 //  "T" means a thread stopped due to a unix signal where "AA" is a hex
1098 //  signal number that describes why the program stopped. This is
1099 //  followed by a series of key/value pairs:
1100 //      - If key is a hex number, it is a register number and value is
1101 //        the hex value of the register in debuggee endian byte order.
1102 //      - If key == "thread", then the value is the big endian hex
1103 //        thread-id of the stopped thread.
1104 //      - If key == "core", then value is a hex number of the core on
1105 //        which the stop was detected.
1106 //      - If key == "watch" or key == "rwatch" or key == "awatch", then
1107 //        value is the data address in big endian hex
1108 //      - If key == "library", then value is ignore and "qXfer:libraries:read"
1109 //        packets should be used to detect any newly loaded shared libraries
1110 //
1111 //  "WAA"
1112 //  "W" means the process exited and "AA" is the exit status.
1113 //
1114 //  "XAA"
1115 //  "X" means the process exited and "AA" is signal that caused the program
1116 //  to exit.
1117 //
1118 //  "O<ascii-hex-string>"
1119 //  "O" means STDOUT has data that was written to its console and is
1120 //  being delivered to the debugger. This packet happens asynchronously
1121 //  and the debugger is expected to continue to wait for another stop reply
1122 //  packet.
1123 //
1124 // LLDB EXTENSIONS
1125 //
1126 //  We have extended the "T" packet to be able to also understand the
1127 //  following keys and values:
1128 //
1129 //  KEY           VALUE     DESCRIPTION
1130 //  ===========   ========  ================================================
1131 //  "metype"      unsigned  mach exception type (the value of the EXC_XXX enumerations)
1132 //                          as an unsigned integer. For targets with mach
1133 //                          kernels only.
1134 //
1135 //  "mecount"     unsigned  mach exception data count as an unsigned integer
1136 //                          For targets with mach kernels only.
1137 //
1138 //  "medata"      unsigned  There should be "mecount" of these and it is the data
1139 //                          that goes along with a mach exception (as an unsigned
1140 //                          integer). For targets with mach kernels only.
1141 //
1142 //  "name"        string    The name of the thread as a plain string. The string
1143 //                          must not contain an special packet characters or
1144 //                          contain a ':' or a ';'. Use "hexname" if the thread
1145 //                          name has special characters.
1146 //
1147 //  "hexname"     ascii-hex An ASCII hex string that contains the name of the thread
1148 //
1149 //  "qaddr"       hex       Big endian hex value that contains the libdispatch
1150 //                          queue address for the queue of the thread.
1151 //
1152 //  "reason"      enum      The enumeration must be one of:
1153 //                          "trace" the program stopped after a single instruction
1154 //                              was executed on a core. Usually done when single
1155 //                              stepping past a breakpoint
1156 //                          "breakpoint" a breakpoint set using a 'z' packet was hit.
1157 //                          "trap" stopped due to user interruption
1158 //                          "signal" stopped due to an actual unix signal, not
1159 //                              just the debugger using a unix signal to keep
1160 //                              the GDB remote client happy.
1161 //                          "watchpoint". Should be used in conjunction with
1162 //                              the "watch"/"rwatch"/"awatch" key value pairs.
1163 //                          "exception" an exception stop reason. Use with
1164 //                              the "description" key/value pair to describe the
1165 //                              exceptional event the user should see as the stop
1166 //                              reason.
1167 //  "description" ascii-hex An ASCII hex string that contains a more descriptive
1168 //                          reason that the thread stopped. This is only needed
1169 //                          if none of the key/value pairs are enough to
1170 //                          describe why something stopped.
1171 //
1172 //  "threads"     comma-sep-base16  A list of thread ids for all threads (including
1173 //                                  the thread that we're reporting as stopped) that
1174 //                                  are live in the process right now.  lldb may
1175 //                                  request that this be included in the T packet via
1176 //                                  the QListThreadsInStopReply packet earlier in
1177 //                                  the debug session.
1178 //
1179 //                                  Example:
1180 //                                  threads:63387,633b2,63424,63462,63486;
1181 //
1182 //  "thread-pcs"  comma-sep-base16  A list of pc values for all threads that currently
1183 //                                  exist in the process, including the thread that
1184 //                                  this T packet is reporting as stopped.
1185 //                                  This key-value pair will only be emitted when the
1186 //                                  "threads" key is already included in the T packet.
1187 //                                  The pc values correspond to the threads reported
1188 //                                  in the "threads" list.  The number of pcs in the
1189 //                                  "thread-pcs" list will be the same as the number of
1190 //                                  threads in the "threads" list.
1191 //                                  lldb may request that this be included in the T
1192 //                                  packet via the QListThreadsInStopReply packet
1193 //                                  earlier in the debug session.
1194 //
1195 //                                  Example:
1196 //                                  thread-pcs:dec14,2cf872b0,2cf8681c,2d02d68c,2cf716a8;
1197 //
1198 // BEST PRACTICES:
1199 //  Since register values can be supplied with this packet, it is often useful
1200 //  to return the PC, SP, FP, LR (if any), and FLAGS registers so that separate
1201 //  packets don't need to be sent to read each of these registers from each
1202 //  thread.
1203 //
1204 //  If a thread is stopped for no reason (like just because another thread
1205 //  stopped, or because when one core stops all cores should stop), use a
1206 //  "T" packet with "00" as the signal number and fill in as many key values
1207 //  and registers as possible.
1208 //
1209 //  LLDB likes to know why a thread stopped since many thread control
1210 //  operations like stepping over a source line, actually are implemented
1211 //  by running the process multiple times. If a breakpoint is hit while
1212 //  trying to step over a source line and LLDB finds out that a breakpoint
1213 //  is hit in the "reason", we will know to stop trying to do the step
1214 //  over because something happened that should stop us from trying to
1215 //  do the step. If we are at a breakpoint and we disable the breakpoint
1216 //  at the current PC and do an instruction single step, knowing that
1217 //  we stopped due to a "trace" helps us know that we can continue
1218 //  running versus stopping due to a "breakpoint" (if we have two
1219 //  breakpoint instruction on consecutive instructions). So the more info
1220 //  we can get about the reason a thread stops, the better job LLDB can
1221 //  do when controlling your process. A typical GDB server behavior is
1222 //  to send a SIGTRAP for breakpoints _and_ also when instruction single
1223 //  stepping, in this case the debugger doesn't really know why we
1224 //  stopped and it can make it hard for the debugger to control your
1225 //  program correctly. What if a real SIGTRAP was delivered to a thread
1226 //  while we were trying to single step? We wouldn't know the difference
1227 //  with a standard GDB remote server and we could do the wrong thing.
1228 //
1229 // PRIORITY TO IMPLEMENT
1230 //  High. Having the extra information in your stop reply packets makes
1231 //  your debug session more reliable and informative.
1232 //----------------------------------------------------------------------
1233
1234
1235 //----------------------------------------------------------------------
1236 // PLATFORM EXTENSION - for use as a GDB remote platform
1237 //----------------------------------------------------------------------
1238 // "qfProcessInfo"
1239 // "qsProcessInfo"
1240 //
1241 // BRIEF
1242 //  Get the first process info (qfProcessInfo) or subsequent process
1243 //  info (qsProcessInfo) for one or more processes on the remote
1244 //  platform. The first call gets the first match and subsequent calls
1245 //  to qsProcessInfo gets the subsequent matches. Return an error EXX,
1246 //  where XX are two hex digits, when no more matches are available.
1247 //
1248 // PRIORITY TO IMPLEMENT
1249 //  Required. The qfProcessInfo packet can be followed by a ':' and
1250 //  some key value pairs. The key value pairs in the command are:
1251 //
1252 //  KEY           VALUE     DESCRIPTION
1253 //  ===========   ========  ================================================
1254 //  "name"        ascii-hex An ASCII hex string that contains the name of
1255 //                          the process that will be matched.
1256 //  "name_match"  enum      One of: "equals", "starts_with", "ends_with",
1257 //                          "contains" or "regex"
1258 //  "pid"         integer   A string value containing the decimal process ID
1259 //  "parent_pid"  integer   A string value containing the decimal parent
1260 //                          process ID
1261 //  "uid"         integer   A string value containing the decimal user ID
1262 //  "gid"         integer   A string value containing the decimal group ID
1263 //  "euid"        integer   A string value containing the decimal effective user ID
1264 //  "egid"        integer   A string value containing the decimal effective group ID
1265 //  "all_users"   bool      A boolean value that specifies if processes should
1266 //                          be listed for all users, not just the user that the
1267 //                          platform is running as
1268 //  "triple"      string    An ASCII triple string ("x86_64",
1269 //                          "x86_64-apple-macosx", "armv7-apple-ios")
1270 //
1271 // The response consists of key/value pairs where the key is separated from the
1272 // values with colons and each pair is terminated with a semi colon. For a list
1273 // of the key/value pairs in the response see the "qProcessInfoPID" packet
1274 // documentation.
1275 //
1276 // Sample packet/response:
1277 // send packet: $qfProcessInfo#00
1278 // read packet: $pid:60001;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:x86_64-apple-macosx;#00
1279 // send packet: $qsProcessInfo#00
1280 // read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:x86_64-apple-macosx;#00
1281 // send packet: $qsProcessInfo#00
1282 // read packet: $E04#00
1283 //----------------------------------------------------------------------
1284
1285
1286 //----------------------------------------------------------------------
1287 // PLATFORM EXTENSION - for use as a GDB remote platform
1288 //----------------------------------------------------------------------
1289 // "qLaunchGDBServer"
1290 //
1291 // BRIEF
1292 //  Have the remote platform launch a GDB server.
1293 //
1294 // PRIORITY TO IMPLEMENT
1295 //  Required. The qLaunchGDBServer packet must be followed by a ':' and
1296 //  some key value pairs. The key value pairs in the command are:
1297 //
1298 //  KEY           VALUE     DESCRIPTION
1299 //  ===========   ========  ================================================
1300 //  "port"        integer   A string value containing the decimal port ID or
1301 //                          zero if the port should be bound and returned
1302 //
1303 //  "host"        integer   The host that connections should be limited to
1304 //                          when the GDB server is connected to.
1305 //
1306 // The response consists of key/value pairs where the key is separated from the
1307 // values with colons and each pair is terminated with a semi colon.
1308 //
1309 // Sample packet/response:
1310 // send packet: $qLaunchGDBServer:port:0;host:lldb.apple.com;#00
1311 // read packet: $pid:60025;port:50776;#00
1312 //
1313 // The "pid" key/value pair is only specified if the remote platform launched
1314 // a separate process for the GDB remote server and can be omitted if no
1315 // process was separately launched.
1316 //
1317 // The "port" key/value pair in the response lets clients know what port number
1318 // to attach to in case zero was specified as the "port" in the sent command.
1319 //----------------------------------------------------------------------
1320
1321
1322 //----------------------------------------------------------------------
1323 // PLATFORM EXTENSION - for use as a GDB remote platform
1324 //----------------------------------------------------------------------
1325 // "qProcessInfoPID:PID"
1326 //
1327 // BRIEF
1328 //  Have the remote platform get detailed information on a process by
1329 //  ID. PID is specified as a decimal integer.
1330 //
1331 // PRIORITY TO IMPLEMENT
1332 //  Optional.
1333 //
1334 // The response consists of key/value pairs where the key is separated from the
1335 // values with colons and each pair is terminated with a semi colon.
1336 //
1337 // The key value pairs in the response are:
1338 //
1339 //  KEY           VALUE     DESCRIPTION
1340 //  ===========   ========  ================================================
1341 //  "pid"         integer   Process ID as a decimal integer string
1342 //  "ppid"        integer   Parent process ID as a decimal integer string
1343 //  "uid"         integer   A string value containing the decimal user ID
1344 //  "gid"         integer   A string value containing the decimal group ID
1345 //  "euid"        integer   A string value containing the decimal effective user ID
1346 //  "egid"        integer   A string value containing the decimal effective group ID
1347 //  "name"        ascii-hex An ASCII hex string that contains the name of the process
1348 //  "triple"      string    A target triple ("x86_64-apple-macosx", "armv7-apple-ios")
1349 //
1350 // Sample packet/response:
1351 // send packet: $qProcessInfoPID:60050#00
1352 // read packet: $pid:60050;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:x86_64-apple-macosx;#00
1353 //----------------------------------------------------------------------
1354
1355 //----------------------------------------------------------------------
1356 // "vAttachName"
1357 //
1358 // BRIEF
1359 //  Same as vAttach, except instead of a "pid" you send a process name.
1360 //
1361 // PRIORITY TO IMPLEMENT
1362 //  Low. Only needed for "process attach -n".  If the packet isn't supported
1363 //  then "process attach -n" will fail gracefully.  So you need only to support
1364 //  it if attaching to a process by name makes sense for your environment.
1365 //----------------------------------------------------------------------
1366
1367 //----------------------------------------------------------------------
1368 // "vAttachWait"
1369 //
1370 // BRIEF
1371 //  Same as vAttachName, except that the stub should wait for the next instance
1372 //  of a process by that name to be launched and attach to that.
1373 //
1374 // PRIORITY TO IMPLEMENT
1375 //  Low. Only needed to support "process attach -w -n" which will fail
1376 //  gracefully if the packet is not supported.
1377 //----------------------------------------------------------------------
1378
1379 //----------------------------------------------------------------------
1380 // "qAttachOrWaitSupported"
1381 //
1382 // BRIEF
1383 //  This is a binary "is it supported" query.  Return OK if you support
1384 //  vAttachOrWait
1385 //
1386 // PRIORITY TO IMPLEMENT
1387 //  Low. This is required if you support vAttachOrWait, otherwise no support
1388 //  is needed since the standard "I don't recognize this packet" response
1389 //  will do the right thing.
1390 //----------------------------------------------------------------------
1391
1392 //----------------------------------------------------------------------
1393 // "vAttachOrWait"
1394 //
1395 // BRIEF
1396 //  Same as vAttachWait, except that the stub will attach to a process
1397 //  by name if it exists, and if it does not, it will wait for a process
1398 //  of that name to appear and attach to it.
1399 //
1400 // PRIORITY TO IMPLEMENT
1401 //  Low. Only needed to implement "process attach -w -i false -n".  If
1402 //  you don't implement it but do implement -n AND lldb can somehow get
1403 //  a process list from your device, it will fall back on scanning the
1404 //  process list, and sending vAttach or vAttachWait depending on
1405 //  whether the requested process exists already.  This is racy,
1406 //  however, so if you want to support this behavior it is better to
1407 //  support this packet.
1408 //----------------------------------------------------------------------
1409
1410 //----------------------------------------------------------------------
1411 // "jThreadExtendedInfo"
1412 //
1413 // BRIEF
1414 //  This packet, which takes its arguments as JSON and sends its reply as
1415 //  JSON, allows the gdb remote stub to provide additional information
1416 //  about a given thread.
1417 //
1418 // PRIORITY TO IMPLEMENT
1419 //  Low.  This packet is only needed if the gdb remote stub wants to
1420 //  provide interesting additional information about a thread for the
1421 //  user.
1422 //
1423 // This packet takes its arguments in JSON form ( http://www.json.org ).
1424 // At a minimum, a thread must be specified, for example:
1425 //
1426 //  jThreadExtendedInfo:{"thread":612910}
1427 //
1428 // Because this is a JSON string, the thread number is provided in base10.
1429 // Additional key-value pairs may be provided by lldb to the gdb remote
1430 // stub.  For instance, on some versions of Mac OS X, lldb can read offset
1431 // information out of the system libraries.  Using those offsets, debugserver
1432 // is able to find the Thread Specific Address (TSD) for a thread and include
1433 // that in the return information.  So lldb will send these additional fields
1434 // like so:
1435 //
1436 //   jThreadExtendedInfo:{"plo_pthread_tsd_base_address_offset":0,"plo_pthread_tsd_base_offset":224,"plo_pthread_tsd_entry_size":8,"thread":612910}
1437 //
1438 // There are no requirements for what is included in the response.  A simple
1439 // reply on a Mac OS X Yosemite / iOS 8 may include the pthread_t value, the
1440 // Thread Specific Data (TSD) address, the dispatch_queue_t value if the thread
1441 // is associated with a GCD queue, and the requested Quality of Service (QoS)
1442 // information about that thread.  For instance, a reply may look like:
1443 //
1444 //  {"tsd_address":4371349728,"requested_qos":{"enum_value":33,"constant_name":"QOS_CLASS_USER_INTERACTIVE","printable_name":"User Interactive"},"pthread_t":4371349504,"dispatch_queue_t":140735087127872}
1445 //
1446 // tsd_address, pthread_t, and dispatch_queue_t are all simple key-value pairs.
1447 // The JSON standard requires that numbers be expressed in base 10 - so all of
1448 // these are.  requested_qos is a dictionary with three key-value pairs in it -
1449 // so the UI layer may choose the form most appropriate for displaying to the user.
1450 //
1451 // Sending JSON over gdb-remote protocol introduces some problems.  We may be
1452 // sending strings with arbitrary contents in them, including the '#', '$', and '*'
1453 // characters that have special meaning in gdb-remote protocol and cannot occur
1454 // in the middle of the string.  The standard solution for this would be to require
1455 // ascii-hex encoding of all strings, or ascii-hex encode the entire JSON payload.
1456 //
1457 // Instead, the binary escaping convention is used for JSON data.  This convention
1458 // (e.g. used for the X packet) says that if '#', '$', '*', or '}' are to occur in
1459 // the payload, the character '}' (0x7d) is emitted, then the metacharacter is emitted
1460 // xor'ed by 0x20.  The '}' character occurs in every JSON payload at least once, and
1461 // '}' ^ 0x20 happens to be ']' so the raw packet characters for a request will look
1462 // like
1463 //
1464 //  jThreadExtendedInfo:{"thread":612910}]
1465 //
1466 // on the wire.
1467 //----------------------------------------------------------------------
1468
1469 //----------------------------------------------------------------------
1470 // "QEnableCompression"
1471 //
1472 // BRIEF
1473 //  This packet enables compression of the packets that the debug stub sends to lldb.
1474 //  If the debug stub can support compression, it indictes this in the reply of the
1475 //  "qSupported" packet.  e.g.
1476 //   LLDB SENDS:    qSupported:xmlRegisters=i386,arm,mips
1477 //   STUB REPLIES:  qXfer:features:read+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;DefaultCompressionMinSize=384
1478 //
1479 //  If lldb knows how to use any of these compression algorithms, it can ask that this
1480 //  compression mode be enabled.  It may optionally change the minimum packet size
1481 //  where compression is used.  Typically small packets do not benefit from compression,
1482 //  as well as compression headers -- compression is most beneficial with larger packets.
1483 //
1484 //  QEnableCompression:type:zlib-deflate;
1485 //  or
1486 //  QEnableCompression:type:zlib-deflate;minsize:512;
1487 //
1488 //  The debug stub should reply with an uncompressed "OK" packet to indicate that the
1489 //  request was accepted.  All further packets the stub sends will use this compression.
1490 //
1491 //  Packets are compressed as the last step before they are sent from the stub, and
1492 //  decompressed as the first step after they are received.  The packet format in compressed
1493 //  mode becomes one of two:
1494 //
1495 //   $N<uncompressed payload>#00
1496 //
1497 //   $C<size of uncompressed payload in base10>:<compressed payload>#00
1498 //
1499 //  Where "#00" is the actual checksum value if noack mode is not enabled.  The checksum
1500 //  value is for the "N<uncompressed payload>" or
1501 //  "C<size of uncompressed payload in base10>:<compressed payload>" bytes in the packet.
1502 //
1503 //  The size of the uncompressed payload in base10 is provided because it will simplify
1504 //  decompression if the final buffer size needed is known ahead of time.
1505 //
1506 //  Compression on low-latency connections is unlikely to be an improvement.  Particularly
1507 //  when the debug stub and lldb are running on the same host.  It should only be used
1508 //  for slow connections, and likely only for larger packets.
1509 //
1510 //  Example compression algorithsm that may be used include
1511 //
1512 //    zlib-deflate
1513 //       The raw DEFLATE format as described in IETF RFC 1951.  With the ZLIB library, you
1514 //       can compress to this format with an initialization like
1515 //           deflateInit2 (&stream, 5, Z_DEFLATED, -15, 8, Z_DEFAULT_STRATEGY)
1516 //       and you can decompress with an initialization like
1517 //           inflateInit2 (&stream, -15)
1518 //
1519 //    lz4
1520 //       https://en.wikipedia.org/wiki/LZ4_(compression_algorithm)
1521 //       https://github.com/Cyan4973/lz4
1522 //       The libcompression APIs on darwin systems call this COMPRESSION_LZ4_RAW.
1523 //
1524 //    lzfse
1525 //       An Apple proprietary compression algorithm implemented in libcompression.
1526 //
1527 //    lzma
1528 //       libcompression implements "LZMA level 6", the default compression for the
1529 //       open source LZMA implementation.
1530 //----------------------------------------------------------------------
1531
1532 //----------------------------------------------------------------------
1533 // "jGetLoadedDynamicLibrariesInfos"
1534 //
1535 // BRIEF
1536 //  This packet asks the remote debug stub to send the details about libraries
1537 //  being added/removed from the process as a performance optimization.
1538 //
1539 //  There are three ways this packet can be used.  All three return a dictionary of
1540 //  binary images formatted the same way.
1541 //
1542 //  On MacOS X 10.11, iOS 9, tvOS 9, watchOS 2 and earlier, the packet is used like
1543 //       jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128}
1544 //  where the image_list_address is an array of {void* load_addr, void* mod_date, void* pathname}
1545 //  in the inferior process memory (and image_count is the number of elements in this array).
1546 //  lldb is using information from the dyld_all_image_infos structure to make these requests to
1547 //  debugserver.  This use is not supported on macOS 10.12, iOS 10, tvOS 10, watchOS 3 or newer.
1548 //
1549 //  On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer, there are two calls.  One requests information
1550 //  on all shared libraries:
1551 //       jGetLoadedDynamicLibrariesInfos:{"fetch_all_solibs":true}
1552 //  And the second requests information about a list of shared libraries, given their load addresses:
1553 //       jGetLoadedDynamicLibrariesInfos:{"solib_addresses":[8382824135,3258302053,830202858503]}
1554 //
1555 //  The second call is both a performance optimization (instead of having lldb read the mach-o header/load commands
1556 //  out of memory with generic read packets) but also adds additional information in the form of the
1557 //  filename of the shared libraries (which is not available in the mach-o header/load commands.)
1558 //
1559 //  An example using the Mac OS X 10.11 style call:
1560 //
1561 //  LLDB SENDS: jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128}
1562 //  STUB REPLIES: ${"images":[{"load_address":4294967296,"mod_date":0,"pathname":"/tmp/a.out","uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF","mach_header":{"magic":4277009103,"cputype":16777223,"cpusubtype":18446744071562067971,"filetype":2},"segments":{"name":"__PAGEZERO","vmaddr":0,"vmsize":4294967296,"fileoff":0,"filesize":0,"maxprot":0},{"name":"__TEXT","vmaddr":4294967296,"vmsize":4096,"fileoff":0,"filesize":4096,"maxprot":7},{"name":"__LINKEDIT","vmaddr":4294971392,"vmsize":4096,"fileoff":4096,"filesize":152,"maxprot":7}}]}#00
1563 //
1564 //  Or pretty-printed,
1565 //
1566 //  STUB REPLIES: ${"images":
1567 //                  [
1568 //                      {"load_address":4294967296,
1569 //                       "mod_date":0,
1570 //                       "pathname":"/tmp/a.out",
1571 //                       "uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF",
1572 //                       "mach_header":
1573 //                          {"magic":4277009103,
1574 //                           "cputype":16777223,
1575 //                           "cpusubtype":18446744071562067971,
1576 //                           "filetype":2
1577 //                           },
1578 //                       "segments":
1579 //                        [
1580 //                          {"name":"__PAGEZERO",
1581 //                           "vmaddr":0,
1582 //                           "vmsize":4294967296,
1583 //                           "fileoff":0,
1584 //                           "filesize":0,
1585 //                           "maxprot":0
1586 //                          },
1587 //                          {"name":"__TEXT",
1588 //                           "vmaddr":4294967296,
1589 //                           "vmsize":4096,
1590 //                           "fileoff":0,
1591 //                           "filesize":4096,
1592 //                           "maxprot":7
1593 //                          },
1594 //                          {"name":"__LINKEDIT",
1595 //                           "vmaddr":4294971392,
1596 //                           "vmsize":4096,
1597 //                           "fileoff":4096,
1598 //                           "filesize":152,
1599 //                           "maxprot":7
1600 //                          }
1601 //                        ]
1602 //                      }
1603 //                  ]
1604 //              }
1605 //
1606 //
1607 // This is similar to the qXfer:libraries:read packet, and it could
1608 // be argued that it should be merged into that packet.  A separate
1609 // packet was created primarily because lldb needs to specify the
1610 // number of images to be read and the address from which the initial
1611 // information is read.  Also the XML DTD would need to be extended
1612 // quite a bit to provide all the information that the DynamicLoaderMacOSX
1613 // would need to work correctly on this platform.
1614 //
1615 // PRIORITY TO IMPLEMENT
1616 //  On Mac OS X 10.11, iOS 9, tvOS 9, watchOS 2 and older: Low.  If this packet is absent,
1617 //  lldb will read the Mach-O headers/load commands out of memory.
1618 //  On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer: High.  If this packet is absent,
1619 //  lldb will not know anything about shared libraries in the inferior, or where the main
1620 //  executable loaded.
1621 //----------------------------------------------------------------------
1622
1623 //----------------------------------------------------------------------
1624 // "jThreadsInfo"
1625 //
1626 // BRIEF
1627 //  Ask for the server for thread stop information of all threads.
1628 //
1629 // PRIORITY TO IMPLEMENT
1630 //  Low. This is a performance optimization, which speeds up debugging by avoiding
1631 //  multiple round-trips for retrieving thread information. The information from this
1632 //  packet can be retrieved using a combination of qThreadStopInfo and m packets.
1633 //----------------------------------------------------------------------
1634
1635 The data in this packet is very similar to the stop reply packets, but is packaged in
1636 JSON and uses JSON arrays where applicable. The JSON output looks like:
1637     [
1638       { "tid":1580681,
1639         "metype":6,
1640         "medata":[2,0],
1641         "reason":"exception",
1642         "qaddr":140735118423168,
1643         "registers": {
1644           "0":"8000000000000000",
1645           "1":"0000000000000000",
1646           "2":"20fabf5fff7f0000",
1647           "3":"e8f8bf5fff7f0000",
1648           "4":"0100000000000000",
1649           "5":"d8f8bf5fff7f0000",
1650           "6":"b0f8bf5fff7f0000",
1651           "7":"20f4bf5fff7f0000",
1652           "8":"8000000000000000",
1653           "9":"61a8db78a61500db",
1654           "10":"3200000000000000",
1655           "11":"4602000000000000",
1656           "12":"0000000000000000",
1657           "13":"0000000000000000",
1658           "14":"0000000000000000",
1659           "15":"0000000000000000",
1660           "16":"960b000001000000",
1661           "17":"0202000000000000",
1662           "18":"2b00000000000000",
1663           "19":"0000000000000000",
1664           "20":"0000000000000000"
1665         },
1666         "memory":[
1667           {"address":140734799804592,"bytes":"c8f8bf5fff7f0000c9a59e8cff7f0000"},
1668           {"address":140734799804616,"bytes":"00000000000000000100000000000000"}
1669         ]
1670       }
1671     ]
1672
1673 It contains an array of dictionaries with all of the key value pairs that are
1674 normally in the stop reply packet, including the expedited registers. The registers are
1675 passed as hex-encoded JSON string in debuggee-endian byte order. Note that the register
1676 numbers are decimal numbers, unlike the stop-reply packet, where they are written in
1677 hex. The packet also contains expedited memory in the "memory" key.  This allows the
1678 server to expedite memory that the client is likely to use (e.g., areas around the
1679 stack pointer, which are needed for computing backtraces) and it reduces the packet
1680 count.
1681
1682 On MacOSX with debugserver, we expedite the frame pointer backchain for a thread
1683 (up to 256 entries) by reading 2 pointers worth of bytes at the frame pointer (for
1684 the previous FP and PC), and follow the backchain. Most backtraces on MacOSX and
1685 iOS now don't require us to read any memory!
1686
1687 //----------------------------------------------------------------------
1688 // "jGetSharedCacheInfo"
1689 //
1690 // BRIEF
1691 //  This packet asks the remote debug stub to send the details about the inferior's
1692 //  shared cache. The shared cache is a collection of common libraries/frameworks that
1693 //  are mapped into every process at the same address on Darwin systems, and can be
1694 //  identified by a load address and UUID.
1695 //
1696 //
1697 //  LLDB SENDS: jGetSharedCacheInfo:{}
1698 //  STUB REPLIES: ${"shared_cache_base_address":140735683125248,"shared_cache_uuid":"DDB8D70C-C9A2-3561-B2C8-BE48A4F33F96","no_shared_cache":false,"shared_cache_private_cache":false]}#00
1699 //
1700 // PRIORITY TO IMPLEMENT
1701 //  Low.  When both lldb and the inferior process are running on the same computer, and lldb
1702 //  and the inferior process have the same shared cache, lldb may (as an optimization) read
1703 //  the shared cache out of its own memory instead of using gdb-remote read packets to read
1704 //  them from the inferior process.
1705 //----------------------------------------------------------------------
1706
1707 //----------------------------------------------------------------------
1708 // "qQueryGDBServer"
1709 //
1710 // BRIEF
1711 //  Ask the platform for the list of gdbservers we have to connect
1712 //
1713 // PRIORITY TO IMPLEMENT
1714 //  Low. The packet is required to support connecting to gdbserver started
1715 //  by the platform instance automatically.
1716 //----------------------------------------------------------------------
1717
1718 If the remote platform automatically started one or more gdbserver instance (without
1719 lldb asking it) then it have to return the list of port number or socket name for
1720 each of them what can be used by lldb to connect to those instances.
1721
1722 The data in this packet is a JSON array of JSON objects with the following keys:
1723 "port":        <the port number to connect>        (optional)
1724 "socket_name": <the name of the socket to connect> (optional)
1725
1726 Example packet:
1727 [
1728     { "port": 1234 },
1729     { "port": 5432 },
1730     { "socket_name": "foo" }
1731 ]