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 driver configuration for the given CPU is updated 161(e.g. via ``sysfs``). 162 163This is the default P-state selection algorithm if the 164:c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option 165is set. 166 167``powersave`` 168............. 169 170Without HWP, this P-state selection algorithm generally depends on the 171processor model and/or the system profile setting in the ACPI tables and there 172are two variants of it. 173 174One of them is used with processors from the Atom line and (regardless of the 175processor model) on platforms with the system profile in the ACPI tables set to 176"mobile" (laptops mostly), "tablet", "appliance PC", "desktop", or 177"workstation". It is also used with processors supporting the HWP feature if 178that feature has not been enabled (that is, with the ``intel_pstate=no_hwp`` 179argument in the kernel command line). It is similar to the algorithm 180implemented by the generic ``schedutil`` scaling governor except that the 181utilization metric used by it is based on numbers coming from feedback 182registers of the CPU. It generally selects P-states proportional to the 183current CPU utilization, so it is referred to as the "proportional" algorithm. 184 185The second variant of the ``powersave`` P-state selection algorithm, used in all 186of the other cases (generally, on processors from the Core line, so it is 187referred to as the "Core" algorithm), is based on the values read from the APERF 188and MPERF feedback registers and the previously requested target P-state. 189It does not really take CPU utilization into account explicitly, but as a rule 190it causes the CPU P-state to ramp up very quickly in response to increased 191utilization which is generally desirable in server environments. 192 193Regardless of the variant, this algorithm is run by the driver's utilization 194update callback for the given CPU when it is invoked by the CPU scheduler, but 195not more often than every 10 ms (that can be tweaked via ``debugfs`` in `this 196particular case <Tuning Interface in debugfs_>`_). Like in the ``performance`` 197case, the hardware configuration is not touched if the new P-state turns out to 198be the same as the current one. 199 200This is the default P-state selection algorithm if the 201:c:macro:`CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE` kernel configuration option 202is not set. 203 204Passive Mode 205------------ 206 207This mode is used if the ``intel_pstate=passive`` argument is passed to the 208kernel in the command line (it implies the ``intel_pstate=no_hwp`` setting too). 209Like in the active mode without HWP support, in this mode ``intel_pstate`` may 210refuse to work with the given processor if it does not recognize it. 211 212If the driver works in this mode, the ``scaling_driver`` policy attribute in 213``sysfs`` for all ``CPUFreq`` policies contains the string "intel_cpufreq". 214Then, the driver behaves like a regular ``CPUFreq`` scaling driver. That is, 215it is invoked by generic scaling governors when necessary to talk to the 216hardware in order to change the P-state of a CPU (in particular, the 217``schedutil`` governor can invoke it directly from scheduler context). 218 219While in this mode, ``intel_pstate`` can be used with all of the (generic) 220scaling governors listed by the ``scaling_available_governors`` policy attribute 221in ``sysfs`` (and the P-state selection algorithms described above are not 222used). Then, it is responsible for the configuration of policy objects 223corresponding to CPUs and provides the ``CPUFreq`` core (and the scaling 224governors attached to the policy objects) with accurate information on the 225maximum and minimum operating frequencies supported by the hardware (including 226the so-called "turbo" frequency ranges). In other words, in the passive mode 227the entire range of available P-states is exposed by ``intel_pstate`` to the 228``CPUFreq`` core. However, in this mode the driver does not register 229utilization update callbacks with the CPU scheduler and the ``scaling_cur_freq`` 230information comes from the ``CPUFreq`` core (and is the last frequency selected 231by the current scaling governor for the given policy). 232 233 234.. _turbo: 235 236Turbo P-states Support 237====================== 238 239In the majority of cases, the entire range of P-states available to 240``intel_pstate`` can be divided into two sub-ranges that correspond to 241different types of processor behavior, above and below a boundary that 242will be referred to as the "turbo threshold" in what follows. 243 244The P-states above the turbo threshold are referred to as "turbo P-states" and 245the whole sub-range of P-states they belong to is referred to as the "turbo 246range". These names are related to the Turbo Boost technology allowing a 247multicore processor to opportunistically increase the P-state of one or more 248cores if there is enough power to do that and if that is not going to cause the 249thermal envelope of the processor package to be exceeded. 250 251Specifically, if software sets the P-state of a CPU core within the turbo range 252(that is, above the turbo threshold), the processor is permitted to take over 253performance scaling control for that core and put it into turbo P-states of its 254choice going forward. However, that permission is interpreted differently by 255different processor generations. Namely, the Sandy Bridge generation of 256processors will never use any P-states above the last one set by software for 257the given core, even if it is within the turbo range, whereas all of the later 258processor generations will take it as a license to use any P-states from the 259turbo range, even above the one set by software. In other words, on those 260processors setting any P-state from the turbo range will enable the processor 261to put the given core into all turbo P-states up to and including the maximum 262supported one as it sees fit. 263 264One important property of turbo P-states is that they are not sustainable. More 265precisely, there is no guarantee that any CPUs will be able to stay in any of 266those states indefinitely, because the power distribution within the processor 267package may change over time or the thermal envelope it was designed for might 268be exceeded if a turbo P-state was used for too long. 269 270In turn, the P-states below the turbo threshold generally are sustainable. In 271fact, if one of them is set by software, the processor is not expected to change 272it to a lower one unless in a thermal stress or a power limit violation 273situation (a higher P-state may still be used if it is set for another CPU in 274the same package at the same time, for example). 275 276Some processors allow multiple cores to be in turbo P-states at the same time, 277but the maximum P-state that can be set for them generally depends on the number 278of cores running concurrently. The maximum turbo P-state that can be set for 3 279cores at the same time usually is lower than the analogous maximum P-state for 2802 cores, which in turn usually is lower than the maximum turbo P-state that can 281be set for 1 core. The one-core maximum turbo P-state is thus the maximum 282supported one overall. 283 284The maximum supported turbo P-state, the turbo threshold (the maximum supported 285non-turbo P-state) and the minimum supported P-state are specific to the 286processor model and can be determined by reading the processor's model-specific 287registers (MSRs). Moreover, some processors support the Configurable TDP 288(Thermal Design Power) feature and, when that feature is enabled, the turbo 289threshold effectively becomes a configurable value that can be set by the 290platform firmware. 291 292Unlike ``_PSS`` objects in the ACPI tables, ``intel_pstate`` always exposes 293the entire range of available P-states, including the whole turbo range, to the 294``CPUFreq`` core and (in the passive mode) to generic scaling governors. This 295generally causes turbo P-states to be set more often when ``intel_pstate`` is 296used relative to ACPI-based CPU performance scaling (see `below <acpi-cpufreq_>`_ 297for more information). 298 299Moreover, since ``intel_pstate`` always knows what the real turbo threshold is 300(even if the Configurable TDP feature is enabled in the processor), its 301``no_turbo`` attribute in ``sysfs`` (described `below <no_turbo_attr_>`_) should 302work as expected in all cases (that is, if set to disable turbo P-states, it 303always should prevent ``intel_pstate`` from using them). 304 305 306Processor Support 307================= 308 309To handle a given processor ``intel_pstate`` requires a number of different 310pieces of information on it to be known, including: 311 312 * The minimum supported P-state. 313 314 * The maximum supported `non-turbo P-state <turbo_>`_. 315 316 * Whether or not turbo P-states are supported at all. 317 318 * The maximum supported `one-core turbo P-state <turbo_>`_ (if turbo P-states 319 are supported). 320 321 * The scaling formula to translate the driver's internal representation 322 of P-states into frequencies and the other way around. 323 324Generally, ways to obtain that information are specific to the processor model 325or family. Although it often is possible to obtain all of it from the processor 326itself (using model-specific registers), there are cases in which hardware 327manuals need to be consulted to get to it too. 328 329For this reason, there is a list of supported processors in ``intel_pstate`` and 330the driver initialization will fail if the detected processor is not in that 331list, unless it supports the `HWP feature <Active Mode_>`_. [The interface to 332obtain all of the information listed above is the same for all of the processors 333supporting the HWP feature, which is why they all are supported by 334``intel_pstate``.] 335 336 337User Space Interface in ``sysfs`` 338================================= 339 340Global Attributes 341----------------- 342 343``intel_pstate`` exposes several global attributes (files) in ``sysfs`` to 344control its functionality at the system level. They are located in the 345``/sys/devices/system/cpu/cpufreq/intel_pstate/`` directory and affect all 346CPUs. 347 348Some of them are not present if the ``intel_pstate=per_cpu_perf_limits`` 349argument is passed to the kernel in the command line. 350 351``max_perf_pct`` 352 Maximum P-state the driver is allowed to set in percent of the 353 maximum supported performance level (the highest supported `turbo 354 P-state <turbo_>`_). 355 356 This attribute will not be exposed if the 357 ``intel_pstate=per_cpu_perf_limits`` argument is present in the kernel 358 command line. 359 360``min_perf_pct`` 361 Minimum P-state the driver is allowed to set in percent of the 362 maximum supported performance level (the highest supported `turbo 363 P-state <turbo_>`_). 364 365 This attribute will not be exposed if the 366 ``intel_pstate=per_cpu_perf_limits`` argument is present in the kernel 367 command line. 368 369``num_pstates`` 370 Number of P-states supported by the processor (between 0 and 255 371 inclusive) including both turbo and non-turbo P-states (see 372 `Turbo P-states Support`_). 373 374 The value of this attribute is not affected by the ``no_turbo`` 375 setting described `below <no_turbo_attr_>`_. 376 377 This attribute is read-only. 378 379``turbo_pct`` 380 Ratio of the `turbo range <turbo_>`_ size to the size of the entire 381 range of supported P-states, in percent. 382 383 This attribute is read-only. 384 385.. _no_turbo_attr: 386 387``no_turbo`` 388 If set (equal to 1), the driver is not allowed to set any turbo P-states 389 (see `Turbo P-states Support`_). If unset (equalt to 0, which is the 390 default), turbo P-states can be set by the driver. 391 [Note that ``intel_pstate`` does not support the general ``boost`` 392 attribute (supported by some other scaling drivers) which is replaced 393 by this one.] 394 395 This attrubute does not affect the maximum supported frequency value 396 supplied to the ``CPUFreq`` core and exposed via the policy interface, 397 but it affects the maximum possible value of per-policy P-state limits 398 (see `Interpretation of Policy Attributes`_ below for details). 399 400.. _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 with 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 476The meaning of these attributes in the `passive mode <Passive Mode_>`_ is the 477same as for other scaling drivers. 478 479Additionally, the value of the ``scaling_driver`` attribute for ``intel_pstate`` 480depends on the operation mode of the driver. Namely, it is either 481"intel_pstate" (in the `active mode <Active Mode_>`_) or "intel_cpufreq" (in the 482`passive mode <Passive Mode_>`_). 483 484Coordination of P-State Limits 485------------------------------ 486 487``intel_pstate`` allows P-state limits to be set in two ways: with the help of 488the ``max_perf_pct`` and ``min_perf_pct`` `global attributes 489<Global Attributes_>`_ or via the ``scaling_max_freq`` and ``scaling_min_freq`` 490``CPUFreq`` policy attributes. The coordination between those limits is based 491on the following rules, regardless of the current operation mode of the driver: 492 493 1. All CPUs are affected by the global limits (that is, none of them can be 494 requested to run faster than the global maximum and none of them can be 495 requested to run slower than the global minimum). 496 497 2. Each individual CPU is affected by its own per-policy limits (that is, it 498 cannot be requested to run faster than its own per-policy maximum and it 499 cannot be requested to run slower than its own per-policy minimum). 500 501 3. The global and per-policy limits can be set independently. 502 503If the `HWP feature is enabled in the processor <Active Mode With HWP_>`_, the 504resulting effective values are written into its registers whenever the limits 505change in order to request its internal P-state selection logic to always set 506P-states within these limits. Otherwise, the limits are taken into account by 507scaling governors (in the `passive mode <Passive Mode_>`_) and by the driver 508every time before setting a new P-state for a CPU. 509 510Additionally, if the ``intel_pstate=per_cpu_perf_limits`` command line argument 511is passed to the kernel, ``max_perf_pct`` and ``min_perf_pct`` are not exposed 512at all and the only way to set the limits is by using the policy attributes. 513 514 515Energy vs Performance Hints 516--------------------------- 517 518If ``intel_pstate`` works in the `active mode with the HWP feature enabled 519<Active Mode With HWP_>`_ in the processor, additional attributes are present 520in every ``CPUFreq`` policy directory in ``sysfs``. They are intended to allow 521user space to help ``intel_pstate`` to adjust the processor's internal P-state 522selection logic by focusing it on performance or on energy-efficiency, or 523somewhere between the two extremes: 524 525``energy_performance_preference`` 526 Current value of the energy vs performance hint for the given policy 527 (or the CPU represented by it). 528 529 The hint can be changed by writing to this attribute. 530 531``energy_performance_available_preferences`` 532 List of strings that can be written to the 533 ``energy_performance_preference`` attribute. 534 535 They represent different energy vs performance hints and should be 536 self-explanatory, except that ``default`` represents whatever hint 537 value was set by the platform firmware. 538 539Strings written to the ``energy_performance_preference`` attribute are 540internally translated to integer values written to the processor's 541Energy-Performance Preference (EPP) knob (if supported) or its 542Energy-Performance Bias (EPB) knob. 543 544[Note that tasks may by migrated from one CPU to another by the scheduler's 545load-balancing algorithm and if different energy vs performance hints are 546set for those CPUs, that may lead to undesirable outcomes. To avoid such 547issues it is better to set the same energy vs performance hint for all CPUs 548or to pin every task potentially sensitive to them to a specific CPU.] 549 550.. _acpi-cpufreq: 551 552``intel_pstate`` vs ``acpi-cpufreq`` 553==================================== 554 555On the majority of systems supported by ``intel_pstate``, the ACPI tables 556provided by the platform firmware contain ``_PSS`` objects returning information 557that can be used for CPU performance scaling (refer to the `ACPI specification`_ 558for details on the ``_PSS`` objects and the format of the information returned 559by them). 560 561The information returned by the ACPI ``_PSS`` objects is used by the 562``acpi-cpufreq`` scaling driver. On systems supported by ``intel_pstate`` 563the ``acpi-cpufreq`` driver uses the same hardware CPU performance scaling 564interface, but the set of P-states it can use is limited by the ``_PSS`` 565output. 566 567On those systems each ``_PSS`` object returns a list of P-states supported by 568the corresponding CPU which basically is a subset of the P-states range that can 569be used by ``intel_pstate`` on the same system, with one exception: the whole 570`turbo range <turbo_>`_ is represented by one item in it (the topmost one). By 571convention, the frequency returned by ``_PSS`` for that item is greater by 1 MHz 572than the frequency of the highest non-turbo P-state listed by it, but the 573corresponding P-state representation (following the hardware specification) 574returned for it matches the maximum supported turbo P-state (or is the 575special value 255 meaning essentially "go as high as you can get"). 576 577The list of P-states returned by ``_PSS`` is reflected by the table of 578available frequencies supplied by ``acpi-cpufreq`` to the ``CPUFreq`` core and 579scaling governors and the minimum and maximum supported frequencies reported by 580it come from that list as well. In particular, given the special representation 581of the turbo range described above, this means that the maximum supported 582frequency reported by ``acpi-cpufreq`` is higher by 1 MHz than the frequency 583of the highest supported non-turbo P-state listed by ``_PSS`` which, of course, 584affects decisions made by the scaling governors, except for ``powersave`` and 585``performance``. 586 587For example, if a given governor attempts to select a frequency proportional to 588estimated CPU load and maps the load of 100% to the maximum supported frequency 589(possibly multiplied by a constant), then it will tend to choose P-states below 590the turbo threshold if ``acpi-cpufreq`` is used as the scaling driver, because 591in that case the turbo range corresponds to a small fraction of the frequency 592band it can use (1 MHz vs 1 GHz or more). In consequence, it will only go to 593the turbo range for the highest loads and the other loads above 50% that might 594benefit from running at turbo frequencies will be given non-turbo P-states 595instead. 596 597One more issue related to that may appear on systems supporting the 598`Configurable TDP feature <turbo_>`_ allowing the platform firmware to set the 599turbo threshold. Namely, if that is not coordinated with the lists of P-states 600returned by ``_PSS`` properly, there may be more than one item corresponding to 601a turbo P-state in those lists and there may be a problem with avoiding the 602turbo range (if desirable or necessary). Usually, to avoid using turbo 603P-states overall, ``acpi-cpufreq`` simply avoids using the topmost state listed 604by ``_PSS``, but that is not sufficient when there are other turbo P-states in 605the list returned by it. 606 607Apart from the above, ``acpi-cpufreq`` works like ``intel_pstate`` in the 608`passive mode <Passive Mode_>`_, except that the number of P-states it can set 609is limited to the ones listed by the ACPI ``_PSS`` objects. 610 611 612Kernel Command Line Options for ``intel_pstate`` 613================================================ 614 615Several kernel command line options can be used to pass early-configuration-time 616parameters to ``intel_pstate`` in order to enforce specific behavior of it. All 617of them have to be prepended with the ``intel_pstate=`` prefix. 618 619``disable`` 620 Do not register ``intel_pstate`` as the scaling driver even if the 621 processor is supported by it. 622 623``passive`` 624 Register ``intel_pstate`` in the `passive mode <Passive Mode_>`_ to 625 start with. 626 627 This option implies the ``no_hwp`` one described below. 628 629``force`` 630 Register ``intel_pstate`` as the scaling driver instead of 631 ``acpi-cpufreq`` even if the latter is preferred on the given system. 632 633 This may prevent some platform features (such as thermal controls and 634 power capping) that rely on the availability of ACPI P-states 635 information from functioning as expected, so it should be used with 636 caution. 637 638 This option does not work with processors that are not supported by 639 ``intel_pstate`` and on platforms where the ``pcc-cpufreq`` scaling 640 driver is used instead of ``acpi-cpufreq``. 641 642``no_hwp`` 643 Do not enable the `hardware-managed P-states (HWP) feature 644 <Active Mode With HWP_>`_ even if it is supported by the processor. 645 646``hwp_only`` 647 Register ``intel_pstate`` as the scaling driver only if the 648 `hardware-managed P-states (HWP) feature <Active Mode With HWP_>`_ is 649 supported by the processor. 650 651``support_acpi_ppc`` 652 Take ACPI ``_PPC`` performance limits into account. 653 654 If the preferred power management profile in the FADT (Fixed ACPI 655 Description Table) is set to "Enterprise Server" or "Performance 656 Server", the ACPI ``_PPC`` limits are taken into account by default 657 and this option has no effect. 658 659``per_cpu_perf_limits`` 660 Use per-logical-CPU P-State limits (see `Coordination of P-state 661 Limits`_ for details). 662 663 664Diagnostics and Tuning 665====================== 666 667Trace Events 668------------ 669 670There are two static trace events that can be used for ``intel_pstate`` 671diagnostics. One of them is the ``cpu_frequency`` trace event generally used 672by ``CPUFreq``, and the other one is the ``pstate_sample`` trace event specific 673to ``intel_pstate``. Both of them are triggered by ``intel_pstate`` only if 674it works in the `active mode <Active Mode_>`_. 675 676The following sequence of shell commands can be used to enable them and see 677their output (if the kernel is generally configured to support event tracing):: 678 679 # cd /sys/kernel/debug/tracing/ 680 # echo 1 > events/power/pstate_sample/enable 681 # echo 1 > events/power/cpu_frequency/enable 682 # cat trace 683 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 684 cat-5235 [002] ..s. 1177.681723: cpu_frequency: state=2900000 cpu_id=2 685 686If ``intel_pstate`` works in the `passive mode <Passive Mode_>`_, the 687``cpu_frequency`` trace event will be triggered either by the ``schedutil`` 688scaling governor (for the policies it is attached to), or by the ``CPUFreq`` 689core (for the policies with other scaling governors). 690 691``ftrace`` 692---------- 693 694The ``ftrace`` interface can be used for low-level diagnostics of 695``intel_pstate``. For example, to check how often the function to set a 696P-state is called, the ``ftrace`` filter can be set to to 697:c:func:`intel_pstate_set_pstate`:: 698 699 # cd /sys/kernel/debug/tracing/ 700 # cat available_filter_functions | grep -i pstate 701 intel_pstate_set_pstate 702 intel_pstate_cpu_init 703 ... 704 # echo intel_pstate_set_pstate > set_ftrace_filter 705 # echo function > current_tracer 706 # cat trace | head -15 707 # tracer: function 708 # 709 # entries-in-buffer/entries-written: 80/80 #P:4 710 # 711 # _-----=> irqs-off 712 # / _----=> need-resched 713 # | / _---=> hardirq/softirq 714 # || / _--=> preempt-depth 715 # ||| / delay 716 # TASK-PID CPU# |||| TIMESTAMP FUNCTION 717 # | | | |||| | | 718 Xorg-3129 [000] ..s. 2537.644844: intel_pstate_set_pstate <-intel_pstate_timer_func 719 gnome-terminal--4510 [002] ..s. 2537.649844: intel_pstate_set_pstate <-intel_pstate_timer_func 720 gnome-shell-3409 [001] ..s. 2537.650850: intel_pstate_set_pstate <-intel_pstate_timer_func 721 <idle>-0 [000] ..s. 2537.654843: intel_pstate_set_pstate <-intel_pstate_timer_func 722 723Tuning Interface in ``debugfs`` 724------------------------------- 725 726The ``powersave`` algorithm provided by ``intel_pstate`` for `the Core line of 727processors in the active mode <powersave_>`_ is based on a `PID controller`_ 728whose parameters were chosen to address a number of different use cases at the 729same time. However, it still is possible to fine-tune it to a specific workload 730and the ``debugfs`` interface under ``/sys/kernel/debug/pstate_snb/`` is 731provided for this purpose. [Note that the ``pstate_snb`` directory will be 732present only if the specific P-state selection algorithm matching the interface 733in it actually is in use.] 734 735The following files present in that directory can be used to modify the PID 736controller parameters at run time: 737 738| ``deadband`` 739| ``d_gain_pct`` 740| ``i_gain_pct`` 741| ``p_gain_pct`` 742| ``sample_rate_ms`` 743| ``setpoint`` 744 745Note, however, that achieving desirable results this way generally requires 746expert-level understanding of the power vs performance tradeoff, so extra care 747is recommended when attempting to do that. 748 749 750.. _LCEU2015: http://events.linuxfoundation.org/sites/events/files/slides/LinuxConEurope_2015.pdf 751.. _SDM: http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-system-programming-manual-325384.html 752.. _ACPI specification: http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf 753.. _PID controller: https://en.wikipedia.org/wiki/PID_controller 754