328 lines
12 KiB
C++
328 lines
12 KiB
C++
//===-- Perf.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
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
/// \file
|
|
/// This file contains a thin wrapper of the perf_event_open API
|
|
/// and classes to handle the destruction of file descriptors
|
|
/// and mmap pointers.
|
|
///
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#ifndef LLDB_SOURCE_PLUGINS_PROCESS_LINUX_PERF_H
|
|
#define LLDB_SOURCE_PLUGINS_PROCESS_LINUX_PERF_H
|
|
|
|
#include "lldb/Utility/TraceIntelPTGDBRemotePackets.h"
|
|
#include "lldb/lldb-types.h"
|
|
#include "llvm/Support/Error.h"
|
|
#include <chrono>
|
|
#include <cstdint>
|
|
#include <linux/perf_event.h>
|
|
|
|
namespace lldb_private {
|
|
namespace process_linux {
|
|
namespace resource_handle {
|
|
|
|
/// Custom deleter for the pointer returned by \a mmap.
|
|
///
|
|
/// This functor type is provided to \a unique_ptr to properly
|
|
/// unmap the region at destruction time.
|
|
class MmapDeleter {
|
|
public:
|
|
/// Construct new \a MmapDeleter.
|
|
///
|
|
/// \param[in] bytes
|
|
/// Size of the mmap'ed region in bytes.
|
|
MmapDeleter(size_t bytes = 0) : m_bytes(bytes) {}
|
|
|
|
/// Unmap the mmap'ed region.
|
|
///
|
|
/// If \a m_bytes==0 or \a ptr==nullptr, nothing is unmmapped.
|
|
///
|
|
/// \param[in] ptr
|
|
/// pointer to the region to be unmmapped.
|
|
void operator()(void *ptr);
|
|
|
|
private:
|
|
/// Size of the mmap'ed region, in bytes, to be unmapped.
|
|
size_t m_bytes;
|
|
};
|
|
|
|
/// Custom deleter for a file descriptor.
|
|
///
|
|
/// This functor type is provided to \a unique_ptr to properly release
|
|
/// the resources associated with the file descriptor at destruction time.
|
|
class FileDescriptorDeleter {
|
|
public:
|
|
/// Close and free the memory associated with the file descriptor pointer.
|
|
///
|
|
/// Effectively a no-op if \a ptr==nullptr or \a*ptr==-1.
|
|
///
|
|
/// \param[in] ptr
|
|
/// Pointer to the file descriptor.
|
|
void operator()(long *ptr);
|
|
};
|
|
|
|
using FileDescriptorUP =
|
|
std::unique_ptr<long, resource_handle::FileDescriptorDeleter>;
|
|
using MmapUP = std::unique_ptr<void, resource_handle::MmapDeleter>;
|
|
|
|
} // namespace resource_handle
|
|
|
|
/// Thin wrapper of the perf_event_open API.
|
|
///
|
|
/// Exposes the metadata page and data and aux buffers of a perf event.
|
|
/// Handles the management of the event's file descriptor and mmap'ed
|
|
/// regions.
|
|
class PerfEvent {
|
|
public:
|
|
/// Create a new performance monitoring event via the perf_event_open syscall.
|
|
///
|
|
/// The parameters are directly forwarded to a perf_event_open syscall,
|
|
/// for additional information on the parameters visit
|
|
/// https://man7.org/linux/man-pages/man2/perf_event_open.2.html.
|
|
///
|
|
/// \param[in] attr
|
|
/// Configuration information for the event.
|
|
///
|
|
/// \param[in] pid
|
|
/// The process or thread to be monitored by the event. If \b None, then
|
|
/// all processes and threads are monitored.
|
|
///
|
|
/// \param[in] cpu
|
|
/// The cpu to be monitored by the event. If \b None, then all cpus are
|
|
/// monitored.
|
|
///
|
|
/// \param[in] group_fd
|
|
/// File descriptor of the group leader. If \b None, then this perf_event
|
|
/// doesn't belong to a preexisting group.
|
|
///
|
|
/// \param[in] flags
|
|
/// Bitmask of additional configuration flags.
|
|
///
|
|
/// \return
|
|
/// If the perf_event_open syscall was successful, a minimal \a PerfEvent
|
|
/// instance, or an \a llvm::Error otherwise.
|
|
static llvm::Expected<PerfEvent> Init(perf_event_attr &attr,
|
|
llvm::Optional<lldb::pid_t> pid,
|
|
llvm::Optional<lldb::cpu_id_t> cpu,
|
|
llvm::Optional<long> group_fd,
|
|
unsigned long flags);
|
|
|
|
/// Create a new performance monitoring event via the perf_event_open syscall
|
|
/// with "default" values for the cpu, group_fd and flags arguments.
|
|
///
|
|
/// Convenience method to be used when the perf event requires minimal
|
|
/// configuration. It handles the default values of all other arguments.
|
|
///
|
|
/// \param[in] attr
|
|
/// Configuration information for the event.
|
|
///
|
|
/// \param[in] pid
|
|
/// The process or thread to be monitored by the event. If \b None, then
|
|
/// all threads and processes are monitored.
|
|
static llvm::Expected<PerfEvent>
|
|
Init(perf_event_attr &attr, llvm::Optional<lldb::pid_t> pid,
|
|
llvm::Optional<lldb::cpu_id_t> core = std::nullopt);
|
|
|
|
/// Mmap the metadata page and the data and aux buffers of the perf event and
|
|
/// expose them through \a PerfEvent::GetMetadataPage() , \a
|
|
/// PerfEvent::GetDataBuffer() and \a PerfEvent::GetAuxBuffer().
|
|
///
|
|
/// This uses mmap underneath, which means that the number of pages mmap'ed
|
|
/// must be less than the actual data available by the kernel. The metadata
|
|
/// page is always mmap'ed.
|
|
///
|
|
/// Mmap is needed because the underlying data might be changed by the kernel
|
|
/// dynamically.
|
|
///
|
|
/// \param[in] num_data_pages
|
|
/// Number of pages in the data buffer to mmap, must be a power of 2.
|
|
/// A value of 0 is useful for "dummy" events that only want to access
|
|
/// the metadata, \a perf_event_mmap_page, or the aux buffer.
|
|
///
|
|
/// \param[in] num_aux_pages
|
|
/// Number of pages in the aux buffer to mmap, must be a power of 2.
|
|
/// A value of 0 effectively is a no-op and no data is mmap'ed for this
|
|
/// buffer.
|
|
///
|
|
/// \param[in] data_buffer_write
|
|
/// Whether to mmap the data buffer with WRITE permissions. This changes
|
|
/// the behavior of how the kernel writes to the data buffer.
|
|
///
|
|
/// \return
|
|
/// \a llvm::Error::success if the mmap operations succeeded,
|
|
/// or an \a llvm::Error otherwise.
|
|
llvm::Error MmapMetadataAndBuffers(size_t num_data_pages,
|
|
size_t num_aux_pages,
|
|
bool data_buffer_write);
|
|
|
|
/// Get the file descriptor associated with the perf event.
|
|
long GetFd() const;
|
|
|
|
/// Get the metadata page from the data section's mmap buffer.
|
|
///
|
|
/// The metadata page is always mmap'ed, even when \a num_data_pages is 0.
|
|
///
|
|
/// This should be called only after \a PerfEvent::MmapMetadataAndBuffers,
|
|
/// otherwise a failure might happen.
|
|
///
|
|
/// \return
|
|
/// The data section's \a perf_event_mmap_page.
|
|
perf_event_mmap_page &GetMetadataPage() const;
|
|
|
|
/// Get the data buffer from the data section's mmap buffer.
|
|
///
|
|
/// The data buffer is the region of the data section's mmap buffer where
|
|
/// perf sample data is located.
|
|
///
|
|
/// This should be called only after \a PerfEvent::MmapMetadataAndBuffers,
|
|
/// otherwise a failure might happen.
|
|
///
|
|
/// \return
|
|
/// \a ArrayRef<uint8_t> extending \a data_size bytes from \a data_offset.
|
|
llvm::ArrayRef<uint8_t> GetDataBuffer() const;
|
|
|
|
/// Get the AUX buffer.
|
|
///
|
|
/// AUX buffer is a region for high-bandwidth data streams
|
|
/// such as IntelPT. This is separate from the metadata and data buffer.
|
|
///
|
|
/// This should be called only after \a PerfEvent::MmapMetadataAndBuffers,
|
|
/// otherwise a failure might happen.
|
|
///
|
|
/// \return
|
|
/// \a ArrayRef<uint8_t> extending \a aux_size bytes from \a aux_offset.
|
|
llvm::ArrayRef<uint8_t> GetAuxBuffer() const;
|
|
|
|
/// Read the aux buffer managed by this perf event assuming it was configured
|
|
/// with PROT_READ permissions only, which indicates that the buffer is
|
|
/// automatically wrapped and overwritten by the kernel or hardware. To ensure
|
|
/// that the data is up-to-date and is not corrupted by read-write race
|
|
/// conditions, the underlying perf_event is paused during read, and later
|
|
/// it's returned to its initial state. The returned data will be linear, i.e.
|
|
/// it will fix the circular wrapping the might exist in the buffer.
|
|
///
|
|
/// \return
|
|
/// A vector with the requested binary data.
|
|
llvm::Expected<std::vector<uint8_t>> GetReadOnlyAuxBuffer();
|
|
|
|
/// Read the data buffer managed by this perf even assuming it was configured
|
|
/// with PROT_READ permissions only, which indicates that the buffer is
|
|
/// automatically wrapped and overwritten by the kernel or hardware. To ensure
|
|
/// that the data is up-to-date and is not corrupted by read-write race
|
|
/// conditions, the underlying perf_event is paused during read, and later
|
|
/// it's returned to its initial state. The returned data will be linear, i.e.
|
|
/// it will fix the circular wrapping the might exist int he buffer.
|
|
///
|
|
/// \return
|
|
/// A vector with the requested binary data.
|
|
llvm::Expected<std::vector<uint8_t>> GetReadOnlyDataBuffer();
|
|
|
|
/// Use the ioctl API to disable the perf event and all the events in its
|
|
/// group. This doesn't terminate the perf event.
|
|
///
|
|
/// This is no-op if the perf event is already disabled.
|
|
///
|
|
/// \return
|
|
/// An Error if the perf event couldn't be disabled.
|
|
llvm::Error DisableWithIoctl();
|
|
|
|
/// Use the ioctl API to enable the perf event and all the events in its
|
|
/// group.
|
|
///
|
|
/// This is no-op if the perf event is already enabled.
|
|
///
|
|
/// \return
|
|
/// An Error if the perf event couldn't be enabled.
|
|
llvm::Error EnableWithIoctl();
|
|
|
|
/// \return
|
|
/// The size in bytes of the section of the data buffer that has effective
|
|
/// data.
|
|
size_t GetEffectiveDataBufferSize() const;
|
|
|
|
/// \return
|
|
/// \b true if and only the perf event is enabled and collecting.
|
|
bool IsEnabled() const;
|
|
|
|
private:
|
|
/// Create new \a PerfEvent.
|
|
///
|
|
/// \param[in] fd
|
|
/// File descriptor of the perf event.
|
|
///
|
|
/// \param[in] enabled
|
|
/// Initial collection state configured for this perf_event.
|
|
PerfEvent(long fd, bool enabled)
|
|
: m_fd(new long(fd), resource_handle::FileDescriptorDeleter()),
|
|
m_enabled(enabled) {}
|
|
|
|
/// Wrapper for \a mmap to provide custom error messages.
|
|
///
|
|
/// The parameters are directly forwarded to a \a mmap syscall,
|
|
/// for information on the parameters visit
|
|
/// https://man7.org/linux/man-pages/man2/mmap.2.html.
|
|
///
|
|
/// The value of \a GetFd() is passed as the \a fd argument to \a mmap.
|
|
llvm::Expected<resource_handle::MmapUP> DoMmap(void *addr, size_t length,
|
|
int prot, int flags,
|
|
long int offset,
|
|
llvm::StringRef buffer_name);
|
|
|
|
/// Mmap the data buffer of the perf event.
|
|
///
|
|
/// \param[in] num_data_pages
|
|
/// Number of pages in the data buffer to mmap, must be a power of 2.
|
|
/// A value of 0 is useful for "dummy" events that only want to access
|
|
/// the metadata, \a perf_event_mmap_page, or the aux buffer.
|
|
///
|
|
/// \param[in] data_buffer_write
|
|
/// Whether to mmap the data buffer with WRITE permissions. This changes
|
|
/// the behavior of how the kernel writes to the data buffer.
|
|
llvm::Error MmapMetadataAndDataBuffer(size_t num_data_pages,
|
|
bool data_buffer_write);
|
|
|
|
/// Mmap the aux buffer of the perf event.
|
|
///
|
|
/// \param[in] num_aux_pages
|
|
/// Number of pages in the aux buffer to mmap, must be a power of 2.
|
|
/// A value of 0 effectively is a no-op and no data is mmap'ed for this
|
|
/// buffer.
|
|
llvm::Error MmapAuxBuffer(size_t num_aux_pages);
|
|
|
|
/// The file descriptor representing the perf event.
|
|
resource_handle::FileDescriptorUP m_fd;
|
|
/// Metadata page and data section where perf samples are stored.
|
|
resource_handle::MmapUP m_metadata_data_base;
|
|
/// AUX buffer is a separate region for high-bandwidth data streams
|
|
/// such as IntelPT.
|
|
resource_handle::MmapUP m_aux_base;
|
|
/// The state of the underlying perf_event.
|
|
bool m_enabled;
|
|
};
|
|
|
|
/// Create a perf event that tracks context switches on a cpu.
|
|
///
|
|
/// \param[in] cpu_id
|
|
/// The core to trace.
|
|
///
|
|
/// \param[in] parent_perf_event
|
|
/// An optional perf event that will be grouped with the
|
|
/// new perf event.
|
|
llvm::Expected<PerfEvent>
|
|
CreateContextSwitchTracePerfEvent(lldb::cpu_id_t cpu_id,
|
|
const PerfEvent *parent_perf_event = nullptr);
|
|
|
|
/// Load \a PerfTscConversionParameters from \a perf_event_mmap_page, if
|
|
/// available.
|
|
llvm::Expected<LinuxPerfZeroTscConversion> LoadPerfTscConversionParameters();
|
|
|
|
} // namespace process_linux
|
|
} // namespace lldb_private
|
|
|
|
#endif // LLDB_SOURCE_PLUGINS_PROCESS_LINUX_PERF_H
|