[PATCH 03/19] drm/doc: Clean up and integrate kerneldoc for drm_gem.c
Daniel Vetter
daniel at ffwll.ch
Thu Jan 23 01:39:30 PST 2014
On Thu, Jan 23, 2014 at 10:21:33AM +0100, David Herrmann wrote:
> 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()).
I think I'll postpone this to a real patch to clean up drm_gem kerneldoc.
Essentially this patch here just shuts up kerneldoc warnings about
mismatched kerneldoc compared to the actual function definition. But I'll
keep your suggestions in mind.
-Daniel
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
More information about the dri-devel
mailing list