LLDB mainline
TraceIntelPT.h
Go to the documentation of this file.
1//===-- TraceIntelPT.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_SOURCE_PLUGINS_TRACE_INTEL_PT_TRACEINTELPT_H
10#define LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_TRACEINTELPT_H
11
12#include "TaskTimer.h"
13#include "ThreadDecoder.h"
17#include "lldb/lldb-types.h"
18#include "llvm/Support/raw_ostream.h"
19#include <optional>
20
21namespace lldb_private {
22namespace trace_intel_pt {
23
24class TraceIntelPT : public Trace {
25public:
26 /// Properties to be used with the `settings` command.
28 public:
29 static llvm::StringRef GetSettingName();
30
32
33 ~PluginProperties() override = default;
34
36
38 };
39
40 /// Return the global properties for this trace plug-in.
42
43 void Dump(Stream *s) const override;
44
45 llvm::Expected<FileSpec> SaveToDisk(FileSpec directory,
46 bool compact) override;
47
48 ~TraceIntelPT() override = default;
49
50 /// PluginInterface protocol
51 /// \{
52 llvm::StringRef GetPluginName() override { return GetPluginNameStatic(); }
53
54 static void Initialize();
55
56 static void Terminate();
57
58 /// Create an instance of this class from a trace bundle.
59 ///
60 /// \param[in] trace_bundle_description
61 /// The description of the trace bundle. See \a Trace::FindPlugin.
62 ///
63 /// \param[in] bundle_dir
64 /// The path to the directory that contains the trace bundle.
65 ///
66 /// \param[in] debugger
67 /// The debugger instance where new Targets will be created as part of the
68 /// JSON data parsing.
69 ///
70 /// \return
71 /// A trace instance or an error in case of failures.
72 static llvm::Expected<lldb::TraceSP> CreateInstanceForTraceBundle(
73 const llvm::json::Value &trace_bundle_description,
74 llvm::StringRef bundle_dir, Debugger &debugger);
75
76 static llvm::Expected<lldb::TraceSP>
78
79 static llvm::StringRef GetPluginNameStatic() { return "intel-pt"; }
80
81 static void DebuggerInitialize(Debugger &debugger);
82 /// \}
83
86
89
90 llvm::StringRef GetSchema() override;
91
92 llvm::Expected<lldb::TraceCursorSP> CreateNewCursor(Thread &thread) override;
93
94 void DumpTraceInfo(Thread &thread, Stream &s, bool verbose,
95 bool json) override;
96
97 llvm::Expected<std::optional<uint64_t>> GetRawTraceSize(Thread &thread);
98
100 llvm::StringRef json_response) override;
101
102 bool IsTraced(lldb::tid_t tid) override;
103
104 const char *GetStartConfigurationHelp() override;
105
106 /// Start tracing a live process.
107 ///
108 /// More information on the parameters below can be found in the
109 /// jLLDBTraceStart section in lldb/docs/lldb-gdb-remote.txt.
110 ///
111 /// \param[in] ipt_trace_size
112 /// Trace size per thread in bytes.
113 ///
114 /// \param[in] total_buffer_size_limit
115 /// Maximum total trace size per process in bytes.
116 ///
117 /// \param[in] enable_tsc
118 /// Whether to use enable TSC timestamps or not.
119 ///
120 /// \param[in] psb_period
121 /// This value defines the period in which PSB packets will be generated.
122 ///
123 /// \param[in] per_cpu_tracing
124 /// This value defines whether to have an intel pt trace buffer per thread
125 /// or per cpu core.
126 ///
127 /// \param[in] disable_cgroup_filtering
128 /// Disable the cgroup filtering that is automatically applied when doing
129 /// per cpu tracing.
130 ///
131 /// \return
132 /// \a llvm::Error::success if the operation was successful, or
133 /// \a llvm::Error otherwise.
134 llvm::Error Start(uint64_t ipt_trace_size, uint64_t total_buffer_size_limit,
135 bool enable_tsc, std::optional<uint64_t> psb_period,
136 bool m_per_cpu_tracing, bool disable_cgroup_filtering);
137
138 /// \copydoc Trace::Start
139 llvm::Error Start(StructuredData::ObjectSP configuration =
140 StructuredData::ObjectSP()) override;
141
142 /// Start tracing live threads.
143 ///
144 /// More information on the parameters below can be found in the
145 /// jLLDBTraceStart section in lldb/docs/lldb-gdb-remote.txt.
146 ///
147 /// \param[in] tids
148 /// Threads to trace.
149 ///
150 /// \param[in] ipt_trace_size
151 /// Trace size per thread or per cpu core in bytes.
152 ///
153 /// \param[in] enable_tsc
154 /// Whether to use enable TSC timestamps or not.
155 ///
156 /// \param[in] psb_period
157 /// This value defines the period in which PSB packets will be generated.
158 ///
159 /// \return
160 /// \a llvm::Error::success if the operation was successful, or
161 /// \a llvm::Error otherwise.
162 llvm::Error Start(llvm::ArrayRef<lldb::tid_t> tids, uint64_t ipt_trace_size,
163 bool enable_tsc, std::optional<uint64_t> psb_period);
164
165 /// \copydoc Trace::Start
166 llvm::Error Start(llvm::ArrayRef<lldb::tid_t> tids,
167 StructuredData::ObjectSP configuration =
168 StructuredData::ObjectSP()) override;
169
170 /// See \a Trace::OnThreadBinaryDataRead().
171 llvm::Error OnThreadBufferRead(lldb::tid_t tid,
172 OnBinaryDataReadCallback callback);
173
174 /// Get or fetch the cpu information from, for example, /proc/cpuinfo.
175 llvm::Expected<pt_cpu> GetCPUInfo();
176
177 /// Get or fetch the values used to convert to and from TSCs and nanos.
178 std::optional<LinuxPerfZeroTscConversion> GetPerfZeroTscConversion();
179
180 /// \return
181 /// The timer object for this trace.
183
184 /// \return
185 /// The ScopedTaskTimer object for the given thread in this trace.
187
188 /// \return
189 /// The global copedTaskTimer object for this trace.
191
193
195
197
198private:
200
201 llvm::Expected<pt_cpu> GetCPUInfoForLiveProcess();
202
203 /// Postmortem trace constructor
204 ///
205 /// \param[in] bundle_description
206 /// The definition file for the postmortem bundle.
207 ///
208 /// \param[in] traced_processes
209 /// The processes traced in the postmortem session.
210 ///
211 /// \param[in] trace_threads
212 /// The threads traced in the postmortem session. They must belong to the
213 /// processes mentioned above.
214 ///
215 /// \param[in] trace_mode
216 /// The tracing mode of the postmortem session.
217 ///
218 /// \return
219 /// A TraceIntelPT shared pointer instance.
220 /// \{
222 JSONTraceBundleDescription &bundle_description,
223 llvm::ArrayRef<lldb::ProcessSP> traced_processes,
224 llvm::ArrayRef<lldb::ThreadPostMortemTraceSP> traced_threads,
226
227 /// This constructor is used by CreateInstanceForPostmortemTrace to get the
228 /// instance ready before using shared pointers, which is a limitation of C++.
230 llvm::ArrayRef<lldb::ProcessSP> traced_processes,
232 /// \}
233
234 /// Constructor for live processes
235 TraceIntelPT(Process &live_process)
236 : Trace(live_process), trace_mode(TraceMode::UserMode){};
237
238 /// Decode the trace of the given thread that, i.e. recontruct the traced
239 /// instructions.
240 ///
241 /// \param[in] thread
242 /// If \a thread is a \a ThreadTrace, then its internal trace file will be
243 /// decoded. Live threads are not currently supported.
244 ///
245 /// \return
246 /// A \a DecodedThread shared pointer with the decoded instructions. Any
247 /// errors are embedded in the instruction list. An \a llvm::Error is
248 /// returned if the decoder couldn't be properly set up.
249 llvm::Expected<DecodedThreadSP> Decode(Thread &thread);
250
251 /// \return
252 /// The lowest timestamp in nanoseconds in all traces if available, \a
253 /// std::nullopt if all the traces were empty or no trace contained no
254 /// timing information, or an \a llvm::Error if it was not possible to set
255 /// up the decoder for some trace.
256 llvm::Expected<std::optional<uint64_t>> FindBeginningOfTimeNanos();
257
258 // Dump out trace info in JSON format
259 void DumpTraceInfoAsJson(Thread &thread, Stream &s, bool verbose);
260
261 /// We package all the data that can change upon process stops to make sure
262 /// this contract is very visible.
263 /// This variable should only be accessed directly by constructores or live
264 /// process data refreshers.
265 struct Storage {
266 std::optional<TraceIntelPTMultiCpuDecoder> multicpu_decoder;
267 /// These decoders are used for the non-per-cpu case
268 llvm::DenseMap<lldb::tid_t, std::unique_ptr<ThreadDecoder>> thread_decoders;
269 /// Helper variable used to track long running operations for telemetry.
271 /// It is provided by either a trace bundle or a live process to convert TSC
272 /// counters to and from nanos. It might not be available on all hosts.
273 std::optional<LinuxPerfZeroTscConversion> tsc_conversion;
274 std::optional<uint64_t> beginning_of_time_nanos;
277
278 /// It is provided by either a trace bundle or a live process' "cpuInfo"
279 /// binary data. We don't put it in the Storage because this variable doesn't
280 /// change.
281 std::optional<pt_cpu> m_cpu_info;
282
283 /// Get the storage after refreshing the data in the case of a live process.
285
286 /// The tracing mode of post mortem trace.
288};
289
290} // namespace trace_intel_pt
291} // namespace lldb_private
292
293#endif // LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_TRACEINTELPT_H
A class to manage flag bits.
Definition: Debugger.h:80
A file utility class.
Definition: FileSpec.h:56
A plug-in interface definition class for debugging a process.
Definition: Process.h:341
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
std::shared_ptr< Object > ObjectSP
A plug-in interface definition class for trace information.
Definition: Trace.h:48
std::function< llvm::Error(llvm::ArrayRef< uint8_t > data)> OnBinaryDataReadCallback
Definition: Trace.h:261
Class used to track the duration of long running tasks related to a single scope for reporting.
Definition: TaskTimer.h:24
Class used to track the duration of long running tasks for reporting.
Definition: TaskTimer.h:60
Properties to be used with the settings command.
Definition: TraceIntelPT.h:27
static TraceIntelPTSP CreateInstanceForPostmortemTrace(JSONTraceBundleDescription &bundle_description, llvm::ArrayRef< lldb::ProcessSP > traced_processes, llvm::ArrayRef< lldb::ThreadPostMortemTraceSP > traced_threads, TraceMode trace_mode)
Postmortem trace constructor.
TraceIntelPT(Process &live_process)
Constructor for live processes.
Definition: TraceIntelPT.h:235
void DumpTraceInfo(Thread &thread, Stream &s, bool verbose, bool json) override
Dump general info about a given thread's trace.
llvm::StringRef GetSchema() override
llvm::Error DoRefreshLiveProcessState(TraceGetStateResponse state, llvm::StringRef json_response) override
Method to be overriden by the plug-in to refresh its own state.
static llvm::Expected< lldb::TraceSP > CreateInstanceForTraceBundle(const llvm::json::Value &trace_bundle_description, llvm::StringRef bundle_dir, Debugger &debugger)
Create an instance of this class from a trace bundle.
static void DebuggerInitialize(Debugger &debugger)
llvm::Error OnThreadBufferRead(lldb::tid_t tid, OnBinaryDataReadCallback callback)
See Trace::OnThreadBinaryDataRead().
void Dump(Stream *s) const override
Dump the trace data that this plug-in has access to.
static llvm::Expected< lldb::TraceSP > CreateInstanceForLiveProcess(Process &process)
std::optional< pt_cpu > m_cpu_info
It is provided by either a trace bundle or a live process' "cpuInfo" binary data.
Definition: TraceIntelPT.h:281
TraceMode trace_mode
The tracing mode of post mortem trace.
Definition: TraceIntelPT.h:287
struct lldb_private::trace_intel_pt::TraceIntelPT::Storage m_storage
Storage & GetUpdatedStorage()
Get the storage after refreshing the data in the case of a live process.
llvm::Expected< lldb::TraceCursorSP > CreateNewCursor(Thread &thread) override
Get a TraceCursor for the given thread's trace.
const char * GetStartConfigurationHelp() override
void DumpTraceInfoAsJson(Thread &thread, Stream &s, bool verbose)
llvm::Expected< pt_cpu > GetCPUInfoForLiveProcess()
llvm::Error Start(uint64_t ipt_trace_size, uint64_t total_buffer_size_limit, bool enable_tsc, std::optional< uint64_t > psb_period, bool m_per_cpu_tracing, bool disable_cgroup_filtering)
Start tracing a live process.
static llvm::StringRef GetPluginNameStatic()
Definition: TraceIntelPT.h:79
static PluginProperties & GetGlobalProperties()
Return the global properties for this trace plug-in.
lldb::CommandObjectSP GetThreadTraceStartCommand(CommandInterpreter &interpreter) override
Get the command handle for the "thread trace start" command.
llvm::Expected< DecodedThreadSP > Decode(Thread &thread)
Decode the trace of the given thread that, i.e.
llvm::Expected< std::optional< uint64_t > > GetRawTraceSize(Thread &thread)
ScopedTaskTimer & GetThreadTimer(lldb::tid_t tid)
lldb::CommandObjectSP GetProcessTraceStartCommand(CommandInterpreter &interpreter) override
Get the command handle for the "process trace start" command.
llvm::Expected< pt_cpu > GetCPUInfo()
Get or fetch the cpu information from, for example, /proc/cpuinfo.
llvm::StringRef GetPluginName() override
PluginInterface protocol.
Definition: TraceIntelPT.h:52
llvm::Expected< std::optional< uint64_t > > FindBeginningOfTimeNanos()
std::optional< LinuxPerfZeroTscConversion > GetPerfZeroTscConversion()
Get or fetch the values used to convert to and from TSCs and nanos.
bool IsTraced(lldb::tid_t tid) override
Check if a thread is currently traced by this object.
TraceIntelPT(JSONTraceBundleDescription &bundle_description, llvm::ArrayRef< lldb::ProcessSP > traced_processes, TraceMode trace_mode)
This constructor is used by CreateInstanceForPostmortemTrace to get the instance ready before using s...
llvm::Expected< FileSpec > SaveToDisk(FileSpec directory, bool compact) override
Save the trace to the specified directory, which will be created if needed.
std::shared_ptr< TraceIntelPT > TraceIntelPTSP
A class that represents a running process on the host machine.
std::shared_ptr< lldb_private::CommandObject > CommandObjectSP
Definition: lldb-forward.h:329
uint64_t tid_t
Definition: lldb-types.h:84
We package all the data that can change upon process stops to make sure this contract is very visible...
Definition: TraceIntelPT.h:265
std::optional< LinuxPerfZeroTscConversion > tsc_conversion
It is provided by either a trace bundle or a live process to convert TSC counters to and from nanos.
Definition: TraceIntelPT.h:273
std::optional< TraceIntelPTMultiCpuDecoder > multicpu_decoder
Definition: TraceIntelPT.h:266
llvm::DenseMap< lldb::tid_t, std::unique_ptr< ThreadDecoder > > thread_decoders
These decoders are used for the non-per-cpu case.
Definition: TraceIntelPT.h:268
TaskTimer task_timer
Helper variable used to track long running operations for telemetry.
Definition: TraceIntelPT.h:270