1 /*
2 * Copyright (c) 2019-2020 Peter Bigot Consulting, LLC
3 * Copyright (c) 2021 NXP
4 * Copyright (c) 2022 Nordic Semiconductor ASA
5 * Copyright (c) 2023 EPAM Systems
6 * SPDX-License-Identifier: Apache-2.0
7 */
8
9 #ifndef ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_
10 #define ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_
11
12 /**
13 * @brief Regulator Interface
14 * @defgroup regulator_interface Regulator Interface
15 * @ingroup io_interfaces
16 * @{
17 */
18
19 #include <errno.h>
20 #include <stdint.h>
21
22 #include <zephyr/device.h>
23 #include <zephyr/devicetree.h>
24 #ifdef CONFIG_REGULATOR_THREAD_SAFE_REFCNT
25 #include <zephyr/kernel.h>
26 #endif
27 #include <zephyr/sys/util_macro.h>
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /** Opaque type to store regulator DVS states */
34 typedef uint8_t regulator_dvs_state_t;
35
36 /** Opaque type to store regulator modes */
37 typedef uint8_t regulator_mode_t;
38
39 /** Opaque bit map for regulator error flags (see @ref REGULATOR_ERRORS) */
40 typedef uint8_t regulator_error_flags_t;
41
42 /**
43 * @name Regulator error flags.
44 * @anchor REGULATOR_ERRORS
45 * @{
46 */
47
48 /** Voltage is too high. */
49 #define REGULATOR_ERROR_OVER_VOLTAGE BIT(0)
50 /** Current is too high. */
51 #define REGULATOR_ERROR_OVER_CURRENT BIT(1)
52 /** Temperature is too high. */
53 #define REGULATOR_ERROR_OVER_TEMP BIT(2)
54
55 /** @} */
56
57 /** @cond INTERNAL_HIDDEN */
58
59 typedef int (*regulator_dvs_state_set_t)(const struct device *dev,
60 regulator_dvs_state_t state);
61
62 typedef int (*regulator_ship_mode_t)(const struct device *dev);
63
64 /** @brief Driver-specific API functions to support parent regulator control. */
65 __subsystem struct regulator_parent_driver_api {
66 regulator_dvs_state_set_t dvs_state_set;
67 regulator_ship_mode_t ship_mode;
68 };
69
70 typedef int (*regulator_enable_t)(const struct device *dev);
71 typedef int (*regulator_disable_t)(const struct device *dev);
72 typedef unsigned int (*regulator_count_voltages_t)(const struct device *dev);
73 typedef int (*regulator_list_voltage_t)(const struct device *dev,
74 unsigned int idx, int32_t *volt_uv);
75 typedef int (*regulator_set_voltage_t)(const struct device *dev, int32_t min_uv,
76 int32_t max_uv);
77 typedef int (*regulator_get_voltage_t)(const struct device *dev,
78 int32_t *volt_uv);
79 typedef int (*regulator_set_current_limit_t)(const struct device *dev,
80 int32_t min_ua, int32_t max_ua);
81 typedef int (*regulator_get_current_limit_t)(const struct device *dev,
82 int32_t *curr_ua);
83 typedef int (*regulator_set_mode_t)(const struct device *dev,
84 regulator_mode_t mode);
85 typedef int (*regulator_get_mode_t)(const struct device *dev,
86 regulator_mode_t *mode);
87 typedef int (*regulator_get_error_flags_t)(
88 const struct device *dev, regulator_error_flags_t *flags);
89
90 /** @brief Driver-specific API functions to support regulator control. */
91 __subsystem struct regulator_driver_api {
92 regulator_enable_t enable;
93 regulator_disable_t disable;
94 regulator_count_voltages_t count_voltages;
95 regulator_list_voltage_t list_voltage;
96 regulator_set_voltage_t set_voltage;
97 regulator_get_voltage_t get_voltage;
98 regulator_set_current_limit_t set_current_limit;
99 regulator_get_current_limit_t get_current_limit;
100 regulator_set_mode_t set_mode;
101 regulator_get_mode_t get_mode;
102 regulator_get_error_flags_t get_error_flags;
103 };
104
105 /**
106 * @name Regulator flags
107 * @anchor REGULATOR_FLAGS
108 * @{
109 */
110 /** Indicates regulator must stay always ON */
111 #define REGULATOR_ALWAYS_ON BIT(0)
112 /** Indicates regulator must be initialized ON */
113 #define REGULATOR_BOOT_ON BIT(1)
114 /** Indicates if regulator must be enabled when initialized */
115 #define REGULATOR_INIT_ENABLED (REGULATOR_ALWAYS_ON | REGULATOR_BOOT_ON)
116
117 /** @} */
118
119 /** Indicates initial mode is unknown/not specified */
120 #define REGULATOR_INITIAL_MODE_UNKNOWN UINT8_MAX
121
122 /**
123 * @brief Common regulator config.
124 *
125 * This structure **must** be placed first in the driver's config structure.
126 */
127 struct regulator_common_config {
128 /** Minimum allowed voltage, in microvolts. */
129 int32_t min_uv;
130 /** Maximum allowed voltage, in microvolts. */
131 int32_t max_uv;
132 /** Initial voltage, in microvolts. */
133 int32_t init_uv;
134 /** Minimum allowed current, in microamps. */
135 int32_t min_ua;
136 /** Maximum allowed current, in microamps. */
137 int32_t max_ua;
138 /** Allowed modes */
139 const regulator_mode_t *allowed_modes;
140 /** Number of allowed modes */
141 uint8_t allowed_modes_cnt;
142 /** Regulator initial mode */
143 regulator_mode_t initial_mode;
144 /** Flags (@reg REGULATOR_FLAGS). */
145 uint8_t flags;
146 };
147
148 /**
149 * @brief Initialize common driver config from devicetree.
150 *
151 * @param node_id Node identifier.
152 */
153 #define REGULATOR_DT_COMMON_CONFIG_INIT(node_id) \
154 { \
155 .min_uv = DT_PROP_OR(node_id, regulator_min_microvolt, \
156 INT32_MIN), \
157 .max_uv = DT_PROP_OR(node_id, regulator_max_microvolt, \
158 INT32_MAX), \
159 .init_uv = DT_PROP_OR(node_id, regulator_init_microvolt, \
160 INT32_MIN), \
161 .min_ua = DT_PROP_OR(node_id, regulator_min_microamp, \
162 INT32_MIN), \
163 .max_ua = DT_PROP_OR(node_id, regulator_max_microamp, \
164 INT32_MAX), \
165 .allowed_modes = (const regulator_mode_t []) \
166 DT_PROP_OR(node_id, regulator_allowed_modes, {}), \
167 .allowed_modes_cnt = \
168 DT_PROP_LEN_OR(node_id, regulator_allowed_modes, 0), \
169 .initial_mode = DT_PROP_OR(node_id, regulator_initial_mode, \
170 REGULATOR_INITIAL_MODE_UNKNOWN), \
171 .flags = ((DT_PROP_OR(node_id, regulator_always_on, 0U) * \
172 REGULATOR_ALWAYS_ON) | \
173 (DT_PROP_OR(node_id, regulator_boot_on, 0U) * \
174 REGULATOR_BOOT_ON)), \
175 }
176
177 /**
178 * @brief Initialize common driver config from devicetree instance.
179 *
180 * @param inst Instance.
181 */
182 #define REGULATOR_DT_INST_COMMON_CONFIG_INIT(inst) \
183 REGULATOR_DT_COMMON_CONFIG_INIT(DT_DRV_INST(inst))
184
185 /**
186 * @brief Common regulator data.
187 *
188 * This structure **must** be placed first in the driver's data structure.
189 */
190 struct regulator_common_data {
191 #if defined(CONFIG_REGULATOR_THREAD_SAFE_REFCNT) || defined(__DOXYGEN__)
192 /** Lock (only if @kconfig{CONFIG_REGULATOR_THREAD_SAFE_REFCNT}=y) */
193 struct k_mutex lock;
194 #endif
195 /** Reference count */
196 int refcnt;
197 };
198
199 /**
200 * @brief Initialize common regulator data.
201 *
202 * This function **must** be called when driver is initialized.
203 *
204 * @param dev Regulator device instance.
205 */
206 void regulator_common_data_init(const struct device *dev);
207
208 /**
209 * @brief Common function to initialize the regulator at init time.
210 *
211 * This function needs to be called after drivers initialize the regulator. It
212 * will:
213 *
214 * - Automatically enable the regulator if it is set to `regulator-boot-on`
215 * or `regulator-always-on` and increase its usage count.
216 * - Configure the regulator mode if `regulator-initial-mode` is set.
217 * - Ensure regulator voltage is set to a valid range.
218 *
219 * Regulators that are enabled by default in hardware, must set @p is_enabled to
220 * `true`.
221 *
222 * @param dev Regulator device instance
223 * @param is_enabled Indicate if the regulator is enabled by default in
224 * hardware.
225 *
226 * @retval 0 If enabled successfully.
227 * @retval -errno Negative errno in case of failure.
228 */
229 int regulator_common_init(const struct device *dev, bool is_enabled);
230
231 /**
232 * @brief Check if regulator is expected to be enabled at init time.
233 *
234 * @param dev Regulator device instance
235 * @return true If regulator needs to be enabled at init time.
236 * @return false If regulator does not need to be enabled at init time.
237 */
regulator_common_is_init_enabled(const struct device * dev)238 static inline bool regulator_common_is_init_enabled(const struct device *dev)
239 {
240 const struct regulator_common_config *config =
241 (const struct regulator_common_config *)dev->config;
242
243 return (config->flags & REGULATOR_INIT_ENABLED) != 0U;
244 }
245
246 /**
247 * @brief Get minimum supported voltage.
248 *
249 * @param dev Regulator device instance.
250 * @param min_uv Where minimum voltage will be stored, in microvolts.
251 *
252 * @retval 0 If successful
253 * @retval -ENOENT If minimum voltage is not specified.
254 */
regulator_common_get_min_voltage(const struct device * dev,int32_t * min_uv)255 static inline int regulator_common_get_min_voltage(const struct device *dev, int32_t *min_uv)
256 {
257 const struct regulator_common_config *config =
258 (const struct regulator_common_config *)dev->config;
259
260 if (config->min_uv == INT32_MIN) {
261 return -ENOENT;
262 }
263
264 *min_uv = config->min_uv;
265 return 0;
266 }
267
268 /** @endcond */
269
270 /**
271 * @brief Regulator Parent Interface
272 * @defgroup regulator_parent_interface Regulator Parent Interface
273 * @{
274 */
275
276 /**
277 * @brief Set a DVS state.
278 *
279 * Some PMICs feature DVS (Dynamic Voltage Scaling) by allowing to program the
280 * voltage level for multiple states. Such states may be automatically changed
281 * by hardware using GPIO pins. Certain MCUs even allow to automatically
282 * configure specific output pins when entering low-power modes so that PMIC
283 * state is changed without software intervention. This API can be used when
284 * state needs to be changed by software.
285 *
286 * @param dev Parent regulator device instance.
287 * @param state DVS state (vendor specific identifier).
288 *
289 * @retval 0 If successful.
290 * @retval -ENOTSUP If given state is not supported.
291 * @retval -EPERM If state can't be changed by software.
292 * @retval -ENOSYS If function is not implemented.
293 * @retval -errno In case of any other error.
294 */
regulator_parent_dvs_state_set(const struct device * dev,regulator_dvs_state_t state)295 static inline int regulator_parent_dvs_state_set(const struct device *dev,
296 regulator_dvs_state_t state)
297 {
298 const struct regulator_parent_driver_api *api =
299 (const struct regulator_parent_driver_api *)dev->api;
300
301 if (api->dvs_state_set == NULL) {
302 return -ENOSYS;
303 }
304
305 return api->dvs_state_set(dev, state);
306 }
307
308 /**
309 * @brief Enter ship mode.
310 *
311 * Some PMICs feature a ship mode, which allows the system to save power.
312 * Exit from low power is normally by pin transition.
313 *
314 * This API can be used when ship mode needs to be entered.
315 *
316 * @param dev Parent regulator device instance.
317 *
318 * @retval 0 If successful.
319 * @retval -ENOSYS If function is not implemented.
320 * @retval -errno In case of any other error.
321 */
regulator_parent_ship_mode(const struct device * dev)322 static inline int regulator_parent_ship_mode(const struct device *dev)
323 {
324 const struct regulator_parent_driver_api *api =
325 (const struct regulator_parent_driver_api *)dev->api;
326
327 if (api->ship_mode == NULL) {
328 return -ENOSYS;
329 }
330
331 return api->ship_mode(dev);
332 }
333
334 /** @} */
335
336 /**
337 * @brief Enable a regulator.
338 *
339 * Reference-counted request that a regulator be turned on. A regulator is
340 * considered "on" when it has reached a stable/usable state. Regulators that
341 * are always on, or configured in devicetree with `regulator-always-on` will
342 * always stay enabled, and so this function will always succeed.
343 *
344 * @param dev Regulator device instance
345 *
346 * @retval 0 If regulator has been successfully enabled.
347 * @retval -errno Negative errno in case of failure.
348 * @retval -ENOTSUP If regulator enablement can not be controlled.
349 */
350 int regulator_enable(const struct device *dev);
351
352 /**
353 * @brief Check if a regulator is enabled.
354 *
355 * @param dev Regulator device instance.
356 *
357 * @retval true If regulator is enabled.
358 * @retval false If regulator is disabled.
359 */
360 bool regulator_is_enabled(const struct device *dev);
361
362 /**
363 * @brief Disable a regulator.
364 *
365 * Release a regulator after a previous regulator_enable() completed
366 * successfully. Regulators that are always on, or configured in devicetree with
367 * `regulator-always-on` will always stay enabled, and so this function will
368 * always succeed.
369 *
370 * This must be invoked at most once for each successful regulator_enable().
371 *
372 * @param dev Regulator device instance.
373 *
374 * @retval 0 If regulator has been successfully disabled.
375 * @retval -errno Negative errno in case of failure.
376 * @retval -ENOTSUP If regulator disablement can not be controlled.
377 */
378 int regulator_disable(const struct device *dev);
379
380 /**
381 * @brief Obtain the number of supported voltage levels.
382 *
383 * Each voltage level supported by a regulator gets an index, starting from
384 * zero. The total number of supported voltage levels can be used together with
385 * regulator_list_voltage() to list all supported voltage levels.
386 *
387 * @param dev Regulator device instance.
388 *
389 * @return Number of supported voltages.
390 */
regulator_count_voltages(const struct device * dev)391 static inline unsigned int regulator_count_voltages(const struct device *dev)
392 {
393 const struct regulator_driver_api *api =
394 (const struct regulator_driver_api *)dev->api;
395
396 if (api->count_voltages == NULL) {
397 return 0U;
398 }
399
400 return api->count_voltages(dev);
401 }
402
403 /**
404 * @brief Obtain the value of a voltage given an index.
405 *
406 * Each voltage level supported by a regulator gets an index, starting from
407 * zero. Together with regulator_count_voltages(), this function can be used
408 * to iterate over all supported voltages.
409 *
410 * @param dev Regulator device instance.
411 * @param idx Voltage index.
412 * @param[out] volt_uv Where voltage for the given @p index will be stored, in
413 * microvolts.
414 *
415 * @retval 0 If @p index corresponds to a supported voltage.
416 * @retval -EINVAL If @p index does not correspond to a supported voltage.
417 */
regulator_list_voltage(const struct device * dev,unsigned int idx,int32_t * volt_uv)418 static inline int regulator_list_voltage(const struct device *dev,
419 unsigned int idx, int32_t *volt_uv)
420 {
421 const struct regulator_driver_api *api =
422 (const struct regulator_driver_api *)dev->api;
423
424 if (api->list_voltage == NULL) {
425 return -EINVAL;
426 }
427
428 return api->list_voltage(dev, idx, volt_uv);
429 }
430
431 /**
432 * @brief Check if a voltage within a window is supported.
433 *
434 * @param dev Regulator device instance.
435 * @param min_uv Minimum voltage in microvolts.
436 * @param max_uv maximum voltage in microvolts.
437 *
438 * @retval true If voltage is supported.
439 * @retval false If voltage is not supported.
440 */
441 bool regulator_is_supported_voltage(const struct device *dev, int32_t min_uv,
442 int32_t max_uv);
443
444 /**
445 * @brief Set the output voltage.
446 *
447 * The output voltage will be configured to the closest supported output
448 * voltage. regulator_get_voltage() can be used to obtain the actual configured
449 * voltage. The voltage will be applied to the active or selected mode. Output
450 * voltage may be limited using `regulator-min-microvolt` and/or
451 * `regulator-max-microvolt` in devicetree.
452 *
453 * @param dev Regulator device instance.
454 * @param min_uv Minimum acceptable voltage in microvolts.
455 * @param max_uv Maximum acceptable voltage in microvolts.
456 *
457 * @retval 0 If successful.
458 * @retval -EINVAL If the given voltage window is not valid.
459 * @retval -ENOSYS If function is not implemented.
460 * @retval -errno In case of any other error.
461 */
462 int regulator_set_voltage(const struct device *dev, int32_t min_uv,
463 int32_t max_uv);
464
465 /**
466 * @brief Obtain output voltage.
467 *
468 * @param dev Regulator device instance.
469 * @param[out] volt_uv Where configured output voltage will be stored.
470 *
471 * @retval 0 If successful
472 * @retval -ENOSYS If function is not implemented.
473 * @retval -errno In case of any other error.
474 */
regulator_get_voltage(const struct device * dev,int32_t * volt_uv)475 static inline int regulator_get_voltage(const struct device *dev,
476 int32_t *volt_uv)
477 {
478 const struct regulator_driver_api *api =
479 (const struct regulator_driver_api *)dev->api;
480
481 if (api->get_voltage == NULL) {
482 return -ENOSYS;
483 }
484
485 return api->get_voltage(dev, volt_uv);
486 }
487
488 /**
489 * @brief Set output current limit.
490 *
491 * The output current limit will be configured to the closest supported output
492 * current limit. regulator_get_current_limit() can be used to obtain the actual
493 * configured current limit. Current may be limited using `current-min-microamp`
494 * and/or `current-max-microamp` in Devicetree.
495 *
496 * @param dev Regulator device instance.
497 * @param min_ua Minimum acceptable current limit in microamps.
498 * @param max_ua Maximum acceptable current limit in microamps.
499 *
500 * @retval 0 If successful.
501 * @retval -EINVAL If the given current limit window is not valid.
502 * @retval -ENOSYS If function is not implemented.
503 * @retval -errno In case of any other error.
504 */
505 int regulator_set_current_limit(const struct device *dev, int32_t min_ua,
506 int32_t max_ua);
507
508 /**
509 * @brief Get output current limit.
510 *
511 * @param dev Regulator device instance.
512 * @param[out] curr_ua Where output current limit will be stored.
513 *
514 * @retval 0 If successful.
515 * @retval -ENOSYS If function is not implemented.
516 * @retval -errno In case of any other error.
517 */
regulator_get_current_limit(const struct device * dev,int32_t * curr_ua)518 static inline int regulator_get_current_limit(const struct device *dev,
519 int32_t *curr_ua)
520 {
521 const struct regulator_driver_api *api =
522 (const struct regulator_driver_api *)dev->api;
523
524 if (api->get_current_limit == NULL) {
525 return -ENOSYS;
526 }
527
528 return api->get_current_limit(dev, curr_ua);
529 }
530
531 /**
532 * @brief Set mode.
533 *
534 * Regulators can support multiple modes in order to permit different voltage
535 * configuration or better power savings. This API will apply a mode for
536 * the regulator. Allowed modes may be limited using `regulator-allowed-modes`
537 * devicetree property.
538 *
539 * @param dev Regulator device instance.
540 * @param mode Mode to select for this regulator.
541 *
542 * @retval 0 If successful.
543 * @retval -ENOTSUP If mode is not supported.
544 * @retval -ENOSYS If function is not implemented.
545 * @retval -errno In case of any other error.
546 */
547 int regulator_set_mode(const struct device *dev, regulator_mode_t mode);
548
549 /**
550 * @brief Get mode.
551 *
552 * @param dev Regulator device instance.
553 * @param[out] mode Where mode will be stored.
554 *
555 * @retval 0 If successful.
556 * @retval -ENOSYS If function is not implemented.
557 * @retval -errno In case of any other error.
558 */
regulator_get_mode(const struct device * dev,regulator_mode_t * mode)559 static inline int regulator_get_mode(const struct device *dev,
560 regulator_mode_t *mode)
561 {
562 const struct regulator_driver_api *api =
563 (const struct regulator_driver_api *)dev->api;
564
565 if (api->get_mode == NULL) {
566 return -ENOSYS;
567 }
568
569 return api->get_mode(dev, mode);
570 }
571
572 /**
573 * @brief Get active error flags.
574 *
575 * @param dev Regulator device instance.
576 * @param[out] flags Where error flags will be stored.
577 *
578 * @retval 0 If successful.
579 * @retval -ENOSYS If function is not implemented.
580 * @retval -errno In case of any other error.
581 */
regulator_get_error_flags(const struct device * dev,regulator_error_flags_t * flags)582 static inline int regulator_get_error_flags(const struct device *dev,
583 regulator_error_flags_t *flags)
584 {
585 const struct regulator_driver_api *api =
586 (const struct regulator_driver_api *)dev->api;
587
588 if (api->get_error_flags == NULL) {
589 return -ENOSYS;
590 }
591
592 return api->get_error_flags(dev, flags);
593 }
594
595 #ifdef __cplusplus
596 }
597 #endif
598
599 /** @} */
600
601 #endif /* ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_ */
602
