regulator.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019-2020 Peter Bigot Consulting, LLC
 * Copyright (c) 2021 NXP
 * Copyright (c) 2022 Nordic Semiconductor ASA
 * Copyright (c) 2023 EPAM Systems
 * Copyright (c) 2023 Meta Platforms
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_
#define ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_

 
#include <errno.h>
#include <stdint.h>
 
#include <zephyr/device.h>
#include <zephyr/devicetree.h>
#ifdef CONFIG_REGULATOR_THREAD_SAFE_REFCNT
#include <zephyr/kernel.h>
#endif
#include <zephyr/sys/util_macro.h>
 
#ifdef __cplusplus
extern "C" {
#endif

typedef uint8_t regulator_dvs_state_t;

typedef uint8_t regulator_mode_t;

typedef uint8_t regulator_error_flags_t;


#define REGULATOR_ERROR_OVER_VOLTAGE BIT(0)
#define REGULATOR_ERROR_OVER_CURRENT BIT(1)
#define REGULATOR_ERROR_OVER_TEMP    BIT(2)


enum regulator_event_type {
        REGULATOR_VOLTAGE_DETECTED,
        REGULATOR_VOLTAGE_REMOVED,
};

struct regulator_event {
        enum regulator_event_type type;
};

typedef void (*regulator_callback_t)(const struct device *dev,
                                     const struct regulator_event *const evt,
                                     const void *const user_data);

 
typedef int (*regulator_dvs_state_set_t)(const struct device *dev,
                                         regulator_dvs_state_t state);
 
typedef int (*regulator_ship_mode_t)(const struct device *dev);

__subsystem struct regulator_parent_driver_api {
        regulator_dvs_state_set_t dvs_state_set;
        regulator_ship_mode_t ship_mode;
};
 
typedef int (*regulator_enable_t)(const struct device *dev);
typedef int (*regulator_disable_t)(const struct device *dev);
typedef unsigned int (*regulator_count_voltages_t)(const struct device *dev);
typedef int (*regulator_list_voltage_t)(const struct device *dev,
                                        unsigned int idx, int32_t *volt_uv);
typedef int (*regulator_set_voltage_t)(const struct device *dev, int32_t min_uv,
                                       int32_t max_uv);
typedef int (*regulator_get_voltage_t)(const struct device *dev,
                                       int32_t *volt_uv);
typedef unsigned int (*regulator_count_current_limits_t)(const struct device *dev);
typedef int (*regulator_list_current_limit_t)(const struct device *dev,
                                              unsigned int idx, int32_t *current_ua);
typedef int (*regulator_set_current_limit_t)(const struct device *dev,
                                             int32_t min_ua, int32_t max_ua);
typedef int (*regulator_get_current_limit_t)(const struct device *dev,
                                             int32_t *curr_ua);
typedef int (*regulator_set_mode_t)(const struct device *dev,
                                    regulator_mode_t mode);
typedef int (*regulator_get_mode_t)(const struct device *dev,
                                    regulator_mode_t *mode);
typedef int (*regulator_set_active_discharge_t)(const struct device *dev,
                                    bool active_discharge);
typedef int (*regulator_get_active_discharge_t)(const struct device *dev,
                                    bool *active_discharge);
typedef int (*regulator_get_error_flags_t)(
        const struct device *dev, regulator_error_flags_t *flags);
typedef int (*regulator_set_callback_t)(const struct device *dev,
        regulator_callback_t cb, const void *const user_data);

__subsystem struct regulator_driver_api {
        regulator_enable_t enable;
        regulator_disable_t disable;
        regulator_count_voltages_t count_voltages;
        regulator_list_voltage_t list_voltage;
        regulator_set_voltage_t set_voltage;
        regulator_get_voltage_t get_voltage;
        regulator_count_current_limits_t count_current_limits;
        regulator_list_current_limit_t list_current_limit;
        regulator_set_current_limit_t set_current_limit;
        regulator_get_current_limit_t get_current_limit;
        regulator_set_mode_t set_mode;
        regulator_get_mode_t get_mode;
        regulator_set_active_discharge_t set_active_discharge;
        regulator_get_active_discharge_t get_active_discharge;
        regulator_get_error_flags_t get_error_flags;
        regulator_set_callback_t set_callback;
};

#define REGULATOR_ALWAYS_ON                BIT(0)
#define REGULATOR_BOOT_ON                  BIT(1)
#define REGULATOR_INIT_ENABLED             (REGULATOR_ALWAYS_ON | REGULATOR_BOOT_ON)
#define REGULATOR_ACTIVE_DISCHARGE_MASK    GENMASK(3, 2)
#define REGULATOR_ACTIVE_DISCHARGE_POS     2
#define REGULATOR_ACTIVE_DISCHARGE_DISABLE 0
#define REGULATOR_ACTIVE_DISCHARGE_ENABLE  1
#define REGULATOR_ACTIVE_DISCHARGE_DEFAULT 2
#define REGULATOR_ACTIVE_DISCHARGE_SET_BITS(x) \
        (((x) << REGULATOR_ACTIVE_DISCHARGE_POS) & REGULATOR_ACTIVE_DISCHARGE_MASK)
#define REGULATOR_ACTIVE_DISCHARGE_GET_BITS(x) \
        (((x) & REGULATOR_ACTIVE_DISCHARGE_MASK) >> REGULATOR_ACTIVE_DISCHARGE_POS)
#define REGULATOR_BOOT_OFF BIT(4)


#define REGULATOR_INITIAL_MODE_UNKNOWN UINT8_MAX

struct regulator_common_config {
        int32_t min_uv;
        int32_t max_uv;
        int32_t init_uv;
        int32_t min_ua;
        int32_t max_ua;
        int32_t init_ua;
        uint32_t startup_delay_us;
        uint32_t off_on_delay_us;
        const regulator_mode_t *allowed_modes;
        uint8_t allowed_modes_cnt;
        regulator_mode_t initial_mode;
        uint8_t flags;
};

#define REGULATOR_DT_COMMON_CONFIG_INIT(node_id)                               \
        {                                                                      \
                .min_uv = DT_PROP_OR(node_id, regulator_min_microvolt,         \
                                     INT32_MIN),                               \
                .max_uv = DT_PROP_OR(node_id, regulator_max_microvolt,         \
                                     INT32_MAX),                               \
                .init_uv = DT_PROP_OR(node_id, regulator_init_microvolt,       \
                                      INT32_MIN),                              \
                .min_ua = DT_PROP_OR(node_id, regulator_min_microamp,          \
                                     INT32_MIN),                               \
                .max_ua = DT_PROP_OR(node_id, regulator_max_microamp,          \
                                     INT32_MAX),                               \
                .init_ua = DT_PROP_OR(node_id, regulator_init_microamp,       \
                                      INT32_MIN),                              \
                .startup_delay_us = DT_PROP_OR(node_id, startup_delay_us, 0),  \
                .off_on_delay_us = DT_PROP_OR(node_id, off_on_delay_us, 0),    \
                .allowed_modes = (const regulator_mode_t [])                   \
                        DT_PROP_OR(node_id, regulator_allowed_modes, {}),      \
                .allowed_modes_cnt =                                           \
                        DT_PROP_LEN_OR(node_id, regulator_allowed_modes, 0),   \
                .initial_mode = DT_PROP_OR(node_id, regulator_initial_mode,    \
                                           REGULATOR_INITIAL_MODE_UNKNOWN),    \
                .flags = ((DT_PROP_OR(node_id, regulator_always_on, 0U) *      \
                           REGULATOR_ALWAYS_ON) |                              \
                          (DT_PROP_OR(node_id, regulator_boot_on, 0U) *        \
                           REGULATOR_BOOT_ON) |                                \
                          (REGULATOR_ACTIVE_DISCHARGE_SET_BITS(                \
                           DT_PROP_OR(node_id, regulator_active_discharge,     \
                           REGULATOR_ACTIVE_DISCHARGE_DEFAULT))) |             \
                          (DT_PROP_OR(node_id, regulator_boot_off, 0U) *       \
                           REGULATOR_BOOT_OFF)),                               \
        }

#define REGULATOR_DT_INST_COMMON_CONFIG_INIT(inst)                             \
        REGULATOR_DT_COMMON_CONFIG_INIT(DT_DRV_INST(inst))

struct regulator_common_data {
#if defined(CONFIG_REGULATOR_THREAD_SAFE_REFCNT) || defined(__DOXYGEN__)
        struct k_mutex lock;
#endif
        int refcnt;
};

void regulator_common_data_init(const struct device *dev);

int regulator_common_init(const struct device *dev, bool is_enabled);

static inline bool regulator_common_is_init_enabled(const struct device *dev)
{
        const struct regulator_common_config *config =
                (const struct regulator_common_config *)dev->config;
 
        return (config->flags & REGULATOR_INIT_ENABLED) != 0U;
}

static inline int regulator_common_get_min_voltage(const struct device *dev, int32_t *min_uv)
{
        const struct regulator_common_config *config =
                (const struct regulator_common_config *)dev->config;
 
        if (config->min_uv == INT32_MIN) {
                return -ENOENT;
        }
 
        *min_uv = config->min_uv;
        return 0;
}

static inline int regulator_common_get_max_voltage(const struct device *dev, int32_t *max_uv)
{
        const struct regulator_common_config *config =
                (const struct regulator_common_config *)dev->config;
 
        if (config->max_uv == INT32_MAX) {
                return -ENOENT;
        }
 
        *max_uv = config->max_uv;
        return 0;
}



static inline int regulator_parent_dvs_state_set(const struct device *dev,
                                                 regulator_dvs_state_t state)
{
        const struct regulator_parent_driver_api *api =
                (const struct regulator_parent_driver_api *)dev->api;
 
        if (api->dvs_state_set == NULL) {
                return -ENOSYS;
        }
 
        return api->dvs_state_set(dev, state);
}

static inline int regulator_parent_ship_mode(const struct device *dev)
{
        const struct regulator_parent_driver_api *api =
                (const struct regulator_parent_driver_api *)dev->api;
 
        if (api->ship_mode == NULL) {
                return -ENOSYS;
        }
 
        return api->ship_mode(dev);
}


int regulator_enable(const struct device *dev);

bool regulator_is_enabled(const struct device *dev);

int regulator_disable(const struct device *dev);

static inline unsigned int regulator_count_voltages(const struct device *dev)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->count_voltages == NULL) {
                return 0U;
        }
 
        return api->count_voltages(dev);
}

static inline int regulator_list_voltage(const struct device *dev,
                                         unsigned int idx, int32_t *volt_uv)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->list_voltage == NULL) {
                return -EINVAL;
        }
 
        return api->list_voltage(dev, idx, volt_uv);
}

bool regulator_is_supported_voltage(const struct device *dev, int32_t min_uv,
                                    int32_t max_uv);

int regulator_set_voltage(const struct device *dev, int32_t min_uv,
                          int32_t max_uv);

static inline int regulator_get_voltage(const struct device *dev,
                                        int32_t *volt_uv)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->get_voltage == NULL) {
                return -ENOSYS;
        }
 
        return api->get_voltage(dev, volt_uv);
}

static inline unsigned int regulator_count_current_limits(const struct device *dev)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->count_current_limits == NULL) {
                return 0U;
        }
 
        return api->count_current_limits(dev);
}

static inline int regulator_list_current_limit(const struct device *dev,
                                               unsigned int idx, int32_t *current_ua)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->list_current_limit == NULL) {
                return -EINVAL;
        }
 
        return api->list_current_limit(dev, idx, current_ua);
}

int regulator_set_current_limit(const struct device *dev, int32_t min_ua,
                                int32_t max_ua);

static inline int regulator_get_current_limit(const struct device *dev,
                                              int32_t *curr_ua)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->get_current_limit == NULL) {
                return -ENOSYS;
        }
 
        return api->get_current_limit(dev, curr_ua);
}

int regulator_set_mode(const struct device *dev, regulator_mode_t mode);

static inline int regulator_get_mode(const struct device *dev,
                                     regulator_mode_t *mode)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->get_mode == NULL) {
                return -ENOSYS;
        }
 
        return api->get_mode(dev, mode);
}

static inline int regulator_set_active_discharge(const struct device *dev,
                                     bool active_discharge)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->set_active_discharge == NULL) {
                return -ENOSYS;
        }
 
        return api->set_active_discharge(dev, active_discharge);
}

static inline int regulator_get_active_discharge(const struct device *dev,
                                     bool *active_discharge)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->get_active_discharge == NULL) {
                return -ENOSYS;
        }
 
        return api->get_active_discharge(dev, active_discharge);
}

static inline int regulator_get_error_flags(const struct device *dev,
                                            regulator_error_flags_t *flags)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->get_error_flags == NULL) {
                return -ENOSYS;
        }
 
        return api->get_error_flags(dev, flags);
}

static inline int regulator_set_callback(const struct device *dev,
                                         regulator_callback_t cb,
                                         const void *const user_data)
{
        const struct regulator_driver_api *api =
                (const struct regulator_driver_api *)dev->api;
 
        if (api->set_callback == NULL) {
                return -ENOSYS;
        }
 
        return api->set_callback(dev, cb, user_data);
}
 
#ifdef __cplusplus
}
#endif

 
#endif /* ZEPHYR_INCLUDE_DRIVERS_REGULATOR_H_ */