Skip to contentSkip to conversation

Add some documentation on the perf sysfs ABI interface

PATCH In review Andi Kleen 3 participants 4 messages Sep 9, 2014

lore
Share & tools
lore

Andi Kleen

author
#0 lore raw

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
new file mode 100644
index 0000000..0b00c7c
@@ -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
#1 lore raw
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-perf
Documentation/ABI/stable/sysfs-devices-perf new file +20 -0
new file mode 100644
index 0000000..0b00c7c
@@ -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

#3 lore raw
In reply to Andi Kleen
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-perf
Documentation/ABI/stable/sysfs-devices-perf new file +0 -0
new file mode 100644
index 0000000..0b00c7c

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