SBTrace.h revision 355940 
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
15class TraceImpl;
16
17namespace lldb {
18
19class LLDB_API SBTrace {
20public:
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
99protected:
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_
117