---
man2/perf_event_open.2 | 126 ++++++++++++++++++++++++++++--------------------
1 file changed, 73 insertions(+), 53 deletions(-)
diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index ed468f2..eb989d4 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -56,7 +56,7 @@ to measure multiple events simultaneously.
Events can be enabled and disabled in two ways: via
.BR ioctl (2)
and via
-.BR prctl (2) .
+.BR prctl (2).
When an event is disabled it does not count or generate overflows but does
continue to exist and maintain its count value.
.PP
@@ -72,7 +72,7 @@ A
.I sampling
event periodically writes measurements to a buffer that can then
be accessed via
-.BR mmap (2) .
+.BR mmap (2).
.SS Arguments
.P
The argument
@@ -164,7 +164,7 @@ This flag re-routes the output from an event to the group leader.
This flag activates per-container system-wide monitoring.
A container
is an abstraction that isolates a set of resources for finer grain
-control (CPUs, memory, etc...).
+control (CPUs, memory, etc.).
In this mode, the event is measured
only if the thread running on the monitored CPU belongs to the designated
container (cgroup).
@@ -226,7 +226,7 @@ struct perf_event_attr {
exclude_callchain_kernel : 1,
/* exclude kernel callchains */
exclude_callchain_user : 1,
- /* exclude user callchains */
+ /* exclude user callchains */
__reserved_1 : 41;
union {
@@ -331,9 +331,9 @@ is set to 64; this was the size of the first published struct.
.B PERF_ATTR_SIZE_VER1
is 72, corresponding to the addition of breakpoints in Linux 2.6.33.
.B PERF_ATTR_SIZE_VER2
-is 80 corresponding to the addition of branch sampling in Linux 3.4.
+is 80, corresponding to the addition of branch sampling in Linux 3.4.
.B PERF_ATR_SIZE_VER3
-is 96 corresponding to the addition
+is 96, corresponding to the addition
of sample_regs_user and sample_stack_user in Linux 3.7.
.TP
@@ -378,12 +378,12 @@ to one of the following:
.TP
.B PERF_COUNT_HW_CPU_CYCLES
Total cycles.
-Be wary of what happens during CPU frequency scaling
+Be wary of what happens during CPU frequency scaling.
.TP
.B PERF_COUNT_HW_INSTRUCTIONS
Retired instructions.
Be careful, these can be affected by various
-issues, most notably hardware interrupt counts
+issues, most notably hardware interrupt counts.
.TP
.B PERF_COUNT_HW_CACHE_REFERENCES
Cache accesses.
@@ -611,11 +611,11 @@ timer tick.
.I "sample_type"
The various bits in this field specify which values to include
in the sample.
-They will be recorded in a ring-buffer,
+They will be recorded in a ring buffer,
which is available to user-space using
.BR mmap (2).
The order in which the values are saved in the
-sample are documented in the MMAP Layout subsection below;
+sample is documented in the MMAP Layout subsection below;
it is not the
.I "enum perf_event_sample_format"
order.
@@ -653,7 +653,8 @@ Records a unique ID for the opened event.
Unlike
.B PERF_SAMPLE_ID
the actual ID is returned, not the group leader.
-This ID is the same as the one returned by PERF_FORMAT_ID.
+This ID is the same as the one returned by
+.BR PERF_FORMAT_ID .
.TP
.B PERF_SAMPLE_RAW
Records additional data, if applicable.
@@ -661,7 +662,8 @@ Usually returned by tracepoint events.
.TP
.BR PERF_SAMPLE_BRANCH_STACK " (Since Linux 3.4)"
Records the branch stack.
-See branch_sample_type.
+See
+.IR branch_sample_type .
.TP
.BR PERF_SAMPLE_REGS_USER " (Since Linux 3.7)"
Records the current register state.
@@ -778,9 +780,9 @@ bit enables recording of exec mmap events.
The
.I comm
bit enables tracking of process command name as modified by the
-.IR exec (2)
+.BR exec (2)
and
-.IR prctl (PR_SET_NAME)
+.BR prctl (PR_SET_NAME)
system calls.
Unfortunately for tools,
there is no way to distinguish one system call versus the other.
@@ -859,7 +861,7 @@ See also
The counterpart of the
.I mmap
field, but enables including data mmap events
-in the ring-buffer.
+in the ring buffer.
.TP
.IR "sample_id_all" " (Since Linux 2.6.38)"
@@ -872,11 +874,11 @@ is selected.
.TP
.IR "exclude_host" " (Since Linux 3.2)"
-Do not measure time spent in VM host
+Do not measure time spent in VM host.
.TP
.IR "exclude_guest" " (Since Linux 3.2)"
-Do not measure time spent in VM guest
+Do not measure time spent in VM guest.
.TP
.IR "exclude_callchain_kernel" " (Since Linux 3.7)"
@@ -932,7 +934,7 @@ is not allowed.
.TP
.IR "bp_addr" " (Since Linux 2.6.33)"
.I bp_addr
-address of the breakpoint.
+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
of the memory location of interest.
@@ -941,7 +943,9 @@ of the memory location of interest.
.IR "config1" " (Since Linux 2.6.39)"
.I config1
is used for setting events that need an extra register or otherwise
-do not fit in the regular config field.
+do not fit in the regular
+.I config
+field.
Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
on 3.3 and later kernels.
@@ -975,28 +979,28 @@ It can have one of the following values:
.RS
.TP
.B PERF_SAMPLE_BRANCH_USER
-Branch target is in user space
+Branch target is in user space.
.TP
.B PERF_SAMPLE_BRANCH_KERNEL
-Branch target is in kernel space
+Branch target is in kernel space.
.TP
.B PERF_SAMPLE_BRANCH_HV
-Branch target is in hypervisor
+Branch target is in hypervisor.
.TP
.B PERF_SAMPLE_BRANCH_ANY
Any branch type.
.TP
.B PERF_SAMPLE_BRANCH_ANY_CALL
-Any call branch
+Any call branch.
.TP
.B PERF_SAMPLE_BRANCH_ANY_RETURN
-Any return branch
+Any return branch.
.TP
.BR PERF_SAMPLE_BRANCH_IND_CALL
-Indirect calls
+Indirect calls.
.TP
.BR PERF_SAMPLE_BRANCH_PLM_ALL
-User, kernel, and hv
+User, kernel, and hv.
.RE
.TP
@@ -1026,7 +1030,7 @@ structure at open time.
If you attempt to read into a buffer that is not big enough to hold the
data
.B ENOSPC
-is returned
+is returned.
Here is the layout of the data returned by a read:
@@ -1095,7 +1099,8 @@ An unsigned 64-bit value containing the counter result.
.I id
A globally unique value for this particular event, only there if
.B PERF_FORMAT_ID
-was specified in read_format.
+was specified in
+.IR read_format .
.RE
.RE
@@ -1110,15 +1115,15 @@ in sampled mode, asynchronous events
(like counter overflow or
.B PROT_EXEC
mmap tracking)
-are logged into a ring-buffer.
-This ring-buffer is created and accessed through
+are logged into a ring buffer.
+This ring buffer is created and accessed through
.BR mmap (2).
The mmap size should be 1+2^n pages, where the first page is a
metadata page
-.IR ( "struct perf_event_mmap_page" )
+.RI ( "struct perf_event_mmap_page" )
that contains various
-bits of information such as where the ring-buffer head is.
+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
ring buffer when sampling even if you do not plan to access it.
@@ -1190,7 +1195,7 @@ Time the event was running.
.TP
.I cap_usr_time
-User time capability
+User time capability.
.TP
.I cap_usr_rdpmc
@@ -1256,7 +1261,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;
@@ -1294,27 +1301,31 @@ The value continuously increases, it does not wrap.
The value needs to be manually wrapped by the size of the mmap buffer
before accessing the samples.
-On SMP-capable platforms, after reading the data_head value,
+On SMP-capable platforms, after reading the
+.I data_head
+value,
user-space should issue an rmb().
.TP
-.I data_tail;
+.I data_tail
When the mapping is
.BR PROT_WRITE ,
the
.I data_tail
value should be written by user space to reflect the last read data.
-In this case the kernel will not over-write unread data.
+In this case the kernel will not overwrite unread data.
.RE
-The following 2^n ring-buffer pages have the layout described below.
+The following 2^n ring buffer pages have the layout described below.
If
.I perf_event_attr.sample_id_all
is set, then all event types will
-have the sample_type selected fields related to where/when (identity)
+have the
+.I sample_type
+selected fields related to where/when (identity)
an event took place (TID, TIME, ID, CPU, STREAM_ID) described in
.B PERF_RECORD_SAMPLE
below, it will be stashed just after the
@@ -1573,7 +1584,8 @@ the current sampling period is written.
.I v
If
.B PERF_SAMPLE_READ
-is enabled, a structure of type read_format
+is enabled, a structure of type
+.I read_format
is included which has values for all events in the event group.
The values included depend on the
.I read_format
@@ -1702,7 +1714,7 @@ The signal handler is set up using the
.BR select (2),
.BR epoll (2)
and
-.BR fcntl (2),
+.BR fcntl (2)
system calls.
To generate signals, sampling must be enabled
@@ -1756,7 +1768,7 @@ to calculate event values can be found in that section.
.PP
Various ioctls act on
.BR perf_event_open ()
-file descriptors
+file descriptors.
.TP
.B PERF_EVENT_IOC_ENABLE
@@ -1790,14 +1802,14 @@ A signal with
.B POLL_IN
set will happen on each overflow until the
count reaches 0; when that happens a signal with
-POLL_HUP
+.B POLL_HUP
set is sent and the event is disabled.
Using an argument of 0 is considered undefined behavior.
.TP
.B PERF_EVENT_IOC_RESET
Reset the event count specified by the
-file descriptor argumentto zero.
+file descriptor argument to zero.
This only resets the counts; there is no way to reset the
multiplexing
.I time_enabled
@@ -1885,7 +1897,8 @@ The default value is
.TP
.I /proc/sys/kernel/perf_event_mlock_kb
-Maximum number of pages an unprivileged user can mlock (2) .
+Maximum number of pages an unprivileged user can
+.BR mlock (2).
The default is 516 (kB).
.RE
@@ -1903,7 +1916,9 @@ Each subdirectory corresponds to a different PMU.
.I /sys/bus/event_source/devices/*/type
This contains an integer that can be used in the
.I type
-field of perf_event_attr to indicate you wish to use this PMU.
+field of
+.I perf_event_attr
+to indicate you wish to use this PMU.
.TP
.I /sys/bus/event_source/devices/*/rdpmc
@@ -1913,7 +1928,9 @@ field of perf_event_attr to indicate you wish to use this PMU.
.I /sys/bus/event_source/devices/*/format/
This sub-directory contains information on what bits in the
.I config
-field of perf_event_attr correspond to.
+field of
+.I perf_event_attr
+correspond to.
.TP
.I /sys/bus/event_source/devices/*/events/
@@ -1953,18 +1970,18 @@ Linus did not like this, and this was changed to
is still returned if you try to read results into
too small of a buffer.
-.SH VERSION
+.SH VERSIONS
.BR perf_event_open ()
was introduced in Linux 2.6.31 but was called
-.BR perf_counter_open () .
+.BR perf_counter_open ().
It was renamed in Linux 2.6.32.
.SH CONFORMING TO
This
.BR perf_event_open ()
-system call Linux- specific
+system call is Linux-specific
and should not be used in programs intended to be portable.
.SH NOTES
@@ -2002,8 +2019,9 @@ scheduled them in an improper counter slot.
Prior to Linux 2.6.34 there was a bug when multiplexing where the
wrong results could be returned.
-Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
-"inherit" is enabled and many threads are started.
+Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash if
+.I inherit
+is enabled and many threads are started.
Prior to Linux 2.6.35,
.B PERF_FORMAT_GROUP
@@ -2016,7 +2034,9 @@ This behavior is unsupported and should not be relied on.
There is a bug in the kernel code between
Linux 2.6.36 and Linux 3.0 that ignores the
-"watermark" field and acts as if a wakeup_event
+.I watermark
+field and acts as if a
+.I wakeup_event
was chosen if the union has a
non-zero value in it.
--
1.7.10.4
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
