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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxx> wrote:
> > Fairly incomplete, but at least a start.
> >
> > Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxx>
> > ---
> >  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
_______________________________________________
dri-devel mailing list
dri-devel@xxxxxxxxxxxxxxxxxxxxx
http://lists.freedesktop.org/mailman/listinfo/dri-devel




[Index of Archives]     [Linux DRI Users]     [Linux Intel Graphics]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]
  Powered by Linux