summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2019-06-20 14:46:15 +0200
committerDaniel Vetter <daniel.vetter@ffwll.ch>2019-06-21 11:48:09 +0200
commit805dc614d58a8fb069ed079005e591247df85246 (patch)
treecde126f87592f827771b75cf690e8f4fd2e33e48 /Documentation
parentb283e92a2315f9368dda010c9633183147fe87e0 (diff)
drm/prime: Update docs
Yes this is a bit a big patch, but since it's essentially a complete rewrite of all the prime docs I didn't see how to better split it up. Changes: - Consistently point to drm_gem_object_funcs as the preferred hooks, where applicable. - Document all the hooks in &drm_driver that lacked kerneldoc. - Completely new overview section, which now also includes the cleaned up lifetime/reference counting subchapter. I also mentioned the weak references in there due to the lookup caches. - Completely rewritten helper intro section, highlight the import/export related functionality. - Polish for all the functions and more cross references. I also sprinkled a bunch of todos all over. Most important: 0 code changes in here. The cleanup motivated by reading and improving all this will follow later on. v2: Actually update the prime helper docs. Plus add a few FIXMEs that I won't address right away in subsequent cleanup patches. v3: - Split out the function moving. This patch is now exclusively documentation changes. - Typos and nits (Sam). v4: Polish suggestions from Noralf. Acked-by: Gerd Hoffmann <kraxel@redhat.com> Acked-by: Emil Velikov <emil.velikov@collabora.com> Acked-by: Noralf Trønnes <noralf@tronnes.org> Cc: Thomas Zimmermann <tzimmermann@suse.de> Cc: Gerd Hoffmann <kraxel@redhat.com> Cc: Noralf Trønnes <noralf@tronnes.org> Cc: Sam Ravnborg <sam@ravnborg.org> Cc: Eric Anholt <eric@anholt.net> Cc: Emil Velikov <emil.l.velikov@gmail.com> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Link: https://patchwork.freedesktop.org/patch/msgid/20190620124615.24434-1-daniel.vetter@ffwll.ch
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/gpu/drm-mm.rst40
1 files changed, 4 insertions, 36 deletions
diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index c8ebd4f66a6a..b664f054c259 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -433,43 +433,11 @@ 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.
-Overview and Driver Interface
------------------------------
+Overview and Lifetime Rules
+---------------------------
-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.
-
-Drivers that support the PRIME API must set the DRIVER_PRIME bit in the
-struct :c:type:`struct drm_driver <drm_driver>`
-driver_features field, and implement the prime_handle_to_fd and
-prime_fd_to_handle operations.
-
-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); 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 unsigned
-integers.
-
-While non-GEM drivers must implement the operations themselves, GEM
-drivers must use the :c:func:`drm_gem_prime_handle_to_fd()` and
-:c:func:`drm_gem_prime_fd_to_handle()` helper functions. Those
-helpers rely on the driver gem_prime_export and gem_prime_import
-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).
-
-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); These two operations are mandatory for GEM drivers that
-support PRIME.
+.. kernel-doc:: drivers/gpu/drm/drm_prime.c
+ :doc: overview and lifetime rules
PRIME Helper Functions
----------------------