* [PATCH] Add some documentation on the perf sysfs ABI interface
@ 2014-09-15 22:47 Andi Kleen
0 siblings, 0 replies; 11+ messages in thread
From: Andi Kleen @ 2014-09-15 22:47 UTC (permalink / raw)
To: peterz; +Cc: linux-kernel, mingo, eranian, Andi Kleen, Vince Weaver, jolsa
From: Andi Kleen <ak@linux.intel.com>
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 <vincent.weaver@maine.edu>
Cc: jolsa@redhat.com
v2: Various fixes. Fix cmask/inv (Stephane) Fixes from Randy Dunlap.
v3: Fix typo (Jiri).
Signed-off-by: Andi Kleen <ak@linux.intel.com>
---
Documentation/ABI/stable/sysfs-devices-perf | 99 +++++++++++++++++++++++++++++
1 file changed, 99 insertions(+)
create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
diff --git a/Documentation/ABI/stable/sysfs-devices-perf b/Documentation/ABI/stable/sysfs-devices-perf
new file mode 100644
index 0000000..73693e7
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-perf
@@ -0,0 +1,99 @@
+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 directory 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
+ XXX is END one beyond?
+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)
--
1.9.3
^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH] Add some documentation on the perf sysfs ABI interface
2014-09-14 15:44 ` Andi Kleen
@ 2014-09-14 15:53 ` Greg KH
0 siblings, 0 replies; 11+ messages in thread
From: Greg KH @ 2014-09-14 15:53 UTC (permalink / raw)
To: Andi Kleen
Cc: Peter Zijlstra, Andi Kleen, linux-kernel, mingo, eranian,
Vince Weaver, jolsa
On Sun, Sep 14, 2014 at 08:44:55AM -0700, Andi Kleen wrote:
> On Sun, Sep 14, 2014 at 08:34:07AM -0700, Greg KH wrote:
> > On Sun, Sep 14, 2014 at 11:30:33AM +0200, Peter Zijlstra wrote:
> > > On Fri, Sep 12, 2014 at 03:34:19PM -0700, Andi Kleen wrote:
> > > > From: Andi Kleen <ak@linux.intel.com>
> > > >
> > > > 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 :)
>
> 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
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Add some documentation on the perf sysfs ABI interface
2014-09-14 15:34 ` Greg KH
@ 2014-09-14 15:44 ` Andi Kleen
2014-09-14 15:53 ` Greg KH
0 siblings, 1 reply; 11+ messages in thread
From: Andi Kleen @ 2014-09-14 15:44 UTC (permalink / raw)
To: Greg KH
Cc: Peter Zijlstra, Andi Kleen, linux-kernel, mingo, eranian,
Vince Weaver, jolsa
On Sun, Sep 14, 2014 at 08:34:07AM -0700, Greg KH wrote:
> On Sun, Sep 14, 2014 at 11:30:33AM +0200, Peter Zijlstra wrote:
> > On Fri, Sep 12, 2014 at 03:34:19PM -0700, Andi Kleen wrote:
> > > From: Andi Kleen <ak@linux.intel.com>
> > >
> > > 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 :)
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
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Add some documentation on the perf sysfs ABI interface
2014-09-14 9:30 ` Peter Zijlstra
@ 2014-09-14 15:34 ` Greg KH
2014-09-14 15:44 ` Andi Kleen
0 siblings, 1 reply; 11+ messages in thread
From: Greg KH @ 2014-09-14 15:34 UTC (permalink / raw)
To: Peter Zijlstra
Cc: Andi Kleen, linux-kernel, mingo, eranian, Andi Kleen,
Vince Weaver, jolsa
On Sun, Sep 14, 2014 at 11:30:33AM +0200, Peter Zijlstra wrote:
> On Fri, Sep 12, 2014 at 03:34:19PM -0700, Andi Kleen wrote:
> > From: Andi Kleen <ak@linux.intel.com>
> >
> > 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 :)
> Other than that it looks like a nice addition and I suppose other
> popular archs can always add to it.
>
> > Cc: Vince Weaver <vincent.weaver@maine.edu>
> > Cc: jolsa@redhat.com
> > v2: Various fixes. Fix cmask/inv (Stephane) Fixes from Randy Dunlap.
> > Signed-off-by: Andi Kleen <ak@linux.intel.com>
> > ---
> > Documentation/ABI/stable/sysfs-devices-perf | 98 +++++++++++++++++++++++++++++
> > 1 file changed, 98 insertions(+)
> > create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
> >
> > diff --git a/Documentation/ABI/stable/sysfs-devices-perf b/Documentation/ABI/stable/sysfs-devices-perf
> > new file mode 100644
> > index 0000000..3fd9bc6
> > --- /dev/null
> > +++ b/Documentation/ABI/stable/sysfs-devices-perf
> > @@ -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.
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?
> > +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.
Why would a sysfs file have a "attr=" string in it? Again, one value per
file is the rule here.
thanks,
greg k-h
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Add some documentation on the perf sysfs ABI interface
2014-09-12 22:34 Andi Kleen
2014-09-14 9:30 ` Peter Zijlstra
@ 2014-09-14 13:23 ` Jiri Olsa
1 sibling, 0 replies; 11+ messages in thread
From: Jiri Olsa @ 2014-09-14 13:23 UTC (permalink / raw)
To: Andi Kleen; +Cc: peterz, linux-kernel, mingo, eranian, Andi Kleen, Vince Weaver
On Fri, Sep 12, 2014 at 03:34:19PM -0700, Andi Kleen wrote:
> From: Andi Kleen <ak@linux.intel.com>
>
> 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 <vincent.weaver@maine.edu>
> Cc: jolsa@redhat.com
> v2: Various fixes. Fix cmask/inv (Stephane) Fixes from Randy Dunlap.
> Signed-off-by: Andi Kleen <ak@linux.intel.com>
> ---
> Documentation/ABI/stable/sysfs-devices-perf | 98 +++++++++++++++++++++++++++++
> 1 file changed, 98 insertions(+)
> create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
>
> diff --git a/Documentation/ABI/stable/sysfs-devices-perf b/Documentation/ABI/stable/sysfs-devices-perf
> new file mode 100644
> index 0000000..3fd9bc6
> --- /dev/null
> +++ b/Documentation/ABI/stable/sysfs-devices-perf
> @@ -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
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Add some documentation on the perf sysfs ABI interface
2014-09-12 22:34 Andi Kleen
@ 2014-09-14 9:30 ` Peter Zijlstra
2014-09-14 15:34 ` Greg KH
2014-09-14 13:23 ` Jiri Olsa
1 sibling, 1 reply; 11+ messages in thread
From: Peter Zijlstra @ 2014-09-14 9:30 UTC (permalink / raw)
To: Andi Kleen
Cc: linux-kernel, mingo, eranian, Andi Kleen, Vince Weaver, jolsa, gregkh
On Fri, Sep 12, 2014 at 03:34:19PM -0700, Andi Kleen wrote:
> From: Andi Kleen <ak@linux.intel.com>
>
> 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.
> Cc: Vince Weaver <vincent.weaver@maine.edu>
> Cc: jolsa@redhat.com
> v2: Various fixes. Fix cmask/inv (Stephane) Fixes from Randy Dunlap.
> Signed-off-by: Andi Kleen <ak@linux.intel.com>
> ---
> Documentation/ABI/stable/sysfs-devices-perf | 98 +++++++++++++++++++++++++++++
> 1 file changed, 98 insertions(+)
> create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
>
> diff --git a/Documentation/ABI/stable/sysfs-devices-perf b/Documentation/ABI/stable/sysfs-devices-perf
> new file mode 100644
> index 0000000..3fd9bc6
> --- /dev/null
> +++ b/Documentation/ABI/stable/sysfs-devices-perf
> @@ -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)
> --
> 1.9.3
>
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH] Add some documentation on the perf sysfs ABI interface
@ 2014-09-12 22:34 Andi Kleen
2014-09-14 9:30 ` Peter Zijlstra
2014-09-14 13:23 ` Jiri Olsa
0 siblings, 2 replies; 11+ messages in thread
From: Andi Kleen @ 2014-09-12 22:34 UTC (permalink / raw)
To: peterz; +Cc: linux-kernel, mingo, eranian, Andi Kleen, Vince Weaver, jolsa
From: Andi Kleen <ak@linux.intel.com>
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 <vincent.weaver@maine.edu>
Cc: jolsa@redhat.com
v2: Various fixes. Fix cmask/inv (Stephane) Fixes from Randy Dunlap.
Signed-off-by: Andi Kleen <ak@linux.intel.com>
---
Documentation/ABI/stable/sysfs-devices-perf | 98 +++++++++++++++++++++++++++++
1 file changed, 98 insertions(+)
create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
diff --git a/Documentation/ABI/stable/sysfs-devices-perf b/Documentation/ABI/stable/sysfs-devices-perf
new file mode 100644
index 0000000..3fd9bc6
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-perf
@@ -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)
--
1.9.3
^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH] Add some documentation on the perf sysfs ABI interface
2014-09-09 17:32 Andi Kleen
2014-09-09 19:01 ` Stephane Eranian
@ 2014-09-09 20:57 ` Randy Dunlap
1 sibling, 0 replies; 11+ messages in thread
From: Randy Dunlap @ 2014-09-09 20:57 UTC (permalink / raw)
To: Andi Kleen, peterz
Cc: linux-kernel, mingo, eranian, tglx, Andi Kleen, Vince Weaver, jolsa
On 09/09/14 10:32, Andi Kleen wrote:
> From: Andi Kleen <ak@linux.intel.com>
>
> 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 <vincent.weaver@maine.edu>
> Cc: jolsa@redhat.com
> Signed-off-by: Andi Kleen <ak@linux.intel.com>
> ---
> Documentation/ABI/stable/sysfs-devices-perf | 87 +++++++++++++++++++++++++++++
> 1 file changed, 87 insertions(+)
> create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
>
> diff --git a/Documentation/ABI/stable/sysfs-devices-perf b/Documentation/ABI/stable/sysfs-devices-perf
> new file mode 100644
> index 0000000..0b00c7c
> --- /dev/null
> +++ b/Documentation/ABI/stable/sysfs-devices-perf
> @@ -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).
> +
> +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 ...
> +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.
> +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
add ending '.' above. Also: is 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
Contains a decimal number: 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)
>
--
~Randy
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Add some documentation on the perf sysfs ABI interface
2014-09-09 19:01 ` Stephane Eranian
@ 2014-09-09 20:11 ` Andi Kleen
0 siblings, 0 replies; 11+ messages in thread
From: Andi Kleen @ 2014-09-09 20:11 UTC (permalink / raw)
To: Stephane Eranian
Cc: Andi Kleen, Peter Zijlstra, LKML, Ingo Molnar, Thomas Gleixner,
Andi Kleen, Vince Weaver, Jiri Olsa
Fixed thanks.
-Andi
--
ak@linux.intel.com -- Speaking for myself only.
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Add some documentation on the perf sysfs ABI interface
2014-09-09 17:32 Andi Kleen
@ 2014-09-09 19:01 ` Stephane Eranian
2014-09-09 20:11 ` Andi Kleen
2014-09-09 20:57 ` Randy Dunlap
1 sibling, 1 reply; 11+ messages in thread
From: Stephane Eranian @ 2014-09-09 19:01 UTC (permalink / raw)
To: Andi Kleen
Cc: Peter Zijlstra, LKML, Ingo Molnar, Thomas Gleixner, Andi Kleen,
Vince Weaver, Jiri Olsa
On Tue, Sep 9, 2014 at 7:32 PM, Andi Kleen <andi@firstfloor.org> wrote:
> From: Andi Kleen <ak@linux.intel.com>
>
> 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 <vincent.weaver@maine.edu>
> Cc: jolsa@redhat.com
> Signed-off-by: Andi Kleen <ak@linux.intel.com>
> ---
> Documentation/ABI/stable/sysfs-devices-perf | 87 +++++++++++++++++++++++++++++
> 1 file changed, 87 insertions(+)
> create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
>
> diff --git a/Documentation/ABI/stable/sysfs-devices-perf b/Documentation/ABI/stable/sysfs-devices-perf
> new file mode 100644
> index 0000000..0b00c7c
> --- /dev/null
> +++ b/Documentation/ABI/stable/sysfs-devices-perf
> @@ -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.
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).
> +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).
> +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
>
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH] Add some documentation on the perf sysfs ABI interface
@ 2014-09-09 17:32 Andi Kleen
2014-09-09 19:01 ` Stephane Eranian
2014-09-09 20:57 ` Randy Dunlap
0 siblings, 2 replies; 11+ messages in thread
From: Andi Kleen @ 2014-09-09 17:32 UTC (permalink / raw)
To: peterz
Cc: linux-kernel, mingo, eranian, tglx, Andi Kleen, Vince Weaver, jolsa
From: Andi Kleen <ak@linux.intel.com>
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 <vincent.weaver@maine.edu>
Cc: jolsa@redhat.com
Signed-off-by: Andi Kleen <ak@linux.intel.com>
---
Documentation/ABI/stable/sysfs-devices-perf | 87 +++++++++++++++++++++++++++++
1 file changed, 87 insertions(+)
create mode 100644 Documentation/ABI/stable/sysfs-devices-perf
diff --git a/Documentation/ABI/stable/sysfs-devices-perf b/Documentation/ABI/stable/sysfs-devices-perf
new file mode 100644
index 0000000..0b00c7c
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-perf
@@ -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)
--
1.9.3
^ permalink raw reply related [flat|nested] 11+ messages in thread
end of thread, other threads:[~2014-09-15 22:47 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-09-15 22:47 [PATCH] Add some documentation on the perf sysfs ABI interface Andi Kleen
-- strict thread matches above, loose matches on Subject: below --
2014-09-12 22:34 Andi Kleen
2014-09-14 9:30 ` Peter Zijlstra
2014-09-14 15:34 ` Greg KH
2014-09-14 15:44 ` Andi Kleen
2014-09-14 15:53 ` Greg KH
2014-09-14 13:23 ` Jiri Olsa
2014-09-09 17:32 Andi Kleen
2014-09-09 19:01 ` Stephane Eranian
2014-09-09 20:11 ` Andi Kleen
2014-09-09 20:57 ` Randy Dunlap
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.