[PATCH v2] smp: Fix the comments of smp_call_function_many()

[PATCH v2] 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().

Finally, the comments have been simplified slightly to avoid duplication.

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

v1 --> v2:
Delete some duplicate comments.

diff --git a/kernel/smp.c b/kernel/smp.c
index 01a7c1706a58b1d..9cbe2509d1010ea 100644
--- a/kernel/smp.c
+++ b/kernel/smp.c
@@ -853,14 +853,17 @@ 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.
+ * @scf_flags: Bitmask that controls the operation. Such as SCF_WAIT,
+ *             SCF_RUN_LOCAL.
+ */
 static void smp_call_function_many_cond(const struct cpumask *mask,
 					smp_call_func_t func, void *info,
 					unsigned int scf_flags,
@@ -972,14 +975,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

Re: [PATCH v2] smp: Fix the comments of smp_call_function_many()

[Randy Dunlap]

Hi,

On 12/14/21 00:10, 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().
> 
> Finally, the comments have been simplified slightly to avoid duplication.
> 
> Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
> ---
>  kernel/smp.c | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)
> 
> v1 --> v2:
> Delete some duplicate comments.
> 
> diff --git a/kernel/smp.c b/kernel/smp.c
> index 01a7c1706a58b1d..9cbe2509d1010ea 100644
> --- a/kernel/smp.c
> +++ b/kernel/smp.c
> @@ -853,14 +853,17 @@ 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.
> + * @scf_flags: Bitmask that controls the operation. Such as SCF_WAIT,
> + *             SCF_RUN_LOCAL.
> + */
>  static void smp_call_function_many_cond(const struct cpumask *mask,
>  					smp_call_func_t func, void *info,
>  					unsigned int scf_flags,
> @@ -972,14 +975,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.
>   *

After applying this patch, kernel-doc emits 4 warnings:

smp.c:871: warning: Function parameter or member 'mask' not described in 'smp_call_function_many_cond'
smp.c:871: warning: Function parameter or member 'func' not described in 'smp_call_function_many_cond'
smp.c:871: warning: Function parameter or member 'info' not described in 'smp_call_function_many_cond'
smp.c:871: warning: Function parameter or member 'cond_func' not described in 'smp_call_function_many_cond'


thanks.
-- 
~Randy

Re: [PATCH v2] smp: Fix the comments of smp_call_function_many()

[Leizhen (ThunderTown)]

On 2021/12/14 23:56, Randy Dunlap wrote:
> Hi,
> 
> On 12/14/21 00:10, 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().
>>
>> Finally, the comments have been simplified slightly to avoid duplication.
>>
>> Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
>> ---
>>  kernel/smp.c | 15 ++++++++-------
>>  1 file changed, 8 insertions(+), 7 deletions(-)
>>
>> v1 --> v2:
>> Delete some duplicate comments.
>>
>> diff --git a/kernel/smp.c b/kernel/smp.c
>> index 01a7c1706a58b1d..9cbe2509d1010ea 100644
>> --- a/kernel/smp.c
>> +++ b/kernel/smp.c
>> @@ -853,14 +853,17 @@ 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.
>> + * @scf_flags: Bitmask that controls the operation. Such as SCF_WAIT,
>> + *             SCF_RUN_LOCAL.
>> + */
>>  static void smp_call_function_many_cond(const struct cpumask *mask,
>>  					smp_call_func_t func, void *info,
>>  					unsigned int scf_flags,
>> @@ -972,14 +975,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.
>>   *
> 
> After applying this patch, kernel-doc emits 4 warnings:
> 
> smp.c:871: warning: Function parameter or member 'mask' not described in 'smp_call_function_many_cond'
> smp.c:871: warning: Function parameter or member 'func' not described in 'smp_call_function_many_cond'
> smp.c:871: warning: Function parameter or member 'info' not described in 'smp_call_function_many_cond'
> smp.c:871: warning: Function parameter or member 'cond_func' not described in 'smp_call_function_many_cond'

OK, I will complete the comments in the next version. Thanks.


> 
> 
> thanks.
>