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       regulator 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