Commit 805dc614 authored by Daniel Vetter's avatar Daniel Vetter

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: default avatarGerd Hoffmann <kraxel@redhat.com>
Acked-by: default avatarEmil Velikov <emil.velikov@collabora.com>
Acked-by: default avatarNoralf 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: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190620124615.24434-1-daniel.vetter@ffwll.ch
parent b283e92a
...@@ -433,43 +433,11 @@ PRIME is the cross device buffer sharing framework in drm, originally ...@@ -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 created for the OPTIMUS range of multi-gpu platforms. To userspace PRIME
buffers are dma-buf based file descriptors. 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 .. kernel-doc:: drivers/gpu/drm/drm_prime.c
share buffer objects across processes. They offer additional security: :doc: overview and lifetime rules
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.
PRIME Helper Functions PRIME Helper Functions
---------------------- ----------------------
......
This diff is collapsed.
...@@ -502,21 +502,25 @@ struct drm_driver { ...@@ -502,21 +502,25 @@ struct drm_driver {
* @gem_free_object: deconstructor for drm_gem_objects * @gem_free_object: deconstructor for drm_gem_objects
* *
* This is deprecated and should not be used by new drivers. Use * This is deprecated and should not be used by new drivers. Use
* @gem_free_object_unlocked instead. * &drm_gem_object_funcs.free instead.
*/ */
void (*gem_free_object) (struct drm_gem_object *obj); void (*gem_free_object) (struct drm_gem_object *obj);
/** /**
* @gem_free_object_unlocked: deconstructor for drm_gem_objects * @gem_free_object_unlocked: deconstructor for drm_gem_objects
* *
* This is for drivers which are not encumbered with &drm_device.struct_mutex * This is deprecated and should not be used by new drivers. Use
* legacy locking schemes. Use this hook instead of @gem_free_object. * &drm_gem_object_funcs.free instead.
* Compared to @gem_free_object this is not encumbered with
* &drm_device.struct_mutex legacy locking schemes.
*/ */
void (*gem_free_object_unlocked) (struct drm_gem_object *obj); void (*gem_free_object_unlocked) (struct drm_gem_object *obj);
/** /**
* @gem_open_object: * @gem_open_object:
* *
* This callback is deprecated in favour of &drm_gem_object_funcs.open.
*
* Driver hook called upon gem handle creation * Driver hook called upon gem handle creation
*/ */
int (*gem_open_object) (struct drm_gem_object *, struct drm_file *); int (*gem_open_object) (struct drm_gem_object *, struct drm_file *);
...@@ -524,6 +528,8 @@ struct drm_driver { ...@@ -524,6 +528,8 @@ struct drm_driver {
/** /**
* @gem_close_object: * @gem_close_object:
* *
* This callback is deprecated in favour of &drm_gem_object_funcs.close.
*
* Driver hook called upon gem handle release * Driver hook called upon gem handle release
*/ */
void (*gem_close_object) (struct drm_gem_object *, struct drm_file *); void (*gem_close_object) (struct drm_gem_object *, struct drm_file *);
...@@ -531,6 +537,9 @@ struct drm_driver { ...@@ -531,6 +537,9 @@ struct drm_driver {
/** /**
* @gem_print_info: * @gem_print_info:
* *
* This callback is deprecated in favour of
* &drm_gem_object_funcs.print_info.
*
* If driver subclasses struct &drm_gem_object, it can implement this * If driver subclasses struct &drm_gem_object, it can implement this
* optional hook for printing additional driver specific info. * optional hook for printing additional driver specific info.
* *
...@@ -545,56 +554,120 @@ struct drm_driver { ...@@ -545,56 +554,120 @@ struct drm_driver {
/** /**
* @gem_create_object: constructor for gem objects * @gem_create_object: constructor for gem objects
* *
* Hook for allocating the GEM object struct, for use by core * Hook for allocating the GEM object struct, for use by the CMA and
* helpers. * SHMEM GEM helpers.
*/ */
struct drm_gem_object *(*gem_create_object)(struct drm_device *dev, struct drm_gem_object *(*gem_create_object)(struct drm_device *dev,
size_t size); size_t size);
/* prime: */
/** /**
* @prime_handle_to_fd: * @prime_handle_to_fd:
* *
* export handle -> fd (see drm_gem_prime_handle_to_fd() helper) * Main PRIME export function. Should be implemented with
* drm_gem_prime_handle_to_fd() for GEM based drivers.
*
* For an in-depth discussion see :ref:`PRIME buffer sharing
* documentation <prime_buffer_sharing>`.
*/ */
int (*prime_handle_to_fd)(struct drm_device *dev, struct drm_file *file_priv, int (*prime_handle_to_fd)(struct drm_device *dev, struct drm_file *file_priv,
uint32_t handle, uint32_t flags, int *prime_fd); uint32_t handle, uint32_t flags, int *prime_fd);
/** /**
* @prime_fd_to_handle: * @prime_fd_to_handle:
* *
* import fd -> handle (see drm_gem_prime_fd_to_handle() helper) * Main PRIME import function. Should be implemented with
* drm_gem_prime_fd_to_handle() for GEM based drivers.
*
* For an in-depth discussion see :ref:`PRIME buffer sharing
* documentation <prime_buffer_sharing>`.
*/ */
int (*prime_fd_to_handle)(struct drm_device *dev, struct drm_file *file_priv, int (*prime_fd_to_handle)(struct drm_device *dev, struct drm_file *file_priv,
int prime_fd, uint32_t *handle); int prime_fd, uint32_t *handle);
/** /**
* @gem_prime_export: * @gem_prime_export:
* *
* export GEM -> dmabuf * Export hook for GEM drivers. Deprecated in favour of
* * &drm_gem_object_funcs.export.
* This defaults to drm_gem_prime_export() if not set.
*/ */
struct dma_buf * (*gem_prime_export)(struct drm_device *dev, struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
struct drm_gem_object *obj, int flags); struct drm_gem_object *obj, int flags);
/** /**
* @gem_prime_import: * @gem_prime_import:
* *
* import dmabuf -> GEM * Import hook for GEM drivers.
* *
* This defaults to drm_gem_prime_import() if not set. * This defaults to drm_gem_prime_import() if not set.
*/ */
struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
struct dma_buf *dma_buf); struct dma_buf *dma_buf);
/**
* @gem_prime_pin:
*
* Deprecated hook in favour of &drm_gem_object_funcs.pin.
*/
int (*gem_prime_pin)(struct drm_gem_object *obj); int (*gem_prime_pin)(struct drm_gem_object *obj);
/**
* @gem_prime_unpin:
*
* Deprecated hook in favour of &drm_gem_object_funcs.unpin.
*/
void (*gem_prime_unpin)(struct drm_gem_object *obj); void (*gem_prime_unpin)(struct drm_gem_object *obj);
/**
* @gem_prime_get_sg_table:
*
* Deprecated hook in favour of &drm_gem_object_funcs.get_sg_table.
*/
struct sg_table *(*gem_prime_get_sg_table)(struct drm_gem_object *obj);
/**
* @gem_prime_res_obj:
*
* Optional hook to look up the &reservation_object for an buffer when
* exporting it.
*
* FIXME: This hook is deprecated. Users of this hook should be replaced
* by setting &drm_gem_object.resv instead.
*/
struct reservation_object * (*gem_prime_res_obj)( struct reservation_object * (*gem_prime_res_obj)(
struct drm_gem_object *obj); struct drm_gem_object *obj);
struct sg_table *(*gem_prime_get_sg_table)(struct drm_gem_object *obj);
/**
* @gem_prime_import_sg_table:
*
* Optional hook used by the PRIME helper functions
* drm_gem_prime_import() respectively drm_gem_prime_import_dev().
*/
struct drm_gem_object *(*gem_prime_import_sg_table)( struct drm_gem_object *(*gem_prime_import_sg_table)(
struct drm_device *dev, struct drm_device *dev,
struct dma_buf_attachment *attach, struct dma_buf_attachment *attach,
struct sg_table *sgt); struct sg_table *sgt);
/**
* @gem_prime_vmap:
*
* Deprecated vmap hook for GEM drivers. Please use
* &drm_gem_object_funcs.vmap instead.
*/
void *(*gem_prime_vmap)(struct drm_gem_object *obj); void *(*gem_prime_vmap)(struct drm_gem_object *obj);
/**
* @gem_prime_vunmap:
*
* Deprecated vunmap hook for GEM drivers. Please use
* &drm_gem_object_funcs.vunmap instead.
*/
void (*gem_prime_vunmap)(struct drm_gem_object *obj, void *vaddr); void (*gem_prime_vunmap)(struct drm_gem_object *obj, void *vaddr);
/**
* @gem_prime_mmap:
*
* mmap hook for GEM drivers, used to implement dma-buf mmap in the
* PRIME helpers.
*
* FIXME: There's way too much duplication going on here, and also moved
* to &drm_gem_object_funcs.
*/
int (*gem_prime_mmap)(struct drm_gem_object *obj, int (*gem_prime_mmap)(struct drm_gem_object *obj,
struct vm_area_struct *vma); struct vm_area_struct *vma);
...@@ -662,6 +735,9 @@ struct drm_driver { ...@@ -662,6 +735,9 @@ struct drm_driver {
/** /**
* @gem_vm_ops: Driver private ops for this object * @gem_vm_ops: Driver private ops for this object
*
* For GEM drivers this is deprecated in favour of
* &drm_gem_object_funcs.vm_ops.
*/ */
const struct vm_operations_struct *gem_vm_ops; const struct vm_operations_struct *gem_vm_ops;
......
...@@ -101,7 +101,7 @@ struct drm_gem_object_funcs { ...@@ -101,7 +101,7 @@ struct drm_gem_object_funcs {
/** /**
* @pin: * @pin:
* *
* Pin backing buffer in memory. * Pin backing buffer in memory. Used by the drm_gem_map_attach() helper.
* *
* This callback is optional. * This callback is optional.
*/ */
...@@ -110,7 +110,7 @@ struct drm_gem_object_funcs { ...@@ -110,7 +110,7 @@ struct drm_gem_object_funcs {
/** /**
* @unpin: * @unpin:
* *
* Unpin backing buffer. * Unpin backing buffer. Used by the drm_gem_map_detach() helper.
* *
* This callback is optional. * This callback is optional.
*/ */
...@@ -120,16 +120,21 @@ struct drm_gem_object_funcs { ...@@ -120,16 +120,21 @@ struct drm_gem_object_funcs {
* @get_sg_table: * @get_sg_table:
* *
* Returns a Scatter-Gather table representation of the buffer. * Returns a Scatter-Gather table representation of the buffer.
* Used when exporting a buffer. * Used when exporting a buffer by the drm_gem_map_dma_buf() helper.
* Releasing is done by calling dma_unmap_sg_attrs() and sg_free_table()
* in drm_gem_unmap_buf(), therefore these helpers and this callback
* here cannot be used for sg tables pointing at driver private memory
* ranges.
* *
* This callback is mandatory if buffer export is supported. * See also drm_prime_pages_to_sg().
*/ */
struct sg_table *(*get_sg_table)(struct drm_gem_object *obj); struct sg_table *(*get_sg_table)(struct drm_gem_object *obj);
/** /**
* @vmap: * @vmap:
* *
* Returns a virtual address for the buffer. * Returns a virtual address for the buffer. Used by the
* drm_gem_dmabuf_vmap() helper.
* *
* This callback is optional. * This callback is optional.
*/ */
...@@ -138,7 +143,8 @@ struct drm_gem_object_funcs { ...@@ -138,7 +143,8 @@ struct drm_gem_object_funcs {
/** /**
* @vunmap: * @vunmap:
* *
* Releases the the address previously returned by @vmap. * Releases the the address previously returned by @vmap. Used by the
* drm_gem_dmabuf_vunmap() helper.
* *
* This callback is optional. * This callback is optional.
*/ */
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment