Skip to contentSkip to conversation

clk: Document of_parse_clkspec() some more

PATCH Applied Stephen Boyd 2 participants 3 messages Aug 26, 2019 – Sep 5, 2019 Common clk

lore
Share & tools
lore

Stephen Boyd

author maintainer
#0 lore raw

PATCH v2 1/1 clk: Document of_parse_clkspec() some more

The return value of of_parse_clkspec() is peculiar. If the function is called with a NULL argument for 'name' it will return -ENOENT, but if it's called with a non-NULL argument for 'name' it will return -EINVAL. This peculiarity is documented by commit 5c56dfe63b6e ("clk: Add comment about __of_clk_get_by_name() error values").

Let's further document this function so that it's clear what the return value is and how to use the arguments to parse clk specifiers.

---
 drivers/clk/clk.c | 43 +++++++++++++++++++++++++++++++++++++------
 1 file changed, 37 insertions(+), 6 deletions(-)
drivers/clk/clk.c +37 -6
index c0990703ce54..5c6585eb35d4 100644
@@ -4316,12 +4316,43 @@ void devm_of_clk_del_provider(struct device *dev)
 }
 EXPORT_SYMBOL(devm_of_clk_del_provider);
 
-/*
- * Beware the return values when np is valid, but no clock provider is found.
- * If name == NULL, the function returns -ENOENT.
- * If name != NULL, the function returns -EINVAL. This is because
- * of_parse_phandle_with_args() is called even if of_property_match_string()
- * returns an error.
+/**
+ * of_parse_clkspec() - Parse a DT clock specifier for a given device node
+ * @np: device node to parse clock specifier from
+ * @index: index of phandle to parse clock out of. If index < 0, @name is used
+ * @name: clock name to find and parse. If name is NULL, the index is used
+ * @out_args: Result of parsing the clock specifier
+ *
+ * Parses a device node's "clocks" and "clock-names" properties to find the
+ * phandle and cells for the index or name that is desired. The resulting clock
+ * specifier is placed into @out_args, or an errno is returned when there's a
+ * parsing error. The @index argument is ignored if @name is non-NULL.
+ *
+ * Example:
+ *
+ * phandle1: clock-controller@1 {
+ *	#clock-cells = <2>;
+ * }
+ *
+ * phandle2: clock-controller@2 {
+ *	#clock-cells = <1>;
+ * }
+ *
+ * clock-consumer@3 {
+ *	clocks = <&phandle1 1 2 &phandle2 3>;
+ *	clock-names = "name1", "name2";
+ * }
+ *
+ * To get a device_node for `clock-controller@2' node you may call this
+ * function a few different ways:
+ *
+ *   of_parse_clkspec(clock-consumer@3, -1, "name2", &args);
+ *   of_parse_clkspec(clock-consumer@3, 1, NULL, &args);
+ *   of_parse_clkspec(clock-consumer@3, 1, "name2", &args);
+ *
+ * Return: 0 upon successfully parsing the clock specifier. Otherwise, -ENOENT
+ * if @name is NULL or -EINVAL if @name is non-NULL and it can't be found in
+ * the "clock-names" property of @np.
  */
 static int of_parse_clkspec(const struct device_node *np, int index,
 			    const char *name, struct of_phandle_args *out_args)
Signature · 1 line
Sent by a computer through tubes
Reviewed-by on v2 1/1
#1 lore raw

Hi Stephen,

Quoted 11 lines · On 26 August 2019 22:21 Stephen Boyd wrote:

The return value of of_parse_clkspec() is peculiar. If the function is called with a NULL argument for 'name' it will return -ENOENT, but if it's called with a non-NULL argument for 'name' it will return -EINVAL. This peculiarity is documented by commit 5c56dfe63b6e ("clk: Add comment about __of_clk_get_by_name() error values").

Let's further document this function so that it's clear what the return value is and how to use the arguments to parse clk specifiers.

Thanks, this is much better than my comment!

Quoted 67 lines
---
 drivers/clk/clk.c | 43 +++++++++++++++++++++++++++++++++++++------
 1 file changed, 37 insertions(+), 6 deletions(-)
drivers/clk/clk.c +4 -6
index c0990703ce54..5c6585eb35d4 100644
@@ -4316,12 +4316,43 @@ void devm_of_clk_del_provider(struct device
 *dev)
 }
 EXPORT_SYMBOL(devm_of_clk_del_provider);
 
-/*
- * Beware the return values when np is valid, but no clock provider is found.
- * If name == NULL, the function returns -ENOENT.
- * If name != NULL, the function returns -EINVAL. This is because
- * of_parse_phandle_with_args() is called even if
 of_property_match_string()
- * returns an error.
+/**
+ * of_parse_clkspec() - Parse a DT clock specifier for a given device node
+ * @np: device node to parse clock specifier from
+ * @index: index of phandle to parse clock out of. If index < 0, @name is

used
+ * @name: clock name to find and parse. If name is NULL, the index is used
+ * @out_args: Result of parsing the clock specifier
+ *
+ * Parses a device node's "clocks" and "clock-names" properties to find the
+ * phandle and cells for the index or name that is desired. The resulting clock
+ * specifier is placed into @out_args, or an errno is returned when there's a
+ * parsing error. The @index argument is ignored if @name is non-NULL.
+ *
+ * Example:
+ *
+ * phandle1: clock-controller@1 {
+ * #clock-cells = <2>;
+ * }
+ *
+ * phandle2: clock-controller@2 {
+ * #clock-cells = <1>;
+ * }
+ *
+ * clock-consumer@3 {
+ * clocks = <&phandle1 1 2 &phandle2 3>;
+ * clock-names = "name1", "name2";
+ * }
+ *
+ * To get a device_node for `clock-controller@2' node you may call this
+ * function a few different ways:
+ *

+ *   of_parse_clkspec(clock-consumer@3, -1, "name2", &args);
+ *   of_parse_clkspec(clock-consumer@3, 1, NULL, &args);
+ *   of_parse_clkspec(clock-consumer@3, 1, "name2", &args);

+ *
+ * Return: 0 upon successfully parsing the clock specifier. Otherwise, - ENOENT
+ * if @name is NULL or -EINVAL if @name is non-NULL and it can't be found in
+ * the "clock-names" property of @np.
*/
static int of_parse_clkspec(const struct device_node *np, int index,
const char *name, struct of_phandle_args
*out_args)
--
Sent by a computer through tubes

author maintainer Applied
#2 lore raw
In reply to Stephen Boyd

Quoting Stephen Boyd (2019-08-26 14:20:42)

Quoted 6 lines

The return value of of_parse_clkspec() is peculiar. If the function is called with a NULL argument for 'name' it will return -ENOENT, but if it's called with a non-NULL argument for 'name' it will return -EINVAL. This peculiarity is documented by commit 5c56dfe63b6e ("clk: Add comment about __of_clk_get_by_name() error values").

Quoted 6 lines

Let's further document this function so that it's clear what the return value is and how to use the arguments to parse clk specifiers.

---

Applied to clk-next