Branch data Line data Source code
1 : : /* SPDX-License-Identifier: GPL-2.0-only */
2 : : /*
3 : : * consumer.h -- SoC Regulator consumer support.
4 : : *
5 : : * Copyright (C) 2007, 2008 Wolfson Microelectronics PLC.
6 : : *
7 : : * Author: Liam Girdwood <lrg@slimlogic.co.uk>
8 : : *
9 : : * Regulator Consumer Interface.
10 : : *
11 : : * A Power Management Regulator framework for SoC based devices.
12 : : * Features:-
13 : : * o Voltage and current level control.
14 : : * o Operating mode control.
15 : : * o Regulator status.
16 : : * o sysfs entries for showing client devices and status
17 : : *
18 : : * EXPERIMENTAL FEATURES:
19 : : * Dynamic Regulator operating Mode Switching (DRMS) - allows regulators
20 : : * to use most efficient operating mode depending upon voltage and load and
21 : : * is transparent to client drivers.
22 : : *
23 : : * e.g. Devices x,y,z share regulator r. Device x and y draw 20mA each during
24 : : * IO and 1mA at idle. Device z draws 100mA when under load and 5mA when
25 : : * idling. Regulator r has > 90% efficiency in NORMAL mode at loads > 100mA
26 : : * but this drops rapidly to 60% when below 100mA. Regulator r has > 90%
27 : : * efficiency in IDLE mode at loads < 10mA. Thus regulator r will operate
28 : : * in normal mode for loads > 10mA and in IDLE mode for load <= 10mA.
29 : : */
30 : :
31 : : #ifndef __LINUX_REGULATOR_CONSUMER_H_
32 : : #define __LINUX_REGULATOR_CONSUMER_H_
33 : :
34 : : #include <linux/err.h>
35 : :
36 : : struct device;
37 : : struct notifier_block;
38 : : struct regmap;
39 : :
40 : : /*
41 : : * Regulator operating modes.
42 : : *
43 : : * Regulators can run in a variety of different operating modes depending on
44 : : * output load. This allows further system power savings by selecting the
45 : : * best (and most efficient) regulator mode for a desired load.
46 : : *
47 : : * Most drivers will only care about NORMAL. The modes below are generic and
48 : : * will probably not match the naming convention of your regulator data sheet
49 : : * but should match the use cases in the datasheet.
50 : : *
51 : : * In order of power efficiency (least efficient at top).
52 : : *
53 : : * Mode Description
54 : : * FAST Regulator can handle fast changes in it's load.
55 : : * e.g. useful in CPU voltage & frequency scaling where
56 : : * load can quickly increase with CPU frequency increases.
57 : : *
58 : : * NORMAL Normal regulator power supply mode. Most drivers will
59 : : * use this mode.
60 : : *
61 : : * IDLE Regulator runs in a more efficient mode for light
62 : : * loads. Can be used for devices that have a low power
63 : : * requirement during periods of inactivity. This mode
64 : : * may be more noisy than NORMAL and may not be able
65 : : * to handle fast load switching.
66 : : *
67 : : * STANDBY Regulator runs in the most efficient mode for very
68 : : * light loads. Can be used by devices when they are
69 : : * in a sleep/standby state. This mode is likely to be
70 : : * the most noisy and may not be able to handle fast load
71 : : * switching.
72 : : *
73 : : * NOTE: Most regulators will only support a subset of these modes. Some
74 : : * will only just support NORMAL.
75 : : *
76 : : * These modes can be OR'ed together to make up a mask of valid register modes.
77 : : */
78 : :
79 : : #define REGULATOR_MODE_INVALID 0x0
80 : : #define REGULATOR_MODE_FAST 0x1
81 : : #define REGULATOR_MODE_NORMAL 0x2
82 : : #define REGULATOR_MODE_IDLE 0x4
83 : : #define REGULATOR_MODE_STANDBY 0x8
84 : :
85 : : /*
86 : : * Regulator notifier events.
87 : : *
88 : : * UNDER_VOLTAGE Regulator output is under voltage.
89 : : * OVER_CURRENT Regulator output current is too high.
90 : : * REGULATION_OUT Regulator output is out of regulation.
91 : : * FAIL Regulator output has failed.
92 : : * OVER_TEMP Regulator over temp.
93 : : * FORCE_DISABLE Regulator forcibly shut down by software.
94 : : * VOLTAGE_CHANGE Regulator voltage changed.
95 : : * Data passed is old voltage cast to (void *).
96 : : * DISABLE Regulator was disabled.
97 : : * PRE_VOLTAGE_CHANGE Regulator is about to have voltage changed.
98 : : * Data passed is "struct pre_voltage_change_data"
99 : : * ABORT_VOLTAGE_CHANGE Regulator voltage change failed for some reason.
100 : : * Data passed is old voltage cast to (void *).
101 : : * PRE_DISABLE Regulator is about to be disabled
102 : : * ABORT_DISABLE Regulator disable failed for some reason
103 : : *
104 : : * NOTE: These events can be OR'ed together when passed into handler.
105 : : */
106 : :
107 : : #define REGULATOR_EVENT_UNDER_VOLTAGE 0x01
108 : : #define REGULATOR_EVENT_OVER_CURRENT 0x02
109 : : #define REGULATOR_EVENT_REGULATION_OUT 0x04
110 : : #define REGULATOR_EVENT_FAIL 0x08
111 : : #define REGULATOR_EVENT_OVER_TEMP 0x10
112 : : #define REGULATOR_EVENT_FORCE_DISABLE 0x20
113 : : #define REGULATOR_EVENT_VOLTAGE_CHANGE 0x40
114 : : #define REGULATOR_EVENT_DISABLE 0x80
115 : : #define REGULATOR_EVENT_PRE_VOLTAGE_CHANGE 0x100
116 : : #define REGULATOR_EVENT_ABORT_VOLTAGE_CHANGE 0x200
117 : : #define REGULATOR_EVENT_PRE_DISABLE 0x400
118 : : #define REGULATOR_EVENT_ABORT_DISABLE 0x800
119 : : #define REGULATOR_EVENT_ENABLE 0x1000
120 : :
121 : : /*
122 : : * Regulator errors that can be queried using regulator_get_error_flags
123 : : *
124 : : * UNDER_VOLTAGE Regulator output is under voltage.
125 : : * OVER_CURRENT Regulator output current is too high.
126 : : * REGULATION_OUT Regulator output is out of regulation.
127 : : * FAIL Regulator output has failed.
128 : : * OVER_TEMP Regulator over temp.
129 : : *
130 : : * NOTE: These errors can be OR'ed together.
131 : : */
132 : :
133 : : #define REGULATOR_ERROR_UNDER_VOLTAGE BIT(1)
134 : : #define REGULATOR_ERROR_OVER_CURRENT BIT(2)
135 : : #define REGULATOR_ERROR_REGULATION_OUT BIT(3)
136 : : #define REGULATOR_ERROR_FAIL BIT(4)
137 : : #define REGULATOR_ERROR_OVER_TEMP BIT(5)
138 : :
139 : :
140 : : /**
141 : : * struct pre_voltage_change_data - Data sent with PRE_VOLTAGE_CHANGE event
142 : : *
143 : : * @old_uV: Current voltage before change.
144 : : * @min_uV: Min voltage we'll change to.
145 : : * @max_uV: Max voltage we'll change to.
146 : : */
147 : : struct pre_voltage_change_data {
148 : : unsigned long old_uV;
149 : : unsigned long min_uV;
150 : : unsigned long max_uV;
151 : : };
152 : :
153 : : struct regulator;
154 : :
155 : : /**
156 : : * struct regulator_bulk_data - Data used for bulk regulator operations.
157 : : *
158 : : * @supply: The name of the supply. Initialised by the user before
159 : : * using the bulk regulator APIs.
160 : : * @consumer: The regulator consumer for the supply. This will be managed
161 : : * by the bulk API.
162 : : *
163 : : * The regulator APIs provide a series of regulator_bulk_() API calls as
164 : : * a convenience to consumers which require multiple supplies. This
165 : : * structure is used to manage data for these calls.
166 : : */
167 : : struct regulator_bulk_data {
168 : : const char *supply;
169 : : struct regulator *consumer;
170 : :
171 : : /* private: Internal use */
172 : : int ret;
173 : : };
174 : :
175 : : #if defined(CONFIG_REGULATOR)
176 : :
177 : : /* regulator get and put */
178 : : struct regulator *__must_check regulator_get(struct device *dev,
179 : : const char *id);
180 : : struct regulator *__must_check devm_regulator_get(struct device *dev,
181 : : const char *id);
182 : : struct regulator *__must_check regulator_get_exclusive(struct device *dev,
183 : : const char *id);
184 : : struct regulator *__must_check devm_regulator_get_exclusive(struct device *dev,
185 : : const char *id);
186 : : struct regulator *__must_check regulator_get_optional(struct device *dev,
187 : : const char *id);
188 : : struct regulator *__must_check devm_regulator_get_optional(struct device *dev,
189 : : const char *id);
190 : : void regulator_put(struct regulator *regulator);
191 : : void devm_regulator_put(struct regulator *regulator);
192 : :
193 : : int regulator_register_supply_alias(struct device *dev, const char *id,
194 : : struct device *alias_dev,
195 : : const char *alias_id);
196 : : void regulator_unregister_supply_alias(struct device *dev, const char *id);
197 : :
198 : : int regulator_bulk_register_supply_alias(struct device *dev,
199 : : const char *const *id,
200 : : struct device *alias_dev,
201 : : const char *const *alias_id,
202 : : int num_id);
203 : : void regulator_bulk_unregister_supply_alias(struct device *dev,
204 : : const char * const *id, int num_id);
205 : :
206 : : int devm_regulator_register_supply_alias(struct device *dev, const char *id,
207 : : struct device *alias_dev,
208 : : const char *alias_id);
209 : : void devm_regulator_unregister_supply_alias(struct device *dev,
210 : : const char *id);
211 : :
212 : : int devm_regulator_bulk_register_supply_alias(struct device *dev,
213 : : const char *const *id,
214 : : struct device *alias_dev,
215 : : const char *const *alias_id,
216 : : int num_id);
217 : : void devm_regulator_bulk_unregister_supply_alias(struct device *dev,
218 : : const char *const *id,
219 : : int num_id);
220 : :
221 : : /* regulator output control and status */
222 : : int __must_check regulator_enable(struct regulator *regulator);
223 : : int regulator_disable(struct regulator *regulator);
224 : : int regulator_force_disable(struct regulator *regulator);
225 : : int regulator_is_enabled(struct regulator *regulator);
226 : : int regulator_disable_deferred(struct regulator *regulator, int ms);
227 : :
228 : : int __must_check regulator_bulk_get(struct device *dev, int num_consumers,
229 : : struct regulator_bulk_data *consumers);
230 : : int __must_check devm_regulator_bulk_get(struct device *dev, int num_consumers,
231 : : struct regulator_bulk_data *consumers);
232 : : int __must_check regulator_bulk_enable(int num_consumers,
233 : : struct regulator_bulk_data *consumers);
234 : : int regulator_bulk_disable(int num_consumers,
235 : : struct regulator_bulk_data *consumers);
236 : : int regulator_bulk_force_disable(int num_consumers,
237 : : struct regulator_bulk_data *consumers);
238 : : void regulator_bulk_free(int num_consumers,
239 : : struct regulator_bulk_data *consumers);
240 : :
241 : : int regulator_count_voltages(struct regulator *regulator);
242 : : int regulator_list_voltage(struct regulator *regulator, unsigned selector);
243 : : int regulator_is_supported_voltage(struct regulator *regulator,
244 : : int min_uV, int max_uV);
245 : : unsigned int regulator_get_linear_step(struct regulator *regulator);
246 : : int regulator_set_voltage(struct regulator *regulator, int min_uV, int max_uV);
247 : : int regulator_set_voltage_time(struct regulator *regulator,
248 : : int old_uV, int new_uV);
249 : : int regulator_get_voltage(struct regulator *regulator);
250 : : int regulator_sync_voltage(struct regulator *regulator);
251 : : int regulator_set_current_limit(struct regulator *regulator,
252 : : int min_uA, int max_uA);
253 : : int regulator_get_current_limit(struct regulator *regulator);
254 : :
255 : : int regulator_set_mode(struct regulator *regulator, unsigned int mode);
256 : : unsigned int regulator_get_mode(struct regulator *regulator);
257 : : int regulator_get_error_flags(struct regulator *regulator,
258 : : unsigned int *flags);
259 : : int regulator_set_load(struct regulator *regulator, int load_uA);
260 : :
261 : : int regulator_allow_bypass(struct regulator *regulator, bool allow);
262 : :
263 : : struct regmap *regulator_get_regmap(struct regulator *regulator);
264 : : int regulator_get_hardware_vsel_register(struct regulator *regulator,
265 : : unsigned *vsel_reg,
266 : : unsigned *vsel_mask);
267 : : int regulator_list_hardware_vsel(struct regulator *regulator,
268 : : unsigned selector);
269 : :
270 : : /* regulator notifier block */
271 : : int regulator_register_notifier(struct regulator *regulator,
272 : : struct notifier_block *nb);
273 : : int devm_regulator_register_notifier(struct regulator *regulator,
274 : : struct notifier_block *nb);
275 : : int regulator_unregister_notifier(struct regulator *regulator,
276 : : struct notifier_block *nb);
277 : : void devm_regulator_unregister_notifier(struct regulator *regulator,
278 : : struct notifier_block *nb);
279 : :
280 : : /* driver data - core doesn't touch */
281 : : void *regulator_get_drvdata(struct regulator *regulator);
282 : : void regulator_set_drvdata(struct regulator *regulator, void *data);
283 : :
284 : : /* misc helpers */
285 : :
286 : : void regulator_bulk_set_supply_names(struct regulator_bulk_data *consumers,
287 : : const char *const *supply_names,
288 : : unsigned int num_supplies);
289 : :
290 : : bool regulator_is_equal(struct regulator *reg1, struct regulator *reg2);
291 : :
292 : : #else
293 : :
294 : : /*
295 : : * Make sure client drivers will still build on systems with no software
296 : : * controllable voltage or current regulators.
297 : : */
298 : : static inline struct regulator *__must_check regulator_get(struct device *dev,
299 : : const char *id)
300 : : {
301 : : /* Nothing except the stubbed out regulator API should be
302 : : * looking at the value except to check if it is an error
303 : : * value. Drivers are free to handle NULL specifically by
304 : : * skipping all regulator API calls, but they don't have to.
305 : : * Drivers which don't, should make sure they properly handle
306 : : * corner cases of the API, such as regulator_get_voltage()
307 : : * returning 0.
308 : : */
309 : : return NULL;
310 : : }
311 : :
312 : : static inline struct regulator *__must_check
313 : : devm_regulator_get(struct device *dev, const char *id)
314 : : {
315 : : return NULL;
316 : : }
317 : :
318 : : static inline struct regulator *__must_check
319 : : regulator_get_exclusive(struct device *dev, const char *id)
320 : : {
321 : : return ERR_PTR(-ENODEV);
322 : : }
323 : :
324 : : static inline struct regulator *__must_check
325 : : regulator_get_optional(struct device *dev, const char *id)
326 : : {
327 : : return ERR_PTR(-ENODEV);
328 : : }
329 : :
330 : :
331 : : static inline struct regulator *__must_check
332 : : devm_regulator_get_optional(struct device *dev, const char *id)
333 : : {
334 : : return ERR_PTR(-ENODEV);
335 : : }
336 : :
337 : : static inline void regulator_put(struct regulator *regulator)
338 : : {
339 : : }
340 : :
341 : : static inline void devm_regulator_put(struct regulator *regulator)
342 : : {
343 : : }
344 : :
345 : : static inline int regulator_register_supply_alias(struct device *dev,
346 : : const char *id,
347 : : struct device *alias_dev,
348 : : const char *alias_id)
349 : : {
350 : : return 0;
351 : : }
352 : :
353 : : static inline void regulator_unregister_supply_alias(struct device *dev,
354 : : const char *id)
355 : : {
356 : : }
357 : :
358 : : static inline int regulator_bulk_register_supply_alias(struct device *dev,
359 : : const char *const *id,
360 : : struct device *alias_dev,
361 : : const char * const *alias_id,
362 : : int num_id)
363 : : {
364 : : return 0;
365 : : }
366 : :
367 : : static inline void regulator_bulk_unregister_supply_alias(struct device *dev,
368 : : const char * const *id,
369 : : int num_id)
370 : : {
371 : : }
372 : :
373 : : static inline int devm_regulator_register_supply_alias(struct device *dev,
374 : : const char *id,
375 : : struct device *alias_dev,
376 : : const char *alias_id)
377 : : {
378 : : return 0;
379 : : }
380 : :
381 : : static inline void devm_regulator_unregister_supply_alias(struct device *dev,
382 : : const char *id)
383 : : {
384 : : }
385 : :
386 : : static inline int devm_regulator_bulk_register_supply_alias(struct device *dev,
387 : : const char *const *id,
388 : : struct device *alias_dev,
389 : : const char *const *alias_id,
390 : : int num_id)
391 : : {
392 : : return 0;
393 : : }
394 : :
395 : : static inline void devm_regulator_bulk_unregister_supply_alias(
396 : : struct device *dev, const char *const *id, int num_id)
397 : : {
398 : : }
399 : :
400 : : static inline int regulator_enable(struct regulator *regulator)
401 : : {
402 : : return 0;
403 : : }
404 : :
405 : : static inline int regulator_disable(struct regulator *regulator)
406 : : {
407 : : return 0;
408 : : }
409 : :
410 : : static inline int regulator_force_disable(struct regulator *regulator)
411 : : {
412 : : return 0;
413 : : }
414 : :
415 : : static inline int regulator_disable_deferred(struct regulator *regulator,
416 : : int ms)
417 : : {
418 : : return 0;
419 : : }
420 : :
421 : : static inline int regulator_is_enabled(struct regulator *regulator)
422 : : {
423 : : return 1;
424 : : }
425 : :
426 : : static inline int regulator_bulk_get(struct device *dev,
427 : : int num_consumers,
428 : : struct regulator_bulk_data *consumers)
429 : : {
430 : : return 0;
431 : : }
432 : :
433 : : static inline int devm_regulator_bulk_get(struct device *dev, int num_consumers,
434 : : struct regulator_bulk_data *consumers)
435 : : {
436 : : return 0;
437 : : }
438 : :
439 : : static inline int regulator_bulk_enable(int num_consumers,
440 : : struct regulator_bulk_data *consumers)
441 : : {
442 : : return 0;
443 : : }
444 : :
445 : : static inline int regulator_bulk_disable(int num_consumers,
446 : : struct regulator_bulk_data *consumers)
447 : : {
448 : : return 0;
449 : : }
450 : :
451 : : static inline int regulator_bulk_force_disable(int num_consumers,
452 : : struct regulator_bulk_data *consumers)
453 : : {
454 : : return 0;
455 : : }
456 : :
457 : : static inline void regulator_bulk_free(int num_consumers,
458 : : struct regulator_bulk_data *consumers)
459 : : {
460 : : }
461 : :
462 : : static inline int regulator_set_voltage(struct regulator *regulator,
463 : : int min_uV, int max_uV)
464 : : {
465 : : return 0;
466 : : }
467 : :
468 : : static inline int regulator_set_voltage_time(struct regulator *regulator,
469 : : int old_uV, int new_uV)
470 : : {
471 : : return 0;
472 : : }
473 : :
474 : : static inline int regulator_get_voltage(struct regulator *regulator)
475 : : {
476 : : return -EINVAL;
477 : : }
478 : :
479 : : static inline int regulator_is_supported_voltage(struct regulator *regulator,
480 : : int min_uV, int max_uV)
481 : : {
482 : : return 0;
483 : : }
484 : :
485 : : static inline unsigned int regulator_get_linear_step(struct regulator *regulator)
486 : : {
487 : : return 0;
488 : : }
489 : :
490 : : static inline int regulator_set_current_limit(struct regulator *regulator,
491 : : int min_uA, int max_uA)
492 : : {
493 : : return 0;
494 : : }
495 : :
496 : : static inline int regulator_get_current_limit(struct regulator *regulator)
497 : : {
498 : : return 0;
499 : : }
500 : :
501 : : static inline int regulator_set_mode(struct regulator *regulator,
502 : : unsigned int mode)
503 : : {
504 : : return 0;
505 : : }
506 : :
507 : : static inline unsigned int regulator_get_mode(struct regulator *regulator)
508 : : {
509 : : return REGULATOR_MODE_NORMAL;
510 : : }
511 : :
512 : : static inline int regulator_get_error_flags(struct regulator *regulator,
513 : : unsigned int *flags)
514 : : {
515 : : return -EINVAL;
516 : : }
517 : :
518 : : static inline int regulator_set_load(struct regulator *regulator, int load_uA)
519 : : {
520 : : return 0;
521 : : }
522 : :
523 : : static inline int regulator_allow_bypass(struct regulator *regulator,
524 : : bool allow)
525 : : {
526 : : return 0;
527 : : }
528 : :
529 : : static inline struct regmap *regulator_get_regmap(struct regulator *regulator)
530 : : {
531 : : return ERR_PTR(-EOPNOTSUPP);
532 : : }
533 : :
534 : : static inline int regulator_get_hardware_vsel_register(struct regulator *regulator,
535 : : unsigned *vsel_reg,
536 : : unsigned *vsel_mask)
537 : : {
538 : : return -EOPNOTSUPP;
539 : : }
540 : :
541 : : static inline int regulator_list_hardware_vsel(struct regulator *regulator,
542 : : unsigned selector)
543 : : {
544 : : return -EOPNOTSUPP;
545 : : }
546 : :
547 : : static inline int regulator_register_notifier(struct regulator *regulator,
548 : : struct notifier_block *nb)
549 : : {
550 : : return 0;
551 : : }
552 : :
553 : : static inline int devm_regulator_register_notifier(struct regulator *regulator,
554 : : struct notifier_block *nb)
555 : : {
556 : : return 0;
557 : : }
558 : :
559 : : static inline int regulator_unregister_notifier(struct regulator *regulator,
560 : : struct notifier_block *nb)
561 : : {
562 : : return 0;
563 : : }
564 : :
565 : : static inline int devm_regulator_unregister_notifier(struct regulator *regulator,
566 : : struct notifier_block *nb)
567 : : {
568 : : return 0;
569 : : }
570 : :
571 : : static inline void *regulator_get_drvdata(struct regulator *regulator)
572 : : {
573 : : return NULL;
574 : : }
575 : :
576 : : static inline void regulator_set_drvdata(struct regulator *regulator,
577 : : void *data)
578 : : {
579 : : }
580 : :
581 : : static inline int regulator_count_voltages(struct regulator *regulator)
582 : : {
583 : : return 0;
584 : : }
585 : :
586 : : static inline int regulator_list_voltage(struct regulator *regulator, unsigned selector)
587 : : {
588 : : return -EINVAL;
589 : : }
590 : :
591 : : static inline void
592 : : regulator_bulk_set_supply_names(struct regulator_bulk_data *consumers,
593 : : const char *const *supply_names,
594 : : unsigned int num_supplies)
595 : : {
596 : : }
597 : :
598 : : static inline bool
599 : : regulator_is_equal(struct regulator *reg1, struct regulator *reg2)
600 : : {
601 : : return false;
602 : : }
603 : : #endif
604 : :
605 : 0 : static inline int regulator_set_voltage_triplet(struct regulator *regulator,
606 : : int min_uV, int target_uV,
607 : : int max_uV)
608 : : {
609 [ # # ]: 0 : if (regulator_set_voltage(regulator, target_uV, max_uV) == 0)
610 : : return 0;
611 : :
612 : 0 : return regulator_set_voltage(regulator, min_uV, max_uV);
613 : : }
614 : :
615 : : static inline int regulator_set_voltage_tol(struct regulator *regulator,
616 : : int new_uV, int tol_uV)
617 : : {
618 : : if (regulator_set_voltage(regulator, new_uV, new_uV + tol_uV) == 0)
619 : : return 0;
620 : : else
621 : : return regulator_set_voltage(regulator,
622 : : new_uV - tol_uV, new_uV + tol_uV);
623 : : }
624 : :
625 : : static inline int regulator_is_supported_voltage_tol(struct regulator *regulator,
626 : : int target_uV, int tol_uV)
627 : : {
628 : : return regulator_is_supported_voltage(regulator,
629 : : target_uV - tol_uV,
630 : : target_uV + tol_uV);
631 : : }
632 : :
633 : : #endif
|
