blob: 6916660255d38b2ee141ae0c508b4bade222b8a0 [file] [log] [blame]
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +02001/*
2 * Copyright (C) 2014-2015 Samsung Electronics
3 * Przemyslaw Marczak <p.marczak@samsung.com>
4 *
5 * SPDX-License-Identifier: GPL-2.0+
6 */
7
8#ifndef _INCLUDE_REGULATOR_H_
9#define _INCLUDE_REGULATOR_H_
10
11/**
12 * U-Boot Voltage/Current Regulator
13 * ================================
14 *
15 * The regulator API is based on a driver model, with the device tree support.
16 * And this header describes the functions and data types for the uclass id:
17 * 'UCLASS_REGULATOR' and the regulator driver API.
18 *
19 * The regulator uclass - is based on uclass platform data which is allocated,
20 * automatically for each regulator device on bind and 'dev->uclass_platdata'
21 * points to it. The data type is: 'struct dm_regulator_uclass_platdata'.
22 * The uclass file: 'drivers/power/regulator/regulator-uclass.c'
23 *
24 * The regulator device - is based on driver's model 'struct udevice'.
25 * The API can use regulator name in two meanings:
26 * - devname - the regulator device's name: 'dev->name'
27 * - platname - the device's platdata's name. So in the code it looks like:
28 * 'uc_pdata = dev->uclass_platdata'; 'name = uc_pdata->name'.
29 *
30 * The regulator device driver - provide an implementation of uclass operations
31 * pointed by 'dev->driver->ops' as a struct of type 'struct dm_regulator_ops'.
32 *
33 * To proper bind the regulator device, the device tree node should provide
34 * regulator constraints, like in the example below:
35 *
36 * ldo1 {
37 * regulator-name = "VDD_MMC_1.8V"; (mandatory for bind)
38 * regulator-min-microvolt = <1000000>; (optional)
39 * regulator-max-microvolt = <1000000>; (optional)
40 * regulator-min-microamp = <1000>; (optional)
41 * regulator-max-microamp = <1000>; (optional)
42 * regulator-always-on; (optional)
43 * regulator-boot-on; (optional)
44 * };
45 *
46 * Please take a notice, that for the proper operation at least name constraint
47 * is needed, e.g. for call the device_by_platname(...).
48 *
49 * Regulator bind:
50 * For each regulator device, the device_bind() should be called with passed
51 * device tree offset. This is required for this uclass's '.post_bind' method,
52 * which do the scan on the device node, for the 'regulator-name' constraint.
53 * If the parent is not a PMIC device, and the child is not bind by function:
54 * 'pmic_bind_childs()', then it's recommended to bind the device by call to
55 * dm_scan_fdt_node() - this is usually done automatically for bus devices,
56 * as a post bind method.
57 * Having the device's name constraint, we can call regulator_by_platname(),
58 * to find interesting regulator. Before return, the regulator is probed,
59 * and the rest of its constraints are put into the device's uclass platform
60 * data, by the uclass regulator '.pre_probe' method.
61 *
62 * For more info about PMIC bind, please refer to file: 'include/power/pmic.h'
63 *
64 * Note:
65 * Please do not use the device_bind_by_name() function, since it pass '-1' as
66 * device node offset - and the bind will fail on uclass .post_bind method,
67 * because of missing 'regulator-name' constraint.
68 *
69 *
70 * Fixed Voltage/Current Regulator
71 * ===============================
72 *
73 * When fixed voltage regulator is needed, then enable the config:
74 * - CONFIG_DM_REGULATOR_FIXED
75 *
76 * The driver file: 'drivers/power/regulator/fixed.c', provides basic support
77 * for control the GPIO, and return the device tree constraint values.
78 *
79 * To bind the fixed voltage regulator device, we usually use a 'simple-bus'
80 * node as a parent. And 'regulator-fixed' for the driver compatible. This is
81 * the same as in the kernel. The example node of fixed regulator:
82 *
83 * simple-bus {
84 * compatible = "simple-bus";
85 * #address-cells = <1>;
86 * #size-cells = <0>;
87 *
88 * blue_led {
89 * compatible = "regulator-fixed";
90 * regulator-name = "VDD_LED_3.3V";
91 * regulator-min-microvolt = <3300000>;
92 * regulator-max-microvolt = <3300000>;
93 * gpio = <&gpc1 0 GPIO_ACTIVE_LOW>;
94 * };
95 * };
96 *
97 * The fixed regulator devices also provide regulator uclass platform data. And
98 * devices bound from such node, can use the regulator drivers API.
99*/
100
101/* enum regulator_type - used for regulator_*() variant calls */
102enum regulator_type {
103 REGULATOR_TYPE_LDO = 0,
104 REGULATOR_TYPE_BUCK,
105 REGULATOR_TYPE_DVS,
106 REGULATOR_TYPE_FIXED,
107 REGULATOR_TYPE_OTHER,
108};
109
110/**
111 * struct dm_regulator_mode - this structure holds an information about
112 * each regulator operation mode. Probably in most cases - an array.
113 * This will be probably a driver-static data, since it is device-specific.
114 *
115 * @id - a driver-specific mode id
116 * @register_value - a driver-specific value for its mode id
117 * @name - the name of mode - used for regulator command
118 * Note:
119 * The field 'id', should be always a positive number, since the negative values
120 * are reserved for the errno numbers when returns the mode id.
121 */
122struct dm_regulator_mode {
123 int id; /* Set only as >= 0 (negative value is reserved for errno) */
124 int register_value;
125 const char *name;
126};
127
128/**
129 * struct dm_regulator_uclass_platdata - pointed by dev->uclass_platdata, and
130 * allocated on each regulator bind. This structure holds an information
131 * about each regulator's constraints and supported operation modes.
132 * There is no "step" voltage value - so driver should take care of this.
133 *
134 * @type - one of 'enum regulator_type'
135 * @mode - pointer to the regulator mode (array if more than one)
136 * @mode_count - number of '.mode' entries
137 * @min_uV* - minimum voltage (micro Volts)
138 * @max_uV* - maximum voltage (micro Volts)
139 * @min_uA* - minimum amperage (micro Amps)
140 * @max_uA* - maximum amperage (micro Amps)
141 * @always_on* - bool type, true or false
142 * @boot_on* - bool type, true or false
143 * @name** - fdt regulator name - should be taken from the device tree
144 *
145 * Note:
146 * * - set automatically on device probe by the uclass's '.pre_probe' method.
147 * ** - set automatically on device bind by the uclass's '.post_bind' method.
148 * The constraints: type, mode, mode_count, can be set by device driver, e.g.
149 * by the driver '.probe' method.
150 */
151struct dm_regulator_uclass_platdata {
152 enum regulator_type type;
153 struct dm_regulator_mode *mode;
154 int mode_count;
155 int min_uV;
156 int max_uV;
157 int min_uA;
158 int max_uA;
159 bool always_on;
160 bool boot_on;
161 const char *name;
162};
163
164/* Regulator device operations */
165struct dm_regulator_ops {
166 /**
167 * The regulator output value function calls operates on a micro Volts.
168 *
169 * get/set_value - get/set output value of the given output number
170 * @dev - regulator device
171 * Sets:
172 * @uV - set the output value [micro Volts]
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200173 * @return output value [uV] on success or negative errno if fail.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200174 */
175 int (*get_value)(struct udevice *dev);
176 int (*set_value)(struct udevice *dev, int uV);
177
178 /**
179 * The regulator output current function calls operates on a micro Amps.
180 *
181 * get/set_current - get/set output current of the given output number
182 * @dev - regulator device
183 * Sets:
184 * @uA - set the output current [micro Amps]
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200185 * @return output value [uA] on success or negative errno if fail.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200186 */
187 int (*get_current)(struct udevice *dev);
188 int (*set_current)(struct udevice *dev, int uA);
189
190 /**
191 * The most basic feature of the regulator output is its enable state.
192 *
193 * get/set_enable - get/set enable state of the given output number
194 * @dev - regulator device
195 * Sets:
196 * @enable - set true - enable or false - disable
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200197 * @return true/false for get; or 0 / -errno for set.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200198 */
199 bool (*get_enable)(struct udevice *dev);
200 int (*set_enable)(struct udevice *dev, bool enable);
201
202 /**
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200203 * The 'get/set_mode()' function calls should operate on a driver-
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200204 * specific mode definitions, which should be found in:
205 * field 'mode' of struct mode_desc.
206 *
207 * get/set_mode - get/set operation mode of the given output number
208 * @dev - regulator device
209 * Sets
210 * @mode_id - set output mode id (struct dm_regulator_mode->id)
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200211 * @return id/0 for get/set on success or negative errno if fail.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200212 * Note:
213 * The field 'id' of struct type 'dm_regulator_mode', should be always
214 * positive number, since the negative is reserved for the error.
215 */
216 int (*get_mode)(struct udevice *dev);
217 int (*set_mode)(struct udevice *dev, int mode_id);
218};
219
220/**
221 * regulator_mode: returns a pointer to the array of regulator mode info
222 *
223 * @dev - pointer to the regulator device
224 * @modep - pointer to the returned mode info array
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200225 * @return - count of modep entries on success or negative errno if fail.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200226 */
227int regulator_mode(struct udevice *dev, struct dm_regulator_mode **modep);
228
229/**
230 * regulator_get_value: get microvoltage voltage value of a given regulator
231 *
232 * @dev - pointer to the regulator device
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200233 * @return - positive output value [uV] on success or negative errno if fail.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200234 */
235int regulator_get_value(struct udevice *dev);
236
237/**
238 * regulator_set_value: set the microvoltage value of a given regulator.
239 *
240 * @dev - pointer to the regulator device
241 * @uV - the output value to set [micro Volts]
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200242 * @return - 0 on success or -errno val if fails
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200243 */
244int regulator_set_value(struct udevice *dev, int uV);
245
246/**
247 * regulator_get_current: get microampere value of a given regulator
248 *
249 * @dev - pointer to the regulator device
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200250 * @return - positive output current [uA] on success or negative errno if fail.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200251 */
252int regulator_get_current(struct udevice *dev);
253
254/**
255 * regulator_set_current: set the microampere value of a given regulator.
256 *
257 * @dev - pointer to the regulator device
258 * @uA - set the output current [micro Amps]
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200259 * @return - 0 on success or -errno val if fails
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200260 */
261int regulator_set_current(struct udevice *dev, int uA);
262
263/**
264 * regulator_get_enable: get regulator device enable state.
265 *
266 * @dev - pointer to the regulator device
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200267 * @return - true/false of enable state
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200268 */
269bool regulator_get_enable(struct udevice *dev);
270
271/**
272 * regulator_set_enable: set regulator enable state
273 *
274 * @dev - pointer to the regulator device
275 * @enable - set true or false
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200276 * @return - 0 on success or -errno val if fails
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200277 */
278int regulator_set_enable(struct udevice *dev, bool enable);
279
280/**
281 * regulator_get_mode: get mode of a given device regulator
282 *
283 * @dev - pointer to the regulator device
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200284 * @return - positive mode number on success or -errno val if fails
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200285 * Note:
286 * The regulator driver should return one of defined, mode number rather, than
287 * the raw register value. The struct type 'mode_desc' provides a field 'mode'
288 * for this purpose and register_value for a raw register value.
289 */
290int regulator_get_mode(struct udevice *dev);
291
292/**
293 * regulator_set_mode: set given regulator mode
294 *
295 * @dev - pointer to the regulator device
296 * @mode - mode type (field 'mode' of struct mode_desc)
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200297 * @return - 0 on success or -errno value if fails
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200298 * Note:
299 * The regulator driver should take one of defined, mode number rather
300 * than a raw register value. The struct type 'regulator_mode_desc' has
301 * a mode field for this purpose and register_value for a raw register value.
302 */
303int regulator_set_mode(struct udevice *dev, int mode);
304
305/**
306 * regulator_by_platname_autoset_and_enable: setup the regulator given by
307 * its uclass's platform data '.name'. The setup depends on constraints found
308 * in device's uclass's platform data (struct dm_regulator_uclass_platdata):
309 * - Voltage value - will set - if '.min_uV' and '.max_uV' values are equal
310 * - Current limit - will set - if '.min_uA' and '.max_uA' values are equal
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200311 * - Enable - will set - if any of: '.always_on' or '.boot_on', is set to true
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200312 *
313 * The function returns on first encountered error.
314 *
315 * @platname - expected string for dm_regulator_uclass_platdata .name field
316 * @devp - returned pointer to the regulator device - if non-NULL passed
317 * @verbose - (true/false) print regulator setup info, or be quiet
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200318 * @return: 0 on success or negative value of errno.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200319 *
320 * The returned 'regulator' device can be used with:
321 * - regulator_get/set_*
322 * For shorter call name, the below macro regulator_autoset() can be used.
323 */
324int regulator_by_platname_autoset_and_enable(const char *platname,
325 struct udevice **devp,
326 bool verbose);
327
328#define regulator_autoset(platname, devp, verbose) \
329 regulator_by_platname_autoset_and_enable(platname, devp, verbose)
330
331/**
332 * regulator_by_platname_list_autoset_and_enable: setup the regulators given by
333 * list of its uclass's platform data '.name'. The setup depends on constraints
334 * found in device's uclass's platform data. The function loops with calls to:
335 * regulator_by_platname_autoset_and_enable() for each name of list.
336 *
337 * @list_platname - an array of expected strings for .name field of each
338 * regulator's uclass platdata
339 * @list_entries - number of regulator's name list entries
340 * @list_devp - an array of returned pointers to the successfully setup
341 * regulator devices if non-NULL passed
342 * @verbose - (true/false) print each regulator setup info, or be quiet
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200343 * @return 0 on successfully setup of all list entries or 1 otwerwise.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200344 *
345 * The returned 'regulator' devices can be used with:
346 * - regulator_get/set_*
347 * For shorter call name, the below macro regulator_list_autoset() can be used.
348 */
349int regulator_by_platname_list_autoset_and_enable(const char *list_platname[],
350 int list_entries,
351 struct udevice *list_devp[],
352 bool verbose);
353
354#define regulator_list_autoset(namelist, entries, devlist, verbose) \
355 regulator_by_platname_list_autoset_and_enable(namelist, entries, \
356 devlist, verbose)
357
358/**
359 * regulator_by_devname: returns the pointer to the pmic regulator device.
360 * Search by name, found in regulator device's name.
361 *
362 * @devname - expected string for 'dev->name' of regulator device
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200363 * @devp - returned pointer to the regulator device
364 * @return 0 on success or negative value of errno.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200365 *
366 * The returned 'regulator' device can be used with:
367 * - regulator_get/set_*
368 */
369int regulator_by_devname(const char *devname, struct udevice **devp);
370
371/**
372 * regulator_by_platname: returns the pointer to the pmic regulator device.
373 * Search by name, found in regulator uclass platdata.
374 *
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200375 * @platname - expected string for uc_pdata->name of regulator uclass platdata
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200376 * @devp - returned pointer to the regulator device
Przemyslaw Marczak1757df42015-04-20 20:07:47 +0200377 * @return 0 on success or negative value of errno.
Przemyslaw Marczakaf41e8d2015-04-20 20:07:42 +0200378 *
379 * The returned 'regulator' device can be used with:
380 * - regulator_get/set_*
381 */
382int regulator_by_platname(const char *platname, struct udevice **devp);
383
384#endif /* _INCLUDE_REGULATOR_H_ */