mirror of https://github.com/mkerrisk/man-pages
perf_event_open.2: Minor grammar, formatting, wording, and typo fixes
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
d2c3d8a829
commit
ce88f77b91
|
@ -97,13 +97,13 @@ when running on the specified CPU.
|
||||||
.TP
|
.TP
|
||||||
.BR "pid == \-1" " and " "cpu >= 0"
|
.BR "pid == \-1" " and " "cpu >= 0"
|
||||||
This measures all processes/threads on the specified CPU.
|
This measures all processes/threads on the specified CPU.
|
||||||
Measurements such as this require the
|
This requires
|
||||||
.B CAP_SYS_ADMIN
|
.B CAP_SYS_ADMIN
|
||||||
capability or a
|
capability or a
|
||||||
.I /proc/sys/kernel/perf_event_paranoid
|
.I /proc/sys/kernel/perf_event_paranoid
|
||||||
value of less than 1.
|
value of less than 1.
|
||||||
.TP
|
.TP
|
||||||
.BR pid==\-1 " and " cpu==\-1
|
.BR "pid == \-1" " and " "cpu == \-1"
|
||||||
This setting is invalid and will return an error.
|
This setting is invalid and will return an error.
|
||||||
.P
|
.P
|
||||||
The
|
The
|
||||||
|
@ -124,7 +124,7 @@ An event group is scheduled onto the CPU as a unit: it will
|
||||||
be put onto the CPU only if all of the events in the group can be put onto
|
be put onto the CPU only if all of the events in the group can be put onto
|
||||||
the CPU.
|
the CPU.
|
||||||
This means that the values of the member events can be
|
This means that the values of the member events can be
|
||||||
meaningfully compared, added, divided (to get ratios), and so on, with each
|
meaningfully compared\(emadded, divided (to get ratios), and so on\(emwith each
|
||||||
other, since they have counted events for the same set of executed
|
other, since they have counted events for the same set of executed
|
||||||
instructions.
|
instructions.
|
||||||
.P
|
.P
|
||||||
|
@ -161,7 +161,7 @@ This flag reroutes the output from an event to the group leader.
|
||||||
.BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)."
|
.BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)."
|
||||||
This flag activates per-container system-wide monitoring.
|
This flag activates per-container system-wide monitoring.
|
||||||
A container
|
A container
|
||||||
is an abstraction that isolates a set of resources for finer grain
|
is an abstraction that isolates a set of resources for finer-grained
|
||||||
control (CPUs, memory, etc.).
|
control (CPUs, memory, etc.).
|
||||||
In this mode, the event is measured
|
In this mode, the event is measured
|
||||||
only if the thread running on the monitored CPU belongs to the designated
|
only if the thread running on the monitored CPU belongs to the designated
|
||||||
|
@ -189,43 +189,43 @@ for the event being created.
|
||||||
.in +4n
|
.in +4n
|
||||||
.nf
|
.nf
|
||||||
struct perf_event_attr {
|
struct perf_event_attr {
|
||||||
__u32 type; /* Type of event */
|
__u32 type; /* Type of event */
|
||||||
__u32 size; /* Size of attribute structure */
|
__u32 size; /* Size of attribute structure */
|
||||||
__u64 config; /* Type-specific configuration */
|
__u64 config; /* Type-specific configuration */
|
||||||
|
|
||||||
union {
|
union {
|
||||||
__u64 sample_period; /* Period of sampling */
|
__u64 sample_period; /* Period of sampling */
|
||||||
__u64 sample_freq; /* Frequency of sampling */
|
__u64 sample_freq; /* Frequency of sampling */
|
||||||
};
|
};
|
||||||
|
|
||||||
__u64 sample_type; /* Specifies values included in sample */
|
__u64 sample_type; /* Specifies values included in sample */
|
||||||
__u64 read_format; /* Specifies values returned in read */
|
__u64 read_format; /* Specifies values returned in read */
|
||||||
|
|
||||||
__u64 disabled : 1, /* off by default */
|
__u64 disabled : 1, /* off by default */
|
||||||
inherit : 1, /* children inherit it */
|
inherit : 1, /* children inherit it */
|
||||||
pinned : 1, /* must always be on PMU */
|
pinned : 1, /* must always be on PMU */
|
||||||
exclusive : 1, /* only group on PMU */
|
exclusive : 1, /* only group on PMU */
|
||||||
exclude_user : 1, /* don't count user */
|
exclude_user : 1, /* don't count user */
|
||||||
exclude_kernel : 1, /* don't count kernel */
|
exclude_kernel : 1, /* don't count kernel */
|
||||||
exclude_hv : 1, /* don't count hypervisor */
|
exclude_hv : 1, /* don't count hypervisor */
|
||||||
exclude_idle : 1, /* don't count when idle */
|
exclude_idle : 1, /* don't count when idle */
|
||||||
mmap : 1, /* include mmap data */
|
mmap : 1, /* include mmap data */
|
||||||
comm : 1, /* include comm data */
|
comm : 1, /* include comm data */
|
||||||
freq : 1, /* use freq, not period */
|
freq : 1, /* use freq, not period */
|
||||||
inherit_stat : 1, /* per task counts */
|
inherit_stat : 1, /* per task counts */
|
||||||
enable_on_exec : 1, /* next exec enables */
|
enable_on_exec : 1, /* next exec enables */
|
||||||
task : 1, /* trace fork/exit */
|
task : 1, /* trace fork/exit */
|
||||||
watermark : 1, /* wakeup_watermark */
|
watermark : 1, /* wakeup_watermark */
|
||||||
precise_ip : 2, /* skid constraint */
|
precise_ip : 2, /* skid constraint */
|
||||||
mmap_data : 1, /* non-exec mmap data */
|
mmap_data : 1, /* non-exec mmap data */
|
||||||
sample_id_all : 1, /* sample_type all events */
|
sample_id_all : 1, /* sample_type all events */
|
||||||
exclude_host : 1, /* don't count in host */
|
exclude_host : 1, /* don't count in host */
|
||||||
exclude_guest : 1, /* don't count in guest */
|
exclude_guest : 1, /* don't count in guest */
|
||||||
exclude_callchain_kernel : 1,
|
exclude_callchain_kernel : 1,
|
||||||
/* exclude kernel callchains */
|
/* exclude kernel callchains */
|
||||||
exclude_callchain_user : 1,
|
exclude_callchain_user : 1,
|
||||||
/* exclude user callchains */
|
/* exclude user callchains */
|
||||||
__reserved_1 : 41;
|
__reserved_1 : 41;
|
||||||
|
|
||||||
union {
|
union {
|
||||||
__u32 wakeup_events; /* wakeup every n events */
|
__u32 wakeup_events; /* wakeup every n events */
|
||||||
|
@ -243,11 +243,11 @@ struct perf_event_attr {
|
||||||
__u64 bp_len; /* breakpoint length */
|
__u64 bp_len; /* breakpoint length */
|
||||||
__u64 config2; /* extension of config1 */
|
__u64 config2; /* extension of config1 */
|
||||||
};
|
};
|
||||||
__u64 branch_sample_type; /* enum perf_branch_sample_type */
|
__u64 branch_sample_type; /* enum perf_branch_sample_type */
|
||||||
__u64 sample_regs_user; /* user regs to dump on samples */
|
__u64 sample_regs_user; /* user regs to dump on samples */
|
||||||
__u32 sample_stack_user; /* size of stack to dump on
|
__u32 sample_stack_user; /* size of stack to dump on
|
||||||
samples */
|
samples */
|
||||||
__u32 __reserved_2; /* Align to u64 */
|
__u32 __reserved_2; /* Align to u64 */
|
||||||
|
|
||||||
};
|
};
|
||||||
.fi
|
.fi
|
||||||
|
@ -1234,35 +1234,35 @@ The structure of the first metadata mmap page is as follows:
|
||||||
.in +4n
|
.in +4n
|
||||||
.nf
|
.nf
|
||||||
struct perf_event_mmap_page {
|
struct perf_event_mmap_page {
|
||||||
__u32 version; /* version number of this structure */
|
__u32 version; /* version number of this structure */
|
||||||
__u32 compat_version; /* lowest version this is compat with */
|
__u32 compat_version; /* lowest version this is compat with */
|
||||||
__u32 lock; /* seqlock for synchronization */
|
__u32 lock; /* seqlock for synchronization */
|
||||||
__u32 index; /* hardware counter identifier */
|
__u32 index; /* hardware counter identifier */
|
||||||
__s64 offset; /* add to hardware counter value */
|
__s64 offset; /* add to hardware counter value */
|
||||||
__u64 time_enabled; /* time event active */
|
__u64 time_enabled; /* time event active */
|
||||||
__u64 time_running; /* time event on CPU */
|
__u64 time_running; /* time event on CPU */
|
||||||
union {
|
union {
|
||||||
__u64 capabilities;
|
__u64 capabilities;
|
||||||
struct {
|
struct {
|
||||||
__u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,
|
__u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,
|
||||||
cap_bit0_is_deprecated : 1,
|
cap_bit0_is_deprecated : 1,
|
||||||
cap_user_rdpmc : 1,
|
cap_user_rdpmc : 1,
|
||||||
cap_user_time : 1,
|
cap_user_time : 1,
|
||||||
cap_user_time_zero : 1,
|
cap_user_time_zero : 1,
|
||||||
};
|
};
|
||||||
};
|
};
|
||||||
__u16 pmc_width;
|
__u16 pmc_width;
|
||||||
__u16 time_shift;
|
__u16 time_shift;
|
||||||
__u32 time_mult;
|
__u32 time_mult;
|
||||||
__u64 time_offset;
|
__u64 time_offset;
|
||||||
__u64 __reserved[120]; /* Pad to 1k */
|
__u64 __reserved[120]; /* Pad to 1k */
|
||||||
__u64 data_head; /* head in the data section */
|
__u64 data_head; /* head in the data section */
|
||||||
__u64 data_tail; /* user-space written tail */
|
__u64 data_tail; /* user-space written tail */
|
||||||
}
|
}
|
||||||
.fi
|
.fi
|
||||||
.in
|
.in
|
||||||
|
|
||||||
The following looks at the fields in the
|
The following list describes the fields in the
|
||||||
.I perf_event_mmap_page
|
.I perf_event_mmap_page
|
||||||
structure in more detail:
|
structure in more detail:
|
||||||
.TP
|
.TP
|
||||||
|
@ -1432,13 +1432,16 @@ If
|
||||||
is set, then the hardware clock (the TSC timestamp counter on x86)
|
is set, then the hardware clock (the TSC timestamp counter on x86)
|
||||||
can be calculated from the
|
can be calculated from the
|
||||||
.IR time_zero ", " time_mult ", and " time_shift " values:"
|
.IR time_zero ", " time_mult ", and " time_shift " values:"
|
||||||
|
|
||||||
.nf
|
.nf
|
||||||
time = timestamp - time_zero;
|
time = timestamp - time_zero;
|
||||||
quot = time / time_mult;
|
quot = time / time_mult;
|
||||||
rem = time % time_mult;
|
rem = time % time_mult;
|
||||||
cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
|
cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
|
||||||
.fi
|
.fi
|
||||||
|
|
||||||
And vice versa:
|
And vice versa:
|
||||||
|
|
||||||
.nf
|
.nf
|
||||||
quot = cyc >> time_shift;
|
quot = cyc >> time_shift;
|
||||||
rem = cyc & ((1 << time_shift) - 1);
|
rem = cyc & ((1 << time_shift) - 1);
|
||||||
|
@ -1452,7 +1455,9 @@ The value continuously increases, it does not wrap.
|
||||||
The value needs to be manually wrapped by the size of the mmap buffer
|
The value needs to be manually wrapped by the size of the mmap buffer
|
||||||
before accessing the samples.
|
before accessing the samples.
|
||||||
|
|
||||||
On SMP-capable platforms, after reading the data_head value,
|
On SMP-capable platforms, after reading the
|
||||||
|
.I data_head
|
||||||
|
value,
|
||||||
user space should issue an rmb().
|
user space should issue an rmb().
|
||||||
.TP
|
.TP
|
||||||
.I data_tail
|
.I data_tail
|
||||||
|
@ -2146,10 +2151,10 @@ to calculate event values can be found in that section.
|
||||||
.PP
|
.PP
|
||||||
Various ioctls act on
|
Various ioctls act on
|
||||||
.BR perf_event_open ()
|
.BR perf_event_open ()
|
||||||
file descriptors
|
file descriptors:
|
||||||
.TP
|
.TP
|
||||||
.B PERF_EVENT_IOC_ENABLE
|
.B PERF_EVENT_IOC_ENABLE
|
||||||
Enables the individual event or event group specified by the
|
This enables the individual event or event group specified by the
|
||||||
file descriptor argument.
|
file descriptor argument.
|
||||||
|
|
||||||
If the
|
If the
|
||||||
|
@ -2159,7 +2164,7 @@ enabled, even if the event specified is not the group leader
|
||||||
(but see BUGS).
|
(but see BUGS).
|
||||||
.TP
|
.TP
|
||||||
.B PERF_EVENT_IOC_DISABLE
|
.B PERF_EVENT_IOC_DISABLE
|
||||||
Disables the individual counter or event group specified by the
|
This disables the individual counter or event group specified by the
|
||||||
file descriptor argument.
|
file descriptor argument.
|
||||||
|
|
||||||
Enabling or disabling the leader of a group enables or disables the
|
Enabling or disabling the leader of a group enables or disables the
|
||||||
|
@ -2234,7 +2239,7 @@ This adds an ftrace filter to this event.
|
||||||
The argument is a pointer to the desired ftrace filter.
|
The argument is a pointer to the desired ftrace filter.
|
||||||
.TP
|
.TP
|
||||||
.BR PERF_EVENT_IOC_ID " (since Linux 3.12)"
|
.BR PERF_EVENT_IOC_ID " (since Linux 3.12)"
|
||||||
Returns the event ID value for the given event fd.
|
This returns the event ID value for the given event fd.
|
||||||
|
|
||||||
The argument is a pointer to a 64-bit unsigned integer
|
The argument is a pointer to a 64-bit unsigned integer
|
||||||
to hold the result.
|
to hold the result.
|
||||||
|
@ -2288,14 +2293,15 @@ The default value is
|
||||||
.TP
|
.TP
|
||||||
.I /proc/sys/kernel/perf_event_mlock_kb
|
.I /proc/sys/kernel/perf_event_mlock_kb
|
||||||
|
|
||||||
Maximum number of pages an unprivileged user can mlock (2) .
|
Maximum number of pages an unprivileged user can
|
||||||
|
.BR mlock (2).
|
||||||
The default is 516 (kB).
|
The default is 516 (kB).
|
||||||
|
|
||||||
.RE
|
.RE
|
||||||
Files in
|
Files in
|
||||||
.I /sys/bus/event_source/devices/
|
.I /sys/bus/event_source/devices/
|
||||||
.RS 4
|
.RS 4
|
||||||
Since Linux 2.6.34 the kernel supports having multiple PMUs
|
Since Linux 2.6.34, the kernel supports having multiple PMUs
|
||||||
available for monitoring.
|
available for monitoring.
|
||||||
Information on how to program these PMUs can be found under
|
Information on how to program these PMUs can be found under
|
||||||
.IR /sys/bus/event_source/devices/ .
|
.IR /sys/bus/event_source/devices/ .
|
||||||
|
@ -2304,7 +2310,9 @@ Each subdirectory corresponds to a different PMU.
|
||||||
.IR /sys/bus/event_source/devices/*/type " (since Linux 2.6.38)"
|
.IR /sys/bus/event_source/devices/*/type " (since Linux 2.6.38)"
|
||||||
This contains an integer that can be used in the
|
This contains an integer that can be used in the
|
||||||
.I type
|
.I type
|
||||||
field of perf_event_attr to indicate you wish to use this PMU.
|
field of
|
||||||
|
.I perf_event_attr
|
||||||
|
to indicate that you wish to use this PMU.
|
||||||
.TP
|
.TP
|
||||||
.IR /sys/bus/event_source/devices/*/rdpmc " (since Linux 3.4)"
|
.IR /sys/bus/event_source/devices/*/rdpmc " (since Linux 3.4)"
|
||||||
If this file is 1, then direct user-space access to the
|
If this file is 1, then direct user-space access to the
|
||||||
|
@ -2315,7 +2323,9 @@ This can be disabled by echoing 0 to the file.
|
||||||
This subdirectory contains information on the architecture-specific
|
This subdirectory contains information on the architecture-specific
|
||||||
subfields available for programming the various
|
subfields available for programming the various
|
||||||
.I config
|
.I config
|
||||||
fields in the perf_event_attr struct.
|
fields in the
|
||||||
|
.I perf_event_attr
|
||||||
|
struct.
|
||||||
|
|
||||||
The content of each file is the name of the config field, followed
|
The content of each file is the name of the config field, followed
|
||||||
by a colon, followed by a series of integer bit ranges separated by
|
by a colon, followed by a series of integer bit ranges separated by
|
||||||
|
@ -2325,7 +2335,8 @@ For example, the file
|
||||||
may contain the value
|
may contain the value
|
||||||
.I config1:1,6-10,44
|
.I config1:1,6-10,44
|
||||||
which indicates that event is an attribute that occupies bits 1,6-10, and 44
|
which indicates that event is an attribute that occupies bits 1,6-10, and 44
|
||||||
of perf_event_attr::config1.
|
of
|
||||||
|
.IR perf_event_attr::config1 .
|
||||||
.TP
|
.TP
|
||||||
.IR /sys/bus/event_source/devices/*/events/ " (since Linux 3.4)"
|
.IR /sys/bus/event_source/devices/*/events/ " (since Linux 3.4)"
|
||||||
This subdirectory contains files with predefined events.
|
This subdirectory contains files with predefined events.
|
||||||
|
@ -2370,7 +2381,8 @@ can be inconsistent, and may
|
||||||
vary across processor architectures and performance monitoring units.
|
vary across processor architectures and performance monitoring units.
|
||||||
.TP
|
.TP
|
||||||
.B E2BIG
|
.B E2BIG
|
||||||
Returned if the perf_event_attr
|
Returned if the
|
||||||
|
.I perf_event_attr
|
||||||
.I size
|
.I size
|
||||||
value is too small
|
value is too small
|
||||||
(smaller than
|
(smaller than
|
||||||
|
@ -2379,7 +2391,8 @@ too big (larger than the page size),
|
||||||
or larger than the kernel supports and the extra bytes are not zero.
|
or larger than the kernel supports and the extra bytes are not zero.
|
||||||
When
|
When
|
||||||
.B E2BIG
|
.B E2BIG
|
||||||
is returned, the perf_event_attr
|
is returned, the
|
||||||
|
.I perf_event_attr
|
||||||
.I size
|
.I size
|
||||||
field is overwritten by the kernel to be the size of the structure
|
field is overwritten by the kernel to be the size of the structure
|
||||||
it was expecting.
|
it was expecting.
|
||||||
|
@ -2522,7 +2535,7 @@ option to
|
||||||
is needed to properly get overflow signals in threads.
|
is needed to properly get overflow signals in threads.
|
||||||
This was introduced in Linux 2.6.32.
|
This was introduced in Linux 2.6.32.
|
||||||
|
|
||||||
Prior to Linux 2.6.33 (at least for x86) the kernel did not check
|
Prior to Linux 2.6.33 (at least for x86), the kernel did not check
|
||||||
if events could be scheduled together until read time.
|
if events could be scheduled together until read time.
|
||||||
The same happens on all known kernels if the NMI watchdog is enabled.
|
The same happens on all known kernels if the NMI watchdog is enabled.
|
||||||
This means to see if a given set of events works you have to
|
This means to see if a given set of events works you have to
|
||||||
|
@ -2530,11 +2543,11 @@ This means to see if a given set of events works you have to
|
||||||
start, then read before you know for sure you
|
start, then read before you know for sure you
|
||||||
can get valid measurements.
|
can get valid measurements.
|
||||||
|
|
||||||
Prior to Linux 2.6.34 event constraints were not enforced by the kernel.
|
Prior to Linux 2.6.34, event constraints were not enforced by the kernel.
|
||||||
In that case, some events would silently return "0" if the kernel
|
In that case, some events would silently return "0" if the kernel
|
||||||
scheduled them in an improper counter slot.
|
scheduled them in an improper counter slot.
|
||||||
|
|
||||||
Prior to Linux 2.6.34 there was a bug when multiplexing where the
|
Prior to Linux 2.6.34, there was a bug when multiplexing where the
|
||||||
wrong results could be returned.
|
wrong results could be returned.
|
||||||
|
|
||||||
Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
|
Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
|
||||||
|
|
Loading…
Reference in New Issue