vendor/lldb/lldb-trunk-r351319

2 files changed, 405 insertions, 0 deletions

diff --git a/docs/building-with-debug-llvm.txt b/docs/building-with-debug-llvm.txt
index f59ca410edb0f..af1bcf8856b2d 100644
--- a/docs/building-with-debug-llvm.txt
+++ b/docs/building-with-debug-llvm.txt
@@ -48,3 +48,4 @@ currently at a shell prompt in a checked-out LLDB repository.
 	the top left of the Xcode window.
 
 6.	Build lldb.xcodeproj.
+
diff --git a/docs/lldb-platform-packets.txt b/docs/lldb-platform-packets.txt
new file mode 100644
index 0000000000000..3258e4c0dd882
--- /dev/null
+++ b/docs/lldb-platform-packets.txt
@@ -0,0 +1,404 @@
+Here is a brief overview of the packets that an lldb platform server
+needs to implement for the lldb testsuite to be run on a remote
+target device/system.
+
+These are almost all lldb extensions to the gdb-remote serial
+protocol.  Many of the vFile: packets are described to the "Host
+I/O Packets" detailed in the gdb-remote protocol documentation,
+although the lldb platform extensions include packets that are not
+defined there (vFile:size:, vFile:mode:, vFile:symlink, vFile:chmod:).
+Most importantly, the flags that lldb passes to vFile:open: are 
+incompatible with the flags that gdb specifies.
+
+
+//----------------------------------------------------------------------
+// QStartNoAckMode
+//
+// BRIEF
+//   A request to stop sending ACK packets for each properly formatted packet.
+//
+// EXAMPLE 
+//   A platform session will typically start like this:
+//
+//   receive: +$QStartNoAckMode#b0
+//   send:    +       <-- ACKing the properly formatted QStartNoAckMode packet
+//   send:    $OK#9a
+//   receive: +       <-- Our OK packet getting ACKed
+//
+//   ACK mode is now disabled.
+
+//----------------------------------------------------------------------
+// qHostInfo
+//
+// BRIEF
+//   Describe the hardware and OS of the target system
+//
+// EXAMPLE
+//
+//  receive: qHostInfo
+//  send:    cputype:16777228;cpusubtype:1;ostype:ios;watchpoint_exceptions_received:before;os_version:12.1;vendor:apple;default_packet_timeout:5;
+//
+//  All numbers are base 10, os_version is a string that will be parsed as major.minor.patch.
+
+//----------------------------------------------------------------------
+// qModuleInfo
+//
+// BRIEF
+//   Report information about a binary on the target system
+//
+// EXAMPLE
+//  receive: qModuleInfo:2f62696e2f6c73;
+//
+// FIXME finish this packet description, v. GDBRemoteCommunicationServerCommon::Handle_qModuleInfo
+
+
+//----------------------------------------------------------------------
+// qGetWorkingDir
+//
+// BRIEF
+//   Get the current working directory of the platform stub in
+//   ASCII hex encoding.
+//
+// EXAMPLE
+// 
+//  receive: qGetWorkingDir
+//  send:    2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773 
+
+
+
+//----------------------------------------------------------------------
+// QSetWorkingDir:
+//
+// BRIEF
+//   Set the current working directory of the platform stub in
+//   ASCII hex encoding.
+//
+// EXAMPLE
+// 
+//  receive: QSetWorkingDir:2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773 
+//  send:    OK
+
+//----------------------------------------------------------------------
+// qPlatform_mkdir:
+//
+// BRIEF
+//   Create a directory on the target system.
+//
+// EXAMPLE
+// 
+//  receive: qPlatform_mkdir:000001fd,2f746d702f6131
+//  send:    F0
+//
+//  request packet has the fields:
+//     1. mode bits in base 16
+//     2. file path in ascii-hex encoding
+//
+//  response is F followed by the return value of the mkdir() call,
+//  base 10 encoded.
+
+//----------------------------------------------------------------------
+// qPlatform_shell:
+//
+// BRIEF
+//   Run a shell command on the target system, return the output.
+//
+// EXAMPLE
+// 
+//  receive: qPlatform_shell:6c73202f746d702f,0000000a
+//  send:    F,0,0,<OUTPUT>
+//
+//  request packet has the fields:
+//     1. shell command ascii-hex encoded
+//     2. timeout 
+//     3. {optional} working directory ascii-hex encoded
+//
+//  Response is F followed by the return value of the command (base 16),
+//  followed by a another number, followed by the output of the command
+/   in binary-escaped-data encoding.
+
+//----------------------------------------------------------------------
+// qLaunchGDBServer
+//
+// BRIEF
+//   Start a gdbserver process (gdbserver, debugserver, lldb-server)
+//   on the target system.
+//
+// EXAMPLE
+// 
+//  receive: qLaunchGDBServer;host:<HOSTNAME_LLDB_IS_ON>;
+//  send:    pid:1337;port:43001;
+//
+//  request packet hostname field is not ascii-hex encoded. Hostnames 
+//  don't have $ or # characters in them.
+//
+//  response to the packet is the pid of the newly launched gdbserver,
+//  and the port it is listening for a connection on.
+//
+//  When the testsuite is running, lldb may use the pid to kill off a 
+//  debugserver that doesn't seem to be responding, etc.
+
+//----------------------------------------------------------------------
+// qKillSpawnedProcess:
+//
+// BRIEF
+//   Kill a process running on the target system.
+//
+// EXAMPLE
+// 
+//  receive: qKillSpawnedProcess:1337
+//  send:    OK
+//
+//  The request packet has the process ID in base 10.
+
+//----------------------------------------------------------------------
+// qProcessInfoPID:
+//
+// BRIEF
+//   Gather information about a process running on the target
+//
+// EXAMPLE
+// 
+//  receive: qProcessInfoPID:71964
+//  send:    pid:71964;name:612e6f7574;
+//
+//  The request packet has the pid encoded in base 10.
+//
+//  The reply has semicolon-separated name:value fields, two are
+//  shown here.  pid is base 10 encoded.  name is ascii hex encoded.
+//  lldb-server can reply with many additional fields, but I think
+//  this is enough for the testsuite.
+
+//----------------------------------------------------------------------
+// qfProcessInfo:
+//
+// BRIEF
+//   Search the process table for processes matching criteria, 
+//   respond with them in multiple packets.
+//
+// EXAMPLE
+// 
+//  receive: qfProcessInfo:name_match:equals;name:6e6f70726f6365737365786973747377697468746869736e616d65;
+//  send:    pid:3500;name:612e6f7574;
+//
+//  The request packet has a criteria to search for, followed by
+//  a specific name.  Other name_match: values include
+//  starts_with, ends_with, contains, regex.  You can specify a pid
+//  to search for, a uid, all_users, triple, etc etc.  The testsuite
+//  only ever searches for name_match:equals.
+//
+//  The response should include any information about the process that
+//  can be retrieved in semicolon-separated name:value fields.
+//  In this example, pid is base 10, name is ascii-hex encoded.
+//  The testsuite seems to only require these two.
+//
+//  This packet only responds with one process.  To get further matches to
+//  the search, qsProcessInfo should be sent.
+//
+//  If no process match is found, Exx should be returned.
+
+//----------------------------------------------------------------------
+// qsProcessInfo
+//
+// BRIEF
+//   Return the next process info found by the most recent qfProcessInfo:
+//   packet.
+//
+// EXAMPLE
+// 
+//  Continues to return the results of the qfProcessInfo.  Once all matches
+//  have been sent, Exx is returned to indicate end of matches.
+
+//----------------------------------------------------------------------
+// vFile:size:
+//
+// BRIEF
+//   Get the size of a file on the target system, filename in ASCII hex.
+//
+// EXAMPLE
+// 
+//  receive: vFile:size:2f746d702f61
+//  send:    Fc008
+//
+//  response is "F" followed by the file size in base 16.
+//  "F-1,errno" with the errno if an error occurs.
+
+
+//----------------------------------------------------------------------
+// vFile:mode:
+//
+// BRIEF
+//   Get the mode bits of a file on the target system, filename in ASCII hex.
+//
+// EXAMPLE
+// 
+//  receive: vFile:mode:2f746d702f61
+//  send:    F1ed
+//
+//  response is "F" followed by the mode bits in base 16, this 0x1ed would 
+//  correspond to 0755 in octal.  
+//  "F-1,errno" with the errno if an error occurs.
+
+//----------------------------------------------------------------------
+// vFile:unlink:
+//
+// BRIEF
+//   Remove a file on the target system.
+//
+// EXAMPLE
+// 
+//  receive: vFile:unlink:2f746d702f61
+//  send:    F0
+//
+//  Argument is a file path in ascii-hex encoding.
+//  Response is "F" plus the return value of unlink(), base 10 encoding.
+
+//----------------------------------------------------------------------
+// vFile:symlink:
+//
+// BRIEF
+//   Create a symbolic link (symlink, soft-link) on the target system.
+//
+// EXAMPLE
+// 
+//  receive: vFile:symlink:<SRC-FILE>,<DST-NAME>
+//  send:    F0,0
+//
+//  Argument file paths are in ascii-hex encoding.
+//  Response is "F" plus the return value of symlink(), base 10 encoding, twice.
+
+//----------------------------------------------------------------------
+// vFile:chmod:
+// qPlatform_chmod:
+//
+// BRIEF
+//   Change the permission mode bits on a file on the target
+//
+// EXAMPLE
+// 
+//  receive: vFile:chmod:180,2f746d702f61
+//  send:    F0
+//
+//  Arguments are the mode bits to set, base 16, and a file path in 
+//  ascii-hex encoding.
+//  Response is "F" plus the return value of chmod(), base 10 encoding.
+//
+//  I don't know why there are two packets for the same thing, v.
+//  vFile:chmod:.
+
+//----------------------------------------------------------------------
+// vFile:chmod:
+//
+// BRIEF
+//   Change the permission mode bits on a file on the target
+//
+// EXAMPLE
+// 
+//  receive: vFile:chmod:180,2f746d702f61
+//  send:    F0
+//
+//  Arguments are the mode bits to set, base 16, and a file path in 
+//  ascii-hex encoding.
+//  Response is "F" plus the return value of chmod(), base 10 encoding.
+
+
+//----------------------------------------------------------------------
+// vFile:open:
+//
+// BRIEF
+//   Open a file on the remote system and return the file descriptor of it.
+//
+// EXAMPLE
+// 
+//  receive: vFile:open:2f746d702f61,00000001,00000180
+//  send:    F8
+//
+//  request packet has the fields:
+//     1. ASCII hex encoded filename
+//     2. flags passed to the open call, base 16.
+//        Note that these are not the oflags that open(2) takes, but
+//        are the constant values in enum OpenOptions from lldb's File.h
+//     3. mode bits, base 16
+//  
+//  response is F followed by the opened file descriptor in base 10.
+//  "F-1,errno" with the errno if an error occurs.
+//
+//  COMPATABILITY
+//    The gdb-remote serial protocol documentatio defines a vFile:open:
+//    packet which uses incompatible flag values, e.g. 1 means O_WRONLY
+//    in gdb's vFile:open:, but it means eOpenOptionRead to lldb's
+//    implementation.
+
+//----------------------------------------------------------------------
+// vFile:close:
+//
+// BRIEF
+//   Close a previously opened file descriptor.
+//
+// EXAMPLE
+// 
+//  receive: vFile:close:7
+//  send:    F0
+//
+//  File descriptor is in base 10.
+//  "F-1,errno" with the errno if an error occurs.
+
+
+//----------------------------------------------------------------------
+// vFile:pread:
+//
+// BRIEF
+//   Read data from an opened file descriptor.
+//
+// EXAMPLE
+// 
+//  receive: vFile:pread:7,1024,0
+//  send:    F4;a'b\00
+//
+//  request packet has the fields:
+//     1. file descriptor, base 10
+//     2. number of bytes to be read, base 10
+//     3. offset into file to start from, base 10
+//
+//  Response is F, followed by the number of bytes read (base 10), a
+//  semicolon, followed by the data in the binary-escaped-data encoding.
+
+
+//----------------------------------------------------------------------
+// vFile:pwrite:
+//
+// BRIEF
+//   Write data to a previously opened file descriptor.
+//
+// EXAMPLE
+// 
+//  receive: vFile:pwrite:8,0,\cf\fa\ed\fe\0c\00\00
+//  send:    F1024
+//
+//  request packet has the fields:
+//     1. file descriptor, base 10
+//     2. offset into file to start from, base 10
+//     3. binary-escaped-data to be written
+//
+//  Response is F, followed by the number of bytes written (base 10)
+
+
+
+
+
+
+Finally, the platform must be able to launch processes so that debugserver
+can attach to them.  To do this, the following packets should be handled:
+
+QSetDisableASLR
+QSetDetachOnError
+QSetSTDOUT
+QSetSTDERR
+QSetSTDIN
+QEnvironment
+QEnvironmentHexEncoded
+A
+qLaunchSuccess
+qProcessInfo
+
+Most of these are documented in the standard gdb-remote protocol
+and/or the lldb-gdb-remote.txt documentation.