perf_event_open.2: ffix and tfix
PATCH 1/1 perf_event_open.2: ffix and tfix
--- man2/perf_event_open.2 | 126 ++++++++++++++++++++++++++++-------------------- 1 file changed, 73 insertions(+), 53 deletions(-)
man2/perf_event_open.2 +73 -53
@@ -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.
Signature · 6 lines
1.7.10.4 -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): 1361551634-17115-1-git-send-email-taffit-8fiUuRrzOP0dnm+yROfE0A@public.gmane.org
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Hi Michael,
Quoted 3 lines · David Prévot
--- 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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Hi David,
Quoted 5 lines · David Prévot
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256Hi Michael,
Quoted 8 lines
Quoted 3 lines · David Prévot
--- 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
Quoted 19 lines
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-----
Signature · 7 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
PATCH 1/1 perf_event_open.2: ffix and wfix
In reply to a message not in the archive--- man2/perf_event_open.2 | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-)
man2/perf_event_open.2 +13 -5
@@ -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
Signature · 6 lines
1.7.10.4 -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Thanks David. Applied.
Quoted 417 lines · David Prévot
--- man2/perf_event_open.2 | 126 ++++++++++++++++++++++++++++-------------------- 1 file changed, 73 insertions(+), 53 deletions(-)man2/perf_event_open.2 +73
-54@@ -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
Signature · 7 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html