Skip to contentSkip to conversation

clk: Clean up optional helpers, and add API docs to HTML

PATCH Superseded Sean Anderson 4 participants 12 messages Dec 1, 2021 – Dec 2, 2021

Subsystems (5)

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

cover clk: Clean up optional helpers, and add API docs to HTML

This cleans up the various optional helpers for clocks, and adds a new one. While we're at it, also convert the existing API docs to our HTML documentation.

Sean Anderson (5):
clk: Rename clk_get_optional_nodev
clk: Inline clk_get_*_optional
clk: Add client API to HTML docs
clk: Add driver API to HTML docs
clk: Add clk_get_by_name_optional

 doc/api/clk.rst            |  19 +++
 doc/api/index.rst          |   1 +
 drivers/clk/clk-uclass.c   |  21 ---
 drivers/clk/clk_zynq.c     |   5 +-
 drivers/phy/phy-mtk-tphy.c |   8 +-
 drivers/rng/meson-rng.c    |   4 +-
 include/clk-uclass.h       | 187 +++++++++++++----------
 include/clk.h              | 306 +++++++++++++++++++++----------------
 8 files changed, 310 insertions(+), 241 deletions(-)
 create mode 100644 doc/api/clk.rst
Signature · 1 line
2.33.0
#1 lore raw

PATCH 1/5 clk: Rename clk_get_optional_nodev

This normalizes the name of this accessor function to put "_optional" last.

---

 drivers/clk/clk-uclass.c   | 3 ++-
 drivers/phy/phy-mtk-tphy.c | 8 ++++----
 include/clk.h              | 7 ++++---
 3 files changed, 10 insertions(+), 8 deletions(-)
drivers/clk/clk-uclass.c +2 -1
index 493018b33e..18699d69e3 100644
@@ -432,7 +432,8 @@ int clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk)
 	return clk_get_by_index_nodev(node, index, clk);
 }
 
-int clk_get_optional_nodev(ofnode node, const char *name, struct clk *clk)
+int clk_get_by_name_nodev_optional(ofnode node, const char *name,
+				   struct clk *clk)
 {
 	int ret;
 
drivers/phy/phy-mtk-tphy.c +4 -4
index 824244b852..2dd964f7b2 100644
@@ -723,13 +723,13 @@ static int mtk_tphy_probe(struct udevice *dev)
 		tphy->phys[index] = instance;
 		index++;
 
-		err = clk_get_optional_nodev(subnode, "ref",
-					     &instance->ref_clk);
+		err = clk_get_by_name_nodev_optional(subnode, "ref",
+						     &instance->ref_clk);
 		if (err)
 			return err;
 
-		err = clk_get_optional_nodev(subnode, "da_ref",
-					     &instance->da_ref_clk);
+		err = clk_get_by_name_nodev_optional(subnode, "da_ref",
+						     &instance->da_ref_clk);
 		if (err)
 			return err;
 	}
include/clk.h +4 -3
index a928879b12..943c87f3c3 100644
@@ -194,7 +194,7 @@ int clk_get_by_name(struct udevice *dev, const char *name, struct clk *clk);
 int clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk);
 
 /**
- * clk_get_optional_nodev - Get/request an optinonal clock by name
+ * clk_get_by_name_nodev_optional - Get/request an optinonal clock by name
  *		without a device.
  * @node:	The client ofnode.
  * @name:	The name of the clock to request.
@@ -206,7 +206,8 @@ int clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk);
  * no clock producer, in this case, skip the error number -ENODATA, and
  * the function returns 0.
  */
-int clk_get_optional_nodev(ofnode node, const char *name, struct clk *clk);
+int clk_get_by_name_nodev_optional(ofnode node, const char *name,
+				   struct clk *clk);
 
 /**
  * devm_clk_get - lookup and obtain a managed reference to a clock producer.
@@ -291,7 +292,7 @@ clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk)
 }
 
 static inline int
-clk_get_optional_nodev(ofnode node, const char *name, struct clk *clk)
+clk_get_by_name_nodev_optional(ofnode node, const char *name, struct clk *clk)
 {
 	return -ENOSYS;
 }
Signature · 1 line
2.33.0
#2 lore raw

PATCH 2/5 clk: Inline clk_get_*_optional

In reply to Sean Anderson

The optional varients of clk_get_* functions are just simple wrappers. Reduce code size a bit by inlining them. On platforms where it is not used (most of them), it will not be compiled in any more. On platforms where they are used, the inlined branch should not cause any significant growth.

---

 drivers/clk/clk-uclass.c | 22 ---------------
 include/clk.h            | 58 ++++++++++++++++++++++++----------------
 2 files changed, 35 insertions(+), 45 deletions(-)
drivers/clk/clk-uclass.c +0 -22
index 18699d69e3..168fb67019 100644
@@ -432,18 +432,6 @@ int clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk)
 	return clk_get_by_index_nodev(node, index, clk);
 }
 
-int clk_get_by_name_nodev_optional(ofnode node, const char *name,
-				   struct clk *clk)
-{
-	int ret;
-
-	ret = clk_get_by_name_nodev(node, name, clk);
-	if (ret == -ENODATA)
-		return 0;
-
-	return ret;
-}
-
 int clk_release_all(struct clk *clk, int count)
 {
 	int i, ret;
@@ -824,16 +812,6 @@ struct clk *devm_clk_get(struct udevice *dev, const char *id)
 	return clk;
 }
 
-struct clk *devm_clk_get_optional(struct udevice *dev, const char *id)
-{
-	struct clk *clk = devm_clk_get(dev, id);
-
-	if (PTR_ERR(clk) == -ENODATA)
-		return NULL;
-
-	return clk;
-}
-
 void devm_clk_put(struct udevice *dev, struct clk *clk)
 {
 	int rc;
include/clk.h +35 -23

82 lines not on this page · raw message

Signature · 1 line
2.33.0
#3 lore raw

PATCH 3/5 clk: Add client API to HTML docs

In reply to Sean Anderson

This converts the existing client (aka clk.h) documentation to kernel doc format, and adds it to the HTML docs. I have tried to preserve existing comments as much as possible, refraining from semantic changes.

---

 doc/api/clk.rst   |  13 +++
 doc/api/index.rst |   1 +
 include/clk.h     | 229 +++++++++++++++++++++++-----------------------
 3 files changed, 129 insertions(+), 114 deletions(-)
 create mode 100644 doc/api/clk.rst
doc/api/clk.rst new file +13 -0
new file mode 100644
index 0000000000..7eb3b5645a
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Clock API
+=========
+
+.. kernel-doc:: include/clk.h
+   :doc: Overview
+
+Client API
+----------
+
+.. kernel-doc:: include/clk.h
+   :internal:
doc/api/index.rst +1 -0
index 806c7385a6..83d4f3e5c1 100644
@@ -6,6 +6,7 @@ U-Boot API documentation
 .. toctree::
    :maxdepth: 2
 
+   clk
    dfu
    efi
    getopt
include/clk.h +115 -114

511 lines not on this page · raw message

Signature · 1 line
2.33.0
#5 lore raw

PATCH 4/5 clk: Add driver API to HTML docs

In reply to Sean Anderson

This converts the existing driver API docs (clk-uclass.h) to kernel doc format and adds them to the HTML documentation. Because the kernel doc sphinx converter does not handle functions in structs very well, the individual methods are documented separately. This is primarily inspired by the phylink documentation [1], which uses this trick extensively.

[1] https://www.kernel.org/doc/html/latest/networking/kapi.html#c.phylink_mac_ops

---

 doc/api/clk.rst      |   6 ++
 include/clk-uclass.h | 187 +++++++++++++++++++++++++------------------
 2 files changed, 115 insertions(+), 78 deletions(-)
doc/api/clk.rst +6 -0
index 7eb3b5645a..7c27066928 100644
@@ -11,3 +11,9 @@ Client API
 
 .. kernel-doc:: include/clk.h
    :internal:
+
+Driver API
+----------
+
+.. kernel-doc:: include/clk-uclass.h
+   :internal:
include/clk-uclass.h +109 -78

205 lines not on this page · raw message

Signature · 1 line
2.33.0
Tested-by on v1 4/5
#6 lore raw

Re: [PATCH 4/5] clk: Add driver API to HTML docs

Quoted 9 lines · Sean Anderson

This converts the existing driver API docs (clk-uclass.h) to kernel doc format and adds them to the HTML documentation. Because the kernel doc sphinx converter does not handle functions in structs very well, the individual methods are documented separately. This is primarily inspired by the phylink documentation [1], which uses this trick extensively.

[1]https://www.kernel.org/doc/html/latest/networking/kapi.html#c.phylink_mac_ops

make htmldocs shows no problems

#7 lore raw

PATCH 5/5 clk: Add clk_get_by_name_optional

In reply to Sean Anderson

This adds a helper function for clk_get_by_name in cases where the clock is optional. Hopefully this helps point driver writers in the right direction. Also convert some existing users.

---

 drivers/clk/clk_zynq.c  |  5 +++--
 drivers/rng/meson-rng.c |  4 ++--
 include/clk.h           | 24 ++++++++++++++++++++++++
 3 files changed, 29 insertions(+), 4 deletions(-)
drivers/clk/clk_zynq.c +3 -2
index 18915c3e04..e80500e382 100644
@@ -472,8 +472,9 @@ static int zynq_clk_probe(struct udevice *dev)
 
 	for (i = 0; i < 2; i++) {
 		sprintf(name, "gem%d_emio_clk", i);
-		ret = clk_get_by_name(dev, name, &priv->gem_emio_clk[i]);
-		if (ret < 0 && ret != -ENODATA) {
+		ret = clk_get_by_name_optional(dev, name,
+					       &priv->gem_emio_clk[i]);
+		if (ret) {
 			dev_err(dev, "failed to get %s clock\n", name);
 			return ret;
 		}
drivers/rng/meson-rng.c +2 -2
index 5a4f45ad5a..e0a1e8c7e0 100644
@@ -91,8 +91,8 @@ static int meson_rng_of_to_plat(struct udevice *dev)
 		return -ENODEV;
 
 	/* Get optional "core" clock */
-	err = clk_get_by_name(dev, "core", &pdata->clk);
-	if (err && err != -ENODATA)
+	err = clk_get_by_name_optional(dev, "core", &pdata->clk);
+	if (err)
 		return err;
 
 	return 0;
include/clk.h +24 -0
index 103ef16bf9..36721188d0 100644
@@ -292,6 +292,30 @@ static inline int clk_release_all(struct clk *clk, int count)
 }
 #endif
 
+/**
+ * clk_get_by_name_optional() - Get/request a optional clock by name.
+ * @dev:	The client device.
+ * @name:	The name of the clock to request, within the client's list of
+ *		clocks.
+ * @clk:	A pointer to a clock struct to initialize.
+ *
+ * Behaves the same as clk_get_by_name(), except when there is no clock
+ * provider. In the latter case, return 0.
+ *
+ * Return: 0 if OK, or a negative error code.
+ */
+static inline int clk_get_by_name_optional(struct udevice *dev,
+					   const char *name, struct clk *clk)
+{
+	int ret;
+
+	ret = clk_get_by_name_optional(dev, name, clk);
+	if (ret == -ENODATA)
+		return 0;
+
+	return ret;
+}
+
 /**
  * clk_get_by_name_nodev_optional - Get/request an optinonal clock by name
  *		without a device.
Signature · 1 line
2.33.0
Reviewed-by on v1 5/5
#8 lore raw

Re: [PATCH 5/5] clk: Add clk_get_by_name_optional

Quoted 69 lines · Sean Anderson

This adds a helper function for clk_get_by_name in cases where the clock is optional. Hopefully this helps point driver writers in the right direction. Also convert some existing users.

---

 drivers/clk/clk_zynq.c  |  5 +++--
 drivers/rng/meson-rng.c |  4 ++--
 include/clk.h           | 24 ++++++++++++++++++++++++
 3 files changed, 29 insertions(+), 4 deletions(-)
drivers/clk/clk_zynq.c +3 -2
index 18915c3e04..e80500e382 100644
@@ -472,8 +472,9 @@ static int zynq_clk_probe(struct udevice *dev)
 
 	for (i = 0; i < 2; i++) {
 		sprintf(name, "gem%d_emio_clk", i);
-		ret = clk_get_by_name(dev, name, &priv->gem_emio_clk[i]);
-		if (ret < 0 && ret != -ENODATA) {
+		ret = clk_get_by_name_optional(dev, name,
+					       &priv->gem_emio_clk[i]);
+		if (ret) {
 			dev_err(dev, "failed to get %s clock\n", name);
 			return ret;
 		}
drivers/rng/meson-rng.c +2 -2
index 5a4f45ad5a..e0a1e8c7e0 100644
@@ -91,8 +91,8 @@ static int meson_rng_of_to_plat(struct udevice *dev)
 		return -ENODEV;
 
 	/* Get optional "core" clock */
-	err = clk_get_by_name(dev, "core", &pdata->clk);
-	if (err && err != -ENODATA)
+	err = clk_get_by_name_optional(dev, "core", &pdata->clk);
+	if (err)
 		return err;
 
 	return 0;
include/clk.h +17 -0
index 103ef16bf9..36721188d0 100644
@@ -292,6 +292,30 @@ static inline int clk_release_all(struct clk *clk, int count)
 }
 #endif
 
+/**
+ * clk_get_by_name_optional() - Get/request a optional clock by name.
+ * @dev:	The client device.
+ * @name:	The name of the clock to request, within the client's list of
+ *		clocks.
+ * @clk:	A pointer to a clock struct to initialize.
+ *
+ * Behaves the same as clk_get_by_name(), except when there is no clock
+ * provider. In the latter case, return 0.
+ *
+ * Return: 0 if OK, or a negative error code.
+ */
+static inline int clk_get_by_name_optional(struct udevice *dev,
+					   const char *name, struct clk *clk)
+{
+	int ret;
+

include/clk.h static inline int clk_release_all(struct clk *clk, int count) · line 321

Quoted 10 lines
include/clk.h +7 -0
+	ret = clk_get_by_name_optional(dev, name, clk);
+	if (ret == -ENODATA)
+		return 0;
+
+	return ret;
+}
+
 /**
  * clk_get_by_name_nodev_optional - Get/request an optinonal clock by name
  *		without a device.

For meson-rng:

#9 lore raw

Re: [PATCH 5/5] clk: Add clk_get_by_name_optional

In reply to Sean Anderson

Hi Sean,

Quoted 49 lines · Sean Anderson

This adds a helper function for clk_get_by_name in cases where the clock is optional. Hopefully this helps point driver writers in the right direction. Also convert some existing users.

---

 drivers/clk/clk_zynq.c  |  5 +++--
 drivers/rng/meson-rng.c |  4 ++--
 include/clk.h           | 24 ++++++++++++++++++++++++
 3 files changed, 29 insertions(+), 4 deletions(-)
drivers/clk/clk_zynq.c +3 -2
index 18915c3e04..e80500e382 100644
@@ -472,8 +472,9 @@ static int zynq_clk_probe(struct udevice *dev)
 
        for (i = 0; i < 2; i++) {
                sprintf(name, "gem%d_emio_clk", i);
-               ret = clk_get_by_name(dev, name, &priv->gem_emio_clk[i]);
-               if (ret < 0 && ret != -ENODATA) {
+               ret = clk_get_by_name_optional(dev, name,
+                                              &priv->gem_emio_clk[i]);
+               if (ret) {
                        dev_err(dev, "failed to get %s clock\n", name);
                        return ret;
                }
drivers/rng/meson-rng.c +2 -2
index 5a4f45ad5a..e0a1e8c7e0 100644
@@ -91,8 +91,8 @@ static int meson_rng_of_to_plat(struct udevice *dev)
                return -ENODEV;
 
        /* Get optional "core" clock */
-       err = clk_get_by_name(dev, "core", &pdata->clk);
-       if (err && err != -ENODATA)
+       err = clk_get_by_name_optional(dev, "core", &pdata->clk);
+       if (err)
                return err;
 
        return 0;
include/clk.h +0 -0
index 103ef16bf9..36721188d0 100644

include/clk.h static inline int clk_release_all(struct clk *clk, int count) · line 296

Quoted 5 lines
include/clk.h +2 -0
@@ -292,6 +292,30 @@ static inline int clk_release_all(struct clk *clk, int count)
 }
 #endif
 
+/**
+ * clk_get_by_name_optional() - Get/request a optional clock by name.

Can I suggest we rename this to ..._opt as it is shorter?

Quoted 26 lines
include/clk.h +22 -1
+ * @dev:       The client device.
+ * @name:      The name of the clock to request, within the client's list of
+ *             clocks.
+ * @clk:       A pointer to a clock struct to initialize.
+ *
+ * Behaves the same as clk_get_by_name(), except when there is no clock
+ * provider. In the latter case, return 0.
+ *
+ * Return: 0 if OK, or a negative error code.
+ */
+static inline int clk_get_by_name_optional(struct udevice *dev,
+                                          const char *name, struct clk *clk)
+{
+       int ret;
+
+       ret = clk_get_by_name_optional(dev, name, clk);
+       if (ret == -ENODATA)
+               return 0;
+
+       return ret;
+}
+
 /**
  * clk_get_by_name_nodev_optional - Get/request an optinonal clock by name
  *             without a device.
--
Quoted 2 lines

2.33.0

Regards,
SImon

#10 lore raw

Re: [PATCH 5/5] clk: Add clk_get_by_name_optional

Hi Simon,

Quoted 55 lines · Simon Glass

Hi Sean,

Quoted 52 lines · Sean Anderson

This adds a helper function for clk_get_by_name in cases where the clock is optional. Hopefully this helps point driver writers in the right direction. Also convert some existing users.

---

  drivers/clk/clk_zynq.c  |  5 +++--
  drivers/rng/meson-rng.c |  4 ++--
  include/clk.h           | 24 ++++++++++++++++++++++++
  3 files changed, 29 insertions(+), 4 deletions(-)
drivers/clk/clk_zynq.c +3 -2
index 18915c3e04..e80500e382 100644
@@ -472,8 +472,9 @@ static int zynq_clk_probe(struct udevice *dev)
 
         for (i = 0; i < 2; i++) {
                 sprintf(name, "gem%d_emio_clk", i);
-               ret = clk_get_by_name(dev, name, &priv->gem_emio_clk[i]);
-               if (ret < 0 && ret != -ENODATA) {
+               ret = clk_get_by_name_optional(dev, name,
+                                              &priv->gem_emio_clk[i]);
+               if (ret) {
                         dev_err(dev, "failed to get %s clock\n", name);
                         return ret;
                 }
drivers/rng/meson-rng.c +2 -2
index 5a4f45ad5a..e0a1e8c7e0 100644
@@ -91,8 +91,8 @@ static int meson_rng_of_to_plat(struct udevice *dev)
                 return -ENODEV;
 
         /* Get optional "core" clock */
-       err = clk_get_by_name(dev, "core", &pdata->clk);
-       if (err && err != -ENODATA)
+       err = clk_get_by_name_optional(dev, "core", &pdata->clk);
+       if (err)
                 return err;
 
         return 0;
include/clk.h +0 -0
index 103ef16bf9..36721188d0 100644
@@ -292,6 +292,30 @@ static inline int clk_release_all(struct clk *clk, int count)
  }
  #endif
 
Quoted 4 lines

include/clk.h static inline int clk_release_all(struct clk *clk, int count) · line 296

Quoted 2 lines
include/clk.h +2 -0
+/**
+ * clk_get_by_name_optional() - Get/request a optional clock by name.

Can I suggest we rename this to ..._opt as it is shorter?

This follows the general trend of suffixing _optional. For example (and several of these are borrowed from Linux):

clk_get_optional
reset_control_bulk_get_optional_exclusive
gpiod_get_optional
platform_get_irq_byname_optional

and particularly, the Linux clock subsystem uses _optional and not _opt as a suffix. While some of these names can get fairly long-winded, I think we should go for consistency here.

--Sean

Quoted 32 lines
Quoted 26 lines
include/clk.h +22 -1
+ * @dev:       The client device.
+ * @name:      The name of the clock to request, within the client's list of
+ *             clocks.
+ * @clk:       A pointer to a clock struct to initialize.
+ *
+ * Behaves the same as clk_get_by_name(), except when there is no clock
+ * provider. In the latter case, return 0.
+ *
+ * Return: 0 if OK, or a negative error code.
+ */
+static inline int clk_get_by_name_optional(struct udevice *dev,
+                                          const char *name, struct clk *clk)
+{
+       int ret;
+
+       ret = clk_get_by_name_optional(dev, name, clk);
+       if (ret == -ENODATA)
+               return 0;
+
+       return ret;
+}
+
  /**
   * clk_get_by_name_nodev_optional - Get/request an optinonal clock by name
   *             without a device.
--
Quoted 2 lines

2.33.0

Regards,
SImon

#11 lore raw

Re: [PATCH 5/5] clk: Add clk_get_by_name_optional

Hi Sean,

Quoted 67 lines · Sean Anderson

Hi Simon,

Quoted 55 lines · Simon Glass

Hi Sean,

Quoted 52 lines · Sean Anderson

This adds a helper function for clk_get_by_name in cases where the clock is optional. Hopefully this helps point driver writers in the right direction. Also convert some existing users.

---

  drivers/clk/clk_zynq.c  |  5 +++--
  drivers/rng/meson-rng.c |  4 ++--
  include/clk.h           | 24 ++++++++++++++++++++++++
  3 files changed, 29 insertions(+), 4 deletions(-)
drivers/clk/clk_zynq.c +3 -2
index 18915c3e04..e80500e382 100644
@@ -472,8 +472,9 @@ static int zynq_clk_probe(struct udevice *dev)
 
         for (i = 0; i < 2; i++) {
                 sprintf(name, "gem%d_emio_clk", i);
-               ret = clk_get_by_name(dev, name, &priv->gem_emio_clk[i]);
-               if (ret < 0 && ret != -ENODATA) {
+               ret = clk_get_by_name_optional(dev, name,
+                                              &priv->gem_emio_clk[i]);
+               if (ret) {
                         dev_err(dev, "failed to get %s clock\n", name);
                         return ret;
                 }
drivers/rng/meson-rng.c +2 -2
index 5a4f45ad5a..e0a1e8c7e0 100644
@@ -91,8 +91,8 @@ static int meson_rng_of_to_plat(struct udevice *dev)
                 return -ENODEV;
 
         /* Get optional "core" clock */
-       err = clk_get_by_name(dev, "core", &pdata->clk);
-       if (err && err != -ENODATA)
+       err = clk_get_by_name_optional(dev, "core", &pdata->clk);
+       if (err)
                 return err;
 
         return 0;
include/clk.h +0 -0
index 103ef16bf9..36721188d0 100644
@@ -292,6 +292,30 @@ static inline int clk_release_all(struct clk *clk, int count)
  }
  #endif
 
Quoted 4 lines

include/clk.h static inline int clk_release_all(struct clk *clk, int count) · line 296

Quoted 2 lines
include/clk.h +2 -0
+/**
+ * clk_get_by_name_optional() - Get/request a optional clock by name.

Can I suggest we rename this to ..._opt as it is shorter?

This follows the general trend of suffixing _optional. For example (and several of these are borrowed from Linux):

Quoted 8 lines

clk_get_optional
reset_control_bulk_get_optional_exclusive
gpiod_get_optional
platform_get_irq_byname_optional

and particularly, the Linux clock subsystem uses _optional and not _opt as a suffix. While some of these names can get fairly long-winded, I think we should go for consistency here.

Yes I agree.

I do wish people would consider brevity as these names are pretty hopeless for readability.

Regards,
Simon