target/linux/generic/backport-5.10/732-v5.13-0005-of-Fix-kerneldoc-output-formatting.patch

   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
   5
   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.
   9
  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
  15 ---
  16  drivers/of/base.c | 275 +++++++++++++++++++++++-----------------------
  17  drivers/of/fdt.c  |   9 +-
  18  2 files changed, 141 insertions(+), 143 deletions(-)
  19
  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);
  24
  25  /**
  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
  30   *
  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.
  35   */
  36  struct device_node *of_get_parent(const struct device_node *node)
  37  {
  38 @@ -673,15 +673,15 @@ struct device_node *of_get_parent(const
  39  EXPORT_SYMBOL(of_get_parent);
  40
  41  /**
  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
  46   *
  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.
  53   *
  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.
  58   */
  59  struct device_node *of_get_next_parent(struct device_node *node)
  60  {
  61 @@ -719,13 +719,13 @@ static struct device_node *__of_get_next
  62              child = __of_get_next_child(parent, child))
  63
  64  /**
  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
  68 - *
  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
  71 - *     refcount of prev.
  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
  75 + *
  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
  78 + * refcount of prev.
  79   */
  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);
  84
  85  /**
  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
  92   *
  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").
  97   */
  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);
 102
 103  /**
 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
 108   *
 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.
 115   */
 116  struct device_node *of_get_next_cpu_node(struct device_node *prev)
 117  {
 118 @@ -834,15 +834,15 @@ struct device_node *of_get_compatible_ch
 119  EXPORT_SYMBOL(of_get_compatible_child);
 120
 121  /**
 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.
 125 - *
 126 - *      This function looks for child node for given matching name
 127 - *
 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.
 134 + *
 135 + * This function looks for child node for given matching name
 136 + *
 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.
 140   */
 141  struct device_node *of_get_child_by_name(const struct device_node *node,
 142                                 const char *name)
 143 @@ -893,22 +893,22 @@ struct device_node *__of_find_node_by_fu
 144  }
 145
 146  /**
 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
 154 - *            a ':' separator.
 155 - *
 156 - *     Valid paths:
 157 - *             /foo/bar        Full path
 158 - *             foo             Valid alias
 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
 167 + *       a ':' separator.
 168 + *
 169 + * Valid paths:
 170 + *  * /foo/bar Full path
 171 + *  * foo      Valid alias
 172 + *  * foo/bar  Valid alias + relative path
 173   *
 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.
 178   */
 179  struct device_node *of_find_node_opts_by_path(const char *path, const char **opts)
 180  {
 181 @@ -958,15 +958,15 @@ struct device_node *of_find_node_opts_by
 182  EXPORT_SYMBOL(of_find_node_opts_by_path);
 183
 184  /**
 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
 194   *
 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.
 199   */
 200  struct device_node *of_find_node_by_name(struct device_node *from,
 201         const char *name)
 202 @@ -985,16 +985,16 @@ struct device_node *of_find_node_by_name
 203  EXPORT_SYMBOL(of_find_node_by_name);
 204
 205  /**
 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
 216   *
 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.
 221   */
 222  struct device_node *of_find_node_by_type(struct device_node *from,
 223         const char *type)
 224 @@ -1013,18 +1013,18 @@ struct device_node *of_find_node_by_type
 225  EXPORT_SYMBOL(of_find_node_by_type);
 226
 227  /**
 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.
 245   *
 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.
 250   */
 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);
 255
 256  /**
 257 - *     of_find_node_with_property - Find a node which has a property with
 258 - *                                   the given name.
 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
 265 + *                              the given name.
 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.
 271   *
 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.
 276   */
 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
 280
 281  /**
 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
 287   *
 288 - *     Low level utility function used by device matching.
 289 + * Low level utility function used by device matching.
 290   */
 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);
 295
 296  /**
 297 - *     of_find_matching_node_and_match - Find a node based on an of_device_id
 298 - *                                       match table.
 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
 306 + *                                  match table.
 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
 313   *
 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.
 318   */
 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
 323   * pointer.
 324   *
 325 - * Example:
 326 + * Example::
 327   *
 328 - * phandle1: node1 {
 329 + *  phandle1: node1 {
 330   *     #list-cells = <2>;
 331 - * }
 332 + *  };
 333   *
 334 - * phandle2: node2 {
 335 + *  phandle2: node2 {
 336   *     #list-cells = <1>;
 337 - * }
 338 + *  };
 339   *
 340 - * node3 {
 341 + *  node3 {
 342   *     list = <&phandle1 1 2 &phandle2 3>;
 343 - * }
 344 + *  };
 345   *
 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);
 349   */
 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
 353   * pointer.
 354   *
 355 - * Example:
 356 - *
 357 - * phandle1: node1 {
 358 - *     #list-cells = <2>;
 359 - * }
 360 - *
 361 - * phandle2: node2 {
 362 - *     #list-cells = <1>;
 363 - * }
 364 + * Example::
 365   *
 366 - * phandle3: node3 {
 367 - *     #list-cells = <1>;
 368 - *     list-map = <0 &phandle2 3>,
 369 - *                <1 &phandle2 2>,
 370 - *                <2 &phandle1 5 1>;
 371 - *     list-map-mask = <0x3>;
 372 - * };
 373 - *
 374 - * node4 {
 375 - *     list = <&phandle1 1 2 &phandle3 0>;
 376 - * }
 377 + *  phandle1: node1 {
 378 + *     #list-cells = <2>;
 379 + *  };
 380 + *
 381 + *  phandle2: node2 {
 382 + *     #list-cells = <1>;
 383 + *  };
 384 + *
 385 + *  phandle3: node3 {
 386 + *     #list-cells = <1>;
 387 + *     list-map = <0 &phandle2 3>,
 388 + *                <1 &phandle2 2>,
 389 + *                <2 &phandle1 5 1>;
 390 + *     list-map-mask = <0x3>;
 391 + *  };
 392 + *
 393 + *  node4 {
 394 + *     list = <&phandle1 1 2 &phandle3 0>;
 395 + *  };
 396   *
 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);
 400   */
 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
 404   * pointer.
 405   *
 406 - * Example:
 407 + * Example::
 408   *
 409 - * phandle1: node1 {
 410 - * }
 411 + *  phandle1: node1 {
 412 + *  };
 413   *
 414 - * phandle2: node2 {
 415 - * }
 416 + *  phandle2: node2 {
 417 + *  };
 418   *
 419 - * node3 {
 420 - *     list = <&phandle1 0 2 &phandle2 2 3>;
 421 - * }
 422 + *  node3 {
 423 + *     list = <&phandle1 0 2 &phandle2 2 3>;
 424 + *  };
 425   *
 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);
 429   */
 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
 432
 433  /**
 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
 437   *
 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.
 441 - *
 442 - * @dt_alloc:  An allocator that provides a virtual address to memory
 443 - *             for storing the resulting tree
 444   */
 445  void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align))
 446  {
 447 @@ -2158,12 +2157,12 @@ bool of_console_check(struct device_node
 448  EXPORT_SYMBOL_GPL(of_console_check);
 449
 450  /**
 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"
 455   *
 456 - *     Returns a node pointer with refcount incremented, use
 457 - *     of_node_put() on it when done.  Caller should hold a reference
 458 - *     to np.
 459 + * Return: A node pointer with refcount incremented, use
 460 + * of_node_put() on it when done.  Caller should hold a reference
 461 + * to np.
 462   */
 463  struct device_node *of_find_next_cache_node(const struct device_node *np)
 464  {
 465 --- a/drivers/of/fdt.c
 466 +++ b/drivers/of/fdt.c
 467 @@ -349,11 +349,6 @@ static int unflatten_dt_nodes(const void
 468
 469  /**
 470   * __unflatten_device_tree - create tree of device_nodes from flat blob
 471 - *
 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
 475 - * can be used.
 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
 482   *
 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.
 486 + *
 487   * Returns NULL on failure or the memory chunk containing the unflattened
 488   * device tree on success.
 489   */