[RISCV] Add addu.w and slliu.w test that uses getelementptr with zero extended indices.
[lldb.git] / lldb / docs / lldb-platform-packets.txt
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 // qPathComplete
242 //
243 // BRIEF
244 //   Get a list of matched disk files/directories by passing a boolean flag
245 //   and a partial path.
246 //
247 // EXAMPLE
248 //
249 //   receive: qPathComplete:0,6d61696e
250 //   send:    M6d61696e2e637070
251 //   receive: qPathComplete:1,746573
252 //   send:    M746573742f,74657374732f
253 //
254 //   If the first argument is zero, the result should contain all
255 //   files (including directories) starting with the given path. If the
256 //   argument is one, the result should contain only directories.
257 //
258 //   The result should be a comma-separated list of hex-encoded paths.
259 //   Paths denoting a directory should end with a directory separator ('/' or '\').
260
261 //----------------------------------------------------------------------
262 // vFile:size:
263 //
264 // BRIEF
265 //   Get the size of a file on the target system, filename in ASCII hex.
266 //
267 // EXAMPLE
268 // 
269 //  receive: vFile:size:2f746d702f61
270 //  send:    Fc008
271 //
272 //  response is "F" followed by the file size in base 16.
273 //  "F-1,errno" with the errno if an error occurs.
274
275
276 //----------------------------------------------------------------------
277 // vFile:mode:
278 //
279 // BRIEF
280 //   Get the mode bits of a file on the target system, filename in ASCII hex.
281 //
282 // EXAMPLE
283 // 
284 //  receive: vFile:mode:2f746d702f61
285 //  send:    F1ed
286 //
287 //  response is "F" followed by the mode bits in base 16, this 0x1ed would 
288 //  correspond to 0755 in octal.  
289 //  "F-1,errno" with the errno if an error occurs.
290
291 //----------------------------------------------------------------------
292 // vFile:unlink:
293 //
294 // BRIEF
295 //   Remove a file on the target system.
296 //
297 // EXAMPLE
298 // 
299 //  receive: vFile:unlink:2f746d702f61
300 //  send:    F0
301 //
302 //  Argument is a file path in ascii-hex encoding.
303 //  Response is "F" plus the return value of unlink(), base 10 encoding.
304
305 //----------------------------------------------------------------------
306 // vFile:symlink:
307 //
308 // BRIEF
309 //   Create a symbolic link (symlink, soft-link) on the target system.
310 //
311 // EXAMPLE
312 // 
313 //  receive: vFile:symlink:<SRC-FILE>,<DST-NAME>
314 //  send:    F0,0
315 //
316 //  Argument file paths are in ascii-hex encoding.
317 //  Response is "F" plus the return value of symlink(), base 10 encoding, twice.
318
319 //----------------------------------------------------------------------
320 // vFile:chmod:
321 // qPlatform_chmod:
322 //
323 // BRIEF
324 //   Change the permission mode bits on a file on the target
325 //
326 // EXAMPLE
327 // 
328 //  receive: vFile:chmod:180,2f746d702f61
329 //  send:    F0
330 //
331 //  Arguments are the mode bits to set, base 16, and a file path in 
332 //  ascii-hex encoding.
333 //  Response is "F" plus the return value of chmod(), base 10 encoding.
334 //
335 //  I don't know why there are two packets for the same thing, v.
336 //  vFile:chmod:.
337
338 //----------------------------------------------------------------------
339 // vFile:chmod:
340 //
341 // BRIEF
342 //   Change the permission mode bits on a file on the target
343 //
344 // EXAMPLE
345 // 
346 //  receive: vFile:chmod:180,2f746d702f61
347 //  send:    F0
348 //
349 //  Arguments are the mode bits to set, base 16, and a file path in 
350 //  ascii-hex encoding.
351 //  Response is "F" plus the return value of chmod(), base 10 encoding.
352
353
354 //----------------------------------------------------------------------
355 // vFile:open:
356 //
357 // BRIEF
358 //   Open a file on the remote system and return the file descriptor of it.
359 //
360 // EXAMPLE
361 // 
362 //  receive: vFile:open:2f746d702f61,00000001,00000180
363 //  send:    F8
364 //
365 //  request packet has the fields:
366 //     1. ASCII hex encoded filename
367 //     2. flags passed to the open call, base 16.
368 //        Note that these are not the oflags that open(2) takes, but
369 //        are the constant values in enum OpenOptions from lldb's File.h
370 //     3. mode bits, base 16
371 //  
372 //  response is F followed by the opened file descriptor in base 10.
373 //  "F-1,errno" with the errno if an error occurs.
374 //
375 //  COMPATIBILITY
376 //    The gdb-remote serial protocol documentatio defines a vFile:open:
377 //    packet which uses incompatible flag values, e.g. 1 means O_WRONLY
378 //    in gdb's vFile:open:, but it means eOpenOptionRead to lldb's
379 //    implementation.
380
381 //----------------------------------------------------------------------
382 // vFile:close:
383 //
384 // BRIEF
385 //   Close a previously opened file descriptor.
386 //
387 // EXAMPLE
388 // 
389 //  receive: vFile:close:7
390 //  send:    F0
391 //
392 //  File descriptor is in base 10.
393 //  "F-1,errno" with the errno if an error occurs.
394
395
396 //----------------------------------------------------------------------
397 // vFile:pread:
398 //
399 // BRIEF
400 //   Read data from an opened file descriptor.
401 //
402 // EXAMPLE
403 // 
404 //  receive: vFile:pread:7,1024,0
405 //  send:    F4;a'b\00
406 //
407 //  request packet has the fields:
408 //     1. file descriptor, base 10
409 //     2. number of bytes to be read, base 10
410 //     3. offset into file to start from, base 10
411 //
412 //  Response is F, followed by the number of bytes read (base 10), a
413 //  semicolon, followed by the data in the binary-escaped-data encoding.
414 //
415 //  COMPATIBILITY
416 //    The gdb-remote serial protocol documentation says that numbers
417 //    in "vFile:" packets should be hexadecimal. Instead lldb uses
418 //    decimal.
419
420
421 //----------------------------------------------------------------------
422 // vFile:pwrite:
423 //
424 // BRIEF
425 //   Write data to a previously opened file descriptor.
426 //
427 // EXAMPLE
428 // 
429 //  receive: vFile:pwrite:8,0,\cf\fa\ed\fe\0c\00\00
430 //  send:    F1024
431 //
432 //  request packet has the fields:
433 //     1. file descriptor, base 10
434 //     2. offset into file to start from, base 10
435 //     3. binary-escaped-data to be written
436 //
437 //  Response is F, followed by the number of bytes written (base 10)
438 //
439 //  COMPATIBILITY
440 //    The gdb-remote serial protocol documentation says that numbers
441 //    in "vFile:" packets should be hexadecimal. Instead lldb uses
442 //    decimal.
443
444
445
446
447
448 Finally, the platform must be able to launch processes so that debugserver
449 can attach to them.  To do this, the following packets should be handled:
450
451 QSetDisableASLR
452 QSetDetachOnError
453 QSetSTDOUT
454 QSetSTDERR
455 QSetSTDIN
456 QEnvironment
457 QEnvironmentHexEncoded
458 A
459 qLaunchSuccess
460 qProcessInfo
461
462 Most of these are documented in the standard gdb-remote protocol
463 and/or the lldb-gdb-remote.txt documentation.