adc.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Nordic Semiconductor ASA
 * Copyright (c) 2015 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_DRIVERS_ADC_H_
#define ZEPHYR_INCLUDE_DRIVERS_ADC_H_
 
#include <zephyr/device.h>
#include <zephyr/dt-bindings/adc/adc.h>
#include <zephyr/kernel.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
enum adc_gain {
        ADC_GAIN_1_6, 
        ADC_GAIN_1_5, 
        ADC_GAIN_1_4, 
        ADC_GAIN_2_7, 
        ADC_GAIN_1_3, 
        ADC_GAIN_2_5, 
        ADC_GAIN_1_2, 
        ADC_GAIN_2_3, 
        ADC_GAIN_4_5, 
        ADC_GAIN_1,   
        ADC_GAIN_2,   
        ADC_GAIN_3,   
        ADC_GAIN_4,   
        ADC_GAIN_6,   
        ADC_GAIN_8,   
        ADC_GAIN_12,  
        ADC_GAIN_16,  
        ADC_GAIN_24,  
        ADC_GAIN_32,  
        ADC_GAIN_64,  
        ADC_GAIN_128, 
};
 
int adc_gain_invert(enum adc_gain gain, int32_t *value);
 
int adc_gain_invert_64(enum adc_gain gain, int64_t *value);
 
enum adc_reference {
        ADC_REF_VDD_1,     
        ADC_REF_VDD_1_2,   
        ADC_REF_VDD_1_3,   
        ADC_REF_VDD_1_4,   
        ADC_REF_INTERNAL,  
        ADC_REF_EXTERNAL0, 
        ADC_REF_EXTERNAL1, 
};
 
struct adc_channel_cfg {
        enum adc_gain gain;
 
        enum adc_reference reference;
 
        uint16_t acquisition_time;
 
        uint8_t channel_id   : 5;
 
        uint8_t differential : 1;
 
#ifdef CONFIG_ADC_CONFIGURABLE_INPUTS
        uint8_t input_positive;
 
        uint8_t input_negative;
#endif /* CONFIG_ADC_CONFIGURABLE_INPUTS */
 
#ifdef CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN
        uint8_t current_source_pin_set : 1;
        uint8_t current_source_pin[2];
#endif /* CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN */
 
#ifdef CONFIG_ADC_CONFIGURABLE_VBIAS_PIN
        uint32_t vbias_pins;
#endif /* CONFIG_ADC_CONFIGURABLE_VBIAS_PIN */
};
 
#define ADC_CHANNEL_CFG_DT(node_id) { \
        .gain             = DT_STRING_TOKEN(node_id, zephyr_gain), \
        .reference        = DT_STRING_TOKEN(node_id, zephyr_reference), \
        .acquisition_time = DT_PROP(node_id, zephyr_acquisition_time), \
        .channel_id       = DT_REG_ADDR(node_id), \
COND_CODE_1(UTIL_OR(DT_PROP(node_id, zephyr_differential), \
                   UTIL_AND(CONFIG_ADC_CONFIGURABLE_INPUTS, \
                            DT_NODE_HAS_PROP(node_id, zephyr_input_negative))), \
        (.differential    = true,), \
        (.differential    = false,)) \
IF_ENABLED(CONFIG_ADC_CONFIGURABLE_INPUTS, \
        (.input_positive  = DT_PROP_OR(node_id, zephyr_input_positive, 0), \
         .input_negative  = DT_PROP_OR(node_id, zephyr_input_negative, 0),)) \
IF_ENABLED(CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN, \
        (.current_source_pin_set = DT_NODE_HAS_PROP(node_id, zephyr_current_source_pin), \
         .current_source_pin = DT_PROP_OR(node_id, zephyr_current_source_pin, {0}),)) \
IF_ENABLED(CONFIG_ADC_CONFIGURABLE_VBIAS_PIN, \
        (.vbias_pins = DT_PROP_OR(node_id, zephyr_vbias_pins, 0),)) \
}
 
struct adc_dt_spec {
        const struct device *dev;
 
        uint8_t channel_id;
 
        bool channel_cfg_dt_node_exists;
 
        struct adc_channel_cfg channel_cfg;
 
        uint16_t vref_mv;
 
        uint8_t resolution;
 
        uint8_t oversampling;
};
 
#define ADC_DT_SPEC_STRUCT(ctlr, input) { \
                .dev = DEVICE_DT_GET(ctlr), \
                .channel_id = input, \
                ADC_CHANNEL_CFG_FROM_DT_NODE(\
                        ADC_CHANNEL_DT_NODE(ctlr, input)) \
        }
 
#define ADC_CHANNEL_DT_NODE(ctlr, input) \
        DT_FOREACH_CHILD_VARGS(ctlr, ADC_FOREACH_INPUT, input)
 
#define ADC_FOREACH_INPUT(node, input) \
        IF_ENABLED(IS_EQ(DT_REG_ADDR_RAW(node), input), (node))
 
#define ADC_CHANNEL_CFG_FROM_DT_NODE(node_id) \
        IF_ENABLED(DT_NODE_EXISTS(node_id), \
                (.channel_cfg_dt_node_exists = true, \
                 .channel_cfg  = ADC_CHANNEL_CFG_DT(node_id), \
                 .vref_mv      = DT_PROP_OR(node_id, zephyr_vref_mv, 0), \
                 .resolution   = DT_PROP_OR(node_id, zephyr_resolution, 0), \
                 .oversampling = DT_PROP_OR(node_id, zephyr_oversampling, 0),))
 
#define ADC_DT_SPEC_GET_BY_NAME(node_id, name) \
        ADC_DT_SPEC_STRUCT(DT_IO_CHANNELS_CTLR_BY_NAME(node_id, name), \
                           DT_IO_CHANNELS_INPUT_BY_NAME(node_id, name))
 
#define ADC_DT_SPEC_INST_GET_BY_NAME(inst, name) \
        ADC_DT_SPEC_GET_BY_NAME(DT_DRV_INST(inst), name)
 
#define ADC_DT_SPEC_GET_BY_IDX(node_id, idx) \
        ADC_DT_SPEC_STRUCT(DT_IO_CHANNELS_CTLR_BY_IDX(node_id, idx), \
                           DT_IO_CHANNELS_INPUT_BY_IDX(node_id, idx))
 
#define ADC_DT_SPEC_INST_GET_BY_IDX(inst, idx) \
        ADC_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), idx)
 
#define ADC_DT_SPEC_GET(node_id) ADC_DT_SPEC_GET_BY_IDX(node_id, 0)
 
#define ADC_DT_SPEC_INST_GET(inst) ADC_DT_SPEC_GET(DT_DRV_INST(inst))
 
/* Forward declaration of the adc_sequence structure. */
struct adc_sequence;
 
enum adc_action {
        ADC_ACTION_CONTINUE = 0,
 
        ADC_ACTION_REPEAT,
 
        ADC_ACTION_FINISH,
};
 
typedef enum adc_action (*adc_sequence_callback)(const struct device *dev,
                                                 const struct adc_sequence *sequence,
                                                 uint16_t sampling_index);
 
struct adc_sequence_options {
        uint32_t interval_us;
 
        adc_sequence_callback callback;
 
        void *user_data;
 
        uint16_t extra_samplings;
};
 
struct adc_sequence {
        const struct adc_sequence_options *options;
 
        uint32_t channels;
 
        void *buffer;
 
        size_t buffer_size;
 
        uint8_t resolution;
 
        uint8_t oversampling;
 
        bool calibrate;
};
 
 
typedef int (*adc_api_channel_setup)(const struct device *dev,
                                     const struct adc_channel_cfg *channel_cfg);
 
typedef int (*adc_api_read)(const struct device *dev,
                            const struct adc_sequence *sequence);
 
typedef int (*adc_api_read_async)(const struct device *dev,
                                  const struct adc_sequence *sequence,
                                  struct k_poll_signal *async);
 
__subsystem struct adc_driver_api {
        adc_api_channel_setup channel_setup;
        adc_api_read          read;
#ifdef CONFIG_ADC_ASYNC
        adc_api_read_async    read_async;
#endif
        uint16_t ref_internal;  /* mV */
};
 
__syscall int adc_channel_setup(const struct device *dev,
                                const struct adc_channel_cfg *channel_cfg);
 
static inline int z_impl_adc_channel_setup(const struct device *dev,
                                           const struct adc_channel_cfg *channel_cfg)
{
        return DEVICE_API_GET(adc, dev)->channel_setup(dev, channel_cfg);
}
 
static inline int adc_channel_setup_dt(const struct adc_dt_spec *spec)
{
        if (!spec->channel_cfg_dt_node_exists) {
                return -ENOTSUP;
        }
 
        return adc_channel_setup(spec->dev, &spec->channel_cfg);
}
 
__syscall int adc_read(const struct device *dev,
                       const struct adc_sequence *sequence);
 
static inline int z_impl_adc_read(const struct device *dev,
                                  const struct adc_sequence *sequence)
{
        return DEVICE_API_GET(adc, dev)->read(dev, sequence);
}
 
static inline int adc_read_dt(const struct adc_dt_spec *spec,
                              const struct adc_sequence *sequence)
{
        return adc_read(spec->dev, sequence);
}
 
__syscall int adc_read_async(const struct device *dev,
                             const struct adc_sequence *sequence,
                             struct k_poll_signal *async);
 
 
#ifdef CONFIG_ADC_ASYNC
static inline int z_impl_adc_read_async(const struct device *dev,
                                        const struct adc_sequence *sequence,
                                        struct k_poll_signal *async)
{
        return DEVICE_API_GET(adc, dev)->read_async(dev, sequence, async);
}
#endif /* CONFIG_ADC_ASYNC */
 
static inline uint16_t adc_ref_internal(const struct device *dev)
{
        return DEVICE_API_GET(adc, dev)->ref_internal;
}
 
typedef int (*adc_raw_to_x_fn)(int32_t ref_mv, enum adc_gain gain, uint8_t resolution,
                               int32_t *valp);
 
static inline int adc_raw_to_millivolts(int32_t ref_mv, enum adc_gain gain, uint8_t resolution,
                                        int32_t *valp)
{
        int32_t adc_mv = *valp * ref_mv;
        int ret = adc_gain_invert(gain, &adc_mv);
 
        if (ret == 0) {
                *valp = (adc_mv >> resolution);
        }
 
        return ret;
}
 
static inline int adc_raw_to_microvolts(int32_t ref_mv, enum adc_gain gain, uint8_t resolution,
                                        int32_t *valp)
{
        int64_t adc_uv = (int64_t)*valp * ref_mv * 1000;
        int ret = adc_gain_invert_64(gain, &adc_uv);
 
        if (ret == 0) {
                *valp = (int32_t)(adc_uv >> resolution);
        }
 
        return ret;
}
 
static inline int adc_raw_to_x_dt_chan(adc_raw_to_x_fn conv_func,
                                            const struct adc_dt_spec *spec,
                                            const struct adc_channel_cfg *channel_cfg,
                                            int32_t *valp)
{
        int32_t vref_mv;
        uint8_t resolution;
 
        if (!spec->channel_cfg_dt_node_exists) {
                return -ENOTSUP;
        }
 
        if (channel_cfg->reference == ADC_REF_INTERNAL) {
                vref_mv = (int32_t)adc_ref_internal(spec->dev);
        } else {
                vref_mv = spec->vref_mv;
        }
 
        resolution = spec->resolution;
 
        /*
         * For differential channels, one bit less needs to be specified
         * for resolution to achieve correct conversion.
         */
        if (channel_cfg->differential) {
                resolution -= 1U;
        }
 
        return conv_func(vref_mv, channel_cfg->gain, resolution, valp);
}
 
 
static inline int adc_raw_to_millivolts_dt(const struct adc_dt_spec *spec, int32_t *valp)
{
        return adc_raw_to_x_dt_chan(adc_raw_to_millivolts, spec, &spec->channel_cfg, valp);
}
 
static inline int adc_raw_to_microvolts_dt(const struct adc_dt_spec *spec, int32_t *valp)
{
        return adc_raw_to_x_dt_chan(adc_raw_to_microvolts, spec, &spec->channel_cfg, valp);
}
 
static inline int adc_sequence_init_dt(const struct adc_dt_spec *spec,
                                       struct adc_sequence *seq)
{
        if (!spec->channel_cfg_dt_node_exists) {
                return -ENOTSUP;
        }
 
        seq->channels = BIT(spec->channel_id);
        seq->resolution = spec->resolution;
        seq->oversampling = spec->oversampling;
 
        return 0;
}
 
static inline bool adc_is_ready_dt(const struct adc_dt_spec *spec)
{
        return device_is_ready(spec->dev);
}
 
#ifdef __cplusplus
}
#endif
 
#include <zephyr/syscalls/adc.h>
 
#endif  /* ZEPHYR_INCLUDE_DRIVERS_ADC_H_ */