LLDB  mainline
Public Member Functions | Private Member Functions | Private Attributes | List of all members
lldb_private::trace_intel_pt::TraceCursorIntelPT Class Reference

#include <TraceCursorIntelPT.h>

Inheritance diagram for lldb_private::trace_intel_pt::TraceCursorIntelPT:
Inheritance graph
[legend]
Collaboration diagram for lldb_private::trace_intel_pt::TraceCursorIntelPT:
Collaboration graph
[legend]

Public Member Functions

 TraceCursorIntelPT (lldb::ThreadSP thread_sp, DecodedThreadSP decoded_thread_sp)
 
uint64_t Seek (int64_t offset, SeekType origin) override
 Make the cursor point to an item in the trace based on an origin point and an offset. More...
 
virtual bool Next () override
 Move the cursor to the next instruction that matches the current granularity. More...
 
const char * GetError () override
 Get the corresponding error message if the cursor points to an error in the trace. More...
 
lldb::addr_t GetLoadAddress () override
 
llvm::Optional< uint64_t > GetCounter (lldb::TraceCounter counter_type) override
 Get the hardware counter of a given type associated with the current instruction. More...
 
lldb::TraceEvents GetEvents () override
 Get a bitmask with a list of events that happened chronologically right before the current instruction or error, but after the previous instruction. More...
 
lldb::TraceInstructionControlFlowType GetInstructionControlFlowType () override
 
bool IsError () override
 Instruction or error information. More...
 
bool GoToId (lldb::user_id_t id) override
 Instruction identifiers: More...
 
lldb::user_id_t GetId () const override
 
- Public Member Functions inherited from lldb_private::TraceCursor
 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...
 
ExecutionContextRefGetExecutionContextRef ()
 

Private Member Functions

size_t GetInternalInstructionSize ()
 

Private Attributes

DecodedThreadSP m_decoded_thread_sp
 Storage of the actual instructions. More...
 
size_t m_pos
 Internal instruction index currently pointing at. More...
 
llvm::Optional< DecodedThread::TscRangem_tsc_range
 Tsc range covering the current instruction. More...
 

Additional Inherited Members

- Public Types inherited from lldb_private::TraceCursor
enum  SeekType { SeekType::Beginning = 0, SeekType::Current, SeekType::End }
 Helper enum to indicate the reference point when invoking TraceCursor::Seek(). More...
 
- Protected Attributes inherited from lldb_private::TraceCursor
ExecutionContextRef m_exe_ctx_ref
 
lldb::TraceInstructionControlFlowType m_granularity
 
bool m_ignore_errors = false
 
bool m_forwards = false
 

Detailed Description

Definition at line 18 of file TraceCursorIntelPT.h.

Constructor & Destructor Documentation

◆ TraceCursorIntelPT()

TraceCursorIntelPT::TraceCursorIntelPT ( lldb::ThreadSP  thread_sp,
DecodedThreadSP  decoded_thread_sp 
)

Definition at line 20 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, m_pos, and m_tsc_range.

Member Function Documentation

◆ GetCounter()

Optional< uint64_t > TraceCursorIntelPT::GetCounter ( lldb::TraceCounter  counter_type)
overridevirtual

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.

Implements lldb_private::TraceCursor.

Definition at line 101 of file TraceCursorIntelPT.cpp.

References lldb::eTraceCounterTSC, and m_tsc_range.

◆ GetError()

const char * TraceCursorIntelPT::GetError ( )
overridevirtual

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

Returns
nullptr if the cursor is not pointing to an error in the trace. Otherwise return the actual error message.

Implements lldb_private::TraceCursor.

Definition at line 92 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetEvents()

lldb::TraceEvents TraceCursorIntelPT::GetEvents ( )
overridevirtual

Get a bitmask with a list of events that happened chronologically right before the current instruction or error, but after the previous instruction.

Returns
The bitmask of events.

Implements lldb_private::TraceCursor.

Definition at line 111 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetId()

user_id_t TraceCursorIntelPT::GetId ( ) const
overridevirtual
Returns
A unique identifier for the instruction or error this cursor is pointing to.

Implements lldb_private::TraceCursor.

Definition at line 129 of file TraceCursorIntelPT.cpp.

References m_pos.

◆ GetInstructionControlFlowType()

TraceInstructionControlFlowType TraceCursorIntelPT::GetInstructionControlFlowType ( )
overridevirtual
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.

Implements lldb_private::TraceCursor.

Definition at line 116 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

Referenced by Next().

◆ GetInternalInstructionSize()

size_t TraceCursorIntelPT::GetInternalInstructionSize ( )
private

Definition at line 30 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp.

Referenced by Next(), and Seek().

◆ GetLoadAddress()

lldb::addr_t TraceCursorIntelPT::GetLoadAddress ( )
overridevirtual
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.

Implements lldb_private::TraceCursor.

Definition at line 96 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GoToId()

bool TraceCursorIntelPT::GoToId ( lldb::user_id_t  id)
overridevirtual

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. Otherwise, false is returned and the cursor doesn't change its position.

Implements lldb_private::TraceCursor.

Definition at line 120 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, m_pos, and m_tsc_range.

◆ IsError()

bool TraceCursorIntelPT::IsError ( )
overridevirtual

Instruction or error information.

Returns
Whether the cursor points to an error or not.

Implements lldb_private::TraceCursor.

Definition at line 88 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

Referenced by Next().

◆ Next()

bool TraceCursorIntelPT::Next ( )
overridevirtual

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.

Implements lldb_private::TraceCursor.

Definition at line 34 of file TraceCursorIntelPT.cpp.

References GetInstructionControlFlowType(), GetInternalInstructionSize(), IsError(), lldb_private::TraceCursor::IsForwards(), lldb_private::TraceCursor::m_granularity, lldb_private::TraceCursor::m_ignore_errors, m_pos, and m_tsc_range.

◆ Seek()

uint64_t TraceCursorIntelPT::Seek ( int64_t  offset,
SeekType  origin 
)
overridevirtual

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.

Implements lldb_private::TraceCursor.

Definition at line 60 of file TraceCursorIntelPT.cpp.

References lldb_private::TraceCursor::Beginning, lldb_private::TraceCursor::Current, lldb_private::TraceCursor::End, GetInternalInstructionSize(), m_decoded_thread_sp, m_pos, and m_tsc_range.

Member Data Documentation

◆ m_decoded_thread_sp

DecodedThreadSP lldb_private::trace_intel_pt::TraceCursorIntelPT::m_decoded_thread_sp
private

◆ m_pos

size_t lldb_private::trace_intel_pt::TraceCursorIntelPT::m_pos
private

Internal instruction index currently pointing at.

Definition at line 50 of file TraceCursorIntelPT.h.

Referenced by GetError(), GetEvents(), GetId(), GetInstructionControlFlowType(), GetLoadAddress(), GoToId(), IsError(), Next(), Seek(), and TraceCursorIntelPT().

◆ m_tsc_range

llvm::Optional<DecodedThread::TscRange> lldb_private::trace_intel_pt::TraceCursorIntelPT::m_tsc_range
private

Tsc range covering the current instruction.

Definition at line 52 of file TraceCursorIntelPT.h.

Referenced by GetCounter(), GoToId(), Next(), Seek(), and TraceCursorIntelPT().


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