linux-kernel - [PATCH V5 2/2] perf doc: Update perf tools topdown documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-Id: <20241211160318.235056-2-kan.liang@linux.intel.com>
Date: Wed, 11 Dec 2024 08:03:18 -0800
From: kan.liang@...ux.intel.com
To: peterz@...radead.org,
	mingo@...hat.com,
	acme@...nel.org,
	namhyung@...nel.org,
	ak@...ux.intel.com,
	james.clark@...aro.org,
	linux-kernel@...r.kernel.org,
	linux-perf-users@...r.kernel.org
Cc: irogers@...gle.com,
	eranian@...gle.com,
	Kan Liang <kan.liang@...ux.intel.com>
Subject: [PATCH V5 2/2] perf doc: Update perf tools topdown documentation

From: Andi Kleen <ak@...ux.intel.com>

- Document and give examples for the Lunar Lake perf metrics reset mode.
- Fix the error handling for mmap (it returns -1 on error, not 0)
- Clarify the slots placement documentation. It is not Icelake specific
and also applies for non sampling.

Reviewed-by: James Clark <james.clark@...aro.org>
Reviewed-by: Kan Liang <kan.liang@...ux.intel.com>
Signed-off-by: Andi Kleen <ak@...ux.intel.com>
---

The doc update patch is originally from
https://lore.kernel.org/linux-perf-users/20241210193554.93013-1-ak@linux.intel.com/

 tools/perf/Documentation/topdown.txt | 33 +++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/tools/perf/Documentation/topdown.txt b/tools/perf/Documentation/topdown.txt
index 5c17fff694ee..44644e917ffd 100644
--- a/tools/perf/Documentation/topdown.txt
+++ b/tools/perf/Documentation/topdown.txt
@@ -87,7 +87,7 @@ if (slots_fd < 0)
 
 /* Memory mapping the fd permits _rdpmc calls from userspace */
 void *slots_p = mmap(0, getpagesize(), PROT_READ, MAP_SHARED, slots_fd, 0);
-if (!slot_p)
+if (slot_p == (void*)-1L)
 	.... error ...
 
 /*
@@ -107,7 +107,7 @@ if (metrics_fd < 0)
 
 /* Memory mapping the fd permits _rdpmc calls from userspace */
 void *metrics_p = mmap(0, getpagesize(), PROT_READ, MAP_SHARED, metrics_fd, 0);
-if (!metrics_p)
+if (metrics_p == (void*)-1L)
 	... error ...
 
 Note: the file descriptors returned by the perf_event_open calls must be memory
@@ -290,15 +290,38 @@ This "opens" a new measurement period.
 A program using RDPMC for TopDown should schedule such a reset
 regularly, as in every few seconds.
 
-Limits on Intel Ice Lake
-========================
+Newer Intel CPUs (Lunar Lake, Arrow Lake+) support automatically
+resetting the perf metrics RDPMC, which can avoid a system call or
+needing to schedule special resets.
+
+This is available if /sys/devices/cpu*/format/metrics_clear
+exists, and requires setting an opt-in bit when opening the
+slots counter:
+
+if (access("/sys/devices/cpu/format/metrics_clear") &&
+    access("/sys/devices/cpu_core/format/metrics_clear"))
+     ... functionality not supported ...
+
+#define INTEL_TD_CFG_METRIC_CLEAR 1ULL
+
+struct perf_event_attr slots_event = {
+	... same as slots example above ...
+	.config1 = INTEL_TD_CFG_METRIC_CLEAR,
+};
+
+... open and map counter same as example above ...
+
+Then any metric read will reset the metrics and slots.
+
+Using perf metrics with perf stat
+=================================
 
 Four pseudo TopDown metric events are exposed for the end-users,
 topdown-retiring, topdown-bad-spec, topdown-fe-bound and topdown-be-bound.
 They can be used to collect the TopDown value under the following
 rules:
 - All the TopDown metric events must be in a group with the SLOTS event.
-- The SLOTS event must be the leader of the group.
+- The SLOTS event must be the first entry of the group.
 - The PERF_FORMAT_GROUP flag must be applied for each TopDown metric
   events
 
-- 
2.38.1