Re: [PATCH RESEND v2] perf/headers: Document PERF_PMU_CAP capability flags

[Ian Rogers]

On Fri, Oct 10, 2025 at 8:11 PM Mi, Dapeng <dapeng1.mi@xxxxxxxxxxxxxxx> wrote:
>
>
> On 9/9/2025 7:39 PM, Nicolas Frattaroli wrote:
> > Over the years, capability flags for perf PMUs were introduced in a
> >
> > piecemeal fashion whenever a new driver needed to signal to the perf
> >
> > core some limitation or special feature.
> >
> >
> >
> > Since one more undocumented flag that can have its meaning inferred from
> >
> > the commit message and implementation never seems that bad, it's
> >
> > understandable that this resulted in a total of 11 undocumented
> >
> > capability flags, which authors of new perf PMU drivers are expected to
> >
> > set correctly for their particular device.
> >
> >
> >
> > Since I am in the process of becoming such an author of a new perf
> >
> > driver, it feels proper to pay it forward by documenting all
> >
> > PERF_PMU_CAP_ constants, so that no future person has to go through an
> >
> > hour or two of git blame + reading perf core code to figure out which
> >
> > capability flags are right for them.
> >
> >
> >
> > Add comments in kernel-doc format that describes each flag. This follows
> >
> > the somewhat verbose "Object-like macro documentation" format, and can
> >
> > be verified with
> >
> >
> >
> >       ./scripts/kernel-doc -v -none include/linux/perf_event.h
> >
> >
> >
> > The current in-tree kernel documentation does not include a page on the
> >
> > perf subsystem, but once it does, these comments should render as proper
> >
> > documentation annotation. Until then, they'll also be quite useful for
> >
> > anyone looking at the header file.
> >
> >
> >
> > Reviewed-by: James Clark <james.clark@xxxxxxxxxx>
> > Reviewed-by: Ian Rogers <irogers@xxxxxxxxxx>
> > Signed-off-by: Nicolas Frattaroli <nicolas.frattaroli@xxxxxxxxxxxxx>
> LGTM. Reviewed-by: Dapeng Mi <dapeng1.mi@xxxxxxxxxxxxxxx>

Ping.

Thanks,
Ian