Zephyr API Documentation  3.7.0-rc1
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
adc.h
Go to the documentation of this file.
1
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
55};
56
74 int32_t *value);
75
85};
86
93
96
107
131
134
135#ifdef CONFIG_ADC_CONFIGURABLE_INPUTS
141 uint8_t input_positive;
142
148 uint8_t input_negative;
149#endif /* CONFIG_ADC_CONFIGURABLE_INPUTS */
150
151#ifdef CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN
152 uint8_t current_source_pin_set : 1;
159 uint8_t current_source_pin[2];
160#endif /* CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN */
161
162#ifdef CONFIG_ADC_CONFIGURABLE_VBIAS_PIN
171 uint32_t vbias_pins;
172#endif /* CONFIG_ADC_CONFIGURABLE_VBIAS_PIN */
173};
174
239#define ADC_CHANNEL_CFG_DT(node_id) { \
240 .gain = DT_STRING_TOKEN(node_id, zephyr_gain), \
241 .reference = DT_STRING_TOKEN(node_id, zephyr_reference), \
242 .acquisition_time = DT_PROP(node_id, zephyr_acquisition_time), \
243 .channel_id = DT_REG_ADDR(node_id), \
244IF_ENABLED(CONFIG_ADC_CONFIGURABLE_INPUTS, \
245 (.differential = DT_NODE_HAS_PROP(node_id, zephyr_input_negative), \
246 .input_positive = DT_PROP_OR(node_id, zephyr_input_positive, 0), \
247 .input_negative = DT_PROP_OR(node_id, zephyr_input_negative, 0),)) \
248IF_ENABLED(DT_PROP(node_id, zephyr_differential), \
249 (.differential = true,)) \
250IF_ENABLED(CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN, \
251 (.current_source_pin_set = DT_NODE_HAS_PROP(node_id, zephyr_current_source_pin), \
252 .current_source_pin = DT_PROP_OR(node_id, zephyr_current_source_pin, {0}),)) \
253IF_ENABLED(CONFIG_ADC_CONFIGURABLE_VBIAS_PIN, \
254 (.vbias_pins = DT_PROP_OR(node_id, zephyr_vbias_pins, 0),)) \
255}
256
268 const struct device *dev;
269
272
279
286
294
301
308};
309
312#define ADC_DT_SPEC_STRUCT(ctlr, input) { \
313 .dev = DEVICE_DT_GET(ctlr), \
314 .channel_id = input, \
315 ADC_CHANNEL_CFG_FROM_DT_NODE(\
316 ADC_CHANNEL_DT_NODE(ctlr, input)) \
317 }
318
319#define ADC_CHANNEL_DT_NODE(ctlr, input) \
320 DT_FOREACH_CHILD_VARGS(ctlr, ADC_FOREACH_INPUT, input)
321
322#define ADC_FOREACH_INPUT(node, input) \
323 IF_ENABLED(IS_EQ(DT_REG_ADDR(node), input), (node))
324
325#define ADC_CHANNEL_CFG_FROM_DT_NODE(node_id) \
326 IF_ENABLED(DT_NODE_EXISTS(node_id), \
327 (.channel_cfg_dt_node_exists = true, \
328 .channel_cfg = ADC_CHANNEL_CFG_DT(node_id), \
329 .vref_mv = DT_PROP_OR(node_id, zephyr_vref_mv, 0), \
330 .resolution = DT_PROP_OR(node_id, zephyr_resolution, 0), \
331 .oversampling = DT_PROP_OR(node_id, zephyr_oversampling, 0),))
332
403#define ADC_DT_SPEC_GET_BY_NAME(node_id, name) \
404 ADC_DT_SPEC_STRUCT(DT_IO_CHANNELS_CTLR_BY_NAME(node_id, name), \
405 DT_IO_CHANNELS_INPUT_BY_NAME(node_id, name))
406
417#define ADC_DT_SPEC_INST_GET_BY_NAME(inst, name) \
418 ADC_DT_SPEC_GET_BY_NAME(DT_DRV_INST(inst), name)
419
489#define ADC_DT_SPEC_GET_BY_IDX(node_id, idx) \
490 ADC_DT_SPEC_STRUCT(DT_IO_CHANNELS_CTLR_BY_IDX(node_id, idx), \
491 DT_IO_CHANNELS_INPUT_BY_IDX(node_id, idx))
492
503#define ADC_DT_SPEC_INST_GET_BY_IDX(inst, idx) \
504 ADC_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), idx)
505
515#define ADC_DT_SPEC_GET(node_id) ADC_DT_SPEC_GET_BY_IDX(node_id, 0)
516
525#define ADC_DT_SPEC_INST_GET(inst) ADC_DT_SPEC_GET(DT_DRV_INST(inst))
526
527/* Forward declaration of the adc_sequence structure. */
528struct adc_sequence;
529
536
542
545};
546
566typedef enum adc_action (*adc_sequence_callback)(const struct device *dev,
567 const struct adc_sequence *sequence,
568 uint16_t sampling_index);
569
584
590
596
602};
603
613
622
634 void *buffer;
635
643
652
660
670};
671
672
677typedef int (*adc_api_channel_setup)(const struct device *dev,
678 const struct adc_channel_cfg *channel_cfg);
679
684typedef int (*adc_api_read)(const struct device *dev,
685 const struct adc_sequence *sequence);
686
692typedef int (*adc_api_read_async)(const struct device *dev,
693 const struct adc_sequence *sequence,
694 struct k_poll_signal *async);
695
701__subsystem struct adc_driver_api {
704#ifdef CONFIG_ADC_ASYNC
705 adc_api_read_async read_async;
706#endif
708};
709
722__syscall int adc_channel_setup(const struct device *dev,
723 const struct adc_channel_cfg *channel_cfg);
724
725static inline int z_impl_adc_channel_setup(const struct device *dev,
726 const struct adc_channel_cfg *channel_cfg)
727{
728 const struct adc_driver_api *api =
729 (const struct adc_driver_api *)dev->api;
730
731 return api->channel_setup(dev, channel_cfg);
732}
733
743static inline int adc_channel_setup_dt(const struct adc_dt_spec *spec)
744{
745 if (!spec->channel_cfg_dt_node_exists) {
746 return -ENOTSUP;
747 }
748
749 return adc_channel_setup(spec->dev, &spec->channel_cfg);
750}
751
773__syscall int adc_read(const struct device *dev,
774 const struct adc_sequence *sequence);
775
776static inline int z_impl_adc_read(const struct device *dev,
777 const struct adc_sequence *sequence)
778{
779 const struct adc_driver_api *api =
780 (const struct adc_driver_api *)dev->api;
781
782 return api->read(dev, sequence);
783}
784
794static inline int adc_read_dt(const struct adc_dt_spec *spec,
795 const struct adc_sequence *sequence)
796{
797 return adc_read(spec->dev, sequence);
798}
799
820__syscall int adc_read_async(const struct device *dev,
821 const struct adc_sequence *sequence,
822 struct k_poll_signal *async);
823
824
825#ifdef CONFIG_ADC_ASYNC
826static inline int z_impl_adc_read_async(const struct device *dev,
827 const struct adc_sequence *sequence,
828 struct k_poll_signal *async)
829{
830 const struct adc_driver_api *api =
831 (const struct adc_driver_api *)dev->api;
832
833 return api->read_async(dev, sequence, async);
834}
835#endif /* CONFIG_ADC_ASYNC */
836
846static inline uint16_t adc_ref_internal(const struct device *dev)
847{
848 const struct adc_driver_api *api =
849 (const struct adc_driver_api *)dev->api;
850
851 return api->ref_internal;
852}
853
877static inline int adc_raw_to_millivolts(int32_t ref_mv,
878 enum adc_gain gain,
879 uint8_t resolution,
880 int32_t *valp)
881{
882 int32_t adc_mv = *valp * ref_mv;
883 int ret = adc_gain_invert(gain, &adc_mv);
884
885 if (ret == 0) {
886 *valp = (adc_mv >> resolution);
887 }
888
889 return ret;
890}
891
905static inline int adc_raw_to_millivolts_dt(const struct adc_dt_spec *spec,
906 int32_t *valp)
907{
908 int32_t vref_mv;
909 uint8_t resolution;
910
911 if (!spec->channel_cfg_dt_node_exists) {
912 return -ENOTSUP;
913 }
914
916 vref_mv = (int32_t)adc_ref_internal(spec->dev);
917 } else {
918 vref_mv = spec->vref_mv;
919 }
920
921 resolution = spec->resolution;
922
923 /*
924 * For differential channels, one bit less needs to be specified
925 * for resolution to achieve correct conversion.
926 */
927 if (spec->channel_cfg.differential) {
928 resolution -= 1U;
929 }
930
931 return adc_raw_to_millivolts(vref_mv, spec->channel_cfg.gain,
932 resolution, valp);
933}
934
953static inline int adc_sequence_init_dt(const struct adc_dt_spec *spec,
954 struct adc_sequence *seq)
955{
956 if (!spec->channel_cfg_dt_node_exists) {
957 return -ENOTSUP;
958 }
959
960 seq->channels = BIT(spec->channel_id);
961 seq->resolution = spec->resolution;
962 seq->oversampling = spec->oversampling;
963
964 return 0;
965}
966
974static inline bool adc_is_ready_dt(const struct adc_dt_spec *spec)
975{
976 return device_is_ready(spec->dev);
977}
978
983#ifdef __cplusplus
984}
985#endif
986
987#include <zephyr/syscalls/adc.h>
988
989#endif /* ZEPHYR_INCLUDE_DRIVERS_ADC_H_ */
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:905
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:794
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:974
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:684
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:953
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:677
adc_action
Action to be performed after a sampling is done.
Definition: adc.h:533
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:566
adc_reference
ADC references.
Definition: adc.h:77
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:692
static uint16_t adc_ref_internal(const struct device *dev)
Get the internal reference voltage.
Definition: adc.h:846
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:743
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:877
@ ADC_GAIN_64
x 64.
Definition: adc.h:53
@ ADC_GAIN_3
x 3.
Definition: adc.h:45
@ ADC_GAIN_4
x 4.
Definition: adc.h:46
@ ADC_GAIN_1_5
x 1/5.
Definition: adc.h:36
@ ADC_GAIN_128
x 128.
Definition: adc.h:54
@ ADC_GAIN_1_2
x 1/2.
Definition: adc.h:40
@ ADC_GAIN_12
x 12.
Definition: adc.h:49
@ ADC_GAIN_2_5
x 2/5.
Definition: adc.h:39
@ ADC_GAIN_16
x 16.
Definition: adc.h:50
@ ADC_GAIN_24
x 24.
Definition: adc.h:51
@ ADC_GAIN_1
x 1.
Definition: adc.h:43
@ ADC_GAIN_6
x 6.
Definition: adc.h:47
@ ADC_GAIN_1_6
x 1/6.
Definition: adc.h:35
@ ADC_GAIN_32
x 32.
Definition: adc.h:52
@ ADC_GAIN_2_3
x 2/3.
Definition: adc.h:41
@ ADC_GAIN_4_5
x 4/5.
Definition: adc.h:42
@ ADC_GAIN_8
x 8.
Definition: adc.h:48
@ ADC_GAIN_1_3
x 1/3.
Definition: adc.h:38
@ ADC_GAIN_1_4
x 1/4.
Definition: adc.h:37
@ ADC_GAIN_2
x 2.
Definition: adc.h:44
@ ADC_ACTION_FINISH
The sequence should be finished immediately.
Definition: adc.h:544
@ ADC_ACTION_REPEAT
The sampling should be repeated.
Definition: adc.h:541
@ ADC_ACTION_CONTINUE
The sequence should be continued normally.
Definition: adc.h:535
@ ADC_REF_INTERNAL
Internal.
Definition: adc.h:82
@ ADC_REF_EXTERNAL1
External, input 1.
Definition: adc.h:84
@ ADC_REF_VDD_1_2
VDD/2.
Definition: adc.h:79
@ ADC_REF_VDD_1_3
VDD/3.
Definition: adc.h:80
@ ADC_REF_VDD_1_4
VDD/4.
Definition: adc.h:81
@ ADC_REF_VDD_1
VDD.
Definition: adc.h:78
@ ADC_REF_EXTERNAL0
External, input 0.
Definition: adc.h:83
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:115
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
Structure for specifying the configuration of an ADC channel.
Definition: adc.h:90
enum adc_gain gain
Gain selection.
Definition: adc.h:92
uint8_t differential
Channel type: single-ended or differential.
Definition: adc.h:133
uint16_t acquisition_time
Acquisition time.
Definition: adc.h:106
enum adc_reference reference
Reference selection.
Definition: adc.h:95
uint8_t channel_id
Channel identifier.
Definition: adc.h:130
ADC driver API.
Definition: adc.h:701
adc_api_read read
Definition: adc.h:703
uint16_t ref_internal
Definition: adc.h:707
adc_api_channel_setup channel_setup
Definition: adc.h:702
Container for ADC channel information specified in devicetree.
Definition: adc.h:263
struct adc_channel_cfg channel_cfg
Configuration of the associated ADC channel specified in devicetree.
Definition: adc.h:285
uint8_t channel_id
ADC channel identifier used by this io-channel.
Definition: adc.h:271
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:293
const struct device * dev
Pointer to the device structure for the ADC driver instance used by this io-channel.
Definition: adc.h:268
uint8_t oversampling
Oversampling setting to be used for that channel.
Definition: adc.h:307
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:278
uint8_t resolution
ADC resolution to be used for that channel.
Definition: adc.h:300
Structure defining additional options for an ADC sampling sequence.
Definition: adc.h:573
void * user_data
Pointer to user data.
Definition: adc.h:595
uint16_t extra_samplings
Number of extra samplings to perform (the total number of samplings is 1 + extra_samplings).
Definition: adc.h:601
adc_sequence_callback callback
Callback function to be called after each sampling is done.
Definition: adc.h:589
uint32_t interval_us
Interval between consecutive samplings (in microseconds), 0 means sample as fast as possible,...
Definition: adc.h:583
Structure defining an ADC sampling sequence.
Definition: adc.h:607
uint8_t oversampling
Oversampling setting.
Definition: adc.h:659
const struct adc_sequence_options * options
Pointer to a structure defining additional options for the sequence.
Definition: adc.h:612
uint32_t channels
Bit-mask indicating the channels to be included in each sampling of this sequence.
Definition: adc.h:621
void * buffer
Pointer to a buffer where the samples are to be written.
Definition: adc.h:634
bool calibrate
Perform calibration before the reading is taken if requested.
Definition: adc.h:669
size_t buffer_size
Specifies the actual size of the buffer pointed by the "buffer" field (in bytes).
Definition: adc.h:642
uint8_t resolution
ADC resolution.
Definition: adc.h:651
Runtime device structure (in ROM) per driver instance.
Definition: device.h:403
const void * api
Address of the API structure exposed by the device instance.
Definition: device.h:409
Definition: kernel.h:5688