Add some documentation on the perf sysfs ABI interface
PATCH 1/1 Add some documentation on the perf sysfs ABI interface
From: Andi Kleen <[email protected]>
Initial attempt of documenting the perf sysfs interface as an ABI. I also added some additional pointers hopefully useful to the users. Comments welcome.
--- Documentation/ABI/stable/sysfs-devices-perf | 87 +++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
Documentation/ABI/stable/sysfs-devices-perf new file +87 -0
@@ -0,0 +1,87 @@ +Perf events enumeration in sysfs + +The perf events subsystem exports the format of hardware performance +counter events supported by perf events. The events can be accessed +using the perf_event_open() syscall. Each directory represents +a PMU (Performance Monitoring Unit) + +What: /sys/devices/*/format/* +Description: + +Each file in format describes how to fill in an event attribute on the +current CPU for the perf_event_open syscall. Multiple event +attributes may be overlapping and only be valid for some combination +of attributes (for example only for some event/umask combinations). +Most attributes are optional. + +Each field may have the following contents: + +CONFIG:START-END Field contains of bits START-END in the perf_event_attr CONFIG field +CONFIG:BIT Field consists of a single bit with index BIT in CONFIG field + +Valid CONFIG fields are config, config1, config2. These map to the respective 64bit words +in the struct perf_event_attr. + +Typical attributes on a x86 platform + +event Set the 8 bit event code (required) +umask Set the 8 bit umask. Event code and umask together select an hardware event. +cmask Set the 8 bit counter Mask. Only increment counters when more than cmask + events happen at the same time. +inv (1bit flag) Invert the event condition +edge (1bit flag) Only increment the event when the condition changes (starts happening) +any (1bit flag) Count on both threads of a core +pc (1bit flag) Toggle the PMi pins when the condition happens + +Attributes available on some x86 platforms: + +in_tx (1bit flag) Only count in a hardware transaction. +in_tx_cp (1bit flag) Undo counts inside transaction when transaction aborts. +ldlat Set the load-use latency threshold for sampling loads. + Note this is a load-use latency so includes pipeline delays. +offcore_rsp Set an extra mask qualifying the type of offcore access. + Only with OFFCORE_RESPONSE events + +For more details on the x86 attributes on Intel platforms please see +http://www.intel.com/sdm Volume 3, Chapter 18 and 19. For more +details on the perf_event_attr struct please see the perf_event_open +manpage. + +What: /sys/devices/*/events/* +Description: + +Describe predefined events available in the CPU. Each file describes an event. +The format is attr=0xHEXNUM{,attr=0xHEXNUM}. Each attr is described in a config +file. Together all the attributes can be used to set up a valid event for the +perf_event_open syscall. + +Note typically only a small subset of the CPU events are described +Some more events are available through predefined classes in perf_event_attr. + +What: /sys/devices/*/type +Description: + +Contains a decimal number. The PMU type to fill into perf_event_attr in the +type field to select the correct PMU. + +What: /sys/devices/*/perf_event_mux_interval_ms +Description: + +Decimal number. Set the counter multiplexing interval in ms. When more +events are active than the hardware directly supports perf events +multiplexes the event. By default this is done on timer interrupts +(depending on the CONFIG_HZ setting) and not done while idle. This +allows to set a different frequency. Note that setting this may impact +idle time, as the event switches will wake up the CPUs now. + +What: /sys/devices/*/rdpmc +Description: + +[x86] When 1, allow the RDPMC instruction in user space to read performance +events that have been set up with perf. + +Users: perf (tools/perf/*) +The following libraries provide more user friendly interfaces: + PAPI (http://icl.cs.utk.edu/papi/) + libpfm4 (http://perfmon2.sourceforge.net/) + jevents (http://github.com/andikleen/pmu-tools)
Signature · 1 line
1.9.3
Quoted 40 lines · Andi Kleen
From: Andi Kleen <[email protected]>
Initial attempt of documenting the perf sysfs interface as an ABI. I also added some additional pointers hopefully useful to the users. Comments welcome.
--- Documentation/ABI/stable/sysfs-devices-perf | 87 +++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 Documentation/ABI/stable/sysfs-devices-perfDocumentation/ABI/stable/sysfs-devices-perf new file +20
-0@@ -0,0 +1,87 @@ +Perf events enumeration in sysfs + +The perf events subsystem exports the format of hardware performance +counter events supported by perf events. The events can be accessed +using the perf_event_open() syscall. Each directory represents +a PMU (Performance Monitoring Unit) + +What: /sys/devices/*/format/* +Description: + +Each file in format describes how to fill in an event attribute on the +current CPU for the perf_event_open syscall. Multiple event +attributes may be overlapping and only be valid for some combination +of attributes (for example only for some event/umask combinations). +Most attributes are optional. + +Each field may have the following contents: + +CONFIG:START-END Field contains of bits START-END in the perf_event_attr CONFIG field +CONFIG:BIT Field consists of a single bit with index BIT in CONFIG field
Documentation/ABI/stable/sysfs-devices-perf line 30
Quoted 10 lines
Documentation/ABI/stable/sysfs-devices-perf new file +10
-0+ +Valid CONFIG fields are config, config1, config2. These map to the respective 64bit words +in the struct perf_event_attr. + +Typical attributes on a x86 platform + +event Set the 8 bit event code (required) +umask Set the 8 bit umask. Event code and umask together select an hardware event. +cmask Set the 8 bit counter Mask. Only increment counters when more than cmask + events happen at the same time.
This is the wrong description for cmask. Here is a better one.
If cmask=N, then counts the number of core cycles in which the event occurs at least N times (>= N).
Documentation/ABI/stable/sysfs-devices-perf line 31
Quoted 1 line
Documentation/ABI/stable/sysfs-devices-perf new file +1
-0+inv (1bit flag) Invert the event condition
Wrong description.
Only valid with cmask>=1. Invert the cmask condition. If cmask=N, then counts the number of
core cycles in which the event occurs strictly less than N times (<N).
Quoted 59 lines
Documentation/ABI/stable/sysfs-devices-perf new file +56
-1+edge (1bit flag) Only increment the event when the condition changes (starts happening) +any (1bit flag) Count on both threads of a core +pc (1bit flag) Toggle the PMi pins when the condition happens + +Attributes available on some x86 platforms: + +in_tx (1bit flag) Only count in a hardware transaction. +in_tx_cp (1bit flag) Undo counts inside transaction when transaction aborts. +ldlat Set the load-use latency threshold for sampling loads. + Note this is a load-use latency so includes pipeline delays. +offcore_rsp Set an extra mask qualifying the type of offcore access. + Only with OFFCORE_RESPONSE events + +For more details on the x86 attributes on Intel platforms please see +http://www.intel.com/sdm Volume 3, Chapter 18 and 19. For more +details on the perf_event_attr struct please see the perf_event_open +manpage. + +What: /sys/devices/*/events/* +Description: + +Describe predefined events available in the CPU. Each file describes an event. +The format is attr=0xHEXNUM{,attr=0xHEXNUM}. Each attr is described in a config +file. Together all the attributes can be used to set up a valid event for the +perf_event_open syscall. + +Note typically only a small subset of the CPU events are described +Some more events are available through predefined classes in perf_event_attr. + +What: /sys/devices/*/type +Description: + +Contains a decimal number. The PMU type to fill into perf_event_attr in the +type field to select the correct PMU. + +What: /sys/devices/*/perf_event_mux_interval_ms +Description: + +Decimal number. Set the counter multiplexing interval in ms. When more +events are active than the hardware directly supports perf events +multiplexes the event. By default this is done on timer interrupts +(depending on the CONFIG_HZ setting) and not done while idle. This +allows to set a different frequency. Note that setting this may impact +idle time, as the event switches will wake up the CPUs now. + +What: /sys/devices/*/rdpmc +Description: + +[x86] When 1, allow the RDPMC instruction in user space to read performance +events that have been set up with perf. + +Users: perf (tools/perf/*) +The following libraries provide more user friendly interfaces: + PAPI (http://icl.cs.utk.edu/papi/) + libpfm4 (http://perfmon2.sourceforge.net/) + jevents (http://github.com/andikleen/pmu-tools) --1.9.3
Fixed thanks.
-Andi
Signature · 1 line
[email protected] -- Speaking for myself only.
Quoted 20 lines · Andi Kleen
From: Andi Kleen <[email protected]>
Initial attempt of documenting the perf sysfs interface as an ABI. I also added some additional pointers hopefully useful to the users. Comments welcome.
--- Documentation/ABI/stable/sysfs-devices-perf | 87 +++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 Documentation/ABI/stable/sysfs-devices-perfDocumentation/ABI/stable/sysfs-devices-perf new file +0
-0
Documentation/ABI/stable/sysfs-devices-perf line 6
Quoted 6 lines
Documentation/ABI/stable/sysfs-devices-perf new file +6
-0@@ -0,0 +1,87 @@ +Perf events enumeration in sysfs + +The perf events subsystem exports the format of hardware performance +counter events supported by perf events. The events can be accessed +using the perf_event_open() syscall. Each directory represents +a PMU (Performance Monitoring Unit)
add ending '.' above: Unit).
Documentation/ABI/stable/sysfs-devices-perf line 19
Quoted 13 lines
Documentation/ABI/stable/sysfs-devices-perf new file +13
-0+ +What: /sys/devices/*/format/* +Description: + +Each file in format describes how to fill in an event attribute on the +current CPU for the perf_event_open syscall. Multiple event +attributes may be overlapping and only be valid for some combination +of attributes (for example only for some event/umask combinations). +Most attributes are optional. + +Each field may have the following contents: + +CONFIG:START-END Field contains of bits START-END in the perf_event_attr CONFIG field
Confusing. Maybe: Field contains bits START-END ...
Documentation/ABI/stable/sysfs-devices-perf line 28
Quoted 9 lines
Documentation/ABI/stable/sysfs-devices-perf new file +9
-0+CONFIG:BIT Field consists of a single bit with index BIT in CONFIG field + +Valid CONFIG fields are config, config1, config2. These map to the respective 64bit words +in the struct perf_event_attr. + +Typical attributes on a x86 platform + +event Set the 8 bit event code (required) +umask Set the 8 bit umask. Event code and umask together select an hardware event.
select a hardware event.
Quoted 20 lines
Documentation/ABI/stable/sysfs-devices-perf new file +20
-0+cmask Set the 8 bit counter Mask. Only increment counters when more than cmask + events happen at the same time. +inv (1bit flag) Invert the event condition +edge (1bit flag) Only increment the event when the condition changes (starts happening) +any (1bit flag) Count on both threads of a core +pc (1bit flag) Toggle the PMi pins when the condition happens + +Attributes available on some x86 platforms: + +in_tx (1bit flag) Only count in a hardware transaction. +in_tx_cp (1bit flag) Undo counts inside transaction when transaction aborts. +ldlat Set the load-use latency threshold for sampling loads. + Note this is a load-use latency so includes pipeline delays. +offcore_rsp Set an extra mask qualifying the type of offcore access. + Only with OFFCORE_RESPONSE events + +For more details on the x86 attributes on Intel platforms please see +http://www.intel.com/sdm Volume 3, Chapter 18 and 19. For more +details on the perf_event_attr struct please see the perf_event_open +manpage.
Documentation/ABI/stable/sysfs-devices-perf line 58
Quoted 10 lines
Documentation/ABI/stable/sysfs-devices-perf new file +10
-0+ +What: /sys/devices/*/events/* +Description: + +Describe predefined events available in the CPU. Each file describes an event. +The format is attr=0xHEXNUM{,attr=0xHEXNUM}. Each attr is described in a config +file. Together all the attributes can be used to set up a valid event for the +perf_event_open syscall. + +Note typically only a small subset of the CPU events are described
add ending '.' above. Also: is described.
Documentation/ABI/stable/sysfs-devices-perf line 64
Quoted 6 lines
Documentation/ABI/stable/sysfs-devices-perf new file +6
-0+Some more events are available through predefined classes in perf_event_attr. + +What: /sys/devices/*/type +Description: + +Contains a decimal number. The PMU type to fill into perf_event_attr in the
Contains a decimal number: the
Quoted 24 lines
Documentation/ABI/stable/sysfs-devices-perf new file +23
-0+type field to select the correct PMU. + +What: /sys/devices/*/perf_event_mux_interval_ms +Description: + +Decimal number. Set the counter multiplexing interval in ms. When more +events are active than the hardware directly supports perf events +multiplexes the event. By default this is done on timer interrupts +(depending on the CONFIG_HZ setting) and not done while idle. This +allows to set a different frequency. Note that setting this may impact +idle time, as the event switches will wake up the CPUs now. + +What: /sys/devices/*/rdpmc +Description: + +[x86] When 1, allow the RDPMC instruction in user space to read performance +events that have been set up with perf. + +Users: perf (tools/perf/*) +The following libraries provide more user friendly interfaces: + PAPI (http://icl.cs.utk.edu/papi/) + libpfm4 (http://perfmon2.sourceforge.net/) + jevents (http://github.com/andikleen/pmu-tools)
Signature · 1 line
~Randy