Skip to contentSkip to conversation

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

PATCH Applied Sean Anderson 2 participants 12 messages Dec 22, 2021 – Jan 15, 2022

Subsystems (5)

v2 of 3 Applied Latest is v3 →

lore
Share & tools
lore
#0 lore raw

v2 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.

Changes in v2:
- Clean up the argument list and descriptions
- Rebased onto u-boot/master

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 v2 1/5 clk: Rename clk_get_optional_nodev

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

---

(no changes since v1)

 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 f2d2642754..0ee9a38b15 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 df5255e510..57c6707a55 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
Reviewed-by Reviewed-by on v2 1/5
#2 lore raw

Re: [PATCH v2 1/5] clk: Rename clk_get_optional_nodev

Quoted 2 lines · Sean Anderson

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

In case you resend for another reason

s/This normalizes/Normalize/

Quoted 10 lines

---

(no changes since v1)

 drivers/clk/clk-uclass.c   | 3 ++-
 drivers/phy/phy-mtk-tphy.c | 8 ++++----
 include/clk.h              | 7 ++++---
 3 files changed, 10 insertions(+), 8 deletions(-)
#3 lore raw

PATCH v2 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.

---

(no changes since v1)

 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 0ee9a38b15..5e9749a75b 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
Reviewed-by on v2 2/5
#4 lore raw

Re: [PATCH v2 2/5] clk: Inline clk_get_*_optional

Hi Sean,

Quoted 6 lines · 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.

Quoted 8 lines

---

(no changes since v1)

 drivers/clk/clk-uclass.c | 22 ---------------
 include/clk.h            | 58 ++++++++++++++++++++++++----------------
 2 files changed, 35 insertions(+), 45 deletions(-)

I wonder if LTO removes this anyway?

#5 lore raw

PATCH v2 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.

---

(no changes since v1)

 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

512 lines not on this page · raw message

Signature · 1 line
2.33.0
Reviewed-by on v2 3/5
#6 lore raw

Re: [PATCH v2 3/5] clk: Add client API to HTML docs

Quoted 9 lines · 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.

---

Quoted 7 lines

(no changes since v1)

 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
#7 lore raw

PATCH v2 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

---

Changes in v2:
- Clean up the argument list and descriptions

 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
Reviewed-by on v2 4/5
#8 lore raw

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

Quoted 11 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

Quoted 8 lines

---

Changes in v2:
- Clean up the argument list and descriptions

 doc/api/clk.rst      |   6 ++
 include/clk-uclass.h | 187 +++++++++++++++++++++++++------------------
 2 files changed, 115 insertions(+), 78 deletions(-)

Oh yuk...

#9 lore raw

PATCH v2 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.

---

(no changes since v1)

 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 33f448eb89..9308b57167 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 v2 5/5
#10 lore raw

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

Quoted 7 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.

Quoted 8 lines

---

(no changes since v1)

 drivers/clk/clk_zynq.c  |  5 +++--
 drivers/rng/meson-rng.c |  4 ++--
 include/clk.h           | 24 ++++++++++++++++++++++++
 3 files changed, 29 insertions(+), 4 deletions(-)
author Applied
#11 lore raw
In reply to Sean Anderson
Quoted 8 lines · Sean Anderson

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.

Changes in v2:
- Clean up the argument list and descriptions
- Rebased onto u-boot/master

[...]

Applied, thanks!

[1/5] clk: Rename clk_get_optional_nodev

      commit: 80a0b4131b718f5685343a043d18949adc493df6
[2/5] clk: Inline clk_get_*_optional
      commit: 40389606194f3d603d034f756169494ad76f84ae
[3/5] clk: Add client API to HTML docs
      commit: 0c0b970cf39cf9e28d838c72e516dfbd7a5b5cb7
[4/5] clk: Add driver API to HTML docs
      commit: decee5e428ae8ab634eeef00f4e763febf1bcbda

Best regards,

Signature · 1 line
Sean Anderson <[email protected]>