//===-- TraceIntelPT.h ------------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
#ifndef LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_TRACEINTELPT_H
#define LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_TRACEINTELPT_H
#include "TaskTimer.h"
#include "ThreadDecoder.h"
#include "TraceIntelPTBundleLoader.h"
#include "TraceIntelPTMultiCpuDecoder.h"
#include "lldb/Utility/FileSpec.h"
#include "lldb/lldb-types.h"
#include "llvm/Support/raw_ostream.h"
#include <optional>
namespace lldb_private {
namespace trace_intel_pt {
class TraceIntelPT : public Trace {
public:
/// Properties to be used with the `settings` command.
class PluginProperties : public Properties {
public:
static llvm::StringRef GetSettingName();
PluginProperties();
~PluginProperties() override = default;
uint64_t GetInfiniteDecodingLoopVerificationThreshold();
uint64_t GetExtremelyLargeDecodingThreshold();
};
/// Return the global properties for this trace plug-in.
static PluginProperties &GetGlobalProperties();
void Dump(Stream *s) const override;
llvm::Expected<FileSpec> SaveToDisk(FileSpec directory,
bool compact) override;
~TraceIntelPT() override = default;
/// PluginInterface protocol
/// \{
llvm::StringRef GetPluginName() override { return GetPluginNameStatic(); }
static void Initialize();
static void Terminate();
/// Create an instance of this class from a trace bundle.
///
/// \param[in] trace_bundle_description
/// The description of the trace bundle. See \a Trace::FindPlugin.
///
/// \param[in] bundle_dir
/// The path to the directory that contains the trace bundle.
///
/// \param[in] debugger
/// The debugger instance where new Targets will be created as part of the
/// JSON data parsing.
///
/// \return
/// A trace instance or an error in case of failures.
static llvm::Expected<lldb::TraceSP> CreateInstanceForTraceBundle(
const llvm::json::Value &trace_bundle_description,
llvm::StringRef bundle_dir, Debugger &debugger);
static llvm::Expected<lldb::TraceSP>
CreateInstanceForLiveProcess(Process &process);
static llvm::StringRef GetPluginNameStatic() { return "intel-pt"; }
static void DebuggerInitialize(Debugger &debugger);
/// \}
lldb::CommandObjectSP
GetProcessTraceStartCommand(CommandInterpreter &interpreter) override;
lldb::CommandObjectSP
GetThreadTraceStartCommand(CommandInterpreter &interpreter) override;
llvm::StringRef GetSchema() override;
llvm::Expected<lldb::TraceCursorSP> CreateNewCursor(Thread &thread) override;
void DumpTraceInfo(Thread &thread, Stream &s, bool verbose,
bool json) override;
llvm::Expected<std::optional<uint64_t>> GetRawTraceSize(Thread &thread);
llvm::Error DoRefreshLiveProcessState(TraceGetStateResponse state,
llvm::StringRef json_response) override;
bool IsTraced(lldb::tid_t tid) override;
const char *GetStartConfigurationHelp() override;
/// Start tracing a live process.
///
/// More information on the parameters below can be found in the
/// jLLDBTraceStart section in lldb/docs/lldb-gdb-remote.txt.
///
/// \param[in] ipt_trace_size
/// Trace size per thread in bytes.
///
/// \param[in] total_buffer_size_limit
/// Maximum total trace size per process in bytes.
///
/// \param[in] enable_tsc
/// Whether to use enable TSC timestamps or not.
///
/// \param[in] psb_period
/// This value defines the period in which PSB packets will be generated.
///
/// \param[in] per_cpu_tracing
/// This value defines whether to have an intel pt trace buffer per thread
/// or per cpu core.
///
/// \param[in] disable_cgroup_filtering
/// Disable the cgroup filtering that is automatically applied when doing
/// per cpu tracing.
///
/// \return
/// \a llvm::Error::success if the operation was successful, or
/// \a llvm::Error otherwise.
llvm::Error Start(uint64_t ipt_trace_size, uint64_t total_buffer_size_limit,
bool enable_tsc, std::optional<uint64_t> psb_period,
bool m_per_cpu_tracing, bool disable_cgroup_filtering);
/// \copydoc Trace::Start
llvm::Error Start(StructuredData::ObjectSP configuration =
StructuredData::ObjectSP()) override;
/// Start tracing live threads.
///
/// More information on the parameters below can be found in the
/// jLLDBTraceStart section in lldb/docs/lldb-gdb-remote.txt.
///
/// \param[in] tids
/// Threads to trace.
///
/// \param[in] ipt_trace_size
/// Trace size per thread or per cpu core in bytes.
///
/// \param[in] enable_tsc
/// Whether to use enable TSC timestamps or not.
///
/// \param[in] psb_period
/// This value defines the period in which PSB packets will be generated.
///
/// \return
/// \a llvm::Error::success if the operation was successful, or
/// \a llvm::Error otherwise.
llvm::Error Start(llvm::ArrayRef<lldb::tid_t> tids, uint64_t ipt_trace_size,
bool enable_tsc, std::optional<uint64_t> psb_period);
/// \copydoc Trace::Start
llvm::Error Start(llvm::ArrayRef<lldb::tid_t> tids,
StructuredData::ObjectSP configuration =
StructuredData::ObjectSP()) override;
/// See \a Trace::OnThreadBinaryDataRead().
llvm::Error OnThreadBufferRead(lldb::tid_t tid,
OnBinaryDataReadCallback callback);
/// Get or fetch the cpu information from, for example, /proc/cpuinfo.
llvm::Expected<pt_cpu> GetCPUInfo();
/// Get or fetch the values used to convert to and from TSCs and nanos.
std::optional<LinuxPerfZeroTscConversion> GetPerfZeroTscConversion();
/// \return
/// The timer object for this trace.
TaskTimer &GetTimer();
/// \return
/// The ScopedTaskTimer object for the given thread in this trace.
ScopedTaskTimer &GetThreadTimer(lldb::tid_t tid);
/// \return
/// The global copedTaskTimer object for this trace.
ScopedTaskTimer &GetGlobalTimer();
TraceIntelPTSP GetSharedPtr();
enum class TraceMode { UserMode, KernelMode };
TraceMode GetTraceMode();
private:
friend class TraceIntelPTBundleLoader;
llvm::Expected<pt_cpu> GetCPUInfoForLiveProcess();
/// Postmortem trace constructor
///
/// \param[in] bundle_description
/// The definition file for the postmortem bundle.
///
/// \param[in] traced_processes
/// The processes traced in the postmortem session.
///
/// \param[in] trace_threads
/// The threads traced in the postmortem session. They must belong to the
/// processes mentioned above.
///
/// \param[in] trace_mode
/// The tracing mode of the postmortem session.
///
/// \return
/// A TraceIntelPT shared pointer instance.
/// \{
static TraceIntelPTSP CreateInstanceForPostmortemTrace(
JSONTraceBundleDescription &bundle_description,
llvm::ArrayRef<lldb::ProcessSP> traced_processes,
llvm::ArrayRef<lldb::ThreadPostMortemTraceSP> traced_threads,
TraceMode trace_mode);
/// This constructor is used by CreateInstanceForPostmortemTrace to get the
/// instance ready before using shared pointers, which is a limitation of C++.
TraceIntelPT(JSONTraceBundleDescription &bundle_description,
llvm::ArrayRef<lldb::ProcessSP> traced_processes,
TraceMode trace_mode);
/// \}
/// Constructor for live processes
TraceIntelPT(Process &live_process)
: Trace(live_process), trace_mode(TraceMode::UserMode){};
/// Decode the trace of the given thread that, i.e. recontruct the traced
/// instructions.
///
/// \param[in] thread
/// If \a thread is a \a ThreadTrace, then its internal trace file will be
/// decoded. Live threads are not currently supported.
///
/// \return
/// A \a DecodedThread shared pointer with the decoded instructions. Any
/// errors are embedded in the instruction list. An \a llvm::Error is
/// returned if the decoder couldn't be properly set up.
llvm::Expected<DecodedThreadSP> Decode(Thread &thread);
/// \return
/// The lowest timestamp in nanoseconds in all traces if available, \a
/// std::nullopt if all the traces were empty or no trace contained no
/// timing information, or an \a llvm::Error if it was not possible to set
/// up the decoder for some trace.
llvm::Expected<std::optional<uint64_t>> FindBeginningOfTimeNanos();
// Dump out trace info in JSON format
void DumpTraceInfoAsJson(Thread &thread, Stream &s, bool verbose);
/// We package all the data that can change upon process stops to make sure
/// this contract is very visible.
/// This variable should only be accessed directly by constructores or live
/// process data refreshers.
struct Storage {
std::optional<TraceIntelPTMultiCpuDecoder> multicpu_decoder;
/// These decoders are used for the non-per-cpu case
llvm::DenseMap<lldb::tid_t, std::unique_ptr<ThreadDecoder>> thread_decoders;
/// Helper variable used to track long running operations for telemetry.
TaskTimer task_timer;
/// It is provided by either a trace bundle or a live process to convert TSC
/// counters to and from nanos. It might not be available on all hosts.
std::optional<LinuxPerfZeroTscConversion> tsc_conversion;
std::optional<uint64_t> beginning_of_time_nanos;
bool beginning_of_time_nanos_calculated = false;
} m_storage;
/// It is provided by either a trace bundle or a live process' "cpuInfo"
/// binary data. We don't put it in the Storage because this variable doesn't
/// change.
std::optional<pt_cpu> m_cpu_info;
/// Get the storage after refreshing the data in the case of a live process.
Storage &GetUpdatedStorage();
/// The tracing mode of post mortem trace.
TraceMode trace_mode;
};
} // namespace trace_intel_pt
} // namespace lldb_private
#endif // LLDB_SOURCE_PLUGINS_TRACE_INTEL_PT_TRACEINTELPT_H
Codebase Browser
llvm