1===================================
2Regulator Consumer Driver Interface
3===================================
4
5This text describes the regulator interface for consumer device drivers.
6Please see overview.txt for a description of the terms used in this text.
7
8
91. Consumer Regulator Access (static & dynamic drivers)
10=======================================================
11
12A consumer driver can get access to its supply regulator by calling ::
13
14	regulator = regulator_get(dev, "Vcc");
15
16The consumer passes in its struct device pointer and power supply ID. The core
17then finds the correct regulator by consulting a machine specific lookup table.
18If the lookup is successful then this call will return a pointer to the struct
19regulator that supplies this consumer.
20
21To release the regulator the consumer driver should call ::
22
23	regulator_put(regulator);
24
25Consumers can be supplied by more than one regulator e.g. codec consumer with
26analog and digital supplies ::
27
28	digital = regulator_get(dev, "Vcc");  /* digital core */
29	analog = regulator_get(dev, "Avdd");  /* analog */
30
31The regulator access functions regulator_get() and regulator_put() will
32usually be called in your device drivers probe() and remove() respectively.
33
34
352. Regulator Output Enable & Disable (static & dynamic drivers)
36===============================================================
37
38
39A consumer can enable its power supply by calling::
40
41	int regulator_enable(regulator);
42
43NOTE:
44  The supply may already be enabled before regulator_enable() is called.
45  This may happen if the consumer shares the regulator or the regulator has been
46  previously enabled by bootloader or kernel board initialization code.
47
48A consumer can determine if a regulator is enabled by calling::
49
50	int regulator_is_enabled(regulator);
51
52This will return > zero when the regulator is enabled.
53
54
55A consumer can disable its supply when no longer needed by calling::
56
57	int regulator_disable(regulator);
58
59NOTE:
60  This may not disable the supply if it's shared with other consumers. The
61  regulator will only be disabled when the enabled reference count is zero.
62
63Finally, a regulator can be forcefully disabled in the case of an emergency::
64
65	int regulator_force_disable(regulator);
66
67NOTE:
68  this will immediately and forcefully shutdown the regulator output. All
69  consumers will be powered off.
70
71
723. Regulator Voltage Control & Status (dynamic drivers)
73=======================================================
74
75Some consumer drivers need to be able to dynamically change their supply
76voltage to match system operating points. e.g. CPUfreq drivers can scale
77voltage along with frequency to save power, SD drivers may need to select the
78correct card voltage, etc.
79
80Consumers can control their supply voltage by calling::
81
82	int regulator_set_voltage(regulator, min_uV, max_uV);
83
84Where min_uV and max_uV are the minimum and maximum acceptable voltages in
85microvolts.
86
87NOTE: this can be called when the regulator is enabled or disabled. If called
88when enabled, then the voltage changes instantly, otherwise the voltage
89configuration changes and the voltage is physically set when the regulator is
90next enabled.
91
92The regulators configured voltage output can be found by calling::
93
94	int regulator_get_voltage(regulator);
95
96NOTE:
97  get_voltage() will return the configured output voltage whether the
98  regulator is enabled or disabled and should NOT be used to determine regulator
99  output state. However this can be used in conjunction with is_enabled() to
100  determine the regulator physical output voltage.
101
102
1034. Regulator Current Limit Control & Status (dynamic drivers)
104=============================================================
105
106Some consumer drivers need to be able to dynamically change their supply
107current limit to match system operating points. e.g. LCD backlight driver can
108change the current limit to vary the backlight brightness, USB drivers may want
109to set the limit to 500mA when supplying power.
110
111Consumers can control their supply current limit by calling::
112
113	int regulator_set_current_limit(regulator, min_uA, max_uA);
114
115Where min_uA and max_uA are the minimum and maximum acceptable current limit in
116microamps.
117
118NOTE:
119  this can be called when the regulator is enabled or disabled. If called
120  when enabled, then the current limit changes instantly, otherwise the current
121  limit configuration changes and the current limit is physically set when the
122  regulator is next enabled.
123
124A regulators current limit can be found by calling::
125
126	int regulator_get_current_limit(regulator);
127
128NOTE:
129  get_current_limit() will return the current limit whether the regulator
130  is enabled or disabled and should not be used to determine regulator current
131  load.
132
133
1345. Regulator Operating Mode Control & Status (dynamic drivers)
135==============================================================
136
137Some consumers can further save system power by changing the operating mode of
138their supply regulator to be more efficient when the consumers operating state
139changes. e.g. consumer driver is idle and subsequently draws less current
140
141Regulator operating mode can be changed indirectly or directly.
142
143Indirect operating mode control.
144--------------------------------
145Consumer drivers can request a change in their supply regulator operating mode
146by calling::
147
148	int regulator_set_load(struct regulator *regulator, int load_uA);
149
150This will cause the core to recalculate the total load on the regulator (based
151on all its consumers) and change operating mode (if necessary and permitted)
152to best match the current operating load.
153
154The load_uA value can be determined from the consumer's datasheet. e.g. most
155datasheets have tables showing the maximum current consumed in certain
156situations.
157
158Most consumers will use indirect operating mode control since they have no
159knowledge of the regulator or whether the regulator is shared with other
160consumers.
161
162Direct operating mode control.
163------------------------------
164
165Bespoke or tightly coupled drivers may want to directly control regulator
166operating mode depending on their operating point. This can be achieved by
167calling::
168
169	int regulator_set_mode(struct regulator *regulator, unsigned int mode);
170	unsigned int regulator_get_mode(struct regulator *regulator);
171
172Direct mode will only be used by consumers that *know* about the regulator and
173are not sharing the regulator with other consumers.
174
175
1766. Regulator Events
177===================
178
179Regulators can notify consumers of external events. Events could be received by
180consumers under regulator stress or failure conditions.
181
182Consumers can register interest in regulator events by calling::
183
184	int regulator_register_notifier(struct regulator *regulator,
185					struct notifier_block *nb);
186
187Consumers can unregister interest by calling::
188
189	int regulator_unregister_notifier(struct regulator *regulator,
190					  struct notifier_block *nb);
191
192Regulators use the kernel notifier framework to send event to their interested
193consumers.
194
1957. Regulator Direct Register Access
196===================================
197
198Some kinds of power management hardware or firmware are designed such that
199they need to do low-level hardware access to regulators, with no involvement
200from the kernel. Examples of such devices are:
201
202- clocksource with a voltage-controlled oscillator and control logic to change
203  the supply voltage over I2C to achieve a desired output clock rate
204- thermal management firmware that can issue an arbitrary I2C transaction to
205  perform system poweroff during overtemperature conditions
206
207To set up such a device/firmware, various parameters like I2C address of the
208regulator, addresses of various regulator registers etc. need to be configured
209to it. The regulator framework provides the following helpers for querying
210these details.
211
212Bus-specific details, like I2C addresses or transfer rates are handled by the
213regmap framework. To get the regulator's regmap (if supported), use::
214
215	struct regmap *regulator_get_regmap(struct regulator *regulator);
216
217To obtain the hardware register offset and bitmask for the regulator's voltage
218selector register, use::
219
220	int regulator_get_hardware_vsel_register(struct regulator *regulator,
221						 unsigned *vsel_reg,
222						 unsigned *vsel_mask);
223
224To convert a regulator framework voltage selector code (used by
225regulator_list_voltage) to a hardware-specific voltage selector that can be
226directly written to the voltage selector register, use::
227
228	int regulator_list_hardware_vsel(struct regulator *regulator,
229					 unsigned selector);
230