• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 /**
11  * U-Boot Voltage/Current Regulator
12  * ================================
13  *
14  * The regulator API is based on a driver model, with the device tree support.
15  * And this header describes the functions and data types for the uclass id:
16  * 'UCLASS_REGULATOR' and the regulator driver API.
17  *
18  * The regulator uclass - is based on uclass platform data which is allocated,
19  * automatically for each regulator device on bind and 'dev->uclass_platdata'
20  * points to it. The data type is: 'struct dm_regulator_uclass_platdata'.
21  * The uclass file: 'drivers/power/regulator/regulator-uclass.c'
22  *
23  * The regulator device - is based on driver's model 'struct udevice'.
24  * The API can use regulator name in two meanings:
25  * - devname  - the regulator device's name: 'dev->name'
26  * - platname - the device's platdata's name. So in the code it looks like:
27  *              'uc_pdata = dev->uclass_platdata'; 'name = uc_pdata->name'.
28  *
29  * The regulator device driver - provide an implementation of uclass operations
30  * pointed by 'dev->driver->ops' as a struct of type 'struct dm_regulator_ops'.
31  *
32  * To proper bind the regulator device, the device tree node should provide
33  * regulator constraints, like in the example below:
34  *
35  * ldo1 {
36  *      regulator-name = "VDD_MMC_1.8V";     (must be unique for proper bind)
37  *      regulator-min-microvolt = <1000000>; (optional)
38  *      regulator-max-microvolt = <1000000>; (optional)
39  *      regulator-min-microamp = <1000>;     (optional)
40  *      regulator-max-microamp = <1000>;     (optional)
41  *      regulator-always-on;                 (optional)
42  *      regulator-boot-on;                   (optional)
43  * };
44  *
45  * Note: For the proper operation, at least name constraint is needed, since
46  * it can be used when calling regulator_get_by_platname(). And the mandatory
47  * rule for this name is, that it must be globally unique for the single dts.
48  * If regulator-name property is not provided, node name will be chosen.
49  *
50  * Regulator bind:
51  * For each regulator device, the device_bind() should be called with passed
52  * device tree offset. This is required for this uclass's '.post_bind' method,
53  * which does the scan on the device node, for the 'regulator-name' constraint.
54  * If the parent is not a PMIC device, and the child is not bind by function:
55  * 'pmic_bind_childs()', then it's recommended to bind the device by call to
56  * dm_scan_fdt_dev() - this is usually done automatically for bus devices,
57  * as a post bind method.
58  *
59  * Regulator get:
60  * Having the device's name constraint, we can call regulator_by_platname(),
61  * to find the required regulator. Before return, the regulator is probed,
62  * and the rest of its constraints are put into the device's uclass platform
63  * data, by the uclass regulator '.pre_probe' method.
64  *
65  * For more info about PMIC bind, please refer to file: 'include/power/pmic.h'
66  *
67  * Note:
68  * Please do not use the device_bind_by_name() function, since it pass '-1' as
69  * device node offset - and the bind will fail on uclass .post_bind method,
70  * because of missing 'regulator-name' constraint.
71  *
72  *
73  * Fixed Voltage/Current Regulator
74  * ===============================
75  *
76  * When fixed voltage regulator is needed, then enable the config:
77  * - CONFIG_DM_REGULATOR_FIXED
78  *
79  * The driver file: 'drivers/power/regulator/fixed.c', provides basic support
80  * for control the GPIO, and return the device tree constraint values.
81  *
82  * To bind the fixed voltage regulator device, we usually use a 'simple-bus'
83  * node as a parent. And 'regulator-fixed' for the driver compatible. This is
84  * the same as in the kernel. The example node of fixed regulator:
85  *
86  * simple-bus {
87  *     compatible = "simple-bus";
88  *     #address-cells = <1>;
89  *     #size-cells = <0>;
90  *
91  *     blue_led {
92  *         compatible = "regulator-fixed";
93  *         regulator-name = "VDD_LED_3.3V";
94  *         regulator-min-microvolt = <3300000>;
95  *         regulator-max-microvolt = <3300000>;
96  *         gpio = <&gpc1 0 GPIO_ACTIVE_LOW>;
97  *     };
98  * };
99  *
100  * The fixed regulator devices also provide regulator uclass platform data. And
101  * devices bound from such node, can use the regulator drivers API.
102 */
103 
104 /* enum regulator_type - used for regulator_*() variant calls */
105 enum regulator_type {
106 	REGULATOR_TYPE_LDO = 0,
107 	REGULATOR_TYPE_BUCK,
108 	REGULATOR_TYPE_DVS,
109 	REGULATOR_TYPE_FIXED,
110 	REGULATOR_TYPE_GPIO,
111 	REGULATOR_TYPE_OTHER,
112 };
113 
114 /**
115  * struct dm_regulator_mode - this structure holds an information about
116  * each regulator operation mode. Probably in most cases - an array.
117  * This will be probably a driver-static data, since it is device-specific.
118  *
119  * @id             - a driver-specific mode id
120  * @register_value - a driver-specific value for its mode id
121  * @name           - the name of mode - used for regulator command
122  * Note:
123  * The field 'id', should be always a positive number, since the negative values
124  * are reserved for the errno numbers when returns the mode id.
125  */
126 struct dm_regulator_mode {
127 	int id; /* Set only as >= 0 (negative value is reserved for errno) */
128 	int register_value;
129 	const char *name;
130 };
131 
132 enum regulator_flag {
133 	REGULATOR_FLAG_AUTOSET_UV	= 1 << 0,
134 	REGULATOR_FLAG_AUTOSET_UA	= 1 << 1,
135 };
136 
137 /**
138  * struct dm_regulator_uclass_platdata - pointed by dev->uclass_platdata, and
139  * allocated on each regulator bind. This structure holds an information
140  * about each regulator's constraints and supported operation modes.
141  * There is no "step" voltage value - so driver should take care of this.
142  *
143  * @type       - one of 'enum regulator_type'
144  * @mode       - pointer to the regulator mode (array if more than one)
145  * @mode_count - number of '.mode' entries
146  * @min_uV*    - minimum voltage (micro Volts)
147  * @max_uV*    - maximum voltage (micro Volts)
148  * @min_uA*    - minimum amperage (micro Amps)
149  * @max_uA*    - maximum amperage (micro Amps)
150  * @always_on* - bool type, true or false
151  * @boot_on*   - bool type, true or false
152  * TODO(sjg@chromium.org): Consider putting the above two into @flags
153  * @flags:     - flags value (see REGULATOR_FLAG_...)
154  * @name**     - fdt regulator name - should be taken from the device tree
155  * ctrl_reg:   - Control register offset used to enable/disable regulator
156  * volt_reg:   - register offset for writing voltage vsel values
157  *
158  * Note:
159  * *  - set automatically on device probe by the uclass's '.pre_probe' method.
160  * ** - set automatically on device bind by the uclass's '.post_bind' method.
161  * The constraints: type, mode, mode_count, can be set by device driver, e.g.
162  * by the driver '.probe' method.
163  */
164 struct dm_regulator_uclass_platdata {
165 	enum regulator_type type;
166 	struct dm_regulator_mode *mode;
167 	int mode_count;
168 	int min_uV;
169 	int max_uV;
170 	int min_uA;
171 	int max_uA;
172 	bool always_on;
173 	bool boot_on;
174 	const char *name;
175 	int flags;
176 	u8 ctrl_reg;
177 	u8 volt_reg;
178 };
179 
180 /* Regulator device operations */
181 struct dm_regulator_ops {
182 	/**
183 	 * The regulator output value function calls operates on a micro Volts.
184 	 *
185 	 * get/set_value - get/set output value of the given output number
186 	 * @dev          - regulator device
187 	 * Sets:
188 	 * @uV           - set the output value [micro Volts]
189 	 * @return output value [uV] on success or negative errno if fail.
190 	 */
191 	int (*get_value)(struct udevice *dev);
192 	int (*set_value)(struct udevice *dev, int uV);
193 
194 	/**
195 	 * The regulator output current function calls operates on a micro Amps.
196 	 *
197 	 * get/set_current - get/set output current of the given output number
198 	 * @dev            - regulator device
199 	 * Sets:
200 	 * @uA           - set the output current [micro Amps]
201 	 * @return output value [uA] on success or negative errno if fail.
202 	 */
203 	int (*get_current)(struct udevice *dev);
204 	int (*set_current)(struct udevice *dev, int uA);
205 
206 	/**
207 	 * The most basic feature of the regulator output is its enable state.
208 	 *
209 	 * get/set_enable - get/set enable state of the given output number
210 	 * @dev           - regulator device
211 	 * Sets:
212 	 * @enable         - set true - enable or false - disable
213 	 * @return true/false for get or -errno if fail; 0 / -errno for set.
214 	 */
215 	int (*get_enable)(struct udevice *dev);
216 	int (*set_enable)(struct udevice *dev, bool enable);
217 
218 	/**
219 	 * The 'get/set_mode()' function calls should operate on a driver-
220 	 * specific mode id definitions, which should be found in:
221 	 * field 'id' of struct dm_regulator_mode.
222 	 *
223 	 * get/set_mode - get/set operation mode of the given output number
224 	 * @dev         - regulator device
225 	 * Sets
226 	 * @mode_id     - set output mode id (struct dm_regulator_mode->id)
227 	 * @return id/0 for get/set on success or negative errno if fail.
228 	 * Note:
229 	 * The field 'id' of struct type 'dm_regulator_mode', should be always
230 	 * a positive number, since the negative is reserved for the error.
231 	 */
232 	int (*get_mode)(struct udevice *dev);
233 	int (*set_mode)(struct udevice *dev, int mode_id);
234 };
235 
236 /**
237  * regulator_mode: returns a pointer to the array of regulator mode info
238  *
239  * @dev        - pointer to the regulator device
240  * @modep      - pointer to the returned mode info array
241  * @return     - count of modep entries on success or negative errno if fail.
242  */
243 int regulator_mode(struct udevice *dev, struct dm_regulator_mode **modep);
244 
245 /**
246  * regulator_get_value: get microvoltage voltage value of a given regulator
247  *
248  * @dev    - pointer to the regulator device
249  * @return - positive output value [uV] on success or negative errno if fail.
250  */
251 int regulator_get_value(struct udevice *dev);
252 
253 /**
254  * regulator_set_value: set the microvoltage value of a given regulator.
255  *
256  * @dev    - pointer to the regulator device
257  * @uV     - the output value to set [micro Volts]
258  * @return - 0 on success or -errno val if fails
259  */
260 int regulator_set_value(struct udevice *dev, int uV);
261 
262 /**
263  * regulator_set_value_force: set the microvoltage value of a given regulator
264  *			      without any min-,max condition check
265  *
266  * @dev    - pointer to the regulator device
267  * @uV     - the output value to set [micro Volts]
268  * @return - 0 on success or -errno val if fails
269  */
270 int regulator_set_value_force(struct udevice *dev, int uV);
271 
272 /**
273  * regulator_get_current: get microampere value of a given regulator
274  *
275  * @dev    - pointer to the regulator device
276  * @return - positive output current [uA] on success or negative errno if fail.
277  */
278 int regulator_get_current(struct udevice *dev);
279 
280 /**
281  * regulator_set_current: set the microampere value of a given regulator.
282  *
283  * @dev    - pointer to the regulator device
284  * @uA     - set the output current [micro Amps]
285  * @return - 0 on success or -errno val if fails
286  */
287 int regulator_set_current(struct udevice *dev, int uA);
288 
289 /**
290  * regulator_get_enable: get regulator device enable state.
291  *
292  * @dev    - pointer to the regulator device
293  * @return - true/false of enable state or -errno val if fails
294  */
295 int regulator_get_enable(struct udevice *dev);
296 
297 /**
298  * regulator_set_enable: set regulator enable state
299  *
300  * @dev    - pointer to the regulator device
301  * @enable - set true or false
302  * @return - 0 on success or -errno val if fails
303  */
304 int regulator_set_enable(struct udevice *dev, bool enable);
305 
306 /**
307  * regulator_get_mode: get active operation mode id of a given regulator
308  *
309  * @dev    - pointer to the regulator device
310  * @return - positive mode 'id' number on success or -errno val if fails
311  * Note:
312  * The device can provide an array of operating modes, which is type of struct
313  * dm_regulator_mode. Each mode has it's own 'id', which should be unique inside
314  * that array. By calling this function, the driver should return an active mode
315  * id of the given regulator device.
316  */
317 int regulator_get_mode(struct udevice *dev);
318 
319 /**
320  * regulator_set_mode: set the given regulator's, active mode id
321  *
322  * @dev     - pointer to the regulator device
323  * @mode_id - mode id to set ('id' field of struct type dm_regulator_mode)
324  * @return  - 0 on success or -errno value if fails
325  * Note:
326  * The device can provide an array of operating modes, which is type of struct
327  * dm_regulator_mode. Each mode has it's own 'id', which should be unique inside
328  * that array. By calling this function, the driver should set the active mode
329  * of a given regulator to given by "mode_id" argument.
330  */
331 int regulator_set_mode(struct udevice *dev, int mode_id);
332 
333 /**
334  * regulators_enable_boot_on() - enable regulators needed for boot
335  *
336  * This enables all regulators which are marked to be on at boot time. This
337  * only works for regulators which don't have a range for voltage/current,
338  * since in that case it is not possible to know which value to use.
339  *
340  * This effectively calls regulator_autoset() for every regulator.
341  */
342 int regulators_enable_boot_on(bool verbose);
343 
344 /**
345  * regulator_autoset: setup the voltage/current on a regulator
346  *
347  * The setup depends on constraints found in device's uclass's platform data
348  * (struct dm_regulator_uclass_platdata):
349  *
350  * - Enable - will set - if any of: 'always_on' or 'boot_on' is set to true,
351  *   or if both are unset, then the function returns
352  * - Voltage value - will set - if '.min_uV' and '.max_uV' values are equal
353  * - Current limit - will set - if '.min_uA' and '.max_uA' values are equal
354  *
355  * The function returns on the first-encountered error.
356  *
357  * @platname - expected string for dm_regulator_uclass_platdata .name field
358  * @devp     - returned pointer to the regulator device - if non-NULL passed
359  * @return: 0 on success or negative value of errno.
360  */
361 int regulator_autoset(struct udevice *dev);
362 
363 /**
364  * regulator_autoset_by_name: setup the regulator given by its uclass's
365  * platform data name field. The setup depends on constraints found in device's
366  * uclass's platform data (struct dm_regulator_uclass_platdata):
367  * - Enable - will set - if any of: 'always_on' or 'boot_on' is set to true,
368  *   or if both are unset, then the function returns
369  * - Voltage value - will set - if '.min_uV' and '.max_uV' values are equal
370  * - Current limit - will set - if '.min_uA' and '.max_uA' values are equal
371  *
372  * The function returns on first encountered error.
373  *
374  * @platname - expected string for dm_regulator_uclass_platdata .name field
375  * @devp     - returned pointer to the regulator device - if non-NULL passed
376  * @return: 0 on success or negative value of errno.
377  *
378  * The returned 'regulator' device can be used with:
379  * - regulator_get/set_*
380  */
381 int regulator_autoset_by_name(const char *platname, struct udevice **devp);
382 
383 /**
384  * regulator_list_autoset: setup the regulators given by list of their uclass's
385  * platform data name field. The setup depends on constraints found in device's
386  * uclass's platform data. The function loops with calls to:
387  * regulator_autoset_by_name() for each name from the list.
388  *
389  * @list_platname - an array of expected strings for .name field of each
390  *                  regulator's uclass platdata
391  * @list_devp     - an array of returned pointers to the successfully setup
392  *                  regulator devices if non-NULL passed
393  * @verbose       - (true/false) print each regulator setup info, or be quiet
394  * @return 0 on successfully setup of all list entries, otherwise first error.
395  *
396  * The returned 'regulator' devices can be used with:
397  * - regulator_get/set_*
398  *
399  * Note: The list must ends with NULL entry, like in the "platname" list below:
400  * char *my_regulators[] = {
401  *     "VCC_3.3V",
402  *     "VCC_1.8V",
403  *     NULL,
404  * };
405  */
406 int regulator_list_autoset(const char *list_platname[],
407 			   struct udevice *list_devp[],
408 			   bool verbose);
409 
410 /**
411  * regulator_get_by_devname: returns the pointer to the pmic regulator device.
412  * Search by name, found in regulator device's name.
413  *
414  * @devname - expected string for 'dev->name' of regulator device
415  * @devp    - returned pointer to the regulator device
416  * @return 0 on success or negative value of errno.
417  *
418  * The returned 'regulator' device is probed and can be used with:
419  * - regulator_get/set_*
420  */
421 int regulator_get_by_devname(const char *devname, struct udevice **devp);
422 
423 /**
424  * regulator_get_by_platname: returns the pointer to the pmic regulator device.
425  * Search by name, found in regulator uclass platdata.
426  *
427  * @platname - expected string for uc_pdata->name of regulator uclass platdata
428  * @devp     - returns pointer to the regulator device or NULL on error
429  * @return 0 on success or negative value of errno.
430  *
431  * The returned 'regulator' device is probed and can be used with:
432  * - regulator_get/set_*
433  */
434 int regulator_get_by_platname(const char *platname, struct udevice **devp);
435 
436 /**
437  * device_get_supply_regulator: returns the pointer to the supply regulator.
438  * Search by phandle, found in device's node.
439  *
440  * Note: Please pay attention to proper order of device bind sequence.
441  * The regulator device searched by the phandle, must be binded before
442  * this function call.
443  *
444  * @dev         - device with supply phandle
445  * @supply_name - phandle name of regulator
446  * @devp        - returned pointer to the supply device
447  * @return 0 on success or negative value of errno.
448  */
449 int device_get_supply_regulator(struct udevice *dev, const char *supply_name,
450 				struct udevice **devp);
451 
452 #endif /* _INCLUDE_REGULATOR_H_ */
453