Copyright (c) 2011 Jukka Ruohonen <jruohonen.iki.fi>
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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.Dd December 1, 2015 .Dt CPUFREQ 9 .Os .Sh NAME .Nm cpufreq , .Nm cpufreq_register , .Nm cpufreq_deregister , .Nm cpufreq_suspend , .Nm cpufreq_resume , .Nm cpufreq_get , .Nm cpufreq_get_backend , .Nm cpufreq_get_state , .Nm cpufreq_get_state_index , .Nm cpufreq_set , .Nm cpufreq_set_all .Nd interface for CPU frequency scaling .Sh SYNOPSIS n sys/cpufreq.h .Ft int .Fn cpufreq_register "struct cpufreq *cf" .Ft void .Fn cpufreq_deregister "void" .Ft void .Fn cpufreq_suspend "struct cpu_info *ci" .Ft void .Fn cpufreq_resume "struct cpu_info *ci" .Ft uint32_t .Fn cpufreq_get "struct cpu_info *ci" .Ft int .Fn cpufreq_get_backend "struct cpufreq *cf" .Ft int .Fn cpufreq_get_state "uint32_t freq" "struct cpufreq_state *cfs" .Ft int .Fn cpufreq_get_state_index "uint32_t index" "struct cpufreq_state *cfs" .Ft void .Fn cpufreq_set "struct cpu_info *ci" "uint32_t freq" .Ft void .Fn cpufreq_set_all "uint32_t freq" .Ft void
.Fn cpufreq_set_higher "struct cpu_info *ci"
.Ft void
.Fn cpufreq_set_lower "struct cpu_info *ci"
.Sh DESCRIPTION The machine-independent .Nm interface provides a framework for .Tn CPU frequency scaling done by a machine-dependent backend implementation.
p The .Nm interface is a per-CPU framework. It is implicitly assumed that the frequency can be set independently for all processors in the system. However, .Nm does not imply any restrictions upon whether this information is utilized by the actual machine-dependent implementation. It is possible to use .Nm with frequency scaling implemented via .Xr pci 4 . In addition, it assumed that the available frequency levels are shared uniformly by all processors in the system, even when it is possible to control the frequency of individual processors.
p It should be noted that the .Nm interface is generally stateless. This implies for instance that possible caching should be done in the machine-dependent backend. The .Fn cpufreq_suspend and .Fn cpufreq_resume functions are exceptions. These can be integrated with .Xr pmf 9 . .Sh FUNCTIONS l -tag -width compact t Fn cpufreq_register "cf" The .Fn cpufreq_register function initializes the interface by associating a machine-dependent backend with the framework. Only one backend can be registered. Upon successful completion, .Fn cpufreq_register returns 0 and sets the frequency of all processors to the maximum available level. Note that the registration can be done only after interrupts have been enabled; cf. .Xr config_interrupts 9 .
p The following elements in .Vt struct cpufreq should be filled prior to the call: d -literal -offset indent char cf_name[CPUFREQ_NAME_MAX]; struct cpufreq_state cf_state[CPUFREQ_STATE_MAX]; uint32_t cf_state_count; bool cf_mp; void *cf_cookie; xcfunc_t cf_get_freq; xcfunc_t cf_set_freq; .Ed
p l -bullet t The name of the backend should be given in .Vt cf_name . t The .Vt cpufreq_state structure conveys descriptive information about the frequency states. The following fields can be used for the registration: d -literal -offset 2n uint32_t cfs_freq; uint32_t cfs_power; .Ed
p From these .Vt cfs_freq (the clock frequency in MHz) is mandatory, whereas the optional .Vt cfs_power can be filled to describe the power consumption (in mW) of each state. The .Fa cf_state array must be filled in descending order, that is, the highest frequency should be at the zero index.
p
If the backend operates with a simple boolean switch
without knowing the clock frequencies, the
.Fa cfs_freq
field should be set to
.Dv CPUFREQ_STATE_ENABLED
or
.Dv CPUFREQ_STATE_DISABLED .
The first constant should precede the latter one in
.Vt cf_state .
t The
.Vt cf_state_count
field defines the number of states that the backend has filled in the
.Vt cf_state
array.
t The
.Vt cf_mp
boolean should be set to false if it is known that the backend
can not handle per-CPU frequency states;
changes should always be propagated
to all processors in the system.
t The
.Vt cf_cookie
field is an opaque pointer passed to the backend when
.Fn cpufreq_get ,
.Fn cpufreq_set ,
or
.Fn cpufreq_set_all
is called.
t The
.Vt cf_get_freq
and
.Vt cf_set_freq
are function pointers that should be associated with the
machine-dependent functions to get and set a frequency, respectively.
The
.Vt xcfunc_t
type is part of
.Xr xcall 9 .
When the function pointers are invoked by
.Nm ,
the first parameter is always the
.Vt cf_cookie
and the second parameter is the frequency, defined as
.Vt uint32_t * .
.El
t Fn cpufreq_deregister Deregisters any possible backend in use.
t Fn cpufreq_suspend "ci" The
.Fn cpufreq_suspend
can be called when the processor suspends.
The function saves the current frequency of
.Fa ci
and sets the minimum available frequency.
t Fn cpufreq_resume "ci" Resumes the frequency of
.Fa ci
that was used before suspend.
t Fn cpufreq_get "ci" Returns the current frequency of the processor
.Fa ci .
A value zero is returned upon failure.
t Fn cpufreq_get_backend "cf" Upon successful completion,
.Fn cpufreq_get_backend
returns 0 and fills
.Fa cf
with the data related to the currently used backend.
t Fn cpufreq_get_state "freq" "cfs" The
.Fn cpufreq_get_state
function looks for the given frequency
from the array of known frequency states.
If
.Fa freq
is not found, the closest match is returned.
Upon successful completion,
the function returns zero and stores the state information to
.Fa cfs .
t Fn cpufreq_get_state_index "index" "cfs" Stores the frequency state with the given
.Fa index
to
.Fa cfs ,
returning zero upon successful completion.
t Fn cpufreq_set "ci" "freq" The
.Fn cpufreq_set
function sets the frequency of
.Fa ci
to
.Fa freq .
t Fn cpufreq_set_all "freq" Sets
.Fa freq
for all processors in the system.
.It Fn cpufreq_set_higher "ci"
Decrements the current frequency level of
.Fa ci
by one state.
.It Fn cpufreq_set_lower "ci"
Increases the current frequency state of
.Fa ci
by one state.
.El
p The three functions .Fn cpufreq_get , .Fn cpufreq_set , and .Fn cpufreq_set_all guarantee that the call will be made in .Xr curcpu 9 . The interface holds a .Xr mutex 9 while calling the functions. This, and the use of .Xr xcall 9 , implies that no memory can be allocated in the backend during the calls. Nor should the functions be called from interrupt context. .Sh CODE REFERENCES The .Nm interface is implemented within
a sys/kern/subr_cpufreq.c . .Sh SEE ALSO .Xr pmf 9 , .Xr xcall 9 .Rs .%A Venkatesh Pallipadi .%A Alexey Starikovskiy .%T The Ondemand Governor. Past, Present, and Future .%I Intel Open Source Technology Center .%O Proceedings of the Linux Symposium .%D July, 2006 .%U http://www.kernel.org/doc/ols/2006/ols2006v2-pages-223-238.pdf .Re .Sh HISTORY The .Nm interface first appeared in .Nx 6.0 . .Sh AUTHORS .An Jukka Ruohonen .Aq jruohonen (at] iki.fi .Sh BUGS The interface does not support different .Dq governors and policies.
Indexes created Sat Sep 20 22:09:52 GMT 2025