From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-12.8 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0AAA1C433E4 for ; Sun, 19 Jul 2020 08:08:10 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id DE5DE207DF for ; Sun, 19 Jul 2020 08:08:09 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="i0E8gCL4" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726131AbgGSIIJ (ORCPT ); Sun, 19 Jul 2020 04:08:09 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59458 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725836AbgGSIIJ (ORCPT ); Sun, 19 Jul 2020 04:08:09 -0400 Received: from mail-lj1-x243.google.com (mail-lj1-x243.google.com [IPv6:2a00:1450:4864:20::243]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id AC83DC0619D2; Sun, 19 Jul 2020 01:08:08 -0700 (PDT) Received: by mail-lj1-x243.google.com with SMTP id f5so17026125ljj.10; Sun, 19 Jul 2020 01:08:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=7IVQg6N9Y7IT+7TfYzwS4f6zi+ddclNT7W4+DeE2wDo=; b=i0E8gCL48VpYyuEGykDhenbE3iBlRnlQ5FR4r7PXKxUOUAe0muJPVupH9d/Fk+n325 v5wig+bRKhZbAE10i+qkAgv0dyz6FZ5SLpA+MQzKOHFFmBCinyTtvZ2QjRWoyR/DwvEG yqLPjaOPDDSXcPvBPby1psHUWpgu3J8GQmbRxesQMcPAr90bf2wH74rMmyeTywwiDslS nn+HZ5RevlFCafij8xAC49Y4CornFojE+GgwsYwXRUQ600kXJRhP/r12OmX2JF2BEA/K jFPIAWHf70NeowfroGq5i42WVJxmD6GUx1i07ugPoDwhXwvvrI+m8Nbk3h1znbAN0bu7 PMsQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=7IVQg6N9Y7IT+7TfYzwS4f6zi+ddclNT7W4+DeE2wDo=; b=E1xgIi2fbr28hYer8DbN5SSjmS1M2ww/qv7WhHKARG72NfocDPBrtKElCzdJQvFnk0 mi09l4nBFT305CYJ7cmcSBrIg6KUaglCvHZQmXFZt1kep+0eqaDxVvzethxl0mWY5FtO O55I2Pcvyz7kQl4m8EVs77hXXrfzeSk81NXnAK25IjGB1iuoMZzoVqnCeM7oQQ4zSqu9 KKQ1KCGKUfTwQIGGgy10KjSqfzPW0yR3ZHDc0RTg3qji/LNcvL0YeSgm45+iD6MRgoNM xu0rw/2TxZCgeN4ohcDAhYEtPYPpY/67jOPiztL/QwHnMAzPU0RJEMHHQ5ZtR9fnzDe2 tpuw== X-Gm-Message-State: AOAM530VxXpRKD3K+oo6vhnDGfA48SpNy4oTYxqIVIt60sOfXQkPJ6Ml JYnPkEUr/1eW84yWuNPS/lI= X-Google-Smtp-Source: ABdhPJxDEQw9zqp/E7cibISbe2kJD9a7+oyRLBO2wfiqQnoW5MHIuyj/0dlgQ4dS3nSDsdxFf/JRcw== X-Received: by 2002:a2e:8199:: with SMTP id e25mr7189788ljg.307.1595146087170; Sun, 19 Jul 2020 01:08:07 -0700 (PDT) Received: from saturn.lan ([2a00:fd00:805f:db00:d5fe:fe9c:fc06:b74c]) by smtp.gmail.com with ESMTPSA id 72sm732407lfh.97.2020.07.19.01.08.05 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 19 Jul 2020 01:08:06 -0700 (PDT) From: Sam Ravnborg To: dri-devel@lists.freedesktop.org, Jingoo Han , Lee Jones , Daniel Thompson Cc: Andy Gross , Bartlomiej Zolnierkiewicz , Bjorn Andersson , Daniel Vetter , David Airlie , Emil Velikov , Jonathan Corbet , linux-arm-msm@vger.kernel.org, linux-pwm@vger.kernel.org, Maarten Lankhorst , Maxime Ripard , Michael Hennerich , patches@opensource.cirrus.com, Support Opensource , Thierry Reding , Thomas Zimmermann , Uwe Kleine-Konig , Peter Ujfalusi , Tomi Valkeinen , Sam Ravnborg Subject: [PATCH v5 03/19] backlight: improve backlight_ops documentation Date: Sun, 19 Jul 2020 10:07:27 +0200 Message-Id: <20200719080743.8560-4-sam@ravnborg.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200719080743.8560-1-sam@ravnborg.org> References: <20200719080743.8560-1-sam@ravnborg.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: linux-arm-msm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-arm-msm@vger.kernel.org Improve the documentation for backlight_ops and adapt it to kernel-doc style. v2: - Add intro for each field (Daniel) Signed-off-by: Sam Ravnborg Reviewed-by: Daniel Thompson Reviewed-by: Emil Velikov Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han --- include/linux/backlight.h | 59 +++++++++++++++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 6 deletions(-) diff --git a/include/linux/backlight.h b/include/linux/backlight.h index 56e51ebab740..dfb43ee02ea0 100644 --- a/include/linux/backlight.h +++ b/include/linux/backlight.h @@ -55,19 +55,66 @@ enum backlight_scale { struct backlight_device; struct fb_info; +/** + * struct backlight_ops - backlight operations + * + * The backlight operations are specifed when the backlight device is registered. + */ struct backlight_ops { + /** + * @options: Configure how operations are called from the core. + * + * The options parameter is used to adjust the behaviour of the core. + * Set BL_CORE_SUSPENDRESUME to get the update_status() operation called + * upon suspend and resume. + */ unsigned int options; #define BL_CORE_SUSPENDRESUME (1 << 0) - /* Notify the backlight driver some property has changed */ + /** + * @update_status: Operation called when properties have changed. + * + * Notify the backlight driver some property has changed. + * The update_status operation is protected by the update_lock. + * + * The backlight driver is expected to use backlight_is_blank() + * to check if the display is blanked and set brightness accordingly. + * update_status() is called when any of the properties has changed. + * + * RETURNS: + * + * 0 on sucees, negative error code if any failure occured. + */ int (*update_status)(struct backlight_device *); - /* Return the current backlight brightness (accounting for power, - fb_blank etc.) */ + + /** + * @get_brightness: Return the current backlight brightness. + * + * The driver may implement this as a readback from the HW. + * This operation is optional and if not present then the current + * brightness property value is used. + * + * RETURNS: + * + * A brightness value which is 0 or a positive numer. + * On failure a negative error code is returned. + */ int (*get_brightness)(struct backlight_device *); - /* Check if given framebuffer device is the one bound to this backlight; - return 0 if not, !=0 if it is. If NULL, backlight always matches the fb. */ - int (*check_fb)(struct backlight_device *, struct fb_info *); + + /** + * @check_fb: Check the framebuffer device. + * + * Check if given framebuffer device is the one bound to this backlight. + * This operation is optional and if not implemented it is assumed that the + * fbdev is always the one bound to the backlight. + * + * RETURNS: + * + * If info is NULL or the info matches the fbdev bound to the backlight return true. + * If info does not match the fbdev bound to the backlight return false. + */ + int (*check_fb)(struct backlight_device *bd, struct fb_info *info); }; /* This structure defines all the properties of a backlight */ -- 2.25.1 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Sam Ravnborg Subject: [PATCH v5 03/19] backlight: improve backlight_ops documentation Date: Sun, 19 Jul 2020 10:07:27 +0200 Message-ID: <20200719080743.8560-4-sam@ravnborg.org> References: <20200719080743.8560-1-sam@ravnborg.org> Mime-Version: 1.0 Content-Transfer-Encoding: 8bit Return-path: In-Reply-To: <20200719080743.8560-1-sam@ravnborg.org> Sender: linux-arm-msm-owner@vger.kernel.org To: dri-devel@lists.freedesktop.org, Jingoo Han , Lee Jones , Daniel Thompson Cc: Andy Gross , Bartlomiej Zolnierkiewicz , Bjorn Andersson , Daniel Vetter , David Airlie , Emil Velikov , Jonathan Corbet , linux-arm-msm@vger.kernel.org, linux-pwm@vger.kernel.org, Maarten Lankhorst , Maxime Ripard , Michael Hennerich , patches@opensource.cirrus.com, Support Opensource , Thierry Reding , Thomas Zimmermann , Uwe Kleine-Konig , Peter Ujfalusi , Tomi Valkeinen List-Id: linux-pwm@vger.kernel.org Improve the documentation for backlight_ops and adapt it to kernel-doc style. v2: - Add intro for each field (Daniel) Signed-off-by: Sam Ravnborg Reviewed-by: Daniel Thompson Reviewed-by: Emil Velikov Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han --- include/linux/backlight.h | 59 +++++++++++++++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 6 deletions(-) diff --git a/include/linux/backlight.h b/include/linux/backlight.h index 56e51ebab740..dfb43ee02ea0 100644 --- a/include/linux/backlight.h +++ b/include/linux/backlight.h @@ -55,19 +55,66 @@ enum backlight_scale { struct backlight_device; struct fb_info; +/** + * struct backlight_ops - backlight operations + * + * The backlight operations are specifed when the backlight device is registered. + */ struct backlight_ops { + /** + * @options: Configure how operations are called from the core. + * + * The options parameter is used to adjust the behaviour of the core. + * Set BL_CORE_SUSPENDRESUME to get the update_status() operation called + * upon suspend and resume. + */ unsigned int options; #define BL_CORE_SUSPENDRESUME (1 << 0) - /* Notify the backlight driver some property has changed */ + /** + * @update_status: Operation called when properties have changed. + * + * Notify the backlight driver some property has changed. + * The update_status operation is protected by the update_lock. + * + * The backlight driver is expected to use backlight_is_blank() + * to check if the display is blanked and set brightness accordingly. + * update_status() is called when any of the properties has changed. + * + * RETURNS: + * + * 0 on sucees, negative error code if any failure occured. + */ int (*update_status)(struct backlight_device *); - /* Return the current backlight brightness (accounting for power, - fb_blank etc.) */ + + /** + * @get_brightness: Return the current backlight brightness. + * + * The driver may implement this as a readback from the HW. + * This operation is optional and if not present then the current + * brightness property value is used. + * + * RETURNS: + * + * A brightness value which is 0 or a positive numer. + * On failure a negative error code is returned. + */ int (*get_brightness)(struct backlight_device *); - /* Check if given framebuffer device is the one bound to this backlight; - return 0 if not, !=0 if it is. If NULL, backlight always matches the fb. */ - int (*check_fb)(struct backlight_device *, struct fb_info *); + + /** + * @check_fb: Check the framebuffer device. + * + * Check if given framebuffer device is the one bound to this backlight. + * This operation is optional and if not implemented it is assumed that the + * fbdev is always the one bound to the backlight. + * + * RETURNS: + * + * If info is NULL or the info matches the fbdev bound to the backlight return true. + * If info does not match the fbdev bound to the backlight return false. + */ + int (*check_fb)(struct backlight_device *bd, struct fb_info *info); }; /* This structure defines all the properties of a backlight */ -- 2.25.1 From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-12.8 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 448F6C43446 for ; Sun, 19 Jul 2020 08:08:26 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 18FFB208B3 for ; Sun, 19 Jul 2020 08:08:26 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="i0E8gCL4" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 18FFB208B3 Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=ravnborg.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=dri-devel-bounces@lists.freedesktop.org Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 2AB846E4D2; Sun, 19 Jul 2020 08:08:17 +0000 (UTC) Received: from mail-lj1-x242.google.com (mail-lj1-x242.google.com [IPv6:2a00:1450:4864:20::242]) by gabe.freedesktop.org (Postfix) with ESMTPS id F420A89F6F for ; Sun, 19 Jul 2020 08:08:08 +0000 (UTC) Received: by mail-lj1-x242.google.com with SMTP id q4so17105753lji.2 for ; Sun, 19 Jul 2020 01:08:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=7IVQg6N9Y7IT+7TfYzwS4f6zi+ddclNT7W4+DeE2wDo=; b=i0E8gCL48VpYyuEGykDhenbE3iBlRnlQ5FR4r7PXKxUOUAe0muJPVupH9d/Fk+n325 v5wig+bRKhZbAE10i+qkAgv0dyz6FZ5SLpA+MQzKOHFFmBCinyTtvZ2QjRWoyR/DwvEG yqLPjaOPDDSXcPvBPby1psHUWpgu3J8GQmbRxesQMcPAr90bf2wH74rMmyeTywwiDslS nn+HZ5RevlFCafij8xAC49Y4CornFojE+GgwsYwXRUQ600kXJRhP/r12OmX2JF2BEA/K jFPIAWHf70NeowfroGq5i42WVJxmD6GUx1i07ugPoDwhXwvvrI+m8Nbk3h1znbAN0bu7 PMsQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=7IVQg6N9Y7IT+7TfYzwS4f6zi+ddclNT7W4+DeE2wDo=; b=OlxbgdO3plVYfqsVHQ+apQWVI7P5L4zZ7u5gGlldz/CGZjBmJutE9RYqLJefZdn7y6 VBRKbakjnm/sHS1bY5T+kUjGA1lV5DEH5O/XodShxbVn6yDmpMLMjz7Qa5/9mJ0E384s 2O+227Q7I5VSf9wpcd234GAzI/MUBhl6aT5qd8QLTMCAQkSiHum7eIvjweMhXDcvlvuG s9I2gSTLEZwZR4hZvxLaVcnW7OngWDMTajeg2+e3VPWnwZ7kecx5WA/GaB8RA8euH2Du MiRChgAwXR1Nvkcfoi9cPX7MD0o4k4cWOqSJ0JOoYj4ulUagMObqqDvZ9jUA9VEdkbmq 3mag== X-Gm-Message-State: AOAM533NtxdjiS3koD8eyG+yNMS5ECb+NZyPgCHAHlUga/a62kfh56Ue OuWDp7mnTcQfr2IcsqhALu0IMlUq6sg= X-Google-Smtp-Source: ABdhPJxDEQw9zqp/E7cibISbe2kJD9a7+oyRLBO2wfiqQnoW5MHIuyj/0dlgQ4dS3nSDsdxFf/JRcw== X-Received: by 2002:a2e:8199:: with SMTP id e25mr7189788ljg.307.1595146087170; Sun, 19 Jul 2020 01:08:07 -0700 (PDT) Received: from saturn.lan ([2a00:fd00:805f:db00:d5fe:fe9c:fc06:b74c]) by smtp.gmail.com with ESMTPSA id 72sm732407lfh.97.2020.07.19.01.08.05 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 19 Jul 2020 01:08:06 -0700 (PDT) From: Sam Ravnborg To: dri-devel@lists.freedesktop.org, Jingoo Han , Lee Jones , Daniel Thompson Subject: [PATCH v5 03/19] backlight: improve backlight_ops documentation Date: Sun, 19 Jul 2020 10:07:27 +0200 Message-Id: <20200719080743.8560-4-sam@ravnborg.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200719080743.8560-1-sam@ravnborg.org> References: <20200719080743.8560-1-sam@ravnborg.org> MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: linux-pwm@vger.kernel.org, Support Opensource , Michael Hennerich , Bartlomiej Zolnierkiewicz , David Airlie , Daniel Vetter , Tomi Valkeinen , Jonathan Corbet , Emil Velikov , Bjorn Andersson , Peter Ujfalusi , Andy Gross , Thierry Reding , Thomas Zimmermann , linux-arm-msm@vger.kernel.org, Uwe Kleine-Konig , Sam Ravnborg , patches@opensource.cirrus.com Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" Improve the documentation for backlight_ops and adapt it to kernel-doc style. v2: - Add intro for each field (Daniel) Signed-off-by: Sam Ravnborg Reviewed-by: Daniel Thompson Reviewed-by: Emil Velikov Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han --- include/linux/backlight.h | 59 +++++++++++++++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 6 deletions(-) diff --git a/include/linux/backlight.h b/include/linux/backlight.h index 56e51ebab740..dfb43ee02ea0 100644 --- a/include/linux/backlight.h +++ b/include/linux/backlight.h @@ -55,19 +55,66 @@ enum backlight_scale { struct backlight_device; struct fb_info; +/** + * struct backlight_ops - backlight operations + * + * The backlight operations are specifed when the backlight device is registered. + */ struct backlight_ops { + /** + * @options: Configure how operations are called from the core. + * + * The options parameter is used to adjust the behaviour of the core. + * Set BL_CORE_SUSPENDRESUME to get the update_status() operation called + * upon suspend and resume. + */ unsigned int options; #define BL_CORE_SUSPENDRESUME (1 << 0) - /* Notify the backlight driver some property has changed */ + /** + * @update_status: Operation called when properties have changed. + * + * Notify the backlight driver some property has changed. + * The update_status operation is protected by the update_lock. + * + * The backlight driver is expected to use backlight_is_blank() + * to check if the display is blanked and set brightness accordingly. + * update_status() is called when any of the properties has changed. + * + * RETURNS: + * + * 0 on sucees, negative error code if any failure occured. + */ int (*update_status)(struct backlight_device *); - /* Return the current backlight brightness (accounting for power, - fb_blank etc.) */ + + /** + * @get_brightness: Return the current backlight brightness. + * + * The driver may implement this as a readback from the HW. + * This operation is optional and if not present then the current + * brightness property value is used. + * + * RETURNS: + * + * A brightness value which is 0 or a positive numer. + * On failure a negative error code is returned. + */ int (*get_brightness)(struct backlight_device *); - /* Check if given framebuffer device is the one bound to this backlight; - return 0 if not, !=0 if it is. If NULL, backlight always matches the fb. */ - int (*check_fb)(struct backlight_device *, struct fb_info *); + + /** + * @check_fb: Check the framebuffer device. + * + * Check if given framebuffer device is the one bound to this backlight. + * This operation is optional and if not implemented it is assumed that the + * fbdev is always the one bound to the backlight. + * + * RETURNS: + * + * If info is NULL or the info matches the fbdev bound to the backlight return true. + * If info does not match the fbdev bound to the backlight return false. + */ + int (*check_fb)(struct backlight_device *bd, struct fb_info *info); }; /* This structure defines all the properties of a backlight */ -- 2.25.1 _______________________________________________ dri-devel mailing list dri-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/dri-devel