A bunch of things have been removed meanwhile and docs not fully
brought up to speed. And a few gaps closed where I noticed missing
kerneldoc while reading through the overview sections.
Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx>
---
Documentation/DocBook/gpu.tmpl | 33 ++++-----------------------------
drivers/gpu/drm/drm_gem.c | 35 ++++++++++++++++++++++++++++++++---
2 files changed, 36 insertions(+), 32 deletions(-)
diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
index 6c5865bb5ee8..e6735d2b6ae8 100644
--- a/Documentation/DocBook/gpu.tmpl
+++ b/Documentation/DocBook/gpu.tmpl
@@ -615,18 +615,6 @@ char *date;</synopsis>
<function>drm_gem_object_init</function>. Storage for private GEM
objects must be managed by drivers.
</para>
- <para>
- Drivers that do not need to extend GEM objects with private information
- can call the <function>drm_gem_object_alloc</function> function to
- allocate and initialize a struct <structname>drm_gem_object</structname>
- instance. The GEM core will call the optional driver
- <methodname>gem_init_object</methodname> operation after initializing
- the GEM object with <function>drm_gem_object_init</function>.
- <synopsis>int (*gem_init_object) (struct drm_gem_object *obj);</synopsis>
- </para>
- <para>
- No alloc-and-init function exists for private GEM objects.
- </para>
</sect3>
<sect3>
<title>GEM Objects Lifetime</title>
@@ -649,15 +637,9 @@ char *date;</synopsis>
</para>
<para>
<synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis>
- Drivers are responsible for freeing all GEM object resources, including
- the resources created by the GEM core. If an mmap offset has been
- created for the object (in which case
- <structname>drm_gem_object</structname>::<structfield>map_list</structfield>::<structfield>map</structfield>
- is not NULL) it must be freed by a call to
- <function>drm_gem_free_mmap_offset</function>. The shmfs backing store
- must be released by calling <function>drm_gem_object_release</function>
- (that function can safely be called if no shmfs backing store has been
- created).
+ Drivers are responsible for freeing all GEM object resources. This includes
+ the resources created by the GEM core, which need to be released with
+ <function>drm_gem_object_release</function>.
</para>
</sect3>
<sect3>
@@ -740,17 +722,10 @@ char *date;</synopsis>
DRM identifies the GEM object to be mapped by a fake offset passed
through the mmap offset argument. Prior to being mapped, a GEM object
must thus be associated with a fake offset. To do so, drivers must call
- <function>drm_gem_create_mmap_offset</function> on the object. The
- function allocates a fake offset range from a pool and stores the
- offset divided by PAGE_SIZE in
- <literal>obj->map_list.hash.key</literal>. Care must be taken not to
- call <function>drm_gem_create_mmap_offset</function> if a fake offset
- has already been allocated for the object. This can be tested by
- <literal>obj->map_list.map</literal> being non-NULL.
+ <function>drm_gem_create_mmap_offset</function> on the object.
</para>
<para>
Once allocated, the fake offset value
- (<literal>obj->map_list.hash.key << PAGE_SHIFT</literal>)
must be passed to the application in a driver-specific way and can then
be used as the mmap offset argument.
</para>
diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c
index 38680380c6b3..c55446a789c7 100644
--- a/drivers/gpu/drm/drm_gem.c
+++ b/drivers/gpu/drm/drm_gem.c
@@ -244,8 +244,9 @@ drm_gem_object_handle_unreference_unlocked(struct drm_gem_object *obj)
* @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.
+ * Removes the GEM handle from the @filp lookup table which has been added with
+ * drm_gem_handle_create(). 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)
@@ -314,6 +315,10 @@ EXPORT_SYMBOL(drm_gem_dumb_destroy);
* 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
* importing an object from either an flink name or a dma-buf.
+ *
+ * Handles must be release again through drm_gem_handle_delete(). This is done
+ * when userspace closes @file_priv for all attached handles, or through the
+ * GEM_CLOSE ioctl for individual handles.
*/
int
drm_gem_handle_create_tail(struct drm_file *file_priv,
@@ -551,7 +556,17 @@ void drm_gem_put_pages(struct drm_gem_object *obj, struct page **pages,
}
EXPORT_SYMBOL(drm_gem_put_pages);
-/** Returns a reference to the object named by the handle. */
+/**
+ * drm_gem_object_lookup - look up a GEM object from it's handle
+ * @dev: DRM device
+ * @filp: DRM file private date
+ * @handle: userspace handle
+ *
+ * Returns:
+ *
+ * A reference to the object named by the handle if such exists on @filp, NULL
+ * otherwise.
+ */
struct drm_gem_object *
drm_gem_object_lookup(struct drm_device *dev, struct drm_file *filp,
u32 handle)
@@ -791,6 +806,13 @@ drm_gem_object_free(struct kref *kref)
}
EXPORT_SYMBOL(drm_gem_object_free);
+/**
+ * drm_gem_vm_open - vma->ops->open implementation for GEM
+ * @vma: VM area structure
+ *
+ * This function implements the #vm_operations_struct open() callback for GEM
+ * drivers. This must be used together with drm_gem_vm_close().
+ */
void drm_gem_vm_open(struct vm_area_struct *vma)
{
struct drm_gem_object *obj = vma->vm_private_data;
@@ -799,6 +821,13 @@ void drm_gem_vm_open(struct vm_area_struct *vma)
}
EXPORT_SYMBOL(drm_gem_vm_open);
+/**
+ * drm_gem_vm_close - vma->ops->close implementation for GEM
+ * @vma: VM area structure
+ *
+ * This function implements the #vm_operations_struct close() callback for GEM
+ * drivers. This must be used together with drm_gem_vm_open().
+ */
void drm_gem_vm_close(struct vm_area_struct *vma)
{
struct drm_gem_object *obj = vma->vm_private_data;
--
2.5.1
_______________________________________________
Intel-gfx mailing list
Intel-gfx@xxxxxxxxxxxxxxxxxxxxx
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
