From nobody Fri Sep 25 01:29:00 2026 Received: from gentwo.org (gentwo.org [62.72.0.81]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A27643CD8BF; Thu, 17 Sep 2026 23:46:53 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=62.72.0.81 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789688815; cv=none; b=jCuIEspMZPXqSJLvopcJHtg2oxbMvfU2aZmaxCCjbFCjqmC6po6XTfsjjh50QUK5OazPX7fZ9WK4W9xMEVYNGfmiGGznutah4qpEROcmkMjYTqFfVRI3tKNLjMsyP5KXgXgbFqwwI3I0YG8Q4GjSYBJPXdMrYa5GtNNVIOKb2Uc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789688815; c=relaxed/simple; bh=3Qtb2MNOmRwJ2Ei/olRj3LhnFV0DH/aL6UWUuaKYPFE=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=GgQQ0M++siLDoIN4LedwkCjC9GfQRIPDkU5w6t7n81ST3x4vKD2ge9aILibwUCZtsKmSij9AbpZuMoJO/8OiVbkjkgYUWOkSuJw14D91wOqADxM2hlr08ZQftioL0SeUUE/x47AlX0wiwDi1Aqm5/Hk5YZliN7/yqdkTrC3/vXU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=gentwo.org; spf=pass smtp.mailfrom=gentwo.org; dkim=pass (1024-bit key) header.d=gentwo.org header.i=@gentwo.org header.b=VhMFhwoD; arc=none smtp.client-ip=62.72.0.81 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=gentwo.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gentwo.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=gentwo.org header.i=@gentwo.org header.b="VhMFhwoD" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gentwo.org; s=default; t=1789677806; bh=3Qtb2MNOmRwJ2Ei/olRj3LhnFV0DH/aL6UWUuaKYPFE=; h=From:Date:Subject:References:In-Reply-To:To:Cc:From; b=VhMFhwoDiEarMVP9Imvr/F+4JOvqdPFPyznTfMnLST4xsBufJZU5l9YKz8AbF8C08 2/pPRBoagi+bqHE1203nT34s0dyIeFq82HdRTBPrgYP0YoSRACv8+4hrkLbuCXGo4U GuTF/tc9/dx3BJo20bYggMePhEYnwjGC43keGceM= Received: from sut02sys-r112.scc-lab.amperecomputing.com (localhost [127.0.0.1]) by gentwo.org (Postfix) with ESMTPS id 713994027F; Thu, 17 Sep 2026 13:43:26 -0700 (PDT) From: "Shubhang Kaushik (Ampere)" Date: Thu, 17 Sep 2026 13:43:24 -0700 Subject: [RFC PATCH v2 1/2] sched: Document WF_SYNC wakeup placement semantics Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260917-sched-wf-sync-doc-v2-1-6d1f107c0596@gentwo.org> References: <20260917-sched-wf-sync-doc-v2-0-6d1f107c0596@gentwo.org> In-Reply-To: <20260917-sched-wf-sync-doc-v2-0-6d1f107c0596@gentwo.org> To: Jonathan Corbet , Shuah Khan , Randy Dunlap , Ingo Molnar , Peter Zijlstra , Juri Lelli , Vincent Guittot , Dietmar Eggemann , Steven Rostedt , Ben Segall , Mel Gorman , Valentin Schneider , K Prateek Nayak , Shubhang Kaushik , Shrikanth Hegde , Madadi Vineeth Reddy , Christopher Lameter Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, "Shubhang Kaushik (Ampere)" X-Mailer: b4 0.14.2 X-Developer-Signature: v=1; a=ed25519-sha256; t=1789677805; l=4087; i=sh@gentwo.org; s=20251010; h=from:subject:message-id; bh=3Qtb2MNOmRwJ2Ei/olRj3LhnFV0DH/aL6UWUuaKYPFE=; b=UgVnqpJxzkzmRqWgP8WyOOVqveVi4jwB6BC/AnA6bSoftng0LDYdqEBED+eiJM+8zK4GfjQAf oXnpTvZfPhUDniQPWCJkXGCfqt28kTZj6eipsXUjBnos5TRQwO9uuWt X-Developer-Key: i=sh@gentwo.org; a=ed25519; pk=jc8YIRvxPSyJaBRe5y+a4N0RXKBUEcAh8+OFhlROXPY= 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) --- 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/in= dex.rst index 17ce8d76befc1bb1dc289e9243bdca98c9ccb172..ac95c79617fd2c03564ea4a9dad= 362091b9d1b86 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/Documentatio= n/scheduler/sched-wake-affinity.rst new file mode 100644 index 0000000000000000000000000000000000000000..dd82b739bb1191db57d4006a38e= 1ac86b614f042 --- /dev/null +++ b/Documentation/scheduler/sched-wake-affinity.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D +WF_SYNC Wakeup Semantics +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D + +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. --=20 2.52.0 From nobody Fri Sep 25 01:29:00 2026 Received: from gentwo.org (gentwo.org [62.72.0.81]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 08AA03B19A3; Thu, 17 Sep 2026 21:36:52 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=62.72.0.81 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789681014; cv=none; b=VKMt52TITcm/eZCtVSgjl2kS7QbFrbNKoGYkmTf4T1Ee3YkgK5a7jZ4kdo6G4a36qbo5r2YMhnKyvv0A3Wgw4C3CbOd2ZVI3L/PkiWJHv7JPZ2WjO4BT5fSoBg7VMtyzwsIUPsi1tcw6MGZy1NLzK7yMgYesuZU4TKnHHB6p0jE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789681014; c=relaxed/simple; bh=wNrHsjDKVfWS8zXNLUqwBHM5EXAhWqtMXDjFXL6wzKI=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=gBakDdxXRgt4IyzWPLtVeiZg5sT52ZfftuYRONnTllDqU4Afwfna1pBuvMWuW6L0HTsVCr5owVBERzLmCEjCSyQXdNQe0HzaMB2aFZbJA6W5bxVNw/osWNITdcL9gNfzF7Je8nwbLdprSetpwRx0TByTggOAV9dSZlcjUjBtKyc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=gentwo.org; spf=pass smtp.mailfrom=gentwo.org; dkim=pass (1024-bit key) header.d=gentwo.org header.i=@gentwo.org header.b=CM0SLvpk; arc=none smtp.client-ip=62.72.0.81 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=gentwo.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gentwo.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=gentwo.org header.i=@gentwo.org header.b="CM0SLvpk" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gentwo.org; s=default; t=1789677807; bh=wNrHsjDKVfWS8zXNLUqwBHM5EXAhWqtMXDjFXL6wzKI=; h=From:Date:Subject:References:In-Reply-To:To:Cc:From; b=CM0SLvpkmXSePx9Tojt0+WyfIF7ZNk4P7SVDVgG+C5iyjzUbinJuHNglKXaUdgW3t Z4FBepHBhVJbRLIlCiqY0lQAR/6UO9bgj0z9lZDm3dlURxauhX6+5fQoQi7fy0uhrE KOZaq/g2I9x5vXqRTPddzpyMCI/axpKZPBEe/C84= Received: from sut02sys-r112.scc-lab.amperecomputing.com (localhost [127.0.0.1]) by gentwo.org (Postfix) with ESMTPS id 0E00640834; Thu, 17 Sep 2026 13:43:27 -0700 (PDT) From: "Shubhang Kaushik (Ampere)" Date: Thu, 17 Sep 2026 13:43:25 -0700 Subject: [RFC PATCH v2 2/2] sched/wait: Clarify WF_SYNC wakeup semantics Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260917-sched-wf-sync-doc-v2-2-6d1f107c0596@gentwo.org> References: <20260917-sched-wf-sync-doc-v2-0-6d1f107c0596@gentwo.org> In-Reply-To: <20260917-sched-wf-sync-doc-v2-0-6d1f107c0596@gentwo.org> To: Jonathan Corbet , Shuah Khan , Randy Dunlap , Ingo Molnar , Peter Zijlstra , Juri Lelli , Vincent Guittot , Dietmar Eggemann , Steven Rostedt , Ben Segall , Mel Gorman , Valentin Schneider , K Prateek Nayak , Shubhang Kaushik , Shrikanth Hegde , Madadi Vineeth Reddy , Christopher Lameter Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, "Shubhang Kaushik (Ampere)" X-Mailer: b4 0.14.2 X-Developer-Signature: v=1; a=ed25519-sha256; t=1789677805; l=3313; i=sh@gentwo.org; s=20251010; h=from:subject:message-id; bh=wNrHsjDKVfWS8zXNLUqwBHM5EXAhWqtMXDjFXL6wzKI=; b=oT5B6U5CH9K2QzLrVe1eoPzmq4znP02JcICOLXbXwCGvHXqBnrWUJuXG6M1L2UWNz0o9ceWWA ZPW+KXrVXhjBbLc+WmgmoNFBZQ86VkmghYaebIEklDWV40C5VM3o6RC X-Developer-Key: i=sh@gentwo.org; a=ed25519; pk=jc8YIRvxPSyJaBRe5y+a4N0RXKBUEcAh8+OFhlROXPY= 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) --- 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..ac1d260a6a37fc35b9340797068= 19b79e20df4ba 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 bef= ore - * 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 bef= ore - * 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) --=20 2.52.0