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