Documentation/cpu-freq/intel-pstate.txt

   1 Intel P-State driver
   2 --------------------
   3
   4 This driver provides an interface to control the P-State selection for the
   5 SandyBridge+ Intel processors.
   6
   7 The following document explains P-States:
   8 http://events.linuxfoundation.org/sites/events/files/slides/LinuxConEurope_2015.pdf
   9 As stated in the document, P-State doesn’t exactly mean a frequency. However, for
  10 the sake of the relationship with cpufreq, P-State and frequency are used
  11 interchangeably.
  12
  13 Understanding the cpufreq core governors and policies are important before
  14 discussing more details about the Intel P-State driver. Based on what callbacks
  15 a cpufreq driver provides to the cpufreq core, it can support two types of
  16 drivers:
  17 - with target_index() callback: In this mode, the drivers using cpufreq core
  18 simply provide the minimum and maximum frequency limits and an additional
  19 interface target_index() to set the current frequency. The cpufreq subsystem
  20 has a number of scaling governors ("performance", "powersave", "ondemand",
  21 etc.). Depending on which governor is in use, cpufreq core will call for
  22 transitions to a specific frequency using target_index() callback.
  23 - setpolicy() callback: In this mode, drivers do not provide target_index()
  24 callback, so cpufreq core can't request a transition to a specific frequency.
  25 The driver provides minimum and maximum frequency limits and callbacks to set a
  26 policy. The policy in cpufreq sysfs is referred to as the "scaling governor".
  27 The cpufreq core can request the driver to operate in any of the two policies:
  28 "performance" and "powersave". The driver decides which frequency to use based
  29 on the above policy selection considering minimum and maximum frequency limits.
  30
  31 The Intel P-State driver falls under the latter category, which implements the
  32 setpolicy() callback. This driver decides what P-State to use based on the
  33 requested policy from the cpufreq core. If the processor is capable of
  34 selecting its next P-State internally, then the driver will offload this
  35 responsibility to the processor (aka HWP: Hardware P-States). If not, the
  36 driver implements algorithms to select the next P-State.
  37
  38 Since these policies are implemented in the driver, they are not same as the
  39 cpufreq scaling governors implementation, even if they have the same name in
  40 the cpufreq sysfs (scaling_governors). For example the "performance" policy is
  41 similar to cpufreq’s "performance" governor, but "powersave" is completely
  42 different than the cpufreq "powersave" governor. The strategy here is similar
  43 to cpufreq "ondemand", where the requested P-State is related to the system load.
  44
  45 Sysfs Interface
  46
  47 In addition to the frequency-controlling interfaces provided by the cpufreq
  48 core, the driver provides its own sysfs files to control the P-State selection.
  49 These files have been added to /sys/devices/system/cpu/intel_pstate/.
  50 Any changes made to these files are applicable to all CPUs (even in a
  51 multi-package system, Refer to later section on placing "Per-CPU limits").
  52
  53       max_perf_pct: Limits the maximum P-State that will be requested by
  54       the driver. It states it as a percentage of the available performance. The
  55       available (P-State) performance may be reduced by the no_turbo
  56       setting described below.
  57
  58       min_perf_pct: Limits the minimum P-State that will be requested by
  59       the driver. It states it as a percentage of the max (non-turbo)
  60       performance level.
  61
  62       no_turbo: Limits the driver to selecting P-State below the turbo
  63       frequency range.
  64
  65       turbo_pct: Displays the percentage of the total performance that
  66       is supported by hardware that is in the turbo range. This number
  67       is independent of whether turbo has been disabled or not.
  68
  69       num_pstates: Displays the number of P-States that are supported
  70       by hardware. This number is independent of whether turbo has
  71       been disabled or not.
  72
  73 For example, if a system has these parameters:
  74         Max 1 core turbo ratio: 0x21 (Max 1 core ratio is the maximum P-State)
  75         Max non turbo ratio: 0x17
  76         Minimum ratio : 0x08 (Here the ratio is called max efficiency ratio)
  77
  78 Sysfs will show :
  79         max_perf_pct:100, which corresponds to 1 core ratio
  80         min_perf_pct:24, max_efficiency_ratio / max 1 Core ratio
  81         no_turbo:0, turbo is not disabled
  82         num_pstates:26 = (max 1 Core ratio - Max Efficiency Ratio + 1)
  83         turbo_pct:39 = (max 1 core ratio - max non turbo ratio) / num_pstates
  84
  85 Refer to "Intel® 64 and IA-32 Architectures Software Developer’s Manual
  86 Volume 3: System Programming Guide" to understand ratios.
  87
  88 There is one more sysfs attribute in /sys/devices/system/cpu/intel_pstate/
  89 that can be used for controlling the operation mode of the driver:
  90
  91       status: Three settings are possible:
  92       "off"     - The driver is not in use at this time.
  93       "active"  - The driver works as a P-state governor (default).
  94       "passive" - The driver works as a regular cpufreq one and collaborates
  95                   with the generic cpufreq governors (it sets P-states as
  96                   requested by those governors).
  97       The current setting is returned by reads from this attribute.  Writing one
  98       of the above strings to it changes the operation mode as indicated by that
  99       string, if possible.  If HW-managed P-states (HWP) are enabled, it is not
 100       possible to change the driver's operation mode and attempts to write to
 101       this attribute will fail.
 102
 103 cpufreq sysfs for Intel P-State
 104
 105 Since this driver registers with cpufreq, cpufreq sysfs is also presented.
 106 There are some important differences, which need to be considered.
 107
 108 scaling_cur_freq: This displays the real frequency which was used during
 109 the last sample period instead of what is requested. Some other cpufreq driver,
 110 like acpi-cpufreq, displays what is requested (Some changes are on the
 111 way to fix this for acpi-cpufreq driver). The same is true for frequencies
 112 displayed at /proc/cpuinfo.
 113
 114 scaling_governor: This displays current active policy. Since each CPU has a
 115 cpufreq sysfs, it is possible to set a scaling governor to each CPU. But this
 116 is not possible with Intel P-States, as there is one common policy for all
 117 CPUs. Here, the last requested policy will be applicable to all CPUs. It is
 118 suggested that one use the cpupower utility to change policy to all CPUs at the
 119 same time.
 120
 121 scaling_setspeed: This attribute can never be used with Intel P-State.
 122
 123 scaling_max_freq/scaling_min_freq: This interface can be used similarly to
 124 the max_perf_pct/min_perf_pct of Intel P-State sysfs. However since frequencies
 125 are converted to nearest possible P-State, this is prone to rounding errors.
 126 This method is not preferred to limit performance.
 127
 128 affected_cpus: Not used
 129 related_cpus: Not used
 130
 131 For contemporary Intel processors, the frequency is controlled by the
 132 processor itself and the P-State exposed to software is related to
 133 performance levels.  The idea that frequency can be set to a single
 134 frequency is fictional for Intel Core processors. Even if the scaling
 135 driver selects a single P-State, the actual frequency the processor
 136 will run at is selected by the processor itself.
 137
 138 Per-CPU limits
 139
 140 The kernel command line option "intel_pstate=per_cpu_perf_limits" forces
 141 the intel_pstate driver to use per-CPU performance limits.  When it is set,
 142 the sysfs control interface described above is subject to limitations.
 143 - The following controls are not available for both read and write
 144         /sys/devices/system/cpu/intel_pstate/max_perf_pct
 145         /sys/devices/system/cpu/intel_pstate/min_perf_pct
 146 - The following controls can be used to set performance limits, as far as the
 147 architecture of the processor permits:
 148         /sys/devices/system/cpu/cpu*/cpufreq/scaling_max_freq
 149         /sys/devices/system/cpu/cpu*/cpufreq/scaling_min_freq
 150         /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
 151 - User can still observe turbo percent and number of P-States from
 152         /sys/devices/system/cpu/intel_pstate/turbo_pct
 153         /sys/devices/system/cpu/intel_pstate/num_pstates
 154 - User can read write system wide turbo status
 155         /sys/devices/system/cpu/no_turbo
 156
 157 Support of energy performance hints
 158 It is possible to provide hints to the HWP algorithms in the processor
 159 to be more performance centric to more energy centric. When the driver
 160 is using HWP, two additional cpufreq sysfs attributes are presented for
 161 each logical CPU.
 162 These attributes are:
 163         - energy_performance_available_preferences
 164         - energy_performance_preference
 165
 166 To get list of supported hints:
 167 $ cat energy_performance_available_preferences
 168     default performance balance_performance balance_power power
 169
 170 The current preference can be read or changed via cpufreq sysfs
 171 attribute "energy_performance_preference". Reading from this attribute
 172 will display current effective setting. User can write any of the valid
 173 preference string to this attribute. User can always restore to power-on
 174 default by writing "default".
 175
 176 Since threads can migrate to different CPUs, this is possible that the
 177 new CPU may have different energy performance preference than the previous
 178 one. To avoid such issues, either threads can be pinned to specific CPUs
 179 or set the same energy performance preference value to all CPUs.
 180
 181 Tuning Intel P-State driver
 182
 183 When the performance can be tuned using PID (Proportional Integral
 184 Derivative) controller, debugfs files are provided for adjusting performance.
 185 They are presented under:
 186 /sys/kernel/debug/pstate_snb/
 187
 188 The PID tunable parameters are:
 189       deadband
 190       d_gain_pct
 191       i_gain_pct
 192       p_gain_pct
 193       sample_rate_ms
 194       setpoint
 195
 196 To adjust these parameters, some understanding of driver implementation is
 197 necessary. There are some tweeks described here, but be very careful. Adjusting
 198 them requires expert level understanding of power and performance relationship.
 199 These limits are only useful when the "powersave" policy is active.
 200
 201 -To make the system more responsive to load changes, sample_rate_ms can
 202 be adjusted  (current default is 10ms).
 203 -To make the system use higher performance, even if the load is lower, setpoint
 204 can be adjusted to a lower number. This will also lead to faster ramp up time
 205 to reach the maximum P-State.
 206 If there are no derivative and integral coefficients, The next P-State will be
 207 equal to:
 208         current P-State - ((setpoint - current cpu load) * p_gain_pct)
 209
 210 For example, if the current PID parameters are (Which are defaults for the core
 211 processors like SandyBridge):
 212       deadband = 0
 213       d_gain_pct = 0
 214       i_gain_pct = 0
 215       p_gain_pct = 20
 216       sample_rate_ms = 10
 217       setpoint = 97
 218
 219 If the current P-State = 0x08 and current load = 100, this will result in the
 220 next P-State = 0x08 - ((97 - 100) * 0.2) = 8.6 (rounded to 9). Here the P-State
 221 goes up by only 1. If during next sample interval the current load doesn't
 222 change and still 100, then P-State goes up by one again. This process will
 223 continue as long as the load is more than the setpoint until the maximum P-State
 224 is reached.
 225
 226 For the same load at setpoint = 60, this will result in the next P-State
 227 = 0x08 - ((60 - 100) * 0.2) = 16
 228 So by changing the setpoint from 97 to 60, there is an increase of the
 229 next P-State from 9 to 16. So this will make processor execute at higher
 230 P-State for the same CPU load. If the load continues to be more than the
 231 setpoint during next sample intervals, then P-State will go up again till the
 232 maximum P-State is reached. But the ramp up time to reach the maximum P-State
 233 will be much faster when the setpoint is 60 compared to 97.
 234
 235 Debugging Intel P-State driver
 236
 237 Event tracing
 238 To debug P-State transition, the Linux event tracing interface can be used.
 239 There are two specific events, which can be enabled (Provided the kernel
 240 configs related to event tracing are enabled).
 241
 242 # cd /sys/kernel/debug/tracing/
 243 # echo 1 > events/power/pstate_sample/enable
 244 # echo 1 > events/power/cpu_frequency/enable
 245 # cat trace
 246 gnome-terminal--4510  [001] ..s.  1177.680733: pstate_sample: core_busy=107
 247         scaled=94 from=26 to=26 mperf=1143818 aperf=1230607 tsc=29838618
 248                 freq=2474476
 249 cat-5235  [002] ..s.  1177.681723: cpu_frequency: state=2900000 cpu_id=2
 250
 251
 252 Using ftrace
 253
 254 If function level tracing is required, the Linux ftrace interface can be used.
 255 For example if we want to check how often a function to set a P-State is
 256 called, we can set ftrace filter to intel_pstate_set_pstate.
 257
 258 # cd /sys/kernel/debug/tracing/
 259 # cat available_filter_functions | grep -i pstate
 260 intel_pstate_set_pstate
 261 intel_pstate_cpu_init
 262 ...
 263
 264 # echo intel_pstate_set_pstate > set_ftrace_filter
 265 # echo function > current_tracer
 266 # cat trace | head -15
 267 # tracer: function
 268 #
 269 # entries-in-buffer/entries-written: 80/80   #P:4
 270 #
 271 #                              _-----=> irqs-off
 272 #                             / _----=> need-resched
 273 #                            | / _---=> hardirq/softirq
 274 #                            || / _--=> preempt-depth
 275 #                            ||| /     delay
 276 #           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION
 277 #              | |       |   ||||       |         |
 278             Xorg-3129  [000] ..s.  2537.644844: intel_pstate_set_pstate <-intel_pstate_timer_func
 279  gnome-terminal--4510  [002] ..s.  2537.649844: intel_pstate_set_pstate <-intel_pstate_timer_func
 280      gnome-shell-3409  [001] ..s.  2537.650850: intel_pstate_set_pstate <-intel_pstate_timer_func
 281           <idle>-0     [000] ..s.  2537.654843: intel_pstate_set_pstate <-intel_pstate_timer_func