[PATCH 03/19] drm/doc: Clean up and integrate kerneldoc for drm_gem.c
David Herrmann
dh.herrmann at gmail.com
Thu Jan 23 01:21:33 PST 2014
Hi
On Thu, Jan 23, 2014 at 9:52 AM, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> Fairly incomplete, but at least a start.
>
> Signed-off-by: Daniel Vetter <daniel.vetter at ffwll.ch>
> ---
> Documentation/DocBook/drm.tmpl | 6 +++-
> drivers/gpu/drm/drm_gem.c | 63 +++++++++++++++++++++++++++++++++++++++---
> 2 files changed, 64 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 9c3fdd59c995..0660bae6928f 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -868,7 +868,11 @@ char *date;</synopsis>
> abstracted from the client in libdrm.
> </para>
> </sect3>
> - </sect2>
> + <sect2>
> + <title>GEM Function Reference</title>
> +!Edrivers/gpu/drm/drm_gem.c
> + </sect2>
> + </sect2>
> </sect1>
>
> <!-- Internals: mode setting -->
> diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c
> index 5bbad873c798..2136052ccee1 100644
> --- a/drivers/gpu/drm/drm_gem.c
> +++ b/drivers/gpu/drm/drm_gem.c
> @@ -85,9 +85,9 @@
> #endif
>
> /**
> - * Initialize the GEM device fields
> + * drm_gem_init - Initialize the GEM device fields
> + * @dev: drm_devic structure to initialize
> */
> -
> int
> drm_gem_init(struct drm_device *dev)
> {
> @@ -120,6 +120,11 @@ drm_gem_destroy(struct drm_device *dev)
> }
>
> /**
> + * drm_gem_object_init - initialize an allocated shmem-backed GEM object
> + * @dev: drm_device the object should be initialized for
> + * @obj: drm_gem_object to initialize
> + * @size: object size
> + *
> * Initialize an already allocated GEM object of the specified size with
> * shmfs backing store.
> */
> @@ -141,6 +146,11 @@ int drm_gem_object_init(struct drm_device *dev,
> EXPORT_SYMBOL(drm_gem_object_init);
>
> /**
> + * drm_gem_object_init - initialize an allocated private GEM object
> + * @dev: drm_device the object should be initialized for
> + * @obj: drm_gem_object to initialize
> + * @size: object size
> + *
> * Initialize an already allocated GEM object of the specified size with
> * no GEM provided backing store. Instead the caller is responsible for
> * backing the object and handling it.
> @@ -176,6 +186,9 @@ drm_gem_remove_prime_handles(struct drm_gem_object *obj, struct drm_file *filp)
> }
>
> /**
> + * drm_gem_object_free - release resources bound to userspace handles
> + * @obj: GEM object to clean up.
> + *
> * Called after the last handle to the object has been closed
> *
> * Removes any name for the object. Note that this must be
> @@ -225,7 +238,12 @@ drm_gem_object_handle_unreference_unlocked(struct drm_gem_object *obj)
> }
>
> /**
> - * Removes the mapping from handle to filp for this object.
> + * drm_gem_handle_delete - deletes the given file-private handle
> + * @filp: drm file-private structure to use for the handle look up
> + * @handle: userspace handle to delete
> + *
> + * Removes the GEM handle from the @filp lookup table and if this is the last
> + * handle also cleans up linked resources like GEM names.
> */
> int
> drm_gem_handle_delete(struct drm_file *filp, u32 handle)
> @@ -270,6 +288,9 @@ EXPORT_SYMBOL(drm_gem_handle_delete);
>
> /**
> * drm_gem_dumb_destroy - dumb fb callback helper for gem based drivers
> + * @file: drm file-private structure to remove the dumb handle from
> + * @dev: corresponding drm_device
> + * @handle: the dumb handle to remove
> *
> * This implements the ->dumb_destroy kms driver callback for drivers which use
> * gem to manage their backing storage.
> @@ -284,6 +305,9 @@ EXPORT_SYMBOL(drm_gem_dumb_destroy);
>
> /**
> * drm_gem_handle_create_tail - internal functions to create a handle
> + * @file_priv: drm file-private structure to register the handle for
> + * @obj: object to register
> + * @handlep: pionter to return the created handle to the caller
> *
> * This expects the dev->object_name_lock to be held already and will drop it
> * before returning. Used to avoid races in establishing new handles when
> @@ -336,6 +360,11 @@ drm_gem_handle_create_tail(struct drm_file *file_priv,
> }
>
> /**
> + * gem_handle_create - create a gem handle for an object
> + * @file_priv: drm file-private structure to register the handle for
> + * @obj: object to register
> + * @handlep: pionter to return the created handle to the caller
> + *
> * Create a handle for this object. This adds a handle reference
> * to the object, which includes a regular reference count. Callers
> * will likely want to dereference the object afterwards.
> @@ -536,6 +565,11 @@ drm_gem_object_lookup(struct drm_device *dev, struct drm_file *filp,
> EXPORT_SYMBOL(drm_gem_object_lookup);
>
> /**
> + * drm_gem_close_ioctl - implementation of the GEM_CLOSE ioctl
> + * @dev: drm_device
> + * @data: ioctl data
> + * @file_priv: drm file-private structure
> + *
> * Releases the handle to an mm object.
> */
> int
> @@ -554,6 +588,11 @@ drm_gem_close_ioctl(struct drm_device *dev, void *data,
> }
>
> /**
> + * drm_gem_flink_ioctl - implementation of the GEM_FLINK ioctl
> + * @dev: drm_device
> + * @data: ioctl data
> + * @file_priv: drm file-private structure
> + *
> * Create a global name for an object, returning the name.
> *
> * Note that the name does not hold a reference; when the object
> @@ -601,6 +640,11 @@ err:
> }
>
> /**
> + * drm_gem_open - implementation of the GEM_OPEN ioctl
> + * @dev: drm_device
> + * @data: ioctl data
> + * @file_priv: drm file-private structure
> + *
> * Open an object using the global name, returning a handle and the size.
> *
> * This handle (of course) holds a reference to the object, so the object
> @@ -640,6 +684,10 @@ drm_gem_open_ioctl(struct drm_device *dev, void *data,
> }
>
> /**
> + * gem_gem_open - initalizes GEM file-private structures at devnode open time
> + * @dev: drm_device which is being opened by userspace
> + * @file_private: drm file-private structure to set up
> + *
> * Called at device open time, sets up the structure for handling refcounting
> * of mm objects.
> */
> @@ -650,7 +698,7 @@ drm_gem_open(struct drm_device *dev, struct drm_file *file_private)
> spin_lock_init(&file_private->table_lock);
> }
>
> -/**
> +/*
> * Called at device close to release the file's
> * handle references on objects.
> */
> @@ -674,6 +722,10 @@ drm_gem_object_release_handle(int id, void *ptr, void *data)
> }
>
> /**
> + * drm_gem_release - release file-private GEM resources
> + * @dev: drm_device which is being closed by userspace
> + * @file_private: drm file-private structure to clean up
> + *
> * Called at close time when the filp is going away.
> *
> * Releases any remaining references on objects by this filp.
> @@ -697,6 +749,9 @@ drm_gem_object_release(struct drm_gem_object *obj)
> EXPORT_SYMBOL(drm_gem_object_release);
drm_gem_object_release() is still missing. Lets at least add a
kernel-doc entry ala:
/**
* drm_gem_object_release() - destroy GEM object
* @obj: drm-object to release
*
* This is the counter-part to drm_gem_object_init() and
drm_gem_private_object_init() and
* must be called by a driver in its gem_free_object() callback to
release any gem-internal
* resources of the GEM-bo.
*/
>
> /**
> + * drm_gem_object_free - free a GEM object
> + * @kref: kref of the object to free
> + *
> * Called after the last reference to the object has been lost.
> * Must be called holding struct_ mutex
> *
drm_gem_object_free() is internal to drm_gem.c. We only export it
because our object_unreference() helper is "static inline" in the
header. I don't think we should include this in the kernel-doc. No-one
should call this directly (same drm_gem_object_release_handle()).
Thanks
David
> --
> 1.8.5.2
>
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dri-devel
More information about the dri-devel
mailing list