Description of "event parameters" from the documentation patch:
Event parameters are a basic way for partial events to be specified in
sysfs with per-event names given to the fields that need to be filled in
when using a particular event.
It is intended for supporting cases where the single 'cpu' parameter is
insufficient. For example, POWER 8 has events for physical
sockets/cores/cpus that are accessible from with virtual machines. To
keep using the single 'cpu' parameter we'd need to perform a mapping
between Linux's cpus and the physical machine's cpus (in this case
Linux is running under a hypervisor). This isn't possible because
bindings between our cpus and physical cpus may not be fixed, and we
probably won't have a "cpu" on each physical cpu.
Description of the sysfs contents when events are parameterized (copied from an
included patch):
Examples:
domain=0x1,offset=0x8,starting_index=$core
In the case of the last example, a value replacing "$core" would need
to be provided by the user selecting the particular event. This is
refered to as "event parameterization". All non-numerical values
indicate an event parameter.
Notes on how perf-list displays parameterized events
PARAMETERIZED EVENTS
--------------------
Some pmu events listed by 'perf list' will be displayed with '$xyz' in
them. For example:
hv_24x7/HPM_THREAD_NAP_CCYC__PHYS_CORE,starting_index=$core/
This means that when provided as an event, a value for $core must also
be supplied. For example:
perf stat -e \
'hv_24x7/HPM_THREAD_NAP_CCYC__PHYS_CORE,starting_index=2'
...
Changelog[v5]
- [Jiri Olsa, Peter Zijlstra] Use '$arg' notation rather than ?
to indicate event parameters.
- [Michael Ellerman] Separate the kernel and tool patches in the
patchset into different patchsets.
Changelog[v4]
- [Jiri Olsa] Rebase to perf/core tree (fix small merge conflict)
Changelog[v3]
- [Jiri Olsa] Changed the event parameters are specified. If
event file specifes 'param=val' make the usage 'param=123'
rather than 'val=123'. (patch 1,2/10)
- Shortened event names using "PHYS" and "VCPU" (patch 4/10)
- Print help message if invalid parameter is specified or required
parameter is missing.
- Moved 3 patches that are unrelated to parametrized events into
a separate patchset.
- Reordered patches so code changes come first.
Changelog[v2]
- [Joe Perches, David Laight] Use beNN_to_cpu() instead of guessing
the size from type.
- Use kmem_cache_free() to free page allocated with kmem_cache_alloc().
- Rebase to recent kernel
Cody P Schafer (4):
tools/perf: support parsing parameterized events
tools/perf: extend format_alias() to include event parameters
perf Documentation: add event parameters
tools/perf: Document parameterized and symbolic events
.../testing/sysfs-bus-event_source-devices-events | 6 ++
tools/perf/Documentation/perf-list.txt | 13 +++
tools/perf/Documentation/perf-record.txt | 12 +++
tools/perf/Documentation/perf-stat.txt | 20 ++++-
tools/perf/util/parse-events.h | 1 +
tools/perf/util/pmu.c | 92 +++++++++++++++++++---
6 files changed, 128 insertions(+), 16 deletions(-)
--
1.8.3.1
@@ -89,6 +89,19 @@ raw encoding of 0x1A8 can be used: You should refer to the processor specific documentation for getting these details. Some of them are referenced in the SEE ALSO section below.+PARAMETERIZED EVENTS+--------------------++Some pmu events listed by 'perf-list' will be displayed with '$x' in them. For+example:++ hv_gpci/dtbp_ptitc,starting_index=$core/++This means that when provided as an event, a value for '$core' must+also be supplied. For example:++ perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,starting_index=0x2/' ...+ OPTIONS -------
@@ -33,6 +33,18 @@ OPTIONS - a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a hexadecimal event descriptor.+ - a symbolically formed PMU event like 'pmu/param1=0x3,param2/' where+ 'param1', 'param2', etc are defined as formats for the PMU in+ /sys/bus/event_sources/devices/<pmu>/format/*.++ - a symbolically formed event like 'pmu/config=M,config1=N,config3=K/'++ where M, N, K are numbers (in decimal, hex, octal format). Acceptable+ values for each of 'config', 'config1' and 'config2' are defined by+ corresponding entries in /sys/bus/event_sources/devices/<pmu>/format/*+ param1 and param2 are defined as formats for the PMU in:+ /sys/bus/event_sources/devices/<pmu>/format/*+ - a hardware breakpoint event in the form of '\mem:addr[:access]' where addr is the address in memory you want to break in. Access is the memory access type (read, write, execute) it can
@@ -25,10 +25,22 @@ OPTIONS -e:: --event=::- Select the PMU event. Selection can be a symbolic event name- (use 'perf list' to list all events) or a raw PMU- event (eventsel+umask) in the form of rNNN where NNN is a- hexadecimal event descriptor.+ Select the PMU event. Selection can be:++ - a symbolic event name (use 'perf list' to list all events)++ - a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a+ hexadecimal event descriptor.++ - a symbolically formed event like 'pmu/param1=0x3,param2/' where+ param1 and param2 are defined as formats for the PMU in+ /sys/bus/event_sources/devices/<pmu>/format/*++ - a symbolically formed event like 'pmu/config=M,config1=N,config2=K/'+ where M, N, K are numbers (in decimal, hex, octal format).+ Acceptable values for each of 'config', 'config1' and 'config2'+ parameters are defined by corresponding entries in+ /sys/bus/event_sources/devices/<pmu>/format/* -i:: --no-inherit::
From: Cody P Schafer <redacted>
Event parameters are a basic way for partial events to be specified in
sysfs with per-event names given to the fields that need to be filled in
when using a particular event.
It is intended for supporting cases where the single 'cpu' parameter is
insufficient. For example, POWER 8 has events for physical
sockets/cores/cpus that are accessible from with virtual machines. To
keep using the single 'cpu' parameter we'd need to perform a mapping
between Linux's cpus and the physical machine's cpus (in this case
Linux is running under a hypervisor). This isn't possible because
bindings between our cpus and physical cpus may not be fixed, and we
probably won't have a "cpu" on each physical cpu.
CC: Sukadev Bhattiprolu <redacted>
CC: Haren Myneni <redacted>
CC: Cody P Schafer <redacted>
Signed-off-by: Cody P Schafer <redacted>
---
Documentation/ABI/testing/sysfs-bus-event_source-devices-events | 6 ++++++
1 file changed, 6 insertions(+)
@@ -52,12 +52,18 @@ Description: Per-pmu performance monitoring events specific to the running syste event=0x2abc event=0x423,inv,cmask=0x3 domain=0x1,offset=0x8,starting_index=0xffff+ domain=0x1,offset=0x8,starting_index=$phys_cpu Each of the assignments indicates a value to be assigned to a particular set of bits (as defined by the format file corresponding to the <term>) in the perf_event structure passed to the perf_open syscall.+ In the case of the last example, a value replacing "$phys_cpu"+ would need to be provided by the user selecting the particular+ event. This is referred to as "event parameterization". All+ non-numerical values indicate an event parameter.+ What: /sys/bus/event_source/devices/<pmu>/events/<event>.unit Date: 2014/02/24 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
From: Cody P Schafer <redacted>
This causes `perf list pmu` to show parameters for parameterized events
like:
pmu/event_name,param1=$param1,param2=$param2/ [Kernel PMU event]
Example:
hv_24x7/HPM_TLBIE__PHYS_CORE,starting_index=$core/ [Kernel PMU event]
Changelog[v5]
[Jiri Olsa, Peter Zijlstra] Use '$' to prefix parameterized events.
Changelog[v4]
[Jiri Olsa] If the parameter for an event in sysfs is 'param=val',
have perf-list show the event as 'param=?' rather than 'val=?'.
CC: Haren Myneni <redacted>
CC: Cody P Schafer <redacted>
Signed-off-by: Cody P Schafer <redacted>
Signed-off-by: Sukadev Bhattiprolu <redacted>
---
tools/perf/util/pmu.c | 27 ++++++++++++++++++++++++++-
1 file changed, 26 insertions(+), 1 deletion(-)
@@ -810,10 +810,35 @@ void perf_pmu__set_format(unsigned long *bits, long from, long to)set_bit(b,bits);}+staticintsub_non_neg(inta,intb)+{+if(b>a)+return0;+returna-b;+}+staticchar*format_alias(char*buf,intlen,structperf_pmu*pmu,structperf_pmu_alias*alias){-snprintf(buf,len,"%s/%s/",pmu->name,alias->name);+structparse_events_term*term;+intused=snprintf(buf,len,"%s/%s",pmu->name,alias->name);++list_for_each_entry(term,&alias->terms,list)+if(term->type_val==PARSE_EVENTS__TERM_TYPE_STR)+used+=snprintf(buf+used,sub_non_neg(len,used),+",%s=$%s",term->config,+term->val.str);++if(sub_non_neg(len,used)>0){+buf[used]='/';+used++;+}+if(sub_non_neg(len,used)>0){+buf[used]='\0';+used++;+}else+buf[len-1]='\0';+returnbuf;}
From: Jiri Olsa <hidden> Date: 2014-12-04 12:45:08
On Tue, Dec 02, 2014 at 06:09:35PM -0800, Sukadev Bhattiprolu wrote:
From: Cody P Schafer <redacted>
Enable event specification like:
pmu/event_name,param1=0x1,param2=0x4/
Assuming that
/sys/bus/event_source/devices/pmu/events/event_name
Contains something like
param2=$foo,bar=1,param1=$baz
oops.. sorry to be PITA on this one.. I might have missed something
in the previous discussion but I guess I might have finally some
opinion on this ;-)
here's how I think your patchset works:
in /sys/bus/event_source/devices/pmu/events/event_name you can actually have:
param2=foo,bar=1,param1=baz
notice no '$', thats what you add later in 'perf list' output, right?
Moreover it actually does not matter whats in value 'param2=HERE',
because it's not used in the config code at all apart from the
'perf list' display processing.
So when we discussed the '$' name way, I thought it'd be like:
in /sys/bus/event_source/devices/pmu/events/event_name you have:
param2=$foo,bar=1,param1=$baz
and on command line you'd use:
pmu/event_name,foo=0x1,bar=0x4/
to assign directly to the $var, which would justify the $var
syntax I think..
anyway we could assign directly to the param term name as you do,
but I think we just need to mark the term as parametrized, like:
in /sys/bus/event_source/devices/pmu/events/event_name you have:
param2=?,bar=1,param1=?
and on command line you'd use:
pmu/event_name,param2=0x1,param1=0x4/
while the config code would check that the param substitution is
done only for terms with '?' in value, like 'param2=?' and not
for all PARSE_EVENTS__TERM_TYPE_STR type terms (as of now)
thanks,
jirka
From: Cody P Schafer <hidden> Date: 2014-12-05 23:05:33
On Thu, Dec 4, 2014 at 7:44 AM, Jiri Olsa [off-list ref] wrote:
On Tue, Dec 02, 2014 at 06:09:35PM -0800, Sukadev Bhattiprolu wrote:
quoted
From: Cody P Schafer <redacted>
Enable event specification like:
pmu/event_name,param1=0x1,param2=0x4/
Assuming that
/sys/bus/event_source/devices/pmu/events/event_name
Contains something like
param2=$foo,bar=1,param1=$baz
oops.. sorry to be PITA on this one.. I might have missed something
in the previous discussion but I guess I might have finally some
opinion on this ;-)
here's how I think your patchset works:
in /sys/bus/event_source/devices/pmu/events/event_name you can actually have:
param2=foo,bar=1,param1=baz
notice no '$', thats what you add later in 'perf list' output, right?
Moreover it actually does not matter whats in value 'param2=HERE',
because it's not used in the config code at all apart from the
'perf list' display processing.
So when we discussed the '$' name way, I thought it'd be like:
in /sys/bus/event_source/devices/pmu/events/event_name you have:
param2=$foo,bar=1,param1=$baz
and on command line you'd use:
pmu/event_name,foo=0x1,bar=0x4/
to assign directly to the $var, which would justify the $var
syntax I think..
Agreed, what you've described above sounds like a good idea.
Compared to monopolizing all strings (which is what I did when
initialy writing this), using a '$' prefix would allow less pain when
some events suddenly need non-integer parameters.
anyway we could assign directly to the param term name as you do,
but I think we just need to mark the term as parametrized, like:
in /sys/bus/event_source/devices/pmu/events/event_name you have:
param2=?,bar=1,param1=?
and on command line you'd use:
pmu/event_name,param2=0x1,param1=0x4/
while the config code would check that the param substitution is
done only for terms with '?' in value, like 'param2=?' and not
for all PARSE_EVENTS__TERM_TYPE_STR type terms (as of now)
I prefer the `foo=0x1` as mentioned previously: it makes the user
interface much less painful as we can have event-specific names for
register/hcall fields.
I'm pretty sure the code used to do this, not sure when it was removed
(haven't been following this patchset closely).
That said: I haven't fiddled with this code in a while (it's Suka's at
this point), and there might be arguments the other way on both of
those.
From: Jiri Olsa <hidden> Date: 2014-12-06 12:21:05
On Fri, Dec 05, 2014 at 06:05:26PM -0500, Cody P Schafer wrote:
On Thu, Dec 4, 2014 at 7:44 AM, Jiri Olsa [off-list ref] wrote:
quoted
On Tue, Dec 02, 2014 at 06:09:35PM -0800, Sukadev Bhattiprolu wrote:
quoted
From: Cody P Schafer <redacted>
Enable event specification like:
pmu/event_name,param1=0x1,param2=0x4/
Assuming that
/sys/bus/event_source/devices/pmu/events/event_name
Contains something like
param2=$foo,bar=1,param1=$baz
oops.. sorry to be PITA on this one.. I might have missed something
in the previous discussion but I guess I might have finally some
opinion on this ;-)
here's how I think your patchset works:
in /sys/bus/event_source/devices/pmu/events/event_name you can actually have:
param2=foo,bar=1,param1=baz
notice no '$', thats what you add later in 'perf list' output, right?
Moreover it actually does not matter whats in value 'param2=HERE',
because it's not used in the config code at all apart from the
'perf list' display processing.
So when we discussed the '$' name way, I thought it'd be like:
in /sys/bus/event_source/devices/pmu/events/event_name you have:
param2=$foo,bar=1,param1=$baz
and on command line you'd use:
pmu/event_name,foo=0x1,bar=0x4/
to assign directly to the $var, which would justify the $var
syntax I think..
Agreed, what you've described above sounds like a good idea.
Compared to monopolizing all strings (which is what I did when
initialy writing this), using a '$' prefix would allow less pain when
some events suddenly need non-integer parameters.
quoted
anyway we could assign directly to the param term name as you do,
but I think we just need to mark the term as parametrized, like:
in /sys/bus/event_source/devices/pmu/events/event_name you have:
param2=?,bar=1,param1=?
and on command line you'd use:
pmu/event_name,param2=0x1,param1=0x4/
while the config code would check that the param substitution is
done only for terms with '?' in value, like 'param2=?' and not
for all PARSE_EVENTS__TERM_TYPE_STR type terms (as of now)
I prefer the `foo=0x1` as mentioned previously: it makes the user
interface much less painful as we can have event-specific names for
register/hcall fields.
I'm pretty sure the code used to do this, not sure when it was removed
(haven't been following this patchset closely).
right, I recall seeing the 2 indirect assignments earlier,
but it was without the '$' marks
That said: I haven't fiddled with this code in a while (it's Suka's at
this point), and there might be arguments the other way on both of
those.
I guess I'm ok with both ways, maybe slightly inclined to
the '$' variable style one ;-)
jirka
Jiri Olsa [jolsa@redhat.com] wrote:
| anyway we could assign directly to the param term name as you do,
| but I think we just need to mark the term as parametrized, like:
|
| in /sys/bus/event_source/devices/pmu/events/event_name you have:
| param2=?,bar=1,param1=?
I like the idea of just using a single ? for required parameters, but
the problem I had with this approach can be seen with these two sysfs
entries:
$ cat HPM_0THRD_NON_IDLE_CCYC__PHYS_CORE
domain=0x2,offset=0xe0,starting_index=core,lpar=0x0
$ cat HPM_0THRD_NON_IDLE_CCYC__VCPU_HOME_CORE
domain=0x3,offset=0xe0,starting_index=vcpu,lpar=sibling_guest_id
The parameter 'starting_index' refers to a core in one event and vcpu in
another event. We were trying to give a hint as to what it refers to.
Given that, 'starting_index' is not very intuitive, how about discarding
starting_index and replacing with what it really means for the event and,
use a simple '?' to indicate required parameter).
$ cat HPM_0THRD_NON_IDLE_CCYC__PHYS_CORE
domain=0x2,offset=0xe0,core=?,lpar=0x0
$ cat HPM_0THRD_NON_IDLE_CCYC__VCPU_HOME_CORE
domain=0x3,offset=0xe0,vcpu=?,lpar=?
perf list shows these as:
hv_24x7/HPM_0THRD_NON_IDLE_CCYC__PHYS_CORE,core=?/
hv_24x7/HPM_0THRD_NON_IDLE_CCYC__VCPU_HOME_CHIP,vcpu=?,lpar=?/
command line would be
-e hv_24x7/HPM_0THRD_NON_IDLE_CCYC__PHYS_CORE,core=2/
or
-e hv_24x7/HPM_0THRD_NON_IDLE_CCYC__VCPU_HOME_CHIP,vcpu=2,lpar=7/
and would fail if a required parameter is missing.
This would eliminate the need for new strings like 'sibling_guest_id' (or
as Cody calls it monopolizing strings...)
Following quick patch on top of the patchset shows the changes:
From: Jiri Olsa <hidden> Date: 2014-12-08 11:00:14
On Sat, Dec 06, 2014 at 11:37:24PM -0800, Sukadev Bhattiprolu wrote:
Jiri Olsa [jolsa@redhat.com] wrote:
| anyway we could assign directly to the param term name as you do,
| but I think we just need to mark the term as parametrized, like:
|
| in /sys/bus/event_source/devices/pmu/events/event_name you have:
| param2=?,bar=1,param1=?
I like the idea of just using a single ? for required parameters, but
the problem I had with this approach can be seen with these two sysfs
entries:
$ cat HPM_0THRD_NON_IDLE_CCYC__PHYS_CORE
domain=0x2,offset=0xe0,starting_index=core,lpar=0x0
$ cat HPM_0THRD_NON_IDLE_CCYC__VCPU_HOME_CORE
domain=0x3,offset=0xe0,starting_index=vcpu,lpar=sibling_guest_id
The parameter 'starting_index' refers to a core in one event and vcpu in
another event. We were trying to give a hint as to what it refers to.
Given that, 'starting_index' is not very intuitive, how about discarding
starting_index and replacing with what it really means for the event and,
use a simple '?' to indicate required parameter).
$ cat HPM_0THRD_NON_IDLE_CCYC__PHYS_CORE
domain=0x2,offset=0xe0,core=?,lpar=0x0
$ cat HPM_0THRD_NON_IDLE_CCYC__VCPU_HOME_CORE
domain=0x3,offset=0xe0,vcpu=?,lpar=?
perf list shows these as:
hv_24x7/HPM_0THRD_NON_IDLE_CCYC__PHYS_CORE,core=?/
hv_24x7/HPM_0THRD_NON_IDLE_CCYC__VCPU_HOME_CHIP,vcpu=?,lpar=?/
command line would be
-e hv_24x7/HPM_0THRD_NON_IDLE_CCYC__PHYS_CORE,core=2/
or
-e hv_24x7/HPM_0THRD_NON_IDLE_CCYC__VCPU_HOME_CHIP,vcpu=2,lpar=7/
and would fail if a required parameter is missing.