A plug-in interface definition class for trace information. More...

#include "lldb/Target/Trace.h"

Inheritance diagram for lldb_private::Trace:

[legend]

Classes
struct	Storage
	We package all the data that can change upon process stops to make sure this contract is very visible. More...

Public Types
using	OnBinaryDataReadCallback = std::function< llvm::Error(llvm::ArrayRef< uint8_t > data)>

using	OnCpusBinaryDataReadCallback = std::function< llvm::Error(const llvm::DenseMap< lldb::cpu_id_t, llvm::ArrayRef< uint8_t > > &cpu_to_data)>

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

virtual llvm::Expected< FileSpec >	SaveToDisk (FileSpec directory, bool compact)=0
	Save the trace to the specified directory, which will be created if needed.

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

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

virtual llvm::StringRef	GetSchema ()=0

virtual llvm::Expected< lldb::TraceCursorSP >	CreateNewCursor (Thread &thread)=0
	Get a TraceCursor for the given thread's trace.

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

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

virtual const char *	GetStartConfigurationHelp ()=0

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

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

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

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

uint32_t	GetStopID ()

llvm::Error	OnThreadBinaryDataRead (lldb::tid_t tid, llvm::StringRef kind, OnBinaryDataReadCallback callback)
	Fetch binary data associated with a thread, either live or postmortem, and pass it to the given callback.

llvm::Error	OnCpuBinaryDataRead (lldb::cpu_id_t cpu_id, llvm::StringRef kind, OnBinaryDataReadCallback callback)
	Fetch binary data associated with a cpu, either live or postmortem, and pass it to the given callback.

llvm::Error	OnAllCpusBinaryDataRead (llvm::StringRef kind, OnCpusBinaryDataReadCallback callback)
	Similar to OnCpuBinaryDataRead but this is able to fetch the same data from all cpus at once.

std::vector< Process * >	GetAllProcesses ()

llvm::ArrayRef< lldb::cpu_id_t >	GetTracedCpus ()

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 &bundle_description, llvm::StringRef session_file_dir)
	Find a trace plug-in using JSON data.

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

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

static llvm::Expected< lldb::TraceSP >	LoadPostMortemTraceFromFile (Debugger &debugger, const FileSpec &trace_description_file)
	Load a trace from a trace description file and create Targets, Processes and Threads based on the contents of such file.

static llvm::Error	OnDataFileRead (FileSpec file, OnBinaryDataReadCallback callback)
	Helper method for reading a data file and passing its data to the given callback.

Protected Member Functions
Process *	GetLiveProcess ()
	Get the currently traced live process.

llvm::ArrayRef< Process * >	GetPostMortemProcesses ()
	Get the currently traced postmortem processes.

llvm::Expected< std::vector< uint8_t > >	GetLiveTraceBinaryData (const TraceGetBinaryDataRequest &request, uint64_t expected_size)
	Dispatcher for live trace data requests with some additional error checking.

llvm::Error	OnLiveThreadBinaryDataRead (lldb::tid_t tid, llvm::StringRef kind, OnBinaryDataReadCallback callback)
	Implementation of OnThreadBinaryDataRead() for live threads.

llvm::Error	OnLiveCpuBinaryDataRead (lldb::cpu_id_t cpu, llvm::StringRef kind, OnBinaryDataReadCallback callback)
	Implementation of OnLiveBinaryDataRead() for live cpus.

llvm::Error	OnPostMortemThreadBinaryDataRead (lldb::tid_t tid, llvm::StringRef kind, OnBinaryDataReadCallback callback)
	Implementation of OnThreadBinaryDataRead() for post mortem threads.

llvm::Error	OnPostMortemCpuBinaryDataRead (lldb::cpu_id_t cpu_id, llvm::StringRef kind, OnBinaryDataReadCallback callback)
	Implementation of OnCpuBinaryDataRead() for post mortem cpus.

llvm::Expected< FileSpec >	GetPostMortemThreadDataFile (lldb::tid_t tid, llvm::StringRef kind)
	Get the file path containing data of a postmortem thread given a data identifier.

llvm::Expected< FileSpec >	GetPostMortemCpuDataFile (lldb::cpu_id_t cpu_id, llvm::StringRef kind)
	Get the file path containing data of a postmortem cpu given a data identifier.

void	SetPostMortemThreadDataFile (lldb::tid_t tid, llvm::StringRef kind, FileSpec file_spec)
	Associate a given thread with a data file using a data identifier.

void	SetPostMortemCpuDataFile (lldb::cpu_id_t cpu_id, llvm::StringRef kind, FileSpec file_spec)
	Associate a given cpu with a data file using a data identifier.

llvm::Expected< std::vector< uint8_t > >	GetLiveThreadBinaryData (lldb::tid_t tid, llvm::StringRef kind)
	Get binary data of a live thread given a data identifier.

llvm::Expected< std::vector< uint8_t > >	GetLiveCpuBinaryData (lldb::cpu_id_t cpu_id, llvm::StringRef kind)
	Get binary data of a live cpu given a data identifier.

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

std::optional< uint64_t >	GetLiveThreadBinaryDataSize (lldb::tid_t tid, llvm::StringRef kind)
	Get the size of the data returned by GetLiveThreadBinaryData.

std::optional< uint64_t >	GetLiveCpuBinaryDataSize (lldb::cpu_id_t cpu_id, llvm::StringRef kind)
	Get the size of the data returned by GetLiveCpuBinaryData.

std::optional< uint64_t >	GetLiveProcessBinaryDataSize (llvm::StringRef kind)
	Get the size of the data returned by GetLiveProcessBinaryData.

	Trace (llvm::ArrayRef< lldb::ProcessSP > postmortem_processes, std::optional< std::vector< lldb::cpu_id_t > > postmortem_cpus)
	Constructor for post mortem processes.

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

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

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

virtual llvm::Error	DoRefreshLiveProcessState (TraceGetStateResponse state, llvm::StringRef json_response)=0
	Method to be overriden by the plug-in to refresh its own state.

std::vector< Process * >	GetTracedProcesses ()
	Return the list of processes traced by this instance.

const char *	RefreshLiveProcessState ()
	Method to be invoked by the plug-in to refresh the live process state.

Private Member Functions
Storage &	GetUpdatedStorage ()
	Get the storage after refreshing the data in the case of a live process.

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

struct lldb_private::Trace::Storage	m_storage

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 47 of file Trace.h.

Member Typedef Documentation

◆ OnBinaryDataReadCallback

using lldb_private::Trace::OnBinaryDataReadCallback = std::function<llvm::Error(llvm::ArrayRef<uint8_t> data)>

Definition at line 260 of file Trace.h.

◆ OnCpusBinaryDataReadCallback

using lldb_private::Trace::OnCpusBinaryDataReadCallback = std::function<llvm::Error( const llvm::DenseMap<lldb::cpu_id_t, llvm::ArrayRef<uint8_t> > &cpu_to_data)>

Definition at line 262 of file Trace.h.

Constructor & Destructor Documentation

◆ Trace() [1/2]

lldb_private::Trace::Trace	(	llvm::ArrayRef< lldb::ProcessSP >	postmortem_processes,
		std::optional< std::vector< lldb::cpu_id_t > >	postmortem_cpus
	)

protected

Constructor for post mortem processes.

◆ Trace() [2/2]

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

inlineprotected

Constructor for a live process.

Definition at line 483 of file Trace.h.

Member Function Documentation

◆ CreateNewCursor()

virtual llvm::Expected< lldb::TraceCursorSP > lldb_private::Trace::CreateNewCursor ( Thread & thread )

pure virtual

Get a TraceCursor for the given thread's trace.

Returns: A TraceCursorSP. If the thread is not traced or its trace information failed to load, an llvm::Error is returned.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ DoRefreshLiveProcessState()

virtual llvm::Error lldb_private::Trace::DoRefreshLiveProcessState	(	TraceGetStateResponse	state,
		llvm::StringRef	json_response
	)

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.
[in]	json_response	The original JSON response as a string. It might be useful to redecode it if it contains custom data for a specific trace plug-in.

Returns: Error::success() if this operation succeedes, or an actual error otherwise.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

Referenced by RefreshLiveProcessState().

◆ 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,
		bool	json
	)

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 134 of file Trace.cpp.

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

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

◆ FindPluginForPostMortemProcess()

Expected< lldb::TraceSP > Trace::FindPluginForPostMortemProcess	(	Debugger &	debugger,
		const llvm::json::Value &	bundle_description,
		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
- cpu 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]	bundle_description	The trace bundle description object describing the trace session.
[in]	bundle_dir	The path to the directory that contains the trace bundle.

Definition at line 119 of file Trace.cpp.

References createInvalidPlugInError(), llvm::json::fromJSON(), lldb_private::PluginManager::GetTraceCreateCallback(), and JSONSimpleTraceBundleDescription::type.

Referenced by LoadPostMortemTraceFromFile().

◆ 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 147 of file Trace.cpp.

References createInvalidPlugInError(), and lldb_private::PluginManager::GetTraceSchema().

Referenced by CommandObjectTraceSchema::DoExecute().

◆ GetAllProcesses()

std::vector< Process * > Trace::GetAllProcesses ( )

Returns: All the currently traced processes.

Definition at line 363 of file Trace.cpp.

References GetLiveProcess(), and GetPostMortemProcesses().

Referenced by BuildKernelSection(), BuildProcessesSection(), and WriteContextSwitchTrace().

◆ GetLiveCpuBinaryData()

Expected< std::vector< uint8_t > > Trace::GetLiveCpuBinaryData	(	lldb::cpu_id_t	cpu_id,
		llvm::StringRef	kind
	)

protected

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

Parameters

[in]	cpu_id	The cpu 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 247 of file Trace.cpp.

References GetLiveCpuBinaryDataSize(), lldb_private::PluginInterface::GetPluginName(), m_live_process, and lldb_private::Process::TraceGetBinaryData().

Referenced by OnLiveCpuBinaryDataRead().

◆ GetLiveCpuBinaryDataSize()

std::optional< uint64_t > Trace::GetLiveCpuBinaryDataSize	(	lldb::cpu_id_t	cpu_id,
		llvm::StringRef	kind
	)

protected

Get the size of the data returned by GetLiveCpuBinaryData.

Definition at line 193 of file Trace.cpp.

References GetUpdatedStorage(), lldb_private::Trace::Storage::live_cpu_data_sizes, and Lookup().

Referenced by GetLiveCpuBinaryData().

◆ GetLiveProcess()

Process * Trace::GetLiveProcess ( )

protected

Get the currently traced live process.

Returns: If it's not a live process, return nullptr.

Definition at line 357 of file Trace.cpp.

References m_live_process.

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

◆ GetLiveProcessBinaryData()

Expected< std::vector< 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 265 of file Trace.cpp.

References GetLiveProcessBinaryDataSize(), GetLiveTraceBinaryData(), and lldb_private::PluginInterface::GetPluginName().

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

◆ GetLiveProcessBinaryDataSize()

std::optional< uint64_t > Trace::GetLiveProcessBinaryDataSize ( llvm::StringRef kind )

protected

Get the size of the data returned by GetLiveProcessBinaryData.

Definition at line 200 of file Trace.cpp.

References GetUpdatedStorage(), lldb_private::Trace::Storage::live_process_data, and Lookup().

Referenced by GetLiveProcessBinaryData().

◆ 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 179 of file Trace.cpp.

References lldb_private::PluginInterface::GetPluginName(), m_live_process, and lldb_private::Process::TraceGetState().

Referenced by RefreshLiveProcessState().

◆ GetLiveThreadBinaryData()

Expected< std::vector< 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 233 of file Trace.cpp.

References GetLiveThreadBinaryDataSize(), GetLiveTraceBinaryData(), and lldb_private::PluginInterface::GetPluginName().

Referenced by OnLiveThreadBinaryDataRead().

◆ GetLiveThreadBinaryDataSize()

std::optional< uint64_t > Trace::GetLiveThreadBinaryDataSize	(	lldb::tid_t	tid,
		llvm::StringRef	kind
	)

protected

Get the size of the data returned by GetLiveThreadBinaryData.

Definition at line 188 of file Trace.cpp.

References GetUpdatedStorage(), lldb_private::Trace::Storage::live_thread_data, and Lookup().

Referenced by GetLiveThreadBinaryData(), and lldb_private::trace_intel_pt::TraceIntelPT::GetRawTraceSize().

◆ GetLiveTraceBinaryData()

Expected< std::vector< uint8_t > > Trace::GetLiveTraceBinaryData	(	const TraceGetBinaryDataRequest &	request,
		uint64_t	expected_size
	)

protected

Dispatcher for live trace data requests with some additional error checking.

Definition at line 206 of file Trace.cpp.

References lldb_private::TraceGetBinaryDataRequest::cpu_id, lldb_private::TraceGetBinaryDataRequest::kind, m_live_process, lldb_private::TraceGetBinaryDataRequest::tid, and lldb_private::Process::TraceGetBinaryData().

Referenced by GetLiveProcessBinaryData(), and GetLiveThreadBinaryData().

◆ GetPostMortemCpuDataFile()

llvm::Expected< FileSpec > Trace::GetPostMortemCpuDataFile	(	lldb::cpu_id_t	cpu_id,
		llvm::StringRef	kind
	)

protected

Get the file path containing data of a postmortem cpu given a data identifier.

Parameters

[in]	cpu_id	The cpu whose data is requested.
[in]	kind	The kind of data requested.

Returns: The file spec containing the requested data, or an llvm::Error in case of failures.

Definition at line 387 of file Trace.cpp.

References GetUpdatedStorage(), Lookup(), and lldb_private::Trace::Storage::postmortem_cpu_data.

Referenced by OnPostMortemCpuBinaryDataRead().

◆ GetPostMortemProcesses()

ArrayRef< Process * > Trace::GetPostMortemProcesses ( )

protected

Get the currently traced postmortem processes.

Returns: If it's not a live process session, return an empty list.

Definition at line 359 of file Trace.cpp.

References m_storage, and lldb_private::Trace::Storage::postmortem_processes.

Referenced by GetAllProcesses().

◆ GetPostMortemThreadDataFile()

llvm::Expected< FileSpec > Trace::GetPostMortemThreadDataFile	(	lldb::tid_t	tid,
		llvm::StringRef	kind
	)

protected

Get the file path containing data of a postmortem thread given a data identifier.

Parameters

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

Returns: The file spec containing the requested data, or an llvm::Error in case of failures.

Definition at line 375 of file Trace.cpp.

References GetUpdatedStorage(), Lookup(), and lldb_private::Trace::Storage::postmortem_thread_data.

Referenced by OnPostMortemThreadBinaryDataRead().

◆ 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 369 of file Trace.cpp.

References m_stop_id, and RefreshLiveProcessState().

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

◆ GetTracedCpus()

ArrayRef< lldb::cpu_id_t > Trace::GetTracedCpus ( )

Returns: The list of cpus being traced. Might be empty depending on the plugin.

Definition at line 513 of file Trace.cpp.

References lldb_private::Trace::Storage::cpus, and GetUpdatedStorage().

Referenced by BuildCpusSection().

◆ GetTracedProcesses()

std::vector< Process * > Trace::GetTracedProcesses ( )

protected

Return the list of processes traced by this instance.

None of the returned pointers are invalid.

Definition at line 520 of file Trace.cpp.

References GetUpdatedStorage(), m_live_process, and lldb_private::Trace::Storage::postmortem_processes.

◆ GetUpdatedStorage()

Trace::Storage & Trace::GetUpdatedStorage ( )

private

Get the storage after refreshing the data in the case of a live process.

Definition at line 278 of file Trace.cpp.

References m_storage, and RefreshLiveProcessState().

Referenced by GetLiveCpuBinaryDataSize(), GetLiveProcessBinaryDataSize(), GetLiveThreadBinaryDataSize(), GetPostMortemCpuDataFile(), GetPostMortemThreadDataFile(), GetTracedCpus(), GetTracedProcesses(), OnAllCpusBinaryDataRead(), OnLiveCpuBinaryDataRead(), SetPostMortemCpuDataFile(), and SetPostMortemThreadDataFile().

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

◆ LoadPostMortemTraceFromFile()

Expected< lldb::TraceSP > Trace::LoadPostMortemTraceFromFile	(	Debugger &	debugger,
		const FileSpec &	trace_description_file
	)

static

Load a trace from a trace description file and create Targets, Processes and Threads based on the contents of such file.

Parameters

[in]	debugger	The debugger instance where new Targets will be created as part of the JSON data parsing.
[in]	trace_description_file	The file containing the necessary information to load the trace.

Returns: A TraceSP instance, or an llvm::Error if loading the trace fails.

Definition at line 96 of file Trace.cpp.

References lldb_private::ConstString::AsCString(), FindPluginForPostMortemProcess(), lldb_private::FileSpec::GetDirectory(), and lldb_private::FileSpec::GetPath().

Referenced by CommandObjectTraceLoad::DoExecute(), and lldb::SBTrace::LoadTraceFromFile().

◆ OnAllCpusBinaryDataRead()

llvm::Error Trace::OnAllCpusBinaryDataRead	(	llvm::StringRef	kind,
		OnCpusBinaryDataReadCallback	callback
	)

Similar to OnCpuBinaryDataRead but this is able to fetch the same data from all cpus at once.

Definition at line 481 of file Trace.cpp.

References lldb_private::Trace::Storage::cpus, GetUpdatedStorage(), and OnCpuBinaryDataRead().

◆ OnCpuBinaryDataRead()

llvm::Error Trace::OnCpuBinaryDataRead	(	lldb::cpu_id_t	cpu_id,
		llvm::StringRef	kind,
		OnBinaryDataReadCallback	callback
	)

Fetch binary data associated with a cpu, either live or postmortem, and pass it to the given callback.

The reason of having a callback is to free the caller from having to manage the life cycle of the data and to hide the different data fetching procedures that exist for live and post mortem cpus.

The fetched data is not persisted after the callback is invoked.

Parameters

[in]	cpu_id	The cpu who owns the data.
[in]	kind	The kind of data to read.
[in]	callback	The callback to be invoked once the data was successfully read. Its return value, which is an llvm::Error, is returned by this function.

Returns: An llvm::Error if the data couldn't be fetched, or the return value of the callback, otherwise.

Definition at line 504 of file Trace.cpp.

References m_live_process, OnLiveCpuBinaryDataRead(), and OnPostMortemCpuBinaryDataRead().

Referenced by GetPSBBlocksForCPU(), OnAllCpusBinaryDataRead(), WriteContextSwitchTrace(), and WriteIntelPTTrace().

◆ OnDataFileRead()

llvm::Error Trace::OnDataFileRead	(	FileSpec	file,
		OnBinaryDataReadCallback	callback
	)

static

Helper method for reading a data file and passing its data to the given callback.

Definition at line 437 of file Trace.cpp.

References lldb_private::FileSpec::GetPath(), and lldb_private::toString().

Referenced by lldb_private::trace_intel_pt::TraceIntelPTBundleLoader::AugmentThreadsFromContextSwitches(), OnPostMortemCpuBinaryDataRead(), and OnPostMortemThreadBinaryDataRead().

◆ OnLiveCpuBinaryDataRead()

llvm::Error Trace::OnLiveCpuBinaryDataRead	(	lldb::cpu_id_t	cpu,
		llvm::StringRef	kind,
		OnBinaryDataReadCallback	callback
	)

protected

Implementation of OnLiveBinaryDataRead() for live cpus.

Definition at line 421 of file Trace.cpp.

References GetLiveCpuBinaryData(), GetUpdatedStorage(), lldb_private::Trace::Storage::live_cpu_data, and LookupAsPtr().

Referenced by OnCpuBinaryDataRead().

◆ OnLiveThreadBinaryDataRead()

llvm::Error Trace::OnLiveThreadBinaryDataRead	(	lldb::tid_t	tid,
		llvm::StringRef	kind,
		OnBinaryDataReadCallback	callback
	)

protected

Implementation of OnThreadBinaryDataRead() for live threads.

Definition at line 413 of file Trace.cpp.

References GetLiveThreadBinaryData().

Referenced by OnThreadBinaryDataRead().

◆ OnPostMortemCpuBinaryDataRead()

llvm::Error Trace::OnPostMortemCpuBinaryDataRead	(	lldb::cpu_id_t	cpu_id,
		llvm::StringRef	kind,
		OnBinaryDataReadCallback	callback
	)

protected

Implementation of OnCpuBinaryDataRead() for post mortem cpus.

Definition at line 463 of file Trace.cpp.

References GetPostMortemCpuDataFile(), and OnDataFileRead().

Referenced by OnCpuBinaryDataRead().

◆ OnPostMortemThreadBinaryDataRead()

llvm::Error Trace::OnPostMortemThreadBinaryDataRead	(	lldb::tid_t	tid,
		llvm::StringRef	kind,
		OnBinaryDataReadCallback	callback
	)

protected

Implementation of OnThreadBinaryDataRead() for post mortem threads.

Definition at line 454 of file Trace.cpp.

References GetPostMortemThreadDataFile(), and OnDataFileRead().

Referenced by OnThreadBinaryDataRead().

◆ OnThreadBinaryDataRead()

llvm::Error Trace::OnThreadBinaryDataRead	(	lldb::tid_t	tid,
		llvm::StringRef	kind,
		OnBinaryDataReadCallback	callback
	)

Fetch binary data associated with a thread, either live or postmortem, and pass it to the given callback.

The reason of having a callback is to free the caller from having to manage the life cycle of the data and to hide the different data fetching procedures that exist for live and post mortem threads.

The fetched data is not persisted after the callback is invoked.

Parameters

[in]	tid	The tid who owns the data.
[in]	kind	The kind of data to read.
[in]	callback	The callback to be invoked once the data was successfully read. Its return value, which is an llvm::Error, is returned by this function.

Returns: An llvm::Error if the data couldn't be fetched, or the return value of the callback, otherwise.

Definition at line 472 of file Trace.cpp.

References m_live_process, OnLiveThreadBinaryDataRead(), and OnPostMortemThreadBinaryDataRead().

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

◆ RefreshLiveProcessState()

const char * Trace::RefreshLiveProcessState ( )

protected

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

It will invoked DoRefreshLiveProcessState at some point, which should be implemented by the plug-in for custom state handling.

The result is cached through the same process stop. Even in the case of errors, it caches the error.

Returns: An error message if this operation failed, or nullptr otherwise.

Definition at line 283 of file Trace.cpp.

Referenced by lldb_private::trace_intel_pt::TraceIntelPT::Decode(), GetStopID(), GetUpdatedStorage(), lldb_private::trace_intel_pt::TraceIntelPT::GetUpdatedStorage(), and lldb_private::trace_intel_pt::TraceIntelPT::SaveToDisk().

◆ SaveToDisk()

virtual llvm::Expected< FileSpec > lldb_private::Trace::SaveToDisk	(	FileSpec	directory,
		bool	compact
	)

pure virtual

Save the trace to the specified directory, which will be created if needed.

This will also create 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.

Parameters

[in]	directory	The directory where the trace files will be saved.
[in]	compact	Try not to save to disk information irrelevant to the traced processes. Each trace plug-in implements this in a different fashion.

Returns: A FileSpec pointing to the bundle description file, or an llvm::Error otherwise.

Implemented in lldb_private::trace_intel_pt::TraceIntelPT.

◆ SetPostMortemCpuDataFile()

void Trace::SetPostMortemCpuDataFile	(	lldb::cpu_id_t	cpu_id,
		llvm::StringRef	kind,
		FileSpec	file_spec
	)

protected

Associate a given cpu with a data file using a data identifier.

Parameters

[in]	cpu_id	The cpu associated with the data file.
[in]	kind	The kind of data being registered.
[in]	file_spec	The path of the data file.

Definition at line 406 of file Trace.cpp.

References GetUpdatedStorage(), and lldb_private::Trace::Storage::postmortem_cpu_data.

◆ SetPostMortemThreadDataFile()

void Trace::SetPostMortemThreadDataFile	(	lldb::tid_t	tid,
		llvm::StringRef	kind,
		FileSpec	file_spec
	)

protected

Associate a given thread with a data file using a data identifier.

Parameters

[in]	tid	The thread associated with the data file.
[in]	kind	The kind of data being registered.
[in]	file_spec	The path of the data file.

Definition at line 400 of file Trace.cpp.

References GetUpdatedStorage(), and lldb_private::Trace::Storage::postmortem_thread_data.

◆ 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 155 of file Trace.cpp.

References m_live_process, and lldb_private::Process::TraceStart().

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

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

◆ 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 163 of file Trace.cpp.

References lldb_private::PluginInterface::GetPluginName(), m_live_process, and lldb_private::Process::TraceStop().

◆ 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 171 of file Trace.cpp.

References lldb_private::PluginInterface::GetPluginName(), m_live_process, and lldb_private::Process::TraceStop().

Member Data Documentation

◆ m_live_process

Process* lldb_private::Trace::m_live_process = nullptr

private

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

Definition at line 541 of file Trace.h.

Referenced by GetLiveCpuBinaryData(), GetLiveProcess(), GetLiveProcessState(), GetLiveTraceBinaryData(), GetTracedProcesses(), OnCpuBinaryDataRead(), OnThreadBinaryDataRead(), RefreshLiveProcessState(), Start(), and Stop().

◆ m_stop_id

uint32_t lldb_private::Trace::m_stop_id = LLDB_INVALID_STOP_ID

private

Definition at line 538 of file Trace.h.

Referenced by GetStopID(), and RefreshLiveProcessState().

◆ m_storage

struct lldb_private::Trace::Storage lldb_private::Trace::m_storage

private

Referenced by GetPostMortemProcesses(), GetUpdatedStorage(), and RefreshLiveProcessState().

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ OnBinaryDataReadCallback

◆ OnCpusBinaryDataReadCallback

Constructor & Destructor Documentation

◆ Trace() [1/2]

◆ Trace() [2/2]

Member Function Documentation

◆ CreateNewCursor()

◆ DoRefreshLiveProcessState()

◆ Dump()

◆ DumpTraceInfo()

◆ FindPluginForLiveProcess()

◆ FindPluginForPostMortemProcess()

◆ FindPluginSchema()

◆ GetAllProcesses()

◆ GetLiveCpuBinaryData()

◆ GetLiveCpuBinaryDataSize()

◆ GetLiveProcess()

◆ GetLiveProcessBinaryData()

◆ GetLiveProcessBinaryDataSize()

◆ GetLiveProcessState()

◆ GetLiveThreadBinaryData()

◆ GetLiveThreadBinaryDataSize()

◆ GetLiveTraceBinaryData()

◆ GetPostMortemCpuDataFile()

◆ GetPostMortemProcesses()

◆ GetPostMortemThreadDataFile()

◆ GetProcessTraceStartCommand()

◆ GetSchema()

◆ GetStartConfigurationHelp()

◆ GetStopID()

◆ GetThreadTraceStartCommand()

◆ GetTracedCpus()

◆ GetTracedProcesses()

◆ GetUpdatedStorage()

◆ IsTraced()

◆ LoadPostMortemTraceFromFile()

◆ OnAllCpusBinaryDataRead()

◆ OnCpuBinaryDataRead()

◆ OnDataFileRead()

◆ OnLiveCpuBinaryDataRead()

◆ OnLiveThreadBinaryDataRead()

◆ OnPostMortemCpuBinaryDataRead()

◆ OnPostMortemThreadBinaryDataRead()

◆ OnThreadBinaryDataRead()

◆ RefreshLiveProcessState()

◆ SaveToDisk()

◆ SetPostMortemCpuDataFile()

◆ SetPostMortemThreadDataFile()

◆ Start() [1/3]

◆ Start() [2/3]

◆ Start() [3/3]

◆ Stop() [1/2]

◆ Stop() [2/2]

Member Data Documentation

◆ m_live_process

◆ m_stop_id

◆ m_storage