kpriv/linux-hardened
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

drm/gem: Update/Polish docs

Browse source 
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@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1445533889-7661-3-git-send-email-daniel.vetter@ffwll.ch
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
This commit is contained in:
Daniel Vetter 2015-10-22 19:11:29 +02:00
parent decc60bf49
commit df2e0900a5
2 changed files with 36 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
Documentation/DocBook/gpu.tmpl
View file

@ -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-&gt;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-&gt;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-&gt;map_list.hash.key &lt;&lt; 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>

35
drivers/gpu/drm/drm_gem.c
View file

@ -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,
@ -541,7 +546,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)
@ -774,6 +789,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;
@ -782,6 +804,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;