[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@xxxxxxxxxx>
---
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@xxxxxxxxxx

---
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@xxxxxxxxxx>