LLDB  mainline
Trace.h
Go to the documentation of this file.
1 //===-- Trace.h -------------------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef LLDB_TARGET_TRACE_H
10 #define LLDB_TARGET_TRACE_H
11 
12 #include <unordered_map>
13 
14 #include "llvm/Support/JSON.h"
15 
17 #include "lldb/Target/Thread.h"
19 #include "lldb/Utility/ArchSpec.h"
22 #include "lldb/lldb-private.h"
23 
24 namespace lldb_private {
25 
26 /// \class Trace Trace.h "lldb/Target/Trace.h"
27 /// A plug-in interface definition class for trace information.
28 ///
29 /// Trace plug-ins allow processor trace information to be loaded into LLDB so
30 /// that the data can be dumped, used for reverse and forward stepping to allow
31 /// introspection into the reason your process crashed or found its way to its
32 /// current state.
33 ///
34 /// Trace information can be loaded into a target without a process to allow
35 /// introspection of the trace information during post mortem analysis, such as
36 /// when loading core files.
37 ///
38 /// Processor trace information can also be fetched through the process
39 /// interfaces during a live debug session if your process supports gathering
40 /// this information.
41 ///
42 /// In order to support live tracing, the name of the plug-in should match the
43 /// name of the tracing type returned by the gdb-remote packet
44 /// \a jLLDBTraceSupported.
45 class Trace : public PluginInterface,
46  public std::enable_shared_from_this<Trace> {
47 public:
48  /// Dump the trace data that this plug-in has access to.
49  ///
50  /// This function will dump all of the trace data for all threads in a user
51  /// readable format. Options for dumping can be added as this API is iterated
52  /// on.
53  ///
54  /// \param[in] s
55  /// A stream object to dump the information to.
56  virtual void Dump(Stream *s) const = 0;
57 
58  /// Find a trace plug-in using JSON data.
59  ///
60  /// When loading trace data from disk, the information for the trace data
61  /// can be contained in multiple files and require plug-in specific
62  /// information about the CPU. Using data like JSON provides an
63  /// easy way to specify all of the settings and information that we will need
64  /// to load trace data into LLDB. This structured data can include:
65  /// - The plug-in name (this allows a specific plug-in to be selected)
66  /// - Architecture or target triple
67  /// - one or more paths to the trace data file on disk
68  /// - core trace data
69  /// - thread events or related information
70  /// - shared library load information to use for this trace data that
71  /// allows a target to be created so the trace information can be
72  /// symbolicated so that the trace information can be displayed to the
73  /// user
74  /// - shared library path
75  /// - load address
76  /// - information on how to fetch the shared library
77  /// - path to locally cached file on disk
78  /// - URL to download the file
79  /// - Any information needed to load the trace file
80  /// - CPU information
81  /// - Custom plug-in information needed to decode the trace information
82  /// correctly.
83  ///
84  /// \param[in] debugger
85  /// The debugger instance where new Targets will be created as part of the
86  /// JSON data parsing.
87  ///
88  /// \param[in] trace_session_file
89  /// The contents of the trace session file describing the trace session.
90  /// See \a TraceSessionFileParser::BuildSchema for more information about
91  /// the schema of this JSON file.
92  ///
93  /// \param[in] session_file_dir
94  /// The path to the directory that contains the session file. It's used to
95  /// resolved relative paths in the session file.
96  static llvm::Expected<lldb::TraceSP>
98  const llvm::json::Value &trace_session_file,
99  llvm::StringRef session_file_dir);
100 
101  /// Find a trace plug-in to trace a live process.
102  ///
103  /// \param[in] plugin_name
104  /// Plug-in name to search.
105  ///
106  /// \param[in] process
107  /// Live process to trace.
108  ///
109  /// \return
110  /// A \a TraceSP instance, or an \a llvm::Error if the plug-in name
111  /// doesn't match any registered plug-ins or tracing couldn't be
112  /// started.
113  static llvm::Expected<lldb::TraceSP>
114  FindPluginForLiveProcess(llvm::StringRef plugin_name, Process &process);
115 
116  /// Get the schema of a Trace plug-in given its name.
117  ///
118  /// \param[in] plugin_name
119  /// Name of the trace plugin.
120  static llvm::Expected<llvm::StringRef>
121  FindPluginSchema(llvm::StringRef plugin_name);
122 
123  /// Get the command handle for the "process trace start" command.
124  virtual lldb::CommandObjectSP
126 
127  /// Get the command handle for the "thread trace start" command.
128  virtual lldb::CommandObjectSP
130 
131  /// \return
132  /// The JSON schema of this Trace plug-in.
133  virtual llvm::StringRef GetSchema() = 0;
134 
135  /// Get a \a TraceCursor for the given thread's trace.
136  ///
137  /// \return
138  /// A \a TraceCursorUP. If the thread is not traced or its trace
139  /// information failed to load, the corresponding error is embedded in the
140  /// trace.
141  virtual lldb::TraceCursorUP GetCursor(Thread &thread) = 0;
142 
143  /// Dump general info about a given thread's trace. Each Trace plug-in
144  /// decides which data to show.
145  ///
146  /// \param[in] thread
147  /// The thread that owns the trace in question.
148  ///
149  /// \param[in] s
150  /// The stream object where the info will be printed printed.
151  ///
152  /// \param[in] verbose
153  /// If \b true, print detailed info
154  /// If \b false, print compact info
155  virtual void DumpTraceInfo(Thread &thread, Stream &s, bool verbose) = 0;
156 
157  /// Check if a thread is currently traced by this object.
158  ///
159  /// \param[in] thread
160  /// The thread in question.
161  ///
162  /// \return
163  /// \b true if the thread is traced by this instance, \b false otherwise.
164  virtual bool IsTraced(const Thread &thread) = 0;
165 
166  /// \return
167  /// A description of the parameters to use for the \a Trace::Start method.
168  virtual const char *GetStartConfigurationHelp() = 0;
169 
170  /// Start tracing a live process.
171  ///
172  /// \param[in] configuration
173  /// See \a SBTrace::Start(const lldb::SBStructuredData &) for more
174  /// information.
175  ///
176  /// \return
177  /// \a llvm::Error::success if the operation was successful, or
178  /// \a llvm::Error otherwise.
179  virtual llvm::Error Start(
180  StructuredData::ObjectSP configuration = StructuredData::ObjectSP()) = 0;
181 
182  /// Start tracing live threads.
183  ///
184  /// \param[in] tids
185  /// Threads to trace. This method tries to trace as many threads as
186  /// possible.
187  ///
188  /// \param[in] configuration
189  /// See \a SBTrace::Start(const lldb::SBThread &, const
190  /// lldb::SBStructuredData &) for more information.
191  ///
192  /// \return
193  /// \a llvm::Error::success if the operation was successful, or
194  /// \a llvm::Error otherwise.
195  virtual llvm::Error Start(
196  llvm::ArrayRef<lldb::tid_t> tids,
197  StructuredData::ObjectSP configuration = StructuredData::ObjectSP()) = 0;
198 
199  /// Stop tracing live threads.
200  ///
201  /// \param[in] tids
202  /// The threads to stop tracing on.
203  ///
204  /// \return
205  /// \a llvm::Error::success if the operation was successful, or
206  /// \a llvm::Error otherwise.
207  llvm::Error Stop(llvm::ArrayRef<lldb::tid_t> tids);
208 
209  /// Stop tracing all current and future threads of a live process.
210  ///
211  /// \param[in] request
212  /// The information determining which threads or process to stop tracing.
213  ///
214  /// \return
215  /// \a llvm::Error::success if the operation was successful, or
216  /// \a llvm::Error otherwise.
217  llvm::Error Stop();
218 
219  /// Get the trace file of the given post mortem thread.
220  llvm::Expected<const FileSpec &> GetPostMortemTraceFile(lldb::tid_t tid);
221 
222  /// \return
223  /// The stop ID of the live process being traced, or an invalid stop ID
224  /// if the trace is in an error or invalid state.
226 
227 protected:
228  /// Get binary data of a live thread given a data identifier.
229  ///
230  /// \param[in] tid
231  /// The thread whose data is requested.
232  ///
233  /// \param[in] kind
234  /// The kind of data requested.
235  ///
236  /// \return
237  /// A vector of bytes with the requested data, or an \a llvm::Error in
238  /// case of failures.
239  llvm::Expected<llvm::ArrayRef<uint8_t>>
240  GetLiveThreadBinaryData(lldb::tid_t tid, llvm::StringRef kind);
241 
242  /// Get binary data of the current process given a data identifier.
243  ///
244  /// \param[in] kind
245  /// The kind of data requested.
246  ///
247  /// \return
248  /// A vector of bytes with the requested data, or an \a llvm::Error in
249  /// case of failures.
250  llvm::Expected<llvm::ArrayRef<uint8_t>>
251  GetLiveProcessBinaryData(llvm::StringRef kind);
252 
253  /// Get the size of the data returned by \a GetLiveThreadBinaryData
254  llvm::Optional<size_t> GetLiveThreadBinaryDataSize(lldb::tid_t tid,
255  llvm::StringRef kind);
256 
257  /// Get the size of the data returned by \a GetLiveProcessBinaryData
258  llvm::Optional<size_t> GetLiveProcessBinaryDataSize(llvm::StringRef kind);
259  /// Constructor for post mortem processes
260  Trace() = default;
261 
262  /// Constructor for a live process
263  Trace(Process &live_process) : m_live_process(&live_process) {}
264 
265  /// Start tracing a live process or its threads.
266  ///
267  /// \param[in] request
268  /// JSON object with the information necessary to start tracing. In the
269  /// case of gdb-remote processes, this JSON object should conform to the
270  /// jLLDBTraceStart packet.
271  ///
272  /// \return
273  /// \a llvm::Error::success if the operation was successful, or
274  /// \a llvm::Error otherwise.
275  llvm::Error Start(const llvm::json::Value &request);
276 
277  /// Get the current tracing state of a live process and its threads.
278  ///
279  /// \return
280  /// A JSON object string with custom data depending on the trace
281  /// technology, or an \a llvm::Error in case of errors.
282  llvm::Expected<std::string> GetLiveProcessState();
283 
284  /// Method to be overriden by the plug-in to refresh its own state.
285  ///
286  /// This is invoked by RefreshLiveProcessState when a new state is found.
287  ///
288  /// \param[in] state
289  /// The jLLDBTraceGetState response.
290  virtual void
291  DoRefreshLiveProcessState(llvm::Expected<TraceGetStateResponse> state) = 0;
292 
293  /// Method to be invoked by the plug-in to refresh the live process state.
294  ///
295  /// The result is cached through the same process stop.
297 
299  /// Process traced by this object if doing live tracing. Otherwise it's null.
301  /// tid -> data kind -> size
302  std::map<lldb::tid_t, std::unordered_map<std::string, size_t>>
304  /// data kind -> size
305  std::unordered_map<std::string, size_t> m_live_process_data;
306 };
307 
308 } // namespace lldb_private
309 
310 #endif // LLDB_TARGET_TRACE_H
lldb_private::Trace::Trace
Trace()=default
Constructor for post mortem processes.
lldb_private::Trace::GetLiveThreadBinaryDataSize
llvm::Optional< size_t > GetLiveThreadBinaryDataSize(lldb::tid_t tid, llvm::StringRef kind)
Get the size of the data returned by GetLiveThreadBinaryData.
Definition: Trace.cpp:130
lldb_private::Trace::GetLiveProcessBinaryData
llvm::Expected< llvm::ArrayRef< uint8_t > > GetLiveProcessBinaryData(llvm::StringRef kind)
Get binary data of the current process given a data identifier.
Definition: Trace.cpp:168
lldb_private::Trace::GetStopID
uint32_t GetStopID()
Definition: Trace.cpp:218
lldb_private::PluginInterface
Definition: PluginInterface.h:16
lldb_private::Trace::DoRefreshLiveProcessState
virtual void DoRefreshLiveProcessState(llvm::Expected< TraceGetStateResponse > state)=0
Method to be overriden by the plug-in to refresh its own state.
lldb_private::Process
Definition: Process.h:341
lldb_private::Trace::GetProcessTraceStartCommand
virtual lldb::CommandObjectSP GetProcessTraceStartCommand(CommandInterpreter &interpreter)=0
Get the command handle for the "process trace start" command.
lldb_private::Trace::FindPluginForLiveProcess
static llvm::Expected< lldb::TraceSP > FindPluginForLiveProcess(llvm::StringRef plugin_name, Process &process)
Find a trace plug-in to trace a live process.
Definition: Trace.cpp:78
lldb_private::Stream
Definition: Stream.h:28
lldb_private::Trace::RefreshLiveProcessState
void RefreshLiveProcessState()
Method to be invoked by the plug-in to refresh the live process state.
Definition: Trace.cpp:183
lldb_private::Trace::GetStartConfigurationHelp
virtual const char * GetStartConfigurationHelp()=0
lldb_private::Trace::m_stop_id
uint32_t m_stop_id
Definition: Trace.h:298
lldb_private::Trace
Definition: Trace.h:45
lldb_private::Trace::IsTraced
virtual bool IsTraced(const Thread &thread)=0
Check if a thread is currently traced by this object.
lldb_private::Trace::m_live_process_data
std::unordered_map< std::string, size_t > m_live_process_data
data kind -> size
Definition: Trace.h:305
UnimplementedError.h
lldb_private::Thread
Definition: Thread.h:62
lldb_private::StructuredData::ObjectSP
std::shared_ptr< Object > ObjectSP
Definition: StructuredData.h:59
lldb_private::Trace::GetPostMortemTraceFile
llvm::Expected< const FileSpec & > GetPostMortemTraceFile(lldb::tid_t tid)
Get the trace file of the given post mortem thread.
lldb_private::Trace::GetThreadTraceStartCommand
virtual lldb::CommandObjectSP GetThreadTraceStartCommand(CommandInterpreter &interpreter)=0
Get the command handle for the "thread trace start" command.
PluginInterface.h
lldb_private::Trace::m_live_thread_data
std::map< lldb::tid_t, std::unordered_map< std::string, size_t > > m_live_thread_data
tid -> data kind -> size
Definition: Trace.h:303
lldb_private::CommandInterpreter
Definition: CommandInterpreter.h:214
lldb_private::Trace::GetLiveThreadBinaryData
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.
Definition: Trace.cpp:150
lldb_private::Debugger
Definition: Debugger.h:70
lldb_private::Trace::Start
virtual llvm::Error Start(StructuredData::ObjectSP configuration=StructuredData::ObjectSP())=0
Start tracing a live process.
Thread.h
lldb-private.h
LLDB_INVALID_STOP_ID
#define LLDB_INVALID_STOP_ID
Invalid value definitions.
Definition: lldb-defines.h:85
lldb_private::Trace::m_live_process
Process * m_live_process
Process traced by this object if doing live tracing. Otherwise it's null.
Definition: Trace.h:300
uint32_t
lldb_private::Trace::Dump
virtual void Dump(Stream *s) const =0
Dump the trace data that this plug-in has access to.
ArchSpec.h
TraceCursor.h
lldb_private::Trace::Stop
llvm::Error Stop()
Stop tracing all current and future threads of a live process.
Definition: Trace.cpp:107
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::Trace::FindPluginForPostMortemProcess
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.
Definition: Trace.cpp:62
lldb_private::Trace::GetCursor
virtual lldb::TraceCursorUP GetCursor(Thread &thread)=0
Get a TraceCursor for the given thread's trace.
Error
llvm::Error Error
Definition: UdtRecordCompleter.cpp:29
lldb_private::Trace::GetSchema
virtual llvm::StringRef GetSchema()=0
lldb_private::Trace::DumpTraceInfo
virtual void DumpTraceInfo(Thread &thread, Stream &s, bool verbose)=0
Dump general info about a given thread's trace.
lldb_private::Trace::Trace
Trace(Process &live_process)
Constructor for a live process.
Definition: Trace.h:263
lldb_private::Trace::FindPluginSchema
static llvm::Expected< llvm::StringRef > FindPluginSchema(llvm::StringRef plugin_name)
Get the schema of a Trace plug-in given its name.
Definition: Trace.cpp:91
lldb_private::Trace::GetLiveProcessBinaryDataSize
llvm::Optional< size_t > GetLiveProcessBinaryDataSize(llvm::StringRef kind)
Get the size of the data returned by GetLiveProcessBinaryData.
Definition: Trace.cpp:142
lldb_private::Trace::GetLiveProcessState
llvm::Expected< std::string > GetLiveProcessState()
Get the current tracing state of a live process and its threads.
Definition: Trace.cpp:123
TraceGDBRemotePackets.h
lldb::tid_t
uint64_t tid_t
Definition: lldb-types.h:86