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