1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3 * Copyright (C) 2014-2015 Samsung Electronics
4 * Przemyslaw Marczak <p.marczak@samsung.com>
5 */
6
7 #ifndef _INCLUDE_REGULATOR_H_
8 #define _INCLUDE_REGULATOR_H_
9
10 #include <linux/errno.h>
11
12 struct udevice;
13
14 /**
15 * U-Boot Voltage/Current Regulator
16 * ================================
17 *
18 * The regulator API is based on a driver model, with the device tree support.
19 * And this header describes the functions and data types for the uclass id:
20 * 'UCLASS_REGULATOR' and the regulator driver API.
21 *
22 * The regulator uclass - is based on uclass platform data which is allocated,
23 * automatically for each regulator device on bind and 'dev->uclass_plat'
24 * points to it. The data type is: 'struct dm_regulator_uclass_plat'.
25 * The uclass file: 'drivers/power/regulator/regulator-uclass.c'
26 *
27 * The regulator device - is based on driver's model 'struct udevice'.
28 * The API can use regulator name in two meanings:
29 * - devname - the regulator device's name: 'dev->name'
30 * - platname - the device's plat's name. So in the code it looks like:
31 * 'uc_pdata = dev->uclass_plat'; 'name = uc_pdata->name'.
32 *
33 * The regulator device driver - provide an implementation of uclass operations
34 * pointed by 'dev->driver->ops' as a struct of type 'struct dm_regulator_ops'.
35 *
36 * To proper bind the regulator device, the device tree node should provide
37 * regulator constraints, like in the example below:
38 *
39 * ldo1 {
40 * regulator-name = "VDD_MMC_1.8V"; (must be unique for proper bind)
41 * regulator-min-microvolt = <1000000>; (optional)
42 * regulator-max-microvolt = <1000000>; (optional)
43 * regulator-min-microamp = <1000>; (optional)
44 * regulator-max-microamp = <1000>; (optional)
45 * regulator-always-on; (optional)
46 * regulator-boot-on; (optional)
47 * };
48 *
49 * Note: For the proper operation, at least name constraint is needed, since
50 * it can be used when calling regulator_get_by_platname(). And the mandatory
51 * rule for this name is, that it must be globally unique for the single dts.
52 * If regulator-name property is not provided, node name will be chosen.
53 *
54 * Regulator bind:
55 * For each regulator device, the device_bind() should be called with passed
56 * device tree offset. This is required for this uclass's '.post_bind' method,
57 * which does the scan on the device node, for the 'regulator-name' constraint.
58 * If the parent is not a PMIC device, and the child is not bind by function:
59 * 'pmic_bind_childs()', then it's recommended to bind the device by call to
60 * dm_scan_fdt_dev() - this is usually done automatically for bus devices,
61 * as a post bind method.
62 *
63 * Regulator get:
64 * Having the device's name constraint, we can call regulator_by_platname(),
65 * to find the required regulator. Before return, the regulator is probed,
66 * and the rest of its constraints are put into the device's uclass platform
67 * data, by the uclass regulator '.pre_probe' method.
68 *
69 * For more info about PMIC bind, please refer to file: 'include/power/pmic.h'
70 *
71 * Note:
72 * Please do not use the device_bind_by_name() function, since it pass '-1' as
73 * device node offset - and the bind will fail on uclass .post_bind method,
74 * because of missing 'regulator-name' constraint.
75 *
76 *
77 * Fixed Voltage/Current Regulator
78 * ===============================
79 *
80 * When fixed voltage regulator is needed, then enable the config:
81 * - CONFIG_DM_REGULATOR_FIXED
82 *
83 * The driver file: 'drivers/power/regulator/fixed.c', provides basic support
84 * for control the GPIO, and return the device tree constraint values.
85 *
86 * To bind the fixed voltage regulator device, we usually use a 'simple-bus'
87 * node as a parent. And 'regulator-fixed' for the driver compatible. This is
88 * the same as in the kernel. The example node of fixed regulator:
89 *
90 * simple-bus {
91 * compatible = "simple-bus";
92 * #address-cells = <1>;
93 * #size-cells = <0>;
94 *
95 * blue_led {
96 * compatible = "regulator-fixed";
97 * regulator-name = "VDD_LED_3.3V";
98 * regulator-min-microvolt = <3300000>;
99 * regulator-max-microvolt = <3300000>;
100 * gpio = <&gpc1 0 GPIO_ACTIVE_LOW>;
101 * };
102 * };
103 *
104 * The fixed regulator devices also provide regulator uclass platform data. And
105 * devices bound from such node, can use the regulator drivers API.
106 */
107
108 /* enum regulator_type - used for regulator_*() variant calls */
109 enum regulator_type {
110 REGULATOR_TYPE_LDO = 0,
111 REGULATOR_TYPE_BUCK,
112 REGULATOR_TYPE_DVS,
113 REGULATOR_TYPE_FIXED,
114 REGULATOR_TYPE_GPIO,
115 REGULATOR_TYPE_OTHER,
116 };
117
118 /**
119 * struct dm_regulator_mode - this structure holds an information about
120 * each regulator operation mode. Probably in most cases - an array.
121 * This will be probably a driver-static data, since it is device-specific.
122 *
123 * @id - a driver-specific mode id
124 * @register_value - a driver-specific value for its mode id
125 * @name - the name of mode - used for regulator command
126 * Note:
127 * The field 'id', should be always a positive number, since the negative values
128 * are reserved for the errno numbers when returns the mode id.
129 */
130 struct dm_regulator_mode {
131 int id; /* Set only as >= 0 (negative value is reserved for errno) */
132 int register_value;
133 const char *name;
134 };
135
136 enum regulator_flag {
137 REGULATOR_FLAG_AUTOSET_UV = 1 << 0,
138 REGULATOR_FLAG_AUTOSET_UA = 1 << 1,
139 REGULATOR_FLAG_AUTOSET_DONE = 1 << 2,
140 };
141
142 /**
143 * struct dm_regulator_uclass_plat - pointed by dev->uclass_plat, and
144 * allocated on each regulator bind. This structure holds an information
145 * about each regulator's constraints and supported operation modes.
146 * There is no "step" voltage value - so driver should take care of this.
147 *
148 * @type - one of 'enum regulator_type'
149 * @mode - pointer to the regulator mode (array if more than one)
150 * @mode_count - number of '.mode' entries
151 * @min_uV* - minimum voltage (micro Volts)
152 * @max_uV* - maximum voltage (micro Volts)
153 * @min_uA* - minimum amperage (micro Amps)
154 * @max_uA* - maximum amperage (micro Amps)
155 * @always_on* - bool type, true or false
156 * @boot_on* - bool type, true or false
157 * @force_off* - bool type, true or false
158 * TODO(sjg@chromium.org): Consider putting the above two into @flags
159 * @ramp_delay - Time to settle down after voltage change (unit: uV/us)
160 * @flags: - flags value (see REGULATOR_FLAG_...)
161 * @name** - fdt regulator name - should be taken from the device tree
162 * ctrl_reg: - Control register offset used to enable/disable regulator
163 * volt_reg: - register offset for writing voltage vsel values
164 *
165 * Note:
166 * * - set automatically on device probe by the uclass's '.pre_probe' method.
167 * ** - set automatically on device bind by the uclass's '.post_bind' method.
168 * The constraints: type, mode, mode_count, can be set by device driver, e.g.
169 * by the driver '.probe' method.
170 */
171 struct dm_regulator_uclass_plat {
172 enum regulator_type type;
173 struct dm_regulator_mode *mode;
174 int mode_count;
175 int min_uV;
176 int max_uV;
177 int init_uV;
178 int min_uA;
179 int max_uA;
180 unsigned int ramp_delay;
181 bool always_on;
182 bool boot_on;
183 bool force_off;
184 const char *name;
185 int flags;
186 u8 ctrl_reg;
187 u8 volt_reg;
188 bool suspend_on;
189 u32 suspend_uV;
190 };
191
192 /* Regulator device operations */
193 struct dm_regulator_ops {
194 /**
195 * The regulator output value function calls operates on a micro Volts.
196 *
197 * get/set_value - get/set output value of the given output number
198 * @dev - regulator device
199 * Sets:
200 * @uV - set the output value [micro Volts]
201 * @return output value [uV] on success or negative errno if fail.
202 */
203 int (*get_value)(struct udevice *dev);
204 int (*set_value)(struct udevice *dev, int uV);
205
206 /**
207 * The regulator suspend output value function calls operates
208 * on a micro Volts.
209 *
210 * get/set_suspen_value - get/set suspend mode output value
211 * @dev - regulator device
212 * Sets:
213 * @uV - set the suspend output value [micro Volts]
214 * @return output value [uV] on success or negative errno if fail.
215 */
216 int (*set_suspend_value)(struct udevice *dev, int uV);
217 int (*get_suspend_value)(struct udevice *dev);
218
219 /**
220 * The regulator output current function calls operates on a micro Amps.
221 *
222 * get/set_current - get/set output current of the given output number
223 * @dev - regulator device
224 * Sets:
225 * @uA - set the output current [micro Amps]
226 * @return output value [uA] on success or negative errno if fail.
227 */
228 int (*get_current)(struct udevice *dev);
229 int (*set_current)(struct udevice *dev, int uA);
230
231 /**
232 * The most basic feature of the regulator output is its enable state.
233 *
234 * get/set_enable - get/set enable state of the given output number
235 * @dev - regulator device
236 * Sets:
237 * @enable - set true - enable or false - disable
238 * @return true/false for get or -errno if fail; 0 / -errno for set.
239 */
240 int (*get_enable)(struct udevice *dev);
241 int (*set_enable)(struct udevice *dev, bool enable);
242
243 /**
244 * The most basic feature of the regulator output is its enable state
245 * in suspend mode.
246 *
247 * get/set_suspend_enable - get/set enable state of the suspend output
248 * @dev - regulator device
249 * Sets:
250 * @enable - set true - enable or false - disable
251 * @return true/false for get or -errno if fail; 0 / -errno for set.
252 */
253 int (*set_suspend_enable)(struct udevice *dev, bool enable);
254 int (*get_suspend_enable)(struct udevice *dev);
255
256 /**
257 * The 'get/set_mode()' function calls should operate on a driver-
258 * specific mode id definitions, which should be found in:
259 * field 'id' of struct dm_regulator_mode.
260 *
261 * get/set_mode - get/set operation mode of the given output number
262 * @dev - regulator device
263 * Sets
264 * @mode_id - set output mode id (struct dm_regulator_mode->id)
265 * @return id/0 for get/set on success or negative errno if fail.
266 * Note:
267 * The field 'id' of struct type 'dm_regulator_mode', should be always
268 * a positive number, since the negative is reserved for the error.
269 */
270 int (*get_mode)(struct udevice *dev);
271 int (*set_mode)(struct udevice *dev, int mode_id);
272 };
273
274 #if CONFIG_IS_ENABLED(DM_REGULATOR)
275 /**
276 * regulator_mode: returns a pointer to the array of regulator mode info
277 *
278 * @dev - pointer to the regulator device
279 * @modep - pointer to the returned mode info array
280 * Return: - count of modep entries on success or negative errno if fail.
281 */
282 int regulator_mode(struct udevice *dev, struct dm_regulator_mode **modep);
283
284 /**
285 * regulator_get_value: get microvoltage voltage value of a given regulator
286 *
287 * @dev - pointer to the regulator device
288 * Return: - positive output value [uV] on success or negative errno if fail.
289 */
290 int regulator_get_value(struct udevice *dev);
291
292 /**
293 * regulator_set_value: set the microvoltage value of a given regulator.
294 *
295 * @dev - pointer to the regulator device
296 * @uV - the output value to set [micro Volts]
297 * Return: - 0 on success or -errno val if fails
298 */
299 int regulator_set_value(struct udevice *dev, int uV);
300
301 /**
302 * regulator_set_suspend_value: set the suspend microvoltage value of a given regulator.
303 *
304 * @dev - pointer to the regulator device
305 * @uV - the output suspend value to set [micro Volts]
306 * Return: - 0 on success or -errno val if fails
307 */
308 int regulator_set_suspend_value(struct udevice *dev, int uV);
309
310 /**
311 * regulator_get_suspend_value: get the suspend microvoltage value of a given regulator.
312 *
313 * @dev - pointer to the regulator device
314 * Return: - positive output value [uV] on success or negative errno if fail.
315 */
316 int regulator_get_suspend_value(struct udevice *dev);
317
318 /**
319 * regulator_set_value_force: set the microvoltage value of a given regulator
320 * without any min-,max condition check
321 *
322 * @dev - pointer to the regulator device
323 * @uV - the output value to set [micro Volts]
324 * Return: - 0 on success or -errno val if fails
325 */
326 int regulator_set_value_force(struct udevice *dev, int uV);
327
328 /**
329 * regulator_get_current: get microampere value of a given regulator
330 *
331 * @dev - pointer to the regulator device
332 * Return: - positive output current [uA] on success or negative errno if fail.
333 */
334 int regulator_get_current(struct udevice *dev);
335
336 /**
337 * regulator_set_current: set the microampere value of a given regulator.
338 *
339 * @dev - pointer to the regulator device
340 * @uA - set the output current [micro Amps]
341 * Return: - 0 on success or -errno val if fails
342 */
343 int regulator_set_current(struct udevice *dev, int uA);
344
345 /**
346 * regulator_get_enable: get regulator device enable state.
347 *
348 * @dev - pointer to the regulator device
349 * Return: - true/false of enable state or -errno val if fails
350 */
351 int regulator_get_enable(struct udevice *dev);
352
353 /**
354 * regulator_set_enable: set regulator enable state
355 *
356 * @dev - pointer to the regulator device
357 * @enable - set true or false
358 * Return: - 0 on success or -errno val if fails
359 */
360 int regulator_set_enable(struct udevice *dev, bool enable);
361
362 /**
363 * regulator_set_enable_if_allowed: set regulator enable state if allowed by
364 * regulator
365 *
366 * @dev - pointer to the regulator device
367 * @enable - set true or false
368 * Return: - 0 on success or if enabling is not supported
369 * -errno val if fails.
370 */
371 int regulator_set_enable_if_allowed(struct udevice *dev, bool enable);
372
373 /**
374 * regulator_set_suspend_enable: set regulator suspend enable state
375 *
376 * @dev - pointer to the regulator device
377 * @enable - set true or false
378 * Return: - 0 on success or -errno val if fails
379 */
380 int regulator_set_suspend_enable(struct udevice *dev, bool enable);
381
382 /**
383 * regulator_get_suspend_enable: get regulator suspend enable state
384 *
385 * @dev - pointer to the regulator device
386 * Return: - true/false of enable state or -errno val if fails
387 */
388 int regulator_get_suspend_enable(struct udevice *dev);
389
390 /**
391 * regulator_get_mode: get active operation mode id of a given regulator
392 *
393 * @dev - pointer to the regulator device
394 * Return: - positive mode 'id' number on success or -errno val if fails
395 * Note:
396 * The device can provide an array of operating modes, which is type of struct
397 * dm_regulator_mode. Each mode has it's own 'id', which should be unique inside
398 * that array. By calling this function, the driver should return an active mode
399 * id of the given regulator device.
400 */
401 int regulator_get_mode(struct udevice *dev);
402
403 /**
404 * regulator_set_mode: set the given regulator's, active mode id
405 *
406 * @dev - pointer to the regulator device
407 * @mode_id - mode id to set ('id' field of struct type dm_regulator_mode)
408 * Return: - 0 on success or -errno value if fails
409 * Note:
410 * The device can provide an array of operating modes, which is type of struct
411 * dm_regulator_mode. Each mode has it's own 'id', which should be unique inside
412 * that array. By calling this function, the driver should set the active mode
413 * of a given regulator to given by "mode_id" argument.
414 */
415 int regulator_set_mode(struct udevice *dev, int mode_id);
416
417 /**
418 * regulator_autoset: setup the voltage/current on a regulator
419 *
420 * The setup depends on constraints found in device's uclass's platform data
421 * (struct dm_regulator_uclass_plat):
422 *
423 * - Enable - will set - if any of: 'always_on' or 'boot_on' is set to true,
424 * or if both are unset, then the function returns
425 * - Voltage value - will set - if '.min_uV' and '.max_uV' values are equal
426 * - Current limit - will set - if '.min_uA' and '.max_uA' values are equal
427 *
428 * The function returns on the first-encountered error.
429 *
430 * @platname - expected string for dm_regulator_uclass_plat .name field
431 * @devp - returned pointer to the regulator device - if non-NULL passed
432 * @return: 0 on success or negative value of errno.
433 */
434 int regulator_autoset(struct udevice *dev);
435
436 /**
437 * regulator_autoset_by_name: setup the regulator given by its uclass's
438 * platform data name field. The setup depends on constraints found in device's
439 * uclass's platform data (struct dm_regulator_uclass_plat):
440 * - Enable - will set - if any of: 'always_on' or 'boot_on' is set to true,
441 * or if both are unset, then the function returns
442 * - Voltage value - will set - if '.min_uV' and '.max_uV' values are equal
443 * - Current limit - will set - if '.min_uA' and '.max_uA' values are equal
444 *
445 * The function returns on first encountered error.
446 *
447 * @platname - expected string for dm_regulator_uclass_plat .name field
448 * @devp - returned pointer to the regulator device - if non-NULL passed
449 * @return: 0 on success or negative value of errno.
450 *
451 * The returned 'regulator' device can be used with:
452 * - regulator_get/set_*
453 */
454 int regulator_autoset_by_name(const char *platname, struct udevice **devp);
455
456 /**
457 * regulator_list_autoset: setup the regulators given by list of their uclass's
458 * platform data name field. The setup depends on constraints found in device's
459 * uclass's platform data. The function loops with calls to:
460 * regulator_autoset_by_name() for each name from the list.
461 *
462 * @list_platname - an array of expected strings for .name field of each
463 * regulator's uclass plat
464 * @list_devp - an array of returned pointers to the successfully setup
465 * regulator devices if non-NULL passed
466 * @verbose - (true/false) print each regulator setup info, or be quiet
467 * Return: 0 on successfully setup of all list entries, otherwise first error.
468 *
469 * The returned 'regulator' devices can be used with:
470 * - regulator_get/set_*
471 *
472 * Note: The list must ends with NULL entry, like in the "platname" list below:
473 * char *my_regulators[] = {
474 * "VCC_3.3V",
475 * "VCC_1.8V",
476 * NULL,
477 * };
478 */
479 int regulator_list_autoset(const char *list_platname[],
480 struct udevice *list_devp[],
481 bool verbose);
482
483 /**
484 * regulator_get_by_devname: returns the pointer to the pmic regulator device.
485 * Search by name, found in regulator device's name.
486 *
487 * @devname - expected string for 'dev->name' of regulator device
488 * @devp - returned pointer to the regulator device
489 * Return: 0 on success or negative value of errno.
490 *
491 * The returned 'regulator' device is probed and can be used with:
492 * - regulator_get/set_*
493 */
494 int regulator_get_by_devname(const char *devname, struct udevice **devp);
495
496 /**
497 * regulator_get_by_platname: returns the pointer to the pmic regulator device.
498 * Search by name, found in regulator uclass plat.
499 *
500 * @platname - expected string for uc_pdata->name of regulator uclass plat
501 * @devp - returns pointer to the regulator device or NULL on error
502 * Return: 0 on success or negative value of errno.
503 *
504 * The returned 'regulator' device is probed and can be used with:
505 * - regulator_get/set_*
506 */
507 int regulator_get_by_platname(const char *platname, struct udevice **devp);
508
509 /**
510 * device_get_supply_regulator: returns the pointer to the supply regulator.
511 * Search by phandle, found in device's node.
512 *
513 * Note: Please pay attention to proper order of device bind sequence.
514 * The regulator device searched by the phandle, must be binded before
515 * this function call.
516 *
517 * @dev - device with supply phandle
518 * @supply_name - phandle name of regulator
519 * @devp - returned pointer to the supply device
520 * Return: 0 on success or negative value of errno.
521 */
522 int device_get_supply_regulator(struct udevice *dev, const char *supply_name,
523 struct udevice **devp);
524 #else
regulator_mode(struct udevice * dev,struct dm_regulator_mode ** modep)525 static inline int regulator_mode(struct udevice *dev, struct dm_regulator_mode **modep)
526 {
527 return -ENOSYS;
528 }
529
regulator_get_value(struct udevice * dev)530 static inline int regulator_get_value(struct udevice *dev)
531 {
532 return -ENOSYS;
533 }
534
regulator_set_value(struct udevice * dev,int uV)535 static inline int regulator_set_value(struct udevice *dev, int uV)
536 {
537 return -ENOSYS;
538 }
539
regulator_set_suspend_value(struct udevice * dev,int uV)540 static inline int regulator_set_suspend_value(struct udevice *dev, int uV)
541 {
542 return -ENOSYS;
543 }
544
regulator_get_suspend_value(struct udevice * dev)545 static inline int regulator_get_suspend_value(struct udevice *dev)
546 {
547 return -ENOSYS;
548 }
549
regulator_set_value_force(struct udevice * dev,int uV)550 static inline int regulator_set_value_force(struct udevice *dev, int uV)
551 {
552 return -ENOSYS;
553 }
554
regulator_get_current(struct udevice * dev)555 static inline int regulator_get_current(struct udevice *dev)
556 {
557 return -ENOSYS;
558 }
559
regulator_set_current(struct udevice * dev,int uA)560 static inline int regulator_set_current(struct udevice *dev, int uA)
561 {
562 return -ENOSYS;
563 }
564
regulator_get_enable(struct udevice * dev)565 static inline int regulator_get_enable(struct udevice *dev)
566 {
567 return -ENOSYS;
568 }
569
regulator_set_enable(struct udevice * dev,bool enable)570 static inline int regulator_set_enable(struct udevice *dev, bool enable)
571 {
572 return -ENOSYS;
573 }
574
regulator_set_enable_if_allowed(struct udevice * dev,bool enable)575 static inline int regulator_set_enable_if_allowed(struct udevice *dev, bool enable)
576 {
577 return -ENOSYS;
578 }
579
regulator_set_suspend_enable(struct udevice * dev,bool enable)580 static inline int regulator_set_suspend_enable(struct udevice *dev, bool enable)
581 {
582 return -ENOSYS;
583 }
584
regulator_get_suspend_enable(struct udevice * dev)585 static inline int regulator_get_suspend_enable(struct udevice *dev)
586 {
587 return -ENOSYS;
588 }
589
regulator_get_mode(struct udevice * dev)590 static inline int regulator_get_mode(struct udevice *dev)
591 {
592 return -ENOSYS;
593 }
594
regulator_set_mode(struct udevice * dev,int mode_id)595 static inline int regulator_set_mode(struct udevice *dev, int mode_id)
596 {
597 return -ENOSYS;
598 }
599
regulator_autoset(struct udevice * dev)600 static inline int regulator_autoset(struct udevice *dev)
601 {
602 return -ENOSYS;
603 }
604
regulator_autoset_by_name(const char * platname,struct udevice ** devp)605 static inline int regulator_autoset_by_name(const char *platname, struct udevice **devp)
606 {
607 return -ENOSYS;
608 }
609
regulator_list_autoset(const char * list_platname[],struct udevice * list_devp[],bool verbose)610 static inline int regulator_list_autoset(const char *list_platname[], struct udevice *list_devp[],
611 bool verbose)
612 {
613 return -ENOSYS;
614 }
615
regulator_get_by_devname(const char * devname,struct udevice ** devp)616 static inline int regulator_get_by_devname(const char *devname, struct udevice **devp)
617 {
618 return -ENOSYS;
619 }
620
regulator_get_by_platname(const char * platname,struct udevice ** devp)621 static inline int regulator_get_by_platname(const char *platname, struct udevice **devp)
622 {
623 return -ENOSYS;
624 }
625
device_get_supply_regulator(struct udevice * dev,const char * supply_name,struct udevice ** devp)626 static inline int device_get_supply_regulator(struct udevice *dev, const char *supply_name,
627 struct udevice **devp)
628 {
629 return -ENOSYS;
630 }
631 #endif
632
633 #endif /* _INCLUDE_REGULATOR_H_ */
634