From patchwork Fri Jul 3 18:45:31 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sam Ravnborg X-Patchwork-Id: 11642643 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 204A813BD for ; Fri, 3 Jul 2020 18:46:19 +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 F30232084C for ; Fri, 3 Jul 2020 18:46:18 +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="HpaxBh5G" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org F30232084C 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 B53A16EB9A; Fri, 3 Jul 2020 18:46:15 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-lj1-x244.google.com (mail-lj1-x244.google.com [IPv6:2a00:1450:4864:20::244]) by gabe.freedesktop.org (Postfix) with ESMTPS id D56156EB9A for ; Fri, 3 Jul 2020 18:46:14 +0000 (UTC) Received: by mail-lj1-x244.google.com with SMTP id n23so38125815ljh.7 for ; Fri, 03 Jul 2020 11:46:14 -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=3+EMFfJ/GWN/oYTzmUu/mo7ItELrHC8VJ43RJqgEoQE=; b=HpaxBh5GXclKWorfDS8eeubjSbUnPeSdneyP8++kij8FIY+Qnp3c4K9T9afDl2eT/F kMzutjwUbVj9XeRzxdqtcKjTi7hRy3ksWM9rplbsHITFwGsyIg4BbGj1v9cqPy0RFeBd xKJxbxzSwMIvTLRgIIxRTFO0bEKMwQs9C1+fOrxXrD/jItC4h0rVXry/gsFbVk3zf/n+ 19TMl2UhhsocFn2yJIrmfW9qkxZpfWFIhY1p9XVPa05x1UYnLcT8dxCA3UCy/LA9HOc+ mcMRtRYnOQxVeSDp7S1ktRoNFyozsHAbvaSIgkO3mrQlNtUGCtLX1MZlzHxOGDCYZk5Z 7irQ== 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=3+EMFfJ/GWN/oYTzmUu/mo7ItELrHC8VJ43RJqgEoQE=; b=NDsREPCH0VWN4f43MGOblNOWz+oIEn6XgmUMc2iW906N3TYNjPX0V567cqPeUcJ7Hk PBrp4imgGCVr4dmy3RFx5jYLPyzl9HKOfGskVfYdSLNRO178F+TqVdUYd+vUXq9cuOeh nIHRWmVWx8pQB6dWaUotKHF2z9kajsrDts4VRed0CgFLn/6wckt87xgzs4OpySD1fcTy brpJtf+F2q09U/r+yA1UITPI1mQiyM3ylABHslbnW9mDsgDMD1NnLFM1BDq8leI7SkOj fgmG83B7g2jY688De9gUxCKM/z5bMw146Ny+y3dBeFwxjpiFqdND3XgD5uMYf4ZX+kxB dn4w== X-Gm-Message-State: AOAM530bQHb5CNgqXpyvxxEzT96NqD0/SkfPHIG1XwQhxQ/ZwSFh1uNn U4q0hgL28DbiwZHYyBfxbqwbhIKLeC0= X-Google-Smtp-Source: ABdhPJxDMmMZURhZTC0zGczgDx+Llxqhg3gaeOXHUSat2Cl1VgrK5usCllaKBX0X8BU0F3tdoUNFCQ== X-Received: by 2002:a2e:9c95:: with SMTP id x21mr13648532lji.234.1593801973131; Fri, 03 Jul 2020 11:46:13 -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.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 03 Jul 2020 11:46:12 -0700 (PDT) From: Sam Ravnborg To: dri-devel@lists.freedesktop.org, Jingoo Han , Lee Jones , Daniel Thompson Subject: [PATCH v4 05/20] backlight: improve backlight_device documentation Date: Fri, 3 Jul 2020 20:45:31 +0200 Message-Id: <20200703184546.144664-6-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_device and adapt it to kernel-doc style. The updated documentation is more strict on how locking is used. With the update neither update_lock nor ops_lock may be used outside the backlight core. This restriction was introduced to keep the locking simple by keeping it in the core. It was verified that this documents the current state by renaming update_lock => bl_update_lock and ops_lock => bl_ops_lock. The rename did not reveal any uses outside the backlight core. The rename is NOT part of this patch. v3: - Update changelog to explain locking details (Daniel) v2: - Add short intro to all fields (Daniel) - Updated description of update_lock (Daniel) Signed-off-by: Sam Ravnborg Reviewed-by: Emil Velikov Cc: Lee Jones Cc: Daniel Thompson Cc: Jingoo Han Reviewed-by: Daniel Thompson Reviewed-by: Jingoo Han --- include/linux/backlight.h | 72 ++++++++++++++++++++++++++------------- 1 file changed, 49 insertions(+), 23 deletions(-) diff --git a/include/linux/backlight.h b/include/linux/backlight.h index 10518b00b059..7654fe5f1589 100644 --- a/include/linux/backlight.h +++ b/include/linux/backlight.h @@ -14,21 +14,6 @@ #include #include -/* Notes on locking: - * - * backlight_device->ops_lock is an internal backlight lock protecting the - * ops pointer and no code outside the core should need to touch it. - * - * Access to update_status() is serialised by the update_lock mutex since - * most drivers seem to need this and historically get it wrong. - * - * Most drivers don't need locking on their get_brightness() method. - * If yours does, you need to implement it in the driver. You can use the - * update_lock mutex if appropriate. - * - * Any other use of the locks below is probably wrong. - */ - enum backlight_update_reason { BACKLIGHT_UPDATE_HOTKEY, BACKLIGHT_UPDATE_SYSFS, @@ -215,30 +200,71 @@ struct backlight_properties { enum backlight_scale scale; }; +/** + * struct backlight_device - backlight device data + * + * This structure holds all data required by a backlight device. + */ struct backlight_device { - /* Backlight properties */ + /** + * @props: Backlight properties + */ struct backlight_properties props; - /* Serialise access to update_status method */ + /** + * @update_lock: The lock used when calling the update_status() operation. + * + * update_lock is an internal backlight lock that serialise access + * to the update_status() operation. The backlight core holds the update_lock + * when calling the update_status() operation. The update_lock shall not + * be used by backlight drivers. + */ struct mutex update_lock; - /* This protects the 'ops' field. If 'ops' is NULL, the driver that - registered this device has been unloaded, and if class_get_devdata() - points to something in the body of that driver, it is also invalid. */ + /** + * @ops_lock: The lock used around everything related to backlight_ops. + * + * ops_lock is an internal backlight lock that protects the ops pointer + * and is used around all accesses to ops and when the operations are + * invoked. The ops_lock shall not be used by backlight drivers. + */ struct mutex ops_lock; + + /** + * @ops: Pointer to the backlight operations. + * + * If ops is NULL, the driver that registered this device has been unloaded, + * and if class_get_devdata() points to something in the body of that driver, + * it is also invalid. + */ const struct backlight_ops *ops; - /* The framebuffer notifier block */ + /** + * @fb_notif: The framebuffer notifier block + */ struct notifier_block fb_notif; - /* list entry of all registered backlight devices */ + /** + * @entry: List entry of all registered backlight devices + */ struct list_head entry; + /** + * @dev: Parent device. + */ struct device dev; - /* Multiple framebuffers may share one backlight device */ + /** + * @fb_bl_on: The state of individual fbdev's. + * + * Multiple fbdev's may share one backlight device. The fb_bl_on + * records the state of the individual fbdev. + */ bool fb_bl_on[FB_MAX]; + /** + * @use_count: The number of uses of fb_bl_on. + */ int use_count; };