Commit 251261db authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/doc: Clarify PRIME documentation 



PRIME fds aren't actually GEM fds but are (like the modeset API)
independent of the underlying buffer manager, as long as that one uses
uint32_t as handles. So move that entire section out of the GEM
section and reword it a bit to clarify which parts of PRIME are
generic, and which are the mandatory pieces for GEM drivers to
correctly implement the GEM lifetime rules. The rewording mostly
consists of not mixing up GEM, PRIME and DRM.

I've considered adding some blurbs to the GEM object lifetime section
about interactions with dma-bufs, but then dropped that. As long as
drivers use the right helpers they should have this all implemented
correctly and hence can be regarded as an implementation detail of the
PRIME/GEM helpers. So no need to confuse driver writers with those
tricky interactions.

Reviewed-by: default avatarAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
parent 2d123f46

Documentation/DocBook/drm.tmpl

+74 −51
Original line number Diff line number Diff line
@@ -698,54 +698,15 @@ char *date;</synopsis> 
          driver-specific support.

        </para>

	<para>

          Similar to global names, GEM file descriptors are also used to share GEM

          objects across processes. They offer additional security: as file

          descriptors must be explicitly sent over UNIX domain sockets to be shared

          between applications, they can't be guessed like the globally unique GEM

          names.

	  GEM also supports buffer sharing with dma-buf file descriptors through

	  PRIME. GEM-based drivers must use the provided helpers functions to

	  implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />.

	  Since sharing file descriptors is inherently more secure than the

	  easily guessable and global GEM names it is the preferred buffer

	  sharing mechanism. Sharing buffers through GEM names is only supported

	  for legacy userspace. Furthermore PRIME also allows cross-device

	  buffer sharing since it is based on dma-bufs.

	</para>

        <para>

          Drivers that support GEM file descriptors, also known as the DRM PRIME

          API, must set the DRIVER_PRIME bit in the struct

          <structname>drm_driver</structname>

          <structfield>driver_features</structfield> field, and implement the

          <methodname>prime_handle_to_fd</methodname> and

          <methodname>prime_fd_to_handle</methodname> operations.

        </para>

        <para>

          <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev,

                            struct drm_file *file_priv, uint32_t handle,

                            uint32_t flags, int *prime_fd);

  int (*prime_fd_to_handle)(struct drm_device *dev,

                            struct drm_file *file_priv, int prime_fd,

                            uint32_t *handle);</synopsis>

          Those two operations convert a handle to a PRIME file descriptor and

          vice versa. Drivers must use the kernel dma-buf buffer sharing framework

          to manage the PRIME file descriptors.

        </para>

        <para>

          While non-GEM drivers must implement the operations themselves, GEM

          drivers must use the <function>drm_gem_prime_handle_to_fd</function>

          and <function>drm_gem_prime_fd_to_handle</function> helper functions.

          Those helpers rely on the driver

          <methodname>gem_prime_export</methodname> and

          <methodname>gem_prime_import</methodname> operations to create a dma-buf

          instance from a GEM object (dma-buf exporter role) and to create a GEM

          object from a dma-buf instance (dma-buf importer role).

        </para>

        <para>

          <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev,

                                       struct drm_gem_object *obj,

                                       int flags);

  struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,

                                              struct dma_buf *dma_buf);</synopsis>

          These two operations are mandatory for GEM drivers that support DRM

          PRIME.

        </para>

        <sect4>

          <title>DRM PRIME Helper Functions Reference</title>

!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers

        </sect4>

      </sect3>

      <sect3 id="drm-gem-objects-mapping">

        <title>GEM Objects Mapping</title>
@@ -868,10 +829,10 @@ char *date;</synopsis> 
          abstracted from the client in libdrm.

        </para>

      </sect3>

      <sect2>

      <sect3>

        <title>GEM Function Reference</title>

!Edrivers/gpu/drm/drm_gem.c

      </sect2>

      </sect3>

      </sect2>

      <sect2>

	<title>VMA Offset Manager</title>
@@ -879,6 +840,68 @@ char *date;</synopsis> 
!Edrivers/gpu/drm/drm_vma_manager.c

!Iinclude/drm/drm_vma_manager.h

      </sect2>

      <sect2 id="drm-prime-support">

	<title>PRIME Buffer Sharing</title>

	<para>

	  PRIME is the cross device buffer sharing framework in drm, originally

	  created for the OPTIMUS range of multi-gpu platforms. To userspace

	  PRIME buffers are dma-buf based file descriptors.

	</para>

	<sect3>

	  <title>Overview and Driver Interface</title>

	  <para>

	    Similar to GEM global names, PRIME file descriptors are

	    also used to share buffer objects across processes. They offer

	    additional security: as file descriptors must be explicitly sent over

	    UNIX domain sockets to be shared between applications, they can't be

	    guessed like the globally unique GEM names.

	  </para>

	  <para>

	    Drivers that support the PRIME

	    API must set the DRIVER_PRIME bit in the struct

	    <structname>drm_driver</structname>

	    <structfield>driver_features</structfield> field, and implement the

	    <methodname>prime_handle_to_fd</methodname> and

	    <methodname>prime_fd_to_handle</methodname> operations.

	  </para>

	  <para>

	    <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev,

			  struct drm_file *file_priv, uint32_t handle,

			  uint32_t flags, int *prime_fd);

int (*prime_fd_to_handle)(struct drm_device *dev,

			  struct drm_file *file_priv, int prime_fd,

			  uint32_t *handle);</synopsis>

	    Those two operations convert a handle to a PRIME file descriptor and

	    vice versa. Drivers must use the kernel dma-buf buffer sharing framework

	    to manage the PRIME file descriptors. Similar to the mode setting

	    API PRIME is agnostic to the underlying buffer object manager, as

	    long as handles are 32bit unsinged integers.

	  </para>

	  <para>

	    While non-GEM drivers must implement the operations themselves, GEM

	    drivers must use the <function>drm_gem_prime_handle_to_fd</function>

	    and <function>drm_gem_prime_fd_to_handle</function> helper functions.

	    Those helpers rely on the driver

	    <methodname>gem_prime_export</methodname> and

	    <methodname>gem_prime_import</methodname> operations to create a dma-buf

	    instance from a GEM object (dma-buf exporter role) and to create a GEM

	    object from a dma-buf instance (dma-buf importer role).

	  </para>

	  <para>

	    <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev,

				     struct drm_gem_object *obj,

				     int flags);

struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,

					    struct dma_buf *dma_buf);</synopsis>

	    These two operations are mandatory for GEM drivers that support

	    PRIME.

	  </para>

	</sect3>

        <sect3>

          <title>PRIME Helper Functions Reference</title>

!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers

        </sect3>

      </sect2>

  </sect1>



  <!-- Internals: mode setting -->

CRA Git | Maintained and supported by SUSTech CRA and CCSE