Debian Codegraph @

Documentation/power/regulator/consumer.rst

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