[PATCH 01/19] drm/doc: Clarify the dumb object interfaces
David Herrmann
dh.herrmann at gmail.com
Thu Jan 23 01:14:35 PST 2014
Hi
On Thu, Jan 23, 2014 at 9:52 AM, Daniel Vetter <daniel.vetter at ffwll.ch> 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 at ideasonboard.com>
> Signed-off-by: Daniel Vetter <daniel.vetter at 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
> @@ -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
> @@ -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. Otherwise
the patch looks fine.
Thanks
David
> </para>
> <para>
> Drivers must first validate the requested frame buffer parameters passed
> @@ -1052,6 +998,71 @@ int max_width, max_height;</synopsis>
> <function>drm_framebuffer_unregister_private</function>.
> </sect2>
> <sect2>
> + <title>Dumb GEM 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) 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 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, as has been
> + attempted on some ARM embedded platforms. Such drivers really must have
> + a hardware-specific ioctl to allocate suitable objects.
> + </para>
> + </sect2>
> + <sect2>
> <title>Output Polling</title>
> <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis>
> <para>
> --
> 1.8.5.2
>
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dri-devel
More information about the dri-devel
mailing list