Zephyr API Documentation 4.0.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
325static inline int regulator_common_get_max_voltage(const struct device *dev, int32_t *max_uv)
326{
327 const struct regulator_common_config *config =
328 (const struct regulator_common_config *)dev->config;
329
330 if (config->max_uv == INT32_MAX) {
331 return -ENOENT;
332 }
333
334 *max_uv = config->max_uv;
335 return 0;
336}
337
365static inline int regulator_parent_dvs_state_set(const struct device *dev,
367{
368 const struct regulator_parent_driver_api *api =
369 (const struct regulator_parent_driver_api *)dev->api;
370
371 if (api->dvs_state_set == NULL) {
372 return -ENOSYS;
373 }
374
375 return api->dvs_state_set(dev, state);
376}
377
392static inline int regulator_parent_ship_mode(const struct device *dev)
393{
394 const struct regulator_parent_driver_api *api =
395 (const struct regulator_parent_driver_api *)dev->api;
396
397 if (api->ship_mode == NULL) {
398 return -ENOSYS;
399 }
400
401 return api->ship_mode(dev);
402}
403
420int regulator_enable(const struct device *dev);
421
430bool regulator_is_enabled(const struct device *dev);
431
448int regulator_disable(const struct device *dev);
449
461static inline unsigned int regulator_count_voltages(const struct device *dev)
462{
463 const struct regulator_driver_api *api =
464 (const struct regulator_driver_api *)dev->api;
465
466 if (api->count_voltages == NULL) {
467 return 0U;
468 }
469
470 return api->count_voltages(dev);
471}
472
488static inline int regulator_list_voltage(const struct device *dev,
489 unsigned int idx, int32_t *volt_uv)
490{
491 const struct regulator_driver_api *api =
492 (const struct regulator_driver_api *)dev->api;
493
494 if (api->list_voltage == NULL) {
495 return -EINVAL;
496 }
497
498 return api->list_voltage(dev, idx, volt_uv);
499}
500
511bool regulator_is_supported_voltage(const struct device *dev, int32_t min_uv,
512 int32_t max_uv);
513
532int regulator_set_voltage(const struct device *dev, int32_t min_uv,
533 int32_t max_uv);
534
545static inline int regulator_get_voltage(const struct device *dev,
546 int32_t *volt_uv)
547{
548 const struct regulator_driver_api *api =
549 (const struct regulator_driver_api *)dev->api;
550
551 if (api->get_voltage == NULL) {
552 return -ENOSYS;
553 }
554
555 return api->get_voltage(dev, volt_uv);
556}
557
569static inline unsigned int regulator_count_current_limits(const struct device *dev)
570{
571 const struct regulator_driver_api *api =
572 (const struct regulator_driver_api *)dev->api;
573
574 if (api->count_current_limits == NULL) {
575 return 0U;
576 }
577
578 return api->count_current_limits(dev);
579}
580
596static inline int regulator_list_current_limit(const struct device *dev,
597 unsigned int idx, int32_t *current_ua)
598{
599 const struct regulator_driver_api *api =
600 (const struct regulator_driver_api *)dev->api;
601
602 if (api->list_current_limit == NULL) {
603 return -EINVAL;
604 }
605
606 return api->list_current_limit(dev, idx, current_ua);
607}
608
626int regulator_set_current_limit(const struct device *dev, int32_t min_ua,
627 int32_t max_ua);
628
639static inline int regulator_get_current_limit(const struct device *dev,
640 int32_t *curr_ua)
641{
642 const struct regulator_driver_api *api =
643 (const struct regulator_driver_api *)dev->api;
644
645 if (api->get_current_limit == NULL) {
646 return -ENOSYS;
647 }
648
649 return api->get_current_limit(dev, curr_ua);
650}
651
668int regulator_set_mode(const struct device *dev, regulator_mode_t mode);
669
680static inline int regulator_get_mode(const struct device *dev,
681 regulator_mode_t *mode)
682{
683 const struct regulator_driver_api *api =
684 (const struct regulator_driver_api *)dev->api;
685
686 if (api->get_mode == NULL) {
687 return -ENOSYS;
688 }
689
690 return api->get_mode(dev, mode);
691}
692
703static inline int regulator_set_active_discharge(const struct device *dev,
704 bool active_discharge)
705{
706 const struct regulator_driver_api *api =
707 (const struct regulator_driver_api *)dev->api;
708
709 if (api->set_active_discharge == NULL) {
710 return -ENOSYS;
711 }
712
713 return api->set_active_discharge(dev, active_discharge);
714}
715
726static inline int regulator_get_active_discharge(const struct device *dev,
727 bool *active_discharge)
728{
729 const struct regulator_driver_api *api =
730 (const struct regulator_driver_api *)dev->api;
731
732 if (api->get_active_discharge == NULL) {
733 return -ENOSYS;
734 }
735
736 return api->get_active_discharge(dev, active_discharge);
737}
738
749static inline int regulator_get_error_flags(const struct device *dev,
751{
752 const struct regulator_driver_api *api =
753 (const struct regulator_driver_api *)dev->api;
754
755 if (api->get_error_flags == NULL) {
756 return -ENOSYS;
757 }
758
759 return api->get_error_flags(dev, flags);
760}
761
762#ifdef __cplusplus
763}
764#endif
765
768#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:569
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:726
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:488
static int regulator_get_current_limit(const struct device *dev, int32_t *curr_ua)
Get output current limit.
Definition regulator.h:639
static int regulator_set_active_discharge(const struct device *dev, bool active_discharge)
Set active discharge setting.
Definition regulator.h:703
static int regulator_get_error_flags(const struct device *dev, regulator_error_flags_t *flags)
Get active error flags.
Definition regulator.h:749
static unsigned int regulator_count_voltages(const struct device *dev)
Obtain the number of supported voltage levels.
Definition regulator.h:461
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:680
static int regulator_get_voltage(const struct device *dev, int32_t *volt_uv)
Obtain output voltage.
Definition regulator.h:545
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:596
static int regulator_parent_dvs_state_set(const struct device *dev, regulator_dvs_state_t state)
Set a DVS state.
Definition regulator.h:365
static int regulator_parent_ship_mode(const struct device *dev)
Enter ship mode.
Definition regulator.h:392
#define ENOENT
No such file or directory.
Definition errno.h:40
#define EINVAL
Invalid argument.
Definition errno.h:60
#define ENOSYS
Function not implemented.
Definition errno.h:82
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
#define INT32_MAX
Definition stdint.h:18
__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:412
const void * api
Address of the API structure exposed by the device instance.
Definition device.h:418
const void * config
Address of device instance config information.
Definition device.h:416
Mutex Structure.
Definition kernel.h:2994
Macro utilities.