aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/testing/sysfs-class-regulator136
-rw-r--r--Documentation/DocBook/Makefile2
-rw-r--r--Documentation/DocBook/regulator.tmpl304
3 files changed, 365 insertions, 77 deletions
diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator
index 3731f6f29bcb..873ef1fc1569 100644
--- a/Documentation/ABI/testing/sysfs-class-regulator
+++ b/Documentation/ABI/testing/sysfs-class-regulator
@@ -3,8 +3,9 @@ Date: April 2008
3KernelVersion: 2.6.26 3KernelVersion: 2.6.26
4Contact: Liam Girdwood <lrg@slimlogic.co.uk> 4Contact: Liam Girdwood <lrg@slimlogic.co.uk>
5Description: 5Description:
6 Each regulator directory will contain a field called 6 Some regulator directories will contain a field called
7 state. This holds the regulator output state. 7 state. This reports the regulator enable status, for
8 regulators which can report that value.
8 9
9 This will be one of the following strings: 10 This will be one of the following strings:
10 11
@@ -18,7 +19,8 @@ Description:
18 'disabled' means the regulator output is OFF and is not 19 'disabled' means the regulator output is OFF and is not
19 supplying power to the system.. 20 supplying power to the system..
20 21
21 'unknown' means software cannot determine the state. 22 'unknown' means software cannot determine the state, or
23 the reported state is invalid.
22 24
23 NOTE: this field can be used in conjunction with microvolts 25 NOTE: this field can be used in conjunction with microvolts
24 and microamps to determine regulator output levels. 26 and microamps to determine regulator output levels.
@@ -53,9 +55,10 @@ Date: April 2008
53KernelVersion: 2.6.26 55KernelVersion: 2.6.26
54Contact: Liam Girdwood <lrg@slimlogic.co.uk> 56Contact: Liam Girdwood <lrg@slimlogic.co.uk>
55Description: 57Description:
56 Each regulator directory will contain a field called 58 Some regulator directories will contain a field called
57 microvolts. This holds the regulator output voltage setting 59 microvolts. This holds the regulator output voltage setting
58 measured in microvolts (i.e. E-6 Volts). 60 measured in microvolts (i.e. E-6 Volts), for regulators
61 which can report that voltage.
59 62
60 NOTE: This value should not be used to determine the regulator 63 NOTE: This value should not be used to determine the regulator
61 output voltage level as this value is the same regardless of 64 output voltage level as this value is the same regardless of
@@ -67,9 +70,10 @@ Date: April 2008
67KernelVersion: 2.6.26 70KernelVersion: 2.6.26
68Contact: Liam Girdwood <lrg@slimlogic.co.uk> 71Contact: Liam Girdwood <lrg@slimlogic.co.uk>
69Description: 72Description:
70 Each regulator directory will contain a field called 73 Some regulator directories will contain a field called
71 microamps. This holds the regulator output current limit 74 microamps. This holds the regulator output current limit
72 setting measured in microamps (i.e. E-6 Amps). 75 setting measured in microamps (i.e. E-6 Amps), for regulators
76 which can report that current.
73 77
74 NOTE: This value should not be used to determine the regulator 78 NOTE: This value should not be used to determine the regulator
75 output current level as this value is the same regardless of 79 output current level as this value is the same regardless of
@@ -81,8 +85,9 @@ Date: April 2008
81KernelVersion: 2.6.26 85KernelVersion: 2.6.26
82Contact: Liam Girdwood <lrg@slimlogic.co.uk> 86Contact: Liam Girdwood <lrg@slimlogic.co.uk>
83Description: 87Description:
84 Each regulator directory will contain a field called 88 Some regulator directories will contain a field called
85 opmode. This holds the regulator operating mode setting. 89 opmode. This holds the current regulator operating mode,
90 for regulators which can report it.
86 91
87 The opmode value can be one of the following strings: 92 The opmode value can be one of the following strings:
88 93
@@ -92,7 +97,7 @@ Description:
92 'standby' 97 'standby'
93 'unknown' 98 'unknown'
94 99
95 The modes are described in include/linux/regulator/regulator.h 100 The modes are described in include/linux/regulator/consumer.h
96 101
97 NOTE: This value should not be used to determine the regulator 102 NOTE: This value should not be used to determine the regulator
98 output operating mode as this value is the same regardless of 103 output operating mode as this value is the same regardless of
@@ -104,9 +109,10 @@ Date: April 2008
104KernelVersion: 2.6.26 109KernelVersion: 2.6.26
105Contact: Liam Girdwood <lrg@slimlogic.co.uk> 110Contact: Liam Girdwood <lrg@slimlogic.co.uk>
106Description: 111Description:
107 Each regulator directory will contain a field called 112 Some regulator directories will contain a field called
108 min_microvolts. This holds the minimum safe working regulator 113 min_microvolts. This holds the minimum safe working regulator
109 output voltage setting for this domain measured in microvolts. 114 output voltage setting for this domain measured in microvolts,
115 for regulators which support voltage constraints.
110 116
111 NOTE: this will return the string 'constraint not defined' if 117 NOTE: this will return the string 'constraint not defined' if
112 the power domain has no min microvolts constraint defined by 118 the power domain has no min microvolts constraint defined by
@@ -118,9 +124,10 @@ Date: April 2008
118KernelVersion: 2.6.26 124KernelVersion: 2.6.26
119Contact: Liam Girdwood <lrg@slimlogic.co.uk> 125Contact: Liam Girdwood <lrg@slimlogic.co.uk>
120Description: 126Description:
121 Each regulator directory will contain a field called 127 Some regulator directories will contain a field called
122 max_microvolts. This holds the maximum safe working regulator 128 max_microvolts. This holds the maximum safe working regulator
123 output voltage setting for this domain measured in microvolts. 129 output voltage setting for this domain measured in microvolts,
130 for regulators which support voltage constraints.
124 131
125 NOTE: this will return the string 'constraint not defined' if 132 NOTE: this will return the string 'constraint not defined' if
126 the power domain has no max microvolts constraint defined by 133 the power domain has no max microvolts constraint defined by
@@ -132,10 +139,10 @@ Date: April 2008
132KernelVersion: 2.6.26 139KernelVersion: 2.6.26
133Contact: Liam Girdwood <lrg@slimlogic.co.uk> 140Contact: Liam Girdwood <lrg@slimlogic.co.uk>
134Description: 141Description:
135 Each regulator directory will contain a field called 142 Some regulator directories will contain a field called
136 min_microamps. This holds the minimum safe working regulator 143 min_microamps. This holds the minimum safe working regulator
137 output current limit setting for this domain measured in 144 output current limit setting for this domain measured in
138 microamps. 145 microamps, for regulators which support current constraints.
139 146
140 NOTE: this will return the string 'constraint not defined' if 147 NOTE: this will return the string 'constraint not defined' if
141 the power domain has no min microamps constraint defined by 148 the power domain has no min microamps constraint defined by
@@ -147,10 +154,10 @@ Date: April 2008
147KernelVersion: 2.6.26 154KernelVersion: 2.6.26
148Contact: Liam Girdwood <lrg@slimlogic.co.uk> 155Contact: Liam Girdwood <lrg@slimlogic.co.uk>
149Description: 156Description:
150 Each regulator directory will contain a field called 157 Some regulator directories will contain a field called
151 max_microamps. This holds the maximum safe working regulator 158 max_microamps. This holds the maximum safe working regulator
152 output current limit setting for this domain measured in 159 output current limit setting for this domain measured in
153 microamps. 160 microamps, for regulators which support current constraints.
154 161
155 NOTE: this will return the string 'constraint not defined' if 162 NOTE: this will return the string 'constraint not defined' if
156 the power domain has no max microamps constraint defined by 163 the power domain has no max microamps constraint defined by
@@ -185,7 +192,7 @@ Date: April 2008
185KernelVersion: 2.6.26 192KernelVersion: 2.6.26
186Contact: Liam Girdwood <lrg@slimlogic.co.uk> 193Contact: Liam Girdwood <lrg@slimlogic.co.uk>
187Description: 194Description:
188 Each regulator directory will contain a field called 195 Some regulator directories will contain a field called
189 requested_microamps. This holds the total requested load 196 requested_microamps. This holds the total requested load
190 current in microamps for this regulator from all its consumer 197 current in microamps for this regulator from all its consumer
191 devices. 198 devices.
@@ -204,125 +211,102 @@ Date: May 2008
204KernelVersion: 2.6.26 211KernelVersion: 2.6.26
205Contact: Liam Girdwood <lrg@slimlogic.co.uk> 212Contact: Liam Girdwood <lrg@slimlogic.co.uk>
206Description: 213Description:
207 Each regulator directory will contain a field called 214 Some regulator directories will contain a field called
208 suspend_mem_microvolts. This holds the regulator output 215 suspend_mem_microvolts. This holds the regulator output
209 voltage setting for this domain measured in microvolts when 216 voltage setting for this domain measured in microvolts when
210 the system is suspended to memory. 217 the system is suspended to memory, for voltage regulators
211 218 implementing suspend voltage configuration constraints.
212 NOTE: this will return the string 'not defined' if
213 the power domain has no suspend to memory voltage defined by
214 platform code.
215 219
216What: /sys/class/regulator/.../suspend_disk_microvolts 220What: /sys/class/regulator/.../suspend_disk_microvolts
217Date: May 2008 221Date: May 2008
218KernelVersion: 2.6.26 222KernelVersion: 2.6.26
219Contact: Liam Girdwood <lrg@slimlogic.co.uk> 223Contact: Liam Girdwood <lrg@slimlogic.co.uk>
220Description: 224Description:
221 Each regulator directory will contain a field called 225 Some regulator directories will contain a field called
222 suspend_disk_microvolts. This holds the regulator output 226 suspend_disk_microvolts. This holds the regulator output
223 voltage setting for this domain measured in microvolts when 227 voltage setting for this domain measured in microvolts when
224 the system is suspended to disk. 228 the system is suspended to disk, for voltage regulators
225 229 implementing suspend voltage configuration constraints.
226 NOTE: this will return the string 'not defined' if
227 the power domain has no suspend to disk voltage defined by
228 platform code.
229 230
230What: /sys/class/regulator/.../suspend_standby_microvolts 231What: /sys/class/regulator/.../suspend_standby_microvolts
231Date: May 2008 232Date: May 2008
232KernelVersion: 2.6.26 233KernelVersion: 2.6.26
233Contact: Liam Girdwood <lrg@slimlogic.co.uk> 234Contact: Liam Girdwood <lrg@slimlogic.co.uk>
234Description: 235Description:
235 Each regulator directory will contain a field called 236 Some regulator directories will contain a field called
236 suspend_standby_microvolts. This holds the regulator output 237 suspend_standby_microvolts. This holds the regulator output
237 voltage setting for this domain measured in microvolts when 238 voltage setting for this domain measured in microvolts when
238 the system is suspended to standby. 239 the system is suspended to standby, for voltage regulators
239 240 implementing suspend voltage configuration constraints.
240 NOTE: this will return the string 'not defined' if
241 the power domain has no suspend to standby voltage defined by
242 platform code.
243 241
244What: /sys/class/regulator/.../suspend_mem_mode 242What: /sys/class/regulator/.../suspend_mem_mode
245Date: May 2008 243Date: May 2008
246KernelVersion: 2.6.26 244KernelVersion: 2.6.26
247Contact: Liam Girdwood <lrg@slimlogic.co.uk> 245Contact: Liam Girdwood <lrg@slimlogic.co.uk>
248Description: 246Description:
249 Each regulator directory will contain a field called 247 Some regulator directories will contain a field called
250 suspend_mem_mode. This holds the regulator operating mode 248 suspend_mem_mode. This holds the regulator operating mode
251 setting for this domain when the system is suspended to 249 setting for this domain when the system is suspended to
252 memory. 250 memory, for regulators implementing suspend mode
253 251 configuration constraints.
254 NOTE: this will return the string 'not defined' if
255 the power domain has no suspend to memory mode defined by
256 platform code.
257 252
258What: /sys/class/regulator/.../suspend_disk_mode 253What: /sys/class/regulator/.../suspend_disk_mode
259Date: May 2008 254Date: May 2008
260KernelVersion: 2.6.26 255KernelVersion: 2.6.26
261Contact: Liam Girdwood <lrg@slimlogic.co.uk> 256Contact: Liam Girdwood <lrg@slimlogic.co.uk>
262Description: 257Description:
263 Each regulator directory will contain a field called 258 Some regulator directories will contain a field called
264 suspend_disk_mode. This holds the regulator operating mode 259 suspend_disk_mode. This holds the regulator operating mode
265 setting for this domain when the system is suspended to disk. 260 setting for this domain when the system is suspended to disk,
266 261 for regulators implementing suspend mode configuration
267 NOTE: this will return the string 'not defined' if 262 constraints.
268 the power domain has no suspend to disk mode defined by
269 platform code.
270 263
271What: /sys/class/regulator/.../suspend_standby_mode 264What: /sys/class/regulator/.../suspend_standby_mode
272Date: May 2008 265Date: May 2008
273KernelVersion: 2.6.26 266KernelVersion: 2.6.26
274Contact: Liam Girdwood <lrg@slimlogic.co.uk> 267Contact: Liam Girdwood <lrg@slimlogic.co.uk>
275Description: 268Description:
276 Each regulator directory will contain a field called 269 Some regulator directories will contain a field called
277 suspend_standby_mode. This holds the regulator operating mode 270 suspend_standby_mode. This holds the regulator operating mode
278 setting for this domain when the system is suspended to 271 setting for this domain when the system is suspended to
279 standby. 272 standby, for regulators implementing suspend mode
280 273 configuration constraints.
281 NOTE: this will return the string 'not defined' if
282 the power domain has no suspend to standby mode defined by
283 platform code.
284 274
285What: /sys/class/regulator/.../suspend_mem_state 275What: /sys/class/regulator/.../suspend_mem_state
286Date: May 2008 276Date: May 2008
287KernelVersion: 2.6.26 277KernelVersion: 2.6.26
288Contact: Liam Girdwood <lrg@slimlogic.co.uk> 278Contact: Liam Girdwood <lrg@slimlogic.co.uk>
289Description: 279Description:
290 Each regulator directory will contain a field called 280 Some regulator directories will contain a field called
291 suspend_mem_state. This holds the regulator operating state 281 suspend_mem_state. This holds the regulator operating state
292 when suspended to memory. 282 when suspended to memory, for regulators implementing suspend
293 283 configuration constraints.
294 This will be one of the following strings:
295 284
296 'enabled' 285 This will be one of the same strings reported by
297 'disabled' 286 the "state" attribute.
298 'not defined'
299 287
300What: /sys/class/regulator/.../suspend_disk_state 288What: /sys/class/regulator/.../suspend_disk_state
301Date: May 2008 289Date: May 2008
302KernelVersion: 2.6.26 290KernelVersion: 2.6.26
303Contact: Liam Girdwood <lrg@slimlogic.co.uk> 291Contact: Liam Girdwood <lrg@slimlogic.co.uk>
304Description: 292Description:
305 Each regulator directory will contain a field called 293 Some regulator directories will contain a field called
306 suspend_disk_state. This holds the regulator operating state 294 suspend_disk_state. This holds the regulator operating state
307 when suspended to disk. 295 when suspended to disk, for regulators implementing
308 296 suspend configuration constraints.
309 This will be one of the following strings:
310 297
311 'enabled' 298 This will be one of the same strings reported by
312 'disabled' 299 the "state" attribute.
313 'not defined'
314 300
315What: /sys/class/regulator/.../suspend_standby_state 301What: /sys/class/regulator/.../suspend_standby_state
316Date: May 2008 302Date: May 2008
317KernelVersion: 2.6.26 303KernelVersion: 2.6.26
318Contact: Liam Girdwood <lrg@slimlogic.co.uk> 304Contact: Liam Girdwood <lrg@slimlogic.co.uk>
319Description: 305Description:
320 Each regulator directory will contain a field called 306 Some regulator directories will contain a field called
321 suspend_standby_state. This holds the regulator operating 307 suspend_standby_state. This holds the regulator operating
322 state when suspended to standby. 308 state when suspended to standby, for regulators implementing
323 309 suspend configuration constraints.
324 This will be one of the following strings:
325 310
326 'enabled' 311 This will be one of the same strings reported by
327 'disabled' 312 the "state" attribute.
328 'not defined'
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 0a08126d3094..dc3154e49279 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -12,7 +12,7 @@ DOCBOOKS := z8530book.xml mcabook.xml \
12 kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ 12 kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ 13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ 14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
15 mac80211.xml debugobjects.xml sh.xml 15 mac80211.xml debugobjects.xml sh.xml regulator.xml
16 16
17### 17###
18# The build process is as follows (targets): 18# The build process is as follows (targets):
diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl
new file mode 100644
index 000000000000..53f4f8d3b810
--- /dev/null
+++ b/Documentation/DocBook/regulator.tmpl
@@ -0,0 +1,304 @@
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>