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

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