drm: Update TTM initialization documentation

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@collabora.co.uk>
[danvet: Keep the warning, ttm docs are still massively inadequate.]
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/20161228143216.26821-7-krisman@collabora.co.uk
This commit is contained in:
Gabriel Krisman Bertazi 2016-12-30 12:50:49 +01:00 committed by Daniel Vetter
parent 5bbf92d3eb
commit b834ff86a6
2 changed files with 40 additions and 10 deletions

View File

@ -34,25 +34,26 @@ TTM initialization
------------------
**Warning**
This section is outdated.
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.
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.
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 +77,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)
====================================

View File

@ -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];