[v6,3/4] perf Documentation: add event parameters

From: Cody P Schafer <cody@linux.vnet.ibm.com>

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.

Changelog[v6]
	Update event description to explain how required parameters
	are displayed.

CC: Sukadev Bhattiprolu <sukadev@linux.vnet.ibm.com>
CC: Haren Myneni <hbabu@us.ibm.com>
CC: Cody P Schafer <dev@codyps.com>
Signed-off-by: Cody P Schafer <cody@linux.vnet.ibm.com>
---
 Documentation/ABI/testing/sysfs-bus-event_source-devices-events | 6 ++++++
 1 file changed, 6 insertions(+)

On Sun, Dec 21, 2014 at 11:49:26PM -0800, Sukadev Bhattiprolu wrote:
> From: Cody P Schafer <cody@linux.vnet.ibm.com>
> 
> 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.
> 
> Changelog[v6]
> 	Update event description to explain how required parameters
> 	are displayed.
> 
> CC: Sukadev Bhattiprolu <sukadev@linux.vnet.ibm.com>
> CC: Haren Myneni <hbabu@us.ibm.com>
> CC: Cody P Schafer <dev@codyps.com>
> Signed-off-by: Cody P Schafer <cody@linux.vnet.ibm.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-event_source-devices-events | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> index 20979f8..47ad2a1 100644
> --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> @@ -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,core=?
>  
>  		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 "?" 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.

I see.. here's the glitch ;-) I thought we agreed on forcing '?'
as the value for param events, not 'All non-numerical values'

thanks,
jirka

Jiri Olsa [jolsa@redhat.com] wrote:
| On Sun, Dec 21, 2014 at 11:49:26PM -0800, Sukadev Bhattiprolu wrote:
| > From: Cody P Schafer <cody@linux.vnet.ibm.com>
| > +		In the case of the last example, a value replacing "?" 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.
| 
| I see.. here's the glitch ;-) I thought we agreed on forcing '?'
| as the value for param events, not 'All non-numerical values'

Yes, it is currently more broad than needed, but it is not really
user input - we are just parsing sysfs entries that developer specified
in the kernel. If necessary, we can tighten that independently ?
| 
| thanks,
| jirka

On Mon, Dec 22, 2014 at 11:34:36AM -0800, Sukadev Bhattiprolu wrote:
> Jiri Olsa [jolsa@redhat.com] wrote:
> | On Sun, Dec 21, 2014 at 11:49:26PM -0800, Sukadev Bhattiprolu wrote:
> | > From: Cody P Schafer <cody@linux.vnet.ibm.com>
> | > +		In the case of the last example, a value replacing "?" 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.
> | 
> | I see.. here's the glitch ;-) I thought we agreed on forcing '?'
> | as the value for param events, not 'All non-numerical values'
> 
> Yes, it is currently more broad than needed, but it is not really
> user input - we are just parsing sysfs entries that developer specified
> in the kernel. If necessary, we can tighten that independently ?

I think it's better to tighten it up from the beginning, so when
we decide later for other string usage, we will not breake the
'current behaviour'.

Like if now we allow users (kernel pmu modules) to put anything
as param event's value, we will brake their expectations/code if
we later decide for another usage of that string value.

As Cody wrong in last version thread:
---
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.
---

thanks,
jirka