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 3/3] docs: sched: describe thermal control with preferred CPUs
Date: Mon, 16 Nov 2026 21:25:41 -0500 [thread overview]
Message-ID: <20261117022542.863028-4-ynorov@nvidia.com> (raw)
In-Reply-To: <20261117022542.863028-1-ynorov@nvidia.com>
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
prev parent reply other threads:[~2026-11-17 2:27 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 ` [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 [this message]
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-4-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