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 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 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