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