From patchwork Thu Dec 29 20:48:37 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 9491457 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 A94FB62AB8 for ; Thu, 29 Dec 2016 20:51:31 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 9826A1FF8E for ; Thu, 29 Dec 2016 20:51:31 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 8CD2422BF1; Thu, 29 Dec 2016 20:51:31 +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 E68C51FF8E for ; Thu, 29 Dec 2016 20:51:30 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 311F26E176; Thu, 29 Dec 2016 20:51:26 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wj0-x242.google.com (mail-wj0-x242.google.com [IPv6:2a00:1450:400c:c01::242]) by gabe.freedesktop.org (Postfix) with ESMTPS id 2F8A96E160 for ; Thu, 29 Dec 2016 20:49:21 +0000 (UTC) Received: by mail-wj0-x242.google.com with SMTP id hb5so25619183wjc.2 for ; Thu, 29 Dec 2016 12:49:21 -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=MqRXsUdehoGJWAHmQHPazMqaFQl4IzoTpYtFp4dcqq8=; b=ae7j3CgMrjQsE13K/Ox/9jddHpomqUPutCOo/t6b4pgGdWWYHO71CEUJSckwaAgvJC T7sq6h+1pKz5D9r20XmGcm16YDWQ6Lg8uOgtK/gFnBtaPvuzFstixQ45bYmD2w6Wsl1l jxjpR6k6LF4ihKNp9fgsk8V/wbv55UImG0Fr0= 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=MqRXsUdehoGJWAHmQHPazMqaFQl4IzoTpYtFp4dcqq8=; b=Aa7EQZwkdNHzyOJMSTNAr4BKX9/UJqPpt7vjoezqV4KLfc5El5IiVZo48BTU8hnpMF rRnVDA9t5/PxM8XxBhrAczBn+9FBUstoy6FVTVkUqy9+us5Ze/sGD8F5nGPsA8qyzx6f dfJV6I7/sUUsCcEfYJJAxyub4hW3aoQlakbaO2XEmWFGljyERPjujcdvjXba0+qoCi5E bB99PlwvJl35arBESQ09EPgWe82bhsNgS6ut7UnHxiX9NT1PmSKcamsof/VYwaDi7WCN kEtWwxB3YTEcZmJA2vJRRI9RoyMaLO4EZSm3W6ZiDMVi8yS2kk8+CRvxr8CmRrrpAUKR fCUg== X-Gm-Message-State: AIkVDXJD04pEOoAT2+jTtPawVn0V57cEtPCmCCF6ZZAKHDHBmH0bme8Q7dtixEc+UQdN9w== X-Received: by 10.194.96.241 with SMTP id dv17mr35578094wjb.28.1483044559141; Thu, 29 Dec 2016 12:49:19 -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.17 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 29 Dec 2016 12:49:18 -0800 (PST) From: Daniel Vetter To: DRI Development Subject: [PATCH 17/17] drm/core: Use recommened kerneldoc for struct member refs Date: Thu, 29 Dec 2016 21:48:37 +0100 Message-Id: <1483044517-5770-17-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 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" 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_auth.c | 4 ++-- drivers/gpu/drm/drm_drv.c | 8 ++++---- drivers/gpu/drm/drm_fops.c | 11 ++++++----- drivers/gpu/drm/drm_irq.c | 10 +++++----- drivers/gpu/drm/drm_pci.c | 2 +- drivers/gpu/drm/drm_platform.c | 2 +- drivers/gpu/drm/drm_sysfs.c | 2 +- include/drm/drm_auth.h | 12 ++++++------ include/drm/drm_drv.h | 2 +- include/drm/drm_irq.h | 4 ++-- 10 files changed, 29 insertions(+), 28 deletions(-) diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c index 860cfe124c2a..7ff697389d74 100644 --- a/drivers/gpu/drm/drm_auth.c +++ b/drivers/gpu/drm/drm_auth.c @@ -40,8 +40,8 @@ * least once successfully became the device master (either through the * SET_MASTER IOCTL, or implicitly through opening the primary device node when * no one else is the current master that time) there exists one &drm_master. - * This is noted in the is_master member of &drm_file. All other clients have - * just a pointer to the &drm_master they are associated with. + * This is noted in &drm_file.is_master. All other clients have just a pointer + * to the &drm_master they are associated with. * * In addition only one &drm_master can be the current master for a &drm_device. * It can be switched through the DROP_MASTER and SET_MASTER IOCTL, or diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c index f8de5804c37c..720427aad1d4 100644 --- a/drivers/gpu/drm/drm_drv.c +++ b/drivers/gpu/drm/drm_drv.c @@ -309,7 +309,7 @@ void drm_minor_release(struct drm_minor *minor) * userspace the device instance can be published using drm_dev_register(). * * There is also deprecated support for initalizing device instances using - * bus-specific helpers and the ->load() callback. But due to + * bus-specific helpers and the &drm_driver.load callback. But due to * backwards-compatibility needs the device instance have to be published too * early, which requires unpretty global locking to make safe and is therefore * only support for existing drivers not yet converted to the new scheme. @@ -718,9 +718,9 @@ static void remove_compat_control_link(struct drm_device *dev) * Never call this twice on any device! * * NOTE: To ensure backward compatibility with existing drivers method this - * function calls the ->load() method after registering the device nodes, - * creating race conditions. Usage of the ->load() methods is therefore - * deprecated, drivers must perform all initialization before calling + * function calls the &drm_driver.load method after registering the device + * nodes, creating race conditions. Usage of the &drm_driver.load methods is + * therefore deprecated, drivers must perform all initialization before calling * drm_dev_register(). * * RETURNS: diff --git a/drivers/gpu/drm/drm_fops.c b/drivers/gpu/drm/drm_fops.c index 48e106557c92..c9383ff36b61 100644 --- a/drivers/gpu/drm/drm_fops.c +++ b/drivers/gpu/drm/drm_fops.c @@ -580,7 +580,7 @@ EXPORT_SYMBOL(drm_poll); * kmalloc and @p must be the first member element. * * This is the locked version of drm_event_reserve_init() for callers which - * already hold dev->event_lock. + * already hold &drm_device.event_lock. * * RETURNS: * @@ -621,7 +621,7 @@ EXPORT_SYMBOL(drm_event_reserve_init_locked); * If callers embedded @p into a larger structure it must be allocated with * kmalloc and @p must be the first member element. * - * Callers which already hold dev->event_lock should use + * Callers which already hold &drm_device.event_lock should use * drm_event_reserve_init_locked() instead. * * RETURNS: @@ -677,7 +677,7 @@ EXPORT_SYMBOL(drm_event_cancel_free); * * This function sends the event @e, initialized with drm_event_reserve_init(), * to its associated userspace DRM file. Callers must already hold - * dev->event_lock, see drm_send_event() for the unlocked version. + * &drm_device.event_lock, see drm_send_event() for the unlocked version. * * Note that the core will take care of unlinking and disarming events when the * corresponding DRM file is closed. Drivers need not worry about whether the @@ -717,8 +717,9 @@ EXPORT_SYMBOL(drm_send_event_locked); * @e: DRM event to deliver * * This function sends the event @e, initialized with drm_event_reserve_init(), - * to its associated userspace DRM file. This function acquires dev->event_lock, - * see drm_send_event_locked() for callers which already hold this lock. + * to its associated userspace DRM file. This function acquires + * &drm_device.event_lock, see drm_send_event_locked() for callers which already + * hold this lock. * * Note that the core will take care of unlinking and disarming events when the * corresponding DRM file is closed. Drivers need not worry about whether the diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c index 88c69e71102e..1c4da043eeda 100644 --- a/drivers/gpu/drm/drm_irq.c +++ b/drivers/gpu/drm/drm_irq.c @@ -95,7 +95,7 @@ static void store_vblank(struct drm_device *dev, unsigned int pipe, * * Only to be called from drm_crtc_vblank_on(). * - * Note: caller must hold dev->vbl_lock since this reads & writes + * Note: caller must hold &drm_device.vbl_lock since this reads & writes * device vblank fields. */ static void drm_reset_vblank_timestamp(struct drm_device *dev, unsigned int pipe) @@ -142,7 +142,7 @@ static void drm_reset_vblank_timestamp(struct drm_device *dev, unsigned int pipe * Only necessary when going from off->on, to account for frames we * didn't get an interrupt for. * - * Note: caller must hold dev->vbl_lock since this reads & writes + * Note: caller must hold &drm_device.vbl_lock since this reads & writes * device vblank fields. */ static void drm_update_vblank_count(struct drm_device *dev, unsigned int pipe, @@ -449,7 +449,7 @@ static void drm_irq_vgaarb_nokms(void *cookie, bool state) * * This is the simplified helper interface provided for drivers with no special * needs. Drivers which need to install interrupt handlers for multiple - * interrupts must instead set drm_device->irq_enabled to signal the DRM core + * interrupts must instead set &drm_device.irq_enabled to signal the DRM core * that vblank interrupts are available. * * Returns: @@ -519,7 +519,7 @@ EXPORT_SYMBOL(drm_irq_install); * Calls the driver's irq_uninstall() function and unregisters the IRQ handler. * This should only be called by drivers which used drm_irq_install() to set up * their interrupt handler. Other drivers must only reset - * drm_device->irq_enabled to false. + * &drm_device.irq_enabled to false. * * Note that for kernel modesetting drivers it is a bug if this function fails. * The sanity checks are only to catch buggy user modesetting drivers which call @@ -982,7 +982,7 @@ static void send_vblank_event(struct drm_device *dev, * period. This helper function implements exactly the required vblank arming * behaviour. * - * NOTE: Drivers using this to send out the event in &struct drm_crtc_state + * NOTE: Drivers using this to send out the &struct drm_crtc_state.event * as part of an atomic commit must ensure that the next vblank happens at * exactly the same time as the atomic commit is committed to the hardware. This * function itself does **not** protect again the next vblank interrupt racing diff --git a/drivers/gpu/drm/drm_pci.c b/drivers/gpu/drm/drm_pci.c index 3ceea9cb9d3e..062422143f05 100644 --- a/drivers/gpu/drm/drm_pci.c +++ b/drivers/gpu/drm/drm_pci.c @@ -223,7 +223,7 @@ void drm_pci_agp_destroy(struct drm_device *dev) * Try and register, if we fail to register, backout previous work. * * NOTE: This function is deprecated, please use drm_dev_alloc() and - * drm_dev_register() instead and remove your ->load() callback. + * drm_dev_register() instead and remove your &drm_driver.load() callback. * * Return: 0 on success or a negative error code on failure. */ diff --git a/drivers/gpu/drm/drm_platform.c b/drivers/gpu/drm/drm_platform.c index 026269851ce9..e52d87dd93e0 100644 --- a/drivers/gpu/drm/drm_platform.c +++ b/drivers/gpu/drm/drm_platform.c @@ -78,7 +78,7 @@ static int drm_get_platform_dev(struct platform_device *platdev, * .load() function. * * NOTE: This function is deprecated, please use drm_dev_alloc() and - * drm_dev_register() instead and remove your ->load() callback. + * drm_dev_register() instead and remove your &drm_driver.load() callback. * * Return: 0 on success or a negative error code on failure. */ diff --git a/drivers/gpu/drm/drm_sysfs.c b/drivers/gpu/drm/drm_sysfs.c index 9a37196c1bf1..513288b5c2f6 100644 --- a/drivers/gpu/drm/drm_sysfs.c +++ b/drivers/gpu/drm/drm_sysfs.c @@ -255,7 +255,7 @@ static const struct attribute_group *connector_dev_groups[] = { * @connector: connector to add * * Create a connector device in sysfs, along with its associated connector - * properties (so far, connection status, dpms, mode list & edid) and + * properties (so far, connection status, dpms, mode list and edid) and * generate a hotplug event so userspace knows there's a new connector * available. */ diff --git a/include/drm/drm_auth.h b/include/drm/drm_auth.h index eecbc2f43f55..1eb4a52cad8d 100644 --- a/include/drm/drm_auth.h +++ b/include/drm/drm_auth.h @@ -43,18 +43,18 @@ struct drm_master { struct kref refcount; struct drm_device *dev; /** - * @unique: Unique identifier: e.g. busid. Protected by struct - * &drm_device master_mutex. + * @unique: Unique identifier: e.g. busid. Protected by + * &drm_device.master_mutex. */ char *unique; /** - * @unique_len: Length of unique field. Protected by &struct drm_device - * master_mutex. + * @unique_len: Length of unique field. Protected by + * &drm_device.master_mutex. */ int unique_len; /** - * @magic_map: Map of used authentication tokens. Protected by struct - * &drm_device master_mutex. + * @magic_map: Map of used authentication tokens. Protected by + * &drm_device.master_mutex. */ struct idr magic_map; struct drm_lock_data lock; diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h index c4fc49583dc0..cd764fa267fc 100644 --- a/include/drm/drm_drv.h +++ b/include/drm/drm_drv.h @@ -282,7 +282,7 @@ struct drm_driver { /** * @gem_free_object_unlocked: deconstructor for drm_gem_objects * - * This is for drivers which are not encumbered with dev->struct_mutex + * This is for drivers which are not encumbered with &drm_device.struct_mutex * legacy locking schemes. Use this hook instead of @gem_free_object. */ void (*gem_free_object_unlocked) (struct drm_gem_object *obj); diff --git a/include/drm/drm_irq.h b/include/drm/drm_irq.h index 18cfd11307e1..2fb880462a57 100644 --- a/include/drm/drm_irq.h +++ b/include/drm/drm_irq.h @@ -67,7 +67,7 @@ struct drm_vblank_crtc { * @disable_timer: Disable timer for the delayed vblank disabling * hysteresis logic. Vblank disabling is controlled through the * drm_vblank_offdelay module option and the setting of the - * max_vblank_count value in the &drm_device structure. + * &drm_device.max_vblank_count value. */ struct timer_list disable_timer; @@ -92,7 +92,7 @@ struct drm_vblank_crtc { */ atomic_t refcount; /* number of users of vblank interruptsper crtc */ /** - * @last: Protected by dev->vbl_lock, used for wraparound handling. + * @last: Protected by &drm_device.vbl_lock, used for wraparound handling. */ u32 last; /**