linux/Documentation/DocBook/regulator.tmpl
<<
>>
Prefs
   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 defining the connections the machine interface
 271         also provides constraints defining 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
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.