258 lines
7.3 KiB
Groff
258 lines
7.3 KiB
Groff
.\" Copyright (c) 2005 Nate Lawson
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 6, 2005
|
|
.Dt CPUFREQ 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cpufreq
|
|
.Nd CPU frequency control framework
|
|
.Sh SYNOPSIS
|
|
.Cd "device cpufreq"
|
|
.Pp
|
|
.In sys/cpu.h
|
|
.Ft int
|
|
.Fn cpufreq_levels "device_t dev" "struct cf_level *levels" "int *count"
|
|
.Ft int
|
|
.Fn cpufreq_set "device_t dev" "const struct cf_level *level" "int priority"
|
|
.Ft int
|
|
.Fn cpufreq_get "device_t dev" "struct cf_level *level"
|
|
.Ft int
|
|
.Fo cpufreq_drv_settings
|
|
.Fa "device_t dev"
|
|
.Fa "struct cf_setting *sets"
|
|
.Fa "int *count"
|
|
.Fa "int *type"
|
|
.Fc
|
|
.Ft int
|
|
.Fn cpufreq_drv_set "device_t dev" "const struct cf_setting *set"
|
|
.Ft int
|
|
.Fn cpufreq_drv_get "device_t dev" "struct cf_setting *set"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides a unified kernel and user interface to CPU frequency
|
|
control drivers.
|
|
It combines multiple drivers offering different settings into a single
|
|
interface of all possible levels.
|
|
Users can access this interface directly via
|
|
.Xr sysctl 8
|
|
or by indicating to
|
|
.Xr power_profile 8
|
|
that it should switch settings when the AC line state changes via
|
|
.Xr rc.conf 5 .
|
|
.Sh SYSCTLS
|
|
These settings may be overridden by kernel drivers requesting alternate
|
|
settings.
|
|
If this occurs, the original values will be restored once the condition
|
|
has passed (e.g., the system has cooled sufficiently).
|
|
If a sysctl cannot be set due to an override condition, it will return
|
|
.Er EPERM .
|
|
.Bl -tag -width indent
|
|
.It Va dev.cpu.%d.freq
|
|
Current active CPU frequency in MHz.
|
|
.It Va dev.cpu.%d.freq_levels
|
|
Currently available levels for the CPU frequency and power usage for each.
|
|
Values are in units of MHz and milliwatts.
|
|
.El
|
|
.Sh SUPPORTED DRIVERS
|
|
The following device drivers offer absolute frequency control via the
|
|
.Nm
|
|
interface.
|
|
Usually, only one of these can be active at a time.
|
|
.Pp
|
|
.Bl -tag -compact -width ".Xr acpi_perf 4"
|
|
.It Xr acpi_perf 4
|
|
ACPI CPU performance states
|
|
.It Xr ichss 4
|
|
Intel SpeedStep for ICH
|
|
.El
|
|
.Pp
|
|
The following device drivers offer relative frequency control and
|
|
have an additive effect:
|
|
.Pp
|
|
.Bl -tag -compact -width ".Xr acpi_throttle 4"
|
|
.It Xr acpi_throttle 4
|
|
ACPI CPU throttling
|
|
.El
|
|
.Sh KERNEL INTERFACE
|
|
Kernel components can query and set CPU frequencies through the
|
|
.Nm
|
|
kernel interface.
|
|
This involves obtaining a
|
|
.Nm
|
|
device, calling
|
|
.Fn cpufreq_levels
|
|
to get the currently available frequency levels,
|
|
checking the current level with
|
|
.Fn cpufreq_get ,
|
|
and setting a new one from the list with
|
|
.Fn cpufreq_set .
|
|
Each level may actually reference more than one
|
|
.Nm
|
|
driver but kernel components do not need to be aware of this.
|
|
The
|
|
.Va total_set
|
|
element of
|
|
.Vt "struct cf_level"
|
|
provides a summary of the frequency and power for this level.
|
|
Unknown or irrelevant values are set to
|
|
.Dv CPUFREQ_VAL_UNKNOWN .
|
|
.Pp
|
|
The
|
|
.Fn cpufreq_levels
|
|
method takes a
|
|
.Nm
|
|
device and an empty array of
|
|
.Fa levels .
|
|
The
|
|
.Fa count
|
|
value should be set to the number of levels available and after the
|
|
function completes, will be set to the actual number of levels returned.
|
|
If there are more levels than
|
|
.Fa count
|
|
will allow, it should return
|
|
.Er E2BIG .
|
|
.Pp
|
|
The
|
|
.Fn cpufreq_get
|
|
method takes a pointer to space to store a
|
|
.Fa level .
|
|
After successful completion, the output will be the current active level
|
|
and is equal to one of the levels returned by
|
|
.Fn cpufreq_levels .
|
|
.Pp
|
|
The
|
|
.Fn cpufreq_set
|
|
method takes a pointer a
|
|
.Fa level
|
|
and attempts to activate it.
|
|
The
|
|
.Fa priority
|
|
(i.e.,
|
|
.Dv CPUFREQ_PRIO_KERN )
|
|
tells
|
|
.Nm
|
|
whether to override previous settings while activating this level.
|
|
If
|
|
.Fa priority
|
|
is higher than the current active level, that level will be saved and
|
|
overridden with the new level.
|
|
If
|
|
.Fn cpufreq_set
|
|
is called with a
|
|
.Dv NULL
|
|
.Fa level ,
|
|
the saved level (if any) will be restored.
|
|
If
|
|
.Fa priority
|
|
is lower than the current active level's priority, this method returns
|
|
.Er EPERM .
|
|
.Sh DRIVER INTERFACE
|
|
Kernel drivers offering hardware-specific CPU frequency control export
|
|
their individual settings through the
|
|
.Nm
|
|
driver interface.
|
|
This involves implementing three methods:
|
|
.Fn cpufreq_drv_settings ,
|
|
.Fn cpufreq_drv_set ,
|
|
and
|
|
.Fn cpufreq_drv_get .
|
|
Additionally, the driver must attach a device as a child of a CPU
|
|
device so that these methods can be called by the
|
|
.Nm
|
|
framework.
|
|
.Pp
|
|
The
|
|
.Fn cpufreq_drv_settings
|
|
method returns an array of currently available settings, each of type
|
|
.Vt "struct cf_setting" .
|
|
The driver should set unknown or irrelevant values to
|
|
.Dv CPUFREQ_VAL_UNKNOWN .
|
|
All the following elements for each setting should be returned:
|
|
.Bd -literal
|
|
struct cf_setting {
|
|
int freq; /* CPU clock in Mhz or 100ths of a percent. */
|
|
int volts; /* Voltage in mV. */
|
|
int power; /* Power consumed in mW. */
|
|
int lat; /* Transition latency in us. */
|
|
device_t dev; /* Driver providing this setting. */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
On entry to this method,
|
|
.Fa count
|
|
contains the number of settings that can be returned.
|
|
On successful completion, the driver sets it to the actual number of
|
|
settings returned.
|
|
If the driver offers more settings than
|
|
.Fa count
|
|
will allow, it should return
|
|
.Er E2BIG .
|
|
The driver sets
|
|
.Fa type
|
|
to the type of settings it offers, either
|
|
.Dv CPUFREQ_TYPE_ABSOLUTE
|
|
or
|
|
.Dv CPUFREQ_TYPE_RELATIVE .
|
|
.Pp
|
|
The
|
|
.Fn cpufreq_drv_set
|
|
method takes a driver setting and makes it active.
|
|
If the setting is invalid or not currently available, it should return
|
|
.Er EINVAL .
|
|
.Pp
|
|
The
|
|
.Fn cpufreq_drv_get
|
|
method returns the currently-active driver setting.
|
|
The
|
|
.Vt "struct cf_setting"
|
|
returned must be valid for passing to
|
|
.Fn cpufreq_drv_set ,
|
|
including all elements being filled out correctly.
|
|
If the driver cannot infer the current setting
|
|
(even by estimating it with
|
|
.Fn cpu_est_clockrate )
|
|
then it should set all elements to
|
|
.Dv CPUFREQ_VAL_UNKNOWN .
|
|
.Sh SEE ALSO
|
|
.Xr acpi 4 ,
|
|
.Xr sysctl 8
|
|
.Sh AUTHORS
|
|
.An Nate Lawson
|
|
.Sh BUGS
|
|
The following drivers have not yet been converted to the
|
|
.Nm
|
|
interface:
|
|
.Xr longrun 4 ,
|
|
.Xr p4tcc 4 .
|
|
.Pp
|
|
Priorities and notification of unrequested frequency changes are not
|
|
implemented yet.
|
|
.Pp
|
|
When multiple CPUs offer frequency control, they cannot be set to different
|
|
levels and must all offer the same frequency settings.
|