Re: [PATCH v4 02/14] of: Do not expose of_alias_scan() and correct its comments

[Rob Herring <robh@kernel.org>]

On Thu, Jan 09, 2025 at 09:26:53PM +0800, Zijun Hu wrote:
> From: Zijun Hu <quic_zijuhu@quicinc.com>
> 
> For of_alias_scan():
> - Do not expose it since it has no external callers.
> - Correct its comments shown below:
>   1) Replace /* with /** to start comments since it is not a API.

You've got that backwards. However, in other places we leave this. I 
prefer if the comment is in kerneldoc format, then it should have '/**' 
to indicate that and so that it is checked by the tools.

>   2) Delete return value descriptions since it is a void function.
> 
> Signed-off-by: Zijun Hu <quic_zijuhu@quicinc.com>
> ---
>  drivers/of/base.c       | 5 ++---
>  drivers/of/of_private.h | 2 ++
>  drivers/of/pdt.c        | 2 ++
>  include/linux/of.h      | 1 -
>  4 files changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/of/base.c b/drivers/of/base.c
> index 969b99838655534915882abe358814d505c6f748..5485307e2a3a3d3a216d271c60bdfc346dd38460 100644
> --- a/drivers/of/base.c
> +++ b/drivers/of/base.c
> @@ -1806,14 +1806,13 @@ static void of_alias_add(struct alias_prop *ap, struct device_node *np,
>  		 ap->alias, ap->stem, ap->id, 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.
> + * the global lookup table with the properties.
>   */
>  void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align))
>  {
> diff --git a/drivers/of/of_private.h b/drivers/of/of_private.h
> index ea5a0951ec5e107bab265ab5f6c043e2bfb15ecc..3433ccd330e84fd3a4b54638e0e922069757c8f0 100644
> --- a/drivers/of/of_private.h
> +++ b/drivers/of/of_private.h
> @@ -119,6 +119,8 @@ extern void *__unflatten_device_tree(const void *blob,
>  			      void *(*dt_alloc)(u64 size, u64 align),
>  			      bool detached);
>  
> +void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align));
> +
>  /**
>   * General utilities for working with live trees.
>   *
> diff --git a/drivers/of/pdt.c b/drivers/of/pdt.c
> index 7eda43c66c916198b1c2d8fc5043fcb1edaede7a..cb0cb374b21ff89323e11f34bd767b183e7a401e 100644
> --- a/drivers/of/pdt.c
> +++ b/drivers/of/pdt.c
> @@ -19,6 +19,8 @@
>  #include <linux/of.h>
>  #include <linux/of_pdt.h>
>  
> +#include "of_private.h"
> +
>  static struct of_pdt_ops *of_pdt_prom_ops __initdata;
>  
>  #if defined(CONFIG_SPARC)
> diff --git a/include/linux/of.h b/include/linux/of.h
> index f921786cb8ac782286ed5ff4425a35668204d050..d451c46132b01efe6d4e0b6cf83a3e2084bb3ec6 100644
> --- a/include/linux/of.h
> +++ b/include/linux/of.h
> @@ -397,7 +397,6 @@ extern int of_phandle_iterator_args(struct of_phandle_iterator *it,
>  				    uint32_t *args,
>  				    int size);
>  
> -extern void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align));
>  extern int of_alias_get_id(const struct device_node *np, const char *stem);
>  extern int of_alias_get_highest_id(const char *stem);
>  
> 
> -- 
> 2.34.1
>