share/man/man4/cpufreq.4

   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 January 31, 2020
  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 and the
  77 hardware does not support invariant TSC.
  78 This is because the timecounter system needs to use a source that has a
  79 constant rate.
  80 (On invariant TSC hardware, the TSC runs at the P0 rate regardless of the
  81 configured P-state.)
  82 Modern hardware mostly has invariant TSC.
  83 The timecounter source can be changed with the
  84 .Pa kern.timecounter.hardware
  85 sysctl.
  86 Available modes are in
  87 .Pa kern.timecounter.choice
  88 sysctl entry.
  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
  93 The specific
  94 .Nm
  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
 108 some systems.
 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
 114 (including by
 115 .Xr powerd 8 )
 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.
 121 .El
 122 .Sh SUPPORTED DRIVERS
 123 The following device drivers offer absolute frequency control via the
 124 .Nm
 125 interface.
 126 Usually, only one of these can be active at a time.
 127 .Pp
 128 .Bl -tag -compact -width ".Pa hwpstate_intel"
 129 .It Pa acpi_perf
 130 ACPI CPU performance states
 131 .It Pa est
 132 Intel Enhanced SpeedStep
 133 .It Pa hwpstate
 134 AMD Cool'n'Quiet2 used in K10 through Family 17h
 135 .It Pa hwpstate_intel
 136 Intel SpeedShift driver
 137 .It Pa ichss
 138 Intel SpeedStep for ICH
 139 .It Pa powernow
 140 AMD PowerNow!\& and Cool'n'Quiet for K7 and K8
 141 .It Pa smist
 142 Intel SMI-based SpeedStep for PIIX4
 143 .El
 144 .Pp
 145 The following device drivers offer relative frequency control and
 146 have an additive effect:
 147 .Pp
 148 .Bl -tag -compact -width ".Pa acpi_throttle"
 149 .It Pa acpi_throttle
 150 ACPI CPU throttling
 151 .It Pa p4tcc
 152 Pentium 4 Thermal Control Circuitry
 153 .El
 154 .Sh KERNEL INTERFACE
 155 Kernel components can query and set CPU frequencies through the
 156 .Nm
 157 kernel interface.
 158 This involves obtaining a
 159 .Nm
 160 device, calling
 161 .Fn cpufreq_levels
 162 to get the currently available frequency levels,
 163 checking the current level with
 164 .Fn cpufreq_get ,
 165 and setting a new one from the list with
 166 .Fn cpufreq_set .
 167 Each level may actually reference more than one
 168 .Nm
 169 driver but kernel components do not need to be aware of this.
 170 The
 171 .Va total_set
 172 element of
 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 .
 177 .Pp
 178 The
 179 .Fn cpufreq_levels
 180 method takes a
 181 .Nm
 182 device and an empty array of
 183 .Fa levels .
 184 The
 185 .Fa count
 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
 189 .Fa count
 190 will allow, it should return
 191 .Er E2BIG .
 192 .Pp
 193 The
 194 .Fn cpufreq_get
 195 method takes a pointer to space to store a
 196 .Fa level .
 197 After successful completion, the output will be the current active level
 198 and is equal to one of the levels returned by
 199 .Fn cpufreq_levels .
 200 .Pp
 201 The
 202 .Fn cpufreq_set
 203 method takes a pointer a
 204 .Fa level
 205 and attempts to activate it.
 206 The
 207 .Fa priority
 208 (i.e.,
 209 .Dv CPUFREQ_PRIO_KERN )
 210 tells
 211 .Nm
 212 whether to override previous settings while activating this level.
 213 If
 214 .Fa priority
 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.
 219 If
 220 .Fn cpufreq_set
 221 is called with a
 222 .Dv NULL
 223 .Fa level ,
 224 the saved level will be restored.
 225 If there is no saved level,
 226 .Fn cpufreq_set
 227 will return
 228 .Er ENXIO .
 229 If
 230 .Fa priority
 231 is lower than the current active level's priority, this method returns
 232 .Er EPERM .
 233 .Sh DRIVER INTERFACE
 234 Kernel drivers offering hardware-specific CPU frequency control export
 235 their individual settings through the
 236 .Nm
 237 driver interface.
 238 This involves implementing these methods:
 239 .Fn cpufreq_drv_settings ,
 240 .Fn cpufreq_drv_type ,
 241 .Fn cpufreq_drv_set ,
 242 and
 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
 246 .Nm
 247 framework.
 248 .Pp
 249 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:
 256 .Bd -literal
 257 struct cf_setting {
 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. */
 263 };
 264 .Ed
 265 .Pp
 266 On entry to this method,
 267 .Fa count
 268 contains the number of settings that can be returned.
 269 On successful completion, the driver sets it to the actual number of
 270 settings returned.
 271 If the driver offers more settings than
 272 .Fa count
 273 will allow, it should return
 274 .Er E2BIG .
 275 .Pp
 276 The
 277 .Fn cpufreq_drv_type
 278 method indicates the type of settings it offers, either
 279 .Dv CPUFREQ_TYPE_ABSOLUTE
 280 or
 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
 286 .Fn cpufreq_drv_set
 287 to activate them.
 288 .Pp
 289 The
 290 .Fn cpufreq_drv_set
 291 method takes a driver setting and makes it active.
 292 If the setting is invalid or not currently available, it should return
 293 .Er EINVAL .
 294 .Pp
 295 The
 296 .Fn cpufreq_drv_get
 297 method returns the currently-active driver setting.
 298 The
 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 .
 308 .Sh SEE ALSO
 309 .Xr acpi 4 ,
 310 .Xr est 4 ,
 311 .Xr timecounters 4 ,
 312 .Xr powerd 8 ,
 313 .Xr sysctl 8
 314 .Sh AUTHORS
 315 .An Nate Lawson
 316 .An Bruno Ducrot
 317 contributed the
 318 .Pa powernow
 319 driver.
 320 .Sh BUGS
 321 The following drivers have not yet been converted to the
 322 .Nm
 323 interface:
 324 .Xr longrun 4 .
 325 .Pp
 326 Notification of CPU and bus frequency changes is not implemented yet.
 327 .Pp
 328 When multiple CPUs offer frequency control, they cannot be set to different
 329 levels and must all offer the same frequency settings.