clk: Clean up optional helpers, and add API docs to HTML
Subsystems (5)
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
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
@@ -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
@@ -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
@@ -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
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
Signed-off-by Sean Anderson <[email protected]>---
(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(-)
PATCH v2 2/5 clk: Inline clk_get_*_optional
In reply to Sean AndersonThe 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
@@ -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
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
Signed-off-by Sean Anderson <[email protected]>---
(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?
PATCH v2 3/5 clk: Add client API to HTML docs
In reply to Sean AndersonThis 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
@@ -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
@@ -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
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.Signed-off-by Sean Anderson <[email protected]>Tested-by Heinrich Schuchardt <[email protected]>---
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
PATCH v2 4/5 clk: Add driver API to HTML docs
In reply to Sean AndersonThis 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
@@ -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
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
Signed-off-by Sean Anderson <[email protected]>Tested-by Heinrich Schuchardt <[email protected]>
Quoted 8 lines
---
Changes in v2:
- Clean up the argument list and descriptionsdoc/api/clk.rst | 6 ++ include/clk-uclass.h | 187 +++++++++++++++++++++++++------------------ 2 files changed, 115 insertions(+), 78 deletions(-)
Oh yuk...
PATCH v2 5/5 clk: Add clk_get_by_name_optional
In reply to Sean AndersonThis 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
@@ -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
@@ -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
@@ -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
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_namein cases where the clock is optional. Hopefully this helps point driver writers in the right direction. Also convert some existing users.Signed-off-by Sean Anderson <[email protected]>Reviewed-by Neil Armstrong <[email protected]>
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(-)
Sean Anderson
AppliedQuoted 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: decee5e428ae8ab634eeef00f4e763febf1bcbdaBest regards,
Signature · 1 line
Sean Anderson <[email protected]>