This clarifies some of the ABI, as there has been some confusion
and minor breakages lately. Most notably it documents that as of
3.10 the events entries can contain decimal values in addition to
hex.
This is version 2 containing whitespace fixes suggested by
Jiri Olsa.
Signed-off-by: Vince Weaver <[email protected]>
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
index 3c1cc24..16d9107 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
@@ -1,30 +1,52 @@
-What: /sys/devices/cpu/events/
+What: /sys/bus/event_source/devices/<dev>/events
+
+Date: 2013/01/08
+
+Contact: Linux kernel mailing list <[email protected]>
+
+Description: Generic performance monitoring events
+
+ A collection of performance monitoring events that are
+ supported by the PMU (performance monitoring unit)
+ specified by "<dev>". These events can be monitored
+ using the 'perf(1)' tool.
+
+ The contents of each file is a list of attribute names
+ (as found in the corresponding
+ /sys/bus/event_source/devices/<dev>/format
+ file) separated by commas. Each entry has
+ an optional value (either hex or decimal). If no
+ value is specified than it is assumed to be a single-bit
+ field with a value of 1.
+
+ An example of what you might find:
+ event=0x2,inv,ldlat=3
+
+
+What: /sys/devices/cpu/events/branch-instructions
/sys/devices/cpu/events/branch-misses
- /sys/devices/cpu/events/cache-references
+ /sys/devices/cpu/events/bus-cycles
/sys/devices/cpu/events/cache-misses
- /sys/devices/cpu/events/stalled-cycles-frontend
- /sys/devices/cpu/events/branch-instructions
- /sys/devices/cpu/events/stalled-cycles-backend
- /sys/devices/cpu/events/instructions
+ /sys/devices/cpu/events/cache-references
/sys/devices/cpu/events/cpu-cycles
+ /sys/devices/cpu/events/instructions
+ /sys/devices/cpu/events/ref-cycles
+ /sys/devices/cpu/events/stalled-cycles-backend
+ /sys/devices/cpu/events/stalled-cycles-frontend
Date: 2013/01/08
Contact: Linux kernel mailing list <[email protected]>
-Description: Generic performance monitoring events
+Description: Generic CPU performance monitoring events
A collection of performance monitoring events that may be
supported by many/most CPUs. These events can be monitored
using the 'perf(1)' tool.
- The contents of each file would look like:
-
- event=0xNNNN
-
- where 'N' is a hex digit and the number '0xNNNN' shows the
- "raw code" for the perf event identified by the file's
- "basename".
+ The format of these files matches that of
+ /sys/bus/event_source/devices/<dev>/events as described
+ previously in this file.
What: /sys/devices/cpu/events/PM_1PLUS_PPC_CMPL
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
index 77f47ff..8f4c13f 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
@@ -15,6 +15,12 @@ Description:
attr2 = 'config:0-7'
attr3 = 'config:12-35'
- Example: 'config1:1,6-10,44'
+ Example: event = 'config1:1,6-10,44'
Defines contents of attribute that occupies bits 1,6-10,44 of
perf_event_attr::config1.
+
+ In this example, the events file would have the value
+ event=0x7f
+ to set all of the specified bits (they will be split up).
+ You would not use 0x10000007c2 (which is what the bits
+ actually passed into config1 would look like).
There were various perf_event related sysfs entries in the
/sys/bus/event_source/devices/*/ directories that were not
documented.
This is version 2 with fixes suggested by Jiri Olsa.
Acked-by: Jiri Olsa <[email protected]>
Signed-off-by: Vince Weaver <[email protected]>
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices b/Documentation/ABI/testing/sysfs-bus-event_source-devices
new file mode 100644
index 0000000..e7434ee
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices
@@ -0,0 +1,45 @@
+What: /sys/bus/event_source/devices/<dev>/cpumask
+
+Date: 2012/09/10
+
+Contact: Linux kernel mailing list <[email protected]>
+
+Description: This value holds a representative core for each
+ socket in a system. It is meant to help when
+ creating a perf_event event for socket-wide events
+ like uncore and northbridge events.
+
+ The format is a comma separated list of cpu numbers,
+ one for each socket in the system that the PMU in
+ question can run on.
+
+ For example, on a two-socket Sandybridge-EP machine and
+ the cbox0 uncore the value of the file will be:
+ 0,8
+
+
+What: /sys/bus/event_source/devices/cpu/rdpmc
+
+Date: 2011/11/20
+
+Contact: Linux kernel mailing list <[email protected]>
+
+Description: Indicates whether a CPU allows userspace "rdpmc"
+ instructions (unprivileged reads of the performance
+ counter MSRs).
+
+ You can echo 0 to this value to disable user rdpmc
+ access.
+
+
+What: /sys/bus/event_source/devices/<dev>/type
+
+Date: 2013/01/08
+
+Contact: Linux kernel mailing list <[email protected]>
+
+Description: This value holds the PMU (Performance Monitor Unit) type
+ value that is passed into the perf_event_open()
+ attr:type field when opening an event.
+
+ The value is a decimal integer.
It's been a month, are there any objections to these perf_event ABI
documentation updates?
Vince
On Thu, 25 Jul 2013, Vince Weaver wrote:
>
> This clarifies some of the ABI, as there has been some confusion
> and minor breakages lately. Most notably it documents that as of
> 3.10 the events entries can contain decimal values in addition to
> hex.
>
> This is version 2 containing whitespace fixes suggested by
> Jiri Olsa.
>
> Signed-off-by: Vince Weaver <[email protected]>
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> index 3c1cc24..16d9107 100644
> --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> @@ -1,30 +1,52 @@
> -What: /sys/devices/cpu/events/
> +What: /sys/bus/event_source/devices/<dev>/events
> +
> +Date: 2013/01/08
> +
> +Contact: Linux kernel mailing list <[email protected]>
> +
> +Description: Generic performance monitoring events
> +
> + A collection of performance monitoring events that are
> + supported by the PMU (performance monitoring unit)
> + specified by "<dev>". These events can be monitored
> + using the 'perf(1)' tool.
> +
> + The contents of each file is a list of attribute names
> + (as found in the corresponding
> + /sys/bus/event_source/devices/<dev>/format
> + file) separated by commas. Each entry has
> + an optional value (either hex or decimal). If no
> + value is specified than it is assumed to be a single-bit
> + field with a value of 1.
> +
> + An example of what you might find:
> + event=0x2,inv,ldlat=3
> +
> +
> +What: /sys/devices/cpu/events/branch-instructions
> /sys/devices/cpu/events/branch-misses
> - /sys/devices/cpu/events/cache-references
> + /sys/devices/cpu/events/bus-cycles
> /sys/devices/cpu/events/cache-misses
> - /sys/devices/cpu/events/stalled-cycles-frontend
> - /sys/devices/cpu/events/branch-instructions
> - /sys/devices/cpu/events/stalled-cycles-backend
> - /sys/devices/cpu/events/instructions
> + /sys/devices/cpu/events/cache-references
> /sys/devices/cpu/events/cpu-cycles
> + /sys/devices/cpu/events/instructions
> + /sys/devices/cpu/events/ref-cycles
> + /sys/devices/cpu/events/stalled-cycles-backend
> + /sys/devices/cpu/events/stalled-cycles-frontend
>
> Date: 2013/01/08
>
> Contact: Linux kernel mailing list <[email protected]>
>
> -Description: Generic performance monitoring events
> +Description: Generic CPU performance monitoring events
>
> A collection of performance monitoring events that may be
> supported by many/most CPUs. These events can be monitored
> using the 'perf(1)' tool.
>
> - The contents of each file would look like:
> -
> - event=0xNNNN
> -
> - where 'N' is a hex digit and the number '0xNNNN' shows the
> - "raw code" for the perf event identified by the file's
> - "basename".
> + The format of these files matches that of
> + /sys/bus/event_source/devices/<dev>/events as described
> + previously in this file.
>
>
> What: /sys/devices/cpu/events/PM_1PLUS_PPC_CMPL
> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
> index 77f47ff..8f4c13f 100644
> --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
> @@ -15,6 +15,12 @@ Description:
> attr2 = 'config:0-7'
> attr3 = 'config:12-35'
>
> - Example: 'config1:1,6-10,44'
> + Example: event = 'config1:1,6-10,44'
> Defines contents of attribute that occupies bits 1,6-10,44 of
> perf_event_attr::config1.
> +
> + In this example, the events file would have the value
> + event=0x7f
> + to set all of the specified bits (they will be split up).
> + You would not use 0x10000007c2 (which is what the bits
> + actually passed into config1 would look like).
>