wire / wire-format / perf-event-ring

perf_event_open ring buffer page (perf_event_mmap_page)

The perf_event_open(2) syscall returns a file descriptor; mmap'ing it gives a shared memory region whose first page is a perf_event_mmap_page control structure. It contains the data_head/data_tail pointers (for the ring buffer), time conversion parameters (for converting hardware timestamps to nanoseconds), and capability bits.

wire-format kind wire-format status standard verification verified tier B wire-format@1

aka: perf_event_open ring buffer page (perf_event_mmap_page)

wire format

spec: Linux kernel (perf_event_open)

The perf_event_open(2) syscall returns a file descriptor; mmap'ing it gives a shared memory region whose first page is a perf_event_mmap_page control structure. It contains the data_head/data_tail pointers (for the ring buffer), time conversion parameters (for converting hardware timestamps to nanoseconds), and capability bits.

fieldsizemeaning
version4 bytes (__u32)Version of the structure (current = 1).
compat_version4 bytes (__u32)Lowest compatible version.
lock4 bytes (__u32)Seqlock for consistent reads of the time fields.
index8 bytes (__u64)Hardware PMU counter index (if PERF_FORMAT_TOTAL_TIME_ENABLED).
offset8 bytes (__u64)Offset to add to the raw counter value.
time_enabled8 bytes (__u64)Time the event was enabled (in nanoseconds).
time_running8 bytes (__u64)Time the event was running (accounts for multiplexing).
cap (union)8 bytesCapability bits: cap_usr_time, cap_usr_rdpmc, cap_bit0_is_deprecated, etc.
pmc_width2 bytes (__u16)Width of the PMU counter in bits.
time_shift2 bytes (__u16)Shift for time conversion: (time_enabled - time_zero) >> time_shift.
time_mult4 bytes (__u32)Multiplier for time conversion.
time_offset8 bytes (__u64)Offset for time conversion.
time_zero8 bytes (__u64)Time base for conversion.
size4 bytes (__u32)Size of this structure.
data_head8 bytes (__u64)Head of the data ring (written by kernel; read by userspace).
data_tail8 bytes (__u64)Tail of the data ring (written by userspace; read by kernel).
data_offset8 bytes (__u64)Offset from mmap base to the data ring.
data_size8 bytes (__u64)Size of the data ring (power of 2).

example:

01 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

perf_event_mmap_page with version 1, data_head=0, data_tail=0


provenance

agent: curl -H 'accept: application/json' wire.phall.io/wire-format/perf-event-ring or /wire-format/perf-event-ring.json