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