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

[Ian Rogers]

On Wed, Sep 23, 2026 at 6:52 AM Christian Melendez <chrismelnu@xxxxxxxxx> 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>

Reviewed-by: Ian Rogers <irogers@xxxxxxxxxx>

Thanks,
Ian

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