@@ -88,55 +88,73 @@ static inline void print_stop_info(const char *log_lvl, struct task_struct *task
8888#endif /* CONFIG_SMP */
8989
9090/*
91- * stop_machine "Bogolock": stop the entire machine, disable
92- * interrupts. This is a very heavy lock, which is equivalent to
93- * grabbing every spinlock (and more). So the "read" side to such a
94- * lock is anything which disables preemption.
91+ * stop_machine "Bogolock": stop the entire machine, disable interrupts.
92+ * This is a very heavy lock, which is equivalent to grabbing every raw
93+ * spinlock (and more). So the "read" side to such a lock is anything
94+ * which disables preemption.
9595 */
9696#if defined(CONFIG_SMP ) || defined(CONFIG_HOTPLUG_CPU )
9797
9898/**
9999 * stop_machine: freeze the machine on all CPUs and run this function
100100 * @fn: the function to run
101- * @data: the data ptr for the @fn()
102- * @cpus: the cpus to run the @fn() on (NULL = any online cpu )
101+ * @data: the data ptr to pass to @fn()
102+ * @cpus: the cpus to run @fn() on (NULL = run on each online CPU )
103103 *
104- * Description: This causes a thread to be scheduled on every cpu,
105- * each of which disables interrupts. The result is that no one is
106- * holding a spinlock or inside any other preempt-disabled region when
107- * @fn() runs.
104+ * Description: This causes a thread to be scheduled on every CPU, which
105+ * will run with interrupts disabled. Each CPU specified by @cpus will
106+ * run @fn. While @fn is executing, there will no other CPUs holding
107+ * a raw spinlock or running within any other type of preempt-disabled
108+ * region of code.
108109 *
109- * This can be thought of as a very heavy write lock, equivalent to
110- * grabbing every spinlock in the kernel.
110+ * When @cpus specifies only a single CPU, this can be thought of as
111+ * a reader-writer lock where readers disable preemption (for example,
112+ * by holding a raw spinlock) and where the insanely heavy writers run
113+ * @fn while also preventing any other CPU from doing any useful work.
114+ * These writers can also be thought of as having implicitly grabbed every
115+ * raw spinlock in the kernel.
111116 *
112- * Protects against CPU hotplug.
117+ * When @fn is a no-op, this can be thought of as an RCU implementation
118+ * where readers again disable preemption and writers use stop_machine()
119+ * in place of synchronize_rcu(), albeit with orders of magnitude more
120+ * disruption than even that of synchronize_rcu_expedited().
121+ *
122+ * Although only one stop_machine() operation can proceed at a time,
123+ * the possibility of blocking in cpus_read_lock() means that the caller
124+ * cannot usefully rely on this serialization.
125+ *
126+ * Return: 0 if all invocations of @fn return zero. Otherwise, the
127+ * value returned by an arbitrarily chosen member of the set of calls to
128+ * @fn that returned non-zero.
113129 */
114130int stop_machine (cpu_stop_fn_t fn , void * data , const struct cpumask * cpus );
115131
116132/**
117133 * stop_machine_cpuslocked: freeze the machine on all CPUs and run this function
118134 * @fn: the function to run
119- * @data: the data ptr for the @fn()
120- * @cpus: the cpus to run the @fn() on (NULL = any online cpu)
135+ * @data: the data ptr to pass to @fn()
136+ * @cpus: the cpus to run @fn() on (NULL = run on each online CPU)
137+ *
138+ * Same as above. Avoids nested calls to cpus_read_lock().
121139 *
122- * Same as above. Must be called from with in a cpus_read_lock() protected
123- * region. Avoids nested calls to cpus_read_lock().
140+ * Context: Must be called from within a cpus_read_lock() protected region.
124141 */
125142int stop_machine_cpuslocked (cpu_stop_fn_t fn , void * data , const struct cpumask * cpus );
126143
127144/**
128145 * stop_core_cpuslocked: - stop all threads on just one core
129146 * @cpu: any cpu in the targeted core
130- * @fn: the function to run
131- * @data: the data ptr for @fn()
147+ * @fn: the function to run on each CPU in the core containing @cpu
148+ * @data: the data ptr to pass to @fn()
132149 *
133- * Same as above, but instead of every CPU, only the logical CPUs of a
134- * single core are affected.
150+ * Same as above, but instead of every CPU, only the logical CPUs of the
151+ * single core containing @cpu are affected.
135152 *
136153 * Context: Must be called from within a cpus_read_lock() protected region.
137154 *
138- * Return: 0 if all executions of @fn returned 0, any non zero return
139- * value if any returned non zero.
155+ * Return: 0 if all invocations of @fn return zero. Otherwise, the
156+ * value returned by an arbitrarily chosen member of the set of calls to
157+ * @fn that returned non-zero.
140158 */
141159int stop_core_cpuslocked (unsigned int cpu , cpu_stop_fn_t fn , void * data );
142160
0 commit comments