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