Class used for iterating over the instructions of a thread's trace, among other kinds of information. More...

#include <TraceCursor.h>

Inheritance diagram for lldb_private::TraceCursor:

Public Member Functions
	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 ()

Protected Attributes
ExecutionContextRef	m_exe_ctx_ref

bool	m_forwards = false

virtual lldb::TraceItemKind	GetItemKind () const =0
	Trace item information (instructions, errors and events)

bool	IsError () const

virtual llvm::StringRef	GetError () const =0

bool	IsEvent () const

virtual lldb::TraceEvent	GetEventType () const =0

const char *	GetEventTypeAsString () const

bool	IsInstruction () const

virtual lldb::addr_t	GetLoadAddress () const =0

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

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

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

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

static const char *	EventKindToString (lldb::TraceEvent event_kind)

Detailed Description

Class used for iterating over the instructions of a thread's trace, among other kinds of information.

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, then it's up to each trace plug-in to decide whether to leave the old cursor unaffected or not.

Cursor items: A TraceCursor can point at one of the following items:

Errors: 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.

Events: The cursor can also point at events in the trace, which aren't errors nor instructions. An example of an event could be a context switch in between two instructions.

Instruction: An actual instruction with a memory address.

Defaults: By default, the cursor points at the most recent item in the trace and is set up to iterate backwards. See the TraceCursor::Next() method for more documentation.

Sample usage:

TraceCursorSP cursor = trace.GetTrace(thread);

for (; cursor->HasValue(); cursor->Next()) { TraceItemKind kind = cursor->GetItemKind(); switch (cursor->GetItemKind()): case eTraceItemKindError: cout << "error found: " << cursor->GetError() << endl; break; case eTraceItemKindEvent: cout << "event found: " << cursor->GetEventTypeAsString() << endl; break; case eTraceItemKindInstruction: std::cout << "instructions found at " << cursor->GetLoadAddress() << std::endl; break; } }

As the trace might be empty or the cursor might have reached the end of the trace, you should always invoke HasValue() to make sure you don't access invalid memory.

Random accesses:

The Trace Cursor offer random acesses in the trace via two APIs:

TraceCursor::Seek(): Unlike the TraceCursor::Next() API, which moves instruction by instruction, the TraceCursor::Seek() method can be used to reposition the cursor to an offset of the end, beginning, or current position of the trace.

TraceCursor::GetId() / TraceCursor::SetId(id): Each item (error or instruction) in the trace has a numeric identifier which is defined by the trace plug-in. It's possible to access the id of the current item using GetId(), and to reposition the cursor to a given id using SetId(id).

You can read more in the documentation of these methods.

Definition at line 94 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 18 of file TraceCursor.cpp.

◆ ~TraceCursor()

virtual lldb_private::TraceCursor::~TraceCursor ( )

virtualdefault

Member Function Documentation

◆ EventKindToString()

const char * TraceCursor::EventKindToString ( lldb::TraceEvent event_kind )

static

Returns: A human-readable description of the given event.

Definition at line 45 of file TraceCursor.cpp.

References lldb::eTraceEventCPUChanged, lldb::eTraceEventDisabledHW, lldb::eTraceEventDisabledSW, lldb::eTraceEventHWClockTick, and lldb::eTraceEventSyncPoint.

Referenced by OutputWriterJSON::DumpEvent(), lldb_private::trace_intel_pt::TraceIntelPT::DumpTraceInfo(), GetEventTypeAsString(), and OutputWriterCLI::TraceItem().

◆ GetCPU()

virtual lldb::cpu_id_t lldb_private::TraceCursor::GetCPU ( ) const

pure virtual

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.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetError()

virtual llvm::StringRef lldb_private::TraceCursor::GetError ( ) const

pure virtual

Returns: The error message the cursor is pointing at.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetEventType()

virtual lldb::TraceEvent lldb_private::TraceCursor::GetEventType ( ) const

pure virtual

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

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

Referenced by GetEventTypeAsString().

◆ GetEventTypeAsString()

const char * TraceCursor::GetEventTypeAsString ( ) const

Returns: A human-readable description of the event this cursor is pointing at.

Definition at line 41 of file TraceCursor.cpp.

References EventKindToString(), and GetEventType().

◆ GetExecutionContextRef()

ExecutionContextRef & TraceCursor::GetExecutionContextRef ( )

Returns: The ExecutionContextRef of the backing thread from the creation time of this cursor.

Definition at line 21 of file TraceCursor.cpp.

References m_exe_ctx_ref.

◆ GetHWClock()

virtual std::optional< uint64_t > lldb_private::TraceCursor::GetHWClock ( ) const

pure virtual

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.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetId()

virtual lldb::user_id_t lldb_private::TraceCursor::GetId ( ) const

pure virtual

Returns: A unique identifier for the instruction or error this cursor is pointing to.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetItemKind()

virtual lldb::TraceItemKind lldb_private::TraceCursor::GetItemKind ( ) const

pure virtual

Trace item information (instructions, errors and events)

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

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

Referenced by IsError(), IsEvent(), and IsInstruction().

◆ GetLoadAddress()

virtual lldb::addr_t lldb_private::TraceCursor::GetLoadAddress ( ) const

pure virtual

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

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetSyncPointMetadata()

virtual std::optional< std::string > lldb_private::TraceCursor::GetSyncPointMetadata ( ) const

pure virtual

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.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GetWallClockTime()

virtual std::optional< double > lldb_private::TraceCursor::GetWallClockTime ( ) const

pure virtual

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.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ GoToId()

virtual bool lldb_private::TraceCursor::GoToId ( lldb::user_id_t id )

pure virtual

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.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ HasId()

virtual bool lldb_private::TraceCursor::HasId ( lldb::user_id_t id ) const

pure virtual

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

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ HasValue()

virtual bool lldb_private::TraceCursor::HasValue ( ) const

pure virtual

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

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ IsError()

bool TraceCursor::IsError ( ) const

Returns: Whether the cursor points to an error or not.

Definition at line 29 of file TraceCursor.cpp.

References lldb::eTraceItemKindError, and GetItemKind().

◆ IsEvent()

bool TraceCursor::IsEvent ( ) const

Returns: Whether the cursor points to an event or not.

Definition at line 33 of file TraceCursor.cpp.

References lldb::eTraceItemKindEvent, and GetItemKind().

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

References m_forwards.

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

◆ IsInstruction()

bool TraceCursor::IsInstruction ( ) const

Returns: Whether the cursor points to an instruction.

Definition at line 37 of file TraceCursor.cpp.

References lldb::eTraceItemKindInstruction, and GetItemKind().

◆ Next()

virtual void lldb_private::TraceCursor::Next ( )

pure virtual

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

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

◆ Seek()

virtual bool lldb_private::TraceCursor::Seek	(	int64_t	offset,
		lldb::TraceCursorSeekType	origin
	)

pure virtual

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.

Implemented in lldb_private::trace_intel_pt::TraceCursorIntelPT.

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

◆ SetForwards()

void TraceCursor::SetForwards ( bool forwards )

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

Parameters

[in] forwards If true, then the traversal will be forwards, otherwise backwards.

Definition at line 25 of file TraceCursor.cpp.

References m_forwards.

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

Member Data Documentation

◆ m_exe_ctx_ref

ExecutionContextRef lldb_private::TraceCursor::m_exe_ctx_ref

protected

Definition at line 288 of file TraceCursor.h.

Referenced by GetExecutionContextRef().

◆ m_forwards

bool lldb_private::TraceCursor::m_forwards = false

protected

Definition at line 289 of file TraceCursor.h.

Referenced by IsForwards(), and SetForwards().

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

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TraceCursor()

◆ ~TraceCursor()

Member Function Documentation

◆ EventKindToString()

◆ GetCPU()

◆ GetError()

◆ GetEventType()

◆ GetEventTypeAsString()

◆ GetExecutionContextRef()

◆ GetHWClock()

◆ GetId()

◆ GetItemKind()

◆ GetLoadAddress()

◆ GetSyncPointMetadata()

◆ GetWallClockTime()

◆ GoToId()

◆ HasId()

◆ HasValue()

◆ IsError()

◆ IsEvent()

◆ IsForwards()

◆ IsInstruction()

◆ Next()

◆ Seek()

◆ SetForwards()

Member Data Documentation

◆ m_exe_ctx_ref

◆ m_forwards