clk: Document of_parse_clkspec() some more

}

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)