From 805dc614d58a8fb069ed079005e591247df85246 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 20 Jun 2019 14:46:15 +0200 Subject: drm/prime: Update docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Acked-by: Emil Velikov Acked-by: Noralf Trønnes Cc: Thomas Zimmermann Cc: Gerd Hoffmann Cc: Noralf Trønnes Cc: Sam Ravnborg Cc: Eric Anholt Cc: Emil Velikov Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20190620124615.24434-1-daniel.vetter@ffwll.ch --- include/drm/drm_gem.h | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) (limited to 'include/drm/drm_gem.h') 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. */ -- cgit v1.2.3