| //===-- 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 = llvm::None); |
| |
| /// 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 |