Commit 5f5a4f1e authored by James Clark's avatar James Clark Committed by Junhao He
Browse files

Documentation: arm64: Document the PMU event counting threshold feature 

mainline inclusion
from mainline-v6.8-rc1
commit bd690638e2c27dcea1d56376aa4bf3995d82ccfc
category: feature
bugzilla: https://gitee.com/openeuler/kernel/issues/I9Q7QP
CVE: NA

Reference: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/commit/?id=bd690638e2c27dcea1d56376aa4bf3995d82ccfc



--------------------------------

Add documentation for the new Perf event open parameters and
the threshold_max capability file.

Reviewed-by: default avatarAnshuman Khandual <anshuman.khandual@arm.com>
Reviewed-by: default avatarSuzuki K Poulose <suzuki.poulose@arm.com>
Acked-by: default avatarNamhyung Kim <namhyung@kernel.org>
Signed-off-by: default avatarJames Clark <james.clark@arm.com>
Link: https://lore.kernel.org/r/20231211161331.1277825-12-james.clark@arm.com


Signed-off-by: default avatarWill Deacon <will@kernel.org>
Signed-off-by: default avatarJunhao He <hejunhao3@huawei.com>
parent bb0f9534

Documentation/arch/arm64/perf.rst

+72 −0
Original line number Diff line number Diff line
@@ -164,3 +164,75 @@ and should be used to mask the upper bits as needed. 
   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/arch/arm64/tests/user-events.c

.. _tools/lib/perf/tests/test-evsel.c:

   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/lib/perf/tests/test-evsel.c



Event Counting Threshold

==========================================



Overview

--------



FEAT_PMUv3_TH (Armv8.8) permits a PMU counter to increment only on

events whose count meets a specified threshold condition. For example if

threshold_compare is set to 2 ('Greater than or equal'), and the

threshold is set to 2, then the PMU counter will now only increment by

when an event would have previously incremented the PMU counter by 2 or

more on a single processor cycle.



To increment by 1 after passing the threshold condition instead of the

number of events on that cycle, add the 'threshold_count' option to the

commandline.



How-to

------



These are the parameters for controlling the feature:



.. list-table::

   :header-rows: 1



   * - Parameter

     - Description

   * - threshold

     - Value to threshold the event by. A value of 0 means that

       thresholding is disabled and the other parameters have no effect.

   * - threshold_compare

     - | Comparison function to use, with the following values supported:

       |

       | 0: Not-equal

       | 1: Equals

       | 2: Greater-than-or-equal

       | 3: Less-than

   * - threshold_count

     - If this is set, count by 1 after passing the threshold condition

       instead of the value of the event on this cycle.



The threshold, threshold_compare and threshold_count values can be

provided per event, for example:



.. code-block:: sh



  perf stat -e stall_slot/threshold=2,threshold_compare=2/ \

            -e dtlb_walk/threshold=10,threshold_compare=3,threshold_count/



In this example the stall_slot event will count by 2 or more on every

cycle where 2 or more stalls happen. And dtlb_walk will count by 1 on

every cycle where the number of dtlb walks were less than 10.



The maximum supported threshold value can be read from the caps of each

PMU, for example:



.. code-block:: sh



  cat /sys/bus/event_source/devices/armv8_pmuv3/caps/threshold_max



  0x000000ff



If a value higher than this is given, then opening the event will result

in an error. The highest possible maximum is 4095, as the config field

for threshold is limited to 12 bits, and the Perf tool will refuse to

parse higher values.



If the PMU doesn't support FEAT_PMUv3_TH, then threshold_max will read

0, and attempting to set a threshold value will also result in an error.

threshold_max will also read as 0 on aarch32 guests, even if the host

is running on hardware with the feature.