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 <device.h>
17 #include <dt-bindings/adc/adc.h>
18
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22
23 /**
24 * @brief ADC driver APIs
25 * @defgroup adc_interface ADC driver APIs
26 * @ingroup io_interfaces
27 * @{
28 */
29
30 /** @brief ADC channel gain factors. */
31 enum adc_gain {
32 ADC_GAIN_1_6, /**< x 1/6. */
33 ADC_GAIN_1_5, /**< x 1/5. */
34 ADC_GAIN_1_4, /**< x 1/4. */
35 ADC_GAIN_1_3, /**< x 1/3. */
36 ADC_GAIN_1_2, /**< x 1/2. */
37 ADC_GAIN_2_3, /**< x 2/3. */
38 ADC_GAIN_1, /**< x 1. */
39 ADC_GAIN_2, /**< x 2. */
40 ADC_GAIN_3, /**< x 3. */
41 ADC_GAIN_4, /**< x 4. */
42 ADC_GAIN_6, /**< x 6. */
43 ADC_GAIN_8, /**< x 8. */
44 ADC_GAIN_12, /**< x 12. */
45 ADC_GAIN_16, /**< x 16. */
46 ADC_GAIN_24, /**< x 24. */
47 ADC_GAIN_32, /**< x 32. */
48 ADC_GAIN_64, /**< x 64. */
49 ADC_GAIN_128, /**< x 128. */
50 };
51
52 /**
53 * @brief Invert the application of gain to a measurement value.
54 *
55 * For example, if the gain passed in is ADC_GAIN_1_6 and the
56 * referenced value is 10, the value after the function returns is 60.
57 *
58 * @param gain the gain used to amplify the input signal.
59 *
60 * @param value a pointer to a value that initially has the effect of
61 * the applied gain but has that effect removed when this function
62 * successfully returns. If the gain cannot be reversed the value
63 * remains unchanged.
64 *
65 * @retval 0 if the gain was successfully reversed
66 * @retval -EINVAL if the gain could not be interpreted
67 */
68 int adc_gain_invert(enum adc_gain gain,
69 int32_t *value);
70
71 /** @brief ADC references. */
72 enum adc_reference {
73 ADC_REF_VDD_1, /**< VDD. */
74 ADC_REF_VDD_1_2, /**< VDD/2. */
75 ADC_REF_VDD_1_3, /**< VDD/3. */
76 ADC_REF_VDD_1_4, /**< VDD/4. */
77 ADC_REF_INTERNAL, /**< Internal. */
78 ADC_REF_EXTERNAL0, /**< External, input 0. */
79 ADC_REF_EXTERNAL1, /**< External, input 1. */
80 };
81
82 /**
83 * @brief Structure for specifying the configuration of an ADC channel.
84 */
85 struct adc_channel_cfg {
86 /** Gain selection. */
87 enum adc_gain gain;
88
89 /** Reference selection. */
90 enum adc_reference reference;
91
92 /**
93 * Acquisition time.
94 * Use the ADC_ACQ_TIME macro to compose the value for this field or
95 * pass ADC_ACQ_TIME_DEFAULT to use the default setting for a given
96 * hardware (e.g. when the hardware does not allow to configure the
97 * acquisition time).
98 * Particular drivers do not necessarily support all the possible units.
99 * Value range is 0-16383 for a given unit.
100 */
101 uint16_t acquisition_time;
102
103 /**
104 * Channel identifier.
105 * This value primarily identifies the channel within the ADC API - when
106 * a read request is done, the corresponding bit in the "channels" field
107 * of the "adc_sequence" structure must be set to include this channel
108 * in the sampling.
109 * For hardware that does not allow selection of analog inputs for given
110 * channels, but rather have dedicated ones, this value also selects the
111 * physical ADC input to be used in the sampling. Otherwise, when it is
112 * needed to explicitly select an analog input for the channel, or two
113 * inputs when the channel is a differential one, the selection is done
114 * in "input_positive" and "input_negative" fields.
115 * Particular drivers indicate which one of the above two cases they
116 * support by selecting or not a special hidden Kconfig option named
117 * ADC_CONFIGURABLE_INPUTS. If this option is not selected, the macro
118 * CONFIG_ADC_CONFIGURABLE_INPUTS is not defined and consequently the
119 * mentioned two fields are not present in this structure.
120 * While this API allows identifiers from range 0-31, particular drivers
121 * may support only a limited number of channel identifiers (dependent
122 * on the underlying hardware capabilities or configured via a dedicated
123 * Kconfig option).
124 */
125 uint8_t channel_id : 5;
126
127 /** Channel type: single-ended or differential. */
128 uint8_t differential : 1;
129
130 #ifdef CONFIG_ADC_CONFIGURABLE_INPUTS
131 /**
132 * Positive ADC input.
133 * This is a driver dependent value that identifies an ADC input to be
134 * associated with the channel.
135 */
136 uint8_t input_positive;
137
138 /**
139 * Negative ADC input (used only for differential channels).
140 * This is a driver dependent value that identifies an ADC input to be
141 * associated with the channel.
142 */
143 uint8_t input_negative;
144 #endif /* CONFIG_ADC_CONFIGURABLE_INPUTS */
145 };
146
147 /**
148 * @brief Convert a raw ADC value to millivolts.
149 *
150 * This function performs the necessary conversion to transform a raw
151 * ADC measurement to a voltage in millivolts.
152 *
153 * @param ref_mv the reference voltage used for the measurement, in
154 * millivolts. This may be from adc_ref_internal() or a known
155 * external reference.
156 *
157 * @param gain the ADC gain configuration used to sample the input
158 *
159 * @param resolution the number of bits in the absolute value of the
160 * sample. For differential sampling this may be one less than the
161 * resolution in struct adc_sequence.
162 *
163 * @param valp pointer to the raw measurement value on input, and the
164 * corresponding millivolt value on successful conversion. If
165 * conversion fails the stored value is left unchanged.
166 *
167 * @retval 0 on successful conversion
168 * @retval -EINVAL if the gain is not reversible
169 */
adc_raw_to_millivolts(int32_t ref_mv,enum adc_gain gain,uint8_t resolution,int32_t * valp)170 static inline int adc_raw_to_millivolts(int32_t ref_mv,
171 enum adc_gain gain,
172 uint8_t resolution,
173 int32_t *valp)
174 {
175 int32_t adc_mv = *valp * ref_mv;
176 int ret = adc_gain_invert(gain, &adc_mv);
177
178 if (ret == 0) {
179 *valp = (adc_mv >> resolution);
180 }
181
182 return ret;
183 }
184
185 /* Forward declaration of the adc_sequence structure. */
186 struct adc_sequence;
187
188 /**
189 * @brief Action to be performed after a sampling is done.
190 */
191 enum adc_action {
192 /** The sequence should be continued normally. */
193 ADC_ACTION_CONTINUE = 0,
194
195 /**
196 * The sampling should be repeated. New samples or sample should be
197 * read from the ADC and written in the same place as the recent ones.
198 */
199 ADC_ACTION_REPEAT,
200
201 /** The sequence should be finished immediately. */
202 ADC_ACTION_FINISH,
203 };
204
205 /**
206 * @brief Type definition of the optional callback function to be called after
207 * a requested sampling is done.
208 *
209 * @param dev Pointer to the device structure for the driver
210 * instance.
211 * @param sequence Pointer to the sequence structure that triggered
212 * the sampling. This parameter points to a copy of
213 * the structure that was supplied to the call that
214 * started the sampling sequence, thus it cannot be
215 * used with the CONTAINER_OF() macro to retrieve
216 * some other data associated with the sequence.
217 * Instead, the adc_sequence_options::user_data field
218 * should be used for such purpose.
219 *
220 * @param sampling_index Index (0-65535) of the sampling done.
221 *
222 * @returns Action to be performed by the driver. See @ref adc_action.
223 */
224 typedef enum adc_action (*adc_sequence_callback)(const struct device *dev,
225 const struct adc_sequence *sequence,
226 uint16_t sampling_index);
227
228 /**
229 * @brief Structure defining additional options for an ADC sampling sequence.
230 */
231 struct adc_sequence_options {
232 /**
233 * Interval between consecutive samplings (in microseconds), 0 means
234 * sample as fast as possible, without involving any timer.
235 * The accuracy of this interval is dependent on the implementation of
236 * a given driver. The default routine that handles the intervals uses
237 * a kernel timer for this purpose, thus, it has the accuracy of the
238 * kernel's system clock. Particular drivers may use some dedicated
239 * hardware timers and achieve a better precision.
240 */
241 uint32_t interval_us;
242
243 /**
244 * Callback function to be called after each sampling is done.
245 * Optional - set to NULL if it is not needed.
246 */
247 adc_sequence_callback callback;
248
249 /**
250 * Pointer to user data. It can be used to associate the sequence
251 * with any other data that is needed in the callback function.
252 */
253 void *user_data;
254
255 /**
256 * Number of extra samplings to perform (the total number of samplings
257 * is 1 + extra_samplings).
258 */
259 uint16_t extra_samplings;
260 };
261
262 /**
263 * @brief Structure defining an ADC sampling sequence.
264 */
265 struct adc_sequence {
266 /**
267 * Pointer to a structure defining additional options for the sequence.
268 * If NULL, the sequence consists of a single sampling.
269 */
270 const struct adc_sequence_options *options;
271
272 /**
273 * Bit-mask indicating the channels to be included in each sampling
274 * of this sequence.
275 * All selected channels must be configured with adc_channel_setup()
276 * before they are used in a sequence.
277 */
278 uint32_t channels;
279
280 /**
281 * Pointer to a buffer where the samples are to be written. Samples
282 * from subsequent samplings are written sequentially in the buffer.
283 * The number of samples written for each sampling is determined by
284 * the number of channels selected in the "channels" field.
285 * The buffer must be of an appropriate size, taking into account
286 * the number of selected channels and the ADC resolution used,
287 * as well as the number of samplings contained in the sequence.
288 */
289 void *buffer;
290
291 /**
292 * Specifies the actual size of the buffer pointed by the "buffer"
293 * field (in bytes). The driver must ensure that samples are not
294 * written beyond the limit and it must return an error if the buffer
295 * turns out to be not large enough to hold all the requested samples.
296 */
297 size_t buffer_size;
298
299 /**
300 * ADC resolution.
301 * For single-ended channels the sample values are from range:
302 * 0 .. 2^resolution - 1,
303 * for differential ones:
304 * - 2^(resolution-1) .. 2^(resolution-1) - 1.
305 */
306 uint8_t resolution;
307
308 /**
309 * Oversampling setting.
310 * Each sample is averaged from 2^oversampling conversion results.
311 * This feature may be unsupported by a given ADC hardware, or in
312 * a specific mode (e.g. when sampling multiple channels).
313 */
314 uint8_t oversampling;
315
316 /**
317 * Perform calibration before the reading is taken if requested.
318 *
319 * The impact of channel configuration on the calibration
320 * process is specific to the underlying hardware. ADC
321 * implementations that do not support calibration should
322 * ignore this flag.
323 */
324 bool calibrate;
325 };
326
327
328 /**
329 * @brief Type definition of ADC API function for configuring a channel.
330 * See adc_channel_setup() for argument descriptions.
331 */
332 typedef int (*adc_api_channel_setup)(const struct device *dev,
333 const struct adc_channel_cfg *channel_cfg);
334
335 /**
336 * @brief Type definition of ADC API function for setting a read request.
337 * See adc_read() for argument descriptions.
338 */
339 typedef int (*adc_api_read)(const struct device *dev,
340 const struct adc_sequence *sequence);
341
342 /**
343 * @brief Type definition of ADC API function for setting an asynchronous
344 * read request.
345 * See adc_read_async() for argument descriptions.
346 */
347 typedef int (*adc_api_read_async)(const struct device *dev,
348 const struct adc_sequence *sequence,
349 struct k_poll_signal *async);
350
351 /**
352 * @brief ADC driver API
353 *
354 * This is the mandatory API any ADC driver needs to expose.
355 */
356 __subsystem struct adc_driver_api {
357 adc_api_channel_setup channel_setup;
358 adc_api_read read;
359 #ifdef CONFIG_ADC_ASYNC
360 adc_api_read_async read_async;
361 #endif
362 uint16_t ref_internal; /* mV */
363 };
364
365 /**
366 * @brief Configure an ADC channel.
367 *
368 * It is required to call this function and configure each channel before it is
369 * selected for a read request.
370 *
371 * @param dev Pointer to the device structure for the driver instance.
372 * @param channel_cfg Channel configuration.
373 *
374 * @retval 0 On success.
375 * @retval -EINVAL If a parameter with an invalid value has been provided.
376 */
377 __syscall int adc_channel_setup(const struct device *dev,
378 const struct adc_channel_cfg *channel_cfg);
379
z_impl_adc_channel_setup(const struct device * dev,const struct adc_channel_cfg * channel_cfg)380 static inline int z_impl_adc_channel_setup(const struct device *dev,
381 const struct adc_channel_cfg *channel_cfg)
382 {
383 const struct adc_driver_api *api =
384 (const struct adc_driver_api *)dev->api;
385
386 return api->channel_setup(dev, channel_cfg);
387 }
388
389 /**
390 * @brief Set a read request.
391 *
392 * @param dev Pointer to the device structure for the driver instance.
393 * @param sequence Structure specifying requested sequence of samplings.
394 *
395 * If invoked from user mode, any sequence struct options for callback must
396 * be NULL.
397 *
398 * @retval 0 On success.
399 * @retval -EINVAL If a parameter with an invalid value has been provided.
400 * @retval -ENOMEM If the provided buffer is to small to hold the results
401 * of all requested samplings.
402 * @retval -ENOTSUP If the requested mode of operation is not supported.
403 * @retval -EBUSY If another sampling was triggered while the previous one
404 * was still in progress. This may occur only when samplings
405 * are done with intervals, and it indicates that the selected
406 * interval was too small. All requested samples are written
407 * in the buffer, but at least some of them were taken with
408 * an extra delay compared to what was scheduled.
409 */
410 __syscall int adc_read(const struct device *dev,
411 const struct adc_sequence *sequence);
412
z_impl_adc_read(const struct device * dev,const struct adc_sequence * sequence)413 static inline int z_impl_adc_read(const struct device *dev,
414 const struct adc_sequence *sequence)
415 {
416 const struct adc_driver_api *api =
417 (const struct adc_driver_api *)dev->api;
418
419 return api->read(dev, sequence);
420 }
421
422 /**
423 * @brief Set an asynchronous read request.
424 *
425 * @note This function is available only if @kconfig{CONFIG_ADC_ASYNC}
426 * is selected.
427 *
428 * If invoked from user mode, any sequence struct options for callback must
429 * be NULL.
430 *
431 * @param dev Pointer to the device structure for the driver instance.
432 * @param sequence Structure specifying requested sequence of samplings.
433 * @param async Pointer to a valid and ready to be signaled struct
434 * k_poll_signal. (Note: if NULL this function will not notify
435 * the end of the transaction, and whether it went successfully
436 * or not).
437 *
438 * @returns 0 on success, negative error code otherwise.
439 * See adc_read() for a list of possible error codes.
440 *
441 */
442 __syscall int adc_read_async(const struct device *dev,
443 const struct adc_sequence *sequence,
444 struct k_poll_signal *async);
445
446
447 #ifdef CONFIG_ADC_ASYNC
z_impl_adc_read_async(const struct device * dev,const struct adc_sequence * sequence,struct k_poll_signal * async)448 static inline int z_impl_adc_read_async(const struct device *dev,
449 const struct adc_sequence *sequence,
450 struct k_poll_signal *async)
451 {
452 const struct adc_driver_api *api =
453 (const struct adc_driver_api *)dev->api;
454
455 return api->read_async(dev, sequence, async);
456 }
457 #endif /* CONFIG_ADC_ASYNC */
458
459 /**
460 * @brief Get the internal reference voltage.
461 *
462 * Returns the voltage corresponding to @ref ADC_REF_INTERNAL,
463 * measured in millivolts.
464 *
465 * @return a positive value is the reference voltage value. Returns
466 * zero if reference voltage information is not available.
467 */
adc_ref_internal(const struct device * dev)468 static inline uint16_t adc_ref_internal(const struct device *dev)
469 {
470 const struct adc_driver_api *api =
471 (const struct adc_driver_api *)dev->api;
472
473 return api->ref_internal;
474 }
475
476 /**
477 * @}
478 */
479
480 #ifdef __cplusplus
481 }
482 #endif
483
484 #include <syscalls/adc.h>
485
486 #endif /* ZEPHYR_INCLUDE_DRIVERS_ADC_H_ */
487
