[PATCH 6/6] drm: Update TTM initialization documentation

[Daniel Vetter]

On Wed, Dec 28, 2016 at 12:32:16PM -0200, Gabriel Krisman Bertazi wrote:
> ttm_global_reference was renamed to drm_global_reference.  This updates
> the documentation to reflect that.  While we are there, document the
> drm_global_reference API and update the initialization interface
> documentation.
> 
> Signed-off-by: Gabriel Krisman Bertazi <krisman at collabora.co.uk>
> ---
>  Documentation/gpu/drm-mm.rst | 30 +++++++++++++++++-------------
>  drivers/gpu/drm/drm_global.c | 23 +++++++++++++++++++++++
>  2 files changed, 40 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> index cb5daffcd6be..3686ed148003 100644
> --- a/Documentation/gpu/drm-mm.rst
> +++ b/Documentation/gpu/drm-mm.rst
> @@ -33,26 +33,24 @@ TTM design background and information belongs here.
>  TTM initialization
>  ------------------
>  
> -    **Warning**
> +Drivers wishing to support TTM must pass a filled :c:type:`ttm_bo_driver
> +<ttm_bo_driver>` structure to ttm_bo_device_init, together with an
> +initialized global reference to the memory manager.  The ttm_bo_driver
> +structure contains several fields with function pointers for
> +initializing the TTM, allocating and freeing memory, waiting for command
> +completion and fence synchronization, and memory migration.
>  
> -    This section is outdated.

Forgot to mention: I kept this warning, since TTM docs are still massively
inadequate.
-Daniel

> -
> -Drivers wishing to support TTM must fill out a drm_bo_driver
> -structure. The structure contains several fields with function pointers
> -for initializing the TTM, allocating and freeing memory, waiting for
> -command completion and fence synchronization, and memory migration. See
> -the radeon_ttm.c file for an example of usage.
> -
> -The ttm_global_reference structure is made up of several fields:
> +The :c:type:`struct drm_global_reference <drm_global_reference>` is made
> +up of several fields:
>  
>  .. code-block:: c
>  
> -              struct ttm_global_reference {
> +              struct drm_global_reference {
>                        enum ttm_global_types global_type;
>                        size_t size;
>                        void *object;
> -                      int (*init) (struct ttm_global_reference *);
> -                      void (*release) (struct ttm_global_reference *);
> +                      int (*init) (struct drm_global_reference *);
> +                      void (*release) (struct drm_global_reference *);
>                };
>  
>  
> @@ -76,6 +74,12 @@ ttm_bo_global_release(), respectively. Also, like the previous
>  object, ttm_global_item_ref() is used to create an initial reference
>  count for the TTM, which will call your initialization function.
>  
> +See the radeon_ttm.c file for an example of usage.
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_global.c
> +   :export:
> +
> +
>  The Graphics Execution Manager (GEM)
>  ====================================
>  
> diff --git a/drivers/gpu/drm/drm_global.c b/drivers/gpu/drm/drm_global.c
> index b404287abb97..b2dc21e33ae0 100644
> --- a/drivers/gpu/drm/drm_global.c
> +++ b/drivers/gpu/drm/drm_global.c
> @@ -63,6 +63,18 @@ void drm_global_release(void)
>  	}
>  }
>  
> +/**
> + * drm_global_item_ref - Initialize and acquire reference to memory
> + * object
> + * @ref: Object for initialization
> + *
> + * This initializes a memory object, allocating memory and calling the
> + * .init() hook. Further calls will increase the reference count for
> + * that item.
> + *
> + * Returns:
> + * Zero on success, non-zero otherwise.
> + */
>  int drm_global_item_ref(struct drm_global_reference *ref)
>  {
>  	int ret = 0;
> @@ -97,6 +109,17 @@ int drm_global_item_ref(struct drm_global_reference *ref)
>  }
>  EXPORT_SYMBOL(drm_global_item_ref);
>  
> +/**
> + * drm_global_item_unref - Drop reference to memory
> + * object
> + * @ref: Object being removed
> + *
> + * Drop a reference to the memory object and eventually call the
> + * release() hook.  The allocated object should be dropped in the
> + * release() hook or before calling this function
> + *
> + */
> +
>  void drm_global_item_unref(struct drm_global_reference *ref)
>  {
>  	struct drm_global_item *item = &glob[ref->global_type];
> -- 
> 2.11.0
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch