EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-05-10 08:42:56
0001 //===-- TraceCursor.h -------------------------------------------*- C++ -*-===// 0002 // 0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 0004 // See https://llvm.org/LICENSE.txt for license information. 0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 0006 // 0007 //===----------------------------------------------------------------------===// 0008 0009 #ifndef LLDB_TARGET_TRACE_CURSOR_H 0010 #define LLDB_TARGET_TRACE_CURSOR_H 0011 0012 #include "lldb/lldb-private.h" 0013 0014 #include "lldb/Target/ExecutionContext.h" 0015 #include <optional> 0016 0017 namespace lldb_private { 0018 0019 /// Class used for iterating over the instructions of a thread's trace, among 0020 /// other kinds of information. 0021 /// 0022 /// This class attempts to be a generic interface for accessing the instructions 0023 /// of the trace so that each Trace plug-in can reconstruct, represent and store 0024 /// the instruction data in an flexible way that is efficient for the given 0025 /// technology. 0026 /// 0027 /// Live processes: 0028 /// In the case of a live process trace, an instance of a \a TraceCursor 0029 /// should point to the trace at the moment it was collected. If the process 0030 /// is later resumed and new trace data is collected, then it's up to each 0031 /// trace plug-in to decide whether to leave the old cursor unaffected or not. 0032 /// 0033 /// Cursor items: 0034 /// A \a TraceCursor can point at one of the following items: 0035 /// 0036 /// Errors: 0037 /// As there could be errors when reconstructing the instructions of a 0038 /// trace, these errors are represented as failed instructions, and the 0039 /// cursor can point at them. 0040 /// 0041 /// Events: 0042 /// The cursor can also point at events in the trace, which aren't errors 0043 /// nor instructions. An example of an event could be a context switch in 0044 /// between two instructions. 0045 /// 0046 /// Instruction: 0047 /// An actual instruction with a memory address. 0048 /// 0049 /// Defaults: 0050 /// By default, the cursor points at the most recent item in the trace and is 0051 /// set up to iterate backwards. See the \a TraceCursor::Next() method for 0052 /// more documentation. 0053 /// 0054 /// Sample usage: 0055 /// 0056 /// TraceCursorSP cursor = trace.GetTrace(thread); 0057 /// 0058 /// for (; cursor->HasValue(); cursor->Next()) { 0059 /// TraceItemKind kind = cursor->GetItemKind(); 0060 /// switch (cursor->GetItemKind()): 0061 /// case eTraceItemKindError: 0062 /// cout << "error found: " << cursor->GetError() << endl; 0063 /// break; 0064 /// case eTraceItemKindEvent: 0065 /// cout << "event found: " << cursor->GetEventTypeAsString() << endl; 0066 /// break; 0067 /// case eTraceItemKindInstruction: 0068 /// std::cout << "instructions found at " << cursor->GetLoadAddress() << 0069 /// std::endl; break; 0070 /// } 0071 /// } 0072 /// 0073 /// As the trace might be empty or the cursor might have reached the end of the 0074 /// trace, you should always invoke \a HasValue() to make sure you don't access 0075 /// invalid memory. 0076 /// 0077 /// Random accesses: 0078 /// 0079 /// The Trace Cursor offer random acesses in the trace via two APIs: 0080 /// 0081 /// TraceCursor::Seek(): 0082 /// Unlike the \a TraceCursor::Next() API, which moves instruction by 0083 /// instruction, the \a TraceCursor::Seek() method can be used to 0084 /// reposition the cursor to an offset of the end, beginning, or current 0085 /// position of the trace. 0086 /// 0087 /// TraceCursor::GetId() / TraceCursor::SetId(id): 0088 /// Each item (error or instruction) in the trace has a numeric identifier 0089 /// which is defined by the trace plug-in. It's possible to access the id 0090 /// of the current item using GetId(), and to reposition the cursor to a 0091 /// given id using SetId(id). 0092 /// 0093 /// You can read more in the documentation of these methods. 0094 class TraceCursor { 0095 public: 0096 /// Create a cursor that initially points to the end of the trace, i.e. the 0097 /// most recent item. 0098 TraceCursor(lldb::ThreadSP thread_sp); 0099 0100 virtual ~TraceCursor() = default; 0101 0102 /// Set the direction to use in the \a TraceCursor::Next() method. 0103 /// 0104 /// \param[in] forwards 0105 /// If \b true, then the traversal will be forwards, otherwise backwards. 0106 void SetForwards(bool forwards); 0107 0108 /// Check if the direction to use in the \a TraceCursor::Next() method is 0109 /// forwards. 0110 /// 0111 /// \return 0112 /// \b true if the current direction is forwards, \b false if backwards. 0113 bool IsForwards() const; 0114 0115 /// Move the cursor to the next item (instruction or error). 0116 /// 0117 /// Direction: 0118 /// The traversal is done following the current direction of the trace. If 0119 /// it is forwards, the instructions are visited forwards 0120 /// chronologically. Otherwise, the traversal is done in 0121 /// the opposite direction. By default, a cursor moves backwards unless 0122 /// changed with \a TraceCursor::SetForwards(). 0123 virtual void Next() = 0; 0124 0125 /// \return 0126 /// \b true if the cursor is pointing to a valid item. \b false if the 0127 /// cursor has reached the end of the trace. 0128 virtual bool HasValue() const = 0; 0129 0130 /// Instruction identifiers: 0131 /// 0132 /// When building complex higher level tools, fast random accesses in the 0133 /// trace might be needed, for which each instruction requires a unique 0134 /// identifier within its thread trace. For example, a tool might want to 0135 /// repeatedly inspect random consecutive portions of a trace. This means that 0136 /// it will need to first move quickly to the beginning of each section and 0137 /// then start its iteration. Given that the number of instructions can be in 0138 /// the order of hundreds of millions, fast random access is necessary. 0139 /// 0140 /// An example of such a tool could be an inspector of the call graph of a 0141 /// trace, where each call is represented with its start and end instructions. 0142 /// Inspecting all the instructions of a call requires moving to its first 0143 /// instruction and then iterating until the last instruction, which following 0144 /// the pattern explained above. 0145 /// 0146 /// Instead of using 0-based indices as identifiers, each Trace plug-in can 0147 /// decide the nature of these identifiers and thus no assumptions can be made 0148 /// regarding their ordering and sequentiality. The reason is that an 0149 /// instruction might be encoded by the plug-in in a way that hides its actual 0150 /// 0-based index in the trace, but it's still possible to efficiently find 0151 /// it. 0152 /// 0153 /// Requirements: 0154 /// - For a given thread, no two instructions have the same id. 0155 /// - In terms of efficiency, moving the cursor to a given id should be as 0156 /// fast as possible, but not necessarily O(1). That's why the recommended 0157 /// way to traverse sequential instructions is to use the \a 0158 /// TraceCursor::Next() method and only use \a TraceCursor::GoToId(id) 0159 /// sparingly. 0160 0161 /// Make the cursor point to the item whose identifier is \p id. 0162 /// 0163 /// \return 0164 /// \b true if the given identifier exists and the cursor effectively 0165 /// moved to it. Otherwise, \b false is returned and the cursor now points 0166 /// to an invalid item, i.e. calling \a HasValue() will return \b false. 0167 virtual bool GoToId(lldb::user_id_t id) = 0; 0168 0169 /// \return 0170 /// \b true if and only if there's an instruction item with the given \p 0171 /// id. 0172 virtual bool HasId(lldb::user_id_t id) const = 0; 0173 0174 /// \return 0175 /// A unique identifier for the instruction or error this cursor is 0176 /// pointing to. 0177 virtual lldb::user_id_t GetId() const = 0; 0178 /// \} 0179 0180 /// Make the cursor point to an item in the trace based on an origin point and 0181 /// an offset. 0182 /// 0183 /// The resulting position of the trace is 0184 /// origin + offset 0185 /// 0186 /// If this resulting position would be out of bounds, the trace then points 0187 /// to an invalid item, i.e. calling \a HasValue() returns \b false. 0188 /// 0189 /// \param[in] offset 0190 /// How many items to move forwards (if positive) or backwards (if 0191 /// negative) from the given origin point. For example, if origin is \b 0192 /// End, then a negative offset would move backward in the trace, but a 0193 /// positive offset would move past the trace to an invalid item. 0194 /// 0195 /// \param[in] origin 0196 /// The reference point to use when moving the cursor. 0197 /// 0198 /// \return 0199 /// \b true if and only if the cursor ends up pointing to a valid item. 0200 virtual bool Seek(int64_t offset, lldb::TraceCursorSeekType origin) = 0; 0201 0202 /// \return 0203 /// The \a ExecutionContextRef of the backing thread from the creation time 0204 /// of this cursor. 0205 ExecutionContextRef &GetExecutionContextRef(); 0206 0207 /// Trace item information (instructions, errors and events) 0208 /// \{ 0209 0210 /// \return 0211 /// The kind of item the cursor is pointing at. 0212 virtual lldb::TraceItemKind GetItemKind() const = 0; 0213 0214 /// \return 0215 /// Whether the cursor points to an error or not. 0216 bool IsError() const; 0217 0218 /// \return 0219 /// The error message the cursor is pointing at. 0220 virtual llvm::StringRef GetError() const = 0; 0221 0222 /// \return 0223 /// Whether the cursor points to an event or not. 0224 bool IsEvent() const; 0225 0226 /// \return 0227 /// The specific kind of event the cursor is pointing at. 0228 virtual lldb::TraceEvent GetEventType() const = 0; 0229 0230 /// \return 0231 /// A human-readable description of the event this cursor is pointing at. 0232 const char *GetEventTypeAsString() const; 0233 0234 /// \return 0235 /// A human-readable description of the given event. 0236 static const char *EventKindToString(lldb::TraceEvent event_kind); 0237 0238 /// \return 0239 /// Whether the cursor points to an instruction. 0240 bool IsInstruction() const; 0241 0242 /// \return 0243 /// The load address of the instruction the cursor is pointing at. 0244 virtual lldb::addr_t GetLoadAddress() const = 0; 0245 0246 /// Get the CPU associated with the current trace item. 0247 /// 0248 /// This call might not be O(1), so it's suggested to invoke this method 0249 /// whenever an eTraceEventCPUChanged event is fired. 0250 /// 0251 /// \return 0252 /// The requested CPU id, or LLDB_INVALID_CPU_ID if this information is 0253 /// not available for the current item. 0254 virtual lldb::cpu_id_t GetCPU() const = 0; 0255 0256 /// Get the last hardware clock value that was emitted before the current 0257 /// trace item. 0258 /// 0259 /// This call might not be O(1), so it's suggested to invoke this method 0260 /// whenever an eTraceEventHWClockTick event is fired. 0261 /// 0262 /// \return 0263 /// The requested HW clock value, or \a std::nullopt if this information 0264 /// is not available for the current item. 0265 virtual std::optional<uint64_t> GetHWClock() const = 0; 0266 0267 /// Get the approximate wall clock time in nanoseconds at which the current 0268 /// trace item was executed. Each trace plug-in has a different definition for 0269 /// what time 0 means. 0270 /// 0271 /// \return 0272 /// The approximate wall clock time for the trace item, or \a std::nullopt 0273 /// if not available. 0274 virtual std::optional<double> GetWallClockTime() const = 0; 0275 0276 /// Get some metadata associated with a synchronization point event. As 0277 /// different trace technologies might have different values for this, 0278 /// we return a string for flexibility. 0279 /// 0280 /// \return 0281 /// A string representing some metadata associated with a 0282 /// \a eTraceEventSyncPoint event. \b std::nullopt if no metadata is 0283 /// available. 0284 virtual std::optional<std::string> GetSyncPointMetadata() const = 0; 0285 /// \} 0286 0287 protected: 0288 ExecutionContextRef m_exe_ctx_ref; 0289 bool m_forwards = false; 0290 }; 0291 } // namespace lldb_private 0292 0293 #endif // LLDB_TARGET_TRACE_CURSOR_H
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|