[PATCH v2 01/11] stop_machine: Clarify @cpus == NULL semantics

["Chang S. Bae" <chang.seok.bae@intel.com>]

The stop-machine API description currently mentions that @cpus == NULL
means running on "each cpu_online_mask". Previously, it was described as
"any cpu_online_mask" before commit:

  fc6f89dc707 ("stop_machine: Improve kernel-doc function-header comments")

In fact, multi_cpu_stop() selects the first CPU in cpu_online_mask when
@cpus is NULL. Right now cpumask_any() is defined as cpumask_first(). So
the previous description was closer but apparently it was not clear
enough either.

Fix those comments for clarity.

Signed-off-by: Chang S. Bae <chang.seok.bae@intel.com>
---
V1 -> V2: New patch

Considering stop_machine_nmi_cpuslocked() and its another cpumask, I
could realize this nullptr implication is not clear enough. Then, it
ended up with this fix.

I also considered just saying CPU0, but still 'cpumask_first(cpu_online_mask)'
are there. So, leave it like that, instead of converting them
aggressively.
---
 include/linux/stop_machine.h | 6 ++++--
 kernel/stop_machine.c        | 4 +++-
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/include/linux/stop_machine.h b/include/linux/stop_machine.h
index 72820503514c..c753dd53e79d 100644
--- a/include/linux/stop_machine.h
+++ b/include/linux/stop_machine.h
@@ -99,7 +99,8 @@ 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. If NULL, @fn() runs on a single
+ *        (arbitrary) CPU from cpu_online_mask.
  *
  * 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 +134,8 @@ 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. If NULL, @fn() runs on a single
+ *        (arbitrary) CPU from cpu_online_mask.
  *
  * Same as above.  Avoids nested calls to cpus_read_lock().
  *
diff --git a/kernel/stop_machine.c b/kernel/stop_machine.c
index 3fe6b0c99f3d..822cf56fdc81 100644
--- a/kernel/stop_machine.c
+++ b/kernel/stop_machine.c
@@ -655,9 +655,11 @@ EXPORT_SYMBOL_GPL(stop_core_cpuslocked);
 
 /**
  * stop_machine_from_inactive_cpu - stop_machine() from inactive CPU
+ *
  * @fn: the function to run
  * @data: the data ptr for the @fn()
- * @cpus: the cpus to run the @fn() on (NULL = any online cpu)
+ * @cpus: the CPUs to run the @fn() on. If NULL, @fn() runs on a single
+ *        (arbitrary) CPU from cpu_online_mask.
  *
  * This is identical to stop_machine() but can be called from a CPU which
  * is not active.  The local CPU is in the process of hotplug (so no other
-- 
2.51.0