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

1 files changed, 12 insertions, 6 deletions

diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h
index a9121fe66ea2..ae693c0666cd 100644
--- a/include/drm/drm_gem.h
+++ b/include/drm/drm_gem.h
@@ -101,7 +101,7 @@ struct drm_gem_object_funcs {
 	/**
 	 * @pin:
 	 *
-	 * Pin backing buffer in memory.
+	 * Pin backing buffer in memory. Used by the drm_gem_map_attach() helper.
 	 *
 	 * This callback is optional.
 	 */
@@ -110,7 +110,7 @@ struct drm_gem_object_funcs {
 	/**
 	 * @unpin:
 	 *
-	 * Unpin backing buffer.
+	 * Unpin backing buffer. Used by the drm_gem_map_detach() helper.
 	 *
 	 * This callback is optional.
 	 */
@@ -120,16 +120,21 @@ struct drm_gem_object_funcs {
 	 * @get_sg_table:
 	 *
 	 * 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);
 
 	/**
 	 * @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.
 	 */
@@ -138,7 +143,8 @@ struct drm_gem_object_funcs {
 	/**
 	 * @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.
 	 */