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