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.
Cc: Vince Weaver <[email protected]>
Cc: [email protected]
v2: Various fixes. Fix cmask/inv (Stephane) Fixes from Randy Dunlap.
--- Documentation/ABI/stable/sysfs-devices-perf | 98 +++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
Documentation/ABI/stable/sysfs-devices-perf new file +98 -0
@@ -0,0 +1,98 @@ +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 perf directory in devices +represents a distinct PMU (Performance Monitoring Unit), but not all +directories in this file are perf directories. + +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 consists 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 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 a + hardware event. +cmask Set the 8 bit counter Mask. Only increment counters when at + least cmask events happen during the same cycle. +inv (1bit flag) Invert the cmask condition. Only valid with + cmask>0. +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 the + 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. The actual mask is CPU model + specific. + +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 and include/uapi/linux/perf_event.h. + +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. + +Typically only a small subset of the CPU events is described in sysfs. +Some more events are available through predefined classes in perf_event_attr. +Even more events require filling in CPU specific values. The libraries referenced +below provide larger event lists. + +What: /sys/devices/*/type +Description: + +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 (value 0) 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 to non 0 +may impact idle time, as the event switches will wake up the CPUs now. + +What: /sys/devices/*/rdpmc +Description: + +[x86] Decimal number: When 1, allow the RDPMC instruction in user space +to read performance events that have been set up with perf. When 0 +ring 3 RDPMC access is disallowed. + +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 5 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.
My only worry is that its a little x86 centric and I'm not sure if that is acceptable with the sysfs crowd, Greg?
Other than that it looks like a nice addition and I suppose other popular archs can always add to it.
Quoted 116 lines
Cc: Vince Weaver <[email protected]>
Cc: [email protected]
v2: Various fixes. Fix cmask/inv (Stephane) Fixes from Randy Dunlap.Signed-off-by Andi Kleen <[email protected]>--- Documentation/ABI/stable/sysfs-devices-perf | 98 +++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 Documentation/ABI/stable/sysfs-devices-perfDocumentation/ABI/stable/sysfs-devices-perf new file +98
-0@@ -0,0 +1,98 @@ +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 perf directory in devices +represents a distinct PMU (Performance Monitoring Unit), but not all +directories in this file are perf directories. + +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 consists 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 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 a + hardware event. +cmask Set the 8 bit counter Mask. Only increment counters when at + least cmask events happen during the same cycle. +inv (1bit flag) Invert the cmask condition. Only valid with + cmask>0. +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 the + 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. The actual mask is CPU model + specific. + +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 and include/uapi/linux/perf_event.h. + +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. + +Typically only a small subset of the CPU events is described in sysfs. +Some more events are available through predefined classes in perf_event_attr. +Even more events require filling in CPU specific values. The libraries referenced +below provide larger event lists. + +What: /sys/devices/*/type +Description: + +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 (value 0) 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 to non 0 +may impact idle time, as the event switches will wake up the CPUs now. + +What: /sys/devices/*/rdpmc +Description: + +[x86] Decimal number: When 1, allow the RDPMC instruction in user space +to read performance events that have been set up with perf. When 0 +ring 3 RDPMC access is disallowed. + +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 9 lines · Peter Zijlstra
Quoted 5 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.
My only worry is that its a little x86 centric and I'm not sure if that is acceptable with the sysfs crowd, Greg?
Does this document what you have today? If so, that's fine, and good to do.
Or, is this a proposed interface that is different per architecture in subtle non-portable ways? If so, probably not :)
Quoted 61 lines
Other than that it looks like a nice addition and I suppose other popular archs can always add to it.
Quoted 58 lines
Cc: Vince Weaver <[email protected]>
Cc: [email protected]
v2: Various fixes. Fix cmask/inv (Stephane) Fixes from Randy Dunlap.Signed-off-by Andi Kleen <[email protected]>--- Documentation/ABI/stable/sysfs-devices-perf | 98 +++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 Documentation/ABI/stable/sysfs-devices-perfDocumentation/ABI/stable/sysfs-devices-perf new file +43
-0@@ -0,0 +1,98 @@ +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 perf directory in devices +represents a distinct PMU (Performance Monitoring Unit), but not all +directories in this file are perf directories. + +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 consists 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 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 a + hardware event. +cmask Set the 8 bit counter Mask. Only increment counters when at + least cmask events happen during the same cycle. +inv (1bit flag) Invert the cmask condition. Only valid with + cmask>0. +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: +
Quoted 8 lines
Documentation/ABI/stable/sysfs-devices-perf line 51
Quoted 8 lines
Documentation/ABI/stable/sysfs-devices-perf new file +8
-0+in_tx (1bit flag) Only count in a hardware transaction. +in_tx_cp (1bit flag) Undo counts inside transaction when the + 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. The actual mask is CPU model + specific.
I don't understand exactly what these files look like, are they just "one value per file", or do they have to be parsed with multiple values in the files?
Quoted 4 lines
Quoted 4 lines
Documentation/ABI/stable/sysfs-devices-perf new file +4
-0+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 and include/uapi/linux/perf_event.h.
Quoted 8 lines
Documentation/ABI/stable/sysfs-devices-perf line 64
Quoted 8 lines
Documentation/ABI/stable/sysfs-devices-perf new file +8
-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.
Why would a sysfs file have a "attr=" string in it? Again, one value per file is the rule here.
thanks,
greg k-h
Quoted 8 lines · Greg KH
Quoted 7 lines · Peter Zijlstra
Quoted 5 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.
Quoted 8 lines
Quoted 2 lines
My only worry is that its a little x86 centric and I'm not sure if that is acceptable with the sysfs crowd, Greg?
Does this document what you have today? If so, that's fine, and good to do.
Or, is this a proposed interface that is different per architecture in subtle non-portable ways? If so, probably not :)
Each architecture describes its own fields in a generic format that can be handled by a generic parser. The generic description is documented.
However I also described the x86 specific attributes.
This is all implemented today.
-Andi
Quoted 18 lines · Andi Kleen
Quoted 8 lines · Greg KH
Quoted 7 lines · Peter Zijlstra
Quoted 5 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.
Quoted 8 lines
Quoted 2 lines
My only worry is that its a little x86 centric and I'm not sure if that is acceptable with the sysfs crowd, Greg?
Does this document what you have today? If so, that's fine, and good to do.
Or, is this a proposed interface that is different per architecture in subtle non-portable ways? If so, probably not :)
Quoted 6 lines
Each architecture describes its own fields in a generic format that can be handled by a generic parser. The generic description is documented.
However I also described the x86 specific attributes.
This is all implemented today.
Ok, as long as things are "one value per file", I have no objection, thanks for the documentation.
greg k-h
Quoted 21 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.
Cc: Vince Weaver <[email protected]>
Cc: [email protected]
v2: Various fixes. Fix cmask/inv (Stephane) Fixes from Randy Dunlap.Signed-off-by Andi Kleen <[email protected]>--- Documentation/ABI/stable/sysfs-devices-perf | 98 +++++++++++++++++++++++++++++ 1 file changed, 98 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 7
Quoted 7 lines
Documentation/ABI/stable/sysfs-devices-perf new file +7
-0@@ -0,0 +1,98 @@ +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 perf directory in devices +represents a distinct PMU (Performance Monitoring Unit), but not all +directories in this file are perf directories.
s/in this file/in this directory/ ?
otherwise it looks ok to me
jirka