[PATCH v3] sched: Clarify WF_SYNC wakeup semantics

[PATCH v3] sched: Clarify WF_SYNC wakeup semantics

[Shubhang Kaushik (Ampere)]

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

WF_SYNC is an advisory hint that the caller expects the waker to
schedule away soon. Scheduler classes may use it for placement or
preemption, but callers must not rely on it to prevent migration,
preserve CPU locality, or make the wakee run next.

Keep this contract next to the flag definition, remove the stale
waitqueue wording, and make the locked helper refer to the unlocked
variant.

---
Signed-off-by: Shubhang Kaushik (Ampere) <sh@gentwo.org>
---
Changes in v3:
  - Drop the standalone documentation in favor of a concise comment next
    to WF_SYNC.
  - Consolidate the series into one patch and remove the stale waitqueue
    wording.

Link to v2: https://lore.kernel.org/r/20260917-sched-wf-sync-doc-v2-0-6d1f107c0596@gentwo.org
---
 kernel/sched/sched.h |  9 +++++++--
 kernel/sched/wait.c  | 22 +++++-----------------
 2 files changed, 12 insertions(+), 19 deletions(-)

diff --git a/kernel/sched/sched.h b/kernel/sched/sched.h
index e656c7059bf864d1ed91d4ec3d4624850aded7e0..fe366e9f248996a293e5bb6b76c8f01485a9ea6b 100644
--- a/kernel/sched/sched.h
+++ b/kernel/sched/sched.h
@@ -2527,8 +2527,13 @@ static inline int task_on_rq_migrating(struct task_struct *p)
 #define WF_EXEC			0x02 /* Wakeup after exec; maps to SD_BALANCE_EXEC */
 #define WF_FORK			0x04 /* Wakeup after fork; maps to SD_BALANCE_FORK */
 #define WF_TTWU			0x08 /* Wakeup;            maps to SD_BALANCE_WAKE */
-
-#define WF_SYNC			0x10 /* Waker goes to sleep after wakeup */
+/*
+ * Hint that the caller expects the waker to sleep soon.
+ * Scheduler classes may use it for placement or preemption.
+ * Callers must not rely on it to prevent migration,
+ * preserve CPU locality or make the wakee run next.
+ */
+#define WF_SYNC			0x10
 #define WF_MIGRATED		0x20 /* Internal use, task got migrated */
 #define WF_CURRENT_CPU		0x40 /* Prefer to move the wakee to the current CPU. */
 #define WF_RQ_SELECTED		0x80 /* ->select_task_rq() was called */
diff --git a/kernel/sched/wait.c b/kernel/sched/wait.c
index d033f600f48c6fc3a0a088ea5d9f6ed95ec4c86e..477e4bf9c01e19a520b626c09a8b95c065616fe1 100644
--- a/kernel/sched/wait.c
+++ b/kernel/sched/wait.c
@@ -174,15 +174,11 @@ 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.
+ * Passes WF_SYNC to waitqueue wake functions. The default wake function
+ * forwards it to the scheduler; see WF_SYNC for the hint's semantics.
  *
- * On UP it can prevent extra 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 +196,7 @@ 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.
- *
- * On UP it can prevent extra preemption.
- *
- * If this function wakes up a task, it executes a full memory barrier before
- * accessing the task state.
+ * Same as __wake_up_sync_key(), but called with @wq_head->lock held.
  */
 void __wake_up_locked_sync_key(struct wait_queue_head *wq_head,
 			       unsigned int mode, void *key)

---
base-commit: fe2ec83746e501645709761605c2464a44fd2929
change-id: 20260824-sched-wf-sync-doc-e92b4fe987f7

Best regards,
-- 
Shubhang Kaushik (Ampere) <sh@gentwo.org>

Re: [PATCH v3] sched: Clarify WF_SYNC wakeup semantics

[Peter Zijlstra]

On Tue, Sep 22, 2026 at 02:57:05PM -0700, Shubhang Kaushik (Ampere) wrote:
> The synchronous waitqueue wakeup comments currently state that a
> synchronous wakee will not be migrated to another CPU. This is not
> guaranteed by the scheduler wakeup path.
> 
> WF_SYNC is an advisory hint that the caller expects the waker to
> schedule away soon. Scheduler classes may use it for placement or
> preemption, but callers must not rely on it to prevent migration,
> preserve CPU locality, or make the wakee run next.
> 
> Keep this contract next to the flag definition, remove the stale
> waitqueue wording, and make the locked helper refer to the unlocked
> variant.
> 
> ---
> Signed-off-by: Shubhang Kaushik (Ampere) <sh@gentwo.org>
> ---

Thanks!

Re: [PATCH v3] sched: Clarify WF_SYNC wakeup semantics

[Shrikanth Hegde]

On 9/23/26 3:27 AM, Shubhang Kaushik (Ampere) wrote:
> The synchronous waitqueue wakeup comments currently state that a
> synchronous wakee will not be migrated to another CPU. This is not
> guaranteed by the scheduler wakeup path.
> 
> WF_SYNC is an advisory hint that the caller expects the waker to
> schedule away soon. Scheduler classes may use it for placement or
> preemption, but callers must not rely on it to prevent migration,
> preserve CPU locality, or make the wakee run next.
> 
> Keep this contract next to the flag definition, remove the stale
> waitqueue wording, and make the locked helper refer to the unlocked
> variant.
> 
> ---

nit:
Don't keep --- before the tag.
Anything after is usually dropped from the changelog.

> Signed-off-by: Shubhang Kaushik (Ampere) <sh@gentwo.org>
> ---
> Changes in v3:
>    - Drop the standalone documentation in favor of a concise comment next
>      to WF_SYNC.
>    - Consolidate the series into one patch and remove the stale waitqueue
>      wording.
> 
> Link to v2: https://lore.kernel.org/r/20260917-sched-wf-sync-doc-v2-0-6d1f107c0596@gentwo.org
> ---
>   kernel/sched/sched.h |  9 +++++++--
>   kernel/sched/wait.c  | 22 +++++-----------------
>   2 files changed, 12 insertions(+), 19 deletions(-)
> 
> diff --git a/kernel/sched/sched.h b/kernel/sched/sched.h
> index e656c7059bf864d1ed91d4ec3d4624850aded7e0..fe366e9f248996a293e5bb6b76c8f01485a9ea6b 100644
> --- a/kernel/sched/sched.h
> +++ b/kernel/sched/sched.h
> @@ -2527,8 +2527,13 @@ static inline int task_on_rq_migrating(struct task_struct *p)
>   #define WF_EXEC			0x02 /* Wakeup after exec; maps to SD_BALANCE_EXEC */
>   #define WF_FORK			0x04 /* Wakeup after fork; maps to SD_BALANCE_FORK */
>   #define WF_TTWU			0x08 /* Wakeup;            maps to SD_BALANCE_WAKE */
> -
> -#define WF_SYNC			0x10 /* Waker goes to sleep after wakeup */
> +/*
> + * Hint that the caller expects the waker to sleep soon.
> + * Scheduler classes may use it for placement or preemption.
> + * Callers must not rely on it to prevent migration,
> + * preserve CPU locality or make the wakee run next.
> + */
> +#define WF_SYNC			0x10
>   #define WF_MIGRATED		0x20 /* Internal use, task got migrated */
>   #define WF_CURRENT_CPU		0x40 /* Prefer to move the wakee to the current CPU. */
>   #define WF_RQ_SELECTED		0x80 /* ->select_task_rq() was called */
> diff --git a/kernel/sched/wait.c b/kernel/sched/wait.c
> index d033f600f48c6fc3a0a088ea5d9f6ed95ec4c86e..477e4bf9c01e19a520b626c09a8b95c065616fe1 100644
> --- a/kernel/sched/wait.c
> +++ b/kernel/sched/wait.c
> @@ -174,15 +174,11 @@ 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.
> + * Passes WF_SYNC to waitqueue wake functions. The default wake function
> + * forwards it to the scheduler; see WF_SYNC for the hint's semantics.
>    *
> - * On UP it can prevent extra 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 +196,7 @@ 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.
> - *
> - * On UP it can prevent extra preemption.
> - *
> - * If this function wakes up a task, it executes a full memory barrier before
> - * accessing the task state.
> + * Same as __wake_up_sync_key(), but called with @wq_head->lock held.
>    */
>   void __wake_up_locked_sync_key(struct wait_queue_head *wq_head,
>   			       unsigned int mode, void *key)
> 
> ---
> base-commit: fe2ec83746e501645709761605c2464a44fd2929
> change-id: 20260824-sched-wf-sync-doc-e92b4fe987f7
> 
> Best regards,

Reviewed-by: Shrikanth Hegde <sshegde@linux.ibm.com>

[tip: sched/core] sched: Clarify WF_SYNC wakeup semantics

[tip-bot2 for Shubhang Kaushik (Ampere)]

The following commit has been merged into the sched/core branch of tip:

Commit-ID:     e4c353c3933968fe8efecb269fdbe3baa1d1ddd0
Gitweb:        https://git.kernel.org/tip/e4c353c3933968fe8efecb269fdbe3baa1d1ddd0
Author:        Shubhang Kaushik (Ampere) <sh@gentwo.org>
AuthorDate:    Tue, 22 Sep 2026 14:57:05 -07:00
Committer:     Peter Zijlstra <peterz@infradead.org>
CommitterDate: Fri, 25 Sep 2026 12:45:59 +02:00

sched: Clarify WF_SYNC wakeup semantics

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

WF_SYNC is an advisory hint that the caller expects the waker to
schedule away soon. Scheduler classes may use it for placement or
preemption, but callers must not rely on it to prevent migration,
preserve CPU locality, or make the wakee run next.

Keep this contract next to the flag definition, remove the stale
waitqueue wording, and make the locked helper refer to the unlocked
variant.

Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Link: https://patch.msgid.link/20260922-sched-wf-sync-doc-v3-1-23ebe9e27bef@gentwo.org
---
 kernel/sched/sched.h |  9 +++++++--
 kernel/sched/wait.c  | 22 +++++-----------------
 2 files changed, 12 insertions(+), 19 deletions(-)

diff --git a/kernel/sched/sched.h b/kernel/sched/sched.h
index f7d0b64..b98084e 100644
--- a/kernel/sched/sched.h
+++ b/kernel/sched/sched.h
@@ -2535,8 +2535,13 @@ static inline int task_on_rq_migrating(struct task_struct *p)
 #define WF_EXEC			0x02 /* Wakeup after exec; maps to SD_BALANCE_EXEC */
 #define WF_FORK			0x04 /* Wakeup after fork; maps to SD_BALANCE_FORK */
 #define WF_TTWU			0x08 /* Wakeup;            maps to SD_BALANCE_WAKE */
-
-#define WF_SYNC			0x10 /* Waker goes to sleep after wakeup */
+/*
+ * Hint that the caller expects the waker to sleep soon.
+ * Scheduler classes may use it for placement or preemption.
+ * Callers must not rely on it to prevent migration,
+ * preserve CPU locality or make the wakee run next.
+ */
+#define WF_SYNC			0x10
 #define WF_MIGRATED		0x20 /* Internal use, task got migrated */
 #define WF_CURRENT_CPU		0x40 /* Prefer to move the wakee to the current CPU. */
 #define WF_RQ_SELECTED		0x80 /* ->select_task_rq() was called */
diff --git a/kernel/sched/wait.c b/kernel/sched/wait.c
index d033f60..477e4bf 100644
--- a/kernel/sched/wait.c
+++ b/kernel/sched/wait.c
@@ -174,15 +174,11 @@ 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.
+ * Passes WF_SYNC to waitqueue wake functions. The default wake function
+ * forwards it to the scheduler; see WF_SYNC for the hint's semantics.
  *
- * On UP it can prevent extra 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 +196,7 @@ 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.
- *
- * On UP it can prevent extra preemption.
- *
- * If this function wakes up a task, it executes a full memory barrier before
- * accessing the task state.
+ * Same as __wake_up_sync_key(), but called with @wq_head->lock held.
  */
 void __wake_up_locked_sync_key(struct wait_queue_head *wq_head,
 			       unsigned int mode, void *key)

Re: [tip: sched/core] sched: Clarify WF_SYNC wakeup semantics

[Shrikanth Hegde]

Hi Peter.

On 9/25/26 4:24 PM, tip-bot2 for Shubhang Kaushik (Ampere) wrote:
> The following commit has been merged into the sched/core branch of tip:
> 
> Commit-ID:     e4c353c3933968fe8efecb269fdbe3baa1d1ddd0
> Gitweb:        https://git.kernel.org/tip/e4c353c3933968fe8efecb269fdbe3baa1d1ddd0
> Author:        Shubhang Kaushik (Ampere) <sh@gentwo.org>
> AuthorDate:    Tue, 22 Sep 2026 14:57:05 -07:00
> Committer:     Peter Zijlstra <peterz@infradead.org>
> CommitterDate: Fri, 25 Sep 2026 12:45:59 +02:00
> 
> sched: Clarify WF_SYNC wakeup semantics
> 
> The synchronous waitqueue wakeup comments currently state that a
> synchronous wakee will not be migrated to another CPU. This is not
> guaranteed by the scheduler wakeup path.
> 
> WF_SYNC is an advisory hint that the caller expects the waker to
> schedule away soon. Scheduler classes may use it for placement or
> preemption, but callers must not rely on it to prevent migration,
> preserve CPU locality, or make the wakee run next.
> 
> Keep this contract next to the flag definition, remove the stale
> waitqueue wording, and make the locked helper refer to the unlocked
> variant.
> 
> Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
> Link: https://patch.msgid.link/20260922-sched-wf-sync-doc-v3-1-23ebe9e27bef@gentwo.org


This is missing Shubhang's signed-off-by tag. Likely caused by the --- tag in his
commit message.


> ---
>   kernel/sched/sched.h |  9 +++++++--
>   kernel/sched/wait.c  | 22 +++++-----------------
>   2 files changed, 12 insertions(+), 19 deletions(-)
> 
> diff --git a/kernel/sched/sched.h b/kernel/sched/sched.h
> index f7d0b64..b98084e 100644
> --- a/kernel/sched/sched.h
> +++ b/kernel/sched/sched.h
> @@ -2535,8 +2535,13 @@ static inline int task_on_rq_migrating(struct task_struct *p)
>   #define WF_EXEC			0x02 /* Wakeup after exec; maps to SD_BALANCE_EXEC */
>   #define WF_FORK			0x04 /* Wakeup after fork; maps to SD_BALANCE_FORK */
>   #define WF_TTWU			0x08 /* Wakeup;            maps to SD_BALANCE_WAKE */
> -
> -#define WF_SYNC			0x10 /* Waker goes to sleep after wakeup */
> +/*
> + * Hint that the caller expects the waker to sleep soon.
> + * Scheduler classes may use it for placement or preemption.
> + * Callers must not rely on it to prevent migration,
> + * preserve CPU locality or make the wakee run next.
> + */
> +#define WF_SYNC			0x10
>   #define WF_MIGRATED		0x20 /* Internal use, task got migrated */
>   #define WF_CURRENT_CPU		0x40 /* Prefer to move the wakee to the current CPU. */
>   #define WF_RQ_SELECTED		0x80 /* ->select_task_rq() was called */
> diff --git a/kernel/sched/wait.c b/kernel/sched/wait.c
> index d033f60..477e4bf 100644
> --- a/kernel/sched/wait.c
> +++ b/kernel/sched/wait.c
> @@ -174,15 +174,11 @@ 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.
> + * Passes WF_SYNC to waitqueue wake functions. The default wake function
> + * forwards it to the scheduler; see WF_SYNC for the hint's semantics.
>    *
> - * On UP it can prevent extra 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 +196,7 @@ 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.
> - *
> - * On UP it can prevent extra preemption.
> - *
> - * If this function wakes up a task, it executes a full memory barrier before
> - * accessing the task state.
> + * Same as __wake_up_sync_key(), but called with @wq_head->lock held.
>    */
>   void __wake_up_locked_sync_key(struct wait_queue_head *wq_head,
>   			       unsigned int mode, void *key)

Re: [tip: sched/core] sched: Clarify WF_SYNC wakeup semantics

[Ingo Molnar]

* tip-bot2 for Shubhang Kaushik (Ampere) <tip-bot2@linutronix.de> wrote:

> The following commit has been merged into the sched/core branch of tip:
> 
> Commit-ID:     e4c353c3933968fe8efecb269fdbe3baa1d1ddd0
> Gitweb:        https://git.kernel.org/tip/e4c353c3933968fe8efecb269fdbe3baa1d1ddd0
> Author:        Shubhang Kaushik (Ampere) <sh@gentwo.org>
> AuthorDate:    Tue, 22 Sep 2026 14:57:05 -07:00
> Committer:     Peter Zijlstra <peterz@infradead.org>
> CommitterDate: Fri, 25 Sep 2026 12:45:59 +02:00
> 
> sched: Clarify WF_SYNC wakeup semantics
> 
> The synchronous waitqueue wakeup comments currently state that a
> synchronous wakee will not be migrated to another CPU. This is not
> guaranteed by the scheduler wakeup path.
> 
> WF_SYNC is an advisory hint that the caller expects the waker to
> schedule away soon. Scheduler classes may use it for placement or
> preemption, but callers must not rely on it to prevent migration,
> preserve CPU locality, or make the wakee run next.
> 
> Keep this contract next to the flag definition, remove the stale
> waitqueue wording, and make the locked helper refer to the unlocked
> variant.
> 
> Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
> Link: https://patch.msgid.link/20260922-sched-wf-sync-doc-v3-1-23ebe9e27bef@gentwo.org

JFYI, I've added Shubhang's SOB which is missing from the commit:

    Signed-off-by: Shubhang Kaushik (Ampere) <sh@gentwo.org>

Which I suppose got lost in some patch application mishap,
because it's present in the original.

Thanks,

	Ingo

[tip: sched/core] sched/wait: Clarify WF_SYNC wakeup semantics

[tip-bot2 for Shubhang Kaushik (Ampere)]

The following commit has been merged into the sched/core branch of tip:

Commit-ID:     627ea30aca3b309af40cdd07a35eb1027ba4a0bc
Gitweb:        https://git.kernel.org/tip/627ea30aca3b309af40cdd07a35eb1027ba4a0bc
Author:        Shubhang Kaushik (Ampere) <sh@gentwo.org>
AuthorDate:    Tue, 22 Sep 2026 14:57:05 -07:00
Committer:     Ingo Molnar <mingo@kernel.org>
CommitterDate: Fri, 25 Sep 2026 20:32:31 +02:00

sched/wait: Clarify WF_SYNC wakeup semantics

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

WF_SYNC is an advisory hint that the caller expects the waker to
schedule away soon. Scheduler classes may use it for placement or
preemption, but callers must not rely on it to prevent migration,
preserve CPU locality, or make the wakee run next.

Keep this contract next to the flag definition, remove the stale
waitqueue wording, and make the locked helper refer to the unlocked
variant.

Signed-off-by: Shubhang Kaushik (Ampere) <sh@gentwo.org>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Link: https://patch.msgid.link/20260922-sched-wf-sync-doc-v3-1-23ebe9e27bef@gentwo.org
---
 kernel/sched/sched.h |  9 +++++++--
 kernel/sched/wait.c  | 22 +++++-----------------
 2 files changed, 12 insertions(+), 19 deletions(-)

diff --git a/kernel/sched/sched.h b/kernel/sched/sched.h
index f7d0b64..b98084e 100644
--- a/kernel/sched/sched.h
+++ b/kernel/sched/sched.h
@@ -2535,8 +2535,13 @@ static inline int task_on_rq_migrating(struct task_struct *p)
 #define WF_EXEC			0x02 /* Wakeup after exec; maps to SD_BALANCE_EXEC */
 #define WF_FORK			0x04 /* Wakeup after fork; maps to SD_BALANCE_FORK */
 #define WF_TTWU			0x08 /* Wakeup;            maps to SD_BALANCE_WAKE */
-
-#define WF_SYNC			0x10 /* Waker goes to sleep after wakeup */
+/*
+ * Hint that the caller expects the waker to sleep soon.
+ * Scheduler classes may use it for placement or preemption.
+ * Callers must not rely on it to prevent migration,
+ * preserve CPU locality or make the wakee run next.
+ */
+#define WF_SYNC			0x10
 #define WF_MIGRATED		0x20 /* Internal use, task got migrated */
 #define WF_CURRENT_CPU		0x40 /* Prefer to move the wakee to the current CPU. */
 #define WF_RQ_SELECTED		0x80 /* ->select_task_rq() was called */
diff --git a/kernel/sched/wait.c b/kernel/sched/wait.c
index d033f60..477e4bf 100644
--- a/kernel/sched/wait.c
+++ b/kernel/sched/wait.c
@@ -174,15 +174,11 @@ 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.
+ * Passes WF_SYNC to waitqueue wake functions. The default wake function
+ * forwards it to the scheduler; see WF_SYNC for the hint's semantics.
  *
- * On UP it can prevent extra 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 +196,7 @@ 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.
- *
- * On UP it can prevent extra preemption.
- *
- * If this function wakes up a task, it executes a full memory barrier before
- * accessing the task state.
+ * Same as __wake_up_sync_key(), but called with @wq_head->lock held.
  */
 void __wake_up_locked_sync_key(struct wait_queue_head *wq_head,
 			       unsigned int mode, void *key)