1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 5<book id="regulator-api"> 6 <bookinfo> 7 <title>Voltage and current regulator API</title> 8 9 <authorgroup> 10 <author> 11 <firstname>Liam</firstname> 12 <surname>Girdwood</surname> 13 <affiliation> 14 <address> 15 <email>lrg@slimlogic.co.uk</email> 16 </address> 17 </affiliation> 18 </author> 19 <author> 20 <firstname>Mark</firstname> 21 <surname>Brown</surname> 22 <affiliation> 23 <orgname>Wolfson Microelectronics</orgname> 24 <address> 25 <email>broonie@opensource.wolfsonmicro.com</email> 26 </address> 27 </affiliation> 28 </author> 29 </authorgroup> 30 31 <copyright> 32 <year>2007-2008</year> 33 <holder>Wolfson Microelectronics</holder> 34 </copyright> 35 <copyright> 36 <year>2008</year> 37 <holder>Liam Girdwood</holder> 38 </copyright> 39 40 <legalnotice> 41 <para> 42 This documentation is free software; you can redistribute 43 it and/or modify it under the terms of the GNU General Public 44 License version 2 as published by the Free Software Foundation. 45 </para> 46 47 <para> 48 This program is distributed in the hope that it will be 49 useful, but WITHOUT ANY WARRANTY; without even the implied 50 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 51 See the GNU General Public License for more details. 52 </para> 53 54 <para> 55 You should have received a copy of the GNU General Public 56 License along with this program; if not, write to the Free 57 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 58 MA 02111-1307 USA 59 </para> 60 61 <para> 62 For more details see the file COPYING in the source 63 distribution of Linux. 64 </para> 65 </legalnotice> 66 </bookinfo> 67 68<toc></toc> 69 70 <chapter id="intro"> 71 <title>Introduction</title> 72 <para> 73 This framework is designed to provide a standard kernel 74 interface to control voltage and current regulators. 75 </para> 76 <para> 77 The intention is to allow systems to dynamically control 78 regulator power output in order to save power and prolong 79 battery life. This applies to both voltage regulators (where 80 voltage output is controllable) and current sinks (where current 81 limit is controllable). 82 </para> 83 <para> 84 Note that additional (and currently more complete) documentation 85 is available in the Linux kernel source under 86 <filename>Documentation/power/regulator</filename>. 87 </para> 88 89 <sect1 id="glossary"> 90 <title>Glossary</title> 91 <para> 92 The regulator API uses a number of terms which may not be 93 familiar: 94 </para> 95 <glossary> 96 97 <glossentry> 98 <glossterm>Regulator</glossterm> 99 <glossdef> 100 <para> 101 Electronic device that supplies power to other devices. Most 102 regulators can enable and disable their output and some can also 103 control their output voltage or current. 104 </para> 105 </glossdef> 106 </glossentry> 107 108 <glossentry> 109 <glossterm>Consumer</glossterm> 110 <glossdef> 111 <para> 112 Electronic device which consumes power provided by a regulator. 113 These may either be static, requiring only a fixed supply, or 114 dynamic, requiring active management of the regulator at 115 runtime. 116 </para> 117 </glossdef> 118 </glossentry> 119 120 <glossentry> 121 <glossterm>Power Domain</glossterm> 122 <glossdef> 123 <para> 124 The electronic circuit supplied by a given regulator, including 125 the regulator and all consumer devices. The configuration of 126 the regulator is shared between all the components in the 127 circuit. 128 </para> 129 </glossdef> 130 </glossentry> 131 132 <glossentry> 133 <glossterm>Power Management Integrated Circuit</glossterm> 134 <acronym>PMIC</acronym> 135 <glossdef> 136 <para> 137 An IC which contains numerous regulators and often also other 138 subsystems. In an embedded system the primary PMIC is often 139 equivalent to a combination of the PSU and southbridge in a 140 desktop system. 141 </para> 142 </glossdef> 143 </glossentry> 144 </glossary> 145 </sect1> 146 </chapter> 147 148 <chapter id="consumer"> 149 <title>Consumer driver interface</title> 150 <para> 151 This offers a similar API to the kernel clock framework. 152 Consumer drivers use <link 153 linkend='API-regulator-get'>get</link> and <link 154 linkend='API-regulator-put'>put</link> operations to acquire and 155 release regulators. Functions are 156 provided to <link linkend='API-regulator-enable'>enable</link> 157 and <link linkend='API-regulator-disable'>disable</link> the 158 reguator and to get and set the runtime parameters of the 159 regulator. 160 </para> 161 <para> 162 When requesting regulators consumers use symbolic names for their 163 supplies, such as "Vcc", which are mapped into actual regulator 164 devices by the machine interface. 165 </para> 166 <para> 167 A stub version of this API is provided when the regulator 168 framework is not in use in order to minimise the need to use 169 ifdefs. 170 </para> 171 172 <sect1 id="consumer-enable"> 173 <title>Enabling and disabling</title> 174 <para> 175 The regulator API provides reference counted enabling and 176 disabling of regulators. Consumer devices use the <function><link 177 linkend='API-regulator-enable'>regulator_enable</link></function> 178 and <function><link 179 linkend='API-regulator-disable'>regulator_disable</link> 180 </function> functions to enable and disable regulators. Calls 181 to the two functions must be balanced. 182 </para> 183 <para> 184 Note that since multiple consumers may be using a regulator and 185 machine constraints may not allow the regulator to be disabled 186 there is no guarantee that calling 187 <function>regulator_disable</function> will actually cause the 188 supply provided by the regulator to be disabled. Consumer 189 drivers should assume that the regulator may be enabled at all 190 times. 191 </para> 192 </sect1> 193 194 <sect1 id="consumer-config"> 195 <title>Configuration</title> 196 <para> 197 Some consumer devices may need to be able to dynamically 198 configure their supplies. For example, MMC drivers may need to 199 select the correct operating voltage for their cards. This may 200 be done while the regulator is enabled or disabled. 201 </para> 202 <para> 203 The <function><link 204 linkend='API-regulator-set-voltage'>regulator_set_voltage</link> 205 </function> and <function><link 206 linkend='API-regulator-set-current-limit' 207 >regulator_set_current_limit</link> 208 </function> functions provide the primary interface for this. 209 Both take ranges of voltages and currents, supporting drivers 210 that do not require a specific value (eg, CPU frequency scaling 211 normally permits the CPU to use a wider range of supply 212 voltages at lower frequencies but does not require that the 213 supply voltage be lowered). Where an exact value is required 214 both minimum and maximum values should be identical. 215 </para> 216 </sect1> 217 218 <sect1 id="consumer-callback"> 219 <title>Callbacks</title> 220 <para> 221 Callbacks may also be <link 222 linkend='API-regulator-register-notifier'>registered</link> 223 for events such as regulation failures. 224 </para> 225 </sect1> 226 </chapter> 227 228 <chapter id="driver"> 229 <title>Regulator driver interface</title> 230 <para> 231 Drivers for regulator chips <link 232 linkend='API-regulator-register'>register</link> the regulators 233 with the regulator core, providing operations structures to the 234 core. A <link 235 linkend='API-regulator-notifier-call-chain'>notifier</link> interface 236 allows error conditions to be reported to the core. 237 </para> 238 <para> 239 Registration should be triggered by explicit setup done by the 240 platform, supplying a <link 241 linkend='API-struct-regulator-init-data'>struct 242 regulator_init_data</link> for the regulator containing 243 <link linkend='machine-constraint'>constraint</link> and 244 <link linkend='machine-supply'>supply</link> information. 245 </para> 246 </chapter> 247 248 <chapter id="machine"> 249 <title>Machine interface</title> 250 <para> 251 This interface provides a way to define how regulators are 252 connected to consumers on a given system and what the valid 253 operating parameters are for the system. 254 </para> 255 256 <sect1 id="machine-supply"> 257 <title>Supplies</title> 258 <para> 259 Regulator supplies are specified using <link 260 linkend='API-struct-regulator-consumer-supply'>struct 261 regulator_consumer_supply</link>. This is done at 262 <link linkend='driver'>driver registration 263 time</link> as part of the machine constraints. 264 </para> 265 </sect1> 266 267 <sect1 id="machine-constraint"> 268 <title>Constraints</title> 269 <para> 270 As well as definining the connections the machine interface 271 also provides constraints definining the operations that 272 clients are allowed to perform and the parameters that may be 273 set. This is required since generally regulator devices will 274 offer more flexibility than it is safe to use on a given 275 system, for example supporting higher supply voltages than the 276 consumers are rated for. 277 </para> 278 <para> 279 This is done at <link linkend='driver'>driver 280 registration time</link> by providing a <link 281 linkend='API-struct-regulation-constraints'>struct 282 regulation_constraints</link>. 283 </para> 284 <para> 285 The constraints may also specify an initial configuration for the 286 regulator in the constraints, which is particularly useful for 287 use with static consumers. 288 </para> 289 </sect1> 290 </chapter> 291 292 <chapter id="api"> 293 <title>API reference</title> 294 <para> 295 Due to limitations of the kernel documentation framework and the 296 existing layout of the source code the entire regulator API is 297 documented here. 298 </para> 299!Iinclude/linux/regulator/consumer.h 300!Iinclude/linux/regulator/machine.h 301!Iinclude/linux/regulator/driver.h 302!Edrivers/regulator/core.c 303 </chapter> 304</book> 305