Message ID | 1445533889-7661-1-git-send-email-daniel.vetter@ffwll.ch (mailing list archive) |
---|---|
State | New, archived |
Headers | show |
On Thu, Oct 22, 2015 at 1:11 PM, Daniel Vetter <daniel.vetter@ffwll.ch> 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 <daniel.vetter@intel.com> Patches 1 and 3 are: Reviewed-by: Alex Deucher <alexander.deucher@amd.com> > --- > 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;</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> > 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 related drm_device > + * Access is covered by dev->object_name_lock. This is used by the GEM_FLINK > + * and GEM_OPEN ioctls. > */ > int name; > > /** > - * Memory domains. These monitor which caches contain read/write data > + * @read_domains: > + * > + * Read memory domains. These monitor which caches contain read/write data > * related to the object. When transitioning from one set of domains > * to another, the driver is called to ensure that caches are suitably > - * flushed and invalidated > + * flushed and invalidated. > */ > uint32_t read_domains; > + > + /** > + * @write_domain: Corresponding unique write memory domain. > + */ > uint32_t write_domain; > > /** > + * @pending_read_domains: > + * > * While validating an exec operation, the > * new read/write domain values are computed here. > * They will be transferred to the above values > * at the point that any cache flushing occurs > */ > uint32_t pending_read_domains; > + > + /** > + * @pending_write_domain: Write domain similar to @pending_read_domains. > + */ > uint32_t pending_write_domain; > > /** > - * dma_buf - dma buf associated with this GEM object > + * @dma_buf: > + * > + * dma-buf associated with this GEM object. > * > * Pointer to the dma-buf associated with this gem object (either > * through importing or exporting). We break the resulting reference > * loop when the last gem handle for this object is released. > * > - * Protected by obj->object_name_lock > + * Protected by obj->object_name_lock. > */ > struct dma_buf *dma_buf; > > /** > - * import_attach - dma buf attachment backing this object > + * @import_attach: > + * > + * dma-buf attachment backing this object. > * > * Any foreign dma_buf imported as a gem object has this set to the > * attachment point for the device. This is invariant over the lifetime > @@ -133,12 +186,30 @@ int drm_gem_mmap_obj(struct drm_gem_object *obj, unsigned long obj_size, > struct vm_area_struct *vma); > int drm_gem_mmap(struct file *filp, struct vm_area_struct *vma); > > +/** > + * drm_gem_object_reference - acquire a GEM BO reference > + * @obj: GEM buffer object > + * > + * This acquires additional reference to @obj. It is illegal to call this > + * without already holding a reference. No locks required. > + */ > static inline void > drm_gem_object_reference(struct drm_gem_object *obj) > { > kref_get(&obj->refcount); > } > > +/** > + * drm_gem_object_unreference - release a GEM BO reference > + * @obj: GEM buffer object > + * > + * This releases a reference to @obj. Callers must hold the dev->struct_mutex > + * lock when calling this function, even when the driver doesn't use > + * dev->struct_mutex for anything. > + * > + * For drivers not encumbered with legacy locking use > + * drm_gem_object_unreference_unlocked() instead. > + */ > static inline void > drm_gem_object_unreference(struct drm_gem_object *obj) > { > @@ -149,6 +220,13 @@ drm_gem_object_unreference(struct drm_gem_object *obj) > } > } > > +/** > + * drm_gem_object_unreference_unlocked - release a GEM BO reference > + * @obj: GEM buffer object > + * > + * This releases a reference to @obj. Callers must not hold the > + * dev->struct_mutex lock when calling this function. > + */ > static inline void > drm_gem_object_unreference_unlocked(struct drm_gem_object *obj) > { > -- > 2.5.1 > > _______________________________________________ > dri-devel mailing list > dri-devel@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/dri-devel
On Thu, Oct 22, 2015 at 01:54:17PM -0400, Alex Deucher wrote: > On Thu, Oct 22, 2015 at 1:11 PM, Daniel Vetter <daniel.vetter@ffwll.ch> 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 <daniel.vetter@intel.com> > > Patches 1 and 3 are: > Reviewed-by: Alex Deucher <alexander.deucher@amd.com> 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;</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> > > 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 related drm_device > > + * Access is covered by dev->object_name_lock. This is used by the GEM_FLINK > > + * and GEM_OPEN ioctls. > > */ > > int name; > > > > /** > > - * Memory domains. These monitor which caches contain read/write data > > + * @read_domains: > > + * > > + * Read memory domains. These monitor which caches contain read/write data > > * related to the object. When transitioning from one set of domains > > * to another, the driver is called to ensure that caches are suitably > > - * flushed and invalidated > > + * flushed and invalidated. > > */ > > uint32_t read_domains; > > + > > + /** > > + * @write_domain: Corresponding unique write memory domain. > > + */ > > uint32_t write_domain; > > > > /** > > + * @pending_read_domains: > > + * > > * While validating an exec operation, the > > * new read/write domain values are computed here. > > * They will be transferred to the above values > > * at the point that any cache flushing occurs > > */ > > uint32_t pending_read_domains; > > + > > + /** > > + * @pending_write_domain: Write domain similar to @pending_read_domains. > > + */ > > uint32_t pending_write_domain; > > > > /** > > - * dma_buf - dma buf associated with this GEM object > > + * @dma_buf: > > + * > > + * dma-buf associated with this GEM object. > > * > > * Pointer to the dma-buf associated with this gem object (either > > * through importing or exporting). We break the resulting reference > > * loop when the last gem handle for this object is released. > > * > > - * Protected by obj->object_name_lock > > + * Protected by obj->object_name_lock. > > */ > > struct dma_buf *dma_buf; > > > > /** > > - * import_attach - dma buf attachment backing this object > > + * @import_attach: > > + * > > + * dma-buf attachment backing this object. > > * > > * Any foreign dma_buf imported as a gem object has this set to the > > * attachment point for the device. This is invariant over the lifetime > > @@ -133,12 +186,30 @@ int drm_gem_mmap_obj(struct drm_gem_object *obj, unsigned long obj_size, > > struct vm_area_struct *vma); > > int drm_gem_mmap(struct file *filp, struct vm_area_struct *vma); > > > > +/** > > + * drm_gem_object_reference - acquire a GEM BO reference > > + * @obj: GEM buffer object > > + * > > + * This acquires additional reference to @obj. It is illegal to call this > > + * without already holding a reference. No locks required. > > + */ > > static inline void > > drm_gem_object_reference(struct drm_gem_object *obj) > > { > > kref_get(&obj->refcount); > > } > > > > +/** > > + * drm_gem_object_unreference - release a GEM BO reference > > + * @obj: GEM buffer object > > + * > > + * This releases a reference to @obj. Callers must hold the dev->struct_mutex > > + * lock when calling this function, even when the driver doesn't use > > + * dev->struct_mutex for anything. > > + * > > + * For drivers not encumbered with legacy locking use > > + * drm_gem_object_unreference_unlocked() instead. > > + */ > > static inline void > > drm_gem_object_unreference(struct drm_gem_object *obj) > > { > > @@ -149,6 +220,13 @@ drm_gem_object_unreference(struct drm_gem_object *obj) > > } > > } > > > > +/** > > + * drm_gem_object_unreference_unlocked - release a GEM BO reference > > + * @obj: GEM buffer object > > + * > > + * This releases a reference to @obj. Callers must not hold the > > + * dev->struct_mutex lock when calling this function. > > + */ > > static inline void > > drm_gem_object_unreference_unlocked(struct drm_gem_object *obj) > > { > > -- > > 2.5.1 > > > > _______________________________________________ > > dri-devel mailing list > > dri-devel@lists.freedesktop.org > > http://lists.freedesktop.org/mailman/listinfo/dri-devel
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;</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> 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 related drm_device + * Access is covered by dev->object_name_lock. This is used by the GEM_FLINK + * and GEM_OPEN ioctls. */ int name; /** - * Memory domains. These monitor which caches contain read/write data + * @read_domains: + * + * Read memory domains. These monitor which caches contain read/write data * related to the object. When transitioning from one set of domains * to another, the driver is called to ensure that caches are suitably - * flushed and invalidated + * flushed and invalidated. */ uint32_t read_domains; + + /** + * @write_domain: Corresponding unique write memory domain. + */ uint32_t write_domain; /** + * @pending_read_domains: + * * While validating an exec operation, the * new read/write domain values are computed here. * They will be transferred to the above values * at the point that any cache flushing occurs */ uint32_t pending_read_domains; + + /** + * @pending_write_domain: Write domain similar to @pending_read_domains. + */ uint32_t pending_write_domain; /** - * dma_buf - dma buf associated with this GEM object + * @dma_buf: + * + * dma-buf associated with this GEM object. * * Pointer to the dma-buf associated with this gem object (either * through importing or exporting). We break the resulting reference * loop when the last gem handle for this object is released. * - * Protected by obj->object_name_lock + * Protected by obj->object_name_lock. */ struct dma_buf *dma_buf; /** - * import_attach - dma buf attachment backing this object + * @import_attach: + * + * dma-buf attachment backing this object. * * Any foreign dma_buf imported as a gem object has this set to the * attachment point for the device. This is invariant over the lifetime @@ -133,12 +186,30 @@ int drm_gem_mmap_obj(struct drm_gem_object *obj, unsigned long obj_size, struct vm_area_struct *vma); int drm_gem_mmap(struct file *filp, struct vm_area_struct *vma); +/** + * drm_gem_object_reference - acquire a GEM BO reference + * @obj: GEM buffer object + * + * This acquires additional reference to @obj. It is illegal to call this + * without already holding a reference. No locks required. + */ static inline void drm_gem_object_reference(struct drm_gem_object *obj) { kref_get(&obj->refcount); } +/** + * drm_gem_object_unreference - release a GEM BO reference + * @obj: GEM buffer object + * + * This releases a reference to @obj. Callers must hold the dev->struct_mutex + * lock when calling this function, even when the driver doesn't use + * dev->struct_mutex for anything. + * + * For drivers not encumbered with legacy locking use + * drm_gem_object_unreference_unlocked() instead. + */ static inline void drm_gem_object_unreference(struct drm_gem_object *obj) { @@ -149,6 +220,13 @@ drm_gem_object_unreference(struct drm_gem_object *obj) } } +/** + * drm_gem_object_unreference_unlocked - release a GEM BO reference + * @obj: GEM buffer object + * + * This releases a reference to @obj. Callers must not hold the + * dev->struct_mutex lock when calling this function. + */ static inline void drm_gem_object_unreference_unlocked(struct drm_gem_object *obj) {
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> --- Documentation/DocBook/gpu.tmpl | 15 +++--- include/drm/drm_gem.h | 106 +++++++++++++++++++++++++++++++++++------ 2 files changed, 100 insertions(+), 21 deletions(-)