Linux Documentation
 help / color / mirror / Atom feed
* [PATCH RFC 0/3] Expose writable interface for preferred CPUs
@ 2026-11-17  2:25 Yury Norov
  2026-11-17  2:25 ` [PATCH RFC 1/3] cpu: add sysfs control for preferred CPUS Yury Norov
                   ` (2 more replies)
  0 siblings, 3 replies; 4+ messages in thread
From: Yury Norov @ 2026-11-17  2:25 UTC (permalink / raw)
  To: Peter Zijlstra, Ingo Molnar, Thomas Gleixner, Juri Lelli,
	Vincent Guittot, Srinivas Pandruvada, Wei Wang, Shrikanth Hegde
  Cc: Yury Norov, Yury Norov, Rafael J. Wysocki, Alexander Gordeev,
	Andrea Righi, Ben Segall, Christian Borntraeger, Daniel Lezcano,
	Danilo Krummrich, Dietmar Eggemann, Fushuai Wang,
	Greg Kroah-Hartman, Heiko Carstens, Ilya Leoshkevich,
	Johan Hovold, Jonathan Corbet, K Prateek Nayak, Lukasz Luba,
	Maxim Kuvyrkov, Mel Gorman, Mete Durlu, Randy Dunlap,
	Rasmus Villemoes, Shuah Khan, Steven Rostedt, Sven Schnelle,
	Valentin Schneider, Vasily Gorbik, linux-kernel, linux-doc,
	driver-core, linux-pm

On top of tip sched/core + [1].

The preferred CPU mask currently lets the steal governor reduce vCPU
demand when physical CPUs are contended.

This series adds a writable sysfs interface, allowing userspace governors
such as thermald to encourage CPU idling in response to external pressure.

Patches #1 and #2 are partial resends of [2]. Patch #3 adds a thermald
example.

The complete series is available at [3].

[1] https://lore.kernel.org/all/20261113184257.621707-1-ynorov@nvidia.com/
[2] https://lore.kernel.org/all/20261101192203.6979-1-ynorov@nvidia.com/
[3] https://github.com/norov/linux/tree/sysfs-preferred-cpumask

Request feedback on preferred CPUs as a thermal-control mechanism and its
relationship to existing cooling methods.

Yury Norov (3):
  cpu: add sysfs control for preferred CPUS
  sched: decouple preferred CPU policies from steal-time accounting
  docs: sched: describe thermal control with preferred CPUs

 .../ABI/testing/sysfs-devices-system-cpu      | 14 ++-
 .../sysfs-devices-system-cpu-preferred        | 42 +++++++++
 Documentation/scheduler/index.rst             |  1 +
 .../scheduler/preferred-cpu-thermal.rst       | 94 +++++++++++++++++++
 Documentation/scheduler/sched-paravirt.rst    | 20 +++-
 drivers/base/cpu.c                            | 76 +++++++++++++++
 kernel/Kconfig.preempt                        | 18 +++-
 7 files changed, 251 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-devices-system-cpu-preferred
 create mode 100644 Documentation/scheduler/preferred-cpu-thermal.rst

-- 
2.53.0


^ permalink raw reply	[flat|nested] 4+ messages in thread

* [PATCH RFC 1/3] cpu: add sysfs control for preferred CPUS
  2026-11-17  2:25 [PATCH RFC 0/3] Expose writable interface for preferred CPUs Yury Norov
@ 2026-11-17  2:25 ` Yury Norov
  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
  2 siblings, 0 replies; 4+ messages in thread
From: Yury Norov @ 2026-11-17  2:25 UTC (permalink / raw)
  To: Peter Zijlstra, Ingo Molnar, Thomas Gleixner, Juri Lelli,
	Vincent Guittot, Srinivas Pandruvada, Wei Wang, Shrikanth Hegde
  Cc: Yury Norov, Yury Norov, Rafael J. Wysocki, Alexander Gordeev,
	Andrea Righi, Ben Segall, Christian Borntraeger, Daniel Lezcano,
	Danilo Krummrich, Dietmar Eggemann, Fushuai Wang,
	Greg Kroah-Hartman, Heiko Carstens, Ilya Leoshkevich,
	Johan Hovold, Jonathan Corbet, K Prateek Nayak, Lukasz Luba,
	Maxim Kuvyrkov, Mel Gorman, Mete Durlu, Randy Dunlap,
	Rasmus Villemoes, Shuah Khan, Steven Rostedt, Sven Schnelle,
	Valentin Schneider, Vasily Gorbik, linux-kernel, linux-doc,
	driver-core, linux-pm

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


^ permalink raw reply related	[flat|nested] 4+ messages in thread

* [PATCH RFC 2/3] sched: decouple preferred CPU policies from steal-time accounting
  2026-11-17  2:25 [PATCH RFC 0/3] Expose writable interface for preferred CPUs Yury Norov
  2026-11-17  2:25 ` [PATCH RFC 1/3] cpu: add sysfs control for preferred CPUS Yury Norov
@ 2026-11-17  2:25 ` Yury Norov
  2026-11-17  2:25 ` [PATCH RFC 3/3] docs: sched: describe thermal control with preferred CPUs Yury Norov
  2 siblings, 0 replies; 4+ messages in thread
From: Yury Norov @ 2026-11-17  2:25 UTC (permalink / raw)
  To: Peter Zijlstra, Ingo Molnar, Thomas Gleixner, Juri Lelli,
	Vincent Guittot, Srinivas Pandruvada, Wei Wang, Shrikanth Hegde
  Cc: Yury Norov, Yury Norov, Rafael J. Wysocki, Alexander Gordeev,
	Andrea Righi, Ben Segall, Christian Borntraeger, Daniel Lezcano,
	Danilo Krummrich, Dietmar Eggemann, Fushuai Wang,
	Greg Kroah-Hartman, Heiko Carstens, Ilya Leoshkevich,
	Johan Hovold, Jonathan Corbet, K Prateek Nayak, Lukasz Luba,
	Maxim Kuvyrkov, Mel Gorman, Mete Durlu, Randy Dunlap,
	Rasmus Villemoes, Shuah Khan, Steven Rostedt, Sven Schnelle,
	Valentin Schneider, Vasily Gorbik, linux-kernel, linux-doc,
	driver-core, linux-pm

Scheduling on preferred subset of active CPUs is useful beyond the
paravirtualization scope.

For example, thermald can trim preferred list of CPUs as temperature
rises and restore them on cooling, allowing fair tasks to concentrate
on fewer CPUs without changing their affinity or taking CPUs offline.

Signed-off-by: Yury Norov <ynorov@nvidia.com>
---
 Documentation/ABI/testing/sysfs-devices-system-cpu | 11 ++++-------
 kernel/Kconfig.preempt                             |  2 +-
 2 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 3bf89c7c4b91..828c5173c3b4 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -821,13 +821,10 @@ What:		/sys/devices/system/cpu/preferred
 Date:		Sep 2026
 Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
 Description:
-		(RO) the list of preferred CPUs applicable in
-		paravirtualized environments.
-
-		The steal governor driver dynamically adjusts this mask
-		based on observed steal time. Scheduling tasks on
-		CPUs outside of this list may lead to performance
-		degradations due to underlying physical CPU contention.
+		(RO) the list of CPUs preferred for fair tasks placement.
+		Fair tasks whose allowed CPUs contain no preferred CPU can
+		still run on active non-preferred CPUs. Other scheduling
+		classes are unaffected.
 
 		See Documentation/ABI/testing/sysfs-devices-system-cpu-preferred
 		and  Documentation/scheduler/sched-paravirt.rst for more details.
diff --git a/kernel/Kconfig.preempt b/kernel/Kconfig.preempt
index 0cbc697202dd..9736c6e291d8 100644
--- a/kernel/Kconfig.preempt
+++ b/kernel/Kconfig.preempt
@@ -197,7 +197,7 @@ config SCHED_CLASS_EXT
 
 config PREFERRED_CPU
 	bool "Preferred CPU scheduling"
-	depends on SMP && HAVE_CPUTIME_STEAL
+	depends on SMP
 	help
 	  Hint the fair scheduler to favor a subset of active CPUs.
 	  Non-preferred CPUs remain online and can still run tasks
-- 
2.53.0


^ permalink raw reply related	[flat|nested] 4+ messages in thread

* [PATCH RFC 3/3] docs: sched: describe thermal control with preferred CPUs
  2026-11-17  2:25 [PATCH RFC 0/3] Expose writable interface for preferred CPUs Yury Norov
  2026-11-17  2:25 ` [PATCH RFC 1/3] cpu: add sysfs control for preferred CPUS Yury Norov
  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 ` Yury Norov
  2 siblings, 0 replies; 4+ messages in thread
From: Yury Norov @ 2026-11-17  2:25 UTC (permalink / raw)
  To: Peter Zijlstra, Ingo Molnar, Thomas Gleixner, Juri Lelli,
	Vincent Guittot, Srinivas Pandruvada, Wei Wang, Shrikanth Hegde
  Cc: Yury Norov, Yury Norov, Rafael J. Wysocki, Alexander Gordeev,
	Andrea Righi, Ben Segall, Christian Borntraeger, Daniel Lezcano,
	Danilo Krummrich, Dietmar Eggemann, Fushuai Wang,
	Greg Kroah-Hartman, Heiko Carstens, Ilya Leoshkevich,
	Johan Hovold, Jonathan Corbet, K Prateek Nayak, Lukasz Luba,
	Maxim Kuvyrkov, Mel Gorman, Mete Durlu, Randy Dunlap,
	Rasmus Villemoes, Shuah Khan, Steven Rostedt, Sven Schnelle,
	Valentin Schneider, Vasily Gorbik, linux-kernel, linux-doc,
	driver-core, linux-pm

Document a thermald policy that keeps CPU0 preferred, marks CPU1
non-preferred at 80 C, and restores its preferred status below 75 C.

Some Qualcomm-based Android devices, including the Nexus 6P, have used
temperature-driven CPU offlining. Preferred CPU selection offers a weaker
alternative that preserves task affinities and avoids CPU hotplug
transitions. If pinned tasks or tasks outside the fair scheduling class
prevent a CPU from becoming idle, a userspace thermal policy can use
stronger controls, such as CPU offlining.

Tested with thermald 2.5.11 in an eight-vCPU virtme/KVM guest on an
Intel Core Ultra 7 268V. Each vCPU is pinned to a separate host CPU.
Thermald uses the relayed host package temperature to control preferred
CPUs, with staggered trips at 46-58 C and 2 C hysteresis. CPU0 remains
preferred throughout.

No host thermal throttling occurred during the test. Guest events, with
sampled package temperatures and preferred CPU masks are logged as
follows.

Elapsed  Event                      Package temp  Preferred CPUs
     0s  Start eight busy loops             42 C  0-7
     1s  CPU1-6 non-preferred               57 C  0,7
     2s  CPU6 preferred                     52 C  0,6-7
    13s  CPU6 non-preferred                 56 C  0,7
    30s  CPU7 non-preferred                 58 C  0
    90s  Stop workload                      56 C  0
    90s  CPU4-7 preferred                   49 C  0,4-7
    93s  CPU3 preferred                     47 C  0,3-7
   102s  CPU2 preferred                     45 C  0,2-7
   106s  CPU2-3 non-preferred               50 C  0,4-7
   107s  CPU2-3 preferred                   45 C  0,2-7

Signed-off-by: Yury Norov <ynorov@nvidia.com>
---
 Documentation/scheduler/index.rst             |  1 +
 .../scheduler/preferred-cpu-thermal.rst       | 94 +++++++++++++++++++
 2 files changed, 95 insertions(+)
 create mode 100644 Documentation/scheduler/preferred-cpu-thermal.rst

diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
index 791178ac8bec..25d1590d8217 100644
--- a/Documentation/scheduler/index.rst
+++ b/Documentation/scheduler/index.rst
@@ -24,6 +24,7 @@ Scheduler
     sched-ext
     sched-debug
     sched-paravirt
+    preferred-cpu-thermal
     sched-preemption
 
     text_files
diff --git a/Documentation/scheduler/preferred-cpu-thermal.rst b/Documentation/scheduler/preferred-cpu-thermal.rst
new file mode 100644
index 000000000000..da6d019e42e4
--- /dev/null
+++ b/Documentation/scheduler/preferred-cpu-thermal.rst
@@ -0,0 +1,94 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Thermal control with preferred CPUs
+===================================
+
+Preferred CPU selection can be driven by thermal signal. A userspace thermal
+policy can reduce the preferred CPU set to concentrate fair tasks on fewer
+CPUs, allowing other CPUs to become idle. This approach may be preferred over
+offlining CPUs because it preserves task affinities and avoids CPU hotplug
+transitions.
+
+The following thermald configuration illustrates this on a system with two
+online CPUs. CPU0 stays preferred. When the package temperature reaches 80 C,
+CPU1 becomes non-preferred. Once the temperature falls below 75 C, CPU1
+becomes preferred again.
+
+Save the configuration as ``/etc/thermald/thermal-conf-preferred.xml``.
+Replace the sensor path with the package temperature sensor on the target
+system: the example assumes ``thermal_zone0/type`` is ``x86_pkg_temp``.
+Temperature and hysteresis values are in millidegrees Celsius::
+
+    <?xml version="1.0"?>
+    <ThermalConfiguration>
+      <Platform>
+        <Name>Preferred CPU thermal policy</Name>
+        <ProductName>*</ProductName>
+        <Preference>QUIET</Preference>
+        <ThermalSensors>
+          <ThermalSensor>
+            <Type>package-temperature</Type>
+            <Path>/sys/class/thermal/thermal_zone0/temp</Path>
+            <AsyncCapable>0</AsyncCapable>
+          </ThermalSensor>
+        </ThermalSensors>
+        <ThermalZones>
+          <ThermalZone>
+            <Type>preferred-cpu-zone</Type>
+            <TripPoints>
+              <TripPoint>
+                <SensorType>package-temperature</SensorType>
+                <Temperature>80000</Temperature>
+                <Hyst>5000</Hyst>
+                <type>passive</type>
+                <ControlType>PARALLEL</ControlType>
+                <CoolingDevice>
+                  <type>preferred-cpu1</type>
+                  <TargetState>0</TargetState>
+                </CoolingDevice>
+              </TripPoint>
+            </TripPoints>
+          </ThermalZone>
+        </ThermalZones>
+        <CoolingDevices>
+          <CoolingDevice>
+            <Type>preferred-cpu0</Type>
+            <Path>/sys/devices/system/cpu/cpu0/preferred</Path>
+            <MinState>1</MinState>
+            <MaxState>1</MaxState>
+            <ReadBack>1</ReadBack>
+          </CoolingDevice>
+          <CoolingDevice>
+            <Type>preferred-cpu1</Type>
+            <Path>/sys/devices/system/cpu/cpu1/preferred</Path>
+            <MinState>1</MinState>
+            <MaxState>0</MaxState>
+            <ReadBack>1</ReadBack>
+          </CoolingDevice>
+        </CoolingDevices>
+      </Platform>
+    </ThermalConfiguration>
+
+CPU0 is declared with both states set to 1 and has no associated trip.
+Start with CPU0 preferred; thermald leaves its preferred status unchanged,
+so at least one CPU remains preferred.
+
+CPU1's cooling states are deliberately reversed: ``MinState=1`` is the
+normal preferred state, and ``MaxState=0`` is the cooling state.
+``TargetState=0`` explicitly clears CPU1's preferred status when the trip
+is active. When the trip clears, thermald restores ``MinState=1``.
+
+Usage.
+
+Stop any existing thermald service, then run this example as root::
+
+    thermald --no-daemon --ignore-default-control --poll-interval=1 \
+        --config-file=/etc/thermald/thermal-conf-preferred.xml
+
+On SMT systems, control all siblings of a core together when the goal is to
+idle a whole core. CPU hotplug can change the preferred mask independently
+of thermald.
+
+See :ref:`sched-paravirt` for scheduling behavior and
+``Documentation/ABI/testing/sysfs-devices-system-cpu-preferred`` for the
+sysfs interface and hotplug rules.
-- 
2.53.0


^ permalink raw reply related	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2026-11-17  2:25 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-17  2:25 [PATCH RFC 0/3] Expose writable interface for preferred CPUs Yury Norov
2026-11-17  2:25 ` [PATCH RFC 1/3] cpu: add sysfs control for preferred CPUS Yury Norov
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

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox