1 /**
2 * @file
3 * @brief ADC public API header file.
4 */
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>
17 #include <zephyr/dt-bindings/adc/adc.h>
18 #include <zephyr/kernel.h>
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 /**
25 * @brief ADC driver APIs
26 * @defgroup adc_interface ADC driver APIs
27 * @since 1.0
28 * @version 1.0.0
29 * @ingroup io_interfaces
30 * @{
31 */
32
33 /** @brief ADC channel gain factors. */
34 enum adc_gain {
35 ADC_GAIN_1_6, /**< x 1/6. */
36 ADC_GAIN_1_5, /**< x 1/5. */
37 ADC_GAIN_1_4, /**< x 1/4. */
38 ADC_GAIN_1_3, /**< x 1/3. */
39 ADC_GAIN_2_5, /**< x 2/5. */
40 ADC_GAIN_1_2, /**< x 1/2. */
41 ADC_GAIN_2_3, /**< x 2/3. */
42 ADC_GAIN_4_5, /**< x 4/5. */
43 ADC_GAIN_1, /**< x 1. */
44 ADC_GAIN_2, /**< x 2. */
45 ADC_GAIN_3, /**< x 3. */
46 ADC_GAIN_4, /**< x 4. */
47 ADC_GAIN_6, /**< x 6. */
48 ADC_GAIN_8, /**< x 8. */
49 ADC_GAIN_12, /**< x 12. */
50 ADC_GAIN_16, /**< x 16. */
51 ADC_GAIN_24, /**< x 24. */
52 ADC_GAIN_32, /**< x 32. */
53 ADC_GAIN_64, /**< x 64. */
54 ADC_GAIN_128, /**< x 128. */
55 };
56
57 /**
58 * @brief Invert the application of gain to a measurement value.
59 *
60 * For example, if the gain passed in is ADC_GAIN_1_6 and the
61 * referenced value is 10, the value after the function returns is 60.
62 *
63 * @param gain the gain used to amplify the input signal.
64 *
65 * @param value a pointer to a value that initially has the effect of
66 * the applied gain but has that effect removed when this function
67 * successfully returns. If the gain cannot be reversed the value
68 * remains unchanged.
69 *
70 * @retval 0 if the gain was successfully reversed
71 * @retval -EINVAL if the gain could not be interpreted
72 */
73 int adc_gain_invert(enum adc_gain gain,
74 int32_t *value);
75
76 /** @brief ADC references. */
77 enum adc_reference {
78 ADC_REF_VDD_1, /**< VDD. */
79 ADC_REF_VDD_1_2, /**< VDD/2. */
80 ADC_REF_VDD_1_3, /**< VDD/3. */
81 ADC_REF_VDD_1_4, /**< VDD/4. */
82 ADC_REF_INTERNAL, /**< Internal. */
83 ADC_REF_EXTERNAL0, /**< External, input 0. */
84 ADC_REF_EXTERNAL1, /**< External, input 1. */
85 };
86
87 /**
88 * @brief Structure for specifying the configuration of an ADC channel.
89 */
90 struct adc_channel_cfg {
91 /** Gain selection. */
92 enum adc_gain gain;
93
94 /** Reference selection. */
95 enum adc_reference reference;
96
97 /**
98 * Acquisition time.
99 * Use the ADC_ACQ_TIME macro to compose the value for this field or
100 * pass ADC_ACQ_TIME_DEFAULT to use the default setting for a given
101 * hardware (e.g. when the hardware does not allow to configure the
102 * acquisition time).
103 * Particular drivers do not necessarily support all the possible units.
104 * Value range is 0-16383 for a given unit.
105 */
106 uint16_t acquisition_time;
107
108 /**
109 * Channel identifier.
110 * This value primarily identifies the channel within the ADC API - when
111 * a read request is done, the corresponding bit in the "channels" field
112 * of the "adc_sequence" structure must be set to include this channel
113 * in the sampling.
114 * For hardware that does not allow selection of analog inputs for given
115 * channels, but rather have dedicated ones, this value also selects the
116 * physical ADC input to be used in the sampling. Otherwise, when it is
117 * needed to explicitly select an analog input for the channel, or two
118 * inputs when the channel is a differential one, the selection is done
119 * in "input_positive" and "input_negative" fields.
120 * Particular drivers indicate which one of the above two cases they
121 * support by selecting or not a special hidden Kconfig option named
122 * ADC_CONFIGURABLE_INPUTS. If this option is not selected, the macro
123 * CONFIG_ADC_CONFIGURABLE_INPUTS is not defined and consequently the
124 * mentioned two fields are not present in this structure.
125 * While this API allows identifiers from range 0-31, particular drivers
126 * may support only a limited number of channel identifiers (dependent
127 * on the underlying hardware capabilities or configured via a dedicated
128 * Kconfig option).
129 */
130 uint8_t channel_id : 5;
131
132 /** Channel type: single-ended or differential. */
133 uint8_t differential : 1;
134
135 #ifdef CONFIG_ADC_CONFIGURABLE_INPUTS
136 /**
137 * Positive ADC input.
138 * This is a driver dependent value that identifies an ADC input to be
139 * associated with the channel.
140 */
141 uint8_t input_positive;
142
143 /**
144 * Negative ADC input (used only for differential channels).
145 * This is a driver dependent value that identifies an ADC input to be
146 * associated with the channel.
147 */
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;
153 /**
154 * Output pin for the current sources.
155 * This is only available if the driver enables this feature
156 * via the hidden configuration option ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN.
157 * The meaning itself is then defined by the driver itself.
158 */
159 uint8_t current_source_pin[2];
160 #endif /* CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN */
161
162 #ifdef CONFIG_ADC_CONFIGURABLE_VBIAS_PIN
163 /**
164 * Output pins for the bias voltage.
165 * This is only available if the driver enables this feature
166 * via the hidden configuration option ADC_CONFIGURABLE_VBIAS_PIN.
167 * The field is interpreted as a bitmask, where each bit represents
168 * one of the input pins. The actual mapping to the physical pins
169 * depends on the driver itself.
170 */
171 uint32_t vbias_pins;
172 #endif /* CONFIG_ADC_CONFIGURABLE_VBIAS_PIN */
173 };
174
175 /**
176 * @brief Get ADC channel configuration from a given devicetree node.
177 *
178 * This returns a static initializer for a <tt>struct adc_channel_cfg</tt>
179 * filled with data from a given devicetree node.
180 *
181 * Example devicetree fragment:
182 *
183 * @code{.dts}
184 * &adc {
185 * #address-cells = <1>;
186 * #size-cells = <0>;
187 *
188 * channel@0 {
189 * reg = <0>;
190 * zephyr,gain = "ADC_GAIN_1_6";
191 * zephyr,reference = "ADC_REF_INTERNAL";
192 * zephyr,acquisition-time = <ADC_ACQ_TIME(ADC_ACQ_TIME_MICROSECONDS, 20)>;
193 * zephyr,input-positive = <NRF_SAADC_AIN6>;
194 * zephyr,input-negative = <NRF_SAADC_AIN7>;
195 * };
196 *
197 * channel@1 {
198 * reg = <1>;
199 * zephyr,gain = "ADC_GAIN_1_6";
200 * zephyr,reference = "ADC_REF_INTERNAL";
201 * zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
202 * zephyr,input-positive = <NRF_SAADC_AIN0>;
203 * };
204 * };
205 * @endcode
206 *
207 * Example usage:
208 *
209 * @code{.c}
210 * static const struct adc_channel_cfg ch0_cfg_dt =
211 * ADC_CHANNEL_CFG_DT(DT_CHILD(DT_NODELABEL(adc), channel_0));
212 * static const struct adc_channel_cfg ch1_cfg_dt =
213 * ADC_CHANNEL_CFG_DT(DT_CHILD(DT_NODELABEL(adc), channel_1));
214 *
215 * // Initializes 'ch0_cfg_dt' to:
216 * // {
217 * // .channel_id = 0,
218 * // .gain = ADC_GAIN_1_6,
219 * // .reference = ADC_REF_INTERNAL,
220 * // .acquisition_time = ADC_ACQ_TIME(ADC_ACQ_TIME_MICROSECONDS, 20),
221 * // .differential = true,
222 * // .input_positive = NRF_SAADC_AIN6,
223 * // .input-negative = NRF_SAADC_AIN7,
224 * // }
225 * // and 'ch1_cfg_dt' to:
226 * // {
227 * // .channel_id = 1,
228 * // .gain = ADC_GAIN_1_6,
229 * // .reference = ADC_REF_INTERNAL,
230 * // .acquisition_time = ADC_ACQ_TIME_DEFAULT,
231 * // .input_positive = NRF_SAADC_AIN0,
232 * // }
233 * @endcode
234 *
235 * @param node_id Devicetree node identifier.
236 *
237 * @return Static initializer for an adc_channel_cfg structure.
238 */
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), \
244 IF_ENABLED(UTIL_OR(DT_PROP(node_id, zephyr_differential), \
245 UTIL_AND(CONFIG_ADC_CONFIGURABLE_INPUTS, \
246 DT_NODE_HAS_PROP(node_id, zephyr_input_negative))), \
247 (.differential = true,)) \
248 IF_ENABLED(CONFIG_ADC_CONFIGURABLE_INPUTS, \
249 (.input_positive = DT_PROP_OR(node_id, zephyr_input_positive, 0), \
250 .input_negative = DT_PROP_OR(node_id, zephyr_input_negative, 0),)) \
251 IF_ENABLED(CONFIG_ADC_CONFIGURABLE_EXCITATION_CURRENT_SOURCE_PIN, \
252 (.current_source_pin_set = DT_NODE_HAS_PROP(node_id, zephyr_current_source_pin), \
253 .current_source_pin = DT_PROP_OR(node_id, zephyr_current_source_pin, {0}),)) \
254 IF_ENABLED(CONFIG_ADC_CONFIGURABLE_VBIAS_PIN, \
255 (.vbias_pins = DT_PROP_OR(node_id, zephyr_vbias_pins, 0),)) \
256 }
257
258 /**
259 * @brief Container for ADC channel information specified in devicetree.
260 *
261 * @see ADC_DT_SPEC_GET_BY_IDX
262 * @see ADC_DT_SPEC_GET
263 */
264 struct adc_dt_spec {
265 /**
266 * Pointer to the device structure for the ADC driver instance
267 * used by this io-channel.
268 */
269 const struct device *dev;
270
271 /** ADC channel identifier used by this io-channel. */
272 uint8_t channel_id;
273
274 /**
275 * Flag indicating whether configuration of the associated ADC channel
276 * is provided as a child node of the corresponding ADC controller in
277 * devicetree.
278 */
279 bool channel_cfg_dt_node_exists;
280
281 /**
282 * Configuration of the associated ADC channel specified in devicetree.
283 * This field is valid only when @a channel_cfg_dt_node_exists is set
284 * to @a true.
285 */
286 struct adc_channel_cfg channel_cfg;
287
288 /**
289 * Voltage of the reference selected for the channel or 0 if this
290 * value is not provided in devicetree.
291 * This field is valid only when @a channel_cfg_dt_node_exists is set
292 * to @a true.
293 */
294 uint16_t vref_mv;
295
296 /**
297 * ADC resolution to be used for that channel.
298 * This field is valid only when @a channel_cfg_dt_node_exists is set
299 * to @a true.
300 */
301 uint8_t resolution;
302
303 /**
304 * Oversampling setting to be used for that channel.
305 * This field is valid only when @a channel_cfg_dt_node_exists is set
306 * to @a true.
307 */
308 uint8_t oversampling;
309 };
310
311 /** @cond INTERNAL_HIDDEN */
312
313 #define ADC_DT_SPEC_STRUCT(ctlr, input) { \
314 .dev = DEVICE_DT_GET(ctlr), \
315 .channel_id = input, \
316 ADC_CHANNEL_CFG_FROM_DT_NODE(\
317 ADC_CHANNEL_DT_NODE(ctlr, input)) \
318 }
319
320 #define ADC_CHANNEL_DT_NODE(ctlr, input) \
321 DT_FOREACH_CHILD_VARGS(ctlr, ADC_FOREACH_INPUT, input)
322
323 #define ADC_FOREACH_INPUT(node, input) \
324 IF_ENABLED(IS_EQ(DT_REG_ADDR(node), input), (node))
325
326 #define ADC_CHANNEL_CFG_FROM_DT_NODE(node_id) \
327 IF_ENABLED(DT_NODE_EXISTS(node_id), \
328 (.channel_cfg_dt_node_exists = true, \
329 .channel_cfg = ADC_CHANNEL_CFG_DT(node_id), \
330 .vref_mv = DT_PROP_OR(node_id, zephyr_vref_mv, 0), \
331 .resolution = DT_PROP_OR(node_id, zephyr_resolution, 0), \
332 .oversampling = DT_PROP_OR(node_id, zephyr_oversampling, 0),))
333
334 /** @endcond */
335
336 /**
337 * @brief Get ADC io-channel information from devicetree by name.
338 *
339 * This returns a static initializer for an @p adc_dt_spec structure
340 * given a devicetree node and a channel name. The node must have
341 * the "io-channels" property defined.
342 *
343 * Example devicetree fragment:
344 *
345 * @code{.dts}
346 * / {
347 * zephyr,user {
348 * io-channels = <&adc0 1>, <&adc0 3>;
349 * io-channel-names = "A0", "A1";
350 * };
351 * };
352 *
353 * &adc0 {
354 * #address-cells = <1>;
355 * #size-cells = <0>;
356 *
357 * channel@3 {
358 * reg = <3>;
359 * zephyr,gain = "ADC_GAIN_1_5";
360 * zephyr,reference = "ADC_REF_VDD_1_4";
361 * zephyr,vref-mv = <750>;
362 * zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
363 * zephyr,resolution = <12>;
364 * zephyr,oversampling = <4>;
365 * };
366 * };
367 * @endcode
368 *
369 * Example usage:
370 *
371 * @code{.c}
372 * static const struct adc_dt_spec adc_chan0 =
373 * ADC_DT_SPEC_GET_BY_NAME(DT_PATH(zephyr_user), a0);
374 * static const struct adc_dt_spec adc_chan1 =
375 * ADC_DT_SPEC_GET_BY_NAME(DT_PATH(zephyr_user), a1);
376 *
377 * // Initializes 'adc_chan0' to:
378 * // {
379 * // .dev = DEVICE_DT_GET(DT_NODELABEL(adc0)),
380 * // .channel_id = 1,
381 * // }
382 * // and 'adc_chan1' to:
383 * // {
384 * // .dev = DEVICE_DT_GET(DT_NODELABEL(adc0)),
385 * // .channel_id = 3,
386 * // .channel_cfg_dt_node_exists = true,
387 * // .channel_cfg = {
388 * // .channel_id = 3,
389 * // .gain = ADC_GAIN_1_5,
390 * // .reference = ADC_REF_VDD_1_4,
391 * // .acquisition_time = ADC_ACQ_TIME_DEFAULT,
392 * // },
393 * // .vref_mv = 750,
394 * // .resolution = 12,
395 * // .oversampling = 4,
396 * // }
397 * @endcode
398 *
399 * @param node_id Devicetree node identifier.
400 * @param name Channel name.
401 *
402 * @return Static initializer for an adc_dt_spec structure.
403 */
404 #define ADC_DT_SPEC_GET_BY_NAME(node_id, name) \
405 ADC_DT_SPEC_STRUCT(DT_IO_CHANNELS_CTLR_BY_NAME(node_id, name), \
406 DT_IO_CHANNELS_INPUT_BY_NAME(node_id, name))
407
408 /** @brief Get ADC io-channel information from a DT_DRV_COMPAT devicetree
409 * instance by name.
410 *
411 * @see ADC_DT_SPEC_GET_BY_NAME()
412 *
413 * @param inst DT_DRV_COMPAT instance number
414 * @param name Channel name.
415 *
416 * @return Static initializer for an adc_dt_spec structure.
417 */
418 #define ADC_DT_SPEC_INST_GET_BY_NAME(inst, name) \
419 ADC_DT_SPEC_GET_BY_NAME(DT_DRV_INST(inst), name)
420
421 /**
422 * @brief Get ADC io-channel information from devicetree.
423 *
424 * This returns a static initializer for an @p adc_dt_spec structure
425 * given a devicetree node and a channel index. The node must have
426 * the "io-channels" property defined.
427 *
428 * Example devicetree fragment:
429 *
430 * @code{.dts}
431 * / {
432 * zephyr,user {
433 * io-channels = <&adc0 1>, <&adc0 3>;
434 * };
435 * };
436 *
437 * &adc0 {
438 * #address-cells = <1>;
439 * #size-cells = <0>;
440 *
441 * channel@3 {
442 * reg = <3>;
443 * zephyr,gain = "ADC_GAIN_1_5";
444 * zephyr,reference = "ADC_REF_VDD_1_4";
445 * zephyr,vref-mv = <750>;
446 * zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
447 * zephyr,resolution = <12>;
448 * zephyr,oversampling = <4>;
449 * };
450 * };
451 * @endcode
452 *
453 * Example usage:
454 *
455 * @code{.c}
456 * static const struct adc_dt_spec adc_chan0 =
457 * ADC_DT_SPEC_GET_BY_IDX(DT_PATH(zephyr_user), 0);
458 * static const struct adc_dt_spec adc_chan1 =
459 * ADC_DT_SPEC_GET_BY_IDX(DT_PATH(zephyr_user), 1);
460 *
461 * // Initializes 'adc_chan0' to:
462 * // {
463 * // .dev = DEVICE_DT_GET(DT_NODELABEL(adc0)),
464 * // .channel_id = 1,
465 * // }
466 * // and 'adc_chan1' to:
467 * // {
468 * // .dev = DEVICE_DT_GET(DT_NODELABEL(adc0)),
469 * // .channel_id = 3,
470 * // .channel_cfg_dt_node_exists = true,
471 * // .channel_cfg = {
472 * // .channel_id = 3,
473 * // .gain = ADC_GAIN_1_5,
474 * // .reference = ADC_REF_VDD_1_4,
475 * // .acquisition_time = ADC_ACQ_TIME_DEFAULT,
476 * // },
477 * // .vref_mv = 750,
478 * // .resolution = 12,
479 * // .oversampling = 4,
480 * // }
481 * @endcode
482 *
483 * @see ADC_DT_SPEC_GET()
484 *
485 * @param node_id Devicetree node identifier.
486 * @param idx Channel index.
487 *
488 * @return Static initializer for an adc_dt_spec structure.
489 */
490 #define ADC_DT_SPEC_GET_BY_IDX(node_id, idx) \
491 ADC_DT_SPEC_STRUCT(DT_IO_CHANNELS_CTLR_BY_IDX(node_id, idx), \
492 DT_IO_CHANNELS_INPUT_BY_IDX(node_id, idx))
493
494 /** @brief Get ADC io-channel information from a DT_DRV_COMPAT devicetree
495 * instance.
496 *
497 * @see ADC_DT_SPEC_GET_BY_IDX()
498 *
499 * @param inst DT_DRV_COMPAT instance number
500 * @param idx Channel index.
501 *
502 * @return Static initializer for an adc_dt_spec structure.
503 */
504 #define ADC_DT_SPEC_INST_GET_BY_IDX(inst, idx) \
505 ADC_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), idx)
506
507 /**
508 * @brief Equivalent to ADC_DT_SPEC_GET_BY_IDX(node_id, 0).
509 *
510 * @see ADC_DT_SPEC_GET_BY_IDX()
511 *
512 * @param node_id Devicetree node identifier.
513 *
514 * @return Static initializer for an adc_dt_spec structure.
515 */
516 #define ADC_DT_SPEC_GET(node_id) ADC_DT_SPEC_GET_BY_IDX(node_id, 0)
517
518 /** @brief Equivalent to ADC_DT_SPEC_INST_GET_BY_IDX(inst, 0).
519 *
520 * @see ADC_DT_SPEC_GET()
521 *
522 * @param inst DT_DRV_COMPAT instance number
523 *
524 * @return Static initializer for an adc_dt_spec structure.
525 */
526 #define ADC_DT_SPEC_INST_GET(inst) ADC_DT_SPEC_GET(DT_DRV_INST(inst))
527
528 /* Forward declaration of the adc_sequence structure. */
529 struct adc_sequence;
530
531 /**
532 * @brief Action to be performed after a sampling is done.
533 */
534 enum adc_action {
535 /** The sequence should be continued normally. */
536 ADC_ACTION_CONTINUE = 0,
537
538 /**
539 * The sampling should be repeated. New samples or sample should be
540 * read from the ADC and written in the same place as the recent ones.
541 */
542 ADC_ACTION_REPEAT,
543
544 /** The sequence should be finished immediately. */
545 ADC_ACTION_FINISH,
546 };
547
548 /**
549 * @brief Type definition of the optional callback function to be called after
550 * a requested sampling is done.
551 *
552 * @param dev Pointer to the device structure for the driver
553 * instance.
554 * @param sequence Pointer to the sequence structure that triggered
555 * the sampling. This parameter points to a copy of
556 * the structure that was supplied to the call that
557 * started the sampling sequence, thus it cannot be
558 * used with the CONTAINER_OF() macro to retrieve
559 * some other data associated with the sequence.
560 * Instead, the adc_sequence_options::user_data field
561 * should be used for such purpose.
562 *
563 * @param sampling_index Index (0-65535) of the sampling done.
564 *
565 * @returns Action to be performed by the driver. See @ref adc_action.
566 */
567 typedef enum adc_action (*adc_sequence_callback)(const struct device *dev,
568 const struct adc_sequence *sequence,
569 uint16_t sampling_index);
570
571 /**
572 * @brief Structure defining additional options for an ADC sampling sequence.
573 */
574 struct adc_sequence_options {
575 /**
576 * Interval between consecutive samplings (in microseconds), 0 means
577 * sample as fast as possible, without involving any timer.
578 * The accuracy of this interval is dependent on the implementation of
579 * a given driver. The default routine that handles the intervals uses
580 * a kernel timer for this purpose, thus, it has the accuracy of the
581 * kernel's system clock. Particular drivers may use some dedicated
582 * hardware timers and achieve a better precision.
583 */
584 uint32_t interval_us;
585
586 /**
587 * Callback function to be called after each sampling is done.
588 * Optional - set to NULL if it is not needed.
589 */
590 adc_sequence_callback callback;
591
592 /**
593 * Pointer to user data. It can be used to associate the sequence
594 * with any other data that is needed in the callback function.
595 */
596 void *user_data;
597
598 /**
599 * Number of extra samplings to perform (the total number of samplings
600 * is 1 + extra_samplings).
601 */
602 uint16_t extra_samplings;
603 };
604
605 /**
606 * @brief Structure defining an ADC sampling sequence.
607 */
608 struct adc_sequence {
609 /**
610 * Pointer to a structure defining additional options for the sequence.
611 * If NULL, the sequence consists of a single sampling.
612 */
613 const struct adc_sequence_options *options;
614
615 /**
616 * Bit-mask indicating the channels to be included in each sampling
617 * of this sequence.
618 * All selected channels must be configured with adc_channel_setup()
619 * before they are used in a sequence.
620 * The least significant bit corresponds to channel 0.
621 */
622 uint32_t channels;
623
624 /**
625 * Pointer to a buffer where the samples are to be written. Samples
626 * from subsequent samplings are written sequentially in the buffer.
627 * The number of samples written for each sampling is determined by
628 * the number of channels selected in the "channels" field.
629 * The values written to the buffer represent a sample from each
630 * selected channel starting from the one with the lowest ID.
631 * The buffer must be of an appropriate size, taking into account
632 * the number of selected channels and the ADC resolution used,
633 * as well as the number of samplings contained in the sequence.
634 */
635 void *buffer;
636
637 /**
638 * Specifies the actual size of the buffer pointed by the "buffer"
639 * field (in bytes). The driver must ensure that samples are not
640 * written beyond the limit and it must return an error if the buffer
641 * turns out to be not large enough to hold all the requested samples.
642 */
643 size_t buffer_size;
644
645 /**
646 * ADC resolution.
647 * For single-ended channels the sample values are from range:
648 * 0 .. 2^resolution - 1,
649 * for differential ones:
650 * - 2^(resolution-1) .. 2^(resolution-1) - 1.
651 */
652 uint8_t resolution;
653
654 /**
655 * Oversampling setting.
656 * Each sample is averaged from 2^oversampling conversion results.
657 * This feature may be unsupported by a given ADC hardware, or in
658 * a specific mode (e.g. when sampling multiple channels).
659 */
660 uint8_t oversampling;
661
662 /**
663 * Perform calibration before the reading is taken if requested.
664 *
665 * The impact of channel configuration on the calibration
666 * process is specific to the underlying hardware. ADC
667 * implementations that do not support calibration should
668 * ignore this flag.
669 */
670 bool calibrate;
671 };
672
673
674 /**
675 * @brief Type definition of ADC API function for configuring a channel.
676 * See adc_channel_setup() for argument descriptions.
677 */
678 typedef int (*adc_api_channel_setup)(const struct device *dev,
679 const struct adc_channel_cfg *channel_cfg);
680
681 /**
682 * @brief Type definition of ADC API function for setting a read request.
683 * See adc_read() for argument descriptions.
684 */
685 typedef int (*adc_api_read)(const struct device *dev,
686 const struct adc_sequence *sequence);
687
688 /**
689 * @brief Type definition of ADC API function for setting an asynchronous
690 * read request.
691 * See adc_read_async() for argument descriptions.
692 */
693 typedef int (*adc_api_read_async)(const struct device *dev,
694 const struct adc_sequence *sequence,
695 struct k_poll_signal *async);
696
697 /**
698 * @brief ADC driver API
699 *
700 * This is the mandatory API any ADC driver needs to expose.
701 */
702 __subsystem struct adc_driver_api {
703 adc_api_channel_setup channel_setup;
704 adc_api_read read;
705 #ifdef CONFIG_ADC_ASYNC
706 adc_api_read_async read_async;
707 #endif
708 uint16_t ref_internal; /* mV */
709 };
710
711 /**
712 * @brief Configure an ADC channel.
713 *
714 * It is required to call this function and configure each channel before it is
715 * selected for a read request.
716 *
717 * @param dev Pointer to the device structure for the driver instance.
718 * @param channel_cfg Channel configuration.
719 *
720 * @retval 0 On success.
721 * @retval -EINVAL If a parameter with an invalid value has been provided.
722 */
723 __syscall int adc_channel_setup(const struct device *dev,
724 const struct adc_channel_cfg *channel_cfg);
725
z_impl_adc_channel_setup(const struct device * dev,const struct adc_channel_cfg * channel_cfg)726 static inline int z_impl_adc_channel_setup(const struct device *dev,
727 const struct adc_channel_cfg *channel_cfg)
728 {
729 const struct adc_driver_api *api =
730 (const struct adc_driver_api *)dev->api;
731
732 return api->channel_setup(dev, channel_cfg);
733 }
734
735 /**
736 * @brief Configure an ADC channel from a struct adc_dt_spec.
737 *
738 * @param spec ADC specification from Devicetree.
739 *
740 * @return A value from adc_channel_setup() or -ENOTSUP if information from
741 * Devicetree is not valid.
742 * @see adc_channel_setup()
743 */
adc_channel_setup_dt(const struct adc_dt_spec * spec)744 static inline int adc_channel_setup_dt(const struct adc_dt_spec *spec)
745 {
746 if (!spec->channel_cfg_dt_node_exists) {
747 return -ENOTSUP;
748 }
749
750 return adc_channel_setup(spec->dev, &spec->channel_cfg);
751 }
752
753 /**
754 * @brief Set a read request.
755 *
756 * @param dev Pointer to the device structure for the driver instance.
757 * @param sequence Structure specifying requested sequence of samplings.
758 *
759 * If invoked from user mode, any sequence struct options for callback must
760 * be NULL.
761 *
762 * @retval 0 On success.
763 * @retval -EINVAL If a parameter with an invalid value has been provided.
764 * @retval -ENOMEM If the provided buffer is to small to hold the results
765 * of all requested samplings.
766 * @retval -ENOTSUP If the requested mode of operation is not supported.
767 * @retval -EBUSY If another sampling was triggered while the previous one
768 * was still in progress. This may occur only when samplings
769 * are done with intervals, and it indicates that the selected
770 * interval was too small. All requested samples are written
771 * in the buffer, but at least some of them were taken with
772 * an extra delay compared to what was scheduled.
773 */
774 __syscall int adc_read(const struct device *dev,
775 const struct adc_sequence *sequence);
776
z_impl_adc_read(const struct device * dev,const struct adc_sequence * sequence)777 static inline int z_impl_adc_read(const struct device *dev,
778 const struct adc_sequence *sequence)
779 {
780 const struct adc_driver_api *api =
781 (const struct adc_driver_api *)dev->api;
782
783 return api->read(dev, sequence);
784 }
785
786 /**
787 * @brief Set a read request from a struct adc_dt_spec.
788 *
789 * @param spec ADC specification from Devicetree.
790 * @param sequence Structure specifying requested sequence of samplings.
791 *
792 * @return A value from adc_read().
793 * @see adc_read()
794 */
adc_read_dt(const struct adc_dt_spec * spec,const struct adc_sequence * sequence)795 static inline int adc_read_dt(const struct adc_dt_spec *spec,
796 const struct adc_sequence *sequence)
797 {
798 return adc_read(spec->dev, sequence);
799 }
800
801 /**
802 * @brief Set an asynchronous read request.
803 *
804 * @note This function is available only if @kconfig{CONFIG_ADC_ASYNC}
805 * is selected.
806 *
807 * If invoked from user mode, any sequence struct options for callback must
808 * be NULL.
809 *
810 * @param dev Pointer to the device structure for the driver instance.
811 * @param sequence Structure specifying requested sequence of samplings.
812 * @param async Pointer to a valid and ready to be signaled struct
813 * k_poll_signal. (Note: if NULL this function will not notify
814 * the end of the transaction, and whether it went successfully
815 * or not).
816 *
817 * @returns 0 on success, negative error code otherwise.
818 * See adc_read() for a list of possible error codes.
819 *
820 */
821 __syscall int adc_read_async(const struct device *dev,
822 const struct adc_sequence *sequence,
823 struct k_poll_signal *async);
824
825
826 #ifdef CONFIG_ADC_ASYNC
z_impl_adc_read_async(const struct device * dev,const struct adc_sequence * sequence,struct k_poll_signal * async)827 static inline int z_impl_adc_read_async(const struct device *dev,
828 const struct adc_sequence *sequence,
829 struct k_poll_signal *async)
830 {
831 const struct adc_driver_api *api =
832 (const struct adc_driver_api *)dev->api;
833
834 return api->read_async(dev, sequence, async);
835 }
836 #endif /* CONFIG_ADC_ASYNC */
837
838 /**
839 * @brief Get the internal reference voltage.
840 *
841 * Returns the voltage corresponding to @ref ADC_REF_INTERNAL,
842 * measured in millivolts.
843 *
844 * @return a positive value is the reference voltage value. Returns
845 * zero if reference voltage information is not available.
846 */
adc_ref_internal(const struct device * dev)847 static inline uint16_t adc_ref_internal(const struct device *dev)
848 {
849 const struct adc_driver_api *api =
850 (const struct adc_driver_api *)dev->api;
851
852 return api->ref_internal;
853 }
854
855 /**
856 * @brief Convert a raw ADC value to millivolts.
857 *
858 * This function performs the necessary conversion to transform a raw
859 * ADC measurement to a voltage in millivolts.
860 *
861 * @param ref_mv the reference voltage used for the measurement, in
862 * millivolts. This may be from adc_ref_internal() or a known
863 * external reference.
864 *
865 * @param gain the ADC gain configuration used to sample the input
866 *
867 * @param resolution the number of bits in the absolute value of the
868 * sample. For differential sampling this needs to be one less than the
869 * resolution in struct adc_sequence.
870 *
871 * @param valp pointer to the raw measurement value on input, and the
872 * corresponding millivolt value on successful conversion. If
873 * conversion fails the stored value is left unchanged.
874 *
875 * @retval 0 on successful conversion
876 * @retval -EINVAL if the gain is not reversible
877 */
adc_raw_to_millivolts(int32_t ref_mv,enum adc_gain gain,uint8_t resolution,int32_t * valp)878 static inline int adc_raw_to_millivolts(int32_t ref_mv,
879 enum adc_gain gain,
880 uint8_t resolution,
881 int32_t *valp)
882 {
883 int32_t adc_mv = *valp * ref_mv;
884 int ret = adc_gain_invert(gain, &adc_mv);
885
886 if (ret == 0) {
887 *valp = (adc_mv >> resolution);
888 }
889
890 return ret;
891 }
892
893 /**
894 * @brief Convert a raw ADC value to millivolts using information stored
895 * in a struct adc_dt_spec.
896 *
897 * @param[in] spec ADC specification from Devicetree.
898 * @param[in,out] valp Pointer to the raw measurement value on input, and the
899 * corresponding millivolt value on successful conversion. If conversion fails
900 * the stored value is left unchanged.
901 *
902 * @return A value from adc_raw_to_millivolts() or -ENOTSUP if information from
903 * Devicetree is not valid.
904 * @see adc_raw_to_millivolts()
905 */
adc_raw_to_millivolts_dt(const struct adc_dt_spec * spec,int32_t * valp)906 static inline int adc_raw_to_millivolts_dt(const struct adc_dt_spec *spec,
907 int32_t *valp)
908 {
909 int32_t vref_mv;
910 uint8_t resolution;
911
912 if (!spec->channel_cfg_dt_node_exists) {
913 return -ENOTSUP;
914 }
915
916 if (spec->channel_cfg.reference == ADC_REF_INTERNAL) {
917 vref_mv = (int32_t)adc_ref_internal(spec->dev);
918 } else {
919 vref_mv = spec->vref_mv;
920 }
921
922 resolution = spec->resolution;
923
924 /*
925 * For differential channels, one bit less needs to be specified
926 * for resolution to achieve correct conversion.
927 */
928 if (spec->channel_cfg.differential) {
929 resolution -= 1U;
930 }
931
932 return adc_raw_to_millivolts(vref_mv, spec->channel_cfg.gain,
933 resolution, valp);
934 }
935
936 /**
937 * @brief Initialize a struct adc_sequence from information stored in
938 * struct adc_dt_spec.
939 *
940 * Note that this function only initializes the following fields:
941 *
942 * - @ref adc_sequence.channels
943 * - @ref adc_sequence.resolution
944 * - @ref adc_sequence.oversampling
945 *
946 * Other fields should be initialized by the caller.
947 *
948 * @param[in] spec ADC specification from Devicetree.
949 * @param[out] seq Sequence to initialize.
950 *
951 * @retval 0 On success
952 * @retval -ENOTSUP If @p spec does not have valid channel configuration
953 */
adc_sequence_init_dt(const struct adc_dt_spec * spec,struct adc_sequence * seq)954 static inline int adc_sequence_init_dt(const struct adc_dt_spec *spec,
955 struct adc_sequence *seq)
956 {
957 if (!spec->channel_cfg_dt_node_exists) {
958 return -ENOTSUP;
959 }
960
961 seq->channels = BIT(spec->channel_id);
962 seq->resolution = spec->resolution;
963 seq->oversampling = spec->oversampling;
964
965 return 0;
966 }
967
968 /**
969 * @brief Validate that the ADC device is ready.
970 *
971 * @param spec ADC specification from devicetree
972 *
973 * @retval true if the ADC device is ready for use and false otherwise.
974 */
adc_is_ready_dt(const struct adc_dt_spec * spec)975 static inline bool adc_is_ready_dt(const struct adc_dt_spec *spec)
976 {
977 return device_is_ready(spec->dev);
978 }
979
980 /**
981 * @}
982 */
983
984 #ifdef __cplusplus
985 }
986 #endif
987
988 #include <zephyr/syscalls/adc.h>
989
990 #endif /* ZEPHYR_INCLUDE_DRIVERS_ADC_H_ */
991
