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
  22 Documentation/admin-guide/pm/cpufreq.rst if 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 two different modes, active or passive.  In the
  58 active mode, it uses its own internal performance scaling governor algorithm or
  59 allows the hardware to do performance scaling by itself, while in the passive
  60 mode it responds to requests made by a generic ``CPUFreq`` governor implementing
  61 a certain performance scaling algorithm.  Which of them will be in effect
  62 depends on what kernel command line options are used and on the capabilities of
  63 the processor.
  64
  65 Active Mode
  66 -----------
  67
  68 This is the default operation mode of ``intel_pstate`` for processors with
  69 hardware-managed P-states (HWP) support.  If it works in this mode, the
  70 ``scaling_driver`` policy attribute in ``sysfs`` for all ``CPUFreq`` policies
  71 contains the string "intel_pstate".
  72
  73 In this mode the driver bypasses the scaling governors layer of ``CPUFreq`` and
  74 provides its own scaling algorithms for P-state selection.  Those algorithms
  75 can be applied to ``CPUFreq`` policies in the same way as generic scaling
  76 governors (that is, through the ``scaling_governor`` policy attribute in
  77 ``sysfs``).  [Note that different P-state selection algorithms may be chosen for
  78 different policies, but that is not recommended.]
  79
  80 They are not generic scaling governors, but their names are the same as the
  81 names of some of those governors.  Moreover, confusingly enough, they generally
  82 do not work in the same way as the generic governors they share the names with.
  83 For 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
  87 There are two P-state selection algorithms provided by ``intel_pstate`` in the
  88 active mode: ``powersave`` and ``performance``.  The way they both operate
  89 depends on whether or not the hardware-managed P-states (HWP) feature has been
  90 enabled in the processor and possibly on the processor model.
  91
  92 Which 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.
  94 Namely, if that option is set, the ``performance`` algorithm will be used by
  95 default, and the other one will be used by default if it is not set.
  96
  97 Active Mode With HWP
  98 ~~~~~~~~~~~~~~~~~~~~
  99
 100 If the processor supports the HWP feature, it will be enabled during the
 101 processor initialization and cannot be disabled after that.  It is possible
 102 to avoid enabling it by passing the ``intel_pstate=no_hwp`` argument to the
 103 kernel in the command line.
 104
 105 If the HWP feature has been enabled, ``intel_pstate`` relies on the processor to
 106 select P-states by itself, but still it can give hints to the processor's
 107 internal P-state selection logic.  What those hints are depends on which P-state
 108 selection algorithm has been applied to the given policy (or to the CPU it
 109 corresponds to).
 110
 111 Even though the P-state selection is carried out by the processor automatically,
 112 ``intel_pstate`` registers utilization update callbacks with the CPU scheduler
 113 in this mode.  However, they are not used for running a P-state selection
 114 algorithm, but for periodic updates of the current CPU frequency information to
 115 be made available from the ``scaling_cur_freq`` policy attribute in ``sysfs``.
 116
 117 HWP + ``performance``
 118 .....................
 119
 120 In this configuration ``intel_pstate`` will write 0 to the processor's
 121 Energy-Performance Preference (EPP) knob (if supported) or its
 122 Energy-Performance Bias (EPB) knob (otherwise), which means that the processor's
 123 internal P-state selection logic is expected to focus entirely on performance.
 124
 125 This will override the EPP/EPB setting coming from the ``sysfs`` interface
 126 (see `Energy vs Performance Hints`_ below).  Moreover, any attempts to change
 127 the EPP/EPB to a value different from 0 ("performance") via ``sysfs`` in this
 128 configuration will be rejected.
 129
 130 Also, in this configuration the range of P-states available to the processor's
 131 internal 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
 134 HWP + ``powersave``
 135 ...................
 136
 137 In this configuration ``intel_pstate`` will set the processor's
 138 Energy-Performance Preference (EPP) knob (if supported) or its
 139 Energy-Performance Bias (EPB) knob (otherwise) to whatever value it was
 140 previously set to via ``sysfs`` (or whatever default value it was
 141 set to by the platform firmware).  This usually causes the processor's
 142 internal P-state selection logic to be less performance-focused.
 143
 144 Active Mode Without HWP
 145 ~~~~~~~~~~~~~~~~~~~~~~~
 146
 147 This operation mode is optional for processors that do not support the HWP
 148 feature or when the ``intel_pstate=no_hwp`` argument is passed to the kernel in
 149 the 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.
 151 In this mode ``intel_pstate`` may refuse to work with processors that are not
 152 recognized by it.  [Note that ``intel_pstate`` will never refuse to work with
 153 any processor with the HWP feature enabled.]
 154
 155 In this mode ``intel_pstate`` registers utilization update callbacks with the
 156 CPU scheduler in order to run a P-state selection algorithm, either
 157 ``powersave`` or ``performance``, depending on the ``scaling_governor`` policy
 158 setting in ``sysfs``.  The current CPU frequency information to be made
 159 available from the ``scaling_cur_freq`` policy attribute in ``sysfs`` is
 160 periodically updated by those utilization update callbacks too.
 161
 162 ``performance``
 163 ...............
 164
 165 Without HWP, this P-state selection algorithm is always the same regardless of
 166 the processor model and platform configuration.
 167
 168 It 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
 172 This is the default P-state selection algorithm if the
 173 :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option
 174 is set.
 175
 176 ``powersave``
 177 .............
 178
 179 Without HWP, this P-state selection algorithm is similar to the algorithm
 180 implemented by the generic ``schedutil`` scaling governor except that the
 181 utilization metric used by it is based on numbers coming from feedback
 182 registers of the CPU.  It generally selects P-states proportional to the
 183 current CPU utilization.
 184
 185 This algorithm is run by the driver's utilization update callback for the
 186 given CPU when it is invoked by the CPU scheduler, but not more often than
 187 every 10 ms.  Like in the ``performance`` case, the hardware configuration
 188 is not touched if the new P-state turns out to be the same as the current
 189 one.
 190
 191 This is the default P-state selection algorithm if the
 192 :c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option
 193 is not set.
 194
 195 Passive Mode
 196 ------------
 197
 198 This is the default operation mode of ``intel_pstate`` for processors without
 199 hardware-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
 201 regardless 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
 203 if it is not combined with ``intel_pstate=active``.]  Like in the active mode
 204 without HWP support, in this mode ``intel_pstate`` may refuse to work with
 205 processors that are not recognized by it if HWP is prevented from being enabled
 206 through the kernel command line.
 207
 208 If the driver works in this mode, the ``scaling_driver`` policy attribute in
 209 ``sysfs`` for all ``CPUFreq`` policies contains the string "intel_cpufreq".
 210 Then, the driver behaves like a regular ``CPUFreq`` scaling driver.  That is,
 211 it is invoked by generic scaling governors when necessary to talk to the
 212 hardware in order to change the P-state of a CPU (in particular, the
 213 ``schedutil`` governor can invoke it directly from scheduler context).
 214
 215 While in this mode, ``intel_pstate`` can be used with all of the (generic)
 216 scaling governors listed by the ``scaling_available_governors`` policy attribute
 217 in ``sysfs`` (and the P-state selection algorithms described above are not
 218 used).  Then, it is responsible for the configuration of policy objects
 219 corresponding to CPUs and provides the ``CPUFreq`` core (and the scaling
 220 governors attached to the policy objects) with accurate information on the
 221 maximum and minimum operating frequencies supported by the hardware (including
 222 the so-called "turbo" frequency ranges).  In other words, in the passive mode
 223 the 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
 225 utilization update callbacks with the CPU scheduler and the ``scaling_cur_freq``
 226 information comes from the ``CPUFreq`` core (and is the last frequency selected
 227 by the current scaling governor for the given policy).
 228
 229
 230 .. _turbo:
 231
 232 Turbo P-states Support
 233 ======================
 234
 235 In 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
 237 different types of processor behavior, above and below a boundary that
 238 will be referred to as the "turbo threshold" in what follows.
 239
 240 The P-states above the turbo threshold are referred to as "turbo P-states" and
 241 the whole sub-range of P-states they belong to is referred to as the "turbo
 242 range".  These names are related to the Turbo Boost technology allowing a
 243 multicore processor to opportunistically increase the P-state of one or more
 244 cores if there is enough power to do that and if that is not going to cause the
 245 thermal envelope of the processor package to be exceeded.
 246
 247 Specifically, 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
 249 performance scaling control for that core and put it into turbo P-states of its
 250 choice going forward.  However, that permission is interpreted differently by
 251 different processor generations.  Namely, the Sandy Bridge generation of
 252 processors will never use any P-states above the last one set by software for
 253 the given core, even if it is within the turbo range, whereas all of the later
 254 processor generations will take it as a license to use any P-states from the
 255 turbo range, even above the one set by software.  In other words, on those
 256 processors setting any P-state from the turbo range will enable the processor
 257 to put the given core into all turbo P-states up to and including the maximum
 258 supported one as it sees fit.
 259
 260 One important property of turbo P-states is that they are not sustainable.  More
 261 precisely, there is no guarantee that any CPUs will be able to stay in any of
 262 those states indefinitely, because the power distribution within the processor
 263 package may change over time  or the thermal envelope it was designed for might
 264 be exceeded if a turbo P-state was used for too long.
 265
 266 In turn, the P-states below the turbo threshold generally are sustainable.  In
 267 fact, if one of them is set by software, the processor is not expected to change
 268 it to a lower one unless in a thermal stress or a power limit violation
 269 situation (a higher P-state may still be used if it is set for another CPU in
 270 the same package at the same time, for example).
 271
 272 Some processors allow multiple cores to be in turbo P-states at the same time,
 273 but the maximum P-state that can be set for them generally depends on the number
 274 of cores running concurrently.  The maximum turbo P-state that can be set for 3
 275 cores at the same time usually is lower than the analogous maximum P-state for
 276 2 cores, which in turn usually is lower than the maximum turbo P-state that can
 277 be set for 1 core.  The one-core maximum turbo P-state is thus the maximum
 278 supported one overall.
 279
 280 The maximum supported turbo P-state, the turbo threshold (the maximum supported
 281 non-turbo P-state) and the minimum supported P-state are specific to the
 282 processor model and can be determined by reading the processor's model-specific
 283 registers (MSRs).  Moreover, some processors support the Configurable TDP
 284 (Thermal Design Power) feature and, when that feature is enabled, the turbo
 285 threshold effectively becomes a configurable value that can be set by the
 286 platform firmware.
 287
 288 Unlike ``_PSS`` objects in the ACPI tables, ``intel_pstate`` always exposes
 289 the 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
 291 generally causes turbo P-states to be set more often when ``intel_pstate`` is
 292 used relative to ACPI-based CPU performance scaling (see `below <acpi-cpufreq_>`_
 293 for more information).
 294
 295 Moreover, 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
 298 work as expected in all cases (that is, if set to disable turbo P-states, it
 299 always should prevent ``intel_pstate`` from using them).
 300
 301
 302 Processor Support
 303 =================
 304
 305 To handle a given processor ``intel_pstate`` requires a number of different
 306 pieces 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
 320 Generally, ways to obtain that information are specific to the processor model
 321 or family.  Although it often is possible to obtain all of it from the processor
 322 itself (using model-specific registers), there are cases in which hardware
 323 manuals need to be consulted to get to it too.
 324
 325 For this reason, there is a list of supported processors in ``intel_pstate`` and
 326 the driver initialization will fail if the detected processor is not in that
 327 list, unless it supports the HWP feature.  [The interface to obtain all of the
 328 information listed above is the same for all of the processors supporting the
 329 HWP feature, which is why ``intel_pstate`` works with all of them.]
 330
 331
 332 User Space Interface in ``sysfs``
 333 =================================
 334
 335 Global Attributes
 336 -----------------
 337
 338 ``intel_pstate`` exposes several global attributes (files) in ``sysfs`` to
 339 control its functionality at the system level.  They are located in the
 340 ``/sys/devices/system/cpu/intel_pstate/`` directory and affect all CPUs.
 341
 342 Some of them are not present if the ``intel_pstate=per_cpu_perf_limits``
 343 argument 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
 450 Interpretation of Policy Attributes
 451 -----------------------------------
 452
 453 The interpretation of some ``CPUFreq`` policy attributes described in
 454 Documentation/admin-guide/pm/cpufreq.rst is special with ``intel_pstate``
 455 as the current scaling driver and it generally depends on the driver's
 456 `operation mode <Operation Modes_>`_.
 457
 458 First 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
 460 multiplier to the internal P-state representation used by ``intel_pstate``.
 461 Also, the values of the ``scaling_max_freq`` and ``scaling_min_freq``
 462 attributes are capped by the frequency corresponding to the maximum P-state that
 463 the driver is allowed to set.
 464
 465 If the ``no_turbo`` `global attribute <no_turbo_attr_>`_ is set, the driver is
 466 not allowed to use turbo P-states, so the maximum value of ``scaling_max_freq``
 467 and ``scaling_min_freq`` is limited to the maximum non-turbo P-state frequency.
 468 Accordingly, setting ``no_turbo`` causes ``scaling_max_freq`` and
 469 ``scaling_min_freq`` to go down to that value if they were above it before.
 470 However, the old values of ``scaling_max_freq`` and ``scaling_min_freq`` will be
 471 restored after unsetting ``no_turbo``, unless these attributes have been written
 472 to after ``no_turbo`` was set.
 473
 474 If ``no_turbo`` is not set, the maximum possible value of ``scaling_max_freq``
 475 and ``scaling_min_freq`` corresponds to the maximum supported turbo P-state,
 476 which also is the value of ``cpuinfo_max_freq`` in either case.
 477
 478 Next, 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
 493 One more policy attribute is present if the HWP feature is enabled in the
 494 processor:
 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
 500 The meaning of these attributes in the `passive mode <Passive Mode_>`_ is the
 501 same as for other scaling drivers.
 502
 503 Additionally, the value of the ``scaling_driver`` attribute for ``intel_pstate``
 504 depends 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
 508 Coordination of P-State Limits
 509 ------------------------------
 510
 511 ``intel_pstate`` allows P-state limits to be set in two ways: with the help of
 512 the ``max_perf_pct`` and ``min_perf_pct`` `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
 515 on 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
 535 In the `active mode with the HWP feature enabled <Active Mode With HWP_>`_, the
 536 resulting effective values are written into hardware registers whenever the
 537 limits change in order to request its internal P-state selection logic to always
 538 set P-states within these limits.  Otherwise, the limits are taken into account
 539 by scaling governors (in the `passive mode <Passive Mode_>`_) and by the driver
 540 every time before setting a new P-state for a CPU.
 541
 542 Additionally, if the ``intel_pstate=per_cpu_perf_limits`` command line argument
 543 is passed to the kernel, ``max_perf_pct`` and ``min_perf_pct`` are not exposed
 544 at all and the only way to set the limits is by using the policy attributes.
 545
 546
 547 Energy vs Performance Hints
 548 ---------------------------
 549
 550 If the hardware-managed P-states (HWP) is enabled in the processor, additional
 551 attributes, intended to allow user space to help ``intel_pstate`` to adjust the
 552 processor's internal P-state selection logic by focusing it on performance or on
 553 energy-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
 570 Strings written to the ``energy_performance_preference`` attribute are
 571 internally translated to integer values written to the processor's
 572 Energy-Performance Preference (EPP) knob (if supported) or its
 573 Energy-Performance Bias (EPB) knob. It is also possible to write a positive
 574 integer value between 0 to 255, if the EPP feature is present. If the EPP
 575 feature is not present, writing integer value to this attribute is not
 576 supported. 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
 580 load-balancing algorithm and if different energy vs performance hints are
 581 set for those CPUs, that may lead to undesirable outcomes.  To avoid such
 582 issues it is better to set the same energy vs performance hint for all CPUs
 583 or 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
 590 On the majority of systems supported by ``intel_pstate``, the ACPI tables
 591 provided by the platform firmware contain ``_PSS`` objects returning information
 592 that 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
 594 returned by them).
 595
 596 The information returned by the ACPI ``_PSS`` objects is used by the
 597 ``acpi-cpufreq`` scaling driver.  On systems supported by ``intel_pstate``
 598 the ``acpi-cpufreq`` driver uses the same hardware CPU performance scaling
 599 interface, but the set of P-states it can use is limited by the ``_PSS``
 600 output.
 601
 602 On those systems each ``_PSS`` object returns a list of P-states supported by
 603 the corresponding CPU which basically is a subset of the P-states range that can
 604 be used by ``intel_pstate`` on the same system, with one exception: the whole
 605 `turbo range <turbo_>`_ is represented by one item in it (the topmost one).  By
 606 convention, the frequency returned by ``_PSS`` for that item is greater by 1 MHz
 607 than the frequency of the highest non-turbo P-state listed by it, but the
 608 corresponding P-state representation (following the hardware specification)
 609 returned for it matches the maximum supported turbo P-state (or is the
 610 special value 255 meaning essentially "go as high as you can get").
 611
 612 The list of P-states returned by ``_PSS`` is reflected by the table of
 613 available frequencies supplied by ``acpi-cpufreq`` to the ``CPUFreq`` core and
 614 scaling governors and the minimum and maximum supported frequencies reported by
 615 it come from that list as well.  In particular, given the special representation
 616 of the turbo range described above, this means that the maximum supported
 617 frequency reported by ``acpi-cpufreq`` is higher by 1 MHz than the frequency
 618 of the highest supported non-turbo P-state listed by ``_PSS`` which, of course,
 619 affects decisions made by the scaling governors, except for ``powersave`` and
 620 ``performance``.
 621
 622 For example, if a given governor attempts to select a frequency proportional to
 623 estimated 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
 625 the turbo threshold if ``acpi-cpufreq`` is used as the scaling driver, because
 626 in that case the turbo range corresponds to a small fraction of the frequency
 627 band it can use (1 MHz vs 1 GHz or more).  In consequence, it will only go to
 628 the turbo range for the highest loads and the other loads above 50% that might
 629 benefit from running at turbo frequencies will be given non-turbo P-states
 630 instead.
 631
 632 One more issue related to that may appear on systems supporting the
 633 `Configurable TDP feature <turbo_>`_ allowing the platform firmware to set the
 634 turbo threshold.  Namely, if that is not coordinated with the lists of P-states
 635 returned by ``_PSS`` properly, there may be more than one item corresponding to
 636 a turbo P-state in those lists and there may be a problem with avoiding the
 637 turbo range (if desirable or necessary).  Usually, to avoid using turbo
 638 P-states overall, ``acpi-cpufreq`` simply avoids using the topmost state listed
 639 by ``_PSS``, but that is not sufficient when there are other turbo P-states in
 640 the list returned by it.
 641
 642 Apart 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
 644 is limited to the ones listed by the ACPI ``_PSS`` objects.
 645
 646
 647 Kernel Command Line Options for ``intel_pstate``
 648 ================================================
 649
 650 Several kernel command line options can be used to pass early-configuration-time
 651 parameters to ``intel_pstate`` in order to enforce specific behavior of it.  All
 652 of 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
 700 Diagnostics and Tuning
 701 ======================
 702
 703 Trace Events
 704 ------------
 705
 706 There are two static trace events that can be used for ``intel_pstate``
 707 diagnostics.  One of them is the ``cpu_frequency`` trace event generally used
 708 by ``CPUFreq``, and the other one is the ``pstate_sample`` trace event specific
 709 to ``intel_pstate``.  Both of them are triggered by ``intel_pstate`` only if
 710 it works in the `active mode <Active Mode_>`_.
 711
 712 The following sequence of shell commands can be used to enable them and see
 713 their output (if the kernel is generally configured to support event tracing)::
 714
 715  # cd /sys/kernel/debug/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
 722 If ``intel_pstate`` works in the `passive mode <Passive Mode_>`_, the
 723 ``cpu_frequency`` trace event will be triggered either by the ``schedutil``
 724 scaling governor (for the policies it is attached to), or by the ``CPUFreq``
 725 core (for the policies with other scaling governors).
 726
 727 ``ftrace``
 728 ----------
 729
 730 The ``ftrace`` interface can be used for low-level diagnostics of
 731 ``intel_pstate``.  For example, to check how often the function to set a
 732 P-state is called, the ``ftrace`` filter can be set to
 733 :c:func:`intel_pstate_set_pstate`::
 734
 735  # cd /sys/kernel/debug/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
 760 References
 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