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