From patchwork Mon Jun 1 06:51:56 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sam Ravnborg X-Patchwork-Id: 188691 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=-9.6 required=3.0 tests=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=ham 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 EF247C433E0 for ; Mon, 1 Jun 2020 06:52:22 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id CDA4B206E2 for ; Mon, 1 Jun 2020 06:52:22 +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="e2Fj5Mog" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726005AbgFAGwW (ORCPT ); Mon, 1 Jun 2020 02:52:22 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44848 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725283AbgFAGwW (ORCPT ); Mon, 1 Jun 2020 02:52:22 -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 BA793C061A0E; Sun, 31 May 2020 23:52:21 -0700 (PDT) Received: by mail-lj1-x243.google.com with SMTP id m18so6757404ljo.5; Sun, 31 May 2020 23:52:21 -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=18JbutLa3sEGZU8ji80y4T0HOoe/GimoCUZDbVyKY0E=; b=e2Fj5MogkKmmlicpZQIOcwOKcfsndqV5JSgZlnOJPZKp5N41Qkoah2I5L+kq+0n5xH 3wTRhIuHGWcFmhJecE6nLFQQEAgNEn0P5D72ORGOutadmzwdvFMXCoQlxfbmN+Myklzl rguVPFRYjbKEkUFrlPWeF5147m7T/7ELoYom48Fdu1C/F1qH4wKFR76529LX2cTBtgDz J5NlM9AJ/0Z7WJGmQPmbZ/x5QYxm5SBp2RdyIl0DAAuuUC7YBSK/2J2uKFoL0ntMGdnK dHZ/3Wy/+sVKJtZtQe2kQ67mTFb5aOlSC8FdrBm5kiY5ybts/i67pwFqK7AJm3E0cJYN 1jfw== 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=18JbutLa3sEGZU8ji80y4T0HOoe/GimoCUZDbVyKY0E=; b=VABIJrX0Da4XIj75CQtWiQqduaUd+9VtLvLy0UI3kYOIa6kNTW9wgYakp0vYtzXaKp fxOLwVyjBj0jpdrTT5bFFa6BX1FMk0fCIV/Ew8lG5cBEH3KJEhyjStL7b9JpueVLFviq N0Dxg1ecxoCNIqNsEuwSizfrxBDpqVDAwMbnqckSXVGOwcwci3IldUbG0MzU074ijqQH wJeLaFXb9RnXIjtJ3eQVIT04c9Ab+ffOxwSEj24cmnANhDVGHSSFZbXwYTUari/KYB3K Idax+FujdfZG6Naiyu/s7LRNdnb77IExdA9Mt9s2z+yyGrG95mQP/inKD5MyjCqXtdZU U07Q== X-Gm-Message-State: AOAM533YdfPasUtMPvoQ+hf+yJEPtSmDOKNfKc2+ypJ/xJl7B1mFl1xz q+/iOpH4cUDQnc/nNKGfPIk= X-Google-Smtp-Source: ABdhPJzTmzfyLe20++Ve5cRFiyoAQagMqwFVvs32L/FlmdwyctEw1qWH+8aNS3DXRsegMEk3+htxXg== X-Received: by 2002:a2e:4612:: with SMTP id t18mr4691823lja.212.1590994340242; Sun, 31 May 2020 23:52:20 -0700 (PDT) Received: from saturn.lan ([2a00:fd00:805f:db00:281d:a604:434c:a58d]) by smtp.gmail.com with ESMTPSA id e13sm2540462ljl.117.2020.05.31.23.52.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 31 May 2020 23:52:19 -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 v3 02/13] backlight: add backlight_is_blank() Date: Mon, 1 Jun 2020 08:51:56 +0200 Message-Id: <20200601065207.492614-3-sam@ravnborg.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200601065207.492614-1-sam@ravnborg.org> References: <20200601065207.492614-1-sam@ravnborg.org> MIME-Version: 1.0 Sender: linux-arm-msm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-arm-msm@vger.kernel.org The backlight support has two properties that express the state: - power - state It is un-documented and easy to get wrong. Add backlight_is_blank() helper to make it simpler for drivers to get the check of the state correct. A lot of drivers also includes checks for fb_blank. This check is redundant when the state is checked and thus not needed in this helper function. But added anyway to avoid introducing subtle bugs due to the creative use of fb_blank in some drivers. Introducing this helper will for some drivers results in added support for fb_blank. This will be a change in functionality, which will improve the backlight driver. Rolling out this helper to all relevant backlight drivers will eliminate almost all accesses to fb_blank. v3: - Clarified that the fb_blank support in backlight_is_blank() may result in functionality changes for the users (Emil) v2: - Added fb_blank condition (Daniel) Signed-off-by: Sam Ravnborg Reviewed-by: Daniel Thompson Cc: Emil Velikov Cc: Daniel Vetter Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han --- include/linux/backlight.h | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/include/linux/backlight.h b/include/linux/backlight.h index c7d6b2e8c3b5..a0a083b35c47 100644 --- a/include/linux/backlight.h +++ b/include/linux/backlight.h @@ -175,6 +175,25 @@ static inline void backlight_put(struct backlight_device *bd) put_device(&bd->dev); } +/** + * backlight_is_blank - Return true if display is expected to be blank + * @bd: the backlight device + * + * Display is expected to be blank if any of these is true:: + * + * 1) if power in not UNBLANK + * 2) if fb_blank is not UNBLANK + * 3) if state indicate BLANK or SUSPENDED + * + * Returns true if display is expected to be blank, false otherwise. + */ +static inline bool backlight_is_blank(struct backlight_device *bd) +{ + return bd->props.power != FB_BLANK_UNBLANK || + bd->props.fb_blank != FB_BLANK_UNBLANK || + bd->props.state & (BL_CORE_SUSPENDED | BL_CORE_FBBLANK); +} + extern struct backlight_device *backlight_device_register(const char *name, struct device *dev, void *devdata, const struct backlight_ops *ops, const struct backlight_properties *props); From patchwork Mon Jun 1 06:51:58 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sam Ravnborg X-Patchwork-Id: 188690 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=-7.9 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, EXCUSE_4, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham 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 95E55C433DF for ; Mon, 1 Jun 2020 06:52:27 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 70A9C2076B for ; Mon, 1 Jun 2020 06:52:27 +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="FB8sUWHt" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726072AbgFAGw1 (ORCPT ); Mon, 1 Jun 2020 02:52:27 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44864 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725283AbgFAGw0 (ORCPT ); Mon, 1 Jun 2020 02:52:26 -0400 Received: from mail-lj1-x244.google.com (mail-lj1-x244.google.com [IPv6:2a00:1450:4864:20::244]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 53759C061A0E; Sun, 31 May 2020 23:52:26 -0700 (PDT) Received: by mail-lj1-x244.google.com with SMTP id e4so6770184ljn.4; Sun, 31 May 2020 23:52:26 -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=wgQFgo3RHYwmcB8tP1uDfvnC0G/9E3cMrWKRfBK9IL8=; b=FB8sUWHtOWot1aPy7v97jwE2MCN9TFsZ8Uzu9Z2YTCLVknO+bXcp3uJkdWR2fGuHs8 ZWssNLxEldBQUfhYGP9t1ThPGqRMwdelU3gewbV3Rftyl9AAetV3O4zpyk8PPHf2QCZ5 xNA7J6x6lk8QJrfOpVkNWjPfi3sXMAl1cVzqbbZurLhdkXvGsIh4A0AabGXW0yNUB/uu AvlqROHPpoYOwtV2h4TlIO7iJWcsAqfKczoGhIiw+uX3BsBm5DnRLmSy3/fbwWyY1CwX l45bKiFfSZbWa14DxgOYoXGnnpi4EinY4CzhASM382I0RrBG1IO9r1D5wH2KlqfmYfqM j2dA== 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=wgQFgo3RHYwmcB8tP1uDfvnC0G/9E3cMrWKRfBK9IL8=; b=r8BqBsMM5xOmC6HYXFbxDGiYX4whgaKQdC26B33pRpDdY0sUkI+P7rj9ybGgKI2ozu U06kB9ZAUjuwBTjWt2gISITUQYVDJPVejJdde31QEGotqbhgu+oulLPHfW5Opw+InL6J TTi69+X1jDA9gkfVLYeWAPQuZnucA26RmtfB5ldi2SUPXcysb1CpPkFCjeRU+YJ9+BSv FhVpOWM7F6tzEFJfrxYTFPp+CtnG3Gz3XAB0BtkAYw2MPItobaMj1myIh4/lLnMJHJVo 1XjqQn0KT4ZmmIO7wTckdVo5bWJEROAM2XQ3X9CB4WykDV37m27QXqbSCGFQLYBiDKLO ByrA== X-Gm-Message-State: AOAM532vktNhY4dVcGtBNOfHQbxfiQWtN5aU27yFPNxYufdh0RkAIorv 8nsG9TLTPXip8ND8TzH5ndc= X-Google-Smtp-Source: ABdhPJzYtFLljsRs6Mh3pY4A40UVOWi60Y4AkVBMEcmu4THO7pQ00+38XavNrIHuVeGK1VbdGJyydg== X-Received: by 2002:a2e:9b4a:: with SMTP id o10mr5192012ljj.278.1590994344766; Sun, 31 May 2020 23:52:24 -0700 (PDT) Received: from saturn.lan ([2a00:fd00:805f:db00:281d:a604:434c:a58d]) by smtp.gmail.com with ESMTPSA id e13sm2540462ljl.117.2020.05.31.23.52.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 31 May 2020 23:52:24 -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 v3 04/13] backlight: improve backlight_properties documentation Date: Mon, 1 Jun 2020 08:51:58 +0200 Message-Id: <20200601065207.492614-5-sam@ravnborg.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200601065207.492614-1-sam@ravnborg.org> References: <20200601065207.492614-1-sam@ravnborg.org> MIME-Version: 1.0 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_properties and adapt it to kernel-doc style. v2: - Added into for each field (Daniel) - Re-written some parts to explain what to do, rather than what not to do. Partly based on suggestions from the review (Daniel) Signed-off-by: Sam Ravnborg Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han Reviewed-by: Daniel Thompson --- include/linux/backlight.h | 96 ++++++++++++++++++++++++++++++++++----- 1 file changed, 85 insertions(+), 11 deletions(-) diff --git a/include/linux/backlight.h b/include/linux/backlight.h index b6c1ab6c922a..69a20da03035 100644 --- a/include/linux/backlight.h +++ b/include/linux/backlight.h @@ -117,28 +117,102 @@ struct backlight_ops { int (*check_fb)(struct backlight_device *bd, struct fb_info *info); }; -/* This structure defines all the properties of a backlight */ +/** + * struct backlight_properties - backlight properties + * + * This structure defines all the properties of a backlight. + */ struct backlight_properties { - /* Current User requested brightness (0 - max_brightness) */ + /** + * @brightness: The current brightness requested by the user. + * + * The backlight core makes sure the range is (0 to max_brightness) + * when the brightness is set via the sysfs attribute: + * /sys/class/backlight//brightness. + * + * This value can be set in the backlight_properties passed + * to devm_backlight_device_register() to set a default brightness + * value. + */ int brightness; - /* Maximal value for brightness (read-only) */ + + /** + * @max_brightness: The maximum brightness value. + * + * This value must be set in the backlight_properties passed to + * devm_backlight_device_register() and shall not be modified by the + * driver after registration. + */ int max_brightness; - /* Current FB Power mode (0: full on, 1..3: power saving - modes; 4: full off), see FB_BLANK_XXX */ + + /** + * @power: The current power mode. + * + * User space can configure the power mode using the sysfs + * attribute: /sys/class/backlight//bl_power + * When the power property is updated update_status() is called. + * + * The possible values are: (0: full on, 1 to 3: power saving + * modes; 4: full off), see FB_BLANK_XXX. + * + * When the backlight device is enabled @power is set + * to FB_BLANK_UNBLANK. When the backlight device is disabled + * @power is set to FB_BLANK_POWERDOWN. + */ int power; - /* FB Blanking active? (values as for power) */ - /* Due to be removed, please use (state & BL_CORE_FBBLANK) */ + + /** + * @fb_blank: The power state from the FBIOBLANK ioclt. + * + * When the FBIOBLANK ioctl is called fb_blank is set to the + * blank parameter and the update_status() operation is called. + * + * When the backlight device is enabled @fb_blank is set + * to FB_BLANK_UNBLANK. When the backlight device is disabled + * @fb_blank is set to FB_BLANK_POWERDOWN. + * + * Backlight drivers should avoid using this property. It has been + * replaced by state & BL_CORE_FBLANK (although most drivers should + * use backlight_is_blank() as the preferred means to get the blank + * state). + * + * fb_blank is deprecated and will be removed. + */ int fb_blank; - /* Backlight type */ + + /** + * @type: The type of backlight supported. + * + * The backlight type allows userspace to make appropriate + * policy desicions based on the backlight type. + * + * This value must be set in the backlight_properties + * passed to devm_backlight_device_register(). + */ enum backlight_type type; - /* Flags used to signal drivers of state changes */ + + /** + * @state: The state of the backlight core. + * + * The state is a bitmask. BL_CORE_FBBLANK is set when the display + * is expected to be blank. BL_CORE_SUSPENDED is set when the + * driver is suspended. + * + * backlight drivers are excpected to use backlight_is_blank() + * in their update_status() operation rather than reading the + * state property. + * + * The state is maintained by the core and drivers may not modify it. + */ unsigned int state; - /* Type of the brightness scale (linear, non-linear, ...) */ - enum backlight_scale scale; #define BL_CORE_SUSPENDED (1 << 0) /* backlight is suspended */ #define BL_CORE_FBBLANK (1 << 1) /* backlight is under an fb blank event */ + /** + * @scale: The type of the brightness scale. + */ + enum backlight_scale scale; }; struct backlight_device { From patchwork Mon Jun 1 06:52:01 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sam Ravnborg X-Patchwork-Id: 188689 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=-9.6 required=3.0 tests=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=ham 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 85A1DC433DF for ; Mon, 1 Jun 2020 06:52:34 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 63BC52076B for ; Mon, 1 Jun 2020 06:52:34 +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="rbuMMtwa" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726145AbgFAGwe (ORCPT ); Mon, 1 Jun 2020 02:52:34 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44888 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725283AbgFAGwd (ORCPT ); Mon, 1 Jun 2020 02:52:33 -0400 Received: from mail-lj1-x241.google.com (mail-lj1-x241.google.com [IPv6:2a00:1450:4864:20::241]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 32874C05BD43; Sun, 31 May 2020 23:52:33 -0700 (PDT) Received: by mail-lj1-x241.google.com with SMTP id q2so6723813ljm.10; Sun, 31 May 2020 23:52:33 -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=NySSdlyQJkQGVkK1Cp0EHZZ6M2Ik0zG0av6w2Ego7I4=; b=rbuMMtwa32PlMgO3FLH9ovOTcW9dDxJqamtsGyz/yDGxwGhiZUOAictnebq5XGOUJa GYZvEoglN5aUz07Eb4Ee3r0Wm9PGmdbXlkyeB+jemEaWfvCvEH7w+t/werIAsAywDiZh KmYK99Ouzqz0FoNxuHqfn4P45jIzXf30SdpFboGDrjsHoYfaxCB8QP0+XD+OCivpqj9e akRwRzz7YLfe6sCinOxkIkYvq+HIEMUyDLTh6aFNitX7C2+2xVj9B2LLnkUJI0UksEnT NxBr+dxvmZYllzVKeglKLHrvkqRhYALq6R6Ni9HlDTtyBCtxtfb2UxmGSU2MA7XnbSif G5sg== 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=NySSdlyQJkQGVkK1Cp0EHZZ6M2Ik0zG0av6w2Ego7I4=; b=FIh5U4G2aPrv/3yiRhN2Wp+Sm0y0B49XKEzzvngxmz9jLyrgoVaSMgpClCDcbN0657 dPiD8oG03wnS7qlROWzJz3gA7rnDg7ubBPIDWRKM/CFtt+tE7Gntf8oKTLai5It6+Mgn SVN4Eq8uZxzNwF35whHznb7CtKVm6AbqkXvmDmgXA6dwOFttpoQ0THxIuHo/xvvVQLsb aRp4NToNl87aOI9XQ6Ht3hXtMrsrHHWiMBaOBjXPkuHiVaLym0lQa93hbEjRc7HRaHvW 5BIYBggL5SlS7IYgTbW+W3jDiX4oO28z6Qs3r7BmN0LAUusRyCC8MOs2cr1sPbByPt2i J/MQ== X-Gm-Message-State: AOAM530Yz+lWXNciiT4gYPvLV6bD/4C0nyZ2xwMHvE9FgzUIDV2vlfIr pKSSNngLkjE2aGDQZ0ycJuk= X-Google-Smtp-Source: ABdhPJzFLoA3566dKX71K1Hk/avEwSPU2a8TFY6W34e11xmPVzkT9VeSoTjpuep92eETOAu24eniEA== X-Received: by 2002:a2e:82d0:: with SMTP id n16mr7862747ljh.6.1590994351618; Sun, 31 May 2020 23:52:31 -0700 (PDT) Received: from saturn.lan ([2a00:fd00:805f:db00:281d:a604:434c:a58d]) by smtp.gmail.com with ESMTPSA id e13sm2540462ljl.117.2020.05.31.23.52.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 31 May 2020 23:52:31 -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 v3 07/13] backlight: document enums in backlight.h Date: Mon, 1 Jun 2020 08:52:01 +0200 Message-Id: <20200601065207.492614-8-sam@ravnborg.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200601065207.492614-1-sam@ravnborg.org> References: <20200601065207.492614-1-sam@ravnborg.org> MIME-Version: 1.0 Sender: linux-arm-msm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-arm-msm@vger.kernel.org Add kernel-doc documentation for the backlight enums v2: - Add intro to each enum member (Daniel) Except backlight type as line lenght was too long. The generated HTML is the same. Signed-off-by: Sam Ravnborg Reviewed-by: Daniel Thompson Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han --- include/linux/backlight.h | 74 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 73 insertions(+), 1 deletion(-) diff --git a/include/linux/backlight.h b/include/linux/backlight.h index f99ca19cc3ec..c1c7b1666a9b 100644 --- a/include/linux/backlight.h +++ b/include/linux/backlight.h @@ -14,26 +14,98 @@ #include #include +/** + * enum backlight_update_reason - what method was used to update backlight + * + * A driver indicates the method (reason) used for updating the backlight + * when calling backlight_force_update(). + */ enum backlight_update_reason { + /** + * @BACKLIGHT_UPDATE_HOTKEY: The backlight was updated using a hot-key. + */ BACKLIGHT_UPDATE_HOTKEY, + + /** + * @BACKLIGHT_UPDATE_SYSFS: The backlight was updated using sysfs. + */ BACKLIGHT_UPDATE_SYSFS, }; +/** + * enum backlight_type - the type of backlight control + * + * The type of interface used to control the backlight. + */ enum backlight_type { + /** + * @BACKLIGHT_RAW: + * + * The backlight is controlled using hardware registers. + */ BACKLIGHT_RAW = 1, + + /** + * @BACKLIGHT_PLATFORM: + * + * The backlight is controlled using a platform-specific interface. + */ BACKLIGHT_PLATFORM, + + /** + * @BACKLIGHT_FIRMWARE: + * + * The backlight is controlled using a standard firmware interface. + */ BACKLIGHT_FIRMWARE, + + /** + * @BACKLIGHT_TYPE_MAX: Number of entries. + */ BACKLIGHT_TYPE_MAX, }; +/** + * enum backlight_notification - the type of notification + * + * The notifications that is used for notification sent to the receiver + * that registered notifications using backlight_register_notifier(). + */ enum backlight_notification { + /** + * @BACKLIGHT_REGISTERED: The backlight device is registered. + */ BACKLIGHT_REGISTERED, + + /** + * @BACKLIGHT_UNREGISTERED: The backlight revice is unregistered. + */ BACKLIGHT_UNREGISTERED, }; +/** enum backlight_scale - the type of scale used for brightness values + * + * The type of scale used for brightness values. + */ enum backlight_scale { + /** + * @BACKLIGHT_SCALE_UNKNOWN: The scale is unknown. + */ BACKLIGHT_SCALE_UNKNOWN = 0, + + /** + * @BACKLIGHT_SCALE_LINEAR: The scale is linear. + * + * The linear scale will increase brightness the same for each step. + */ BACKLIGHT_SCALE_LINEAR, + + /** + * @BACKLIGHT_SCALE_NON_LINEAR: The scale is not linear. + * + * This is often used when the brightness values tries to adjust to + * the relative perception of the eye demanding a non-linear scale. + */ BACKLIGHT_SCALE_NON_LINEAR, }; @@ -149,7 +221,7 @@ struct backlight_properties { /** * @fb_blank: The power state from the FBIOBLANK ioclt. * - * When the FBIOBLANK ioctl is called fb_blank is set to the + * When the FBIOBLANK ioctl is called @fb_blank is set to the * blank parameter and the update_status() operation is called. * * When the backlight device is enabled @fb_blank is set From patchwork Mon Jun 1 06:52:02 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sam Ravnborg X-Patchwork-Id: 188688 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=-9.6 required=3.0 tests=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=ham 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 2CF61C433DF for ; Mon, 1 Jun 2020 06:52:38 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 065CB206E2 for ; Mon, 1 Jun 2020 06:52:38 +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="CEXAusFg" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726152AbgFAGwh (ORCPT ); Mon, 1 Jun 2020 02:52:37 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44894 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726142AbgFAGwh (ORCPT ); Mon, 1 Jun 2020 02:52:37 -0400 Received: from mail-lj1-x242.google.com (mail-lj1-x242.google.com [IPv6:2a00:1450:4864:20::242]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C37FBC061A0E; Sun, 31 May 2020 23:52:35 -0700 (PDT) Received: by mail-lj1-x242.google.com with SMTP id z6so6697004ljm.13; Sun, 31 May 2020 23:52:35 -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=vDqVAIjccZnYRUpLcbxJO82lc5tSgraJEEtyeI//9cw=; b=CEXAusFgeTZ1RgVQ9hS2P6VoCaZ82REziAk3UsxYQeACDlGmILLx/1tyRgu5k/gsHK 7bhDWlYPZxQ//HvR95PuodmqLBjecdAs3P/yv6AvhsvKnd/T7BIUgwHXAQvim2XUOXMO 02RqhhhLt6EAxVEE4xFd1MfMrb3dQ70WWXGsEyjblCUE521UmSz3KzCLMKGd2YyjTBcp DN8/HmhnXU41qBZ26BynfdCgn47BZOI6N0wZJI1qSDjwg81QvvH/nZRdJVbIqO7Imddy c8BhPMbJ4xv51Q0pkZ1PdoSyGoZR0Nsw5F57UEp666T/rTZbD6uwwH+nQU2V/+J4GRSP hlWw== 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=vDqVAIjccZnYRUpLcbxJO82lc5tSgraJEEtyeI//9cw=; b=Ft1z+/OYEqt9DgXwtN/7y/WLaeapSd13Mb849eAyEcc/GuCSZ4SqeeOYjduowV1X8S /TNXagxHy3yWIA3+UYdAswmt6ZgRQud8/nMhSZ+rZzrldNCJZvsyEZcjYDEmNXRkyqxa sBEfsGuwONj6nQkYPobc/9WnwZ7weB4UgOtX/+DUOSB/1iuW429AA9nr3JhS4laWY8Hb sK30m9Awva5EDelTU6XOq9bmvWfwt8EScjy0ZtG7DUpUtAj2MD0J4SCKpt1mcO+nEekN J6F/YDfJmNCNiG39g7186yyMJEO65mjjO3H563IMbOQAyLTJbRbPssMe1q3iSOTGJmBv BBAw== X-Gm-Message-State: AOAM533PwTvJu8krD1qaneVJV61zJsGv71RaB1fX1TT1jfnUvjE8V9Gl mSp+KjD3+NO8Xh+IO91mlVw= X-Google-Smtp-Source: ABdhPJx/qq0CrraGku2u6S8qFTum2RKXM4M4pOEdTsmcCFc4PeCAn382lO6xEJ0gLuJxdJ41zO8/VQ== X-Received: by 2002:a2e:a0cd:: with SMTP id f13mr6644884ljm.139.1590994353880; Sun, 31 May 2020 23:52:33 -0700 (PDT) Received: from saturn.lan ([2a00:fd00:805f:db00:281d:a604:434c:a58d]) by smtp.gmail.com with ESMTPSA id e13sm2540462ljl.117.2020.05.31.23.52.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 31 May 2020 23:52:33 -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 v3 08/13] backlight: remove the unused backlight_bl driver Date: Mon, 1 Jun 2020 08:52:02 +0200 Message-Id: <20200601065207.492614-9-sam@ravnborg.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200601065207.492614-1-sam@ravnborg.org> References: <20200601065207.492614-1-sam@ravnborg.org> MIME-Version: 1.0 Sender: linux-arm-msm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-arm-msm@vger.kernel.org The backlight_bl driver required initialization using struct generic_bl_info. As there are no more references to this struct there is no users left. So it is safe to delete the driver. Signed-off-by: Sam Ravnborg Reviewed-by: Daniel Thompson Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han --- drivers/video/backlight/Kconfig | 8 -- drivers/video/backlight/Makefile | 1 - drivers/video/backlight/generic_bl.c | 110 --------------------------- include/linux/backlight.h | 9 --- 4 files changed, 128 deletions(-) delete mode 100644 drivers/video/backlight/generic_bl.c diff --git a/drivers/video/backlight/Kconfig b/drivers/video/backlight/Kconfig index 7d22d7377606..14abfeee8868 100644 --- a/drivers/video/backlight/Kconfig +++ b/drivers/video/backlight/Kconfig @@ -173,14 +173,6 @@ config BACKLIGHT_EP93XX To compile this driver as a module, choose M here: the module will be called ep93xx_bl. -config BACKLIGHT_GENERIC - tristate "Generic (aka Sharp Corgi) Backlight Driver" - default y - help - Say y to enable the generic platform backlight driver previously - known as the Corgi backlight driver. If you have a Sharp Zaurus - SL-C7xx, SL-Cxx00 or SL-6000x say y. - config BACKLIGHT_IPAQ_MICRO tristate "iPAQ microcontroller backlight driver" depends on MFD_IPAQ_MICRO diff --git a/drivers/video/backlight/Makefile b/drivers/video/backlight/Makefile index 0c1a1524627a..9b998cfdc56d 100644 --- a/drivers/video/backlight/Makefile +++ b/drivers/video/backlight/Makefile @@ -31,7 +31,6 @@ obj-$(CONFIG_BACKLIGHT_CLASS_DEVICE) += backlight.o obj-$(CONFIG_BACKLIGHT_DA903X) += da903x_bl.o obj-$(CONFIG_BACKLIGHT_DA9052) += da9052_bl.o obj-$(CONFIG_BACKLIGHT_EP93XX) += ep93xx_bl.o -obj-$(CONFIG_BACKLIGHT_GENERIC) += generic_bl.o obj-$(CONFIG_BACKLIGHT_GPIO) += gpio_backlight.o obj-$(CONFIG_BACKLIGHT_HP680) += hp680_bl.o obj-$(CONFIG_BACKLIGHT_HP700) += jornada720_bl.o diff --git a/drivers/video/backlight/generic_bl.c b/drivers/video/backlight/generic_bl.c deleted file mode 100644 index 8fe63dbc8590..000000000000 --- a/drivers/video/backlight/generic_bl.c +++ /dev/null @@ -1,110 +0,0 @@ -// SPDX-License-Identifier: GPL-2.0-only -/* - * Generic Backlight Driver - * - * Copyright (c) 2004-2008 Richard Purdie - */ - -#include -#include -#include -#include -#include -#include -#include - -static int genericbl_intensity; -static struct backlight_device *generic_backlight_device; -static struct generic_bl_info *bl_machinfo; - -static int genericbl_send_intensity(struct backlight_device *bd) -{ - int intensity = bd->props.brightness; - - if (bd->props.power != FB_BLANK_UNBLANK) - intensity = 0; - if (bd->props.state & BL_CORE_FBBLANK) - intensity = 0; - if (bd->props.state & BL_CORE_SUSPENDED) - intensity = 0; - - bl_machinfo->set_bl_intensity(intensity); - - genericbl_intensity = intensity; - - if (bl_machinfo->kick_battery) - bl_machinfo->kick_battery(); - - return 0; -} - -static int genericbl_get_intensity(struct backlight_device *bd) -{ - return genericbl_intensity; -} - -static const struct backlight_ops genericbl_ops = { - .options = BL_CORE_SUSPENDRESUME, - .get_brightness = genericbl_get_intensity, - .update_status = genericbl_send_intensity, -}; - -static int genericbl_probe(struct platform_device *pdev) -{ - struct backlight_properties props; - struct generic_bl_info *machinfo = dev_get_platdata(&pdev->dev); - const char *name = "generic-bl"; - struct backlight_device *bd; - - bl_machinfo = machinfo; - if (!machinfo->limit_mask) - machinfo->limit_mask = -1; - - if (machinfo->name) - name = machinfo->name; - - memset(&props, 0, sizeof(struct backlight_properties)); - props.type = BACKLIGHT_RAW; - props.max_brightness = machinfo->max_intensity; - bd = devm_backlight_device_register(&pdev->dev, name, &pdev->dev, - NULL, &genericbl_ops, &props); - if (IS_ERR(bd)) - return PTR_ERR(bd); - - platform_set_drvdata(pdev, bd); - - bd->props.power = FB_BLANK_UNBLANK; - bd->props.brightness = machinfo->default_intensity; - backlight_update_status(bd); - - generic_backlight_device = bd; - - dev_info(&pdev->dev, "Generic Backlight Driver Initialized.\n"); - return 0; -} - -static int genericbl_remove(struct platform_device *pdev) -{ - struct backlight_device *bd = platform_get_drvdata(pdev); - - bd->props.power = 0; - bd->props.brightness = 0; - backlight_update_status(bd); - - dev_info(&pdev->dev, "Generic Backlight Driver Unloaded\n"); - return 0; -} - -static struct platform_driver genericbl_driver = { - .probe = genericbl_probe, - .remove = genericbl_remove, - .driver = { - .name = "generic-bl", - }, -}; - -module_platform_driver(genericbl_driver); - -MODULE_AUTHOR("Richard Purdie "); -MODULE_DESCRIPTION("Generic Backlight Driver"); -MODULE_LICENSE("GPL"); diff --git a/include/linux/backlight.h b/include/linux/backlight.h index c1c7b1666a9b..6bd981a600ef 100644 --- a/include/linux/backlight.h +++ b/include/linux/backlight.h @@ -453,15 +453,6 @@ static inline void * bl_get_data(struct backlight_device *bl_dev) return dev_get_drvdata(&bl_dev->dev); } -struct generic_bl_info { - const char *name; - int max_intensity; - int default_intensity; - int limit_mask; - void (*set_bl_intensity)(int intensity); - void (*kick_battery)(void); -}; - #ifdef CONFIG_OF struct backlight_device *of_find_backlight_by_node(struct device_node *node); #else From patchwork Mon Jun 1 06:52:04 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sam Ravnborg X-Patchwork-Id: 188687 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=-9.6 required=3.0 tests=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=ham 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 5FC49C433DF for ; Mon, 1 Jun 2020 06:52:41 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 3BB4D20772 for ; Mon, 1 Jun 2020 06:52:41 +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="sy/pCIaU" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726860AbgFAGwk (ORCPT ); Mon, 1 Jun 2020 02:52:40 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44908 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726142AbgFAGwk (ORCPT ); Mon, 1 Jun 2020 02:52:40 -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 E31B8C061A0E; Sun, 31 May 2020 23:52:39 -0700 (PDT) Received: by mail-lj1-x243.google.com with SMTP id q2so6724166ljm.10; Sun, 31 May 2020 23:52:39 -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=eLPbrmDW/Xo7kllaN/jCjZjnSWOdy/pm0/gQ/6XVf4A=; b=sy/pCIaUj13T9e3LXdfQwILdRtEsOihqjqCmAlpi+ZAG38uyQTE6UdXc+uASFgFnUp aa0b/ut2gLuNbsSGBSTZi95lJrPlNBQgWJp3VGCmnztKoD/29bqHjc28reTrc9m8ke2t x0wSf/RDekXJuDSRufwrLqpnsuvzvOSziNd7Z/UXDIOVyN4MlnPPwWLvNwvNy971BQGT YoyY9Jd7+mJ2WCIFTd/krWbAxDSrT7PVKvPK8BSy6y672fB/d3bLS9wKC483H4+ZTXwh wAY9ThG1Ar/QQVF/dzX1gNBJo4peBDoXZJ9WwsWsZFBOHSQxhHXc+YiU9DkfR+RHs1c/ LDsA== 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=eLPbrmDW/Xo7kllaN/jCjZjnSWOdy/pm0/gQ/6XVf4A=; b=tjiK5BiVwElJ0XJOzooAmxytTG0OrHThvSRmx5U7zfwLdDR507NaMi7FkLJAqIXKFq RZXOs4Mg2ifEmfsqyHKEIqP00xCvFwAoZuAV7QpeaTVWvCIn1O+DC/Iv6qWpluB3N7ma GLryqHVepenwdPC0T2ag+DOCq9bcN2bdiMi1JkbLO+yROIysjxhnFT0DHwkgmrALsent ePfjtsiJdNin01ZNAivZGnYDSCykZdDUp4FxplMtje4ci2OZyidf2dir1ucSEijU8V+m bvxSAZTUONuEnPRHsy1UzsfsKg+jwkyZcrJN/5qDqtCq/+iGiwkwJFzNHIytkwZqeLJC k1DA== X-Gm-Message-State: AOAM530nUG3uWBT9+zS7PBLu/WDYkvF6889a+ozPNsHKVowzCrelnSbn wNXo31nPyKeC3Pbo5BDna0M= X-Google-Smtp-Source: ABdhPJx3iN7XIZ42IHrIlaq3HbS6VzZr9rEiDubQTN25H+BVg8cLbISr3mtT4bLA/BTkd8q1dsTEYg== X-Received: by 2002:a2e:9105:: with SMTP id m5mr10594493ljg.408.1590994358348; Sun, 31 May 2020 23:52:38 -0700 (PDT) Received: from saturn.lan ([2a00:fd00:805f:db00:281d:a604:434c:a58d]) by smtp.gmail.com with ESMTPSA id e13sm2540462ljl.117.2020.05.31.23.52.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 31 May 2020 23:52:37 -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 v3 10/13] backlight: add overview and update existing doc Date: Mon, 1 Jun 2020 08:52:04 +0200 Message-Id: <20200601065207.492614-11-sam@ravnborg.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200601065207.492614-1-sam@ravnborg.org> References: <20200601065207.492614-1-sam@ravnborg.org> MIME-Version: 1.0 Sender: linux-arm-msm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-arm-msm@vger.kernel.org Add overview chapter to backlight.c. Update existing kernel-doc to follow a more consistent style and drop kernel-doc for deprecated functions. v2: - Sevaral editorial corrections that makes reading much easier (Daniel) - Spelling fixes (Daniel) - updated intro chapter with a little more info Signed-off-by: Sam Ravnborg Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han --- drivers/video/backlight/backlight.c | 131 +++++++++++++++++++--------- 1 file changed, 90 insertions(+), 41 deletions(-) diff --git a/drivers/video/backlight/backlight.c b/drivers/video/backlight/backlight.c index 17f04cff50ab..06bcddd76a7e 100644 --- a/drivers/video/backlight/backlight.c +++ b/drivers/video/backlight/backlight.c @@ -22,6 +22,46 @@ #include #endif +/** + * DOC: overview + * + * The backlight core supports implementing backlight drivers. + * + * A backlight driver registers a driver using + * devm_backlight_device_register(). The properties of the backlight + * driver such as type and max_brightness must be specified. + * When the core detect changes in for example brightness or power state + * the update_status() operation is called. The backlight driver shall + * implement this operation and use it to adjust backlight. + * + * Several sysfs attributes are provided by the backlight core:: + * + * - brightness R/W, set the requested brightness level + * - actual_brighness RO, the brightness level used by the HW + * - max_brightness RO, the maximum brightness level supported + * + * See Documentation/ABI/stable/sysfs-class-backlight for the full list. + * + * The backlight can be adjusted using the sysfs interface, and + * the backlight driver may also support adjusting backlight using + * a hot-key or some other platfrom or firmware specific way. + * + * The driver shall implement the get_brightness() operation if + * the HW do not support all the levels that can be specified in + * brightness, thus providing user-space access to the actual level + * via the actual_brightness attribute. + * When the backlight changes this is reported to user-space using + * an uevent connected to the actual_brightness attribute. + * When brightness is set by platform specific means, for example + * a hot-key to adjust backlight, the driver must notify the backlight + * core that brightness has changed using backlight_force_update(). + * + * The backlight driver core receives notifications from fbdev and + * if the event is FB_EVENT_BLANK and if the value of blank, from the + * FBIOBLANK ioclt, results in a change in the backlight state the + * update_status() operation is called. + */ + static struct list_head backlight_dev_list; static struct mutex backlight_dev_list_mutex; static struct blocking_notifier_head backlight_notifier; @@ -40,9 +80,17 @@ static const char *const backlight_scale_types[] = { #if defined(CONFIG_FB) || (defined(CONFIG_FB_MODULE) && \ defined(CONFIG_BACKLIGHT_CLASS_DEVICE_MODULE)) -/* This callback gets called when something important happens inside a - * framebuffer driver. We're looking if that important event is blanking, - * and if it is and necessary, we're switching backlight power as well ... +/* + * fb_notifier_callback + * + * This callback gets called when something important happens inside a + * framebuffer driver. The backlight core only cares about FB_BLANK_UNBLANK + * which is reported to the driver using backlight_update_status() + * as a state change. + * + * There may be several fbdev's connected to the backlight device, + * in which case they are kept track of. A state change is only reported + * if there is a change in backlight for the specified fbdev. */ static int fb_notifier_callback(struct notifier_block *self, unsigned long event, void *data) @@ -318,12 +366,15 @@ static struct attribute *bl_device_attrs[] = { ATTRIBUTE_GROUPS(bl_device); /** - * backlight_force_update - tell the backlight subsystem that hardware state - * has changed + * backlight_force_update - force an update due to a hardware change * @bd: the backlight device to update + * @reason: the method used for the backlight update * * Updates the internal state of the backlight in response to a hardware event, - * and generate a uevent to notify userspace + * and generates an uevent to notify userspace. A backlight driver shall call + * backlight_force_update() when the backlight is changed using, for example, + * a hot-key. The updated brightness is read using get_brightness() and the + * brightness value is reported using an uevent. */ void backlight_force_update(struct backlight_device *bd, enum backlight_update_reason reason) @@ -336,19 +387,7 @@ void backlight_force_update(struct backlight_device *bd, } EXPORT_SYMBOL(backlight_force_update); -/** - * backlight_device_register - create and register a new object of - * backlight_device class. - * @name: the name of the new object(must be the same as the name of the - * respective framebuffer device). - * @parent: a pointer to the parent device - * @devdata: an optional pointer to be stored for private driver use. The - * methods may retrieve it by using bl_get_data(bd). - * @ops: the backlight operations structure. - * - * Creates and registers new backlight device. Returns either an - * ERR_PTR() or a pointer to the newly allocated device. - */ +/* deprecated - use devm_backlight_device_register() */ struct backlight_device *backlight_device_register(const char *name, struct device *parent, void *devdata, const struct backlight_ops *ops, const struct backlight_properties *props) @@ -415,6 +454,15 @@ struct backlight_device *backlight_device_register(const char *name, } EXPORT_SYMBOL(backlight_device_register); +/** backlight_device_get_by_type - find first backlight device of a type + * @type: the type of backlight device + * + * Look up the first backlight device of the specified type + * + * RETURNS: + * + * Pointer to backlight device if any was found. Otherwise NULL. + */ struct backlight_device *backlight_device_get_by_type(enum backlight_type type) { bool found = false; @@ -433,12 +481,7 @@ struct backlight_device *backlight_device_get_by_type(enum backlight_type type) } EXPORT_SYMBOL(backlight_device_get_by_type); -/** - * backlight_device_unregister - unregisters a backlight device object. - * @bd: the backlight device object to be unregistered and freed. - * - * Unregisters a previously registered via backlight_device_register object. - */ +/* deprecated - use devm_backlight_device_unregister() */ void backlight_device_unregister(struct backlight_device *bd) { if (!bd) @@ -486,10 +529,12 @@ static int devm_backlight_device_match(struct device *dev, void *res, * backlight_register_notifier - get notified of backlight (un)registration * @nb: notifier block with the notifier to call on backlight (un)registration * - * @return 0 on success, otherwise a negative error code - * * Register a notifier to get notified when backlight devices get registered * or unregistered. + * + * RETURNS: + * + * 0 on success, otherwise a negative error code */ int backlight_register_notifier(struct notifier_block *nb) { @@ -501,10 +546,12 @@ EXPORT_SYMBOL(backlight_register_notifier); * backlight_unregister_notifier - unregister a backlight notifier * @nb: notifier block to unregister * - * @return 0 on success, otherwise a negative error code - * * Register a notifier to get notified when backlight devices get registered * or unregistered. + * + * RETURNS: + * + * 0 on success, otherwise a negative error code */ int backlight_unregister_notifier(struct notifier_block *nb) { @@ -513,20 +560,22 @@ int backlight_unregister_notifier(struct notifier_block *nb) EXPORT_SYMBOL(backlight_unregister_notifier); /** - * devm_backlight_device_register - resource managed backlight_device_register() + * devm_backlight_device_register - register a new backlight device * @dev: the device to register * @name: the name of the device - * @parent: a pointer to the parent device + * @parent: a pointer to the parent device (often the same as @dev) * @devdata: an optional pointer to be stored for private driver use * @ops: the backlight operations structure * @props: the backlight properties * - * @return a struct backlight on success, or an ERR_PTR on error + * Creates and registers new backlight device. When a backlight device + * is registered the configuration must be specified in the @props + * parameter. See description of &backlight_properties. * - * Managed backlight_device_register(). The backlight_device returned - * from this function are automatically freed on driver detach. - * See backlight_device_register() for more information. - */ + * RETURNS: + * + * struct backlight on success, or an ERR_PTR on error +*/ struct backlight_device *devm_backlight_device_register(struct device *dev, const char *name, struct device *parent, void *devdata, const struct backlight_ops *ops, @@ -553,13 +602,13 @@ struct backlight_device *devm_backlight_device_register(struct device *dev, EXPORT_SYMBOL(devm_backlight_device_register); /** - * devm_backlight_device_unregister - resource managed backlight_device_unregister() + * devm_backlight_device_unregister - unregister backlight device * @dev: the device to unregister * @bd: the backlight device to unregister * - * Deallocated a backlight allocated with devm_backlight_device_register(). + * Deallocates a backlight allocated with devm_backlight_device_register(). * Normally this function will not need to be called and the resource management - * code will ensure that the resource is freed. + * code will ensure that the resources are freed. */ void devm_backlight_device_unregister(struct device *dev, struct backlight_device *bd) @@ -650,8 +699,8 @@ static void devm_backlight_release(void *data) } /** - * devm_of_find_backlight - Resource-managed of_find_backlight() - * @dev: Device + * devm_of_find_backlight - find backlight for a device + * @dev: the device * * Device managed version of of_find_backlight(). * The reference on the backlight device is automatically From patchwork Mon Jun 1 06:52:06 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sam Ravnborg X-Patchwork-Id: 188686 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=-9.6 required=3.0 tests=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=ham 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 85461C433E1 for ; Mon, 1 Jun 2020 06:52:46 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 6315D2076B for ; Mon, 1 Jun 2020 06:52:46 +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="mtY7E35P" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727096AbgFAGwq (ORCPT ); Mon, 1 Jun 2020 02:52:46 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44924 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726142AbgFAGwp (ORCPT ); Mon, 1 Jun 2020 02:52:45 -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 2AE43C061A0E; Sun, 31 May 2020 23:52:44 -0700 (PDT) Received: by mail-lj1-x243.google.com with SMTP id z18so6709181lji.12; Sun, 31 May 2020 23:52:44 -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=NjiBPif2aC324+vDH5W7L3OnbFVYWltMaLDt/zt0WxE=; b=mtY7E35P7NMSOhp9i+6bfaqRO2BlrKF2/SCdxL4Wo+C/dxcNueZ/8rL6drsV5Qk4ms OBZHTwJMwRh3vvlu1nl9mBpequPzPsTggrEfpwP84EHz2HBpIB9avd6RWb23Qqp2sjkZ Pb04vSzZr1FEM/sZ8OBTs38Gh1DDOLFSM1Ujn+0t7oUMdCNm9bVm2M0EIeSGSnwt45KB 6Y/glw6EfVkRqqZhnjpU+wNvUkQRAf/gun9TNPiJ1plRGvTPhUJ5Gd9V7gakd43XkzX4 tNhtDSKq6ZvNVi01I14PkmXvUCoLKioBy7SAaHwC79131X0KVxC3qKFBFsgkuxrePiiE nX1g== 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=NjiBPif2aC324+vDH5W7L3OnbFVYWltMaLDt/zt0WxE=; b=Vtkx1uzQTWZ1C2TgmC+7t/ZE3uNgipBa10QFfmojFh19+rNLtMafGMGIP5nZlawuxl AbZyBLjypDNA4HAbc4ukT1pufkYeR8HgdaANJwhS4SysgtOmZapGG7kh30iBmCdw3nBd +B57x2dv6D8we2T9M0rNQWaWVUXXhpWSz1D0TxywV4lSxygKJdZfzbkYbnRsBZ6qa/l1 vIfpdrEE9OmvTp+d8NyE16n+6mwG3yEXD0+IKfVlS1/bOy3DF4yoQVIa+c8K5LJHlDxu DJCxa9V0xQh8HQ3XPlAek/yYApkU7L5m5EkhwvaSF5d+HngZsdra8Ai0Q37q0p1D9bSS jqyA== X-Gm-Message-State: AOAM532xOYN+keFy9fH15XCkVVMhtU+ZhGmC0gxN746u/nMKPz3Pu+sl EydlrPTWBGxcfTcQt8c1r7k= X-Google-Smtp-Source: ABdhPJy7GQRKVdKefzETWFNpD9tAcpKEGeCIQ2ORhC0pwxa34K7ayOx8SXEcMeR6aBbHrE77mAFjFQ== X-Received: by 2002:a2e:8044:: with SMTP id p4mr10445457ljg.151.1590994362678; Sun, 31 May 2020 23:52:42 -0700 (PDT) Received: from saturn.lan ([2a00:fd00:805f:db00:281d:a604:434c:a58d]) by smtp.gmail.com with ESMTPSA id e13sm2540462ljl.117.2020.05.31.23.52.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 31 May 2020 23:52:42 -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 v3 12/13] backlight: as3711_bl: introduce backlight_is_blank() Date: Mon, 1 Jun 2020 08:52:06 +0200 Message-Id: <20200601065207.492614-13-sam@ravnborg.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200601065207.492614-1-sam@ravnborg.org> References: <20200601065207.492614-1-sam@ravnborg.org> MIME-Version: 1.0 Sender: linux-arm-msm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-arm-msm@vger.kernel.org Replaces the open-coded checks of the state, with the backlight_is_blank() helper. This increases readability of the code and aling the functionality across the drivers. Futhermore drop the debug prints in update_status(). If we need debug printing then we can add it to the backlight core. Signed-off-by: Sam Ravnborg Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han Cc: Emil Velikov --- drivers/video/backlight/as3711_bl.c | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/drivers/video/backlight/as3711_bl.c b/drivers/video/backlight/as3711_bl.c index 33f0f0f2e8b3..cc5628beaffd 100644 --- a/drivers/video/backlight/as3711_bl.c +++ b/drivers/video/backlight/as3711_bl.c @@ -107,13 +107,7 @@ static int as3711_bl_update_status(struct backlight_device *bl) int brightness = bl->props.brightness; int ret = 0; - dev_dbg(&bl->dev, "%s(): brightness %u, pwr %x, blank %x, state %x\n", - __func__, bl->props.brightness, bl->props.power, - bl->props.fb_blank, bl->props.state); - - if (bl->props.power != FB_BLANK_UNBLANK || - bl->props.fb_blank != FB_BLANK_UNBLANK || - bl->props.state & (BL_CORE_SUSPENDED | BL_CORE_FBBLANK)) + if (backlight_is_blank(bl)) brightness = 0; if (data->type == AS3711_BL_SU1) {