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. 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::Set = 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 SetGranularity (lldb::TraceInstructionControlFlowType granularity)
 Set the granularity to use in the TraceCursor::Next() method. More...
 
void SetIgnoreErrors (bool ignore_errors)
 Set the "ignore errors" flag to use in the TraceCursor::Next() method. More...
 
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 bool Next ()=0
 Move the cursor to the next instruction that matches the current granularity. More...
 
virtual size_t Seek (ssize_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 ()
 
virtual bool IsError ()=0
 Instruction or error information. More...
 
virtual llvm::Error GetError ()=0
 Get the corresponding error message if the cursor points to an error in the trace. More...
 
virtual lldb::addr_t GetLoadAddress ()=0
 
virtual llvm::Optional< uint64_t > GetTimestampCounter ()=0
 Get the timestamp counter associated with the current instruction. More...
 
virtual lldb::TraceInstructionControlFlowType GetInstructionControlFlowType ()=0
 

Protected Attributes

ExecutionContextRef m_exe_ctx_ref
 
lldb::TraceInstructionControlFlowType m_granularity
 
bool m_ignore_errors = false
 
bool m_forwards = false
 

Detailed Description

Class used for iterating over the instructions of a thread's trace.

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, that should leave that old cursor unaffected.

Errors in the trace: 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. The consumer should invoke TraceCursor::GetError() to check if the cursor is pointing to either a valid instruction or an error.

Instructions: A TraceCursor always points to a specific instruction or error in the trace.

Defaults: By default, the cursor points at the end item of the trace, moves backwards, has a move granularity of eTraceInstructionControlFlowTypeInstruction (i.e. visit every instruction) and stops at every error (the "ignore errors" flag is false). See the TraceCursor::Next() method for more documentation.

Sample usage:

TraceCursorUP cursor = trace.GetTrace(thread);

cursor->SetGranularity(eTraceInstructionControlFlowTypeCall | eTraceInstructionControlFlowTypeReturn);

do { if (llvm::Error error = cursor->GetError()) cout << "error found at: " << llvm::toString(error) << endl; else if (cursor->GetInstructionControlFlowType() & eTraceInstructionControlFlowTypeCall) std::cout << "call found at " << cursor->GetLoadAddress() << std::endl; else if (cursor->GetInstructionControlFlowType() & eTraceInstructionControlFlowTypeReturn) std::cout << "return found at " << cursor->GetLoadAddress() << std::endl; } while(cursor->Next());

Low level traversal: Unlike the TraceCursor::Next() API, which uses a given granularity and direction to advance the cursor, the TraceCursor::Seek() method can be used to reposition the cursor to an offset of the end, beginning, or current position of the trace.

Definition at line 73 of file TraceCursor.h.

Member Enumeration Documentation

◆ SeekType

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

Enumerator
Set 

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 77 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 17 of file TraceCursor.cpp.

◆ ~TraceCursor()

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

Member Function Documentation

◆ GetError()

virtual llvm::Error lldb_private::TraceCursor::GetError ( )
pure virtual

Get the corresponding error message if the cursor points to an error in the trace.

Returns
llvm::Error::success if the cursor is not pointing to an error in the trace. Otherwise return an llvm::Error describing the issue.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetExecutionContextRef()

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

Definition at line 20 of file TraceCursor.cpp.

References m_exe_ctx_ref.

◆ GetInstructionControlFlowType()

virtual lldb::TraceInstructionControlFlowType lldb_private::TraceCursor::GetInstructionControlFlowType ( )
pure virtual
Returns
The lldb::TraceInstructionControlFlowType categories the instruction the cursor is pointing at falls into. If the cursor points to an error in the trace, return 0.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

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

◆ GetLoadAddress()

virtual lldb::addr_t lldb_private::TraceCursor::GetLoadAddress ( )
pure virtual
Returns
The load address of the instruction the cursor is pointing at. If the cursor points to an error in the trace, return LLDB_INVALID_ADDRESS.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

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

◆ GetTimestampCounter()

virtual llvm::Optional<uint64_t> lldb_private::TraceCursor::GetTimestampCounter ( )
pure virtual

Get the timestamp counter associated with the current instruction.

Modern Intel, ARM and AMD processors support this counter. However, a trace plugin might decide to use a different time unit instead of an actual TSC.

Returns
The timestamp or llvm::None if not available.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ IsError()

virtual bool lldb_private::TraceCursor::IsError ( )
pure virtual

Instruction or error information.

Returns
Whether the cursor points to an error or not.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

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

◆ 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 35 of file TraceCursor.cpp.

References m_forwards.

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

◆ Next()

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

Move the cursor to the next instruction that matches the current granularity.

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().

Granularity: The cursor will traverse the trace looking for the first instruction that matches the current granularity. If there aren't any matching instructions, the cursor won't move, to give the opportunity of changing granularities.

Ignore errors: If the "ignore errors" flags is false, the traversal will stop as soon as it finds an error in the trace and the cursor will point at it.

Returns
true if the cursor effectively moved, false otherwise.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

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

◆ Seek()

virtual size_t lldb_private::TraceCursor::Seek ( ssize_t  offset,
SeekType  origin 
)
pure virtual

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

This API doesn't distinguishes instruction types nor errors in the trace, unlike the TraceCursor::Next() method.

The resulting position of the trace is origin + offset

If this resulting position would be out of bounds, it will be adjusted to the last or first item in the trace correspondingly.

Parameters
[in]offsetHow many items to move forwards (if positive) or backwards (if negative) from the given origin point.
[in]originThe reference point to use when moving the cursor.
Returns
The number of trace items moved from the origin.

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 33 of file TraceCursor.cpp.

References m_forwards.

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

◆ SetGranularity()

void TraceCursor::SetGranularity ( lldb::TraceInstructionControlFlowType  granularity)

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

Definition at line 24 of file TraceCursor.cpp.

References m_granularity.

◆ SetIgnoreErrors()

void TraceCursor::SetIgnoreErrors ( bool  ignore_errors)

Set the "ignore errors" flag to use in the TraceCursor::Next() method.

Definition at line 29 of file TraceCursor.cpp.

References m_ignore_errors.

Member Data Documentation

◆ m_exe_ctx_ref

ExecutionContextRef lldb_private::TraceCursor::m_exe_ctx_ref
protected

Definition at line 201 of file TraceCursor.h.

Referenced by GetExecutionContextRef().

◆ m_forwards

bool lldb_private::TraceCursor::m_forwards = false
protected

Definition at line 206 of file TraceCursor.h.

Referenced by IsForwards(), and SetForwards().

◆ m_granularity

lldb::TraceInstructionControlFlowType lldb_private::TraceCursor::m_granularity
protected
Initial value:
=
lldb::eTraceInstructionControlFlowTypeInstruction

Definition at line 203 of file TraceCursor.h.

Referenced by lldb_private::trace_intel_pt::TraceCursorIntelPT::Next(), and SetGranularity().

◆ m_ignore_errors

bool lldb_private::TraceCursor::m_ignore_errors = false
protected

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