From decc60bf49b5e514ef60fe9dd4b2517328b27e15 Mon Sep 17 00:00:00 2001
From: Daniel Vetter <daniel.vetter@ffwll.ch>
Date: Thu, 22 Oct 2015 19:11:27 +0200
Subject: drm: Update GEM refcounting docs
I just realized that I've forgotten to update all the gem refcounting
docs. For pennance also add pretty docs for the overall drm_gem_object
structure, with a few links thrown in fore good.
As usually we need to make sure the kerneldoc reference is at most a
sect2 for otherwise it won't be listed.
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1445533889-7661-1-git-send-email-daniel.vetter@ffwll.ch
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
Documentation/DocBook/gpu.tmpl | 15 ++++++++-------
1 file changed, 8 insertions(+), 7 deletions(-)
(limited to 'Documentation/DocBook/gpu.tmpl')
diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
index 201dcd3c2e9d..47b06dfa454d 100644
--- a/Documentation/DocBook/gpu.tmpl
+++ b/Documentation/DocBook/gpu.tmpl
@@ -635,10 +635,10 @@ char *date;</synopsis>
acquired and release by <function>calling drm_gem_object_reference</function>
and <function>drm_gem_object_unreference</function> respectively. The
caller must hold the <structname>drm_device</structname>
- <structfield>struct_mutex</structfield> lock. As a convenience, GEM
- provides the <function>drm_gem_object_reference_unlocked</function> and
- <function>drm_gem_object_unreference_unlocked</function> functions that
- can be called without holding the lock.
+ <structfield>struct_mutex</structfield> lock when calling
+ <function>drm_gem_object_reference</function>. As a convenience, GEM
+ provides <function>drm_gem_object_unreference_unlocked</function>
+ functions that can be called without holding the lock.
</para>
<para>
When the last reference to a GEM object is released the GEM core calls
@@ -836,10 +836,11 @@ char *date;</synopsis>
abstracted from the client in libdrm.
</para>
</sect3>
- <sect3>
- <title>GEM Function Reference</title>
+ </sect2>
+ <sect2>
+ <title>GEM Function Reference</title>
!Edrivers/gpu/drm/drm_gem.c
- </sect3>
+!Iinclude/drm/drm_gem.h
</sect2>
<sect2>
<title>VMA Offset Manager</title>
--
cgit
From df2e0900a5965795c2607640e4e9c2667e16c669 Mon Sep 17 00:00:00 2001
From: Daniel Vetter <daniel.vetter@ffwll.ch>
Date: Thu, 22 Oct 2015 19:11:29 +0200
Subject: drm/gem: Update/Polish docs
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>
---
Documentation/DocBook/gpu.tmpl | 33 ++++-----------------------------
1 file changed, 4 insertions(+), 29 deletions(-)
(limited to 'Documentation/DocBook/gpu.tmpl')
diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
index 47b06dfa454d..944e65a87033 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>
--
cgit