Zephyr API Documentation 4.2.99
A Scalable Open Source RTOS
 4.2.99
adc.h
Go to the documentation of this file.
1
5
6/*
7 * Copyright (c) 2018 Nordic Semiconductor ASA
8 * Copyright (c) 2015 Intel Corporation
9 *
10 * SPDX-License-Identifier: Apache-2.0
11 */
12
13#ifndef ZEPHYR_INCLUDE_DRIVERS_ADC_H_
14#define ZEPHYR_INCLUDE_DRIVERS_ADC_H_
15
16#include <zephyr/device.h>
18#include <zephyr/kernel.h>
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
32
57
74int adc_gain_invert(enum adc_gain gain, int32_t *value);
75
92int adc_gain_invert_64(enum adc_gain gain, int64_t *value);
93
104
111
114
125
149
152
153#ifdef CONFIG_ADC_CONFIGURABLE_INPUTS
159 uint8_t input_positive;
160
166 uint8_t input_negative;
167#endif /* CONFIG_ADC_CONFIGURABLE_INPUTS */
168
169#ifdef CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN
170 uint8_t current_source_pin_set : 1;
177 uint8_t current_source_pin[2];
178#endif /* CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN */
179
180#ifdef CONFIG_ADC_CONFIGURABLE_VBIAS_PIN
189 uint32_t vbias_pins;
190#endif /* CONFIG_ADC_CONFIGURABLE_VBIAS_PIN */
191};
192
257#define ADC_CHANNEL_CFG_DT(node_id) { \
258 .gain = DT_STRING_TOKEN(node_id, zephyr_gain), \
259 .reference = DT_STRING_TOKEN(node_id, zephyr_reference), \
260 .acquisition_time = DT_PROP(node_id, zephyr_acquisition_time), \
261 .channel_id = DT_REG_ADDR(node_id), \
262COND_CODE_1(UTIL_OR(DT_PROP(node_id, zephyr_differential), \
263 UTIL_AND(CONFIG_ADC_CONFIGURABLE_INPUTS, \
264 DT_NODE_HAS_PROP(node_id, zephyr_input_negative))), \
265 (.differential = true,), \
266 (.differential = false,)) \
267IF_ENABLED(CONFIG_ADC_CONFIGURABLE_INPUTS, \
268 (.input_positive = DT_PROP_OR(node_id, zephyr_input_positive, 0), \
269 .input_negative = DT_PROP_OR(node_id, zephyr_input_negative, 0),)) \
270IF_ENABLED(CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN, \
271 (.current_source_pin_set = DT_NODE_HAS_PROP(node_id, zephyr_current_source_pin), \
272 .current_source_pin = DT_PROP_OR(node_id, zephyr_current_source_pin, {0}),)) \
273IF_ENABLED(CONFIG_ADC_CONFIGURABLE_VBIAS_PIN, \
274 (.vbias_pins = DT_PROP_OR(node_id, zephyr_vbias_pins, 0),)) \
275}
276
329
331
332#define ADC_DT_SPEC_STRUCT(ctlr, input) { \
333 .dev = DEVICE_DT_GET(ctlr), \
334 .channel_id = input, \
335 ADC_CHANNEL_CFG_FROM_DT_NODE(\
336 ADC_CHANNEL_DT_NODE(ctlr, input)) \
337 }
338
339#define ADC_CHANNEL_DT_NODE(ctlr, input) \
340 DT_FOREACH_CHILD_VARGS(ctlr, ADC_FOREACH_INPUT, input)
341
342#define ADC_FOREACH_INPUT(node, input) \
343 IF_ENABLED(IS_EQ(DT_REG_ADDR_RAW(node), input), (node))
344
345#define ADC_CHANNEL_CFG_FROM_DT_NODE(node_id) \
346 IF_ENABLED(DT_NODE_EXISTS(node_id), \
347 (.channel_cfg_dt_node_exists = true, \
348 .channel_cfg = ADC_CHANNEL_CFG_DT(node_id), \
349 .vref_mv = DT_PROP_OR(node_id, zephyr_vref_mv, 0), \
350 .resolution = DT_PROP_OR(node_id, zephyr_resolution, 0), \
351 .oversampling = DT_PROP_OR(node_id, zephyr_oversampling, 0),))
352
354
423#define ADC_DT_SPEC_GET_BY_NAME(node_id, name) \
424 ADC_DT_SPEC_STRUCT(DT_IO_CHANNELS_CTLR_BY_NAME(node_id, name), \
425 DT_IO_CHANNELS_INPUT_BY_NAME(node_id, name))
426
437#define ADC_DT_SPEC_INST_GET_BY_NAME(inst, name) \
438 ADC_DT_SPEC_GET_BY_NAME(DT_DRV_INST(inst), name)
439
509#define ADC_DT_SPEC_GET_BY_IDX(node_id, idx) \
510 ADC_DT_SPEC_STRUCT(DT_IO_CHANNELS_CTLR_BY_IDX(node_id, idx), \
511 DT_IO_CHANNELS_INPUT_BY_IDX(node_id, idx))
512
523#define ADC_DT_SPEC_INST_GET_BY_IDX(inst, idx) \
524 ADC_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), idx)
525
535#define ADC_DT_SPEC_GET(node_id) ADC_DT_SPEC_GET_BY_IDX(node_id, 0)
536
545#define ADC_DT_SPEC_INST_GET(inst) ADC_DT_SPEC_GET(DT_DRV_INST(inst))
546
547/* Forward declaration of the adc_sequence structure. */
548struct adc_sequence;
549
566
586typedef enum adc_action (*adc_sequence_callback)(const struct device *dev,
587 const struct adc_sequence *sequence,
588 uint16_t sampling_index);
589
623
691
692
697typedef int (*adc_api_channel_setup)(const struct device *dev,
698 const struct adc_channel_cfg *channel_cfg);
699
704typedef int (*adc_api_read)(const struct device *dev,
705 const struct adc_sequence *sequence);
706
712typedef int (*adc_api_read_async)(const struct device *dev,
713 const struct adc_sequence *sequence,
714 struct k_poll_signal *async);
715
721__subsystem struct adc_driver_api {
724#ifdef CONFIG_ADC_ASYNC
725 adc_api_read_async read_async;
726#endif
728};
729
742__syscall int adc_channel_setup(const struct device *dev,
743 const struct adc_channel_cfg *channel_cfg);
744
745static inline int z_impl_adc_channel_setup(const struct device *dev,
746 const struct adc_channel_cfg *channel_cfg)
747{
748 return DEVICE_API_GET(adc, dev)->channel_setup(dev, channel_cfg);
749}
750
760static inline int adc_channel_setup_dt(const struct adc_dt_spec *spec)
761{
762 if (!spec->channel_cfg_dt_node_exists) {
763 return -ENOTSUP;
764 }
765
766 return adc_channel_setup(spec->dev, &spec->channel_cfg);
767}
768
790__syscall int adc_read(const struct device *dev,
791 const struct adc_sequence *sequence);
792
793static inline int z_impl_adc_read(const struct device *dev,
794 const struct adc_sequence *sequence)
795{
796 return DEVICE_API_GET(adc, dev)->read(dev, sequence);
797}
798
808static inline int adc_read_dt(const struct adc_dt_spec *spec,
809 const struct adc_sequence *sequence)
810{
811 return adc_read(spec->dev, sequence);
812}
813
834__syscall int adc_read_async(const struct device *dev,
835 const struct adc_sequence *sequence,
836 struct k_poll_signal *async);
837
838
839#ifdef CONFIG_ADC_ASYNC
840static inline int z_impl_adc_read_async(const struct device *dev,
841 const struct adc_sequence *sequence,
842 struct k_poll_signal *async)
843{
844 return DEVICE_API_GET(adc, dev)->read_async(dev, sequence, async);
845}
846#endif /* CONFIG_ADC_ASYNC */
847
857static inline uint16_t adc_ref_internal(const struct device *dev)
858{
859 return DEVICE_API_GET(adc, dev)->ref_internal;
860}
861
885typedef int (*adc_raw_to_x_fn)(int32_t ref_mv, enum adc_gain gain, uint8_t resolution,
886 int32_t *valp);
887
893static inline int adc_raw_to_millivolts(int32_t ref_mv, enum adc_gain gain, uint8_t resolution,
894 int32_t *valp)
895{
896 int32_t adc_mv = *valp * ref_mv;
897 int ret = adc_gain_invert(gain, &adc_mv);
898
899 if (ret == 0) {
900 *valp = (adc_mv >> resolution);
901 }
902
903 return ret;
904}
905
911static inline int adc_raw_to_microvolts(int32_t ref_mv, enum adc_gain gain, uint8_t resolution,
912 int32_t *valp)
913{
914 int64_t adc_uv = (int64_t)*valp * ref_mv * 1000;
915 int ret = adc_gain_invert_64(gain, &adc_uv);
916
917 if (ret == 0) {
918 *valp = (int32_t)(adc_uv >> resolution);
919 }
920
921 return ret;
922}
923
940static inline int adc_raw_to_x_dt_chan(adc_raw_to_x_fn conv_func,
941 const struct adc_dt_spec *spec,
942 const struct adc_channel_cfg *channel_cfg,
943 int32_t *valp)
944{
945 int32_t vref_mv;
946 uint8_t resolution;
947
948 if (!spec->channel_cfg_dt_node_exists) {
949 return -ENOTSUP;
950 }
951
952 if (channel_cfg->reference == ADC_REF_INTERNAL) {
953 vref_mv = (int32_t)adc_ref_internal(spec->dev);
954 } else {
955 vref_mv = spec->vref_mv;
956 }
957
958 resolution = spec->resolution;
959
960 /*
961 * For differential channels, one bit less needs to be specified
962 * for resolution to achieve correct conversion.
963 */
964 if (channel_cfg->differential) {
965 resolution -= 1U;
966 }
967
968 return conv_func(vref_mv, channel_cfg->gain, resolution, valp);
969}
970
971
985static inline int adc_raw_to_millivolts_dt(const struct adc_dt_spec *spec, int32_t *valp)
986{
987 return adc_raw_to_x_dt_chan(adc_raw_to_millivolts, spec, &spec->channel_cfg, valp);
988}
989
1003static inline int adc_raw_to_microvolts_dt(const struct adc_dt_spec *spec, int32_t *valp)
1004{
1005 return adc_raw_to_x_dt_chan(adc_raw_to_microvolts, spec, &spec->channel_cfg, valp);
1006}
1007
1026static inline int adc_sequence_init_dt(const struct adc_dt_spec *spec,
1027 struct adc_sequence *seq)
1028{
1029 if (!spec->channel_cfg_dt_node_exists) {
1030 return -ENOTSUP;
1031 }
1032
1033 seq->channels = BIT(spec->channel_id);
1034 seq->resolution = spec->resolution;
1035 seq->oversampling = spec->oversampling;
1036
1037 return 0;
1038}
1039
1047static inline bool adc_is_ready_dt(const struct adc_dt_spec *spec)
1048{
1049 return device_is_ready(spec->dev);
1050}
1051
1055
1056#ifdef __cplusplus
1057}
1058#endif
1059
1060#include <zephyr/syscalls/adc.h>
1061
1062#endif /* ZEPHYR_INCLUDE_DRIVERS_ADC_H_ */
#define DEVICE_API_GET(_class, _dev)
Expands to the pointer of a device's API for a given class.
Definition device.h:1350
int adc_read_async(const struct device *dev, const struct adc_sequence *sequence, struct k_poll_signal *async)
Set an asynchronous read request.
static int adc_raw_to_millivolts_dt(const struct adc_dt_spec *spec, int32_t *valp)
Convert a raw ADC value to millivolts using information stored in a struct adc_dt_spec.
Definition adc.h:985
static 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)
Convert a raw ADC value to an arbitrary output unit.
Definition adc.h:940
int adc_gain_invert_64(enum adc_gain gain, int64_t *value)
Invert the application of gain to a measurement value.
static int adc_read_dt(const struct adc_dt_spec *spec, const struct adc_sequence *sequence)
Set a read request from a struct adc_dt_spec.
Definition adc.h:808
adc_gain
ADC channel gain factors.
Definition adc.h:34
static bool adc_is_ready_dt(const struct adc_dt_spec *spec)
Validate that the ADC device is ready.
Definition adc.h:1047
int(* adc_raw_to_x_fn)(int32_t ref_mv, enum adc_gain gain, uint8_t resolution, int32_t *valp)
Conversion from raw ADC units to a specific output unit.
Definition adc.h:885
static int adc_raw_to_microvolts(int32_t ref_mv, enum adc_gain gain, uint8_t resolution, int32_t *valp)
Convert a raw ADC value to microvolts.
Definition adc.h:911
static int adc_raw_to_microvolts_dt(const struct adc_dt_spec *spec, int32_t *valp)
Convert a raw ADC value to microvolts using information stored in a struct adc_dt_spec.
Definition adc.h:1003
int(* adc_api_read)(const struct device *dev, const struct adc_sequence *sequence)
Type definition of ADC API function for setting a read request.
Definition adc.h:704
static int adc_sequence_init_dt(const struct adc_dt_spec *spec, struct adc_sequence *seq)
Initialize a struct adc_sequence from information stored in struct adc_dt_spec.
Definition adc.h:1026
int adc_gain_invert(enum adc_gain gain, int32_t *value)
Invert the application of gain to a measurement value.
int adc_read(const struct device *dev, const struct adc_sequence *sequence)
Set a read request.
int adc_channel_setup(const struct device *dev, const struct adc_channel_cfg *channel_cfg)
Configure an ADC channel.
int(* adc_api_channel_setup)(const struct device *dev, const struct adc_channel_cfg *channel_cfg)
Type definition of ADC API function for configuring a channel.
Definition adc.h:697
adc_action
Action to be performed after a sampling is done.
Definition adc.h:553
enum adc_action(* adc_sequence_callback)(const struct device *dev, const struct adc_sequence *sequence, uint16_t sampling_index)
Type definition of the optional callback function to be called after a requested sampling is done.
Definition adc.h:586
adc_reference
ADC references.
Definition adc.h:95
int(* adc_api_read_async)(const struct device *dev, const struct adc_sequence *sequence, struct k_poll_signal *async)
Type definition of ADC API function for setting an asynchronous read request.
Definition adc.h:712
static uint16_t adc_ref_internal(const struct device *dev)
Get the internal reference voltage.
Definition adc.h:857
static int adc_channel_setup_dt(const struct adc_dt_spec *spec)
Configure an ADC channel from a struct adc_dt_spec.
Definition adc.h:760
static int adc_raw_to_millivolts(int32_t ref_mv, enum adc_gain gain, uint8_t resolution, int32_t *valp)
Convert a raw ADC value to millivolts.
Definition adc.h:893
@ ADC_GAIN_64
x 64.
Definition adc.h:54
@ ADC_GAIN_3
x 3.
Definition adc.h:46
@ ADC_GAIN_4
x 4.
Definition adc.h:47
@ ADC_GAIN_1_5
x 1/5.
Definition adc.h:36
@ ADC_GAIN_128
x 128.
Definition adc.h:55
@ ADC_GAIN_1_2
x 1/2.
Definition adc.h:41
@ ADC_GAIN_2_7
x 2/7.
Definition adc.h:38
@ ADC_GAIN_12
x 12.
Definition adc.h:50
@ ADC_GAIN_2_5
x 2/5.
Definition adc.h:40
@ ADC_GAIN_16
x 16.
Definition adc.h:51
@ ADC_GAIN_24
x 24.
Definition adc.h:52
@ ADC_GAIN_1
x 1.
Definition adc.h:44
@ ADC_GAIN_6
x 6.
Definition adc.h:48
@ ADC_GAIN_1_6
x 1/6.
Definition adc.h:35
@ ADC_GAIN_32
x 32.
Definition adc.h:53
@ ADC_GAIN_2_3
x 2/3.
Definition adc.h:42
@ ADC_GAIN_4_5
x 4/5.
Definition adc.h:43
@ ADC_GAIN_8
x 8.
Definition adc.h:49
@ ADC_GAIN_1_3
x 1/3.
Definition adc.h:39
@ ADC_GAIN_1_4
x 1/4.
Definition adc.h:37
@ ADC_GAIN_2
x 2.
Definition adc.h:45
@ ADC_ACTION_FINISH
The sequence should be finished immediately.
Definition adc.h:564
@ ADC_ACTION_REPEAT
The sampling should be repeated.
Definition adc.h:561
@ ADC_ACTION_CONTINUE
The sequence should be continued normally.
Definition adc.h:555
@ ADC_REF_INTERNAL
Internal.
Definition adc.h:100
@ ADC_REF_EXTERNAL1
External, input 1.
Definition adc.h:102
@ ADC_REF_VDD_1_2
VDD/2.
Definition adc.h:97
@ ADC_REF_VDD_1_3
VDD/3.
Definition adc.h:98
@ ADC_REF_VDD_1_4
VDD/4.
Definition adc.h:99
@ ADC_REF_VDD_1
VDD.
Definition adc.h:96
@ ADC_REF_EXTERNAL0
External, input 0.
Definition adc.h:101
bool device_is_ready(const struct device *dev)
Verify that a device is ready for use.
#define BIT(n)
Unsigned integer with bit position n set (signed in assembly language).
Definition util_macro.h:44
#define ENOTSUP
Unsupported value.
Definition errno.h:114
Public kernel APIs.
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__INT32_TYPE__ int32_t
Definition stdint.h:74
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
__INT64_TYPE__ int64_t
Definition stdint.h:75
Structure for specifying the configuration of an ADC channel.
Definition adc.h:108
enum adc_gain gain
Gain selection.
Definition adc.h:110
uint8_t differential
Channel type: single-ended or differential.
Definition adc.h:151
uint16_t acquisition_time
Acquisition time.
Definition adc.h:124
enum adc_reference reference
Reference selection.
Definition adc.h:113
uint8_t channel_id
Channel identifier.
Definition adc.h:148
ADC driver API.
Definition adc.h:721
adc_api_read read
Definition adc.h:723
uint16_t ref_internal
Definition adc.h:727
adc_api_channel_setup channel_setup
Definition adc.h:722
Container for ADC channel information specified in devicetree.
Definition adc.h:283
struct adc_channel_cfg channel_cfg
Configuration of the associated ADC channel specified in devicetree.
Definition adc.h:305
uint8_t channel_id
ADC channel identifier used by this io-channel.
Definition adc.h:291
uint16_t vref_mv
Voltage of the reference selected for the channel or 0 if this value is not provided in devicetree.
Definition adc.h:313
const struct device * dev
Pointer to the device structure for the ADC driver instance used by this io-channel.
Definition adc.h:288
uint8_t oversampling
Oversampling setting to be used for that channel.
Definition adc.h:327
bool channel_cfg_dt_node_exists
Flag indicating whether configuration of the associated ADC channel is provided as a child node of th...
Definition adc.h:298
uint8_t resolution
ADC resolution to be used for that channel.
Definition adc.h:320
Structure defining additional options for an ADC sampling sequence.
Definition adc.h:593
void * user_data
Pointer to user data.
Definition adc.h:615
uint16_t extra_samplings
Number of extra samplings to perform (the total number of samplings is 1 + extra_samplings).
Definition adc.h:621
adc_sequence_callback callback
Callback function to be called after each sampling is done.
Definition adc.h:609
uint32_t interval_us
Interval between consecutive samplings (in microseconds), 0 means sample as fast as possible,...
Definition adc.h:603
Structure defining an ADC sampling sequence.
Definition adc.h:627
uint8_t oversampling
Oversampling setting.
Definition adc.h:679
const struct adc_sequence_options * options
Pointer to a structure defining additional options for the sequence.
Definition adc.h:632
uint32_t channels
Bit-mask indicating the channels to be included in each sampling of this sequence.
Definition adc.h:641
void * buffer
Pointer to a buffer where the samples are to be written.
Definition adc.h:654
bool calibrate
Perform calibration before the reading is taken if requested.
Definition adc.h:689
size_t buffer_size
Specifies the actual size of the buffer pointed by the "buffer" field (in bytes).
Definition adc.h:662
uint8_t resolution
ADC resolution.
Definition adc.h:671
Runtime device structure (in ROM) per driver instance.
Definition device.h:510
Definition kernel.h:6149