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

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

[Sandipan Das]

Processors from the AMD Zen family 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/*.

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 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 "ic_tag_hit_miss.all_instruction_cache_accesses"
event with code 0x18e and umask 0x1f can be programmed
using its symbolic name as:

  $ sudo perf --debug perf-event-open stat -e ic_tag_hit_miss.all_instruction_cache_accesses sleep 1
  ------------------------------------------------------------
  perf_event_attr:
    type                             4
    size                             128
    config                           0x100001f8e
    sample_type                      IDENTIFIER
    read_format                      TOTAL_TIME_ENABLED|TOTAL_TIME_RUNNING
    disabled                         1
    inherit                          1
    enable_on_exec                   1
    exclude_guest                    1
  ------------------------------------------------------------
  [...]

In raw format, it may be programmed incorrectly as:

  $ sudo perf --debug perf-event-open stat -e r1f18e sleep 1
  ------------------------------------------------------------
  perf_event_attr:
    type                             4
    size                             128
    config                           0x1f18e
    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 r100001f8e sleep 1
  ------------------------------------------------------------
  perf_event_attr:
    type                             4
    size                             128
    config                           0x100001f8e
    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>
---
 tools/perf/Documentation/perf-list.txt   | 36 +++++++++++++++++++++++-
 tools/perf/Documentation/perf-record.txt |  6 ++--
 tools/perf/Documentation/perf-stat.txt   |  6 ++--
 tools/perf/Documentation/perf-top.txt    |  7 +++--
 4 files changed, 47 insertions(+), 8 deletions(-)

diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt
index 4dc8d0af19df..9c54c0566fda 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,40 @@ It's also possible to use pmu syntax:
  perf record -e cpu/r1a8/ ...
  perf record -e cpu/r0x1a8/ ...
 
+Some processors, like those from the AMD Zen family, 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     Comment
+
+  18EH     1FH  ic_tag_hit_miss.all_instruction_cache_accesses  Counts various  Use umask=1f to count
+                                                                IC tag related  all instruction cache
+								hit and miss    accesses
+								events
+
+raw encoding of 0x1F18E 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 0x100001F8E should be used instead:
+
+ perf stat -e r100001f8e -a sleep 1
+ perf record -e r100001f8e ...
+
+It's also possible to use pmu syntax:
+
+ perf record -e r100001f8e -a sleep 1
+ perf record -e cpu/r100001f8e/ ...
+ perf record -e cpu/r0x100001f8e/ ...
+
 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..43d945e12d97 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/<pmu>/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..0f279b5498e4 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/<pmu>/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..21028910561f 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/<pmu>/format/*.
 
 -E <entries>::
 --entries=<entries>::
-- 
2.30.2

[PATCH 2/2] perf/docs: Update link to AMD documentation

[Sandipan Das]

This updates the link to documentation on AMD processors.
The new link points to a page where users can find the
Processor Programming Reference (PPR) documents for the
family and model codes corresponding to processors they
are using.

Signed-off-by: Sandipan Das <sandipan.das@amd.com>
---
 tools/perf/Documentation/perf-list.txt | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt
index 9c54c0566fda..2f892a76c659 100644
--- a/tools/perf/Documentation/perf-list.txt
+++ b/tools/perf/Documentation/perf-list.txt
@@ -81,7 +81,11 @@ On AMD systems it is implemented using IBS (up to precise-level 2).
 The precise modifier works with event types 0x76 (cpu-cycles, CPU
 clocks not halted) and 0xC1 (micro-ops retired). Both events map to
 IBS execution sampling (IBS op) with the IBS Op Counter Control bit
-(IbsOpCntCtl) set respectively (see AMD64 Architecture Programmer’s
+(IbsOpCntCtl) set respectively (see the
+Core Complex -> Processor x86 Core -> Instruction Based Sampling (IBS)
+section of the [AMD Processor Programming Reference (PPR)] relevant to the
+family and model which the processor being used belongs to).
+
 Manual Volume 2: System Programming, 13.3 Instruction-Based
 Sampling). Examples to use IBS:
 
@@ -96,8 +100,10 @@ it can be encoded in a per processor specific way.
 
 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)).
+of IA32_PERFEVTSELx MSRs) or AMD's PERF_CTL MSRs (see the
+Core Complex (CCX) -> Processor x86 Core -> MSR Registers section of the
+[AMD Processor Programming Reference (PPR)] relevant to the family and model
+which the processor being used belongs to).
 
 Note: Only the following bit fields can be set in x86 counter
 registers: event, umask, edge, inv, cmask. Esp. guest/host only and
@@ -350,4 +356,4 @@ SEE ALSO
 linkperf:perf-stat[1], linkperf:perf-top[1],
 linkperf:perf-record[1],
 http://www.intel.com/sdm/[Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide],
-http://support.amd.com/us/Processor_TechDocs/24593_APM_v2.pdf[AMD64 Architecture Programmer’s Manual Volume 2: System Programming]
+https://www.amd.com/en/support/tech-docs/[AMD Processor Programming Reference (PPR)]
-- 
2.30.2

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

[Kim Phillips]

On 11/19/21 5:12 AM, Sandipan Das wrote:
> Processors from the AMD Zen family have events with event

It's also from prior to "Zen," possibly from the first
AMD x86 PMU incarnation.

BTW, "Zen" is a broad term to describe the new generation
of core microarchitectures.  "Family" in x86 speak usually
refers to a number, as in the Family, Model, and Stepping
number triplet.

> 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/*.
> 
> 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 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 "ic_tag_hit_miss.all_instruction_cache_accesses"
> event with code 0x18e and umask 0x1f can be programmed
> using its symbolic name as:
> 
>    $ sudo perf --debug perf-event-open stat -e ic_tag_hit_miss.all_instruction_cache_accesses sleep 1
>    ------------------------------------------------------------
>    perf_event_attr:
>      type                             4
>      size                             128
>      config                           0x100001f8e
>      sample_type                      IDENTIFIER
>      read_format                      TOTAL_TIME_ENABLED|TOTAL_TIME_RUNNING
>      disabled                         1
>      inherit                          1
>      enable_on_exec                   1
>      exclude_guest                    1
>    ------------------------------------------------------------
>    [...]
> 
> In raw format, it may be programmed incorrectly as:
> 
>    $ sudo perf --debug perf-event-open stat -e r1f18e sleep 1
>    ------------------------------------------------------------
>    perf_event_attr:
>      type                             4
>      size                             128
>      config                           0x1f18e
>      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 r100001f8e sleep 1
>    ------------------------------------------------------------
>    perf_event_attr:
>      type                             4
>      size                             128
>      config                           0x100001f8e
>      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>
> ---
>   tools/perf/Documentation/perf-list.txt   | 36 +++++++++++++++++++++++-
>   tools/perf/Documentation/perf-record.txt |  6 ++--
>   tools/perf/Documentation/perf-stat.txt   |  6 ++--
>   tools/perf/Documentation/perf-top.txt    |  7 +++--
>   4 files changed, 47 insertions(+), 8 deletions(-)
> 
> diff --git a/tools/perf/Documentation/perf-list.txt b/tools/perf/Documentation/perf-list.txt
> index 4dc8d0af19df..9c54c0566fda 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,40 @@ It's also possible to use pmu syntax:
>    perf record -e cpu/r1a8/ ...
>    perf record -e cpu/r0x1a8/ ...
>   
> +Some processors, like those from the AMD Zen family, 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     Comment
> +
> +  18EH     1FH  ic_tag_hit_miss.all_instruction_cache_accesses  Counts various  Use umask=1f to count
> +                                                                IC tag related  all instruction cache
> +								hit and miss    accesses
> +								events
> +
> +raw encoding of 0x1F18E 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 0x100001F8E should be used instead:
> +
> + perf stat -e r100001f8e -a sleep 1
> + perf record -e r100001f8e ...

Would it be better to have an example where
the most significant hex digit of the unit
mask were different from that of the triple-
digit event, so people's eyes could easily
see where each go?  I'm talking about
those two '1's..

> +It's also possible to use pmu syntax:
> +
> + perf record -e r100001f8e -a sleep 1
> + perf record -e cpu/r100001f8e/ ...
> + perf record -e cpu/r0x100001f8e/ ...
> +
>   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..43d945e12d97 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/<pmu>/format/*.

r notation is for the cpu pmu only.

>   
>           - 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..0f279b5498e4 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/<pmu>/format/*.

same here.

>           - 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..21028910561f 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/<pmu>/format/*.

and here.

Thanks,

Kim

Re: [PATCH 2/2] perf/docs: Update link to AMD documentation

[Kim Phillips]

On 11/19/21 5:12 AM, Sandipan Das wrote:
> This updates the link to documentation on AMD processors.
> The new link points to a page where users can find the
> Processor Programming Reference (PPR) documents for the
> family and model codes corresponding to processors they
> are using.

<snip>

> -http://support.amd.com/us/Processor_TechDocs/24593_APM_v2.pdf[AMD64 Architecture Programmer’s Manual Volume 2: System Programming]
> +https://www.amd.com/en/support/tech-docs/[AMD Processor Programming Reference (PPR)]

That's one of many URLs where one can find some PPRs,
and others are elsewhere on amd.com, e.g. we have
seen PPRs sprinkled in all of the below base URLs:

https://developer.amd.com/wordpress/media

https://www.amd.com/system/files/TechDocs

https://developer.amd.com/wp-content/resources/

https://support.amd.com/TechDocs/

So maybe use the bugzilla link created just for this purpose?:

https://bugzilla.kernel.org/show_bug.cgi?id=206537

Thanks,

Kim