Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 065a5027 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

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: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: default avatarAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
parent 786a7828

Documentation/DocBook/drm.tmpl

+72 −61
Original line number Diff line number Diff line
@@ -829,62 +829,6 @@ char *date;</synopsis> 
          faults can implement their own mmap file operation handler.

        </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>
@@ -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
@@ -1051,6 +997,71 @@ int max_width, max_height;</synopsis> 
	unload time with

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