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