| blob | aa1da043fc42bbda01bdaba21f515fde69a626dd |
1 .\" Copyright (c) 2005 Nate Lawson
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
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.
12 .\"
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
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD$
26 .\"
27 .Dd March 3, 2006
28 .Dt CPUFREQ 4
29 .Os
30 .Sh NAME
31 .Nm cpufreq
32 .Nd CPU frequency control framework
33 .Sh SYNOPSIS
34 .Cd "device cpufreq"
35 .Pp
36 .In sys/cpu.h
37 .Ft int
38 .Fn cpufreq_levels "device_t dev" "struct cf_level *levels" "int *count"
39 .Ft int
40 .Fn cpufreq_set "device_t dev" "const struct cf_level *level" "int priority"
41 .Ft int
42 .Fn cpufreq_get "device_t dev" "struct cf_level *level"
43 .Ft int
44 .Fo cpufreq_drv_settings
45 .Fa "device_t dev"
46 .Fa "struct cf_setting *sets"
47 .Fa "int *count"
48 .Fc
49 .Ft int
50 .Fn cpufreq_drv_type "device_t dev" "int *type"
51 .Ft int
52 .Fn cpufreq_drv_set "device_t dev" "const struct cf_setting *set"
53 .Ft int
54 .Fn cpufreq_drv_get "device_t dev" "struct cf_setting *set"
55 .Sh DESCRIPTION
56 The
57 .Nm
58 driver provides a unified kernel and user interface to CPU frequency
59 control drivers.
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
63 .Xr sysctl 8
64 or by indicating to
65 .Pa /etc/rc.d/power_profile
66 that it should switch settings when the AC line state changes via
67 .Xr rc.conf 5 .
68 .Sh SYSCTL VARIABLES
69 These settings may be overridden by kernel drivers requesting alternate
70 settings.
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
74 .Er EPERM .
75 .Pp
76 The frequency cannot be changed if TSC is in use as the timecounter.
77 This is because the timecounter system needs to use a source that has a
78 constant rate.
79 The timecounter source can be changed with the
80 .Pa kern.timecounter.hardware
81 sysctl.
82 Available modes are in
83 .Pa kern.timecounter.choice
84 sysctl entry.
85 .Bl -tag -width indent
86 .It Va dev.cpu.%d.freq
87 Current active CPU frequency in MHz.
88 .It Va dev.cpu.%d.freq_levels
89 Currently available levels for the CPU (frequency/power usage).
90 Values are in units of MHz and milliwatts.
91 .It Va dev.DEVICE.%d.freq_settings
92 Currently available settings for the driver (frequency/power usage).
93 Values are in units of MHz and milliwatts.
94 This is helpful for understanding which settings are offered by which
95 driver for debugging purposes.
96 .It Va debug.cpufreq.lowest
97 Lowest CPU frequency in MHz to offer to users.
98 This setting is also accessible via a tunable with the same name.
99 This can be used to disable very low levels that may be unusable on
100 some systems.
101 .It Va debug.cpufreq.verbose
102 Print verbose messages.
103 This setting is also accessible via a tunable with the same name.
104 .El
105 .Sh SUPPORTED DRIVERS
106 The following device drivers offer absolute frequency control via the
107 .Nm
108 interface.
109 Usually, only one of these can be active at a time.
110 .Pp
111 .Bl -tag -compact -width ".Pa acpi_perf"
112 .It Pa acpi_perf
113 ACPI CPU performance states
114 .It Pa est
115 Intel Enhanced SpeedStep
116 .It Pa ichss
117 Intel SpeedStep for ICH
118 .It Pa powernow
119 AMD PowerNow!\& and Cool'n'Quiet for K7 and K8
120 .It Pa smist
121 Intel SMI-based SpeedStep for PIIX4
122 .El
123 .Pp
124 The following device drivers offer relative frequency control and
125 have an additive effect:
126 .Pp
127 .Bl -tag -compact -width ".Pa acpi_throttle"
128 .It Pa acpi_throttle
129 ACPI CPU throttling
130 .It Pa p4tcc
131 Pentium 4 Thermal Control Circuitry
132 .El
133 .Sh KERNEL INTERFACE
134 Kernel components can query and set CPU frequencies through the
135 .Nm
136 kernel interface.
137 This involves obtaining a
138 .Nm
139 device, calling
140 .Fn cpufreq_levels
141 to get the currently available frequency levels,
142 checking the current level with
143 .Fn cpufreq_get ,
144 and setting a new one from the list with
145 .Fn cpufreq_set .
146 Each level may actually reference more than one
147 .Nm
148 driver but kernel components do not need to be aware of this.
149 The
150 .Va total_set
151 element of
152 .Vt "struct cf_level"
153 provides a summary of the frequency and power for this level.
154 Unknown or irrelevant values are set to
155 .Dv CPUFREQ_VAL_UNKNOWN .
156 .Pp
157 The
158 .Fn cpufreq_levels
159 method takes a
160 .Nm
161 device and an empty array of
162 .Fa levels .
163 The
164 .Fa count
165 value should be set to the number of levels available and after the
166 function completes, will be set to the actual number of levels returned.
167 If there are more levels than
168 .Fa count
169 will allow, it should return
170 .Er E2BIG .
171 .Pp
172 The
173 .Fn cpufreq_get
174 method takes a pointer to space to store a
175 .Fa level .
176 After successful completion, the output will be the current active level
177 and is equal to one of the levels returned by
178 .Fn cpufreq_levels .
179 .Pp
180 The
181 .Fn cpufreq_set
182 method takes a pointer a
183 .Fa level
184 and attempts to activate it.
185 The
186 .Fa priority
187 (i.e.,
188 .Dv CPUFREQ_PRIO_KERN )
189 tells
190 .Nm
191 whether to override previous settings while activating this level.
192 If
193 .Fa priority
194 is higher than the current active level, that level will be saved and
195 overridden with the new level.
196 If a level is already saved, the new level is set without overwriting
197 the older saved level.
198 If
199 .Fn cpufreq_set
200 is called with a
201 .Dv NULL
202 .Fa level ,
203 the saved level will be restored.
204 If there is no saved level,
205 .Fn cpufreq_set
206 will return
207 .Er ENXIO .
208 If
209 .Fa priority
210 is lower than the current active level's priority, this method returns
211 .Er EPERM .
212 .Sh DRIVER INTERFACE
213 Kernel drivers offering hardware-specific CPU frequency control export
214 their individual settings through the
215 .Nm
216 driver interface.
217 This involves implementing these methods:
218 .Fn cpufreq_drv_settings ,
219 .Fn cpufreq_drv_type ,
220 .Fn cpufreq_drv_set ,
221 and
222 .Fn cpufreq_drv_get .
223 Additionally, the driver must attach a device as a child of a CPU
224 device so that these methods can be called by the
225 .Nm
226 framework.
227 .Pp
228 The
229 .Fn cpufreq_drv_settings
230 method returns an array of currently available settings, each of type
231 .Vt "struct cf_setting" .
232 The driver should set unknown or irrelevant values to
233 .Dv CPUFREQ_VAL_UNKNOWN .
234 All the following elements for each setting should be returned:
235 .Bd -literal
236 struct cf_setting {
237 int freq; /* CPU clock in Mhz or 100ths of a percent. */
238 int volts; /* Voltage in mV. */
239 int power; /* Power consumed in mW. */
240 int lat; /* Transition latency in us. */
241 device_t dev; /* Driver providing this setting. */
242 };
243 .Ed
244 .Pp
245 On entry to this method,
246 .Fa count
247 contains the number of settings that can be returned.
248 On successful completion, the driver sets it to the actual number of
249 settings returned.
250 If the driver offers more settings than
251 .Fa count
252 will allow, it should return
253 .Er E2BIG .
254 .Pp
255 The
256 .Fn cpufreq_drv_type
257 method indicates the type of settings it offers, either
258 .Dv CPUFREQ_TYPE_ABSOLUTE
259 or
260 .Dv CPUFREQ_TYPE_RELATIVE .
261 Additionally, the driver may set the
262 .Dv CPUFREQ_FLAG_INFO_ONLY
263 flag if the settings it provides are information for other drivers only
264 and cannot be passed to
265 .Fn cpufreq_drv_set
266 to activate them.
267 .Pp
268 The
269 .Fn cpufreq_drv_set
270 method takes a driver setting and makes it active.
271 If the setting is invalid or not currently available, it should return
272 .Er EINVAL .
273 .Pp
274 The
275 .Fn cpufreq_drv_get
276 method returns the currently-active driver setting.
277 The
278 .Vt "struct cf_setting"
279 returned must be valid for passing to
280 .Fn cpufreq_drv_set ,
281 including all elements being filled out correctly.
282 If the driver cannot infer the current setting
283 (even by estimating it with
284 .Fn cpu_est_clockrate )
285 then it should set all elements to
286 .Dv CPUFREQ_VAL_UNKNOWN .
287 .Sh SEE ALSO
288 .Xr acpi 4 ,
289 .Xr powerd 8 ,
290 .Xr sysctl 8
291 .Sh AUTHORS
292 .An Nate Lawson
293 .An Bruno Ducrot
294 contributed the
295 .Pa powernow
296 driver.
297 .Sh BUGS
298 The following drivers have not yet been converted to the
299 .Nm
300 interface:
301 .Xr longrun 4 .
302 .Pp
303 Notification of CPU and bus frequency changes is not implemented yet.
304 .Pp
305 When multiple CPUs offer frequency control, they cannot be set to different
306 levels and must all offer the same frequency settings.