Documentation/DocBook/regulator.tmpl

   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>