Thin wrapper of the perf_event_open API. More...

#include <Perf.h>

Public Member Functions
llvm::Error	MmapMetadataAndBuffers (size_t num_data_pages, size_t num_aux_pages, bool data_buffer_write)
	Mmap the metadata page and the data and aux buffers of the perf event and expose them through PerfEvent::GetMetadataPage() , PerfEvent::GetDataBuffer() and PerfEvent::GetAuxBuffer().
long	GetFd () const
	Get the file descriptor associated with the perf event.
perf_event_mmap_page &	GetMetadataPage () const
	Get the metadata page from the data section's mmap buffer.
llvm::ArrayRef< uint8_t >	GetDataBuffer () const
	Get the data buffer from the data section's mmap buffer.
llvm::ArrayRef< uint8_t >	GetAuxBuffer () const
	Get the AUX buffer.
llvm::Expected< std::vector< uint8_t > >	GetReadOnlyAuxBuffer ()
	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.
llvm::Expected< std::vector< uint8_t > >	GetReadOnlyDataBuffer ()
	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.
llvm::Error	DisableWithIoctl ()
	Use the ioctl API to disable the perf event and all the events in its group.
llvm::Error	EnableWithIoctl ()
	Use the ioctl API to enable the perf event and all the events in its group.
size_t	GetEffectiveDataBufferSize () const
bool	IsEnabled () const

Static Public Member Functions
static llvm::Expected< PerfEvent >	Init (perf_event_attr &attr, std::optional< lldb::pid_t > pid, std::optional< lldb::cpu_id_t > cpu, std::optional< long > group_fd, unsigned long flags)
	Create a new performance monitoring event via the perf_event_open syscall.
static llvm::Expected< PerfEvent >	Init (perf_event_attr &attr, std::optional< lldb::pid_t > pid, std::optional< lldb::cpu_id_t > core=std::nullopt)
	Create a new performance monitoring event via the perf_event_open syscall with "default" values for the cpu, group_fd and flags arguments.

Private Member Functions
	PerfEvent (long fd, bool enabled)
	Create new PerfEvent.
llvm::Expected< resource_handle::MmapUP >	DoMmap (void *addr, size_t length, int prot, int flags, long int offset, llvm::StringRef buffer_name)
	Wrapper for mmap to provide custom error messages.
llvm::Error	MmapMetadataAndDataBuffer (size_t num_data_pages, bool data_buffer_write)
	Mmap the data buffer of the perf event.
llvm::Error	MmapAuxBuffer (size_t num_aux_pages)
	Mmap the aux buffer of the perf event.

Private Attributes
resource_handle::FileDescriptorUP	m_fd
	The file descriptor representing the perf event.
resource_handle::MmapUP	m_metadata_data_base
	Metadata page and data section where perf samples are stored.
resource_handle::MmapUP	m_aux_base
	AUX buffer is a separate region for high-bandwidth data streams such as IntelPT.
bool	m_enabled
	The state of the underlying perf_event.

Detailed Description

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.

Definition at line 80 of file Perf.h.

Constructor & Destructor Documentation

◆ PerfEvent()

lldb_private::process_linux::PerfEvent::PerfEvent	(	long	fd,
		bool	enabled )

inlineprivate

Create new PerfEvent.

Parameters

[in]	fd	File descriptor of the perf event.
[in]	enabled	Initial collection state configured for this perf_event.

Definition at line 260 of file Perf.h.

References m_enabled, and m_fd.

Referenced by Init().

Member Function Documentation

◆ DisableWithIoctl()

Error PerfEvent::DisableWithIoctl ( )

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.

Returns: An Error if the perf event couldn't be disabled.

Definition at line 291 of file Perf.cpp.

References createStringError(), m_enabled, and m_fd.

Referenced by GetReadOnlyAuxBuffer(), and GetReadOnlyDataBuffer().

◆ DoMmap()

llvm::Expected< resource_handle::MmapUP > PerfEvent::DoMmap	(	void *	addr,
		size_t	length,
		int	prot,
		int	flags,
		long int	offset,
		llvm::StringRef	buffer_name )

private

Wrapper for mmap to provide custom error messages.

The parameters are directly forwarded to a mmap syscall, for information on the parameters visit https://man7.org/linux/man-pages/man2/mmap.2.html.

The value of GetFd() is passed as the fd argument to mmap.

Definition at line 100 of file Perf.cpp.

References createStringError(), and GetFd().

Referenced by MmapAuxBuffer(), and MmapMetadataAndDataBuffer().

◆ EnableWithIoctl()

Error PerfEvent::EnableWithIoctl ( )

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.

Returns: An Error if the perf event couldn't be enabled.

Definition at line 306 of file Perf.cpp.

References createStringError(), m_enabled, and m_fd.

Referenced by GetReadOnlyAuxBuffer(), and GetReadOnlyDataBuffer().

◆ GetAuxBuffer()

ArrayRef< uint8_t > PerfEvent::GetAuxBuffer ( ) 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 PerfEvent::MmapMetadataAndBuffers, otherwise a failure might happen.

Returns: ArrayRef<uint8_t> extending aux_size bytes from aux_offset.

Definition at line 187 of file Perf.cpp.

References GetMetadataPage(), and m_aux_base.

Referenced by GetReadOnlyAuxBuffer().

◆ GetDataBuffer()

ArrayRef< uint8_t > PerfEvent::GetDataBuffer ( ) 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 PerfEvent::MmapMetadataAndBuffers, otherwise a failure might happen.

Returns: ArrayRef<uint8_t> extending data_size bytes from data_offset.

Definition at line 176 of file Perf.cpp.

References GetMetadataPage(), and m_metadata_data_base.

Referenced by GetReadOnlyDataBuffer().

◆ GetEffectiveDataBufferSize()

size_t PerfEvent::GetEffectiveDataBufferSize ( ) const

Returns: The size in bytes of the section of the data buffer that has effective data.

Definition at line 319 of file Perf.cpp.

References GetMetadataPage().

Referenced by lldb_private::process_linux::IntelPTMultiCoreTrace::GetState().

◆ GetFd()

long PerfEvent::GetFd ( ) const

Get the file descriptor associated with the perf event.

Definition at line 170 of file Perf.cpp.

References m_fd.

Referenced by lldb_private::process_linux::CreateContextSwitchTracePerfEvent(), and DoMmap().

◆ GetMetadataPage()

perf_event_mmap_page & PerfEvent::GetMetadataPage ( ) const

Get the metadata page from the data section's mmap buffer.

The metadata page is always mmap'ed, even when num_data_pages is 0.

This should be called only after PerfEvent::MmapMetadataAndBuffers, otherwise a failure might happen.

Returns: The data section's perf_event_mmap_page.

Definition at line 172 of file Perf.cpp.

References m_metadata_data_base.

Referenced by GetAuxBuffer(), GetDataBuffer(), GetEffectiveDataBufferSize(), GetReadOnlyAuxBuffer(), GetReadOnlyDataBuffer(), and MmapAuxBuffer().

◆ GetReadOnlyAuxBuffer()

Expected< std::vector< uint8_t > > PerfEvent::GetReadOnlyAuxBuffer ( )

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.

Returns: A vector with the requested binary data.

Definition at line 246 of file Perf.cpp.

References createStringError(), DisableWithIoctl(), EnableWithIoctl(), GetAuxBuffer(), GetMetadataPage(), and m_enabled.

◆ GetReadOnlyDataBuffer()

Expected< std::vector< uint8_t > > PerfEvent::GetReadOnlyDataBuffer ( )

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.

Returns: A vector with the requested binary data.

Definition at line 197 of file Perf.cpp.

References createStringError(), DisableWithIoctl(), EnableWithIoctl(), GetDataBuffer(), GetMetadataPage(), and m_enabled.

◆ Init() [1/2]

llvm::Expected< PerfEvent > PerfEvent::Init	(	perf_event_attr &	attr,
		std::optional< lldb::pid_t >	pid,
		std::optional< lldb::cpu_id_t >	core = std::nullopt )

static

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.

Parameters

[in]	attr	Configuration information for the event.
[in]	pid	The process or thread to be monitored by the event. If std::nullopt, then all threads and processes are monitored.

Definition at line 93 of file Perf.cpp.

References Init().

◆ Init() [2/2]

llvm::Expected< PerfEvent > PerfEvent::Init	(	perf_event_attr &	attr,
		std::optional< lldb::pid_t >	pid,
		std::optional< lldb::cpu_id_t >	cpu,
		std::optional< long >	group_fd,
		unsigned long	flags )

static

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.

Parameters

[in]	attr	Configuration information for the event.
[in]	pid	The process or thread to be monitored by the event. If None, then all processes and threads are monitored.
[in]	cpu	The cpu to be monitored by the event. If None, then all cpus are monitored.
[in]	group_fd	File descriptor of the group leader. If None, then this perf_event doesn't belong to a preexisting group.
[in]	flags	Bitmask of additional configuration flags.

Returns: If the perf_event_open syscall was successful, a minimal PerfEvent instance, or an llvm::Error otherwise.

Definition at line 77 of file Perf.cpp.

References PerfEvent().

Referenced by lldb_private::process_linux::CreateContextSwitchTracePerfEvent(), Init(), lldb_private::process_linux::LoadPerfTscConversionParameters(), and lldb_private::process_linux::IntelPTSingleBufferTrace::Start().

◆ IsEnabled()

bool PerfEvent::IsEnabled ( ) const

Returns: true if and only the perf event is enabled and collecting.

Definition at line 304 of file Perf.cpp.

References m_enabled.

Referenced by lldb_private::process_linux::CreateContextSwitchTracePerfEvent().

◆ MmapAuxBuffer()

llvm::Error PerfEvent::MmapAuxBuffer ( size_t num_aux_pages )

private

Mmap the aux buffer of the perf event.

Parameters

[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.

Definition at line 126 of file Perf.cpp.

References createStringError(), DoMmap(), GetMetadataPage(), m_aux_base, and PROT_READ.

Referenced by MmapMetadataAndBuffers().

◆ MmapMetadataAndBuffers()

llvm::Error PerfEvent::MmapMetadataAndBuffers	(	size_t	num_data_pages,
		size_t	num_aux_pages,
		bool	data_buffer_write )

Mmap the metadata page and the data and aux buffers of the perf event and expose them through PerfEvent::GetMetadataPage() , PerfEvent::GetDataBuffer() and 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.

Parameters

[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, perf_event_mmap_page, or the aux buffer.
[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.
[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.

Returns: llvm::Error::success if the mmap operations succeeded, or an llvm::Error otherwise.

Definition at line 150 of file Perf.cpp.

References MmapAuxBuffer(), and MmapMetadataAndDataBuffer().

◆ MmapMetadataAndDataBuffer()

llvm::Error PerfEvent::MmapMetadataAndDataBuffer	(	size_t	num_data_pages,
		bool	data_buffer_write )

private

Mmap the data buffer of the perf event.

Parameters

[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, perf_event_mmap_page, or the aux buffer.
[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.

Definition at line 114 of file Perf.cpp.

References DoMmap(), m_metadata_data_base, PROT_READ, and PROT_WRITE.

Referenced by MmapMetadataAndBuffers().

Member Data Documentation

◆ m_aux_base

resource_handle::MmapUP lldb_private::process_linux::PerfEvent::m_aux_base

private

AUX buffer is a separate region for high-bandwidth data streams such as IntelPT.

Definition at line 303 of file Perf.h.

Referenced by GetAuxBuffer(), and MmapAuxBuffer().

◆ m_enabled

bool lldb_private::process_linux::PerfEvent::m_enabled

private

The state of the underlying perf_event.

Definition at line 305 of file Perf.h.

Referenced by DisableWithIoctl(), EnableWithIoctl(), GetReadOnlyAuxBuffer(), GetReadOnlyDataBuffer(), IsEnabled(), and PerfEvent().

◆ m_fd

resource_handle::FileDescriptorUP lldb_private::process_linux::PerfEvent::m_fd

private

The file descriptor representing the perf event.

Definition at line 298 of file Perf.h.

Referenced by DisableWithIoctl(), EnableWithIoctl(), GetFd(), and PerfEvent().

◆ m_metadata_data_base

resource_handle::MmapUP lldb_private::process_linux::PerfEvent::m_metadata_data_base

private

Metadata page and data section where perf samples are stored.

Definition at line 300 of file Perf.h.

Referenced by GetDataBuffer(), GetMetadataPage(), and MmapMetadataAndDataBuffer().

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PerfEvent()

Member Function Documentation

◆ DisableWithIoctl()

◆ DoMmap()

◆ EnableWithIoctl()

◆ GetAuxBuffer()

◆ GetDataBuffer()

◆ GetEffectiveDataBufferSize()

◆ GetFd()

◆ GetMetadataPage()

◆ GetReadOnlyAuxBuffer()

◆ GetReadOnlyDataBuffer()

◆ Init() [1/2]

◆ Init() [2/2]

◆ IsEnabled()

◆ MmapAuxBuffer()

◆ MmapMetadataAndBuffers()

◆ MmapMetadataAndDataBuffer()

Member Data Documentation

◆ m_aux_base

◆ m_enabled

◆ m_fd

◆ m_metadata_data_base