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

[Arnaldo Carvalho de Melo <acme@kernel.org>]

On Thu, Sep 24, 2026 at 03:23:57PM -0700, Namhyung Kim wrote:
> 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@mail.gmail.com
> > Signed-off-by: Christian Melendez <chrismelnu@gmail.com>
> > ---
> >  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.

Since I'll need to force push due to a missing Signed-off-by in a patch
that had --- markers before the author's Signed-off-by, I'll remove the
:u.

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