#include "lldb/Target/Trace.h"

Inheritance diagram for lldb_private::Trace:

[legend]

Collaboration diagram for lldb_private::Trace:

[legend]

Public Member Functions
virtual void	Dump (Stream *s) const =0
	Dump the trace data that this plug-in has access to. More...

virtual llvm::Error	SaveLiveTraceToDisk (FileSpec directory)=0
	Save the trace of a live process to the specified directory, which will be created if needed. More...

virtual lldb::CommandObjectSP	GetProcessTraceStartCommand (CommandInterpreter &interpreter)=0
	Get the command handle for the "process trace start" command. More...

virtual lldb::CommandObjectSP	GetThreadTraceStartCommand (CommandInterpreter &interpreter)=0
	Get the command handle for the "thread trace start" command. More...

virtual llvm::StringRef	GetSchema ()=0

virtual lldb::TraceCursorUP	GetCursor (Thread &thread)=0
	Get a TraceCursor for the given thread's trace. More...

virtual void	DumpTraceInfo (Thread &thread, Stream &s, bool verbose)=0
	Dump general info about a given thread's trace. More...

virtual bool	IsTraced (lldb::tid_t tid)=0
	Check if a thread is currently traced by this object. More...

virtual const char *	GetStartConfigurationHelp ()=0

virtual llvm::Error	Start (StructuredData::ObjectSP configuration=StructuredData::ObjectSP())=0
	Start tracing a live process. More...

virtual llvm::Error	Start (llvm::ArrayRef< lldb::tid_t > tids, StructuredData::ObjectSP configuration=StructuredData::ObjectSP())=0
	Start tracing live threads. More...

llvm::Error	Stop (llvm::ArrayRef< lldb::tid_t > tids)
	Stop tracing live threads. More...

llvm::Error	Stop ()
	Stop tracing all current and future threads of a live process. More...

llvm::Expected< const FileSpec & >	GetPostMortemTraceFile (lldb::tid_t tid)
	Get the trace file of the given post mortem thread. More...

uint32_t	GetStopID ()

Public Member Functions inherited from lldb_private::PluginInterface
	PluginInterface ()=default

virtual	~PluginInterface ()=default

virtual llvm::StringRef	GetPluginName ()=0

	PluginInterface (const PluginInterface &)=delete

PluginInterface &	operator= (const PluginInterface &)=delete

Static Public Member Functions
static llvm::Expected< lldb::TraceSP >	FindPluginForPostMortemProcess (Debugger &debugger, const llvm::json::Value &trace_session_file, llvm::StringRef session_file_dir)
	Find a trace plug-in using JSON data. More...

static llvm::Expected< lldb::TraceSP >	FindPluginForLiveProcess (llvm::StringRef plugin_name, Process &process)
	Find a trace plug-in to trace a live process. More...

static llvm::Expected< llvm::StringRef >	FindPluginSchema (llvm::StringRef plugin_name)
	Get the schema of a Trace plug-in given its name. More...

Protected Member Functions
llvm::Expected< llvm::ArrayRef< uint8_t > >	GetLiveThreadBinaryData (lldb::tid_t tid, llvm::StringRef kind)
	Get binary data of a live thread given a data identifier. More...

llvm::Expected< llvm::ArrayRef< uint8_t > >	GetLiveProcessBinaryData (llvm::StringRef kind)
	Get binary data of the current process given a data identifier. More...

llvm::Optional< size_t >	GetLiveThreadBinaryDataSize (lldb::tid_t tid, llvm::StringRef kind)
	Get the size of the data returned by GetLiveThreadBinaryData. More...

llvm::Optional< size_t >	GetLiveProcessBinaryDataSize (llvm::StringRef kind)
	Get the size of the data returned by GetLiveProcessBinaryData. More...

	Trace ()=default
	Constructor for post mortem processes. More...

	Trace (Process &live_process)
	Constructor for a live process. More...

llvm::Error	Start (const llvm::json::Value &request)
	Start tracing a live process or its threads. More...

llvm::Expected< std::string >	GetLiveProcessState ()
	Get the current tracing state of a live process and its threads. More...

virtual void	DoRefreshLiveProcessState (llvm::Expected< TraceGetStateResponse > state)=0
	Method to be overriden by the plug-in to refresh its own state. More...

void	RefreshLiveProcessState ()
	Method to be invoked by the plug-in to refresh the live process state. More...

Protected Attributes
uint32_t	m_stop_id = LLDB_INVALID_STOP_ID

Process *	m_live_process = nullptr
	Process traced by this object if doing live tracing. Otherwise it's null. More...

std::map< lldb::tid_t, std::unordered_map< std::string, size_t > >	m_live_thread_data
	tid -> data kind -> size More...

std::unordered_map< std::string, size_t >	m_live_process_data
	data kind -> size More...

Detailed Description

A plug-in interface definition class for trace information.

Trace plug-ins allow processor trace information to be loaded into LLDB so that the data can be dumped, used for reverse and forward stepping to allow introspection into the reason your process crashed or found its way to its current state.

Trace information can be loaded into a target without a process to allow introspection of the trace information during post mortem analysis, such as when loading core files.

Processor trace information can also be fetched through the process interfaces during a live debug session if your process supports gathering this information.

In order to support live tracing, the name of the plug-in should match the name of the tracing type returned by the gdb-remote packet jLLDBTraceSupported.

Definition at line 46 of file Trace.h.

Constructor & Destructor Documentation

◆ Trace() [1/2]

lldb_private::Trace::Trace ( )

protecteddefault

Constructor for post mortem processes.

◆ Trace() [2/2]

lldb_private::Trace::Trace ( Process & live_process )

inlineprotected

Constructor for a live process.

Definition at line 280 of file Trace.h.

Member Function Documentation

◆ DoRefreshLiveProcessState()

virtual void lldb_private::Trace::DoRefreshLiveProcessState ( llvm::Expected< TraceGetStateResponse > state )

protectedpure virtual

Method to be overriden by the plug-in to refresh its own state.

This is invoked by RefreshLiveProcessState when a new state is found.

Parameters

[in] state The jLLDBTraceGetState response.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ Dump()

virtual void lldb_private::Trace::Dump ( Stream * s ) const

pure virtual

Dump the trace data that this plug-in has access to.

This function will dump all of the trace data for all threads in a user readable format. Options for dumping can be added as this API is iterated on.

Parameters

[in] s A stream object to dump the information to.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ DumpTraceInfo()

virtual void lldb_private::Trace::DumpTraceInfo	(	Thread &	thread,
		Stream &	s,
		bool	verbose
	)

pure virtual

Dump general info about a given thread's trace.

Each Trace plug-in decides which data to show.

Parameters

[in]	thread	The thread that owns the trace in question.
[in]	s	The stream object where the info will be printed printed.
[in]	verbose	If true, print detailed info If false, print compact info

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ FindPluginForLiveProcess()

Expected< lldb::TraceSP > Trace::FindPluginForLiveProcess	(	llvm::StringRef	plugin_name,
		Process &	process
	)

static

Find a trace plug-in to trace a live process.

Parameters

[in]	plugin_name	Plug-in name to search.
[in]	process	Live process to trace.

Returns: A TraceSP instance, or an llvm::Error if the plug-in name doesn't match any registered plug-ins or tracing couldn't be started.

Definition at line 78 of file Trace.cpp.

References createInvalidPlugInError(), and lldb_private::Process::IsLiveDebugSession().

Referenced by lldb_private::Target::CreateTrace().

◆ FindPluginForPostMortemProcess()

Expected< lldb::TraceSP > Trace::FindPluginForPostMortemProcess	(	Debugger &	debugger,
		const llvm::json::Value &	trace_session_file,
		llvm::StringRef	session_file_dir
	)

static

Find a trace plug-in using JSON data.

When loading trace data from disk, the information for the trace data can be contained in multiple files and require plug-in specific information about the CPU. Using data like JSON provides an easy way to specify all of the settings and information that we will need to load trace data into LLDB. This structured data can include:

The plug-in name (this allows a specific plug-in to be selected)
Architecture or target triple
one or more paths to the trace data file on disk
- core trace data
- thread events or related information
shared library load information to use for this trace data that allows a target to be created so the trace information can be symbolicated so that the trace information can be displayed to the user
- shared library path
- load address
- information on how to fetch the shared library
  - path to locally cached file on disk
  - URL to download the file
Any information needed to load the trace file
- CPU information
- Custom plug-in information needed to decode the trace information correctly.

Parameters

[in]	debugger	The debugger instance where new Targets will be created as part of the JSON data parsing.
[in]	trace_session_file	The contents of the trace session file describing the trace session. See TraceSessionFileParser::BuildSchema for more information about the schema of this JSON file.
[in]	session_file_dir	The path to the directory that contains the session file. It's used to resolved relative paths in the session file.

Definition at line 62 of file Trace.cpp.

References createInvalidPlugInError(), llvm::json::fromJSON(), JSONSimpleTraceSession::trace, and JSONSimplePluginSettings::type.

◆ FindPluginSchema()

Expected< StringRef > Trace::FindPluginSchema ( llvm::StringRef plugin_name )

static

Get the schema of a Trace plug-in given its name.

Parameters

[in] plugin_name Name of the trace plugin.

Definition at line 91 of file Trace.cpp.

References createInvalidPlugInError().

◆ GetCursor()

virtual lldb::TraceCursorUP lldb_private::Trace::GetCursor ( Thread & thread )

pure virtual

Get a TraceCursor for the given thread's trace.

Returns: A TraceCursorUP. If the thread is not traced or its trace information failed to load, the corresponding error is embedded in the trace.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ GetLiveProcessBinaryData()

Expected< ArrayRef< uint8_t > > Trace::GetLiveProcessBinaryData ( llvm::StringRef kind )

protected

Get binary data of the current process given a data identifier.

Parameters

[in] kind The kind of data requested.

Returns: A vector of bytes with the requested data, or an llvm::Error in case of failures.

Definition at line 166 of file Trace.cpp.

Referenced by lldb_private::trace_intel_pt::TraceIntelPT::GetCPUInfoForLiveProcess().

◆ GetLiveProcessBinaryDataSize()

Optional< size_t > Trace::GetLiveProcessBinaryDataSize ( llvm::StringRef kind )

protected

Get the size of the data returned by GetLiveProcessBinaryData.

Definition at line 140 of file Trace.cpp.

◆ GetLiveProcessState()

Expected< std::string > Trace::GetLiveProcessState ( )

protected

Get the current tracing state of a live process and its threads.

Returns: A JSON object string with custom data depending on the trace technology, or an llvm::Error in case of errors.

Definition at line 121 of file Trace.cpp.

◆ GetLiveThreadBinaryData()

Expected< ArrayRef< uint8_t > > Trace::GetLiveThreadBinaryData	(	lldb::tid_t	tid,
		llvm::StringRef	kind
	)

protected

Get binary data of a live thread given a data identifier.

Parameters

[in]	tid	The thread whose data is requested.
[in]	kind	The kind of data requested.

Returns: A vector of bytes with the requested data, or an llvm::Error in case of failures.

Definition at line 148 of file Trace.cpp.

Referenced by lldb_private::trace_intel_pt::TraceIntelPT::GetLiveThreadBuffer().

◆ GetLiveThreadBinaryDataSize()

Optional< size_t > Trace::GetLiveThreadBinaryDataSize	(	lldb::tid_t	tid,
		llvm::StringRef	kind
	)

protected

Get the size of the data returned by GetLiveThreadBinaryData.

Definition at line 128 of file Trace.cpp.

◆ GetPostMortemTraceFile()

llvm::Expected<const FileSpec &> lldb_private::Trace::GetPostMortemTraceFile ( lldb::tid_t tid )

Get the trace file of the given post mortem thread.

◆ GetProcessTraceStartCommand()

virtual lldb::CommandObjectSP lldb_private::Trace::GetProcessTraceStartCommand ( CommandInterpreter & interpreter )

pure virtual

Get the command handle for the "process trace start" command.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

Referenced by CommandObjectProcessTraceStart::GetDelegateCommand().

◆ GetSchema()

virtual llvm::StringRef lldb_private::Trace::GetSchema ( )

pure virtual

Returns: The JSON schema of this Trace plug-in.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ GetStartConfigurationHelp()

virtual const char* lldb_private::Trace::GetStartConfigurationHelp ( )

pure virtual

Returns: A description of the parameters to use for the Trace::Start method.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ GetStopID()

uint32_t Trace::GetStopID ( )

Returns: The stop ID of the live process being traced, or an invalid stop ID if the trace is in an error or invalid state.

Definition at line 216 of file Trace.cpp.

◆ GetThreadTraceStartCommand()

virtual lldb::CommandObjectSP lldb_private::Trace::GetThreadTraceStartCommand ( CommandInterpreter & interpreter )

pure virtual

Get the command handle for the "thread trace start" command.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

Referenced by CommandObjectTraceStart::GetDelegateCommand().

◆ IsTraced()

virtual bool lldb_private::Trace::IsTraced ( lldb::tid_t tid )

pure virtual

Check if a thread is currently traced by this object.

Parameters

[in] tid The id of the thread in question.

Returns: true if the thread is traced by this instance, false otherwise.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ RefreshLiveProcessState()

void Trace::RefreshLiveProcessState ( )

protected

Method to be invoked by the plug-in to refresh the live process state.

The result is cached through the same process stop.

Definition at line 181 of file Trace.cpp.

References lldb_private::TraceThreadState::binaryData, lldb_private::TraceBinaryData::kind, lldb_private::TraceBinaryData::size, and lldb_private::TraceThreadState::tid.

Referenced by lldb_private::trace_intel_pt::TraceIntelPT::Decode(), and lldb_private::trace_intel_pt::TraceIntelPT::IsTraced().

◆ SaveLiveTraceToDisk()

virtual llvm::Error lldb_private::Trace::SaveLiveTraceToDisk ( FileSpec directory )

pure virtual

Save the trace of a live process to the specified directory, which will be created if needed.

This will also create a a file <directory>/trace.json with the main properties of the trace session, along with others files which contain the actual trace data. The trace.json file can be used later as input for the "trace load" command to load the trace in LLDB. The process being trace is not a live process, return an error.

Parameters

[in] directory The directory where the trace files will be saved.

Returns: llvm::success if the operation was successful, or an llvm::Error otherwise.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ Start() [1/3]

Error Trace::Start ( const llvm::json::Value & request )

protected

Start tracing a live process or its threads.

Parameters

[in] request JSON object with the information necessary to start tracing. In the case of gdb-remote processes, this JSON object should conform to the jLLDBTraceStart packet.

Returns: llvm::Error::success if the operation was successful, or llvm::Error otherwise.

Definition at line 100 of file Trace.cpp.

◆ Start() [2/3]

virtual llvm::Error lldb_private::Trace::Start	(	llvm::ArrayRef< lldb::tid_t >	tids,
		StructuredData::ObjectSP	configuration = `StructuredData::ObjectSP()`
	)

pure virtual

Start tracing live threads.

Parameters

[in]	tids	Threads to trace. This method tries to trace as many threads as possible.
[in]	configuration	See SBTrace::Start(const lldb::SBThread &, const lldb::SBStructuredData &) for more information.

Returns: llvm::Error::success if the operation was successful, or llvm::Error otherwise.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ Start() [3/3]

virtual llvm::Error lldb_private::Trace::Start ( StructuredData::ObjectSP configuration = StructuredData::ObjectSP() )

pure virtual

Start tracing a live process.

Parameters

[in] configuration See SBTrace::Start(const lldb::SBStructuredData &) for more information.

Returns: llvm::Error::success if the operation was successful, or llvm::Error otherwise.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ Stop() [1/2]

Error Trace::Stop ( )

Stop tracing all current and future threads of a live process.

Parameters

[in] request The information determining which threads or process to stop tracing.

Returns: llvm::Error::success if the operation was successful, or llvm::Error otherwise.

Definition at line 107 of file Trace.cpp.

◆ Stop() [2/2]

Error Trace::Stop ( llvm::ArrayRef< lldb::tid_t > tids )

Stop tracing live threads.

Parameters

[in] tids The threads to stop tracing on.

Returns: llvm::Error::success if the operation was successful, or llvm::Error otherwise.

Definition at line 114 of file Trace.cpp.

Member Data Documentation

◆ m_live_process

Process* lldb_private::Trace::m_live_process = nullptr

protected

Process traced by this object if doing live tracing. Otherwise it's null.

Definition at line 317 of file Trace.h.

Referenced by lldb_private::trace_intel_pt::TraceIntelPT::DoRefreshLiveProcessState(), and lldb_private::trace_intel_pt::TraceIntelPT::GetLiveProcess().

◆ m_live_process_data

std::unordered_map<std::string, size_t> lldb_private::Trace::m_live_process_data

protected

data kind -> size

Definition at line 322 of file Trace.h.

◆ m_live_thread_data

std::map<lldb::tid_t, std::unordered_map<std::string, size_t> > lldb_private::Trace::m_live_thread_data

protected

tid -> data kind -> size

Definition at line 320 of file Trace.h.

◆ m_stop_id

uint32_t lldb_private::Trace::m_stop_id = LLDB_INVALID_STOP_ID

protected

Definition at line 315 of file Trace.h.

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Trace() [1/2]

◆ Trace() [2/2]

Member Function Documentation

◆ DoRefreshLiveProcessState()

◆ Dump()

◆ DumpTraceInfo()

◆ FindPluginForLiveProcess()

◆ FindPluginForPostMortemProcess()

◆ FindPluginSchema()

◆ GetCursor()

◆ GetLiveProcessBinaryData()

◆ GetLiveProcessBinaryDataSize()

◆ GetLiveProcessState()

◆ GetLiveThreadBinaryData()

◆ GetLiveThreadBinaryDataSize()

◆ GetPostMortemTraceFile()

◆ GetProcessTraceStartCommand()

◆ GetSchema()

◆ GetStartConfigurationHelp()

◆ GetStopID()

◆ GetThreadTraceStartCommand()

◆ IsTraced()

◆ RefreshLiveProcessState()

◆ SaveLiveTraceToDisk()

◆ Start() [1/3]

◆ Start() [2/3]

◆ Start() [3/3]

◆ Stop() [1/2]

◆ Stop() [2/2]

Member Data Documentation

◆ m_live_process

◆ m_live_process_data

◆ m_live_thread_data

◆ m_stop_id