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