drm: Improve kerneldoc for new mode object refcounting

Slipped through the cracks in my review. The one issue I spotted
is that drm_mode_object_find now acquires references and can be
used on FB objects, which caused follow-on bugs in get/set_prop ioctls.
Follow-up patches will fix that.

[airlied: fixup some incr fb/decr object mixups]

Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Dave Airlie <airlied@redhat.com>

diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
index d078a5c34d48a1a06f5bfb07c452e1153ac9d95f..27c64541876c92c7616c67d2d1d5be04b456657e 100644 (file)
--- a/drivers/gpu/drm/drm_crtc.c
+++ b/drivers/gpu/drm/drm_crtc.c
@@ -380,10 +380,9 @@ static struct drm_mode_object *_object_find(struct drm_device *dev,
  * @id: id of the mode object
  * @type: type of the mode object
  *
- * Note that framebuffers cannot be looked up with this functions - since those
- * are reference counted, they need special treatment.  Even with
- * DRM_MODE_OBJECT_ANY (although that will simply return NULL
- * rather than WARN_ON()).
+ * This function is used to look up a modeset object. It will acquire a
+ * reference for reference counted objects. This reference must be dropped again
+ * by callind drm_mode_object_unreference().
  */
 struct drm_mode_object *drm_mode_object_find(struct drm_device *dev,
                uint32_t id, uint32_t type)
@@ -398,6 +397,14 @@ struct drm_mode_object *drm_mode_object_find(struct drm_device *dev,
 }
 EXPORT_SYMBOL(drm_mode_object_find);
 
+/**
+ * drm_mode_object_unreference - decr the object refcnt
+ * @obj: mode_object
+ *
+ * This functions decrements the object's refcount if it is a refcounted modeset
+ * object. It is a no-op on any other object. This is used to drop references
+ * acquired with drm_mode_object_reference().
+ */
 void drm_mode_object_unreference(struct drm_mode_object *obj)
 {
        if (obj->free_cb) {
@@ -408,11 +415,12 @@ void drm_mode_object_unreference(struct drm_mode_object *obj)
 EXPORT_SYMBOL(drm_mode_object_unreference);
 
 /**
- * drm_mode_object_reference - incr the fb refcnt
+ * drm_mode_object_reference - incr the object refcnt
  * @obj: mode_object
  *
- * This function operates only on refcounted objects.
- * This functions increments the object's refcount.
+ * This functions increments the object's refcount if it is a refcounted modeset
+ * object. It is a no-op on any other object. References should be dropped again
+ * by calling drm_mode_object_unreference().
  */
 void drm_mode_object_reference(struct drm_mode_object *obj)
 {