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 | |
14 | #include "lldb/Target/ExecutionContext.h" |
15 | #include <optional> |
16 | |
17 | namespace 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. |
94 | class TraceCursor { |
95 | public: |
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. |
205 | ExecutionContextRef &GetExecutionContextRef(); |
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 llvm::StringRef 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 | |
287 | protected: |
288 | ExecutionContextRef m_exe_ctx_ref; |
289 | bool m_forwards = false; |
290 | }; |
291 | } // namespace lldb_private |
292 | |
293 | #endif // LLDB_TARGET_TRACE_CURSOR_H |
294 | |