0001 .\" This page Copyright (C) 2010 - 2015 Len Brown <len.brown@intel.com>
0002 .\" Distributed under the GPL, Copyleft 1994.
0003 .TH X86_ENERGY_PERF_POLICY 8
0004 .SH NAME
0005 x86_energy_perf_policy \- Manage Energy vs. Performance Policy via x86 Model Specific Registers
0006 .SH SYNOPSIS
0007 .B x86_energy_perf_policy
0008 .RB "[ options ] [ scope ] [field \ value]"
0009 .br
0010 .RB "scope: \-\-cpu\ cpu-list | \-\-pkg\ pkg-list"
0011 .br
0012 .RB "cpu-list, pkg-list: # | #,# | #-# | all"
0013 .br
0014 .RB "field: \-\-all | \-\-epb | \-\-hwp-epp | \-\-hwp-min | \-\-hwp-max | \-\-hwp-desired"
0015 .br
0016 .RB "other: (\-\-force | \-\-hwp-enable | \-\-turbo-enable) value)"
0017 .br
0018 .RB "value: # | default | performance | balance-performance | balance-power | power"
0019 .SH DESCRIPTION
0020 \fBx86_energy_perf_policy\fP
0021 displays and updates energy-performance policy settings specific to
0022 Intel Architecture Processors. Settings are accessed via Model Specific Register (MSR)
0023 updates, no matter if the Linux cpufreq sub-system is enabled or not.
0024
0025 Policy in MSR_IA32_ENERGY_PERF_BIAS (EPB)
0026 may affect a wide range of hardware decisions,
0027 such as how aggressively the hardware enters and exits CPU idle states (C-states)
0028 and Processor Performance States (P-states).
0029 This policy hint does not replace explicit OS C-state and P-state selection.
0030 Rather, it tells the hardware how aggressively to implement those selections.
0031 Further, it allows the OS to influence energy/performance trade-offs where there
0032 is no software interface, such as in the opportunistic "turbo-mode" P-state range.
0033 Note that MSR_IA32_ENERGY_PERF_BIAS is defined per CPU,
0034 but some implementations
0035 share a single MSR among all CPUs in each processor package.
0036 On those systems, a write to EPB on one processor will
0037 be visible, and will have an effect, on all CPUs
0038 in the same processor package.
0039
0040 Hardware P-States (HWP) are effectively an expansion of hardware
0041 P-state control from the opportunistic turbo-mode P-state range
0042 to include the entire range of available P-states.
0043 On Broadwell Xeon, the initial HWP implementation, EPB influenced HWP.
0044 That influence was removed in subsequent generations,
0045 where it was moved to the
0046 Energy_Performance_Preference (EPP) field in
0047 a pair of dedicated MSRs -- MSR_IA32_HWP_REQUEST and MSR_IA32_HWP_REQUEST_PKG.
0048
0049 EPP is the most commonly managed knob in HWP mode,
0050 but MSR_IA32_HWP_REQUEST also allows the user to specify
0051 minimum-frequency for Quality-of-Service,
0052 and maximum-frequency for power-capping.
0053 MSR_IA32_HWP_REQUEST is defined per-CPU.
0054
0055 MSR_IA32_HWP_REQUEST_PKG has the same capability as MSR_IA32_HWP_REQUEST,
0056 but it can simultaneously set the default policy for all CPUs within a package.
0057 A bit in per-CPU MSR_IA32_HWP_REQUEST indicates whether it is
0058 over-ruled-by or exempt-from MSR_IA32_HWP_REQUEST_PKG.
0059
0060 MSR_HWP_CAPABILITIES shows the default values for the fields
0061 in MSR_IA32_HWP_REQUEST. It is displayed when no values
0062 are being written.
0063
0064 .SS SCOPE OPTIONS
0065 .PP
0066 \fB-c, --cpu\fP Operate on the MSR_IA32_HWP_REQUEST for each CPU in a CPU-list.
0067 The CPU-list may be comma-separated CPU numbers, with dash for range
0068 or the string "all". Eg. '--cpu 1,4,6-8' or '--cpu all'.
0069 When --cpu is used, \fB--hwp-use-pkg\fP is available, which specifies whether the per-cpu
0070 MSR_IA32_HWP_REQUEST should be over-ruled by MSR_IA32_HWP_REQUEST_PKG (1),
0071 or exempt from MSR_IA32_HWP_REQUEST_PKG (0).
0072
0073 \fB-p, --pkg\fP Operate on the MSR_IA32_HWP_REQUEST_PKG for each package in the package-list.
0074 The list is a string of individual package numbers separated
0075 by commas, and or ranges of package numbers separated by a dash,
0076 or the string "all".
0077 For example '--pkg 1,3' or '--pkg all'
0078
0079 .SS VALUE OPTIONS
0080 .PP
0081 .I normal | default
0082 Set a policy with a normal balance between performance and energy efficiency.
0083 The processor will tolerate minor performance compromise
0084 for potentially significant energy savings.
0085 This is a reasonable default for most desktops and servers.
0086 "default" is a synonym for "normal".
0087 .PP
0088 .I performance
0089 Set a policy for maximum performance,
0090 accepting no performance sacrifice for the benefit of energy efficiency.
0091 .PP
0092 .I balance-performance
0093 Set a policy with a high priority on performance,
0094 but allowing some performance loss to benefit energy efficiency.
0095 .PP
0096 .I balance-power
0097 Set a policy where the performance and power are balanced.
0098 This is the default.
0099 .PP
0100 .I power
0101 Set a policy where the processor can accept
0102 a measurable performance impact to maximize energy efficiency.
0103
0104 .PP
0105 The following table shows the mapping from the value strings above to actual MSR values.
0106 This mapping is defined in the Linux-kernel header, msr-index.h.
0107
0108 .nf
0109 VALUE STRING EPB EPP
0110 performance 0 0
0111 balance-performance 4 128
0112 normal, default 6 128
0113 balance-power 8 192
0114 power 15 255
0115 .fi
0116 .PP
0117 For MSR_IA32_HWP_REQUEST performance fields
0118 (--hwp-min, --hwp-max, --hwp-desired), the value option
0119 is in units of 100 MHz, Eg. 12 signifies 1200 MHz.
0120
0121 .SS FIELD OPTIONS
0122 \fB-a, --all value-string\fP Sets all EPB and EPP and HWP limit fields to the value associated with
0123 the value-string. In addition, enables turbo-mode and HWP-mode, if they were previous disabled.
0124 Thus "--all normal" will set a system without cpufreq into a well known configuration.
0125 .PP
0126 \fB-B, --epb\fP set EPB per-core or per-package.
0127 See value strings in the table above.
0128 .PP
0129 \fB-d, --debug\fP debug increases verbosity. By default
0130 x86_energy_perf_policy is silent for updates,
0131 and verbose for read-only mode.
0132 .PP
0133 \fB-P, --hwp-epp\fP set HWP.EPP per-core or per-package.
0134 See value strings in the table above.
0135 .PP
0136 \fB-m, --hwp-min\fP request HWP to not go below the specified core/bus ratio.
0137 The "default" is the value found in IA32_HWP_CAPABILITIES.min.
0138 .PP
0139 \fB-M, --hwp-max\fP request HWP not exceed a the specified core/bus ratio.
0140 The "default" is the value found in IA32_HWP_CAPABILITIES.max.
0141 .PP
0142 \fB-D, --hwp-desired\fP request HWP 'desired' frequency.
0143 The "normal" setting is 0, which
0144 corresponds to 'full autonomous' HWP control.
0145 Non-zero performance values request a specific performance
0146 level on this processor, specified in multiples of 100 MHz.
0147 .PP
0148 \fB-w, --hwp-window\fP specify integer number of microsec
0149 in the sliding window that HWP uses to maintain average frequency.
0150 This parameter is meaningful only when the "desired" field above is non-zero.
0151 Default is 0, allowing the HW to choose.
0152 .SH OTHER OPTIONS
0153 .PP
0154 \fB-f, --force\fP writes the specified values without bounds checking.
0155 .PP
0156 \fB-U, --hwp-use-pkg\fP (0 | 1), when used in conjunction with --cpu,
0157 indicates whether the per-CPU MSR_IA32_HWP_REQUEST should be overruled (1)
0158 or exempt (0) from per-Package MSR_IA32_HWP_REQUEST_PKG settings.
0159 The default is exempt.
0160 .PP
0161 \fB-H, --hwp-enable\fP enable HardWare-P-state (HWP) mode. Once enabled, system RESET is required to disable HWP mode.
0162 .PP
0163 \fB-t, --turbo-enable\fP enable (1) or disable (0) turbo mode.
0164 .PP
0165 \fB-v, --version\fP print version and exit.
0166 .PP
0167 If no request to change policy is made,
0168 the default behavior is to read
0169 and display the current system state,
0170 including the default capabilities.
0171 .SH WARNING
0172 .PP
0173 This utility writes directly to Model Specific Registers.
0174 There is no locking or coordination should this utility
0175 be used to modify HWP limit fields at the same time that
0176 intel_pstate's sysfs attributes access the same MSRs.
0177 .PP
0178 Note that --hwp-desired and --hwp-window are considered experimental.
0179 Future versions of Linux reserve the right to access these
0180 fields internally -- potentially conflicting with user-space access.
0181 .SH EXAMPLE
0182 .nf
0183 # sudo x86_energy_perf_policy
0184 cpu0: EPB 6
0185 cpu0: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
0186 cpu0: HWP_CAP: low 1 eff 8 guar 27 high 35
0187 cpu1: EPB 6
0188 cpu1: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
0189 cpu1: HWP_CAP: low 1 eff 8 guar 27 high 35
0190 cpu2: EPB 6
0191 cpu2: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
0192 cpu2: HWP_CAP: low 1 eff 8 guar 27 high 35
0193 cpu3: EPB 6
0194 cpu3: HWP_REQ: min 6 max 35 des 0 epp 128 window 0x0 (0*10^0us) use_pkg 0
0195 cpu3: HWP_CAP: low 1 eff 8 guar 27 high 35
0196 .fi
0197 .SH NOTES
0198 .B "x86_energy_perf_policy"
0199 runs only as root.
0200 .SH FILES
0201 .ta
0202 .nf
0203 /dev/cpu/*/msr
0204 .fi
0205 .SH "SEE ALSO"
0206 .nf
0207 msr(4)
0208 Intel(R) 64 and IA-32 Architectures Software Developer's Manual
0209 .fi
0210 .PP
0211 .SH AUTHORS
0212 .nf
0213 Len Brown
