312 lines
8.3 KiB
Groff
312 lines
8.3 KiB
Groff
.\" $NetBSD: cpufreq.9,v 1.7 2015/12/01 12:07:41 jmcneill Exp $ */
|
|
.\"
|
|
.\" 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
|
|
.In 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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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
|
|
.Bl -tag -width compact
|
|
.It 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 .
|
|
.Pp
|
|
The following elements in
|
|
.Vt struct cpufreq
|
|
should be filled prior to the call:
|
|
.Bd -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
|
|
.Pp
|
|
.Bl -bullet
|
|
.It
|
|
The name of the backend should be given in
|
|
.Vt cf_name .
|
|
.It
|
|
The
|
|
.Vt cpufreq_state
|
|
structure conveys descriptive information about the frequency states.
|
|
The following fields can be used for the registration:
|
|
.Bd -literal -offset 2n
|
|
uint32_t cfs_freq;
|
|
uint32_t cfs_power;
|
|
.Ed
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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 .
|
|
.It
|
|
The
|
|
.Vt cf_state_count
|
|
field defines the number of states that the backend has filled in the
|
|
.Vt cf_state
|
|
array.
|
|
.It
|
|
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.
|
|
.It
|
|
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.
|
|
.It
|
|
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
|
|
.It Fn cpufreq_deregister
|
|
Deregisters any possible backend in use.
|
|
.It 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.
|
|
.It Fn cpufreq_resume "ci"
|
|
Resumes the frequency of
|
|
.Fa ci
|
|
that was used before suspend.
|
|
.It Fn cpufreq_get "ci"
|
|
Returns the current frequency of the processor
|
|
.Fa ci .
|
|
A value zero is returned upon failure.
|
|
.It 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.
|
|
.It 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 .
|
|
.It Fn cpufreq_get_state_index "index" "cfs"
|
|
Stores the frequency state with the given
|
|
.Fa index
|
|
to
|
|
.Fa cfs ,
|
|
returning zero upon successful completion.
|
|
.It Fn cpufreq_set "ci" "freq"
|
|
The
|
|
.Fn cpufreq_set
|
|
function sets the frequency of
|
|
.Fa ci
|
|
to
|
|
.Fa freq .
|
|
.It 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
|
|
.Pp
|
|
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
|
|
.Pa 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@iki.fi
|
|
.Sh BUGS
|
|
The interface does not support different
|
|
.Dq governors
|
|
and policies.
|