Add a new qGDBServerVersion packet so lldb can query

the name of the remote gdb-protocol server, and get
a version number from it.  This can be useful if lldb
needs to interoperate with a gdb-protocol server with
a known issue or bug.

llvm-svn: 191729

3 files changed, 81 insertions, 10 deletions

diff --git a/lldb/docs/lldb-gdb-remote.txt b/lldb/docs/lldb-gdb-remote.txt
index 8d9dcd4bc9b..6a9fef3a685 100644
--- a/lldb/docs/lldb-gdb-remote.txt
+++ b/lldb/docs/lldb-gdb-remote.txt
@@ -170,12 +170,12 @@ This packet must be sent  _prior_ to sending a "A" packet.
 //  depending on the actual CPU type that is used.
 //----------------------------------------------------------------------
 
-With LLDB, for register information, remote GDB servers can add support for
-the "qRegisterInfoN" packet where "N" is a zero based register number that
-must start at zero and increase by one for each register that is supported.
-The response is done in typical GDB remote fashion where a serious of
-"KEY:VALUE;" pairs are returned. An example for the x86_64 registers is
-included below:
+With LLDB, for register information, remote GDB servers can add
+support for the "qRegisterInfoN" packet where "N" is a zero based
+base16 register number that must start at zero and increase by one
+for each register that is supported.  The response is done in typical
+GDB remote fashion where a serious of "KEY:VALUE;" pairs are returned.
+An example for the x86_64 registers is included below:
 
 send packet: $qRegisterInfo0#00
 read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00
@@ -298,8 +298,14 @@ read packet: $E45#00
 
 As we see above we keep making subsequent calls to the remote server to
 discover all registers by increasing the number appended to qRegisterInfo and
-we get a response back that is a series of "key=value;" strings. The keys and
-values are detailed below:
+we get a response back that is a series of "key=value;" strings. 
+
+The register offsets may end up describing a register context with gaps.  The
+actual register context structure used may have gaps due to alignment issues.
+Implementations of the g/G packet construction/parsing must handle this padding
+if it exists.  
+
+The keys and values are detailed below:
 
 Key         Value
 ==========  ================================================================
@@ -308,10 +314,12 @@ name        The primary register name as a string ("rbp" for example)
 alt-name    An alternate name for a register as a string ("fp" for example for
             the above "rbp")
 
-bitsize     Size in bits of a register (32, 64, etc)
+bitsize     Size in bits of a register (32, 64, etc).  Base 10.
 
 offset      The offset within the "g" and "G" packet of the register data for
-            this register
+            this register.  This is the byte offset once the data has been
+            transformed into binary, not the character offset into the g/G 
+            packet.  Base 10.
 
 encoding    The encoding type of the register which must be one of: 
 
@@ -478,6 +486,53 @@ endian: is one of "little", "big", or "pdp"
 ptrsize: is a number that represents how big pointers are in bytes on the debug target
 
 //----------------------------------------------------------------------
+// "qGDBServerVersion"
+//
+// BRIEF
+//  Get version information about this implementation of the gdb-remote 
+//  protocol.
+//
+// PRIORITY TO IMPLEMENT
+//  High. This packet is usually very easy to implement and can help
+//  LLDB to work around bugs in a server's implementation when they 
+//  are found.
+//----------------------------------------------------------------------
+
+The goal of this packet is to provide enough information about an
+implementation of the gdb-remote-protocol server that lldb can
+work around implementation problems that are discovered after the
+version has been released/deployed.  The name and version number
+should be sufficiently unique that lldb can unambiguously identify
+the origin of the program (for instance, debugserver from lldb) and
+the version/submission number/patch level of the program - whatever
+is appropriate for your server implementation.
+
+The packet follows the key-value pair model, semicolon separated.
+
+send packet: $qGDBServerVersion#00
+read packet: $name:debugserver;version:310.2;#00
+
+Other clients may find other key-value pairs to be useful for identifying
+a gdb stub.  Patch level, release name, build number may all be keys that 
+better describe your implementation's version.  
+Suggested key names:
+
+  name   : the name of your remote server - "debugserver" is the lldb standard
+           implementation
+
+  version : identifies the version number of this server
+
+  patch_level : the patch level of this server
+
+  release_name : the name of this release, if your project uses names
+
+  build_number : if you use a build system with increasing build numbers,
+                 this may be the right key name for your server
+
+  major_version : major version number
+  minor_version : minor version number
+
+//----------------------------------------------------------------------
 // "qProcessInfo"
 //
 // BRIEF
diff --git a/lldb/tools/debugserver/source/RNBRemote.cpp b/lldb/tools/debugserver/source/RNBRemote.cpp
index 2055201d8a0..27d198de264 100644
--- a/lldb/tools/debugserver/source/RNBRemote.cpp
+++ b/lldb/tools/debugserver/source/RNBRemote.cpp
@@ -171,6 +171,7 @@ RNBRemote::CreatePacketTable  ()
     t.push_back (Packet (query_vattachorwait_supported, &RNBRemote::HandlePacket_qVAttachOrWaitSupported,NULL, "qVAttachOrWaitSupported", "Replys with OK if the 'vAttachOrWait' packet is supported."));
     t.push_back (Packet (query_sync_thread_state_supported, &RNBRemote::HandlePacket_qSyncThreadStateSupported,NULL, "qSyncThreadStateSupported", "Replys with OK if the 'QSyncThreadState:' packet is supported."));
     t.push_back (Packet (query_host_info,               &RNBRemote::HandlePacket_qHostInfo,     NULL, "qHostInfo", "Replies with multiple 'key:value;' tuples appended to each other."));
+    t.push_back (Packet (query_gdb_server_version,      &RNBRemote::HandlePacket_qGDBServerVersion,       NULL, "qGDBServerVersion", "Replies with multiple 'key:value;' tuples appended to each other."));
     t.push_back (Packet (query_process_info,            &RNBRemote::HandlePacket_qProcessInfo,     NULL, "qProcessInfo", "Replies with multiple 'key:value;' tuples appended to each other."));
 //  t.push_back (Packet (query_symbol_lookup,           &RNBRemote::HandlePacket_UNIMPLEMENTED, NULL, "qSymbol", "Notify that host debugger is ready to do symbol lookups"));
     t.push_back (Packet (start_noack_mode,              &RNBRemote::HandlePacket_QStartNoAckMode        , NULL, "QStartNoAckMode", "Request that " DEBUGSERVER_PROGRAM_NAME " stop acking remote protocol packets"));
@@ -3964,6 +3965,19 @@ RNBRemote::HandlePacket_qHostInfo (const char *p)
     return SendPacket (strm.str());
 }
 
+rnb_err_t
+RNBRemote::HandlePacket_qGDBServerVersion (const char *p)
+{
+    std::ostringstream strm;
+    
+    if (DEBUGSERVER_PROGRAM_NAME)
+        strm << "name:" DEBUGSERVER_PROGRAM_NAME ";";
+    else
+        strm << "name:debugserver;";
+    strm << "version:" << DEBUGSERVER_VERSION_NUM << ";";
+
+    return SendPacket (strm.str());
+}
 
 // Note that all numeric values returned by qProcessInfo are hex encoded,
 // including the pid and the cpu type.
diff --git a/lldb/tools/debugserver/source/RNBRemote.h b/lldb/tools/debugserver/source/RNBRemote.h
index 15d725ce4cd..7008e71de9f 100644
--- a/lldb/tools/debugserver/source/RNBRemote.h
+++ b/lldb/tools/debugserver/source/RNBRemote.h
@@ -95,6 +95,7 @@ public:
         query_vattachorwait_supported,  // 'qVAttachOrWaitSupported'
         query_sync_thread_state_supported,// 'QSyncThreadState'
         query_host_info,                // 'qHostInfo'
+        query_gdb_server_version,       // 'qGDBServerVersion'
         query_process_info,             // 'qProcessInfo'
         pass_signals_to_inferior,       // 'QPassSignals'
         start_noack_mode,               // 'QStartNoAckMode'
@@ -178,6 +179,7 @@ public:
     rnb_err_t HandlePacket_qThreadExtraInfo (const char *p);
     rnb_err_t HandlePacket_qThreadStopInfo (const char *p);
     rnb_err_t HandlePacket_qHostInfo (const char *p);
+    rnb_err_t HandlePacket_qGDBServerVersion (const char *p);
     rnb_err_t HandlePacket_qProcessInfo (const char *p);
     rnb_err_t HandlePacket_QStartNoAckMode (const char *p);
     rnb_err_t HandlePacket_QThreadSuffixSupported (const char *p);