LLDB  mainline
IntelPTSingleBufferTrace.h
Go to the documentation of this file.
1 //===-- IntelPTSingleBufferTrace.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 liblldb_IntelPTSingleBufferTrace_H_
10 #define liblldb_IntelPTSingleBufferTrace_H_
11 
12 #include "Perf.h"
14 #include "lldb/lldb-types.h"
15 #include "llvm/Support/Error.h"
16 #include <memory>
17 
18 namespace lldb_private {
19 namespace process_linux {
20 
21 llvm::Expected<uint32_t> GetIntelPTOSEventType();
22 
23 /// This class wraps a single perf event collecting intel pt data in a single
24 /// buffer.
26 public:
27  /// Start tracing using a single Intel PT trace buffer.
28  ///
29  /// \param[in] request
30  /// Intel PT configuration parameters.
31  ///
32  /// \param[in] tid
33  /// The tid of the thread to be traced. If \b None, then this traces all
34  /// threads of all processes.
35  ///
36  /// \param[in] cpu_id
37  /// The CPU core id where to trace. If \b None, then this traces all CPUs.
38  ///
39  /// \param[in] disabled
40  /// If \b true, then no data is collected until \a Resume is invoked.
41  /// Similarly, if \b false, data is collected right away until \a Pause is
42  /// invoked.
43  ///
44  /// \param[in] cgroup_fd
45  /// A file descriptor in /sys/fs associated with the cgroup of the process
46  /// to trace. If not \a llvm::None, then the trace sesion will use cgroup
47  /// filtering.
48  ///
49  /// \return
50  /// A \a IntelPTSingleBufferTrace instance if tracing was successful, or
51  /// an \a llvm::Error otherwise.
52  static llvm::Expected<IntelPTSingleBufferTrace>
53  Start(const TraceIntelPTStartRequest &request,
54  llvm::Optional<lldb::tid_t> tid,
55  llvm::Optional<lldb::cpu_id_t> cpu_id = llvm::None,
56  bool disabled = false, llvm::Optional<int> cgroup_fd = llvm::None);
57 
58  /// \return
59  /// The bytes requested by a jLLDBTraceGetBinaryData packet that was routed
60  /// to this trace instace.
61  llvm::Expected<std::vector<uint8_t>>
62  GetBinaryData(const TraceGetBinaryDataRequest &request) const;
63 
64  /// Read the intel pt trace buffer managed by this trace instance. To ensure
65  /// that the data is up-to-date and is not corrupted by read-write race
66  /// conditions, the underlying perf_event is paused during read, and later
67  /// it's returned to its initial state.
68  ///
69  /// \return
70  /// A vector with the requested binary data.
71  llvm::Expected<std::vector<uint8_t>> GetIptTrace();
72 
73  /// \return
74  /// The total the size in bytes used by the intel pt trace buffer managed
75  /// by this trace instance.
76  size_t GetIptTraceSize() const;
77 
78  /// Resume the collection of this trace.
79  ///
80  /// \return
81  /// An error if the trace couldn't be resumed. If the trace is already
82  /// running, this returns \a Error::success().
84 
85  /// Pause the collection of this trace.
86  ///
87  /// \return
88  /// An error if the trace couldn't be paused. If the trace is already
89  /// paused, this returns \a Error::success().
91 
92  /// \return
93  /// The underlying PerfEvent for this trace.
94  const PerfEvent &GetPerfEvent() const;
95 
96 private:
97  /// Construct new \a IntelPTSingleBufferThreadTrace. Users are supposed to
98  /// create instances of this class via the \a Start() method and not invoke
99  /// this one directly.
100  ///
101  /// \param[in] perf_event
102  /// perf event configured for IntelPT.
103  ///
104  /// \param[in] collection_state
105  /// The initial collection state for the provided perf_event.
107  : m_perf_event(std::move(perf_event)) {}
108 
109  /// perf event configured for IntelPT.
111 };
112 
113 } // namespace process_linux
114 } // namespace lldb_private
115 
116 #endif // liblldb_IntelPTSingleBufferTrace_H_
lldb_private::TraceGetBinaryDataRequest
jLLDBTraceGetBinaryData gdb-remote packet
Definition: TraceGDBRemotePackets.h:149
lldb_private::process_linux::PerfEvent
Thin wrapper of the perf_event_open API.
Definition: Perf.h:80
lldb_private::process_linux::IntelPTSingleBufferTrace::Resume
llvm::Error Resume()
Resume the collection of this trace.
Definition: IntelPTSingleBufferTrace.cpp:208
lldb_private::process_linux::IntelPTSingleBufferTrace::m_perf_event
PerfEvent m_perf_event
perf event configured for IntelPT.
Definition: IntelPTSingleBufferTrace.h:110
lldb_private::process_linux::IntelPTSingleBufferTrace::GetBinaryData
llvm::Expected< std::vector< uint8_t > > GetBinaryData(const TraceGetBinaryDataRequest &request) const
lldb_private::process_linux::IntelPTSingleBufferTrace::IntelPTSingleBufferTrace
IntelPTSingleBufferTrace(PerfEvent &&perf_event)
Construct new IntelPTSingleBufferThreadTrace.
Definition: IntelPTSingleBufferTrace.h:106
TraceIntelPTGDBRemotePackets.h
lldb_private::process_linux::IntelPTSingleBufferTrace::GetIptTraceSize
size_t GetIptTraceSize() const
Definition: IntelPTSingleBufferTrace.cpp:200
lldb_private::process_linux::IntelPTSingleBufferTrace
This class wraps a single perf event collecting intel pt data in a single buffer.
Definition: IntelPTSingleBufferTrace.h:25
lldb_private::TraceIntelPTStartRequest
jLLDBTraceStart gdb-remote packet
Definition: TraceIntelPTGDBRemotePackets.h:33
lldb-types.h
lldb_private::process_linux::IntelPTSingleBufferTrace::Pause
llvm::Error Pause()
Pause the collection of this trace.
Definition: IntelPTSingleBufferTrace.cpp:204
lldb_private::process_linux::IntelPTSingleBufferTrace::GetPerfEvent
const PerfEvent & GetPerfEvent() const
Definition: IntelPTSingleBufferTrace.cpp:283
lldb_private::process_linux::IntelPTSingleBufferTrace::Start
static llvm::Expected< IntelPTSingleBufferTrace > Start(const TraceIntelPTStartRequest &request, llvm::Optional< lldb::tid_t > tid, llvm::Optional< lldb::cpu_id_t > cpu_id=llvm::None, bool disabled=false, llvm::Optional< int > cgroup_fd=llvm::None)
Start tracing using a single Intel PT trace buffer.
Definition: IntelPTSingleBufferTrace.cpp:230
Perf.h
lldb_private::process_linux::IntelPTSingleBufferTrace::GetIptTrace
llvm::Expected< std::vector< uint8_t > > GetIptTrace()
Read the intel pt trace buffer managed by this trace instance.
Definition: IntelPTSingleBufferTrace.cpp:212
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
Error
llvm::Error Error
Definition: UdtRecordCompleter.cpp:30
lldb_private::process_linux::GetIntelPTOSEventType
llvm::Expected< uint32_t > GetIntelPTOSEventType()
Return the Linux perf event type for Intel PT.
Definition: IntelPTSingleBufferTrace.cpp:107