[PATCH v4 0/2] smp: Fix the comments in smp.c

[PATCH v4 0/2] smp: Fix the comments in smp.c

[Zhen Lei]

v3 --> v4:
1. Change "function-name:" to "function-name -".
2. Fix other kernel-doc related mistakes.

v2 --> v3:
Add the descrition of other parameters of smp_call_function_many_cond().

v1 --> v2:
Delete some duplicate comments.

Zhen Lei (2):
  smp: Fix the comments of smp_call_function_many()
  smp: Fix kernel-doc related mistakes

 kernel/smp.c | 36 ++++++++++++++++++++++++------------
 1 file changed, 24 insertions(+), 12 deletions(-)

-- 
2.25.1

[PATCH v4 1/2] smp: Fix the comments of smp_call_function_many()

[Zhen Lei]

As commit a32a4d8a815c ("smp: Run functions concurrently in
smp_call_function_many_cond()") itself says:
                  "Keep other smp_call_function_many() semantic as it is
today for backward compatibility: the called function is not executed in
this case locally."

It's clear that, the function header comments of smp_call_function_many()
does not need to be changed.

So move the comment about 'scf_flags' to smp_call_function_many_cond(),
and restore the original comments of smp_call_function_many(). The
comments have been simplified slightly to avoid duplication. And the
description of other parameters of smp_call_function_many_cond() is added.

Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
---
 kernel/smp.c | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/kernel/smp.c b/kernel/smp.c
index 01a7c1706a58b1d..1e5221fe200296a 100644
--- a/kernel/smp.c
+++ b/kernel/smp.c
@@ -853,14 +853,26 @@ int smp_call_function_any(const struct cpumask *mask,
 EXPORT_SYMBOL_GPL(smp_call_function_any);
 
 /*
- * Flags to be used as scf_flags argument of smp_call_function_many_cond().
- *
  * %SCF_WAIT:		Wait until function execution is completed
  * %SCF_RUN_LOCAL:	Run also locally if local cpu is set in cpumask
  */
 #define SCF_WAIT	(1U << 0)
 #define SCF_RUN_LOCAL	(1U << 1)
 
+/**
+ * smp_call_function_many_cond() - Run a function on a set of CPUs.
+ * @mask:	The set of cpus to run on (only runs on online subset).
+ *		Whether to allow execution on the local CPU is also controlled
+ *		by @scf_flags.
+ * @func:	The function to run on all applicable CPUs.
+ * @info:	An arbitrary pointer to pass to @func.
+ * @scf_flags:	Bitmask that controls the operation. Such as SCF_WAIT,
+ *		SCF_RUN_LOCAL.
+ * @cond_func:	A callback function that is passed a cpu id and the info
+ *		parameter. The function should return a blooean value
+ *		indicating whether @func will be executed on the specified CPU.
+ *		If @cond_func is NULL, that means unconditional, always true.
+ */
 static void smp_call_function_many_cond(const struct cpumask *mask,
 					smp_call_func_t func, void *info,
 					unsigned int scf_flags,
@@ -972,14 +984,12 @@ static void smp_call_function_many_cond(const struct cpumask *mask,
 }
 
 /**
- * smp_call_function_many(): Run a function on a set of CPUs.
+ * smp_call_function_many() - Run a function on a set of other CPUs.
  * @mask: The set of cpus to run on (only runs on online subset).
  * @func: The function to run. This must be fast and non-blocking.
  * @info: An arbitrary pointer to pass to the function.
- * @wait: Bitmask that controls the operation. If %SCF_WAIT is set, wait
- *        (atomically) until function has completed on other CPUs. If
- *        %SCF_RUN_LOCAL is set, the function will also be run locally
- *        if the local CPU is set in the @cpumask.
+ * @wait: If true, wait (atomically) until function has completed
+ *        on other CPUs.
  *
  * If @wait is true, then returns once @func has returned.
  *
-- 
2.25.1

[PATCH v4 2/2] smp: Fix kernel-doc related mistakes

[Zhen Lei]

1. Change "function-name:" to "function-name -".
2. The kernel-doc comments should start with "/**".
3. Add descriptions for the missing parameters.
4. Fix a mismatched function name in the comment.

Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
---
 kernel/smp.c | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/kernel/smp.c b/kernel/smp.c
index 1e5221fe200296a..d00cc8e0e5d8b16 100644
--- a/kernel/smp.c
+++ b/kernel/smp.c
@@ -698,8 +698,9 @@ void flush_smp_call_function_from_idle(void)
 	local_irq_restore(flags);
 }
 
-/*
+/**
  * smp_call_function_single - Run a function on a specific CPU
+ * @cpu:  The CPU to run on.
  * @func: The function to run. This must be fast and non-blocking.
  * @info: An arbitrary pointer to pass to the function.
  * @wait: If true, wait until function has completed on other CPUs.
@@ -809,7 +810,7 @@ int smp_call_function_single_async(int cpu, struct __call_single_data *csd)
 }
 EXPORT_SYMBOL_GPL(smp_call_function_single_async);
 
-/*
+/**
  * smp_call_function_any - Run a function on any of the given cpus
  * @mask: The mask of cpus it can run on.
  * @func: The function to run. This must be fast and non-blocking.
@@ -1005,7 +1006,7 @@ void smp_call_function_many(const struct cpumask *mask,
 EXPORT_SYMBOL(smp_call_function_many);
 
 /**
- * smp_call_function(): Run a function on all other CPUs.
+ * smp_call_function() - Run a function on all other CPUs.
  * @func: The function to run. This must be fast and non-blocking.
  * @info: An arbitrary pointer to pass to the function.
  * @wait: If true, wait (atomically) until function has completed
@@ -1111,8 +1112,8 @@ void __init smp_init(void)
 	smp_cpus_done(setup_max_cpus);
 }
 
-/*
- * on_each_cpu_cond(): Call a function on each processor for which
+/**
+ * on_each_cpu_cond_mask() - Call a function on each processor for which
  * the supplied function cond_func returns true, optionally waiting
  * for all the required CPUs to finish. This may include the local
  * processor.
@@ -1126,6 +1127,7 @@ void __init smp_init(void)
  * @info:	An arbitrary pointer to pass to both functions.
  * @wait:	If true, wait (atomically) until function has
  *		completed on other CPUs.
+ * @mask:	The set of cpus to run on (only runs on online subset).
  *
  * Preemption is disabled to protect against CPUs going offline but not online.
  * CPUs going online during the call will not be seen or sent an IPI.
-- 
2.25.1

Re: [PATCH v4 2/2] smp: Fix kernel-doc related mistakes

[Randy Dunlap]

On 12/16/21 06:40, Zhen Lei wrote:
> 1. Change "function-name:" to "function-name -".
> 2. The kernel-doc comments should start with "/**".
> 3. Add descriptions for the missing parameters.
> 4. Fix a mismatched function name in the comment.
> 
> Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>

Acked-by: Randy Dunlap <rdunlap@infradead.org>

thanks.


> ---
>  kernel/smp.c | 12 +++++++-----
>  1 file changed, 7 insertions(+), 5 deletions(-)
> 
> diff --git a/kernel/smp.c b/kernel/smp.c
> index 1e5221fe200296a..d00cc8e0e5d8b16 100644
> --- a/kernel/smp.c
> +++ b/kernel/smp.c
> @@ -698,8 +698,9 @@ void flush_smp_call_function_from_idle(void)
>  	local_irq_restore(flags);
>  }
>  
> -/*
> +/**
>   * smp_call_function_single - Run a function on a specific CPU
> + * @cpu:  The CPU to run on.
>   * @func: The function to run. This must be fast and non-blocking.
>   * @info: An arbitrary pointer to pass to the function.
>   * @wait: If true, wait until function has completed on other CPUs.
> @@ -809,7 +810,7 @@ int smp_call_function_single_async(int cpu, struct __call_single_data *csd)
>  }
>  EXPORT_SYMBOL_GPL(smp_call_function_single_async);
>  
> -/*
> +/**
>   * smp_call_function_any - Run a function on any of the given cpus
>   * @mask: The mask of cpus it can run on.
>   * @func: The function to run. This must be fast and non-blocking.
> @@ -1005,7 +1006,7 @@ void smp_call_function_many(const struct cpumask *mask,
>  EXPORT_SYMBOL(smp_call_function_many);
>  
>  /**
> - * smp_call_function(): Run a function on all other CPUs.
> + * smp_call_function() - Run a function on all other CPUs.
>   * @func: The function to run. This must be fast and non-blocking.
>   * @info: An arbitrary pointer to pass to the function.
>   * @wait: If true, wait (atomically) until function has completed
> @@ -1111,8 +1112,8 @@ void __init smp_init(void)
>  	smp_cpus_done(setup_max_cpus);
>  }
>  
> -/*
> - * on_each_cpu_cond(): Call a function on each processor for which
> +/**
> + * on_each_cpu_cond_mask() - Call a function on each processor for which
>   * the supplied function cond_func returns true, optionally waiting
>   * for all the required CPUs to finish. This may include the local
>   * processor.
> @@ -1126,6 +1127,7 @@ void __init smp_init(void)
>   * @info:	An arbitrary pointer to pass to both functions.
>   * @wait:	If true, wait (atomically) until function has
>   *		completed on other CPUs.
> + * @mask:	The set of cpus to run on (only runs on online subset).
>   *
>   * Preemption is disabled to protect against CPUs going offline but not online.
>   * CPUs going online during the call will not be seen or sent an IPI.

-- 
~Randy

Re: [PATCH v4 1/2] smp: Fix the comments of smp_call_function_many()

[Randy Dunlap]

On 12/16/21 06:40, Zhen Lei wrote:
> As commit a32a4d8a815c ("smp: Run functions concurrently in
> smp_call_function_many_cond()") itself says:
>                   "Keep other smp_call_function_many() semantic as it is
> today for backward compatibility: the called function is not executed in
> this case locally."
> 
> It's clear that, the function header comments of smp_call_function_many()
> does not need to be changed.
> 
> So move the comment about 'scf_flags' to smp_call_function_many_cond(),
> and restore the original comments of smp_call_function_many(). The
> comments have been simplified slightly to avoid duplication. And the
> description of other parameters of smp_call_function_many_cond() is added.
> 
> Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>

Acked-by: Randy Dunlap <rdunlap@infradead.org>

thanks.

> ---
>  kernel/smp.c | 24 +++++++++++++++++-------
>  1 file changed, 17 insertions(+), 7 deletions(-)
> 
> diff --git a/kernel/smp.c b/kernel/smp.c
> index 01a7c1706a58b1d..1e5221fe200296a 100644
> --- a/kernel/smp.c
> +++ b/kernel/smp.c
> @@ -853,14 +853,26 @@ int smp_call_function_any(const struct cpumask *mask,
>  EXPORT_SYMBOL_GPL(smp_call_function_any);
>  
>  /*
> - * Flags to be used as scf_flags argument of smp_call_function_many_cond().
> - *
>   * %SCF_WAIT:		Wait until function execution is completed
>   * %SCF_RUN_LOCAL:	Run also locally if local cpu is set in cpumask
>   */
>  #define SCF_WAIT	(1U << 0)
>  #define SCF_RUN_LOCAL	(1U << 1)
>  
> +/**
> + * smp_call_function_many_cond() - Run a function on a set of CPUs.
> + * @mask:	The set of cpus to run on (only runs on online subset).
> + *		Whether to allow execution on the local CPU is also controlled
> + *		by @scf_flags.
> + * @func:	The function to run on all applicable CPUs.
> + * @info:	An arbitrary pointer to pass to @func.
> + * @scf_flags:	Bitmask that controls the operation. Such as SCF_WAIT,
> + *		SCF_RUN_LOCAL.
> + * @cond_func:	A callback function that is passed a cpu id and the info
> + *		parameter. The function should return a blooean value
> + *		indicating whether @func will be executed on the specified CPU.
> + *		If @cond_func is NULL, that means unconditional, always true.
> + */
>  static void smp_call_function_many_cond(const struct cpumask *mask,
>  					smp_call_func_t func, void *info,
>  					unsigned int scf_flags,
> @@ -972,14 +984,12 @@ static void smp_call_function_many_cond(const struct cpumask *mask,
>  }
>  
>  /**
> - * smp_call_function_many(): Run a function on a set of CPUs.
> + * smp_call_function_many() - Run a function on a set of other CPUs.
>   * @mask: The set of cpus to run on (only runs on online subset).
>   * @func: The function to run. This must be fast and non-blocking.
>   * @info: An arbitrary pointer to pass to the function.
> - * @wait: Bitmask that controls the operation. If %SCF_WAIT is set, wait
> - *        (atomically) until function has completed on other CPUs. If
> - *        %SCF_RUN_LOCAL is set, the function will also be run locally
> - *        if the local CPU is set in the @cpumask.
> + * @wait: If true, wait (atomically) until function has completed
> + *        on other CPUs.
>   *
>   * If @wait is true, then returns once @func has returned.
>   *

-- 
~Randy