[PATCH 1/4] drm: Improve kerneldoc for new mode object refcounting

[Daniel Vetter]

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.

Cc: Dave Airlie <airlied at gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter at ffwll.ch>
---
 drivers/gpu/drm/drm_crtc.c | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
index d078a5c34d48..52e6001a40e4 100644
--- 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 - incr the fb 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) {
@@ -411,8 +418,9 @@ EXPORT_SYMBOL(drm_mode_object_unreference);
  * drm_mode_object_reference - incr the fb 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)
 {
-- 
2.5.0