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

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

Posted by Thomas Weißschuh 1 month, 2 weeks ago

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@linutronix.de>
---
There doesn't seem to be a formal maintainer for stop_machine.
Paul, could you take this through your tree?
---
 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@linutronix.de>

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

Posted by Paul E. McKenney 1 month, 2 weeks ago

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@linutronix.de>
> ---
> 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@linutronix.de>
>

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

Posted by Sebastian Andrzej Siewior 1 month, 2 weeks ago

On 2026-02-17 14:11:11 [+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.

It is the first online CPU.
It temporary freezes all CPUs and runs the function the first online
CPU. I would prefer this over "unspecified".
Unless you point that it does hold and CPU hotplug locks.

> Fixes: fc6f89dc7078 ("stop_machine: Improve kernel-doc function-header comments")
> Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de>

Sebastian

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

Posted by Paul E. McKenney 1 month, 2 weeks ago

On Tue, Feb 17, 2026 at 05:31:05PM +0100, Sebastian Andrzej Siewior wrote:
> On 2026-02-17 14:11:11 [+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.
> 
> It is the first online CPU.

Do we want to set that in stone?

							Thanx, Paul

> It temporary freezes all CPUs and runs the function the first online
> CPU. I would prefer this over "unspecified".
> Unless you point that it does hold and CPU hotplug locks.
> 
> > Fixes: fc6f89dc7078 ("stop_machine: Improve kernel-doc function-header comments")
> > Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de>
> 
> Sebastian

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

Posted by Sebastian Andrzej Siewior 1 month, 1 week ago

On 2026-02-17 09:01:11 [-0800], Paul E. McKenney wrote:
> On Tue, Feb 17, 2026 at 05:31:05PM +0100, Sebastian Andrzej Siewior wrote:
> > On 2026-02-17 14:11:11 [+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.
> > 
> > It is the first online CPU.
> 
> Do we want to set that in stone?

then keep it as is. I somehow don't like the wording but I'm not here
for bike shedding.

Reviewed-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

> 							Thanx, Paul
Sebastian

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

Posted by Paul E. McKenney 1 month, 1 week ago

On Wed, Feb 18, 2026 at 08:26:11AM +0100, Sebastian Andrzej Siewior wrote:
> On 2026-02-17 09:01:11 [-0800], Paul E. McKenney wrote:
> > On Tue, Feb 17, 2026 at 05:31:05PM +0100, Sebastian Andrzej Siewior wrote:
> > > On 2026-02-17 14:11:11 [+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.
> > > 
> > > It is the first online CPU.
> > 
> > Do we want to set that in stone?
> 
> then keep it as is. I somehow don't like the wording but I'm not here
> for bike shedding.

I agree that it probably could be improved, but it does seem clear,
correct, and unambiguous, so I also agree with leaving good enough
alone.  ;-)

> Reviewed-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

Applied and pushed, thank you!

							Thanx, Paul