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.
18 //----------------------------------------------------------------------
22 // Try to enable no ACK mode to skip sending ACKs and NACKs.
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
36 send packet: $QStartNoAckMode#b0
41 //----------------------------------------------------------------------
45 // Query the GDB remote server for features it supports
47 // PRIORITY TO IMPLEMENT
49 //----------------------------------------------------------------------
51 QSupported is a standard GDB Remote Serial Protocol packet, but
52 there are several additions to the response that lldb can parse.
53 They are not all listed here.
57 send packet: qSupported:xmlRegisters=i386,arm,mips,arc;multiprocess+;fork-events+;vfork-events+
59 read packet: qXfer:features:read+;PacketSize=20000;qEcho+;native-signals+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;SupportedWatchpointTypes=aarch64-mask,aarch64-bas;
61 In the example above, three lldb extensions are shown:
64 The base 16 maximum packet size that the stub can handle.
65 SupportedCompressions=<item,item,...>
66 A list of compression types that the stub can use to compress packets
67 when the QEnableCompression packet is used to request one of them.
68 SupportedWatchpointTypes=<item,item,...>
69 A list of watchpoint types that this stub can manage.
70 Currently defined names are:
71 x86_64 64-bit x86-64 watchpoints
72 (1, 2, 4, 8 byte watchpoints aligned to those amounts)
73 aarch64-bas AArch64 Byte Address Select watchpoints
74 (any number of contiguous bytes within a doubleword)
75 aarch64-mask AArch64 MASK watchpoints
76 (any power-of-2 region of memory from 8 to 2GB, aligned)
77 If nothing is specified, lldb will default to sending power-of-2
78 watchpoints, up to a pointer size, `sizeof(void*)`, a reasonable
81 //----------------------------------------------------------------------
82 // "A" - launch args packet
85 // Launch a program using the supplied arguments
87 // PRIORITY TO IMPLEMENT
88 // Low. Only needed if the remote target wants to launch a target after
89 // making a connection to a GDB server that isn't already connected to
90 // an inferior process.
91 //----------------------------------------------------------------------
93 We have added support for the "set program arguments" packet where we can
94 start a connection to a remote server and then later supply the path to the
95 executable and the arguments to use when executing:
97 GDB remote docs for this:
99 set program arguments(reserved) Aarglen,argnum,arg,...
101 Where A is followed by the length in bytes of the hex encoded argument,
102 followed by an argument integer, and followed by the ASCII characters
103 converted into hex bytes foreach arg
105 send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00
108 The above packet helps when you have remote debugging abilities where you
109 could launch a process on a remote host, this isn't needed for bare board
112 //----------------------------------------------------------------------
113 // "QEnvironment:NAME=VALUE"
116 // Setup the environment up for a new child process that will soon be
117 // launched using the "A" packet.
119 // NB: key/value pairs are sent as-is so gdb-remote protocol meta characters
120 // (e.g. '#' or '$') are not acceptable. If any non-printable or
121 // metacharacters are present in the strings, QEnvironmentHexEncoded
122 // should be used instead if it is available. If you don't want to
123 // scan the environment strings before sending, prefer
124 // the QEnvironmentHexEncoded packet over QEnvironment, if it is
127 // PRIORITY TO IMPLEMENT
128 // Low. Only needed if the remote target wants to launch a target after
129 // making a connection to a GDB server that isn't already connected to
130 // an inferior process.
131 //----------------------------------------------------------------------
133 Both GDB and LLDB support passing down environment variables. Is it ok to
134 respond with a "$#00" (unimplemented):
136 send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00
139 This packet can be sent one or more times _prior_ to sending a "A" packet.
141 //----------------------------------------------------------------------
142 // "QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)"
145 // Setup the environment up for a new child process that will soon be
146 // launched using the "A" packet.
148 // The only difference between this packet and QEnvironment is that the
149 // environment key-value pair is ascii hex encoded for transmission.
150 // This allows values with gdb-remote metacharacters like '#' to be sent.
152 // PRIORITY TO IMPLEMENT
153 // Low. Only needed if the remote target wants to launch a target after
154 // making a connection to a GDB server that isn't already connected to
155 // an inferior process.
156 //----------------------------------------------------------------------
158 Both GDB and LLDB support passing down environment variables. Is it ok to
159 respond with a "$#00" (unimplemented):
161 send packet: $QEnvironment:41434b5f434f4c4f525f46494c454e414d453d626f6c642379656c6c6f77#00
164 This packet can be sent one or more times _prior_ to sending a "A" packet.
166 //----------------------------------------------------------------------
167 // "QEnableErrorStrings"
170 // This packet enables reporting of Error strings in remote packet
171 // replies from the server to client. If the server supports this
172 // feature, it should send an OK response. The client can expect the
173 // following error replies if this feature is enabled in the server ->
177 // where AAAAAAAAA will be a hex encoded ASCII string.
178 // XX is hex encoded byte number.
180 // It must be noted that even if the client has enabled reporting
181 // strings in error replies, it must not expect error strings to all
184 // PRIORITY TO IMPLEMENT
185 // Low. Only needed if the remote target wants to provide strings that
186 // are human readable along with an error code.
187 //----------------------------------------------------------------------
189 send packet: $QEnableErrorStrings
192 //----------------------------------------------------------------------
193 // "QSetSTDIN:<ascii-hex-path>"
194 // "QSetSTDOUT:<ascii-hex-path>"
195 // "QSetSTDERR:<ascii-hex-path>"
198 // Setup where STDIN, STDOUT, and STDERR go prior to sending an "A"
201 // PRIORITY TO IMPLEMENT
202 // Low. Only needed if the remote target wants to launch a target after
203 // making a connection to a GDB server that isn't already connected to
204 // an inferior process.
205 //----------------------------------------------------------------------
207 When launching a program through the GDB remote protocol with the "A" packet,
208 you might also want to specify where stdin/out/err go:
210 QSetSTDIN:<ascii-hex-path>
211 QSetSTDOUT:<ascii-hex-path>
212 QSetSTDERR:<ascii-hex-path>
214 These packets must be sent _prior_ to sending a "A" packet.
216 //----------------------------------------------------------------------
217 // "QSetWorkingDir:<ascii-hex-path>"
220 // Set the working directory prior to sending an "A" packet.
222 // PRIORITY TO IMPLEMENT
223 // Low. Only needed if the remote target wants to launch a target after
224 // making a connection to a GDB server that isn't already connected to
225 // an inferior process.
226 //----------------------------------------------------------------------
228 Or specify the working directory:
230 QSetWorkingDir:<ascii-hex-path>
232 This packet must be sent _prior_ to sending a "A" packet.
234 //----------------------------------------------------------------------
235 // "QSetDisableASLR:<bool>"
238 // Enable or disable ASLR on the next "A" packet.
240 // PRIORITY TO IMPLEMENT
241 // Low. Only needed if the remote target wants to launch a target after
242 // making a connection to a GDB server that isn't already connected to
243 // an inferior process and if the target supports disabling ASLR
244 // (Address space layout randomization).
245 //----------------------------------------------------------------------
247 Or control if ASLR is enabled/disabled:
249 send packet: QSetDisableASLR:1
252 send packet: QSetDisableASLR:0
255 This packet must be sent _prior_ to sending a "A" packet.
257 //----------------------------------------------------------------------
258 // QListThreadsInStopReply
261 // Enable the threads: and thread-pcs: data in the question-mark packet
262 // ("T packet") responses when the stub reports that a program has
263 // stopped executing.
265 // PRIORITY TO IMPLEMENT
266 // Performance. This is a performance benefit to lldb if the thread id's
267 // and thread pc values are provided to lldb in the T stop packet -- if
268 // they are not provided to lldb, lldb will likely need to send one to
269 // two packets per thread to fetch the data at every private stop.
270 //----------------------------------------------------------------------
272 send packet: QListThreadsInStopReply
275 //----------------------------------------------------------------------
276 // jLLDBTraceSupported
279 // Get the processor tracing type supported by the gdb-server for the current
280 // inferior. Responses might be different depending on the architecture and
281 // capabilities of the underlying OS.
286 // Tracing technology name, e.g. intel-pt, arm-etm.
287 // "description": <string>,
288 // Description for this technology.
291 // If no tracing technology is supported for the inferior, or no process is
292 // running, then an error message is returned.
295 // This packet is used by Trace plug-ins (see lldb_private::Trace.h) to
296 // do live tracing. Specifically, the name of the plug-in should match the name
297 // of the tracing technology returned by this packet.
298 //----------------------------------------------------------------------
300 send packet: jLLDBTraceSupported
301 read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAAA
303 //----------------------------------------------------------------------
307 // Start tracing a process or its threads using a provided tracing technology.
308 // The input and output are specified as JSON objects. In case of success, an OK
309 // response is returned, or an error otherwise.
312 // This traces existing and future threads of the current process. An error is
313 // returned if the process is already being traced.
316 // This traces specific threads.
321 // Tracing technology name, e.g. intel-pt, arm-etm.
323 // /* thread tracing only */
324 // "tids"?: [<decimal integer>],
325 // Individual threads to trace.
327 // ... other parameters specific to the provided tracing type
331 // - If "tids" is not provided, then the operation is "process tracing",
332 // otherwise it's "thread tracing".
333 // - Each tracing technology can have different levels of support for "thread
334 // tracing" and "process tracing".
337 // intel-pt supports both "thread tracing" and "process tracing".
339 // "Process tracing" is implemented in two different ways. If the
340 // "perCpuTracing" option is false, then each thread is traced individually
341 // but managed by the same "process trace" instance. This means that the
342 // amount of trace buffers used is proportional to the number of running
343 // threads. This is the recommended option unless the number of threads is
344 // huge. If "perCpuTracing" is true, then each cpu core is traced invidually
345 // instead of each thread, which uses a fixed number of trace buffers, but
346 // might result in less data available for less frequent threads. See
347 // "perCpuTracing" below for more information.
349 // Each actual intel pt trace buffer, either from "process tracing" or "thread
350 // tracing", is stored in an in-memory circular buffer, which keeps the most
353 // Additional params in the input schema:
355 // "iptTraceSize": <decimal integer>,
356 // Size in bytes used by each individual per-thread or per-cpu trace
357 // buffer. It must be a power of 2 greater than or equal to 4096 (2^12)
360 // "enableTsc": <boolean>,
361 // Whether to enable TSC timestamps or not. This is supported on
362 // all devices that support intel-pt. A TSC timestamp is generated along
363 // with PSB (synchronization) packets, whose frequency can be configured
364 // with the "psbPeriod" parameter.
366 // "psbPeriod"?: <Optional decimal integer>,
367 // This value defines the period in which PSB packets will be generated.
368 // A PSB packet is a synchronization packet that contains a TSC
369 // timestamp and the current absolute instruction pointer.
371 // This parameter can only be used if
373 // /sys/bus/event_source/devices/intel_pt/caps/psb_cyc
375 // is 1. Otherwise, the PSB period will be defined by the processor.
377 // If supported, valid values for this period can be found in
379 // /sys/bus/event_source/devices/intel_pt/caps/psb_periods
381 // which contains a hexadecimal number, whose bits represent valid
382 // values e.g. if bit 2 is set, then value 2 is valid.
384 // The psb_period value is converted to the approximate number of
385 // raw trace bytes between PSB packets as:
389 // e.g. value 3 means 16KiB between PSB packets. Defaults to
392 // /* process tracing only */
393 // "perCpuTracing": <boolean>
394 // Instead of having an individual trace buffer per thread, this option
395 // triggers the collection on a per cpu core basis. This effectively
396 // traces the entire activity on all cores. At decoding time, in order
397 // to correctly associate a decoded instruction with a thread, the
398 // context switch trace of each core is needed, as well as a record per
399 // cpu indicating which thread was running on each core when tracing
400 // started. These secondary traces are correlated with the intel-pt
401 // trace by comparing TSC timestamps.
403 // This option forces the capture of TSC timestamps (see "enableTsc").
405 // Note: This option can't be used simulatenously with any other trace
406 // sessions because of its system-wide nature.
408 // /* process tracing only */
409 // "processBufferSizeLimit": <decimal integer>,
410 // Maximum total buffer size per process in bytes.
411 // This limit applies to the sum of the sizes of all thread or cpu core
412 // buffers for the current process, excluding the ones started with
415 // If "perCpuTracing" is false, whenever a thread is attempted to be
416 // traced due to "process tracing" and the limit would be reached, the
417 // process is stopped with a "tracing" reason along with a meaningful
418 // description, so that the user can retrace the process if needed.
420 // If "perCpuTracing" is true, then starting the system-wide trace
421 // session fails if all the individual per-cpu trace buffers require
422 // in total more memory that the limit impossed by this parameter.
426 // - Modifying the parameters of an existing trace is not supported. The user
427 // needs to stop the trace and start a new one.
428 // - If "process tracing" is attempted and there are individual threads
429 // already being traced with "thread tracing", these traces are left
430 // unaffected and the threads not traced twice.
431 // - If "thread tracing" is attempted on a thread already being traced with
432 // either "thread tracing" or "process tracing", it fails.
433 //----------------------------------------------------------------------
436 send packet: jLLDBTraceStart:{"type":<type>,...other params}]
437 read packet: OK/E<error code>;AAAAAAAAA
440 send packet: jLLDBTraceStart:{"type":<type>,"tids":<tids>,...other params}]
441 read packet: OK/E<error code>;AAAAAAAAA
443 //----------------------------------------------------------------------
447 // Stop tracing a process or its threads using a provided tracing technology.
448 // The input and output are specified as JSON objects. In case of success, an OK
449 // response is returned, or an error otherwise.
451 // PROCESS TRACE STOPPING
452 // Stopping a process trace stops the active traces initiated with
455 // THREAD TRACE STOPPING
456 // This is a best effort request, which tries to stop as many traces as
460 // The schema for the input is
464 // Tracing technology name, e.g. intel-pt, arm-etm.
466 // /* thread trace stopping only */
467 // "tids": [<decimal integer>]
468 // Individual thread traces to stop.
472 // - If "tids" is not provided, then the operation is "process trace stopping".
475 // Stopping a specific thread trace started with "process tracing" is allowed.
476 //----------------------------------------------------------------------
478 Process trace stopping:
479 send packet: jLLDBTraceStop:{"type":<type>}]
480 read packet: OK/E<error code>;AAAAAAAAA
482 Thread trace stopping:
483 send packet: jLLDBTraceStop:{"type":<type>,"tids":<tids>}]
484 read packet: OK/E<error code>;AAAAAAAAA
486 //----------------------------------------------------------------------
487 // jLLDBTraceGetState
490 // Get the current state of the process and its threads being traced by
491 // a given trace technology. The response is a JSON object with custom
492 // information depending on the trace technology. In case of errors, an
493 // error message is returned.
498 // Tracing technology name, e.g. intel-pt, arm-etm.
503 // "tracedThreads": [{
504 // "tid": <decimal integer>,
508 // Identifier for some binary data related to this thread to
509 // fetch with the jLLDBTraceGetBinaryData packet.
510 // "size": <decimal integer>,
511 // Size in bytes of this thread data.
515 // "processBinaryData": [
518 // Identifier for some binary data related to this process to
519 // fetch with the jLLDBTraceGetBinaryData packet.
520 // "size": <decimal integer>,
521 // Size in bytes of this thread data.
525 // "id": <decimal integer>,
526 // Identifier for this CPU logical core.
530 // Identifier for some binary data related to this thread to
531 // fetch with the jLLDBTraceGetBinaryData packet.
532 // "size": <decimal integer>,
533 // Size in bytes of this cpu core data.
537 // "warnings"?: [<string>],
538 // Non-fatal messages useful for troubleshooting.
540 // ... other attributes specific to the given tracing technology
544 // - "traceThreads" includes all thread traced by both "process tracing" and
549 // If per-cpu process tracing is enabled, "tracedThreads" will contain all
550 // the threads of the process without any trace buffers. Besides that, the
551 // "cpus" field will also be returned with per cpu core trace buffers.
552 // A side effect of per-cpu tracing is that all the threads of unrelated
553 // processes will also be traced, thus polluting the tracing data.
555 // Binary data kinds:
556 // - iptTrace: trace buffer for a thread or a cpu.
557 // - perfContextSwitchTrace: context switch trace for a cpu generated by
559 // - procfsCpuInfo: contents of the /proc/cpuinfo file.
561 // Additional attributes:
562 // tscPerfZeroConversion:
564 // This field allows converting Intel processor's TSC values to nanoseconds.
565 // It is available through the Linux perf_event API when cap_user_time and cap_user_time_zero
567 // See the documentation of time_zero in
568 // https://man7.org/linux/man-pages/man2/perf_event_open.2.html for more information about
569 // the calculation and the meaning of the values in the schema below.
571 // Schema for this field:
573 // "tscPerfZeroConversion": {
574 // "timeMult": <decimal integer>,
575 // "timeShift": <decimal integer>,
576 // "timeZero": <decimal integer>,
578 //----------------------------------------------------------------------
580 send packet: jLLDBTraceGetState:{"type":<type>}]
581 read packet: {...object}/E<error code>;AAAAAAAAA
583 //----------------------------------------------------------------------
584 // jLLDBTraceGetBinaryData
587 // Get binary data given a trace technology and a data identifier.
588 // The input is specified as a JSON object and the response has the same format
589 // as the "binary memory read" (aka "x") packet. In case of failures, an error
590 // message is returned.
593 // The schema for the input is
597 // Tracing technology name, e.g. intel-pt, arm-etm.
599 // Identifier for the data.
600 // "cpuId": <Optional decimal>,
601 // Core id in decimal if the data belongs to a CPU core.
602 // "tid"?: <Optional decimal>,
603 // Tid in decimal if the data belongs to a thread.
605 //----------------------------------------------------------------------
607 send packet: jLLDBTraceGetBinaryData:{"type":<type>,"kind":<query>,"tid":<tid>,"offset":<offset>,"size":<size>}]
608 read packet: <binary data>/E<error code>;AAAAAAAAA
610 //----------------------------------------------------------------------
611 // "qRegisterInfo<hex-reg-id>"
614 // Discover register information from the remote GDB server.
616 // PRIORITY TO IMPLEMENT
617 // High. Any target that can self describe its registers, should do so.
618 // This means if new registers are ever added to a remote target, they
619 // will get picked up automatically, and allows registers to change
620 // depending on the actual CPU type that is used.
622 // NB: qRegisterInfo is deprecated in favor of the standard gdb remote
623 // serial protocol register description method,
624 // "qXfer:features:read:target.xml".
625 // If qXfer:features:read:target.xml is supported, qRegisterInfo does
626 // not need to be implemented. The target.xml format is used by most
627 // gdb RSP stubs whereas qRegisterInfo was an lldb-only design.
628 // qRegisterInfo requires one packet per register and can have undesirable
629 // performance costs at the start of a debug session, whereas target.xml
630 // may be able to describe all registers in a single packet.
631 //----------------------------------------------------------------------
633 With LLDB, for register information, remote GDB servers can add
634 support for the "qRegisterInfoN" packet where "N" is a zero based
635 base 16 register number that must start at zero and increase by one
636 for each register that is supported. The response is done in typical
637 GDB remote fashion where a series of "KEY:VALUE;" pairs are returned.
638 An example for the x86_64 registers is included below:
640 send packet: $qRegisterInfo0#00
641 read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00
642 send packet: $qRegisterInfo1#00
643 read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00
644 send packet: $qRegisterInfo2#00
645 read packet: $name:rcx;bitsize:64;offset:16;encoding:uint;format:hex;set:General Purpose Registers;gcc:2;dwarf:2;#00
646 send packet: $qRegisterInfo3#00
647 read packet: $name:rdx;bitsize:64;offset:24;encoding:uint;format:hex;set:General Purpose Registers;gcc:1;dwarf:1;#00
648 send packet: $qRegisterInfo4#00
649 read packet: $name:rdi;bitsize:64;offset:32;encoding:uint;format:hex;set:General Purpose Registers;gcc:5;dwarf:5;#00
650 send packet: $qRegisterInfo5#00
651 read packet: $name:rsi;bitsize:64;offset:40;encoding:uint;format:hex;set:General Purpose Registers;gcc:4;dwarf:4;#00
652 send packet: $qRegisterInfo6#00
653 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
654 send packet: $qRegisterInfo7#00
655 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
656 send packet: $qRegisterInfo8#00
657 read packet: $name:r8;bitsize:64;offset:64;encoding:uint;format:hex;set:General Purpose Registers;gcc:8;dwarf:8;#00
658 send packet: $qRegisterInfo9#00
659 read packet: $name:r9;bitsize:64;offset:72;encoding:uint;format:hex;set:General Purpose Registers;gcc:9;dwarf:9;#00
660 send packet: $qRegisterInfoa#00
661 read packet: $name:r10;bitsize:64;offset:80;encoding:uint;format:hex;set:General Purpose Registers;gcc:10;dwarf:10;#00
662 send packet: $qRegisterInfob#00
663 read packet: $name:r11;bitsize:64;offset:88;encoding:uint;format:hex;set:General Purpose Registers;gcc:11;dwarf:11;#00
664 send packet: $qRegisterInfoc#00
665 read packet: $name:r12;bitsize:64;offset:96;encoding:uint;format:hex;set:General Purpose Registers;gcc:12;dwarf:12;#00
666 send packet: $qRegisterInfod#00
667 read packet: $name:r13;bitsize:64;offset:104;encoding:uint;format:hex;set:General Purpose Registers;gcc:13;dwarf:13;#00
668 send packet: $qRegisterInfoe#00
669 read packet: $name:r14;bitsize:64;offset:112;encoding:uint;format:hex;set:General Purpose Registers;gcc:14;dwarf:14;#00
670 send packet: $qRegisterInfof#00
671 read packet: $name:r15;bitsize:64;offset:120;encoding:uint;format:hex;set:General Purpose Registers;gcc:15;dwarf:15;#00
672 send packet: $qRegisterInfo10#00
673 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
674 send packet: $qRegisterInfo11#00
675 read packet: $name:rflags;alt-name:flags;bitsize:64;offset:136;encoding:uint;format:hex;set:General Purpose Registers;#00
676 send packet: $qRegisterInfo12#00
677 read packet: $name:cs;bitsize:64;offset:144;encoding:uint;format:hex;set:General Purpose Registers;#00
678 send packet: $qRegisterInfo13#00
679 read packet: $name:fs;bitsize:64;offset:152;encoding:uint;format:hex;set:General Purpose Registers;#00
680 send packet: $qRegisterInfo14#00
681 read packet: $name:gs;bitsize:64;offset:160;encoding:uint;format:hex;set:General Purpose Registers;#00
682 send packet: $qRegisterInfo15#00
683 read packet: $name:fctrl;bitsize:16;offset:176;encoding:uint;format:hex;set:Floating Point Registers;#00
684 send packet: $qRegisterInfo16#00
685 read packet: $name:fstat;bitsize:16;offset:178;encoding:uint;format:hex;set:Floating Point Registers;#00
686 send packet: $qRegisterInfo17#00
687 read packet: $name:ftag;bitsize:8;offset:180;encoding:uint;format:hex;set:Floating Point Registers;#00
688 send packet: $qRegisterInfo18#00
689 read packet: $name:fop;bitsize:16;offset:182;encoding:uint;format:hex;set:Floating Point Registers;#00
690 send packet: $qRegisterInfo19#00
691 read packet: $name:fioff;bitsize:32;offset:184;encoding:uint;format:hex;set:Floating Point Registers;#00
692 send packet: $qRegisterInfo1a#00
693 read packet: $name:fiseg;bitsize:16;offset:188;encoding:uint;format:hex;set:Floating Point Registers;#00
694 send packet: $qRegisterInfo1b#00
695 read packet: $name:fooff;bitsize:32;offset:192;encoding:uint;format:hex;set:Floating Point Registers;#00
696 send packet: $qRegisterInfo1c#00
697 read packet: $name:foseg;bitsize:16;offset:196;encoding:uint;format:hex;set:Floating Point Registers;#00
698 send packet: $qRegisterInfo1d#00
699 read packet: $name:mxcsr;bitsize:32;offset:200;encoding:uint;format:hex;set:Floating Point Registers;#00
700 send packet: $qRegisterInfo1e#00
701 read packet: $name:mxcsrmask;bitsize:32;offset:204;encoding:uint;format:hex;set:Floating Point Registers;#00
702 send packet: $qRegisterInfo1f#00
703 read packet: $name:stmm0;bitsize:80;offset:208;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:33;dwarf:33;#00
704 send packet: $qRegisterInfo20#00
705 read packet: $name:stmm1;bitsize:80;offset:224;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:34;dwarf:34;#00
706 send packet: $qRegisterInfo21#00
707 read packet: $name:stmm2;bitsize:80;offset:240;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:35;dwarf:35;#00
708 send packet: $qRegisterInfo22#00
709 read packet: $name:stmm3;bitsize:80;offset:256;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:36;dwarf:36;#00
710 send packet: $qRegisterInfo23#00
711 read packet: $name:stmm4;bitsize:80;offset:272;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:37;dwarf:37;#00
712 send packet: $qRegisterInfo24#00
713 read packet: $name:stmm5;bitsize:80;offset:288;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:38;dwarf:38;#00
714 send packet: $qRegisterInfo25#00
715 read packet: $name:stmm6;bitsize:80;offset:304;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:39;dwarf:39;#00
716 send packet: $qRegisterInfo26#00
717 read packet: $name:stmm7;bitsize:80;offset:320;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:40;dwarf:40;#00
718 send packet: $qRegisterInfo27#00
719 read packet: $name:xmm0;bitsize:128;offset:336;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:17;dwarf:17;#00
720 send packet: $qRegisterInfo28#00
721 read packet: $name:xmm1;bitsize:128;offset:352;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:18;dwarf:18;#00
722 send packet: $qRegisterInfo29#00
723 read packet: $name:xmm2;bitsize:128;offset:368;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:19;dwarf:19;#00
724 send packet: $qRegisterInfo2a#00
725 read packet: $name:xmm3;bitsize:128;offset:384;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:20;dwarf:20;#00
726 send packet: $qRegisterInfo2b#00
727 read packet: $name:xmm4;bitsize:128;offset:400;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:21;dwarf:21;#00
728 send packet: $qRegisterInfo2c#00
729 read packet: $name:xmm5;bitsize:128;offset:416;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:22;dwarf:22;#00
730 send packet: $qRegisterInfo2d#00
731 read packet: $name:xmm6;bitsize:128;offset:432;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:23;dwarf:23;#00
732 send packet: $qRegisterInfo2e#00
733 read packet: $name:xmm7;bitsize:128;offset:448;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:24;dwarf:24;#00
734 send packet: $qRegisterInfo2f#00
735 read packet: $name:xmm8;bitsize:128;offset:464;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:25;dwarf:25;#00
736 send packet: $qRegisterInfo30#00
737 read packet: $name:xmm9;bitsize:128;offset:480;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:26;dwarf:26;#00
738 send packet: $qRegisterInfo31#00
739 read packet: $name:xmm10;bitsize:128;offset:496;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:27;dwarf:27;#00
740 send packet: $qRegisterInfo32#00
741 read packet: $name:xmm11;bitsize:128;offset:512;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:28;dwarf:28;#00
742 send packet: $qRegisterInfo33#00
743 read packet: $name:xmm12;bitsize:128;offset:528;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:29;dwarf:29;#00
744 send packet: $qRegisterInfo34#00
745 read packet: $name:xmm13;bitsize:128;offset:544;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:30;dwarf:30;#00
746 send packet: $qRegisterInfo35#00
747 read packet: $name:xmm14;bitsize:128;offset:560;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:31;dwarf:31;#00
748 send packet: $qRegisterInfo36#00
749 read packet: $name:xmm15;bitsize:128;offset:576;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:32;dwarf:32;#00
750 send packet: $qRegisterInfo37#00
751 read packet: $name:trapno;bitsize:32;offset:696;encoding:uint;format:hex;set:Exception State Registers;#00
752 send packet: $qRegisterInfo38#00
753 read packet: $name:err;bitsize:32;offset:700;encoding:uint;format:hex;set:Exception State Registers;#00
754 send packet: $qRegisterInfo39#00
755 read packet: $name:faultvaddr;bitsize:64;offset:704;encoding:uint;format:hex;set:Exception State Registers;#00
756 send packet: $qRegisterInfo3a#00
759 As we see above we keep making subsequent calls to the remote server to
760 discover all registers by increasing the number appended to qRegisterInfo and
761 we get a response back that is a series of "key=value;" strings.
763 The offset: fields should not leave a gap anywhere in the g/G packet -- the
764 register values should be appended one after another. For instance, if the
765 register context for a thread looks like
768 uint32_t gpr1; // offset 0
769 uint32_t gpr2; // offset 4
770 uint32_t gpr3; // offset 8
771 uint64_t fp1; // offset 16
774 You may end up with a 4-byte gap between gpr3 and fp1 on architectures
775 that align values like this. The correct offset: value for fp1 is 12 -
776 in the g/G packet fp1 will immediately follow gpr3, even though the
777 in-memory thread structure has an empty 4 bytes for alignment between
780 The keys and values are detailed below:
783 ========== ================================================================
784 name The primary register name as a string ("rbp" for example)
786 alt-name An alternate name for a register as a string ("fp" for example for
789 bitsize Size in bits of a register (32, 64, etc). Base 10.
791 offset The offset within the "g" and "G" packet of the register data for
792 this register. This is the byte offset once the data has been
793 transformed into binary, not the character offset into the g/G
796 encoding The encoding type of the register which must be one of:
798 uint (unsigned integer)
799 sint (signed integer)
800 ieee754 (IEEE 754 float)
801 vector (vector register)
803 format The preferred format for display of this register. The value must
819 set The register set name as a string that this register belongs to.
821 gcc The GCC compiler registers number for this register (used for
822 EH frame and other compiler information that is encoded in the
823 executable files). The supplied number will be decoded like a
824 string passed to strtoul() with a base of zero, so the number
825 can be decimal, or hex if it is prefixed with "0x".
827 NOTE: If the compiler doesn't have a register number for this
828 register, this key/value pair should be omitted.
830 dwarf The DWARF register number for this register that is used for this
831 register in the debug information. The supplied number will be decoded
832 like a string passed to strtoul() with a base of zero, so the number
833 can be decimal, or hex if it is prefixed with "0x".
835 NOTE: If the compiler doesn't have a register number for this
836 register, this key/value pair should be omitted.
838 generic If the register is a generic register that most CPUs have, classify
839 it correctly so the debugger knows. Valid values are one of:
840 pc (a program counter register. for example "name=eip;" (i386),
841 "name=rip;" (x86_64), "name=r15;" (32 bit arm) would
842 include a "generic=pc;" key value pair)
843 sp (a stack pointer register. for example "name=esp;" (i386),
844 "name=rsp;" (x86_64), "name=r13;" (32 bit arm) would
845 include a "generic=sp;" key value pair)
846 fp (a frame pointer register. for example "name=ebp;" (i386),
847 "name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx
848 ABI) would include a "generic=fp;" key value pair)
849 ra (a return address register. for example "name=lr;" (32 bit ARM)
850 would include a "generic=ra;" key value pair)
851 flags (a CPU flags register. for example "name=eflags;" (i386),
852 "name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM)
853 would include a "generic=flags;" key value pair)
854 arg1 - arg8 (specified for registers that contain function
855 arguments when the argument fits into a register)
858 The value for this key is a comma separated list of raw hex (optional
859 leading "0x") register numbers.
861 This specifies that this register is contained in other concrete
862 register values. For example "eax" is in the lower 32 bits of the
863 "rax" register value for x86_64, so "eax" could specify that it is
864 contained in "rax" by specifying the register number for "rax" (whose
865 register number is 0x00)
869 If a register is comprised of one or more registers, like "d0" is ARM
870 which is a 64 bit register, it might be made up of "s0" and "s1". If
871 the register number for "s0" is 0x20, and the register number of "s1"
872 is "0x21", the "container-regs" key/value pair would be:
874 "container-regs:20,21;"
876 This is handy for defining what GDB used to call "pseudo" registers.
877 These registers are never requested by LLDB via the register read
878 or write packets, the container registers will be requested on behalf
882 The value for this key is a comma separated list of raw hex (optional
883 leading "0x") register numbers.
885 This specifies which register values should be invalidated when this
886 register is modified. For example if modifying "eax" would cause "rax",
887 "eax", "ax", "ah", and "al" to be modified where rax is 0x0, eax is 0x15,
888 ax is 0x25, ah is 0x35, and al is 0x39, the "invalidate-regs" key/value
891 "invalidate-regs:0,15,25,35,39;"
893 If there is a single register that gets invalidated, then omit the comma
894 and just list a single register:
898 This is handy when modifying a specific register can cause other
899 register values to change. For example, when debugging an ARM target,
900 modifying the CPSR register can cause the r8 - r14 and cpsr value to
901 change depending on if the mode has changed.
903 //----------------------------------------------------------------------
907 // Run a command in a shell on the connected remote machine.
909 // PRIORITY TO IMPLEMENT
910 // High. This command allows LLDB clients to run arbitrary shell
911 // commands on a remote host.
913 /----------------------------------------------------------------------
915 The request consists of the command to be executed encoded in ASCII characters
916 converted into hex bytes.
918 The response to this packet consists of the letter F followed by the return code,
919 followed by the signal number (or 0 if no signal was delivered), and escaped bytes
920 of captured program output.
922 Below is an example communication from a client sending an "ls -la" command:
924 send packet: $qPlatform_shell:6c73202d6c61,00000002#ec
925 read packet: $F,00000000,00000000,total 4736
926 drwxrwxr-x 16 username groupname 4096 Aug 15 21:36 .
927 drwxr-xr-x 17 username groupname 4096 Aug 10 16:39 ..
928 -rw-rw-r-- 1 username groupname 73875 Aug 12 16:46 notes.txt
929 drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp
930 -rw-r--r-- 1 username groupname 2792 Aug 12 16:46 a.out
931 -rw-r--r-- 1 username groupname 3190 Aug 12 16:46 Makefile
933 //----------------------------------------------------------------------
937 // Creates a new directory on the connected remote machine.
939 // PRIORITY TO IMPLEMENT
940 // Low. This command allows LLDB clients to create new directories on
943 /----------------------------------------------------------------------
946 qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path>
950 mkdir called successfully and returned with the given return code
954 //----------------------------------------------------------------------
958 // Change the permissions of a file on the connected remote machine.
960 // PRIORITY TO IMPLEMENT
961 // Low. This command allows LLDB clients to change the permissions of
962 // a file on the remote host.
964 /----------------------------------------------------------------------
967 qPlatform_chmod:<hex-file-mode>,<ascii-hex-path>
971 chmod called successfully and returned with the given return code
975 //----------------------------------------------------------------------
979 // Get information about the host we are remotely connected to.
981 // PRIORITY TO IMPLEMENT
982 // High. This packet is usually very easy to implement and can help
983 // LLDB select the correct plug-ins for the job based on the target
984 // triple information that is supplied.
985 //----------------------------------------------------------------------
987 LLDB supports a host info call that gets all sorts of details of the system
988 that is being debugged:
990 send packet: $qHostInfo#00
991 read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00
993 Key value pairs are one of:
995 cputype: is a number that is the mach-o CPU type that is being debugged (base 10)
996 cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged (base 10)
997 triple: a string for the target triple (x86_64-apple-macosx) that can be used to specify arch + vendor + os in one entry
998 vendor: a string for the vendor (apple), not needed if "triple" is specified
999 ostype: a string for the OS being debugged (macosx, linux, freebsd, ios, watchos), not needed if "triple" is specified
1000 endian: is one of "little", "big", or "pdp"
1001 ptrsize: an unsigned number that represents how big pointers are in bytes on the debug target
1002 hostname: the hostname of the host that is running the GDB server if available
1003 os_build: a string for the OS build for the remote host as a string value
1004 os_kernel: a string describing the kernel version
1005 os_version: a version string that represents the current OS version (10.8.2)
1006 watchpoint_exceptions_received: one of "before" or "after" to specify if a watchpoint is triggered before or after the pc when it stops
1007 default_packet_timeout: an unsigned number that specifies the default timeout in seconds
1008 distribution_id: optional. For linux, specifies distribution id (e.g. ubuntu, fedora, etc.)
1009 osmajor: optional, specifies the major version number of the OS (e.g. for macOS 10.12.2, it would be 10)
1010 osminor: optional, specifies the minor version number of the OS (e.g. for macOS 10.12.2, it would be 12)
1011 ospatch: optional, specifies the patch level number of the OS (e.g. for macOS 10.12.2, it would be 2)
1012 vm-page-size: optional, specifies the target system VM page size, base 10.
1013 Needed for the "dirty-pages:" list in the qMemoryRegionInfo
1014 packet, where a list of dirty pages is sent from the remote
1015 stub. This page size tells lldb how large each dirty page is.
1016 addressing_bits: optional, specifies how many bits in addresses are
1017 significant for addressing, base 10. If bits 38..0
1018 in a 64-bit pointer are significant for addressing,
1019 then the value is 39. This is needed on e.g. AArch64
1020 v8.3 ABIs that use pointer authentication, so lldb
1021 knows which bits to clear/set to get the actual
1023 low_mem_addressing_bits: optional, specifies how many bits in
1024 addresses in low memory are significant for addressing, base 10.
1025 AArch64 can have different page table setups for low and high
1026 memory, and therefore a different number of bits used for addressing.
1027 high_mem_addressing_bits: optional, specifies how many bits in
1028 addresses in high memory are significant for addressing, base 10.
1029 AArch64 can have different page table setups for low and high
1030 memory, and therefore a different number of bits used for addressing.
1032 //----------------------------------------------------------------------
1033 // "qGDBServerVersion"
1036 // Get version information about this implementation of the gdb-remote
1039 // PRIORITY TO IMPLEMENT
1040 // High. This packet is usually very easy to implement and can help
1041 // LLDB to work around bugs in a server's implementation when they
1043 //----------------------------------------------------------------------
1045 The goal of this packet is to provide enough information about an
1046 implementation of the gdb-remote-protocol server that lldb can
1047 work around implementation problems that are discovered after the
1048 version has been released/deployed. The name and version number
1049 should be sufficiently unique that lldb can unambiguously identify
1050 the origin of the program (for instance, debugserver from lldb) and
1051 the version/submission number/patch level of the program - whatever
1052 is appropriate for your server implementation.
1054 The packet follows the key-value pair model, semicolon separated.
1056 send packet: $qGDBServerVersion#00
1057 read packet: $name:debugserver;version:310.2;#00
1059 Other clients may find other key-value pairs to be useful for identifying
1060 a gdb stub. Patch level, release name, build number may all be keys that
1061 better describe your implementation's version.
1062 Suggested key names:
1064 name : the name of your remote server - "debugserver" is the lldb standard
1067 version : identifies the version number of this server
1069 patch_level : the patch level of this server
1071 release_name : the name of this release, if your project uses names
1073 build_number : if you use a build system with increasing build numbers,
1074 this may be the right key name for your server
1076 major_version : major version number
1077 minor_version : minor version number
1079 //----------------------------------------------------------------------
1083 // Get information about the process we are currently debugging.
1085 // PRIORITY TO IMPLEMENT
1086 // Medium. On systems which can launch multiple different architecture processes,
1087 // the qHostInfo may not disambiguate sufficiently to know what kind of
1088 // process is being debugged.
1089 // e.g. on a 64-bit x86 Mac system both 32-bit and 64-bit user processes are possible,
1090 // and with Mach-O universal files, the executable file may contain both 32- and
1091 // 64-bit slices so it may be impossible to know until you're attached to a real
1092 // process to know what you're working with.
1094 // All numeric fields return base 16 numbers without any "0x" prefix.
1095 //----------------------------------------------------------------------
1099 send packet: $qProcessInfo#00
1100 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
1104 send packet: $qProcessInfo#00
1105 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
1107 Key value pairs include:
1110 parent-pid: the process of the parent process (often debugserver will become the parent when attaching)
1111 real-uid: the real user id of the process
1112 real-gid: the real group id of the process
1113 effective-uid: the effective user id of the process
1114 effective-gid: the effective group id of the process
1115 cputype: the Mach-O CPU type of the process (base 16)
1116 cpusubtype: the Mach-O CPU subtype of the process (base 16)
1117 ostype: is a string the represents the OS being debugged (darwin, linux, freebsd)
1118 vendor: is a string that represents the vendor (apple)
1119 endian: is one of "little", "big", or "pdp"
1120 ptrsize: is a number that represents how big pointers are in bytes
1122 main-binary-uuid: is the UUID of a firmware type binary that the gdb stub knows about
1123 main-binary-address: is the load address of the firmware type binary
1124 main-binary-slide: is the slide of the firmware type binary, if address isn't known
1126 binary-addresses: A comma-separated list of binary load addresses base 16.
1127 lldb will parse the binaries in memory to get UUIDs, then
1128 try to find the binaries & debug info by UUID. Intended for
1129 use with a small number of firmware type binaries where the
1130 search for binary/debug info may be expensive.
1132 //----------------------------------------------------------------------
1136 // Get an address where the dynamic linker stores information about
1137 // where shared libraries are loaded.
1139 // PRIORITY TO IMPLEMENT
1140 // High if you have a dynamic loader plug-in in LLDB for your target
1141 // triple (see the "qHostInfo" packet) that can use this information.
1142 // Many times address load randomization can make it hard to detect
1143 // where the dynamic loader binary and data structures are located and
1144 // some platforms know, or can find out where this information is.
1146 // Low if you have a debug target where all object and symbol files
1147 // contain static load addresses.
1148 //----------------------------------------------------------------------
1150 LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each
1151 debugger as to where to find the dynamic loader information. For darwin
1152 binaries that run in user land this is the address of the "all_image_infos"
1153 structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO
1154 call. The result is returned as big endian hex bytes that are the address
1157 send packet: $qShlibInfoAddr#00
1158 read packet: $7fff5fc40040#00
1162 //----------------------------------------------------------------------
1163 // "qThreadStopInfo<tid>"
1166 // Get information about why a thread, whose ID is "<tid>", is stopped.
1168 // PRIORITY TO IMPLEMENT
1169 // High if you need to support multi-threaded or multi-core debugging.
1170 // Many times one thread will hit a breakpoint and while the debugger
1171 // is in the process of suspending the other threads, other threads
1172 // will also hit a breakpoint. This packet allows LLDB to know why all
1173 // threads (live system debug) / cores (JTAG) in your program have
1174 // stopped and allows LLDB to display and control your program
1176 //----------------------------------------------------------------------
1178 LLDB tries to use the "qThreadStopInfo" packet which is formatted as
1179 "qThreadStopInfo%x" where %x is the hex thread ID. This requests information
1180 about why a thread is stopped. The response is the same as the stop reply
1181 packets and tells us what happened to the other threads. The standard GDB
1182 remote packets love to think that there is only _one_ reason that _one_ thread
1183 stops at a time. This allows us to see why all threads stopped and allows us
1184 to implement better multi-threaded debugging support.
1186 //----------------------------------------------------------------------
1187 // "QThreadSuffixSupported"
1190 // Try to enable thread suffix support for the 'g', 'G', 'p', and 'P'
1193 // PRIORITY TO IMPLEMENT
1194 // High. Adding a thread suffix allows us to read and write registers
1195 // more efficiently and stops us from having to select a thread with
1196 // one packet and then read registers with a second packet. It also
1197 // makes sure that no errors can occur where the debugger thinks it
1198 // already has a thread selected (see the "Hg" packet from the standard
1199 // GDB remote protocol documentation) yet the remote GDB server actually
1200 // has another thread selected.
1201 //----------------------------------------------------------------------
1203 When reading thread registers, you currently need to set the current
1204 thread, then read the registers. This is kind of cumbersome, so we added the
1205 ability to query if the remote GDB server supports adding a "thread:<tid>;"
1206 suffix to all packets that request information for a thread. To test if the
1207 remote GDB server supports this feature:
1209 send packet: $QThreadSuffixSupported#00
1212 If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a
1213 thread suffix. So to send a 'g' packet (read all register values):
1215 send packet: $g;thread:<tid>;#00
1218 send packet: $G;thread:<tid>;#00
1221 send packet: $p1a;thread:<tid>;#00
1224 send packet: $P1a=1234abcd;thread:<tid>;#00
1228 otherwise, without this you would need to always send two packets:
1230 send packet: $Hg<tid>#00
1235 We also added support for allocating and deallocating memory. We use this to
1236 allocate memory so we can run JITed code.
1238 //----------------------------------------------------------------------
1239 // "_M<size>,<permissions>"
1242 // Allocate memory on the remote target with the specified size and
1245 // PRIORITY TO IMPLEMENT
1246 // High if you want LLDB to be able to JIT code and run that code. JIT
1247 // code also needs data which is also allocated and tracked.
1249 // Low if you don't support running JIT'ed code.
1250 //----------------------------------------------------------------------
1252 The allocate memory packet starts with "_M<size>,<permissions>". It returns a
1253 raw big endian address value, or "" for unimplemented, or "EXX" for an error
1254 code. The packet is formatted as:
1258 packet_len = ::snprintf (
1263 permissions & lldb::ePermissionsReadable ? "r" : "",
1264 permissions & lldb::ePermissionsWritable ? "w" : "",
1265 permissions & lldb::ePermissionsExecutable ? "x" : "");
1267 You request a size and give the permissions. This packet does NOT need to be
1268 implemented if you don't want to support running JITed code. The return value
1269 is just the address of the newly allocated memory as raw big endian hex bytes.
1271 //----------------------------------------------------------------------
1275 // Deallocate memory that was previously allocated using an allocate
1278 // PRIORITY TO IMPLEMENT
1279 // High if you want LLDB to be able to JIT code and run that code. JIT
1280 // code also needs data which is also allocated and tracked.
1282 // Low if you don't support running JIT'ed code.
1283 //----------------------------------------------------------------------
1285 The deallocate memory packet is "_m<addr>" where you pass in the address you
1286 got back from a previous call to the allocate memory packet. It returns "OK"
1287 if the memory was successfully deallocated, or "EXX" for an error, or "" if
1290 //----------------------------------------------------------------------
1291 // "qMemoryRegionInfo:<addr>"
1294 // Get information about the address range that contains "<addr>"
1296 // PRIORITY TO IMPLEMENT
1297 // Medium. This is nice to have, but it isn't necessary. It helps LLDB
1298 // do stack unwinding when we branch into memory that isn't executable.
1299 // If we can detect that the code we are stopped in isn't executable,
1300 // then we can recover registers for stack frames above the current
1301 // frame. Otherwise we must assume we are in some JIT'ed code (not JIT
1302 // code that LLDB has made) and assume that no registers are available
1303 // in higher stack frames.
1304 //----------------------------------------------------------------------
1306 We added a way to get information for a memory region. The packet is:
1308 qMemoryRegionInfo:<addr>
1310 Where <addr> is a big endian hex address. The response is returned in a series
1311 of tuples like the data returned in a stop reply packet. The currently valid
1312 tuples to return are:
1314 start:<start-addr>; // <start-addr> is a big endian hex address that is
1315 // the start address of the range that contains <addr>
1317 size:<size>; // <size> is a big endian hex byte size of the address
1318 // of the range that contains <addr>
1320 permissions:<permissions>; // <permissions> is a string that contains one
1321 // or more of the characters from "rwx"
1323 name:<name>; // <name> is a hex encoded string that contains the name of
1324 // the memory region mapped at the given address. In case of
1325 // regions backed by a file it have to be the absolute path of
1326 // the file while for anonymous regions it have to be the name
1327 // associated to the region if that is available.
1329 flags:<flags-string>; // where <flags-string> is a space separated string
1330 // of flag names. Currently the only supported flag
1331 // is "mt" for AArch64 memory tagging. lldb will
1332 // ignore any other flags in this field.
1334 type:[<type>][,<type>]; // memory types that apply to this region, e.g.
1335 // "stack" for stack memory.
1337 error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is
1338 // a hex encoded string value that
1339 // contains an error string
1341 dirty-pages:[<hexaddr>][,<hexaddr]; // A list of memory pages within this
1342 // region that are "dirty" -- they have been modified.
1343 // Page addresses are in base 16. The size of a page can
1344 // be found from the qHostInfo's page-size key-value.
1346 // If the stub supports identifying dirty pages within a
1347 // memory region, this key should always be present for all
1348 // qMemoryRegionInfo replies. This key with no pages
1349 // listed ("dirty-pages:;") indicates no dirty pages in
1350 // this memory region. The *absence* of this key means
1351 // that this stub cannot determine dirty pages.
1353 If the address requested is not in a mapped region (e.g. we've jumped through
1354 a NULL pointer and are at 0x0) currently lldb expects to get back the size
1355 of the unmapped region -- that is, the distance to the next valid region.
1356 For instance, with a macOS process which has nothing mapped in the first
1357 4GB of its address space, if we're asking about address 0x2,
1360 start:2;size:fffffffe;
1362 The lack of 'permissions:' indicates that none of read/write/execute are valid
1365 //----------------------------------------------------------------------
1366 // "x" - Binary memory read
1368 // Like the 'm' (read) and 'M' (write) packets, this is a partner to the
1369 // 'X' (write binary data) packet, 'x'.
1371 // It is called like
1375 // where both ADDRESS and LENGTH are big-endian base 16 values.
1377 // To test if this packet is available, send a addr/len of 0:
1381 // and you will get an "OK" response.
1383 // The reply will be the data requested in 8-bit binary data format.
1384 // The standard quoting is applied to the payload -- characters
1386 // will all be escaped with '}' (0x7d) character and then XOR'ed with 0x20.
1388 // A typical use to read 512 bytes at 0x1000 would look like
1392 // The "0x" prefixes are optional - like most of the gdb-remote packets,
1393 // omitting them will work fine; these numbers are always base 16.
1395 // The length of the payload is not provided. A reliable, 8-bit clean,
1396 // transport layer is assumed.
1397 //----------------------------------------------------------------------
1399 //----------------------------------------------------------------------
1400 // Detach and stay stopped:
1402 // We extended the "D" packet to specify that the monitor should keep the
1403 // target suspended on detach. The normal behavior is to resume execution
1404 // on detach. We will send:
1406 // qSupportsDetachAndStayStopped:
1408 // to query whether the monitor supports the extended detach, and if it does,
1409 // when we want the monitor to detach but not resume the target, we will
1414 // In any case, if we want the normal detach behavior we will just send:
1417 //----------------------------------------------------------------------
1419 //----------------------------------------------------------------------
1420 // QSaveRegisterState
1421 // QSaveRegisterState;thread:XXXX;
1424 // The QSaveRegisterState packet tells the remote debugserver to save
1425 // all registers and return a non-zero unique integer ID that
1426 // represents these save registers. If thread suffixes are enabled the
1427 // second form of this packet is used, otherwise the first form is
1428 // used. This packet is called prior to executing an expression, so
1429 // the remote GDB server should do anything it needs to in order to
1430 // ensure the registers that are saved are correct. On macOS this
1431 // involves calling "thread_abort_safely(mach_port_t thread)" to
1432 // ensure we get the correct registers for a thread in case it is
1433 // currently having code run on its behalf in the kernel.
1436 // unsigned - The save_id result is a non-zero unsigned integer value
1437 // that can be passed back to the GDB server using a
1438 // QRestoreRegisterState packet to restore the registers
1440 // "EXX" - or an error code in the form of EXX where XX is a
1443 // PRIORITY TO IMPLEMENT
1444 // Low, this is mostly a convenience packet to avoid having to send all
1445 // registers via a g packet. It should only be implemented if support
1446 // for the QRestoreRegisterState is added.
1447 //----------------------------------------------------------------------
1449 //----------------------------------------------------------------------
1450 // QRestoreRegisterState:<save_id>
1451 // QRestoreRegisterState:<save_id>;thread:XXXX;
1454 // The QRestoreRegisterState packet tells the remote debugserver to
1455 // restore all registers using the "save_id" which is an unsigned
1456 // integer that was returned from a previous call to
1457 // QSaveRegisterState. The restoration process can only be done once
1458 // as the data backing the register state will be freed upon the
1459 // completion of the QRestoreRegisterState command.
1461 // If thread suffixes are enabled the second form of this packet is
1462 // used, otherwise the first form is used.
1465 // "OK" - if all registers were successfully restored
1466 // "EXX" - for any errors
1468 // PRIORITY TO IMPLEMENT
1469 // Low, this is mostly a convenience packet to avoid having to send all
1470 // registers via a g packet. It should only be implemented if support
1471 // for the QSaveRegisterState is added.
1472 //----------------------------------------------------------------------
1474 //----------------------------------------------------------------------
1475 // qFileLoadAddress:<file_path>
1478 // Get the load address of a memory mapped file.
1479 // The load address is defined as the address of the first memory
1480 // region what contains data mapped from the specified file.
1483 // <unsigned-hex64> - Load address of the file in big endian encoding
1484 // "E01" - the requested file isn't loaded
1485 // "EXX" - for any other errors
1487 // PRIORITY TO IMPLEMENT
1488 // Low, required if dynamic linker don't fill in the load address of
1489 // some object file in the rendezvous data structure.
1490 //----------------------------------------------------------------------
1492 //----------------------------------------------------------------------
1493 // qModuleInfo:<module_path>;<arch triple>
1496 // Get information for a module by given module path and architecture.
1499 // "(uuid|md5):...;triple:...;file_offset:...;file_size...;"
1500 // "EXX" - for any errors
1502 // PRIORITY TO IMPLEMENT
1503 // Optional, required if dynamic loader cannot fetch module's information like
1504 // UUID directly from inferior's memory.
1505 //----------------------------------------------------------------------
1507 //----------------------------------------------------------------------
1508 // jModulesInfo:[{"file":"...",triple:"..."}, ...]
1511 // Get information for a list of modules by given module path and
1515 // A JSON array of dictionaries containing the following keys: uuid,
1516 // triple, file_path, file_offset, file_size. The meaning of the fields
1517 // is the same as in the qModuleInfo packet. The server signals the
1518 // failure to retrieve the module info for a file by ommiting the
1519 // corresponding array entry from the response. The server may also
1520 // include entries the client did not ask for, if it has reason to
1521 // the modules will be interesting to the client.
1523 // PRIORITY TO IMPLEMENT
1524 // Optional. If not implemented, qModuleInfo packet will be used, which
1525 // may be slower if the target contains a large number of modules and
1526 // the communication link has a non-negligible latency.
1527 //----------------------------------------------------------------------
1529 //----------------------------------------------------------------------
1530 // Stop reply packet extensions
1533 // This section describes some of the additional information you can
1534 // specify in stop reply packets that help LLDB to know more detailed
1535 // information about your threads.
1538 // Standard GDB remote stop reply packets are reply packets sent in
1539 // response to a packet that made the program run. They come in the
1543 // "S" means signal and "AA" is a hex signal number that describes why
1544 // the thread or stopped. It doesn't specify which thread, so the "T"
1545 // packet is recommended to use instead of the "S" packet.
1547 // "TAAkey1:value1;key2:value2;..."
1548 // "T" means a thread stopped due to a unix signal where "AA" is a hex
1549 // signal number that describes why the program stopped. This is
1550 // followed by a series of key/value pairs:
1551 // - If key is a hex number, it is a register number and value is
1552 // the hex value of the register in debuggee endian byte order.
1553 // - If key == "thread", then the value is the big endian hex
1554 // thread-id of the stopped thread.
1555 // - If key == "core", then value is a hex number of the core on
1556 // which the stop was detected.
1557 // - If key == "watch" or key == "rwatch" or key == "awatch", then
1558 // value is the data address in big endian hex
1559 // - If key == "library", then value is ignore and "qXfer:libraries:read"
1560 // packets should be used to detect any newly loaded shared libraries
1563 // "W" means the process exited and "AA" is the exit status.
1566 // "X" means the process exited and "AA" is signal that caused the program
1569 // "O<ascii-hex-string>"
1570 // "O" means STDOUT has data that was written to its console and is
1571 // being delivered to the debugger. This packet happens asynchronously
1572 // and the debugger is expected to continue to wait for another stop reply
1577 // We have extended the "T" packet to be able to also understand the
1578 // following keys and values:
1580 // KEY VALUE DESCRIPTION
1581 // =========== ======== ================================================
1582 // "metype" unsigned mach exception type (the value of the EXC_XXX enumerations)
1583 // as an unsigned integer. For targets with mach
1586 // "mecount" unsigned mach exception data count as an unsigned integer
1587 // For targets with mach kernels only.
1589 // "medata" unsigned There should be "mecount" of these and it is the data
1590 // that goes along with a mach exception (as an unsigned
1591 // integer). For targets with mach kernels only.
1593 // "name" string The name of the thread as a plain string. The string
1594 // must not contain an special packet characters or
1595 // contain a ':' or a ';'. Use "hexname" if the thread
1596 // name has special characters.
1598 // "hexname" ascii-hex An ASCII hex string that contains the name of the thread
1600 // "qaddr" hex Big endian hex value that contains the libdispatch
1601 // queue address for the queue of the thread.
1603 // "reason" enum The enumeration must be one of:
1604 // "trace" the program stopped after a single instruction
1605 // was executed on a core. Usually done when single
1606 // stepping past a breakpoint
1607 // "breakpoint" a breakpoint set using a 'z' packet was hit.
1608 // "trap" stopped due to user interruption
1609 // "signal" stopped due to an actual unix signal, not
1610 // just the debugger using a unix signal to keep
1611 // the GDB remote client happy.
1612 // "watchpoint". Can be used with of the
1613 // "watch"/"rwatch"/"awatch" key value pairs.
1614 // Or can be used *instead* of those keys,
1615 // with the specially formatted "description" field.
1616 // "exception" an exception stop reason. Use with
1617 // the "description" key/value pair to describe the
1618 // exceptional event the user should see as the stop
1620 // "description" ascii-hex An ASCII hex string that contains a more descriptive
1621 // reason that the thread stopped. This is only needed
1622 // if none of the key/value pairs are enough to
1623 // describe why something stopped.
1625 // For "reason:watchpoint", "description" is an ascii-hex
1626 // encoded string with between one and three base 10 numbers,
1627 // space separated. The three numbers are
1628 // 1. watchpoint address. This address should always be within
1629 // a memory region lldb has a watchpoint on.
1630 // On architectures where the actual reported hit address may
1631 // be outside the watchpoint that was triggered, the remote
1632 // stub should determine which watchpoint was triggered and
1633 // report an address from within its range.
1634 // 2. watchpoint hardware register index number.
1635 // 3. actual watchpoint trap address, which may be outside
1636 // the range of any watched region of memory. On MIPS, an addr
1637 // outside a watched range means lldb should disable the wp,
1638 // step, re-enable the wp and continue silently.
1640 // On MIPS, the low 3 bits are masked so if a watchpoint is on
1641 // 0x1004, a 2-byte write to 0x1000 will trigger the watchpoint
1642 // (a false positive hit), and lldb needs to disable the
1643 // watchpoint at 0x1004, inst-step, then re-enable the watchpoint
1644 // and not make this a user visible event. The description here
1645 // would be "0x1004 0 0x1000". lldb needs a known watchpoint address
1646 // in the first field, so it can disable it & step.
1648 // On AArch64 we have a related issue, where you watch 4 bytes at
1649 // 0x1004, an instruction does an 8-byte write starting at
1650 // 0x1000 (a true watchpoint hit) and the hardware may report the
1651 // trap address as 0x1000 - before the watched memory region -
1652 // with the write extending into the watched region. This can
1653 // be reported as "0x1004 0 0x1000". lldb will use 0x1004 to
1654 // identify which Watchpoint was triggered, and can report 0x1000
1655 // to the user. The behavior of silently stepping over the
1656 // watchpoint, with an 3rd field addr outside the range, is
1657 // restricted to MIPS.
1658 // There may be false-positive watchpoint hits on AArch64 as well,
1659 // in the SVE Streaming Mode, but that is less common (see ESR
1660 // register flag "WPF", "Watchpoint might be False-Positive") and
1661 // not currently handled by lldb.
1663 // "threads" comma-sep-base16 A list of thread ids for all threads (including
1664 // the thread that we're reporting as stopped) that
1665 // are live in the process right now. lldb may
1666 // request that this be included in the T packet via
1667 // the QListThreadsInStopReply packet earlier in
1668 // the debug session.
1671 // threads:63387,633b2,63424,63462,63486;
1673 // "thread-pcs" comma-sep-base16 A list of pc values for all threads that currently
1674 // exist in the process, including the thread that
1675 // this T packet is reporting as stopped.
1676 // This key-value pair will only be emitted when the
1677 // "threads" key is already included in the T packet.
1678 // The pc values correspond to the threads reported
1679 // in the "threads" list. The number of pcs in the
1680 // "thread-pcs" list will be the same as the number of
1681 // threads in the "threads" list.
1682 // lldb may request that this be included in the T
1683 // packet via the QListThreadsInStopReply packet
1684 // earlier in the debug session.
1687 // thread-pcs:dec14,2cf872b0,2cf8681c,2d02d68c,2cf716a8;
1689 // "addressing_bits" unsigned optional Specifies how many bits in addresses
1690 // are significant for addressing, base
1691 // 10. If bits 38..0 in a 64-bit
1692 // pointer are significant for
1693 // addressing, then the value is 39.
1694 // This is needed on e.g. AArch64
1695 // v8.3 ABIs that use pointer
1696 // authentication in the high bits.
1697 // This value is normally sent in the
1698 // qHostInfo packet response, and if the
1699 // value cannot change during the process
1700 // lifetime, it does not need to be
1701 // duplicated here in the stop packet.
1702 // For a firmware environment with early
1703 // start code that may be changing the
1704 // page table setup, a dynamically set
1705 // value may be needed.
1706 // "low_mem_addressing_bits" unsigned optional, specifies how many bits in
1707 // addresses in low memory are significant
1708 // for addressing, base 10. AArch64 can
1709 // have different page table setups for low
1710 // and high memory, and therefore a different
1711 // number of bits used for addressing.
1712 // "high_mem_addressing_bits" unsigned optional, specifies how many bits in
1713 // addresses in high memory are significant
1714 // for addressing, base 10. AArch64 can have
1715 // different page table setups for low and
1716 // high memory, and therefore a different
1717 // number of bits used for addressing.
1720 // Since register values can be supplied with this packet, it is often useful
1721 // to return the PC, SP, FP, LR (if any), and FLAGS registers so that separate
1722 // packets don't need to be sent to read each of these registers from each
1725 // If a thread is stopped for no reason (like just because another thread
1726 // stopped, or because when one core stops all cores should stop), use a
1727 // "T" packet with "00" as the signal number and fill in as many key values
1728 // and registers as possible.
1730 // LLDB likes to know why a thread stopped since many thread control
1731 // operations like stepping over a source line, actually are implemented
1732 // by running the process multiple times. If a breakpoint is hit while
1733 // trying to step over a source line and LLDB finds out that a breakpoint
1734 // is hit in the "reason", we will know to stop trying to do the step
1735 // over because something happened that should stop us from trying to
1736 // do the step. If we are at a breakpoint and we disable the breakpoint
1737 // at the current PC and do an instruction single step, knowing that
1738 // we stopped due to a "trace" helps us know that we can continue
1739 // running versus stopping due to a "breakpoint" (if we have two
1740 // breakpoint instruction on consecutive instructions). So the more info
1741 // we can get about the reason a thread stops, the better job LLDB can
1742 // do when controlling your process. A typical GDB server behavior is
1743 // to send a SIGTRAP for breakpoints _and_ also when instruction single
1744 // stepping, in this case the debugger doesn't really know why we
1745 // stopped and it can make it hard for the debugger to control your
1746 // program correctly. What if a real SIGTRAP was delivered to a thread
1747 // while we were trying to single step? We wouldn't know the difference
1748 // with a standard GDB remote server and we could do the wrong thing.
1750 // PRIORITY TO IMPLEMENT
1751 // High. Having the extra information in your stop reply packets makes
1752 // your debug session more reliable and informative.
1753 //----------------------------------------------------------------------
1756 //----------------------------------------------------------------------
1757 // PLATFORM EXTENSION - for use as a GDB remote platform
1758 //----------------------------------------------------------------------
1763 // Get the first process info (qfProcessInfo) or subsequent process
1764 // info (qsProcessInfo) for one or more processes on the remote
1765 // platform. The first call gets the first match and subsequent calls
1766 // to qsProcessInfo gets the subsequent matches. Return an error EXX,
1767 // where XX are two hex digits, when no more matches are available.
1769 // PRIORITY TO IMPLEMENT
1770 // Required. The qfProcessInfo packet can be followed by a ':' and
1771 // some key value pairs. The key value pairs in the command are:
1773 // KEY VALUE DESCRIPTION
1774 // =========== ======== ================================================
1775 // "name" ascii-hex An ASCII hex string that contains the name of
1776 // the process that will be matched.
1777 // "name_match" enum One of: "equals", "starts_with", "ends_with",
1778 // "contains" or "regex"
1779 // "pid" integer A string value containing the decimal process ID
1780 // "parent_pid" integer A string value containing the decimal parent
1782 // "uid" integer A string value containing the decimal user ID
1783 // "gid" integer A string value containing the decimal group ID
1784 // "euid" integer A string value containing the decimal effective user ID
1785 // "egid" integer A string value containing the decimal effective group ID
1786 // "all_users" bool A boolean value that specifies if processes should
1787 // be listed for all users, not just the user that the
1788 // platform is running as
1789 // "triple" string An ASCII triple string ("x86_64",
1790 // "x86_64-apple-macosx", "armv7-apple-ios")
1791 // "args" string A string value containing the process arguments
1792 // separated by the character '-', where each argument is
1793 // hex-encoded. It includes argv[0].
1795 // The response consists of key/value pairs where the key is separated from the
1796 // values with colons and each pair is terminated with a semi colon. For a list
1797 // of the key/value pairs in the response see the "qProcessInfoPID" packet
1800 // Sample packet/response:
1801 // send packet: $qfProcessInfo#00
1802 // read packet: $pid:60001;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:x86_64-apple-macosx;#00
1803 // send packet: $qsProcessInfo#00
1804 // read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:x86_64-apple-macosx;#00
1805 // send packet: $qsProcessInfo#00
1806 // read packet: $E04#00
1807 //----------------------------------------------------------------------
1810 //----------------------------------------------------------------------
1811 // PLATFORM EXTENSION - for use as a GDB remote platform
1812 //----------------------------------------------------------------------
1813 // "qLaunchGDBServer"
1816 // Have the remote platform launch a GDB server.
1818 // PRIORITY TO IMPLEMENT
1819 // Required. The qLaunchGDBServer packet must be followed by a ':' and
1820 // some key value pairs. The key value pairs in the command are:
1822 // KEY VALUE DESCRIPTION
1823 // =========== ======== ================================================
1824 // "port" integer A string value containing the decimal port ID or
1825 // zero if the port should be bound and returned
1827 // "host" integer The host that connections should be limited to
1828 // when the GDB server is connected to.
1830 // The response consists of key/value pairs where the key is separated from the
1831 // values with colons and each pair is terminated with a semi colon.
1833 // Sample packet/response:
1834 // send packet: $qLaunchGDBServer:port:0;host:lldb.apple.com;#00
1835 // read packet: $pid:60025;port:50776;#00
1837 // The "pid" key/value pair is only specified if the remote platform launched
1838 // a separate process for the GDB remote server and can be omitted if no
1839 // process was separately launched.
1841 // The "port" key/value pair in the response lets clients know what port number
1842 // to attach to in case zero was specified as the "port" in the sent command.
1843 //----------------------------------------------------------------------
1846 //----------------------------------------------------------------------
1847 // PLATFORM EXTENSION - for use as a GDB remote platform
1848 //----------------------------------------------------------------------
1849 // "qProcessInfoPID:PID"
1852 // Have the remote platform get detailed information on a process by
1853 // ID. PID is specified as a decimal integer.
1855 // PRIORITY TO IMPLEMENT
1858 // The response consists of key/value pairs where the key is separated from the
1859 // values with colons and each pair is terminated with a semi colon.
1861 // The key value pairs in the response are:
1863 // KEY VALUE DESCRIPTION
1864 // =========== ======== ================================================
1865 // "pid" integer Process ID as a decimal integer string
1866 // "ppid" integer Parent process ID as a decimal integer string
1867 // "uid" integer A string value containing the decimal user ID
1868 // "gid" integer A string value containing the decimal group ID
1869 // "euid" integer A string value containing the decimal effective user ID
1870 // "egid" integer A string value containing the decimal effective group ID
1871 // "name" ascii-hex An ASCII hex string that contains the name of the process
1872 // "triple" string A target triple ("x86_64-apple-macosx", "armv7-apple-ios")
1874 // Sample packet/response:
1875 // send packet: $qProcessInfoPID:60050#00
1876 // read packet: $pid:60050;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:x86_64-apple-macosx;#00
1877 //----------------------------------------------------------------------
1879 //----------------------------------------------------------------------
1883 // Same as vAttach, except instead of a "pid" you send a process name.
1885 // PRIORITY TO IMPLEMENT
1886 // Low. Only needed for "process attach -n". If the packet isn't supported
1887 // then "process attach -n" will fail gracefully. So you need only to support
1888 // it if attaching to a process by name makes sense for your environment.
1889 //----------------------------------------------------------------------
1891 //----------------------------------------------------------------------
1895 // Same as vAttachName, except that the stub should wait for the next instance
1896 // of a process by that name to be launched and attach to that.
1898 // PRIORITY TO IMPLEMENT
1899 // Low. Only needed to support "process attach -w -n" which will fail
1900 // gracefully if the packet is not supported.
1901 //----------------------------------------------------------------------
1903 //----------------------------------------------------------------------
1904 // "qAttachOrWaitSupported"
1907 // This is a binary "is it supported" query. Return OK if you support
1910 // PRIORITY TO IMPLEMENT
1911 // Low. This is required if you support vAttachOrWait, otherwise no support
1912 // is needed since the standard "I don't recognize this packet" response
1913 // will do the right thing.
1914 //----------------------------------------------------------------------
1916 //----------------------------------------------------------------------
1920 // Same as vAttachWait, except that the stub will attach to a process
1921 // by name if it exists, and if it does not, it will wait for a process
1922 // of that name to appear and attach to it.
1924 // PRIORITY TO IMPLEMENT
1925 // Low. Only needed to implement "process attach -w -i false -n". If
1926 // you don't implement it but do implement -n AND lldb can somehow get
1927 // a process list from your device, it will fall back on scanning the
1928 // process list, and sending vAttach or vAttachWait depending on
1929 // whether the requested process exists already. This is racy,
1930 // however, so if you want to support this behavior it is better to
1931 // support this packet.
1932 //----------------------------------------------------------------------
1934 //----------------------------------------------------------------------
1935 // "jThreadExtendedInfo"
1938 // This packet, which takes its arguments as JSON and sends its reply as
1939 // JSON, allows the gdb remote stub to provide additional information
1940 // about a given thread.
1942 // PRIORITY TO IMPLEMENT
1943 // Low. This packet is only needed if the gdb remote stub wants to
1944 // provide interesting additional information about a thread for the
1947 // This packet takes its arguments in JSON form ( http://www.json.org ).
1948 // At a minimum, a thread must be specified, for example:
1950 // jThreadExtendedInfo:{"thread":612910}
1952 // Because this is a JSON string, the thread number is provided in base 10.
1953 // Additional key-value pairs may be provided by lldb to the gdb remote
1954 // stub. For instance, on some versions of macOS, lldb can read offset
1955 // information out of the system libraries. Using those offsets, debugserver
1956 // is able to find the Thread Specific Address (TSD) for a thread and include
1957 // that in the return information. So lldb will send these additional fields
1960 // jThreadExtendedInfo:{"plo_pthread_tsd_base_address_offset":0,"plo_pthread_tsd_base_offset":224,"plo_pthread_tsd_entry_size":8,"thread":612910}
1962 // There are no requirements for what is included in the response. A simple
1963 // reply on a OS X Yosemite / iOS 8 may include the pthread_t value, the
1964 // Thread Specific Data (TSD) address, the dispatch_queue_t value if the thread
1965 // is associated with a GCD queue, and the requested Quality of Service (QoS)
1966 // information about that thread. For instance, a reply may look like:
1968 // {"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}
1970 // tsd_address, pthread_t, and dispatch_queue_t are all simple key-value pairs.
1971 // The JSON standard requires that numbers be expressed in base 10 - so all of
1972 // these are. requested_qos is a dictionary with three key-value pairs in it -
1973 // so the UI layer may choose the form most appropriate for displaying to the user.
1975 // Sending JSON over gdb-remote protocol introduces some problems. We may be
1976 // sending strings with arbitrary contents in them, including the '#', '$', and '*'
1977 // characters that have special meaning in gdb-remote protocol and cannot occur
1978 // in the middle of the string. The standard solution for this would be to require
1979 // ascii-hex encoding of all strings, or ascii-hex encode the entire JSON payload.
1981 // Instead, the binary escaping convention is used for JSON data. This convention
1982 // (e.g. used for the X packet) says that if '#', '$', '*', or '}' are to occur in
1983 // the payload, the character '}' (0x7d) is emitted, then the metacharacter is emitted
1984 // xor'ed by 0x20. The '}' character occurs in every JSON payload at least once, and
1985 // '}' ^ 0x20 happens to be ']' so the raw packet characters for a request will look
1988 // jThreadExtendedInfo:{"thread":612910}]
1991 //----------------------------------------------------------------------
1993 //----------------------------------------------------------------------
1994 // "QEnableCompression"
1997 // This packet enables compression of the packets that the debug stub sends to lldb.
1998 // If the debug stub can support compression, it indictes this in the reply of the
1999 // "qSupported" packet. e.g.
2000 // LLDB SENDS: qSupported:xmlRegisters=i386,arm,mips
2001 // STUB REPLIES: qXfer:features:read+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;
2003 // If lldb knows how to use any of these compression algorithms, it can ask that this
2004 // compression mode be enabled.
2006 // QEnableCompression:type:zlib-deflate;
2008 // The debug stub should reply with an uncompressed "OK" packet to indicate that the
2009 // request was accepted. All further packets the stub sends will use this compression.
2011 // Packets are compressed as the last step before they are sent from the stub, and
2012 // decompressed as the first step after they are received. The packet format in compressed
2013 // mode becomes one of two:
2015 // $N<uncompressed payload>#00
2017 // $C<size of uncompressed payload in base 10>:<compressed payload>#00
2019 // Where "#00" is the actual checksum value if noack mode is not enabled. The checksum
2020 // value is for the "N<uncompressed payload>" or
2021 // "C<size of uncompressed payload in base 10>:<compressed payload>" bytes in the packet.
2023 // The size of the uncompressed payload in base 10 is provided because it will simplify
2024 // decompression if the final buffer size needed is known ahead of time.
2026 // Compression on low-latency connections is unlikely to be an improvement. Particularly
2027 // when the debug stub and lldb are running on the same host. It should only be used
2028 // for slow connections, and likely only for larger packets.
2030 // Example compression algorithsm that may be used include
2033 // The raw DEFLATE format as described in IETF RFC 1951. With the ZLIB library, you
2034 // can compress to this format with an initialization like
2035 // deflateInit2 (&stream, 5, Z_DEFLATED, -15, 8, Z_DEFAULT_STRATEGY)
2036 // and you can decompress with an initialization like
2037 // inflateInit2 (&stream, -15)
2040 // https://en.wikipedia.org/wiki/LZ4_(compression_algorithm)
2041 // https://github.com/Cyan4973/lz4
2042 // The libcompression APIs on darwin systems call this COMPRESSION_LZ4_RAW.
2045 // Compression algorithm added in macOS 10.11, with open source C reference
2046 // implementation on github.
2047 // https://en.wikipedia.org/wiki/LZFSE
2048 // https://github.com/lzfse/lzfse
2051 // libcompression implements "LZMA level 6", the default compression for the
2052 // open source LZMA implementation.
2053 //----------------------------------------------------------------------
2055 //----------------------------------------------------------------------
2056 // "jGetLoadedDynamicLibrariesInfos"
2059 // This packet asks the remote debug stub to send the details about libraries
2060 // being added/removed from the process as a performance optimization.
2062 // There are two ways this packet can be used. Both return a dictionary of
2063 // binary images formatted the same way.
2065 // One requests information on all shared libraries:
2066 // jGetLoadedDynamicLibrariesInfos:{"fetch_all_solibs":true}
2067 // with an optional `"report_load_commands":false` which can be added, asking
2068 // that only the dyld SPI information (load addresses, filenames) be returned.
2069 // The default behavior is that debugserver scans the mach-o header and load
2070 // commands of each binary, and returns it in the JSON reply.
2072 // And the second requests information about a list of shared libraries, given their load addresses:
2073 // jGetLoadedDynamicLibrariesInfos:{"solib_addresses":[8382824135,3258302053,830202858503]}
2075 // The second call is both a performance optimization (instead of having lldb read the mach-o header/load commands
2076 // out of memory with generic read packets) but also adds additional information in the form of the
2077 // filename of the shared libraries (which is not available in the mach-o header/load commands.)
2079 // An example using the OS X 10.11 style call:
2081 // LLDB SENDS: jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128}
2082 // 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
2084 // Or pretty-printed,
2086 // STUB REPLIES: ${"images":
2088 // {"load_address":4294967296,
2090 // "pathname":"/tmp/a.out",
2091 // "uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF",
2093 // {"magic":4277009103,
2094 // "cputype":16777223,
2095 // "cpusubtype":18446744071562067971,
2100 // {"name":"__PAGEZERO",
2102 // "vmsize":4294967296,
2107 // {"name":"__TEXT",
2108 // "vmaddr":4294967296,
2114 // {"name":"__LINKEDIT",
2115 // "vmaddr":4294971392,
2127 // This is similar to the qXfer:libraries:read packet, and it could
2128 // be argued that it should be merged into that packet. A separate
2129 // packet was created primarily because lldb needs to specify the
2130 // number of images to be read and the address from which the initial
2131 // information is read. Also the XML DTD would need to be extended
2132 // quite a bit to provide all the information that the DynamicLoaderMacOSX
2133 // would need to work correctly on this platform.
2135 // PRIORITY TO IMPLEMENT
2136 // On OS X 10.11, iOS 9, tvOS 9, watchOS 2 and older: Low. If this packet is absent,
2137 // lldb will read the Mach-O headers/load commands out of memory.
2138 // On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer: High. If this packet is absent,
2139 // lldb will not know anything about shared libraries in the inferior, or where the main
2140 // executable loaded.
2141 //----------------------------------------------------------------------
2143 //----------------------------------------------------------------------
2147 // Ask for the server for thread stop information of all threads.
2149 // PRIORITY TO IMPLEMENT
2150 // Low. This is a performance optimization, which speeds up debugging by avoiding
2151 // multiple round-trips for retrieving thread information. The information from this
2152 // packet can be retrieved using a combination of qThreadStopInfo and m packets.
2153 //----------------------------------------------------------------------
2155 The data in this packet is very similar to the stop reply packets, but is packaged in
2156 JSON and uses JSON arrays where applicable. The JSON output looks like:
2161 "reason":"exception",
2162 "qaddr":140735118423168,
2164 "0":"8000000000000000",
2165 "1":"0000000000000000",
2166 "2":"20fabf5fff7f0000",
2167 "3":"e8f8bf5fff7f0000",
2168 "4":"0100000000000000",
2169 "5":"d8f8bf5fff7f0000",
2170 "6":"b0f8bf5fff7f0000",
2171 "7":"20f4bf5fff7f0000",
2172 "8":"8000000000000000",
2173 "9":"61a8db78a61500db",
2174 "10":"3200000000000000",
2175 "11":"4602000000000000",
2176 "12":"0000000000000000",
2177 "13":"0000000000000000",
2178 "14":"0000000000000000",
2179 "15":"0000000000000000",
2180 "16":"960b000001000000",
2181 "17":"0202000000000000",
2182 "18":"2b00000000000000",
2183 "19":"0000000000000000",
2184 "20":"0000000000000000"
2187 {"address":140734799804592,"bytes":"c8f8bf5fff7f0000c9a59e8cff7f0000"},
2188 {"address":140734799804616,"bytes":"00000000000000000100000000000000"}
2193 It contains an array of dictionaries with all of the key value pairs that are
2194 normally in the stop reply packet, including the expedited registers. The registers are
2195 passed as hex-encoded JSON string in debuggee-endian byte order. Note that the register
2196 numbers are decimal numbers, unlike the stop-reply packet, where they are written in
2197 hex. The packet also contains expedited memory in the "memory" key. This allows the
2198 server to expedite memory that the client is likely to use (e.g., areas around the
2199 stack pointer, which are needed for computing backtraces) and it reduces the packet
2202 On macOS with debugserver, we expedite the frame pointer backchain for a thread
2203 (up to 256 entries) by reading 2 pointers worth of bytes at the frame pointer (for
2204 the previous FP and PC), and follow the backchain. Most backtraces on macOS and
2205 iOS now don't require us to read any memory!
2207 //----------------------------------------------------------------------
2208 // "jGetSharedCacheInfo"
2211 // This packet asks the remote debug stub to send the details about the inferior's
2212 // shared cache. The shared cache is a collection of common libraries/frameworks that
2213 // are mapped into every process at the same address on Darwin systems, and can be
2214 // identified by a load address and UUID.
2217 // LLDB SENDS: jGetSharedCacheInfo:{}
2218 // 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
2220 // PRIORITY TO IMPLEMENT
2221 // Low. When both lldb and the inferior process are running on the same computer, and lldb
2222 // and the inferior process have the same shared cache, lldb may (as an optimization) read
2223 // the shared cache out of its own memory instead of using gdb-remote read packets to read
2224 // them from the inferior process.
2225 //----------------------------------------------------------------------
2227 //----------------------------------------------------------------------
2228 // "qQueryGDBServer"
2231 // Ask the platform for the list of gdbservers we have to connect
2233 // PRIORITY TO IMPLEMENT
2234 // Low. The packet is required to support connecting to gdbserver started
2235 // by the platform instance automatically.
2236 //----------------------------------------------------------------------
2238 If the remote platform automatically started one or more gdbserver instance (without
2239 lldb asking it) then it have to return the list of port number or socket name for
2240 each of them what can be used by lldb to connect to those instances.
2242 The data in this packet is a JSON array of JSON objects with the following keys:
2243 "port": <the port number to connect> (optional)
2244 "socket_name": <the name of the socket to connect> (optional)
2250 { "socket_name": "foo" }
2253 //----------------------------------------------------------------------
2254 // "QSetDetachOnError"
2257 // Sets what the server should do when the communication channel with LLDB
2258 // goes down. Either kill the inferior process (0) or remove breakpoints and
2261 // PRIORITY TO IMPLEMENT
2262 // Low. Only required if the target wants to keep the inferior process alive
2263 // when the communication channel goes down.
2264 //----------------------------------------------------------------------
2266 The data in this packet is a single a character, which should be '0' if the
2267 inferior process should be killed, or '1' if the server should remove all
2268 breakpoints and detach from the inferior.
2270 //----------------------------------------------------------------------
2271 // "jGetDyldProcessState"
2274 // This packet fetches the process launch state, as reported by libdyld on
2275 // Darwin systems, most importantly to indicate when the system libraries
2276 // have initialized sufficiently to safely call utility functions.
2279 // LLDB SENDS: jGetDyldProcessState
2280 // STUB REPLIES: {"process_state_value":48,"process_state string":"dyld_process_state_libSystem_initialized"}
2282 // PRIORITY TO IMPLEMENT
2283 // Low. This packet is needed to prevent lldb's utility functions for
2284 // scanning the Objective-C class list from running very early in
2286 //----------------------------------------------------------------------