From b4bd8040f471c245455a66c32c8979d3262faa2f Mon Sep 17 00:00:00 2001

From: =?UTF-8?q?Nikola=20Forr=C3=B3?= <nforro@redhat.com>

Date: Wed, 22 Aug 2018 11:11:05 +0200

Subject: [PATCH 3/3] perf_event_open.2: sync with upstream

---

 man-pages/man2/perf_event_open.2 | 2448 +++++++++++++++++++++++-------

 1 file changed, 1861 insertions(+), 587 deletions(-)

diff --git a/man-pages/man2/perf_event_open.2 b/man-pages/man2/perf_event_open.2

index 2ab3eb9..0f29d96 100644

--- a/man-pages/man2/perf_event_open.2

+++ b/man-pages/man2/perf_event_open.2

@@ -24,19 +24,19 @@

 .\" This document is based on the perf_event.h header file, the

 .\" tools/perf/design.txt file, and a lot of bitter experience.

 .\"

-.TH PERF_EVENT_OPEN 2 2013-07-16 "Linux" "Linux Programmer's Manual"

+.TH PERF_EVENT_OPEN 2 2018-02-02 "Linux" "Linux Programmer's Manual"

 .SH NAME

 perf_event_open \- set up performance monitoring

 .SH SYNOPSIS

 .nf

 .B #include <linux/perf_event.h>

 .B #include <linux/hw_breakpoint.h>

-.sp

+.PP

 .BI "int perf_event_open(struct perf_event_attr *" attr ,

 .BI "                    pid_t " pid ", int " cpu ", int " group_fd ,

 .BI "                    unsigned long " flags  );

 .fi

-

+.PP

 .IR Note :

 There is no glibc wrapper for this system call; see NOTES.

 .SH DESCRIPTION

@@ -56,7 +56,7 @@ to measure multiple events simultaneously.

 Events can be enabled and disabled in two ways: via

 .BR ioctl (2)

 and via

-.BR prctl (2) .

+.BR prctl (2).

 When an event is disabled it does not count or generate overflows but does

 continue to exist and maintain its count value.

 .PP

@@ -72,58 +72,48 @@ A

 .I sampling

 event periodically writes measurements to a buffer that can then

 be accessed via

-.BR  mmap (2) .

+.BR mmap (2).

 .SS Arguments

-.P

-The argument

-.I pid

-allows events to be attached to processes in various ways.

-If

-.I pid

-is 0, measurements happen on the current thread, if

-.I pid

-is greater than 0, the process indicated by

-.I pid

-is measured, and if

-.I pid

-is \-1, all processes are counted.

-

+.PP

 The

-.I cpu

-argument allows measurements to be specific to a CPU.

-If

-.I cpu

-is greater than or equal to 0,

-measurements are restricted to the specified CPU;

-if

-.I cpu

-is \-1, the events are measured on all CPUs.

-.P

-Note that the combination of

-.IR pid " == \-1"

-and

-.IR cpu " == \-1"

-is not valid.

-.P

-A

-.IR pid " > 0"

-and

-.IR cpu " == \-1"

-setting measures per-process and follows that process to whatever CPU the

-process gets scheduled to.

-Per-process events can be created by any user.

-.P

-A

-.IR pid " == \-1"

+.I pid

 and

-.IR cpu " >= 0"

-setting is per-CPU and measures all processes on the specified CPU.

-Per-CPU events need the

+.I cpu

+arguments allow specifying which process and CPU to monitor:

+.TP

+.BR "pid == 0" " and " "cpu == \-1"

+This measures the calling process/thread on any CPU.

+.TP

+.BR "pid == 0" " and " "cpu >= 0"

+This measures the calling process/thread only

+when running on the specified CPU.

+.TP

+.BR "pid > 0" " and " "cpu == \-1"

+This measures the specified process/thread on any CPU.

+.TP

+.BR "pid > 0" " and " "cpu >= 0"

+This measures the specified process/thread only

+when running on the specified CPU.

+.TP

+.BR "pid == \-1" " and " "cpu >= 0"

+This measures all processes/threads on the specified CPU.

+This requires

 .B CAP_SYS_ADMIN

 capability or a

 .I /proc/sys/kernel/perf_event_paranoid

 value of less than 1.

-.P

+.TP

+.BR "pid == \-1" " and " "cpu == \-1"

+This setting is invalid and will return an error.

+.PP

+When

+.I pid

+is greater than zero, permission to perform this system call

+is governed by a ptrace access mode

+.B PTRACE_MODE_READ_REALCREDS

+check; see

+.BR ptrace (2).

+.PP

 The

 .I group_fd

 argument allows event groups to be created.

@@ -134,7 +124,7 @@ The rest of the group members are created with subsequent

 .BR perf_event_open ()

 calls with

 .IR group_fd

-being set to the fd of the group leader.

+being set to the file descriptor of the group leader.

 (A single event on its own is created with

 .IR group_fd " = \-1"

 and is considered to be a group with only 1 member.)

@@ -142,29 +132,51 @@ 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

 the CPU.

 This means that the values of the member events can be

-meaningfully compared, added, divided (to get ratios), etc., 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

 instructions.

-.P

+.PP

 The

 .I flags

 argument is formed by ORing together zero or more of the following values:

 .TP

+.BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)"

+.\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e

+This flag enables the close-on-exec flag for the created

+event file descriptor,

+so that the file descriptor is automatically closed on

+.BR execve (2).

+Setting the close-on-exec flags at creation time, rather than later with

+.BR fcntl (2),

+avoids potential race conditions where the calling thread invokes

+.BR perf_event_open ()

+and

+.BR fcntl (2)

+at the same time as another thread calls

+.BR fork (2)

+then

+.BR execve (2).

+.TP

 .BR PERF_FLAG_FD_NO_GROUP

-.\" FIXME The following sentence is unclear

-This flag allows creating an event as part of an event group but

-having no group leader.

-It is unclear why this is useful.

-.\" FIXME So, why is it useful?

+This flag tells the event to ignore the

+.IR group_fd

+parameter except for the purpose of setting up output redirection

+using the

+.B PERF_FLAG_FD_OUTPUT

+flag.

 .TP

-.BR PERF_FLAG_FD_OUTPUT

-This flag re-routes the output from an event to the group leader.

+.BR PERF_FLAG_FD_OUTPUT " (broken since Linux 2.6.35)"

+.\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318

+This flag re-routes the event's sampled output to instead

+be included in the mmap buffer of the event specified by

+.IR group_fd .

 .TP

-.BR PERF_FLAG_PID_CGROUP " (Since Linux 2.6.39)."

+.BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)"

+.\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25

 This flag activates per-container system-wide monitoring.

 A container

-is an abstraction that isolates a set of resources for finer grain

-control (CPUs, memory, etc...).

+is an abstraction that isolates a set of resources for finer-grained

+control (CPUs, memory, etc.).

 In this mode, the event is measured

 only if the thread running on the monitored CPU belongs to the designated

 container (cgroup).

@@ -182,52 +194,58 @@ must be passed as the

 parameter.

 cgroup monitoring is available only

 for system-wide events and may therefore require extra permissions.

-.P

+.PP

 The

 .I perf_event_attr

 structure provides detailed configuration information

 for the event being created.

-

+.PP

 .in +4n

-.nf

+.EX

 struct perf_event_attr {

-    __u32     type;         /* Type of event */

-    __u32     size;         /* Size of attribute structure */

-    __u64     config;       /* Type-specific configuration */

+    __u32 type;                 /* Type of event */

+    __u32 size;                 /* Size of attribute structure */

+    __u64 config;               /* Type-specific configuration */

     union {

         __u64 sample_period;    /* Period of sampling */

         __u64 sample_freq;      /* Frequency of sampling */

     };

-    __u64     sample_type;  /* Specifies values included in sample */

-    __u64     read_format;  /* Specifies values returned in read */

-

-    __u64     disabled       : 1,   /* off by default */

-              inherit        : 1,   /* children inherit it */

-              pinned         : 1,   /* must always be on PMU */

-              exclusive      : 1,   /* only group on PMU */

-              exclude_user   : 1,   /* don't count user */

-              exclude_kernel : 1,   /* don't count kernel */

-              exclude_hv     : 1,   /* don't count hypervisor */

-              exclude_idle   : 1,   /* don't count when idle */

-              mmap           : 1,   /* include mmap data */

-              comm           : 1,   /* include comm data */

-              freq           : 1,   /* use freq, not period */

-              inherit_stat   : 1,   /* per task counts */

-              enable_on_exec : 1,   /* next exec enables */

-              task           : 1,   /* trace fork/exit */

-              watermark      : 1,   /* wakeup_watermark */

-              precise_ip     : 2,   /* skid constraint */

-              mmap_data      : 1,   /* non-exec mmap data */

-              sample_id_all  : 1,   /* sample_type all events */

-              exclude_host   : 1,   /* don't count in host */

-              exclude_guest  : 1,   /* don't count in guest */

-              exclude_callchain_kernel : 1,

-                                    /* exclude kernel callchains */

-              exclude_callchain_user   : 1,

-	                            /* exclude user callchains */

-              __reserved_1   : 41;

+    __u64 sample_type;  /* Specifies values included in sample */

+    __u64 read_format;  /* Specifies values returned in read */

+

+    __u64 disabled       : 1,   /* off by default */

+          inherit        : 1,   /* children inherit it */

+          pinned         : 1,   /* must always be on PMU */

+          exclusive      : 1,   /* only group on PMU */

+          exclude_user   : 1,   /* don't count user */

+          exclude_kernel : 1,   /* don't count kernel */

+          exclude_hv     : 1,   /* don't count hypervisor */

+          exclude_idle   : 1,   /* don't count when idle */

+          mmap           : 1,   /* include mmap data */

+          comm           : 1,   /* include comm data */

+          freq           : 1,   /* use freq, not period */

+          inherit_stat   : 1,   /* per task counts */

+          enable_on_exec : 1,   /* next exec enables */

+          task           : 1,   /* trace fork/exit */

+          watermark      : 1,   /* wakeup_watermark */

+          precise_ip     : 2,   /* skid constraint */

+          mmap_data      : 1,   /* non-exec mmap data */

+          sample_id_all  : 1,   /* sample_type all events */

+          exclude_host   : 1,   /* don't count in host */

+          exclude_guest  : 1,   /* don't count in guest */

+          exclude_callchain_kernel : 1,

+                                /* exclude kernel callchains */

+          exclude_callchain_user   : 1,

+                                /* exclude user callchains */

+          mmap2          :  1,  /* include mmap with inode data */

+          comm_exec      :  1,  /* flag comm events that are

+                                   due to exec */

+          use_clockid    :  1,  /* use clockid for time fields */

+          context_switch :  1,  /* context switch data */

+

+          __reserved_1   : 37;

     union {

         __u32 wakeup_events;    /* wakeup every n events */

@@ -238,23 +256,31 @@ struct perf_event_attr {

     union {

         __u64 bp_addr;          /* breakpoint address */

+        __u64 kprobe_func;      /* for perf_kprobe */

+        __u64 uprobe_path;      /* for perf_uprobe */

         __u64 config1;          /* extension of config */

     };

     union {

         __u64 bp_len;           /* breakpoint length */

+        __u64 kprobe_addr;      /* with kprobe_func == NULL */

+        __u64 probe_offset;     /* for perf_[k,u]probe */

         __u64 config2;          /* extension of config1 */

     };

-    __u64   branch_sample_type; /* enum perf_branch_sample_type */

-    __u64   sample_regs_user;   /* user regs to dump on samples */

-    __u32   sample_stack_user;  /* size of stack to dump on

+    __u64 branch_sample_type;   /* enum perf_branch_sample_type */

+    __u64 sample_regs_user;     /* user regs to dump on samples */

+    __u32 sample_stack_user;    /* size of stack to dump on

                                    samples */

-    __u32   __reserved_2;       /* Align to u64 */

+    __s32 clockid;              /* clock to use for time fields */

+    __u64 sample_regs_intr;     /* regs to dump on samples */

+    __u32 aux_watermark;        /* aux bytes before wakeup */

+    __u16 sample_max_stack;     /* max frames in callchain */

+    __u16 __reserved_2;         /* align to u64 */

 };

-.fi

+.EE

 .in

-

+.PP

 The fields of the

 .I perf_event_attr

 structure are described in more detail below:

@@ -289,13 +315,15 @@ field definition.

 This indicates a "raw" implementation-specific event in the

 .IR config " field."

 .TP

-.BR PERF_TYPE_BREAKPOINT " (Since Linux 2.6.33)"

+.BR PERF_TYPE_BREAKPOINT " (since Linux 2.6.33)"

+.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e

 This indicates a hardware breakpoint as provided by the CPU.

 Breakpoints can be read/write accesses to an address as well as

 execution of an instruction address.

 .TP

 .RB "dynamic PMU"

-Since Linux 2.6.39,

+Since Linux 2.6.38,

+.\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19

 .BR perf_event_open ()

 can support multiple PMUs.

 To enable this, a value exported by the kernel can be used in the

@@ -304,7 +332,7 @@ field to indicate which PMU to use.

 The value to use can be found in the sysfs filesystem:

 there is a subdirectory per PMU instance under

 .IR /sys/bus/event_source/devices .

-In each sub-directory there is a

+In each subdirectory there is a

 .I type

 file whose content is an integer that can be used in the

 .I type

@@ -312,6 +340,17 @@ field.

 For instance,

 .I /sys/bus/event_source/devices/cpu/type

 contains the value for the core CPU PMU, which is usually 4.

+.TP

+.BR kprobe " and " uprobe " (since Linux 4.17)"

+.\" commit 65074d43fc77bcae32776724b7fa2696923c78e4

+.\" commit e12f03d7031a977356e3d7b75a68c2185ff8d155

+.\" commit 33ea4b24277b06dbc55d7f5772a46f029600255e

+These two dynamic PMUs create a kprobe/uprobe and attach it to the

+file descriptor generated by perf_event_open.

+The kprobe/uprobe will be destroyed on the destruction of the file descriptor.

+See fields

+.IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset

+for more details.

 .RE

 .TP

 .I "size"

@@ -322,21 +361,36 @@ Set this using

 .I sizeof(struct perf_event_attr)

 to allow the kernel to see

 the struct size at the time of compilation.

-

+.IP

 The related define

 .B PERF_ATTR_SIZE_VER0

 is set to 64; this was the size of the first published struct.

 .B PERF_ATTR_SIZE_VER1

 is 72, corresponding to the addition of breakpoints in Linux 2.6.33.

+.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2

+.\" this was added much later when PERF_ATTR_SIZE_VER2 happened

+.\" but the actual attr_size had increased in 2.6.33

 .B PERF_ATTR_SIZE_VER2

 is 80 corresponding to the addition of branch sampling in Linux 3.4.

-.B PERF_ATR_SIZE_VER3

+.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2

+.B PERF_ATTR_SIZE_VER3

 is 96 corresponding to the addition

 of

 .I sample_regs_user

 and

 .I sample_stack_user

 in Linux 3.7.

+.\" commit 1659d129ed014b715b0b2120e6fd929bdd33ed03

+.B PERF_ATTR_SIZE_VER4

+is 104 corresponding to the addition of

+.I sample_regs_intr

+in Linux 3.19.

+.\" commit 60e2364e60e86e81bc6377f49779779e6120977f

+.B PERF_ATTR_SIZE_VER5

+is 112 corresponding to the addition of

+.I aux_watermark

+in Linux 4.1.

+.\" commit 1a5941312414c71dece6717da9a0fa1303127afa

 .TP

 .I "config"

 This specifies which event you want, in conjunction with

@@ -348,13 +402,7 @@ The

 fields are also taken into account in cases where 64 bits is not

 enough to fully specify the event.

 The encoding of these fields are event dependent.

-

-The most significant bit (bit 63) of

-.I config

-signifies CPU-specific (raw) counter configuration data;

-if the most significant bit is unset, the next 7 bits are an event

-type and the rest of the bits are the event identifier.

-

+.IP

 There are various ways to set the

 .I config

 field that are dependent on the value of the previously

@@ -365,7 +413,7 @@ What follows are various possible settings for

 .I config

 separated out by

 .IR type .

-

+.IP

 If

 .I type

 is

@@ -379,12 +427,12 @@ to one of the following:

 .TP

 .B PERF_COUNT_HW_CPU_CYCLES

 Total cycles.

-Be wary of what happens during CPU frequency scaling

+Be wary of what happens during CPU frequency scaling.

 .TP

 .B PERF_COUNT_HW_INSTRUCTIONS

 Retired instructions.

 Be careful, these can be affected by various

-issues, most notably hardware interrupt counts

+issues, most notably hardware interrupt counts.

 .TP

 .B PERF_COUNT_HW_CACHE_REFERENCES

 Cache accesses.

@@ -402,8 +450,9 @@ event to calculate cache miss rates.

 .TP

 .B PERF_COUNT_HW_BRANCH_INSTRUCTIONS

 Retired branch instructions.

-Prior to Linux 2.6.34, this used

+Prior to Linux 2.6.35, this used

 the wrong event on AMD processors.

+.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2

 .TP

 .B PERF_COUNT_HW_BRANCH_MISSES

 Mispredicted branch instructions.

@@ -411,13 +460,16 @@ Mispredicted branch instructions.

 .B PERF_COUNT_HW_BUS_CYCLES

 Bus cycles, which can be different from total cycles.

 .TP

-.BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (Since Linux 3.0)"

+.BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (since Linux 3.0)"

+.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a

 Stalled cycles during issue.

 .TP

-.BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND  " (Since Linux 3.0)"

+.BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND  " (since Linux 3.0)"

+.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a

 Stalled cycles during retirement.

 .TP

-.BR PERF_COUNT_HW_REF_CPU_CYCLES  " (Since Linux 3.3)"

+.BR PERF_COUNT_HW_REF_CPU_CYCLES  " (since Linux 3.3)"

+.\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890

 Total cycles; not affected by CPU frequency scaling.

 .RE

 .IP

@@ -444,6 +496,7 @@ This reports the number of page faults.

 This counts context switches.

 Until Linux 2.6.34, these were all reported as user-space

 events, after that they are reported as happening in the kernel.

+.\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21

 .TP

 .B PERF_COUNT_SW_CPU_MIGRATIONS

 This reports the number of times the process

@@ -457,19 +510,29 @@ These did not require disk I/O to handle.

 This counts the number of major page faults.

 These required disk I/O to handle.

 .TP

-.BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (Since Linux 2.6.33)"

+.BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (since Linux 2.6.33)"

+.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497

 This counts the number of alignment faults.

 These happen when unaligned memory accesses happen; the kernel

 can handle these but it reduces performance.

 This happens only on some architectures (never on x86).

 .TP

-.BR PERF_COUNT_SW_EMULATION_FAULTS " (Since Linux 2.6.33)"

+.BR PERF_COUNT_SW_EMULATION_FAULTS " (since Linux 2.6.33)"

+.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497

 This counts the number of emulation faults.

 The kernel sometimes traps on unimplemented instructions

 and emulates them for user space.

 This can negatively impact performance.

+.TP

+.BR PERF_COUNT_SW_DUMMY " (since Linux 3.12)"

+.\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77

+This is a placeholder event that counts nothing.

+Informational sample record types such as mmap or comm

+must be associated with an active event.

+This dummy event allows gathering such records without requiring

+a counting event.

 .RE

-

+.PP

 .RS

 If

 .I type

@@ -482,7 +545,7 @@ can be obtained from under debugfs

 .I tracing/events/*/*/id

 if ftrace is enabled in the kernel.

 .RE

-

+.PP

 .RS

 If

 .I type

@@ -492,13 +555,13 @@ then we are measuring a hardware CPU cache event.

 To calculate the appropriate

 .I config

 value use the following equation:

+.PP

 .RS 4

 .nf

-

     (perf_hw_cache_id) | (perf_hw_cache_op_id << 8) |

     (perf_hw_cache_op_result_id << 16)

 .fi

-.P

+.PP

 where

 .I perf_hw_cache_id

 is one of:

@@ -522,13 +585,14 @@ for measuring the Instruction TLB

 .B PERF_COUNT_HW_CACHE_BPU

 for measuring the branch prediction unit

 .TP

-.BR PERF_COUNT_HW_CACHE_NODE " (Since Linux 3.0)"

+.BR PERF_COUNT_HW_CACHE_NODE " (since Linux 3.1)"

+.\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477

 for measuring local memory accesses

 .RE

-.P

+.PP

 and

 .I perf_hw_cache_op_id

-is one of

+is one of:

 .RS 4

 .TP

 .B PERF_COUNT_HW_CACHE_OP_READ

@@ -540,10 +604,10 @@ for write accesses

 .B PERF_COUNT_HW_CACHE_OP_PREFETCH

 for prefetch accesses

 .RE

-.P

+.PP

 and

 .I perf_hw_cache_op_result_id

-is one of

+is one of:

 .RS 4

 .TP

 .B PERF_COUNT_HW_CACHE_RESULT_ACCESS

@@ -553,7 +617,7 @@ to measure accesses

 to measure misses

 .RE

 .RE

-

+.PP

 If

 .I type

 is

@@ -569,7 +633,7 @@ The libpfm4 library can be used to translate from the name in the

 architectural manuals to the raw hex value

 .BR perf_event_open ()

 expects in this field.

-

+.PP

 If

 .I type

 is

@@ -578,23 +642,63 @@ then leave

 .I config

 set to zero.

 Its parameters are set in other places.

+.PP

+If

+.I type

+is

+.BR kprobe

+or

+.BR uprobe ,

+set

+.IR retprobe

+(bit 0 of

+.IR config ,

+see

+.IR /sys/bus/event_source/devices/[k,u]probe/format/retprobe )

+for kretprobe/uretprobe.

+See fields

+.IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset

+for more details.

 .RE

 .TP

+.IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset

+These fields describe the kprobe/uprobe for dynamic PMUs

+.BR kprobe

+and

+.BR uprobe .

+For

+.BR kprobe :

+use

+.I kprobe_func

+and

+.IR probe_offset ,

+or use

+.I kprobe_addr

+and leave

+.I kprobe_func

+as NULL.

+For

+.BR uprobe :

+use

+.I uprobe_path

+and

+.IR probe_offset .

+.TP

 .IR sample_period ", " sample_freq

-A "sampling" counter is one that generates an interrupt

+A "sampling" event is one that generates an overflow notification

 every N events, where N is given by

 .IR sample_period .

-A sampling counter has

+A sampling event has

 .IR sample_period " > 0."

-When an overflow interrupt occurs, requested data is recorded

+When an overflow occurs, requested data is recorded

 in the mmap buffer.

 The

 .I sample_type

-field controls what data is recorded on each interrupt.

-

+field controls what data is recorded on each overflow.

+.IP

 .I sample_freq

 can be used if you wish to use frequency rather than period.

-In this case you set the

+In this case, you set the

 .I freq

 flag.

 The kernel will adjust the sampling period

@@ -647,39 +751,106 @@ Records a unique ID for the opened event.

 Unlike

 .B PERF_SAMPLE_ID

 the actual ID is returned, not the group leader.

-This ID is the same as the one returned by PERF_FORMAT_ID.

+This ID is the same as the one returned by

+.BR PERF_FORMAT_ID .

 .TP

 .B PERF_SAMPLE_RAW

 Records additional data, if applicable.

 Usually returned by tracepoint events.

 .TP

-.BR PERF_SAMPLE_BRANCH_STACK " (Since Linux 3.4)"

+.BR PERF_SAMPLE_BRANCH_STACK " (since Linux 3.4)"

+.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e

 This provides a record of recent branches, as provided

 by CPU branch sampling hardware (such as Intel Last Branch Record).

 Not all hardware supports this feature.

-

+.IP

 See the

 .I branch_sample_type

 field for how to filter which branches are reported.

 .TP

-.BR PERF_SAMPLE_REGS_USER " (Since Linux 3.7)"

+.BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)"

+.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56

 Records the current user-level CPU register state

 (the values in the process before the kernel was called).

 .TP

-.BR PERF_SAMPLE_STACK_USER " (Since Linux 3.7)"

+.BR PERF_SAMPLE_STACK_USER " (since Linux 3.7)"

+.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7

 Records the user level stack, allowing stack unwinding.

 .TP

-.BR PERF_SAMPLE_WEIGHT " (Since Linux 3.10)"

+.BR PERF_SAMPLE_WEIGHT " (since Linux 3.10)"