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

Fri Jan 24 11:56:52 PST 2014

Am 24.01.2014 17:58, schrieb Daniel Vetter:

Just two typos ('said' my spellchecker...;-)

Regards,
    Dieter

> - 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.
> 
> v4: More text polish from Laurent's review.
> 
> 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 | 131 
> ++++++++++++++++++++++-------------------
>  1 file changed, 71 insertions(+), 60 deletions(-)
> 
> diff --git a/Documentation/DocBook/drm.tmpl 
> b/Documentation/DocBook/drm.tmpl
> index ed1d6d289022..67cfe184749c 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -830,62 +830,6 @@ char *date;</synopsis>
>          </para>
>        </sect3>
>        <sect3>
> -        <title>Dumb GEM Objects</title>
> -        <para>
> -          The GEM API doesn't standardize GEM objects creation and 
> leaves it to
> -          driver-specific ioctls. While not an issue for full-fledged 
> graphics
> -          stacks that include device-specific userspace components
> (in libdrm for
> -          instance), this limit makes DRM-based early boot graphics
> unnecessarily
> -          complex.
> -        </para>
> -        <para>
> -          Dumb GEM objects partly alleviate the problem by providing a 
> standard
> -          API to create dumb buffers suitable for scanout, which can
> then be used
> -          to create KMS frame buffers.
> -        </para>
> -        <para>
> -          To support dumb GEM objects drivers must implement the
> -          <methodname>dumb_create</methodname>,
> -          <methodname>dumb_destroy</methodname> and
> -          <methodname>dumb_map_offset</methodname> operations.
> -        </para>
> -        <itemizedlist>
> -          <listitem>
> -            <synopsis>int (*dumb_create)(struct drm_file *file_priv,
> struct drm_device *dev,
> -                     struct drm_mode_create_dumb *args);</synopsis>
> -            <para>
> -              The <methodname>dumb_create</methodname> operation 
> creates a GEM
> -              object suitable for scanout based on the width, height 
> and depth
> -              from the struct 
> <structname>drm_mode_create_dumb</structname>
> -              argument. It fills the argument's
> <structfield>handle</structfield>,
> -              <structfield>pitch</structfield> and
> <structfield>size</structfield>
> -              fields with a handle for the newly created GEM object
> and its line
> -              pitch and size in bytes.
> -            </para>
> -          </listitem>
> -          <listitem>
> -            <synopsis>int (*dumb_destroy)(struct drm_file *file_priv,
> struct drm_device *dev,
> -                      uint32_t handle);</synopsis>
> -            <para>
> -              The <methodname>dumb_destroy</methodname> operation
> destroys a dumb
> -              GEM object created by 
> <methodname>dumb_create</methodname>.
> -            </para>
> -          </listitem>
> -          <listitem>
> -            <synopsis>int (*dumb_map_offset)(struct drm_file
> *file_priv, struct drm_device *dev,
> -                         uint32_t handle, uint64_t 
> *offset);</synopsis>
> -            <para>
> -              The <methodname>dumb_map_offset</methodname> operation
> associates an
> -              mmap fake offset with the GEM object given by the
> handle and returns
> -              it. Drivers must use the
> -              <function>drm_gem_create_mmap_offset</function> function 
> to
> -              associate the fake offset as described in
> -              <xref linkend="drm-gem-objects-mapping"/>.
> -            </para>
> -          </listitem>
> -        </itemizedlist>
> -      </sect3>
> -      <sect3>
>          <title>Memory Coherency</title>
>          <para>
>            When mapped to the device or used in a command buffer, 
> backing pages
> @@ -968,9 +912,11 @@ int max_width, max_height;</synopsis>
>          Frame buffers rely on the underneath memory manager for
> low-level memory
>          operations. When creating a frame buffer applications pass a 
> memory
>          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.
> +	the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers 
> using
> +	GEM as their userspace buffer management interface this would be a 
> GEM
> +	handle.  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 and not GEM handles.
>        </para>
>        <para>
>          Drivers must first validate the requested frame buffer
> parameters passed
> @@ -992,7 +938,7 @@ int max_width, max_height;</synopsis>
>        </para>
> 
>        <para>
> -	The initailization of the new framebuffer instance is finalized with 
> a
> +	The initilization of the new framebuffer instance is finalized with a

=> initialization ;-)

>  	call to <function>drm_framebuffer_init</function> which takes a 
> pointer
>  	to DRM frame buffer operations (struct
>  	<structname>drm_framebuffer_funcs</structname>). Note that this 
> function
> @@ -1052,6 +998,71 @@ int max_width, max_height;</synopsis>
>  	<function>drm_framebuffer_unregister_private</function>.
>      </sect2>
>      <sect2>
> +      <title>Dumb Buffer Objects</title>
> +      <para>
> +	The KMS API doesn't standardize backing storage object creation and
> +	leaves it to driver-specific ioctls. Furthermore actually creating a
> +	buffer object even for GEM-based drivers is done through a
> +	driver-specific ioctl - GEM only has a common userspace interface for
> +	sharing and destroying objects. While not an issue for full-fledged
> +	graphics stacks that include device-specific userspace components (in
> +	libdrm for instance), this limit makes DRM-based early boot graphics
> +	unnecessarily complex.
> +      </para>
> +      <para>
> +        Dumb objects partly alleviate the problem by providing a 
> standard
> +        API to create dumb buffers suitable for scanout, which can 
> then be used
> +        to create KMS frame buffers.
> +      </para>
> +      <para>
> +        To support dumb objects drivers must implement the
> +        <methodname>dumb_create</methodname>,
> +        <methodname>dumb_destroy</methodname> and
> +        <methodname>dumb_map_offset</methodname> operations.
> +      </para>
> +      <itemizedlist>
> +        <listitem>
> +          <synopsis>int (*dumb_create)(struct drm_file *file_priv,
> struct drm_device *dev,
> +                   struct drm_mode_create_dumb *args);</synopsis>
> +          <para>
> +            The <methodname>dumb_create</methodname> operation creates 
> a driver
> +	    object (GEM or TTM handle) suitable for scanout based on the
> +	    width, height and depth from the struct
> +	    <structname>drm_mode_create_dumb</structname> argument. It fills 
> the
> +	    argument's <structfield>handle</structfield>,
> +	    <structfield>pitch</structfield> and 
> <structfield>size</structfield>
> +	    fields with a handle for the newly created object and its line
> +            pitch and size in bytes.
> +          </para>
> +        </listitem>
> +        <listitem>
> +          <synopsis>int (*dumb_destroy)(struct drm_file *file_priv,
> struct drm_device *dev,
> +                    uint32_t handle);</synopsis>
> +          <para>
> +            The <methodname>dumb_destroy</methodname> operation 
> destroys a dumb
> +            object created by <methodname>dumb_create</methodname>.
> +          </para>
> +        </listitem>
> +        <listitem>
> +          <synopsis>int (*dumb_map_offset)(struct drm_file
> *file_priv, struct drm_device *dev,
> +                       uint32_t handle, uint64_t *offset);</synopsis>
> +          <para>
> +            The <methodname>dumb_map_offset</methodname> operation
> associates an
> +            mmap fake offset with the object given by the handle and 
> returns
> +            it. Drivers must use the
> +            <function>drm_gem_create_mmap_offset</function> function 
> to
> +            associate the fake offset as described in
> +            <xref linkend="drm-gem-objects-mapping"/>.
> +          </para>
> +        </listitem>
> +      </itemizedlist>
> +      <para>
> +        Note that dumb objects may not be used for gpu accelaration,

=> acceleration

> as has been
> +	attempted on some ARM embedded platforms. Such drivers really must 
> have
> +	a hardware-specific ioctl to allocate suitable buffer objects.
> +      </para>
> +    </sect2>
> +    <sect2>
>        <title>Output Polling</title>
>        <synopsis>void (*output_poll_changed)(struct drm_device 
> *dev);</synopsis>
>        <para>