From: Yury Norov <ynorov@nvidia.com>
To: Peter Zijlstra <peterz@infradead.org>,
Ingo Molnar <mingo@redhat.com>, Thomas Gleixner <tglx@kernel.org>,
Juri Lelli <juri.lelli@redhat.com>,
Vincent Guittot <vincent.guittot@linaro.org>,
Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>,
Wei Wang <wvw@google.com>,
Shrikanth Hegde <sshegde@linux.ibm.com>
Cc: Yury Norov <ynorov@nvidia.com>, Yury Norov <yury.norov@gmail.com>,
"Rafael J. Wysocki" <rafael@kernel.org>,
Alexander Gordeev <agordeev@linux.ibm.com>,
Andrea Righi <arighi@nvidia.com>, Ben Segall <bsegall@google.com>,
Christian Borntraeger <borntraeger@linux.ibm.com>,
Daniel Lezcano <daniel.lezcano@kernel.org>,
Danilo Krummrich <dakr@kernel.org>,
Dietmar Eggemann <dietmar.eggemann@arm.com>,
Fushuai Wang <fushuai.wang@linux.dev>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
Heiko Carstens <hca@linux.ibm.com>,
Ilya Leoshkevich <iii@linux.ibm.com>,
Johan Hovold <johan@kernel.org>, Jonathan Corbet <corbet@lwn.net>,
K Prateek Nayak <kprateek.nayak@amd.com>,
Lukasz Luba <lukasz.luba@arm.com>,
Maxim Kuvyrkov <maxim.kuvyrkov@grdncc.com>,
Mel Gorman <mgorman@suse.de>, Mete Durlu <meted@linux.ibm.com>,
Randy Dunlap <rdunlap@infradead.org>,
Rasmus Villemoes <linux@rasmusvillemoes.dk>,
Shuah Khan <skhan@linuxfoundation.org>,
Steven Rostedt <rostedt@goodmis.org>,
Sven Schnelle <svens@linux.ibm.com>,
Valentin Schneider <vschneid@redhat.com>,
Vasily Gorbik <gor@linux.ibm.com>,
linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org,
driver-core@lists.linux.dev, linux-pm@vger.kernel.org
Subject: [PATCH RFC 1/3] cpu: add sysfs control for preferred CPUS
Date: Mon, 16 Nov 2026 21:25:39 -0500 [thread overview]
Message-ID: <20261117022542.863028-2-ynorov@nvidia.com> (raw)
In-Reply-To: <20261117022542.863028-1-ynorov@nvidia.com>
Preferred cpumask is a powerful instrument to hint the fair scheduler
on tasks placement under certain conditions like vCPU overcommitment.
It may be even more powerful if the final decision on which vCPUs are
preferred is delegated to userspace.
Considering two VMs running training and inference AI workloads, the
inference is more latency critical. In case of contention, the
inference VM should keep more preferred vCPUs for better UX.
The in-kernel steal governor is the reasonable default approach that
works good for cooperative VMs running similar workloads. In case of
non-symmetrical VMs, optimal vCPUs throttling may require sharing more
information between VMs, or at least knowing their role. This may be
naturally addressed on userspace level.
Preferred cpumask has no write interface other than via a loadable
module. Modules are disabled under certain configurations or can't be
loaded due to system policies; or impractical if the preferred CPU
state is supposed to be controlled by an existing user level software.
Add the write access via sysfs interface, similar to CPU hotplug. The
write is not available if the preferred cpumask is claimed by a kernel
module. Kernel ownership does not prevent reads.
Sysfs interface shares the kernel modules limitations: making non-active
CPUs preferred and making all active CPUs non-preferred is not allowed.
Write access to the preferred cpumask may also be useful for the system
debugging, benchmarking or CPU isolation without changing tasks affinity.
Signed-off-by: Yury Norov <ynorov@nvidia.com>
---
.../ABI/testing/sysfs-devices-system-cpu | 3 +-
.../sysfs-devices-system-cpu-preferred | 42 ++++++++++
Documentation/scheduler/sched-paravirt.rst | 20 ++++-
drivers/base/cpu.c | 76 +++++++++++++++++++
kernel/Kconfig.preempt | 16 +++-
5 files changed, 151 insertions(+), 6 deletions(-)
create mode 100644 Documentation/ABI/testing/sysfs-devices-system-cpu-preferred
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 545687ebadcc..3bf89c7c4b91 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -829,4 +829,5 @@ Description:
CPUs outside of this list may lead to performance
degradations due to underlying physical CPU contention.
- See Documentation/scheduler/sched-paravirt.rst for more details.
+ See Documentation/ABI/testing/sysfs-devices-system-cpu-preferred
+ and Documentation/scheduler/sched-paravirt.rst for more details.
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu-preferred b/Documentation/ABI/testing/sysfs-devices-system-cpu-preferred
new file mode 100644
index 000000000000..a0e9680e1c34
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu-preferred
@@ -0,0 +1,42 @@
+What: /sys/devices/system/cpu/cpu[0-9]*/preferred
+Date: October 2026
+Contact: Yury Norov <yury.norov@gmail.com>
+Description:
+ Control whether a CPU is preferred for fair tasks placement.
+ Reads 1 if this CPU is preferred, 0 otherwise. Fair tasks
+ whose allowed CPUs contain no preferred CPU can still run on
+ active non-preferred CPUs. Other scheduling classes are
+ unaffected.
+
+ As for the online attribute, boolean spellings such as 1/0, y/n
+ or on/off are accepted to set the preferred status of the CPU.
+
+ Writes change a system-wide fair tasks placement preference
+ without changing task affinities, cpuset settings or CPU
+ online state. Cpuset constraints continue to bound task
+ placement. Use cpusets to constrain a workload's eligible CPUs
+ or create exclusive CPU partitions.
+
+ This attribute does not reserve CPUs or configure tick
+ suppression, RCU offloading or interrupt affinity.
+
+ Selecting an inactive CPU, deselecting the last preferred CPU,
+ or writing an invalid boolean fails with EINVAL without changing
+ the mask. Writing the current value is a no-op. Writes across
+ all CPUs are serialized. To replace a selection, select new CPUs
+ before deselecting the old ones.
+
+ Reads and writes may fail with EAGAIN if CPU hotplug is in
+ progress. Retry the operation in that case.
+
+ The list of preferred CPUs can be found in:
+
+ /sys/devices/system/cpu/preferred.
+
+ CPU hotplug sets the status of new active CPU as preferred, and
+ deactivated CPUs become non-preferred. Offlining the last
+ preferred CPU resets the status such that all remaining active
+ CPUs become preferred; and emits a notice in the kernel log.
+
+ Writes fail with EBUSY if the preferred cpumask is claimed by a
+ kernel module. Reads remain available while the mask is claimed.
diff --git a/Documentation/scheduler/sched-paravirt.rst b/Documentation/scheduler/sched-paravirt.rst
index d8f446c3ab6e..4cea2bf7c4f4 100644
--- a/Documentation/scheduler/sched-paravirt.rst
+++ b/Documentation/scheduler/sched-paravirt.rst
@@ -42,13 +42,25 @@ This is achieved by:
``/sys/devices/system/cpu/preferred`` prints the current ``cpu_preferred_mask``
in cpulist format.
+Userspace governors may control preferred cpumask through the sysfs
+interface similar to CPU hotplug::
+
+ echo 0 > /sys/devices/system/cpu/cpu1/preferred
+ echo 1 > /sys/devices/system/cpu/cpu1/preferred
+
+If ``cpu_preferred_mask`` is claimed by a kernel module, an attempt to
+write would return EBUSY. Disabling the last preferred CPU or enabling
+non-active CPU in the preferred mask is not allowed, and EINVAL would
+be returned.
+
Notes:
1. This feature is available under ``CONFIG_PREFERRED_CPU``. Driver which
makes decisions should enable it. For example, steal_governor driver
(``CONFIG_STEAL_GOVERNOR``). On enabling the driver, CPU preferred state
- can change based on steal time. Without the driver, preferred CPUs is
- same as active CPUs. Only one governor may be enabled at a time.
+ can change based on steal time. Preferred CPUs mirror active cpumask unless
+ modified by governor or via sysfs. Only one governor may be enabled at a
+ time.
2. This feature works for the FAIR class only.
@@ -56,8 +68,8 @@ Notes:
to run based on its affinity. But no load balancing happens if it is affined
only on non-preferred CPUs.
-4. Decision to change the preferred CPU state is driven by the kernel.
- Hence it shouldn't break user affinities. One of the main reasons why
+4. Decision to change the preferred CPU state is driven by the governor
+ and does not break user affinities. One of the main reasons why
CPU hotplug or Isolated cpuset partitions was not a solution.
5. This feature works best only when all the Guest VMs enable the feature as
diff --git a/drivers/base/cpu.c b/drivers/base/cpu.c
index 747915ff974f..88e803cdcc36 100644
--- a/drivers/base/cpu.c
+++ b/drivers/base/cpu.c
@@ -5,6 +5,7 @@
#include <linux/kernel.h>
#include <linux/module.h>
+#include <linux/mutex.h>
#include <linux/init.h>
#include <linux/sched.h>
#include <linux/cpu.h>
@@ -145,6 +146,75 @@ static DEVICE_ATTR(release, S_IWUSR, NULL, cpu_release_store);
#endif /* CONFIG_ARCH_CPU_PROBE_RELEASE */
#endif /* CONFIG_HOTPLUG_CPU */
+#ifdef CONFIG_PREFERRED_CPU
+static ssize_t preferred_cpu_show(struct device *dev,
+ struct device_attribute *attr, char *buf)
+{
+ ssize_t ret;
+
+ /* CPU removal drains active sysfs callbacks with cpus_write_lock held. */
+ if (!cpus_read_trylock())
+ return -EAGAIN;
+
+ mutex_lock(&cpu_preferred_mutex);
+ ret = sysfs_emit(buf, "%u\n", cpu_preferred(dev->id));
+ mutex_unlock(&cpu_preferred_mutex);
+
+ cpus_read_unlock();
+ return ret;
+}
+
+static ssize_t preferred_cpu_store(struct device *dev,
+ struct device_attribute *attr,
+ const char *buf, size_t count)
+{
+ unsigned int cpu = dev->id;
+ bool preferred;
+ int ret;
+
+ ret = kstrtobool(buf, &preferred);
+ if (ret)
+ return ret;
+
+ /* CPU removal drains active sysfs callbacks with cpus_write_lock held. */
+ if (!cpus_read_trylock())
+ return -EAGAIN;
+
+ mutex_lock(&cpu_preferred_mutex);
+
+ ret = -EBUSY;
+ if (!preferred_cpumask_owned_by(NULL))
+ goto out;
+
+ ret = -EINVAL;
+ if (preferred && !cpu_active(cpu))
+ goto out;
+
+ if (!preferred && cpu_preferred(cpu) &&
+ cpumask_weight(cpu_preferred_mask) == 1)
+ goto out;
+
+ set_cpu_preferred(cpu, preferred);
+ ret = count;
+out:
+ mutex_unlock(&cpu_preferred_mutex);
+ cpus_read_unlock();
+ return ret;
+}
+
+static struct device_attribute dev_attr_cpu_preferred =
+ __DEVICE_ATTR(preferred, 0644, preferred_cpu_show, preferred_cpu_store);
+
+static struct attribute *preferred_cpu_attrs[] = {
+ &dev_attr_cpu_preferred.attr,
+ NULL
+};
+
+static const struct attribute_group preferred_cpu_attr_group = {
+ .attrs = preferred_cpu_attrs,
+};
+#endif /* CONFIG_PREFERRED_CPU */
+
#ifdef CONFIG_CRASH_DUMP
#include <linux/kexec.h>
@@ -190,6 +260,9 @@ static const struct attribute_group crash_note_cpu_attr_group = {
#endif
static const struct attribute_group *common_cpu_attr_groups[] = {
+#ifdef CONFIG_PREFERRED_CPU
+ &preferred_cpu_attr_group,
+#endif
#ifdef CONFIG_CRASH_DUMP
&crash_note_cpu_attr_group,
#endif
@@ -197,6 +270,9 @@ static const struct attribute_group *common_cpu_attr_groups[] = {
};
static const struct attribute_group *hotplugable_cpu_attr_groups[] = {
+#ifdef CONFIG_PREFERRED_CPU
+ &preferred_cpu_attr_group,
+#endif
#ifdef CONFIG_CRASH_DUMP
&crash_note_cpu_attr_group,
#endif
diff --git a/kernel/Kconfig.preempt b/kernel/Kconfig.preempt
index ffd2cb2a4d69..0cbc697202dd 100644
--- a/kernel/Kconfig.preempt
+++ b/kernel/Kconfig.preempt
@@ -196,5 +196,19 @@ config SCHED_CLASS_EXT
https://github.com/sched-ext/scx
config PREFERRED_CPU
- bool
+ bool "Preferred CPU scheduling"
depends on SMP && HAVE_CPUTIME_STEAL
+ help
+ Hint the fair scheduler to favor a subset of active CPUs.
+ Non-preferred CPUs remain online and can still run tasks
+ if their affinity requires it.
+
+ Preferred CPUs can be selected through the per-CPU preferred
+ sysfs attribute or managed by a kernel module, like steal
+ governor, to reduce CPU contention in virtual machines.
+
+ See Documentation/scheduler/sched-paravirt.rst and
+ Documentation/ABI/testing/sysfs-devices-system-cpu-preferred
+ for details.
+
+ If unsure, say N.
--
2.53.0
next prev parent reply other threads:[~2026-11-17 2:25 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-17 2:25 [PATCH RFC 0/3] Expose writable interface for preferred CPUs Yury Norov
2026-11-17 2:25 ` Yury Norov [this message]
2026-11-17 2:25 ` [PATCH RFC 2/3] sched: decouple preferred CPU policies from steal-time accounting Yury Norov
2026-11-17 2:25 ` [PATCH RFC 3/3] docs: sched: describe thermal control with preferred CPUs Yury Norov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261117022542.863028-2-ynorov@nvidia.com \
--to=ynorov@nvidia.com \
--cc=agordeev@linux.ibm.com \
--cc=arighi@nvidia.com \
--cc=borntraeger@linux.ibm.com \
--cc=bsegall@google.com \
--cc=corbet@lwn.net \
--cc=dakr@kernel.org \
--cc=daniel.lezcano@kernel.org \
--cc=dietmar.eggemann@arm.com \
--cc=driver-core@lists.linux.dev \
--cc=fushuai.wang@linux.dev \
--cc=gor@linux.ibm.com \
--cc=gregkh@linuxfoundation.org \
--cc=hca@linux.ibm.com \
--cc=iii@linux.ibm.com \
--cc=johan@kernel.org \
--cc=juri.lelli@redhat.com \
--cc=kprateek.nayak@amd.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-pm@vger.kernel.org \
--cc=linux@rasmusvillemoes.dk \
--cc=lukasz.luba@arm.com \
--cc=maxim.kuvyrkov@grdncc.com \
--cc=meted@linux.ibm.com \
--cc=mgorman@suse.de \
--cc=mingo@redhat.com \
--cc=peterz@infradead.org \
--cc=rafael@kernel.org \
--cc=rdunlap@infradead.org \
--cc=rostedt@goodmis.org \
--cc=skhan@linuxfoundation.org \
--cc=srinivas.pandruvada@linux.intel.com \
--cc=sshegde@linux.ibm.com \
--cc=svens@linux.ibm.com \
--cc=tglx@kernel.org \
--cc=vincent.guittot@linaro.org \
--cc=vschneid@redhat.com \
--cc=wvw@google.com \
--cc=yury.norov@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox