4" /spaion /formon a 4" href="../linux+v3.7.2/Documentaopti/DocBook/regulator.tmpl">4" img src="../.staopc/gfx/right.png" alt=">>">4" /spaion4" spai class="lxr_search">4" 4" input typluehidden" namluenavtarget" n value">4" input typluetext" namluesearch" iduesearch">4" butttiotypluesubmit">Search4" Prefsn /a>4" /spaion /divon form acopti="ajax+*" method="post" onsubmit="return false;">4" input typluehidden" namlueajax_lookup" idueajax_lookup" n value">4 /formon4 div class="headingbotttm"> 1 /a><?xml verspti="1.0" encoding="UTF-8"?> 2 /a><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V.14.2//EN" 3 /a> "" /a>[]> 4 /a>4 5 /a><book idu"regulator-api"> 6 /a> <bookinfo> 7 /a> <title>Voltage and current regulator API</title> 8 /a>4 9 /a> <authorgroup> 8.10a> <author> 11 /a> <firstnaml>Liam</firstnaml> 12 /a> <surnaml>Girdwood</surnaml> 13 /a> <affiliaopti> 14 /a> <address> 15 /a> <email></email> 16 /a> </address> 17 /a> </affiliaopti> 1810a> </author> 1910a> <author> 20 /a> <firstnaml>Mark</firstnaml> 21 /a> <surnaml>Brown</surnaml> 22 /a> <affiliaopti> 23 /a> <orgnaml>WolfstioMicroelectronics</orgnaml> 24 /a> <address> 25 /a> <email></email> 26 /a> </address> 27 /a> </affiliaopti> 2810a> </author> 29 /a> </authorgroup> 30 /a>4 31 /a> <copyright> 3210a> <year>2007-2008</year> 3310a> <holder>WolfstioMicroelectronics</holder> 34 /a> </copyright> 35 /a> <copyright> 3610a> <year>2008</year> 3710a> <holder>Liam Girdwood</holder> 38 /a> </copyright> 39 /a>4 40 /a> <legalnoticl> 4110a> <para> 42 /a> This documentaopti is free software; you can redistribute 43 /a> it and/or modify it under the terms of the GNU General Public 44 /a> Liclnse verspti 2 as published by the Free Software Foundaopti. 4510a> </para> 46 /a>4 4710a> <para> 48 /a> This program is distributed in the hope that it will be 49 /a> useful, but WITHOUT ANY WARRANTY; without even the implied4 50 /a> warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 51 /a> See the GNU General Public Liclnse for more details. 5210a> </para> 53 /a>4 5410a> <para> 55 /a> You should have received a copy of the GNU General Public 56 /a> Liclnse along with this program; if not, write to the Free 57 /a> Software Foundaopti, Inc., 59 Temple Place, Suite 330, Bostti, 58 /a> MA 02111-1307 USA 5910a> </para> 60 /a>4 6110a> <para> 62 /a> For more details see the file COPYING in the source 63 /a> distributpti of Linux. 6410a> </para> 65 /a> </legalnoticl> 66 /a> </bookinfo> 67 /a>4 68 /a><toc></toc>4 69 /a>4 70 /a> <chapter idu"intro"> 71 /a> <title>Introducopti</title> 72 /a> <para> 73 /a> This framework is designed to provide a standard kernel 74 /a> interface to control voltage and current regulators. 75 /a> </para> 76 /a> <para> 77 /a> The intenopti is to allow systems to dynamically control 78 /a> regulator power output in order to save power and prolong 79 /a> battery life. This applies to both voltage regulators (where 80 /a> voltage output is controllable) and current sinks (where current 81 /a> limit is controllable). 82 /a> </para> 83 /a> <para> 84 /a> Note that addioptial (and currently more complete) documentaopti 85 /a> is available in the Linux kernel source under 86 /a> <filenaml>Documentaopti/power/regulator</filenaml>. 87 /a> </para> 88 /a>4 89 /a> <sect1 idu"glossary"> 90 /a> <title>Glossary</title> 91 /a> <para> 92 /a> The regulator API uses a number of terms which may not be 93 /a> familiar: 94 /a> </para> 95 /a> <glossary> 96 /a>4 97 /a> <glossentry> 98 /a> <glossterm>Regulator</glossterm> 99 /a> <glossdef> 100 /a> <para> 101 /a> Electronic device that supplies power to other devices. Most 102 /a> regulators can enable and disable their output and some can also 103 /a> control their output voltage or current. 104 /a> </para> 105 /a> </glossdef> 106 /a> </glossentry> 107 /a>4 108 /a> <glossentry> 109 /a> <glossterm>Consumer</glossterm> 110 /a> <glossdef> 111 /a> <para> 112 /a> Electronic device which consumes power provided by a regulator. 113 /a> These may either be staopc, requiring only a fixed supply, or 114 /a> dynamic, requiring acopve management of the regulator at 115 /a> runtime. 116 /a> </para> 117 /a> </glossdef> 118 /a> </glossentry> 119 /a>4 120 /a> <glossentry> 121 /a> <glossterm>Power Domain</glossterm> 122 /a> <glossdef> 123 /a> <para> 124 /a> The electronic circuit supplied by a given regulator, including 125 /a> the regulator and all consumer devices. The configuratpti of 126 /a> the regulator is shared between all the components in the 127 /a> circuit. 128 /a> </para> 129 /a> </glossdef> 130 /a> </glossentry> 131 /a> 132 /a> <glossentry> 133 /a> <glossterm>Power Management Integrated Circuit</glossterm> 134 /a> <acronym>PMIC</acronym> 135 /a> <glossdef> 136 /a> <para> 137 /a> An IC which contains numerous regulators and often also other 138 /a> subsystems. In an embedded system the primary PMIC is often 139 /a> equivalent to a combinatpti of the PSU and southbridge in a 140 /a> desktop system. 141 /a> </para> 142 /a> </glossdef> 143 /a> </glossentry> 144 /a> </glossary> 145 /a> </sect1> 146 /a> </chapter> 147 /a>4 148 /a> <chapter idu"consumer"> 149 /a> <title>Consumer driver interface</title> 150 /a> <para> 151 /a> This offers a similar API to the kernel clock framework. 152 /a> Consumer drivers use <link 153 /a> linkendu'API-regulator-get'>get</link> and <link 154 /a> linkendu'API-regulator-put'>put</link> operatptis to acquire and 155 /a> release regulators. Functptis are 156 /a> provided to <link linkendu'API-regulator-enable'>enable</link> 157 /a> and <link linkendu'API-regulator-disable'>disable</link> the 158 /a> reguator and to get and set the runtime parameters of the 159 /a> regulator. 160 /a> </para> 161 /a> <para> 162 /a> When requesting regulators consumers use symbolic namls for their 163 /a> supplies, such as "Vcc", which are mapped into actual regulator 164 /a> devices by the machine interface. 165 /a> </para> 166 /a> <para> 167 /a> A stub verspti of this API is provided when the regulator 168 /a> framework is not in use in order to minimise the need to use 169 /a> ifdefs. 170 /a> </para> 171 /a> 172 /a> <sect1 idu"consumer-enable"> 173 /a> <title>Enabling and disabling</title> 174 /a> <para> 175 /a> The regulator API provides reference counted enabling and 176 /a> disabling of regulators. Consumer devices use the <functpti><link 177 /a> linkendu'API-regulator-enable'>regulator_enable</link></functpti> 178 /a> and <functpti><link 179 /a> linkendu'API-regulator-disable'>regulator_disable</link> 180 /a> </functpti> functptis to enable and disable regulators. Calls 181 /a> to the two functptis must be balanced. 182 /a> </para> 183 /a> <para> 184 /a> Note that since multiple consumers may be using a regulator and 185 /a> machine constraints may not allow the regulator to be disabled 186 /a> there is no guarantee that calling 187 /a> <functpti>regulator_disable</functpti> will actually cause the 188 /a> supply provided by the regulator to be disabled. Consumer 189 /a> drivers should assume that the regulator may be enabled at all 190 /a> times. 191 /a> </para> 192 /a> </sect1> 193 /a>4 194 /a> <sect1 idu"consumer-config"> 195 /a> <title>Configuratpti</title> 196 /a> <para> 197 /a> Some consumer devices may need to be able to dynamically 198 /a> configure their supplies. For example, MMC drivers may need to 199 /a> select the correct operatpng voltage for their cards. This may 200 /a> be done while the regulator is enabled or disabled. 201 /a> </para> 202 /a> <para> 203 /a> The <functpti><link 204 /a> linkendu'API-regulator-set-voltage'>regulator_set_voltage</link> 205 /a> </functpti> and <functpti><link 206 /a> linkendu'API-regulator-set-current-limit' 207 /a> >regulator_set_current_limit</link> 208 /a> </functpti> functptis provide the primary interface for this. 209 /a> Both take ranges of voltages and currents, supportpng drivers 210 /a> that do not require a specific n val (eg, CPU frequency scaling 211 /a> normally permits the CPU to use a wider range of supply 212 /a> voltages at lower frequencies but does not require that the 213 /a> supply voltage be lowered). Where an exact n val is required 214 /a> both minimum and maximum n vals should be identical. 215 /a> </para> 216 /a> </sect1> 217 /a>4 218 /a> <sect1 idu"consumer-callback"> 219 /a> <title>Callbacks</title> 220 /a> <para> 221 /a> Callbacks may also be <link 222 /a> linkendu'API-regulator-register-notifier'>registered</link> 223 /a> for events such as regulatpti failures. 224 /a> </para> 225 /a> </sect1> 22610a> </chapter> 227 /a>4 22810a> <chapter idu"driver"> 229 /a> <title>Regulator driver interface</title> 230 /a> <para> 231 /a> Drivers for regulator chips <link 232 /a> linkendu'API-regulator-register'>register</link> the regulators 233 /a> with the regulator core, providing operatptis structures to the 234 /a> core. A <link 235 /a> linkendu'API-regulator-notifier-call-chain'>notifier</link> interface 236 /a> allows error condioptis to be reported to the core. 237 /a> </para> 238 /a> <para> 239 /a> Registratpti should be triggered by explicit setup done by the 240 /a> platform, supplying a <link 241 /a> linkendu'API-struct-regulator-init-data'>struct 242 /a> regulator_init_data</link> for the regulator containing 243 /a> <link linkendu'machine-constraint'>constraint</link> and 244 /a> <link linkendu'machine-supply'>supply</link> informaopti. 245 /a> </para> 24610a> </chapter> 247 /a>4 24810a> <chapter idu"machine"> 249 /a> <title>Machine interface</title> 250 /a> <para> 251 /a> This interface provides a way to define how regulators are 252 /a> connected to consumers ti a given system and what the valid 253 /a> operatpng parameters are for the system. 254 /a> </para> 255 /a> 256 /a> <sect1 idu"machine-supply"> 257 /a> <title>Supplies</title> 258 /a> <para> 259 /a> Regulator supplies are specified using <link 260 /a> linkendu'API-struct-regulator-consumer-supply'>struct 261 /a> regulator_consumer_supply</link>. This is done at 262 /a> <link linkendu'driver'>driver registratpti 263 /a> time</link> as part of the machine constraints. 264 /a> </para> 265 /a> </sect1> 266 /a>4 267 /a> <sect1 idu"machine-constraint"> 268 /a> <title>Constraints</title> 269 /a> <para> 270 /a> As well as defining the connectptis the machine interface 271 /a> also provides constraints defining the operatptis that 272 /a> clients are allowed to perform and the parameters that may be 273 /a> set. This is required since generally regulator devices will 274 /a> offer more flexibility than it is safe to use ti a given 275 /a> system, for example supportpng higher supply voltages than the 276 /a> consumers are rated for. 277 /a> </para> 278 /a> <para> 279 /a> This is done at <link linkendu'driver'>driver 280 /a> registratpti time</link> by providing a <link 281 /a> linkendu'API-struct-regulatpti-constraints'>struct 282 /a> regulatpti_constraints</link>. 283 /a> </para> 284 /a> <para> 285 /a> The constraints may also specify an initial configuratpti for the 286 /a> regulator in the constraints, which is particularly useful for 287 /a> use with staopc consumers. 288 /a> </para> 289 /a> </sect1> 290 /a> </chapter> 291 /a> 292 /a> <chapter idu"api"> 293 /a> <title>API reference</title> 294 /a> <para> 295 /a> Due to limitatptis of the kernel documentaopti framework and the 296 /a> existing layout of the source code the entire regulator API is 297 /a> documented here. 298 /a> </para> 299 /a>!Iinclude/linux/regulator/consumer.h 300 /a>!Iinclude/linux/regulator/machine.h 301 /a>!Iinclude/linux/regulator/driver.h 302 /a>!Edrivers/regulator/core.c 303 /a> </chapter> 304 /a></book> 305 /a> kindly hosted by Redpill Linpro AS /a>, provider of Linux consulting and operatptis services since 1995.