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