Commit 4edb117e authored by Sandipan Das's avatar Sandipan Das Committed by Arnaldo Carvalho de Melo
Browse files

perf docs: Add info on AMD raw event encoding 



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/*.

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
  ------------------------------------------------------------
  [...]

Reviewed-by: default avatarKajol Jain <kjain@linux.ibm.com>
Signed-off-by: default avatarSandipan Das <sandipan.das@amd.com>
Acked-by: default avatarJiri Olsa <jolsa@redhat.com>
Cc: Ananth Narayan <ananth.narayan@amd.com>
Cc: Kim Phillips <kim.phillips@amd.com>
Cc: Ravi Bangoria <ravi.bangoria@amd.com>
Cc: Robert Richter <rrichter@amd.com>
Cc: Santosh Shukla <santosh.shukla@amd.com>
Link: https://lore.kernel.org/r/20211123084613.243792-1-sandipan.das@amd.com


Signed-off-by: default avatarArnaldo Carvalho de Melo <acme@redhat.com>
parent a7f3713f

tools/perf/Documentation/perf-list.txt

+33 −1
Original line number Diff line number Diff line
@@ -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.

tools/perf/Documentation/perf-record.txt

+4 −2
Original line number Diff line number Diff line
@@ -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

tools/perf/Documentation/perf-stat.txt

+4 −2
Original line number Diff line number Diff line
@@ -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

tools/perf/Documentation/perf-top.txt

+4 −3
Original line number Diff line number Diff line
@@ -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>::