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

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@gmail.com Cc: Laurent Pinchart laurent.pinchart@ideasonboard.com Signed-off-by: Daniel Vetter daniel.vetter@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>