From 95655a22795948470e8f2228360d8c57b8f66000 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 14 Oct 2015 08:58:28 +0200 Subject: [PATCH] perf_event_open.2: Minor fixes Signed-off-by: Michael Kerrisk --- man2/perf_event_open.2 | 41 ++++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index fc7481f2d..d10fd6286 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -1261,7 +1261,7 @@ Branch in transactional memory transaction. Branch not in transactional memory transaction. .BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)" .\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70 -Branch is part of a hardware generated call stack. +Branch is part of a hardware-generated call stack. This requires hardware support, currently only found on Intel x86 Haswell or newer. .RE @@ -1289,8 +1289,12 @@ use for timestamps. The available timers are defined in .IR linux/time.h , with -.BR CLOCK_MONOTONIC , CLOCK_MONOTONIC_RAW , CLOCK_REALTIME , -.BR CLOCK_BOOTTIME ", and " CLOCK_TAI +.BR CLOCK_MONOTONIC , +.BR CLOCK_MONOTONIC_RAW , +.BR CLOCK_REALTIME , +.BR CLOCK_BOOTTIME , +and +.B CLOCK_TAI currently supported. .TP .IR "aux_watermark" " (since Linux 4.1)" @@ -1396,7 +1400,7 @@ metadata page that contains various bits of information such as where the ring-buffer head is. -Before kernel 2.6.39, there is a bug that means you must allocate a mmap +Before kernel 2.6.39, there is a bug that means you must allocate an mmap ring buffer when sampling even if you do not plan to access it. The structure of the first metadata mmap page is as follows: @@ -1664,9 +1668,9 @@ the mmap buffer. .TP .IR aux_head ", " aux_tail ", " aux_offset ", " aux_size " (since Linux 4.1) .\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff -The AUX region allows mmaping a separate sample buffer for high -bandwidth data streams (separate from the main perf sample buffer). -An example of a high bandwidth stream is instruction tracing support, +The AUX region allows mmaping a separate sample buffer for +high-bandwidth data streams (separate from the main perf sample buffer). +An example of a high-bandwidth stream is instruction tracing support, as is found in newer Intel processors. To set up an AUX area, first @@ -1679,17 +1683,20 @@ needs to be set to the desired buffer size. The desired offset and size must be page aligned, and the size must be a power of two. These values are then passed to mmap in order to map the AUX buffer. -Pages in the AUX buffer are included as part of the user mlock -rlimit as well as the +Pages in the AUX buffer are included as part of the +.BR RLIMIT_MEMLOCK +resource limit (see +.BR setrlimit (2)), +and also as part of the .I perf_event_mlock_kb allowance. -By default the AUX buffer will be truncated if it will not fit +By default, the AUX buffer will be truncated if it will not fit in the available space in the ring buffer. If the AUX buffer is mapped as a read only buffer, then it will operate in ring buffer mode where old data will be overwritten by new. -In overwrite mode it might not be possible to infer where the +In overwrite mode, it might not be possible to infer where the new data began, and it is the consumer's job to disable measurement while reading to avoid possible data races. @@ -2493,16 +2500,16 @@ offset in the AUX mmap region where the new data begins. size of the data made available. .TP .I flags -describes the aux update. +describes the AUX update. .RS .TP .B PERF_AUX_FLAG_TRUNCATED -if set then the data returned was truncated to fit the available +if set, then the data returned was truncated to fit the available buffer size. .TP .B PERF_AUX_FLAG_OVERWRITE .\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142 -if set then the data returned has overwritten previous data. +if set, then the data returned has overwritten previous data. .RE .RE .TP @@ -2523,10 +2530,10 @@ struct { .RS .TP .I pid -process id of the thread starting an instruction trace. +process ID of the thread starting an instruction trace. .TP .I tid -thread id of the thread starting an instruction trace. +thread ID of the thread starting an instruction trace. .RE .RE .SS Overflow handling @@ -2602,7 +2609,7 @@ the counters. Starting with Linux 4.0 .\" 7911d3f7af14a614617e38245fedf98a724e46a9 rdpmc support is only allowed if an event is currently enabled -in a process' context. +in a process's context. To restore the old behavior, write the value 2 to .IR /sys/devices/cpu/rdpmc . .SS perf_event ioctl calls