drm/doc: Clarify the dumb object interfaces

- 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.

v5: More typo fixes from Dieter.

Cc: Dieter Nützel <Dieter@nuetzel-hh.de>
Cc: David Herrmann <dh.herrmann@gmail.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

1 files changed, 72 insertions, 61 deletions

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index ed1d6d289022..f2d0f5b89194 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 initialization 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 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>
@@ -2134,7 +2145,7 @@ void intel_crt_init(struct drm_device *dev)
             set the <structfield>display_info</structfield>
             <structfield>width_mm</structfield> and
             <structfield>height_mm</structfield> fields if they haven't been set
-            already (for instance at initilization time when a fixed-size panel is
+            already (for instance at initialization time when a fixed-size panel is
             attached to the connector). The mode <structfield>width_mm</structfield>
             and <structfield>height_mm</structfield> fields are only used internally
             during EDID parsing and should not be set when creating modes manually.