Implementation of remote packets for Trace data.

Summary:
The changes consist of new packets for trace manipulation and
trace collection. The new packets are also documented. The packets
are capable of providing custom trace specific parameters to start
tracing and also retrieve such configuration from the server.

Reviewers: clayborg, lldb-commits, tberghammer, labath, zturner

Reviewed By: clayborg, labath

Subscribers: krytarowski, lldb-commits

Differential Revision: https://reviews.llvm.org/D32585

git-svn-id: https://llvm.org/svn/llvm-project/lldb/trunk@303972 91177308-0d34-0410-b5e6-96231b3b80d8

Author: ravithejaintel

docs/lldb-gdb-remote.txt

@@ -208,6 +208,163 @@ This packet must be sent  _prior_ to sending a "A" packet.
 send packet: QListThreadsInStopReply
 read packet: OK
 
+//----------------------------------------------------------------------
+// jTraceStart:
+//
+// BRIEF
+//  Packet for starting trace of type lldb::TraceType. The following
+//  parameters should be appended to the packet formatted as a JSON
+//  dictionary, where the schematic for the JSON dictionary in terms of
+//  the recognized Keys is given below in the table.
+//  Different tracing types could require different custom parameters.
+//  Such custom tracing parameters if needed should be collectively
+//  specified in a JSON dictionary and the dictionary can be appended
+//  to this packet (as Value corresponding to "params"). Since sending
+//  JSON data over gdb-remote protocol has certain limitations, binary
+//  escaping convention should be used.
+//
+//  Following is the list of parameters -
+//
+//  Key             Value (Integer)                         (O)Optional/
+//                  (except params which should be a        (M)Mandatory
+//                  JSON dictionary)
+//  ==========      ====================================================
+//
+//  type            The type of trace to start (see          M
+//                  lldb-enumerations for TraceType)
+//
+//  buffersize      The size of the buffer to allocate       M
+//                  for trace gathering.
+//
+//  threadid        The id of the thread to start tracing    O
+//                  on.
+//
+//  metabuffersize  The size of buffer to hold meta data     O
+//                  used for decoding the trace data.
+//
+//  params          Any parameters that are specific to      O
+//                  certain trace technologies should be
+//                  collectively specified as a JSON
+//                  dictionary
+//  ==========      ====================================================
+//
+//  Each tracing instance is identified by a trace id which is returned
+//  as the reply to this packet. In case the tracing failed to begin an
+//  error code is returned instead.
+//----------------------------------------------------------------------
+
+send packet: jTraceStart:{"type":<type>,"buffersize":<buffersize>}]
+read packet: <trace id>/E<error code>
+
+//----------------------------------------------------------------------
+// jTraceStop:
+//
+// BRIEF
+//  Stop tracing instance with trace id <trace id>, of course trace
+//  needs to be started before. The following parameters should be
+//  formatted as a JSON dictionary to the packet. Since sending
+//  JSON data over gdb-remote protocol has certain limitations, binary
+//  escaping convention should be used.
+//
+//  Following is the list of parameters -
+//
+//  Key             Value (Integer)                         (O)Optional/
+//                                                          (M)Mandatory
+//  ==========      ====================================================
+//
+//  traceid         The trace id of the tracing instance    M
+//
+//  threadid        The id of the thread to stop tracing    O
+//                  on. Since <trace id> could map to
+//                  multiple trace instances (in case it
+//                  maps to the complete process), the
+//                  threadid of a particular thread could
+//                  be appended as "threadid:<thread id>;"
+//                  to stop tracing on that thread.
+//  ==========      ====================================================
+//
+//  An OK response is sent in case of success else an error code is
+//  returned.
+//----------------------------------------------------------------------
+
+send packet: jTraceStop:{"traceid":<trace id>}]
+read packet: <OK response>/E<error code>
+
+//----------------------------------------------------------------------
+// jTraceBufferRead:
+//
+// BRIEF
+//  Packet for reading the trace for tracing instance <trace id>, i.e the
+//  id obtained from StartTrace API. The following parameters should be
+//  formatted as a JSON dictionary to the packet. Since sending
+//  JSON data over gdb-remote protocol has certain limitations, binary
+//  escaping convention should be used.
+//
+//  Following is the list of parameters -
+//
+//  Key             Value (Integer)                         (O)Optional/
+//                                                          (M)Mandatory
+//  ==========      ====================================================
+//  traceid         The trace id of the tracing instance    M
+//
+//  offset          The offset to start reading the data    M
+//                  from.
+//
+//  buffersize      The size of the data intended to read.  M
+//
+//  threadid        The id of the thread to retrieve data   O
+//                  from.
+//  ==========      ====================================================
+//
+//  The trace data is sent as raw binary data if the read was successful
+//  else an error code is sent.
+//----------------------------------------------------------------------
+
+send packet: jTraceBufferRead:{"traceid":<trace id>,"offset":<byteoffset>,"buffersize":<byte_count>}]
+read packet: <binary trace data>/E<error code>
+
+//----------------------------------------------------------------------
+// jTraceMetaRead:
+//
+// BRIEF
+//  Similar Packet as above except it reads meta data.
+//----------------------------------------------------------------------
+
+/----------------------------------------------------------------------
+// jTraceConfigRead:
+//
+// BRIEF
+//  Request the trace configuration for the tracing instance with id
+//  <trace id>.
+//
+//  Following is the list of parameters -
+//
+//  Key             Value (Integer)                         (O)Optional/
+//                                                          (M)Mandatory
+//  ==========      ====================================================
+//  traceid         The trace id of the tracing instance    M
+//
+//  threadid        The id of the thread to obtain trace    O
+//                  configuration from. Since <trace id>
+//                  could map to multiple trace instances
+//                  (in case it maps to the complete
+//                  process), the threadid of a particular
+//                  thread could be appended as
+//                  "threadid:<thread id>;" to obtain the
+//                  trace configuration of that thread.
+//  ==========      ====================================================
+//
+//  In the response packet the trace configuration is sent as text,
+//  formatted as a JSON dictionary. Since sending JSON data over
+//  gdb-remote protocol has certain limitations, binary escaping
+//  convention is used.
+//  In case the trace instance with the <trace id> was not found, an
+//  error code is returned.
+//----------------------------------------------------------------------
+
+send packet: jTraceConfigRead:{"traceid":<trace id>}
+read packet: {"conf1":<conf1>,"conf2":<conf2>,"params":{"paramName":paramValue}]}];/E<error code>
+
 //----------------------------------------------------------------------
 // "qRegisterInfo<hex-reg-id>"
 //

include/lldb/API/SBTrace.h

@@ -40,7 +40,7 @@ class LLDB_API SBTrace {
   ///
   /// @param[in] thread_id
   ///     Tracing could be started for the complete process or a
-  ///     single thread, in the first case the uid obtained would
+  ///     single thread, in the first case the traceid obtained would
   ///     map to all the threads existing within the process and the
   ///     ones spawning later. The thread_id parameter can be used in
   ///     such a scenario to select the trace data for a specific
@@ -68,16 +68,17 @@ class LLDB_API SBTrace {
   ///     An error explaining what went wrong.
   ///
   /// @param[in] thread_id
-  ///     The user id could map to a tracing instance for a thread
+  ///     The trace id could map to a tracing instance for a thread
   ///     or could also map to a group of threads being traced with
   ///     the same trace options. A thread_id is normally optional
   ///     except in the case of tracing a complete process and tracing
   ///     needs to switched off on a particular thread.
   ///     A situation could occur where initially a thread (lets say
-  ///     thread A) is being individually traced with a particular uid
-  ///     and then tracing is started on the complete process, in this
-  ///     case thread A will continue without any change. All newly
-  ///     spawned threads would be traced with the uid of the process.
+  ///     thread A) is being individually traced with a particular
+  ///     trace id and then tracing is started on the complete
+  ///     process, in this case thread A will continue without any
+  ///     change. All newly spawned threads would be traced with the
+  ///     trace id of the process.
   ///     Now if the StopTrace API is called for the whole process,
   ///     thread A will not be stopped and must be stopped separately.
   //------------------------------------------------------------------

include/lldb/Core/TraceOptions.h

@@ -18,8 +18,7 @@
 namespace lldb_private {
 class TraceOptions {
 public:
-  TraceOptions()
-      : m_trace_params(new StructuredData::Dictionary()) {}
+  TraceOptions() : m_trace_params(new StructuredData::Dictionary()) {}
 
   const StructuredData::DictionarySP &getTraceParams() const {
     return m_trace_params;
@@ -43,7 +42,7 @@ class TraceOptions {
 
   void setThreadID(lldb::tid_t thread_id) { m_thread_id = thread_id; }
 
-  lldb::tid_t getThreadID() { return m_thread_id; }
+  lldb::tid_t getThreadID() const { return m_thread_id; }
 
 private:
   lldb::TraceType m_type;

include/lldb/Host/common/NativeProcessProtocol.h

@@ -10,6 +10,7 @@
 #ifndef liblldb_NativeProcessProtocol_h_
 #define liblldb_NativeProcessProtocol_h_
 
+#include "lldb/Core/TraceOptions.h"
 #include "lldb/Host/MainLoop.h"
 #include "lldb/Utility/Status.h"
 #include "lldb/lldb-private-forward.h"
@@ -308,6 +309,108 @@ class NativeProcessProtocol
   static Status Attach(lldb::pid_t pid, NativeDelegate &native_delegate,
                        MainLoop &mainloop, NativeProcessProtocolSP &process_sp);
 
+  //------------------------------------------------------------------
+  /// StartTracing API for starting a tracing instance with the
+  /// TraceOptions on a specific thread or process.
+  ///
+  /// @param[in] config
+  ///     The configuration to use when starting tracing.
+  ///
+  /// @param[out] error
+  ///     Status indicates what went wrong.
+  ///
+  /// @return
+  ///     The API returns a user_id which can be used to get trace
+  ///     data, trace configuration or stopping the trace instance.
+  ///     The user_id is a key to identify and operate with a tracing
+  ///     instance. It may refer to the complete process or a single
+  ///     thread.
+  //------------------------------------------------------------------
+  virtual lldb::user_id_t StartTrace(const TraceOptions &config,
+                                     Status &error) {
+    error.SetErrorString("Not implemented");
+    return LLDB_INVALID_UID;
+  }
+
+  //------------------------------------------------------------------
+  /// StopTracing API as the name suggests stops a tracing instance.
+  ///
+  /// @param[in] uid
+  ///     The user id of the trace intended to be stopped. Now a
+  ///     user_id may map to multiple threads in which case this API
+  ///     could be used to stop the tracing for a specific thread by
+  ///     supplying its thread id.
+  ///
+  /// @param[in] thread
+  ///     Thread is needed when the complete process is being traced
+  ///     and the user wishes to stop tracing on a particular thread.
+  ///
+  /// @return
+  ///     Status indicating what went wrong.
+  //------------------------------------------------------------------
+  virtual Status StopTrace(lldb::user_id_t uid,
+                           lldb::tid_t thread = LLDB_INVALID_THREAD_ID) {
+    return Status("Not implemented");
+  }
+
+  //------------------------------------------------------------------
+  /// This API provides the trace data collected in the form of raw
+  /// data.
+  ///
+  /// @param[in] uid thread
+  ///     The uid and thread provide the context for the trace
+  ///     instance.
+  ///
+  /// @param[in] buffer
+  ///     The buffer provides the destination buffer where the trace
+  ///     data would be read to. The buffer should be truncated to the
+  ///     filled length by this function.
+  ///
+  /// @param[in] offset
+  ///     There is possibility to read partially the trace data from
+  ///     a specified offset where in such cases the buffer provided
+  ///     may be smaller than the internal trace collection container.
+  ///
+  /// @return
+  ///     The size of the data actually read.
+  //------------------------------------------------------------------
+  virtual Status GetData(lldb::user_id_t uid, lldb::tid_t thread,
+                         llvm::MutableArrayRef<uint8_t> &buffer,
+                         size_t offset = 0) {
+    return Status("Not implemented");
+  }
+
+  //------------------------------------------------------------------
+  /// Similar API as above except it aims to provide any extra data
+  /// useful for decoding the actual trace data.
+  //------------------------------------------------------------------
+  virtual Status GetMetaData(lldb::user_id_t uid, lldb::tid_t thread,
+                             llvm::MutableArrayRef<uint8_t> &buffer,
+                             size_t offset = 0) {
+    return Status("Not implemented");
+  }
+
+  //------------------------------------------------------------------
+  /// API to query the TraceOptions for a given user id
+  ///
+  /// @param[in] uid
+  ///     The user id of the tracing instance.
+  ///
+  /// @param[in] config
+  ///     The thread id of the tracing instance, in case configuration
+  ///     for a specific thread is needed should be specified in the
+  ///     config.
+  ///
+  /// @param[out] error
+  ///     Status indicates what went wrong.
+  ///
+  /// @param[out] config
+  ///     The actual configuration being used for tracing.
+  //------------------------------------------------------------------
+  virtual Status GetTraceConfig(lldb::user_id_t uid, TraceOptions &config) {
+    return Status("Not implemented");
+  }
+
 protected:
   lldb::pid_t m_pid;
 
@@ -381,6 +484,6 @@ class NativeProcessProtocol
 private:
   void SynchronouslyNotifyProcessStateChanged(lldb::StateType state);
 };
-}
+} // namespace lldb_private
 
 #endif // #ifndef liblldb_NativeProcessProtocol_h_