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