Re: [PATCH] Update perf tools topdown documentation

[James Clark <james.clark@linaro.org>]

On 10/12/2024 7:35 pm, 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)
>   	.... 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

Minor nit: "automatically using RDPMC"?

Reviewed-by: James Clark <james.clark@linaro.org>

> +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
>