Re: [PATCH] Update perf tools topdown documentation

[Namhyung Kim <namhyung@kernel.org>]

Hello,

On Tue, Dec 10, 2024 at 11:35:54AM -0800, Andi Kleen wrote:
> - 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.
> 
> Signed-off-by: Andi Kleen <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..3e2340f3f78e 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)

We can check with MAP_FAILED.

Thanks,
Namhyung

>  	.... 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 resetting the perf
> +metrics automatically RDPMC, which can avoid a system call or needing
> +to schedule special resets.
> +
> +This is available if /sys/devices/cpu*/cap/metrics_clear
> +exists, and requires setting an opt-in bit when opening the 
> +slots counter:
> +
> +if (access("/sys/devices/cpu/cap/metrics_clear") &&
> +    access("/sys/devices/cpu_core/cap/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.47.1
>