LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

perf_event_open.2: Remove unneeded blank lines 

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Denys Vlasenko 2013-02-25 06:36:49 +01:00 committed by Michael Kerrisk
parent ad73a2ccc9
commit 0ee9322e58
1 changed files with 0 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
man2/perf_event_open.2
View File

@ -337,7 +337,6 @@ of
and
.I sample_stack_user
in Linux 3.7.
.TP
.I "config"
This specifies which event you want, in conjunction with
@ -606,8 +605,6 @@ The kernel will adjust the sampling period
to try and achieve the desired rate.
The rate of adjustment is a
timer tick.
.TP
.I "sample_type"
The various bits in this field specify which values to include
@ -670,7 +667,6 @@ Records the current register state.
.BR PERF_SAMPLE_STACK_USER " (Since Linux 3.7)"
[To be documented]
.RE
.TP
.IR "read_format"
This field specifies the format of the data returned by
@ -700,7 +696,6 @@ Adds a 64-bit unique value that corresponds to the event group.
.B PERF_FORMAT_GROUP
Allows all counter values in an event group to be read with one read.
.RE
.TP
.IR "disabled"
The
@ -711,7 +706,6 @@ If disabled, the event can later be enabled by
.BR prctl (2),
or
.IR enable_on_exec .
.TP
.IR "inherit"
The
@ -726,7 +720,6 @@ Inherit does not work for some combinations of
.IR read_format s,
such as
.BR PERF_FORMAT_GROUP .
.TP
.IR "pinned"
The
@ -740,7 +733,6 @@ event), then the counter goes into an 'error' state, where reads
return end-of-file (i.e.,
.BR read (2)
returns 0) until the counter is subsequently enabled or disabled.
.TP
.IR "exclusive"
The
@ -750,15 +742,12 @@ it should be the only group using the CPU's counters.
In the future this may allow monitoring programs to
support PMU features that need to run alone so that they do not
disrupt other hardware counters.
.TP
.IR "exclude_user"
If this bit is set, the count excludes events that happen in user space.
.TP
.IR "exclude_kernel"
If this bit is set, the count excludes events that happen in kernel-space.
.TP
.IR "exclude_hv"
If this bit is set, the count excludes events that happen in the
@ -767,17 +756,14 @@ This is mainly for PMUs that have built-in support for handling this
(such as POWER).
Extra support is needed for handling hypervisor measurements on most
machines.
.TP
.IR "exclude_idle"
If set, don't count when the CPU is idle.
.TP
.IR "mmap"
The
.I mmap
bit enables recording of exec mmap events.
.TP
.IR "comm"
The
@ -789,7 +775,6 @@ and
system calls.
Unfortunately for tools,
there is no way to distinguish one system call versus the other.
.TP
.IR "freq"
If this bit is set, then
@ -797,7 +782,6 @@ If this bit is set, then
not
.I sample_period
is used when setting up the sampling interval.
.TP
.IR "inherit_stat"
This bit enables saving of event counts on context switch for
@ -805,18 +789,15 @@ inherited tasks.
This is only meaningful if the
.I inherit
field is set.
.TP
.IR "enable_on_exec"
If this bit is set, a counter is automatically
enabled after a call to
.BR exec (2).
.TP
.IR "task"
If this bit is set, then
fork/exit notifications are included in the ring buffer.
.TP
.IR "watermark"
If set, have a sampling interrupt happen when we cross the
@ -825,7 +806,6 @@ boundary.
Otherwise interrupts happen after
.I wakeup_events
samples.
.TP
.IR "precise_ip" " (Since Linux 2.6.35)"
This controls the amount of skid.
@ -858,14 +838,12 @@ must have 0 skid.
See also
.BR PERF_RECORD_MISC_EXACT_IP .
.RE
.TP
.IR "mmap_data" " (Since Linux 2.6.36)"
The counterpart of the
.I mmap
field, but enables including data mmap events
in the ring-buffer.
.TP
.IR "sample_id_all" " (Since Linux 2.6.38)"
If set, then TID, TIME, ID, CPU, and STREAM_ID can
@ -874,23 +852,18 @@ additionally be included in
if the corresponding
.I sample_type
is selected.
.TP
.IR "exclude_host" " (Since Linux 3.2)"
Do not measure time spent in VM host
.TP
.IR "exclude_guest" " (Since Linux 3.2)"
Do not measure time spent in VM guest
.TP
.IR "exclude_callchain_kernel" " (Since Linux 3.7)"
Do not include kernel callchains.
.TP
.IR "exclude_callchain_user" " (Since Linux 3.7)"
Do not include user callchains.
.TP
.IR "wakeup_events" ", " "wakeup_watermark"
This union sets how many samples
@ -901,7 +874,6 @@ happen before an overflow signal happens.
Which one is used is selected by the
.I watermark
bitflag.
.TP
.IR "bp_type" " (Since Linux 2.6.33)"
This chooses the breakpoint type.
@ -922,7 +894,6 @@ count when we read or write the memory location
.TP
.BR HW_BREAKPOINT_X
count when we execute code at the memory location
.LP
The values can be combined via a bitwise or, but the
combination of
@ -933,7 +904,6 @@ with
.B HW_BREAKPOINT_X
is not allowed.
.RE
.TP
.IR "bp_addr" " (Since Linux 2.6.33)"
.I bp_addr
@ -941,7 +911,6 @@ address of the breakpoint.
For execution breakpoints this is the memory address of the instruction
of interest; for read and write breakpoints it is the memory address
of the memory location of interest.
.TP
.IR "config1" " (Since Linux 2.6.39)"
.I config1
@ -949,7 +918,6 @@ is used for setting events that need an extra register or otherwise
do not fit in the regular config field.
Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
on 3.3 and later kernels.
.TP
.IR "bp_len" " (Since Linux 2.6.33)"
.I bp_len
@ -964,7 +932,6 @@ Options are
.BR HW_BREAKPOINT_LEN_8 .
For an execution breakpoint, set this to
.IR sizeof(long) .
.TP
.IR "config2" " (Since Linux 2.6.39)"
@ -972,7 +939,6 @@ For an execution breakpoint, set this to
is a further extension of the
.I config1
field.
.TP
.IR "branch_sample_type" " (Since Linux 3.4)"
This is used with the CPUs hardware branch sampling, if available.
@ -1003,20 +969,16 @@ Indirect calls
.BR PERF_SAMPLE_BRANCH_PLM_ALL
User, kernel, and hv
.RE
.TP
.IR "sample_regs_user" " (Since Linux 3.7)"
This defines the set of user registers to dump on samples.
See
.\" FIXME: The following reference seems to be not quite right:
.IR asm/perf_regs.h .
.TP
.IR "sample_stack_user" " (Since Linux 3.7)"
This defines the size of the user stack to dump on samples.
.RE
.SS Reading results
Once a
.BR perf_event_open ()
@ -1078,7 +1040,6 @@ The number of events in this file descriptor.
Only available if
.B PERF_FORMAT_GROUP
was specified.
.TP
.IR time_enabled ", " time_running
Total time the event was enabled and running.
@ -1091,24 +1052,17 @@ In that case the
and
.I time running
values can be used to scale an estimated value for the count.
.TP
.I value
An unsigned 64-bit value containing the counter result.
.TP
.I id
A globally unique value for this particular event, only there if
.B PERF_FORMAT_ID
was specified in read_format.
.RE
.RE
.SS MMAP layout
When using
.BR perf_event_open ()
in sampled mode, asynchronous events
@ -1163,40 +1117,31 @@ The following looks at the fields in the
structure in more detail.
.RS 4
.TP
.I version
Version number of this structure.
.TP
.I compat_version
The lowest version this is compatible with.
.TP
.I lock
A seqlock for synchronization.
.TP
.I index
A unique hardware counter identifier.
.TP
.I offset
.\" FIXME clarify
Add this to hardware counter value??
.TP
.I time_enabled
Time the event was active.
.TP
.I time_running
Time the event was running.
.TP
.I cap_usr_time
User time capability
.TP
.I cap_usr_rdpmc
If the hardware supports user-space read of performance counters
@ -1235,9 +1180,6 @@ do {
} while (pc\->lock != seq);
.fi
.in
.TP
.I pmc_width
If
@ -1253,8 +1195,6 @@ pmc >>= 64 \- pmc_width; // signed shift right
count += pmc;
.fi
.in
.TP
.IR time_shift ", " time_mult ", " time_offset
@ -1291,7 +1231,6 @@ enabled and possible running (if idx), improving the scaling:
rem = count % running;
count = quot * enabled + (rem * enabled) / running;
.fi
.TP
.I data_head
This points to the head of the data section.
@ -1301,7 +1240,6 @@ before accessing the samples.
On SMP-capable platforms, after reading the data_head value,
user space should issue an rmb().
.TP
.I data_tail;
When the mapping is
@ -1310,10 +1248,7 @@ the
.I data_tail
value should be written by user space to reflect the last read data.
In this case the kernel will not over-write unread data.
.RE
The following 2^n ring-buffer pages have the layout described below.
If
@ -1345,7 +1280,6 @@ struct perf_event_header {
Below, we describe the
.I perf_event_header
fields in more detail.
.TP
.I type
The
@ -1355,7 +1289,6 @@ The values in the corresponding record (that follows the header)
depend on the
.I type
selected as shown.
.RS
.TP 4
.B PERF_RECORD_MMAP
@ -1377,7 +1310,6 @@ struct {
};
.fi
.in
.TP
.B PERF_RECORD_LOST
This record indicates when events are lost.
@ -1391,7 +1323,6 @@ struct {
};
.fi
.in
.RS
.TP
.I id
@ -1400,7 +1331,6 @@ is the unique event ID for the samples that were lost.
.I lost
is the number of events that were lost.
.RE
.TP
.B PERF_RECORD_COMM
This record indicates a change in the process name.
@ -1414,7 +1344,6 @@ struct {
};
.fi
.in
.TP
.B PERF_RECORD_EXIT
This record indicates a process exit event.
@ -1429,7 +1358,6 @@ struct {
};
.fi
.in
.TP
.BR PERF_RECORD_THROTTLE ", " PERF_RECORD_UNTHROTTLE
This record indicates a throttle/unthrottle event.
@ -1444,7 +1372,6 @@ struct {
};
.fi
.in
.TP
.B PERF_RECORD_FORK
This record indicates a fork event.
@ -1459,7 +1386,6 @@ struct {
};
.fi
.in
.TP
.B PERF_RECORD_READ
This record indicates a read event.
@ -1473,7 +1399,6 @@ struct {
};
.fi
.in
.TP
.B PERF_RECORD_SAMPLE
This record indicates a sample.
@ -1506,7 +1431,6 @@ struct {
u64 dyn_size; /* if PERF_SAMPLE_STACK_USER */
};
.fi
.RS
.TP
.I ip
@ -1514,14 +1438,12 @@ If
.B PERF_SAMPLE_IP
is enabled, then a 64-bit instruction
pointer value is included.
.TP
.IR pid ", " tid
If
.B PERF_SAMPLE_TID
is enabled, then a 32-bit process ID
and 32-bit thread ID are included.
.TP
.I time
If
@ -1530,7 +1452,6 @@ is enabled, then a 64-bit timestamp
is included.
This is obtained via local_clock() which is a hardware timestamp
if available and the jiffies value if not.
.TP
.I addr
If
@ -1538,7 +1459,6 @@ If
is enabled, then a 64-bit address is included.
This is usually the address of a tracepoint,
breakpoint, or software event; otherwise the value is 0.
.TP
.I id
If
@ -1547,7 +1467,6 @@ is enabled, a 64-bit unique ID is included.
If the event is a member of an event group, the group leader ID is returned.
This ID is the same as the one returned by
.BR PERF_FORMAT_ID .
.TP
.I stream_id
If
@ -1558,7 +1477,6 @@ Unlike
the actual ID is returned, not the group leader.
This ID is the same as the one returned by
.BR PERF_FORMAT_ID .
.TP
.IR cpu ", " res
If
@ -1566,14 +1484,12 @@ If
is enabled, this is a 32-bit value indicating
which CPU was being used, in addition to a reserved (unused)
32-bit value.
.TP
.I period
If
.B PERF_SAMPLE_PERIOD
is enabled, a 64-bit value indicating
the current sampling period is written.
.TP
.I v
If
@ -1585,7 +1501,6 @@ The values included depend on the
value used at
.BR perf_event_open ()
time.
.TP
.IR nr ", " ips[nr]
If
@ -1594,7 +1509,6 @@ is enabled, then a 64-bit number is included
which indicates how many following 64-bit instruction pointers will
follow.
This is the current callchain.
.TP
.IR size ", " data[size]
If
@ -1607,7 +1521,6 @@ This RAW record data is opaque with respect to the ABI.
The ABI doesn't make any promises with respect to the stability
of its content, it may vary depending
on event, hardware, and kernel version.
.TP
.IR bnr ", " lbr[bnr]
If
@ -1619,7 +1532,6 @@ the number of records is included, followed by
structures.
These structures have from, to, and flags values indicating
the from and to addresses from the branches on the callstack.
.TP
.IR abi ", " regs[weight(mask)]
If
@ -1632,19 +1544,14 @@ The
field is one of
.BR PERF_SAMPLE_REGS_ABI_NONE ", " PERF_SAMPLE_REGS_ABI_32 " or "
.BR PERF_SAMPLE_REGS_ABI_64 .
.TP
.IR size ", " data[size] ", " dyn_size
If
.B PERF_SAMPLE_STACK_USER
is enabled, then
[to be documented].
.RE
.RE
.TP
.I misc
The
@ -1686,21 +1593,15 @@ points
to the actual instruction that triggered the event.
See also
.IR perf_event_attr.precise_ip .
.TP
.B PERF_RECORD_MISC_EXT_RESERVED
This indicates there is extended data available (currently not used).
.RE
.TP
.I size
This indicates the size of the record.
.RE
.SS Signal overflow
Events can be set to deliver a signal when a threshold is crossed.
The signal handler is set up using the
.BR poll (2),
@ -1743,7 +1644,6 @@ Note: on newer kernels (definitely noticed with 3.2)
a signal is provided for every overflow, even if
.I wakeup_events
is not set.
.SS rdpmc instruction
Starting with Linux 3.4 on x86, you can use the
.I rdpmc
@ -1756,20 +1656,17 @@ Support for this can be detected with the
.I cap_usr_rdpmc
field in the mmap page; documentation on how
to calculate event values can be found in that section.
.SS perf_event ioctl calls
.PP
Various ioctls act on
.BR perf_event_open ()
file descriptors
.TP
.B PERF_EVENT_IOC_ENABLE
Enables the individual event or event group specified by the
file descriptor argument.
The ioctl argument is ignored.
.TP
.B PERF_EVENT_IOC_DISABLE
Disables the individual counter or event group specified by the
@ -1783,7 +1680,6 @@ affects that counter; disabling a non-leader
stops that counter from counting but doesn't affect any other counter.
The ioctl argument is ignored.
.TP
.B PERF_EVENT_IOC_REFRESH
Non-inherited overflow counters can use this
@ -1798,7 +1694,6 @@ count reaches 0; when that happens a signal with
POLL_HUP
set is sent and the event is disabled.
Using an argument of 0 is considered undefined behavior.
.TP
.B PERF_EVENT_IOC_RESET
Reset the event count specified by the
@ -1813,7 +1708,6 @@ When sent to a group leader, only
the leader is reset (child events are not).
The ioctl argument is ignored.
.TP
.B PERF_EVENT_IOC_PERIOD
IOC_PERIOD is the command to update the period; it
@ -1821,7 +1715,6 @@ does not update the current period but instead defers until next.
The argument is a pointer to a 64-bit value containing the
desired new period.
.TP
.B PERF_EVENT_IOC_SET_OUTPUT
This tells the kernel to report event notifications to the specified
@ -1830,13 +1723,11 @@ The file descriptors must all be on the same CPU.
The argument specifies the desired file descriptor, or \-1 if
output should be ignored.
.TP
.BR PERF_EVENT_IOC_SET_FILTER " (Since Linux 2.6.33)"
This adds an ftrace filter to this event.
The argument is a pointer to the desired ftrace filter.
.SS Using prctl
A process can enable or disable all the event groups that are
attached to it using the
@ -1850,12 +1741,9 @@ this process or by another, and does not affect any counters that this
process has created on other processes.
It only enables or disables
the group leaders, not any other members in the groups.
.SS perf_event related configuration files
Files in
.I /proc/sys/kernel/
.RS 4
.TP
.I /proc/sys/kernel/perf_event_paranoid
@ -1876,7 +1764,6 @@ The existence of the
.I perf_event_paranoid
file is the official method for determining if a kernel supports
.BR perf_event_open ().
.TP
.I /proc/sys/kernel/perf_event_max_sample_rate
@ -1886,40 +1773,33 @@ users to sample at a rate that impacts overall machine performance
and potentially lock up the machine.
The default value is
100000 (samples per second).
.TP
.I /proc/sys/kernel/perf_event_mlock_kb
Maximum number of pages an unprivileged user can mlock (2) .
The default is 516 (kB).
.RE
Files in
.I /sys/bus/event_source/devices/
.RS 4
Since Linux 2.6.34 the kernel supports having multiple PMUs
available for monitoring.
Information on how to program these PMUs can be found under
.IR /sys/bus/event_source/devices/ .
Each subdirectory corresponds to a different PMU.
.TP
.I /sys/bus/event_source/devices/*/type
This contains an integer that can be used in the
.I type
field of perf_event_attr to indicate you wish to use this PMU.
.TP
.I /sys/bus/event_source/devices/*/rdpmc
[To be documented]
.TP
.I /sys/bus/event_source/devices/*/format/
This sub-directory contains information on what bits in the
.I config
field of perf_event_attr correspond to.
.TP
.I /sys/bus/event_source/devices/*/events/
This sub-directory contains files with pre-defined events.
@ -1929,14 +1809,10 @@ expressed in terms of the fields found in the
directory.
These are not necessarily complete lists of all events supported by
a PMU, but usually a subset of events deemed useful or interesting.
.TP
.I /sys/bus/event_source/devices/*/uevent
[To be documented]
.RE
.SH RETURN VALUE
.BR perf_event_open ()
returns the new file descriptor, or \-1 if an error occurred
@ -1957,21 +1833,16 @@ Linus did not like this, and this was changed to
.B ENOSPC
is still returned if you try to read results into
too small of a buffer.
.SH VERSION
.BR perf_event_open ()
was introduced in Linux 2.6.31 but was called
.BR perf_counter_open () .
It was renamed in Linux 2.6.32.
.SH CONFORMING TO
This
.BR perf_event_open ()
system call Linux- specific
and should not be used in programs intended to be portable.
.SH NOTES
Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
@ -1982,9 +1853,7 @@ The official way of knowing if
support is enabled is checking
for the existence of the file
.IR /proc/sys/kernel/perf_event_paranoid .
.SH BUGS
The
.B F_SETOWN_EX
option to
@ -2029,7 +1898,6 @@ Always double-check your results!
Various generalized events have had wrong values.
For example, retired branches measured
the wrong thing on AMD machines until Linux 2.6.35.
.SH EXAMPLE
The following is a short example that measures the total
instruction count of a call to
@ -2055,11 +1923,9 @@ perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
return ret;
}
int
main(int argc, char **argv)
{
struct perf_event_attr pe;
long long count;
int fd;
@ -2091,7 +1957,6 @@ main(int argc, char **argv)
close(fd);
}
.fi
.SH SEE ALSO
.BR fcntl (2),
.BR mmap (2),