From 42f9b7047820de194667fe01ad3644eca7eae8f3 Mon Sep 17 00:00:00 2001
From: Daniel Vetter <daniel.vetter@ffwll.ch>
Date: Mon, 11 May 2020 11:35:48 +0200
Subject: drm/doc: Some polish for shmem helpers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Git-commit: 0b638559aa1a1964446dbc25e652035469f93cc9
Patch-mainline: v5.9-rc1
References: jsc#SLE-12680, jsc#SLE-12880, jsc#SLE-12882, jsc#SLE-12883, jsc#SLE-13496, jsc#SLE-15322
- Move the shmem helper section to the drm-mm.rst file, next to the
vram helpers. Makes a lot more sense there with the now wider scope.
Also, that's where the all the other backing storage stuff resides.
It's just the framebuffer helpers that should be in the kms helper
section.
- Try to clarify which functiosn are for implementing
drm_gem_object_funcs, and which for drivers to call directly. At
least one driver screwed that up a bit.
Cc: Gerd Hoffmann <kraxel@redhat.com>
Cc: Rob Herring <robh@kernel.org>
Cc: Noralf Trønnes <noralf@tronnes.org>
Reviewed-by: Thomas Zimmermann <tzimmermann@suse.de>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20200511093554.211493-4-daniel.vetter@ffwll.ch
Signed-off-by: Patrik Jakobsson <pjakobsson@suse.de>
---
Documentation/gpu/drm-kms-helpers.rst | 12 --------
Documentation/gpu/drm-mm.rst | 12 ++++++++
drivers/gpu/drm/drm_gem_shmem_helper.c | 39 +++++++++++++++++++++-----
3 files changed, 44 insertions(+), 19 deletions(-)
diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst
index ee730457bf4e..b89ddd06dabb 100644
--- a/Documentation/gpu/drm-kms-helpers.rst
+++ b/Documentation/gpu/drm-kms-helpers.rst
@@ -411,15 +411,3 @@ Legacy CRTC/Modeset Helper Functions Reference
.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
:export:
-
-SHMEM GEM Helper Reference
-==========================
-
-.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
- :doc: overview
-
-.. kernel-doc:: include/drm/drm_gem_shmem_helper.h
- :internal:
-
-.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
- :export:
diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index 00643fc46fed..9abee1589c1e 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -370,6 +370,18 @@ GEM CMA Helper Functions Reference
.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c
:export:
+GEM SHMEM Helper Function Reference
+-----------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
+ :doc: overview
+
+.. kernel-doc:: include/drm/drm_gem_shmem_helper.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
+ :export:
+
GEM VRAM Helper Functions Reference
-----------------------------------
diff --git a/drivers/gpu/drm/drm_gem_shmem_helper.c b/drivers/gpu/drm/drm_gem_shmem_helper.c
index 339eee79ea52..3885854e85a9 100644
--- a/drivers/gpu/drm/drm_gem_shmem_helper.c
+++ b/drivers/gpu/drm/drm_gem_shmem_helper.c
@@ -103,7 +103,8 @@ EXPORT_SYMBOL_GPL(drm_gem_shmem_create);
* @obj: GEM object to free
*
* This function cleans up the GEM object state and frees the memory used to
- * store the object itself.
+ * store the object itself. It should be used to implement
+ * &drm_gem_object_funcs.free.
*/
void drm_gem_shmem_free_object(struct drm_gem_object *obj)
{
@@ -214,7 +215,8 @@ EXPORT_SYMBOL(drm_gem_shmem_put_pages);
* @obj: GEM object
*
* This function makes sure the backing pages are pinned in memory while the
- * buffer is exported.
+ * buffer is exported. It should only be used to implement
+ * &drm_gem_object_funcs.pin.
*
* Returns:
* 0 on success or a negative error code on failure.
@@ -232,7 +234,7 @@ EXPORT_SYMBOL(drm_gem_shmem_pin);
* @obj: GEM object
*
* This function removes the requirement that the backing pages are pinned in
- * memory.
+ * memory. It should only be used to implement &drm_gem_object_funcs.unpin.
*/
void drm_gem_shmem_unpin(struct drm_gem_object *obj)
{
@@ -285,8 +287,14 @@ static void *drm_gem_shmem_vmap_locked(struct drm_gem_shmem_object *shmem)
* drm_gem_shmem_vmap - Create a virtual mapping for a shmem GEM object
* @shmem: shmem GEM object
*
- * This function makes sure that a virtual address exists for the buffer backing
- * the shmem GEM object.
+ * This function makes sure that a contiguous kernel virtual address mapping
+ * exists for the buffer backing the shmem GEM object.
+ *
+ * This function can be used to implement &drm_gem_object_funcs.vmap. But it can
+ * also be called by drivers directly, in which case it will hide the
+ * differences between dma-buf imported and natively allocated objects.
+ *
+ * Acquired mappings should be cleaned up by calling drm_gem_shmem_vunmap().
*
* Returns:
* 0 on success or a negative error code on failure.
@@ -330,7 +338,13 @@ static void drm_gem_shmem_vunmap_locked(struct drm_gem_shmem_object *shmem)
* drm_gem_shmem_vunmap - Unmap a virtual mapping fo a shmem GEM object
* @shmem: shmem GEM object
*
- * This function removes the virtual address when use count drops to zero.
+ * This function cleans up a kernel virtual address mapping acquired by
+ * drm_gem_shmem_vmap(). The mapping is only removed when the use count drops to
+ * zero.
+ *
+ * This function can be used to implement &drm_gem_object_funcs.vmap. But it can
+ * also be called by drivers directly, in which case it will hide the
+ * differences between dma-buf imported and natively allocated objects.
*/
void drm_gem_shmem_vunmap(struct drm_gem_object *obj, void *vaddr)
{
@@ -559,6 +573,8 @@ EXPORT_SYMBOL_GPL(drm_gem_shmem_mmap);
* @p: DRM printer
* @indent: Tab indentation level
* @obj: GEM object
+ *
+ * This implements the &drm_gem_object_funcs.info callback.
*/
void drm_gem_shmem_print_info(struct drm_printer *p, unsigned int indent,
const struct drm_gem_object *obj)
@@ -577,7 +593,12 @@ EXPORT_SYMBOL(drm_gem_shmem_print_info);
* @obj: GEM object
*
* This function exports a scatter/gather table suitable for PRIME usage by
- * calling the standard DMA mapping API.
+ * calling the standard DMA mapping API. Drivers should not call this function
+ * directly, instead it should only be used as an implementation for
+ * &drm_gem_object_funcs.get_sg_table.
+ *
+ * Drivers who need to acquire an scatter/gather table for objects need to call
+ * drm_gem_shmem_get_pages_sgt() instead.
*
* Returns:
* A pointer to the scatter/gather table of pinned pages or NULL on failure.
@@ -599,6 +620,10 @@ EXPORT_SYMBOL_GPL(drm_gem_shmem_get_sg_table);
* the sg table doesn't exist, the pages are pinned, dma-mapped, and a sg
* table created.
*
+ * This is the main function for drivers to get at backing storage, and it hides
+ * and difference between dma-buf imported and natively allocated objects.
+ * drm_gem_shmem_get_sg_table() should not be directly called by drivers.
+ *
* Returns:
* A pointer to the scatter/gather table of pinned pages or errno on failure.
*/
--
2.29.2