Em Fri, 26 Mar 2021 13:26:06 -0600 Rob Herring <r...@kernel.org> escreveu:
> The indentation of the kerneldoc comments affects the output formatting. > Leading tabs in particular don't work, sections need to be indented > under the section header, and several code blocks are reformatted. > > Cc: Frank Rowand <frowand.l...@gmail.com> > Cc: Mauro Carvalho Chehab <mche...@kernel.org> Reviewed-by: Mauro Carvalho Chehab <mchehab+hua...@kernel.org> > Signed-off-by: Rob Herring <r...@kernel.org> > --- > v2: > - Updated the example code blocks to use 'Example::' which depends (for > nice output) on Mauro's fix. > > The rest of the series is here[1]. > > [1] https://lore.kernel.org/r/20210325164713.1296407-1-r...@kernel.org/ > > drivers/of/base.c | 275 +++++++++++++++++++++++----------------------- > drivers/of/fdt.c | 9 +- > 2 files changed, 141 insertions(+), 143 deletions(-) > > diff --git a/drivers/of/base.c b/drivers/of/base.c > index 457d1ec27300..a64c093d30ef 100644 > --- a/drivers/of/base.c > +++ b/drivers/of/base.c > @@ -651,11 +651,11 @@ bool of_device_is_big_endian(const struct device_node > *device) > EXPORT_SYMBOL(of_device_is_big_endian); > > /** > - * of_get_parent - Get a node's parent if any > - * @node: Node to get parent > + * of_get_parent - Get a node's parent if any > + * @node: Node to get parent > * > - * Returns a node pointer with refcount incremented, use > - * of_node_put() on it when done. > + * Return: A node pointer with refcount incremented, use > + * of_node_put() on it when done. > */ > struct device_node *of_get_parent(const struct device_node *node) > { > @@ -673,15 +673,15 @@ struct device_node *of_get_parent(const struct > device_node *node) > EXPORT_SYMBOL(of_get_parent); > > /** > - * of_get_next_parent - Iterate to a node's parent > - * @node: Node to get parent of > + * of_get_next_parent - Iterate to a node's parent > + * @node: Node to get parent of > * > - * This is like of_get_parent() except that it drops the > - * refcount on the passed node, making it suitable for iterating > - * through a node's parents. > + * This is like of_get_parent() except that it drops the > + * refcount on the passed node, making it suitable for iterating > + * through a node's parents. > * > - * Returns a node pointer with refcount incremented, use > - * of_node_put() on it when done. > + * Return: A node pointer with refcount incremented, use > + * of_node_put() on it when done. > */ > struct device_node *of_get_next_parent(struct device_node *node) > { > @@ -719,13 +719,13 @@ static struct device_node *__of_get_next_child(const > struct device_node *node, > child = __of_get_next_child(parent, child)) > > /** > - * of_get_next_child - Iterate a node childs > - * @node: parent node > - * @prev: previous child of the parent node, or NULL to get first > + * of_get_next_child - Iterate a node childs > + * @node: parent node > + * @prev: previous child of the parent node, or NULL to get first > * > - * Returns a node pointer with refcount incremented, use of_node_put() on > - * it when done. Returns NULL when prev is the last child. Decrements the > - * refcount of prev. > + * Return: A node pointer with refcount incremented, use of_node_put() on > + * it when done. Returns NULL when prev is the last child. Decrements the > + * refcount of prev. > */ > struct device_node *of_get_next_child(const struct device_node *node, > struct device_node *prev) > @@ -741,12 +741,12 @@ struct device_node *of_get_next_child(const struct > device_node *node, > EXPORT_SYMBOL(of_get_next_child); > > /** > - * of_get_next_available_child - Find the next available child node > - * @node: parent node > - * @prev: previous child of the parent node, or NULL to get first > + * of_get_next_available_child - Find the next available child node > + * @node: parent node > + * @prev: previous child of the parent node, or NULL to get first > * > - * This function is like of_get_next_child(), except that it > - * automatically skips any disabled nodes (i.e. status = "disabled"). > + * This function is like of_get_next_child(), except that it > + * automatically skips any disabled nodes (i.e. status = "disabled"). > */ > struct device_node *of_get_next_available_child(const struct device_node > *node, > struct device_node *prev) > @@ -772,12 +772,12 @@ struct device_node *of_get_next_available_child(const > struct device_node *node, > EXPORT_SYMBOL(of_get_next_available_child); > > /** > - * of_get_next_cpu_node - Iterate on cpu nodes > - * @prev: previous child of the /cpus node, or NULL to get first > + * of_get_next_cpu_node - Iterate on cpu nodes > + * @prev: previous child of the /cpus node, or NULL to get first > * > - * Returns a cpu node pointer with refcount incremented, use of_node_put() > - * on it when done. Returns NULL when prev is the last child. Decrements > - * the refcount of prev. > + * Return: A cpu node pointer with refcount incremented, use of_node_put() > + * on it when done. Returns NULL when prev is the last child. Decrements > + * the refcount of prev. > */ > struct device_node *of_get_next_cpu_node(struct device_node *prev) > { > @@ -834,15 +834,15 @@ struct device_node *of_get_compatible_child(const > struct device_node *parent, > EXPORT_SYMBOL(of_get_compatible_child); > > /** > - * of_get_child_by_name - Find the child node by name for a given parent > - * @node: parent node > - * @name: child name to look for. > + * of_get_child_by_name - Find the child node by name for a given parent > + * @node: parent node > + * @name: child name to look for. > * > - * This function looks for child node for given matching name > + * This function looks for child node for given matching name > * > - * Returns a node pointer if found, with refcount incremented, use > - * of_node_put() on it when done. > - * Returns NULL if node is not found. > + * Return: A node pointer if found, with refcount incremented, use > + * of_node_put() on it when done. > + * Returns NULL if node is not found. > */ > struct device_node *of_get_child_by_name(const struct device_node *node, > const char *name) > @@ -893,22 +893,22 @@ struct device_node *__of_find_node_by_full_path(struct > device_node *node, > } > > /** > - * of_find_node_opts_by_path - Find a node matching a full OF path > - * @path: Either the full path to match, or if the path does not > - * start with '/', the name of a property of the /aliases > - * node (an alias). In the case of an alias, the node > - * matching the alias' value will be returned. > - * @opts: Address of a pointer into which to store the start of > - * an options string appended to the end of the path with > - * a ':' separator. > - * > - * Valid paths: > - * /foo/bar Full path > - * foo Valid alias > - * foo/bar Valid alias + relative path > - * > - * Returns a node pointer with refcount incremented, use > - * of_node_put() on it when done. > + * of_find_node_opts_by_path - Find a node matching a full OF path > + * @path: Either the full path to match, or if the path does not > + * start with '/', the name of a property of the /aliases > + * node (an alias). In the case of an alias, the node > + * matching the alias' value will be returned. > + * @opts: Address of a pointer into which to store the start of > + * an options string appended to the end of the path with > + * a ':' separator. > + * > + * Valid paths: > + * * /foo/bar Full path > + * * foo Valid alias > + * * foo/bar Valid alias + relative path > + * > + * Return: A node pointer with refcount incremented, use > + * of_node_put() on it when done. > */ > struct device_node *of_find_node_opts_by_path(const char *path, const char > **opts) > { > @@ -958,15 +958,15 @@ struct device_node *of_find_node_opts_by_path(const > char *path, const char **opt > EXPORT_SYMBOL(of_find_node_opts_by_path); > > /** > - * of_find_node_by_name - Find a node by its "name" property > - * @from: The node to start searching from or NULL; the node > + * of_find_node_by_name - Find a node by its "name" property > + * @from: The node to start searching from or NULL; the node > * you pass will not be searched, only the next one > * will. Typically, you pass what the previous call > * returned. of_node_put() will be called on @from. > - * @name: The name string to match against > + * @name: The name string to match against > * > - * Returns a node pointer with refcount incremented, use > - * of_node_put() on it when done. > + * Return: A node pointer with refcount incremented, use > + * of_node_put() on it when done. > */ > struct device_node *of_find_node_by_name(struct device_node *from, > const char *name) > @@ -985,16 +985,16 @@ struct device_node *of_find_node_by_name(struct > device_node *from, > EXPORT_SYMBOL(of_find_node_by_name); > > /** > - * of_find_node_by_type - Find a node by its "device_type" property > - * @from: The node to start searching from, or NULL to start searching > + * of_find_node_by_type - Find a node by its "device_type" property > + * @from: The node to start searching from, or NULL to start searching > * the entire device tree. The node you pass will not be > * searched, only the next one will; typically, you pass > * what the previous call returned. of_node_put() will be > * called on from for you. > - * @type: The type string to match against > + * @type: The type string to match against > * > - * Returns a node pointer with refcount incremented, use > - * of_node_put() on it when done. > + * Return: A node pointer with refcount incremented, use > + * of_node_put() on it when done. > */ > struct device_node *of_find_node_by_type(struct device_node *from, > const char *type) > @@ -1013,18 +1013,18 @@ struct device_node *of_find_node_by_type(struct > device_node *from, > EXPORT_SYMBOL(of_find_node_by_type); > > /** > - * of_find_compatible_node - Find a node based on type and one of the > + * of_find_compatible_node - Find a node based on type and one of the > * tokens in its "compatible" property > - * @from: The node to start searching from or NULL, the node > - * you pass will not be searched, only the next one > - * will; typically, you pass what the previous call > - * returned. of_node_put() will be called on it > - * @type: The type string to match "device_type" or NULL to ignore > - * @compatible: The string to match to one of the tokens in the device > - * "compatible" list. > - * > - * Returns a node pointer with refcount incremented, use > - * of_node_put() on it when done. > + * @from: The node to start searching from or NULL, the node > + * you pass will not be searched, only the next one > + * will; typically, you pass what the previous call > + * returned. of_node_put() will be called on it > + * @type: The type string to match "device_type" or NULL to ignore > + * @compatible: The string to match to one of the tokens in the device > + * "compatible" list. > + * > + * Return: A node pointer with refcount incremented, use > + * of_node_put() on it when done. > */ > struct device_node *of_find_compatible_node(struct device_node *from, > const char *type, const char *compatible) > @@ -1044,16 +1044,16 @@ struct device_node *of_find_compatible_node(struct > device_node *from, > EXPORT_SYMBOL(of_find_compatible_node); > > /** > - * of_find_node_with_property - Find a node which has a property with > - * the given name. > - * @from: The node to start searching from or NULL, the node > - * you pass will not be searched, only the next one > - * will; typically, you pass what the previous call > - * returned. of_node_put() will be called on it > - * @prop_name: The name of the property to look for. > - * > - * Returns a node pointer with refcount incremented, use > - * of_node_put() on it when done. > + * of_find_node_with_property - Find a node which has a property with > + * the given name. > + * @from: The node to start searching from or NULL, the node > + * you pass will not be searched, only the next one > + * will; typically, you pass what the previous call > + * returned. of_node_put() will be called on it > + * @prop_name: The name of the property to look for. > + * > + * Return: A node pointer with refcount incremented, use > + * of_node_put() on it when done. > */ > struct device_node *of_find_node_with_property(struct device_node *from, > const char *prop_name) > @@ -1102,10 +1102,10 @@ const struct of_device_id *__of_match_node(const > struct of_device_id *matches, > > /** > * of_match_node - Tell if a device_node has a matching of_match structure > - * @matches: array of of device match structures to search in > - * @node: the of device structure to match against > + * @matches: array of of device match structures to search in > + * @node: the of device structure to match against > * > - * Low level utility function used by device matching. > + * Low level utility function used by device matching. > */ > const struct of_device_id *of_match_node(const struct of_device_id *matches, > const struct device_node *node) > @@ -1121,17 +1121,17 @@ const struct of_device_id *of_match_node(const struct > of_device_id *matches, > EXPORT_SYMBOL(of_match_node); > > /** > - * of_find_matching_node_and_match - Find a node based on an of_device_id > - * match table. > - * @from: The node to start searching from or NULL, the node > - * you pass will not be searched, only the next one > - * will; typically, you pass what the previous call > - * returned. of_node_put() will be called on it > - * @matches: array of of device match structures to search in > - * @match: Updated to point at the matches entry which matched > - * > - * Returns a node pointer with refcount incremented, use > - * of_node_put() on it when done. > + * of_find_matching_node_and_match - Find a node based on an of_device_id > + * match table. > + * @from: The node to start searching from or NULL, the node > + * you pass will not be searched, only the next one > + * will; typically, you pass what the previous call > + * returned. of_node_put() will be called on it > + * @matches: array of of device match structures to search in > + * @match: Updated to point at the matches entry which matched > + * > + * Return: A node pointer with refcount incremented, use > + * of_node_put() on it when done. > */ > struct device_node *of_find_matching_node_and_match(struct device_node *from, > const struct of_device_id *matches, > @@ -1460,21 +1460,21 @@ EXPORT_SYMBOL(of_parse_phandle); > * Caller is responsible to call of_node_put() on the returned out_args->np > * pointer. > * > - * Example: > + * Example:: > * > - * phandle1: node1 { > + * phandle1: node1 { > * #list-cells = <2>; > - * } > + * }; > * > - * phandle2: node2 { > + * phandle2: node2 { > * #list-cells = <1>; > - * } > + * }; > * > - * node3 { > + * node3 { > * list = <&phandle1 1 2 &phandle2 3>; > - * } > + * }; > * > - * To get a device_node of the `node2' node you may call this: > + * To get a device_node of the ``node2`` node you may call this: > * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args); > */ > int of_parse_phandle_with_args(const struct device_node *np, const char > *list_name, > @@ -1512,29 +1512,29 @@ EXPORT_SYMBOL(of_parse_phandle_with_args); > * Caller is responsible to call of_node_put() on the returned out_args->np > * pointer. > * > - * Example: > + * Example:: > * > - * phandle1: node1 { > - * #list-cells = <2>; > - * } > + * phandle1: node1 { > + * #list-cells = <2>; > + * }; > * > - * phandle2: node2 { > - * #list-cells = <1>; > - * } > + * phandle2: node2 { > + * #list-cells = <1>; > + * }; > * > - * phandle3: node3 { > - * #list-cells = <1>; > - * list-map = <0 &phandle2 3>, > - * <1 &phandle2 2>, > - * <2 &phandle1 5 1>; > - * list-map-mask = <0x3>; > - * }; > + * phandle3: node3 { > + * #list-cells = <1>; > + * list-map = <0 &phandle2 3>, > + * <1 &phandle2 2>, > + * <2 &phandle1 5 1>; > + * list-map-mask = <0x3>; > + * }; > * > - * node4 { > - * list = <&phandle1 1 2 &phandle3 0>; > - * } > + * node4 { > + * list = <&phandle1 1 2 &phandle3 0>; > + * }; > * > - * To get a device_node of the `node2' node you may call this: > + * To get a device_node of the ``node2`` node you may call this: > * of_parse_phandle_with_args(node4, "list", "list", 1, &args); > */ > int of_parse_phandle_with_args_map(const struct device_node *np, > @@ -1694,19 +1694,19 @@ EXPORT_SYMBOL(of_parse_phandle_with_args_map); > * Caller is responsible to call of_node_put() on the returned out_args->np > * pointer. > * > - * Example: > + * Example:: > * > - * phandle1: node1 { > - * } > + * phandle1: node1 { > + * }; > * > - * phandle2: node2 { > - * } > + * phandle2: node2 { > + * }; > * > - * node3 { > - * list = <&phandle1 0 2 &phandle2 2 3>; > - * } > + * node3 { > + * list = <&phandle1 0 2 &phandle2 2 3>; > + * }; > * > - * To get a device_node of the `node2' node you may call this: > + * To get a device_node of the ``node2`` node you may call this: > * of_parse_phandle_with_fixed_args(node3, "list", 2, 1, &args); > */ > int of_parse_phandle_with_fixed_args(const struct device_node *np, > @@ -1952,13 +1952,12 @@ static void of_alias_add(struct alias_prop *ap, > struct device_node *np, > > /** > * of_alias_scan - Scan all properties of the 'aliases' node > + * @dt_alloc: An allocator that provides a virtual address to memory > + * for storing the resulting tree > * > * The function scans all the properties of the 'aliases' node and populates > * the global lookup table with the properties. It returns the > * number of alias properties found, or an error code in case of failure. > - * > - * @dt_alloc: An allocator that provides a virtual address to memory > - * for storing the resulting tree > */ > void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align)) > { > @@ -2153,12 +2152,12 @@ bool of_console_check(struct device_node *dn, char > *name, int index) > EXPORT_SYMBOL_GPL(of_console_check); > > /** > - * of_find_next_cache_node - Find a node's subsidiary cache > - * @np: node of type "cpu" or "cache" > + * of_find_next_cache_node - Find a node's subsidiary cache > + * @np: node of type "cpu" or "cache" > * > - * Returns a node pointer with refcount incremented, use > - * of_node_put() on it when done. Caller should hold a reference > - * to np. > + * Return: A node pointer with refcount incremented, use > + * of_node_put() on it when done. Caller should hold a reference > + * to np. > */ > struct device_node *of_find_next_cache_node(const struct device_node *np) > { > diff --git a/drivers/of/fdt.c b/drivers/of/fdt.c > index 4d6d195e089a..ba53da9c3895 100644 > --- a/drivers/of/fdt.c > +++ b/drivers/of/fdt.c > @@ -349,11 +349,6 @@ static int unflatten_dt_nodes(const void *blob, > > /** > * __unflatten_device_tree - create tree of device_nodes from flat blob > - * > - * unflattens a device-tree, creating the > - * tree of struct device_node. It also fills the "name" and "type" > - * pointers of the nodes so the normal device-tree walking functions > - * can be used. > * @blob: The blob to expand > * @dad: Parent device node > * @mynodes: The device_node tree created by the call > @@ -361,6 +356,10 @@ static int unflatten_dt_nodes(const void *blob, > * for the resulting tree > * @detached: if true set OF_DETACHED on @mynodes > * > + * unflattens a device-tree, creating the tree of struct device_node. It also > + * fills the "name" and "type" pointers of the nodes so the normal > device-tree > + * walking functions can be used. > + * > * Returns NULL on failure or the memory chunk containing the unflattened > * device tree on success. > */ Thanks, Mauro
