|
|
96cc1f |
From b4bd8040f471c245455a66c32c8979d3262faa2f Mon Sep 17 00:00:00 2001
|
|
|
96cc1f |
From: =?UTF-8?q?Nikola=20Forr=C3=B3?= <nforro@redhat.com>
|
|
|
96cc1f |
Date: Wed, 22 Aug 2018 11:11:05 +0200
|
|
|
96cc1f |
Subject: [PATCH 3/3] perf_event_open.2: sync with upstream
|
|
|
96cc1f |
|
|
|
96cc1f |
---
|
|
|
96cc1f |
man-pages/man2/perf_event_open.2 | 2448 +++++++++++++++++++++++-------
|
|
|
96cc1f |
1 file changed, 1861 insertions(+), 587 deletions(-)
|
|
|
96cc1f |
|
|
|
96cc1f |
diff --git a/man-pages/man2/perf_event_open.2 b/man-pages/man2/perf_event_open.2
|
|
|
96cc1f |
index 2ab3eb9..0f29d96 100644
|
|
|
96cc1f |
--- a/man-pages/man2/perf_event_open.2
|
|
|
96cc1f |
+++ b/man-pages/man2/perf_event_open.2
|
|
|
96cc1f |
@@ -24,19 +24,19 @@
|
|
|
96cc1f |
.\" This document is based on the perf_event.h header file, the
|
|
|
96cc1f |
.\" tools/perf/design.txt file, and a lot of bitter experience.
|
|
|
96cc1f |
.\"
|
|
|
96cc1f |
-.TH PERF_EVENT_OPEN 2 2013-07-16 "Linux" "Linux Programmer's Manual"
|
|
|
96cc1f |
+.TH PERF_EVENT_OPEN 2 2018-02-02 "Linux" "Linux Programmer's Manual"
|
|
|
96cc1f |
.SH NAME
|
|
|
96cc1f |
perf_event_open \- set up performance monitoring
|
|
|
96cc1f |
.SH SYNOPSIS
|
|
|
96cc1f |
.nf
|
|
|
96cc1f |
.B #include <linux/perf_event.h>
|
|
|
96cc1f |
.B #include <linux/hw_breakpoint.h>
|
|
|
96cc1f |
-.sp
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
.BI "int perf_event_open(struct perf_event_attr *" attr ,
|
|
|
96cc1f |
.BI " pid_t " pid ", int " cpu ", int " group_fd ,
|
|
|
96cc1f |
.BI " unsigned long " flags );
|
|
|
96cc1f |
.fi
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
.IR Note :
|
|
|
96cc1f |
There is no glibc wrapper for this system call; see NOTES.
|
|
|
96cc1f |
.SH DESCRIPTION
|
|
|
96cc1f |
@@ -56,7 +56,7 @@ to measure multiple events simultaneously.
|
|
|
96cc1f |
Events can be enabled and disabled in two ways: via
|
|
|
96cc1f |
.BR ioctl (2)
|
|
|
96cc1f |
and via
|
|
|
96cc1f |
-.BR prctl (2) .
|
|
|
96cc1f |
+.BR prctl (2).
|
|
|
96cc1f |
When an event is disabled it does not count or generate overflows but does
|
|
|
96cc1f |
continue to exist and maintain its count value.
|
|
|
96cc1f |
.PP
|
|
|
96cc1f |
@@ -72,58 +72,48 @@ A
|
|
|
96cc1f |
.I sampling
|
|
|
96cc1f |
event periodically writes measurements to a buffer that can then
|
|
|
96cc1f |
be accessed via
|
|
|
96cc1f |
-.BR mmap (2) .
|
|
|
96cc1f |
+.BR mmap (2).
|
|
|
96cc1f |
.SS Arguments
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
-The argument
|
|
|
96cc1f |
-.I pid
|
|
|
96cc1f |
-allows events to be attached to processes in various ways.
|
|
|
96cc1f |
-If
|
|
|
96cc1f |
-.I pid
|
|
|
96cc1f |
-is 0, measurements happen on the current thread, if
|
|
|
96cc1f |
-.I pid
|
|
|
96cc1f |
-is greater than 0, the process indicated by
|
|
|
96cc1f |
-.I pid
|
|
|
96cc1f |
-is measured, and if
|
|
|
96cc1f |
-.I pid
|
|
|
96cc1f |
-is \-1, all processes are counted.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The
|
|
|
96cc1f |
-.I cpu
|
|
|
96cc1f |
-argument allows measurements to be specific to a CPU.
|
|
|
96cc1f |
-If
|
|
|
96cc1f |
-.I cpu
|
|
|
96cc1f |
-is greater than or equal to 0,
|
|
|
96cc1f |
-measurements are restricted to the specified CPU;
|
|
|
96cc1f |
-if
|
|
|
96cc1f |
-.I cpu
|
|
|
96cc1f |
-is \-1, the events are measured on all CPUs.
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
-Note that the combination of
|
|
|
96cc1f |
-.IR pid " == \-1"
|
|
|
96cc1f |
-and
|
|
|
96cc1f |
-.IR cpu " == \-1"
|
|
|
96cc1f |
-is not valid.
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
-A
|
|
|
96cc1f |
-.IR pid " > 0"
|
|
|
96cc1f |
-and
|
|
|
96cc1f |
-.IR cpu " == \-1"
|
|
|
96cc1f |
-setting measures per-process and follows that process to whatever CPU the
|
|
|
96cc1f |
-process gets scheduled to.
|
|
|
96cc1f |
-Per-process events can be created by any user.
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
-A
|
|
|
96cc1f |
-.IR pid " == \-1"
|
|
|
96cc1f |
+.I pid
|
|
|
96cc1f |
and
|
|
|
96cc1f |
-.IR cpu " >= 0"
|
|
|
96cc1f |
-setting is per-CPU and measures all processes on the specified CPU.
|
|
|
96cc1f |
-Per-CPU events need the
|
|
|
96cc1f |
+.I cpu
|
|
|
96cc1f |
+arguments allow specifying which process and CPU to monitor:
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR "pid == 0" " and " "cpu == \-1"
|
|
|
96cc1f |
+This measures the calling process/thread on any CPU.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR "pid == 0" " and " "cpu >= 0"
|
|
|
96cc1f |
+This measures the calling process/thread only
|
|
|
96cc1f |
+when running on the specified CPU.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR "pid > 0" " and " "cpu == \-1"
|
|
|
96cc1f |
+This measures the specified process/thread on any CPU.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR "pid > 0" " and " "cpu >= 0"
|
|
|
96cc1f |
+This measures the specified process/thread only
|
|
|
96cc1f |
+when running on the specified CPU.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR "pid == \-1" " and " "cpu >= 0"
|
|
|
96cc1f |
+This measures all processes/threads on the specified CPU.
|
|
|
96cc1f |
+This requires
|
|
|
96cc1f |
.B CAP_SYS_ADMIN
|
|
|
96cc1f |
capability or a
|
|
|
96cc1f |
.I /proc/sys/kernel/perf_event_paranoid
|
|
|
96cc1f |
value of less than 1.
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR "pid == \-1" " and " "cpu == \-1"
|
|
|
96cc1f |
+This setting is invalid and will return an error.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+When
|
|
|
96cc1f |
+.I pid
|
|
|
96cc1f |
+is greater than zero, permission to perform this system call
|
|
|
96cc1f |
+is governed by a ptrace access mode
|
|
|
96cc1f |
+.B PTRACE_MODE_READ_REALCREDS
|
|
|
96cc1f |
+check; see
|
|
|
96cc1f |
+.BR ptrace (2).
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The
|
|
|
96cc1f |
.I group_fd
|
|
|
96cc1f |
argument allows event groups to be created.
|
|
|
96cc1f |
@@ -134,7 +124,7 @@ The rest of the group members are created with subsequent
|
|
|
96cc1f |
.BR perf_event_open ()
|
|
|
96cc1f |
calls with
|
|
|
96cc1f |
.IR group_fd
|
|
|
96cc1f |
-being set to the fd of the group leader.
|
|
|
96cc1f |
+being set to the file descriptor of the group leader.
|
|
|
96cc1f |
(A single event on its own is created with
|
|
|
96cc1f |
.IR group_fd " = \-1"
|
|
|
96cc1f |
and is considered to be a group with only 1 member.)
|
|
|
96cc1f |
@@ -142,29 +132,51 @@ An event group is scheduled onto the CPU as a unit: it will
|
|
|
96cc1f |
be put onto the CPU only if all of the events in the group can be put onto
|
|
|
96cc1f |
the CPU.
|
|
|
96cc1f |
This means that the values of the member events can be
|
|
|
96cc1f |
-meaningfully compared, added, divided (to get ratios), etc., with each
|
|
|
96cc1f |
+meaningfully compared\(emadded, divided (to get ratios), and so on\(emwith each
|
|
|
96cc1f |
other, since they have counted events for the same set of executed
|
|
|
96cc1f |
instructions.
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The
|
|
|
96cc1f |
.I flags
|
|
|
96cc1f |
argument is formed by ORing together zero or more of the following values:
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
+.BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)"
|
|
|
96cc1f |
+.\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e
|
|
|
96cc1f |
+This flag enables the close-on-exec flag for the created
|
|
|
96cc1f |
+event file descriptor,
|
|
|
96cc1f |
+so that the file descriptor is automatically closed on
|
|
|
96cc1f |
+.BR execve (2).
|
|
|
96cc1f |
+Setting the close-on-exec flags at creation time, rather than later with
|
|
|
96cc1f |
+.BR fcntl (2),
|
|
|
96cc1f |
+avoids potential race conditions where the calling thread invokes
|
|
|
96cc1f |
+.BR perf_event_open ()
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.BR fcntl (2)
|
|
|
96cc1f |
+at the same time as another thread calls
|
|
|
96cc1f |
+.BR fork (2)
|
|
|
96cc1f |
+then
|
|
|
96cc1f |
+.BR execve (2).
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.BR PERF_FLAG_FD_NO_GROUP
|
|
|
96cc1f |
-.\" FIXME The following sentence is unclear
|
|
|
96cc1f |
-This flag allows creating an event as part of an event group but
|
|
|
96cc1f |
-having no group leader.
|
|
|
96cc1f |
-It is unclear why this is useful.
|
|
|
96cc1f |
-.\" FIXME So, why is it useful?
|
|
|
96cc1f |
+This flag tells the event to ignore the
|
|
|
96cc1f |
+.IR group_fd
|
|
|
96cc1f |
+parameter except for the purpose of setting up output redirection
|
|
|
96cc1f |
+using the
|
|
|
96cc1f |
+.B PERF_FLAG_FD_OUTPUT
|
|
|
96cc1f |
+flag.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_FLAG_FD_OUTPUT
|
|
|
96cc1f |
-This flag re-routes the output from an event to the group leader.
|
|
|
96cc1f |
+.BR PERF_FLAG_FD_OUTPUT " (broken since Linux 2.6.35)"
|
|
|
96cc1f |
+.\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318
|
|
|
96cc1f |
+This flag re-routes the event's sampled output to instead
|
|
|
96cc1f |
+be included in the mmap buffer of the event specified by
|
|
|
96cc1f |
+.IR group_fd .
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_FLAG_PID_CGROUP " (Since Linux 2.6.39)."
|
|
|
96cc1f |
+.BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)"
|
|
|
96cc1f |
+.\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25
|
|
|
96cc1f |
This flag activates per-container system-wide monitoring.
|
|
|
96cc1f |
A container
|
|
|
96cc1f |
-is an abstraction that isolates a set of resources for finer grain
|
|
|
96cc1f |
-control (CPUs, memory, etc...).
|
|
|
96cc1f |
+is an abstraction that isolates a set of resources for finer-grained
|
|
|
96cc1f |
+control (CPUs, memory, etc.).
|
|
|
96cc1f |
In this mode, the event is measured
|
|
|
96cc1f |
only if the thread running on the monitored CPU belongs to the designated
|
|
|
96cc1f |
container (cgroup).
|
|
|
96cc1f |
@@ -182,52 +194,58 @@ must be passed as the
|
|
|
96cc1f |
parameter.
|
|
|
96cc1f |
cgroup monitoring is available only
|
|
|
96cc1f |
for system-wide events and may therefore require extra permissions.
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The
|
|
|
96cc1f |
.I perf_event_attr
|
|
|
96cc1f |
structure provides detailed configuration information
|
|
|
96cc1f |
for the event being created.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct perf_event_attr {
|
|
|
96cc1f |
- __u32 type; /* Type of event */
|
|
|
96cc1f |
- __u32 size; /* Size of attribute structure */
|
|
|
96cc1f |
- __u64 config; /* Type-specific configuration */
|
|
|
96cc1f |
+ __u32 type; /* Type of event */
|
|
|
96cc1f |
+ __u32 size; /* Size of attribute structure */
|
|
|
96cc1f |
+ __u64 config; /* Type-specific configuration */
|
|
|
96cc1f |
|
|
|
96cc1f |
union {
|
|
|
96cc1f |
__u64 sample_period; /* Period of sampling */
|
|
|
96cc1f |
__u64 sample_freq; /* Frequency of sampling */
|
|
|
96cc1f |
};
|
|
|
96cc1f |
|
|
|
96cc1f |
- __u64 sample_type; /* Specifies values included in sample */
|
|
|
96cc1f |
- __u64 read_format; /* Specifies values returned in read */
|
|
|
96cc1f |
-
|
|
|
96cc1f |
- __u64 disabled : 1, /* off by default */
|
|
|
96cc1f |
- inherit : 1, /* children inherit it */
|
|
|
96cc1f |
- pinned : 1, /* must always be on PMU */
|
|
|
96cc1f |
- exclusive : 1, /* only group on PMU */
|
|
|
96cc1f |
- exclude_user : 1, /* don't count user */
|
|
|
96cc1f |
- exclude_kernel : 1, /* don't count kernel */
|
|
|
96cc1f |
- exclude_hv : 1, /* don't count hypervisor */
|
|
|
96cc1f |
- exclude_idle : 1, /* don't count when idle */
|
|
|
96cc1f |
- mmap : 1, /* include mmap data */
|
|
|
96cc1f |
- comm : 1, /* include comm data */
|
|
|
96cc1f |
- freq : 1, /* use freq, not period */
|
|
|
96cc1f |
- inherit_stat : 1, /* per task counts */
|
|
|
96cc1f |
- enable_on_exec : 1, /* next exec enables */
|
|
|
96cc1f |
- task : 1, /* trace fork/exit */
|
|
|
96cc1f |
- watermark : 1, /* wakeup_watermark */
|
|
|
96cc1f |
- precise_ip : 2, /* skid constraint */
|
|
|
96cc1f |
- mmap_data : 1, /* non-exec mmap data */
|
|
|
96cc1f |
- sample_id_all : 1, /* sample_type all events */
|
|
|
96cc1f |
- exclude_host : 1, /* don't count in host */
|
|
|
96cc1f |
- exclude_guest : 1, /* don't count in guest */
|
|
|
96cc1f |
- exclude_callchain_kernel : 1,
|
|
|
96cc1f |
- /* exclude kernel callchains */
|
|
|
96cc1f |
- exclude_callchain_user : 1,
|
|
|
96cc1f |
- /* exclude user callchains */
|
|
|
96cc1f |
- __reserved_1 : 41;
|
|
|
96cc1f |
+ __u64 sample_type; /* Specifies values included in sample */
|
|
|
96cc1f |
+ __u64 read_format; /* Specifies values returned in read */
|
|
|
96cc1f |
+
|
|
|
96cc1f |
+ __u64 disabled : 1, /* off by default */
|
|
|
96cc1f |
+ inherit : 1, /* children inherit it */
|
|
|
96cc1f |
+ pinned : 1, /* must always be on PMU */
|
|
|
96cc1f |
+ exclusive : 1, /* only group on PMU */
|
|
|
96cc1f |
+ exclude_user : 1, /* don't count user */
|
|
|
96cc1f |
+ exclude_kernel : 1, /* don't count kernel */
|
|
|
96cc1f |
+ exclude_hv : 1, /* don't count hypervisor */
|
|
|
96cc1f |
+ exclude_idle : 1, /* don't count when idle */
|
|
|
96cc1f |
+ mmap : 1, /* include mmap data */
|
|
|
96cc1f |
+ comm : 1, /* include comm data */
|
|
|
96cc1f |
+ freq : 1, /* use freq, not period */
|
|
|
96cc1f |
+ inherit_stat : 1, /* per task counts */
|
|
|
96cc1f |
+ enable_on_exec : 1, /* next exec enables */
|
|
|
96cc1f |
+ task : 1, /* trace fork/exit */
|
|
|
96cc1f |
+ watermark : 1, /* wakeup_watermark */
|
|
|
96cc1f |
+ precise_ip : 2, /* skid constraint */
|
|
|
96cc1f |
+ mmap_data : 1, /* non-exec mmap data */
|
|
|
96cc1f |
+ sample_id_all : 1, /* sample_type all events */
|
|
|
96cc1f |
+ exclude_host : 1, /* don't count in host */
|
|
|
96cc1f |
+ exclude_guest : 1, /* don't count in guest */
|
|
|
96cc1f |
+ exclude_callchain_kernel : 1,
|
|
|
96cc1f |
+ /* exclude kernel callchains */
|
|
|
96cc1f |
+ exclude_callchain_user : 1,
|
|
|
96cc1f |
+ /* exclude user callchains */
|
|
|
96cc1f |
+ mmap2 : 1, /* include mmap with inode data */
|
|
|
96cc1f |
+ comm_exec : 1, /* flag comm events that are
|
|
|
96cc1f |
+ due to exec */
|
|
|
96cc1f |
+ use_clockid : 1, /* use clockid for time fields */
|
|
|
96cc1f |
+ context_switch : 1, /* context switch data */
|
|
|
96cc1f |
+
|
|
|
96cc1f |
+ __reserved_1 : 37;
|
|
|
96cc1f |
|
|
|
96cc1f |
union {
|
|
|
96cc1f |
__u32 wakeup_events; /* wakeup every n events */
|
|
|
96cc1f |
@@ -238,23 +256,31 @@ struct perf_event_attr {
|
|
|
96cc1f |
|
|
|
96cc1f |
union {
|
|
|
96cc1f |
__u64 bp_addr; /* breakpoint address */
|
|
|
96cc1f |
+ __u64 kprobe_func; /* for perf_kprobe */
|
|
|
96cc1f |
+ __u64 uprobe_path; /* for perf_uprobe */
|
|
|
96cc1f |
__u64 config1; /* extension of config */
|
|
|
96cc1f |
};
|
|
|
96cc1f |
|
|
|
96cc1f |
union {
|
|
|
96cc1f |
__u64 bp_len; /* breakpoint length */
|
|
|
96cc1f |
+ __u64 kprobe_addr; /* with kprobe_func == NULL */
|
|
|
96cc1f |
+ __u64 probe_offset; /* for perf_[k,u]probe */
|
|
|
96cc1f |
__u64 config2; /* extension of config1 */
|
|
|
96cc1f |
};
|
|
|
96cc1f |
- __u64 branch_sample_type; /* enum perf_branch_sample_type */
|
|
|
96cc1f |
- __u64 sample_regs_user; /* user regs to dump on samples */
|
|
|
96cc1f |
- __u32 sample_stack_user; /* size of stack to dump on
|
|
|
96cc1f |
+ __u64 branch_sample_type; /* enum perf_branch_sample_type */
|
|
|
96cc1f |
+ __u64 sample_regs_user; /* user regs to dump on samples */
|
|
|
96cc1f |
+ __u32 sample_stack_user; /* size of stack to dump on
|
|
|
96cc1f |
samples */
|
|
|
96cc1f |
- __u32 __reserved_2; /* Align to u64 */
|
|
|
96cc1f |
+ __s32 clockid; /* clock to use for time fields */
|
|
|
96cc1f |
+ __u64 sample_regs_intr; /* regs to dump on samples */
|
|
|
96cc1f |
+ __u32 aux_watermark; /* aux bytes before wakeup */
|
|
|
96cc1f |
+ __u16 sample_max_stack; /* max frames in callchain */
|
|
|
96cc1f |
+ __u16 __reserved_2; /* align to u64 */
|
|
|
96cc1f |
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The fields of the
|
|
|
96cc1f |
.I perf_event_attr
|
|
|
96cc1f |
structure are described in more detail below:
|
|
|
96cc1f |
@@ -289,13 +315,15 @@ field definition.
|
|
|
96cc1f |
This indicates a "raw" implementation-specific event in the
|
|
|
96cc1f |
.IR config " field."
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_TYPE_BREAKPOINT " (Since Linux 2.6.33)"
|
|
|
96cc1f |
+.BR PERF_TYPE_BREAKPOINT " (since Linux 2.6.33)"
|
|
|
96cc1f |
+.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
|
|
|
96cc1f |
This indicates a hardware breakpoint as provided by the CPU.
|
|
|
96cc1f |
Breakpoints can be read/write accesses to an address as well as
|
|
|
96cc1f |
execution of an instruction address.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.RB "dynamic PMU"
|
|
|
96cc1f |
-Since Linux 2.6.39,
|
|
|
96cc1f |
+Since Linux 2.6.38,
|
|
|
96cc1f |
+.\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19
|
|
|
96cc1f |
.BR perf_event_open ()
|
|
|
96cc1f |
can support multiple PMUs.
|
|
|
96cc1f |
To enable this, a value exported by the kernel can be used in the
|
|
|
96cc1f |
@@ -304,7 +332,7 @@ field to indicate which PMU to use.
|
|
|
96cc1f |
The value to use can be found in the sysfs filesystem:
|
|
|
96cc1f |
there is a subdirectory per PMU instance under
|
|
|
96cc1f |
.IR /sys/bus/event_source/devices .
|
|
|
96cc1f |
-In each sub-directory there is a
|
|
|
96cc1f |
+In each subdirectory there is a
|
|
|
96cc1f |
.I type
|
|
|
96cc1f |
file whose content is an integer that can be used in the
|
|
|
96cc1f |
.I type
|
|
|
96cc1f |
@@ -312,6 +340,17 @@ field.
|
|
|
96cc1f |
For instance,
|
|
|
96cc1f |
.I /sys/bus/event_source/devices/cpu/type
|
|
|
96cc1f |
contains the value for the core CPU PMU, which is usually 4.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR kprobe " and " uprobe " (since Linux 4.17)"
|
|
|
96cc1f |
+.\" commit 65074d43fc77bcae32776724b7fa2696923c78e4
|
|
|
96cc1f |
+.\" commit e12f03d7031a977356e3d7b75a68c2185ff8d155
|
|
|
96cc1f |
+.\" commit 33ea4b24277b06dbc55d7f5772a46f029600255e
|
|
|
96cc1f |
+These two dynamic PMUs create a kprobe/uprobe and attach it to the
|
|
|
96cc1f |
+file descriptor generated by perf_event_open.
|
|
|
96cc1f |
+The kprobe/uprobe will be destroyed on the destruction of the file descriptor.
|
|
|
96cc1f |
+See fields
|
|
|
96cc1f |
+.IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset
|
|
|
96cc1f |
+for more details.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I "size"
|
|
|
96cc1f |
@@ -322,21 +361,36 @@ Set this using
|
|
|
96cc1f |
.I sizeof(struct perf_event_attr)
|
|
|
96cc1f |
to allow the kernel to see
|
|
|
96cc1f |
the struct size at the time of compilation.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The related define
|
|
|
96cc1f |
.B PERF_ATTR_SIZE_VER0
|
|
|
96cc1f |
is set to 64; this was the size of the first published struct.
|
|
|
96cc1f |
.B PERF_ATTR_SIZE_VER1
|
|
|
96cc1f |
is 72, corresponding to the addition of breakpoints in Linux 2.6.33.
|
|
|
96cc1f |
+.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
|
|
|
96cc1f |
+.\" this was added much later when PERF_ATTR_SIZE_VER2 happened
|
|
|
96cc1f |
+.\" but the actual attr_size had increased in 2.6.33
|
|
|
96cc1f |
.B PERF_ATTR_SIZE_VER2
|
|
|
96cc1f |
is 80 corresponding to the addition of branch sampling in Linux 3.4.
|
|
|
96cc1f |
-.B PERF_ATR_SIZE_VER3
|
|
|
96cc1f |
+.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
|
|
|
96cc1f |
+.B PERF_ATTR_SIZE_VER3
|
|
|
96cc1f |
is 96 corresponding to the addition
|
|
|
96cc1f |
of
|
|
|
96cc1f |
.I sample_regs_user
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.I sample_stack_user
|
|
|
96cc1f |
in Linux 3.7.
|
|
|
96cc1f |
+.\" commit 1659d129ed014b715b0b2120e6fd929bdd33ed03
|
|
|
96cc1f |
+.B PERF_ATTR_SIZE_VER4
|
|
|
96cc1f |
+is 104 corresponding to the addition of
|
|
|
96cc1f |
+.I sample_regs_intr
|
|
|
96cc1f |
+in Linux 3.19.
|
|
|
96cc1f |
+.\" commit 60e2364e60e86e81bc6377f49779779e6120977f
|
|
|
96cc1f |
+.B PERF_ATTR_SIZE_VER5
|
|
|
96cc1f |
+is 112 corresponding to the addition of
|
|
|
96cc1f |
+.I aux_watermark
|
|
|
96cc1f |
+in Linux 4.1.
|
|
|
96cc1f |
+.\" commit 1a5941312414c71dece6717da9a0fa1303127afa
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I "config"
|
|
|
96cc1f |
This specifies which event you want, in conjunction with
|
|
|
96cc1f |
@@ -348,13 +402,7 @@ The
|
|
|
96cc1f |
fields are also taken into account in cases where 64 bits is not
|
|
|
96cc1f |
enough to fully specify the event.
|
|
|
96cc1f |
The encoding of these fields are event dependent.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-The most significant bit (bit 63) of
|
|
|
96cc1f |
-.I config
|
|
|
96cc1f |
-signifies CPU-specific (raw) counter configuration data;
|
|
|
96cc1f |
-if the most significant bit is unset, the next 7 bits are an event
|
|
|
96cc1f |
-type and the rest of the bits are the event identifier.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
There are various ways to set the
|
|
|
96cc1f |
.I config
|
|
|
96cc1f |
field that are dependent on the value of the previously
|
|
|
96cc1f |
@@ -365,7 +413,7 @@ What follows are various possible settings for
|
|
|
96cc1f |
.I config
|
|
|
96cc1f |
separated out by
|
|
|
96cc1f |
.IR type .
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.I type
|
|
|
96cc1f |
is
|
|
|
96cc1f |
@@ -379,12 +427,12 @@ to one of the following:
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_COUNT_HW_CPU_CYCLES
|
|
|
96cc1f |
Total cycles.
|
|
|
96cc1f |
-Be wary of what happens during CPU frequency scaling
|
|
|
96cc1f |
+Be wary of what happens during CPU frequency scaling.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_COUNT_HW_INSTRUCTIONS
|
|
|
96cc1f |
Retired instructions.
|
|
|
96cc1f |
Be careful, these can be affected by various
|
|
|
96cc1f |
-issues, most notably hardware interrupt counts
|
|
|
96cc1f |
+issues, most notably hardware interrupt counts.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_COUNT_HW_CACHE_REFERENCES
|
|
|
96cc1f |
Cache accesses.
|
|
|
96cc1f |
@@ -402,8 +450,9 @@ event to calculate cache miss rates.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_COUNT_HW_BRANCH_INSTRUCTIONS
|
|
|
96cc1f |
Retired branch instructions.
|
|
|
96cc1f |
-Prior to Linux 2.6.34, this used
|
|
|
96cc1f |
+Prior to Linux 2.6.35, this used
|
|
|
96cc1f |
the wrong event on AMD processors.
|
|
|
96cc1f |
+.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_COUNT_HW_BRANCH_MISSES
|
|
|
96cc1f |
Mispredicted branch instructions.
|
|
|
96cc1f |
@@ -411,13 +460,16 @@ Mispredicted branch instructions.
|
|
|
96cc1f |
.B PERF_COUNT_HW_BUS_CYCLES
|
|
|
96cc1f |
Bus cycles, which can be different from total cycles.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (Since Linux 3.0)"
|
|
|
96cc1f |
+.BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (since Linux 3.0)"
|
|
|
96cc1f |
+.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
|
|
|
96cc1f |
Stalled cycles during issue.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND " (Since Linux 3.0)"
|
|
|
96cc1f |
+.BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND " (since Linux 3.0)"
|
|
|
96cc1f |
+.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
|
|
|
96cc1f |
Stalled cycles during retirement.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_COUNT_HW_REF_CPU_CYCLES " (Since Linux 3.3)"
|
|
|
96cc1f |
+.BR PERF_COUNT_HW_REF_CPU_CYCLES " (since Linux 3.3)"
|
|
|
96cc1f |
+.\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890
|
|
|
96cc1f |
Total cycles; not affected by CPU frequency scaling.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
.IP
|
|
|
96cc1f |
@@ -444,6 +496,7 @@ This reports the number of page faults.
|
|
|
96cc1f |
This counts context switches.
|
|
|
96cc1f |
Until Linux 2.6.34, these were all reported as user-space
|
|
|
96cc1f |
events, after that they are reported as happening in the kernel.
|
|
|
96cc1f |
+.\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_COUNT_SW_CPU_MIGRATIONS
|
|
|
96cc1f |
This reports the number of times the process
|
|
|
96cc1f |
@@ -457,19 +510,29 @@ These did not require disk I/O to handle.
|
|
|
96cc1f |
This counts the number of major page faults.
|
|
|
96cc1f |
These required disk I/O to handle.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (Since Linux 2.6.33)"
|
|
|
96cc1f |
+.BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (since Linux 2.6.33)"
|
|
|
96cc1f |
+.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
|
|
|
96cc1f |
This counts the number of alignment faults.
|
|
|
96cc1f |
These happen when unaligned memory accesses happen; the kernel
|
|
|
96cc1f |
can handle these but it reduces performance.
|
|
|
96cc1f |
This happens only on some architectures (never on x86).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_COUNT_SW_EMULATION_FAULTS " (Since Linux 2.6.33)"
|
|
|
96cc1f |
+.BR PERF_COUNT_SW_EMULATION_FAULTS " (since Linux 2.6.33)"
|
|
|
96cc1f |
+.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
|
|
|
96cc1f |
This counts the number of emulation faults.
|
|
|
96cc1f |
The kernel sometimes traps on unimplemented instructions
|
|
|
96cc1f |
and emulates them for user space.
|
|
|
96cc1f |
This can negatively impact performance.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_COUNT_SW_DUMMY " (since Linux 3.12)"
|
|
|
96cc1f |
+.\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77
|
|
|
96cc1f |
+This is a placeholder event that counts nothing.
|
|
|
96cc1f |
+Informational sample record types such as mmap or comm
|
|
|
96cc1f |
+must be associated with an active event.
|
|
|
96cc1f |
+This dummy event allows gathering such records without requiring
|
|
|
96cc1f |
+a counting event.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.I type
|
|
|
96cc1f |
@@ -482,7 +545,7 @@ can be obtained from under debugfs
|
|
|
96cc1f |
.I tracing/events/*/*/id
|
|
|
96cc1f |
if ftrace is enabled in the kernel.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.I type
|
|
|
96cc1f |
@@ -492,13 +555,13 @@ then we are measuring a hardware CPU cache event.
|
|
|
96cc1f |
To calculate the appropriate
|
|
|
96cc1f |
.I config
|
|
|
96cc1f |
value use the following equation:
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
.RS 4
|
|
|
96cc1f |
.nf
|
|
|
96cc1f |
-
|
|
|
96cc1f |
(perf_hw_cache_id) | (perf_hw_cache_op_id << 8) |
|
|
|
96cc1f |
(perf_hw_cache_op_result_id << 16)
|
|
|
96cc1f |
.fi
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
where
|
|
|
96cc1f |
.I perf_hw_cache_id
|
|
|
96cc1f |
is one of:
|
|
|
96cc1f |
@@ -522,13 +585,14 @@ for measuring the Instruction TLB
|
|
|
96cc1f |
.B PERF_COUNT_HW_CACHE_BPU
|
|
|
96cc1f |
for measuring the branch prediction unit
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_COUNT_HW_CACHE_NODE " (Since Linux 3.0)"
|
|
|
96cc1f |
+.BR PERF_COUNT_HW_CACHE_NODE " (since Linux 3.1)"
|
|
|
96cc1f |
+.\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477
|
|
|
96cc1f |
for measuring local memory accesses
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.I perf_hw_cache_op_id
|
|
|
96cc1f |
-is one of
|
|
|
96cc1f |
+is one of:
|
|
|
96cc1f |
.RS 4
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_COUNT_HW_CACHE_OP_READ
|
|
|
96cc1f |
@@ -540,10 +604,10 @@ for write accesses
|
|
|
96cc1f |
.B PERF_COUNT_HW_CACHE_OP_PREFETCH
|
|
|
96cc1f |
for prefetch accesses
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
-.P
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.I perf_hw_cache_op_result_id
|
|
|
96cc1f |
-is one of
|
|
|
96cc1f |
+is one of:
|
|
|
96cc1f |
.RS 4
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_COUNT_HW_CACHE_RESULT_ACCESS
|
|
|
96cc1f |
@@ -553,7 +617,7 @@ to measure accesses
|
|
|
96cc1f |
to measure misses
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.I type
|
|
|
96cc1f |
is
|
|
|
96cc1f |
@@ -569,7 +633,7 @@ The libpfm4 library can be used to translate from the name in the
|
|
|
96cc1f |
architectural manuals to the raw hex value
|
|
|
96cc1f |
.BR perf_event_open ()
|
|
|
96cc1f |
expects in this field.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.I type
|
|
|
96cc1f |
is
|
|
|
96cc1f |
@@ -578,23 +642,63 @@ then leave
|
|
|
96cc1f |
.I config
|
|
|
96cc1f |
set to zero.
|
|
|
96cc1f |
Its parameters are set in other places.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+If
|
|
|
96cc1f |
+.I type
|
|
|
96cc1f |
+is
|
|
|
96cc1f |
+.BR kprobe
|
|
|
96cc1f |
+or
|
|
|
96cc1f |
+.BR uprobe ,
|
|
|
96cc1f |
+set
|
|
|
96cc1f |
+.IR retprobe
|
|
|
96cc1f |
+(bit 0 of
|
|
|
96cc1f |
+.IR config ,
|
|
|
96cc1f |
+see
|
|
|
96cc1f |
+.IR /sys/bus/event_source/devices/[k,u]probe/format/retprobe )
|
|
|
96cc1f |
+for kretprobe/uretprobe.
|
|
|
96cc1f |
+See fields
|
|
|
96cc1f |
+.IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset
|
|
|
96cc1f |
+for more details.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
+.IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset
|
|
|
96cc1f |
+These fields describe the kprobe/uprobe for dynamic PMUs
|
|
|
96cc1f |
+.BR kprobe
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.BR uprobe .
|
|
|
96cc1f |
+For
|
|
|
96cc1f |
+.BR kprobe :
|
|
|
96cc1f |
+use
|
|
|
96cc1f |
+.I kprobe_func
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.IR probe_offset ,
|
|
|
96cc1f |
+or use
|
|
|
96cc1f |
+.I kprobe_addr
|
|
|
96cc1f |
+and leave
|
|
|
96cc1f |
+.I kprobe_func
|
|
|
96cc1f |
+as NULL.
|
|
|
96cc1f |
+For
|
|
|
96cc1f |
+.BR uprobe :
|
|
|
96cc1f |
+use
|
|
|
96cc1f |
+.I uprobe_path
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.IR probe_offset .
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.IR sample_period ", " sample_freq
|
|
|
96cc1f |
-A "sampling" counter is one that generates an interrupt
|
|
|
96cc1f |
+A "sampling" event is one that generates an overflow notification
|
|
|
96cc1f |
every N events, where N is given by
|
|
|
96cc1f |
.IR sample_period .
|
|
|
96cc1f |
-A sampling counter has
|
|
|
96cc1f |
+A sampling event has
|
|
|
96cc1f |
.IR sample_period " > 0."
|
|
|
96cc1f |
-When an overflow interrupt occurs, requested data is recorded
|
|
|
96cc1f |
+When an overflow occurs, requested data is recorded
|
|
|
96cc1f |
in the mmap buffer.
|
|
|
96cc1f |
The
|
|
|
96cc1f |
.I sample_type
|
|
|
96cc1f |
-field controls what data is recorded on each interrupt.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+field controls what data is recorded on each overflow.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.I sample_freq
|
|
|
96cc1f |
can be used if you wish to use frequency rather than period.
|
|
|
96cc1f |
-In this case you set the
|
|
|
96cc1f |
+In this case, you set the
|
|
|
96cc1f |
.I freq
|
|
|
96cc1f |
flag.
|
|
|
96cc1f |
The kernel will adjust the sampling period
|
|
|
96cc1f |
@@ -647,39 +751,106 @@ Records a unique ID for the opened event.
|
|
|
96cc1f |
Unlike
|
|
|
96cc1f |
.B PERF_SAMPLE_ID
|
|
|
96cc1f |
the actual ID is returned, not the group leader.
|
|
|
96cc1f |
-This ID is the same as the one returned by PERF_FORMAT_ID.
|
|
|
96cc1f |
+This ID is the same as the one returned by
|
|
|
96cc1f |
+.BR PERF_FORMAT_ID .
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_SAMPLE_RAW
|
|
|
96cc1f |
Records additional data, if applicable.
|
|
|
96cc1f |
Usually returned by tracepoint events.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_SAMPLE_BRANCH_STACK " (Since Linux 3.4)"
|
|
|
96cc1f |
+.BR PERF_SAMPLE_BRANCH_STACK " (since Linux 3.4)"
|
|
|
96cc1f |
+.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
|
|
|
96cc1f |
This provides a record of recent branches, as provided
|
|
|
96cc1f |
by CPU branch sampling hardware (such as Intel Last Branch Record).
|
|
|
96cc1f |
Not all hardware supports this feature.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
See the
|
|
|
96cc1f |
.I branch_sample_type
|
|
|
96cc1f |
field for how to filter which branches are reported.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_SAMPLE_REGS_USER " (Since Linux 3.7)"
|
|
|
96cc1f |
+.BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)"
|
|
|
96cc1f |
+.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
|
|
|
96cc1f |
Records the current user-level CPU register state
|
|
|
96cc1f |
(the values in the process before the kernel was called).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_SAMPLE_STACK_USER " (Since Linux 3.7)"
|
|
|
96cc1f |
+.BR PERF_SAMPLE_STACK_USER " (since Linux 3.7)"
|
|
|
96cc1f |
+.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
|
|
|
96cc1f |
Records the user level stack, allowing stack unwinding.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_SAMPLE_WEIGHT " (Since Linux 3.10)"
|
|
|
96cc1f |
+.BR PERF_SAMPLE_WEIGHT " (since Linux 3.10)"
|
|
|
96cc1f |
+.\" commit c3feedf2aaf9ac8bad6f19f5d21e4ee0b4b87e9c
|
|
|
96cc1f |
Records a hardware provided weight value that expresses how
|
|
|
96cc1f |
costly the sampled event was.
|
|
|
96cc1f |
This allows the hardware to highlight expensive events in
|
|
|
96cc1f |
a profile.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_SAMPLE_DATA_SRC " (Since Linux 3.10)"
|
|
|
96cc1f |
+.BR PERF_SAMPLE_DATA_SRC " (since Linux 3.10)"
|
|
|
96cc1f |
+.\" commit d6be9ad6c960f43800a6f118932bc8a5a4eadcd1
|
|
|
96cc1f |
Records the data source: where in the memory hierarchy
|
|
|
96cc1f |
the data associated with the sampled instruction came from.
|
|
|
96cc1f |
-This is only available if the underlying hardware
|
|
|
96cc1f |
+This is available only if the underlying hardware
|
|
|
96cc1f |
supports this feature.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_SAMPLE_IDENTIFIER " (since Linux 3.12)"
|
|
|
96cc1f |
+.\" commit ff3d527cebc1fa3707c617bfe9e74f53fcfb0955
|
|
|
96cc1f |
+Places the
|
|
|
96cc1f |
+.B SAMPLE_ID
|
|
|
96cc1f |
+value in a fixed position in the record,
|
|
|
96cc1f |
+either at the beginning (for sample events) or at the end
|
|
|
96cc1f |
+(if a non-sample event).
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+This was necessary because a sample stream may have
|
|
|
96cc1f |
+records from various different event sources with different
|
|
|
96cc1f |
+.I sample_type
|
|
|
96cc1f |
+settings.
|
|
|
96cc1f |
+Parsing the event stream properly was not possible because the
|
|
|
96cc1f |
+format of the record was needed to find
|
|
|
96cc1f |
+.BR SAMPLE_ID ,
|
|
|
96cc1f |
+but
|
|
|
96cc1f |
+the format could not be found without knowing what
|
|
|
96cc1f |
+event the sample belonged to (causing a circular
|
|
|
96cc1f |
+dependency).
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.B PERF_SAMPLE_IDENTIFIER
|
|
|
96cc1f |
+setting makes the event stream always parsable
|
|
|
96cc1f |
+by putting
|
|
|
96cc1f |
+.B SAMPLE_ID
|
|
|
96cc1f |
+in a fixed location, even though
|
|
|
96cc1f |
+it means having duplicate
|
|
|
96cc1f |
+.B SAMPLE_ID
|
|
|
96cc1f |
+values in records.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_SAMPLE_TRANSACTION " (since Linux 3.13)"
|
|
|
96cc1f |
+.\" commit fdfbbd07e91f8fe387140776f3fd94605f0c89e5
|
|
|
96cc1f |
+Records reasons for transactional memory abort events
|
|
|
96cc1f |
+(for example, from Intel TSX transactional memory support).
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.I precise_ip
|
|
|
96cc1f |
+setting must be greater than 0 and a transactional memory abort
|
|
|
96cc1f |
+event must be measured or no values will be recorded.
|
|
|
96cc1f |
+Also note that some perf_event measurements, such as sampled
|
|
|
96cc1f |
+cycle counting, may cause extraneous aborts (by causing an
|
|
|
96cc1f |
+interrupt during a transaction).
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_SAMPLE_REGS_INTR " (since Linux 3.19)"
|
|
|
96cc1f |
+.\" commit 60e2364e60e86e81bc6377f49779779e6120977f
|
|
|
96cc1f |
+Records a subset of the current CPU register state
|
|
|
96cc1f |
+as specified by
|
|
|
96cc1f |
+.IR sample_regs_intr .
|
|
|
96cc1f |
+Unlike
|
|
|
96cc1f |
+.B PERF_SAMPLE_REGS_USER
|
|
|
96cc1f |
+the register values will return kernel register
|
|
|
96cc1f |
+state if the overflow happened while kernel
|
|
|
96cc1f |
+code is running.
|
|
|
96cc1f |
+If the CPU supports hardware sampling of
|
|
|
96cc1f |
+register state (i.e., PEBS on Intel x86) and
|
|
|
96cc1f |
+.I precise_ip
|
|
|
96cc1f |
+is set higher than zero then the register
|
|
|
96cc1f |
+values returned are those captured by
|
|
|
96cc1f |
+hardware at the time of the sampled
|
|
|
96cc1f |
+instruction's retirement.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "read_format"
|
|
|
96cc1f |
@@ -702,7 +873,7 @@ Adds the 64-bit
|
|
|
96cc1f |
.I time_running
|
|
|
96cc1f |
field.
|
|
|
96cc1f |
This can be used to calculate estimated totals if
|
|
|
96cc1f |
-the PMU is overcommitted and multiplexing is happening.
|
|
|
96cc1f |
+the PMU is overcommitted and multiplexing is happening.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_FORMAT_ID
|
|
|
96cc1f |
Adds a 64-bit unique value that corresponds to the event group.
|
|
|
96cc1f |
@@ -720,6 +891,17 @@ If disabled, the event can later be enabled by
|
|
|
96cc1f |
.BR prctl (2),
|
|
|
96cc1f |
or
|
|
|
96cc1f |
.IR enable_on_exec .
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+When creating an event group, typically the group leader is initialized
|
|
|
96cc1f |
+with
|
|
|
96cc1f |
+.I disabled
|
|
|
96cc1f |
+set to 1 and any child events are initialized with
|
|
|
96cc1f |
+.I disabled
|
|
|
96cc1f |
+set to 0.
|
|
|
96cc1f |
+Despite
|
|
|
96cc1f |
+.I disabled
|
|
|
96cc1f |
+being 0, the child events will not start until the group leader
|
|
|
96cc1f |
+is enabled.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "inherit"
|
|
|
96cc1f |
The
|
|
|
96cc1f |
@@ -729,10 +911,10 @@ tasks as well as the task specified.
|
|
|
96cc1f |
This applies only to new children, not to any existing children at
|
|
|
96cc1f |
the time the counter is created (nor to any new children of
|
|
|
96cc1f |
existing children).
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
Inherit does not work for some combinations of
|
|
|
96cc1f |
-.IR read_format s,
|
|
|
96cc1f |
-such as
|
|
|
96cc1f |
+.IR read_format
|
|
|
96cc1f |
+values, such as
|
|
|
96cc1f |
.BR PERF_FORMAT_GROUP .
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "pinned"
|
|
|
96cc1f |
@@ -756,12 +938,19 @@ it should be the only group using the CPU's counters.
|
|
|
96cc1f |
In the future this may allow monitoring programs to
|
|
|
96cc1f |
support PMU features that need to run alone so that they do not
|
|
|
96cc1f |
disrupt other hardware counters.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+Note that many unexpected situations may prevent events with the
|
|
|
96cc1f |
+.I exclusive
|
|
|
96cc1f |
+bit set from ever running.
|
|
|
96cc1f |
+This includes any users running a system-wide
|
|
|
96cc1f |
+measurement as well as any kernel use of the performance counters
|
|
|
96cc1f |
+(including the commonly enabled NMI Watchdog Timer interface).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "exclude_user"
|
|
|
96cc1f |
If this bit is set, the count excludes events that happen in user space.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "exclude_kernel"
|
|
|
96cc1f |
-If this bit is set, the count excludes events that happen in kernel-space.
|
|
|
96cc1f |
+If this bit is set, the count excludes events that happen in kernel space.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "exclude_hv"
|
|
|
96cc1f |
If this bit is set, the count excludes events that happen in the
|
|
|
96cc1f |
@@ -772,23 +961,42 @@ Extra support is needed for handling hypervisor measurements on most
|
|
|
96cc1f |
machines.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "exclude_idle"
|
|
|
96cc1f |
-If set, don't count when the CPU is idle.
|
|
|
96cc1f |
+If set, don't count when the CPU is running the idle task.
|
|
|
96cc1f |
+While you can currently enable this for any event type, it is ignored
|
|
|
96cc1f |
+for all but software events.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "mmap"
|
|
|
96cc1f |
The
|
|
|
96cc1f |
.I mmap
|
|
|
96cc1f |
-bit enables recording of exec mmap events.
|
|
|
96cc1f |
+bit enables generation of
|
|
|
96cc1f |
+.B PERF_RECORD_MMAP
|
|
|
96cc1f |
+samples for every
|
|
|
96cc1f |
+.BR mmap (2)
|
|
|
96cc1f |
+call that has
|
|
|
96cc1f |
+.B PROT_EXEC
|
|
|
96cc1f |
+set.
|
|
|
96cc1f |
+This allows tools to notice new executable code being mapped into
|
|
|
96cc1f |
+a program (dynamic shared libraries for example)
|
|
|
96cc1f |
+so that addresses can be mapped back to the original code.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "comm"
|
|
|
96cc1f |
The
|
|
|
96cc1f |
.I comm
|
|
|
96cc1f |
bit enables tracking of process command name as modified by the
|
|
|
96cc1f |
-.IR exec (2)
|
|
|
96cc1f |
+.BR exec (2)
|
|
|
96cc1f |
and
|
|
|
96cc1f |
-.IR prctl (PR_SET_NAME)
|
|
|
96cc1f |
-system calls.
|
|
|
96cc1f |
-Unfortunately for tools,
|
|
|
96cc1f |
-there is no way to distinguish one system call versus the other.
|
|
|
96cc1f |
+.BR prctl (PR_SET_NAME)
|
|
|
96cc1f |
+system calls as well as writing to
|
|
|
96cc1f |
+.IR /proc/self/comm .
|
|
|
96cc1f |
+If the
|
|
|
96cc1f |
+.I comm_exec
|
|
|
96cc1f |
+flag is also successfully set (possible since Linux 3.16),
|
|
|
96cc1f |
+.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
|
|
|
96cc1f |
+then the misc flag
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_COMM_EXEC
|
|
|
96cc1f |
+can be used to differentiate the
|
|
|
96cc1f |
+.BR exec (2)
|
|
|
96cc1f |
+case from the others.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "freq"
|
|
|
96cc1f |
If this bit is set, then
|
|
|
96cc1f |
@@ -814,14 +1022,15 @@ If this bit is set, then
|
|
|
96cc1f |
fork/exit notifications are included in the ring buffer.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR "watermark"
|
|
|
96cc1f |
-If set, have a sampling interrupt happen when we cross the
|
|
|
96cc1f |
+If set, have an overflow notification happen when we cross the
|
|
|
96cc1f |
.I wakeup_watermark
|
|
|
96cc1f |
boundary.
|
|
|
96cc1f |
-Otherwise interrupts happen after
|
|
|
96cc1f |
+Otherwise, overflow notifications happen after
|
|
|
96cc1f |
.I wakeup_events
|
|
|
96cc1f |
samples.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "precise_ip" " (Since Linux 2.6.35)"
|
|
|
96cc1f |
+.IR "precise_ip" " (since Linux 2.6.35)"
|
|
|
96cc1f |
+.\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076
|
|
|
96cc1f |
This controls the amount of skid.
|
|
|
96cc1f |
Skid is how many instructions
|
|
|
96cc1f |
execute between an event of interest happening and the kernel
|
|
|
96cc1f |
@@ -830,95 +1039,200 @@ Smaller skid is
|
|
|
96cc1f |
better and allows more accurate reporting of which events
|
|
|
96cc1f |
correspond to which instructions, but hardware is often limited
|
|
|
96cc1f |
with how small this can be.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-The values of this are the following:
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The possible values of this field are the following:
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
-.TP
|
|
|
96cc1f |
-0 -
|
|
|
96cc1f |
+.IP 0 3
|
|
|
96cc1f |
.B SAMPLE_IP
|
|
|
96cc1f |
-can have arbitrary skid
|
|
|
96cc1f |
-.TP
|
|
|
96cc1f |
-1 -
|
|
|
96cc1f |
+can have arbitrary skid.
|
|
|
96cc1f |
+.IP 1
|
|
|
96cc1f |
.B SAMPLE_IP
|
|
|
96cc1f |
-must have constant skid
|
|
|
96cc1f |
-.TP
|
|
|
96cc1f |
-2 -
|
|
|
96cc1f |
+must have constant skid.
|
|
|
96cc1f |
+.IP 2
|
|
|
96cc1f |
.B SAMPLE_IP
|
|
|
96cc1f |
-requested to have 0 skid
|
|
|
96cc1f |
-.TP
|
|
|
96cc1f |
-3 -
|
|
|
96cc1f |
+requested to have 0 skid.
|
|
|
96cc1f |
+.IP 3
|
|
|
96cc1f |
.B SAMPLE_IP
|
|
|
96cc1f |
must have 0 skid.
|
|
|
96cc1f |
-See also
|
|
|
96cc1f |
+See also the description of
|
|
|
96cc1f |
.BR PERF_RECORD_MISC_EXACT_IP .
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "mmap_data" " (Since Linux 2.6.36)"
|
|
|
96cc1f |
-The counterpart of the
|
|
|
96cc1f |
+.IR "mmap_data" " (since Linux 2.6.36)"
|
|
|
96cc1f |
+.\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e
|
|
|
96cc1f |
+This is the counterpart of the
|
|
|
96cc1f |
.I mmap
|
|
|
96cc1f |
-field, but enables including data mmap events
|
|
|
96cc1f |
-in the ring-buffer.
|
|
|
96cc1f |
+field.
|
|
|
96cc1f |
+This enables generation of
|
|
|
96cc1f |
+.B PERF_RECORD_MMAP
|
|
|
96cc1f |
+samples for
|
|
|
96cc1f |
+.BR mmap (2)
|
|
|
96cc1f |
+calls that do not have
|
|
|
96cc1f |
+.B PROT_EXEC
|
|
|
96cc1f |
+set (for example data and SysV shared memory).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "sample_id_all" " (Since Linux 2.6.38)"
|
|
|
96cc1f |
-If set, then TID, TIME, ID, CPU, and STREAM_ID can
|
|
|
96cc1f |
+.IR "sample_id_all" " (since Linux 2.6.38)"
|
|
|
96cc1f |
+.\" commit c980d1091810df13f21aabbce545fd98f545bbf7
|
|
|
96cc1f |
+If set, then TID, TIME, ID, STREAM_ID, and CPU can
|
|
|
96cc1f |
additionally be included in
|
|
|
96cc1f |
.RB non- PERF_RECORD_SAMPLE s
|
|
|
96cc1f |
if the corresponding
|
|
|
96cc1f |
.I sample_type
|
|
|
96cc1f |
is selected.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+If
|
|
|
96cc1f |
+.B PERF_SAMPLE_IDENTIFIER
|
|
|
96cc1f |
+is specified, then an additional ID value is included
|
|
|
96cc1f |
+as the last value to ease parsing the record stream.
|
|
|
96cc1f |
+This may lead to the
|
|
|
96cc1f |
+.I id
|
|
|
96cc1f |
+value appearing twice.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The layout is described by this pseudo-structure:
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.in +4n
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
+struct sample_id {
|
|
|
96cc1f |
+ { u32 pid, tid; } /* if PERF_SAMPLE_TID set */
|
|
|
96cc1f |
+ { u64 time; } /* if PERF_SAMPLE_TIME set */
|
|
|
96cc1f |
+ { u64 id; } /* if PERF_SAMPLE_ID set */
|
|
|
96cc1f |
+ { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set */
|
|
|
96cc1f |
+ { u32 cpu, res; } /* if PERF_SAMPLE_CPU set */
|
|
|
96cc1f |
+ { u64 id; } /* if PERF_SAMPLE_IDENTIFIER set */
|
|
|
96cc1f |
+};
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
+.in
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "exclude_host" " (Since Linux 3.2)"
|
|
|
96cc1f |
-Do not measure time spent in VM host
|
|
|
96cc1f |
-.TP
|
|
|
96cc1f |
-.IR "exclude_guest" " (Since Linux 3.2)"
|
|
|
96cc1f |
-Do not measure time spent in VM guest
|
|
|
96cc1f |
-.TP
|
|
|
96cc1f |
-.IR "exclude_callchain_kernel" " (Since Linux 3.7)"
|
|
|
96cc1f |
+.IR "exclude_host" " (since Linux 3.2)"
|
|
|
96cc1f |
+.\" commit a240f76165e6255384d4bdb8139895fac7988799
|
|
|
96cc1f |
+When conducting measurements that include processes running
|
|
|
96cc1f |
+VM instances (i.e., have executed a
|
|
|
96cc1f |
+.B KVM_RUN
|
|
|
96cc1f |
+.BR ioctl (2)),
|
|
|
96cc1f |
+only measure events happening inside a guest instance.
|
|
|
96cc1f |
+This is only meaningful outside the guests; this setting does
|
|
|
96cc1f |
+not change counts gathered inside of a guest.
|
|
|
96cc1f |
+Currently, this functionality is x86 only.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR "exclude_guest" " (since Linux 3.2)"
|
|
|
96cc1f |
+.\" commit a240f76165e6255384d4bdb8139895fac7988799
|
|
|
96cc1f |
+When conducting measurements that include processes running
|
|
|
96cc1f |
+VM instances (i.e., have executed a
|
|
|
96cc1f |
+.B KVM_RUN
|
|
|
96cc1f |
+.BR ioctl (2)),
|
|
|
96cc1f |
+do not measure events happening inside guest instances.
|
|
|
96cc1f |
+This is only meaningful outside the guests; this setting does
|
|
|
96cc1f |
+not change counts gathered inside of a guest.
|
|
|
96cc1f |
+Currently, this functionality is x86 only.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR "exclude_callchain_kernel" " (since Linux 3.7)"
|
|
|
96cc1f |
+.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
|
|
|
96cc1f |
Do not include kernel callchains.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "exclude_callchain_user" " (Since Linux 3.7)"
|
|
|
96cc1f |
+.IR "exclude_callchain_user" " (since Linux 3.7)"
|
|
|
96cc1f |
+.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
|
|
|
96cc1f |
Do not include user callchains.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
+.IR "mmap2" " (since Linux 3.16)"
|
|
|
96cc1f |
+.\" commit 13d7a2410fa637f450a29ecb515ac318ee40c741
|
|
|
96cc1f |
+.\" This is tricky; was committed during 3.12 development
|
|
|
96cc1f |
+.\" but right before release was disabled.
|
|
|
96cc1f |
+.\" So while you could select mmap2 starting with 3.12
|
|
|
96cc1f |
+.\" it did not work until 3.16
|
|
|
96cc1f |
+.\" commit a5a5ba72843dd05f991184d6cb9a4471acce1005
|
|
|
96cc1f |
+Generate an extended executable mmap record that contains enough
|
|
|
96cc1f |
+additional information to uniquely identify shared mappings.
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.I mmap
|
|
|
96cc1f |
+flag must also be set for this to work.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR "comm_exec" " (since Linux 3.16)"
|
|
|
96cc1f |
+.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
|
|
|
96cc1f |
+This is purely a feature-detection flag, it does not change
|
|
|
96cc1f |
+kernel behavior.
|
|
|
96cc1f |
+If this flag can successfully be set, then, when
|
|
|
96cc1f |
+.I comm
|
|
|
96cc1f |
+is enabled, the
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_COMM_EXEC
|
|
|
96cc1f |
+flag will be set in the
|
|
|
96cc1f |
+.I misc
|
|
|
96cc1f |
+field of a comm record header if the rename event being
|
|
|
96cc1f |
+reported was caused by a call to
|
|
|
96cc1f |
+.BR exec (2).
|
|
|
96cc1f |
+This allows tools to distinguish between the various
|
|
|
96cc1f |
+types of process renaming.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR "use_clockid" " (since Linux 4.1)"
|
|
|
96cc1f |
+.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
|
|
|
96cc1f |
+This allows selecting which internal Linux clock to use
|
|
|
96cc1f |
+when generating timestamps via the
|
|
|
96cc1f |
+.I clockid
|
|
|
96cc1f |
+field.
|
|
|
96cc1f |
+This can make it easier to correlate perf sample times with
|
|
|
96cc1f |
+timestamps generated by other tools.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR "context_switch" " (since Linux 4.3)"
|
|
|
96cc1f |
+.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
|
|
|
96cc1f |
+This enables the generation of
|
|
|
96cc1f |
+.B PERF_RECORD_SWITCH
|
|
|
96cc1f |
+records when a context switch occurs.
|
|
|
96cc1f |
+It also enables the generation of
|
|
|
96cc1f |
+.B PERF_RECORD_SWITCH_CPU_WIDE
|
|
|
96cc1f |
+records when sampling in CPU-wide mode.
|
|
|
96cc1f |
+This functionality is in addition to existing tracepoint and
|
|
|
96cc1f |
+software events for measuring context switches.
|
|
|
96cc1f |
+The advantage of this method is that it will give full
|
|
|
96cc1f |
+information even with strict
|
|
|
96cc1f |
+.I perf_event_paranoid
|
|
|
96cc1f |
+settings.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.IR "wakeup_events" ", " "wakeup_watermark"
|
|
|
96cc1f |
This union sets how many samples
|
|
|
96cc1f |
.RI ( wakeup_events )
|
|
|
96cc1f |
or bytes
|
|
|
96cc1f |
.RI ( wakeup_watermark )
|
|
|
96cc1f |
-happen before an overflow signal happens.
|
|
|
96cc1f |
+happen before an overflow notification happens.
|
|
|
96cc1f |
Which one is used is selected by the
|
|
|
96cc1f |
.I watermark
|
|
|
96cc1f |
-bitflag.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+bit flag.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.I wakeup_events
|
|
|
96cc1f |
-only counts
|
|
|
96cc1f |
+counts only
|
|
|
96cc1f |
.B PERF_RECORD_SAMPLE
|
|
|
96cc1f |
record types.
|
|
|
96cc1f |
-To receive a signal for every incoming
|
|
|
96cc1f |
+To receive overflow notification for all
|
|
|
96cc1f |
.B PERF_RECORD
|
|
|
96cc1f |
-type set
|
|
|
96cc1f |
+types choose watermark and set
|
|
|
96cc1f |
.I wakeup_watermark
|
|
|
96cc1f |
to 1.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+Prior to Linux 3.0, setting
|
|
|
96cc1f |
+.\" commit f506b3dc0ec454a16d40cab9ee5d75435b39dc50
|
|
|
96cc1f |
+.I wakeup_events
|
|
|
96cc1f |
+to 0 resulted in no overflow notifications;
|
|
|
96cc1f |
+more recent kernels treat 0 the same as 1.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "bp_type" " (Since Linux 2.6.33)"
|
|
|
96cc1f |
+.IR "bp_type" " (since Linux 2.6.33)"
|
|
|
96cc1f |
+.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
|
|
|
96cc1f |
This chooses the breakpoint type.
|
|
|
96cc1f |
It is one of:
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.BR HW_BREAKPOINT_EMPTY
|
|
|
96cc1f |
-no breakpoint
|
|
|
96cc1f |
+No breakpoint.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.BR HW_BREAKPOINT_R
|
|
|
96cc1f |
-count when we read the memory location
|
|
|
96cc1f |
+Count when we read the memory location.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.BR HW_BREAKPOINT_W
|
|
|
96cc1f |
-count when we write the memory location
|
|
|
96cc1f |
+Count when we write the memory location.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.BR HW_BREAKPOINT_RW
|
|
|
96cc1f |
-count when we read or write the memory location
|
|
|
96cc1f |
+Count when we read or write the memory location.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.BR HW_BREAKPOINT_X
|
|
|
96cc1f |
-count when we execute code at the memory location
|
|
|
96cc1f |
-.LP
|
|
|
96cc1f |
+Count when we execute code at the memory location.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The values can be combined via a bitwise or, but the
|
|
|
96cc1f |
combination of
|
|
|
96cc1f |
.B HW_BREAKPOINT_R
|
|
|
96cc1f |
@@ -929,21 +1243,23 @@ with
|
|
|
96cc1f |
is not allowed.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "bp_addr" " (Since Linux 2.6.33)"
|
|
|
96cc1f |
-.I bp_addr
|
|
|
96cc1f |
-address of the breakpoint.
|
|
|
96cc1f |
-For execution breakpoints this is the memory address of the instruction
|
|
|
96cc1f |
-of interest; for read and write breakpoints it is the memory address
|
|
|
96cc1f |
+.IR "bp_addr" " (since Linux 2.6.33)"
|
|
|
96cc1f |
+.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
|
|
|
96cc1f |
+This is the address of the breakpoint.
|
|
|
96cc1f |
+For execution breakpoints, this is the memory address of the instruction
|
|
|
96cc1f |
+of interest; for read and write breakpoints, it is the memory address
|
|
|
96cc1f |
of the memory location of interest.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "config1" " (Since Linux 2.6.39)"
|
|
|
96cc1f |
+.IR "config1" " (since Linux 2.6.39)"
|
|
|
96cc1f |
+.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
|
|
|
96cc1f |
.I config1
|
|
|
96cc1f |
is used for setting events that need an extra register or otherwise
|
|
|
96cc1f |
do not fit in the regular config field.
|
|
|
96cc1f |
Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
|
|
|
96cc1f |
-on 3.3 and later kernels.
|
|
|
96cc1f |
+on Linux 3.3 and later kernels.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "bp_len" " (Since Linux 2.6.33)"
|
|
|
96cc1f |
+.IR "bp_len" " (since Linux 2.6.33)"
|
|
|
96cc1f |
+.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
|
|
|
96cc1f |
.I bp_len
|
|
|
96cc1f |
is the length of the breakpoint being measured if
|
|
|
96cc1f |
.I type
|
|
|
96cc1f |
@@ -953,100 +1269,167 @@ Options are
|
|
|
96cc1f |
.BR HW_BREAKPOINT_LEN_1 ,
|
|
|
96cc1f |
.BR HW_BREAKPOINT_LEN_2 ,
|
|
|
96cc1f |
.BR HW_BREAKPOINT_LEN_4 ,
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
.BR HW_BREAKPOINT_LEN_8 .
|
|
|
96cc1f |
For an execution breakpoint, set this to
|
|
|
96cc1f |
.IR sizeof(long) .
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "config2" " (Since Linux 2.6.39)"
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IR "config2" " (since Linux 2.6.39)"
|
|
|
96cc1f |
+.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
|
|
|
96cc1f |
.I config2
|
|
|
96cc1f |
is a further extension of the
|
|
|
96cc1f |
.I config1
|
|
|
96cc1f |
field.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "branch_sample_type" " (Since Linux 3.4)"
|
|
|
96cc1f |
+.IR "branch_sample_type" " (since Linux 3.4)"
|
|
|
96cc1f |
+.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.B PERF_SAMPLE_BRANCH_STACK
|
|
|
96cc1f |
is enabled, then this specifies what branches to include
|
|
|
96cc1f |
in the branch record.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The first part of the value is the privilege level, which
|
|
|
96cc1f |
+is a combination of one of the values listed below.
|
|
|
96cc1f |
If the user does not set privilege level explicitly, the kernel
|
|
|
96cc1f |
will use the event's privilege level.
|
|
|
96cc1f |
Event and branch privilege levels do not have to match.
|
|
|
96cc1f |
-The value is formed by ORing together zero or more of the following values,
|
|
|
96cc1f |
-although
|
|
|
96cc1f |
-.B PERF_SAMPLE_BRANCH_ANY
|
|
|
96cc1f |
-covers all branch types.
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_SAMPLE_BRANCH_USER
|
|
|
96cc1f |
-Branch target is in user space
|
|
|
96cc1f |
+Branch target is in user space.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_SAMPLE_BRANCH_KERNEL
|
|
|
96cc1f |
-Branch target is in kernel space
|
|
|
96cc1f |
+Branch target is in kernel space.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_SAMPLE_BRANCH_HV
|
|
|
96cc1f |
-Branch target is in hypervisor
|
|
|
96cc1f |
+Branch target is in hypervisor.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_SAMPLE_BRANCH_PLM_ALL
|
|
|
96cc1f |
+A convenience value that is the three preceding values ORed together.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+In addition to the privilege value, at least one or more of the
|
|
|
96cc1f |
+following bits must be set.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_SAMPLE_BRANCH_ANY
|
|
|
96cc1f |
Any branch type.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_SAMPLE_BRANCH_ANY_CALL
|
|
|
96cc1f |
-Any call branch
|
|
|
96cc1f |
+Any call branch (includes direct calls, indirect calls, and far jumps).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_SAMPLE_BRANCH_ANY_RETURN
|
|
|
96cc1f |
-Any return branch
|
|
|
96cc1f |
+.B PERF_SAMPLE_BRANCH_IND_CALL
|
|
|
96cc1f |
+Indirect calls.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_SAMPLE_BRANCH_IND_CALL
|
|
|
96cc1f |
-Indirect calls
|
|
|
96cc1f |
+.BR PERF_SAMPLE_BRANCH_CALL " (since Linux 4.4)"
|
|
|
96cc1f |
+.\" commit c229bf9dc179d2023e185c0f705bdf68484c1e73
|
|
|
96cc1f |
+Direct calls.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_SAMPLE_BRANCH_PLM_ALL
|
|
|
96cc1f |
-User, kernel, and hv
|
|
|
96cc1f |
+.B PERF_SAMPLE_BRANCH_ANY_RETURN
|
|
|
96cc1f |
+Any return branch.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_SAMPLE_BRANCH_IND_JUMP " (since Linux 4.2)"
|
|
|
96cc1f |
+.\" commit c9fdfa14c3792c0160849c484e83aa57afd80ccc
|
|
|
96cc1f |
+Indirect jumps.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_SAMPLE_BRANCH_COND " (since Linux 3.16)"
|
|
|
96cc1f |
+.\" commit bac52139f0b7ab31330e98fd87fc5a2664951050
|
|
|
96cc1f |
+Conditional branches.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_SAMPLE_BRANCH_ABORT_TX " (since Linux 3.11)"
|
|
|
96cc1f |
+.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
|
|
|
96cc1f |
+Transactional memory aborts.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_SAMPLE_BRANCH_IN_TX " (since Linux 3.11)"
|
|
|
96cc1f |
+.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
|
|
|
96cc1f |
+Branch in transactional memory transaction.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_SAMPLE_BRANCH_NO_TX " (since Linux 3.11)"
|
|
|
96cc1f |
+.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
|
|
|
96cc1f |
+Branch not in transactional memory transaction.
|
|
|
96cc1f |
+.BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)"
|
|
|
96cc1f |
+.\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70
|
|
|
96cc1f |
+Branch is part of a hardware-generated call stack.
|
|
|
96cc1f |
+This requires hardware support, currently only found
|
|
|
96cc1f |
+on Intel x86 Haswell or newer.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "sample_regs_user" " (Since Linux 3.7)"
|
|
|
96cc1f |
-This bitmask defines the set of user CPU registers to dump on samples.
|
|
|
96cc1f |
-The layout of the register mask is architecture specific and
|
|
|
96cc1f |
-described in the kernel header
|
|
|
96cc1f |
+.IR "sample_regs_user" " (since Linux 3.7)"
|
|
|
96cc1f |
+.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
|
|
|
96cc1f |
+This bit mask defines the set of user CPU registers to dump on samples.
|
|
|
96cc1f |
+The layout of the register mask is architecture-specific and
|
|
|
96cc1f |
+is described in the kernel header file
|
|
|
96cc1f |
.IR arch/ARCH/include/uapi/asm/perf_regs.h .
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR "sample_stack_user" " (Since Linux 3.7)"
|
|
|
96cc1f |
+.IR "sample_stack_user" " (since Linux 3.7)"
|
|
|
96cc1f |
+.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
|
|
|
96cc1f |
This defines the size of the user stack to dump if
|
|
|
96cc1f |
.B PERF_SAMPLE_STACK_USER
|
|
|
96cc1f |
is specified.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR "clockid" " (since Linux 4.1)"
|
|
|
96cc1f |
+.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
|
|
|
96cc1f |
+If
|
|
|
96cc1f |
+.I use_clockid
|
|
|
96cc1f |
+is set, then this field selects which internal Linux timer to
|
|
|
96cc1f |
+use for timestamps.
|
|
|
96cc1f |
+The available timers are defined in
|
|
|
96cc1f |
+.IR linux/time.h ,
|
|
|
96cc1f |
+with
|
|
|
96cc1f |
+.BR CLOCK_MONOTONIC ,
|
|
|
96cc1f |
+.BR CLOCK_MONOTONIC_RAW ,
|
|
|
96cc1f |
+.BR CLOCK_REALTIME ,
|
|
|
96cc1f |
+.BR CLOCK_BOOTTIME ,
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.B CLOCK_TAI
|
|
|
96cc1f |
+currently supported.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR "aux_watermark" " (since Linux 4.1)"
|
|
|
96cc1f |
+.\" commit 1a5941312414c71dece6717da9a0fa1303127afa
|
|
|
96cc1f |
+This specifies how much data is required to trigger a
|
|
|
96cc1f |
+.B PERF_RECORD_AUX
|
|
|
96cc1f |
+sample.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR "sample_max_stack" " (since Linux 4.8)"
|
|
|
96cc1f |
+.\" commit 97c79a38cd454602645f0470ffb444b3b75ce574
|
|
|
96cc1f |
+When
|
|
|
96cc1f |
+.I sample_type
|
|
|
96cc1f |
+includes
|
|
|
96cc1f |
+.BR PERF_SAMPLE_CALLCHAIN ,
|
|
|
96cc1f |
+this field specifies how many stack frames to report when
|
|
|
96cc1f |
+generating the callchain.
|
|
|
96cc1f |
.SS Reading results
|
|
|
96cc1f |
Once a
|
|
|
96cc1f |
.BR perf_event_open ()
|
|
|
96cc1f |
-file descriptor has been opened, the values
|
|
|
96cc1f |
+file descriptor has been opened, the values
|
|
|
96cc1f |
of the events can be read from the file descriptor.
|
|
|
96cc1f |
The values that are there are specified by the
|
|
|
96cc1f |
.I read_format
|
|
|
96cc1f |
field in the
|
|
|
96cc1f |
.I attr
|
|
|
96cc1f |
structure at open time.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
If you attempt to read into a buffer that is not big enough to hold the
|
|
|
96cc1f |
-data
|
|
|
96cc1f |
+data, the error
|
|
|
96cc1f |
.B ENOSPC
|
|
|
96cc1f |
-is returned
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+results.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
Here is the layout of the data returned by a read:
|
|
|
96cc1f |
.IP * 2
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.B PERF_FORMAT_GROUP
|
|
|
96cc1f |
was specified to allow reading all events in a group at once:
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct read_format {
|
|
|
96cc1f |
u64 nr; /* The number of events */
|
|
|
96cc1f |
u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
|
|
|
96cc1f |
u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
|
|
|
96cc1f |
- struct
|
|
|
96cc1f |
+ struct {
|
|
|
96cc1f |
u64 value; /* The value of the event */
|
|
|
96cc1f |
u64 id; /* if PERF_FORMAT_ID */
|
|
|
96cc1f |
} values[nr];
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
.IP *
|
|
|
96cc1f |
If
|
|
|
96cc1f |
@@ -1054,33 +1437,33 @@ If
|
|
|
96cc1f |
was
|
|
|
96cc1f |
.I not
|
|
|
96cc1f |
specified:
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct read_format {
|
|
|
96cc1f |
u64 value; /* The value of the event */
|
|
|
96cc1f |
u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
|
|
|
96cc1f |
u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
|
|
|
96cc1f |
u64 id; /* if PERF_FORMAT_ID */
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
.PP
|
|
|
96cc1f |
The values read are as follows:
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I nr
|
|
|
96cc1f |
The number of events in this file descriptor.
|
|
|
96cc1f |
-Only available if
|
|
|
96cc1f |
+Available only if
|
|
|
96cc1f |
.B PERF_FORMAT_GROUP
|
|
|
96cc1f |
was specified.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR time_enabled ", " time_running
|
|
|
96cc1f |
Total time the event was enabled and running.
|
|
|
96cc1f |
-Normally these are the same.
|
|
|
96cc1f |
-If more events are started
|
|
|
96cc1f |
-than available counter slots on the PMU, then multiplexing
|
|
|
96cc1f |
+Normally these values are the same.
|
|
|
96cc1f |
+If more events are started,
|
|
|
96cc1f |
+then available counter slots on the PMU, then multiplexing
|
|
|
96cc1f |
happens and events run only part of the time.
|
|
|
96cc1f |
-In that case the
|
|
|
96cc1f |
+In that case, the
|
|
|
96cc1f |
.I time_enabled
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.I time running
|
|
|
96cc1f |
@@ -1090,7 +1473,7 @@ values can be used to scale an estimated value for the count.
|
|
|
96cc1f |
An unsigned 64-bit value containing the counter result.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I id
|
|
|
96cc1f |
-A globally unique value for this particular event, only there if
|
|
|
96cc1f |
+A globally unique value for this particular event; only present if
|
|
|
96cc1f |
.B PERF_FORMAT_ID
|
|
|
96cc1f |
was specified in
|
|
|
96cc1f |
.IR read_format .
|
|
|
96cc1f |
@@ -1104,45 +1487,57 @@ mmap tracking)
|
|
|
96cc1f |
are logged into a ring-buffer.
|
|
|
96cc1f |
This ring-buffer is created and accessed through
|
|
|
96cc1f |
.BR mmap (2).
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The mmap size should be 1+2^n pages, where the first page is a
|
|
|
96cc1f |
metadata page
|
|
|
96cc1f |
.RI ( "struct perf_event_mmap_page" )
|
|
|
96cc1f |
that contains various
|
|
|
96cc1f |
bits of information such as where the ring-buffer head is.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-Before kernel 2.6.39, there is a bug that means you must allocate a mmap
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+Before kernel 2.6.39, there is a bug that means you must allocate an mmap
|
|
|
96cc1f |
ring buffer when sampling even if you do not plan to access it.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The structure of the first metadata mmap page is as follows:
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct perf_event_mmap_page {
|
|
|
96cc1f |
- __u32 version; /* version number of this structure */
|
|
|
96cc1f |
- __u32 compat_version; /* lowest version this is compat with */
|
|
|
96cc1f |
- __u32 lock; /* seqlock for synchronization */
|
|
|
96cc1f |
- __u32 index; /* hardware counter identifier */
|
|
|
96cc1f |
- __s64 offset; /* add to hardware counter value */
|
|
|
96cc1f |
- __u64 time_enabled; /* time event active */
|
|
|
96cc1f |
- __u64 time_running; /* time event on CPU */
|
|
|
96cc1f |
+ __u32 version; /* version number of this structure */
|
|
|
96cc1f |
+ __u32 compat_version; /* lowest version this is compat with */
|
|
|
96cc1f |
+ __u32 lock; /* seqlock for synchronization */
|
|
|
96cc1f |
+ __u32 index; /* hardware counter identifier */
|
|
|
96cc1f |
+ __s64 offset; /* add to hardware counter value */
|
|
|
96cc1f |
+ __u64 time_enabled; /* time event active */
|
|
|
96cc1f |
+ __u64 time_running; /* time event on CPU */
|
|
|
96cc1f |
union {
|
|
|
96cc1f |
__u64 capabilities;
|
|
|
96cc1f |
- __u64 cap_usr_time : 1,
|
|
|
96cc1f |
- cap_usr_rdpmc : 1,
|
|
|
96cc1f |
+ struct {
|
|
|
96cc1f |
+ __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,
|
|
|
96cc1f |
+ cap_bit0_is_deprecated : 1,
|
|
|
96cc1f |
+ cap_user_rdpmc : 1,
|
|
|
96cc1f |
+ cap_user_time : 1,
|
|
|
96cc1f |
+ cap_user_time_zero : 1,
|
|
|
96cc1f |
+ };
|
|
|
96cc1f |
};
|
|
|
96cc1f |
- __u16 pmc_width;
|
|
|
96cc1f |
- __u16 time_shift;
|
|
|
96cc1f |
- __u32 time_mult;
|
|
|
96cc1f |
- __u64 time_offset;
|
|
|
96cc1f |
- __u64 __reserved[120]; /* Pad to 1k */
|
|
|
96cc1f |
- __u64 data_head; /* head in the data section */
|
|
|
96cc1f |
- __u64 data_tail; /* user-space written tail */
|
|
|
96cc1f |
+ __u16 pmc_width;
|
|
|
96cc1f |
+ __u16 time_shift;
|
|
|
96cc1f |
+ __u32 time_mult;
|
|
|
96cc1f |
+ __u64 time_offset;
|
|
|
96cc1f |
+ __u64 __reserved[120]; /* Pad to 1 k */
|
|
|
96cc1f |
+ __u64 data_head; /* head in the data section */
|
|
|
96cc1f |
+ __u64 data_tail; /* user-space written tail */
|
|
|
96cc1f |
+ __u64 data_offset; /* where the buffer starts */
|
|
|
96cc1f |
+ __u64 data_size; /* data buffer size */
|
|
|
96cc1f |
+ __u64 aux_head;
|
|
|
96cc1f |
+ __u64 aux_tail;
|
|
|
96cc1f |
+ __u64 aux_offset;
|
|
|
96cc1f |
+ __u64 aux_size;
|
|
|
96cc1f |
+
|
|
|
96cc1f |
}
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-The following looks at the fields in the
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+The following list describes the fields in the
|
|
|
96cc1f |
.I perf_event_mmap_page
|
|
|
96cc1f |
structure in more detail:
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
@@ -1159,8 +1554,9 @@ A seqlock for synchronization.
|
|
|
96cc1f |
A unique hardware counter identifier.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I offset
|
|
|
96cc1f |
-.\" FIXME clarify
|
|
|
96cc1f |
-Add this to hardware counter value??
|
|
|
96cc1f |
+When using rdpmc for reads this offset value
|
|
|
96cc1f |
+must be added to the one returned by rdpmc to get
|
|
|
96cc1f |
+the current total event count.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I time_enabled
|
|
|
96cc1f |
Time the event was active.
|
|
|
96cc1f |
@@ -1168,20 +1564,56 @@ Time the event was active.
|
|
|
96cc1f |
.I time_running
|
|
|
96cc1f |
Time the event was running.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
+.IR cap_usr_time " / " cap_usr_rdpmc " / " cap_bit0 " (since Linux 3.4)"
|
|
|
96cc1f |
+.\" commit c7206205d00ab375839bd6c7ddb247d600693c09
|
|
|
96cc1f |
+There was a bug in the definition of
|
|
|
96cc1f |
.I cap_usr_time
|
|
|
96cc1f |
-User time capability
|
|
|
96cc1f |
-.TP
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.I cap_usr_rdpmc
|
|
|
96cc1f |
+from Linux 3.4 until Linux 3.11.
|
|
|
96cc1f |
+Both bits were defined to point to the same location, so it was
|
|
|
96cc1f |
+impossible to know if
|
|
|
96cc1f |
+.I cap_usr_time
|
|
|
96cc1f |
+or
|
|
|
96cc1f |
+.I cap_usr_rdpmc
|
|
|
96cc1f |
+were actually set.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+Starting with Linux 3.12, these are renamed to
|
|
|
96cc1f |
+.\" commit fa7315871046b9a4c48627905691dbde57e51033
|
|
|
96cc1f |
+.I cap_bit0
|
|
|
96cc1f |
+and you should use the
|
|
|
96cc1f |
+.I cap_user_time
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.I cap_user_rdpmc
|
|
|
96cc1f |
+fields instead.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR cap_bit0_is_deprecated " (since Linux 3.12)"
|
|
|
96cc1f |
+.\" commit fa7315871046b9a4c48627905691dbde57e51033
|
|
|
96cc1f |
+If set, this bit indicates that the kernel supports
|
|
|
96cc1f |
+the properly separated
|
|
|
96cc1f |
+.I cap_user_time
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.I cap_user_rdpmc
|
|
|
96cc1f |
+bits.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+If not-set, it indicates an older kernel where
|
|
|
96cc1f |
+.I cap_usr_time
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
.I cap_usr_rdpmc
|
|
|
96cc1f |
+map to the same bit and thus both features should
|
|
|
96cc1f |
+be used with caution.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR cap_user_rdpmc " (since Linux 3.12)"
|
|
|
96cc1f |
+.\" commit fa7315871046b9a4c48627905691dbde57e51033
|
|
|
96cc1f |
If the hardware supports user-space read of performance counters
|
|
|
96cc1f |
without syscall (this is the "rdpmc" instruction on x86), then
|
|
|
96cc1f |
the following code can be used to do a read:
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
u32 seq, time_mult, time_shift, idx, width;
|
|
|
96cc1f |
u64 count, enabled, running;
|
|
|
96cc1f |
u64 cyc, time_offset;
|
|
|
96cc1f |
-s64 pmc = 0;
|
|
|
96cc1f |
|
|
|
96cc1f |
do {
|
|
|
96cc1f |
seq = pc\->lock;
|
|
|
96cc1f |
@@ -1201,45 +1633,59 @@ do {
|
|
|
96cc1f |
|
|
|
96cc1f |
if (pc\->cap_usr_rdpmc && idx) {
|
|
|
96cc1f |
width = pc\->pmc_width;
|
|
|
96cc1f |
- pmc = rdpmc(idx \- 1);
|
|
|
96cc1f |
+ count += rdpmc(idx \- 1);
|
|
|
96cc1f |
}
|
|
|
96cc1f |
|
|
|
96cc1f |
barrier();
|
|
|
96cc1f |
} while (pc\->lock != seq);
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
+.IR cap_user_time " (since Linux 3.12)"
|
|
|
96cc1f |
+.\" commit fa7315871046b9a4c48627905691dbde57e51033
|
|
|
96cc1f |
+This bit indicates the hardware has a constant, nonstop
|
|
|
96cc1f |
+timestamp counter (TSC on x86).
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR cap_user_time_zero " (since Linux 3.12)"
|
|
|
96cc1f |
+.\" commit fa7315871046b9a4c48627905691dbde57e51033
|
|
|
96cc1f |
+Indicates the presence of
|
|
|
96cc1f |
+.I time_zero
|
|
|
96cc1f |
+which allows mapping timestamp values to
|
|
|
96cc1f |
+the hardware clock.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.I pmc_width
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.IR cap_usr_rdpmc ,
|
|
|
96cc1f |
this field provides the bit-width of the value
|
|
|
96cc1f |
read using the rdpmc or equivalent instruction.
|
|
|
96cc1f |
This can be used to sign extend the result like:
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
pmc <<= 64 \- pmc_width;
|
|
|
96cc1f |
pmc >>= 64 \- pmc_width; // signed shift right
|
|
|
96cc1f |
count += pmc;
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR time_shift ", " time_mult ", " time_offset
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.IR cap_usr_time ,
|
|
|
96cc1f |
these fields can be used to compute the time
|
|
|
96cc1f |
-delta since time_enabled (in nanoseconds) using rdtsc or similar.
|
|
|
96cc1f |
+delta since
|
|
|
96cc1f |
+.I time_enabled
|
|
|
96cc1f |
+(in nanoseconds) using rdtsc or similar.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.nf
|
|
|
96cc1f |
-
|
|
|
96cc1f |
u64 quot, rem;
|
|
|
96cc1f |
u64 delta;
|
|
|
96cc1f |
quot = (cyc >> time_shift);
|
|
|
96cc1f |
- rem = cyc & ((1 << time_shift) \- 1);
|
|
|
96cc1f |
+ rem = cyc & (((u64)1 << time_shift) \- 1);
|
|
|
96cc1f |
delta = time_offset + quot * time_mult +
|
|
|
96cc1f |
((rem * time_mult) >> time_shift);
|
|
|
96cc1f |
.fi
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
Where
|
|
|
96cc1f |
.IR time_offset ,
|
|
|
96cc1f |
.IR time_mult ,
|
|
|
96cc1f |
@@ -1250,8 +1696,8 @@ are read in the
|
|
|
96cc1f |
seqcount loop described above.
|
|
|
96cc1f |
This delta can then be added to
|
|
|
96cc1f |
enabled and possible running (if idx), improving the scaling:
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.nf
|
|
|
96cc1f |
-
|
|
|
96cc1f |
enabled += delta;
|
|
|
96cc1f |
if (idx)
|
|
|
96cc1f |
running += delta;
|
|
|
96cc1f |
@@ -1260,25 +1706,102 @@ enabled and possible running (if idx), improving the scaling:
|
|
|
96cc1f |
count = quot * enabled + (rem * enabled) / running;
|
|
|
96cc1f |
.fi
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
+.IR time_zero " (since Linux 3.12)"
|
|
|
96cc1f |
+.\" commit fa7315871046b9a4c48627905691dbde57e51033
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+If
|
|
|
96cc1f |
+.I cap_usr_time_zero
|
|
|
96cc1f |
+is set, then the hardware clock (the TSC timestamp counter on x86)
|
|
|
96cc1f |
+can be calculated from the
|
|
|
96cc1f |
+.IR time_zero ", " time_mult ", and " time_shift " values:"
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.nf
|
|
|
96cc1f |
+ time = timestamp - time_zero;
|
|
|
96cc1f |
+ quot = time / time_mult;
|
|
|
96cc1f |
+ rem = time % time_mult;
|
|
|
96cc1f |
+ cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
|
|
|
96cc1f |
+.fi
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+And vice versa:
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.nf
|
|
|
96cc1f |
+ quot = cyc >> time_shift;
|
|
|
96cc1f |
+ rem = cyc & (((u64)1 << time_shift) - 1);
|
|
|
96cc1f |
+ timestamp = time_zero + quot * time_mult +
|
|
|
96cc1f |
+ ((rem * time_mult) >> time_shift);
|
|
|
96cc1f |
+.fi
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.I data_head
|
|
|
96cc1f |
This points to the head of the data section.
|
|
|
96cc1f |
The value continuously increases, it does not wrap.
|
|
|
96cc1f |
The value needs to be manually wrapped by the size of the mmap buffer
|
|
|
96cc1f |
before accessing the samples.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-On SMP-capable platforms, after reading the data_head value,
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+On SMP-capable platforms, after reading the
|
|
|
96cc1f |
+.I data_head
|
|
|
96cc1f |
+value,
|
|
|
96cc1f |
user space should issue an rmb().
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.I data_tail;
|
|
|
96cc1f |
+.I data_tail
|
|
|
96cc1f |
When the mapping is
|
|
|
96cc1f |
.BR PROT_WRITE ,
|
|
|
96cc1f |
the
|
|
|
96cc1f |
.I data_tail
|
|
|
96cc1f |
value should be written by user space to reflect the last read data.
|
|
|
96cc1f |
-In this case the kernel will not over-write unread data.
|
|
|
96cc1f |
+In this case, the kernel will not overwrite unread data.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR data_offset " (since Linux 4.1)"
|
|
|
96cc1f |
+.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
|
|
|
96cc1f |
+Contains the offset of the location in the mmap buffer
|
|
|
96cc1f |
+where perf sample data begins.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR data_size " (since Linux 4.1)"
|
|
|
96cc1f |
+.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
|
|
|
96cc1f |
+Contains the size of the perf sample region within
|
|
|
96cc1f |
+the mmap buffer.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR aux_head ", " aux_tail ", " aux_offset ", " aux_size " (since Linux 4.1)
|
|
|
96cc1f |
+.\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff
|
|
|
96cc1f |
+The AUX region allows mmaping a separate sample buffer for
|
|
|
96cc1f |
+high-bandwidth data streams (separate from the main perf sample buffer).
|
|
|
96cc1f |
+An example of a high-bandwidth stream is instruction tracing support,
|
|
|
96cc1f |
+as is found in newer Intel processors.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+To set up an AUX area, first
|
|
|
96cc1f |
+.I aux_offset
|
|
|
96cc1f |
+needs to be set with an offset greater than
|
|
|
96cc1f |
+.IR data_offset + data_size
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.I aux_size
|
|
|
96cc1f |
+needs to be set to the desired buffer size.
|
|
|
96cc1f |
+The desired offset and size must be page aligned, and the size
|
|
|
96cc1f |
+must be a power of two.
|
|
|
96cc1f |
+These values are then passed to mmap in order to map the AUX buffer.
|
|
|
96cc1f |
+Pages in the AUX buffer are included as part of the
|
|
|
96cc1f |
+.BR RLIMIT_MEMLOCK
|
|
|
96cc1f |
+resource limit (see
|
|
|
96cc1f |
+.BR setrlimit (2)),
|
|
|
96cc1f |
+and also as part of the
|
|
|
96cc1f |
+.I perf_event_mlock_kb
|
|
|
96cc1f |
+allowance.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+By default, the AUX buffer will be truncated if it will not fit
|
|
|
96cc1f |
+in the available space in the ring buffer.
|
|
|
96cc1f |
+If the AUX buffer is mapped as a read only buffer, then it will
|
|
|
96cc1f |
+operate in ring buffer mode where old data will be overwritten
|
|
|
96cc1f |
+by new.
|
|
|
96cc1f |
+In overwrite mode, it might not be possible to infer where the
|
|
|
96cc1f |
+new data began, and it is the consumer's job to disable
|
|
|
96cc1f |
+measurement while reading to avoid possible data races.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.IR aux_head " and " aux_tail
|
|
|
96cc1f |
+ring buffer pointers have the same behavior and ordering
|
|
|
96cc1f |
+rules as the previous described
|
|
|
96cc1f |
+.IR data_head " and " data_tail .
|
|
|
96cc1f |
.PP
|
|
|
96cc1f |
The following 2^n ring-buffer pages have the layout described below.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.I perf_event_attr.sample_id_all
|
|
|
96cc1f |
is set, then all event types will
|
|
|
96cc1f |
@@ -1288,46 +1811,136 @@ an event took place (TID, TIME, ID, CPU, STREAM_ID) described in
|
|
|
96cc1f |
below, it will be stashed just after the
|
|
|
96cc1f |
.I perf_event_header
|
|
|
96cc1f |
and the fields already present for the existing
|
|
|
96cc1f |
-fields, i.e., at the end of the payload.
|
|
|
96cc1f |
-That way a newer perf.data
|
|
|
96cc1f |
-file will be supported by older perf tools, with these new optional
|
|
|
96cc1f |
+fields, that is, at the end of the payload.
|
|
|
96cc1f |
+This allows a newer perf.data
|
|
|
96cc1f |
+file to be supported by older perf tools, with the new optional
|
|
|
96cc1f |
fields being ignored.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The mmap values start with a header:
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct perf_event_header {
|
|
|
96cc1f |
__u32 type;
|
|
|
96cc1f |
__u16 misc;
|
|
|
96cc1f |
__u16 size;
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
Below, we describe the
|
|
|
96cc1f |
.I perf_event_header
|
|
|
96cc1f |
fields in more detail.
|
|
|
96cc1f |
+For ease of reading,
|
|
|
96cc1f |
+the fields with shorter descriptions are presented first.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.I type
|
|
|
96cc1f |
+.I size
|
|
|
96cc1f |
+This indicates the size of the record.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I misc
|
|
|
96cc1f |
The
|
|
|
96cc1f |
-.I type
|
|
|
96cc1f |
-value is one of the below.
|
|
|
96cc1f |
-The values in the corresponding record (that follows the header)
|
|
|
96cc1f |
-depend on the
|
|
|
96cc1f |
-.I type
|
|
|
96cc1f |
-selected as shown.
|
|
|
96cc1f |
-.RS
|
|
|
96cc1f |
-.TP 4
|
|
|
96cc1f |
+.I misc
|
|
|
96cc1f |
+field contains additional information about the sample.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The CPU mode can be determined from this value by masking with
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_CPUMODE_MASK
|
|
|
96cc1f |
+and looking for one of the following (note these are not
|
|
|
96cc1f |
+bit masks, only one can be set at a time):
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_CPUMODE_UNKNOWN
|
|
|
96cc1f |
+Unknown CPU mode.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_KERNEL
|
|
|
96cc1f |
+Sample happened in the kernel.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_USER
|
|
|
96cc1f |
+Sample happened in user code.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_HYPERVISOR
|
|
|
96cc1f |
+Sample happened in the hypervisor.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_RECORD_MISC_GUEST_KERNEL " (since Linux 2.6.35)"
|
|
|
96cc1f |
+.\" commit 39447b386c846bbf1c56f6403c5282837486200f
|
|
|
96cc1f |
+Sample happened in the guest kernel.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_GUEST_USER " (since Linux 2.6.35)"
|
|
|
96cc1f |
+.\" commit 39447b386c846bbf1c56f6403c5282837486200f
|
|
|
96cc1f |
+Sample happened in guest user code.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+Since the following three statuses are generated by
|
|
|
96cc1f |
+different record types, they alias to the same bit:
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_RECORD_MISC_MMAP_DATA " (since Linux 3.10)"
|
|
|
96cc1f |
+.\" commit 2fe85427e3bf65d791700d065132772fc26e4d75
|
|
|
96cc1f |
+This is set when the mapping is not executable;
|
|
|
96cc1f |
+otherwise the mapping is executable.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_RECORD_MISC_COMM_EXEC " (since Linux 3.16)"
|
|
|
96cc1f |
+.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
|
|
|
96cc1f |
+This is set for a
|
|
|
96cc1f |
+.B PERF_RECORD_COMM
|
|
|
96cc1f |
+record on kernels more recent than Linux 3.16
|
|
|
96cc1f |
+if a process name change was caused by an
|
|
|
96cc1f |
+.BR exec (2)
|
|
|
96cc1f |
+system call.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_RECORD_MISC_SWITCH_OUT " (since Linux 4.3)"
|
|
|
96cc1f |
+.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
|
|
|
96cc1f |
+When a
|
|
|
96cc1f |
+.BR PERF_RECORD_SWITCH
|
|
|
96cc1f |
+or
|
|
|
96cc1f |
+.BR PERF_RECORD_SWITCH_CPU_WIDE
|
|
|
96cc1f |
+record is generated, this bit indicates that the
|
|
|
96cc1f |
+context switch is away from the current process
|
|
|
96cc1f |
+(instead of into the current process).
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+In addition, the following bits can be set:
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_EXACT_IP
|
|
|
96cc1f |
+This indicates that the content of
|
|
|
96cc1f |
+.B PERF_SAMPLE_IP
|
|
|
96cc1f |
+points
|
|
|
96cc1f |
+to the actual instruction that triggered the event.
|
|
|
96cc1f |
+See also
|
|
|
96cc1f |
+.IR perf_event_attr.precise_ip .
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_RECORD_MISC_EXT_RESERVED " (since Linux 2.6.35)"
|
|
|
96cc1f |
+.\" commit 1676b8a077c352085d52578fb4f29350b58b6e74
|
|
|
96cc1f |
+This indicates there is extended data available (currently not used).
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT
|
|
|
96cc1f |
+.\" commit 930e6fcd2bcce9bcd9d4aa7e755678d33f3fe6f4
|
|
|
96cc1f |
+This bit is not set by the kernel.
|
|
|
96cc1f |
+It is reserved for the user-space perf utility to indicate that
|
|
|
96cc1f |
+.I /proc/i[pid]/maps
|
|
|
96cc1f |
+parsing was taking too long and was stopped, and thus the mmap
|
|
|
96cc1f |
+records may be truncated.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I type
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.I type
|
|
|
96cc1f |
+value is one of the below.
|
|
|
96cc1f |
+The values in the corresponding record (that follows the header)
|
|
|
96cc1f |
+depend on the
|
|
|
96cc1f |
+.I type
|
|
|
96cc1f |
+selected as shown.
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP 4
|
|
|
96cc1f |
.B PERF_RECORD_MMAP
|
|
|
96cc1f |
The MMAP events record the
|
|
|
96cc1f |
.B PROT_EXEC
|
|
|
96cc1f |
mappings so that we can correlate
|
|
|
96cc1f |
user-space IPs to code.
|
|
|
96cc1f |
They have the following structure:
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct {
|
|
|
96cc1f |
struct perf_event_header header;
|
|
|
96cc1f |
u32 pid, tid;
|
|
|
96cc1f |
@@ -1336,20 +1949,38 @@ struct {
|
|
|
96cc1f |
u64 pgoff;
|
|
|
96cc1f |
char filename[];
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I pid
|
|
|
96cc1f |
+is the process ID.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I tid
|
|
|
96cc1f |
+is the thread ID.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I addr
|
|
|
96cc1f |
+is the address of the allocated memory.
|
|
|
96cc1f |
+.I len
|
|
|
96cc1f |
+is the length of the allocated memory.
|
|
|
96cc1f |
+.I pgoff
|
|
|
96cc1f |
+is the page offset of the allocated memory.
|
|
|
96cc1f |
+.I filename
|
|
|
96cc1f |
+is a string describing the backing of the allocated memory.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_RECORD_LOST
|
|
|
96cc1f |
This record indicates when events are lost.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct {
|
|
|
96cc1f |
struct perf_event_header header;
|
|
|
96cc1f |
- u64 id;
|
|
|
96cc1f |
- u64 lost;
|
|
|
96cc1f |
+ u64 id;
|
|
|
96cc1f |
+ u64 lost;
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
@@ -1362,106 +1993,140 @@ is the number of events that were lost.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_RECORD_COMM
|
|
|
96cc1f |
This record indicates a change in the process name.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct {
|
|
|
96cc1f |
struct perf_event_header header;
|
|
|
96cc1f |
- u32 pid, tid;
|
|
|
96cc1f |
- char comm[];
|
|
|
96cc1f |
+ u32 pid;
|
|
|
96cc1f |
+ u32 tid;
|
|
|
96cc1f |
+ char comm[];
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I pid
|
|
|
96cc1f |
+is the process ID.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I tid
|
|
|
96cc1f |
+is the thread ID.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I comm
|
|
|
96cc1f |
+is a string containing the new name of the process.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_RECORD_EXIT
|
|
|
96cc1f |
This record indicates a process exit event.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct {
|
|
|
96cc1f |
struct perf_event_header header;
|
|
|
96cc1f |
- u32 pid, ppid;
|
|
|
96cc1f |
- u32 tid, ptid;
|
|
|
96cc1f |
- u64 time;
|
|
|
96cc1f |
+ u32 pid, ppid;
|
|
|
96cc1f |
+ u32 tid, ptid;
|
|
|
96cc1f |
+ u64 time;
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.BR PERF_RECORD_THROTTLE ", " PERF_RECORD_UNTHROTTLE
|
|
|
96cc1f |
This record indicates a throttle/unthrottle event.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct {
|
|
|
96cc1f |
struct perf_event_header header;
|
|
|
96cc1f |
- u64 time;
|
|
|
96cc1f |
- u64 id;
|
|
|
96cc1f |
- u64 stream_id;
|
|
|
96cc1f |
+ u64 time;
|
|
|
96cc1f |
+ u64 id;
|
|
|
96cc1f |
+ u64 stream_id;
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_RECORD_FORK
|
|
|
96cc1f |
This record indicates a fork event.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct {
|
|
|
96cc1f |
struct perf_event_header header;
|
|
|
96cc1f |
- u32 pid, ppid;
|
|
|
96cc1f |
- u32 tid, ptid;
|
|
|
96cc1f |
- u64 time;
|
|
|
96cc1f |
+ u32 pid, ppid;
|
|
|
96cc1f |
+ u32 tid, ptid;
|
|
|
96cc1f |
+ u64 time;
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_RECORD_READ
|
|
|
96cc1f |
This record indicates a read event.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct {
|
|
|
96cc1f |
struct perf_event_header header;
|
|
|
96cc1f |
- u32 pid, tid;
|
|
|
96cc1f |
+ u32 pid, tid;
|
|
|
96cc1f |
struct read_format values;
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.in
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_RECORD_SAMPLE
|
|
|
96cc1f |
This record indicates a sample.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
.in +4n
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
struct {
|
|
|
96cc1f |
struct perf_event_header header;
|
|
|
96cc1f |
- u64 ip; /* if PERF_SAMPLE_IP */
|
|
|
96cc1f |
- u32 pid, tid; /* if PERF_SAMPLE_TID */
|
|
|
96cc1f |
- u64 time; /* if PERF_SAMPLE_TIME */
|
|
|
96cc1f |
- u64 addr; /* if PERF_SAMPLE_ADDR */
|
|
|
96cc1f |
- u64 id; /* if PERF_SAMPLE_ID */
|
|
|
96cc1f |
- u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */
|
|
|
96cc1f |
- u32 cpu, res; /* if PERF_SAMPLE_CPU */
|
|
|
96cc1f |
- u64 period; /* if PERF_SAMPLE_PERIOD */
|
|
|
96cc1f |
- struct read_format v; /* if PERF_SAMPLE_READ */
|
|
|
96cc1f |
- u64 nr; /* if PERF_SAMPLE_CALLCHAIN */
|
|
|
96cc1f |
- u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */
|
|
|
96cc1f |
- u32 size; /* if PERF_SAMPLE_RAW */
|
|
|
96cc1f |
- char data[size]; /* if PERF_SAMPLE_RAW */
|
|
|
96cc1f |
- u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */
|
|
|
96cc1f |
+ u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */
|
|
|
96cc1f |
+ u64 ip; /* if PERF_SAMPLE_IP */
|
|
|
96cc1f |
+ u32 pid, tid; /* if PERF_SAMPLE_TID */
|
|
|
96cc1f |
+ u64 time; /* if PERF_SAMPLE_TIME */
|
|
|
96cc1f |
+ u64 addr; /* if PERF_SAMPLE_ADDR */
|
|
|
96cc1f |
+ u64 id; /* if PERF_SAMPLE_ID */
|
|
|
96cc1f |
+ u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */
|
|
|
96cc1f |
+ u32 cpu, res; /* if PERF_SAMPLE_CPU */
|
|
|
96cc1f |
+ u64 period; /* if PERF_SAMPLE_PERIOD */
|
|
|
96cc1f |
+ struct read_format v;
|
|
|
96cc1f |
+ /* if PERF_SAMPLE_READ */
|
|
|
96cc1f |
+ u64 nr; /* if PERF_SAMPLE_CALLCHAIN */
|
|
|
96cc1f |
+ u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */
|
|
|
96cc1f |
+ u32 size; /* if PERF_SAMPLE_RAW */
|
|
|
96cc1f |
+ char data[size]; /* if PERF_SAMPLE_RAW */
|
|
|
96cc1f |
+ u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */
|
|
|
96cc1f |
struct perf_branch_entry lbr[bnr];
|
|
|
96cc1f |
- /* if PERF_SAMPLE_BRANCH_STACK */
|
|
|
96cc1f |
- u64 abi; /* if PERF_SAMPLE_REGS_USER */
|
|
|
96cc1f |
- u64 regs[weight(mask)];
|
|
|
96cc1f |
- /* if PERF_SAMPLE_REGS_USER */
|
|
|
96cc1f |
- u64 size; /* if PERF_SAMPLE_STACK_USER */
|
|
|
96cc1f |
- char data[size]; /* if PERF_SAMPLE_STACK_USER */
|
|
|
96cc1f |
- u64 dyn_size; /* if PERF_SAMPLE_STACK_USER */
|
|
|
96cc1f |
- u64 weight; /* if PERF_SAMPLE_WEIGHT */
|
|
|
96cc1f |
- u64 data_src; /* if PERF_SAMPLE_DATA_SRC */
|
|
|
96cc1f |
+ /* if PERF_SAMPLE_BRANCH_STACK */
|
|
|
96cc1f |
+ u64 abi; /* if PERF_SAMPLE_REGS_USER */
|
|
|
96cc1f |
+ u64 regs[weight(mask)];
|
|
|
96cc1f |
+ /* if PERF_SAMPLE_REGS_USER */
|
|
|
96cc1f |
+ u64 size; /* if PERF_SAMPLE_STACK_USER */
|
|
|
96cc1f |
+ char data[size]; /* if PERF_SAMPLE_STACK_USER */
|
|
|
96cc1f |
+ u64 dyn_size; /* if PERF_SAMPLE_STACK_USER &&
|
|
|
96cc1f |
+ size != 0 */
|
|
|
96cc1f |
+ u64 weight; /* if PERF_SAMPLE_WEIGHT */
|
|
|
96cc1f |
+ u64 data_src; /* if PERF_SAMPLE_DATA_SRC */
|
|
|
96cc1f |
+ u64 transaction; /* if PERF_SAMPLE_TRANSACTION */
|
|
|
96cc1f |
+ u64 abi; /* if PERF_SAMPLE_REGS_INTR */
|
|
|
96cc1f |
+ u64 regs[weight(mask)];
|
|
|
96cc1f |
+ /* if PERF_SAMPLE_REGS_INTR */
|
|
|
96cc1f |
};
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
-.RS
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
+.RS 4
|
|
|
96cc1f |
+.TP 4
|
|
|
96cc1f |
+.I sample_id
|
|
|
96cc1f |
+If
|
|
|
96cc1f |
+.B PERF_SAMPLE_IDENTIFIER
|
|
|
96cc1f |
+is enabled, a 64-bit unique ID is included.
|
|
|
96cc1f |
+This is a duplication of the
|
|
|
96cc1f |
+.B PERF_SAMPLE_ID
|
|
|
96cc1f |
+.I id
|
|
|
96cc1f |
+value, but included at the beginning of the sample
|
|
|
96cc1f |
+so parsers can easily obtain the value.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I ip
|
|
|
96cc1f |
If
|
|
|
96cc1f |
@@ -1546,7 +2211,7 @@ If
|
|
|
96cc1f |
is enabled, then a 32-bit value indicating size
|
|
|
96cc1f |
is included followed by an array of 8-bit values of length size.
|
|
|
96cc1f |
The values are padded with 0 to have 64-bit alignment.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
This RAW record data is opaque with respect to the ABI.
|
|
|
96cc1f |
The ABI doesn't make any promises with respect to the stability
|
|
|
96cc1f |
of its content, it may vary depending
|
|
|
96cc1f |
@@ -1563,39 +2228,57 @@ structures which each include the fields:
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I from
|
|
|
96cc1f |
-indicating the source instruction (may not be a branch)
|
|
|
96cc1f |
+This indicates the source instruction (may not be a branch).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I to
|
|
|
96cc1f |
-the branch target
|
|
|
96cc1f |
+The branch target.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I mispred
|
|
|
96cc1f |
-the branch target was mispredicted
|
|
|
96cc1f |
+The branch target was mispredicted.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I predicted
|
|
|
96cc1f |
-the branch target was predicted.
|
|
|
96cc1f |
-.RE
|
|
|
96cc1f |
+The branch target was predicted.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR in_tx " (since Linux 3.11)"
|
|
|
96cc1f |
+.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
|
|
|
96cc1f |
+The branch was in a transactional memory transaction.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR abort " (since Linux 3.11)"
|
|
|
96cc1f |
+.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
|
|
|
96cc1f |
+The branch was in an aborted transactional memory transaction.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR cycles " (since Linux 4.3)"
|
|
|
96cc1f |
+.\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f
|
|
|
96cc1f |
+This reports the number of cycles elapsed since the
|
|
|
96cc1f |
+previous branch stack update.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The entries are from most to least recent, so the first entry
|
|
|
96cc1f |
has the most recent branch.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
Support for
|
|
|
96cc1f |
-.I mispred
|
|
|
96cc1f |
+.IR mispred ,
|
|
|
96cc1f |
+.IR predicted ,
|
|
|
96cc1f |
and
|
|
|
96cc1f |
-.I predicted
|
|
|
96cc1f |
-is optional; if not supported, both
|
|
|
96cc1f |
+.IR cycles
|
|
|
96cc1f |
+is optional; if not supported, those
|
|
|
96cc1f |
values will be 0.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+The type of branches recorded is specified by the
|
|
|
96cc1f |
+.I branch_sample_type
|
|
|
96cc1f |
+field.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR abi ", " regs[weight(mask)]
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.B PERF_SAMPLE_REGS_USER
|
|
|
96cc1f |
is enabled, then the user CPU registers are recorded.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The
|
|
|
96cc1f |
.I abi
|
|
|
96cc1f |
field is one of
|
|
|
96cc1f |
.BR PERF_SAMPLE_REGS_ABI_NONE ", " PERF_SAMPLE_REGS_ABI_32 " or "
|
|
|
96cc1f |
.BR PERF_SAMPLE_REGS_ABI_64 .
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The
|
|
|
96cc1f |
.I regs
|
|
|
96cc1f |
field is an array of the CPU registers that were specified by
|
|
|
96cc1f |
@@ -1604,26 +2287,33 @@ the
|
|
|
96cc1f |
attr field.
|
|
|
96cc1f |
The number of values is the number of bits set in the
|
|
|
96cc1f |
.I sample_regs_user
|
|
|
96cc1f |
-bitmask.
|
|
|
96cc1f |
+bit mask.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.IR size ", " data[size] ", " dyn_size
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.B PERF_SAMPLE_STACK_USER
|
|
|
96cc1f |
-is enabled, then record the user stack to enable backtracing.
|
|
|
96cc1f |
+is enabled, then the user stack is recorded.
|
|
|
96cc1f |
+This can be used to generate stack backtraces.
|
|
|
96cc1f |
.I size
|
|
|
96cc1f |
is the size requested by the user in
|
|
|
96cc1f |
-.I stack_user_size
|
|
|
96cc1f |
+.I sample_stack_user
|
|
|
96cc1f |
or else the maximum record size.
|
|
|
96cc1f |
.I data
|
|
|
96cc1f |
-is the stack data.
|
|
|
96cc1f |
+is the stack data (a raw dump of the memory pointed to by the
|
|
|
96cc1f |
+stack pointer at the time of sampling).
|
|
|
96cc1f |
.I dyn_size
|
|
|
96cc1f |
is the amount of data actually dumped (can be less than
|
|
|
96cc1f |
.IR size ).
|
|
|
96cc1f |
+Note that
|
|
|
96cc1f |
+.I dyn_size
|
|
|
96cc1f |
+is omitted if
|
|
|
96cc1f |
+.I size
|
|
|
96cc1f |
+is 0.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I weight
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.B PERF_SAMPLE_WEIGHT
|
|
|
96cc1f |
-is enabled, then a 64 bit value provided by the hardware
|
|
|
96cc1f |
+is enabled, then a 64-bit value provided by the hardware
|
|
|
96cc1f |
is recorded that indicates how costly the event was.
|
|
|
96cc1f |
This allows expensive events to stand out more clearly
|
|
|
96cc1f |
in profiles.
|
|
|
96cc1f |
@@ -1631,211 +2321,508 @@ in profiles.
|
|
|
96cc1f |
.I data_src
|
|
|
96cc1f |
If
|
|
|
96cc1f |
.B PERF_SAMPLE_DATA_SRC
|
|
|
96cc1f |
-is enabled, then a 64 bit value is recorded that is made up of
|
|
|
96cc1f |
+is enabled, then a 64-bit value is recorded that is made up of
|
|
|
96cc1f |
the following fields:
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
-.TP
|
|
|
96cc1f |
+.TP 4
|
|
|
96cc1f |
.I mem_op
|
|
|
96cc1f |
-type of opcode, a bitwise combination of
|
|
|
96cc1f |
+Type of opcode, a bitwise combination of:
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.PD 0
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP 24
|
|
|
96cc1f |
.B PERF_MEM_OP_NA
|
|
|
96cc1f |
-(not available),
|
|
|
96cc1f |
+Not available
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_OP_LOAD
|
|
|
96cc1f |
-(load instruction),
|
|
|
96cc1f |
+Load instruction
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_OP_STORE
|
|
|
96cc1f |
-(store instruction),
|
|
|
96cc1f |
+Store instruction
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_OP_PFETCH
|
|
|
96cc1f |
-(prefetch), and
|
|
|
96cc1f |
+Prefetch
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_OP_EXEC
|
|
|
96cc1f |
-(executable code).
|
|
|
96cc1f |
+Executable code
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.PD
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I mem_lvl
|
|
|
96cc1f |
-memory hierarchy level hit or miss, a bitwise combination of
|
|
|
96cc1f |
+Memory hierarchy level hit or miss, a bitwise combination of
|
|
|
96cc1f |
+the following, shifted left by
|
|
|
96cc1f |
+.BR PERF_MEM_LVL_SHIFT :
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.PD 0
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP 24
|
|
|
96cc1f |
.B PERF_MEM_LVL_NA
|
|
|
96cc1f |
-(not available),
|
|
|
96cc1f |
+Not available
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_HIT
|
|
|
96cc1f |
-(hit),
|
|
|
96cc1f |
+Hit
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_MISS
|
|
|
96cc1f |
-(miss),
|
|
|
96cc1f |
+Miss
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_L1
|
|
|
96cc1f |
-(level 1 cache),
|
|
|
96cc1f |
+Level 1 cache
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_LFB
|
|
|
96cc1f |
-(line fill buffer),
|
|
|
96cc1f |
+Line fill buffer
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_L2
|
|
|
96cc1f |
-(level 2 cache),
|
|
|
96cc1f |
+Level 2 cache
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_L3
|
|
|
96cc1f |
-(level 3 cache),
|
|
|
96cc1f |
+Level 3 cache
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_LOC_RAM
|
|
|
96cc1f |
-(local DRAM),
|
|
|
96cc1f |
+Local DRAM
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_REM_RAM1
|
|
|
96cc1f |
-(remote DRAM 1 hop),
|
|
|
96cc1f |
+Remote DRAM 1 hop
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_REM_RAM2
|
|
|
96cc1f |
-(remote DRAM 2 hops),
|
|
|
96cc1f |
+Remote DRAM 2 hops
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_REM_CCE1
|
|
|
96cc1f |
-(remote cache 1 hop),
|
|
|
96cc1f |
+Remote cache 1 hop
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_REM_CCE2
|
|
|
96cc1f |
-(remote cache 2 hops),
|
|
|
96cc1f |
+Remote cache 2 hops
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_IO
|
|
|
96cc1f |
-(I/O memory), and
|
|
|
96cc1f |
+I/O memory
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LVL_UNC
|
|
|
96cc1f |
-(uncached memory).
|
|
|
96cc1f |
+Uncached memory
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.PD
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I mem_snoop
|
|
|
96cc1f |
-snoop mode, a bitwise combination of
|
|
|
96cc1f |
+Snoop mode, a bitwise combination of the following, shifted left by
|
|
|
96cc1f |
+.BR PERF_MEM_SNOOP_SHIFT :
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.PD 0
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP 24
|
|
|
96cc1f |
.B PERF_MEM_SNOOP_NA
|
|
|
96cc1f |
-(not available),
|
|
|
96cc1f |
+Not available
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_SNOOP_NONE
|
|
|
96cc1f |
-(no snoop),
|
|
|
96cc1f |
+No snoop
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_SNOOP_HIT
|
|
|
96cc1f |
-(snoop hit),
|
|
|
96cc1f |
+Snoop hit
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_SNOOP_MISS
|
|
|
96cc1f |
-(snoop miss), and
|
|
|
96cc1f |
+Snoop miss
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_SNOOP_HITM
|
|
|
96cc1f |
-(snoop hit modified).
|
|
|
96cc1f |
+Snoop hit modified
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.PD
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I mem_lock
|
|
|
96cc1f |
-lock instruction, a bitwise combination of
|
|
|
96cc1f |
+Lock instruction, a bitwise combination of the following, shifted left by
|
|
|
96cc1f |
+.BR PERF_MEM_LOCK_SHIFT :
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.PD 0
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP 24
|
|
|
96cc1f |
.B PERF_MEM_LOCK_NA
|
|
|
96cc1f |
-(not available) and
|
|
|
96cc1f |
+Not available
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_LOCK_LOCKED
|
|
|
96cc1f |
-(locked transaction).
|
|
|
96cc1f |
+Locked transaction
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.PD
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I mem_dtlb
|
|
|
96cc1f |
-tlb access hit or miss, a bitwise combination of
|
|
|
96cc1f |
+TLB access hit or miss, a bitwise combination of the following, shifted
|
|
|
96cc1f |
+left by
|
|
|
96cc1f |
+.BR PERF_MEM_TLB_SHIFT :
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.PD 0
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP 24
|
|
|
96cc1f |
.B PERF_MEM_TLB_NA
|
|
|
96cc1f |
-(not available),
|
|
|
96cc1f |
+Not available
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_TLB_HIT
|
|
|
96cc1f |
-(hit),
|
|
|
96cc1f |
+Hit
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_TLB_MISS
|
|
|
96cc1f |
-(miss),
|
|
|
96cc1f |
+Miss
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_TLB_L1
|
|
|
96cc1f |
-(level 1 TLB),
|
|
|
96cc1f |
+Level 1 TLB
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_TLB_L2
|
|
|
96cc1f |
-(level 2 TLB),
|
|
|
96cc1f |
+Level 2 TLB
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_TLB_WK
|
|
|
96cc1f |
-(hardware walker), and
|
|
|
96cc1f |
+Hardware walker
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.B PERF_MEM_TLB_OS
|
|
|
96cc1f |
-(OS fault handler).
|
|
|
96cc1f |
+OS fault handler
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
+.PD
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I transaction
|
|
|
96cc1f |
+If the
|
|
|
96cc1f |
+.B PERF_SAMPLE_TRANSACTION
|
|
|
96cc1f |
+flag is set, then a 64-bit field is recorded describing
|
|
|
96cc1f |
+the sources of any transactional memory aborts.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The field is a bitwise combination of the following values:
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_TXN_ELISION
|
|
|
96cc1f |
+Abort from an elision type transaction (Intel-CPU-specific).
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_TXN_TRANSACTION
|
|
|
96cc1f |
+Abort from a generic transaction.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_TXN_SYNC
|
|
|
96cc1f |
+Synchronous abort (related to the reported instruction).
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_TXN_ASYNC
|
|
|
96cc1f |
+Asynchronous abort (not related to the reported instruction).
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_TXN_RETRY
|
|
|
96cc1f |
+Retryable abort (retrying the transaction may have succeeded).
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_TXN_CONFLICT
|
|
|
96cc1f |
+Abort due to memory conflicts with other threads.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_TXN_CAPACITY_WRITE
|
|
|
96cc1f |
+Abort due to write capacity overflow.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_TXN_CAPACITY_READ
|
|
|
96cc1f |
+Abort due to read capacity overflow.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+In addition, a user-specified abort code can be obtained from
|
|
|
96cc1f |
+the high 32 bits of the field by shifting right by
|
|
|
96cc1f |
+.B PERF_TXN_ABORT_SHIFT
|
|
|
96cc1f |
+and masking with the value
|
|
|
96cc1f |
+.BR PERF_TXN_ABORT_MASK .
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.I misc
|
|
|
96cc1f |
+.IR abi ", " regs[weight(mask)]
|
|
|
96cc1f |
+If
|
|
|
96cc1f |
+.B PERF_SAMPLE_REGS_INTR
|
|
|
96cc1f |
+is enabled, then the user CPU registers are recorded.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The
|
|
|
96cc1f |
-.I misc
|
|
|
96cc1f |
-field contains additional information about the sample.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-The CPU mode can be determined from this value by masking with
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_CPUMODE_MASK
|
|
|
96cc1f |
-and looking for one of the following (note these are not
|
|
|
96cc1f |
-bit masks, only one can be set at a time):
|
|
|
96cc1f |
+.I abi
|
|
|
96cc1f |
+field is one of
|
|
|
96cc1f |
+.BR PERF_SAMPLE_REGS_ABI_NONE ,
|
|
|
96cc1f |
+.BR PERF_SAMPLE_REGS_ABI_32 ,
|
|
|
96cc1f |
+or
|
|
|
96cc1f |
+.BR PERF_SAMPLE_REGS_ABI_64 .
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.I regs
|
|
|
96cc1f |
+field is an array of the CPU registers that were specified by
|
|
|
96cc1f |
+the
|
|
|
96cc1f |
+.I sample_regs_intr
|
|
|
96cc1f |
+attr field.
|
|
|
96cc1f |
+The number of values is the number of bits set in the
|
|
|
96cc1f |
+.I sample_regs_intr
|
|
|
96cc1f |
+bit mask.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_RECORD_MMAP2
|
|
|
96cc1f |
+This record includes extended information on
|
|
|
96cc1f |
+.BR mmap (2)
|
|
|
96cc1f |
+calls returning executable mappings.
|
|
|
96cc1f |
+The format is similar to that of the
|
|
|
96cc1f |
+.B PERF_RECORD_MMAP
|
|
|
96cc1f |
+record, but includes extra values that allow uniquely identifying
|
|
|
96cc1f |
+shared mappings.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.in +4n
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
+struct {
|
|
|
96cc1f |
+ struct perf_event_header header;
|
|
|
96cc1f |
+ u32 pid;
|
|
|
96cc1f |
+ u32 tid;
|
|
|
96cc1f |
+ u64 addr;
|
|
|
96cc1f |
+ u64 len;
|
|
|
96cc1f |
+ u64 pgoff;
|
|
|
96cc1f |
+ u32 maj;
|
|
|
96cc1f |
+ u32 min;
|
|
|
96cc1f |
+ u64 ino;
|
|
|
96cc1f |
+ u64 ino_generation;
|
|
|
96cc1f |
+ u32 prot;
|
|
|
96cc1f |
+ u32 flags;
|
|
|
96cc1f |
+ char filename[];
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
+};
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_CPUMODE_UNKNOWN
|
|
|
96cc1f |
-Unknown CPU mode.
|
|
|
96cc1f |
+.I pid
|
|
|
96cc1f |
+is the process ID.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_KERNEL
|
|
|
96cc1f |
-Sample happened in the kernel.
|
|
|
96cc1f |
+.I tid
|
|
|
96cc1f |
+is the thread ID.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_USER
|
|
|
96cc1f |
-Sample happened in user code.
|
|
|
96cc1f |
+.I addr
|
|
|
96cc1f |
+is the address of the allocated memory.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_HYPERVISOR
|
|
|
96cc1f |
-Sample happened in the hypervisor.
|
|
|
96cc1f |
+.I len
|
|
|
96cc1f |
+is the length of the allocated memory.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_GUEST_KERNEL
|
|
|
96cc1f |
-Sample happened in the guest kernel.
|
|
|
96cc1f |
+.I pgoff
|
|
|
96cc1f |
+is the page offset of the allocated memory.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_GUEST_USER
|
|
|
96cc1f |
-Sample happened in guest user code.
|
|
|
96cc1f |
+.I maj
|
|
|
96cc1f |
+is the major ID of the underlying device.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I min
|
|
|
96cc1f |
+is the minor ID of the underlying device.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I ino
|
|
|
96cc1f |
+is the inode number.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I ino_generation
|
|
|
96cc1f |
+is the inode generation.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I prot
|
|
|
96cc1f |
+is the protection information.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I flags
|
|
|
96cc1f |
+is the flags information.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I filename
|
|
|
96cc1f |
+is a string describing the backing of the allocated memory.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_RECORD_AUX " (since Linux 4.1)"
|
|
|
96cc1f |
+\" commit 68db7e98c3a6ebe7284b6cf14906ed7c55f3f7f0
|
|
|
96cc1f |
+This record reports that new data is available in the separate
|
|
|
96cc1f |
+AUX buffer region.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.in +4n
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
+struct {
|
|
|
96cc1f |
+ struct perf_event_header header;
|
|
|
96cc1f |
+ u64 aux_offset;
|
|
|
96cc1f |
+ u64 aux_size;
|
|
|
96cc1f |
+ u64 flags;
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
+};
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.RS
|
|
|
96cc1f |
-In addition, one of the following bits can be set:
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_MMAP_DATA
|
|
|
96cc1f |
-This is set when the mapping is not executable;
|
|
|
96cc1f |
-otherwise the mapping is executable.
|
|
|
96cc1f |
+.I aux_offset
|
|
|
96cc1f |
+offset in the AUX mmap region where the new data begins.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_EXACT_IP
|
|
|
96cc1f |
-This indicates that the content of
|
|
|
96cc1f |
-.B PERF_SAMPLE_IP
|
|
|
96cc1f |
-points
|
|
|
96cc1f |
-to the actual instruction that triggered the event.
|
|
|
96cc1f |
-See also
|
|
|
96cc1f |
-.IR perf_event_attr.precise_ip .
|
|
|
96cc1f |
+.I aux_size
|
|
|
96cc1f |
+size of the data made available.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.B PERF_RECORD_MISC_EXT_RESERVED
|
|
|
96cc1f |
-This indicates there is extended data available (currently not used).
|
|
|
96cc1f |
+.I flags
|
|
|
96cc1f |
+describes the AUX update.
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_AUX_FLAG_TRUNCATED
|
|
|
96cc1f |
+if set, then the data returned was truncated to fit the available
|
|
|
96cc1f |
+buffer size.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B PERF_AUX_FLAG_OVERWRITE
|
|
|
96cc1f |
+.\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142
|
|
|
96cc1f |
+if set, then the data returned has overwritten previous data.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.I size
|
|
|
96cc1f |
-This indicates the size of the record.
|
|
|
96cc1f |
+.BR PERF_RECORD_ITRACE_START " (since Linux 4.1)"
|
|
|
96cc1f |
+\" ec0d7729bbaed4b9d2d3fada693278e13a3d1368
|
|
|
96cc1f |
+This record indicates which process has initiated an instruction
|
|
|
96cc1f |
+trace event, allowing tools to properly correlate the instruction
|
|
|
96cc1f |
+addresses in the AUX buffer with the proper executable.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.in +4n
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
+struct {
|
|
|
96cc1f |
+ struct perf_event_header header;
|
|
|
96cc1f |
+ u32 pid;
|
|
|
96cc1f |
+ u32 tid;
|
|
|
96cc1f |
+};
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I pid
|
|
|
96cc1f |
+process ID of the thread starting an instruction trace.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I tid
|
|
|
96cc1f |
+thread ID of the thread starting an instruction trace.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_RECORD_LOST_SAMPLES " (since Linux 4.2)"
|
|
|
96cc1f |
+\" f38b0dbb491a6987e198aa6b428db8692a6480f8
|
|
|
96cc1f |
+When using hardware sampling (such as Intel PEBS) this record
|
|
|
96cc1f |
+indicates some number of samples that may have been lost.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.in +4n
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
+struct {
|
|
|
96cc1f |
+ struct perf_event_header header;
|
|
|
96cc1f |
+ u64 lost;
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
+};
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I lost
|
|
|
96cc1f |
+the number of potentially lost samples.
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
-.SS Signal overflow
|
|
|
96cc1f |
-Events can be set to deliver a signal when a threshold is crossed.
|
|
|
96cc1f |
-The signal handler is set up using the
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_RECORD_SWITCH " (since Linux 4.3)"
|
|
|
96cc1f |
+\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
|
|
|
96cc1f |
+This record indicates a context switch has happened.
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_SWITCH_OUT
|
|
|
96cc1f |
+bit in the
|
|
|
96cc1f |
+.I misc
|
|
|
96cc1f |
+field indicates whether it was a context switch into
|
|
|
96cc1f |
+or away from the current process.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.in +4n
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
+struct {
|
|
|
96cc1f |
+ struct perf_event_header header;
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
+};
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_RECORD_SWITCH_CPU_WIDE " (since Linux 4.3)"
|
|
|
96cc1f |
+\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
|
|
|
96cc1f |
+As with
|
|
|
96cc1f |
+.B PERF_RECORD_SWITCH
|
|
|
96cc1f |
+this record indicates a context switch has happened,
|
|
|
96cc1f |
+but it only occurs when sampling in CPU-wide mode
|
|
|
96cc1f |
+and provides additional information on the process
|
|
|
96cc1f |
+being switched to/from.
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.B PERF_RECORD_MISC_SWITCH_OUT
|
|
|
96cc1f |
+bit in the
|
|
|
96cc1f |
+.I misc
|
|
|
96cc1f |
+field indicates whether it was a context switch into
|
|
|
96cc1f |
+or away from the current process.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.in +4n
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
+struct {
|
|
|
96cc1f |
+ struct perf_event_header header;
|
|
|
96cc1f |
+ u32 next_prev_pid;
|
|
|
96cc1f |
+ u32 next_prev_tid;
|
|
|
96cc1f |
+ struct sample_id sample_id;
|
|
|
96cc1f |
+};
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I next_prev_pid
|
|
|
96cc1f |
+The process ID of the previous (if switching in)
|
|
|
96cc1f |
+or next (if switching out) process on the CPU.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.I next_prev_tid
|
|
|
96cc1f |
+The thread ID of the previous (if switching in)
|
|
|
96cc1f |
+or next (if switching out) thread on the CPU.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.SS Overflow handling
|
|
|
96cc1f |
+Events can be set to notify when a threshold is crossed,
|
|
|
96cc1f |
+indicating an overflow.
|
|
|
96cc1f |
+Overflow conditions can be captured by monitoring the
|
|
|
96cc1f |
+event file descriptor with
|
|
|
96cc1f |
.BR poll (2),
|
|
|
96cc1f |
.BR select (2),
|
|
|
96cc1f |
-.BR epoll (2)
|
|
|
96cc1f |
+or
|
|
|
96cc1f |
+.BR epoll (7).
|
|
|
96cc1f |
+Alternatively, the overflow events can be captured via sa signal handler,
|
|
|
96cc1f |
+by enabling I/O signaling on the file descriptor; see the discussion of the
|
|
|
96cc1f |
+.BR F_SETOWN
|
|
|
96cc1f |
and
|
|
|
96cc1f |
-.BR fcntl (2),
|
|
|
96cc1f |
-system calls.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-To generate signals, sampling must be enabled
|
|
|
96cc1f |
+.BR F_SETSIG
|
|
|
96cc1f |
+operations in
|
|
|
96cc1f |
+.BR fcntl (2).
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+Overflows are generated only by sampling events
|
|
|
96cc1f |
.RI ( sample_period
|
|
|
96cc1f |
-must have a non-zero value).
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-There are two ways to generate signals.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+must have a nonzero value).
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+There are two ways to generate overflow notifications.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The first is to set a
|
|
|
96cc1f |
.I wakeup_events
|
|
|
96cc1f |
or
|
|
|
96cc1f |
.I wakeup_watermark
|
|
|
96cc1f |
-value that will generate a signal if a certain number of samples
|
|
|
96cc1f |
+value that will trigger if a certain number of samples
|
|
|
96cc1f |
or bytes have been written to the mmap ring buffer.
|
|
|
96cc1f |
-In this case a signal of type
|
|
|
96cc1f |
+In this case,
|
|
|
96cc1f |
.B POLL_IN
|
|
|
96cc1f |
-is sent.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+is indicated.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The other way is by use of the
|
|
|
96cc1f |
.B PERF_EVENT_IOC_REFRESH
|
|
|
96cc1f |
ioctl.
|
|
|
96cc1f |
This ioctl adds to a counter that decrements each time the event overflows.
|
|
|
96cc1f |
-When non-zero, a
|
|
|
96cc1f |
+When nonzero,
|
|
|
96cc1f |
.B POLL_IN
|
|
|
96cc1f |
-signal is sent on overflow, but
|
|
|
96cc1f |
-once the value reaches 0, a signal is sent of type
|
|
|
96cc1f |
+is indicated, but
|
|
|
96cc1f |
+once the counter reaches 0
|
|
|
96cc1f |
.B POLL_HUP
|
|
|
96cc1f |
-and
|
|
|
96cc1f |
+is indicated and
|
|
|
96cc1f |
the underlying event is disabled.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-Note: on newer kernels (definitely noticed with 3.2)
|
|
|
96cc1f |
-.\" FIXME(Vince) : Find out when this was introduced
|
|
|
96cc1f |
-a signal is provided for every overflow, even if
|
|
|
96cc1f |
-.I wakeup_events
|
|
|
96cc1f |
-is not set.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+Refreshing an event group leader refreshes all siblings and
|
|
|
96cc1f |
+refreshing with a parameter of 0 currently enables infinite
|
|
|
96cc1f |
+refreshes;
|
|
|
96cc1f |
+these behaviors are unsupported and should not be relied on.
|
|
|
96cc1f |
+.\" See https://lkml.org/lkml/2011/5/24/337
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+Starting with Linux 3.18,
|
|
|
96cc1f |
+.\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883
|
|
|
96cc1f |
+.B POLL_HUP
|
|
|
96cc1f |
+is indicated if the event being monitored is attached to a different
|
|
|
96cc1f |
+process and that process exits.
|
|
|
96cc1f |
.SS rdpmc instruction
|
|
|
96cc1f |
Starting with Linux 3.4 on x86, you can use the
|
|
|
96cc1f |
+.\" commit c7206205d00ab375839bd6c7ddb247d600693c09
|
|
|
96cc1f |
.I rdpmc
|
|
|
96cc1f |
instruction to get low-latency reads without having to enter the kernel.
|
|
|
96cc1f |
Note that using
|
|
|
96cc1f |
.I rdpmc
|
|
|
96cc1f |
is not necessarily faster than other methods for reading event values.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
Support for this can be detected with the
|
|
|
96cc1f |
.I cap_usr_rdpmc
|
|
|
96cc1f |
field in the mmap page; documentation on how
|
|
|
96cc1f |
to calculate event values can be found in that section.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+Originally, when rdpmc support was enabled, any process (not just ones
|
|
|
96cc1f |
+with an active perf event) could use the rdpmc instruction to access
|
|
|
96cc1f |
+the counters.
|
|
|
96cc1f |
+Starting with Linux 4.0,
|
|
|
96cc1f |
+.\" 7911d3f7af14a614617e38245fedf98a724e46a9
|
|
|
96cc1f |
+rdpmc support is only allowed if an event is currently enabled
|
|
|
96cc1f |
+in a process's context.
|
|
|
96cc1f |
+To restore the old behavior, write the value 2 to
|
|
|
96cc1f |
+.IR /sys/devices/cpu/rdpmc .
|
|
|
96cc1f |
.SS perf_event ioctl calls
|
|
|
96cc1f |
.PP
|
|
|
96cc1f |
Various ioctls act on
|
|
|
96cc1f |
.BR perf_event_open ()
|
|
|
96cc1f |
-file descriptors
|
|
|
96cc1f |
+file descriptors:
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_EVENT_IOC_ENABLE
|
|
|
96cc1f |
-Enables the individual event or event group specified by the
|
|
|
96cc1f |
+This enables the individual event or event group specified by the
|
|
|
96cc1f |
file descriptor argument.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
If the
|
|
|
96cc1f |
.B PERF_IOC_FLAG_GROUP
|
|
|
96cc1f |
bit is set in the ioctl argument, then all events in a group are
|
|
|
96cc1f |
@@ -1843,16 +2830,16 @@ enabled, even if the event specified is not the group leader
|
|
|
96cc1f |
(but see BUGS).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_EVENT_IOC_DISABLE
|
|
|
96cc1f |
-Disables the individual counter or event group specified by the
|
|
|
96cc1f |
+This disables the individual counter or event group specified by the
|
|
|
96cc1f |
file descriptor argument.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
Enabling or disabling the leader of a group enables or disables the
|
|
|
96cc1f |
entire group; that is, while the group leader is disabled, none of the
|
|
|
96cc1f |
counters in the group will count.
|
|
|
96cc1f |
Enabling or disabling a member of a group other than the leader
|
|
|
96cc1f |
affects only that counter; disabling a non-leader
|
|
|
96cc1f |
stops that counter from counting but doesn't affect any other counter.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
If the
|
|
|
96cc1f |
.B PERF_IOC_FLAG_GROUP
|
|
|
96cc1f |
bit is set in the ioctl argument, then all events in a group are
|
|
|
96cc1f |
@@ -1865,11 +2852,11 @@ to enable a counter for a number of overflows specified by the argument,
|
|
|
96cc1f |
after which it is disabled.
|
|
|
96cc1f |
Subsequent calls of this ioctl add the argument value to the current
|
|
|
96cc1f |
count.
|
|
|
96cc1f |
-A signal with
|
|
|
96cc1f |
+An overflow notification with
|
|
|
96cc1f |
.B POLL_IN
|
|
|
96cc1f |
set will happen on each overflow until the
|
|
|
96cc1f |
-count reaches 0; when that happens a signal with
|
|
|
96cc1f |
-POLL_HUP
|
|
|
96cc1f |
+count reaches 0; when that happens a notification with
|
|
|
96cc1f |
+.B POLL_HUP
|
|
|
96cc1f |
set is sent and the event is disabled.
|
|
|
96cc1f |
Using an argument of 0 is considered undefined behavior.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
@@ -1882,7 +2869,7 @@ multiplexing
|
|
|
96cc1f |
or
|
|
|
96cc1f |
.I time_running
|
|
|
96cc1f |
values.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
If the
|
|
|
96cc1f |
.B PERF_IOC_FLAG_GROUP
|
|
|
96cc1f |
bit is set in the ioctl argument, then all events in a group are
|
|
|
96cc1f |
@@ -1890,63 +2877,168 @@ reset, even if the event specified is not the group leader
|
|
|
96cc1f |
(but see BUGS).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_EVENT_IOC_PERIOD
|
|
|
96cc1f |
-IOC_PERIOD is the command to update the period; it
|
|
|
96cc1f |
-does not update the current period but instead defers until next.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+This updates the overflow period for the event.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+Since Linux 3.7 (on ARM)
|
|
|
96cc1f |
+.\" commit 3581fe0ef37ce12ac7a4f74831168352ae848edc
|
|
|
96cc1f |
+and Linux 3.14 (all other architectures),
|
|
|
96cc1f |
+.\" commit bad7192b842c83e580747ca57104dd51fe08c223
|
|
|
96cc1f |
+the new period takes effect immediately.
|
|
|
96cc1f |
+On older kernels, the new period did not take effect until
|
|
|
96cc1f |
+after the next overflow.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The argument is a pointer to a 64-bit value containing the
|
|
|
96cc1f |
desired new period.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+Prior to Linux 2.6.36,
|
|
|
96cc1f |
+.\" commit ad0cf3478de8677f720ee06393b3147819568d6a
|
|
|
96cc1f |
+this ioctl always failed due to a bug
|
|
|
96cc1f |
+in the kernel.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B PERF_EVENT_IOC_SET_OUTPUT
|
|
|
96cc1f |
This tells the kernel to report event notifications to the specified
|
|
|
96cc1f |
file descriptor rather than the default one.
|
|
|
96cc1f |
The file descriptors must all be on the same CPU.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The argument specifies the desired file descriptor, or \-1 if
|
|
|
96cc1f |
output should be ignored.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.BR PERF_EVENT_IOC_SET_FILTER " (Since Linux 2.6.33)"
|
|
|
96cc1f |
+.BR PERF_EVENT_IOC_SET_FILTER " (since Linux 2.6.33)"
|
|
|
96cc1f |
+.\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830
|
|
|
96cc1f |
This adds an ftrace filter to this event.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The argument is a pointer to the desired ftrace filter.
|
|
|
96cc1f |
-.SS Using prctl
|
|
|
96cc1f |
-A process can enable or disable all the event groups that are
|
|
|
96cc1f |
-attached to it using the
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_EVENT_IOC_ID " (since Linux 3.12)"
|
|
|
96cc1f |
+.\" commit cf4957f17f2a89984915ea808876d9c82225b862
|
|
|
96cc1f |
+This returns the event ID value for the given event file descriptor.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The argument is a pointer to a 64-bit unsigned integer
|
|
|
96cc1f |
+to hold the result.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_EVENT_IOC_SET_BPF " (since Linux 4.1)"
|
|
|
96cc1f |
+.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5
|
|
|
96cc1f |
+This allows attaching a Berkeley Packet Filter (BPF)
|
|
|
96cc1f |
+program to an existing kprobe tracepoint event.
|
|
|
96cc1f |
+You need
|
|
|
96cc1f |
+.B CAP_SYS_ADMIN
|
|
|
96cc1f |
+privileges to use this ioctl.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The argument is a BPF program file descriptor that was created by
|
|
|
96cc1f |
+a previous
|
|
|
96cc1f |
+.BR bpf (2)
|
|
|
96cc1f |
+system call.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_EVENT_IOC_PAUSE_OUTPUT " (since Linux 4.7)"
|
|
|
96cc1f |
+.\" commit 86e7972f690c1017fd086cdfe53d8524e68c661c
|
|
|
96cc1f |
+This allows pausing and resuming the event's ring-buffer.
|
|
|
96cc1f |
+A paused ring-buffer does not prevent generation of samples,
|
|
|
96cc1f |
+but simply discards them.
|
|
|
96cc1f |
+The discarded samples are considered lost, and cause a
|
|
|
96cc1f |
+.BR PERF_RECORD_LOST
|
|
|
96cc1f |
+sample to be generated when possible.
|
|
|
96cc1f |
+An overflow signal may still be triggered by the discarded sample
|
|
|
96cc1f |
+even though the ring-buffer remains empty.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The argument is an unsigned 32-bit integer.
|
|
|
96cc1f |
+A nonzero value pauses the ring-buffer, while a
|
|
|
96cc1f |
+zero value resumes the ring-buffer.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_EVENT_MODIFY_ATTRIBUTES " (since Linux 4.17)"
|
|
|
96cc1f |
+.\" commit 32ff77e8cc9e66cc4fb38098f64fd54cc8f54573
|
|
|
96cc1f |
+This allows modifying an existing event without the overhead
|
|
|
96cc1f |
+of closing and reopening a new event.
|
|
|
96cc1f |
+Currently this is supported only for breakpoint events.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The argument is a pointer to a
|
|
|
96cc1f |
+.I perf_event_attr
|
|
|
96cc1f |
+structure containing the updated event settings.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR PERF_EVENT_IOC_QUERY_BPF " (since Linux 4.16)"
|
|
|
96cc1f |
+.\" commit f371b304f12e31fe30207c41ca7754564e0ea4dc
|
|
|
96cc1f |
+This allows querying which Berkeley Packet Filter (BPF)
|
|
|
96cc1f |
+programs are attached to an existing kprobe tracepoint.
|
|
|
96cc1f |
+You can only attach one BPF program per event, but you can
|
|
|
96cc1f |
+have multiple events attached to a tracepoint.
|
|
|
96cc1f |
+Querying this value on one tracepoint event returns the id
|
|
|
96cc1f |
+of all BPF programs in all events attached to the tracepoint.
|
|
|
96cc1f |
+You need
|
|
|
96cc1f |
+.B CAP_SYS_ADMIN
|
|
|
96cc1f |
+privileges to use this ioctl.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The argument is a pointer to a structure
|
|
|
96cc1f |
+.in +4n
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
+struct perf_event_query_bpf {
|
|
|
96cc1f |
+ __u32 ids_len;
|
|
|
96cc1f |
+ __u32 prog_cnt;
|
|
|
96cc1f |
+ __u32 ids[0];
|
|
|
96cc1f |
+};
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.I ids_len
|
|
|
96cc1f |
+field indicates the number of ids that can fit in the provided
|
|
|
96cc1f |
+.I ids
|
|
|
96cc1f |
+array.
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.I prog_cnt
|
|
|
96cc1f |
+value is filled in by the kernel with the number of attached
|
|
|
96cc1f |
+BPF programs.
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.I ids
|
|
|
96cc1f |
+array is filled with the id of each attached BPF program.
|
|
|
96cc1f |
+If there are more programs than will fit in the array, then the
|
|
|
96cc1f |
+kernel will return
|
|
|
96cc1f |
+.B ENOSPC
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.I ids_len
|
|
|
96cc1f |
+will indicate the number of program IDs that were successfully copied.
|
|
|
96cc1f |
+.\"
|
|
|
96cc1f |
+.SS Using prctl(2)
|
|
|
96cc1f |
+A process can enable or disable all currently open event groups
|
|
|
96cc1f |
+using the
|
|
|
96cc1f |
.BR prctl (2)
|
|
|
96cc1f |
.B PR_TASK_PERF_EVENTS_ENABLE
|
|
|
96cc1f |
and
|
|
|
96cc1f |
.B PR_TASK_PERF_EVENTS_DISABLE
|
|
|
96cc1f |
operations.
|
|
|
96cc1f |
-This applies to all counters on the current process, whether created by
|
|
|
96cc1f |
-this process or by another, and does not affect any counters that this
|
|
|
96cc1f |
-process has created on other processes.
|
|
|
96cc1f |
-It enables or disables only
|
|
|
96cc1f |
-the group leaders, not any other members in the groups.
|
|
|
96cc1f |
+This applies only to events created locally by the calling process.
|
|
|
96cc1f |
+This does not apply to events created by other processes attached
|
|
|
96cc1f |
+to the calling process or inherited events from a parent process.
|
|
|
96cc1f |
+Only group leaders are enabled and disabled,
|
|
|
96cc1f |
+not any other members of the groups.
|
|
|
96cc1f |
.SS perf_event related configuration files
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
Files in
|
|
|
96cc1f |
.I /proc/sys/kernel/
|
|
|
96cc1f |
.RS 4
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I /proc/sys/kernel/perf_event_paranoid
|
|
|
96cc1f |
-
|
|
|
96cc1f |
The
|
|
|
96cc1f |
.I perf_event_paranoid
|
|
|
96cc1f |
file can be set to restrict access to the performance counters.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-2 - only allow user-space measurements
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-1 - (default) allow both kernel and user measurements
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-0 - allow access to CPU-specific data but not raw tracepoint samples
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-\-1 - no restrictions
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+.PD 0
|
|
|
96cc1f |
+.RS
|
|
|
96cc1f |
+.IP 2 4
|
|
|
96cc1f |
+allow only user-space measurements (default since Linux 4.6).
|
|
|
96cc1f |
+.\" default changed in commit 0161028b7c8aebef64194d3d73e43bc3b53b5c66
|
|
|
96cc1f |
+.IP 1
|
|
|
96cc1f |
+allow both kernel and user measurements (default before Linux 4.6).
|
|
|
96cc1f |
+.IP 0
|
|
|
96cc1f |
+allow access to CPU-specific data but not raw tracepoint samples.
|
|
|
96cc1f |
+.IP \-1
|
|
|
96cc1f |
+no restrictions.
|
|
|
96cc1f |
+.RE
|
|
|
96cc1f |
+.PD
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The existence of the
|
|
|
96cc1f |
.I perf_event_paranoid
|
|
|
96cc1f |
file is the official method for determining if a kernel supports
|
|
|
96cc1f |
.BR perf_event_open ().
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I /proc/sys/kernel/perf_event_max_sample_rate
|
|
|
96cc1f |
-
|
|
|
96cc1f |
This sets the maximum sample rate.
|
|
|
96cc1f |
Setting this too high can allow
|
|
|
96cc1f |
users to sample at a rate that impacts overall machine performance
|
|
|
96cc1f |
@@ -1954,71 +3046,96 @@ and potentially lock up the machine.
|
|
|
96cc1f |
The default value is
|
|
|
96cc1f |
100000 (samples per second).
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
+.I /proc/sys/kernel/perf_event_max_stack
|
|
|
96cc1f |
+.\" Introduced in c5dfd78eb79851e278b7973031b9ca363da87a7e
|
|
|
96cc1f |
+This file sets the maximum depth of stack frame entries reported
|
|
|
96cc1f |
+when generating a call trace.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
.I /proc/sys/kernel/perf_event_mlock_kb
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-Maximum number of pages an unprivileged user can mlock (2) .
|
|
|
96cc1f |
+Maximum number of pages an unprivileged user can
|
|
|
96cc1f |
+.BR mlock (2).
|
|
|
96cc1f |
The default is 516 (kB).
|
|
|
96cc1f |
-
|
|
|
96cc1f |
.RE
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
Files in
|
|
|
96cc1f |
.I /sys/bus/event_source/devices/
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
.RS 4
|
|
|
96cc1f |
-Since Linux 2.6.34 the kernel supports having multiple PMUs
|
|
|
96cc1f |
+Since Linux 2.6.34, the kernel supports having multiple PMUs
|
|
|
96cc1f |
available for monitoring.
|
|
|
96cc1f |
Information on how to program these PMUs can be found under
|
|
|
96cc1f |
.IR /sys/bus/event_source/devices/ .
|
|
|
96cc1f |
Each subdirectory corresponds to a different PMU.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR /sys/bus/event_source/devices/*/type " (Since Linux 2.6.38)"
|
|
|
96cc1f |
+.IR /sys/bus/event_source/devices/*/type " (since Linux 2.6.38)"
|
|
|
96cc1f |
+.\" commit abe43400579d5de0078c2d3a760e6598e183f871
|
|
|
96cc1f |
This contains an integer that can be used in the
|
|
|
96cc1f |
.I type
|
|
|
96cc1f |
-field of perf_event_attr to indicate you wish to use this PMU.
|
|
|
96cc1f |
+field of
|
|
|
96cc1f |
+.I perf_event_attr
|
|
|
96cc1f |
+to indicate that you wish to use this PMU.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR /sys/bus/event_source/devices/*/rdpmc " (Since Linux 3.4)"
|
|
|
96cc1f |
+.IR /sys/bus/event_source/devices/cpu/rdpmc " (since Linux 3.4)"
|
|
|
96cc1f |
+.\" commit 0c9d42ed4cee2aa1dfc3a260b741baae8615744f
|
|
|
96cc1f |
If this file is 1, then direct user-space access to the
|
|
|
96cc1f |
performance counter registers is allowed via the rdpmc instruction.
|
|
|
96cc1f |
This can be disabled by echoing 0 to the file.
|
|
|
96cc1f |
-.TP
|
|
|
96cc1f |
-.IR /sys/bus/event_source/devices/*/format/ " (Since Linux 3.4)"
|
|
|
96cc1f |
-This sub-directory contains information on the architecture-specific
|
|
|
96cc1f |
-sub-fields available for programming the various
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+As of Linux 4.0
|
|
|
96cc1f |
+.\" a66734297f78707ce39d756b656bfae861d53f62
|
|
|
96cc1f |
+.\" 7911d3f7af14a614617e38245fedf98a724e46a9
|
|
|
96cc1f |
+the behavior has changed, so that 1 now means only allow access
|
|
|
96cc1f |
+to processes with active perf events, with 2 indicating the old
|
|
|
96cc1f |
+allow-anyone-access behavior.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.IR /sys/bus/event_source/devices/*/format/ " (since Linux 3.4)"
|
|
|
96cc1f |
+.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
|
|
|
96cc1f |
+This subdirectory contains information on the architecture-specific
|
|
|
96cc1f |
+subfields available for programming the various
|
|
|
96cc1f |
.I config
|
|
|
96cc1f |
-fields in the perf_event_attr struct.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+fields in the
|
|
|
96cc1f |
+.I perf_event_attr
|
|
|
96cc1f |
+struct.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The content of each file is the name of the config field, followed
|
|
|
96cc1f |
by a colon, followed by a series of integer bit ranges separated by
|
|
|
96cc1f |
commas.
|
|
|
96cc1f |
For example, the file
|
|
|
96cc1f |
.I event
|
|
|
96cc1f |
may contain the value
|
|
|
96cc1f |
-.I config1:1,6-10,44
|
|
|
96cc1f |
-which indicates that event is an attribute that occupies bits 1,6-10, and 44
|
|
|
96cc1f |
-of perf_event_attr::config1.
|
|
|
96cc1f |
+.I config1:1,6\-10,44
|
|
|
96cc1f |
+which indicates that event is an attribute that occupies bits 1,6\(en10, and 44
|
|
|
96cc1f |
+of
|
|
|
96cc1f |
+.IR perf_event_attr::config1 .
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR /sys/bus/event_source/devices/*/events/ " (Since Linux 3.4)"
|
|
|
96cc1f |
-This sub-directory contains files with pre-defined events.
|
|
|
96cc1f |
+.IR /sys/bus/event_source/devices/*/events/ " (since Linux 3.4)"
|
|
|
96cc1f |
+.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
|
|
|
96cc1f |
+This subdirectory contains files with predefined events.
|
|
|
96cc1f |
The contents are strings describing the event settings
|
|
|
96cc1f |
expressed in terms of the fields found in the previously mentioned
|
|
|
96cc1f |
.I ./format/
|
|
|
96cc1f |
directory.
|
|
|
96cc1f |
These are not necessarily complete lists of all events supported by
|
|
|
96cc1f |
a PMU, but usually a subset of events deemed useful or interesting.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
The content of each file is a list of attribute names
|
|
|
96cc1f |
separated by commas.
|
|
|
96cc1f |
Each entry has an optional value (either hex or decimal).
|
|
|
96cc1f |
-If no value is specified than it is assumed to be a single-bit
|
|
|
96cc1f |
+If no value is specified, then it is assumed to be a single-bit
|
|
|
96cc1f |
field with a value of 1.
|
|
|
96cc1f |
An example entry may look like this:
|
|
|
96cc1f |
-.I event=0x2,inv,ldlat=3
|
|
|
96cc1f |
+.IR event=0x2,inv,ldlat=3 .
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.I /sys/bus/event_source/devices/*/uevent
|
|
|
96cc1f |
This file is the standard kernel device interface
|
|
|
96cc1f |
for injecting hotplug events.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
-.IR /sys/bus/event_source/devices/*/cpumask " (Since Linux 3.7)"
|
|
|
96cc1f |
-The cpumask file contains a comma-separated list of integers that
|
|
|
96cc1f |
-indicate a representative cpu number for each socket (package)
|
|
|
96cc1f |
+.IR /sys/bus/event_source/devices/*/cpumask " (since Linux 3.7)"
|
|
|
96cc1f |
+.\" commit 314d9f63f385096580e9e2a06eaa0745d92fe4ac
|
|
|
96cc1f |
+The
|
|
|
96cc1f |
+.I cpumask
|
|
|
96cc1f |
+file contains a comma-separated list of integers that
|
|
|
96cc1f |
+indicate a representative CPU number for each socket (package)
|
|
|
96cc1f |
on the motherboard.
|
|
|
96cc1f |
This is needed when setting up uncore or northbridge events, as
|
|
|
96cc1f |
those PMUs present socket-wide events.
|
|
|
96cc1f |
@@ -2030,34 +3147,172 @@ returns the new file descriptor, or \-1 if an error occurred
|
|
|
96cc1f |
.I errno
|
|
|
96cc1f |
is set appropriately).
|
|
|
96cc1f |
.SH ERRORS
|
|
|
96cc1f |
+The errors returned by
|
|
|
96cc1f |
+.BR perf_event_open ()
|
|
|
96cc1f |
+can be inconsistent, and may
|
|
|
96cc1f |
+vary across processor architectures and performance monitoring units.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B E2BIG
|
|
|
96cc1f |
+Returned if the
|
|
|
96cc1f |
+.I perf_event_attr
|
|
|
96cc1f |
+.I size
|
|
|
96cc1f |
+value is too small
|
|
|
96cc1f |
+(smaller than
|
|
|
96cc1f |
+.BR PERF_ATTR_SIZE_VER0 ),
|
|
|
96cc1f |
+too big (larger than the page size),
|
|
|
96cc1f |
+or larger than the kernel supports and the extra bytes are not zero.
|
|
|
96cc1f |
+When
|
|
|
96cc1f |
+.B E2BIG
|
|
|
96cc1f |
+is returned, the
|
|
|
96cc1f |
+.I perf_event_attr
|
|
|
96cc1f |
+.I size
|
|
|
96cc1f |
+field is overwritten by the kernel to be the size of the structure
|
|
|
96cc1f |
+it was expecting.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B EACCES
|
|
|
96cc1f |
+Returned when the requested event requires
|
|
|
96cc1f |
+.B CAP_SYS_ADMIN
|
|
|
96cc1f |
+permissions (or a more permissive perf_event paranoid setting).
|
|
|
96cc1f |
+Some common cases where an unprivileged process
|
|
|
96cc1f |
+may encounter this error:
|
|
|
96cc1f |
+attaching to a process owned by a different user;
|
|
|
96cc1f |
+monitoring all processes on a given CPU (i.e., specifying the
|
|
|
96cc1f |
+.I pid
|
|
|
96cc1f |
+argument as \-1);
|
|
|
96cc1f |
+and not setting
|
|
|
96cc1f |
+.I exclude_kernel
|
|
|
96cc1f |
+when the paranoid setting requires it.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B EBADF
|
|
|
96cc1f |
+Returned if the
|
|
|
96cc1f |
+.I group_fd
|
|
|
96cc1f |
+file descriptor is not valid, or, if
|
|
|
96cc1f |
+.B PERF_FLAG_PID_CGROUP
|
|
|
96cc1f |
+is set,
|
|
|
96cc1f |
+the cgroup file descriptor in
|
|
|
96cc1f |
+.I pid
|
|
|
96cc1f |
+is not valid.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR EBUSY " (since Linux 4.1)"
|
|
|
96cc1f |
+.\" bed5b25ad9c8a2f5d735ef0bc746ec870c01c1b0
|
|
|
96cc1f |
+Returned if another event already has exclusive
|
|
|
96cc1f |
+access to the PMU.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B EFAULT
|
|
|
96cc1f |
+Returned if the
|
|
|
96cc1f |
+.I attr
|
|
|
96cc1f |
+pointer points at an invalid memory address.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B EINVAL
|
|
|
96cc1f |
-Returned if the specified event is not available.
|
|
|
96cc1f |
+Returned if the specified event is invalid.
|
|
|
96cc1f |
+There are many possible reasons for this.
|
|
|
96cc1f |
+A not-exhaustive list:
|
|
|
96cc1f |
+.I sample_freq
|
|
|
96cc1f |
+is higher than the maximum setting;
|
|
|
96cc1f |
+the
|
|
|
96cc1f |
+.I cpu
|
|
|
96cc1f |
+to monitor does not exist;
|
|
|
96cc1f |
+.I read_format
|
|
|
96cc1f |
+is out of range;
|
|
|
96cc1f |
+.I sample_type
|
|
|
96cc1f |
+is out of range;
|
|
|
96cc1f |
+the
|
|
|
96cc1f |
+.I flags
|
|
|
96cc1f |
+value is out of range;
|
|
|
96cc1f |
+.I exclusive
|
|
|
96cc1f |
+or
|
|
|
96cc1f |
+.I pinned
|
|
|
96cc1f |
+set and the event is not a group leader;
|
|
|
96cc1f |
+the event
|
|
|
96cc1f |
+.I config
|
|
|
96cc1f |
+values are out of range or set reserved bits;
|
|
|
96cc1f |
+the generic event selected is not supported; or
|
|
|
96cc1f |
+there is not enough room to add the selected event.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B EMFILE
|
|
|
96cc1f |
+Each opened event uses one file descriptor.
|
|
|
96cc1f |
+If a large number of events are opened,
|
|
|
96cc1f |
+the per-process limit on the number of open file descriptors will be reached,
|
|
|
96cc1f |
+and no more events can be created.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B ENODEV
|
|
|
96cc1f |
+Returned when the event involves a feature not supported
|
|
|
96cc1f |
+by the current CPU.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B ENOENT
|
|
|
96cc1f |
+Returned if the
|
|
|
96cc1f |
+.I type
|
|
|
96cc1f |
+setting is not valid.
|
|
|
96cc1f |
+This error is also returned for
|
|
|
96cc1f |
+some unsupported generic events.
|
|
|
96cc1f |
.TP
|
|
|
96cc1f |
.B ENOSPC
|
|
|
96cc1f |
Prior to Linux 3.3, if there was not enough room for the event,
|
|
|
96cc1f |
+.\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6
|
|
|
96cc1f |
.B ENOSPC
|
|
|
96cc1f |
was returned.
|
|
|
96cc1f |
-Linus did not like this, and this was changed to
|
|
|
96cc1f |
+In Linux 3.3, this was changed to
|
|
|
96cc1f |
.BR EINVAL .
|
|
|
96cc1f |
.B ENOSPC
|
|
|
96cc1f |
-is still returned if you try to read results into
|
|
|
96cc1f |
-too small of a buffer.
|
|
|
96cc1f |
+is still returned if you try to add more breakpoint events
|
|
|
96cc1f |
+than supported by the hardware.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B ENOSYS
|
|
|
96cc1f |
+Returned if
|
|
|
96cc1f |
+.B PERF_SAMPLE_STACK_USER
|
|
|
96cc1f |
+is set in
|
|
|
96cc1f |
+.I sample_type
|
|
|
96cc1f |
+and it is not supported by hardware.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B EOPNOTSUPP
|
|
|
96cc1f |
+Returned if an event requiring a specific hardware feature is
|
|
|
96cc1f |
+requested but there is no hardware support.
|
|
|
96cc1f |
+This includes requesting low-skid events if not supported,
|
|
|
96cc1f |
+branch tracing if it is not available, sampling if no PMU
|
|
|
96cc1f |
+interrupt is available, and branch stacks for software events.
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.BR EOVERFLOW " (since Linux 4.8)"
|
|
|
96cc1f |
+.\" 97c79a38cd454602645f0470ffb444b3b75ce574
|
|
|
96cc1f |
+Returned if
|
|
|
96cc1f |
+.B PERF_SAMPLE_CALLCHAIN
|
|
|
96cc1f |
+is requested and
|
|
|
96cc1f |
+.I sample_max_stack
|
|
|
96cc1f |
+is larger than the maximum specified in
|
|
|
96cc1f |
+.IR /proc/sys/kernel/perf_event_max_stack .
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B EPERM
|
|
|
96cc1f |
+Returned on many (but not all) architectures when an unsupported
|
|
|
96cc1f |
+.IR exclude_hv ", " exclude_idle ", " exclude_user ", or " exclude_kernel
|
|
|
96cc1f |
+setting is specified.
|
|
|
96cc1f |
+.IP
|
|
|
96cc1f |
+It can also happen, as with
|
|
|
96cc1f |
+.BR EACCES ,
|
|
|
96cc1f |
+when the requested event requires
|
|
|
96cc1f |
+.B CAP_SYS_ADMIN
|
|
|
96cc1f |
+permissions (or a more permissive perf_event paranoid setting).
|
|
|
96cc1f |
+This includes setting a breakpoint on a kernel address,
|
|
|
96cc1f |
+and (since Linux 3.13) setting a kernel function-trace tracepoint.
|
|
|
96cc1f |
+.\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34
|
|
|
96cc1f |
+.TP
|
|
|
96cc1f |
+.B ESRCH
|
|
|
96cc1f |
+Returned if attempting to attach to a process that does not exist.
|
|
|
96cc1f |
.SH VERSION
|
|
|
96cc1f |
.BR perf_event_open ()
|
|
|
96cc1f |
was introduced in Linux 2.6.31 but was called
|
|
|
96cc1f |
-.BR perf_counter_open () .
|
|
|
96cc1f |
+.\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e
|
|
|
96cc1f |
+.BR perf_counter_open ().
|
|
|
96cc1f |
It was renamed in Linux 2.6.32.
|
|
|
96cc1f |
+.\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
|
|
|
96cc1f |
.SH CONFORMING TO
|
|
|
96cc1f |
This
|
|
|
96cc1f |
.BR perf_event_open ()
|
|
|
96cc1f |
-system call Linux- specific
|
|
|
96cc1f |
+system call Linux-specific
|
|
|
96cc1f |
and should not be used in programs intended to be portable.
|
|
|
96cc1f |
.SH NOTES
|
|
|
96cc1f |
Glibc does not provide a wrapper for this system call; call it using
|
|
|
96cc1f |
.BR syscall (2).
|
|
|
96cc1f |
See the example below.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
The official way of knowing if
|
|
|
96cc1f |
.BR perf_event_open ()
|
|
|
96cc1f |
support is enabled is checking
|
|
|
96cc1f |
@@ -2070,56 +3325,74 @@ option to
|
|
|
96cc1f |
.BR fcntl (2)
|
|
|
96cc1f |
is needed to properly get overflow signals in threads.
|
|
|
96cc1f |
This was introduced in Linux 2.6.32.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-Prior to Linux 2.6.33 (at least for x86) the kernel did not check
|
|
|
96cc1f |
+.\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+Prior to Linux 2.6.33 (at least for x86),
|
|
|
96cc1f |
+.\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1
|
|
|
96cc1f |
+the kernel did not check
|
|
|
96cc1f |
if events could be scheduled together until read time.
|
|
|
96cc1f |
The same happens on all known kernels if the NMI watchdog is enabled.
|
|
|
96cc1f |
This means to see if a given set of events works you have to
|
|
|
96cc1f |
.BR perf_event_open (),
|
|
|
96cc1f |
start, then read before you know for sure you
|
|
|
96cc1f |
can get valid measurements.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-Prior to Linux 2.6.34 event constraints were not enforced by the kernel.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+Prior to Linux 2.6.34,
|
|
|
96cc1f |
+.\" FIXME . cannot find a kernel commit for this one
|
|
|
96cc1f |
+event constraints were not enforced by the kernel.
|
|
|
96cc1f |
In that case, some events would silently return "0" if the kernel
|
|
|
96cc1f |
scheduled them in an improper counter slot.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-Prior to Linux 2.6.34 there was a bug when multiplexing where the
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+Prior to Linux 2.6.34, there was a bug when multiplexing where the
|
|
|
96cc1f |
wrong results could be returned.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
|
|
|
96cc1f |
"inherit" is enabled and many threads are started.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
Prior to Linux 2.6.35,
|
|
|
96cc1f |
+.\" commit 050735b08ca8a016bbace4445fa025b88fee770b
|
|
|
96cc1f |
.B PERF_FORMAT_GROUP
|
|
|
96cc1f |
did not work with attached processes.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
-In older Linux 2.6 versions,
|
|
|
96cc1f |
-refreshing an event group leader refreshed all siblings,
|
|
|
96cc1f |
-and refreshing with a parameter of 0 enabled infinite refresh.
|
|
|
96cc1f |
-This behavior is unsupported and should not be relied on.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
There is a bug in the kernel code between
|
|
|
96cc1f |
Linux 2.6.36 and Linux 3.0 that ignores the
|
|
|
96cc1f |
"watermark" field and acts as if a wakeup_event
|
|
|
96cc1f |
was chosen if the union has a
|
|
|
96cc1f |
-non-zero value in it.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+nonzero value in it.
|
|
|
96cc1f |
+.\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
From Linux 2.6.31 to Linux 3.4, the
|
|
|
96cc1f |
.B PERF_IOC_FLAG_GROUP
|
|
|
96cc1f |
ioctl argument was broken and would repeatedly operate
|
|
|
96cc1f |
on the event specified rather than iterating across
|
|
|
96cc1f |
all sibling events in a group.
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+From Linux 3.4 to Linux 3.11, the mmap
|
|
|
96cc1f |
+.\" commit fa7315871046b9a4c48627905691dbde57e51033
|
|
|
96cc1f |
+.I cap_usr_rdpmc
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.I cap_usr_time
|
|
|
96cc1f |
+bits mapped to the same location.
|
|
|
96cc1f |
+Code should migrate to the new
|
|
|
96cc1f |
+.I cap_user_rdpmc
|
|
|
96cc1f |
+and
|
|
|
96cc1f |
+.I cap_user_time
|
|
|
96cc1f |
+fields instead.
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
Always double-check your results!
|
|
|
96cc1f |
Various generalized events have had wrong values.
|
|
|
96cc1f |
For example, retired branches measured
|
|
|
96cc1f |
the wrong thing on AMD machines until Linux 2.6.35.
|
|
|
96cc1f |
+.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
|
|
|
96cc1f |
.SH EXAMPLE
|
|
|
96cc1f |
The following is a short example that measures the total
|
|
|
96cc1f |
instruction count of a call to
|
|
|
96cc1f |
.BR printf (3).
|
|
|
96cc1f |
-.nf
|
|
|
96cc1f |
-
|
|
|
96cc1f |
+.PP
|
|
|
96cc1f |
+.EX
|
|
|
96cc1f |
#include <stdlib.h>
|
|
|
96cc1f |
#include <stdio.h>
|
|
|
96cc1f |
#include <unistd.h>
|
|
|
96cc1f |
@@ -2128,7 +3401,7 @@ instruction count of a call to
|
|
|
96cc1f |
#include <linux/perf_event.h>
|
|
|
96cc1f |
#include <asm/unistd.h>
|
|
|
96cc1f |
|
|
|
96cc1f |
-long
|
|
|
96cc1f |
+static long
|
|
|
96cc1f |
perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
|
|
|
96cc1f |
int cpu, int group_fd, unsigned long flags)
|
|
|
96cc1f |
{
|
|
|
96cc1f |
@@ -2172,8 +3445,9 @@ main(int argc, char **argv)
|
|
|
96cc1f |
|
|
|
96cc1f |
close(fd);
|
|
|
96cc1f |
}
|
|
|
96cc1f |
-.fi
|
|
|
96cc1f |
+.EE
|
|
|
96cc1f |
.SH SEE ALSO
|
|
|
96cc1f |
+.BR perf (1),
|
|
|
96cc1f |
.BR fcntl (2),
|
|
|
96cc1f |
.BR mmap (2),
|
|
|
96cc1f |
.BR open (2),
|
|
|
96cc1f |
--
|
|
|
96cc1f |
2.17.1
|
|
|
96cc1f |
|