1 .\" Copyright (c) 2005 Nate Lawson
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd CPU frequency control framework
38 .Fn cpufreq_levels "device_t dev" "struct cf_level *levels" "int *count"
40 .Fn cpufreq_set "device_t dev" "const struct cf_level *level" "int priority"
42 .Fn cpufreq_get "device_t dev" "struct cf_level *level"
44 .Fo cpufreq_drv_settings
46 .Fa "struct cf_setting *sets"
50 .Fn cpufreq_drv_type "device_t dev" "int *type"
52 .Fn cpufreq_drv_set "device_t dev" "const struct cf_setting *set"
54 .Fn cpufreq_drv_get "device_t dev" "struct cf_setting *set"
58 driver provides a unified kernel and user interface to CPU frequency
60 It combines multiple drivers offering different settings into a single
61 interface of all possible levels.
62 Users can access this interface directly via
65 .Pa /etc/rc.d/power_profile
66 that it should switch settings when the AC line state changes via
69 These settings may be overridden by kernel drivers requesting alternate
71 If this occurs, the original values will be restored once the condition
72 has passed (e.g., the system has cooled sufficiently).
73 If a sysctl cannot be set due to an override condition, it will return
76 The frequency cannot be changed if TSC is in use as the timecounter and the
77 hardware does not support invariant TSC.
78 This is because the timecounter system needs to use a source that has a
80 (On invariant TSC hardware, the TSC runs at the P0 rate regardless of the
82 Modern hardware mostly has invariant TSC.
83 The timecounter source can be changed with the
84 .Pa kern.timecounter.hardware
86 Available modes are in
87 .Pa kern.timecounter.choice
89 .Bl -tag -width indent
90 .It Va dev.cpu.%d.freq
91 Current active CPU frequency in MHz.
92 .It Va dev.cpu.%d.freq_driver
95 driver used by this cpu.
96 .It Va dev.cpu.%d.freq_levels
97 Currently available levels for the CPU (frequency/power usage).
98 Values are in units of MHz and milliwatts.
99 .It Va dev.DEVICE.%d.freq_settings
100 Currently available settings for the driver (frequency/power usage).
101 Values are in units of MHz and milliwatts.
102 This is helpful for understanding which settings are offered by which
103 driver for debugging purposes.
104 .It Va debug.cpufreq.lowest
105 Lowest CPU frequency in MHz to offer to users.
106 This setting is also accessible via a tunable with the same name.
107 This can be used to disable very low levels that may be unusable on
109 .It Va debug.cpufreq.verbose
110 Print verbose messages.
111 This setting is also accessible via a tunable with the same name.
112 .It Va debug.hwpstate_pstate_limit
113 If enabled, the AMD hwpstate driver limits administrative control of P-states
116 to the value in the 0xc0010061 MSR, known as "PStateCurLim[CurPstateLimit]."
117 It is disabled (0) by default.
118 On some hardware, the limit register seems to simply follow the configured
119 P-state, which results in the inability to ever raise the P-state back to P0
120 from a reduced frequency state.
122 .Sh SUPPORTED DRIVERS
123 The following device drivers offer absolute frequency control via the
126 Usually, only one of these can be active at a time.
128 .Bl -tag -compact -width "hwpstate_intel(4)"
130 ACPI CPU performance states
132 Intel Enhanced SpeedStep
134 AMD Cool'n'Quiet2 used in K10 through Family 17h
135 .It Xr hwpstate_intel 4
136 Intel SpeedShift driver
138 Intel SpeedStep for ICH
140 AMD PowerNow!\& and Cool'n'Quiet for K7 and K8
142 Intel SMI-based SpeedStep for PIIX4
145 The following device drivers offer relative frequency control and
146 have an additive effect:
148 .Bl -tag -compact -width "acpi_throttle"
152 Pentium 4 Thermal Control Circuitry
155 Kernel components can query and set CPU frequencies through the
158 This involves obtaining a
162 to get the currently available frequency levels,
163 checking the current level with
165 and setting a new one from the list with
167 Each level may actually reference more than one
169 driver but kernel components do not need to be aware of this.
173 .Vt "struct cf_level"
174 provides a summary of the frequency and power for this level.
175 Unknown or irrelevant values are set to
176 .Dv CPUFREQ_VAL_UNKNOWN .
182 device and an empty array of
186 value should be set to the number of levels available and after the
187 function completes, will be set to the actual number of levels returned.
188 If there are more levels than
190 will allow, it should return
195 method takes a pointer to space to store a
197 After successful completion, the output will be the current active level
198 and is equal to one of the levels returned by
203 method takes a pointer a
205 and attempts to activate it.
209 .Dv CPUFREQ_PRIO_KERN )
212 whether to override previous settings while activating this level.
215 is higher than the current active level, that level will be saved and
216 overridden with the new level.
217 If a level is already saved, the new level is set without overwriting
218 the older saved level.
224 the saved level will be restored.
225 If there is no saved level,
231 is lower than the current active level's priority, this method returns
234 Kernel drivers offering hardware-specific CPU frequency control export
235 their individual settings through the
238 This involves implementing these methods:
239 .Fn cpufreq_drv_settings ,
240 .Fn cpufreq_drv_type ,
241 .Fn cpufreq_drv_set ,
243 .Fn cpufreq_drv_get .
244 Additionally, the driver must attach a device as a child of a CPU
245 device so that these methods can be called by the
250 .Fn cpufreq_drv_settings
251 method returns an array of currently available settings, each of type
252 .Vt "struct cf_setting" .
253 The driver should set unknown or irrelevant values to
254 .Dv CPUFREQ_VAL_UNKNOWN .
255 All the following elements for each setting should be returned:
258 int freq; /* CPU clock in MHz or 100ths of a percent. */
259 int volts; /* Voltage in mV. */
260 int power; /* Power consumed in mW. */
261 int lat; /* Transition latency in us. */
262 device_t dev; /* Driver providing this setting. */
266 On entry to this method,
268 contains the number of settings that can be returned.
269 On successful completion, the driver sets it to the actual number of
271 If the driver offers more settings than
273 will allow, it should return
278 method indicates the type of settings it offers, either
279 .Dv CPUFREQ_TYPE_ABSOLUTE
281 .Dv CPUFREQ_TYPE_RELATIVE .
282 Additionally, the driver may set the
283 .Dv CPUFREQ_FLAG_INFO_ONLY
284 flag if the settings it provides are information for other drivers only
285 and cannot be passed to
291 method takes a driver setting and makes it active.
292 If the setting is invalid or not currently available, it should return
297 method returns the currently-active driver setting.
299 .Vt "struct cf_setting"
300 returned must be valid for passing to
301 .Fn cpufreq_drv_set ,
302 including all elements being filled out correctly.
303 If the driver cannot infer the current setting
304 (even by estimating it with
305 .Fn cpu_est_clockrate )
306 then it should set all elements to
307 .Dv CPUFREQ_VAL_UNKNOWN .
321 The following drivers have not yet been converted to the
326 Notification of CPU and bus frequency changes is not implemented yet.
328 When multiple CPUs offer frequency control, they cannot be set to different
329 levels and must all offer the same frequency settings.