Linux-PWM Archive on lore.kernel.org
 help / color / Atom feed
From: Sam Ravnborg <sam@ravnborg.org>
To: dri-devel@lists.freedesktop.org,
	Jingoo Han <jingoohan1@gmail.com>,
	Lee Jones <lee.jones@linaro.org>,
	Daniel Thompson <daniel.thompson@linaro.org>
Cc: Andy Gross <agross@kernel.org>,
	Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>,
	Bjorn Andersson <bjorn.andersson@linaro.org>,
	Daniel Vetter <daniel.vetter@ffwll.ch>,
	David Airlie <airlied@linux.ie>,
	Emil Velikov <emil.l.velikov@gmail.com>,
	Jonathan Corbet <corbet@lwn.net>,
	linux-arm-msm@vger.kernel.org, linux-pwm@vger.kernel.org,
	Maarten Lankhorst <maarten.lankhorst@linux.intel.com>,
	Maxime Ripard <mripard@kernel.org>,
	Michael Hennerich <michael.hennerich@analog.com>,
	patches@opensource.cirrus.com,
	Support Opensource <support.opensource@diasemi.com>,
	Thierry Reding <thierry.reding@gmail.com>,
	Thomas Zimmermann <tzimmermann@suse.de>,
	Uwe Kleine-Konig <u.kleine-koenig@pengutronix.de>,
	Peter Ujfalusi <peter.ujfalusi@ti.com>, Tomi Valkeinen <tomi.v>
Subject: [PATCH v5 05/19] backlight: improve backlight_device documentation
Date: Sun, 19 Jul 2020 10:07:29 +0200
Message-ID: <20200719080743.8560-6-sam@ravnborg.org> (raw)
In-Reply-To: <20200719080743.8560-1-sam@ravnborg.org>

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 <sam@ravnborg.org>
Reviewed-by: Emil Velikov <emil.l.velikov@gmail.com>
Reviewed-by: Daniel Thompson <daniel.thompson@linaro.org>
Reviewed-by: Jingoo Han <jingoohan1@gmail.com>
Cc: Lee Jones <lee.jones@linaro.org>
Cc: Daniel Thompson <daniel.thompson@linaro.org>
Cc: Jingoo Han <jingoohan1@gmail.com>
---
 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 <linux/mutex.h>
 #include <linux/notifier.h>
 
-/* 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;
 };
 
-- 
2.25.1

  parent reply index

Thread overview: 24+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-07-19  8:07 [PATCH v5 0/19] backlight: backlight updates Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 01/19] backlight: refactor fb_notifier_callback() Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 02/19] backlight: add backlight_is_blank() Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 03/19] backlight: improve backlight_ops documentation Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 04/19] backlight: improve backlight_properties documentation Sam Ravnborg
2020-07-19  8:07 ` Sam Ravnborg [this message]
2020-07-19  8:07 ` [PATCH v5 06/19] backlight: document inline functions in backlight.h Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 07/19] backlight: document enums " Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 08/19] backlight: remove the unused backlight_bl driver Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 09/19] backlight: drop extern from prototypes Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 10/19] backlight: add overview and update existing doc Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 11/19] backlight: wire up kernel-doc documentation Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 12/19] backlight: introduce backlight_get_brightness() Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 13/19] backlight: as3711_bl: simplify update_status Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 14/19] backlight: cr_bllcd: introduce gpio-backlight semantics Sam Ravnborg
2020-07-20  8:48   ` Daniel Thompson
2020-07-20  9:14     ` Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 15/19] backlight: gpio_backlight: simplify update_status() Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 16/19] backlight: jornada720_bl: introduce backlight_is_blank() Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 17/19] backlight: use backlight_get_brightness() Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 18/19] backlight: drop backlight_put() Sam Ravnborg
2020-07-19  8:07 ` [PATCH v5 19/19] backlight: make of_find_backlight static Sam Ravnborg
2020-07-20  9:36 ` [PATCH v5 0/19] backlight: backlight updates Lee Jones
2020-07-20 11:01   ` Sam Ravnborg

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200719080743.8560-6-sam@ravnborg.org \
    --to=sam@ravnborg.org \
    --cc=agross@kernel.org \
    --cc=airlied@linux.ie \
    --cc=b.zolnierkie@samsung.com \
    --cc=bjorn.andersson@linaro.org \
    --cc=corbet@lwn.net \
    --cc=daniel.thompson@linaro.org \
    --cc=daniel.vetter@ffwll.ch \
    --cc=dri-devel@lists.freedesktop.org \
    --cc=emil.l.velikov@gmail.com \
    --cc=jingoohan1@gmail.com \
    --cc=lee.jones@linaro.org \
    --cc=linux-arm-msm@vger.kernel.org \
    --cc=linux-pwm@vger.kernel.org \
    --cc=maarten.lankhorst@linux.intel.com \
    --cc=michael.hennerich@analog.com \
    --cc=mripard@kernel.org \
    --cc=patches@opensource.cirrus.com \
    --cc=peter.ujfalusi@ti.com \
    --cc=support.opensource@diasemi.com \
    --cc=thierry.reding@gmail.com \
    --cc=tzimmermann@suse.de \
    --cc=u.kleine-koenig@pengutronix.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-PWM Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-pwm/0 linux-pwm/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-pwm linux-pwm/ https://lore.kernel.org/linux-pwm \
		linux-pwm@vger.kernel.org
	public-inbox-index linux-pwm

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-pwm


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git