1.\" $NetBSD: cpufreq.9,v 1.6 2011/10/27 05:25:08 jruoho Exp $ */ 2.\" 3.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen.iki.fi> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 17.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 18.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26.\" POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd October 27, 2011 29.Dt CPUFREQ 9 30.Os 31.Sh NAME 32.Nm cpufreq , 33.Nm cpufreq_register , 34.Nm cpufreq_deregister , 35.Nm cpufreq_suspend , 36.Nm cpufreq_resume , 37.Nm cpufreq_get , 38.Nm cpufreq_get_backend , 39.Nm cpufreq_get_state , 40.Nm cpufreq_get_state_index , 41.Nm cpufreq_set , 42.Nm cpufreq_set_all 43.Nd interface for CPU frequency scaling 44.Sh SYNOPSIS 45.In sys/cpufreq.h 46.Ft int 47.Fn cpufreq_register "struct cpufreq *cf" 48.Ft void 49.Fn cpufreq_deregister "void" 50.Ft void 51.Fn cpufreq_suspend "struct cpu_info *ci" 52.Ft void 53.Fn cpufreq_resume "struct cpu_info *ci" 54.Ft uint32_t 55.Fn cpufreq_get "struct cpu_info *ci" 56.Ft int 57.Fn cpufreq_get_backend "struct cpufreq *cf" 58.Ft int 59.Fn cpufreq_get_state "uint32_t freq" "struct cpufreq_state *cfs" 60.Ft int 61.Fn cpufreq_get_state_index "uint32_t index" "struct cpufreq_state *cfs" 62.Ft void 63.Fn cpufreq_set "struct cpu_info *ci" "uint32_t freq" 64.Ft void 65.Fn cpufreq_set_all "uint32_t freq" 66.\" .Ft void 67.\" .Fn cpufreq_set_higher "struct cpu_info *ci" 68.\" .Ft void 69.\" .Fn cpufreq_set_lower "struct cpu_info *ci" 70.Sh DESCRIPTION 71The machine-independent 72.Nm 73interface provides a framework for 74.Tn CPU 75frequency scaling done by a machine-dependent backend implementation. 76User space control is available via 77.Xr cpuctl 8 . 78.Pp 79The 80.Nm 81interface is a per-CPU framework. 82It is implicitly assumed that the frequency can be set 83independently for all processors in the system. 84However, 85.Nm 86does not imply any restrictions upon whether this information 87is utilized by the actual machine-dependent implementation. 88It is possible to use 89.Nm 90with frequency scaling implemented via 91.Xr pci 4 . 92In addition, it assumed that the available frequency levels are 93shared uniformly by all processors in the system, 94even when it is possible to control the frequency of individual processors. 95.Pp 96It should be noted that the 97.Nm 98interface is generally stateless. 99This implies for instance that possible caching should 100be done in the machine-dependent backend. 101The 102.Fn cpufreq_suspend 103and 104.Fn cpufreq_resume 105functions are exceptions. 106These can be integrated with 107.Xr pmf 9 . 108.Sh FUNCTIONS 109.Bl -tag -width compact 110.It Fn cpufreq_register "cf" 111The 112.Fn cpufreq_register 113function initializes the interface by associating 114a machine-dependent backend with the framework. 115Only one backend can be registered. 116Upon successful completion, 117.Fn cpufreq_register 118returns 0 and sets the frequency of all processors 119to the maximum available level. 120Note that the registration can be done 121only after interrupts have been enabled; cf. 122.Xr config_interrupts 9 . 123.Pp 124The following elements in 125.Vt struct cpufreq 126should be filled prior to the call: 127.Bd -literal -offset indent 128char cf_name[CPUFREQ_NAME_MAX]; 129struct cpufreq_state cf_state[CPUFREQ_STATE_MAX]; 130uint32_t cf_state_count; 131bool cf_mp; 132void *cf_cookie; 133xcfunc_t cf_get_freq; 134xcfunc_t cf_set_freq; 135.Ed 136.Pp 137.Bl -bullet 138.It 139The name of the backend should be given in 140.Vt cf_name . 141.It 142The 143.Vt cpufreq_state 144structure conveys descriptive information about the frequency states. 145The following fields can be used for the registration: 146.Bd -literal -offset 2n 147uint32_t cfs_freq; 148uint32_t cfs_power; 149.Ed 150.Pp 151From these 152.Vt cfs_freq 153(the clock frequency in MHz) is mandatory, whereas the optional 154.Vt cfs_power 155can be filled to describe the power consumption (in mW) of each state. 156The 157.Fa cf_state 158array must be filled in descending order, that is, the highest 159frequency should be at the zero index. 160.Pp 161If the backend operates with a simple boolean switch 162without knowing the clock frequencies, the 163.Fa cfs_freq 164field should be set to 165.Dv CPUFREQ_STATE_ENABLED 166or 167.Dv CPUFREQ_STATE_DISABLED . 168The first constant should precede the latter one in 169.Vt cf_state . 170.It 171The 172.Vt cf_state_count 173field defines the number of states that the backend has filled in the 174.Vt cf_state 175array. 176.It 177The 178.Vt cf_mp 179boolean should be set to false if it is known that the backend 180can not handle per-CPU frequency states; 181changes should always be propagated 182to all processors in the system. 183.It 184The 185.Vt cf_cookie 186field is an opaque pointer passed to the backend when 187.Fn cpufreq_get , 188.Fn cpufreq_set , 189or 190.Fn cpufreq_set_all 191is called. 192.It 193The 194.Vt cf_get_freq 195and 196.Vt cf_set_freq 197are function pointers that should be associated with the 198machine-dependent functions to get and set a frequency, respectively. 199The 200.Vt xcfunc_t 201type is part of 202.Xr xcall 9 . 203When the function pointers are invoked by 204.Nm , 205the first parameter is always the 206.Vt cf_cookie 207and the second parameter is the frequency, defined as 208.Vt uint32_t * . 209.El 210.It Fn cpufreq_deregister 211Deregisters any possible backend in use. 212.It Fn cpufreq_suspend "ci" 213The 214.Fn cpufreq_suspend 215can be called when the processor suspends. 216The function saves the current frequency of 217.Fa ci 218and sets the minimum available frequency. 219.It Fn cpufreq_resume "ci" 220Resumes the frequency of 221.Fa ci 222that was used before suspend. 223.It Fn cpufreq_get "ci" 224Returns the current frequency of the processor 225.Fa ci . 226A value zero is returned upon failure. 227.It Fn cpufreq_get_backend "cf" 228Upon successful completion, 229.Fn cpufreq_get_backend 230returns 0 and fills 231.Fa cf 232with the data related to the currently used backend. 233.It Fn cpufreq_get_state "freq" "cfs" 234The 235.Fn cpufreq_get_state 236function looks for the given frequency 237from the array of known frequency states. 238If 239.Fa freq 240is not found, the closest match is returned. 241Upon successful completion, 242the function returns zero and stores the state information to 243.Fa cfs . 244.It Fn cpufreq_get_state_index "index" "cfs" 245Stores the frequency state with the given 246.Fa index 247to 248.Fa cfs , 249returning zero upon successful completion. 250.It Fn cpufreq_set "ci" "freq" 251The 252.Fn cpufreq_set 253function sets the frequency of 254.Fa ci 255to 256.Fa freq . 257.It Fn cpufreq_set_all "freq" 258Sets 259.Fa freq 260for all processors in the system. 261.\" .It Fn cpufreq_set_higher "ci" 262.\" Decrements the current frequency level of 263.\" .Fa ci 264.\" by one state. 265.\" .It Fn cpufreq_set_lower "ci" 266.\" Increases the current frequency state of 267.\" .Fa ci 268.\" by one state. 269.El 270.Pp 271The three functions 272.Fn cpufreq_get , 273.Fn cpufreq_set , 274and 275.Fn cpufreq_set_all 276guarantee that the call will be made in 277.Xr curcpu 9 . 278The interface holds a 279.Xr mutex 9 280while calling the functions. 281This, and the use of 282.Xr xcall 9 , 283implies that no memory can be allocated in the backend during the calls. 284Nor should the functions be called from interrupt context. 285.Sh CODE REFERENCES 286The 287.Nm 288interface is implemented within 289.Pa sys/kern/subr_cpufreq.c . 290.Sh SEE ALSO 291.Xr cpuctl 8 , 292.Xr pmf 9 , 293.Xr xcall 9 294.Rs 295.%A Venkatesh Pallipadi 296.%A Alexey Starikovskiy 297.%T The Ondemand Governor. Past, Present, and Future 298.%I Intel Open Source Technology Center 299.%O Proceedings of the Linux Symposium 300.%D July, 2006 301.%U http://www.kernel.org/doc/ols/2006/ols2006v2-pages-223-238.pdf 302.Re 303.Sh HISTORY 304The 305.Nm 306interface first appeared in 307.Nx 6.0 . 308.Sh AUTHORS 309.An Jukka Ruohonen 310.Aq jruohonen@iki.fi 311.Sh BUGS 312The interface does not support different 313.Dq governors 314and policies. 315