[RFC PATCH 2/2] sched/wait: Clarify WF_SYNC wakeup semantics

[Shubhang Kaushik (Ampere)]

The synchronous waitqueue wakeup comments state that the wakee will not
be migrated to another CPU. This is not guaranteed by the current
scheduler wakeup path.

The synchronous helpers pass WF_SYNC to waitqueue wake functions. The
default wake function forwards it to the scheduler, where fair-class
tasks can use it as a wakeup-placement and preemption hint.

Correct the API comments to describe this behavior and remove the
incorrect no-migration guarantee.

Signed-off-by: Shubhang Kaushik (Ampere) <sh@xxxxxxxxxx>
---
 kernel/sched/wait.c | 30 ++++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/kernel/sched/wait.c b/kernel/sched/wait.c
index d033f600f48c6fc3a0a088ea5d9f6ed95ec4c86e..ac1d260a6a37fc35b934079706819b79e20df4ba 100644
--- a/kernel/sched/wait.c
+++ b/kernel/sched/wait.c
@@ -174,15 +174,16 @@ EXPORT_SYMBOL_GPL(__wake_up_locked_key);
  * @mode: which threads
  * @key: opaque value to be passed to wakeup targets
  *
- * The sync wakeup differs that the waker knows that it will schedule
- * away soon, so while the target thread will be woken up, it will not
- * be migrated to another CPU - ie. the two threads are 'synchronized'
- * with each other. This can prevent needless bouncing between CPUs.
+ * The caller expects the waker to schedule away soon. This helper passes
+ * WF_SYNC to waitqueue wake functions. The default wake function forwards
+ * it to the scheduler.
  *
- * On UP it can prevent extra preemption.
+ * For fair-class tasks, WF_SYNC is a wakeup-placement and preemption
+ * hint. It does not guarantee that the wakee will run on the waker CPU
+ * or avoid migration. On UP, this may avoid an unnecessary preemption.
  *
- * If this function wakes up a task, it executes a full memory barrier before
- * accessing the task state.
+ * If this function wakes up a task, it executes a full memory barrier
+ * before accessing the task state.
  */
 void __wake_up_sync_key(struct wait_queue_head *wq_head, unsigned int mode,
 			void *key)
@@ -200,15 +201,16 @@ EXPORT_SYMBOL_GPL(__wake_up_sync_key);
  * @mode: which threads
  * @key: opaque value to be passed to wakeup targets
  *
- * The sync wakeup differs in that the waker knows that it will schedule
- * away soon, so while the target thread will be woken up, it will not
- * be migrated to another CPU - ie. the two threads are 'synchronized'
- * with each other. This can prevent needless bouncing between CPUs.
+ * The caller expects the waker to schedule away soon. This helper passes
+ * WF_SYNC to waitqueue wake functions. The default wake function forwards
+ * it to the scheduler
  *
- * On UP it can prevent extra preemption.
+ * For fair-class tasks, WF_SYNC is a wakeup-placement and preemption
+ * hint. It does not guarantee that the wakee will run on the waker CPU
+ * or avoid migration. On UP, this may avoid an unnecessary preemption.
  *
- * If this function wakes up a task, it executes a full memory barrier before
- * accessing the task state.
+ * If this function wakes up a task, it executes a full memory barrier
+ * before accessing the task state.
  */
 void __wake_up_locked_sync_key(struct wait_queue_head *wq_head,
 			       unsigned int mode, void *key)

-- 
2.52.0