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 #include <linux/suspend.h>
36 #include <regulator/regulator.h>
37
38 struct device;
39 struct notifier_block;
40 struct regmap;
41 struct regulator_dev;
42
43 /*
44 * Regulator operating modes.
45 *
46 * Regulators can run in a variety of different operating modes depending on
47 * output load. This allows further system power savings by selecting the
48 * best (and most efficient) regulator mode for a desired load.
49 *
50 * Most drivers will only care about NORMAL. The modes below are generic and
51 * will probably not match the naming convention of your regulator data sheet
52 * but should match the use cases in the datasheet.
53 *
54 * In order of power efficiency (least efficient at top).
55 *
56 * Mode Description
57 * FAST Regulator can handle fast changes in it's load.
58 * e.g. useful in CPU voltage & frequency scaling where
59 * load can quickly increase with CPU frequency increases.
60 *
61 * NORMAL Normal regulator power supply mode. Most drivers will
62 * use this mode.
63 *
64 * IDLE Regulator runs in a more efficient mode for light
65 * loads. Can be used for devices that have a low power
66 * requirement during periods of inactivity. This mode
67 * may be more noisy than NORMAL and may not be able
68 * to handle fast load switching.
69 *
70 * STANDBY Regulator runs in the most efficient mode for very
71 * light loads. Can be used by devices when they are
72 * in a sleep/standby state. This mode is likely to be
73 * the most noisy and may not be able to handle fast load
74 * switching.
75 *
76 * NOTE: Most regulators will only support a subset of these modes. Some
77 * will only just support NORMAL.
78 *
79 * These modes can be OR'ed together to make up a mask of valid register modes.
80 */
81
82 #define REGULATOR_MODE_INVALID 0x0
83 #define REGULATOR_MODE_FAST 0x1
84 #define REGULATOR_MODE_NORMAL 0x2
85 #define REGULATOR_MODE_IDLE 0x4
86 #define REGULATOR_MODE_STANDBY 0x8
87
88 /*
89 * Regulator errors that can be queried using regulator_get_error_flags
90 *
91 * UNDER_VOLTAGE Regulator output is under voltage.
92 * OVER_CURRENT Regulator output current is too high.
93 * REGULATION_OUT Regulator output is out of regulation.
94 * FAIL Regulator output has failed.
95 * OVER_TEMP Regulator over temp.
96 *
97 * NOTE: These errors can be OR'ed together.
98 */
99
100 #define REGULATOR_ERROR_UNDER_VOLTAGE BIT(1)
101 #define REGULATOR_ERROR_OVER_CURRENT BIT(2)
102 #define REGULATOR_ERROR_REGULATION_OUT BIT(3)
103 #define REGULATOR_ERROR_FAIL BIT(4)
104 #define REGULATOR_ERROR_OVER_TEMP BIT(5)
105
106 #define REGULATOR_ERROR_UNDER_VOLTAGE_WARN BIT(6)
107 #define REGULATOR_ERROR_OVER_CURRENT_WARN BIT(7)
108 #define REGULATOR_ERROR_OVER_VOLTAGE_WARN BIT(8)
109 #define REGULATOR_ERROR_OVER_TEMP_WARN BIT(9)
110
111 /**
112 * struct pre_voltage_change_data - Data sent with PRE_VOLTAGE_CHANGE event
113 *
114 * @old_uV: Current voltage before change.
115 * @min_uV: Min voltage we'll change to.
116 * @max_uV: Max voltage we'll change to.
117 */
118 struct pre_voltage_change_data {
119 unsigned long old_uV;
120 unsigned long min_uV;
121 unsigned long max_uV;
122 };
123
124 struct regulator;
125
126 /**
127 * struct regulator_bulk_data - Data used for bulk regulator operations.
128 *
129 * @supply: The name of the supply. Initialised by the user before
130 * using the bulk regulator APIs.
131 * @consumer: The regulator consumer for the supply. This will be managed
132 * by the bulk API.
133 * @init_load_uA: After getting the regulator, regulator_set_load() will be
134 * called with this load. Initialised by the user before
135 * using the bulk regulator APIs.
136 *
137 * The regulator APIs provide a series of regulator_bulk_() API calls as
138 * a convenience to consumers which require multiple supplies. This
139 * structure is used to manage data for these calls.
140 */
141 struct regulator_bulk_data {
142 const char *supply;
143 struct regulator *consumer;
144 int init_load_uA;
145
146 /* private: Internal use */
147 int ret;
148 };
149
150 #if defined(CONFIG_REGULATOR)
151
152 /* regulator get and put */
153 struct regulator *__must_check regulator_get(struct device *dev,
154 const char *id);
155 struct regulator *__must_check devm_regulator_get(struct device *dev,
156 const char *id);
157 struct regulator *__must_check regulator_get_exclusive(struct device *dev,
158 const char *id);
159 struct regulator *__must_check devm_regulator_get_exclusive(struct device *dev,
160 const char *id);
161 struct regulator *__must_check regulator_get_optional(struct device *dev,
162 const char *id);
163 struct regulator *__must_check devm_regulator_get_optional(struct device *dev,
164 const char *id);
165 int devm_regulator_get_enable(struct device *dev, const char *id);
166 int devm_regulator_get_enable_optional(struct device *dev, const char *id);
167 int devm_regulator_get_enable_read_voltage(struct device *dev, const char *id);
168 void regulator_put(struct regulator *regulator);
169 void devm_regulator_put(struct regulator *regulator);
170
171 int regulator_register_supply_alias(struct device *dev, const char *id,
172 struct device *alias_dev,
173 const char *alias_id);
174 void regulator_unregister_supply_alias(struct device *dev, const char *id);
175
176 int regulator_bulk_register_supply_alias(struct device *dev,
177 const char *const *id,
178 struct device *alias_dev,
179 const char *const *alias_id,
180 int num_id);
181 void regulator_bulk_unregister_supply_alias(struct device *dev,
182 const char * const *id, int num_id);
183
184 int devm_regulator_register_supply_alias(struct device *dev, const char *id,
185 struct device *alias_dev,
186 const char *alias_id);
187
188 int devm_regulator_bulk_register_supply_alias(struct device *dev,
189 const char *const *id,
190 struct device *alias_dev,
191 const char *const *alias_id,
192 int num_id);
193
194 /* regulator output control and status */
195 int __must_check regulator_enable(struct regulator *regulator);
196 int regulator_disable(struct regulator *regulator);
197 int regulator_force_disable(struct regulator *regulator);
198 int regulator_is_enabled(struct regulator *regulator);
199 int regulator_disable_deferred(struct regulator *regulator, int ms);
200
201 int __must_check regulator_bulk_get(struct device *dev, int num_consumers,
202 struct regulator_bulk_data *consumers);
203 int __must_check of_regulator_bulk_get_all(struct device *dev, struct device_node *np,
204 struct regulator_bulk_data **consumers);
205 int __must_check devm_regulator_bulk_get(struct device *dev, int num_consumers,
206 struct regulator_bulk_data *consumers);
207 void devm_regulator_bulk_put(struct regulator_bulk_data *consumers);
208 int __must_check devm_regulator_bulk_get_exclusive(struct device *dev, int num_consumers,
209 struct regulator_bulk_data *consumers);
210 int __must_check devm_regulator_bulk_get_const(
211 struct device *dev, int num_consumers,
212 const struct regulator_bulk_data *in_consumers,
213 struct regulator_bulk_data **out_consumers);
214 int __must_check regulator_bulk_enable(int num_consumers,
215 struct regulator_bulk_data *consumers);
216 int devm_regulator_bulk_get_enable(struct device *dev, int num_consumers,
217 const char * const *id);
218 int regulator_bulk_disable(int num_consumers,
219 struct regulator_bulk_data *consumers);
220 int regulator_bulk_force_disable(int num_consumers,
221 struct regulator_bulk_data *consumers);
222 void regulator_bulk_free(int num_consumers,
223 struct regulator_bulk_data *consumers);
224
225 int regulator_count_voltages(struct regulator *regulator);
226 int regulator_list_voltage(struct regulator *regulator, unsigned selector);
227 int regulator_is_supported_voltage(struct regulator *regulator,
228 int min_uV, int max_uV);
229 unsigned int regulator_get_linear_step(struct regulator *regulator);
230 int regulator_set_voltage(struct regulator *regulator, int min_uV, int max_uV);
231 int regulator_set_voltage_time(struct regulator *regulator,
232 int old_uV, int new_uV);
233 int regulator_get_voltage(struct regulator *regulator);
234 int regulator_sync_voltage(struct regulator *regulator);
235 int regulator_set_current_limit(struct regulator *regulator,
236 int min_uA, int max_uA);
237 int regulator_get_current_limit(struct regulator *regulator);
238
239 int regulator_set_mode(struct regulator *regulator, unsigned int mode);
240 unsigned int regulator_get_mode(struct regulator *regulator);
241 int regulator_get_error_flags(struct regulator *regulator,
242 unsigned int *flags);
243 int regulator_set_load(struct regulator *regulator, int load_uA);
244
245 int regulator_allow_bypass(struct regulator *regulator, bool allow);
246
247 struct regmap *regulator_get_regmap(struct regulator *regulator);
248 int regulator_get_hardware_vsel_register(struct regulator *regulator,
249 unsigned *vsel_reg,
250 unsigned *vsel_mask);
251 int regulator_list_hardware_vsel(struct regulator *regulator,
252 unsigned selector);
253 int regulator_hardware_enable(struct regulator *regulator, bool enable);
254
255 /* regulator notifier block */
256 int regulator_register_notifier(struct regulator *regulator,
257 struct notifier_block *nb);
258 int devm_regulator_register_notifier(struct regulator *regulator,
259 struct notifier_block *nb);
260 int regulator_unregister_notifier(struct regulator *regulator,
261 struct notifier_block *nb);
262 void devm_regulator_unregister_notifier(struct regulator *regulator,
263 struct notifier_block *nb);
264
265 /* regulator suspend */
266 int regulator_suspend_enable(struct regulator_dev *rdev,
267 suspend_state_t state);
268 int regulator_suspend_disable(struct regulator_dev *rdev,
269 suspend_state_t state);
270 int regulator_set_suspend_voltage(struct regulator *regulator, int min_uV,
271 int max_uV, suspend_state_t state);
272
273 /* driver data - core doesn't touch */
274 void *regulator_get_drvdata(struct regulator *regulator);
275 void regulator_set_drvdata(struct regulator *regulator, void *data);
276
277 /* misc helpers */
278
279 void regulator_bulk_set_supply_names(struct regulator_bulk_data *consumers,
280 const char *const *supply_names,
281 unsigned int num_supplies);
282
283 bool regulator_is_equal(struct regulator *reg1, struct regulator *reg2);
284
285 #else
286
287 /*
288 * Make sure client drivers will still build on systems with no software
289 * controllable voltage or current regulators.
290 */
291 static inline struct regulator *__must_check regulator_get(struct device *dev,
292 const char *id)
293 {
294 /* Nothing except the stubbed out regulator API should be
295 * looking at the value except to check if it is an error
296 * value. Drivers are free to handle NULL specifically by
297 * skipping all regulator API calls, but they don't have to.
298 * Drivers which don't, should make sure they properly handle
299 * corner cases of the API, such as regulator_get_voltage()
300 * returning 0.
301 */
302 return NULL;
303 }
304
305 static inline struct regulator *__must_check
306 devm_regulator_get(struct device *dev, const char *id)
307 {
308 return NULL;
309 }
310
311 static inline struct regulator *__must_check
312 regulator_get_exclusive(struct device *dev, const char *id)
313 {
314 return ERR_PTR(-ENODEV);
315 }
316
317 static inline struct regulator *__must_check
318 devm_regulator_get_exclusive(struct device *dev, const char *id)
319 {
320 return ERR_PTR(-ENODEV);
321 }
322
323 static inline int devm_regulator_get_enable(struct device *dev, const char *id)
324 {
325 return 0;
326 }
327
328 static inline int devm_regulator_get_enable_optional(struct device *dev,
329 const char *id)
330 {
331 return 0;
332 }
333
334 static inline int devm_regulator_get_enable_read_voltage(struct device *dev,
335 const char *id)
336 {
337 return -ENODEV;
338 }
339
340 static inline struct regulator *__must_check
341 regulator_get_optional(struct device *dev, const char *id)
342 {
343 return ERR_PTR(-ENODEV);
344 }
345
346
347 static inline struct regulator *__must_check
348 devm_regulator_get_optional(struct device *dev, const char *id)
349 {
350 return ERR_PTR(-ENODEV);
351 }
352
353 static inline void regulator_put(struct regulator *regulator)
354 {
355 }
356
357 static inline void devm_regulator_put(struct regulator *regulator)
358 {
359 }
360
361 static inline void devm_regulator_bulk_put(struct regulator_bulk_data *consumers)
362 {
363 }
364
365 static inline int regulator_register_supply_alias(struct device *dev,
366 const char *id,
367 struct device *alias_dev,
368 const char *alias_id)
369 {
370 return 0;
371 }
372
373 static inline void regulator_unregister_supply_alias(struct device *dev,
374 const char *id)
375 {
376 }
377
378 static inline int regulator_bulk_register_supply_alias(struct device *dev,
379 const char *const *id,
380 struct device *alias_dev,
381 const char * const *alias_id,
382 int num_id)
383 {
384 return 0;
385 }
386
387 static inline void regulator_bulk_unregister_supply_alias(struct device *dev,
388 const char * const *id,
389 int num_id)
390 {
391 }
392
393 static inline int devm_regulator_register_supply_alias(struct device *dev,
394 const char *id,
395 struct device *alias_dev,
396 const char *alias_id)
397 {
398 return 0;
399 }
400
401 static inline int devm_regulator_bulk_register_supply_alias(struct device *dev,
402 const char *const *id,
403 struct device *alias_dev,
404 const char *const *alias_id,
405 int num_id)
406 {
407 return 0;
408 }
409
410 static inline int regulator_enable(struct regulator *regulator)
411 {
412 return 0;
413 }
414
415 static inline int regulator_disable(struct regulator *regulator)
416 {
417 return 0;
418 }
419
420 static inline int regulator_force_disable(struct regulator *regulator)
421 {
422 return 0;
423 }
424
425 static inline int regulator_disable_deferred(struct regulator *regulator,
426 int ms)
427 {
428 return 0;
429 }
430
431 static inline int regulator_is_enabled(struct regulator *regulator)
432 {
433 return 1;
434 }
435
436 static inline int regulator_bulk_get(struct device *dev,
437 int num_consumers,
438 struct regulator_bulk_data *consumers)
439 {
440 return 0;
441 }
442
443 static inline int devm_regulator_bulk_get(struct device *dev, int num_consumers,
444 struct regulator_bulk_data *consumers)
445 {
446 return 0;
447 }
448
449 static inline int of_regulator_bulk_get_all(struct device *dev, struct device_node *np,
450 struct regulator_bulk_data **consumers)
451 {
452 return 0;
453 }
454
455 static inline int devm_regulator_bulk_get_const(
456 struct device *dev, int num_consumers,
457 const struct regulator_bulk_data *in_consumers,
458 struct regulator_bulk_data **out_consumers)
459 {
460 return 0;
461 }
462
463 static inline int regulator_bulk_enable(int num_consumers,
464 struct regulator_bulk_data *consumers)
465 {
466 return 0;
467 }
468
469 static inline int devm_regulator_bulk_get_enable(struct device *dev,
470 int num_consumers,
471 const char * const *id)
472 {
473 return 0;
474 }
475
476 static inline int regulator_bulk_disable(int num_consumers,
477 struct regulator_bulk_data *consumers)
478 {
479 return 0;
480 }
481
482 static inline int regulator_bulk_force_disable(int num_consumers,
483 struct regulator_bulk_data *consumers)
484 {
485 return 0;
486 }
487
488 static inline void regulator_bulk_free(int num_consumers,
489 struct regulator_bulk_data *consumers)
490 {
491 }
492
493 static inline int regulator_set_voltage(struct regulator *regulator,
494 int min_uV, int max_uV)
495 {
496 return 0;
497 }
498
499 static inline int regulator_set_voltage_time(struct regulator *regulator,
500 int old_uV, int new_uV)
501 {
502 return 0;
503 }
504
505 static inline int regulator_get_voltage(struct regulator *regulator)
506 {
507 return -EINVAL;
508 }
509
510 static inline int regulator_sync_voltage(struct regulator *regulator)
511 {
512 return -EINVAL;
513 }
514
515 static inline int regulator_is_supported_voltage(struct regulator *regulator,
516 int min_uV, int max_uV)
517 {
518 return 0;
519 }
520
521 static inline unsigned int regulator_get_linear_step(struct regulator *regulator)
522 {
523 return 0;
524 }
525
526 static inline int regulator_set_current_limit(struct regulator *regulator,
527 int min_uA, int max_uA)
528 {
529 return 0;
530 }
531
532 static inline int regulator_get_current_limit(struct regulator *regulator)
533 {
534 return 0;
535 }
536
537 static inline int regulator_set_mode(struct regulator *regulator,
538 unsigned int mode)
539 {
540 return 0;
541 }
542
543 static inline unsigned int regulator_get_mode(struct regulator *regulator)
544 {
545 return REGULATOR_MODE_NORMAL;
546 }
547
548 static inline int regulator_get_error_flags(struct regulator *regulator,
549 unsigned int *flags)
550 {
551 return -EINVAL;
552 }
553
554 static inline int regulator_set_load(struct regulator *regulator, int load_uA)
555 {
556 return 0;
557 }
558
559 static inline int regulator_allow_bypass(struct regulator *regulator,
560 bool allow)
561 {
562 return 0;
563 }
564
565 static inline struct regmap *regulator_get_regmap(struct regulator *regulator)
566 {
567 return ERR_PTR(-EOPNOTSUPP);
568 }
569
570 static inline int regulator_get_hardware_vsel_register(struct regulator *regulator,
571 unsigned *vsel_reg,
572 unsigned *vsel_mask)
573 {
574 return -EOPNOTSUPP;
575 }
576
577 static inline int regulator_list_hardware_vsel(struct regulator *regulator,
578 unsigned selector)
579 {
580 return -EOPNOTSUPP;
581 }
582
583 static inline int regulator_hardware_enable(struct regulator *regulator,
584 bool enable)
585 {
586 return -EOPNOTSUPP;
587 }
588
589 static inline int regulator_register_notifier(struct regulator *regulator,
590 struct notifier_block *nb)
591 {
592 return 0;
593 }
594
595 static inline int devm_regulator_register_notifier(struct regulator *regulator,
596 struct notifier_block *nb)
597 {
598 return 0;
599 }
600
601 static inline int regulator_unregister_notifier(struct regulator *regulator,
602 struct notifier_block *nb)
603 {
604 return 0;
605 }
606
607 static inline int devm_regulator_unregister_notifier(struct regulator *regulator,
608 struct notifier_block *nb)
609 {
610 return 0;
611 }
612
613 static inline int regulator_suspend_enable(struct regulator_dev *rdev,
614 suspend_state_t state)
615 {
616 return -EINVAL;
617 }
618
619 static inline int regulator_suspend_disable(struct regulator_dev *rdev,
620 suspend_state_t state)
621 {
622 return -EINVAL;
623 }
624
625 static inline int regulator_set_suspend_voltage(struct regulator *regulator,
626 int min_uV, int max_uV,
627 suspend_state_t state)
628 {
629 return -EINVAL;
630 }
631
632 static inline void *regulator_get_drvdata(struct regulator *regulator)
633 {
634 return NULL;
635 }
636
637 static inline void regulator_set_drvdata(struct regulator *regulator,
638 void *data)
639 {
640 }
641
642 static inline int regulator_count_voltages(struct regulator *regulator)
643 {
644 return 0;
645 }
646
647 static inline int regulator_list_voltage(struct regulator *regulator, unsigned selector)
648 {
649 return -EINVAL;
650 }
651
652 static inline void
653 regulator_bulk_set_supply_names(struct regulator_bulk_data *consumers,
654 const char *const *supply_names,
655 unsigned int num_supplies)
656 {
657 }
658
659 static inline bool
660 regulator_is_equal(struct regulator *reg1, struct regulator *reg2)
661 {
662 return false;
663 }
664 #endif
665
666 static inline int regulator_set_voltage_triplet(struct regulator *regulator,
667 int min_uV, int target_uV,
668 int max_uV)
669 {
670 if (regulator_set_voltage(regulator, target_uV, max_uV) == 0)
671 return 0;
672
673 return regulator_set_voltage(regulator, min_uV, max_uV);
674 }
675
676 static inline int regulator_set_voltage_tol(struct regulator *regulator,
677 int new_uV, int tol_uV)
678 {
679 if (regulator_set_voltage(regulator, new_uV, new_uV + tol_uV) == 0)
680 return 0;
681 else
682 return regulator_set_voltage(regulator,
683 new_uV - tol_uV, new_uV + tol_uV);
684 }
685
686 static inline int regulator_is_supported_voltage_tol(struct regulator *regulator,
687 int target_uV, int tol_uV)
688 {
689 return regulator_is_supported_voltage(regulator,
690 target_uV - tol_uV,
691 target_uV + tol_uV);
692 }
693
694 #endif
695
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.