Re: [PATCH] perf_event_open.2: srcfix

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Alex,

On 11/13/20 9:34 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
> 
> Hi Michael,
> 
> Here are a few srcfixes I found.
> And an unnecessary parentheses removal in an example.

Thanks. Applied.

Cheers,

Michael

>  man2/perf_event_open.2 | 215 +++++++++++++++++++++++------------------
>  1 file changed, 122 insertions(+), 93 deletions(-)
> 
> diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
> index eb7ab29ea..e7b0aa132 100644
> --- a/man2/perf_event_open.2
> +++ b/man2/perf_event_open.2
> @@ -126,7 +126,7 @@ The leader is created first, with
>  The rest of the group members are created with subsequent
>  .BR perf_event_open ()
>  calls with
> -.IR group_fd
> +.I group_fd
>  being set to the file descriptor of the group leader.
>  (A single event on its own is created with
>  .IR group_fd " = \-1"
> @@ -162,7 +162,7 @@ then
>  .TP
>  .BR PERF_FLAG_FD_NO_GROUP
>  This flag tells the event to ignore the
> -.IR group_fd
> +.I group_fd
>  parameter except for the purpose of setting up output redirection
>  using the
>  .B PERF_FLAG_FD_OUTPUT
> @@ -352,7 +352,11 @@ 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
> +.IR kprobe_func ,
> +.IR uprobe_path ,
> +.IR kprobe_addr ,
> +and
> +.I probe_offset
>  for more details.
>  .RE
>  .TP
> @@ -401,7 +405,9 @@ the
>  .I type
>  field.
>  The
> -.IR config1 " and " config2
> +.I config1
> +and
> +.I config2
>  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.
> @@ -558,15 +564,15 @@ then we are measuring a hardware CPU cache event.
>  To calculate the appropriate
>  .I config
>  value use the following equation:
> -.PP
> -.RS 4
>  .RS 4
> +.PP
> +.in +4n
>  .EX
>  config = (perf_hw_cache_id) |
>           (perf_hw_cache_op_id << 8) |
>           (perf_hw_cache_op_result_id << 16);
>  .EE
> -.RE
> +.in
>  .PP
>  where
>  .I perf_hw_cache_id
> @@ -652,24 +658,28 @@ Its parameters are set in other places.
>  If
>  .I type
>  is
> -.BR kprobe
> +.B kprobe
>  or
>  .BR uprobe ,
>  set
> -.IR retprobe
> +.I 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
> +.IR kprobe_func ,
> +.IR uprobe_path ,
> +.IR kprobe_addr ,
> +and
> +.I 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
> +.B kprobe
>  and
>  .BR uprobe .
>  For
> @@ -712,7 +722,7 @@ to try and achieve the desired rate.
>  The rate of adjustment is a
>  timer tick.
>  .TP
> -.I "sample_type"
> +.I sample_type
>  The various bits in this field specify which values to include
>  in the sample.
>  They will be recorded in a ring-buffer,
> @@ -859,7 +869,7 @@ hardware at the time of the sampled
>  instruction's retirement.
>  .RE
>  .TP
> -.IR "read_format"
> +.I read_format
>  This field specifies the format of the data returned by
>  .BR read (2)
>  on a
> @@ -888,7 +898,7 @@ Adds a 64-bit unique value that corresponds to the event group.
>  Allows all counter values in an event group to be read with one read.
>  .RE
>  .TP
> -.IR "disabled"
> +.I disabled
>  The
>  .I disabled
>  bit specifies whether the counter starts out disabled or enabled.
> @@ -909,7 +919,7 @@ Despite
>  being 0, the child events will not start until the group leader
>  is enabled.
>  .TP
> -.IR "inherit"
> +.I inherit
>  The
>  .I inherit
>  bit specifies that this counter should count events of child
> @@ -923,7 +933,7 @@ Inherit does not work for some combinations of
>  values, such as
>  .BR PERF_FORMAT_GROUP .
>  .TP
> -.IR "pinned"
> +.I pinned
>  The
>  .I pinned
>  bit specifies that the counter should always be on the CPU if at all
> @@ -936,7 +946,7 @@ return end-of-file (i.e.,
>  .BR read (2)
>  returns 0) until the counter is subsequently enabled or disabled.
>  .TP
> -.IR "exclusive"
> +.I exclusive
>  The
>  .I exclusive
>  bit specifies that when this counter's group is on the CPU,
> @@ -952,13 +962,13 @@ This includes any users running a system-wide
>  measurement as well as any kernel use of the performance counters
>  (including the commonly enabled NMI Watchdog Timer interface).
>  .TP
> -.IR "exclude_user"
> +.I exclude_user
>  If this bit is set, the count excludes events that happen in user space.
>  .TP
> -.IR "exclude_kernel"
> +.I exclude_kernel
>  If this bit is set, the count excludes events that happen in kernel space.
>  .TP
> -.IR "exclude_hv"
> +.I exclude_hv
>  If this bit is set, the count excludes events that happen in the
>  hypervisor.
>  This is mainly for PMUs that have built-in support for handling this
> @@ -966,12 +976,12 @@ This is mainly for PMUs that have built-in support for handling this
>  Extra support is needed for handling hypervisor measurements on most
>  machines.
>  .TP
> -.IR "exclude_idle"
> +.I exclude_idle
>  If set, don't count when the CPU is running the idle task.
>  While you can currently enable this for any event type, it is ignored
>  for all but software events.
>  .TP
> -.IR "mmap"
> +.I mmap
>  The
>  .I mmap
>  bit enables generation of
> @@ -985,7 +995,7 @@ This allows tools to notice new executable code being mapped into
>  a program (dynamic shared libraries for example)
>  so that addresses can be mapped back to the original code.
>  .TP
> -.IR "comm"
> +.I comm
>  The
>  .I comm
>  bit enables tracking of process command name as modified by the
> @@ -1004,30 +1014,30 @@ can be used to differentiate the
>  .BR exec (2)
>  case from the others.
>  .TP
> -.IR "freq"
> +.I freq
>  If this bit is set, then
>  .I sample_frequency
>  not
>  .I sample_period
>  is used when setting up the sampling interval.
>  .TP
> -.IR "inherit_stat"
> +.I inherit_stat
>  This bit enables saving of event counts on context switch for
>  inherited tasks.
>  This is meaningful only if the
>  .I inherit
>  field is set.
>  .TP
> -.IR "enable_on_exec"
> +.I enable_on_exec
>  If this bit is set, a counter is automatically
>  enabled after a call to
>  .BR exec (2).
>  .TP
> -.IR "task"
> +.I task
>  If this bit is set, then
>  fork/exit notifications are included in the ring buffer.
>  .TP
> -.IR "watermark"
> +.I watermark
>  If set, have an overflow notification happen when we cross the
>  .I wakeup_watermark
>  boundary.
> @@ -1035,7 +1045,7 @@ Otherwise, overflow notifications happen after
>  .I wakeup_events
>  samples.
>  .TP
> -.IR "precise_ip" " (since Linux 2.6.35)"
> +.IR precise_ip " (since Linux 2.6.35)"
>  .\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076
>  This controls the amount of skid.
>  Skid is how many instructions
> @@ -1064,7 +1074,7 @@ See also the description of
>  .BR PERF_RECORD_MISC_EXACT_IP .
>  .RE
>  .TP
> -.IR "mmap_data" " (since Linux 2.6.36)"
> +.IR mmap_data " (since Linux 2.6.36)"
>  .\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e
>  This is the counterpart of the
>  .I mmap
> @@ -1077,7 +1087,7 @@ calls that do not have
>  .B PROT_EXEC
>  set (for example data and SysV shared memory).
>  .TP
> -.IR "sample_id_all" " (since Linux 2.6.38)"
> +.IR sample_id_all " (since Linux 2.6.38)"
>  .\" commit c980d1091810df13f21aabbce545fd98f545bbf7
>  If set, then TID, TIME, ID, STREAM_ID, and CPU can
>  additionally be included in
> @@ -1109,7 +1119,7 @@ struct sample_id {
>  .EE
>  .in
>  .TP
> -.IR "exclude_host" " (since Linux 3.2)"
> +.IR exclude_host " (since Linux 3.2)"
>  .\" commit a240f76165e6255384d4bdb8139895fac7988799
>  When conducting measurements that include processes running
>  VM instances (i.e., have executed a
> @@ -1120,7 +1130,7 @@ This is only meaningful outside the guests; this setting does
>  not change counts gathered inside of a guest.
>  Currently, this functionality is x86 only.
>  .TP
> -.IR "exclude_guest" " (since Linux 3.2)"
> +.IR exclude_guest " (since Linux 3.2)"
>  .\" commit a240f76165e6255384d4bdb8139895fac7988799
>  When conducting measurements that include processes running
>  VM instances (i.e., have executed a
> @@ -1131,15 +1141,15 @@ This is only meaningful outside the guests; this setting does
>  not change counts gathered inside of a guest.
>  Currently, this functionality is x86 only.
>  .TP
> -.IR "exclude_callchain_kernel" " (since Linux 3.7)"
> +.IR exclude_callchain_kernel " (since Linux 3.7)"
>  .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
>  Do not include kernel callchains.
>  .TP
> -.IR "exclude_callchain_user" " (since Linux 3.7)"
> +.IR exclude_callchain_user " (since Linux 3.7)"
>  .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
>  Do not include user callchains.
>  .TP
> -.IR "mmap2" " (since Linux 3.16)"
> +.IR mmap2 " (since Linux 3.16)"
>  .\" commit 13d7a2410fa637f450a29ecb515ac318ee40c741
>  .\" This is tricky; was committed during 3.12 development
>  .\" but right before release was disabled.
> @@ -1152,7 +1162,7 @@ The
>  .I mmap
>  flag must also be set for this to work.
>  .TP
> -.IR "comm_exec" " (since Linux 3.16)"
> +.IR comm_exec " (since Linux 3.16)"
>  .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
>  This is purely a feature-detection flag, it does not change
>  kernel behavior.
> @@ -1168,7 +1178,7 @@ reported was caused by a call to
>  This allows tools to distinguish between the various
>  types of process renaming.
>  .TP
> -.IR "use_clockid" " (since Linux 4.1)"
> +.IR use_clockid " (since Linux 4.1)"
>  .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
>  This allows selecting which internal Linux clock to use
>  when generating timestamps via the
> @@ -1177,7 +1187,7 @@ field.
>  This can make it easier to correlate perf sample times with
>  timestamps generated by other tools.
>  .TP
> -.IR "context_switch" " (since Linux 4.3)"
> +.IR context_switch " (since Linux 4.3)"
>  .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
>  This enables the generation of
>  .B PERF_RECORD_SWITCH
> @@ -1192,7 +1202,7 @@ information even with strict
>  .I perf_event_paranoid
>  settings.
>  .TP
> -.IR "wakeup_events" ", " "wakeup_watermark"
> +.IR wakeup_events ", " wakeup_watermark
>  This union sets how many samples
>  .RI ( wakeup_events )
>  or bytes
> @@ -1218,25 +1228,25 @@ Prior to Linux 3.0, setting
>  to 0 resulted in no overflow notifications;
>  more recent kernels treat 0 the same as 1.
>  .TP
> -.IR "bp_type" " (since Linux 2.6.33)"
> +.IR bp_type " (since Linux 2.6.33)"
>  .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
>  This chooses the breakpoint type.
>  It is one of:
>  .RS
>  .TP
> -.BR HW_BREAKPOINT_EMPTY
> +.B HW_BREAKPOINT_EMPTY
>  No breakpoint.
>  .TP
> -.BR HW_BREAKPOINT_R
> +.B HW_BREAKPOINT_R
>  Count when we read the memory location.
>  .TP
> -.BR HW_BREAKPOINT_W
> +.B HW_BREAKPOINT_W
>  Count when we write the memory location.
>  .TP
> -.BR HW_BREAKPOINT_RW
> +.B HW_BREAKPOINT_RW
>  Count when we read or write the memory location.
>  .TP
> -.BR HW_BREAKPOINT_X
> +.B HW_BREAKPOINT_X
>  Count when we execute code at the memory location.
>  .PP
>  The values can be combined via a bitwise or, but the
> @@ -1249,14 +1259,14 @@ with
>  is not allowed.
>  .RE
>  .TP
> -.IR "bp_addr" " (since Linux 2.6.33)"
> +.IR bp_addr " (since Linux 2.6.33)"
>  .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
>  This is the address of the breakpoint.
>  For execution breakpoints, this is the memory address of the instruction
>  of interest; for read and write breakpoints, it is the memory address
>  of the memory location of interest.
>  .TP
> -.IR "config1" " (since Linux 2.6.39)"
> +.IR config1 " (since Linux 2.6.39)"
>  .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
>  .I config1
>  is used for setting events that need an extra register or otherwise
> @@ -1264,7 +1274,7 @@ do not fit in the regular config field.
>  Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
>  on Linux 3.3 and later kernels.
>  .TP
> -.IR "bp_len" " (since Linux 2.6.33)"
> +.IR bp_len " (since Linux 2.6.33)"
>  .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
>  .I bp_len
>  is the length of the breakpoint being measured if
> @@ -1280,14 +1290,14 @@ and
>  For an execution breakpoint, set this to
>  .IR sizeof(long) .
>  .TP
> -.IR "config2" " (since Linux 2.6.39)"
> +.IR config2 " (since Linux 2.6.39)"
>  .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
>  .I config2
>  is a further extension of the
>  .I config1
>  field.
>  .TP
> -.IR "branch_sample_type" " (since Linux 3.4)"
> +.IR branch_sample_type " (since Linux 3.4)"
>  .\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
>  If
>  .B PERF_SAMPLE_BRANCH_STACK
> @@ -1358,20 +1368,20 @@ This requires hardware support, currently only found
>  on Intel x86 Haswell or newer.
>  .RE
>  .TP
> -.IR "sample_regs_user" " (since Linux 3.7)"
> +.IR sample_regs_user " (since Linux 3.7)"
>  .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
>  This bit mask defines the set of user CPU registers to dump on samples.
>  The layout of the register mask is architecture-specific and
>  is described in the kernel header file
>  .IR arch/ARCH/include/uapi/asm/perf_regs.h .
>  .TP
> -.IR "sample_stack_user" " (since Linux 3.7)"
> +.IR sample_stack_user " (since Linux 3.7)"
>  .\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
>  This defines the size of the user stack to dump if
>  .B PERF_SAMPLE_STACK_USER
>  is specified.
>  .TP
> -.IR "clockid" " (since Linux 4.1)"
> +.IR clockid " (since Linux 4.1)"
>  .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
>  If
>  .I use_clockid
> @@ -1388,13 +1398,13 @@ and
>  .B CLOCK_TAI
>  currently supported.
>  .TP
> -.IR "aux_watermark" " (since Linux 4.1)"
> +.IR aux_watermark " (since Linux 4.1)"
>  .\" commit 1a5941312414c71dece6717da9a0fa1303127afa
>  This specifies how much data is required to trigger a
>  .B PERF_RECORD_AUX
>  sample.
>  .TP
> -.IR "sample_max_stack" " (since Linux 4.8)"
> +.IR sample_max_stack " (since Linux 4.8)"
>  .\" commit 97c79a38cd454602645f0470ffb444b3b75ce574
>  When
>  .I sample_type
> @@ -1682,34 +1692,39 @@ delta since
>  .I time_enabled
>  (in nanoseconds) using rdtsc or similar.
>  .IP
> -.nf
> -    u64 quot, rem;
> -    u64 delta;
> -    quot = (cyc >> time_shift);
> -    rem = cyc & (((u64)1 << time_shift) \- 1);
> -    delta = time_offset + quot * time_mult +
> -            ((rem * time_mult) >> time_shift);
> -.fi
> +.in +4n
> +.EX
> +u64 quot, rem;
> +u64 delta;
> +
> +quot  = cyc >> time_shift;
> +rem   = cyc & (((u64)1 << time_shift) \- 1);
> +delta = time_offset + quot * time_mult +
> +        ((rem * time_mult) >> time_shift);
> +.EE
> +.in
>  .IP
>  Where
>  .IR time_offset ,
>  .IR time_mult ,
>  .IR time_shift ,
>  and
> -.IR cyc
> +.I cyc
>  are read in the
>  seqcount loop described above.
>  This delta can then be added to
>  enabled and possible running (if idx), improving the scaling:
>  .IP
> -.nf
> -    enabled += delta;
> -    if (idx)
> -        running += delta;
> -    quot = count / running;
> -    rem  = count % running;
> -    count = quot * enabled + (rem * enabled) / running;
> -.fi
> +.in +4n
> +.EX
> +enabled += delta;
> +if (idx)
> +    running += delta;
> +quot  = count / running;
> +rem   = count % running;
> +count = quot * enabled + (rem * enabled) / running;
> +.EE
> +.in
>  .TP
>  .IR time_zero " (since Linux 3.12)"
>  .\" commit fa7315871046b9a4c48627905691dbde57e51033
> @@ -1718,23 +1733,31 @@ If
>  .I cap_usr_time_zero
>  is set, then the hardware clock (the TSC timestamp counter on x86)
>  can be calculated from the
> -.IR time_zero ", " time_mult ", and " time_shift " values:"
> +.IR time_zero ,
> +.IR time_mult ,
> +and
> +.I time_shift
> +values:
>  .IP
> -.nf
> -    time = timestamp - time_zero;
> -    quot = time / time_mult;
> -    rem  = time % time_mult;
> -    cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
> -.fi
> +.in +4n
> +.EX
> +time = timestamp - time_zero;
> +quot = time / time_mult;
> +rem  = time % time_mult;
> +cyc  = (quot << time_shift) + (rem << time_shift) / time_mult;
> +.EE
> +.in
>  .IP
>  And vice versa:
>  .IP
> -.nf
> -    quot = cyc >> time_shift;
> -    rem  = cyc & (((u64)1 << time_shift) - 1);
> -    timestamp = time_zero + quot * time_mult +
> -        ((rem * time_mult) >> time_shift);
> -.fi
> +.in +4n
> +.EX
> +quot = cyc >> time_shift;
> +rem  = cyc & (((u64)1 << time_shift) - 1);
> +timestamp = time_zero + quot * time_mult +
> +            ((rem * time_mult) >> time_shift);
> +.EE
> +.in
>  .TP
>  .I data_head
>  This points to the head of the data section.
> @@ -1785,7 +1808,7 @@ The desired offset and size must be page aligned, and the size
>  must be a power of two.
>  These values are then passed to mmap in order to map the AUX buffer.
>  Pages in the AUX buffer are included as part of the
> -.BR RLIMIT_MEMLOCK
> +.B RLIMIT_MEMLOCK
>  resource limit (see
>  .BR setrlimit (2)),
>  and also as part of the
> @@ -1802,10 +1825,14 @@ new data began, and it is the consumer's job to disable
>  measurement while reading to avoid possible data races.
>  .IP
>  The
> -.IR aux_head " and " aux_tail
> +.I aux_head
> +and
> +.I aux_tail
>  ring buffer pointers have the same behavior and ordering
>  rules as the previous described
> -.IR data_head " and " data_tail .
> +.I data_head
> +and
> +.IR data_tail .
>  .PP
>  The following 2^n ring-buffer pages have the layout described below.
>  .PP
> @@ -1897,9 +1924,9 @@ system call.
>  .BR PERF_RECORD_MISC_SWITCH_OUT " (since Linux 4.3)"
>  .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
>  When a
> -.BR PERF_RECORD_SWITCH
> +.B PERF_RECORD_SWITCH
>  or
> -.BR PERF_RECORD_SWITCH_CPU_WIDE
> +.B PERF_RECORD_SWITCH_CPU_WIDE
>  record is generated, this bit indicates that the
>  context switch is away from the current process
>  (instead of into the current process).
> @@ -2267,7 +2294,7 @@ Support for
>  .IR mispred ,
>  .IR predicted ,
>  and
> -.IR cycles
> +.I cycles
>  is optional; if not supported, those
>  values will be 0.
>  .PP
> @@ -2284,7 +2311,9 @@ is enabled, then the user CPU registers are recorded.
>  The
>  .I abi
>  field is one of
> -.BR PERF_SAMPLE_REGS_ABI_NONE ", " PERF_SAMPLE_REGS_ABI_32 " or"
> +.BR PERF_SAMPLE_REGS_ABI_NONE ,
> +.BR PERF_SAMPLE_REGS_ABI_32 ,
> +or
>  .BR PERF_SAMPLE_REGS_ABI_64 .
>  .IP
>  The
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/