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