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