From 4b3a5f018a0890e99dd10ad0ad00a183a48e23e9 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 17 Oct 2016 11:09:55 +0200 Subject: [PATCH] perf_event_open.2: Minor wording fixes Signed-off-by: Michael Kerrisk --- man2/perf_event_open.2 | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index a7832455b..774c133d0 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -857,8 +857,8 @@ the time the counter is created (nor to any new children of existing children). Inherit does not work for some combinations of -.IR read_format s, -such as +.IR read_format +values, such as .BR PERF_FORMAT_GROUP . .TP .IR "pinned" @@ -1172,8 +1172,8 @@ is not allowed. .IR "bp_addr" " (since Linux 2.6.33)" .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e This is the address of the breakpoint. -For execution breakpoints this is the memory address of the instruction -of interest; for read and write breakpoints it is the memory address +For execution breakpoints, this is the memory address of the instruction +of interest; for read and write breakpoints, it is the memory address of the memory location of interest. .TP .IR "config1" " (since Linux 2.6.39)" @@ -1182,7 +1182,7 @@ of the memory location of interest. is used for setting events that need an extra register or otherwise do not fit in the regular config field. Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field -on 3.3 and later kernels. +on Linux 3.3 and later kernels. .TP .IR "bp_len" " (since Linux 2.6.33)" .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e @@ -1195,6 +1195,7 @@ Options are .BR HW_BREAKPOINT_LEN_1 , .BR HW_BREAKPOINT_LEN_2 , .BR HW_BREAKPOINT_LEN_4 , +and .BR HW_BREAKPOINT_LEN_8 . For an execution breakpoint, set this to .IR sizeof(long) . @@ -1214,7 +1215,7 @@ is enabled, then this specifies what branches to include in the branch record. The first part of the value is the privilege level, which -is a combination of one of the following values. +is a combination of one of the values listed below. If the user does not set privilege level explicitly, the kernel will use the event's privilege level. Event and branch privilege levels do not have to match. @@ -1277,7 +1278,7 @@ on Intel x86 Haswell or newer. .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56 This bit mask defines the set of user CPU registers to dump on samples. The layout of the register mask is architecture-specific and -described in the kernel header +is described in the kernel header file .IR arch/ARCH/include/uapi/asm/perf_regs.h . .TP .IR "sample_stack_user" " (since Linux 3.7)" @@ -1315,7 +1316,7 @@ When .I sample_type includes .BR PERF_SAMPLE_CALLCHAIN , -this filed specifies how many stack frames to report when +this field specifies how many stack frames to report when generating the callchain. .SS Reading results Once a @@ -1329,9 +1330,9 @@ field in the structure at open time. If you attempt to read into a buffer that is not big enough to hold the -data +data, the error .B ENOSPC -is returned +results. Here is the layout of the data returned by a read: .IP * 2 @@ -1380,7 +1381,7 @@ was specified. .TP .IR time_enabled ", " time_running Total time the event was enabled and running. -Normally these are the same. +Normally these values are the same. If more events are started, then available counter slots on the PMU, then multiplexing happens and events run only part of the time. @@ -1394,7 +1395,7 @@ values can be used to scale an estimated value for the count. An unsigned 64-bit value containing the counter result. .TP .I id -A globally unique value for this particular event, only present if +A globally unique value for this particular event; only present if .B PERF_FORMAT_ID was specified in .IR read_format . @@ -1594,7 +1595,9 @@ count += pmc; If .IR cap_usr_time , these fields can be used to compute the time -delta since time_enabled (in nanoseconds) using rdtsc or similar. +delta since +.I time_enabled +(in nanoseconds) using rdtsc or similar. .nf u64 quot, rem; @@ -1731,8 +1734,8 @@ below, it will be stashed just after the .I perf_event_header and the fields already present for the existing fields, that is, at the end of the payload. -That way a newer perf.data -file will be supported by older perf tools, with these new optional +This allows a newer perf.data +file to be supported by older perf tools, with the new optional fields being ignored. The mmap values start with a header: @@ -2400,7 +2403,7 @@ Abort due to read capacity overflow. In addition, a user-specified abort code can be obtained from the high 32 bits of the field by shifting right by .B PERF_TXN_ABORT_SHIFT -and masking with +and masking with the value .BR PERF_TXN_ABORT_MASK . .TP .IR abi ", " regs[weight(mask)] @@ -2411,7 +2414,9 @@ is enabled, then the user CPU registers are recorded. The .I abi field is one of -.BR PERF_SAMPLE_REGS_ABI_NONE ", " PERF_SAMPLE_REGS_ABI_32 " or " +.BR PERF_SAMPLE_REGS_ABI_NONE , +.BR PERF_SAMPLE_REGS_ABI_32 , +or .BR PERF_SAMPLE_REGS_ABI_64 . The @@ -2579,7 +2584,7 @@ event file descriptor with .BR poll (2), .BR select (2), or -.BR epoll (2). +.BR epoll (7). Alternately, a SIGIO signal handler can be created and the event configured with .BR fcntl (2)