From patchwork Thu Dec 29 20:48:33 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 9491461 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 3A4DB62AB8 for ; Thu, 29 Dec 2016 20:51:37 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 299351FF8E for ; Thu, 29 Dec 2016 20:51:37 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1E9D822BF1; Thu, 29 Dec 2016 20:51:37 +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 99D761FF8E for ; Thu, 29 Dec 2016 20:51:35 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 2E32B6E174; 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 003656E164 for ; Thu, 29 Dec 2016 20:49:12 +0000 (UTC) Received: by mail-wj0-x242.google.com with SMTP id hb5so25618885wjc.2 for ; Thu, 29 Dec 2016 12:49:12 -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=ZmXZjgH+dFKrdsPvVSIsTl3gDPvKKcBOj+KmQo/sF6Y=; b=InDqB1PVejo0hrk3YjxDeWH5hKfUPla+qLMzcWIoNGBFKDys+oDOZ1slBgNautZweY izEO5qIwTLjBvmqpoHIkq1EeMg3zTqA0SQ5MqmErRp0lWGf28zACeHDrxJaOBK32k60I F6QPMuVYiM5ekWGJoSB+k8UOattYkxvlvQm44= 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=ZmXZjgH+dFKrdsPvVSIsTl3gDPvKKcBOj+KmQo/sF6Y=; b=D3PRln0ROCoSW93A3BzVEZZjqRIi6QS5DqllczxmBmaDxO8nDwQwAlXMhdn2nQmVjX F0+0jK3Bp/Zya7+3CelLsFvhot4RiHSKgWuduZGBtiYdfELFOtMQ/Mqe/u1hfhlEbC5Z IHI6nGKxImfceUt770mm8QF7J2iKqqSyifIXcipSSBv4Avk6c/IklN7Ev/WP5EjY3Iep DI0/7D5sU8IXlUqFBK7xrSPXB1faikRM4y6OjtVhxj1ccuI0J0+6amY96TSHD4yEAYCo RdBKFIcP2eqq5Vl0K4GzQPTC93Um99tmr1fiKQwA5B/Ne/sbbQyI3e7HpHmY+OVnK7/k wk/A== X-Gm-Message-State: AIkVDXIhSYaoqXHW/UGmxja7zuyKhkst5Xq/4/dvljQsqBrumUNLyckLJcvgAbWomI1Y+Q== X-Received: by 10.194.236.135 with SMTP id uu7mr38014457wjc.195.1483044551144; Thu, 29 Dec 2016 12:49:11 -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.09 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 29 Dec 2016 12:49:10 -0800 (PST) From: Daniel Vetter To: DRI Development Subject: [PATCH 13/17] drm/bridge: Use recommened kerneldoc for struct member refs Date: Thu, 29 Dec 2016 21:48:33 +0100 Message-Id: <1483044517-5770-13-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 , Intel Graphics Development , Daniel Vetter 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: Archit Taneja Cc: Jani Nikula Cc: Chris Wilson Signed-off-by: Daniel Vetter Reviewed-by: Archit Taneja --- drivers/gpu/drm/drm_bridge.c | 27 +++++++++++-------------- include/drm/drm_bridge.h | 48 +++++++++++++++++++++++++------------------- 2 files changed, 39 insertions(+), 36 deletions(-) diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c index ae5e57ad718c..86a7637ba344 100644 --- a/drivers/gpu/drm/drm_bridge.c +++ b/drivers/gpu/drm/drm_bridge.c @@ -55,7 +55,7 @@ * just provide additional hooks to get the desired output at the end of the * encoder chain. * - * Bridges can also be chained up using the next pointer in &struct drm_bridge. + * Bridges can also be chained up using the &drm_bridge.next pointer. * * Both legacy CRTC helpers and the new atomic modeset helpers support bridges. */ @@ -179,7 +179,7 @@ void drm_bridge_detach(struct drm_bridge *bridge) * @mode: desired mode to be set for the bridge * @adjusted_mode: updated mode that works for this bridge * - * Calls ->mode_fixup() &drm_bridge_funcs op for all the bridges in the + * Calls &drm_bridge_funcs.mode_fixup for all the bridges in the * encoder chain, starting from the first bridge to the last. * * Note: the bridge passed should be the one closest to the encoder @@ -206,11 +206,10 @@ bool drm_bridge_mode_fixup(struct drm_bridge *bridge, EXPORT_SYMBOL(drm_bridge_mode_fixup); /** - * drm_bridge_disable - calls ->disable() &drm_bridge_funcs op for all - * bridges in the encoder chain. + * drm_bridge_disable - disables all bridges in the encoder chain * @bridge: bridge control structure * - * Calls ->disable() &drm_bridge_funcs op for all the bridges in the encoder + * Calls &drm_bridge_funcs.disable op for all the bridges in the encoder * chain, starting from the last bridge to the first. These are called before * calling the encoder's prepare op. * @@ -229,11 +228,10 @@ void drm_bridge_disable(struct drm_bridge *bridge) EXPORT_SYMBOL(drm_bridge_disable); /** - * drm_bridge_post_disable - calls ->post_disable() &drm_bridge_funcs op for - * all bridges in the encoder chain. + * drm_bridge_post_disable - cleans up after disabling all bridges in the encoder chain * @bridge: bridge control structure * - * Calls ->post_disable() &drm_bridge_funcs op for all the bridges in the + * Calls &drm_bridge_funcs.post_disable op for all the bridges in the * encoder chain, starting from the first bridge to the last. These are called * after completing the encoder's prepare op. * @@ -258,7 +256,7 @@ EXPORT_SYMBOL(drm_bridge_post_disable); * @mode: desired mode to be set for the bridge * @adjusted_mode: updated mode that works for this bridge * - * Calls ->mode_set() &drm_bridge_funcs op for all the bridges in the + * Calls &drm_bridge_funcs.mode_set op for all the bridges in the * encoder chain, starting from the first bridge to the last. * * Note: the bridge passed should be the one closest to the encoder @@ -278,11 +276,11 @@ void drm_bridge_mode_set(struct drm_bridge *bridge, EXPORT_SYMBOL(drm_bridge_mode_set); /** - * drm_bridge_pre_enable - calls ->pre_enable() &drm_bridge_funcs op for all - * bridges in the encoder chain. + * drm_bridge_pre_enable - prepares for enabling all + * bridges in the encoder chain * @bridge: bridge control structure * - * Calls ->pre_enable() &drm_bridge_funcs op for all the bridges in the encoder + * Calls &drm_bridge_funcs.pre_enable op for all the bridges in the encoder * chain, starting from the last bridge to the first. These are called * before calling the encoder's commit op. * @@ -301,11 +299,10 @@ void drm_bridge_pre_enable(struct drm_bridge *bridge) EXPORT_SYMBOL(drm_bridge_pre_enable); /** - * drm_bridge_enable - calls ->enable() &drm_bridge_funcs op for all bridges - * in the encoder chain. + * drm_bridge_enable - enables all bridges in the encoder chain * @bridge: bridge control structure * - * Calls ->enable() &drm_bridge_funcs op for all the bridges in the encoder + * Calls &drm_bridge_funcs.enable op for all the bridges in the encoder * chain, starting from the first bridge to the last. These are called * after completing the encoder's commit op. * diff --git a/include/drm/drm_bridge.h b/include/drm/drm_bridge.h index d3ca16f4da8f..1595a57dfbf2 100644 --- a/include/drm/drm_bridge.h +++ b/include/drm/drm_bridge.h @@ -87,18 +87,19 @@ struct drm_bridge_funcs { * True if an acceptable configuration is possible, false if the modeset * operation should be rejected. */ - bool (*mode_fixup)(struct drm_bridge *bridge, - const struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode); + bool (*mode_fixup)(struct drm_bridge *bridge, const struct + drm_display_mode *mode, struct drm_display_mode + *adjusted_mode); /** * @disable: * * This callback should disable the bridge. It is called right before * the preceding element in the display pipe is disabled. If the * preceding element is a bridge this means it's called before that - * bridge's ->disable() function. If the preceding element is a - * &drm_encoder it's called right before the encoder's ->disable(), - * ->prepare() or ->dpms() hook from &struct drm_encoder_helper_funcs. + * bridge's @disable vfunc. If the preceding element is a &drm_encoder + * it's called right before the &drm_encoder_helper_funcs.disable, + * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms + * hook. * * The bridge can assume that the display pipe (i.e. clocks and timing * signals) feeding it is still running when this callback is called. @@ -110,12 +111,13 @@ struct drm_bridge_funcs { /** * @post_disable: * - * This callback should disable the bridge. It is called right after - * the preceding element in the display pipe is disabled. If the - * preceding element is a bridge this means it's called after that - * bridge's ->post_disable() function. If the preceding element is a - * &drm_encoder it's called right after the encoder's ->disable(), - * ->prepare() or ->dpms() hook from &struct drm_encoder_helper_funcs. + * This callback should disable the bridge. It is called right after the + * preceding element in the display pipe is disabled. If the preceding + * element is a bridge this means it's called after that bridge's + * @post_disable function. If the preceding element is a &drm_encoder + * it's called right after the encoder's + * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare + * or &drm_encoder_helper_funcs.dpms hook. * * The bridge must assume that the display pipe (i.e. clocks and timing * singals) feeding it is no longer running when this callback is @@ -129,9 +131,11 @@ struct drm_bridge_funcs { * @mode_set: * * This callback should set the given mode on the bridge. It is called - * after the ->mode_set() callback for the preceding element in the - * display pipeline has been called already. The display pipe (i.e. - * clocks and timing signals) is off when this function is called. + * after the @mode_set callback for the preceding element in the display + * pipeline has been called already. If the bridge is the first element + * then this would be &drm_encoder_helper_funcs.mode_set. The display + * pipe (i.e. clocks and timing signals) is off when this function is + * called. */ void (*mode_set)(struct drm_bridge *bridge, struct drm_display_mode *mode, @@ -142,9 +146,10 @@ struct drm_bridge_funcs { * This callback should enable the bridge. It is called right before * the preceding element in the display pipe is enabled. If the * preceding element is a bridge this means it's called before that - * bridge's ->pre_enable() function. If the preceding element is a - * &drm_encoder it's called right before the encoder's ->enable(), - * ->commit() or ->dpms() hook from &struct drm_encoder_helper_funcs. + * bridge's @pre_enable function. If the preceding element is a + * &drm_encoder it's called right before the encoder's + * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or + * &drm_encoder_helper_funcs.dpms hook. * * The display pipe (i.e. clocks and timing signals) feeding this bridge * will not yet be running when this callback is called. The bridge must @@ -161,9 +166,10 @@ struct drm_bridge_funcs { * This callback should enable the bridge. It is called right after * the preceding element in the display pipe is enabled. If the * preceding element is a bridge this means it's called after that - * bridge's ->enable() function. If the preceding element is a - * &drm_encoder it's called right after the encoder's ->enable(), - * ->commit() or ->dpms() hook from &struct drm_encoder_helper_funcs. + * bridge's @enable function. If the preceding element is a + * &drm_encoder it's called right after the encoder's + * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or + * &drm_encoder_helper_funcs.dpms hook. * * The bridge can assume that the display pipe (i.e. clocks and timing * signals) feeding it is running when this callback is called. This