LLDB mainline
TraceCursor.h
Go to the documentation of this file.
1//===-- TraceCursor.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_TARGET_TRACE_CURSOR_H
10#define LLDB_TARGET_TRACE_CURSOR_H
11
12#include "lldb/lldb-private.h"
13
15#include <optional>
16
17namespace lldb_private {
18
19/// Class used for iterating over the instructions of a thread's trace, among
20/// other kinds of information.
21///
22/// This class attempts to be a generic interface for accessing the instructions
23/// of the trace so that each Trace plug-in can reconstruct, represent and store
24/// the instruction data in an flexible way that is efficient for the given
25/// technology.
26///
27/// Live processes:
28/// In the case of a live process trace, an instance of a \a TraceCursor
29/// should point to the trace at the moment it was collected. If the process
30/// is later resumed and new trace data is collected, then it's up to each
31/// trace plug-in to decide whether to leave the old cursor unaffected or not.
32///
33/// Cursor items:
34/// A \a TraceCursor can point at one of the following items:
35///
36/// Errors:
37/// As there could be errors when reconstructing the instructions of a
38/// trace, these errors are represented as failed instructions, and the
39/// cursor can point at them.
40///
41/// Events:
42/// The cursor can also point at events in the trace, which aren't errors
43/// nor instructions. An example of an event could be a context switch in
44/// between two instructions.
45///
46/// Instruction:
47/// An actual instruction with a memory address.
48///
49/// Defaults:
50/// By default, the cursor points at the most recent item in the trace and is
51/// set up to iterate backwards. See the \a TraceCursor::Next() method for
52/// more documentation.
53///
54/// Sample usage:
55///
56/// TraceCursorSP cursor = trace.GetTrace(thread);
57///
58/// for (; cursor->HasValue(); cursor->Next()) {
59/// TraceItemKind kind = cursor->GetItemKind();
60/// switch (cursor->GetItemKind()):
61/// case eTraceItemKindError:
62/// cout << "error found: " << cursor->GetError() << endl;
63/// break;
64/// case eTraceItemKindEvent:
65/// cout << "event found: " << cursor->GetEventTypeAsString() << endl;
66/// break;
67/// case eTraceItemKindInstruction:
68/// std::cout << "instructions found at " << cursor->GetLoadAddress() <<
69/// std::endl; break;
70/// }
71/// }
72///
73/// As the trace might be empty or the cursor might have reached the end of the
74/// trace, you should always invoke \a HasValue() to make sure you don't access
75/// invalid memory.
76///
77/// Random accesses:
78///
79/// The Trace Cursor offer random acesses in the trace via two APIs:
80///
81/// TraceCursor::Seek():
82/// Unlike the \a TraceCursor::Next() API, which moves instruction by
83/// instruction, the \a TraceCursor::Seek() method can be used to
84/// reposition the cursor to an offset of the end, beginning, or current
85/// position of the trace.
86///
87/// TraceCursor::GetId() / TraceCursor::SetId(id):
88/// Each item (error or instruction) in the trace has a numeric identifier
89/// which is defined by the trace plug-in. It's possible to access the id
90/// of the current item using GetId(), and to reposition the cursor to a
91/// given id using SetId(id).
92///
93/// You can read more in the documentation of these methods.
95public:
96 /// Create a cursor that initially points to the end of the trace, i.e. the
97 /// most recent item.
98 TraceCursor(lldb::ThreadSP thread_sp);
99
100 virtual ~TraceCursor() = default;
101
102 /// Set the direction to use in the \a TraceCursor::Next() method.
103 ///
104 /// \param[in] forwards
105 /// If \b true, then the traversal will be forwards, otherwise backwards.
106 void SetForwards(bool forwards);
107
108 /// Check if the direction to use in the \a TraceCursor::Next() method is
109 /// forwards.
110 ///
111 /// \return
112 /// \b true if the current direction is forwards, \b false if backwards.
113 bool IsForwards() const;
114
115 /// Move the cursor to the next item (instruction or error).
116 ///
117 /// Direction:
118 /// The traversal is done following the current direction of the trace. If
119 /// it is forwards, the instructions are visited forwards
120 /// chronologically. Otherwise, the traversal is done in
121 /// the opposite direction. By default, a cursor moves backwards unless
122 /// changed with \a TraceCursor::SetForwards().
123 virtual void Next() = 0;
124
125 /// \return
126 /// \b true if the cursor is pointing to a valid item. \b false if the
127 /// cursor has reached the end of the trace.
128 virtual bool HasValue() const = 0;
129
130 /// Instruction identifiers:
131 ///
132 /// When building complex higher level tools, fast random accesses in the
133 /// trace might be needed, for which each instruction requires a unique
134 /// identifier within its thread trace. For example, a tool might want to
135 /// repeatedly inspect random consecutive portions of a trace. This means that
136 /// it will need to first move quickly to the beginning of each section and
137 /// then start its iteration. Given that the number of instructions can be in
138 /// the order of hundreds of millions, fast random access is necessary.
139 ///
140 /// An example of such a tool could be an inspector of the call graph of a
141 /// trace, where each call is represented with its start and end instructions.
142 /// Inspecting all the instructions of a call requires moving to its first
143 /// instruction and then iterating until the last instruction, which following
144 /// the pattern explained above.
145 ///
146 /// Instead of using 0-based indices as identifiers, each Trace plug-in can
147 /// decide the nature of these identifiers and thus no assumptions can be made
148 /// regarding their ordering and sequentiality. The reason is that an
149 /// instruction might be encoded by the plug-in in a way that hides its actual
150 /// 0-based index in the trace, but it's still possible to efficiently find
151 /// it.
152 ///
153 /// Requirements:
154 /// - For a given thread, no two instructions have the same id.
155 /// - In terms of efficiency, moving the cursor to a given id should be as
156 /// fast as possible, but not necessarily O(1). That's why the recommended
157 /// way to traverse sequential instructions is to use the \a
158 /// TraceCursor::Next() method and only use \a TraceCursor::GoToId(id)
159 /// sparingly.
160
161 /// Make the cursor point to the item whose identifier is \p id.
162 ///
163 /// \return
164 /// \b true if the given identifier exists and the cursor effectively
165 /// moved to it. Otherwise, \b false is returned and the cursor now points
166 /// to an invalid item, i.e. calling \a HasValue() will return \b false.
167 virtual bool GoToId(lldb::user_id_t id) = 0;
168
169 /// \return
170 /// \b true if and only if there's an instruction item with the given \p
171 /// id.
172 virtual bool HasId(lldb::user_id_t id) const = 0;
173
174 /// \return
175 /// A unique identifier for the instruction or error this cursor is
176 /// pointing to.
177 virtual lldb::user_id_t GetId() const = 0;
178 /// \}
179
180 /// Make the cursor point to an item in the trace based on an origin point and
181 /// an offset.
182 ///
183 /// The resulting position of the trace is
184 /// origin + offset
185 ///
186 /// If this resulting position would be out of bounds, the trace then points
187 /// to an invalid item, i.e. calling \a HasValue() returns \b false.
188 ///
189 /// \param[in] offset
190 /// How many items to move forwards (if positive) or backwards (if
191 /// negative) from the given origin point. For example, if origin is \b
192 /// End, then a negative offset would move backward in the trace, but a
193 /// positive offset would move past the trace to an invalid item.
194 ///
195 /// \param[in] origin
196 /// The reference point to use when moving the cursor.
197 ///
198 /// \return
199 /// \b true if and only if the cursor ends up pointing to a valid item.
200 virtual bool Seek(int64_t offset, lldb::TraceCursorSeekType origin) = 0;
201
202 /// \return
203 /// The \a ExecutionContextRef of the backing thread from the creation time
204 /// of this cursor.
206
207 /// Trace item information (instructions, errors and events)
208 /// \{
209
210 /// \return
211 /// The kind of item the cursor is pointing at.
212 virtual lldb::TraceItemKind GetItemKind() const = 0;
213
214 /// \return
215 /// Whether the cursor points to an error or not.
216 bool IsError() const;
217
218 /// \return
219 /// The error message the cursor is pointing at.
220 virtual const char *GetError() const = 0;
221
222 /// \return
223 /// Whether the cursor points to an event or not.
224 bool IsEvent() const;
225
226 /// \return
227 /// The specific kind of event the cursor is pointing at.
228 virtual lldb::TraceEvent GetEventType() const = 0;
229
230 /// \return
231 /// A human-readable description of the event this cursor is pointing at.
232 const char *GetEventTypeAsString() const;
233
234 /// \return
235 /// A human-readable description of the given event.
236 static const char *EventKindToString(lldb::TraceEvent event_kind);
237
238 /// \return
239 /// Whether the cursor points to an instruction.
240 bool IsInstruction() const;
241
242 /// \return
243 /// The load address of the instruction the cursor is pointing at.
244 virtual lldb::addr_t GetLoadAddress() const = 0;
245
246 /// Get the CPU associated with the current trace item.
247 ///
248 /// This call might not be O(1), so it's suggested to invoke this method
249 /// whenever an eTraceEventCPUChanged event is fired.
250 ///
251 /// \return
252 /// The requested CPU id, or LLDB_INVALID_CPU_ID if this information is
253 /// not available for the current item.
254 virtual lldb::cpu_id_t GetCPU() const = 0;
255
256 /// Get the last hardware clock value that was emitted before the current
257 /// trace item.
258 ///
259 /// This call might not be O(1), so it's suggested to invoke this method
260 /// whenever an eTraceEventHWClockTick event is fired.
261 ///
262 /// \return
263 /// The requested HW clock value, or \a std::nullopt if this information
264 /// is not available for the current item.
265 virtual std::optional<uint64_t> GetHWClock() const = 0;
266
267 /// Get the approximate wall clock time in nanoseconds at which the current
268 /// trace item was executed. Each trace plug-in has a different definition for
269 /// what time 0 means.
270 ///
271 /// \return
272 /// The approximate wall clock time for the trace item, or \a std::nullopt
273 /// if not available.
274 virtual std::optional<double> GetWallClockTime() const = 0;
275
276 /// Get some metadata associated with a synchronization point event. As
277 /// different trace technologies might have different values for this,
278 /// we return a string for flexibility.
279 ///
280 /// \return
281 /// A string representing some metadata associated with a
282 /// \a eTraceEventSyncPoint event. \b std::nullopt if no metadata is
283 /// available.
284 virtual std::optional<std::string> GetSyncPointMetadata() const = 0;
285 /// \}
286
287protected:
289 bool m_forwards = false;
290};
291} // namespace lldb_private
292
293#endif // LLDB_TARGET_TRACE_CURSOR_H
Execution context objects refer to objects in the execution of the program that is being debugged.
Class used for iterating over the instructions of a thread's trace, among other kinds of information.
Definition: TraceCursor.h:94
const char * GetEventTypeAsString() const
Definition: TraceCursor.cpp:41
static const char * EventKindToString(lldb::TraceEvent event_kind)
Definition: TraceCursor.cpp:45
virtual lldb::TraceItemKind GetItemKind() const =0
Trace item information (instructions, errors and events)
void SetForwards(bool forwards)
Set the direction to use in the TraceCursor::Next() method.
Definition: TraceCursor.cpp:25
virtual bool Seek(int64_t offset, lldb::TraceCursorSeekType origin)=0
Make the cursor point to an item in the trace based on an origin point and an offset.
virtual bool GoToId(lldb::user_id_t id)=0
Instruction identifiers:
virtual void Next()=0
Move the cursor to the next item (instruction or error).
virtual lldb::addr_t GetLoadAddress() const =0
ExecutionContextRef m_exe_ctx_ref
Definition: TraceCursor.h:288
virtual lldb::user_id_t GetId() const =0
ExecutionContextRef & GetExecutionContextRef()
Definition: TraceCursor.cpp:21
virtual ~TraceCursor()=default
virtual bool HasValue() const =0
virtual lldb::cpu_id_t GetCPU() const =0
Get the CPU associated with the current trace item.
virtual std::optional< double > GetWallClockTime() const =0
Get the approximate wall clock time in nanoseconds at which the current trace item was executed.
virtual std::optional< uint64_t > GetHWClock() const =0
Get the last hardware clock value that was emitted before the current trace item.
virtual std::optional< std::string > GetSyncPointMetadata() const =0
Get some metadata associated with a synchronization point event.
virtual bool HasId(lldb::user_id_t id) const =0
virtual lldb::TraceEvent GetEventType() const =0
virtual const char * GetError() const =0
bool IsForwards() const
Check if the direction to use in the TraceCursor::Next() method is forwards.
Definition: TraceCursor.cpp:27
A class that represents a running process on the host machine.
TraceEvent
Events that might happen during a trace session.
TraceCursorSeekType
Enum to indicate the reference point when invoking TraceCursor::Seek().
uint64_t user_id_t
Definition: lldb-types.h:84
uint64_t addr_t
Definition: lldb-types.h:83