[Intel-gfx] [PATCH 3/9] drm/doc: Some polish for shmem helpers

Mon May 11 11:12:49 UTC 2020

Am 11.05.20 um 11:35 schrieb Daniel Vetter:
> - 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 at redhat.com>
> Cc: Rob Herring <robh at kernel.org>
> Cc: Noralf Trønnes <noralf at tronnes.org>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>

Reviewed-by: Thomas Zimmermann <tzimmermann at suse.de>

See below for a suggestion on the help text.

> ---
>  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 1839762044be..c01757b0ac25 100644
> --- a/Documentation/gpu/drm-mm.rst
> +++ b/Documentation/gpu/drm-mm.rst
> @@ -373,6 +373,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 df31e5782eed..2a70159d50ef 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.

It should 'only' be used? Or maybe you can say that it should be used by
drivers that don't implement struct drm_driver.gem_create_object.

>   */
>  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.
>   */
> 

-- 
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Maxfeldstr. 5, 90409 Nürnberg, Germany
(HRB 36809, AG Nürnberg)
Geschäftsführer: Felix Imendörffer

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/intel-gfx/attachments/20200511/88b945fe/attachment-0001.sig>