Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
regulator.h
Go to the documentation of this file.
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 * Copyright (c) 2023 Meta Platforms
7 * SPDX-License-Identifier: Apache-2.0
8 */
9
10#ifndef ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_
11#define ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_
12
22#include <errno.h>
23#include <stdint.h>
24
25#include <zephyr/device.h>
26#include <zephyr/devicetree.h>
27#ifdef CONFIG_REGULATOR_THREAD_SAFE_REFCNT
28#include <zephyr/kernel.h>
29#endif
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
38
41
44
52#define REGULATOR_ERROR_OVER_VOLTAGE BIT(0)
54#define REGULATOR_ERROR_OVER_CURRENT BIT(1)
56#define REGULATOR_ERROR_OVER_TEMP BIT(2)
57
62typedef int (*regulator_dvs_state_set_t)(const struct device *dev,
64
65typedef int (*regulator_ship_mode_t)(const struct device *dev);
66
68__subsystem struct regulator_parent_driver_api {
69 regulator_dvs_state_set_t dvs_state_set;
70 regulator_ship_mode_t ship_mode;
71};
72
73typedef int (*regulator_enable_t)(const struct device *dev);
74typedef int (*regulator_disable_t)(const struct device *dev);
75typedef unsigned int (*regulator_count_voltages_t)(const struct device *dev);
76typedef int (*regulator_list_voltage_t)(const struct device *dev,
77 unsigned int idx, int32_t *volt_uv);
78typedef int (*regulator_set_voltage_t)(const struct device *dev, int32_t min_uv,
79 int32_t max_uv);
80typedef int (*regulator_get_voltage_t)(const struct device *dev,
81 int32_t *volt_uv);
82typedef unsigned int (*regulator_count_current_limits_t)(const struct device *dev);
83typedef int (*regulator_list_current_limit_t)(const struct device *dev,
84 unsigned int idx, int32_t *current_ua);
85typedef int (*regulator_set_current_limit_t)(const struct device *dev,
86 int32_t min_ua, int32_t max_ua);
87typedef int (*regulator_get_current_limit_t)(const struct device *dev,
88 int32_t *curr_ua);
89typedef int (*regulator_set_mode_t)(const struct device *dev,
90 regulator_mode_t mode);
91typedef int (*regulator_get_mode_t)(const struct device *dev,
92 regulator_mode_t *mode);
93typedef int (*regulator_set_active_discharge_t)(const struct device *dev,
94 bool active_discharge);
95typedef int (*regulator_get_active_discharge_t)(const struct device *dev,
96 bool *active_discharge);
97typedef int (*regulator_get_error_flags_t)(
98 const struct device *dev, regulator_error_flags_t *flags);
99
101__subsystem struct regulator_driver_api {
102 regulator_enable_t enable;
103 regulator_disable_t disable;
104 regulator_count_voltages_t count_voltages;
105 regulator_list_voltage_t list_voltage;
106 regulator_set_voltage_t set_voltage;
107 regulator_get_voltage_t get_voltage;
108 regulator_count_current_limits_t count_current_limits;
109 regulator_list_current_limit_t list_current_limit;
110 regulator_set_current_limit_t set_current_limit;
111 regulator_get_current_limit_t get_current_limit;
112 regulator_set_mode_t set_mode;
113 regulator_get_mode_t get_mode;
114 regulator_set_active_discharge_t set_active_discharge;
115 regulator_get_active_discharge_t get_active_discharge;
116 regulator_get_error_flags_t get_error_flags;
117};
118
125#define REGULATOR_ALWAYS_ON BIT(0)
127#define REGULATOR_BOOT_ON BIT(1)
129#define REGULATOR_INIT_ENABLED (REGULATOR_ALWAYS_ON | REGULATOR_BOOT_ON)
131#define REGULATOR_ACTIVE_DISCHARGE_MASK GENMASK(3, 2)
133#define REGULATOR_ACTIVE_DISCHARGE_POS 2
135#define REGULATOR_ACTIVE_DISCHARGE_DISABLE 0
137#define REGULATOR_ACTIVE_DISCHARGE_ENABLE 1
139#define REGULATOR_ACTIVE_DISCHARGE_DEFAULT 2
141#define REGULATOR_ACTIVE_DISCHARGE_SET_BITS(x) \
142 (((x) << REGULATOR_ACTIVE_DISCHARGE_POS) & REGULATOR_ACTIVE_DISCHARGE_MASK)
144#define REGULATOR_ACTIVE_DISCHARGE_GET_BITS(x) \
145 (((x) & REGULATOR_ACTIVE_DISCHARGE_MASK) >> REGULATOR_ACTIVE_DISCHARGE_POS)
147#define REGULATOR_BOOT_OFF BIT(4)
148
152#define REGULATOR_INITIAL_MODE_UNKNOWN UINT8_MAX
153
159struct regulator_common_config {
161 int32_t min_uv;
163 int32_t max_uv;
165 int32_t init_uv;
167 int32_t min_ua;
169 int32_t max_ua;
171 int32_t init_ua;
173 uint32_t startup_delay_us;
175 uint32_t off_on_delay_us;
177 const regulator_mode_t *allowed_modes;
179 uint8_t allowed_modes_cnt;
181 regulator_mode_t initial_mode;
184};
185
191#define REGULATOR_DT_COMMON_CONFIG_INIT(node_id) \
192 { \
193 .min_uv = DT_PROP_OR(node_id, regulator_min_microvolt, \
194 INT32_MIN), \
195 .max_uv = DT_PROP_OR(node_id, regulator_max_microvolt, \
196 INT32_MAX), \
197 .init_uv = DT_PROP_OR(node_id, regulator_init_microvolt, \
198 INT32_MIN), \
199 .min_ua = DT_PROP_OR(node_id, regulator_min_microamp, \
200 INT32_MIN), \
201 .max_ua = DT_PROP_OR(node_id, regulator_max_microamp, \
202 INT32_MAX), \
203 .init_ua = DT_PROP_OR(node_id, regulator_init_microamp, \
204 INT32_MIN), \
205 .startup_delay_us = DT_PROP_OR(node_id, startup_delay_us, 0), \
206 .off_on_delay_us = DT_PROP_OR(node_id, off_on_delay_us, 0), \
207 .allowed_modes = (const regulator_mode_t []) \
208 DT_PROP_OR(node_id, regulator_allowed_modes, {}), \
209 .allowed_modes_cnt = \
210 DT_PROP_LEN_OR(node_id, regulator_allowed_modes, 0), \
211 .initial_mode = DT_PROP_OR(node_id, regulator_initial_mode, \
212 REGULATOR_INITIAL_MODE_UNKNOWN), \
213 .flags = ((DT_PROP_OR(node_id, regulator_always_on, 0U) * \
214 REGULATOR_ALWAYS_ON) | \
215 (DT_PROP_OR(node_id, regulator_boot_on, 0U) * \
216 REGULATOR_BOOT_ON) | \
217 (REGULATOR_ACTIVE_DISCHARGE_SET_BITS( \
218 DT_PROP_OR(node_id, regulator_active_discharge, \
219 REGULATOR_ACTIVE_DISCHARGE_DEFAULT))) | \
220 (DT_PROP_OR(node_id, regulator_boot_off, 0U) * \
221 REGULATOR_BOOT_OFF)), \
222 }
223
229#define REGULATOR_DT_INST_COMMON_CONFIG_INIT(inst) \
230 REGULATOR_DT_COMMON_CONFIG_INIT(DT_DRV_INST(inst))
231
237struct regulator_common_data {
238#if defined(CONFIG_REGULATOR_THREAD_SAFE_REFCNT) || defined(__DOXYGEN__)
240 struct k_mutex lock;
241#endif
243 int refcnt;
244};
245
253void regulator_common_data_init(const struct device *dev);
254
277int regulator_common_init(const struct device *dev, bool is_enabled);
278
286static inline bool regulator_common_is_init_enabled(const struct device *dev)
287{
288 const struct regulator_common_config *config =
289 (const struct regulator_common_config *)dev->config;
290
291 return (config->flags & REGULATOR_INIT_ENABLED) != 0U;
292}
293
303static inline int regulator_common_get_min_voltage(const struct device *dev, int32_t *min_uv)
304{
305 const struct regulator_common_config *config =
306 (const struct regulator_common_config *)dev->config;
307
308 if (config->min_uv == INT32_MIN) {
309 return -ENOENT;
310 }
311
312 *min_uv = config->min_uv;
313 return 0;
314}
315
343static inline int regulator_parent_dvs_state_set(const struct device *dev,
345{
346 const struct regulator_parent_driver_api *api =
347 (const struct regulator_parent_driver_api *)dev->api;
348
349 if (api->dvs_state_set == NULL) {
350 return -ENOSYS;
351 }
352
353 return api->dvs_state_set(dev, state);
354}
355
370static inline int regulator_parent_ship_mode(const struct device *dev)
371{
372 const struct regulator_parent_driver_api *api =
373 (const struct regulator_parent_driver_api *)dev->api;
374
375 if (api->ship_mode == NULL) {
376 return -ENOSYS;
377 }
378
379 return api->ship_mode(dev);
380}
381
398int regulator_enable(const struct device *dev);
399
408bool regulator_is_enabled(const struct device *dev);
409
426int regulator_disable(const struct device *dev);
427
439static inline unsigned int regulator_count_voltages(const struct device *dev)
440{
441 const struct regulator_driver_api *api =
442 (const struct regulator_driver_api *)dev->api;
443
444 if (api->count_voltages == NULL) {
445 return 0U;
446 }
447
448 return api->count_voltages(dev);
449}
450
466static inline int regulator_list_voltage(const struct device *dev,
467 unsigned int idx, int32_t *volt_uv)
468{
469 const struct regulator_driver_api *api =
470 (const struct regulator_driver_api *)dev->api;
471
472 if (api->list_voltage == NULL) {
473 return -EINVAL;
474 }
475
476 return api->list_voltage(dev, idx, volt_uv);
477}
478
489bool regulator_is_supported_voltage(const struct device *dev, int32_t min_uv,
490 int32_t max_uv);
491
510int regulator_set_voltage(const struct device *dev, int32_t min_uv,
511 int32_t max_uv);
512
523static inline int regulator_get_voltage(const struct device *dev,
524 int32_t *volt_uv)
525{
526 const struct regulator_driver_api *api =
527 (const struct regulator_driver_api *)dev->api;
528
529 if (api->get_voltage == NULL) {
530 return -ENOSYS;
531 }
532
533 return api->get_voltage(dev, volt_uv);
534}
535
547static inline unsigned int regulator_count_current_limits(const struct device *dev)
548{
549 const struct regulator_driver_api *api =
550 (const struct regulator_driver_api *)dev->api;
551
552 if (api->count_current_limits == NULL) {
553 return 0U;
554 }
555
556 return api->count_current_limits(dev);
557}
558
574static inline int regulator_list_current_limit(const struct device *dev,
575 unsigned int idx, int32_t *current_ua)
576{
577 const struct regulator_driver_api *api =
578 (const struct regulator_driver_api *)dev->api;
579
580 if (api->list_current_limit == NULL) {
581 return -EINVAL;
582 }
583
584 return api->list_current_limit(dev, idx, current_ua);
585}
586
604int regulator_set_current_limit(const struct device *dev, int32_t min_ua,
605 int32_t max_ua);
606
617static inline int regulator_get_current_limit(const struct device *dev,
618 int32_t *curr_ua)
619{
620 const struct regulator_driver_api *api =
621 (const struct regulator_driver_api *)dev->api;
622
623 if (api->get_current_limit == NULL) {
624 return -ENOSYS;
625 }
626
627 return api->get_current_limit(dev, curr_ua);
628}
629
646int regulator_set_mode(const struct device *dev, regulator_mode_t mode);
647
658static inline int regulator_get_mode(const struct device *dev,
659 regulator_mode_t *mode)
660{
661 const struct regulator_driver_api *api =
662 (const struct regulator_driver_api *)dev->api;
663
664 if (api->get_mode == NULL) {
665 return -ENOSYS;
666 }
667
668 return api->get_mode(dev, mode);
669}
670
681static inline int regulator_set_active_discharge(const struct device *dev,
682 bool active_discharge)
683{
684 const struct regulator_driver_api *api =
685 (const struct regulator_driver_api *)dev->api;
686
687 if (api->set_active_discharge == NULL) {
688 return -ENOSYS;
689 }
690
691 return api->set_active_discharge(dev, active_discharge);
692}
693
704static inline int regulator_get_active_discharge(const struct device *dev,
705 bool *active_discharge)
706{
707 const struct regulator_driver_api *api =
708 (const struct regulator_driver_api *)dev->api;
709
710 if (api->get_active_discharge == NULL) {
711 return -ENOSYS;
712 }
713
714 return api->get_active_discharge(dev, active_discharge);
715}
716
727static inline int regulator_get_error_flags(const struct device *dev,
729{
730 const struct regulator_driver_api *api =
731 (const struct regulator_driver_api *)dev->api;
732
733 if (api->get_error_flags == NULL) {
734 return -ENOSYS;
735 }
736
737 return api->get_error_flags(dev, flags);
738}
739
740#ifdef __cplusplus
741}
742#endif
743
746#endif /* ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_ */
Devicetree main header.
System error numbers.
int regulator_enable(const struct device *dev)
Enable a regulator.
int regulator_set_mode(const struct device *dev, regulator_mode_t mode)
Set mode.
uint8_t regulator_mode_t
Opaque type to store regulator modes.
Definition: regulator.h:40
static unsigned int regulator_count_current_limits(const struct device *dev)
Obtain the number of supported current limit levels.
Definition: regulator.h:547
bool regulator_is_enabled(const struct device *dev)
Check if a regulator is enabled.
int regulator_set_voltage(const struct device *dev, int32_t min_uv, int32_t max_uv)
Set the output voltage.
int regulator_set_current_limit(const struct device *dev, int32_t min_ua, int32_t max_ua)
Set output current limit.
bool regulator_is_supported_voltage(const struct device *dev, int32_t min_uv, int32_t max_uv)
Check if a voltage within a window is supported.
uint8_t regulator_error_flags_t
Opaque bit map for regulator error flags (see REGULATOR_ERRORS)
Definition: regulator.h:43
static int regulator_get_active_discharge(const struct device *dev, bool *active_discharge)
Get active discharge setting.
Definition: regulator.h:704
static int regulator_list_voltage(const struct device *dev, unsigned int idx, int32_t *volt_uv)
Obtain the value of a voltage given an index.
Definition: regulator.h:466
static int regulator_get_current_limit(const struct device *dev, int32_t *curr_ua)
Get output current limit.
Definition: regulator.h:617
static int regulator_set_active_discharge(const struct device *dev, bool active_discharge)
Set active discharge setting.
Definition: regulator.h:681
static int regulator_get_error_flags(const struct device *dev, regulator_error_flags_t *flags)
Get active error flags.
Definition: regulator.h:727
static unsigned int regulator_count_voltages(const struct device *dev)
Obtain the number of supported voltage levels.
Definition: regulator.h:439
uint8_t regulator_dvs_state_t
Opaque type to store regulator DVS states.
Definition: regulator.h:37
static int regulator_get_mode(const struct device *dev, regulator_mode_t *mode)
Get mode.
Definition: regulator.h:658
static int regulator_get_voltage(const struct device *dev, int32_t *volt_uv)
Obtain output voltage.
Definition: regulator.h:523
int regulator_disable(const struct device *dev)
Disable a regulator.
static int regulator_list_current_limit(const struct device *dev, unsigned int idx, int32_t *current_ua)
Obtain the value of a current limit given an index.
Definition: regulator.h:574
static int regulator_parent_dvs_state_set(const struct device *dev, regulator_dvs_state_t state)
Set a DVS state.
Definition: regulator.h:343
static int regulator_parent_ship_mode(const struct device *dev)
Enter ship mode.
Definition: regulator.h:370
#define ENOENT
No such file or directory.
Definition: errno.h:41
#define EINVAL
Invalid argument.
Definition: errno.h:61
#define ENOSYS
Function not implemented.
Definition: errno.h:83
Public kernel APIs.
flags
Definition: parser.h:96
state
Definition: parser_state.h:29
__UINT32_TYPE__ uint32_t
Definition: stdint.h:90
__INT32_TYPE__ int32_t
Definition: stdint.h:74
__UINT8_TYPE__ uint8_t
Definition: stdint.h:88
#define INT32_MIN
Definition: stdint.h:24
Runtime device structure (in ROM) per driver instance.
Definition: device.h:403
const void * api
Address of the API structure exposed by the device instance.
Definition: device.h:409
const void * config
Address of device instance config information.
Definition: device.h:407
Mutex Structure.
Definition: kernel.h:2917
Macro utilities.