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