Re: [PATCH 03/19] drm/doc: Clean up and integrate kerneldoc for drm_gem.c

From: David Herrmann <dh.herrmann@gmail.com>
To: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: DRI Development <dri-devel@lists.freedesktop.org>
Subject: Re: [PATCH 03/19] drm/doc: Clean up and integrate kerneldoc for drm_gem.c
Date: Thu, 23 Jan 2014 10:21:33 +0100	[thread overview]
Message-ID: <CANq1E4T=WaX8-izjWkUtWYWo-Ne2+Z2VjEg+g5QJXn+VNQPJLA@mail.gmail.com> (raw)
In-Reply-To: <1390467164-951-4-git-send-email-daniel.vetter@ffwll.ch>

Hi

On Thu, Jan 23, 2014 at 9:52 AM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> Fairly incomplete, but at least a start.
>
> Signed-off-by: Daniel Vetter <daniel.vetter@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@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dri-devel