tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
regulator: Add basic DocBook manual
Add a basic DocBook manual for the regulator API. This is much more
skeletal than the existing text documentation, the main benefit is to
provide a skeleton for automatic generation of a manual based on the
kerneldoc for the API.
Since large portions of the text are lifted from the existing text format
documentation written by Liam Girdwood much of the credit belongs to
him.
Signed-off-by: Mark Brown <broonie@opensource.wolfsonmicro.com>
Signed-off-by: Liam Girdwood <lrg@slimlogic.co.uk>
authored by
Mark Brown
and committed by
Liam Girdwood
9fe5817f
cf7bbcdf
+305
-1
+1
-1
Documentation/DocBook/Makefile
+1
-1
Documentation/DocBook/Makefile
···
12
12
kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
13
13
gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
14
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
18
# The build process is as follows (targets):
+304
Documentation/DocBook/regulator.tmpl
+304
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 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>