LLDB  mainline
Public Types | Public Member Functions | Protected Attributes | List of all members
lldb_private::TraceCursor Class Referenceabstract

Class used for iterating over the instructions of a thread's trace, among other kinds of information. More...

#include <TraceCursor.h>

Inheritance diagram for lldb_private::TraceCursor:
Inheritance graph
[legend]
Collaboration diagram for lldb_private::TraceCursor:
Collaboration graph
[legend]

Public Types

enum  SeekType { SeekType::Beginning = 0, SeekType::Current, SeekType::End }
 Helper enum to indicate the reference point when invoking TraceCursor::Seek(). More...
 

Public Member Functions

 TraceCursor (lldb::ThreadSP thread_sp)
 Create a cursor that initially points to the end of the trace, i.e. More...
 
virtual ~TraceCursor ()=default
 
void SetForwards (bool forwards)
 Set the direction to use in the TraceCursor::Next() method. More...
 
bool IsForwards () const
 Check if the direction to use in the TraceCursor::Next() method is forwards. More...
 
virtual void Next ()=0
 Move the cursor to the next item (instruction or error). More...
 
virtual bool HasValue () const =0
 
virtual bool GoToId (lldb::user_id_t id)=0
 Instruction identifiers: More...
 
virtual bool HasId (lldb::user_id_t id) const =0
 
virtual lldb::user_id_t GetId () const =0
 
virtual bool Seek (int64_t offset, SeekType origin)=0
 Make the cursor point to an item in the trace based on an origin point and an offset. More...
 
ExecutionContextRefGetExecutionContextRef ()
 

Protected Attributes

ExecutionContextRef m_exe_ctx_ref
 
bool m_forwards = false
 
virtual lldb::TraceItemKind GetItemKind () const =0
 Instruction, event or error information. More...
 
bool IsError () const
 
virtual const char * GetError () const =0
 
bool IsEvent () const
 
virtual lldb::TraceEvent GetEventType () const =0
 
const char * GetEventTypeAsString () const
 
bool IsInstruction () const
 
virtual lldb::addr_t GetLoadAddress () const =0
 
virtual llvm::Optional< uint64_t > GetCounter (lldb::TraceCounter counter_type) const =0
 Get the hardware counter of a given type associated with the current instruction. More...
 
virtual llvm::Optional< lldb::cpu_id_tGetCPU () const =0
 Get the CPU associated with the current trace item. More...
 
static const char * EventKindToString (lldb::TraceEvent event_kind)
 

Detailed Description

Class used for iterating over the instructions of a thread's trace, among other kinds of information.

This class attempts to be a generic interface for accessing the instructions of the trace so that each Trace plug-in can reconstruct, represent and store the instruction data in an flexible way that is efficient for the given technology.

Live processes: In the case of a live process trace, an instance of a TraceCursor should point to the trace at the moment it was collected. If the process is later resumed and new trace data is collected, then it's up to each trace plug-in to decide whether to leave the old cursor unaffected or not.

Cursor items: A TraceCursor can point at one of the following items:

Errors: As there could be errors when reconstructing the instructions of a trace, these errors are represented as failed instructions, and the cursor can point at them.

Events: The cursor can also point at events in the trace, which aren't errors nor instructions. An example of an event could be a context switch in between two instructions.

Instruction: An actual instruction with a memory address.

Defaults: By default, the cursor points at the most recent item in the trace and is set up to iterate backwards. See the TraceCursor::Next() method for more documentation.

Sample usage:

TraceCursorUP cursor = trace.GetTrace(thread);

for (; cursor->HasValue(); cursor->Next()) { TraceItemKind kind = cursor->GetItemKind(); switch (cursor->GetItemKind()): case eTraceItemKindError: cout << "error found: " << cursor->GetError() << endl; break; case eTraceItemKindEvent: cout << "event found: " << cursor->GetEventTypeAsString() << endl; break; case eTraceItemKindInstruction: std::cout << "instructions found at " << cursor->GetLoadAddress() << std::endl; break; } }

As the trace might be empty or the cursor might have reached the end of the trace, you should always invoke HasValue() to make sure you don't access invalid memory.

Random accesses:

The Trace Cursor offer random acesses in the trace via two APIs:

TraceCursor::Seek(): Unlike the TraceCursor::Next() API, which moves instruction by instruction, the TraceCursor::Seek() method can be used to reposition the cursor to an offset of the end, beginning, or current position of the trace.

TraceCursor::GetId() / TraceCursor::SetId(id): Each item (error or instruction) in the trace has a numeric identifier which is defined by the trace plug-in. It's possible to access the id of the current item using GetId(), and to reposition the cursor to a given id using SetId(id).

You can read more in the documentation of these methods.

Definition at line 93 of file TraceCursor.h.

Member Enumeration Documentation

◆ SeekType

Helper enum to indicate the reference point when invoking TraceCursor::Seek().

The following values are inspired by std::istream::seekg.

Enumerator
Beginning 

The beginning of the trace, i.e the oldest item.

Current 

The current position in the trace.

End 

The end of the trace, i.e the most recent item.

Definition at line 98 of file TraceCursor.h.

Constructor & Destructor Documentation

◆ TraceCursor()

TraceCursor::TraceCursor ( lldb::ThreadSP  thread_sp)

Create a cursor that initially points to the end of the trace, i.e.

the most recent item.

Definition at line 18 of file TraceCursor.cpp.

◆ ~TraceCursor()

virtual lldb_private::TraceCursor::~TraceCursor ( )
virtualdefault

Member Function Documentation

◆ EventKindToString()

const char * TraceCursor::EventKindToString ( lldb::TraceEvent  event_kind)
static
Returns
A human-readable description of the given event.

Definition at line 45 of file TraceCursor.cpp.

References lldb::eTraceEventCPUChanged, lldb::eTraceEventDisabledHW, and lldb::eTraceEventDisabledSW.

Referenced by lldb_private::trace_intel_pt::TraceIntelPT::DumpTraceInfo(), and GetEventTypeAsString().

◆ GetCounter()

virtual llvm::Optional<uint64_t> lldb_private::TraceCursor::GetCounter ( lldb::TraceCounter  counter_type) const
pure virtual

Get the hardware counter of a given type associated with the current instruction.

Each architecture might support different counters. It might happen that only some instructions of an entire trace have a given counter associated with them.

Parameters
[in]counter_typeThe counter type.
Returns
The value of the counter or llvm::None if not available.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetCPU()

virtual llvm::Optional<lldb::cpu_id_t> lldb_private::TraceCursor::GetCPU ( ) const
pure virtual

Get the CPU associated with the current trace item.

This call might not be O(1), so it's suggested to invoke this method whenever a cpu change event is fired.

Returns
The requested CPU id, or llvm::None if this information is not available for the current item.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetError()

virtual const char* lldb_private::TraceCursor::GetError ( ) const
pure virtual
Returns
The error message the cursor is pointing at.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetEventType()

virtual lldb::TraceEvent lldb_private::TraceCursor::GetEventType ( ) const
pure virtual
Returns
The specific kind of event the cursor is pointing at, or TraceEvent::eTraceEventNone if the cursor not pointing to an event.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

Referenced by GetEventTypeAsString().

◆ GetEventTypeAsString()

const char * TraceCursor::GetEventTypeAsString ( ) const
Returns
A human-readable description of the event this cursor is pointing at.

Definition at line 41 of file TraceCursor.cpp.

References EventKindToString(), and GetEventType().

◆ GetExecutionContextRef()

ExecutionContextRef & TraceCursor::GetExecutionContextRef ( )
Returns
The ExecutionContextRef of the backing thread from the creation time of this cursor.

Definition at line 21 of file TraceCursor.cpp.

References m_exe_ctx_ref.

◆ GetId()

virtual lldb::user_id_t lldb_private::TraceCursor::GetId ( ) const
pure virtual
Returns
A unique identifier for the instruction or error this cursor is pointing to.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetItemKind()

virtual lldb::TraceItemKind lldb_private::TraceCursor::GetItemKind ( ) const
pure virtual

Instruction, event or error information.

Returns
The kind of item the cursor is pointing at.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

Referenced by IsError(), IsEvent(), and IsInstruction().

◆ GetLoadAddress()

virtual lldb::addr_t lldb_private::TraceCursor::GetLoadAddress ( ) const
pure virtual
Returns
The load address of the instruction the cursor is pointing at.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GoToId()

virtual bool lldb_private::TraceCursor::GoToId ( lldb::user_id_t  id)
pure virtual

Instruction identifiers:

When building complex higher level tools, fast random accesses in the trace might be needed, for which each instruction requires a unique identifier within its thread trace. For example, a tool might want to repeatedly inspect random consecutive portions of a trace. This means that it will need to first move quickly to the beginning of each section and then start its iteration. Given that the number of instructions can be in the order of hundreds of millions, fast random access is necessary.

An example of such a tool could be an inspector of the call graph of a trace, where each call is represented with its start and end instructions. Inspecting all the instructions of a call requires moving to its first instruction and then iterating until the last instruction, which following the pattern explained above.

Instead of using 0-based indices as identifiers, each Trace plug-in can decide the nature of these identifiers and thus no assumptions can be made regarding their ordering and sequentiality. The reason is that an instruction might be encoded by the plug-in in a way that hides its actual 0-based index in the trace, but it's still possible to efficiently find it.

Requirements:

  • For a given thread, no two instructions have the same id.
  • In terms of efficiency, moving the cursor to a given id should be as fast as possible, but not necessarily O(1). That's why the recommended way to traverse sequential instructions is to use the TraceCursor::Next() method and only use TraceCursor::GoToId(id) sparingly. Make the cursor point to the item whose identifier is id.
Returns
true if the given identifier exists and the cursor effectively moved to it. Otherwise, false is returned and the cursor now points to an invalid item, i.e. calling HasValue() will return false.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ HasId()

virtual bool lldb_private::TraceCursor::HasId ( lldb::user_id_t  id) const
pure virtual
Returns
true if and only if there's an instruction item with the given id.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ HasValue()

virtual bool lldb_private::TraceCursor::HasValue ( ) const
pure virtual
Returns
true if the cursor is pointing to a valid item. false if the cursor has reached the end of the trace.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ IsError()

bool TraceCursor::IsError ( ) const
Returns
Whether the cursor points to an error or not.

Definition at line 29 of file TraceCursor.cpp.

References lldb::eTraceItemKindError, and GetItemKind().

◆ IsEvent()

bool TraceCursor::IsEvent ( ) const
Returns
Whether the cursor points to an event or not.

Definition at line 33 of file TraceCursor.cpp.

References lldb::eTraceItemKindEvent, and GetItemKind().

◆ IsForwards()

bool TraceCursor::IsForwards ( ) const

Check if the direction to use in the TraceCursor::Next() method is forwards.

Returns
true if the current direction is forwards, false if backwards.

Definition at line 27 of file TraceCursor.cpp.

References m_forwards.

Referenced by lldb_private::trace_intel_pt::TraceCursorIntelPT::Next().

◆ IsInstruction()

bool TraceCursor::IsInstruction ( ) const
Returns
Whether the cursor points to an instruction.

Definition at line 37 of file TraceCursor.cpp.

References lldb::eTraceItemKindInstruction, and GetItemKind().

◆ Next()

virtual void lldb_private::TraceCursor::Next ( )
pure virtual

Move the cursor to the next item (instruction or error).

Direction: The traversal is done following the current direction of the trace. If it is forwards, the instructions are visited forwards chronologically. Otherwise, the traversal is done in the opposite direction. By default, a cursor moves backwards unless changed with TraceCursor::SetForwards().

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ Seek()

virtual bool lldb_private::TraceCursor::Seek ( int64_t  offset,
SeekType  origin 
)
pure virtual

Make the cursor point to an item in the trace based on an origin point and an offset.

The resulting position of the trace is origin + offset

If this resulting position would be out of bounds, the trace then points to an invalid item, i.e. calling HasValue() returns false.

Parameters
[in]offsetHow many items to move forwards (if positive) or backwards (if negative) from the given origin point. For example, if origin is End, then a negative offset would move backward in the trace, but a positive offset would move past the trace to an invalid item.
[in]originThe reference point to use when moving the cursor.
Returns
true if and only if the cursor ends up pointing to a valid item.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

Referenced by lldb_private::TraceHTR::TraceHTR().

◆ SetForwards()

void TraceCursor::SetForwards ( bool  forwards)

Set the direction to use in the TraceCursor::Next() method.

Parameters
[in]forwardsIf true, then the traversal will be forwards, otherwise backwards.

Definition at line 25 of file TraceCursor.cpp.

References m_forwards.

Referenced by lldb_private::TraceHTR::TraceHTR().

Member Data Documentation

◆ m_exe_ctx_ref

ExecutionContextRef lldb_private::TraceCursor::m_exe_ctx_ref
protected

Definition at line 282 of file TraceCursor.h.

Referenced by GetExecutionContextRef().

◆ m_forwards

bool lldb_private::TraceCursor::m_forwards = false
protected

Definition at line 283 of file TraceCursor.h.

Referenced by IsForwards(), and SetForwards().


The documentation for this class was generated from the following files: