[Intel-gfx] [PATCH 2/2] drm/doc: Add RFC section

[Rodrigo Vivi]

On Tue, Mar 23, 2021 at 02:10:17PM +0100, Daniel Vetter wrote:
> On Tue, Mar 23, 2021 at 08:37:07AM -0400, Rodrigo Vivi wrote:
> > On Tue, Mar 23, 2021 at 09:44:53AM +0100, Daniel Vetter wrote:
> > > Motivated by the pre-review process for i915 gem/gt features, but
> > > probably useful in general for complex stuff.
> > > 
> > > Cc: Jani Nikula <jani.nikula at linux.intel.com>
> > > Cc: Joonas Lahtinen <joonas.lahtinen at linux.intel.com>
> > > Cc: Rodrigo Vivi <rodrigo.vivi at intel.com>
> > > Cc: Jason Ekstrand <jason at jlekstrand.net>
> > > Cc: Dave Airlie <airlied at redhat.com>
> > > Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> > > ---
> > >  Documentation/gpu/index.rst |  1 +
> > >  Documentation/gpu/rfc.rst   | 16 ++++++++++++++++
> > >  2 files changed, 17 insertions(+)
> > >  create mode 100644 Documentation/gpu/rfc.rst
> > > 
> > > diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
> > > index c9a51e3bfb5a..df58cb826d68 100644
> > > --- a/Documentation/gpu/index.rst
> > > +++ b/Documentation/gpu/index.rst
> > > @@ -16,6 +16,7 @@ Linux GPU Driver Developer's Guide
> > >     vga-switcheroo
> > >     vgaarbiter
> > >     todo
> > > +   rfc
> > 
> > I understand the motivation here so I didn't commented earlier, but looking now,
> > I'm wondering that this section will polute the official doc...
> 
> We already have this problem between documentation meant for kernel driver
> developers and documentation meant for userspace developers around uapi
> and all that. "who is the audience here" is very ill-defined for our
> current set of docs in Documentation/gpu :-(

you have a point...

another thing that I don't like is the overhead, but otoh it forces us to
write more docs...

with all the pros and cons understood, let's move on...

Acked-by: Rodrigo Vivi <rodrigo.vivi at intel.com>

> 
> So I agree with you, but I also don't think this will make things worse.
> -Daniel
> 
> > 
> > >  
> > >  .. only::  subproject and html
> > >  
> > > diff --git a/Documentation/gpu/rfc.rst b/Documentation/gpu/rfc.rst
> > > new file mode 100644
> > > index 000000000000..9d0ff2921af8
> > > --- /dev/null
> > > +++ b/Documentation/gpu/rfc.rst
> > > @@ -0,0 +1,16 @@
> > > +===============
> > > +GPU RFC Section
> > > +===============
> > > +
> > > +For complex work, especially new uapi, it is often good to nail the high level
> > > +design issues before getting lost in the code details. This section is meant to
> > > +host such documentation:
> > > +
> > > +* Each RFC should be a section in this file, explaining the goal and main design
> > > +  considerations.
> > > +
> > > +* For uapi structures add a file to this directory with and then pull the
> > > +  kerneldoc in like with real uapi headers.
> > > +
> > > +* Once the code has landed move all the documentation to the right places in
> > > +  the main core, helper or driver sections.
> > > -- 
> > > 2.31.0
> > > 
> 
> -- 
> Daniel Vetter
> Software Engineer, Intel Corporation
> http://blog.ffwll.ch