tools/power/x86/x86_energy_perf_policy/x86_energy_perf_policy.8

   1 .\"  This page Copyright (C) 2010 - 2015 Len Brown <len.brown@intel.com>
   2 .\"  Distributed under the GPL, Copyleft 1994.
   3 .TH X86_ENERGY_PERF_POLICY 8
   4 .SH NAME
   5 x86_energy_perf_policy \- Manage Energy vs. Performance Policy via x86 Model Specific Registers
   6 .SH SYNOPSIS
   7 .B x86_energy_perf_policy
   8 .RB "[ options ] [ scope ] [field \ value]"
   9 .br
  10 .RB "scope: \-\-cpu\ cpu-list | \-\-pkg\ pkg-list"
  11 .br
  12 .RB "cpu-list, pkg-list: # | #,# | #-# | all"
  13 .br
  14 .RB "field: \-\-all | \-\-epb | \-\-hwp-epp | \-\-hwp-min | \-\-hwp-max | \-\-hwp-desired"
  15 .br
  16 .RB "other: (\-\-force | \-\-hwp-enable | \-\-turbo-enable)  value)"
  17 .br
  18 .RB "value: # | default | performance | balance-performance | balance-power | power"
  19 .SH DESCRIPTION
  20 \fBx86_energy_perf_policy\fP
  21 displays and updates energy-performance policy settings specific to
  22 Intel Architecture Processors.  Settings are accessed via Model Specific Register (MSR)
  23 updates, no matter if the Linux cpufreq sub-system is enabled or not.
  24
  25 Policy in MSR_IA32_ENERGY_PERF_BIAS (EPB)
  26 may affect a wide range of hardware decisions,
  27 such as how aggressively the hardware enters and exits CPU idle states (C-states)
  28 and Processor Performance States (P-states).
  29 This policy hint does not replace explicit OS C-state and P-state selection.
  30 Rather, it tells the hardware how aggressively to implement those selections.
  31 Further, it allows the OS to influence energy/performance trade-offs where there
  32 is no software interface, such as in the opportunistic "turbo-mode" P-state range.
  33 Note that MSR_IA32_ENERGY_PERF_BIAS is defined per CPU,
  34 but some implementations
  35 share a single MSR among all CPUs in each processor package.
  36 On those systems, a write to EPB on one processor will
  37 be visible, and will have an effect, on all CPUs
  38 in the same processor package.
  39
  40 Hardware P-States (HWP) are effectively an expansion of hardware
  41 P-state control from the opportunistic turbo-mode P-state range
  42 to include the entire range of available P-states.
  43 On Broadwell Xeon, the initial HWP implementation, EBP influenced HWP.
  44 That influence was removed in subsequent generations,
  45 where it was moved to the
  46 Energy_Performance_Preference (EPP) field in
  47 a pair of dedicated MSRs -- MSR_IA32_HWP_REQUEST and MSR_IA32_HWP_REQUEST_PKG.
  48
  49 EPP is the most commonly managed knob in HWP mode,
  50 but MSR_IA32_HWP_REQUEST also allows the user to specify
  51 minimum-frequency for Quality-of-Service,
  52 and maximum-frequency for power-capping.
  53 MSR_IA32_HWP_REQUEST is defined per-CPU.
  54
  55 MSR_IA32_HWP_REQUEST_PKG has the same capability as MSR_IA32_HWP_REQUEST,
  56 but it can simultaneously set the default policy for all CPUs within a package.
  57 A bit in per-CPU MSR_IA32_HWP_REQUEST indicates whether it is
  58 over-ruled-by or exempt-from MSR_IA32_HWP_REQUEST_PKG.
  59
  60 MSR_HWP_CAPABILITIES shows the default values for the fields
  61 in MSR_IA32_HWP_REQUEST.  It is displayed when no values
  62 are being written.
  63
  64 .SS SCOPE OPTIONS
  65 .PP
  66 \fB-c, --cpu\fP Operate on the MSR_IA32_HWP_REQUEST for each CPU in a CPU-list.
  67 The CPU-list may be comma-separated CPU numbers, with dash for range
  68 or the string "all".  Eg. '--cpu 1,4,6-8' or '--cpu all'.
  69 When --cpu is used, \fB--hwp-use-pkg\fP is available, which specifies whether the per-cpu
  70 MSR_IA32_HWP_REQUEST should be over-ruled by MSR_IA32_HWP_REQUEST_PKG (1),
  71 or exempt from MSR_IA32_HWP_REQUEST_PKG (0).
  72
  73 \fB-p, --pkg\fP Operate on the MSR_IA32_HWP_REQUEST_PKG for each package in the package-list.
  74 The list is a string of individual package numbers separated
  75 by commas, and or ranges of package numbers separated by a dash,
  76 or the string "all".
  77 For example '--pkg 1,3' or '--pkg all'
  78
  79 .SS VALUE OPTIONS
  80 .PP
  81 .I normal | default
  82 Set a policy with a normal balance between performance and energy efficiency.
  83 The processor will tolerate minor performance compromise
  84 for potentially significant energy savings.
  85 This is a reasonable default for most desktops and servers.
  86 "default" is a synonym for "normal".
  87 .PP
  88 .I performance
  89 Set a policy for maximum performance,
  90 accepting no performance sacrifice for the benefit of energy efficiency.
  91 .PP
  92 .I balance-performance
  93 Set a policy with a high priority on performance,
  94 but allowing some performance loss to benefit energy efficiency.
  95 .PP
  96 .I balance-power
  97 Set a policy where the performance and power are balanced.
  98 This is the default.
  99 .PP
 100 .I power
 101 Set a policy where the processor can accept
 102 a measurable performance impact to maximize energy efficiency.
 103
 104 .PP
 105 The following table shows the mapping from the value strings above to actual MSR values.
 106 This mapping is defined in the Linux-kernel header, msr-index.h.
 107
 108 .nf
 109 VALUE STRING            EPB     EPP
 110 performance             0       0
 111 balance-performance     4       128
 112 normal, default         6       128
 113 balance-power           8       192
 114 power                   15      255
 115 .fi
 116 .PP
 117 For MSR_IA32_HWP_REQUEST performance fields
 118 (--hwp-min, --hwp-max, --hwp-desired), the value option
 119 is in units of 100 MHz, Eg. 12 signifies 1200 MHz.
 120
 121 .SS FIELD OPTIONS
 122 \fB-a, --all value-string\fP Sets all EPB and EPP and HWP limit fields to the value associated with
 123 the value-string.  In addition, enables turbo-mode and HWP-mode, if they were previous disabled.
 124 Thus "--all normal" will set a system without cpufreq into a well known configuration.
 125 .PP
 126 \fB-B, --epb\fP set EPB per-core or per-package.
 127 See value strings in the table above.
 128 .PP
 129 \fB-d, --debug\fP debug increases verbosity.  By default
 130 x86_energy_perf_policy is silent for updates,
 131 and verbose for read-only mode.
 132 .PP
 133 \fB-P, --hwp-epp\fP set HWP.EPP per-core or per-package.
 134 See value strings in the table above.
 135 .PP
 136 \fB-m, --hwp-min\fP request HWP to not go below the specified core/bus ratio.
 137 The "default" is the value found in IA32_HWP_CAPABILITIES.min.
 138 .PP
 139 \fB-M, --hwp-max\fP request HWP not exceed a the specified core/bus ratio.
 140 The "default" is the value found in IA32_HWP_CAPABILITIES.max.
 141 .PP
 142 \fB-D, --hwp-desired\fP request HWP 'desired' frequency.
 143 The "normal" setting is 0, which
 144 corresponds to 'full autonomous' HWP control.
 145 Non-zero performance values request a specific performance
 146 level on this processor, specified in multiples of 100 MHz.
 147 .PP
 148 \fB-w, --hwp-window\fP specify integer number of microsec
 149 in the sliding window that HWP uses to maintain average frequency.
 150 This parameter is meaningful only when the "desired" field above is non-zero.
 151 Default is 0, allowing the HW to choose.
 152 .SH OTHER OPTIONS
 153 .PP
 154 \fB-f, --force\fP writes the specified values without bounds checking.
 155 .PP
 156 \fB-U, --hwp-use-pkg\fP (0 | 1), when used in conjunction with --cpu,
 157 indicates whether the per-CPU MSR_IA32_HWP_REQUEST should be overruled (1)
 158 or exempt (0) from per-Package MSR_IA32_HWP_REQUEST_PKG settings.
 159 The default is exempt.
 160 .PP
 161 \fB-H, --hwp-enable\fP enable HardWare-P-state (HWP) mode.  Once enabled, system RESET is required to disable HWP mode.
 162 .PP
 163 \fB-t, --turbo-enable\fP enable (1) or disable (0) turbo mode.
 164 .PP
 165 \fB-v, --version\fP print version and exit.
 166 .PP
 167 If no request to change policy is made,
 168 the default behavior is to read
 169 and display the current system state,
 170 including the default capabilities.
 171 .SH WARNING
 172 .PP
 173 This utility writes directly to Model Specific Registers.
 174 There is no locking or coordination should this utility
 175 be used to modify HWP limit fields at the same time that
 176 intel_pstate's sysfs attributes access the same MSRs.
 177 .PP
 178 Note that --hwp-desired and --hwp-window are considered experimental.
 179 Future versions of Linux reserve the right to access these
 180 fields internally -- potentially conflicting with user-space access.
 181 .SH EXAMPLE
 182 .nf
 183 # sudo x86_energy_perf_policy
 184 cpu0: EPB 6
 185 cpu0: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
 186 cpu0: HWP_CAP: low 1 eff 8 guar 27 high 35
 187 cpu1: EPB 6
 188 cpu1: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
 189 cpu1: HWP_CAP: low 1 eff 8 guar 27 high 35
 190 cpu2: EPB 6
 191 cpu2: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
 192 cpu2: HWP_CAP: low 1 eff 8 guar 27 high 35
 193 cpu3: EPB 6
 194 cpu3: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
 195 cpu3: HWP_CAP: low 1 eff 8 guar 27 high 35
 196 .fi
 197 .SH NOTES
 198 .B "x86_energy_perf_policy"
 199 runs only as root.
 200 .SH FILES
 201 .ta
 202 .nf
 203 /dev/cpu/*/msr
 204 .fi
 205 .SH "SEE ALSO"
 206 .nf
 207 msr(4)
 208 Intel(R) 64 and IA-32 Architectures Software Developer's Manual
 209 .fi
 210 .PP
 211 .SH AUTHORS
 212 .nf
 213 Len Brown