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 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.  
//
//  KEY           VALUE     DESCRIPTION
//  ===========   ========  ================================================
//  "name"        ascii-hex An ASCII hex string that contains the name of 
//                          the process that will be matched.
//  "name_match"  enum      One of: "equals", "starts_with", "ends_with", 
//                          "contains" or "regex"
//  "pid"         integer   A string value containing the decimal process ID
//  "parent_pid"  integer   A string value containing the decimal parent 
//                          process ID
//  "uid"         integer   A string value containing the decimal user ID
//  "gid"         integer   A string value containing the decimal group ID
//  "euid"        integer   A string value containing the decimal effective user ID
//  "egid"        integer   A string value containing the decimal effective group ID
//  "all_users"   bool      A boolean value that specifies if processes should
//                          be listed for all users, not just the user that the 
//                          platform is running as
//  "triple"      ascii-hex An ASCII hex target triple string ("x86_64", 
//                          "x86_64-apple-macosx", "armv7-apple-ios")
//
//  If no criteria is given, qfProcessInfo will request a list of every process.
//
//  The lldb testsuite currently only uses name_match:equals and the
//  no-criteria mode to list every process.
//
//  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.
//
//  Sample packet/response:
//  send packet: $qfProcessInfo#00
//  read packet: $pid:60001;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:7838365f36342d6170706c652d6d61636f7378;#00
//  send packet: $qsProcessInfo#00
//  read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:7838365f36342d6170706c652d6d61636f7378;#00
//  send packet: $qsProcessInfo#00
//  read packet: $E04#00

//----------------------------------------------------------------------
// 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.

//----------------------------------------------------------------------
// qPathComplete
//
// BRIEF
//   Get a list of matched disk files/directories by passing a boolean flag
//   and a partial path.
//
// EXAMPLE
//
//   receive: qPathComplete:0,6d61696e
//   send:    M6d61696e2e637070
//   receive: qPathComplete:1,746573
//   send:    M746573742f,74657374732f
//
//   If the first argument is zero, the result should contain all
//   files (including directories) starting with the given path. If the
//   argument is one, the result should contain only directories.
//
//   The result should be a comma-separated list of hex-encoded paths.
//   Paths denoting a directory should end with a directory separator ('/' or '\').

//----------------------------------------------------------------------
// 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.
//
//  COMPATIBILITY
//    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.
//
//  COMPATIBILITY
//    The gdb-remote serial protocol documentation says that numbers
//    in "vFile:" packets should be hexadecimal. Instead lldb uses
//    decimal.


//----------------------------------------------------------------------
// 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)
//
//  COMPATIBILITY
//    The gdb-remote serial protocol documentation says that numbers
//    in "vFile:" packets should be hexadecimal. Instead lldb uses
//    decimal.





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.
