[PATCH] drm/doc: Clarify the dumb object interfaces

[Daniel Vetter]

On Fri, Jan 24, 2014 at 12:13:11PM +0100, Laurent Pinchart wrote:
> Hi Daniel,
> 
> Thank you for the patch.
> 
> One last round of nitpicking (including a typo fix, which gives me an excuse 
> for a couple more comments :-)).
> 
> On Thursday 23 January 2014 14:50:25 Daniel Vetter wrote:
> > - This is _not_ a generic interface to create gem objects, but just an
> >   interface to make early boot services (like boot splash) with a
> >   generic KMS userspace driver possible. Hence it's better to move
> >   the documentation for this from the GEM section to the KMS section,
> >   next to the creation of framebuffer objects.
> > 
> > - Make it really clear that the returned handle isn't necessarily a
> >   GEM object (it can also be e.g. a TTM handle when running on top of
> >   vmwgfx).
> > 
> > - Add a paragraph to make it clear that this is just for unaccelarated
> >   userspace - gpu drivers need to have their own buffer object
> >   creation ioctl which is hardware specific.
> > 
> > v2: Clarify that the documentation doesn't just apply to GEM-based
> > drivers only but is now generally valid, as suggested by David.
> > 
> > v3: Polish the intro sentence a bit and one s/objects/handles/ for
> > clarification, both suggested by Laurent.
> > 
> > Cc: David Herrmann <dh.herrmann at gmail.com>
> > Cc: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter at ffwll.ch>
> > ---
> >  Documentation/DocBook/drm.tmpl | 129 ++++++++++++++++++++------------------
> > 1 file changed, 70 insertions(+), 59 deletions(-)
> > 
> > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> > index ed1d6d289022..767318d5ddb6 100644
> > --- a/Documentation/DocBook/drm.tmpl
> > +++ b/Documentation/DocBook/drm.tmpl
> 
> [snip]
> 
> > @@ -1052,6 +998,71 @@ int max_width, max_height;</synopsis>
> >  	<function>drm_framebuffer_unregister_private</function>.
> >      </sect2>
> >      <sect2>
> > +      <title>Dumb GEM Objects</title>
> 
> What about calling this "Dumb Memory Objects" (or something similar), as 
> they're not specific to GEM ?

I've gone through the entire section to remove all GEM-specific language
and missed the title. That's some good fail right there ;-) I'm going with
buffer objects, which I think is the most established language for gfx
memory management - GL also uses it in specs.

[snip]

> > +	attempted on some ARM embedded platforms. Such drivers really must have
> > +	a hardware-specific ioctl to allocate suitable objects.
> 
> What about s/objects/memory objects/ ? "object" alone is rather vague for 
> people not too familiar with DRM/KMS.

Also opted for buffer object here. Other suggestions applies unchaged.

Thanks, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch