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, const llvm::Optional< LinuxPerfZeroTscConversion > &tsc_conversion, llvm::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. More...
 
void Next () override
 Move the cursor to the next item (instruction or error). More...
 
bool HasValue () const override
 
const char * 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. More...
 
llvm::Optional< uint64_t > GetHWClock () const override
 Get the last hardware clock value that was emitted before the current trace item. More...
 
lldb::TraceItemKind GetItemKind () const override
 Trace item information (instructions, errors and events) More...
 
bool GoToId (lldb::user_id_t id) override
 Instruction identifiers: More...
 
lldb::user_id_t GetId () const override
 
bool HasId (lldb::user_id_t id) const override
 
llvm::Optional< double > GetWallClockTime () const override
 Get the approximate wall clock time in nanoseconds at which the current trace item was executed. More...
 
llvm::Optional< std::stringGetSyncPointMetadata () const override
 Get some metadata associated with a synchronization point event. More...
 
- 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 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 ()
 
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. More...
 
const llvm::Optional< DecodedThread::TSCRange > & GetTSCRange () const
 Get or calculate the TSC range that includes the current trace item. More...
 
const llvm::Optional< DecodedThread::NanosecondsRange > & GetNanosecondsRange () const
 Get or calculate the TSC range that includes the current trace item. More...
 

Private Attributes

DecodedThreadSP m_decoded_thread_sp
 Storage of the actual instructions. More...
 
int64_t m_pos
 Internal instruction index currently pointing at. More...
 
llvm::Optional< LinuxPerfZeroTscConversionm_tsc_conversion
 Timing information and cached values. More...
 
llvm::Optional< uint64_t > m_beginning_of_time_nanos
 Lowest nanoseconds timestamp seen in any thread trace, None if not available at all. More...
 
llvm::Optional< DecodedThread::TSCRangem_tsc_range
 Range of trace items with the same TSC that includes the current trace item, None if not calculated or not available. More...
 
bool m_tsc_range_calculated = false
 
llvm::Optional< DecodedThread::NanosecondsRangem_nanoseconds_range
 Range of trace items with the same non-interpolated timestamps in nanoseconds that includes the current trace item, None if not calculated or not available. More...
 
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 17 of file TraceCursorIntelPT.h.

Constructor & Destructor Documentation

◆ TraceCursorIntelPT()

TraceCursorIntelPT::TraceCursorIntelPT ( lldb::ThreadSP  thread_sp,
DecodedThreadSP  decoded_thread_sp,
const llvm::Optional< LinuxPerfZeroTscConversion > &  tsc_conversion,
llvm::Optional< uint64_t >  beginning_of_time_nanos 
)

Definition at line 19 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 34 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 119 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetError()

const char * TraceCursorIntelPT::GetError ( ) const
overridevirtual
Returns
The error message the cursor is pointing at.

Implements lldb_private::TraceCursor.

Definition at line 97 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 123 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetHWClock()

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 llvm::None if this information is not available for the current item.

Implements lldb_private::TraceCursor.

Definition at line 105 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 139 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 93 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 101 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetNanosecondsRange()

const Optional< DecodedThread::NanosecondsRange > & TraceCursorIntelPT::GetNanosecondsRange ( ) const
private

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

Definition at line 61 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, m_nanoseconds_range, m_nanoseconds_range_calculated, and m_pos.

Referenced by GetWallClockTime().

◆ GetSyncPointMetadata()

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. None if no metadata is available.

Implements lldb_private::TraceCursor.

Definition at line 141 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, and m_pos.

◆ GetTSCRange()

const Optional< DecodedThread::TSCRange > & TraceCursorIntelPT::GetTSCRange ( ) const
private

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

Definition at line 52 of file TraceCursorIntelPT.cpp.

References m_decoded_thread_sp, m_pos, m_tsc_range, and m_tsc_range_calculated.

Referenced by GetHWClock().

◆ GetWallClockTime()

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 llvm::None if not available.

Implements lldb_private::TraceCursor.

Definition at line 111 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 127 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 135 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 88 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 29 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]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.

Implements lldb_private::TraceCursor.

Definition at line 70 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

llvm::Optional<uint64_t> lldb_private::trace_intel_pt::TraceCursorIntelPT::m_beginning_of_time_nanos
private

Lowest nanoseconds timestamp seen in any thread trace, None if not available at all.

Definition at line 76 of file TraceCursorIntelPT.h.

Referenced by GetWallClockTime().

◆ m_decoded_thread_sp

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

◆ m_nanoseconds_range

llvm::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, None if not calculated or not available.

Definition at line 84 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 85 of file TraceCursorIntelPT.h.

Referenced by ClearTimingRangesIfInvalid(), and GetNanosecondsRange().

◆ m_pos

int64_t lldb_private::trace_intel_pt::TraceCursorIntelPT::m_pos
private

◆ m_tsc_conversion

llvm::Optional<LinuxPerfZeroTscConversion> lldb_private::trace_intel_pt::TraceCursorIntelPT::m_tsc_conversion
private

Timing information and cached values.

TSC -> nanos conversion utility. None if not available at all.

Definition at line 73 of file TraceCursorIntelPT.h.

Referenced by GetWallClockTime().

◆ m_tsc_range

llvm::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, None if not calculated or not available.

Definition at line 79 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 80 of file TraceCursorIntelPT.h.

Referenced by ClearTimingRangesIfInvalid(), and GetTSCRange().


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