LLDB  mainline
TraceSessionSaver.h
Go to the documentation of this file.
1 //===-- SessionSaver.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_TRACESESSIONSAVER_H
10 #define LLDB_TARGET_TRACESESSIONSAVER_H
11 
12 #include "TraceJSONStructs.h"
13 
14 namespace lldb_private {
15 
17 
18 public:
19  /// Save the trace session description JSON object inside the given directory
20  /// as a file named \a trace.json.
21  ///
22  /// \param[in] trace_session_description
23  /// The trace's session, as JSON Object.
24  ///
25  /// \param[in] directory
26  /// The directory where the JSON file will be saved.
27  ///
28  /// \return
29  /// \a llvm::success if the operation was successful, or an \a llvm::Error
30  /// otherwise.
31  static llvm::Error
32  WriteSessionToFile(const llvm::json::Value &trace_session_description,
33  FileSpec directory);
34 
35  /// Build the processes section of the trace session description file. Besides
36  /// returning the processes information, this method saves to disk all modules
37  /// and raw traces corresponding to the traced threads of the given process.
38  ///
39  /// \param[in] live_process
40  /// The process being traced.
41  ///
42  /// \param[in] raw_trace_fetcher
43  /// Callback function that receives a thread ID and returns its raw trace.
44  /// This callback should return \a None if the thread is not being traced.
45  /// Otherwise, it should return the raw trace in bytes or an
46  /// \a llvm::Error in case of failures.
47  ///
48  /// \param[in] directory
49  /// The directory where files will be saved when building the processes
50  /// section.
51  ///
52  /// \return
53  /// The processes section or \a llvm::Error in case of failures.
54  static llvm::Expected<JSONTraceSessionBase> BuildProcessesSection(
55  Process &live_process,
56  std::function<
57  llvm::Expected<llvm::Optional<std::vector<uint8_t>>>(lldb::tid_t tid)>
58  raw_trace_fetcher,
59  FileSpec directory);
60 
61  /// Build the threads sub-section of the trace session description file.
62  /// For each traced thread, its raw trace is also written to the file
63  /// \a thread_id_.trace inside of the given directory.
64  ///
65  /// \param[in] live_process
66  /// The process being traced.
67  ///
68  /// \param[in] raw_trace_fetcher
69  /// Callback function that receives a thread ID and returns its raw trace.
70  /// This callback should return \a None if the thread is not being traced.
71  /// Otherwise, it should return the raw trace in bytes or an
72  /// \a llvm::Error in case of failures.
73  ///
74  /// \param[in] directory
75  /// The directory where files will be saved when building the threads
76  /// section.
77  ///
78  /// \return
79  /// The threads section or \a llvm::Error in case of failures.
80  static llvm::Expected<std::vector<JSONThread>> BuildThreadsSection(
81  Process &live_process,
82  std::function<
83  llvm::Expected<llvm::Optional<std::vector<uint8_t>>>(lldb::tid_t tid)>
84  raw_trace_fetcher,
85  FileSpec directory);
86 
87  /// Build modules sub-section of the trace's session. The original modules
88  /// will be copied over to the \a <directory/modules> folder. Invalid modules
89  /// are skipped.
90  /// Copying the modules has the benefit of making these trace session
91  /// directories self-contained, as the raw traces and modules are part of the
92  /// output directory and can be sent to another machine, where lldb can load
93  /// them and replicate exactly the same trace session.
94  ///
95  /// \param[in] live_process
96  /// The process being traced.
97  ///
98  /// \param[in] directory
99  /// The directory where the modules files will be saved when building
100  /// the modules section.
101  /// Example: If a module \a libbar.so exists in the path
102  /// \a /usr/lib/foo/libbar.so, then it will be copied to
103  /// \a <directory>/modules/usr/lib/foo/libbar.so.
104  ///
105  /// \return
106  /// The modules section or \a llvm::Error in case of failures.
107  static llvm::Expected<std::vector<JSONModule>>
108  BuildModulesSection(Process &live_process, FileSpec directory);
109 };
110 } // namespace lldb_private
111 
112 #endif // LLDB_TARGET_TRACESESSIONSAVER_H
lldb_private::TraceSessionSaver::BuildThreadsSection
static llvm::Expected< std::vector< JSONThread > > BuildThreadsSection(Process &live_process, std::function< llvm::Expected< llvm::Optional< std::vector< uint8_t >>>(lldb::tid_t tid)> raw_trace_fetcher, FileSpec directory)
Build the threads sub-section of the trace session description file.
Definition: TraceSessionSaver.cpp:66
lldb_private::TraceSessionSaver::WriteSessionToFile
static llvm::Error WriteSessionToFile(const llvm::json::Value &trace_session_description, FileSpec directory)
Save the trace session description JSON object inside the given directory as a file named trace....
Definition: TraceSessionSaver.cpp:26
lldb_private::Process
Definition: Process.h:338
lldb_private::FileSpec
Definition: FileSpec.h:56
lldb_private::TraceSessionSaver::BuildModulesSection
static llvm::Expected< std::vector< JSONModule > > BuildModulesSection(Process &live_process, FileSpec directory)
Build modules sub-section of the trace's session.
Definition: TraceSessionSaver.cpp:105
lldb_private::TraceSessionSaver
Definition: TraceSessionSaver.h:16
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
Error
llvm::Error Error
Definition: UdtRecordCompleter.cpp:29
lldb_private::TraceSessionSaver::BuildProcessesSection
static llvm::Expected< JSONTraceSessionBase > BuildProcessesSection(Process &live_process, std::function< llvm::Expected< llvm::Optional< std::vector< uint8_t >>>(lldb::tid_t tid)> raw_trace_fetcher, FileSpec directory)
Build the processes section of the trace session description file.
Definition: TraceSessionSaver.cpp:41
TraceJSONStructs.h
lldb::tid_t
uint64_t tid_t
Definition: lldb-types.h:86