Zephyr API Documentation 4.5.99
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
15
16#ifndef ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_
17#define ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_
18
33
34#include <errno.h>
35#include <stdint.h>
36
37#include <zephyr/device.h>
38#include <zephyr/devicetree.h>
39#ifdef CONFIG_REGULATOR_THREAD_SAFE_REFCNT
40#include <zephyr/kernel.h>
41#endif
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47
50
53
56
62
64#define REGULATOR_ERROR_OVER_VOLTAGE BIT(0)
66#define REGULATOR_ERROR_OVER_CURRENT BIT(1)
68#define REGULATOR_ERROR_OVER_TEMP BIT(2)
70#define REGULATOR_ERROR_UNDER_VOLTAGE BIT(3)
71
73
83
89
97typedef void (*regulator_callback_t)(const struct device *dev,
98 const struct regulator_event *const evt,
99 const void *const user_data);
100
105
110typedef int (*regulator_dvs_state_set_t)(const struct device *dev,
112
117typedef int (*regulator_ship_mode_t)(const struct device *dev);
118
128
133typedef int (*regulator_enable_t)(const struct device *dev);
134
139typedef int (*regulator_disable_t)(const struct device *dev);
140
145typedef unsigned int (*regulator_count_voltages_t)(const struct device *dev);
146
151typedef int (*regulator_list_voltage_t)(const struct device *dev,
152 unsigned int idx, int32_t *volt_uv);
153
158typedef int (*regulator_set_voltage_t)(const struct device *dev, int32_t min_uv,
159 int32_t max_uv);
160
165typedef int (*regulator_get_voltage_t)(const struct device *dev,
166 int32_t *volt_uv);
167
172typedef unsigned int (*regulator_count_current_limits_t)(const struct device *dev);
173
178typedef int (*regulator_list_current_limit_t)(const struct device *dev,
179 unsigned int idx, int32_t *current_ua);
180
185typedef int (*regulator_set_current_limit_t)(const struct device *dev,
186 int32_t min_ua, int32_t max_ua);
187
192typedef int (*regulator_get_current_limit_t)(const struct device *dev,
193 int32_t *curr_ua);
194
199typedef int (*regulator_set_mode_t)(const struct device *dev,
200 regulator_mode_t mode);
201
206typedef int (*regulator_get_mode_t)(const struct device *dev,
207 regulator_mode_t *mode);
208
213typedef int (*regulator_set_active_discharge_t)(const struct device *dev,
214 bool active_discharge);
215
220typedef int (*regulator_get_active_discharge_t)(const struct device *dev,
221 bool *active_discharge);
222
228 const struct device *dev, regulator_error_flags_t *flags);
229
234typedef int (*regulator_set_callback_t)(const struct device *dev,
235 regulator_callback_t cb, const void *const user_data);
236
274
276
278
285#define REGULATOR_ALWAYS_ON BIT(0)
287#define REGULATOR_BOOT_ON BIT(1)
289#define REGULATOR_INIT_ENABLED (REGULATOR_ALWAYS_ON | REGULATOR_BOOT_ON)
291#define REGULATOR_ACTIVE_DISCHARGE_MASK GENMASK(3, 2)
293#define REGULATOR_ACTIVE_DISCHARGE_POS 2
295#define REGULATOR_ACTIVE_DISCHARGE_DISABLE 0
297#define REGULATOR_ACTIVE_DISCHARGE_ENABLE 1
299#define REGULATOR_ACTIVE_DISCHARGE_DEFAULT 2
301#define REGULATOR_ACTIVE_DISCHARGE_SET_BITS(x) \
302 (((x) << REGULATOR_ACTIVE_DISCHARGE_POS) & REGULATOR_ACTIVE_DISCHARGE_MASK)
304#define REGULATOR_ACTIVE_DISCHARGE_GET_BITS(x) \
305 (((x) & REGULATOR_ACTIVE_DISCHARGE_MASK) >> REGULATOR_ACTIVE_DISCHARGE_POS)
307#define REGULATOR_BOOT_OFF BIT(4)
308
310
312#define REGULATOR_INITIAL_MODE_UNKNOWN UINT8_MAX
313
319struct regulator_common_config {
321 int32_t min_uv;
323 int32_t max_uv;
325 int32_t init_uv;
327 int32_t min_ua;
329 int32_t max_ua;
331 int32_t init_ua;
333 uint32_t startup_delay_us;
335 uint32_t off_on_delay_us;
337 const regulator_mode_t *allowed_modes;
339 uint8_t allowed_modes_cnt;
341 regulator_mode_t initial_mode;
344};
345
351#define REGULATOR_DT_COMMON_CONFIG_INIT(node_id) \
352 { \
353 .min_uv = DT_PROP_OR(node_id, regulator_min_microvolt, \
354 INT32_MIN), \
355 .max_uv = DT_PROP_OR(node_id, regulator_max_microvolt, \
356 INT32_MAX), \
357 .init_uv = DT_PROP_OR(node_id, regulator_init_microvolt, \
358 INT32_MIN), \
359 .min_ua = DT_PROP_OR(node_id, regulator_min_microamp, \
360 INT32_MIN), \
361 .max_ua = DT_PROP_OR(node_id, regulator_max_microamp, \
362 INT32_MAX), \
363 .init_ua = DT_PROP_OR(node_id, regulator_init_microamp, \
364 INT32_MIN), \
365 .startup_delay_us = DT_PROP_OR(node_id, startup_delay_us, 0), \
366 .off_on_delay_us = DT_PROP_OR(node_id, off_on_delay_us, 0), \
367 .allowed_modes = (const regulator_mode_t []) \
368 DT_PROP_OR(node_id, regulator_allowed_modes, {}), \
369 .allowed_modes_cnt = \
370 DT_PROP_LEN_OR(node_id, regulator_allowed_modes, 0), \
371 .initial_mode = DT_PROP_OR(node_id, regulator_initial_mode, \
372 REGULATOR_INITIAL_MODE_UNKNOWN), \
373 .flags = ((DT_PROP_OR(node_id, regulator_always_on, 0U) * \
374 REGULATOR_ALWAYS_ON) | \
375 (DT_PROP_OR(node_id, regulator_boot_on, 0U) * \
376 REGULATOR_BOOT_ON) | \
377 (REGULATOR_ACTIVE_DISCHARGE_SET_BITS( \
378 DT_PROP_OR(node_id, regulator_active_discharge, \
379 REGULATOR_ACTIVE_DISCHARGE_DEFAULT))) | \
380 (DT_PROP_OR(node_id, regulator_boot_off, 0U) * \
381 REGULATOR_BOOT_OFF)), \
382 }
383
389#define REGULATOR_DT_INST_COMMON_CONFIG_INIT(inst) \
390 REGULATOR_DT_COMMON_CONFIG_INIT(DT_DRV_INST(inst))
391
397struct regulator_common_data {
398#if defined(CONFIG_REGULATOR_THREAD_SAFE_REFCNT) || defined(__DOXYGEN__)
400 struct k_mutex lock;
401#endif
403 int refcnt;
404};
405
413void regulator_common_data_init(const struct device *dev);
414
436int regulator_common_init(const struct device *dev, bool is_enabled);
437
445static inline bool regulator_common_is_init_enabled(const struct device *dev)
446{
447 const struct regulator_common_config *config =
448 (const struct regulator_common_config *)dev->config;
449
450 return (config->flags & REGULATOR_INIT_ENABLED) != 0U;
451}
452
462static inline int regulator_common_get_min_voltage(const struct device *dev, int32_t *min_uv)
463{
464 const struct regulator_common_config *config =
465 (const struct regulator_common_config *)dev->config;
466
467 if (config->min_uv == INT32_MIN) {
468 return -ENOENT;
469 }
470
471 *min_uv = config->min_uv;
472 return 0;
473}
474
484static inline int regulator_common_get_max_voltage(const struct device *dev, int32_t *max_uv)
485{
486 const struct regulator_common_config *config =
487 (const struct regulator_common_config *)dev->config;
488
489 if (config->max_uv == INT32_MAX) {
490 return -ENOENT;
491 }
492
493 *max_uv = config->max_uv;
494 return 0;
495}
496
498
504
523static inline int regulator_parent_dvs_state_set(const struct device *dev,
525{
526 const struct regulator_parent_driver_api *api = DEVICE_API_GET(regulator_parent, dev);
527
528 if (api->dvs_state_set == NULL) {
529 return -ENOSYS;
530 }
531
532 return api->dvs_state_set(dev, state);
533}
534
548static inline int regulator_parent_ship_mode(const struct device *dev)
549{
550 const struct regulator_parent_driver_api *api = DEVICE_API_GET(regulator_parent, dev);
551
552 if (api->ship_mode == NULL) {
553 return -ENOSYS;
554 }
555
556 return api->ship_mode(dev);
557}
558
560
574int regulator_enable(const struct device *dev);
575
584bool regulator_is_enabled(const struct device *dev);
585
601int regulator_disable(const struct device *dev);
602
614static inline unsigned int regulator_count_voltages(const struct device *dev)
615{
616 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
617
618 if (api->count_voltages == NULL) {
619 return 0U;
620 }
621
622 return api->count_voltages(dev);
623}
624
640static inline int regulator_list_voltage(const struct device *dev,
641 unsigned int idx, int32_t *volt_uv)
642{
643 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
644
645 if (api->list_voltage == NULL) {
646 return -EINVAL;
647 }
648
649 return api->list_voltage(dev, idx, volt_uv);
650}
651
662bool regulator_is_supported_voltage(const struct device *dev, int32_t min_uv,
663 int32_t max_uv);
664
682int regulator_set_voltage(const struct device *dev, int32_t min_uv,
683 int32_t max_uv);
684
694static inline int regulator_get_voltage(const struct device *dev,
695 int32_t *volt_uv)
696{
697 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
698
699 if (api->get_voltage == NULL) {
700 return -ENOSYS;
701 }
702
703 return api->get_voltage(dev, volt_uv);
704}
705
717static inline unsigned int regulator_count_current_limits(const struct device *dev)
718{
719 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
720
721 if (api->count_current_limits == NULL) {
722 return 0U;
723 }
724
725 return api->count_current_limits(dev);
726}
727
743static inline int regulator_list_current_limit(const struct device *dev,
744 unsigned int idx, int32_t *current_ua)
745{
746 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
747
748 if (api->list_current_limit == NULL) {
749 return -EINVAL;
750 }
751
752 return api->list_current_limit(dev, idx, current_ua);
753}
754
771int regulator_set_current_limit(const struct device *dev, int32_t min_ua,
772 int32_t max_ua);
773
783static inline int regulator_get_current_limit(const struct device *dev,
784 int32_t *curr_ua)
785{
786 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
787
788 if (api->get_current_limit == NULL) {
789 return -ENOSYS;
790 }
791
792 return api->get_current_limit(dev, curr_ua);
793}
794
810int regulator_set_mode(const struct device *dev, regulator_mode_t mode);
811
821static inline int regulator_get_mode(const struct device *dev,
822 regulator_mode_t *mode)
823{
824 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
825
826 if (api->get_mode == NULL) {
827 return -ENOSYS;
828 }
829
830 return api->get_mode(dev, mode);
831}
832
842static inline int regulator_set_active_discharge(const struct device *dev,
843 bool active_discharge)
844{
845 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
846
847 if (api->set_active_discharge == NULL) {
848 return -ENOSYS;
849 }
850
851 return api->set_active_discharge(dev, active_discharge);
852}
853
863static inline int regulator_get_active_discharge(const struct device *dev,
864 bool *active_discharge)
865{
866 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
867
868 if (api->get_active_discharge == NULL) {
869 return -ENOSYS;
870 }
871
872 return api->get_active_discharge(dev, active_discharge);
873}
874
884static inline int regulator_get_error_flags(const struct device *dev,
886{
887 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
888
889 if (api->get_error_flags == NULL) {
890 return -ENOSYS;
891 }
892
893 return api->get_error_flags(dev, flags);
894}
895
910static inline int regulator_set_callback(const struct device *dev,
912 const void *const user_data)
913{
914 const struct regulator_driver_api *api = DEVICE_API_GET(regulator, dev);
915
916 if (api->set_callback == NULL) {
917 return -ENOSYS;
918 }
919
920 return api->set_callback(dev, cb, user_data);
921}
922
923#ifdef __cplusplus
924}
925#endif
926
928
929#endif /* ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_ */
APIs and macros for the Zephyr device model.
#define DEVICE_API_GET(_class, _dev)
Expands to the pointer of a device's API for a given class.
Definition device.h:1505
Devicetree main header.
System error numbers.
int(* regulator_get_active_discharge_t)(const struct device *dev, bool *active_discharge)
Get active discharge setting.
Definition regulator.h:220
int(* regulator_set_voltage_t)(const struct device *dev, int32_t min_uv, int32_t max_uv)
Set the output voltage.
Definition regulator.h:158
int(* regulator_list_current_limit_t)(const struct device *dev, unsigned int idx, int32_t *current_ua)
Obtain the value of a current limit given an index.
Definition regulator.h:178
int(* regulator_set_active_discharge_t)(const struct device *dev, bool active_discharge)
Set active discharge setting.
Definition regulator.h:213
int(* regulator_get_current_limit_t)(const struct device *dev, int32_t *curr_ua)
Get output current limit.
Definition regulator.h:192
int(* regulator_get_mode_t)(const struct device *dev, regulator_mode_t *mode)
Get mode.
Definition regulator.h:206
unsigned int(* regulator_count_current_limits_t)(const struct device *dev)
Obtain the number of supported current limit levels.
Definition regulator.h:172
int(* regulator_get_error_flags_t)(const struct device *dev, regulator_error_flags_t *flags)
Get active error flags.
Definition regulator.h:227
int(* regulator_set_mode_t)(const struct device *dev, regulator_mode_t mode)
Set mode.
Definition regulator.h:199
int(* regulator_get_voltage_t)(const struct device *dev, int32_t *volt_uv)
Obtain output voltage.
Definition regulator.h:165
int(* regulator_set_current_limit_t)(const struct device *dev, int32_t min_ua, int32_t max_ua)
Set output current limit.
Definition regulator.h:185
int(* regulator_ship_mode_t)(const struct device *dev)
Enter ship mode.
Definition regulator.h:117
int(* regulator_dvs_state_set_t)(const struct device *dev, regulator_dvs_state_t state)
Set a DVS state.
Definition regulator.h:110
int(* regulator_disable_t)(const struct device *dev)
Disable a regulator.
Definition regulator.h:139
int(* regulator_enable_t)(const struct device *dev)
Enable a regulator.
Definition regulator.h:133
unsigned int(* regulator_count_voltages_t)(const struct device *dev)
Obtain the number of supported voltage levels.
Definition regulator.h:145
int(* regulator_set_callback_t)(const struct device *dev, regulator_callback_t cb, const void *const user_data)
Set event handler function.
Definition regulator.h:234
int(* regulator_list_voltage_t)(const struct device *dev, unsigned int idx, int32_t *volt_uv)
Obtain the value of a voltage given an index.
Definition regulator.h:151
void(* regulator_callback_t)(const struct device *dev, const struct regulator_event *const evt, const void *const user_data)
Regulator callback function signature.
Definition regulator.h:97
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:52
static unsigned int regulator_count_current_limits(const struct device *dev)
Obtain the number of supported current limit levels.
Definition regulator.h:717
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:55
static int regulator_get_active_discharge(const struct device *dev, bool *active_discharge)
Get active discharge setting.
Definition regulator.h:863
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:640
static int regulator_get_current_limit(const struct device *dev, int32_t *curr_ua)
Get output current limit.
Definition regulator.h:783
static int regulator_set_active_discharge(const struct device *dev, bool active_discharge)
Set active discharge setting.
Definition regulator.h:842
static int regulator_get_error_flags(const struct device *dev, regulator_error_flags_t *flags)
Get active error flags.
Definition regulator.h:884
static unsigned int regulator_count_voltages(const struct device *dev)
Obtain the number of supported voltage levels.
Definition regulator.h:614
uint8_t regulator_dvs_state_t
Opaque type to store regulator DVS states.
Definition regulator.h:49
static int regulator_get_mode(const struct device *dev, regulator_mode_t *mode)
Get mode.
Definition regulator.h:821
static int regulator_get_voltage(const struct device *dev, int32_t *volt_uv)
Obtain output voltage.
Definition regulator.h:694
int regulator_disable(const struct device *dev)
Disable a regulator.
regulator_event_type
Regulator event types.
Definition regulator.h:77
static int regulator_set_callback(const struct device *dev, regulator_callback_t cb, const void *const user_data)
Set event handler function.
Definition regulator.h:910
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:743
@ REGULATOR_VOLTAGE_DETECTED
Regulator voltage is detected.
Definition regulator.h:79
@ REGULATOR_VOLTAGE_REMOVED
Regulator voltage is removed.
Definition regulator.h:81
static int regulator_parent_dvs_state_set(const struct device *dev, regulator_dvs_state_t state)
Set a DVS state.
Definition regulator.h:523
static int regulator_parent_ship_mode(const struct device *dev)
Enter ship mode.
Definition regulator.h:548
#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:86
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:543
const void * config
Address of device instance config information.
Definition device.h:547
<span class="mlabel">Driver Operations</span> Regulator driver operations
Definition regulator.h:240
regulator_set_current_limit_t set_current_limit
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:258
regulator_list_current_limit_t list_current_limit
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:256
regulator_enable_t enable
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:242
regulator_set_voltage_t set_voltage
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:250
regulator_count_voltages_t count_voltages
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:246
regulator_get_error_flags_t get_error_flags
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:270
regulator_list_voltage_t list_voltage
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:248
regulator_set_active_discharge_t set_active_discharge
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:266
regulator_get_mode_t get_mode
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:264
regulator_set_callback_t set_callback
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:272
regulator_set_mode_t set_mode
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:262
regulator_get_active_discharge_t get_active_discharge
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:268
regulator_get_voltage_t get_voltage
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:252
regulator_disable_t disable
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:244
regulator_get_current_limit_t get_current_limit
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:260
regulator_count_current_limits_t count_current_limits
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:254
Regulator event structure.
Definition regulator.h:85
enum regulator_event_type type
Event type.
Definition regulator.h:87
<span class="mlabel">Driver Operations</span> Regulator Parent driver operations
Definition regulator.h:122
regulator_dvs_state_set_t dvs_state_set
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:124
regulator_ship_mode_t ship_mode
<span class="op-badge op-opt" title="This operation MAY optionally be implemented by the driver....
Definition regulator.h:126
Macro utilities.