Re: [PATCH] stop_machine: Fix the documentation for a NULL cpus argument

[Paul E. McKenney]

On Tue, Feb 17, 2026 at 02:11:11PM +0100, Thomas Weißschuh wrote:
> A recent refactoring of the kernel-docs for stop machine changed the
> description of the cpus parameter from "NULL = any online cpu"
> to "NULL = run on each online CPU".
> 
> However the callback is only executed on a single CPU, not all of them.
> The old wording was a bit ambiguous and could have been read both ways.
> 
> Reword the documentation to be correct again and hopefully also clearer.
> 
> Fixes: fc6f89dc7078 ("stop_machine: Improve kernel-doc function-header comments")
> Signed-off-by: Thomas Weißschuh <thomas.weissschuh@xxxxxxxxxxxxx>
> ---
> There doesn't seem to be a formal maintainer for stop_machine.
> Paul, could you take this through your tree?

Good catch, and I have pulled it in for further review.  Perhaps the
various LLMs will test it as well?  ;-)

							Thanx, Paul

> ---
>  include/linux/stop_machine.h | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/include/linux/stop_machine.h b/include/linux/stop_machine.h
> index 72820503514c..01011113d226 100644
> --- a/include/linux/stop_machine.h
> +++ b/include/linux/stop_machine.h
> @@ -99,7 +99,7 @@ static inline void print_stop_info(const char *log_lvl, struct task_struct *task
>   * stop_machine: freeze the machine on all CPUs and run this function
>   * @fn: the function to run
>   * @data: the data ptr to pass to @fn()
> - * @cpus: the cpus to run @fn() on (NULL = run on each online CPU)
> + * @cpus: the cpus to run @fn() on (NULL = one unspecified online CPU)
>   *
>   * Description: This causes a thread to be scheduled on every CPU, which
>   * will run with interrupts disabled.  Each CPU specified by @cpus will
> @@ -133,7 +133,7 @@ int stop_machine(cpu_stop_fn_t fn, void *data, const struct cpumask *cpus);
>   * stop_machine_cpuslocked: freeze the machine on all CPUs and run this function
>   * @fn: the function to run
>   * @data: the data ptr to pass to @fn()
> - * @cpus: the cpus to run @fn() on (NULL = run on each online CPU)
> + * @cpus: the cpus to run @fn() on (NULL = one unspecified online CPU)
>   *
>   * Same as above.  Avoids nested calls to cpus_read_lock().
>   *
> 
> ---
> base-commit: 9702969978695d9a699a1f34771580cdbb153b33
> change-id: 20260217-stop_machine-comment-795b2bd2a745
> 
> Best regards,
> -- 
> Thomas Weißschuh <thomas.weissschuh@xxxxxxxxxxxxx>
>