|
150
|
1 Here is a brief overview of the packets that an lldb platform server
|
|
|
2 needs to implement for the lldb testsuite to be run on a remote
|
|
|
3 target device/system.
|
|
|
4
|
|
|
5 These are almost all lldb extensions to the gdb-remote serial
|
|
|
6 protocol. Many of the vFile: packets are described to the "Host
|
|
|
7 I/O Packets" detailed in the gdb-remote protocol documentation,
|
|
|
8 although the lldb platform extensions include packets that are not
|
|
|
9 defined there (vFile:size:, vFile:mode:, vFile:symlink, vFile:chmod:).
|
|
|
10 Most importantly, the flags that lldb passes to vFile:open: are
|
|
|
11 incompatible with the flags that gdb specifies.
|
|
|
12
|
|
|
13
|
|
|
14 //----------------------------------------------------------------------
|
|
|
15 // QStartNoAckMode
|
|
|
16 //
|
|
|
17 // BRIEF
|
|
|
18 // A request to stop sending ACK packets for each properly formatted packet.
|
|
|
19 //
|
|
|
20 // EXAMPLE
|
|
|
21 // A platform session will typically start like this:
|
|
|
22 //
|
|
|
23 // receive: +$QStartNoAckMode#b0
|
|
|
24 // send: + <-- ACKing the properly formatted QStartNoAckMode packet
|
|
|
25 // send: $OK#9a
|
|
|
26 // receive: + <-- Our OK packet getting ACKed
|
|
|
27 //
|
|
|
28 // ACK mode is now disabled.
|
|
|
29
|
|
|
30 //----------------------------------------------------------------------
|
|
|
31 // qHostInfo
|
|
|
32 //
|
|
|
33 // BRIEF
|
|
|
34 // Describe the hardware and OS of the target system
|
|
|
35 //
|
|
|
36 // EXAMPLE
|
|
|
37 //
|
|
|
38 // receive: qHostInfo
|
|
|
39 // send: cputype:16777228;cpusubtype:1;ostype:ios;watchpoint_exceptions_received:before;os_version:12.1;vendor:apple;default_packet_timeout:5;
|
|
|
40 //
|
|
|
41 // All numbers are base 10, os_version is a string that will be parsed as major.minor.patch.
|
|
|
42
|
|
|
43 //----------------------------------------------------------------------
|
|
|
44 // qModuleInfo
|
|
|
45 //
|
|
|
46 // BRIEF
|
|
|
47 // Report information about a binary on the target system
|
|
|
48 //
|
|
|
49 // EXAMPLE
|
|
|
50 // receive: qModuleInfo:2f62696e2f6c73;
|
|
|
51 //
|
|
|
52 // FIXME finish this packet description, v. GDBRemoteCommunicationServerCommon::Handle_qModuleInfo
|
|
|
53
|
|
|
54
|
|
|
55 //----------------------------------------------------------------------
|
|
|
56 // qGetWorkingDir
|
|
|
57 //
|
|
|
58 // BRIEF
|
|
|
59 // Get the current working directory of the platform stub in
|
|
|
60 // ASCII hex encoding.
|
|
|
61 //
|
|
|
62 // EXAMPLE
|
|
|
63 //
|
|
|
64 // receive: qGetWorkingDir
|
|
|
65 // send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
|
|
|
66
|
|
|
67
|
|
|
68
|
|
|
69 //----------------------------------------------------------------------
|
|
|
70 // QSetWorkingDir:
|
|
|
71 //
|
|
|
72 // BRIEF
|
|
|
73 // Set the current working directory of the platform stub in
|
|
|
74 // ASCII hex encoding.
|
|
|
75 //
|
|
|
76 // EXAMPLE
|
|
|
77 //
|
|
|
78 // receive: QSetWorkingDir:2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
|
|
|
79 // send: OK
|
|
|
80
|
|
|
81 //----------------------------------------------------------------------
|
|
|
82 // qPlatform_mkdir:
|
|
|
83 //
|
|
|
84 // BRIEF
|
|
|
85 // Create a directory on the target system.
|
|
|
86 //
|
|
|
87 // EXAMPLE
|
|
|
88 //
|
|
|
89 // receive: qPlatform_mkdir:000001fd,2f746d702f6131
|
|
|
90 // send: F0
|
|
|
91 //
|
|
|
92 // request packet has the fields:
|
|
|
93 // 1. mode bits in base 16
|
|
|
94 // 2. file path in ascii-hex encoding
|
|
|
95 //
|
|
|
96 // response is F followed by the return value of the mkdir() call,
|
|
|
97 // base 10 encoded.
|
|
|
98
|
|
|
99 //----------------------------------------------------------------------
|
|
|
100 // qPlatform_shell:
|
|
|
101 //
|
|
|
102 // BRIEF
|
|
|
103 // Run a shell command on the target system, return the output.
|
|
|
104 //
|
|
|
105 // EXAMPLE
|
|
|
106 //
|
|
|
107 // receive: qPlatform_shell:6c73202f746d702f,0000000a
|
|
|
108 // send: F,0,0,<OUTPUT>
|
|
|
109 //
|
|
|
110 // request packet has the fields:
|
|
|
111 // 1. shell command ascii-hex encoded
|
|
|
112 // 2. timeout
|
|
|
113 // 3. {optional} working directory ascii-hex encoded
|
|
|
114 //
|
|
|
115 // Response is F followed by the return value of the command (base 16),
|
|
|
116 // followed by a another number, followed by the output of the command
|
|
|
117 / in binary-escaped-data encoding.
|
|
|
118
|
|
|
119 //----------------------------------------------------------------------
|
|
|
120 // qLaunchGDBServer
|
|
|
121 //
|
|
|
122 // BRIEF
|
|
|
123 // Start a gdbserver process (gdbserver, debugserver, lldb-server)
|
|
|
124 // on the target system.
|
|
|
125 //
|
|
|
126 // EXAMPLE
|
|
|
127 //
|
|
|
128 // receive: qLaunchGDBServer;host:<HOSTNAME_LLDB_IS_ON>;
|
|
|
129 // send: pid:1337;port:43001;
|
|
|
130 //
|
|
|
131 // request packet hostname field is not ascii-hex encoded. Hostnames
|
|
|
132 // don't have $ or # characters in them.
|
|
|
133 //
|
|
|
134 // response to the packet is the pid of the newly launched gdbserver,
|
|
|
135 // and the port it is listening for a connection on.
|
|
|
136 //
|
|
|
137 // When the testsuite is running, lldb may use the pid to kill off a
|
|
|
138 // debugserver that doesn't seem to be responding, etc.
|
|
|
139
|
|
|
140 //----------------------------------------------------------------------
|
|
|
141 // qKillSpawnedProcess:
|
|
|
142 //
|
|
|
143 // BRIEF
|
|
|
144 // Kill a process running on the target system.
|
|
|
145 //
|
|
|
146 // EXAMPLE
|
|
|
147 //
|
|
|
148 // receive: qKillSpawnedProcess:1337
|
|
|
149 // send: OK
|
|
|
150 //
|
|
|
151 // The request packet has the process ID in base 10.
|
|
|
152
|
|
|
153 //----------------------------------------------------------------------
|
|
|
154 // qProcessInfoPID:
|
|
|
155 //
|
|
|
156 // BRIEF
|
|
|
157 // Gather information about a process running on the target
|
|
|
158 //
|
|
|
159 // EXAMPLE
|
|
|
160 //
|
|
|
161 // receive: qProcessInfoPID:71964
|
|
|
162 // send: pid:71964;name:612e6f7574;
|
|
|
163 //
|
|
|
164 // The request packet has the pid encoded in base 10.
|
|
|
165 //
|
|
|
166 // The reply has semicolon-separated name:value fields, two are
|
|
|
167 // shown here. pid is base 10 encoded. name is ascii hex encoded.
|
|
|
168 // lldb-server can reply with many additional fields, but I think
|
|
|
169 // this is enough for the testsuite.
|
|
|
170
|
|
|
171 //----------------------------------------------------------------------
|
|
|
172 // qfProcessInfo:
|
|
|
173 //
|
|
|
174 // BRIEF
|
|
|
175 // Search the process table for processes matching criteria,
|
|
|
176 // respond with them in multiple packets.
|
|
|
177 //
|
|
|
178 // EXAMPLE
|
|
|
179 //
|
|
|
180 // receive: qfProcessInfo:name_match:equals;name:6e6f70726f6365737365786973747377697468746869736e616d65;
|
|
|
181 // send: pid:3500;name:612e6f7574;
|
|
|
182 //
|
|
|
183 // The request packet has a criteria to search for, followed by
|
|
|
184 // a specific name.
|
|
|
185 //
|
|
|
186 // KEY VALUE DESCRIPTION
|
|
|
187 // =========== ======== ================================================
|
|
|
188 // "name" ascii-hex An ASCII hex string that contains the name of
|
|
|
189 // the process that will be matched.
|
|
|
190 // "name_match" enum One of: "equals", "starts_with", "ends_with",
|
|
|
191 // "contains" or "regex"
|
|
|
192 // "pid" integer A string value containing the decimal process ID
|
|
|
193 // "parent_pid" integer A string value containing the decimal parent
|
|
|
194 // process ID
|
|
|
195 // "uid" integer A string value containing the decimal user ID
|
|
|
196 // "gid" integer A string value containing the decimal group ID
|
|
|
197 // "euid" integer A string value containing the decimal effective user ID
|
|
|
198 // "egid" integer A string value containing the decimal effective group ID
|
|
|
199 // "all_users" bool A boolean value that specifies if processes should
|
|
|
200 // be listed for all users, not just the user that the
|
|
|
201 // platform is running as
|
|
|
202 // "triple" ascii-hex An ASCII hex target triple string ("x86_64",
|
|
|
203 // "x86_64-apple-macosx", "armv7-apple-ios")
|
|
|
204 //
|
|
|
205 // If no criteria is given, qfProcessInfo will request a list of every process.
|
|
|
206 //
|
|
|
207 // The lldb testsuite currently only uses name_match:equals and the
|
|
|
208 // no-criteria mode to list every process.
|
|
|
209 //
|
|
|
210 // The response should include any information about the process that
|
|
|
211 // can be retrieved in semicolon-separated name:value fields.
|
|
|
212 // In this example, pid is base 10, name is ascii-hex encoded.
|
|
|
213 // The testsuite seems to only require these two.
|
|
|
214 //
|
|
|
215 // This packet only responds with one process. To get further matches to
|
|
|
216 // the search, qsProcessInfo should be sent.
|
|
|
217 //
|
|
|
218 // If no process match is found, Exx should be returned.
|
|
|
219 //
|
|
|
220 // Sample packet/response:
|
|
|
221 // send packet: $qfProcessInfo#00
|
|
|
222 // read packet: $pid:60001;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:7838365f36342d6170706c652d6d61636f7378;#00
|
|
|
223 // send packet: $qsProcessInfo#00
|
|
|
224 // read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:7838365f36342d6170706c652d6d61636f7378;#00
|
|
|
225 // send packet: $qsProcessInfo#00
|
|
|
226 // read packet: $E04#00
|
|
|
227
|
|
|
228 //----------------------------------------------------------------------
|
|
|
229 // qsProcessInfo
|
|
|
230 //
|
|
|
231 // BRIEF
|
|
|
232 // Return the next process info found by the most recent qfProcessInfo:
|
|
|
233 // packet.
|
|
|
234 //
|
|
|
235 // EXAMPLE
|
|
|
236 //
|
|
|
237 // Continues to return the results of the qfProcessInfo. Once all matches
|
|
|
238 // have been sent, Exx is returned to indicate end of matches.
|
|
|
239
|
|
|
240 //----------------------------------------------------------------------
|
|
|
241 // vFile:size:
|
|
|
242 //
|
|
|
243 // BRIEF
|
|
|
244 // Get the size of a file on the target system, filename in ASCII hex.
|
|
|
245 //
|
|
|
246 // EXAMPLE
|
|
|
247 //
|
|
|
248 // receive: vFile:size:2f746d702f61
|
|
|
249 // send: Fc008
|
|
|
250 //
|
|
|
251 // response is "F" followed by the file size in base 16.
|
|
|
252 // "F-1,errno" with the errno if an error occurs.
|
|
|
253
|
|
|
254
|
|
|
255 //----------------------------------------------------------------------
|
|
|
256 // vFile:mode:
|
|
|
257 //
|
|
|
258 // BRIEF
|
|
|
259 // Get the mode bits of a file on the target system, filename in ASCII hex.
|
|
|
260 //
|
|
|
261 // EXAMPLE
|
|
|
262 //
|
|
|
263 // receive: vFile:mode:2f746d702f61
|
|
|
264 // send: F1ed
|
|
|
265 //
|
|
|
266 // response is "F" followed by the mode bits in base 16, this 0x1ed would
|
|
|
267 // correspond to 0755 in octal.
|
|
|
268 // "F-1,errno" with the errno if an error occurs.
|
|
|
269
|
|
|
270 //----------------------------------------------------------------------
|
|
|
271 // vFile:unlink:
|
|
|
272 //
|
|
|
273 // BRIEF
|
|
|
274 // Remove a file on the target system.
|
|
|
275 //
|
|
|
276 // EXAMPLE
|
|
|
277 //
|
|
|
278 // receive: vFile:unlink:2f746d702f61
|
|
|
279 // send: F0
|
|
|
280 //
|
|
|
281 // Argument is a file path in ascii-hex encoding.
|
|
|
282 // Response is "F" plus the return value of unlink(), base 10 encoding.
|
|
|
283
|
|
|
284 //----------------------------------------------------------------------
|
|
|
285 // vFile:symlink:
|
|
|
286 //
|
|
|
287 // BRIEF
|
|
|
288 // Create a symbolic link (symlink, soft-link) on the target system.
|
|
|
289 //
|
|
|
290 // EXAMPLE
|
|
|
291 //
|
|
|
292 // receive: vFile:symlink:<SRC-FILE>,<DST-NAME>
|
|
|
293 // send: F0,0
|
|
|
294 //
|
|
|
295 // Argument file paths are in ascii-hex encoding.
|
|
|
296 // Response is "F" plus the return value of symlink(), base 10 encoding, twice.
|
|
|
297
|
|
|
298 //----------------------------------------------------------------------
|
|
|
299 // vFile:chmod:
|
|
|
300 // qPlatform_chmod:
|
|
|
301 //
|
|
|
302 // BRIEF
|
|
|
303 // Change the permission mode bits on a file on the target
|
|
|
304 //
|
|
|
305 // EXAMPLE
|
|
|
306 //
|
|
|
307 // receive: vFile:chmod:180,2f746d702f61
|
|
|
308 // send: F0
|
|
|
309 //
|
|
|
310 // Arguments are the mode bits to set, base 16, and a file path in
|
|
|
311 // ascii-hex encoding.
|
|
|
312 // Response is "F" plus the return value of chmod(), base 10 encoding.
|
|
|
313 //
|
|
|
314 // I don't know why there are two packets for the same thing, v.
|
|
|
315 // vFile:chmod:.
|
|
|
316
|
|
|
317 //----------------------------------------------------------------------
|
|
|
318 // vFile:chmod:
|
|
|
319 //
|
|
|
320 // BRIEF
|
|
|
321 // Change the permission mode bits on a file on the target
|
|
|
322 //
|
|
|
323 // EXAMPLE
|
|
|
324 //
|
|
|
325 // receive: vFile:chmod:180,2f746d702f61
|
|
|
326 // send: F0
|
|
|
327 //
|
|
|
328 // Arguments are the mode bits to set, base 16, and a file path in
|
|
|
329 // ascii-hex encoding.
|
|
|
330 // Response is "F" plus the return value of chmod(), base 10 encoding.
|
|
|
331
|
|
|
332
|
|
|
333 //----------------------------------------------------------------------
|
|
|
334 // vFile:open:
|
|
|
335 //
|
|
|
336 // BRIEF
|
|
|
337 // Open a file on the remote system and return the file descriptor of it.
|
|
|
338 //
|
|
|
339 // EXAMPLE
|
|
|
340 //
|
|
|
341 // receive: vFile:open:2f746d702f61,00000001,00000180
|
|
|
342 // send: F8
|
|
|
343 //
|
|
|
344 // request packet has the fields:
|
|
|
345 // 1. ASCII hex encoded filename
|
|
|
346 // 2. flags passed to the open call, base 16.
|
|
|
347 // Note that these are not the oflags that open(2) takes, but
|
|
|
348 // are the constant values in enum OpenOptions from lldb's File.h
|
|
|
349 // 3. mode bits, base 16
|
|
|
350 //
|
|
|
351 // response is F followed by the opened file descriptor in base 10.
|
|
|
352 // "F-1,errno" with the errno if an error occurs.
|
|
|
353 //
|
|
173
|
354 // COMPATIBILITY
|
|
150
|
355 // The gdb-remote serial protocol documentatio defines a vFile:open:
|
|
|
356 // packet which uses incompatible flag values, e.g. 1 means O_WRONLY
|
|
|
357 // in gdb's vFile:open:, but it means eOpenOptionRead to lldb's
|
|
|
358 // implementation.
|
|
|
359
|
|
|
360 //----------------------------------------------------------------------
|
|
|
361 // vFile:close:
|
|
|
362 //
|
|
|
363 // BRIEF
|
|
|
364 // Close a previously opened file descriptor.
|
|
|
365 //
|
|
|
366 // EXAMPLE
|
|
|
367 //
|
|
|
368 // receive: vFile:close:7
|
|
|
369 // send: F0
|
|
|
370 //
|
|
|
371 // File descriptor is in base 10.
|
|
|
372 // "F-1,errno" with the errno if an error occurs.
|
|
|
373
|
|
|
374
|
|
|
375 //----------------------------------------------------------------------
|
|
|
376 // vFile:pread:
|
|
|
377 //
|
|
|
378 // BRIEF
|
|
|
379 // Read data from an opened file descriptor.
|
|
|
380 //
|
|
|
381 // EXAMPLE
|
|
|
382 //
|
|
|
383 // receive: vFile:pread:7,1024,0
|
|
|
384 // send: F4;a'b\00
|
|
|
385 //
|
|
|
386 // request packet has the fields:
|
|
|
387 // 1. file descriptor, base 10
|
|
|
388 // 2. number of bytes to be read, base 10
|
|
|
389 // 3. offset into file to start from, base 10
|
|
|
390 //
|
|
|
391 // Response is F, followed by the number of bytes read (base 10), a
|
|
|
392 // semicolon, followed by the data in the binary-escaped-data encoding.
|
|
|
393
|
|
|
394
|
|
|
395 //----------------------------------------------------------------------
|
|
|
396 // vFile:pwrite:
|
|
|
397 //
|
|
|
398 // BRIEF
|
|
|
399 // Write data to a previously opened file descriptor.
|
|
|
400 //
|
|
|
401 // EXAMPLE
|
|
|
402 //
|
|
|
403 // receive: vFile:pwrite:8,0,\cf\fa\ed\fe\0c\00\00
|
|
|
404 // send: F1024
|
|
|
405 //
|
|
|
406 // request packet has the fields:
|
|
|
407 // 1. file descriptor, base 10
|
|
|
408 // 2. offset into file to start from, base 10
|
|
|
409 // 3. binary-escaped-data to be written
|
|
|
410 //
|
|
|
411 // Response is F, followed by the number of bytes written (base 10)
|
|
|
412
|
|
|
413
|
|
|
414
|
|
|
415
|
|
|
416
|
|
|
417
|
|
|
418 Finally, the platform must be able to launch processes so that debugserver
|
|
|
419 can attach to them. To do this, the following packets should be handled:
|
|
|
420
|
|
|
421 QSetDisableASLR
|
|
|
422 QSetDetachOnError
|
|
|
423 QSetSTDOUT
|
|
|
424 QSetSTDERR
|
|
|
425 QSetSTDIN
|
|
|
426 QEnvironment
|
|
|
427 QEnvironmentHexEncoded
|
|
|
428 A
|
|
|
429 qLaunchSuccess
|
|
|
430 qProcessInfo
|
|
|
431
|
|
|
432 Most of these are documented in the standard gdb-remote protocol
|
|
|
433 and/or the lldb-gdb-remote.txt documentation.
|
