| Message ID | 1390467164-951-4-git-send-email-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
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
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@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()). 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
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_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 *
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(-)