clk: Document of_parse_clkspec() some more
Stephen Boyd
maintainerPATCH 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
@@ -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
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 commit5c56dfe63b6e("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.
Cc Phil Edworthy <[email protected]>Signed-off-by Stephen Boyd <[email protected]>
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@@ -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 adevice_nodefor `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-EINVALif @name is non-NULL and it can't be found in
+ * the "clock-names" property of @np.
*/
static int of_parse_clkspec(const structdevice_node*np, int index,
const char *name, structof_phandle_args*out_args)
--
Sent by a computer through tubes
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 commit5c56dfe63b6e("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.
Cc Phil Edworthy <[email protected]>Signed-off-by Stephen Boyd <[email protected]>---
Applied to clk-next