1 From 62f026f082e4d762a47b43ea693b38f025122332 Mon Sep 17 00:00:00 2001
2 From: Rob Herring <robh@kernel.org>
3 Date: Fri, 26 Mar 2021 13:26:06 -0600
4 Subject: [PATCH] of: Fix kerneldoc output formatting
6 The indentation of the kerneldoc comments affects the output formatting.
7 Leading tabs in particular don't work, sections need to be indented
8 under the section header, and several code blocks are reformatted.
10 Cc: Frank Rowand <frowand.list@gmail.com>
11 Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
12 Signed-off-by: Rob Herring <robh@kernel.org>
13 Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
14 Link: https://lore.kernel.org/r/20210326192606.3702739-1-robh@kernel.org
16 drivers/of/base.c | 275 +++++++++++++++++++++++-----------------------
17 drivers/of/fdt.c | 9 +-
18 2 files changed, 141 insertions(+), 143 deletions(-)
20 --- a/drivers/of/base.c
21 +++ b/drivers/of/base.c
22 @@ -651,11 +651,11 @@ bool of_device_is_big_endian(const struc
23 EXPORT_SYMBOL(of_device_is_big_endian);
26 - * of_get_parent - Get a node's parent if any
27 - * @node: Node to get parent
28 + * of_get_parent - Get a node's parent if any
29 + * @node: Node to get parent
31 - * Returns a node pointer with refcount incremented, use
32 - * of_node_put() on it when done.
33 + * Return: A node pointer with refcount incremented, use
34 + * of_node_put() on it when done.
36 struct device_node *of_get_parent(const struct device_node *node)
38 @@ -673,15 +673,15 @@ struct device_node *of_get_parent(const
39 EXPORT_SYMBOL(of_get_parent);
42 - * of_get_next_parent - Iterate to a node's parent
43 - * @node: Node to get parent of
44 + * of_get_next_parent - Iterate to a node's parent
45 + * @node: Node to get parent of
47 - * This is like of_get_parent() except that it drops the
48 - * refcount on the passed node, making it suitable for iterating
49 - * through a node's parents.
50 + * This is like of_get_parent() except that it drops the
51 + * refcount on the passed node, making it suitable for iterating
52 + * through a node's parents.
54 - * Returns a node pointer with refcount incremented, use
55 - * of_node_put() on it when done.
56 + * Return: A node pointer with refcount incremented, use
57 + * of_node_put() on it when done.
59 struct device_node *of_get_next_parent(struct device_node *node)
61 @@ -719,13 +719,13 @@ static struct device_node *__of_get_next
62 child = __of_get_next_child(parent, child))
65 - * of_get_next_child - Iterate a node childs
66 - * @node: parent node
67 - * @prev: previous child of the parent node, or NULL to get first
69 - * Returns a node pointer with refcount incremented, use of_node_put() on
70 - * it when done. Returns NULL when prev is the last child. Decrements the
72 + * of_get_next_child - Iterate a node childs
73 + * @node: parent node
74 + * @prev: previous child of the parent node, or NULL to get first
76 + * Return: A node pointer with refcount incremented, use of_node_put() on
77 + * it when done. Returns NULL when prev is the last child. Decrements the
80 struct device_node *of_get_next_child(const struct device_node *node,
81 struct device_node *prev)
82 @@ -741,12 +741,12 @@ struct device_node *of_get_next_child(co
83 EXPORT_SYMBOL(of_get_next_child);
86 - * of_get_next_available_child - Find the next available child node
87 - * @node: parent node
88 - * @prev: previous child of the parent node, or NULL to get first
89 + * of_get_next_available_child - Find the next available child node
90 + * @node: parent node
91 + * @prev: previous child of the parent node, or NULL to get first
93 - * This function is like of_get_next_child(), except that it
94 - * automatically skips any disabled nodes (i.e. status = "disabled").
95 + * This function is like of_get_next_child(), except that it
96 + * automatically skips any disabled nodes (i.e. status = "disabled").
98 struct device_node *of_get_next_available_child(const struct device_node *node,
99 struct device_node *prev)
100 @@ -772,12 +772,12 @@ struct device_node *of_get_next_availabl
101 EXPORT_SYMBOL(of_get_next_available_child);
104 - * of_get_next_cpu_node - Iterate on cpu nodes
105 - * @prev: previous child of the /cpus node, or NULL to get first
106 + * of_get_next_cpu_node - Iterate on cpu nodes
107 + * @prev: previous child of the /cpus node, or NULL to get first
109 - * Returns a cpu node pointer with refcount incremented, use of_node_put()
110 - * on it when done. Returns NULL when prev is the last child. Decrements
111 - * the refcount of prev.
112 + * Return: A cpu node pointer with refcount incremented, use of_node_put()
113 + * on it when done. Returns NULL when prev is the last child. Decrements
114 + * the refcount of prev.
116 struct device_node *of_get_next_cpu_node(struct device_node *prev)
118 @@ -834,15 +834,15 @@ struct device_node *of_get_compatible_ch
119 EXPORT_SYMBOL(of_get_compatible_child);
122 - * of_get_child_by_name - Find the child node by name for a given parent
123 - * @node: parent node
124 - * @name: child name to look for.
126 - * This function looks for child node for given matching name
128 - * Returns a node pointer if found, with refcount incremented, use
129 - * of_node_put() on it when done.
130 - * Returns NULL if node is not found.
131 + * of_get_child_by_name - Find the child node by name for a given parent
132 + * @node: parent node
133 + * @name: child name to look for.
135 + * This function looks for child node for given matching name
137 + * Return: A node pointer if found, with refcount incremented, use
138 + * of_node_put() on it when done.
139 + * Returns NULL if node is not found.
141 struct device_node *of_get_child_by_name(const struct device_node *node,
143 @@ -893,22 +893,22 @@ struct device_node *__of_find_node_by_fu
147 - * of_find_node_opts_by_path - Find a node matching a full OF path
148 - * @path: Either the full path to match, or if the path does not
149 - * start with '/', the name of a property of the /aliases
150 - * node (an alias). In the case of an alias, the node
151 - * matching the alias' value will be returned.
152 - * @opts: Address of a pointer into which to store the start of
153 - * an options string appended to the end of the path with
157 - * /foo/bar Full path
159 - * foo/bar Valid alias + relative path
160 + * of_find_node_opts_by_path - Find a node matching a full OF path
161 + * @path: Either the full path to match, or if the path does not
162 + * start with '/', the name of a property of the /aliases
163 + * node (an alias). In the case of an alias, the node
164 + * matching the alias' value will be returned.
165 + * @opts: Address of a pointer into which to store the start of
166 + * an options string appended to the end of the path with
170 + * * /foo/bar Full path
171 + * * foo Valid alias
172 + * * foo/bar Valid alias + relative path
174 - * Returns a node pointer with refcount incremented, use
175 - * of_node_put() on it when done.
176 + * Return: A node pointer with refcount incremented, use
177 + * of_node_put() on it when done.
179 struct device_node *of_find_node_opts_by_path(const char *path, const char **opts)
181 @@ -958,15 +958,15 @@ struct device_node *of_find_node_opts_by
182 EXPORT_SYMBOL(of_find_node_opts_by_path);
185 - * of_find_node_by_name - Find a node by its "name" property
186 - * @from: The node to start searching from or NULL; the node
187 + * of_find_node_by_name - Find a node by its "name" property
188 + * @from: The node to start searching from or NULL; the node
189 * you pass will not be searched, only the next one
190 * will. Typically, you pass what the previous call
191 * returned. of_node_put() will be called on @from.
192 - * @name: The name string to match against
193 + * @name: The name string to match against
195 - * Returns a node pointer with refcount incremented, use
196 - * of_node_put() on it when done.
197 + * Return: A node pointer with refcount incremented, use
198 + * of_node_put() on it when done.
200 struct device_node *of_find_node_by_name(struct device_node *from,
202 @@ -985,16 +985,16 @@ struct device_node *of_find_node_by_name
203 EXPORT_SYMBOL(of_find_node_by_name);
206 - * of_find_node_by_type - Find a node by its "device_type" property
207 - * @from: The node to start searching from, or NULL to start searching
208 + * of_find_node_by_type - Find a node by its "device_type" property
209 + * @from: The node to start searching from, or NULL to start searching
210 * the entire device tree. The node you pass will not be
211 * searched, only the next one will; typically, you pass
212 * what the previous call returned. of_node_put() will be
213 * called on from for you.
214 - * @type: The type string to match against
215 + * @type: The type string to match against
217 - * Returns a node pointer with refcount incremented, use
218 - * of_node_put() on it when done.
219 + * Return: A node pointer with refcount incremented, use
220 + * of_node_put() on it when done.
222 struct device_node *of_find_node_by_type(struct device_node *from,
224 @@ -1013,18 +1013,18 @@ struct device_node *of_find_node_by_type
225 EXPORT_SYMBOL(of_find_node_by_type);
228 - * of_find_compatible_node - Find a node based on type and one of the
229 + * of_find_compatible_node - Find a node based on type and one of the
230 * tokens in its "compatible" property
231 - * @from: The node to start searching from or NULL, the node
232 - * you pass will not be searched, only the next one
233 - * will; typically, you pass what the previous call
234 - * returned. of_node_put() will be called on it
235 - * @type: The type string to match "device_type" or NULL to ignore
236 - * @compatible: The string to match to one of the tokens in the device
237 - * "compatible" list.
238 + * @from: The node to start searching from or NULL, the node
239 + * you pass will not be searched, only the next one
240 + * will; typically, you pass what the previous call
241 + * returned. of_node_put() will be called on it
242 + * @type: The type string to match "device_type" or NULL to ignore
243 + * @compatible: The string to match to one of the tokens in the device
244 + * "compatible" list.
246 - * Returns a node pointer with refcount incremented, use
247 - * of_node_put() on it when done.
248 + * Return: A node pointer with refcount incremented, use
249 + * of_node_put() on it when done.
251 struct device_node *of_find_compatible_node(struct device_node *from,
252 const char *type, const char *compatible)
253 @@ -1044,16 +1044,16 @@ struct device_node *of_find_compatible_n
254 EXPORT_SYMBOL(of_find_compatible_node);
257 - * of_find_node_with_property - Find a node which has a property with
259 - * @from: The node to start searching from or NULL, the node
260 - * you pass will not be searched, only the next one
261 - * will; typically, you pass what the previous call
262 - * returned. of_node_put() will be called on it
263 - * @prop_name: The name of the property to look for.
264 + * of_find_node_with_property - Find a node which has a property with
266 + * @from: The node to start searching from or NULL, the node
267 + * you pass will not be searched, only the next one
268 + * will; typically, you pass what the previous call
269 + * returned. of_node_put() will be called on it
270 + * @prop_name: The name of the property to look for.
272 - * Returns a node pointer with refcount incremented, use
273 - * of_node_put() on it when done.
274 + * Return: A node pointer with refcount incremented, use
275 + * of_node_put() on it when done.
277 struct device_node *of_find_node_with_property(struct device_node *from,
278 const char *prop_name)
279 @@ -1102,10 +1102,10 @@ const struct of_device_id *__of_match_no
282 * of_match_node - Tell if a device_node has a matching of_match structure
283 - * @matches: array of of device match structures to search in
284 - * @node: the of device structure to match against
285 + * @matches: array of of device match structures to search in
286 + * @node: the of device structure to match against
288 - * Low level utility function used by device matching.
289 + * Low level utility function used by device matching.
291 const struct of_device_id *of_match_node(const struct of_device_id *matches,
292 const struct device_node *node)
293 @@ -1121,17 +1121,17 @@ const struct of_device_id *of_match_node
294 EXPORT_SYMBOL(of_match_node);
297 - * of_find_matching_node_and_match - Find a node based on an of_device_id
299 - * @from: The node to start searching from or NULL, the node
300 - * you pass will not be searched, only the next one
301 - * will; typically, you pass what the previous call
302 - * returned. of_node_put() will be called on it
303 - * @matches: array of of device match structures to search in
304 - * @match: Updated to point at the matches entry which matched
305 + * of_find_matching_node_and_match - Find a node based on an of_device_id
307 + * @from: The node to start searching from or NULL, the node
308 + * you pass will not be searched, only the next one
309 + * will; typically, you pass what the previous call
310 + * returned. of_node_put() will be called on it
311 + * @matches: array of of device match structures to search in
312 + * @match: Updated to point at the matches entry which matched
314 - * Returns a node pointer with refcount incremented, use
315 - * of_node_put() on it when done.
316 + * Return: A node pointer with refcount incremented, use
317 + * of_node_put() on it when done.
319 struct device_node *of_find_matching_node_and_match(struct device_node *from,
320 const struct of_device_id *matches,
321 @@ -1465,21 +1465,21 @@ EXPORT_SYMBOL(of_parse_phandle);
322 * Caller is responsible to call of_node_put() on the returned out_args->np
328 - * phandle1: node1 {
329 + * phandle1: node1 {
334 - * phandle2: node2 {
335 + * phandle2: node2 {
342 * list = <&phandle1 1 2 &phandle2 3>;
346 - * To get a device_node of the `node2' node you may call this:
347 + * To get a device_node of the ``node2`` node you may call this:
348 * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args);
350 int of_parse_phandle_with_args(const struct device_node *np, const char *list_name,
351 @@ -1517,29 +1517,29 @@ EXPORT_SYMBOL(of_parse_phandle_with_args
352 * Caller is responsible to call of_node_put() on the returned out_args->np
357 - * phandle1: node1 {
358 - * #list-cells = <2>;
361 - * phandle2: node2 {
362 - * #list-cells = <1>;
366 - * phandle3: node3 {
367 - * #list-cells = <1>;
368 - * list-map = <0 &phandle2 3>,
370 - * <2 &phandle1 5 1>;
371 - * list-map-mask = <0x3>;
375 - * list = <&phandle1 1 2 &phandle3 0>;
377 + * phandle1: node1 {
378 + * #list-cells = <2>;
381 + * phandle2: node2 {
382 + * #list-cells = <1>;
385 + * phandle3: node3 {
386 + * #list-cells = <1>;
387 + * list-map = <0 &phandle2 3>,
389 + * <2 &phandle1 5 1>;
390 + * list-map-mask = <0x3>;
394 + * list = <&phandle1 1 2 &phandle3 0>;
397 - * To get a device_node of the `node2' node you may call this:
398 + * To get a device_node of the ``node2`` node you may call this:
399 * of_parse_phandle_with_args(node4, "list", "list", 1, &args);
401 int of_parse_phandle_with_args_map(const struct device_node *np,
402 @@ -1699,19 +1699,19 @@ EXPORT_SYMBOL(of_parse_phandle_with_args
403 * Caller is responsible to call of_node_put() on the returned out_args->np
409 - * phandle1: node1 {
411 + * phandle1: node1 {
414 - * phandle2: node2 {
416 + * phandle2: node2 {
420 - * list = <&phandle1 0 2 &phandle2 2 3>;
423 + * list = <&phandle1 0 2 &phandle2 2 3>;
426 - * To get a device_node of the `node2' node you may call this:
427 + * To get a device_node of the ``node2`` node you may call this:
428 * of_parse_phandle_with_fixed_args(node3, "list", 2, 1, &args);
430 int of_parse_phandle_with_fixed_args(const struct device_node *np,
431 @@ -1957,13 +1957,12 @@ static void of_alias_add(struct alias_pr
434 * of_alias_scan - Scan all properties of the 'aliases' node
435 + * @dt_alloc: An allocator that provides a virtual address to memory
436 + * for storing the resulting tree
438 * The function scans all the properties of the 'aliases' node and populates
439 * the global lookup table with the properties. It returns the
440 * number of alias properties found, or an error code in case of failure.
442 - * @dt_alloc: An allocator that provides a virtual address to memory
443 - * for storing the resulting tree
445 void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align))
447 @@ -2158,12 +2157,12 @@ bool of_console_check(struct device_node
448 EXPORT_SYMBOL_GPL(of_console_check);
451 - * of_find_next_cache_node - Find a node's subsidiary cache
452 - * @np: node of type "cpu" or "cache"
453 + * of_find_next_cache_node - Find a node's subsidiary cache
454 + * @np: node of type "cpu" or "cache"
456 - * Returns a node pointer with refcount incremented, use
457 - * of_node_put() on it when done. Caller should hold a reference
459 + * Return: A node pointer with refcount incremented, use
460 + * of_node_put() on it when done. Caller should hold a reference
463 struct device_node *of_find_next_cache_node(const struct device_node *np)
465 --- a/drivers/of/fdt.c
466 +++ b/drivers/of/fdt.c
467 @@ -349,11 +349,6 @@ static int unflatten_dt_nodes(const void
470 * __unflatten_device_tree - create tree of device_nodes from flat blob
472 - * unflattens a device-tree, creating the
473 - * tree of struct device_node. It also fills the "name" and "type"
474 - * pointers of the nodes so the normal device-tree walking functions
476 * @blob: The blob to expand
477 * @dad: Parent device node
478 * @mynodes: The device_node tree created by the call
479 @@ -361,6 +356,10 @@ static int unflatten_dt_nodes(const void
480 * for the resulting tree
481 * @detached: if true set OF_DETACHED on @mynodes
483 + * unflattens a device-tree, creating the tree of struct device_node. It also
484 + * fills the "name" and "type" pointers of the nodes so the normal device-tree
485 + * walking functions can be used.
487 * Returns NULL on failure or the memory chunk containing the unflattened
488 * device tree on success.