#include <TraceCursorIntelPT.h>

Inheritance diagram for lldb_private::trace_intel_pt::TraceCursorIntelPT:

Collaboration diagram for lldb_private::trace_intel_pt::TraceCursorIntelPT:

[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...

ExecutionContextRef &	GetExecutionContextRef ()

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::TscRange >	m_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_type The 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]	offset	How many items to move forwards (if positive) or backwards (if negative) from the given origin point.
[in]	origin	The 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

Storage of the actual instructions.

Definition at line 48 of file TraceCursorIntelPT.h.

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

◆ 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:

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ TraceCursorIntelPT()

Member Function Documentation

◆ GetCounter()

◆ GetError()

◆ GetEvents()

◆ GetId()

◆ GetInstructionControlFlowType()

◆ GetInternalInstructionSize()

◆ GetLoadAddress()

◆ GoToId()

◆ IsError()

◆ Next()

◆ Seek()

Member Data Documentation

◆ m_decoded_thread_sp

◆ m_pos

◆ m_tsc_range