[PATCH] perf_event_open.2: ffix and tfix

[PATCH] perf_event_open.2: ffix and tfix

[David Prévot]

---
 man2/perf_event_open.2 |  126 ++++++++++++++++++++++++++++--------------------
 1 file changed, 73 insertions(+), 53 deletions(-)

diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index ed468f2..eb989d4 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -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,7 +72,7 @@ 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
@@ -164,7 +164,7 @@ This flag re-routes the output from an event to the group leader.
 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...).
+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).
@@ -226,7 +226,7 @@ struct perf_event_attr {
               exclude_callchain_kernel : 1,
                                     /* exclude kernel callchains */
               exclude_callchain_user   : 1,
-	                            /* exclude user callchains */
+                                    /* exclude user callchains */
               __reserved_1   : 41;
 
     union {
@@ -331,9 +331,9 @@ 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.
 .B PERF_ATTR_SIZE_VER2
-is 80 corresponding to the addition of branch sampling in Linux 3.4.
+is 80, corresponding to the addition of branch sampling in Linux 3.4.
 .B PERF_ATR_SIZE_VER3
-is 96 corresponding to the addition
+is 96, corresponding to the addition
 of sample_regs_user and sample_stack_user in Linux 3.7.
 
 .TP
@@ -378,12 +378,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.
@@ -611,11 +611,11 @@ timer tick.
 .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,
+They will be recorded in a ring buffer,
 which is available to user-space using
 .BR mmap (2).
 The order in which the values are saved in the
-sample are documented in the MMAP Layout subsection below;
+sample is documented in the MMAP Layout subsection below;
 it is not the
 .I "enum perf_event_sample_format"
 order.
@@ -653,7 +653,8 @@ 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.
@@ -661,7 +662,8 @@ Usually returned by tracepoint events.
 .TP
 .BR PERF_SAMPLE_BRANCH_STACK " (Since Linux 3.4)"
 Records the branch stack.
-See branch_sample_type.
+See
+.IR branch_sample_type .
 .TP
 .BR PERF_SAMPLE_REGS_USER " (Since Linux 3.7)"
 Records the current register state.
@@ -778,9 +780,9 @@ bit enables recording of exec mmap events.
 The
 .I comm
 bit enables tracking of process command name as modified by the
-.IR exec (2)
+.BR exec (2)
 and
-.IR prctl (PR_SET_NAME)
+.BR prctl (PR_SET_NAME)
 system calls.
 Unfortunately for tools,
 there is no way to distinguish one system call versus the other.
@@ -859,7 +861,7 @@ See also
 The counterpart of the
 .I mmap
 field, but enables including data mmap events
-in the ring-buffer.
+in the ring buffer.
 
 .TP
 .IR "sample_id_all" " (Since Linux 2.6.38)"
@@ -872,11 +874,11 @@ is selected.
 
 .TP
 .IR "exclude_host" " (Since Linux 3.2)"
-Do not measure time spent in VM host
+Do not measure time spent in VM host.
 
 .TP
 .IR "exclude_guest" " (Since Linux 3.2)"
-Do not measure time spent in VM guest
+Do not measure time spent in VM guest.
 
 .TP
 .IR "exclude_callchain_kernel" " (Since Linux 3.7)"
@@ -932,7 +934,7 @@ is not allowed.
 .TP
 .IR "bp_addr" " (Since Linux 2.6.33)"
 .I bp_addr
-address of the breakpoint.
+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.
@@ -941,7 +943,9 @@ of the memory location of interest.
 .IR "config1" " (Since Linux 2.6.39)"
 .I config1
 is used for setting events that need an extra register or otherwise
-do not fit in the regular config field.
+do not fit in the regular
+.I config
+field.
 Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
 on 3.3 and later kernels.
 
@@ -975,28 +979,28 @@ It can have one of the following values:
 .RS
 .TP
 .B PERF_SAMPLE_BRANCH_USER
-Branch target is in user space
+Branch target is in user space.
 .TP
 .B PERF_SAMPLE_BRANCH_KERNEL
-Branch target is in kernel space
+Branch target is in kernel space.
 .TP
 .B PERF_SAMPLE_BRANCH_HV
-Branch target is in hypervisor
+Branch target is in hypervisor.
 .TP
 .B PERF_SAMPLE_BRANCH_ANY
 Any branch type.
 .TP
 .B PERF_SAMPLE_BRANCH_ANY_CALL
-Any call branch
+Any call branch.
 .TP
 .B PERF_SAMPLE_BRANCH_ANY_RETURN
-Any return branch
+Any return branch.
 .TP
 .BR PERF_SAMPLE_BRANCH_IND_CALL
-Indirect calls
+Indirect calls.
 .TP
 .BR PERF_SAMPLE_BRANCH_PLM_ALL
-User, kernel, and hv
+User, kernel, and hv.
 .RE
 
 .TP
@@ -1026,7 +1030,7 @@ structure at open time.
 If you attempt to read into a buffer that is not big enough to hold the
 data
 .B ENOSPC
-is returned
+is returned.
 
 Here is the layout of the data returned by a read:
 
@@ -1095,7 +1099,8 @@ An unsigned 64-bit value containing the counter result.
 .I id
 A globally unique value for this particular event, only there if
 .B PERF_FORMAT_ID
-was specified in read_format.
+was specified in
+.IR read_format .
 
 .RE
 .RE
@@ -1110,15 +1115,15 @@ in sampled mode, asynchronous events
 (like counter overflow or
 .B PROT_EXEC
 mmap tracking)
-are logged into a ring-buffer.
-This ring-buffer is created and accessed through
+are logged into a ring buffer.
+This ring buffer is created and accessed through
 .BR mmap (2).
 
 The mmap size should be 1+2^n pages, where the first page is a
 metadata page
-.IR ( "struct perf_event_mmap_page" )
+.RI ( "struct perf_event_mmap_page" )
 that contains various
-bits of information such as where the ring-buffer head is.
+bits of information such as where the ring buffer head is.
 
 Before kernel 2.6.39, there is a bug that means you must allocate a mmap
 ring buffer when sampling even if you do not plan to access it.
@@ -1190,7 +1195,7 @@ Time the event was running.
 
 .TP
 .I cap_usr_time
-User time capability
+User time capability.
 
 .TP
 .I cap_usr_rdpmc
@@ -1256,7 +1261,9 @@ count += pmc;
 If
 .IR cap_usr_time ,
 these fields can be used to compute the time
-delta since time_enabled (in nanoseconds) using rdtsc or similar.
+delta since
+.I time_enabled
+(in nanoseconds) using rdtsc or similar.
 .nf
 
     u64 quot, rem;
@@ -1294,27 +1301,31 @@ The value continuously increases, it does not wrap.
 The value needs to be manually wrapped by the size of the mmap buffer
 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().
 
 .TP
-.I data_tail;
+.I data_tail
 When the mapping is
 .BR PROT_WRITE ,
 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.
+In this case the kernel will not overwrite unread data.
 
 .RE
 
 
-The following 2^n ring-buffer pages have the layout described below.
+The following 2^n ring buffer pages have the layout described below.
 
 If
 .I perf_event_attr.sample_id_all
 is set, then all event types will
-have the sample_type selected fields related to where/when (identity)
+have the
+.I sample_type
+selected fields related to where/when (identity)
 an event took place (TID, TIME, ID, CPU, STREAM_ID) described in
 .B PERF_RECORD_SAMPLE
 below, it will be stashed just after the
@@ -1573,7 +1584,8 @@ the current sampling period is written.
 .I v
 If
 .B PERF_SAMPLE_READ
-is enabled, a structure of type read_format
+is enabled, a structure of type
+.I read_format
 is included which has values for all events in the event group.
 The values included depend on the
 .I read_format
@@ -1702,7 +1714,7 @@ The signal handler is set up using the
 .BR select (2),
 .BR epoll (2)
 and
-.BR fcntl (2),
+.BR fcntl (2)
 system calls.
 
 To generate signals, sampling must be enabled
@@ -1756,7 +1768,7 @@ to calculate event values can be found in that section.
 .PP
 Various ioctls act on
 .BR perf_event_open ()
-file descriptors
+file descriptors.
 
 .TP
 .B PERF_EVENT_IOC_ENABLE
@@ -1790,14 +1802,14 @@ A signal with
 .B POLL_IN
 set will happen on each overflow until the
 count reaches 0; when that happens a signal with
-POLL_HUP
+.B 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
-file descriptor argumentto zero.
+file descriptor argument to zero.
 This only resets the counts; there is no way to reset the
 multiplexing
 .I time_enabled
@@ -1885,7 +1897,8 @@ The default value is
 .TP
 .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).
 .RE
 
@@ -1903,7 +1916,9 @@ Each subdirectory corresponds to a different PMU.
 .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.
+field of
+.I perf_event_attr
+to indicate you wish to use this PMU.
 
 .TP
 .I /sys/bus/event_source/devices/*/rdpmc
@@ -1913,7 +1928,9 @@ field of perf_event_attr to indicate you wish to use this PMU.
 .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.
+field of
+.I perf_event_attr
+correspond to.
 
 .TP
 .I /sys/bus/event_source/devices/*/events/
@@ -1953,18 +1970,18 @@ Linus did not like this, and this was changed to
 is still returned if you try to read results into
 too small of a buffer.
 
-.SH VERSION
+.SH VERSIONS
 
 .BR perf_event_open ()
 was introduced in Linux 2.6.31 but was called
-.BR perf_counter_open () .
+.BR perf_counter_open ().
 It was renamed in Linux 2.6.32.
 
 .SH CONFORMING TO
 
 This
 .BR perf_event_open ()
-system call Linux- specific
+system call is Linux-specific
 and should not be used in programs intended to be portable.
 
 .SH NOTES
@@ -2002,8 +2019,9 @@ scheduled them in an improper counter slot.
 Prior to Linux 2.6.34 there was a bug when multiplexing where the
 wrong results could be returned.
 
-Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
-"inherit" is enabled and many threads are started.
+Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash if
+.I inherit
+is enabled and many threads are started.
 
 Prior to Linux 2.6.35,
 .B PERF_FORMAT_GROUP
@@ -2016,7 +2034,9 @@ This behavior is unsupported and should not be relied on.
 
 There is a bug in the kernel code between
 Linux 2.6.36 and Linux 3.0 that ignores the
-"watermark" field and acts as if a wakeup_event
+.I watermark
+field and acts as if a
+.I wakeup_event
 was chosen if the union has a
 non-zero value in it.
 
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] perf_event_open.2: ffix and tfix

[David Prévot]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi Michael,

Le 22/02/2013 12:47, David Prévot a écrit :
> ---
>  man2/perf_event_open.2 |  126 ++++++++++++++++++++++++++++--------------------
>  1 file changed, 73 insertions(+), 53 deletions(-)

I forgot to mention, that you may wish to unify all the “user-space”
occurrences to “user space” (ditto for “kernel-space” into “kernel
space”) or the other way around, but not only on this page.

Regards

David

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iQIcBAEBCAAGBQJRJ6KGAAoJELgqIXr9/gny7T0QAK7jTSyg61oS4y3eWRqW2DTO
k9flm4dLIb2fxenARzoto+1IuZ5piyldbgx+cNHsZZoWXN3t8e3FNMjgk2NdvCJu
Gi5q/GN+ISoSzhZu8y3smRI81DF35YuYmHANbOhsYKY7aNXQt8cwofo+8xpmiXW6
fVem4U4XrNje5CNSvl1AcJ8XtLFy9UoZ3IEbT3k2D74tZT8i7d566xq0wIQCr0g2
4DIqsVBWJWJOr8Mddwtx+BMEFI9ULFcMTQRxGemie25+W9HixsARuhy4Ds57Vr18
uWMXDXVZp08yQwUuEHY0SrnO2xieo2EproqoosTHxMmUIe1lfL+jWB3wcdDDKJlY
ekCbm6uUkg0BfSn4c3XaVwTc9Pc6RHaE1ifqTAp8wYrEnzycBgepeGiwAlso8FUx
9ul0l3qxEqK8X2zwvIXwIol2/WbNBjUjxuCEtwJikrg3R5BkEwdVQ6L4hmIfc2Yu
Md7WE014JhkqCMTrltDQtJhEdQTah7R/Om1T4bFWyGA3gM1h0975xMhqFpBMGsBL
rPb3U2nwSva63dsr+hL6raB0yhh35QJRCBRrM97qDBFp6+hi9JdwT5tAi4EjCTsp
/S0qfwvfihApupaIup0beOCSAiYAdkV6Zaq55MgG6WkLqeGXRA8ISRV94/62AhEA
bYcoqMEeBUinnt55t5dM
=qlZ6
-----END PGP SIGNATURE-----
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] perf_event_open.2: ffix and wfix

[David Prévot]

---
 man2/perf_event_open.2 |   18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index eb989d4..42ec49f 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -334,7 +334,11 @@ is 72, corresponding to the addition of breakpoints in Linux 2.6.33.
 is 80, corresponding to the addition of branch sampling in Linux 3.4.
 .B PERF_ATR_SIZE_VER3
 is 96, corresponding to the addition
-of sample_regs_user and sample_stack_user in Linux 3.7.
+of
+.I sample_regs_user
+and
+.I sample_stack_user
+in Linux 3.7.
 
 .TP
 .I "config"
@@ -682,12 +686,16 @@ file descriptor.
 .RS
 .TP
 .B PERF_FORMAT_TOTAL_TIME_ENABLED
-Adds the 64-bit "time_enabled" field.
+Adds the 64-bit
+.I time_enabled
+field.
 This can be used to calculate estimated totals if
 the PMU is overcommitted and multiplexing is happening.
 .TP
 .B PERF_FORMAT_TOTAL_TIME_RUNNING
-Adds the 64-bit "time_running" field.
+Adds the 64-bit
+.I time_running
+field.
 This can be used to calculate estimated totals if
 the PMU is overcommitted and  multiplexing is happening.
 .TP
@@ -1012,7 +1020,7 @@ See
 
 .TP
 .IR "sample_stack_user" " (Since Linux 3.7)"
-This defines the size of the user stack to dump on sample.
+This defines the size of the user stack to dump on samples.
 
 .RE
 
@@ -1603,7 +1611,7 @@ follow.
 This is the current callchain.
 
 .TP
-.IR size ", " data
+.IR size ", " data[size]
 If
 .B PERF_SAMPLE_RAW
 is enabled, then a 32-bit value indicating size
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] perf_event_open.2: ffix and tfix

[Michael Kerrisk (man-pages)]

Thanks David. Applied.

On Fri, Feb 22, 2013 at 5:47 PM, David Prévot <taffit-8fiUuRrzOP0dnm+yROfE0A@public.gmane.org> wrote:
> ---
>  man2/perf_event_open.2 |  126 ++++++++++++++++++++++++++++--------------------
>  1 file changed, 73 insertions(+), 53 deletions(-)
>
> diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
> index ed468f2..eb989d4 100644
> --- a/man2/perf_event_open.2
> +++ b/man2/perf_event_open.2
> @@ -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,7 +72,7 @@ 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
> @@ -164,7 +164,7 @@ This flag re-routes the output from an event to the group leader.
>  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...).
> +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).
> @@ -226,7 +226,7 @@ struct perf_event_attr {
>                exclude_callchain_kernel : 1,
>                                      /* exclude kernel callchains */
>                exclude_callchain_user   : 1,
> -                                   /* exclude user callchains */
> +                                    /* exclude user callchains */
>                __reserved_1   : 41;
>
>      union {
> @@ -331,9 +331,9 @@ 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.
>  .B PERF_ATTR_SIZE_VER2
> -is 80 corresponding to the addition of branch sampling in Linux 3.4.
> +is 80, corresponding to the addition of branch sampling in Linux 3.4.
>  .B PERF_ATR_SIZE_VER3
> -is 96 corresponding to the addition
> +is 96, corresponding to the addition
>  of sample_regs_user and sample_stack_user in Linux 3.7.
>
>  .TP
> @@ -378,12 +378,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.
> @@ -611,11 +611,11 @@ timer tick.
>  .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,
> +They will be recorded in a ring buffer,
>  which is available to user-space using
>  .BR mmap (2).
>  The order in which the values are saved in the
> -sample are documented in the MMAP Layout subsection below;
> +sample is documented in the MMAP Layout subsection below;
>  it is not the
>  .I "enum perf_event_sample_format"
>  order.
> @@ -653,7 +653,8 @@ 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.
> @@ -661,7 +662,8 @@ Usually returned by tracepoint events.
>  .TP
>  .BR PERF_SAMPLE_BRANCH_STACK " (Since Linux 3.4)"
>  Records the branch stack.
> -See branch_sample_type.
> +See
> +.IR branch_sample_type .
>  .TP
>  .BR PERF_SAMPLE_REGS_USER " (Since Linux 3.7)"
>  Records the current register state.
> @@ -778,9 +780,9 @@ bit enables recording of exec mmap events.
>  The
>  .I comm
>  bit enables tracking of process command name as modified by the
> -.IR exec (2)
> +.BR exec (2)
>  and
> -.IR prctl (PR_SET_NAME)
> +.BR prctl (PR_SET_NAME)
>  system calls.
>  Unfortunately for tools,
>  there is no way to distinguish one system call versus the other.
> @@ -859,7 +861,7 @@ See also
>  The counterpart of the
>  .I mmap
>  field, but enables including data mmap events
> -in the ring-buffer.
> +in the ring buffer.
>
>  .TP
>  .IR "sample_id_all" " (Since Linux 2.6.38)"
> @@ -872,11 +874,11 @@ is selected.
>
>  .TP
>  .IR "exclude_host" " (Since Linux 3.2)"
> -Do not measure time spent in VM host
> +Do not measure time spent in VM host.
>
>  .TP
>  .IR "exclude_guest" " (Since Linux 3.2)"
> -Do not measure time spent in VM guest
> +Do not measure time spent in VM guest.
>
>  .TP
>  .IR "exclude_callchain_kernel" " (Since Linux 3.7)"
> @@ -932,7 +934,7 @@ is not allowed.
>  .TP
>  .IR "bp_addr" " (Since Linux 2.6.33)"
>  .I bp_addr
> -address of the breakpoint.
> +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.
> @@ -941,7 +943,9 @@ of the memory location of interest.
>  .IR "config1" " (Since Linux 2.6.39)"
>  .I config1
>  is used for setting events that need an extra register or otherwise
> -do not fit in the regular config field.
> +do not fit in the regular
> +.I config
> +field.
>  Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
>  on 3.3 and later kernels.
>
> @@ -975,28 +979,28 @@ It can have one of the following values:
>  .RS
>  .TP
>  .B PERF_SAMPLE_BRANCH_USER
> -Branch target is in user space
> +Branch target is in user space.
>  .TP
>  .B PERF_SAMPLE_BRANCH_KERNEL
> -Branch target is in kernel space
> +Branch target is in kernel space.
>  .TP
>  .B PERF_SAMPLE_BRANCH_HV
> -Branch target is in hypervisor
> +Branch target is in hypervisor.
>  .TP
>  .B PERF_SAMPLE_BRANCH_ANY
>  Any branch type.
>  .TP
>  .B PERF_SAMPLE_BRANCH_ANY_CALL
> -Any call branch
> +Any call branch.
>  .TP
>  .B PERF_SAMPLE_BRANCH_ANY_RETURN
> -Any return branch
> +Any return branch.
>  .TP
>  .BR PERF_SAMPLE_BRANCH_IND_CALL
> -Indirect calls
> +Indirect calls.
>  .TP
>  .BR PERF_SAMPLE_BRANCH_PLM_ALL
> -User, kernel, and hv
> +User, kernel, and hv.
>  .RE
>
>  .TP
> @@ -1026,7 +1030,7 @@ structure at open time.
>  If you attempt to read into a buffer that is not big enough to hold the
>  data
>  .B ENOSPC
> -is returned
> +is returned.
>
>  Here is the layout of the data returned by a read:
>
> @@ -1095,7 +1099,8 @@ An unsigned 64-bit value containing the counter result.
>  .I id
>  A globally unique value for this particular event, only there if
>  .B PERF_FORMAT_ID
> -was specified in read_format.
> +was specified in
> +.IR read_format .
>
>  .RE
>  .RE
> @@ -1110,15 +1115,15 @@ in sampled mode, asynchronous events
>  (like counter overflow or
>  .B PROT_EXEC
>  mmap tracking)
> -are logged into a ring-buffer.
> -This ring-buffer is created and accessed through
> +are logged into a ring buffer.
> +This ring buffer is created and accessed through
>  .BR mmap (2).
>
>  The mmap size should be 1+2^n pages, where the first page is a
>  metadata page
> -.IR ( "struct perf_event_mmap_page" )
> +.RI ( "struct perf_event_mmap_page" )
>  that contains various
> -bits of information such as where the ring-buffer head is.
> +bits of information such as where the ring buffer head is.
>
>  Before kernel 2.6.39, there is a bug that means you must allocate a mmap
>  ring buffer when sampling even if you do not plan to access it.
> @@ -1190,7 +1195,7 @@ Time the event was running.
>
>  .TP
>  .I cap_usr_time
> -User time capability
> +User time capability.
>
>  .TP
>  .I cap_usr_rdpmc
> @@ -1256,7 +1261,9 @@ count += pmc;
>  If
>  .IR cap_usr_time ,
>  these fields can be used to compute the time
> -delta since time_enabled (in nanoseconds) using rdtsc or similar.
> +delta since
> +.I time_enabled
> +(in nanoseconds) using rdtsc or similar.
>  .nf
>
>      u64 quot, rem;
> @@ -1294,27 +1301,31 @@ The value continuously increases, it does not wrap.
>  The value needs to be manually wrapped by the size of the mmap buffer
>  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().
>
>  .TP
> -.I data_tail;
> +.I data_tail
>  When the mapping is
>  .BR PROT_WRITE ,
>  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.
> +In this case the kernel will not overwrite unread data.
>
>  .RE
>
>
> -The following 2^n ring-buffer pages have the layout described below.
> +The following 2^n ring buffer pages have the layout described below.
>
>  If
>  .I perf_event_attr.sample_id_all
>  is set, then all event types will
> -have the sample_type selected fields related to where/when (identity)
> +have the
> +.I sample_type
> +selected fields related to where/when (identity)
>  an event took place (TID, TIME, ID, CPU, STREAM_ID) described in
>  .B PERF_RECORD_SAMPLE
>  below, it will be stashed just after the
> @@ -1573,7 +1584,8 @@ the current sampling period is written.
>  .I v
>  If
>  .B PERF_SAMPLE_READ
> -is enabled, a structure of type read_format
> +is enabled, a structure of type
> +.I read_format
>  is included which has values for all events in the event group.
>  The values included depend on the
>  .I read_format
> @@ -1702,7 +1714,7 @@ The signal handler is set up using the
>  .BR select (2),
>  .BR epoll (2)
>  and
> -.BR fcntl (2),
> +.BR fcntl (2)
>  system calls.
>
>  To generate signals, sampling must be enabled
> @@ -1756,7 +1768,7 @@ to calculate event values can be found in that section.
>  .PP
>  Various ioctls act on
>  .BR perf_event_open ()
> -file descriptors
> +file descriptors.
>
>  .TP
>  .B PERF_EVENT_IOC_ENABLE
> @@ -1790,14 +1802,14 @@ A signal with
>  .B POLL_IN
>  set will happen on each overflow until the
>  count reaches 0; when that happens a signal with
> -POLL_HUP
> +.B 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
> -file descriptor argumentto zero.
> +file descriptor argument to zero.
>  This only resets the counts; there is no way to reset the
>  multiplexing
>  .I time_enabled
> @@ -1885,7 +1897,8 @@ The default value is
>  .TP
>  .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).
>  .RE
>
> @@ -1903,7 +1916,9 @@ Each subdirectory corresponds to a different PMU.
>  .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.
> +field of
> +.I perf_event_attr
> +to indicate you wish to use this PMU.
>
>  .TP
>  .I /sys/bus/event_source/devices/*/rdpmc
> @@ -1913,7 +1928,9 @@ field of perf_event_attr to indicate you wish to use this PMU.
>  .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.
> +field of
> +.I perf_event_attr
> +correspond to.
>
>  .TP
>  .I /sys/bus/event_source/devices/*/events/
> @@ -1953,18 +1970,18 @@ Linus did not like this, and this was changed to
>  is still returned if you try to read results into
>  too small of a buffer.
>
> -.SH VERSION
> +.SH VERSIONS
>
>  .BR perf_event_open ()
>  was introduced in Linux 2.6.31 but was called
> -.BR perf_counter_open () .
> +.BR perf_counter_open ().
>  It was renamed in Linux 2.6.32.
>
>  .SH CONFORMING TO
>
>  This
>  .BR perf_event_open ()
> -system call Linux- specific
> +system call is Linux-specific
>  and should not be used in programs intended to be portable.
>
>  .SH NOTES
> @@ -2002,8 +2019,9 @@ scheduled them in an improper counter slot.
>  Prior to Linux 2.6.34 there was a bug when multiplexing where the
>  wrong results could be returned.
>
> -Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
> -"inherit" is enabled and many threads are started.
> +Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash if
> +.I inherit
> +is enabled and many threads are started.
>
>  Prior to Linux 2.6.35,
>  .B PERF_FORMAT_GROUP
> @@ -2016,7 +2034,9 @@ This behavior is unsupported and should not be relied on.
>
>  There is a bug in the kernel code between
>  Linux 2.6.36 and Linux 3.0 that ignores the
> -"watermark" field and acts as if a wakeup_event
> +.I watermark
> +field and acts as if a
> +.I wakeup_event
>  was chosen if the union has a
>  non-zero value in it.
>
> --
> 1.7.10.4
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] perf_event_open.2: ffix and tfix

[Michael Kerrisk (man-pages)]

Hi David,

On Fri, Feb 22, 2013 at 5:53 PM, David Prévot <taffit-8fiUuRrzOP0dnm+yROfE0A@public.gmane.org> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> Hi Michael,
>
> Le 22/02/2013 12:47, David Prévot a écrit :
>> ---
>>  man2/perf_event_open.2 |  126 ++++++++++++++++++++++++++++--------------------
>>  1 file changed, 73 insertions(+), 53 deletions(-)
>
> I forgot to mention, that you may wish to unify all the “user-space”
> occurrences to “user space” (ditto for “kernel-space” into “kernel
> space”) or the other way around, but not only on this page.

The general rule for compounds like this in English is that they
should be hyphenated when used attributively, and not hyphenated
otherwise. Thus:

     user-space operations

and

    operations performed in user space.

Man pages generally follows that rule, but you were right that the
perf_event_open.2 page was inconsistent. I've fixed it now.

Thanks,

Michael



> David
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.12 (GNU/Linux)
>
> iQIcBAEBCAAGBQJRJ6KGAAoJELgqIXr9/gny7T0QAK7jTSyg61oS4y3eWRqW2DTO
> k9flm4dLIb2fxenARzoto+1IuZ5piyldbgx+cNHsZZoWXN3t8e3FNMjgk2NdvCJu
> Gi5q/GN+ISoSzhZu8y3smRI81DF35YuYmHANbOhsYKY7aNXQt8cwofo+8xpmiXW6
> fVem4U4XrNje5CNSvl1AcJ8XtLFy9UoZ3IEbT3k2D74tZT8i7d566xq0wIQCr0g2
> 4DIqsVBWJWJOr8Mddwtx+BMEFI9ULFcMTQRxGemie25+W9HixsARuhy4Ds57Vr18
> uWMXDXVZp08yQwUuEHY0SrnO2xieo2EproqoosTHxMmUIe1lfL+jWB3wcdDDKJlY
> ekCbm6uUkg0BfSn4c3XaVwTc9Pc6RHaE1ifqTAp8wYrEnzycBgepeGiwAlso8FUx
> 9ul0l3qxEqK8X2zwvIXwIol2/WbNBjUjxuCEtwJikrg3R5BkEwdVQ6L4hmIfc2Yu
> Md7WE014JhkqCMTrltDQtJhEdQTah7R/Om1T4bFWyGA3gM1h0975xMhqFpBMGsBL
> rPb3U2nwSva63dsr+hL6raB0yhh35QJRCBRrM97qDBFp6+hi9JdwT5tAi4EjCTsp
> /S0qfwvfihApupaIup0beOCSAiYAdkV6Zaq55MgG6WkLqeGXRA8ISRV94/62AhEA
> bYcoqMEeBUinnt55t5dM
> =qlZ6
> -----END PGP SIGNATURE-----



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html