LLDB  mainline
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
lldb_private::Trace Class Referenceabstract

#include "lldb/Target/Trace.h"

Inheritance diagram for lldb_private::Trace:
Inheritance graph
[legend]
Collaboration diagram for lldb_private::Trace:
Collaboration graph
[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
 
PluginInterfaceoperator= (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::stringGetLiveProcessState ()
 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
 
Processm_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]stateThe 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]sA 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]threadThe thread that owns the trace in question.
[in]sThe stream object where the info will be printed printed.
[in]verboseIf 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_namePlug-in name to search.
[in]processLive 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]debuggerThe debugger instance where new Targets will be created as part of the JSON data parsing.
[in]trace_session_fileThe 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_dirThe 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_nameName 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]kindThe 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]tidThe thread whose data is requested.
[in]kindThe 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]tidThe 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]directoryThe 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]requestJSON 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]tidsThreads to trace. This method tries to trace as many threads as possible.
[in]configurationSee 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]configurationSee 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]requestThe 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]tidsThe 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: