Re: [PATCH] perf stat: document task-clock/cpu-clock in TIMINGS

[Namhyung Kim]

Hello,

On Wed, Sep 23, 2026 at 03:51:40PM +0200, Christian Melendez wrote:
> task-clock/cpu-clock appear in perf stat's own example output but
> were never explained in perf-stat.txt, unlike time elapsed/user/sys.
> This came up unanswered on the list in 2013 and 2015 without docs
> ever being added.
> 
> Link: https://patch.msgid.link/CAP-5=fV0-yvc68BUSKoSajHjHY_A6COgbEJYiFxRg+G-8LeJhQ@xxxxxxxxxxxxxx
> Signed-off-by: Christian Melendez <chrismelnu@xxxxxxxxx>
> ---
>  tools/perf/Documentation/perf-stat.txt | 12 +++++++++++-
>  1 file changed, 11 insertions(+), 1 deletion(-)
> 
> diff --git a/tools/perf/Documentation/perf-stat.txt b/tools/perf/Documentation/perf-stat.txt
> index f334aabdc809..c0d6c344f9eb 100644
> --- a/tools/perf/Documentation/perf-stat.txt
> +++ b/tools/perf/Documentation/perf-stat.txt
> @@ -621,6 +621,16 @@ user/system lands:
>  
>  Those times are the very same as displayed by the 'time' tool.
>  
> +We also display a clock-based timing metric that depends on the
> +target being monitored:
> +
> +        83723.452481      task-clock:u (msec)       #    1.004 CPUs utilized

I'm afraid task-clock and any other software events don't support
privilege filters or modifiers.  So task-clock:u would be same as
task-clock, but it can give a wrong idea that it only measured time
in userspace.

Maybe the kernel can reject ones with modifiers but then it would have
a compatibility issue. :(

So I think it's better to remove the ":u" modifier in the example
output.  Probably we need to change the perf not to add it to the
software events.

Thanks,
Namhyung

> +
> +For a single task, task-clock reports a clock count specific to that
> +task. When the target is a CPU or the whole system (-a or -C),
> +cpu-clock is reported instead. cpu-clock is a high-resolution per-CPU
> +timer. See perf_event_open(2) for more details.
> +
>  CSV FORMAT
>  ----------
>  
> @@ -671,4 +681,4 @@ that can be used for parsing.
>  
>  SEE ALSO
>  --------
> -linkperf:perf-top[1], linkperf:perf-list[1]
> +linkperf:perf-top[1], linkperf:perf-list[1], perf_event_open(2)
> -- 
> 2.34.1
>