1.\" $NetBSD: cpufreq.9,v 1.7 2015/12/01 12:07:41 jmcneill 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 December 1, 2015 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. 76.Pp 77The 78.Nm 79interface is a per-CPU framework. 80It is implicitly assumed that the frequency can be set 81independently for all processors in the system. 82However, 83.Nm 84does not imply any restrictions upon whether this information 85is utilized by the actual machine-dependent implementation. 86It is possible to use 87.Nm 88with frequency scaling implemented via 89.Xr pci 4 . 90In addition, it assumed that the available frequency levels are 91shared uniformly by all processors in the system, 92even when it is possible to control the frequency of individual processors. 93.Pp 94It should be noted that the 95.Nm 96interface is generally stateless. 97This implies for instance that possible caching should 98be done in the machine-dependent backend. 99The 100.Fn cpufreq_suspend 101and 102.Fn cpufreq_resume 103functions are exceptions. 104These can be integrated with 105.Xr pmf 9 . 106.Sh FUNCTIONS 107.Bl -tag -width compact 108.It Fn cpufreq_register "cf" 109The 110.Fn cpufreq_register 111function initializes the interface by associating 112a machine-dependent backend with the framework. 113Only one backend can be registered. 114Upon successful completion, 115.Fn cpufreq_register 116returns 0 and sets the frequency of all processors 117to the maximum available level. 118Note that the registration can be done 119only after interrupts have been enabled; cf. 120.Xr config_interrupts 9 . 121.Pp 122The following elements in 123.Vt struct cpufreq 124should be filled prior to the call: 125.Bd -literal -offset indent 126char cf_name[CPUFREQ_NAME_MAX]; 127struct cpufreq_state cf_state[CPUFREQ_STATE_MAX]; 128uint32_t cf_state_count; 129bool cf_mp; 130void *cf_cookie; 131xcfunc_t cf_get_freq; 132xcfunc_t cf_set_freq; 133.Ed 134.Pp 135.Bl -bullet 136.It 137The name of the backend should be given in 138.Vt cf_name . 139.It 140The 141.Vt cpufreq_state 142structure conveys descriptive information about the frequency states. 143The following fields can be used for the registration: 144.Bd -literal -offset 2n 145uint32_t cfs_freq; 146uint32_t cfs_power; 147.Ed 148.Pp 149From these 150.Vt cfs_freq 151(the clock frequency in MHz) is mandatory, whereas the optional 152.Vt cfs_power 153can be filled to describe the power consumption (in mW) of each state. 154The 155.Fa cf_state 156array must be filled in descending order, that is, the highest 157frequency should be at the zero index. 158.Pp 159If the backend operates with a simple boolean switch 160without knowing the clock frequencies, the 161.Fa cfs_freq 162field should be set to 163.Dv CPUFREQ_STATE_ENABLED 164or 165.Dv CPUFREQ_STATE_DISABLED . 166The first constant should precede the latter one in 167.Vt cf_state . 168.It 169The 170.Vt cf_state_count 171field defines the number of states that the backend has filled in the 172.Vt cf_state 173array. 174.It 175The 176.Vt cf_mp 177boolean should be set to false if it is known that the backend 178can not handle per-CPU frequency states; 179changes should always be propagated 180to all processors in the system. 181.It 182The 183.Vt cf_cookie 184field is an opaque pointer passed to the backend when 185.Fn cpufreq_get , 186.Fn cpufreq_set , 187or 188.Fn cpufreq_set_all 189is called. 190.It 191The 192.Vt cf_get_freq 193and 194.Vt cf_set_freq 195are function pointers that should be associated with the 196machine-dependent functions to get and set a frequency, respectively. 197The 198.Vt xcfunc_t 199type is part of 200.Xr xcall 9 . 201When the function pointers are invoked by 202.Nm , 203the first parameter is always the 204.Vt cf_cookie 205and the second parameter is the frequency, defined as 206.Vt uint32_t * . 207.El 208.It Fn cpufreq_deregister 209Deregisters any possible backend in use. 210.It Fn cpufreq_suspend "ci" 211The 212.Fn cpufreq_suspend 213can be called when the processor suspends. 214The function saves the current frequency of 215.Fa ci 216and sets the minimum available frequency. 217.It Fn cpufreq_resume "ci" 218Resumes the frequency of 219.Fa ci 220that was used before suspend. 221.It Fn cpufreq_get "ci" 222Returns the current frequency of the processor 223.Fa ci . 224A value zero is returned upon failure. 225.It Fn cpufreq_get_backend "cf" 226Upon successful completion, 227.Fn cpufreq_get_backend 228returns 0 and fills 229.Fa cf 230with the data related to the currently used backend. 231.It Fn cpufreq_get_state "freq" "cfs" 232The 233.Fn cpufreq_get_state 234function looks for the given frequency 235from the array of known frequency states. 236If 237.Fa freq 238is not found, the closest match is returned. 239Upon successful completion, 240the function returns zero and stores the state information to 241.Fa cfs . 242.It Fn cpufreq_get_state_index "index" "cfs" 243Stores the frequency state with the given 244.Fa index 245to 246.Fa cfs , 247returning zero upon successful completion. 248.It Fn cpufreq_set "ci" "freq" 249The 250.Fn cpufreq_set 251function sets the frequency of 252.Fa ci 253to 254.Fa freq . 255.It Fn cpufreq_set_all "freq" 256Sets 257.Fa freq 258for all processors in the system. 259.\" .It Fn cpufreq_set_higher "ci" 260.\" Decrements the current frequency level of 261.\" .Fa ci 262.\" by one state. 263.\" .It Fn cpufreq_set_lower "ci" 264.\" Increases the current frequency state of 265.\" .Fa ci 266.\" by one state. 267.El 268.Pp 269The three functions 270.Fn cpufreq_get , 271.Fn cpufreq_set , 272and 273.Fn cpufreq_set_all 274guarantee that the call will be made in 275.Xr curcpu 9 . 276The interface holds a 277.Xr mutex 9 278while calling the functions. 279This, and the use of 280.Xr xcall 9 , 281implies that no memory can be allocated in the backend during the calls. 282Nor should the functions be called from interrupt context. 283.Sh CODE REFERENCES 284The 285.Nm 286interface is implemented within 287.Pa sys/kern/subr_cpufreq.c . 288.Sh SEE ALSO 289.Xr pmf 9 , 290.Xr xcall 9 291.Rs 292.%A Venkatesh Pallipadi 293.%A Alexey Starikovskiy 294.%T The Ondemand Governor. Past, Present, and Future 295.%I Intel Open Source Technology Center 296.%O Proceedings of the Linux Symposium 297.%D July, 2006 298.%U http://www.kernel.org/doc/ols/2006/ols2006v2-pages-223-238.pdf 299.Re 300.Sh HISTORY 301The 302.Nm 303interface first appeared in 304.Nx 6.0 . 305.Sh AUTHORS 306.An Jukka Ruohonen 307.Aq jruohonen@iki.fi 308.Sh BUGS 309The interface does not support different 310.Dq governors 311and policies. 312