Message ID | 20190826212042.48642-1-sboyd@kernel.org (mailing list archive) |
---|---|
State | Accepted, archived |
Headers | show |
Series | [v2] clk: Document of_parse_clkspec() some more | expand |
Hi Stephen, 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. > > Cc: Phil Edworthy <phil.edworthy@renesas.com> > Signed-off-by: Stephen Boyd <sboyd@kernel.org> Thanks, this is much better than my comment! Reviewed-by: Phil Edworthy <phil.edworthy@renesas.com> > --- > drivers/clk/clk.c | 43 +++++++++++++++++++++++++++++++++++++------ > 1 file changed, 37 insertions(+), 6 deletions(-) > > diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c > index c0990703ce54..5c6585eb35d4 100644 > --- a/drivers/clk/clk.c > +++ b/drivers/clk/clk.c > @@ -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
Quoting Stephen Boyd (2019-08-26 14:20:42) > 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. > > Cc: Phil Edworthy <phil.edworthy@renesas.com> > Signed-off-by: Stephen Boyd <sboyd@kernel.org> > --- Applied to clk-next
diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c index c0990703ce54..5c6585eb35d4 100644 --- a/drivers/clk/clk.c +++ b/drivers/clk/clk.c @@ -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)
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. Cc: Phil Edworthy <phil.edworthy@renesas.com> Signed-off-by: Stephen Boyd <sboyd@kernel.org> --- drivers/clk/clk.c | 43 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-)