About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / regulator.tmpl




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

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>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.