Re: [Intel-gfx] [PATCH 1/3] drm: Update GEM refcounting docs
On Thu, Oct 22, 2015 at 01:54:17PM -0400, Alex Deucher wrote: > On Thu, Oct 22, 2015 at 1:11 PM, Daniel Vetter wrote: > > 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 > > Patches 1 and 3 are: > Reviewed-by: Alex Deucher Thanks, applied to drm-misc. -Daniel > > > --- > > Documentation/DocBook/gpu.tmpl | 15 +++--- > > include/drm/drm_gem.h | 106 > > +++-- > > 2 files changed, 100 insertions(+), 21 deletions(-) > > > > diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl > > index 90c2aab31269..6c5865bb5ee8 100644 > > --- a/Documentation/DocBook/gpu.tmpl > > +++ b/Documentation/DocBook/gpu.tmpl > > @@ -635,10 +635,10 @@ char *date; > >acquired and release by calling > > drm_gem_object_reference > >and drm_gem_object_unreference > > respectively. The > >caller must hold the drm_device > > - struct_mutex lock. As a convenience, > > GEM > > - provides the > > drm_gem_object_reference_unlocked and > > - drm_gem_object_unreference_unlocked > > functions that > > - can be called without holding the lock. > > + struct_mutex lock when calling > > + drm_gem_object_reference. As a convenience, > > GEM > > + provides drm_gem_object_unreference_unlocked > > + functions that can be called without holding the lock. > > > > > >When the last reference to a GEM object is released the GEM core > > calls > > @@ -836,10 +836,11 @@ char *date; > >abstracted from the client in libdrm. > > > > > > - > > -GEM Function Reference > > + > > + > > + GEM Function Reference > > !Edrivers/gpu/drm/drm_gem.c > > - > > +!Iinclude/drm/drm_gem.h > > > > > >VMA Offset Manager > > diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h > > index 15e7f007380f..0b3e11ab8757 100644 > > --- a/include/drm/drm_gem.h > > +++ b/include/drm/drm_gem.h > > @@ -35,76 +35,129 @@ > > */ > > > > /** > > - * This structure defines the drm_mm memory object, which will be used by > > the > > - * DRM for its buffer objects. > > + * struct drm_gem_object - GEM buffer object > > + * > > + * This structure defines the generic parts for GEM buffer objects, which > > are > > + * mostly around handling mmap and userspace handles. > > + * > > + * Buffer objects are often abbreviated to BO. > > */ > > struct drm_gem_object { > > - /** Reference count of this object */ > > + /** > > +* @refcount: > > +* > > +* Reference count of this object > > +* > > +* Please use drm_gem_object_reference() to acquire and > > +* drm_gem_object_unreference() or > > drm_gem_object_unreference_unlocked() > > +* to release a reference to a GEM buffer object. > > +*/ > > struct kref refcount; > > > > /** > > -* handle_count - gem file_priv handle count of this object > > +* @handle_count: > > +* > > +* This is the GEM file_priv handle count of this object. > > * > > * Each handle also holds a reference. Note that when the > > handle_count > > * drops to 0 any global names (e.g. the id in the flink namespace) > > will > > * be cleared. > > * > > * Protected by dev->object_name_lock. > > -* */ > > +*/ > > unsigned handle_count; > > > > - /** Related drm device */ > > + /** > > +* @dev: DRM dev this object belongs to. > > +*/ > > struct drm_device *dev; > > > > - /** File representing the shmem storage */ > > + /** > > +* @filp: > > +* > > +* SHMEM file node used as backing storage for swappable buffer > > objects. > > +* GEM also supports driver private objects with driver-specific > > backing > > +* storage (contiguous CMA memory, special reserved blocks). In this > > +* case @filp is NULL. > > +*/ > > struct file *filp; > > > > - /* Mapping info for this object */ > > + /** > > +* @vma_node: > > +* > > +* Mapping info for this object to support mmap. Drivers are > > supposed to > > +* allocate the mmap offset using drm_gem_create_mmap_offset(). The > > +* offset itself can be retrieved using drm_vma_node_offset_addr(). > > +* > > +* Memory mapping itself is handled by drm_gem_mmap(), which also > > checks > > +* that userspace is allowed to access the object. > > +*/ > >
Re: [Intel-gfx] [PATCH 1/3] drm: Update GEM refcounting docs
On Thu, Oct 22, 2015 at 1:11 PM, Daniel Vetter wrote: > 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 Patches 1 and 3 are: Reviewed-by: Alex Deucher > --- > Documentation/DocBook/gpu.tmpl | 15 +++--- > include/drm/drm_gem.h | 106 > +++-- > 2 files changed, 100 insertions(+), 21 deletions(-) > > diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl > index 90c2aab31269..6c5865bb5ee8 100644 > --- a/Documentation/DocBook/gpu.tmpl > +++ b/Documentation/DocBook/gpu.tmpl > @@ -635,10 +635,10 @@ char *date; >acquired and release by calling > drm_gem_object_reference >and drm_gem_object_unreference respectively. > The >caller must hold the drm_device > - struct_mutex lock. As a convenience, GEM > - provides the > drm_gem_object_reference_unlocked and > - drm_gem_object_unreference_unlocked functions > that > - can be called without holding the lock. > + struct_mutex lock when calling > + drm_gem_object_reference. As a convenience, GEM > + provides drm_gem_object_unreference_unlocked > + functions that can be called without holding the lock. > > >When the last reference to a GEM object is released the GEM core > calls > @@ -836,10 +836,11 @@ char *date; >abstracted from the client in libdrm. > > > - > -GEM Function Reference > + > + > + GEM Function Reference > !Edrivers/gpu/drm/drm_gem.c > - > +!Iinclude/drm/drm_gem.h > > >VMA Offset Manager > diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h > index 15e7f007380f..0b3e11ab8757 100644 > --- a/include/drm/drm_gem.h > +++ b/include/drm/drm_gem.h > @@ -35,76 +35,129 @@ > */ > > /** > - * This structure defines the drm_mm memory object, which will be used by the > - * DRM for its buffer objects. > + * struct drm_gem_object - GEM buffer object > + * > + * This structure defines the generic parts for GEM buffer objects, which are > + * mostly around handling mmap and userspace handles. > + * > + * Buffer objects are often abbreviated to BO. > */ > struct drm_gem_object { > - /** Reference count of this object */ > + /** > +* @refcount: > +* > +* Reference count of this object > +* > +* Please use drm_gem_object_reference() to acquire and > +* drm_gem_object_unreference() or > drm_gem_object_unreference_unlocked() > +* to release a reference to a GEM buffer object. > +*/ > struct kref refcount; > > /** > -* handle_count - gem file_priv handle count of this object > +* @handle_count: > +* > +* This is the GEM file_priv handle count of this object. > * > * Each handle also holds a reference. Note that when the handle_count > * drops to 0 any global names (e.g. the id in the flink namespace) > will > * be cleared. > * > * Protected by dev->object_name_lock. > -* */ > +*/ > unsigned handle_count; > > - /** Related drm device */ > + /** > +* @dev: DRM dev this object belongs to. > +*/ > struct drm_device *dev; > > - /** File representing the shmem storage */ > + /** > +* @filp: > +* > +* SHMEM file node used as backing storage for swappable buffer > objects. > +* GEM also supports driver private objects with driver-specific > backing > +* storage (contiguous CMA memory, special reserved blocks). In this > +* case @filp is NULL. > +*/ > struct file *filp; > > - /* Mapping info for this object */ > + /** > +* @vma_node: > +* > +* Mapping info for this object to support mmap. Drivers are supposed > to > +* allocate the mmap offset using drm_gem_create_mmap_offset(). The > +* offset itself can be retrieved using drm_vma_node_offset_addr(). > +* > +* Memory mapping itself is handled by drm_gem_mmap(), which also > checks > +* that userspace is allowed to access the object. > +*/ > struct drm_vma_offset_node vma_node; > > /** > +* @size: > +* > * Size of the object, in bytes. Immutable over the object's > * lifetime. > */ > size_t size; > > /** > +* @name: > +* > * Global name for this object, starts at 1. 0 means unnamed. > -* Access is covered by the object_name_lock in the r