#include <TraceCursorIntelPT.h>

Inheritance diagram for lldb_private::trace_intel_pt::TraceCursorIntelPT:

Public Member Functions
	TraceCursorIntelPT (lldb::ThreadSP thread_sp, DecodedThreadSP decoded_thread_sp, const std::optional< LinuxPerfZeroTscConversion > &tsc_conversion, std::optional< uint64_t > beginning_of_time_nanos)

bool	Seek (int64_t offset, lldb::TraceCursorSeekType origin) override
	Make the cursor point to an item in the trace based on an origin point and an offset.

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

bool	HasValue () const override

llvm::StringRef	GetError () const override

lldb::addr_t	GetLoadAddress () const override

lldb::TraceEvent	GetEventType () const override

lldb::cpu_id_t	GetCPU () const override
	Get the CPU associated with the current trace item.

std::optional< uint64_t >	GetHWClock () const override
	Get the last hardware clock value that was emitted before the current trace item.

lldb::TraceItemKind	GetItemKind () const override
	Trace item information (instructions, errors and events)

bool	GoToId (lldb::user_id_t id) override
	Instruction identifiers:

lldb::user_id_t	GetId () const override

bool	HasId (lldb::user_id_t id) const override

std::optional< double >	GetWallClockTime () const override
	Get the approximate wall clock time in nanoseconds at which the current trace item was executed.

std::optional< std::string >	GetSyncPointMetadata () const override
	Get some metadata associated with a synchronization point event.

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.

virtual	~TraceCursor ()=default

void	SetForwards (bool forwards)
	Set the direction to use in the TraceCursor::Next() method.

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

virtual void	Next ()=0
	Move the cursor to the next item (instruction or error).

virtual bool	HasValue () const =0

virtual bool	GoToId (lldb::user_id_t id)=0
	Instruction identifiers:

virtual bool	HasId (lldb::user_id_t id) const =0

virtual lldb::user_id_t	GetId () const =0

virtual bool	Seek (int64_t offset, lldb::TraceCursorSeekType origin)=0
	Make the cursor point to an item in the trace based on an origin point and an offset.

ExecutionContextRef &	GetExecutionContextRef ()

bool	IsError () const

bool	IsEvent () const

const char *	GetEventTypeAsString () const

bool	IsInstruction () const

Private Member Functions
void	ClearTimingRangesIfInvalid ()
	Clear the current TSC and nanoseconds ranges if after moving they are not valid anymore.

const std::optional< DecodedThread::TSCRange > &	GetTSCRange () const
	Get or calculate the TSC range that includes the current trace item.

const std::optional< DecodedThread::NanosecondsRange > &	GetNanosecondsRange () const
	Get or calculate the TSC range that includes the current trace item.

Private Attributes
DecodedThreadSP	m_decoded_thread_sp
	Storage of the actual instructions.

int64_t	m_pos
	Internal instruction index currently pointing at.


std::optional< LinuxPerfZeroTscConversion >	m_tsc_conversion
	Timing information and cached values.

std::optional< uint64_t >	m_beginning_of_time_nanos
	Lowest nanoseconds timestamp seen in any thread trace, std::nullopt if not available at all.

std::optional< DecodedThread::TSCRange >	m_tsc_range
	Range of trace items with the same TSC that includes the current trace item, std::nullopt if not calculated or not available.

bool	m_tsc_range_calculated = false

std::optional< DecodedThread::NanosecondsRange >	m_nanoseconds_range
	Range of trace items with the same non-interpolated timestamps in nanoseconds that includes the current trace item, std::nullopt if not calculated or not available.

bool	m_nanoseconds_range_calculated = false

Additional Inherited Members
Static Public Member Functions inherited from lldb_private::TraceCursor
static const char *	EventKindToString (lldb::TraceEvent event_kind)

Protected Attributes inherited from lldb_private::TraceCursor
ExecutionContextRef	m_exe_ctx_ref

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,
		const std::optional< LinuxPerfZeroTscConversion > &	tsc_conversion,
		std::optional< uint64_t >	beginning_of_time_nanos
	)

Definition at line 20 of file TraceCursorIntelPT.cpp.

References lldb::eTraceCursorSeekTypeEnd, and Seek().

Member Function Documentation

◆ ClearTimingRangesIfInvalid()

void TraceCursorIntelPT::ClearTimingRangesIfInvalid ( )

private

Clear the current TSC and nanoseconds ranges if after moving they are not valid anymore.

Definition at line 35 of file TraceCursorIntelPT.cpp.

References m_nanoseconds_range, m_nanoseconds_range_calculated, m_pos, m_tsc_range, and m_tsc_range_calculated.

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

◆ GetCPU()

lldb::cpu_id_t TraceCursorIntelPT::GetCPU ( ) const

overridevirtual

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 an eTraceEventCPUChanged event is fired.

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

Implements lldb_private::TraceCursor.

Definition at line 120 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetError()

llvm::StringRef TraceCursorIntelPT::GetError ( ) const

overridevirtual

Returns: The error message the cursor is pointing at.

Implements lldb_private::TraceCursor.

Definition at line 98 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetEventType()

lldb::TraceEvent TraceCursorIntelPT::GetEventType ( ) const

overridevirtual

Returns: The specific kind of event the cursor is pointing at.

Implements lldb_private::TraceCursor.

Definition at line 124 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetHWClock()

std::optional< uint64_t > TraceCursorIntelPT::GetHWClock ( ) const

overridevirtual

Get the last hardware clock value that was emitted before the current trace item.

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

Returns: The requested HW clock value, or std::nullopt if this information is not available for the current item.

Implements lldb_private::TraceCursor.

Definition at line 106 of file TraceCursorIntelPT.cpp.

References GetTSCRange().

◆ 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 140 of file TraceCursorIntelPT.cpp.

References m_pos.

◆ GetItemKind()

lldb::TraceItemKind TraceCursorIntelPT::GetItemKind ( ) const

overridevirtual

Trace item information (instructions, errors and events)

Returns: The kind of item the cursor is pointing at.

Implements lldb_private::TraceCursor.

Definition at line 94 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetLoadAddress()

lldb::addr_t TraceCursorIntelPT::GetLoadAddress ( ) const

overridevirtual

Returns: The load address of the instruction the cursor is pointing at.

Implements lldb_private::TraceCursor.

Definition at line 102 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetNanosecondsRange()

const std::optional< DecodedThread::NanosecondsRange > & TraceCursorIntelPT::GetNanosecondsRange ( ) const

private

Get or calculate the TSC range that includes the current trace item.

Definition at line 62 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, m_nanoseconds_range, m_nanoseconds_range_calculated, and m_pos.

Referenced by GetWallClockTime().

◆ GetSyncPointMetadata()

std::optional< std::string > TraceCursorIntelPT::GetSyncPointMetadata ( ) const

overridevirtual

Get some metadata associated with a synchronization point event.

As different trace technologies might have different values for this, we return a string for flexibility.

Returns: A string representing some metadata associated with a eTraceEventSyncPoint event. std::nullopt if no metadata is available.

Implements lldb_private::TraceCursor.

Definition at line 142 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetTSCRange()

const std::optional< DecodedThread::TSCRange > & TraceCursorIntelPT::GetTSCRange ( ) const

private

Get or calculate the TSC range that includes the current trace item.

Definition at line 53 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, m_pos, m_tsc_range, and m_tsc_range_calculated.

Referenced by GetHWClock().

◆ GetWallClockTime()

std::optional< double > TraceCursorIntelPT::GetWallClockTime ( ) const

overridevirtual

Get the approximate wall clock time in nanoseconds at which the current trace item was executed.

Each trace plug-in has a different definition for what time 0 means.

Returns: The approximate wall clock time for the trace item, or std::nullopt if not available.

Implements lldb_private::TraceCursor.

Definition at line 112 of file TraceCursorIntelPT.cpp.

References GetNanosecondsRange(), m_beginning_of_time_nanos, m_pos, and m_tsc_conversion.

◆ 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 to it. Otherwise, false is returned and the cursor now points to an invalid item, i.e. calling HasValue() will return false.

Implements lldb_private::TraceCursor.

Definition at line 128 of file TraceCursorIntelPT.cpp.

References ClearTimingRangesIfInvalid(), HasId(), and m_pos.

◆ HasId()

bool TraceCursorIntelPT::HasId ( lldb::user_id_t id ) const

overridevirtual

Returns: true if and only if there's an instruction item with the given id.

Implements lldb_private::TraceCursor.

Definition at line 136 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp.

Referenced by GoToId().

◆ HasValue()

bool TraceCursorIntelPT::HasValue ( ) const

overridevirtual

Returns: true if the cursor is pointing to a valid item. false if the cursor has reached the end of the trace.

Implements lldb_private::TraceCursor.

Definition at line 89 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

Referenced by Seek().

◆ Next()

void TraceCursorIntelPT::Next ( )

overridevirtual

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

Implements lldb_private::TraceCursor.

Definition at line 30 of file TraceCursorIntelPT.cpp.

References ClearTimingRangesIfInvalid(), lldb_private::TraceCursor::IsForwards(), and m_pos.

◆ Seek()

bool TraceCursorIntelPT::Seek	(	int64_t	offset,
		lldb::TraceCursorSeekType	origin
	)

overridevirtual

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]	offset	How 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]	origin	The reference point to use when moving the cursor.

Returns: true if and only if the cursor ends up pointing to a valid item.

Implements lldb_private::TraceCursor.

Definition at line 71 of file TraceCursorIntelPT.cpp.

References ClearTimingRangesIfInvalid(), lldb::eTraceCursorSeekTypeBeginning, lldb::eTraceCursorSeekTypeCurrent, lldb::eTraceCursorSeekTypeEnd, HasValue(), m_decoded_thread_sp, and m_pos.

Referenced by TraceCursorIntelPT().

Member Data Documentation

◆ m_beginning_of_time_nanos

std::optional<uint64_t> lldb_private::trace_intel_pt::TraceCursorIntelPT::m_beginning_of_time_nanos

private

Lowest nanoseconds timestamp seen in any thread trace, std::nullopt if not available at all.

Definition at line 77 of file TraceCursorIntelPT.h.

Referenced by GetWallClockTime().

◆ m_decoded_thread_sp

DecodedThreadSP lldb_private::trace_intel_pt::TraceCursorIntelPT::m_decoded_thread_sp

private

Storage of the actual instructions.

Definition at line 66 of file TraceCursorIntelPT.h.

Referenced by GetCPU(), GetError(), GetEventType(), GetItemKind(), GetLoadAddress(), GetNanosecondsRange(), GetSyncPointMetadata(), GetTSCRange(), HasId(), HasValue(), and Seek().

◆ m_nanoseconds_range

std::optional<DecodedThread::NanosecondsRange> lldb_private::trace_intel_pt::TraceCursorIntelPT::m_nanoseconds_range

mutableprivate

Range of trace items with the same non-interpolated timestamps in nanoseconds that includes the current trace item, std::nullopt if not calculated or not available.

Definition at line 85 of file TraceCursorIntelPT.h.

Referenced by ClearTimingRangesIfInvalid(), and GetNanosecondsRange().

◆ m_nanoseconds_range_calculated

bool lldb_private::trace_intel_pt::TraceCursorIntelPT::m_nanoseconds_range_calculated = false

mutableprivate

Definition at line 86 of file TraceCursorIntelPT.h.

Referenced by ClearTimingRangesIfInvalid(), and GetNanosecondsRange().

◆ m_pos

int64_t lldb_private::trace_intel_pt::TraceCursorIntelPT::m_pos

private

Internal instruction index currently pointing at.

Definition at line 68 of file TraceCursorIntelPT.h.

Referenced by ClearTimingRangesIfInvalid(), GetCPU(), GetError(), GetEventType(), GetId(), GetItemKind(), GetLoadAddress(), GetNanosecondsRange(), GetSyncPointMetadata(), GetTSCRange(), GetWallClockTime(), GoToId(), HasValue(), Next(), and Seek().

◆ m_tsc_conversion

std::optional<LinuxPerfZeroTscConversion> lldb_private::trace_intel_pt::TraceCursorIntelPT::m_tsc_conversion

private

Timing information and cached values.

TSC -> nanos conversion utility. std::nullopt if not available at all.

Definition at line 74 of file TraceCursorIntelPT.h.

Referenced by GetWallClockTime().

◆ m_tsc_range

std::optional<DecodedThread::TSCRange> lldb_private::trace_intel_pt::TraceCursorIntelPT::m_tsc_range

mutableprivate

Range of trace items with the same TSC that includes the current trace item, std::nullopt if not calculated or not available.

Definition at line 80 of file TraceCursorIntelPT.h.

Referenced by ClearTimingRangesIfInvalid(), and GetTSCRange().

◆ m_tsc_range_calculated

bool lldb_private::trace_intel_pt::TraceCursorIntelPT::m_tsc_range_calculated = false

mutableprivate

Definition at line 81 of file TraceCursorIntelPT.h.

Referenced by ClearTimingRangesIfInvalid(), and GetTSCRange().

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

◆ ClearTimingRangesIfInvalid()

◆ GetCPU()

◆ GetError()

◆ GetEventType()

◆ GetHWClock()

◆ GetId()

◆ GetItemKind()

◆ GetLoadAddress()

◆ GetNanosecondsRange()

◆ GetSyncPointMetadata()

◆ GetTSCRange()

◆ GetWallClockTime()

◆ GoToId()

◆ HasId()

◆ HasValue()

◆ Next()

◆ Seek()

Member Data Documentation

◆ m_beginning_of_time_nanos

◆ m_decoded_thread_sp

◆ m_nanoseconds_range

◆ m_nanoseconds_range_calculated

◆ m_pos

◆ m_tsc_conversion

◆ m_tsc_range

◆ m_tsc_range_calculated