1 .. SPDX-License-Identifier: GPL-2.0 <<
2 .. include:: <isonum.txt> <<
3 <<
4 ============================================== 1 ===============================================
5 ``intel_pstate`` CPU Performance Scaling Drive 2 ``intel_pstate`` CPU Performance Scaling Driver
6 ============================================== 3 ===============================================
7 4
8 :Copyright: |copy| 2017 Intel Corporation !! 5 ::
9 6
10 :Author: Rafael J. Wysocki <rafael.j.wysocki@in !! 7 Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
11 8
12 9
13 General Information 10 General Information
14 =================== 11 ===================
15 12
16 ``intel_pstate`` is a part of the 13 ``intel_pstate`` is a part of the
17 :doc:`CPU performance scaling subsystem <cpufr 14 :doc:`CPU performance scaling subsystem <cpufreq>` in the Linux kernel
18 (``CPUFreq``). It is a scaling driver for the 15 (``CPUFreq``). It is a scaling driver for the Sandy Bridge and later
19 generations of Intel processors. Note, howeve 16 generations of Intel processors. Note, however, that some of those processors
20 may not be supported. [To understand ``intel_ 17 may not be supported. [To understand ``intel_pstate`` it is necessary to know
21 how ``CPUFreq`` works in general, so this is t !! 18 how ``CPUFreq`` works in general, so this is the time to read :doc:`cpufreq` if
22 Documentation/admin-guide/pm/cpufreq.rst if yo !! 19 you have not done that yet.]
23 20
24 For the processors supported by ``intel_pstate 21 For the processors supported by ``intel_pstate``, the P-state concept is broader
25 than just an operating frequency or an operati 22 than just an operating frequency or an operating performance point (see the
26 LinuxCon Europe 2015 presentation by Kristen A !! 23 `LinuxCon Europe 2015 presentation by Kristen Accardi <LCEU2015_>`_ for more
27 information about that). For this reason, the 24 information about that). For this reason, the representation of P-states used
28 by ``intel_pstate`` internally follows the har 25 by ``intel_pstate`` internally follows the hardware specification (for details
29 refer to Intel Software Developer’s Manual [ !! 26 refer to `Intel® 64 and IA-32 Architectures Software Developer’s Manual
>> 27 Volume 3: System Programming Guide <SDM_>`_). However, the ``CPUFreq`` core
30 uses frequencies for identifying operating per 28 uses frequencies for identifying operating performance points of CPUs and
31 frequencies are involved in the user space int 29 frequencies are involved in the user space interface exposed by it, so
32 ``intel_pstate`` maps its internal representat 30 ``intel_pstate`` maps its internal representation of P-states to frequencies too
33 (fortunately, that mapping is unambiguous). A 31 (fortunately, that mapping is unambiguous). At the same time, it would not be
34 practical for ``intel_pstate`` to supply the ` 32 practical for ``intel_pstate`` to supply the ``CPUFreq`` core with a table of
35 available frequencies due to the possible size 33 available frequencies due to the possible size of it, so the driver does not do
36 that. Some functionality of the core is limit 34 that. Some functionality of the core is limited by that.
37 35
38 Since the hardware P-state selection interface 36 Since the hardware P-state selection interface used by ``intel_pstate`` is
39 available at the logical CPU level, the driver 37 available at the logical CPU level, the driver always works with individual
40 CPUs. Consequently, if ``intel_pstate`` is in 38 CPUs. Consequently, if ``intel_pstate`` is in use, every ``CPUFreq`` policy
41 object corresponds to one logical CPU and ``CP 39 object corresponds to one logical CPU and ``CPUFreq`` policies are effectively
42 equivalent to CPUs. In particular, this means 40 equivalent to CPUs. In particular, this means that they become "inactive" every
43 time the corresponding CPU is taken offline an 41 time the corresponding CPU is taken offline and need to be re-initialized when
44 it goes back online. 42 it goes back online.
45 43
46 ``intel_pstate`` is not modular, so it cannot 44 ``intel_pstate`` is not modular, so it cannot be unloaded, which means that the
47 only way to pass early-configuration-time para 45 only way to pass early-configuration-time parameters to it is via the kernel
48 command line. However, its configuration can 46 command line. However, its configuration can be adjusted via ``sysfs`` to a
49 great extent. In some configurations it even 47 great extent. In some configurations it even is possible to unregister it via
50 ``sysfs`` which allows another ``CPUFreq`` sca 48 ``sysfs`` which allows another ``CPUFreq`` scaling driver to be loaded and
51 registered (see `below <status_attr_>`_). 49 registered (see `below <status_attr_>`_).
52 50
53 51
54 Operation Modes 52 Operation Modes
55 =============== 53 ===============
56 54
57 ``intel_pstate`` can operate in two different !! 55 ``intel_pstate`` can operate in three different modes: in the active mode with
58 active mode, it uses its own internal performa !! 56 or without hardware-managed P-states support and in the passive mode. Which of
59 allows the hardware to do performance scaling !! 57 them will be in effect depends on what kernel command line options are used and
60 mode it responds to requests made by a generic !! 58 on the capabilities of the processor.
61 a certain performance scaling algorithm. Whic <<
62 depends on what kernel command line options ar <<
63 the processor. <<
64 59
65 Active Mode 60 Active Mode
66 ----------- 61 -----------
67 62
68 This is the default operation mode of ``intel_ !! 63 This is the default operation mode of ``intel_pstate``. If it works in this
69 hardware-managed P-states (HWP) support. If i !! 64 mode, the ``scaling_driver`` policy attribute in ``sysfs`` for all ``CPUFreq``
70 ``scaling_driver`` policy attribute in ``sysfs !! 65 policies contains the string "intel_pstate".
71 contains the string "intel_pstate". <<
72 66
73 In this mode the driver bypasses the scaling g 67 In this mode the driver bypasses the scaling governors layer of ``CPUFreq`` and
74 provides its own scaling algorithms for P-stat 68 provides its own scaling algorithms for P-state selection. Those algorithms
75 can be applied to ``CPUFreq`` policies in the 69 can be applied to ``CPUFreq`` policies in the same way as generic scaling
76 governors (that is, through the ``scaling_gove 70 governors (that is, through the ``scaling_governor`` policy attribute in
77 ``sysfs``). [Note that different P-state sele 71 ``sysfs``). [Note that different P-state selection algorithms may be chosen for
78 different policies, but that is not recommende 72 different policies, but that is not recommended.]
79 73
80 They are not generic scaling governors, but th 74 They are not generic scaling governors, but their names are the same as the
81 names of some of those governors. Moreover, c 75 names of some of those governors. Moreover, confusingly enough, they generally
82 do not work in the same way as the generic gov 76 do not work in the same way as the generic governors they share the names with.
83 For example, the ``powersave`` P-state selecti 77 For example, the ``powersave`` P-state selection algorithm provided by
84 ``intel_pstate`` is not a counterpart of the g 78 ``intel_pstate`` is not a counterpart of the generic ``powersave`` governor
85 (roughly, it corresponds to the ``schedutil`` 79 (roughly, it corresponds to the ``schedutil`` and ``ondemand`` governors).
86 80
87 There are two P-state selection algorithms pro 81 There are two P-state selection algorithms provided by ``intel_pstate`` in the
88 active mode: ``powersave`` and ``performance`` 82 active mode: ``powersave`` and ``performance``. The way they both operate
89 depends on whether or not the hardware-managed 83 depends on whether or not the hardware-managed P-states (HWP) feature has been
90 enabled in the processor and possibly on the p 84 enabled in the processor and possibly on the processor model.
91 85
92 Which of the P-state selection algorithms is u 86 Which of the P-state selection algorithms is used by default depends on the
93 :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMA 87 :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option.
94 Namely, if that option is set, the ``performan 88 Namely, if that option is set, the ``performance`` algorithm will be used by
95 default, and the other one will be used by def 89 default, and the other one will be used by default if it is not set.
96 90
97 Active Mode With HWP 91 Active Mode With HWP
98 ~~~~~~~~~~~~~~~~~~~~ 92 ~~~~~~~~~~~~~~~~~~~~
99 93
100 If the processor supports the HWP feature, it 94 If the processor supports the HWP feature, it will be enabled during the
101 processor initialization and cannot be disable 95 processor initialization and cannot be disabled after that. It is possible
102 to avoid enabling it by passing the ``intel_ps 96 to avoid enabling it by passing the ``intel_pstate=no_hwp`` argument to the
103 kernel in the command line. 97 kernel in the command line.
104 98
105 If the HWP feature has been enabled, ``intel_p 99 If the HWP feature has been enabled, ``intel_pstate`` relies on the processor to
106 select P-states by itself, but still it can gi 100 select P-states by itself, but still it can give hints to the processor's
107 internal P-state selection logic. What those 101 internal P-state selection logic. What those hints are depends on which P-state
108 selection algorithm has been applied to the gi 102 selection algorithm has been applied to the given policy (or to the CPU it
109 corresponds to). 103 corresponds to).
110 104
111 Even though the P-state selection is carried o 105 Even though the P-state selection is carried out by the processor automatically,
112 ``intel_pstate`` registers utilization update 106 ``intel_pstate`` registers utilization update callbacks with the CPU scheduler
113 in this mode. However, they are not used for 107 in this mode. However, they are not used for running a P-state selection
114 algorithm, but for periodic updates of the cur 108 algorithm, but for periodic updates of the current CPU frequency information to
115 be made available from the ``scaling_cur_freq` 109 be made available from the ``scaling_cur_freq`` policy attribute in ``sysfs``.
116 110
117 HWP + ``performance`` 111 HWP + ``performance``
118 ..................... 112 .....................
119 113
120 In this configuration ``intel_pstate`` will wr 114 In this configuration ``intel_pstate`` will write 0 to the processor's
121 Energy-Performance Preference (EPP) knob (if s 115 Energy-Performance Preference (EPP) knob (if supported) or its
122 Energy-Performance Bias (EPB) knob (otherwise) 116 Energy-Performance Bias (EPB) knob (otherwise), which means that the processor's
123 internal P-state selection logic is expected t 117 internal P-state selection logic is expected to focus entirely on performance.
124 118
125 This will override the EPP/EPB setting coming 119 This will override the EPP/EPB setting coming from the ``sysfs`` interface
126 (see `Energy vs Performance Hints`_ below). M !! 120 (see `Energy vs Performance Hints`_ below).
127 the EPP/EPB to a value different from 0 ("perf <<
128 configuration will be rejected. <<
129 121
130 Also, in this configuration the range of P-sta 122 Also, in this configuration the range of P-states available to the processor's
131 internal P-state selection logic is always res 123 internal P-state selection logic is always restricted to the upper boundary
132 (that is, the maximum P-state that the driver 124 (that is, the maximum P-state that the driver is allowed to use).
133 125
134 HWP + ``powersave`` 126 HWP + ``powersave``
135 ................... 127 ...................
136 128
137 In this configuration ``intel_pstate`` will se 129 In this configuration ``intel_pstate`` will set the processor's
138 Energy-Performance Preference (EPP) knob (if s 130 Energy-Performance Preference (EPP) knob (if supported) or its
139 Energy-Performance Bias (EPB) knob (otherwise) 131 Energy-Performance Bias (EPB) knob (otherwise) to whatever value it was
140 previously set to via ``sysfs`` (or whatever d 132 previously set to via ``sysfs`` (or whatever default value it was
141 set to by the platform firmware). This usuall 133 set to by the platform firmware). This usually causes the processor's
142 internal P-state selection logic to be less pe 134 internal P-state selection logic to be less performance-focused.
143 135
144 Active Mode Without HWP 136 Active Mode Without HWP
145 ~~~~~~~~~~~~~~~~~~~~~~~ 137 ~~~~~~~~~~~~~~~~~~~~~~~
146 138
147 This operation mode is optional for processors !! 139 This is the default operation mode for processors that do not support the HWP
148 feature or when the ``intel_pstate=no_hwp`` ar !! 140 feature. It also is used by default with the ``intel_pstate=no_hwp`` argument
149 the command line. The active mode is used in !! 141 in the kernel command line. However, in this mode ``intel_pstate`` may refuse
150 ``intel_pstate=active`` argument is passed to !! 142 to work with the given processor if it does not recognize it. [Note that
151 In this mode ``intel_pstate`` may refuse to wo !! 143 ``intel_pstate`` will never refuse to work with any processor with the HWP
152 recognized by it. [Note that ``intel_pstate`` !! 144 feature enabled.]
153 any processor with the HWP feature enabled.] <<
154 145
155 In this mode ``intel_pstate`` registers utiliz 146 In this mode ``intel_pstate`` registers utilization update callbacks with the
156 CPU scheduler in order to run a P-state select 147 CPU scheduler in order to run a P-state selection algorithm, either
157 ``powersave`` or ``performance``, depending on !! 148 ``powersave`` or ``performance``, depending on the ``scaling_cur_freq`` policy
158 setting in ``sysfs``. The current CPU frequen 149 setting in ``sysfs``. The current CPU frequency information to be made
159 available from the ``scaling_cur_freq`` policy 150 available from the ``scaling_cur_freq`` policy attribute in ``sysfs`` is
160 periodically updated by those utilization upda 151 periodically updated by those utilization update callbacks too.
161 152
162 ``performance`` 153 ``performance``
163 ............... 154 ...............
164 155
165 Without HWP, this P-state selection algorithm 156 Without HWP, this P-state selection algorithm is always the same regardless of
166 the processor model and platform configuration 157 the processor model and platform configuration.
167 158
168 It selects the maximum P-state it is allowed t 159 It selects the maximum P-state it is allowed to use, subject to limits set via
169 ``sysfs``, every time the driver configuration 160 ``sysfs``, every time the driver configuration for the given CPU is updated
170 (e.g. via ``sysfs``). 161 (e.g. via ``sysfs``).
171 162
172 This is the default P-state selection algorith 163 This is the default P-state selection algorithm if the
173 :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMA 164 :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option
174 is set. 165 is set.
175 166
176 ``powersave`` 167 ``powersave``
177 ............. 168 .............
178 169
179 Without HWP, this P-state selection algorithm !! 170 Without HWP, this P-state selection algorithm generally depends on the
>> 171 processor model and/or the system profile setting in the ACPI tables and there
>> 172 are two variants of it.
>> 173
>> 174 One of them is used with processors from the Atom line and (regardless of the
>> 175 processor model) on platforms with the system profile in the ACPI tables set to
>> 176 "mobile" (laptops mostly), "tablet", "appliance PC", "desktop", or
>> 177 "workstation". It is also used with processors supporting the HWP feature if
>> 178 that feature has not been enabled (that is, with the ``intel_pstate=no_hwp``
>> 179 argument in the kernel command line). It is similar to the algorithm
180 implemented by the generic ``schedutil`` scali 180 implemented by the generic ``schedutil`` scaling governor except that the
181 utilization metric used by it is based on numb 181 utilization metric used by it is based on numbers coming from feedback
182 registers of the CPU. It generally selects P- 182 registers of the CPU. It generally selects P-states proportional to the
183 current CPU utilization. !! 183 current CPU utilization, so it is referred to as the "proportional" algorithm.
184 184
185 This algorithm is run by the driver's utilizat !! 185 The second variant of the ``powersave`` P-state selection algorithm, used in all
186 given CPU when it is invoked by the CPU schedu !! 186 of the other cases (generally, on processors from the Core line, so it is
187 every 10 ms. Like in the ``performance`` case !! 187 referred to as the "Core" algorithm), is based on the values read from the APERF
188 is not touched if the new P-state turns out to !! 188 and MPERF feedback registers and the previously requested target P-state.
189 one. !! 189 It does not really take CPU utilization into account explicitly, but as a rule
>> 190 it causes the CPU P-state to ramp up very quickly in response to increased
>> 191 utilization which is generally desirable in server environments.
>> 192
>> 193 Regardless of the variant, this algorithm is run by the driver's utilization
>> 194 update callback for the given CPU when it is invoked by the CPU scheduler, but
>> 195 not more often than every 10 ms (that can be tweaked via ``debugfs`` in `this
>> 196 particular case <Tuning Interface in debugfs_>`_). Like in the ``performance``
>> 197 case, the hardware configuration is not touched if the new P-state turns out to
>> 198 be the same as the current one.
190 199
191 This is the default P-state selection algorith 200 This is the default P-state selection algorithm if the
192 :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMA 201 :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option
193 is not set. 202 is not set.
194 203
195 Passive Mode 204 Passive Mode
196 ------------ 205 ------------
197 206
198 This is the default operation mode of ``intel_ !! 207 This mode is used if the ``intel_pstate=passive`` argument is passed to the
199 hardware-managed P-states (HWP) support. It i !! 208 kernel in the command line (it implies the ``intel_pstate=no_hwp`` setting too).
200 ``intel_pstate=passive`` argument is passed to !! 209 Like in the active mode without HWP support, in this mode ``intel_pstate`` may
201 regardless of whether or not the given process !! 210 refuse to work with the given processor if it does not recognize it.
202 ``intel_pstate=no_hwp`` setting causes the dri <<
203 if it is not combined with ``intel_pstate=acti <<
204 without HWP support, in this mode ``intel_psta <<
205 processors that are not recognized by it if HW <<
206 through the kernel command line. <<
207 211
208 If the driver works in this mode, the ``scalin 212 If the driver works in this mode, the ``scaling_driver`` policy attribute in
209 ``sysfs`` for all ``CPUFreq`` policies contain 213 ``sysfs`` for all ``CPUFreq`` policies contains the string "intel_cpufreq".
210 Then, the driver behaves like a regular ``CPUF 214 Then, the driver behaves like a regular ``CPUFreq`` scaling driver. That is,
211 it is invoked by generic scaling governors whe 215 it is invoked by generic scaling governors when necessary to talk to the
212 hardware in order to change the P-state of a C 216 hardware in order to change the P-state of a CPU (in particular, the
213 ``schedutil`` governor can invoke it directly 217 ``schedutil`` governor can invoke it directly from scheduler context).
214 218
215 While in this mode, ``intel_pstate`` can be us 219 While in this mode, ``intel_pstate`` can be used with all of the (generic)
216 scaling governors listed by the ``scaling_avai 220 scaling governors listed by the ``scaling_available_governors`` policy attribute
217 in ``sysfs`` (and the P-state selection algori 221 in ``sysfs`` (and the P-state selection algorithms described above are not
218 used). Then, it is responsible for the config 222 used). Then, it is responsible for the configuration of policy objects
219 corresponding to CPUs and provides the ``CPUFr 223 corresponding to CPUs and provides the ``CPUFreq`` core (and the scaling
220 governors attached to the policy objects) with 224 governors attached to the policy objects) with accurate information on the
221 maximum and minimum operating frequencies supp 225 maximum and minimum operating frequencies supported by the hardware (including
222 the so-called "turbo" frequency ranges). In o 226 the so-called "turbo" frequency ranges). In other words, in the passive mode
223 the entire range of available P-states is expo 227 the entire range of available P-states is exposed by ``intel_pstate`` to the
224 ``CPUFreq`` core. However, in this mode the d 228 ``CPUFreq`` core. However, in this mode the driver does not register
225 utilization update callbacks with the CPU sche 229 utilization update callbacks with the CPU scheduler and the ``scaling_cur_freq``
226 information comes from the ``CPUFreq`` core (a 230 information comes from the ``CPUFreq`` core (and is the last frequency selected
227 by the current scaling governor for the given 231 by the current scaling governor for the given policy).
228 232
229 233
230 .. _turbo: 234 .. _turbo:
231 235
232 Turbo P-states Support 236 Turbo P-states Support
233 ====================== 237 ======================
234 238
235 In the majority of cases, the entire range of 239 In the majority of cases, the entire range of P-states available to
236 ``intel_pstate`` can be divided into two sub-r 240 ``intel_pstate`` can be divided into two sub-ranges that correspond to
237 different types of processor behavior, above a 241 different types of processor behavior, above and below a boundary that
238 will be referred to as the "turbo threshold" i 242 will be referred to as the "turbo threshold" in what follows.
239 243
240 The P-states above the turbo threshold are ref 244 The P-states above the turbo threshold are referred to as "turbo P-states" and
241 the whole sub-range of P-states they belong to 245 the whole sub-range of P-states they belong to is referred to as the "turbo
242 range". These names are related to the Turbo 246 range". These names are related to the Turbo Boost technology allowing a
243 multicore processor to opportunistically incre 247 multicore processor to opportunistically increase the P-state of one or more
244 cores if there is enough power to do that and 248 cores if there is enough power to do that and if that is not going to cause the
245 thermal envelope of the processor package to b 249 thermal envelope of the processor package to be exceeded.
246 250
247 Specifically, if software sets the P-state of 251 Specifically, if software sets the P-state of a CPU core within the turbo range
248 (that is, above the turbo threshold), the proc 252 (that is, above the turbo threshold), the processor is permitted to take over
249 performance scaling control for that core and 253 performance scaling control for that core and put it into turbo P-states of its
250 choice going forward. However, that permissio 254 choice going forward. However, that permission is interpreted differently by
251 different processor generations. Namely, the 255 different processor generations. Namely, the Sandy Bridge generation of
252 processors will never use any P-states above t 256 processors will never use any P-states above the last one set by software for
253 the given core, even if it is within the turbo 257 the given core, even if it is within the turbo range, whereas all of the later
254 processor generations will take it as a licens 258 processor generations will take it as a license to use any P-states from the
255 turbo range, even above the one set by softwar 259 turbo range, even above the one set by software. In other words, on those
256 processors setting any P-state from the turbo 260 processors setting any P-state from the turbo range will enable the processor
257 to put the given core into all turbo P-states 261 to put the given core into all turbo P-states up to and including the maximum
258 supported one as it sees fit. 262 supported one as it sees fit.
259 263
260 One important property of turbo P-states is th 264 One important property of turbo P-states is that they are not sustainable. More
261 precisely, there is no guarantee that any CPUs 265 precisely, there is no guarantee that any CPUs will be able to stay in any of
262 those states indefinitely, because the power d 266 those states indefinitely, because the power distribution within the processor
263 package may change over time or the thermal e 267 package may change over time or the thermal envelope it was designed for might
264 be exceeded if a turbo P-state was used for to 268 be exceeded if a turbo P-state was used for too long.
265 269
266 In turn, the P-states below the turbo threshol 270 In turn, the P-states below the turbo threshold generally are sustainable. In
267 fact, if one of them is set by software, the p 271 fact, if one of them is set by software, the processor is not expected to change
268 it to a lower one unless in a thermal stress o 272 it to a lower one unless in a thermal stress or a power limit violation
269 situation (a higher P-state may still be used 273 situation (a higher P-state may still be used if it is set for another CPU in
270 the same package at the same time, for example 274 the same package at the same time, for example).
271 275
272 Some processors allow multiple cores to be in 276 Some processors allow multiple cores to be in turbo P-states at the same time,
273 but the maximum P-state that can be set for th 277 but the maximum P-state that can be set for them generally depends on the number
274 of cores running concurrently. The maximum tu 278 of cores running concurrently. The maximum turbo P-state that can be set for 3
275 cores at the same time usually is lower than t 279 cores at the same time usually is lower than the analogous maximum P-state for
276 2 cores, which in turn usually is lower than t 280 2 cores, which in turn usually is lower than the maximum turbo P-state that can
277 be set for 1 core. The one-core maximum turbo 281 be set for 1 core. The one-core maximum turbo P-state is thus the maximum
278 supported one overall. 282 supported one overall.
279 283
280 The maximum supported turbo P-state, the turbo 284 The maximum supported turbo P-state, the turbo threshold (the maximum supported
281 non-turbo P-state) and the minimum supported P 285 non-turbo P-state) and the minimum supported P-state are specific to the
282 processor model and can be determined by readi 286 processor model and can be determined by reading the processor's model-specific
283 registers (MSRs). Moreover, some processors s 287 registers (MSRs). Moreover, some processors support the Configurable TDP
284 (Thermal Design Power) feature and, when that 288 (Thermal Design Power) feature and, when that feature is enabled, the turbo
285 threshold effectively becomes a configurable v 289 threshold effectively becomes a configurable value that can be set by the
286 platform firmware. 290 platform firmware.
287 291
288 Unlike ``_PSS`` objects in the ACPI tables, `` 292 Unlike ``_PSS`` objects in the ACPI tables, ``intel_pstate`` always exposes
289 the entire range of available P-states, includ 293 the entire range of available P-states, including the whole turbo range, to the
290 ``CPUFreq`` core and (in the passive mode) to 294 ``CPUFreq`` core and (in the passive mode) to generic scaling governors. This
291 generally causes turbo P-states to be set more 295 generally causes turbo P-states to be set more often when ``intel_pstate`` is
292 used relative to ACPI-based CPU performance sc 296 used relative to ACPI-based CPU performance scaling (see `below <acpi-cpufreq_>`_
293 for more information). 297 for more information).
294 298
295 Moreover, since ``intel_pstate`` always knows 299 Moreover, since ``intel_pstate`` always knows what the real turbo threshold is
296 (even if the Configurable TDP feature is enabl 300 (even if the Configurable TDP feature is enabled in the processor), its
297 ``no_turbo`` attribute in ``sysfs`` (described 301 ``no_turbo`` attribute in ``sysfs`` (described `below <no_turbo_attr_>`_) should
298 work as expected in all cases (that is, if set 302 work as expected in all cases (that is, if set to disable turbo P-states, it
299 always should prevent ``intel_pstate`` from us 303 always should prevent ``intel_pstate`` from using them).
300 304
301 305
302 Processor Support 306 Processor Support
303 ================= 307 =================
304 308
305 To handle a given processor ``intel_pstate`` r 309 To handle a given processor ``intel_pstate`` requires a number of different
306 pieces of information on it to be known, inclu 310 pieces of information on it to be known, including:
307 311
308 * The minimum supported P-state. 312 * The minimum supported P-state.
309 313
310 * The maximum supported `non-turbo P-state <t 314 * The maximum supported `non-turbo P-state <turbo_>`_.
311 315
312 * Whether or not turbo P-states are supported 316 * Whether or not turbo P-states are supported at all.
313 317
314 * The maximum supported `one-core turbo P-sta 318 * The maximum supported `one-core turbo P-state <turbo_>`_ (if turbo P-states
315 are supported). 319 are supported).
316 320
317 * The scaling formula to translate the driver 321 * The scaling formula to translate the driver's internal representation
318 of P-states into frequencies and the other 322 of P-states into frequencies and the other way around.
319 323
320 Generally, ways to obtain that information are 324 Generally, ways to obtain that information are specific to the processor model
321 or family. Although it often is possible to o 325 or family. Although it often is possible to obtain all of it from the processor
322 itself (using model-specific registers), there 326 itself (using model-specific registers), there are cases in which hardware
323 manuals need to be consulted to get to it too. 327 manuals need to be consulted to get to it too.
324 328
325 For this reason, there is a list of supported 329 For this reason, there is a list of supported processors in ``intel_pstate`` and
326 the driver initialization will fail if the det 330 the driver initialization will fail if the detected processor is not in that
327 list, unless it supports the HWP feature. [Th !! 331 list, unless it supports the `HWP feature <Active Mode_>`_. [The interface to
328 information listed above is the same for all o !! 332 obtain all of the information listed above is the same for all of the processors
329 HWP feature, which is why ``intel_pstate`` wor !! 333 supporting the HWP feature, which is why they all are supported by
>> 334 ``intel_pstate``.]
330 335
331 336
332 User Space Interface in ``sysfs`` 337 User Space Interface in ``sysfs``
333 ================================= 338 =================================
334 339
335 Global Attributes 340 Global Attributes
336 ----------------- 341 -----------------
337 342
338 ``intel_pstate`` exposes several global attrib 343 ``intel_pstate`` exposes several global attributes (files) in ``sysfs`` to
339 control its functionality at the system level. 344 control its functionality at the system level. They are located in the
340 ``/sys/devices/system/cpu/intel_pstate/`` dire !! 345 ``/sys/devices/system/cpu/cpufreq/intel_pstate/`` directory and affect all
>> 346 CPUs.
341 347
342 Some of them are not present if the ``intel_ps 348 Some of them are not present if the ``intel_pstate=per_cpu_perf_limits``
343 argument is passed to the kernel in the comman 349 argument is passed to the kernel in the command line.
344 350
345 ``max_perf_pct`` 351 ``max_perf_pct``
346 Maximum P-state the driver is allowed 352 Maximum P-state the driver is allowed to set in percent of the
347 maximum supported performance level (t 353 maximum supported performance level (the highest supported `turbo
348 P-state <turbo_>`_). 354 P-state <turbo_>`_).
349 355
350 This attribute will not be exposed if 356 This attribute will not be exposed if the
351 ``intel_pstate=per_cpu_perf_limits`` a 357 ``intel_pstate=per_cpu_perf_limits`` argument is present in the kernel
352 command line. 358 command line.
353 359
354 ``min_perf_pct`` 360 ``min_perf_pct``
355 Minimum P-state the driver is allowed 361 Minimum P-state the driver is allowed to set in percent of the
356 maximum supported performance level (t 362 maximum supported performance level (the highest supported `turbo
357 P-state <turbo_>`_). 363 P-state <turbo_>`_).
358 364
359 This attribute will not be exposed if 365 This attribute will not be exposed if the
360 ``intel_pstate=per_cpu_perf_limits`` a 366 ``intel_pstate=per_cpu_perf_limits`` argument is present in the kernel
361 command line. 367 command line.
362 368
363 ``num_pstates`` 369 ``num_pstates``
364 Number of P-states supported by the pr 370 Number of P-states supported by the processor (between 0 and 255
365 inclusive) including both turbo and no 371 inclusive) including both turbo and non-turbo P-states (see
366 `Turbo P-states Support`_). 372 `Turbo P-states Support`_).
367 373
368 This attribute is present only if the <<
369 for all of the CPUs in the system. <<
370 <<
371 The value of this attribute is not aff 374 The value of this attribute is not affected by the ``no_turbo``
372 setting described `below <no_turbo_att 375 setting described `below <no_turbo_attr_>`_.
373 376
374 This attribute is read-only. 377 This attribute is read-only.
375 378
376 ``turbo_pct`` 379 ``turbo_pct``
377 Ratio of the `turbo range <turbo_>`_ s 380 Ratio of the `turbo range <turbo_>`_ size to the size of the entire
378 range of supported P-states, in percen 381 range of supported P-states, in percent.
379 382
380 This attribute is present only if the <<
381 for all of the CPUs in the system. <<
382 <<
383 This attribute is read-only. 383 This attribute is read-only.
384 384
385 .. _no_turbo_attr: 385 .. _no_turbo_attr:
386 386
387 ``no_turbo`` 387 ``no_turbo``
388 If set (equal to 1), the driver is not 388 If set (equal to 1), the driver is not allowed to set any turbo P-states
389 (see `Turbo P-states Support`_). If u !! 389 (see `Turbo P-states Support`_). If unset (equalt to 0, which is the
390 default), turbo P-states can be set by 390 default), turbo P-states can be set by the driver.
391 [Note that ``intel_pstate`` does not s 391 [Note that ``intel_pstate`` does not support the general ``boost``
392 attribute (supported by some other sca 392 attribute (supported by some other scaling drivers) which is replaced
393 by this one.] 393 by this one.]
394 394
395 This attribute does not affect the max !! 395 This attrubute does not affect the maximum supported frequency value
396 supplied to the ``CPUFreq`` core and e 396 supplied to the ``CPUFreq`` core and exposed via the policy interface,
397 but it affects the maximum possible va 397 but it affects the maximum possible value of per-policy P-state limits
398 (see `Interpretation of Policy Attribu 398 (see `Interpretation of Policy Attributes`_ below for details).
399 399
400 ``hwp_dynamic_boost`` <<
401 This attribute is only present if ``in <<
402 `active mode with the HWP feature enab <<
403 the processor. If set (equal to 1), i <<
404 to be increased dynamically for a shor <<
405 waiting on I/O is selected to run on a <<
406 of this mechanism is to improve perfor <<
407 <<
408 This setting has no effect on logical <<
409 is directly set to the highest non-tur <<
410 <<
411 .. _status_attr: 400 .. _status_attr:
412 401
413 ``status`` 402 ``status``
414 Operation mode of the driver: "active" 403 Operation mode of the driver: "active", "passive" or "off".
415 404
416 "active" 405 "active"
417 The driver is functional and i 406 The driver is functional and in the `active mode
418 <Active Mode_>`_. 407 <Active Mode_>`_.
419 408
420 "passive" 409 "passive"
421 The driver is functional and i 410 The driver is functional and in the `passive mode
422 <Passive Mode_>`_. 411 <Passive Mode_>`_.
423 412
424 "off" 413 "off"
425 The driver is not functional ( 414 The driver is not functional (it is not registered as a scaling
426 driver with the ``CPUFreq`` co 415 driver with the ``CPUFreq`` core).
427 416
428 This attribute can be written to in or 417 This attribute can be written to in order to change the driver's
429 operation mode or to unregister it. T 418 operation mode or to unregister it. The string written to it must be
430 one of the possible values of it and, 419 one of the possible values of it and, if successful, the write will
431 cause the driver to switch over to the 420 cause the driver to switch over to the operation mode represented by
432 that string - or to be unregistered in 421 that string - or to be unregistered in the "off" case. [Actually,
433 switching over from the active mode to 422 switching over from the active mode to the passive mode or the other
434 way around causes the driver to be unr 423 way around causes the driver to be unregistered and registered again
435 with a different set of callbacks, so 424 with a different set of callbacks, so all of its settings (the global
436 as well as the per-policy ones) are th 425 as well as the per-policy ones) are then reset to their default
437 values, possibly depending on the targ 426 values, possibly depending on the target operation mode.]
438 427
439 ``energy_efficiency`` !! 428 That only is supported in some configurations, though (for example, if
440 This attribute is only present on plat !! 429 the `HWP feature is enabled in the processor <Active Mode With HWP_>`_,
441 Lake or Coffee Lake desktop CPU model. !! 430 the operation mode of the driver cannot be changed), and if it is not
442 optimizations are disabled on these CP !! 431 supported in the current configuration, writes to this attribute with
443 Enabling energy-efficiency optimizatio !! 432 fail with an appropriate error.
444 frequency with or without the HWP feat <<
445 optimizations are done only in the tur <<
446 they are done in the entire available <<
447 attribute to "1" enables the energy-ef <<
448 to "0" disables them. <<
449 433
450 Interpretation of Policy Attributes 434 Interpretation of Policy Attributes
451 ----------------------------------- 435 -----------------------------------
452 436
453 The interpretation of some ``CPUFreq`` policy 437 The interpretation of some ``CPUFreq`` policy attributes described in
454 Documentation/admin-guide/pm/cpufreq.rst is sp !! 438 :doc:`cpufreq` is special with ``intel_pstate`` as the current scaling driver
455 as the current scaling driver and it generally !! 439 and it generally depends on the driver's `operation mode <Operation Modes_>`_.
456 `operation mode <Operation Modes_>`_. <<
457 440
458 First of all, the values of the ``cpuinfo_max_ 441 First of all, the values of the ``cpuinfo_max_freq``, ``cpuinfo_min_freq`` and
459 ``scaling_cur_freq`` attributes are produced b 442 ``scaling_cur_freq`` attributes are produced by applying a processor-specific
460 multiplier to the internal P-state representat 443 multiplier to the internal P-state representation used by ``intel_pstate``.
461 Also, the values of the ``scaling_max_freq`` a 444 Also, the values of the ``scaling_max_freq`` and ``scaling_min_freq``
462 attributes are capped by the frequency corresp 445 attributes are capped by the frequency corresponding to the maximum P-state that
463 the driver is allowed to set. 446 the driver is allowed to set.
464 447
465 If the ``no_turbo`` `global attribute <no_turb 448 If the ``no_turbo`` `global attribute <no_turbo_attr_>`_ is set, the driver is
466 not allowed to use turbo P-states, so the maxi 449 not allowed to use turbo P-states, so the maximum value of ``scaling_max_freq``
467 and ``scaling_min_freq`` is limited to the max 450 and ``scaling_min_freq`` is limited to the maximum non-turbo P-state frequency.
468 Accordingly, setting ``no_turbo`` causes ``sca 451 Accordingly, setting ``no_turbo`` causes ``scaling_max_freq`` and
469 ``scaling_min_freq`` to go down to that value 452 ``scaling_min_freq`` to go down to that value if they were above it before.
470 However, the old values of ``scaling_max_freq` 453 However, the old values of ``scaling_max_freq`` and ``scaling_min_freq`` will be
471 restored after unsetting ``no_turbo``, unless 454 restored after unsetting ``no_turbo``, unless these attributes have been written
472 to after ``no_turbo`` was set. 455 to after ``no_turbo`` was set.
473 456
474 If ``no_turbo`` is not set, the maximum possib 457 If ``no_turbo`` is not set, the maximum possible value of ``scaling_max_freq``
475 and ``scaling_min_freq`` corresponds to the ma 458 and ``scaling_min_freq`` corresponds to the maximum supported turbo P-state,
476 which also is the value of ``cpuinfo_max_freq` 459 which also is the value of ``cpuinfo_max_freq`` in either case.
477 460
478 Next, the following policy attributes have spe 461 Next, the following policy attributes have special meaning if
479 ``intel_pstate`` works in the `active mode <Ac 462 ``intel_pstate`` works in the `active mode <Active Mode_>`_:
480 463
481 ``scaling_available_governors`` 464 ``scaling_available_governors``
482 List of P-state selection algorithms p 465 List of P-state selection algorithms provided by ``intel_pstate``.
483 466
484 ``scaling_governor`` 467 ``scaling_governor``
485 P-state selection algorithm provided b 468 P-state selection algorithm provided by ``intel_pstate`` currently in
486 use with the given policy. 469 use with the given policy.
487 470
488 ``scaling_cur_freq`` 471 ``scaling_cur_freq``
489 Frequency of the average P-state of th 472 Frequency of the average P-state of the CPU represented by the given
490 policy for the time interval between t 473 policy for the time interval between the last two invocations of the
491 driver's utilization update callback b 474 driver's utilization update callback by the CPU scheduler for that CPU.
492 475
493 One more policy attribute is present if the HW <<
494 processor: <<
495 <<
496 ``base_frequency`` <<
497 Shows the base frequency of the CPU. A <<
498 in the turbo frequency range. <<
499 <<
500 The meaning of these attributes in the `passiv 476 The meaning of these attributes in the `passive mode <Passive Mode_>`_ is the
501 same as for other scaling drivers. 477 same as for other scaling drivers.
502 478
503 Additionally, the value of the ``scaling_drive 479 Additionally, the value of the ``scaling_driver`` attribute for ``intel_pstate``
504 depends on the operation mode of the driver. 480 depends on the operation mode of the driver. Namely, it is either
505 "intel_pstate" (in the `active mode <Active Mo 481 "intel_pstate" (in the `active mode <Active Mode_>`_) or "intel_cpufreq" (in the
506 `passive mode <Passive Mode_>`_). 482 `passive mode <Passive Mode_>`_).
507 483
508 Coordination of P-State Limits 484 Coordination of P-State Limits
509 ------------------------------ 485 ------------------------------
510 486
511 ``intel_pstate`` allows P-state limits to be s 487 ``intel_pstate`` allows P-state limits to be set in two ways: with the help of
512 the ``max_perf_pct`` and ``min_perf_pct`` `glo 488 the ``max_perf_pct`` and ``min_perf_pct`` `global attributes
513 <Global Attributes_>`_ or via the ``scaling_ma 489 <Global Attributes_>`_ or via the ``scaling_max_freq`` and ``scaling_min_freq``
514 ``CPUFreq`` policy attributes. The coordinati 490 ``CPUFreq`` policy attributes. The coordination between those limits is based
515 on the following rules, regardless of the curr 491 on the following rules, regardless of the current operation mode of the driver:
516 492
517 1. All CPUs are affected by the global limits 493 1. All CPUs are affected by the global limits (that is, none of them can be
518 requested to run faster than the global ma 494 requested to run faster than the global maximum and none of them can be
519 requested to run slower than the global mi 495 requested to run slower than the global minimum).
520 496
521 2. Each individual CPU is affected by its own 497 2. Each individual CPU is affected by its own per-policy limits (that is, it
522 cannot be requested to run faster than its 498 cannot be requested to run faster than its own per-policy maximum and it
523 cannot be requested to run slower than its !! 499 cannot be requested to run slower than its own per-policy minimum).
524 effective performance depends on whether t <<
525 P-states, hyper-threading is enabled and o <<
526 from other CPUs. When platform doesn't sup <<
527 effective performance can be more than the <<
528 other CPUs are requesting higher performan <<
529 core P-states support, when hyper-threadin <<
530 is requesting higher performance, the othe <<
531 performance than their policy limits. <<
532 500
533 3. The global and per-policy limits can be se 501 3. The global and per-policy limits can be set independently.
534 502
535 In the `active mode with the HWP feature enabl !! 503 If the `HWP feature is enabled in the processor <Active Mode With HWP_>`_, the
536 resulting effective values are written into ha !! 504 resulting effective values are written into its registers whenever the limits
537 limits change in order to request its internal !! 505 change in order to request its internal P-state selection logic to always set
538 set P-states within these limits. Otherwise, !! 506 P-states within these limits. Otherwise, the limits are taken into account by
539 by scaling governors (in the `passive mode <Pa !! 507 scaling governors (in the `passive mode <Passive Mode_>`_) and by the driver
540 every time before setting a new P-state for a 508 every time before setting a new P-state for a CPU.
541 509
542 Additionally, if the ``intel_pstate=per_cpu_pe 510 Additionally, if the ``intel_pstate=per_cpu_perf_limits`` command line argument
543 is passed to the kernel, ``max_perf_pct`` and 511 is passed to the kernel, ``max_perf_pct`` and ``min_perf_pct`` are not exposed
544 at all and the only way to set the limits is b 512 at all and the only way to set the limits is by using the policy attributes.
545 513
546 514
547 Energy vs Performance Hints 515 Energy vs Performance Hints
548 --------------------------- 516 ---------------------------
549 517
550 If the hardware-managed P-states (HWP) is enab !! 518 If ``intel_pstate`` works in the `active mode with the HWP feature enabled
551 attributes, intended to allow user space to he !! 519 <Active Mode With HWP_>`_ in the processor, additional attributes are present
552 processor's internal P-state selection logic b !! 520 in every ``CPUFreq`` policy directory in ``sysfs``. They are intended to allow
553 energy-efficiency, or somewhere between the tw !! 521 user space to help ``intel_pstate`` to adjust the processor's internal P-state
554 ``CPUFreq`` policy directory in ``sysfs``. Th !! 522 selection logic by focusing it on performance or on energy-efficiency, or
>> 523 somewhere between the two extremes:
555 524
556 ``energy_performance_preference`` 525 ``energy_performance_preference``
557 Current value of the energy vs perform 526 Current value of the energy vs performance hint for the given policy
558 (or the CPU represented by it). 527 (or the CPU represented by it).
559 528
560 The hint can be changed by writing to 529 The hint can be changed by writing to this attribute.
561 530
562 ``energy_performance_available_preferences`` 531 ``energy_performance_available_preferences``
563 List of strings that can be written to 532 List of strings that can be written to the
564 ``energy_performance_preference`` attr 533 ``energy_performance_preference`` attribute.
565 534
566 They represent different energy vs per 535 They represent different energy vs performance hints and should be
567 self-explanatory, except that ``defaul 536 self-explanatory, except that ``default`` represents whatever hint
568 value was set by the platform firmware 537 value was set by the platform firmware.
569 538
570 Strings written to the ``energy_performance_pr 539 Strings written to the ``energy_performance_preference`` attribute are
571 internally translated to integer values writte 540 internally translated to integer values written to the processor's
572 Energy-Performance Preference (EPP) knob (if s 541 Energy-Performance Preference (EPP) knob (if supported) or its
573 Energy-Performance Bias (EPB) knob. It is also !! 542 Energy-Performance Bias (EPB) knob.
574 integer value between 0 to 255, if the EPP fea <<
575 feature is not present, writing integer value <<
576 supported. In this case, user can use the <<
577 "/sys/devices/system/cpu/cpu*/power/energy_per <<
578 543
579 [Note that tasks may by migrated from one CPU 544 [Note that tasks may by migrated from one CPU to another by the scheduler's
580 load-balancing algorithm and if different ener 545 load-balancing algorithm and if different energy vs performance hints are
581 set for those CPUs, that may lead to undesirab 546 set for those CPUs, that may lead to undesirable outcomes. To avoid such
582 issues it is better to set the same energy vs 547 issues it is better to set the same energy vs performance hint for all CPUs
583 or to pin every task potentially sensitive to 548 or to pin every task potentially sensitive to them to a specific CPU.]
584 549
585 .. _acpi-cpufreq: 550 .. _acpi-cpufreq:
586 551
587 ``intel_pstate`` vs ``acpi-cpufreq`` 552 ``intel_pstate`` vs ``acpi-cpufreq``
588 ==================================== 553 ====================================
589 554
590 On the majority of systems supported by ``inte 555 On the majority of systems supported by ``intel_pstate``, the ACPI tables
591 provided by the platform firmware contain ``_P 556 provided by the platform firmware contain ``_PSS`` objects returning information
592 that can be used for CPU performance scaling ( !! 557 that can be used for CPU performance scaling (refer to the `ACPI specification`_
593 [3]_ for details on the ``_PSS`` objects and t !! 558 for details on the ``_PSS`` objects and the format of the information returned
594 returned by them). !! 559 by them).
595 560
596 The information returned by the ACPI ``_PSS`` 561 The information returned by the ACPI ``_PSS`` objects is used by the
597 ``acpi-cpufreq`` scaling driver. On systems s 562 ``acpi-cpufreq`` scaling driver. On systems supported by ``intel_pstate``
598 the ``acpi-cpufreq`` driver uses the same hard 563 the ``acpi-cpufreq`` driver uses the same hardware CPU performance scaling
599 interface, but the set of P-states it can use 564 interface, but the set of P-states it can use is limited by the ``_PSS``
600 output. 565 output.
601 566
602 On those systems each ``_PSS`` object returns 567 On those systems each ``_PSS`` object returns a list of P-states supported by
603 the corresponding CPU which basically is a sub 568 the corresponding CPU which basically is a subset of the P-states range that can
604 be used by ``intel_pstate`` on the same system 569 be used by ``intel_pstate`` on the same system, with one exception: the whole
605 `turbo range <turbo_>`_ is represented by one 570 `turbo range <turbo_>`_ is represented by one item in it (the topmost one). By
606 convention, the frequency returned by ``_PSS`` 571 convention, the frequency returned by ``_PSS`` for that item is greater by 1 MHz
607 than the frequency of the highest non-turbo P- 572 than the frequency of the highest non-turbo P-state listed by it, but the
608 corresponding P-state representation (followin 573 corresponding P-state representation (following the hardware specification)
609 returned for it matches the maximum supported 574 returned for it matches the maximum supported turbo P-state (or is the
610 special value 255 meaning essentially "go as h 575 special value 255 meaning essentially "go as high as you can get").
611 576
612 The list of P-states returned by ``_PSS`` is r 577 The list of P-states returned by ``_PSS`` is reflected by the table of
613 available frequencies supplied by ``acpi-cpufr 578 available frequencies supplied by ``acpi-cpufreq`` to the ``CPUFreq`` core and
614 scaling governors and the minimum and maximum 579 scaling governors and the minimum and maximum supported frequencies reported by
615 it come from that list as well. In particular 580 it come from that list as well. In particular, given the special representation
616 of the turbo range described above, this means 581 of the turbo range described above, this means that the maximum supported
617 frequency reported by ``acpi-cpufreq`` is high 582 frequency reported by ``acpi-cpufreq`` is higher by 1 MHz than the frequency
618 of the highest supported non-turbo P-state lis 583 of the highest supported non-turbo P-state listed by ``_PSS`` which, of course,
619 affects decisions made by the scaling governor 584 affects decisions made by the scaling governors, except for ``powersave`` and
620 ``performance``. 585 ``performance``.
621 586
622 For example, if a given governor attempts to s 587 For example, if a given governor attempts to select a frequency proportional to
623 estimated CPU load and maps the load of 100% t 588 estimated CPU load and maps the load of 100% to the maximum supported frequency
624 (possibly multiplied by a constant), then it w 589 (possibly multiplied by a constant), then it will tend to choose P-states below
625 the turbo threshold if ``acpi-cpufreq`` is use 590 the turbo threshold if ``acpi-cpufreq`` is used as the scaling driver, because
626 in that case the turbo range corresponds to a 591 in that case the turbo range corresponds to a small fraction of the frequency
627 band it can use (1 MHz vs 1 GHz or more). In 592 band it can use (1 MHz vs 1 GHz or more). In consequence, it will only go to
628 the turbo range for the highest loads and the 593 the turbo range for the highest loads and the other loads above 50% that might
629 benefit from running at turbo frequencies will 594 benefit from running at turbo frequencies will be given non-turbo P-states
630 instead. 595 instead.
631 596
632 One more issue related to that may appear on s 597 One more issue related to that may appear on systems supporting the
633 `Configurable TDP feature <turbo_>`_ allowing 598 `Configurable TDP feature <turbo_>`_ allowing the platform firmware to set the
634 turbo threshold. Namely, if that is not coord 599 turbo threshold. Namely, if that is not coordinated with the lists of P-states
635 returned by ``_PSS`` properly, there may be mo 600 returned by ``_PSS`` properly, there may be more than one item corresponding to
636 a turbo P-state in those lists and there may b 601 a turbo P-state in those lists and there may be a problem with avoiding the
637 turbo range (if desirable or necessary). Usua 602 turbo range (if desirable or necessary). Usually, to avoid using turbo
638 P-states overall, ``acpi-cpufreq`` simply avoi 603 P-states overall, ``acpi-cpufreq`` simply avoids using the topmost state listed
639 by ``_PSS``, but that is not sufficient when t 604 by ``_PSS``, but that is not sufficient when there are other turbo P-states in
640 the list returned by it. 605 the list returned by it.
641 606
642 Apart from the above, ``acpi-cpufreq`` works l 607 Apart from the above, ``acpi-cpufreq`` works like ``intel_pstate`` in the
643 `passive mode <Passive Mode_>`_, except that t 608 `passive mode <Passive Mode_>`_, except that the number of P-states it can set
644 is limited to the ones listed by the ACPI ``_P 609 is limited to the ones listed by the ACPI ``_PSS`` objects.
645 610
646 611
647 Kernel Command Line Options for ``intel_pstate 612 Kernel Command Line Options for ``intel_pstate``
648 ============================================== 613 ================================================
649 614
650 Several kernel command line options can be use 615 Several kernel command line options can be used to pass early-configuration-time
651 parameters to ``intel_pstate`` in order to enf 616 parameters to ``intel_pstate`` in order to enforce specific behavior of it. All
652 of them have to be prepended with the ``intel_ 617 of them have to be prepended with the ``intel_pstate=`` prefix.
653 618
654 ``disable`` 619 ``disable``
655 Do not register ``intel_pstate`` as th 620 Do not register ``intel_pstate`` as the scaling driver even if the
656 processor is supported by it. 621 processor is supported by it.
657 622
658 ``active`` <<
659 Register ``intel_pstate`` in the `acti <<
660 with. <<
661 <<
662 ``passive`` 623 ``passive``
663 Register ``intel_pstate`` in the `pass 624 Register ``intel_pstate`` in the `passive mode <Passive Mode_>`_ to
664 start with. 625 start with.
665 626
>> 627 This option implies the ``no_hwp`` one described below.
>> 628
666 ``force`` 629 ``force``
667 Register ``intel_pstate`` as the scali 630 Register ``intel_pstate`` as the scaling driver instead of
668 ``acpi-cpufreq`` even if the latter is 631 ``acpi-cpufreq`` even if the latter is preferred on the given system.
669 632
670 This may prevent some platform feature 633 This may prevent some platform features (such as thermal controls and
671 power capping) that rely on the availa 634 power capping) that rely on the availability of ACPI P-states
672 information from functioning as expect 635 information from functioning as expected, so it should be used with
673 caution. 636 caution.
674 637
675 This option does not work with process 638 This option does not work with processors that are not supported by
676 ``intel_pstate`` and on platforms wher 639 ``intel_pstate`` and on platforms where the ``pcc-cpufreq`` scaling
677 driver is used instead of ``acpi-cpufr 640 driver is used instead of ``acpi-cpufreq``.
678 641
679 ``no_hwp`` 642 ``no_hwp``
680 Do not enable the hardware-managed P-s !! 643 Do not enable the `hardware-managed P-states (HWP) feature
681 supported by the processor. !! 644 <Active Mode With HWP_>`_ even if it is supported by the processor.
682 645
683 ``hwp_only`` 646 ``hwp_only``
684 Register ``intel_pstate`` as the scali 647 Register ``intel_pstate`` as the scaling driver only if the
685 hardware-managed P-states (HWP) featur !! 648 `hardware-managed P-states (HWP) feature <Active Mode With HWP_>`_ is
>> 649 supported by the processor.
686 650
687 ``support_acpi_ppc`` 651 ``support_acpi_ppc``
688 Take ACPI ``_PPC`` performance limits 652 Take ACPI ``_PPC`` performance limits into account.
689 653
690 If the preferred power management prof 654 If the preferred power management profile in the FADT (Fixed ACPI
691 Description Table) is set to "Enterpri 655 Description Table) is set to "Enterprise Server" or "Performance
692 Server", the ACPI ``_PPC`` limits are 656 Server", the ACPI ``_PPC`` limits are taken into account by default
693 and this option has no effect. 657 and this option has no effect.
694 658
695 ``per_cpu_perf_limits`` 659 ``per_cpu_perf_limits``
696 Use per-logical-CPU P-State limits (se 660 Use per-logical-CPU P-State limits (see `Coordination of P-state
697 Limits`_ for details). 661 Limits`_ for details).
698 662
699 663
700 Diagnostics and Tuning 664 Diagnostics and Tuning
701 ====================== 665 ======================
702 666
703 Trace Events 667 Trace Events
704 ------------ 668 ------------
705 669
706 There are two static trace events that can be 670 There are two static trace events that can be used for ``intel_pstate``
707 diagnostics. One of them is the ``cpu_frequen 671 diagnostics. One of them is the ``cpu_frequency`` trace event generally used
708 by ``CPUFreq``, and the other one is the ``pst 672 by ``CPUFreq``, and the other one is the ``pstate_sample`` trace event specific
709 to ``intel_pstate``. Both of them are trigger 673 to ``intel_pstate``. Both of them are triggered by ``intel_pstate`` only if
710 it works in the `active mode <Active Mode_>`_. 674 it works in the `active mode <Active Mode_>`_.
711 675
712 The following sequence of shell commands can b 676 The following sequence of shell commands can be used to enable them and see
713 their output (if the kernel is generally confi 677 their output (if the kernel is generally configured to support event tracing)::
714 678
715 # cd /sys/kernel/tracing/ !! 679 # cd /sys/kernel/debug/tracing/
716 # echo 1 > events/power/pstate_sample/enable 680 # echo 1 > events/power/pstate_sample/enable
717 # echo 1 > events/power/cpu_frequency/enable 681 # echo 1 > events/power/cpu_frequency/enable
718 # cat trace 682 # cat trace
719 gnome-terminal--4510 [001] ..s. 1177.680733 683 gnome-terminal--4510 [001] ..s. 1177.680733: pstate_sample: core_busy=107 scaled=94 from=26 to=26 mperf=1143818 aperf=1230607 tsc=29838618 freq=2474476
720 cat-5235 [002] ..s. 1177.681723: cpu_freque 684 cat-5235 [002] ..s. 1177.681723: cpu_frequency: state=2900000 cpu_id=2
721 685
722 If ``intel_pstate`` works in the `passive mode 686 If ``intel_pstate`` works in the `passive mode <Passive Mode_>`_, the
723 ``cpu_frequency`` trace event will be triggere 687 ``cpu_frequency`` trace event will be triggered either by the ``schedutil``
724 scaling governor (for the policies it is attac 688 scaling governor (for the policies it is attached to), or by the ``CPUFreq``
725 core (for the policies with other scaling gove 689 core (for the policies with other scaling governors).
726 690
727 ``ftrace`` 691 ``ftrace``
728 ---------- 692 ----------
729 693
730 The ``ftrace`` interface can be used for low-l 694 The ``ftrace`` interface can be used for low-level diagnostics of
731 ``intel_pstate``. For example, to check how o 695 ``intel_pstate``. For example, to check how often the function to set a
732 P-state is called, the ``ftrace`` filter can b !! 696 P-state is called, the ``ftrace`` filter can be set to to
733 :c:func:`intel_pstate_set_pstate`:: 697 :c:func:`intel_pstate_set_pstate`::
734 698
735 # cd /sys/kernel/tracing/ !! 699 # cd /sys/kernel/debug/tracing/
736 # cat available_filter_functions | grep -i ps 700 # cat available_filter_functions | grep -i pstate
737 intel_pstate_set_pstate 701 intel_pstate_set_pstate
738 intel_pstate_cpu_init 702 intel_pstate_cpu_init
739 ... 703 ...
740 # echo intel_pstate_set_pstate > set_ftrace_f 704 # echo intel_pstate_set_pstate > set_ftrace_filter
741 # echo function > current_tracer 705 # echo function > current_tracer
742 # cat trace | head -15 706 # cat trace | head -15
743 # tracer: function 707 # tracer: function
744 # 708 #
745 # entries-in-buffer/entries-written: 80/80 709 # entries-in-buffer/entries-written: 80/80 #P:4
746 # 710 #
747 # _-----=> irqs- 711 # _-----=> irqs-off
748 # / _----=> need- 712 # / _----=> need-resched
749 # | / _---=> hardi 713 # | / _---=> hardirq/softirq
750 # || / _--=> preem 714 # || / _--=> preempt-depth
751 # ||| / delay 715 # ||| / delay
752 # TASK-PID CPU# |||| TIMESTAM 716 # TASK-PID CPU# |||| TIMESTAMP FUNCTION
753 # | | | |||| | 717 # | | | |||| | |
754 Xorg-3129 [000] ..s. 2537.64484 718 Xorg-3129 [000] ..s. 2537.644844: intel_pstate_set_pstate <-intel_pstate_timer_func
755 gnome-terminal--4510 [002] ..s. 2537.64984 719 gnome-terminal--4510 [002] ..s. 2537.649844: intel_pstate_set_pstate <-intel_pstate_timer_func
756 gnome-shell-3409 [001] ..s. 2537.65085 720 gnome-shell-3409 [001] ..s. 2537.650850: intel_pstate_set_pstate <-intel_pstate_timer_func
757 <idle>-0 [000] ..s. 2537.65484 721 <idle>-0 [000] ..s. 2537.654843: intel_pstate_set_pstate <-intel_pstate_timer_func
758 722
>> 723 Tuning Interface in ``debugfs``
>> 724 -------------------------------
759 725
760 References !! 726 The ``powersave`` algorithm provided by ``intel_pstate`` for `the Core line of
761 ========== !! 727 processors in the active mode <powersave_>`_ is based on a `PID controller`_
762 !! 728 whose parameters were chosen to address a number of different use cases at the
763 .. [1] Kristen Accardi, *Balancing Power and P !! 729 same time. However, it still is possible to fine-tune it to a specific workload
764 https://events.static.linuxfound.org/si !! 730 and the ``debugfs`` interface under ``/sys/kernel/debug/pstate_snb/`` is
765 !! 731 provided for this purpose. [Note that the ``pstate_snb`` directory will be
766 .. [2] *Intel® 64 and IA-32 Architectures Sof !! 732 present only if the specific P-state selection algorithm matching the interface
767 https://www.intel.com/content/www/us/en !! 733 in it actually is in use.]
768 !! 734
769 .. [3] *Advanced Configuration and Power Inter !! 735 The following files present in that directory can be used to modify the PID
770 https://uefi.org/sites/default/files/re !! 736 controller parameters at run time:
>> 737
>> 738 | ``deadband``
>> 739 | ``d_gain_pct``
>> 740 | ``i_gain_pct``
>> 741 | ``p_gain_pct``
>> 742 | ``sample_rate_ms``
>> 743 | ``setpoint``
>> 744
>> 745 Note, however, that achieving desirable results this way generally requires
>> 746 expert-level understanding of the power vs performance tradeoff, so extra care
>> 747 is recommended when attempting to do that.
>> 748
>> 749
>> 750 .. _LCEU2015: http://events.linuxfoundation.org/sites/events/files/slides/LinuxConEurope_2015.pdf
>> 751 .. _SDM: http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-system-programming-manual-325384.html
>> 752 .. _ACPI specification: http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf
>> 753 .. _PID controller: https://en.wikipedia.org/wiki/PID_controller
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.