clk: Clean up optional helpers, and add API docs to HTML
Subsystems (5)
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
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
@@ -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
PATCH 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.
---
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
PATCH 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.
---
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
511 lines not on this page · raw message
Signature · 1 line
2.33.0
Re: [PATCH 3/5] clk: Add client API to HTML docs
Quoted 5 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]>
make htmldocs shows no problems
PATCH 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
---
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 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
Signed-off-by Sean Anderson<[email protected]>
make htmldocs shows no problems
PATCH 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.
---
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 5/5] clk: Add clk_get_by_name_optional
Quoted 69 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]>---
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 +17
-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; +
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:
Re: [PATCH 5/5] clk: Add clk_get_by_name_optional
In reply to Sean AndersonHi Sean,
Quoted 49 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]>---
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 +0
-0
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
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_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]>---
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 +0
-0@@ -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
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_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]>---
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 +0
-0@@ -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_optionaland particularly, the Linux clock subsystem uses
_optionaland not_optas 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