[RFC PATCH v2 0/2] sched: Document WF_SYNC wakeup placement semantics

[RFC PATCH v2 0/2] sched: Document WF_SYNC wakeup placement semantics

[Shubhang Kaushik (Ampere)]

WF_SYNC is passed by synchronous waitqueue wakeup helpers when the
caller expects the waker to schedule away soon. Its fair class semantics
are not documented.

In particular, the waitqueue API comments state that a synchronous wakee
will not be migrated to another CPU. This is not guaranteed by the
current wakeup path.

Document the current fair class WF_SYNC semantics and correct the stale
waitqueue API comments. WF_SYNC is a non-binding hint that can influence
placement and preemption, but does not guarantee CPU locality, avoidance
of migration, or immediate wakee preemption.

This series does not change scheduler behavior or define a stronger
WF_SYNC placement policy.

Signed-off-by: Shubhang Kaushik (Ampere) <sh@gentwo.org>
---
Changes in v2:
  - Describe stable WF_SYNC semantics rather than scheduler implementation flow.
  - Remove helper names, predicates, and CPU-selection details.
  - Clarify custom wake function handling and WF_SYNC placement and
    preemption limitations.

Link to v1: https://lore.kernel.org/r/20260825-sched-wf-sync-doc-v1-0-f899edb44ff5@gentwo.org

---
Shubhang Kaushik (Ampere) (2):
      sched: Document WF_SYNC wakeup placement semantics
      sched/wait: Clarify WF_SYNC wakeup semantics

 Documentation/scheduler/index.rst               |  1 +
 Documentation/scheduler/sched-wake-affinity.rst | 67 +++++++++++++++++++++++++
 kernel/sched/wait.c                             | 30 +++++------
 3 files changed, 84 insertions(+), 14 deletions(-)
---
base-commit: b5a051f6b840d48f159166ef073d3021989bfb50
change-id: 20260824-sched-wf-sync-doc-e92b4fe987f7

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

[RFC PATCH v2 1/2] sched: Document WF_SYNC wakeup placement semantics

[Shubhang Kaushik (Ampere)]

WF_SYNC is supplied by callers that expect the waker to schedule away
soon. The fair scheduler can use it as a placement and preemption hint,
but its semantics are not documented.

Document the stable fair-class WF_SYNC semantics. WF_SYNC is advisory:
it can influence placement and preemption, but does not guarantee CPU
locality, avoidance of migration, or immediate wakee preemption.

This documents existing behavior only. It does not establish a new
WF_SYNC placement policy.

Signed-off-by: Shubhang Kaushik (Ampere) <sh@gentwo.org>
---
 Documentation/scheduler/index.rst               |  1 +
 Documentation/scheduler/sched-wake-affinity.rst | 67 +++++++++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
index 17ce8d76befc1bb1dc289e9243bdca98c9ccb172..ac95c79617fd2c03564ea4a9dad362091b9d1b86 100644
--- a/Documentation/scheduler/index.rst
+++ b/Documentation/scheduler/index.rst
@@ -14,6 +14,7 @@ Scheduler
     sched-design-CFS
     sched-eevdf
     sched-domains
+    sched-wake-affinity
     sched-capacity
     sched-energy
     schedutil
diff --git a/Documentation/scheduler/sched-wake-affinity.rst b/Documentation/scheduler/sched-wake-affinity.rst
new file mode 100644
index 0000000000000000000000000000000000000000..dd82b739bb1191db57d4006a38e1ac86b614f042
--- /dev/null
+++ b/Documentation/scheduler/sched-wake-affinity.rst
@@ -0,0 +1,67 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================
+WF_SYNC Wakeup Semantics
+=========================
+
+WF_SYNC is a wakeup flag supplied by callers that expect the waking task
+to schedule away soon after waking another task. It is a scheduler hint,
+not a CPU-placement request.
+
+The synchronous waitqueue helpers pass WF_SYNC to their wake functions.
+The default wake function forwards it to the scheduler. WF_SYNC itself
+does not block, yield, or otherwise change the state of the waker.
+
+This document describes the current WF_SYNC semantics for the fair
+scheduler. Other scheduler classes may ignore WF_SYNC or apply their own
+policy.
+
+Custom waitqueue wake functions may ignore WF_SYNC. The following
+describes fair-scheduler behavior when a wake function forwards the flag
+to the scheduler.
+
+Placement
+=========
+
+For fair-class tasks, WF_SYNC can influence CPU selection for a wakee.
+It expresses that placing the wakee so that it can run after the waker
+schedules away may be beneficial.
+
+WF_SYNC is advisory. CPU selection remains subject to the wakee's
+affinity and migration constraints, as well as the scheduler's other
+placement policy. The scheduler can therefore select an eligible CPU
+other than the waker's CPU or the wakee's previous CPU.
+
+In particular, WF_SYNC does not guarantee that the wakee:
+
+* runs on the waker CPU;
+* remains on its previous CPU;
+* avoids migration; or
+* shares a core with the waker.
+
+Preemption
+==========
+
+For fair-class tasks, WF_SYNC can also influence wakeup preemption. It
+does not guarantee either immediate preemption or non-preemption. The
+scheduler can preempt the current task immediately or defer the wakee's
+execution according to fair scheduling policy.
+
+The scheduler does not verify that the waker subsequently schedules
+away. A caller can continue to execute after a WF_SYNC wakeup or issue
+several WF_SYNC wakeups before scheduling away. WF_SYNC consequently
+does not imply that the wakee will run immediately after the wakeup.
+
+On uniprocessor systems, WF_SYNC may avoid a preemption when the waker
+is expected to schedule away soon.
+
+Policy
+======
+
+WF_SYNC is a non-binding hint. It describes the caller's expectation,
+but does not establish a placement or execution-order guarantee for the
+wakee.
+
+The hint leaves placement and preemption decisions to the scheduler.
+Any future policy that strengthens WF_SYNC semantics must define its
+placement and preemption guarantees explicitly.

-- 
2.52.0

[RFC PATCH v2 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@gentwo.org>
---
 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

Re: [RFC PATCH v2 1/2] sched: Document WF_SYNC wakeup placement semantics

[Peter Zijlstra]

On Thu, Sep 17, 2026 at 01:43:24PM -0700, Shubhang Kaushik (Ampere) wrote:
> WF_SYNC is supplied by callers that expect the waker to schedule away
> soon. The fair scheduler can use it as a placement and preemption hint,
> but its semantics are not documented.
> 
> Document the stable fair-class WF_SYNC semantics. WF_SYNC is advisory:
> it can influence placement and preemption, but does not guarantee CPU
> locality, avoidance of migration, or immediate wakee preemption.
> 
> This documents existing behavior only. It does not establish a new
> WF_SYNC placement policy.
> 
> Signed-off-by: Shubhang Kaushik (Ampere) <sh@gentwo.org>

*groan*, why not just a comment that goes with WF_SYNC? All this
documentation stuff is a dumping ground for bitrot.

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

[Peter Zijlstra]

On Thu, Sep 17, 2026 at 01:43:25PM -0700, Shubhang Kaushik (Ampere) wrote:
> 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@gentwo.org>
> ---
>  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)

Does it make sense to have one of those function refer to the other and
de-duplicate all that? Also, how relevant is the UP comment? I don't
think anybody much still cares about UP.

Re: [RFC PATCH v2 1/2] sched: Document WF_SYNC wakeup placement semantics

[Shrikanth Hegde]

Hi Peter,

On 9/18/26 5:03 PM, Peter Zijlstra wrote:
> On Thu, Sep 17, 2026 at 01:43:24PM -0700, Shubhang Kaushik (Ampere) wrote:
>> WF_SYNC is supplied by callers that expect the waker to schedule away
>> soon. The fair scheduler can use it as a placement and preemption hint,
>> but its semantics are not documented.
>>
>> Document the stable fair-class WF_SYNC semantics. WF_SYNC is advisory:
>> it can influence placement and preemption, but does not guarantee CPU
>> locality, avoidance of migration, or immediate wakee preemption.
>>
>> This documents existing behavior only. It does not establish a new
>> WF_SYNC placement policy.
>>
>> Signed-off-by: Shubhang Kaushik (Ampere) <sh@gentwo.org>
> 
> *groan*, why not just a comment that goes with WF_SYNC? All this
> documentation stuff is a dumping ground for bitrot.

I suggested to document this since there were atleast 4 proposals around
modifications of WF_SYNC and it was very confusing.

Did you get a chance to look at below abuse of the sync api?
https://lore.kernel.org/all/20260714013940.4068189-4-srikar@linux.ibm.com/

For that reason, I think either document/comment around what's the expectation
will help. Either scheduler need to account of all usecases of even when users of
SYNC misbehave or such callsites must be fixed and SYNC behavior can be kept minimum.