contrib/llvm/tools/lldb/include/lldb/API/SBTrace.h

   1 //===-- SBTrace.h -----------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLDB_SBTrace_h_
  11 #define LLDB_SBTrace_h_
  12
  13 #include "lldb/API/SBDefines.h"
  14 #include "lldb/API/SBError.h"
  15
  16 class TraceImpl;
  17
  18 namespace lldb {
  19
  20 class LLDB_API SBTrace {
  21 public:
  22   SBTrace();
  23   //------------------------------------------------------------------
  24   /// Obtain the trace data as raw bytes.
  25   ///
  26   /// @param[out] error
  27   ///     An error explaining what went wrong.
  28   ///
  29   /// @param[in] buf
  30   ///     Buffer to write the trace data to.
  31   ///
  32   /// @param[in] size
  33   ///     The size of the buffer used to read the data. This is
  34   ///     also the size of the data intended to read. It is also
  35   ///     possible to partially read the trace data for some trace
  36   ///     technologies by specifying a smaller buffer.
  37   ///
  38   /// @param[in] offset
  39   ///     The start offset to begin reading the trace data.
  40   ///
  41   /// @param[in] thread_id
  42   ///     Tracing could be started for the complete process or a
  43   ///     single thread, in the first case the uid obtained would
  44   ///     map to all the threads existing within the process and the
  45   ///     ones spawning later. The thread_id parameter can be used in
  46   ///     such a scenario to select the trace data for a specific
  47   ///     thread.
  48   ///
  49   /// @return
  50   ///     The size of the trace data effectively read by the API call.
  51   //------------------------------------------------------------------
  52   size_t GetTraceData(SBError &error, void *buf, size_t size, size_t offset = 0,
  53                       lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
  54
  55   //------------------------------------------------------------------
  56   /// Obtain any meta data as raw bytes for the tracing instance.
  57   /// The input parameter definition is similar to the previous
  58   /// function.
  59   //------------------------------------------------------------------
  60   size_t GetMetaData(SBError &error, void *buf, size_t size, size_t offset = 0,
  61                      lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
  62
  63   //------------------------------------------------------------------
  64   /// Stop the tracing instance. Stopping the trace will also
  65   /// lead to deletion of any gathered trace data.
  66   ///
  67   /// @param[out] error
  68   ///     An error explaining what went wrong.
  69   ///
  70   /// @param[in] thread_id
  71   ///     The user id could map to a tracing instance for a thread
  72   ///     or could also map to a group of threads being traced with
  73   ///     the same trace options. A thread_id is normally optional
  74   ///     except in the case of tracing a complete process and tracing
  75   ///     needs to switched off on a particular thread.
  76   ///     A situation could occur where initially a thread (lets say
  77   ///     thread A) is being individually traced with a particular uid
  78   ///     and then tracing is started on the complete process, in this
  79   ///     case thread A will continue without any change. All newly
  80   ///     spawned threads would be traced with the uid of the process.
  81   ///     Now if the StopTrace API is called for the whole process,
  82   ///     thread A will not be stopped and must be stopped separately.
  83   //------------------------------------------------------------------
  84   void StopTrace(SBError &error,
  85                  lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
  86
  87   //------------------------------------------------------------------
  88   /// Get the trace configuration being used for the trace instance.
  89   /// The threadid in the SBTraceOptions needs to be set when the
  90   /// configuration used by a specific thread is being requested.
  91   ///
  92   /// @param[out] options
  93   ///     The trace options actually used by the trace instance
  94   ///     would be filled by the API.
  95   ///
  96   /// @param[out] error
  97   ///     An error explaining what went wrong.
  98   //------------------------------------------------------------------
  99   void GetTraceConfig(SBTraceOptions &options, SBError &error);
 100
 101   lldb::user_id_t GetTraceUID();
 102
 103   bool IsValid();
 104
 105 protected:
 106   typedef std::shared_ptr<TraceImpl> TraceImplSP;
 107
 108   friend class SBProcess;
 109
 110   void SetTraceUID(lldb::user_id_t uid);
 111
 112   TraceImplSP m_trace_impl_sp;
 113
 114   lldb::ProcessSP GetSP() const;
 115
 116   void SetSP(const ProcessSP &process_sp);
 117
 118   lldb::ProcessWP m_opaque_wp;
 119 };
 120 } // namespace lldb
 121
 122 #endif // LLDB_SBTrace_h_