All of lore.kernel.org
 help / color / mirror / Atom feed
From: "Uwe Kleine-König" <u.kleine-koenig@pengutronix.de>
To: Russell King <linux@armlinux.org.uk>, Stephen Boyd <sboyd@kernel.org>
Cc: linux-clk@vger.kernel.org, kernel@pengutronix.de,
	Michael Turquette <mturquette@baylibre.com>,
	Jonathan Cameron <jic23@kernel.org>,
	Alexandru Ardelean <aardelean@deviqon.com>
Subject: [PATCH v9 1/4] clk: Improve documentation for devm_clk_get() and its optional variant
Date: Fri, 20 May 2022 09:57:34 +0200	[thread overview]
Message-ID: <20220520075737.758761-2-u.kleine-koenig@pengutronix.de> (raw)
In-Reply-To: <20220520075737.758761-1-u.kleine-koenig@pengutronix.de>

Make use of "Context:" and "Return:". Mention that the clk is not to be
expected to be prepared, previously only not being enabled was mentioned
which probably dates from the times when the concept of clk preparation
wasn't invented yet.

Also describe devm_clk_get_optional() fully instead of just referencing
devm_clk_get().

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
 include/linux/clk.h | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/include/linux/clk.h b/include/linux/clk.h
index 39faa54efe88..c8fc398d2ad7 100644
--- a/include/linux/clk.h
+++ b/include/linux/clk.h
@@ -443,15 +443,16 @@ int __must_check devm_clk_bulk_get_all(struct device *dev,
  * @dev: device for clock "consumer"
  * @id: clock consumer ID
  *
- * Returns a struct clk corresponding to the clock producer, or
+ * Context: May sleep.
+ *
+ * Return: a struct clk corresponding to the clock producer, or
  * valid IS_ERR() condition containing errno.  The implementation
  * uses @dev and @id to determine the clock consumer, and thereby
  * the clock producer.  (IOW, @id may be identical strings, but
  * clk_get may return different clock producers depending on @dev.)
  *
- * Drivers must assume that the clock source is not enabled.
- *
- * devm_clk_get should not be called from within interrupt context.
+ * Drivers must assume that the clock source is neither prepared nor
+ * enabled.
  *
  * The clock will automatically be freed when the device is unbound
  * from the bus.
@@ -464,8 +465,20 @@ struct clk *devm_clk_get(struct device *dev, const char *id);
  * @dev: device for clock "consumer"
  * @id: clock consumer ID
  *
- * Behaves the same as devm_clk_get() except where there is no clock producer.
- * In this case, instead of returning -ENOENT, the function returns NULL.
+ * Context: May sleep.
+ *
+ * Return: a struct clk corresponding to the clock producer, or
+ * valid IS_ERR() condition containing errno.  The implementation
+ * uses @dev and @id to determine the clock consumer, and thereby
+ * the clock producer.  If no such clk is found, it returns NULL
+ * which serves as a dummy clk.  That's the only difference compared
+ * to devm_clk_get().
+ *
+ * Drivers must assume that the clock source is neither prepared nor
+ * enabled.
+ *
+ * The clock will automatically be freed when the device is unbound
+ * from the bus.
  */
 struct clk *devm_clk_get_optional(struct device *dev, const char *id);
 
-- 
2.35.1


  reply	other threads:[~2022-05-20  7:58 UTC|newest]

Thread overview: 23+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-05-20  7:57 [PATCH v9 0/4] clk: provide new devm helpers for prepared and enabled clocks Uwe Kleine-König
2022-05-20  7:57 ` Uwe Kleine-König
2022-05-20  7:57 ` Uwe Kleine-König [this message]
2022-06-07 11:46   ` [PATCH v9 1/4] clk: Improve documentation for devm_clk_get() and its optional variant Russell King (Oracle)
2022-06-16  2:35   ` Stephen Boyd
2022-05-20  7:57 ` [PATCH v9 2/4] clk: generalize devm_clk_get() a bit Uwe Kleine-König
2022-06-16  2:35   ` Stephen Boyd
     [not found]   ` <CGME20220620152612eucas1p2bd95bcec491a02c486d0a5f6b97864cd@eucas1p2.samsung.com>
2022-06-20 15:26     ` Marek Szyprowski
2022-06-20 17:18       ` [PATCH] clk: Fix pointer casting to prevent oops in devm_clk_release() Uwe Kleine-König
2022-06-21  6:25         ` Marek Szyprowski
2022-06-21  9:52           ` Uwe Kleine-König
2022-06-22 17:22         ` Uwe Kleine-König
2022-06-22 23:11         ` Stephen Boyd
2022-05-20  7:57 ` [PATCH v9 3/4] clk: Provide new devm_clk helpers for prepared and enabled clocks Uwe Kleine-König
2022-06-16  2:37   ` Stephen Boyd
2022-05-20  7:57 ` [PATCH v9 4/4] clk: meson: axg-audio: Don't duplicate devm_clk_get_enabled() Uwe Kleine-König
2022-05-20  7:57   ` Uwe Kleine-König
2022-06-16  2:37   ` Stephen Boyd
2022-06-16  2:37     ` Stephen Boyd
2022-06-07 11:08 ` [PATCH v9 0/4] clk: provide new devm helpers for prepared and enabled clocks Uwe Kleine-König
2022-06-07 11:08   ` Uwe Kleine-König
2022-06-07 11:42   ` Russell King (Oracle)
2022-06-07 11:42     ` Russell King (Oracle)

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=20220520075737.758761-2-u.kleine-koenig@pengutronix.de \
    --to=u.kleine-koenig@pengutronix.de \
    --cc=aardelean@deviqon.com \
    --cc=jic23@kernel.org \
    --cc=kernel@pengutronix.de \
    --cc=linux-clk@vger.kernel.org \
    --cc=linux@armlinux.org.uk \
    --cc=mturquette@baylibre.com \
    --cc=sboyd@kernel.org \
    --subject='Re: [PATCH v9 1/4] clk: Improve documentation for devm_clk_get() and its optional variant' \
    /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

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.