diff options
| -rw-r--r-- | Documentation/gpu/drm-kms-helpers.rst | 12 | ||||
| -rw-r--r-- | Documentation/gpu/drm-mm.rst | 12 | ||||
| -rw-r--r-- | 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 8c8540ee859c..8d10e6b38918 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 @@ err_zero_use: * 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. */ |