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

[Shrikanth Hegde <sshegde@linux.ibm.com>]

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>