aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2008-08-01 13:56:40 -0400
committerLinus Torvalds <torvalds@linux-foundation.org>2008-08-01 13:56:40 -0400
commit561b35b341b1aeeab486affe1ede0ee6640ce33b (patch)
treea7570737884bef3c15db98cae629a82ce3586b3c /Documentation
parenta7c2a10dab4e5122cbcfa3d5e9d589a52ccc2287 (diff)
parent0eb5d5ab3ec99bfd22ff16797d95835369ffb25b (diff)
Merge branch 'reg-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/lrg/voltage-2.6
* 'reg-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/lrg/voltage-2.6: regulator: TI bq24022 Li-Ion Charger driver regulator: maintainers - add maintainers for regulator framework. regulator: documentation - ABI regulator: documentation - machine regulator: documentation - regulator driver regulator: documentation - consumer interface regulator: documentation - overview regulator: core kbuild files regulator: regulator test harness regulator: add support for fixed regulators. regulator: regulator framework core regulator: fixed regulator interface regulator: machine driver interface regulator: regulator driver interface regulator: consumer device interface
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/testing/sysfs-class-regulator315
-rw-r--r--Documentation/power/regulator/consumer.txt182
-rw-r--r--Documentation/power/regulator/machine.txt101
-rw-r--r--Documentation/power/regulator/overview.txt171
-rw-r--r--Documentation/power/regulator/regulator.txt30
5 files changed, 799 insertions, 0 deletions
diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator
new file mode 100644
index 000000000000..79a4a75b2d2c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-regulator
@@ -0,0 +1,315 @@
1What: /sys/class/regulator/.../state
2Date: April 2008
3KernelVersion: 2.6.26
4Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
5Description:
6 Each regulator directory will contain a field called
7 state. This holds the regulator output state.
8
9 This will be one of the following strings:
10
11 'enabled'
12 'disabled'
13 'unknown'
14
15 'enabled' means the regulator output is ON and is supplying
16 power to the system.
17
18 'disabled' means the regulator output is OFF and is not
19 supplying power to the system..
20
21 'unknown' means software cannot determine the state.
22
23 NOTE: this field can be used in conjunction with microvolts
24 and microamps to determine regulator output levels.
25
26
27What: /sys/class/regulator/.../type
28Date: April 2008
29KernelVersion: 2.6.26
30Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
31Description:
32 Each regulator directory will contain a field called
33 type. This holds the regulator type.
34
35 This will be one of the following strings:
36
37 'voltage'
38 'current'
39 'unknown'
40
41 'voltage' means the regulator output voltage can be controlled
42 by software.
43
44 'current' means the regulator output current limit can be
45 controlled by software.
46
47 'unknown' means software cannot control either voltage or
48 current limit.
49
50
51What: /sys/class/regulator/.../microvolts
52Date: April 2008
53KernelVersion: 2.6.26
54Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
55Description:
56 Each regulator directory will contain a field called
57 microvolts. This holds the regulator output voltage setting
58 measured in microvolts (i.e. E-6 Volts).
59
60 NOTE: This value should not be used to determine the regulator
61 output voltage level as this value is the same regardless of
62 whether the regulator is enabled or disabled.
63
64
65What: /sys/class/regulator/.../microamps
66Date: April 2008
67KernelVersion: 2.6.26
68Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
69Description:
70 Each regulator directory will contain a field called
71 microamps. This holds the regulator output current limit
72 setting measured in microamps (i.e. E-6 Amps).
73
74 NOTE: This value should not be used to determine the regulator
75 output current level as this value is the same regardless of
76 whether the regulator is enabled or disabled.
77
78
79What: /sys/class/regulator/.../opmode
80Date: April 2008
81KernelVersion: 2.6.26
82Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
83Description:
84 Each regulator directory will contain a field called
85 opmode. This holds the regulator operating mode setting.
86
87 The opmode value can be one of the following strings:
88
89 'fast'
90 'normal'
91 'idle'
92 'standby'
93 'unknown'
94
95 The modes are described in include/linux/regulator/regulator.h
96
97 NOTE: This value should not be used to determine the regulator
98 output operating mode as this value is the same regardless of
99 whether the regulator is enabled or disabled.
100
101
102What: /sys/class/regulator/.../min_microvolts
103Date: April 2008
104KernelVersion: 2.6.26
105Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
106Description:
107 Each regulator directory will contain a field called
108 min_microvolts. This holds the minimum safe working regulator
109 output voltage setting for this domain measured in microvolts.
110
111 NOTE: this will return the string 'constraint not defined' if
112 the power domain has no min microvolts constraint defined by
113 platform code.
114
115
116What: /sys/class/regulator/.../max_microvolts
117Date: April 2008
118KernelVersion: 2.6.26
119Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
120Description:
121 Each regulator directory will contain a field called
122 max_microvolts. This holds the maximum safe working regulator
123 output voltage setting for this domain measured in microvolts.
124
125 NOTE: this will return the string 'constraint not defined' if
126 the power domain has no max microvolts constraint defined by
127 platform code.
128
129
130What: /sys/class/regulator/.../min_microamps
131Date: April 2008
132KernelVersion: 2.6.26
133Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
134Description:
135 Each regulator directory will contain a field called
136 min_microamps. This holds the minimum safe working regulator
137 output current limit setting for this domain measured in
138 microamps.
139
140 NOTE: this will return the string 'constraint not defined' if
141 the power domain has no min microamps constraint defined by
142 platform code.
143
144
145What: /sys/class/regulator/.../max_microamps
146Date: April 2008
147KernelVersion: 2.6.26
148Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
149Description:
150 Each regulator directory will contain a field called
151 max_microamps. This holds the maximum safe working regulator
152 output current limit setting for this domain measured in
153 microamps.
154
155 NOTE: this will return the string 'constraint not defined' if
156 the power domain has no max microamps constraint defined by
157 platform code.
158
159
160What: /sys/class/regulator/.../num_users
161Date: April 2008
162KernelVersion: 2.6.26
163Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
164Description:
165 Each regulator directory will contain a field called
166 num_users. This holds the number of consumer devices that
167 have called regulator_enable() on this regulator.
168
169
170What: /sys/class/regulator/.../requested_microamps
171Date: April 2008
172KernelVersion: 2.6.26
173Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
174Description:
175 Each regulator directory will contain a field called
176 requested_microamps. This holds the total requested load
177 current in microamps for this regulator from all its consumer
178 devices.
179
180
181What: /sys/class/regulator/.../parent
182Date: April 2008
183KernelVersion: 2.6.26
184Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
185Description:
186 Some regulator directories will contain a link called parent.
187 This points to the parent or supply regulator if one exists.
188
189What: /sys/class/regulator/.../suspend_mem_microvolts
190Date: May 2008
191KernelVersion: 2.6.26
192Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
193Description:
194 Each regulator directory will contain a field called
195 suspend_mem_microvolts. This holds the regulator output
196 voltage setting for this domain measured in microvolts when
197 the system is suspended to memory.
198
199 NOTE: this will return the string 'not defined' if
200 the power domain has no suspend to memory voltage defined by
201 platform code.
202
203What: /sys/class/regulator/.../suspend_disk_microvolts
204Date: May 2008
205KernelVersion: 2.6.26
206Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
207Description:
208 Each regulator directory will contain a field called
209 suspend_disk_microvolts. This holds the regulator output
210 voltage setting for this domain measured in microvolts when
211 the system is suspended to disk.
212
213 NOTE: this will return the string 'not defined' if
214 the power domain has no suspend to disk voltage defined by
215 platform code.
216
217What: /sys/class/regulator/.../suspend_standby_microvolts
218Date: May 2008
219KernelVersion: 2.6.26
220Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
221Description:
222 Each regulator directory will contain a field called
223 suspend_standby_microvolts. This holds the regulator output
224 voltage setting for this domain measured in microvolts when
225 the system is suspended to standby.
226
227 NOTE: this will return the string 'not defined' if
228 the power domain has no suspend to standby voltage defined by
229 platform code.
230
231What: /sys/class/regulator/.../suspend_mem_mode
232Date: May 2008
233KernelVersion: 2.6.26
234Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
235Description:
236 Each regulator directory will contain a field called
237 suspend_mem_mode. This holds the regulator operating mode
238 setting for this domain when the system is suspended to
239 memory.
240
241 NOTE: this will return the string 'not defined' if
242 the power domain has no suspend to memory mode defined by
243 platform code.
244
245What: /sys/class/regulator/.../suspend_disk_mode
246Date: May 2008
247KernelVersion: 2.6.26
248Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
249Description:
250 Each regulator directory will contain a field called
251 suspend_disk_mode. This holds the regulator operating mode
252 setting for this domain when the system is suspended to disk.
253
254 NOTE: this will return the string 'not defined' if
255 the power domain has no suspend to disk mode defined by
256 platform code.
257
258What: /sys/class/regulator/.../suspend_standby_mode
259Date: May 2008
260KernelVersion: 2.6.26
261Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
262Description:
263 Each regulator directory will contain a field called
264 suspend_standby_mode. This holds the regulator operating mode
265 setting for this domain when the system is suspended to
266 standby.
267
268 NOTE: this will return the string 'not defined' if
269 the power domain has no suspend to standby mode defined by
270 platform code.
271
272What: /sys/class/regulator/.../suspend_mem_state
273Date: May 2008
274KernelVersion: 2.6.26
275Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
276Description:
277 Each regulator directory will contain a field called
278 suspend_mem_state. This holds the regulator operating state
279 when suspended to memory.
280
281 This will be one of the following strings:
282
283 'enabled'
284 'disabled'
285 'not defined'
286
287What: /sys/class/regulator/.../suspend_disk_state
288Date: May 2008
289KernelVersion: 2.6.26
290Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
291Description:
292 Each regulator directory will contain a field called
293 suspend_disk_state. This holds the regulator operating state
294 when suspended to disk.
295
296 This will be one of the following strings:
297
298 'enabled'
299 'disabled'
300 'not defined'
301
302What: /sys/class/regulator/.../suspend_standby_state
303Date: May 2008
304KernelVersion: 2.6.26
305Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com>
306Description:
307 Each regulator directory will contain a field called
308 suspend_standby_state. This holds the regulator operating
309 state when suspended to standby.
310
311 This will be one of the following strings:
312
313 'enabled'
314 'disabled'
315 'not defined'
diff --git a/Documentation/power/regulator/consumer.txt b/Documentation/power/regulator/consumer.txt
new file mode 100644
index 000000000000..82b7a43aadba
--- /dev/null
+++ b/Documentation/power/regulator/consumer.txt
@@ -0,0 +1,182 @@
1Regulator Consumer Driver Interface
2===================================
3
4This text describes the regulator interface for consumer device drivers.
5Please see overview.txt for a description of the terms used in this text.
6
7
81. Consumer Regulator Access (static & dynamic drivers)
9=======================================================
10
11A consumer driver can get access to it's supply regulator by calling :-
12
13regulator = regulator_get(dev, "Vcc");
14
15The consumer passes in it's struct device pointer and power supply ID. The core
16then finds the correct regulator by consulting a machine specific lookup table.
17If the lookup is successful then this call will return a pointer to the struct
18regulator that supplies this consumer.
19
20To release the regulator the consumer driver should call :-
21
22regulator_put(regulator);
23
24Consumers can be supplied by more than one regulator e.g. codec consumer with
25analog and digital supplies :-
26
27digital = regulator_get(dev, "Vcc"); /* digital core */
28analog = regulator_get(dev, "Avdd"); /* analog */
29
30The regulator access functions regulator_get() and regulator_put() will
31usually be called in your device drivers probe() and remove() respectively.
32
33
342. Regulator Output Enable & Disable (static & dynamic drivers)
35====================================================================
36
37A consumer can enable it's power supply by calling:-
38
39int regulator_enable(regulator);
40
41NOTE: The supply may already be enabled before regulator_enabled() is called.
42This may happen if the consumer shares the regulator or the regulator has been
43previously enabled by bootloader or kernel board initialization code.
44
45A consumer can determine if a regulator is enabled by calling :-
46
47int regulator_is_enabled(regulator);
48
49This will return > zero when the regulator is enabled.
50
51
52A consumer can disable it's supply when no longer needed by calling :-
53
54int regulator_disable(regulator);
55
56NOTE: This may not disable the supply if it's shared with other consumers. The
57regulator will only be disabled when the enabled reference count is zero.
58
59Finally, a regulator can be forcefully disabled in the case of an emergency :-
60
61int regulator_force_disable(regulator);
62
63NOTE: this will immediately and forcefully shutdown the regulator output. All
64consumers will be powered off.
65
66
673. Regulator Voltage Control & Status (dynamic drivers)
68======================================================
69
70Some consumer drivers need to be able to dynamically change their supply
71voltage to match system operating points. e.g. CPUfreq drivers can scale
72voltage along with frequency to save power, SD drivers may need to select the
73correct card voltage, etc.
74
75Consumers can control their supply voltage by calling :-
76
77int regulator_set_voltage(regulator, min_uV, max_uV);
78
79Where min_uV and max_uV are the minimum and maximum acceptable voltages in
80microvolts.
81
82NOTE: this can be called when the regulator is enabled or disabled. If called
83when enabled, then the voltage changes instantly, otherwise the voltage
84configuration changes and the voltage is physically set when the regulator is
85next enabled.
86
87The regulators configured voltage output can be found by calling :-
88
89int regulator_get_voltage(regulator);
90
91NOTE: get_voltage() will return the configured output voltage whether the
92regulator is enabled or disabled and should NOT be used to determine regulator
93output state. However this can be used in conjunction with is_enabled() to
94determine the regulator physical output voltage.
95
96
974. Regulator Current Limit Control & Status (dynamic drivers)
98===========================================================
99
100Some consumer drivers need to be able to dynamically change their supply
101current limit to match system operating points. e.g. LCD backlight driver can
102change the current limit to vary the backlight brightness, USB drivers may want
103to set the limit to 500mA when supplying power.
104
105Consumers can control their supply current limit by calling :-
106
107int regulator_set_current_limit(regulator, min_uV, max_uV);
108
109Where min_uA and max_uA are the minimum and maximum acceptable current limit in
110microamps.
111
112NOTE: this can be called when the regulator is enabled or disabled. If called
113when enabled, then the current limit changes instantly, otherwise the current
114limit configuration changes and the current limit is physically set when the
115regulator is next enabled.
116
117A regulators current limit can be found by calling :-
118
119int regulator_get_current_limit(regulator);
120
121NOTE: get_current_limit() will return the current limit whether the regulator
122is enabled or disabled and should not be used to determine regulator current
123load.
124
125
1265. Regulator Operating Mode Control & Status (dynamic drivers)
127=============================================================
128
129Some consumers can further save system power by changing the operating mode of
130their supply regulator to be more efficient when the consumers operating state
131changes. e.g. consumer driver is idle and subsequently draws less current
132
133Regulator operating mode can be changed indirectly or directly.
134
135Indirect operating mode control.
136--------------------------------
137Consumer drivers can request a change in their supply regulator operating mode
138by calling :-
139
140int regulator_set_optimum_mode(struct regulator *regulator, int load_uA);
141
142This will cause the core to recalculate the total load on the regulator (based
143on all it's consumers) and change operating mode (if necessary and permitted)
144to best match the current operating load.
145
146The load_uA value can be determined from the consumers datasheet. e.g.most
147datasheets have tables showing the max current consumed in certain situations.
148
149Most consumers will use indirect operating mode control since they have no
150knowledge of the regulator or whether the regulator is shared with other
151consumers.
152
153Direct operating mode control.
154------------------------------
155Bespoke or tightly coupled drivers may want to directly control regulator
156operating mode depending on their operating point. This can be achieved by
157calling :-
158
159int regulator_set_mode(struct regulator *regulator, unsigned int mode);
160unsigned int regulator_get_mode(struct regulator *regulator);
161
162Direct mode will only be used by consumers that *know* about the regulator and
163are not sharing the regulator with other consumers.
164
165
1666. Regulator Events
167===================
168Regulators can notify consumers of external events. Events could be received by
169consumers under regulator stress or failure conditions.
170
171Consumers can register interest in regulator events by calling :-
172
173int regulator_register_notifier(struct regulator *regulator,
174 struct notifier_block *nb);
175
176Consumers can uregister interest by calling :-
177
178int regulator_unregister_notifier(struct regulator *regulator,
179 struct notifier_block *nb);
180
181Regulators use the kernel notifier framework to send event to thier interested
182consumers.
diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.txt
new file mode 100644
index 000000000000..c9a35665cf70
--- /dev/null
+++ b/Documentation/power/regulator/machine.txt
@@ -0,0 +1,101 @@
1Regulator Machine Driver Interface
2===================================
3
4The regulator machine driver interface is intended for board/machine specific
5initialisation code to configure the regulator subsystem. Typical things that
6machine drivers would do are :-
7
8 1. Regulator -> Device mapping.
9 2. Regulator supply configuration.
10 3. Power Domain constraint setting.
11
12
13
141. Regulator -> device mapping
15==============================
16Consider the following machine :-
17
18 Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
19 |
20 +-> [Consumer B @ 3.3V]
21
22The drivers for consumers A & B must be mapped to the correct regulator in
23order to control their power supply. This mapping can be achieved in machine
24initialisation code by calling :-
25
26int regulator_set_device_supply(const char *regulator, struct device *dev,
27 const char *supply);
28
29and is shown with the following code :-
30
31regulator_set_device_supply("Regulator-1", devB, "Vcc");
32regulator_set_device_supply("Regulator-2", devA, "Vcc");
33
34This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2
35to the 'Vcc' supply for Consumer A.
36
37
382. Regulator supply configuration.
39==================================
40Consider the following machine (again) :-
41
42 Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
43 |
44 +-> [Consumer B @ 3.3V]
45
46Regulator-1 supplies power to Regulator-2. This relationship must be registered
47with the core so that Regulator-1 is also enabled when Consumer A enables it's
48supply (Regulator-2).
49
50This relationship can be register with the core via :-
51
52int regulator_set_supply(const char *regulator, const char *regulator_supply);
53
54In this example we would use the following code :-
55
56regulator_set_supply("Regulator-2", "Regulator-1");
57
58Relationships can be queried by calling :-
59
60const char *regulator_get_supply(const char *regulator);
61
62
633. Power Domain constraint setting.
64===================================
65Each power domain within a system has physical constraints on voltage and
66current. This must be defined in software so that the power domain is always
67operated within specifications.
68
69Consider the following machine (again) :-
70
71 Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
72 |
73 +-> [Consumer B @ 3.3V]
74
75This gives us two regulators and two power domains:
76
77 Domain 1: Regulator-2, Consumer B.
78 Domain 2: Consumer A.
79
80Constraints can be registered by calling :-
81
82int regulator_set_platform_constraints(const char *regulator,
83 struct regulation_constraints *constraints);
84
85The example is defined as follows :-
86
87struct regulation_constraints domain_1 = {
88 .min_uV = 3300000,
89 .max_uV = 3300000,
90 .valid_modes_mask = REGULATOR_MODE_NORMAL,
91};
92
93struct regulation_constraints domain_2 = {
94 .min_uV = 1800000,
95 .max_uV = 2000000,
96 .valid_ops_mask = REGULATOR_CHANGE_VOLTAGE,
97 .valid_modes_mask = REGULATOR_MODE_NORMAL,
98};
99
100regulator_set_platform_constraints("Regulator-1", &domain_1);
101regulator_set_platform_constraints("Regulator-2", &domain_2);
diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.txt
new file mode 100644
index 000000000000..bdcb332bd7fb
--- /dev/null
+++ b/Documentation/power/regulator/overview.txt
@@ -0,0 +1,171 @@
1Linux voltage and current regulator framework
2=============================================
3
4About
5=====
6
7This framework is designed to provide a standard kernel interface to control
8voltage and current regulators.
9
10The intention is to allow systems to dynamically control regulator power output
11in order to save power and prolong battery life. This applies to both voltage
12regulators (where voltage output is controllable) and current sinks (where
13current limit is controllable).
14
15(C) 2008 Wolfson Microelectronics PLC.
16Author: Liam Girdwood <lg@opensource.wolfsonmicro.com>
17
18
19Nomenclature
20============
21
22Some terms used in this document:-
23
24 o Regulator - Electronic device that supplies power to other devices.
25 Most regulators can enable and disable their output whilst
26 some can control their output voltage and or current.
27
28 Input Voltage -> Regulator -> Output Voltage
29
30
31 o PMIC - Power Management IC. An IC that contains numerous regulators
32 and often contains other susbsystems.
33
34
35 o Consumer - Electronic device that is supplied power by a regulator.
36 Consumers can be classified into two types:-
37
38 Static: consumer does not change it's supply voltage or
39 current limit. It only needs to enable or disable it's
40 power supply. It's supply voltage is set by the hardware,
41 bootloader, firmware or kernel board initialisation code.
42
43 Dynamic: consumer needs to change it's supply voltage or
44 current limit to meet operation demands.
45
46
47 o Power Domain - Electronic circuit that is supplied it's input power by the
48 output power of a regulator, switch or by another power
49 domain.
50
51 The supply regulator may be behind a switch(s). i.e.
52
53 Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
54 | |
55 | +-> [Consumer B], [Consumer C]
56 |
57 +-> [Consumer D], [Consumer E]
58
59 That is one regulator and three power domains:
60
61 Domain 1: Switch-1, Consumers D & E.
62 Domain 2: Switch-2, Consumers B & C.
63 Domain 3: Consumer A.
64
65 and this represents a "supplies" relationship:
66
67 Domain-1 --> Domain-2 --> Domain-3.
68
69 A power domain may have regulators that are supplied power
70 by other regulators. i.e.
71
72 Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
73 |
74 +-> [Consumer B]
75
76 This gives us two regulators and two power domains:
77
78 Domain 1: Regulator-2, Consumer B.
79 Domain 2: Consumer A.
80
81 and a "supplies" relationship:
82
83 Domain-1 --> Domain-2
84
85
86 o Constraints - Constraints are used to define power levels for performance
87 and hardware protection. Constraints exist at three levels:
88
89 Regulator Level: This is defined by the regulator hardware
90 operating parameters and is specified in the regulator
91 datasheet. i.e.
92
93 - voltage output is in the range 800mV -> 3500mV.
94 - regulator current output limit is 20mA @ 5V but is
95 10mA @ 10V.
96
97 Power Domain Level: This is defined in software by kernel
98 level board initialisation code. It is used to constrain a
99 power domain to a particular power range. i.e.
100
101 - Domain-1 voltage is 3300mV
102 - Domain-2 voltage is 1400mV -> 1600mV
103 - Domain-3 current limit is 0mA -> 20mA.
104
105 Consumer Level: This is defined by consumer drivers
106 dynamically setting voltage or current limit levels.
107
108 e.g. a consumer backlight driver asks for a current increase
109 from 5mA to 10mA to increase LCD illumination. This passes
110 to through the levels as follows :-
111
112 Consumer: need to increase LCD brightness. Lookup and
113 request next current mA value in brightness table (the
114 consumer driver could be used on several different
115 personalities based upon the same reference device).
116
117 Power Domain: is the new current limit within the domain
118 operating limits for this domain and system state (e.g.
119 battery power, USB power)
120
121 Regulator Domains: is the new current limit within the
122 regulator operating parameters for input/ouput voltage.
123
124 If the regulator request passes all the constraint tests
125 then the new regulator value is applied.
126
127
128Design
129======
130
131The framework is designed and targeted at SoC based devices but may also be
132relevant to non SoC devices and is split into the following four interfaces:-
133
134
135 1. Consumer driver interface.
136
137 This uses a similar API to the kernel clock interface in that consumer
138 drivers can get and put a regulator (like they can with clocks atm) and
139 get/set voltage, current limit, mode, enable and disable. This should
140 allow consumers complete control over their supply voltage and current
141 limit. This also compiles out if not in use so drivers can be reused in
142 systems with no regulator based power control.
143
144 See Documentation/power/regulator/consumer.txt
145
146 2. Regulator driver interface.
147
148 This allows regulator drivers to register their regulators and provide
149 operations to the core. It also has a notifier call chain for propagating
150 regulator events to clients.
151
152 See Documentation/power/regulator/regulator.txt
153
154 3. Machine interface.
155
156 This interface is for machine specific code and allows the creation of
157 voltage/current domains (with constraints) for each regulator. It can
158 provide regulator constraints that will prevent device damage through
159 overvoltage or over current caused by buggy client drivers. It also
160 allows the creation of a regulator tree whereby some regulators are
161 supplied by others (similar to a clock tree).
162
163 See Documentation/power/regulator/machine.txt
164
165 4. Userspace ABI.
166
167 The framework also exports a lot of useful voltage/current/opmode data to
168 userspace via sysfs. This could be used to help monitor device power
169 consumption and status.
170
171 See Documentation/ABI/testing/regulator-sysfs.txt
diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt
new file mode 100644
index 000000000000..a69050143592
--- /dev/null
+++ b/Documentation/power/regulator/regulator.txt
@@ -0,0 +1,30 @@
1Regulator Driver Interface
2==========================
3
4The regulator driver interface is relatively simple and designed to allow
5regulator drivers to register their services with the core framework.
6
7
8Registration
9============
10
11Drivers can register a regulator by calling :-
12
13struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
14 void *reg_data);
15
16This will register the regulators capabilities and operations the regulator
17core. The core does not touch reg_data (private to regulator driver).
18
19Regulators can be unregistered by calling :-
20
21void regulator_unregister(struct regulator_dev *rdev);
22
23
24Regulator Events
25================
26Regulators can send events (e.g. over temp, under voltage, etc) to consumer
27drivers by calling :-
28
29int regulator_notifier_call_chain(struct regulator_dev *rdev,
30 unsigned long event, void *data);