- 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
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, 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>
--
1.8.5.2
