Re: [Intel-xe] [PATCH 01/10] drm/xe/oa: Introduce OA uapi

[Rodrigo Vivi <rodrigo.vivi@intel.com>]

On Thu, Aug 31, 2023 at 01:12:52PM -0700, Dixit, Ashutosh wrote:
> On Thu, 31 Aug 2023 12:55:14 -0700, Rodrigo Vivi wrote:
> >
> 
> Hi Rodrigo,
> 
> > On Tue, Aug 22, 2023 at 10:31:06AM +0200, Francois Dugast wrote:
> > > Hi Ashutosh,
> > >
> > > On Mon, Aug 07, 2023 at 06:31:50PM -0700, Ashutosh Dixit wrote:
> > > > OA uapi allows userspace to:
> > > > * Read streams of performance counters written by hardware
> > > > * Configure (and reconfigure) which sets of perf counters are captured as
> > > >   part of OA streams
> > > > * Configure other properties (such as format and periodicity) of such
> > > >   captures.
> > > > * Query associated parameters such as OA unit timestamp freq, oa_unit_id's
> > > >   for hw engines and OA ioctl version
> > >
> > > Please document the uapi structures, not only their members. Also it would
> > > be nice to explicit somewhere what OA stands for, maybe in the commit
> > > message as well.
> >
> > Besides that, we need true API like documentation with examples showing
> > how this is used. Please!
> 
> Sorry, not following. What sort of "examples"? Are there similar examples
> in xe_drm.h, could you please point them out so we know what to add. Or you
> mean examples outside xe_drm.h, e.g. in Documentation/ e.g.?
> 
> The IGT series was also posted along with the kernel series here:
> 
> 	https://patchwork.freedesktop.org/series/121082/
> 
> That has plenty of examples but probably that's not what you mean?

I know we are really far from having a good API documentation in general,
not just in xe or not just xe and i915...
But a good API documentation would target any developer willing to create
a new user space component and use that API, even without having to
look to IGT or other UMD drivers. So good examples in the documentation
would be important.

I believe a good example is the PXP doc in i915 section:
https://docs.kernel.org/gpu/driver-uapi.html

> 
> Thanks.
> --
> Ashutosh