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

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

Hi David,

On Thursday 23 January 2014 10:14:35 David Herrmann wrote:
> On Thu, Jan 23, 2014 at 9:52 AM, 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.
> > 
> > Cc: Laurent Pinchart laurent.pinchart@ideasonboard.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > ---
> > 
> >  Documentation/DocBook/drm.tmpl | 125 +++++++++++++++++++-----------------
> > 1 file changed, 68 insertions(+), 57 deletions(-)
> > 
> > diff --git a/Documentation/DocBook/drm.tmpl
> > b/Documentation/DocBook/drm.tmpl index ed1d6d289022..9c3fdd59c995 100644
> > --- a/Documentation/DocBook/drm.tmpl
> > +++ b/Documentation/DocBook/drm.tmpl

[snip]

> > @@ -970,7 +914,9 @@ int max_width, max_height;</synopsis>
> > 
> >          handle (or a list of memory handles for multi-planar formats)
> >          through the <parameter>drm_mode_fb_cmd2</parameter> argument.
> >          This document assumes that the driver uses GEM, those handles
> >          thus reference GEM 
> > -        objects.
> > +        objects. But drivers are free to use their own backing storage
> > object
> > +       handles, e.g. vmwgfx directly exposes special TTM handles to
> > userspace
> > +       and so expects TTM handles in the create ioctl and not GEM
> > objects.
>
> Maybe remove the sentence saying "this document assumes that the
> driver uses GEM". I don't see where we explicitly do that.

We do in one place, in the documentation of the create_handle operation. We
could apply the following change and replace the above sentence with

"For drivers using GEM those handles reference GEM objects. Drivers are
however free to use their own backing storage object handles, e.g. vmwgfx
directly exposes special TTM handles to userspace and so expects TTM handles
in the create ioctl, not GEM object handles."

@@ -1010,8 +1010,8 @@ int max_width, max_height;</synopsis>
               reference the memory object associated with the first plane.
             </para>
             <para>
-              Drivers call <function>drm_gem_handle_create</function> to create
-              the handle.
+              GEM-aware drivers call <function>drm_gem_handle_create</function> to
+              create the handle.
             </para>
           </listitem>
           <listitem>

> Otherwise the patch looks fine.

-- 
Regards,

Laurent Pinchart