Re: [PATCH v3 1/2] perf/docs: Add info on AMD raw event encoding

[kajoljain <kjain@linux.ibm.com>]

On 11/23/21 2:16 PM, Sandipan Das wrote:
> AMD processors have events with event select codes and unit
> masks larger than a byte. The core PMU, for example, uses
> 12-bit event select codes split between bits 0-7 and 32-35
> of the PERF_CTL MSRs as can be seen from
> /sys/bus/event_sources/devices/cpu/format/*.

Patch looks good to me.

Reviewed-by: Kajol Jain<kjain@linux.ibm.com>

Thanks,
Kajol Jain

> 
> The Processor Programming Reference (PPR) lists the event
> codes as unified 12-bit hexadecimal values instead and the
> split between the bits is not apparent to someone who is
> not aware of the layout of the PERF_CTL MSRs.
> 
> 8-bit event select codes continue to work as the layout
> matches that of the PERF_CTL MSRs i.e. bits 0-7 for event
> select and 8-15 for unit mask.
> 
> This adds more details in the perf man pages about using
> /sys/bus/event_sources/devices/*/format/* for determining
> the correct raw event encoding scheme.
> 
> E.g. the "op_cache_hit_miss.op_cache_hit" event with code
> 0x28f and umask 0x03 can be programmed using its symbolic
> name as:
> 
>   $ sudo perf --debug perf-event-open stat -e op_cache_hit_miss.op_cache_hit sleep 1
>   ------------------------------------------------------------
>   perf_event_attr:
>     type                             4
>     size                             128
>     config                           0x20000038f
>     sample_type                      IDENTIFIER
>     read_format                      TOTAL_TIME_ENABLED|TOTAL_TIME_RUNNING
>     disabled                         1
>     inherit                          1
>     enable_on_exec                   1
>     exclude_guest                    1
>   ------------------------------------------------------------
>   [...]
> 
> One might use a simple eventsel+umask combination based on
> what the current man pages say and incorrectly program the
> event as:
> 
>   $ sudo perf --debug perf-event-open stat -e r0328f sleep 1
>   ------------------------------------------------------------
>   perf_event_attr:
>     type                             4
>     size                             128
>     config                           0x328f
>     sample_type                      IDENTIFIER
>     read_format                      TOTAL_TIME_ENABLED|TOTAL_TIME_RUNNING
>     disabled                         1
>     inherit                          1
>     enable_on_exec                   1
>     exclude_guest                    1
>   ------------------------------------------------------------
>   [...]
> 
> When it should have been based on the format from sysfs:
> 
>   $ cat /sys/bus/event_source/devices/cpu/format/event
>   config:0-7,32-35
> 
>   $ sudo perf --debug perf-event-open stat -e r20000038f sleep 1
>   ------------------------------------------------------------
>   perf_event_attr:
>     type                             4
>     size                             128
>     config                           0x20000038f
>     sample_type                      IDENTIFIER
>     read_format                      TOTAL_TIME_ENABLED|TOTAL_TIME_RUNNING
>     disabled                         1
>     inherit                          1
>     enable_on_exec                   1
>     exclude_guest                    1
>   ------------------------------------------------------------
>   [...]
> 
> Signed-off-by: Sandipan Das <sandipan.das@amd.com>
> ---
> v1: https://lore.kernel.org/linux-perf-users/20211119111234.170726-1-sandipan.das@amd.com/
> v2: https://lore.kernel.org/linux-perf-users/20211123065104.236717-1-sandipan.das@amd.com/
> 
> v3:
> - Mention why simple eventsel+umask combinations will not
>   work in the commit message.
> 
> ---
>  tools/perf/Documentation/perf-list.txt   | 34 +++++++++++++++++++++++-
>  tools/perf/Documentation/perf-record.txt |  6 +++--
>  tools/perf/Documentation/perf-stat.txt   |  6 +++--
>  tools/perf/Documentation/perf-top.txt    |  7 ++---
>  4 files changed, 45 insertions(+), 8 deletions(-)
> 
> diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt
> index 4dc8d0af19df..a922a95289a9 100644
> --- a/tools/perf/Documentation/perf-list.txt
> +++ b/tools/perf/Documentation/perf-list.txt
> @@ -94,7 +94,7 @@ RAW HARDWARE EVENT DESCRIPTOR
>  Even when an event is not available in a symbolic form within perf right now,
>  it can be encoded in a per processor specific way.
>  
> -For instance For x86 CPUs NNN represents the raw register encoding with the
> +For instance on x86 CPUs, N is a hexadecimal value that represents the raw register encoding with the
>  layout of IA32_PERFEVTSELx MSRs (see [Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide] Figure 30-1 Layout
>  of IA32_PERFEVTSELx MSRs) or AMD's PerfEvtSeln (see [AMD64 Architecture Programmer’s Manual Volume 2: System Programming], Page 344,
>  Figure 13-7 Performance Event-Select Register (PerfEvtSeln)).
> @@ -126,6 +126,38 @@ It's also possible to use pmu syntax:
>   perf record -e cpu/r1a8/ ...
>   perf record -e cpu/r0x1a8/ ...
>  
> +Some processors, like those from AMD, support event codes and unit masks
> +larger than a byte. In such cases, the bits corresponding to the event
> +configuration parameters can be seen with:
> +
> +  cat /sys/bus/event_source/devices/<pmu>/format/<config>
> +
> +Example:
> +
> +If the AMD docs for an EPYC 7713 processor describe an event as:
> +
> +  Event  Umask  Event Mask
> +  Num.   Value  Mnemonic                        Description
> +
> +  28FH     03H  op_cache_hit_miss.op_cache_hit  Counts Op Cache micro-tag
> +                                                hit events.
> +
> +raw encoding of 0x0328F cannot be used since the upper nibble of the
> +EventSelect bits have to be specified via bits 32-35 as can be seen with:
> +
> +  cat /sys/bus/event_source/devices/cpu/format/event
> +
> +raw encoding of 0x20000038F should be used instead:
> +
> + perf stat -e r20000038f -a sleep 1
> + perf record -e r20000038f ...
> +
> +It's also possible to use pmu syntax:
> +
> + perf record -e r20000038f -a sleep 1
> + perf record -e cpu/r20000038f/ ...
> + perf record -e cpu/r0x20000038f/ ...
> +
>  You should refer to the processor specific documentation for getting these
>  details. Some of them are referenced in the SEE ALSO section below.
>  
> diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
> index 3cf7bac67239..55df7b073a55 100644
> --- a/tools/perf/Documentation/perf-record.txt
> +++ b/tools/perf/Documentation/perf-record.txt
> @@ -30,8 +30,10 @@ OPTIONS
>  
>          - 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 raw PMU event in the form of rN where N is a hexadecimal value
> +          that represents the raw register encoding with the layout of the
> +          event control registers as described by entries in
> +          /sys/bus/event_sources/devices/cpu/format/*.
>  
>          - a symbolic or raw PMU event followed by an optional colon
>  	  and a list of event modifiers, e.g., cpu-cycles:p.  See the
> diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt
> index 7e6fb7cbc0f4..604e6f2301ea 100644
> --- a/tools/perf/Documentation/perf-stat.txt
> +++ b/tools/perf/Documentation/perf-stat.txt
> @@ -36,8 +36,10 @@ report::
>  
>  	- 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 raw PMU event in the form of rN where N is a hexadecimal value
> +	  that represents the raw register encoding with the layout of the
> +	  event control registers as described by entries in
> +	  /sys/bus/event_sources/devices/cpu/format/*.
>  
>          - a symbolic or raw PMU event followed by an optional colon
>  	  and a list of event modifiers, e.g., cpu-cycles:p.  See the
> diff --git a/tools/perf/Documentation/perf-top.txt b/tools/perf/Documentation/perf-top.txt
> index 9898a32b8d9c..cac3dfbee7d8 100644
> --- a/tools/perf/Documentation/perf-top.txt
> +++ b/tools/perf/Documentation/perf-top.txt
> @@ -38,9 +38,10 @@ Default is to monitor all CPUS.
>  -e <event>::
>  --event=<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.
> +	(use 'perf list' to list all events) or a raw PMU event in the form
> +	of rN where N is a hexadecimal value that represents the raw register
> +	encoding with the layout of the event control registers as described
> +	by entries in /sys/bus/event_sources/devices/cpu/format/*.
>  
>  -E <entries>::
>  --entries=<entries>::
>