diff mbox series

[5/5] drm/shmem-helper: Clarify drm_gem_shmem_v[un]map() usage

Message ID 20230626120247.1337962-6-boris.brezillon@collabora.com (mailing list archive)
State New, archived
Headers show
Series drm/shmem-helper: Follow-up on 'Switch to reservation lock' | expand

Commit Message

Boris Brezillon June 26, 2023, 12:02 p.m. UTC 
Drivers are not supposed to call these functions directly when they
want to map/unamp a GEM in kernel space. They should instead go
through drm_gem_v[un]map[_unlocked]() that will forward the request
to drm_gem_object_funcs::v[un]map() which in turn will call
drm_gem_shmem_v[un]map().

Let's clarify that in the functions doc.

Signed-off-by: Boris Brezillon <boris.brezillon@collabora.com>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: Emil Velikov <emil.l.velikov@gmail.com>
Cc: Dmitry Osipenko <dmitry.osipenko@collabora.com>
---
 drivers/gpu/drm/drm_gem_shmem_helper.c | 10 ++++++++++
 1 file changed, 10 insertions(+)
diff mbox series

Patch

diff --git a/drivers/gpu/drm/drm_gem_shmem_helper.c b/drivers/gpu/drm/drm_gem_shmem_helper.c
index 2b8a32f6b656..daada172fe70 100644
--- a/drivers/gpu/drm/drm_gem_shmem_helper.c
+++ b/drivers/gpu/drm/drm_gem_shmem_helper.c
@@ -279,6 +279,11 @@  EXPORT_SYMBOL(drm_gem_shmem_unpin);
  *
  * Acquired mappings should be cleaned up by calling drm_gem_shmem_vunmap().
  *
+ * This function is not meant to be used directly, but rather used as a helper
+ * to implement driver-specific versions of drm_gem_object_funcs::vmap(). If
+ * you need to vmap() a GEM object from your driver, use
+ * drm_gem_vmap[_unlocked]() instead.
+ *
  * Returns:
  * 0 on success or a negative error code on failure.
  */
@@ -348,6 +353,11 @@  EXPORT_SYMBOL(drm_gem_shmem_vmap);
  *
  * This function hides the differences between dma-buf imported and natively
  * allocated objects.
+ *
+ * This function is not meant to be used directly, but rather used as a helper
+ * to implement driver-specific versions of drm_gem_object_funcs::vunmap(). If
+ * you need to vunmap() a GEM object from your driver, use
+ * drm_gem_vunmap[_unlocked]() instead.
  */
 void drm_gem_shmem_vunmap(struct drm_gem_shmem_object *shmem,
 			  struct iosys_map *map)