From patchwork Thu Dec 29 20:48:36 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 9491463 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 3D99762AB8 for ; Thu, 29 Dec 2016 20:51:39 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2CB681FF8E for ; Thu, 29 Dec 2016 20:51:39 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 210DF22BF1; Thu, 29 Dec 2016 20:51:39 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.1 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED, T_DKIM_INVALID autolearn=unavailable version=3.3.1 Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id A0C671FF8E for ; Thu, 29 Dec 2016 20:51:38 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id B6EBE6E16C; Thu, 29 Dec 2016 20:51:37 +0000 (UTC) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from mail-wm0-x244.google.com (mail-wm0-x244.google.com [IPv6:2a00:1450:400c:c09::244]) by gabe.freedesktop.org (Postfix) with ESMTPS id 175E86E163 for ; Thu, 29 Dec 2016 20:49:19 +0000 (UTC) Received: by mail-wm0-x244.google.com with SMTP id m203so68074265wma.3 for ; Thu, 29 Dec 2016 12:49:19 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ffwll.ch; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=ej7RLuQqf7V+kFsLavXBdVQhfUxCL0r+t6X1Q1G/KRU=; b=JbXeWxlydckFnzFrJy+FYFh75gHEQTL0q2u/3D7+uAC62ByS9kXixu6WH63aL17xyc HcNKLLb7ZT5BaWsUMU7GIocmlI03fuD9DpxiNKaVkjDCae/lg9mPbeCVHLBXJmu+jJ3Y NJ27vXRlQQGspGwTx76XW2Pkx72/xyoZ09vXY= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=ej7RLuQqf7V+kFsLavXBdVQhfUxCL0r+t6X1Q1G/KRU=; b=lyXzTdMuSGAqEaQLt5d39qf/rB/IoPer/RNV66CZDe6QePBeqZ+kZQwP4juVIdGPn6 3TOIlicQJrskIJtpk9fBg32HOzwryZu6l32XuuqE6l407RDiJ+tgv5pdEYDwBLAkbHVv nkKimb6RAv5Wt2bgjMna9srbB2jQgtP0UITfH5JKf3KaSZdYx3D/RPn3ItN/bHM52CVb IBBNKDbimNxGN++Ss6egknd9ks51ILC+qxZfu9MNeY9EqBLnXYpQf04+6NVLn2dVOT/x 0mtKYIqz1/CdC5u/MbwUHmsYDiMr2qFOb+TyX6enmSJs5bGC6tPokQs5aHB4WU5D1RKk eT3g== X-Gm-Message-State: AIkVDXLGsEAC/MBuXAhUzhJhjLrYg2J1wu0IPZDqaKLu3AqqFnme2bCRNcm+vvE1onLBCg== X-Received: by 10.28.143.20 with SMTP id r20mr38403942wmd.2.1483044557136; Thu, 29 Dec 2016 12:49:17 -0800 (PST) Received: from dvetter-linux.ger.corp.intel.com ([194.230.155.242]) by smtp.gmail.com with ESMTPSA id 63sm67007754wmg.2.2016.12.29.12.49.15 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 29 Dec 2016 12:49:16 -0800 (PST) From: Daniel Vetter To: DRI Development Date: Thu, 29 Dec 2016 21:48:36 +0100 Message-Id: <1483044517-5770-16-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1483044517-5770-1-git-send-email-daniel.vetter@ffwll.ch> References: <1483044517-5770-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter , Daniel Vetter , Intel Graphics Development Subject: [Intel-gfx] [PATCH 16/17] drm/gem|prime|mm: Use recommened kerneldoc for struct member refs X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Virus-Scanned: ClamAV using ClamSMTP I just learned that &struct_name.member_name works and looks pretty even. It doesn't (yet) link to the member directly though, which would be really good for big structures or vfunc tables (where the per-member kerneldoc tends to be long). Also some minor drive-by polish where it makes sense, I read a lot of docs ... Cc: Jani Nikula Cc: Chris Wilson Signed-off-by: Daniel Vetter --- drivers/gpu/drm/drm_gem.c | 24 ++++++++++++------------ drivers/gpu/drm/drm_mm.c | 4 ++-- drivers/gpu/drm/drm_prime.c | 2 +- include/drm/drm_gem.h | 16 ++++++++-------- 4 files changed, 23 insertions(+), 23 deletions(-) diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c index 465bacd0a630..bc93de308673 100644 --- a/drivers/gpu/drm/drm_gem.c +++ b/drivers/gpu/drm/drm_gem.c @@ -316,8 +316,8 @@ EXPORT_SYMBOL(drm_gem_handle_delete); * @dev: corresponding drm_device * @handle: the dumb handle to remove * - * This implements the ->dumb_destroy kms driver callback for drivers which use - * gem to manage their backing storage. + * This implements the &drm_driver.dumb_destroy kms driver callback for drivers + * which use gem to manage their backing storage. */ int drm_gem_dumb_destroy(struct drm_file *file, struct drm_device *dev, @@ -333,9 +333,9 @@ EXPORT_SYMBOL(drm_gem_dumb_destroy); * @obj: object to register * @handlep: pointer to return the created handle to the caller * - * This expects the dev->object_name_lock to be held already and will drop it - * before returning. Used to avoid races in establishing new handles when - * importing an object from either an flink name or a dma-buf. + * This expects the &drm_device.object_name_lock to be held already and will + * drop it before returning. Used to avoid races in establishing new handles + * when importing an object from either an flink name or a dma-buf. * * Handles must be release again through drm_gem_handle_delete(). This is done * when userspace closes @file_priv for all attached handles, or through the @@ -447,8 +447,8 @@ EXPORT_SYMBOL(drm_gem_free_mmap_offset); * structures. * * This routine allocates and attaches a fake offset for @obj, in cases where - * the virtual size differs from the physical size (ie. obj->size). Otherwise - * just use drm_gem_create_mmap_offset(). + * the virtual size differs from the physical size (ie. &drm_gem_object.size). + * Otherwise just use drm_gem_create_mmap_offset(). * * This function is idempotent and handles an already allocated mmap offset * transparently. Drivers do not need to check for this case. @@ -787,7 +787,7 @@ EXPORT_SYMBOL(drm_gem_object_release); * @kref: kref of the object to free * * Called after the last reference to the object has been lost. - * Must be called holding &drm_device->struct_mutex. + * Must be called holding &drm_device.struct_mutex. * * Frees the object */ @@ -813,7 +813,7 @@ EXPORT_SYMBOL(drm_gem_object_free); * @obj: GEM buffer object * * This releases a reference to @obj. Callers must not hold the - * dev->struct_mutex lock when calling this function. + * &drm_device.struct_mutex lock when calling this function. * * See also __drm_gem_object_unreference(). */ @@ -840,9 +840,9 @@ EXPORT_SYMBOL(drm_gem_object_unreference_unlocked); * 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. + * This releases a reference to @obj. Callers must hold the + * &drm_device.struct_mutex lock when calling this function, even when the + * driver doesn't use &drm_device.struct_mutex for anything. * * For drivers not encumbered with legacy locking use * drm_gem_object_unreference_unlocked() instead. diff --git a/drivers/gpu/drm/drm_mm.c b/drivers/gpu/drm/drm_mm.c index 229b3f525dee..e51876e588d6 100644 --- a/drivers/gpu/drm/drm_mm.c +++ b/drivers/gpu/drm/drm_mm.c @@ -552,8 +552,8 @@ EXPORT_SYMBOL(drm_mm_replace_node); * objects to the roster, probably by walking an LRU list, but this can be * freely implemented. Eviction candiates are added using * drm_mm_scan_add_block() until a suitable hole is found or there are no - * further evictable objects. Eviction roster metadata is tracked in struct - * &drm_mm_scan. + * further evictable objects. Eviction roster metadata is tracked in &struct + * drm_mm_scan. * * The driver must walk through all objects again in exactly the reverse * order to restore the allocator state. Note that while the allocator is used diff --git a/drivers/gpu/drm/drm_prime.c b/drivers/gpu/drm/drm_prime.c index 8d77b2462594..485e558d6661 100644 --- a/drivers/gpu/drm/drm_prime.c +++ b/drivers/gpu/drm/drm_prime.c @@ -291,7 +291,7 @@ static void drm_gem_unmap_dma_buf(struct dma_buf_attachment *attach, * This wraps dma_buf_export() for use by generic GEM drivers that are using * drm_gem_dmabuf_release(). In addition to calling dma_buf_export(), we take * a reference to the &drm_device and the exported &drm_gem_object (stored in - * exp_info->priv) which is released by drm_gem_dmabuf_release(). + * &dma_buf_export_info.priv) which is released by drm_gem_dmabuf_release(). * * Returns the new dmabuf. */ diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h index 9f63736e6163..449a41b56ffc 100644 --- a/include/drm/drm_gem.h +++ b/include/drm/drm_gem.h @@ -63,7 +63,7 @@ struct drm_gem_object { * drops to 0 any global names (e.g. the id in the flink namespace) will * be cleared. * - * Protected by dev->object_name_lock. + * Protected by &drm_device.object_name_lock. */ unsigned handle_count; @@ -106,8 +106,8 @@ struct drm_gem_object { * @name: * * Global name for this object, starts at 1. 0 means unnamed. - * Access is covered by dev->object_name_lock. This is used by the GEM_FLINK - * and GEM_OPEN ioctls. + * Access is covered by &drm_device.object_name_lock. This is used by + * the GEM_FLINK and GEM_OPEN ioctls. */ int name; @@ -150,7 +150,7 @@ struct drm_gem_object { * 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 &drm_device.object_name_lock. */ struct dma_buf *dma_buf; @@ -163,7 +163,7 @@ struct drm_gem_object { * attachment point for the device. This is invariant over the lifetime * of a gem object. * - * The driver's ->gem_free_object callback is responsible for cleaning + * The &drm_driver.gem_free_object callback is responsible for cleaning * up the dma_buf attachment and references acquired at import time. * * Note that the drm gem/prime core does not depend upon drivers setting @@ -204,7 +204,7 @@ drm_gem_object_reference(struct drm_gem_object *obj) * @obj: GEM buffer object * * This function is meant to be used by drivers which are not encumbered with - * dev->struct_mutex legacy locking and which are using the + * &drm_device.struct_mutex legacy locking and which are using the * gem_free_object_unlocked callback. It avoids all the locking checks and * locking overhead of drm_gem_object_unreference() and * drm_gem_object_unreference_unlocked(). @@ -212,8 +212,8 @@ drm_gem_object_reference(struct drm_gem_object *obj) * Drivers should never call this directly in their code. Instead they should * wrap it up into a ``driver_gem_object_unreference(struct driver_gem_object * *obj)`` wrapper function, and use that. Shared code should never call this, to - * avoid breaking drivers by accident which still depend upon dev->struct_mutex - * locking. + * avoid breaking drivers by accident which still depend upon + * &drm_device.struct_mutex locking. */ static inline void __drm_gem_object_unreference(struct drm_gem_object *obj)