1 //===-- SBTraceCursor.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_API_SBTRACECURSOR_H 10 #define LLDB_API_SBTRACECURSOR_H 11 12 #include "lldb/API/SBDefines.h" 13 #include "lldb/API/SBError.h" 14 #include "lldb/API/SBExecutionContext.h" 15 16 namespace lldb { 17 18 class LLDB_API SBTraceCursor { 19 public: 20 /// Default constructor for an invalid \a SBTraceCursor object. 21 SBTraceCursor(); 22 23 /// Create a cursor that initially points to the end of the trace, i.e. the 24 /// most recent item. 25 SBTraceCursor(lldb::TraceCursorSP trace_cursor_sp); 26 27 /// Set the direction to use in the \a SBTraceCursor::Next() method. 28 /// 29 /// \param[in] forwards 30 /// If \b true, then the traversal will be forwards, otherwise backwards. 31 void SetForwards(bool forwards); 32 33 /// Check if the direction to use in the \a SBTraceCursor::Next() method is 34 /// forwards. 35 /// 36 /// \return 37 /// \b true if the current direction is forwards, \b false if backwards. 38 bool IsForwards() const; 39 40 /// Move the cursor to the next item (instruction or error). 41 /// 42 /// Direction: 43 /// The traversal is done following the current direction of the trace. If 44 /// it is forwards, the instructions are visited forwards 45 /// chronologically. Otherwise, the traversal is done in 46 /// the opposite direction. By default, a cursor moves backwards unless 47 /// changed with \a SBTraceCursor::SetForwards(). 48 void Next(); 49 50 /// \return 51 /// \b true if the cursor is pointing to a valid item. \b false if the 52 /// cursor has reached the end of the trace. 53 bool HasValue() const; 54 55 /// Instruction identifiers: 56 /// 57 /// When building complex higher level tools, fast random accesses in the 58 /// trace might be needed, for which each instruction requires a unique 59 /// identifier within its thread trace. For example, a tool might want to 60 /// repeatedly inspect random consecutive portions of a trace. This means that 61 /// it will need to first move quickly to the beginning of each section and 62 /// then start its iteration. Given that the number of instructions can be in 63 /// the order of hundreds of millions, fast random access is necessary. 64 /// 65 /// An example of such a tool could be an inspector of the call graph of a 66 /// trace, where each call is represented with its start and end instructions. 67 /// Inspecting all the instructions of a call requires moving to its first 68 /// instruction and then iterating until the last instruction, which following 69 /// the pattern explained above. 70 /// 71 /// Instead of using 0-based indices as identifiers, each Trace plug-in can 72 /// decide the nature of these identifiers and thus no assumptions can be made 73 /// regarding their ordering and sequentiality. The reason is that an 74 /// instruction might be encoded by the plug-in in a way that hides its actual 75 /// 0-based index in the trace, but it's still possible to efficiently find 76 /// it. 77 /// 78 /// Requirements: 79 /// - For a given thread, no two instructions have the same id. 80 /// - In terms of efficiency, moving the cursor to a given id should be as 81 /// fast as possible, but not necessarily O(1). That's why the recommended 82 /// way to traverse sequential instructions is to use the \a 83 /// SBTraceCursor::Next() method and only use \a SBTraceCursor::GoToId(id) 84 /// sparingly. 85 86 /// Make the cursor point to the item whose identifier is \p id. 87 /// 88 /// \return 89 /// \b true if the given identifier exists and the cursor effectively 90 /// moved to it. Otherwise, \b false is returned and the cursor now points 91 /// to an invalid item, i.e. calling \a HasValue() will return \b false. 92 bool GoToId(lldb::user_id_t id); 93 94 /// \return 95 /// \b true if and only if there's an instruction item with the given \p 96 /// id. 97 bool HasId(lldb::user_id_t id) const; 98 99 /// \return 100 /// A unique identifier for the instruction or error this cursor is 101 /// pointing to. 102 lldb::user_id_t GetId() const; 103 /// \} 104 105 /// Make the cursor point to an item in the trace based on an origin point and 106 /// an offset. 107 /// 108 /// The resulting position of the trace is 109 /// origin + offset 110 /// 111 /// If this resulting position would be out of bounds, the trace then points 112 /// to an invalid item, i.e. calling \a HasValue() returns \b false. 113 /// 114 /// \param[in] offset 115 /// How many items to move forwards (if positive) or backwards (if 116 /// negative) from the given origin point. For example, if origin is \b 117 /// End, then a negative offset would move backward in the trace, but a 118 /// positive offset would move past the trace to an invalid item. 119 /// 120 /// \param[in] origin 121 /// The reference point to use when moving the cursor. 122 /// 123 /// \return 124 /// \b true if and only if the cursor ends up pointing to a valid item. 125 bool Seek(int64_t offset, lldb::TraceCursorSeekType origin); 126 127 /// \return 128 /// The \a ExecutionContextRef of the backing thread from the creation time 129 /// of this cursor. 130 SBExecutionContext &GetExecutionContextRef(); 131 132 /// Trace item information (instructions, errors and events) 133 /// \{ 134 135 /// \return 136 /// The kind of item the cursor is pointing at. 137 lldb::TraceItemKind GetItemKind() const; 138 139 /// \return 140 /// Whether the cursor points to an error or not. 141 bool IsError() const; 142 143 /// \return 144 /// The error message the cursor is pointing at. 145 const char *GetError() const; 146 147 /// \return 148 /// Whether the cursor points to an event or not. 149 bool IsEvent() const; 150 151 /// \return 152 /// The specific kind of event the cursor is pointing at. 153 lldb::TraceEvent GetEventType() const; 154 155 /// \return 156 /// A human-readable description of the event this cursor is pointing at. 157 const char *GetEventTypeAsString() const; 158 159 /// \return 160 /// Whether the cursor points to an instruction. 161 bool IsInstruction() const; 162 163 /// \return 164 /// The load address of the instruction the cursor is pointing at. 165 lldb::addr_t GetLoadAddress() const; 166 167 /// \return 168 /// The requested CPU id, or LLDB_INVALID_CPU_ID if this information is 169 /// not available for the current item. 170 lldb::cpu_id_t GetCPU() const; 171 172 bool IsValid() const; 173 174 explicit operator bool() const; 175 176 protected: 177 lldb::TraceCursorSP m_opaque_sp; 178 }; 179 } // namespace lldb 180 181 #endif // LLDB_API_SBTRACECURSOR_H 182