blob: 55c4175d80996fbb75cca8ed33e85691697988ff [file] [log] [blame]
Liam Girdwood63927762008-04-30 17:19:02 +01001Regulator 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
Francis Galieguea33f3222010-04-23 00:08:02 +020011A consumer driver can get access to its supply regulator by calling :-
Liam Girdwood63927762008-04-30 17:19:02 +010012
13regulator = regulator_get(dev, "Vcc");
14
Francis Galieguea33f3222010-04-23 00:08:02 +020015The consumer passes in its struct device pointer and power supply ID. The core
Liam Girdwood63927762008-04-30 17:19:02 +010016then 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
Francis Galieguea33f3222010-04-23 00:08:02 +020037A consumer can enable its power supply by calling:-
Liam Girdwood63927762008-04-30 17:19:02 +010038
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
Francis Galieguea33f3222010-04-23 00:08:02 +020052A consumer can disable its supply when no longer needed by calling :-
Liam Girdwood63927762008-04-30 17:19:02 +010053
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
Dr. David Alan Gilbert1b35eda2009-11-22 14:53:15 +0000107int regulator_set_current_limit(regulator, min_uA, max_uA);
Liam Girdwood63927762008-04-30 17:19:02 +0100108
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
Francis Galieguea33f3222010-04-23 00:08:02 +0200143on all its consumers) and change operating mode (if necessary and permitted)
Liam Girdwood63927762008-04-30 17:19:02 +0100144to 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
Matt LaPlante19f59462009-04-27 15:06:31 +0200181Regulators use the kernel notifier framework to send event to their interested
Liam Girdwood63927762008-04-30 17:19:02 +0100182consumers.