ADC driver APIs

ADC driver APIs. More...

Modules
	Emulated ADC
	Emulated ADC backend API.

Data Structures
struct	adc_channel_cfg
	Structure for specifying the configuration of an ADC channel. More...
struct	adc_sequence_options
	Structure defining additional options for an ADC sampling sequence. More...
struct	adc_sequence
	Structure defining an ADC sampling sequence. More...
struct	adc_driver_api
	ADC driver API. More...

Typedefs
typedef 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. More...
typedef 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. See adc_channel_setup() for argument descriptions. More...
typedef int(*	adc_api_read) (const struct device *dev, const struct adc_sequence *sequence)
	Type definition of ADC API function for setting a read request. See adc_read() for argument descriptions. More...
typedef 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. See adc_read_async() for argument descriptions. More...

Enumerations
enum	adc_gain {   ADC_GAIN_1_6 , ADC_GAIN_1_5 , ADC_GAIN_1_4 , ADC_GAIN_1_3 ,   ADC_GAIN_1_2 , ADC_GAIN_2_3 , 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 }
	ADC channel gain factors. More...
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 }
	ADC references. More...
enum	adc_action { ADC_ACTION_CONTINUE = 0 , ADC_ACTION_REPEAT , ADC_ACTION_FINISH }
	Action to be performed after a sampling is done. More...

Functions
int	adc_gain_invert (enum adc_gain gain, int32_t *value)
	Invert the application of gain to a measurement value. More...
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. More...
int	adc_channel_setup (const struct device *dev, const struct adc_channel_cfg *channel_cfg)
	Configure an ADC channel. More...
int	adc_read (const struct device *dev, const struct adc_sequence *sequence)
	Set a read request. More...
int	adc_read_async (const struct device *dev, const struct adc_sequence *sequence, struct k_poll_signal *async)
	Set an asynchronous read request. More...
static uint16_t	adc_ref_internal (const struct device *dev)
	Get the internal reference voltage. More...

Detailed Description

ADC driver APIs.

Typedef Documentation

adc_api_channel_setup

typedef int(* adc_api_channel_setup) (const struct device *dev, const struct adc_channel_cfg *channel_cfg)

#include <include/drivers/adc.h>

Type definition of ADC API function for configuring a channel. See adc_channel_setup() for argument descriptions.

adc_api_read

typedef int(* adc_api_read) (const struct device *dev, const struct adc_sequence *sequence)

#include <include/drivers/adc.h>

Type definition of ADC API function for setting a read request. See adc_read() for argument descriptions.

adc_api_read_async

typedef int(* adc_api_read_async) (const struct device *dev, const struct adc_sequence *sequence, struct k_poll_signal *async)

#include <include/drivers/adc.h>

Type definition of ADC API function for setting an asynchronous read request. See adc_read_async() for argument descriptions.

adc_sequence_callback

typedef enum adc_action(* adc_sequence_callback) (const struct device *dev, const struct adc_sequence *sequence, uint16_t sampling_index)

#include <include/drivers/adc.h>

Type definition of the optional callback function to be called after a requested sampling is done.

Parameters

dev	Pointer to the device structure for the driver instance.
sequence	Pointer to the sequence structure that triggered the sampling. This parameter points to a copy of the structure that was supplied to the call that started the sampling sequence, thus it cannot be used with the CONTAINER_OF() macro to retrieve some other data associated with the sequence. Instead, the adc_sequence_options::user_data field should be used for such purpose.
sampling_index	Index (0-65535) of the sampling done.

Returns

Action to be performed by the driver. See adc_action.

Enumeration Type Documentation

adc_action

enum adc_action

#include <include/drivers/adc.h>

Action to be performed after a sampling is done.

Enumerator
ADC_ACTION_CONTINUE	The sequence should be continued normally.
ADC_ACTION_REPEAT	The sampling should be repeated. New samples or sample should be read from the ADC and written in the same place as the recent ones.
ADC_ACTION_FINISH	The sequence should be finished immediately.

adc_gain

enum adc_gain

#include <include/drivers/adc.h>

ADC channel gain factors.

Enumerator
ADC_GAIN_1_6	x 1/6.
ADC_GAIN_1_5	x 1/5.
ADC_GAIN_1_4	x 1/4.
ADC_GAIN_1_3	x 1/3.
ADC_GAIN_1_2	x 1/2.
ADC_GAIN_2_3	x 2/3.
ADC_GAIN_1	x 1.
ADC_GAIN_2	x 2.
ADC_GAIN_3	x 3.
ADC_GAIN_4	x 4.
ADC_GAIN_6	x 6.
ADC_GAIN_8	x 8.
ADC_GAIN_12	x 12.
ADC_GAIN_16	x 16.
ADC_GAIN_24	x 24.
ADC_GAIN_32	x 32.
ADC_GAIN_64	x 64.
ADC_GAIN_128	x 128.

adc_reference

enum adc_reference

#include <include/drivers/adc.h>

ADC references.

Enumerator
ADC_REF_VDD_1	VDD.
ADC_REF_VDD_1_2	VDD/2.
ADC_REF_VDD_1_3	VDD/3.
ADC_REF_VDD_1_4	VDD/4.
ADC_REF_INTERNAL	Internal.
ADC_REF_EXTERNAL0	External, input 0.
ADC_REF_EXTERNAL1	External, input 1.

Function Documentation

adc_channel_setup()

int adc_channel_setup	(	const struct device *	dev,
		const struct adc_channel_cfg *	channel_cfg
	)

#include <include/drivers/adc.h>

Configure an ADC channel.

It is required to call this function and configure each channel before it is selected for a read request.

Parameters

dev	Pointer to the device structure for the driver instance.
channel_cfg	Channel configuration.

Return values

0	On success.
-EINVAL	If a parameter with an invalid value has been provided.

adc_gain_invert()

int adc_gain_invert	(	enum adc_gain	gain,
		int32_t *	value
	)

#include <include/drivers/adc.h>

Invert the application of gain to a measurement value.

For example, if the gain passed in is ADC_GAIN_1_6 and the referenced value is 10, the value after the function returns is 60.

Parameters

gain	the gain used to amplify the input signal.
value	a pointer to a value that initially has the effect of the applied gain but has that effect removed when this function successfully returns. If the gain cannot be reversed the value remains unchanged.

Return values

0	if the gain was successfully reversed
-EINVAL	if the gain could not be interpreted

adc_raw_to_millivolts()

static int adc_raw_to_millivolts ( int32_t  ref_mv, enum adc_gain  gain, uint8_t  resolution, int32_t *  valp  )

inlinestatic

#include <include/drivers/adc.h>

Convert a raw ADC value to millivolts.

This function performs the necessary conversion to transform a raw ADC measurement to a voltage in millivolts.

Parameters

ref_mv	the reference voltage used for the measurement, in millivolts. This may be from adc_ref_internal() or a known external reference.
gain	the ADC gain configuration used to sample the input
resolution	the number of bits in the absolute value of the sample. For differential sampling this may be one less than the resolution in struct adc_sequence.
valp	pointer to the raw measurement value on input, and the corresponding millivolt value on successful conversion. If conversion fails the stored value is left unchanged.

Return values

0	on successful conversion
-EINVAL	if the gain is not reversible

adc_read()

int adc_read	(	const struct device *	dev,
		const struct adc_sequence *	sequence
	)

#include <include/drivers/adc.h>

Set a read request.

Parameters

dev	Pointer to the device structure for the driver instance.
sequence	Structure specifying requested sequence of samplings.

If invoked from user mode, any sequence struct options for callback must be NULL.

Return values

0	On success.
-EINVAL	If a parameter with an invalid value has been provided.
-ENOMEM	If the provided buffer is to small to hold the results of all requested samplings.
-ENOTSUP	If the requested mode of operation is not supported.
-EBUSY	If another sampling was triggered while the previous one was still in progress. This may occur only when samplings are done with intervals, and it indicates that the selected interval was too small. All requested samples are written in the buffer, but at least some of them were taken with an extra delay compared to what was scheduled.

adc_read_async()

int adc_read_async	(	const struct device *	dev,
		const struct adc_sequence *	sequence,
		struct k_poll_signal *	async
	)

#include <include/drivers/adc.h>

Set an asynchronous read request.

Note

This function is available only if

embed:rst:inline :kconfig:`CONFIG_ADC_ASYNC` 

is selected.

If invoked from user mode, any sequence struct options for callback must be NULL.

Parameters

dev	Pointer to the device structure for the driver instance.
sequence	Structure specifying requested sequence of samplings.
async	Pointer to a valid and ready to be signaled struct k_poll_signal. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).

Returns

0 on success, negative error code otherwise. See adc_read() for a list of possible error codes.

adc_ref_internal()

static uint16_t adc_ref_internal ( const struct device *  dev )

inlinestatic

#include <include/drivers/adc.h>

Get the internal reference voltage.

Returns the voltage corresponding to ADC_REF_INTERNAL, measured in millivolts.

Returns

a positive value is the reference voltage value. Returns zero if reference voltage information is not available.