From patchwork Fri Jul 3 18:45:30 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sam Ravnborg X-Patchwork-Id: 11642639 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 5CFDA60D for ; Fri, 3 Jul 2020 18:46:17 +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 3B9FF2084C for ; Fri, 3 Jul 2020 18:46:17 +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="aUrQbKZd" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 3B9FF2084C 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 662BF6EB97; Fri, 3 Jul 2020 18:46:14 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org 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 D2C946EB9A for ; Fri, 3 Jul 2020 18:46:12 +0000 (UTC) Received: by mail-lj1-x242.google.com with SMTP id e4so38110093ljn.4 for ; Fri, 03 Jul 2020 11:46:12 -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=nbqgxv/h5SeSHOXMolpp1BPamIvzkqESgLDvhPwqMhU=; b=aUrQbKZdkhxD1Dd4uBn5ucmlkFRreyu98hbK7o3nUJZwjsPOawXWWS3FA7FkPHM25i t+C8U4CEYx2Yg5LL/Vs9FGMuAvPEf1RTdiSrn8EvyIxw0IQmpmxWlfxR5tK5D36ezspC VqkBZ7eiUJKfCW88KNSRS0JtIBAGLD+KKpPMpyDTOFfUI3wCZx+MfDnHO+YMtMp9i4fN Ym/N7AHLblWfueGGKW8aszqrB0bYioGSbtVSsrZUvIdOTEhWfUqmBaNpQS3xmKxDUouD ar0ODZlYti3Y9E2NBZ9hkIJC24AyseEOkN1Vjxc+BfGlvVCtCHe8yNYEqFXWa0z/3Zbx aNmQ== 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=nbqgxv/h5SeSHOXMolpp1BPamIvzkqESgLDvhPwqMhU=; b=ggC/IKPzvnzDE3YWW1g9Qj2qMD2QYFvVWZDt0AL0mzOGw02CvKlqvIhutuBgBDHMjv ES9DjeGXB3eSGcMcABd40VmW6JvdlJRhXFfU1I2rroMgwKA37pr+sJtwsmCV/j/UXDyu Z6y/iuPJQ4TyzLwEerES9WcHSEB1vdnpQAA03X/6PW5zF04eRT8ppU36l+FDzuRK9R+K R3segsi4y0IdFeexrtNXUm8McTSvhn/lNIT2Gile7V4Fp/W1lRpH2HVvuQMk5SpGJtZq X5FS5IeV9AGmGpiqns+XI2MIwHOIwfC9EgMhZfjOXZpcj4rum6Qhrt8JF7cEpwyNsP/z cAyg== X-Gm-Message-State: AOAM533Po6k7hgb2z/ySxPVF0NKBVCpnsC/WavQExm0ixu5qnPE2ndhr 8joaNZ7Kra++cVkdBDCossMUx1hiaDc= X-Google-Smtp-Source: ABdhPJyB2KLbGvSFYJK9M08dD+WetXzOuCGvcnziBRnn8Uhx16R3/LsaKsRHnGUZi1/20iEoXXzyoQ== X-Received: by 2002:a2e:8804:: with SMTP id x4mr20595944ljh.56.1593801971005; Fri, 03 Jul 2020 11:46:11 -0700 (PDT) Received: from saturn.lan ([2a00:fd00:805f:db00:4025:a614:1d5c:b7bc]) by smtp.gmail.com with ESMTPSA id h22sm4404224ljg.1.2020.07.03.11.46.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 03 Jul 2020 11:46:10 -0700 (PDT) From: Sam Ravnborg To: dri-devel@lists.freedesktop.org, Jingoo Han , Lee Jones , Daniel Thompson Subject: [PATCH v4 04/20] backlight: improve backlight_properties documentation Date: Fri, 3 Jul 2020 20:45:30 +0200 Message-Id: <20200703184546.144664-5-sam@ravnborg.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200703184546.144664-1-sam@ravnborg.org> References: <20200703184546.144664-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 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" Improve the documentation for backlight_properties and adapt it to kernel-doc style. v3: - Added missing '@' in kernel-doc 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 Reviewed-by: Daniel Thompson Reviewed-by: Emil Velikov Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han --- 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 dfb43ee02ea0..10518b00b059 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 {