Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Analog-to-Digital Converter (ADC) Driver

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Analog-to-Digital Converter functionality, for the conversion of analog voltages into a corresponding digital form.

The following driver Application Programming Interface (API) modes are covered by this manual:

The following peripheral is used by this module:

The following devices can use this module:

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

This driver provides an interface for the Analog-to-Digital conversion functions on the device, to convert analog voltages to a corresponding digital value. The ADC has up to 12-bit resolution, and is capable of converting up to 500K samples per second (KSPS).

The ADC has a compare function for accurate monitoring of user defined thresholds with minimum software intervention required. The ADC may be configured for 8-, 10-, or 12-bit result, reducing the conversion time. ADC conversion results are provided left or right adjusted which eases calculation when the result is represented as a signed integer.

The input selection is flexible, and both single-ended and differential measurements can be made. For differential measurements, an optional gain stage is available to increase the dynamic range. In addition, several internal signal inputs are available. The ADC can provide both signed and unsigned results.

The ADC measurements can either be started by application software or an incoming event from another peripheral in the device, and both internal and external reference voltages can be selected.

Note
Internal references will be enabled by the driver, but not disabled. Any reference not used by the application should be disabled by the application.

A simplified block diagram of the ADC can be seen in the figure below.

Sample Clock Prescaler

The ADC features a prescaler, which enables conversion at lower clock rates than the input Generic Clock to the ADC module. This feature can be used to lower the synchronization time of the digital interface to the ADC module via a high speed Generic Clock frequency, while still allowing the ADC sampling rate to be reduced.

ADC Resolution

The ADC supports full 8-, 10-, or 12-bit resolution. Hardware oversampling and decimation can be used to increase the effective resolution at the expense of throughput. Using oversampling and decimation mode the ADC resolution is increased from 12-bit to an effective 13-, 14-, 15-, or 16-bit. In these modes the conversion rate is reduced, as a greater number of samples is used to achieve the increased resolution. The available resolutions and effective conversion rate is listed in the table below.

Effective ADC Conversion Speed Using Oversampling
Resolution Effective conversion rate
13-bit Conversion rate divided by 4
14-bit Conversion rate divided by 16
15-bit Conversion rate divided by 64
16-bit Conversion rate divided by 256

Conversion Modes

ADC conversions can be software triggered on demand by the user application, if continuous sampling is not required. It is also possible to configure the ADC in free running mode, where new conversions are started as soon as the previous conversion is completed, or configure the ADC to scan across a number of input pins (see Pin Scan).

Differential and Single-ended Conversion

The ADC has two conversion modes; differential and single-ended. When measuring signals where the positive input pin is always at a higher voltage than the negative input pin, the single-ended conversion mode should be used in order to achieve a full 12-bit output resolution.

If however the positive input pin voltage may drop below the negative input pin the signed differential mode should be used.

Sample Time

The sample time for each ADC conversion is configurable as a number of half prescaled ADC clock cycles (depending on the prescaler value), allowing the user application to achieve faster or slower sampling depending on the source impedance of the ADC input channels. For applications with high impedance inputs the sample time can be increased to give the ADC an adequate time to sample and convert the input channel.

The resulting sampling time is given by the following equation:

\[ t_{SAMPLE} = (sample\_length+1) \times \frac{ADC_{CLK}} {2} \]

Averaging

The ADC can be configured to trade conversion speed for accuracy by averaging multiple samples in hardware. This feature is suitable when operating in noisy conditions.

You can specify any number of samples to accumulate (up to 1024) and the divide ratio to use (up to divide by 128). To modify these settings the ADC_RESOLUTION_CUSTOM needs to be set as the resolution. When this is set the number of samples to accumulate and the division ratio can be set by the configuration struct members adc_config::accumulate_samples and adc_config::divide_result. When using this mode the ADC result register will be set to be 16-bit wide to accommodate the larger result sizes produced by the accumulator.

The effective ADC conversion rate will be reduced by a factor of the number of accumulated samples; however, the effective resolution will be increased according to the table below.

Effective ADC Resolution From Various Hardware Averaging Modes
Number of samples Final result
1 12-bit
2 13-bit
4 14-bit
8 15-bit
16 16-bit
32 16-bit
64 16-bit
128 16-bit
256 16-bit
512 16-bit
1024 16-bit

Offset and Gain Correction

Inherent gain and offset errors affect the absolute accuracy of the ADC.

The offset error is defined as the deviation of the ADC's actual transfer function from ideal straight line at zero input voltage.

The gain error is defined as the deviation of the last output step's midpoint from the ideal straight line, after compensating for offset error.

The offset correction value is subtracted from the converted data before the result is ready. The gain correction value is multiplied with the offset corrected value.

The equation for both offset and gain error compensation is shown below:

\[ ADC_{RESULT} = (VALUE_{CONV} + CORR_{OFFSET}) \times CORR_{GAIN} \]

When enabled, a given set of offset and gain correction values can be applied to the sampled data in hardware, giving a corrected stream of sample data to the user application at the cost of an increased sample latency.

In single conversion, a latency of 13 ADC Generic Clock cycles is added for the final sample result availability. As the correction time is always less than the propagation delay, in free running mode this latency appears only during the first conversion. After the first conversion is complete, future conversion results are available at the defined sampling rate.

Pin Scan

In pin scan mode, the first ADC conversion will begin from the configured positive channel, plus the requested starting offset. When the first conversion is completed, the next conversion will start at the next positive input channel and so on, until all requested pins to scan have been sampled and converted. SAM L21/L22 has automatic sequences feature instead of pin scan mode. In automatic sequence mode, all of 32 positives inputs can be included in a sequence. The sequence starts from the lowest input, and go to the next enabled input automatically.

Pin scanning gives a simple mechanism to sample a large number of physical input channel samples, using a single physical ADC channel.

Window Monitor

The ADC module window monitor function can be used to automatically compare the conversion result against a preconfigured pair of upper and lower threshold values.

The threshold values are evaluated differently, depending on whether differential or single-ended mode is selected. In differential mode, the upper and lower thresholds are evaluated as signed values for the comparison, while in single-ended mode the comparisons are made as a set of unsigned values.

The significant bits of the lower window monitor threshold and upper window monitor threshold values are user-configurable, and follow the overall ADC sampling bit precision set when the ADC is configured by the user application. For example, only the eight lower bits of the window threshold values will be compared to the sampled data whilst the ADC is configured in 8-bit mode. In addition, if using differential mode, the 8th bit will be considered as the sign bit even if bit 9 is zero.

Events

Event generation and event actions are configurable in the ADC.

The ADC has two actions that can be triggered upon event reception:

The ADC can generate two events:

If the event actions are enabled in the configuration, any incoming event will trigger the action.

If the window monitor event is enabled, an event will be generated when the configured window condition is detected.

If the result ready event is enabled, an event will be generated when a conversion is completed.

Note
The connection of events between modules requires the use of the SAM Event System Driver (EVENTS) to route output event of one module to the input event of another. For more information on event routing, refer to the event driver documentation.

Special Considerations

An integrated analog temperature sensor is available for use with the ADC. The bandgap voltage, as well as the scaled I/O and core voltages can also be measured by the ADC. For internal ADC inputs, the internal source(s) may need to be manually enabled by the user application before they can be measured.

Extra Information

For extra information, see Extra Information for ADC Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for ADC Driver.

API Overview

Data Structures

struct  adc_config
 ADC configuration structure. More...
 
struct  adc_correction_config
 Gain and offset correction configuration structure. More...
 
struct  adc_events
 ADC event enable/disable structure. More...
 
struct  adc_module
 ADC software device instance structure. More...
 
struct  adc_window_config
 Window monitor configuration structure. More...
 

Macros

#define FEATURE_ADC_SUPPORT_MASTER_SLAVE
 Output Driver Strength Selection feature support. More...
 

Typedefs

typedef void(* adc_callback_t )(struct adc_module *const module)
 Type of the callback functions. More...
 

Enumerations

enum  adc_accumulate_samples {
  ADC_ACCUMULATE_DISABLE = ADC_AVGCTRL_SAMPLENUM_1,
  ADC_ACCUMULATE_SAMPLES_2 = ADC_AVGCTRL_SAMPLENUM_2,
  ADC_ACCUMULATE_SAMPLES_4 = ADC_AVGCTRL_SAMPLENUM_4,
  ADC_ACCUMULATE_SAMPLES_8 = ADC_AVGCTRL_SAMPLENUM_8,
  ADC_ACCUMULATE_SAMPLES_16 = ADC_AVGCTRL_SAMPLENUM_16,
  ADC_ACCUMULATE_SAMPLES_32 = ADC_AVGCTRL_SAMPLENUM_32,
  ADC_ACCUMULATE_SAMPLES_64 = ADC_AVGCTRL_SAMPLENUM_64,
  ADC_ACCUMULATE_SAMPLES_128 = ADC_AVGCTRL_SAMPLENUM_128,
  ADC_ACCUMULATE_SAMPLES_256 = ADC_AVGCTRL_SAMPLENUM_256,
  ADC_ACCUMULATE_SAMPLES_512 = ADC_AVGCTRL_SAMPLENUM_512,
  ADC_ACCUMULATE_SAMPLES_1024 = ADC_AVGCTRL_SAMPLENUM_1024
}
 ADC number of accumulated samples enum. More...
 
enum  adc_callback {
  ADC_CALLBACK_READ_BUFFER,
  ADC_CALLBACK_WINDOW,
  ADC_CALLBACK_ERROR
}
 ADC callback enum. More...
 
enum  adc_clock_prescaler {
  ADC_CLOCK_PRESCALER_DIV2 = ADC_CTRLB_PRESCALER_DIV2,
  ADC_CLOCK_PRESCALER_DIV4 = ADC_CTRLB_PRESCALER_DIV4,
  ADC_CLOCK_PRESCALER_DIV8 = ADC_CTRLB_PRESCALER_DIV8,
  ADC_CLOCK_PRESCALER_DIV16 = ADC_CTRLB_PRESCALER_DIV16,
  ADC_CLOCK_PRESCALER_DIV32 = ADC_CTRLB_PRESCALER_DIV32,
  ADC_CLOCK_PRESCALER_DIV64 = ADC_CTRLB_PRESCALER_DIV64,
  ADC_CLOCK_PRESCALER_DIV128 = ADC_CTRLB_PRESCALER_DIV128,
  ADC_CLOCK_PRESCALER_DIV256 = ADC_CTRLB_PRESCALER_DIV256
}
 ADC clock prescaler enum. More...
 
enum  adc_divide_result {
  ADC_DIVIDE_RESULT_DISABLE = 0,
  ADC_DIVIDE_RESULT_2 = 1,
  ADC_DIVIDE_RESULT_4 = 2,
  ADC_DIVIDE_RESULT_8 = 3,
  ADC_DIVIDE_RESULT_16 = 4,
  ADC_DIVIDE_RESULT_32 = 5,
  ADC_DIVIDE_RESULT_64 = 6,
  ADC_DIVIDE_RESULT_128 = 7
}
 ADC possible dividers for the result register. More...
 
enum  adc_dual_mode_trigger_selection {
  ADC_DUAL_MODE_BOTH = ADC_CTRLC_DUALSEL_BOTH,
  ADC_DUAL_MODE_INTERLEAVE = ADC_CTRLC_DUALSEL_INTERLEAVE
}
 Enum for the trigger selection in dual mode. More...
 
enum  adc_event_action {
  ADC_EVENT_ACTION_DISABLED = 0,
  ADC_EVENT_ACTION_FLUSH_START_CONV = ADC_EVCTRL_FLUSHEI,
  ADC_EVENT_ACTION_START_CONV = ADC_EVCTRL_STARTEI
}
 ADC event action enum. More...
 
enum  adc_interrupt_flag {
  ADC_INTERRUPT_RESULT_READY = ADC_INTFLAG_RESRDY,
  ADC_INTERRUPT_WINDOW = ADC_INTFLAG_WINMON,
  ADC_INTERRUPT_OVERRUN = ADC_INTFLAG_OVERRUN
}
 Enum for the possible ADC interrupt flags. More...
 
enum  adc_job_type { ADC_JOB_READ_BUFFER }
 Enum for the possible types of ADC asynchronous jobs that may be issued to the driver. More...
 
enum  adc_negative_input {
  ADC_NEGATIVE_INPUT_PIN0 = ADC_INPUTCTRL_MUXNEG_AIN0,
  ADC_NEGATIVE_INPUT_PIN1 = ADC_INPUTCTRL_MUXNEG_AIN1,
  ADC_NEGATIVE_INPUT_PIN2 = ADC_INPUTCTRL_MUXNEG_AIN2,
  ADC_NEGATIVE_INPUT_PIN3 = ADC_INPUTCTRL_MUXNEG_AIN3,
  ADC_NEGATIVE_INPUT_PIN4 = ADC_INPUTCTRL_MUXNEG_AIN4,
  ADC_NEGATIVE_INPUT_PIN5 = ADC_INPUTCTRL_MUXNEG_AIN5,
  ADC_NEGATIVE_INPUT_GND = ADC_INPUTCTRL_MUXNEG(0x18u)
}
 ADC negative MUX input selection enum. More...
 
enum  adc_oversampling_and_decimation {
  ADC_OVERSAMPLING_AND_DECIMATION_DISABLE = 0,
  ADC_OVERSAMPLING_AND_DECIMATION_1BIT,
  ADC_OVERSAMPLING_AND_DECIMATION_2BIT,
  ADC_OVERSAMPLING_AND_DECIMATION_3BIT,
  ADC_OVERSAMPLING_AND_DECIMATION_4BIT
}
 ADC oversampling and decimation enum. More...
 
enum  adc_positive_input {
  ADC_POSITIVE_INPUT_PIN0 = ADC_INPUTCTRL_MUXPOS_AIN0,
  ADC_POSITIVE_INPUT_PIN1 = ADC_INPUTCTRL_MUXPOS_AIN1,
  ADC_POSITIVE_INPUT_PIN2 = ADC_INPUTCTRL_MUXPOS_AIN2,
  ADC_POSITIVE_INPUT_PIN3 = ADC_INPUTCTRL_MUXPOS_AIN3,
  ADC_POSITIVE_INPUT_PIN4 = ADC_INPUTCTRL_MUXPOS_AIN4,
  ADC_POSITIVE_INPUT_PIN5 = ADC_INPUTCTRL_MUXPOS_AIN5,
  ADC_POSITIVE_INPUT_PIN6 = ADC_INPUTCTRL_MUXPOS_AIN6,
  ADC_POSITIVE_INPUT_PIN7 = ADC_INPUTCTRL_MUXPOS_AIN7,
  ADC_POSITIVE_INPUT_PIN8 = ADC_INPUTCTRL_MUXPOS_AIN8,
  ADC_POSITIVE_INPUT_PIN9 = ADC_INPUTCTRL_MUXPOS_AIN9,
  ADC_POSITIVE_INPUT_PIN10 = ADC_INPUTCTRL_MUXPOS_AIN10,
  ADC_POSITIVE_INPUT_PIN11 = ADC_INPUTCTRL_MUXPOS_AIN11,
  ADC_POSITIVE_INPUT_BANDGAP = ADC_INPUTCTRL_MUXPOS_BANDGAP,
  ADC_POSITIVE_INPUT_SCALEDCOREVCC = ADC_INPUTCTRL_MUXPOS_SCALEDCOREVCC,
  ADC_POSITIVE_INPUT_SCALEDIOVCC = ADC_INPUTCTRL_MUXPOS_SCALEDIOVCC
}
 ADC positive MUX input selection enum. More...
 
enum  adc_reference {
  ADC_REFERENCE_INTREF = ADC_REFCTRL_REFSEL_INTREF,
  ADC_REFERENCE_INTVCC0 = ADC_REFCTRL_REFSEL_INTVCC0,
  ADC_REFERENCE_INTVCC1 = ADC_REFCTRL_REFSEL_INTVCC1,
  ADC_REFERENCE_AREFA = ADC_REFCTRL_REFSEL_AREFA,
  ADC_REFERENCE_INTVCC2 = ADC_REFCTRL_REFSEL_INTVCC2
}
 ADC reference voltage enum. More...
 
enum  adc_resolution {
  ADC_RESOLUTION_12BIT = ADC_CTRLC_RESSEL_12BIT,
  ADC_RESOLUTION_16BIT = ADC_CTRLC_RESSEL_16BIT,
  ADC_RESOLUTION_10BIT = ADC_CTRLC_RESSEL_10BIT,
  ADC_RESOLUTION_8BIT = ADC_CTRLC_RESSEL_8BIT,
  ADC_RESOLUTION_13BIT,
  ADC_RESOLUTION_14BIT,
  ADC_RESOLUTION_15BIT,
  ADC_RESOLUTION_CUSTOM
}
 ADC resolution enum. More...
 
enum  adc_window_mode {
  ADC_WINDOW_MODE_DISABLE = ADC_CTRLC_WINMODE_DISABLE,
  ADC_WINDOW_MODE_ABOVE_LOWER = ADC_CTRLC_WINMODE_MODE1,
  ADC_WINDOW_MODE_BELOW_UPPER = ADC_CTRLC_WINMODE_MODE2,
  ADC_WINDOW_MODE_BETWEEN = ADC_CTRLC_WINMODE_MODE3,
  ADC_WINDOW_MODE_BETWEEN_INVERTED = ADC_CTRLC_WINMODE_MODE4
}
 ADC window monitor mode enum. More...
 

Functions

static void adc_set_master_slave_mode (struct adc_module *const master_inst, struct adc_module *const slave_inst, enum adc_dual_mode_trigger_selection dualsel)
 Set ADC master and slave mode. More...
 

Module Status Flags

ADC status flags, returned by adc_get_status() and cleared by adc_clear_status().

#define ADC_STATUS_RESULT_READY   (1UL << 0)
 ADC result ready. More...
 
#define ADC_STATUS_WINDOW   (1UL << 1)
 Window monitor match. More...
 
#define ADC_STATUS_OVERRUN   (1UL << 2)
 ADC result overwritten before read. More...
 

Driver Initialization and Configuration

enum status_code adc_init (struct adc_module *const module_inst, Adc *hw, struct adc_config *config)
 Initializes the ADC. More...
 
void adc_get_config_defaults (struct adc_config *const config)
 Initializes an ADC configuration structure to defaults. More...
 

Status Management

static uint32_t adc_get_status (struct adc_module *const module_inst)
 Retrieves the current module status. More...
 
static void adc_clear_status (struct adc_module *const module_inst, const uint32_t status_flags)
 Clears a module status flag. More...
 

Enable, Disable, and Reset ADC Module, Start Conversion and Read Result

static enum status_code adc_enable (struct adc_module *const module_inst)
 Enables the ADC module. More...
 
static enum status_code adc_disable (struct adc_module *const module_inst)
 Disables the ADC module. More...
 
static enum status_code adc_reset (struct adc_module *const module_inst)
 Resets the ADC module. More...
 
static void adc_enable_events (struct adc_module *const module_inst, struct adc_events *const events)
 Enables an ADC event input or output. More...
 
static void adc_disable_events (struct adc_module *const module_inst, struct adc_events *const events)
 Disables an ADC event input or output. More...
 
static void adc_start_conversion (struct adc_module *const module_inst)
 Starts an ADC conversion. More...
 
static enum status_code adc_read (struct adc_module *const module_inst, uint16_t *result)
 Reads the ADC result. More...
 

Runtime Changes of ADC Module

static void adc_flush (struct adc_module *const module_inst)
 Flushes the ADC pipeline. More...
 
void adc_set_window_mode (struct adc_module *const module_inst, const enum adc_window_mode window_mode, const int16_t window_lower_value, const int16_t window_upper_value)
 Sets the ADC window mode. More...
 
static void adc_set_positive_input (struct adc_module *const module_inst, const enum adc_positive_input positive_input)
 Sets positive ADC input pin. More...
 
static void adc_set_negative_input (struct adc_module *const module_inst, const enum adc_negative_input negative_input)
 Sets negative ADC input pin for differential mode. More...
 

Enable and Disable Interrupts

static void adc_enable_interrupt (struct adc_module *const module_inst, enum adc_interrupt_flag interrupt)
 Enable interrupt. More...
 
static void adc_disable_interrupt (struct adc_module *const module_inst, enum adc_interrupt_flag interrupt)
 Disable interrupt. More...
 

Callback Management

void adc_register_callback (struct adc_module *const module, adc_callback_t callback_func, enum adc_callback callback_type)
 Registers a callback. More...
 
void adc_unregister_callback (struct adc_module *module, enum adc_callback callback_type)
 Unregisters a callback. More...
 
static void adc_enable_callback (struct adc_module *const module, enum adc_callback callback_type)
 Enables callback. More...
 
static void adc_disable_callback (struct adc_module *const module, enum adc_callback callback_type)
 Disables callback. More...
 

Job Management

enum status_code adc_read_buffer_job (struct adc_module *const module_inst, uint16_t *buffer, uint16_t samples)
 Read multiple samples from ADC. More...
 
enum status_code adc_get_job_status (struct adc_module *module_inst, enum adc_job_type type)
 Gets the status of a job. More...
 
void adc_abort_job (struct adc_module *module_inst, enum adc_job_type type)
 Aborts an ongoing job. More...
 

Positive Input Sequence

static void adc_enable_positive_input_sequence (struct adc_module *const module_inst, uint32_t positive_input_sequence_mask_enable)
 Enable positive input sequence mask for conversion. More...
 
static void adc_disable_positive_input_sequence (struct adc_module *const module_inst)
 Disable positive input in the sequence. More...
 
static void adc_get_sequence_status (struct adc_module *const module_inst, bool *is_sequence_busy, uint8_t *sequence_state)
 Get ADC sequence status. More...
 

#define ADC_STATUS_OVERRUN   (1UL << 2)

ADC result overwritten before read.

Referenced by adc_clear_status(), adc_get_status(), and adc_read().

#define ADC_STATUS_RESULT_READY   (1UL << 0)

ADC result ready.

Referenced by adc_clear_status(), adc_get_status(), and adc_read().

#define ADC_STATUS_WINDOW   (1UL << 1)

Window monitor match.

Referenced by adc_clear_status(), and adc_get_status().

#define FEATURE_ADC_SUPPORT_MASTER_SLAVE

Output Driver Strength Selection feature support.

typedef void(* adc_callback_t)(struct adc_module *const module)

Type of the callback functions.

ADC number of accumulated samples enum.

Enum for the possible numbers of ADC samples to accumulate. This setting is only used when the ADC_RESOLUTION_CUSTOM resolution setting is used.

Enumerator
ADC_ACCUMULATE_DISABLE 

No averaging.

ADC_ACCUMULATE_SAMPLES_2 

Average 2 samples.

ADC_ACCUMULATE_SAMPLES_4 

Average 4 samples.

ADC_ACCUMULATE_SAMPLES_8 

Average 8 samples.

ADC_ACCUMULATE_SAMPLES_16 

Average 16 samples.

ADC_ACCUMULATE_SAMPLES_32 

Average 32 samples.

ADC_ACCUMULATE_SAMPLES_64 

Average 64 samples.

ADC_ACCUMULATE_SAMPLES_128 

Average 128 samples.

ADC_ACCUMULATE_SAMPLES_256 

Average 256 samples.

ADC_ACCUMULATE_SAMPLES_512 

Average 512 samples.

ADC_ACCUMULATE_SAMPLES_1024 

Average 1024 samples.

ADC callback enum.

Callback types for ADC callback driver.

Enumerator
ADC_CALLBACK_READ_BUFFER 

Callback for buffer received.

ADC_CALLBACK_WINDOW 

Callback when window is hit.

ADC_CALLBACK_ERROR 

Callback for error.

ADC clock prescaler enum.

Enum for the possible clock prescaler values for the ADC.

Enumerator
ADC_CLOCK_PRESCALER_DIV2 

ADC clock division factor 2.

ADC_CLOCK_PRESCALER_DIV4 

ADC clock division factor 4.

ADC_CLOCK_PRESCALER_DIV8 

ADC clock division factor 8.

ADC_CLOCK_PRESCALER_DIV16 

ADC clock division factor 16.

ADC_CLOCK_PRESCALER_DIV32 

ADC clock division factor 32.

ADC_CLOCK_PRESCALER_DIV64 

ADC clock division factor 64.

ADC_CLOCK_PRESCALER_DIV128 

ADC clock division factor 128.

ADC_CLOCK_PRESCALER_DIV256 

ADC clock division factor 256.

ADC possible dividers for the result register.

Enum for the possible division factors to use when accumulating multiple samples. To keep the same resolution for the averaged result and the actual input value, the division factor must be equal to the number of samples accumulated. This setting is only used when the ADC_RESOLUTION_CUSTOM resolution setting is used.

Enumerator
ADC_DIVIDE_RESULT_DISABLE 

Don't divide result register after accumulation.

ADC_DIVIDE_RESULT_2 

Divide result register by 2 after accumulation.

ADC_DIVIDE_RESULT_4 

Divide result register by 4 after accumulation.

ADC_DIVIDE_RESULT_8 

Divide result register by 8 after accumulation.

ADC_DIVIDE_RESULT_16 

Divide result register by 16 after accumulation.

ADC_DIVIDE_RESULT_32 

Divide result register by 32 after accumulation.

ADC_DIVIDE_RESULT_64 

Divide result register by 64 after accumulation.

ADC_DIVIDE_RESULT_128 

Divide result register by 128 after accumulation.

Enum for the trigger selection in dual mode.

Enumerator
ADC_DUAL_MODE_BOTH 

Start event or software trigger will start a conversion on both ADCs.

ADC_DUAL_MODE_INTERLEAVE 

START event or software trigger will alternatingly start a conversion on ADC0 and ADC1.

ADC event action enum.

Enum for the possible actions to take on an incoming event.

Enumerator
ADC_EVENT_ACTION_DISABLED 

Event action disabled.

ADC_EVENT_ACTION_FLUSH_START_CONV 

Flush ADC and start conversion.

ADC_EVENT_ACTION_START_CONV 

Start conversion.

Enum for the possible ADC interrupt flags.

Enumerator
ADC_INTERRUPT_RESULT_READY 

ADC result ready.

ADC_INTERRUPT_WINDOW 

Window monitor match.

ADC_INTERRUPT_OVERRUN 

ADC result overwritten before read.

Enum for the possible types of ADC asynchronous jobs that may be issued to the driver.

Enumerator
ADC_JOB_READ_BUFFER 

Asynchronous ADC read into a user provided buffer.

ADC negative MUX input selection enum.

Enum for the possible negative MUX input selections for the ADC.

Enumerator
ADC_NEGATIVE_INPUT_PIN0 

ADC0 pin.

ADC_NEGATIVE_INPUT_PIN1 

ADC1 pin.

ADC_NEGATIVE_INPUT_PIN2 

ADC2 pin.

ADC_NEGATIVE_INPUT_PIN3 

ADC3 pin.

ADC_NEGATIVE_INPUT_PIN4 

ADC4 pin.

ADC_NEGATIVE_INPUT_PIN5 

ADC5 pin.

ADC_NEGATIVE_INPUT_GND 

Internal ground.

ADC oversampling and decimation enum.

Enum for the possible numbers of bits resolution can be increased by when using oversampling and decimation.

Enumerator
ADC_OVERSAMPLING_AND_DECIMATION_DISABLE 

Don't use oversampling and decimation mode.

ADC_OVERSAMPLING_AND_DECIMATION_1BIT 

1-bit resolution increase

ADC_OVERSAMPLING_AND_DECIMATION_2BIT 

2-bit resolution increase

ADC_OVERSAMPLING_AND_DECIMATION_3BIT 

3-bit resolution increase

ADC_OVERSAMPLING_AND_DECIMATION_4BIT 

4-bit resolution increase

ADC positive MUX input selection enum.

Enum for the possible positive MUX input selections for the ADC.

Enumerator
ADC_POSITIVE_INPUT_PIN0 

ADC0 pin.

ADC_POSITIVE_INPUT_PIN1 

ADC1 pin.

ADC_POSITIVE_INPUT_PIN2 

ADC2 pin.

ADC_POSITIVE_INPUT_PIN3 

ADC3 pin.

ADC_POSITIVE_INPUT_PIN4 

ADC4 pin.

ADC_POSITIVE_INPUT_PIN5 

ADC5 pin.

ADC_POSITIVE_INPUT_PIN6 

ADC6 pin.

ADC_POSITIVE_INPUT_PIN7 

ADC7 pin.

ADC_POSITIVE_INPUT_PIN8 

ADC8 pin.

ADC_POSITIVE_INPUT_PIN9 

ADC9 pin.

ADC_POSITIVE_INPUT_PIN10 

ADC10 pin.

ADC_POSITIVE_INPUT_PIN11 

ADC11 pin.

ADC_POSITIVE_INPUT_BANDGAP 

Bandgap voltage.

ADC_POSITIVE_INPUT_SCALEDCOREVCC 

1/4 scaled core supply

ADC_POSITIVE_INPUT_SCALEDIOVCC 

1/4 scaled I/O supply

ADC reference voltage enum.

Enum for the possible reference voltages for the ADC.

Enumerator
ADC_REFERENCE_INTREF 

Internal Bandgap Reference.

ADC_REFERENCE_INTVCC0 

1/1.48VCC reference

ADC_REFERENCE_INTVCC1 

1/2VCC (only for internal VCC > 2.1V)

ADC_REFERENCE_AREFA 

External reference A.

ADC_REFERENCE_INTVCC2 

VDDANA.

ADC resolution enum.

Enum for the possible resolution values for the ADC.

Enumerator
ADC_RESOLUTION_12BIT 

ADC 12-bit resolution.

ADC_RESOLUTION_16BIT 

ADC 16-bit resolution using oversampling and decimation.

ADC_RESOLUTION_10BIT 

ADC 10-bit resolution.

ADC_RESOLUTION_8BIT 

ADC 8-bit resolution.

ADC_RESOLUTION_13BIT 

ADC 13-bit resolution using oversampling and decimation.

ADC_RESOLUTION_14BIT 

ADC 14-bit resolution using oversampling and decimation.

ADC_RESOLUTION_15BIT 

ADC 15-bit resolution using oversampling and decimation.

ADC_RESOLUTION_CUSTOM 

ADC 16-bit result register for use with averaging.

When using this mode the ADC result register will be set to 16-bit wide, and the number of samples to accumulate and the division factor is configured by the adc_config::accumulate_samples and adc_config::divide_result members in the configuration struct.

ADC window monitor mode enum.

Enum for the possible window monitor modes for the ADC.

Enumerator
ADC_WINDOW_MODE_DISABLE 

No window mode.

ADC_WINDOW_MODE_ABOVE_LOWER 

RESULT > WINLT.

ADC_WINDOW_MODE_BELOW_UPPER 

RESULT < WINUT.

ADC_WINDOW_MODE_BETWEEN 

WINLT < RESULT < WINUT.

ADC_WINDOW_MODE_BETWEEN_INVERTED 

!(WINLT < RESULT < WINUT)

void adc_abort_job ( struct adc_module module_inst,
enum adc_job_type  type 
)

Aborts an ongoing job.

Aborts an ongoing job.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]typeType of job to abort

References adc_disable_interrupt(), ADC_INTERRUPT_RESULT_READY, ADC_JOB_READ_BUFFER, Assert, and STATUS_ABORTED.

static void adc_clear_status ( struct adc_module *const  module_inst,
const uint32_t  status_flags 
)
inlinestatic

Clears a module status flag.

Clears the given status flag of the module.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]status_flagsBitmask of ADC_STATUS_* flags to clear

References ADC_STATUS_OVERRUN, ADC_STATUS_RESULT_READY, ADC_STATUS_WINDOW, and Assert.

Referenced by adc_read().

static enum status_code adc_disable ( struct adc_module *const  module_inst)
inlinestatic

Disables the ADC module.

Disables an ADC module that was previously enabled.

Parameters
[in]module_instPointer to the ADC software instance struct

References _adc_get_inst_index(), Assert, STATUS_OK, system_interrupt_disable(), and SYSTEM_INTERRUPT_MODULE_ADC.

Referenced by adc_reset(), setup_adc_average_mode_test(), and setup_adc_window_mode_test().

static void adc_disable_callback ( struct adc_module *const  module,
enum adc_callback  callback_type 
)
inlinestatic

Disables callback.

Disables the callback function registered by the adc_register_callback.

Parameters
[in]modulePointer to ADC software instance struct
[in]callback_typeCallback type given by an enum
Returns
Status of the operation.
Return values
STATUS_OKIf operation was completed
STATUS_ERR_INVALIDIf operation was not completed, due to invalid callback_type

References ADC_CALLBACK_ERROR, ADC_CALLBACK_WINDOW, adc_disable_interrupt(), ADC_INTERRUPT_OVERRUN, ADC_INTERRUPT_WINDOW, and Assert.

Referenced by cleanup_adc_callback_mode_test(), and cleanup_adc_window_mode_test().

static void adc_disable_events ( struct adc_module *const  module_inst,
struct adc_events *const  events 
)
inlinestatic

Disables an ADC event input or output.

Disables one or more input or output events to or from the ADC module. See Struct adc_events for a list of events this module supports.

Note
Events cannot be altered while the module is enabled.
Parameters
[in]module_instSoftware instance for the ADC peripheral
[in]eventsStruct containing flags of events to disable

References Assert, adc_events::generate_event_on_conversion_done, and adc_events::generate_event_on_window_monitor.

static void adc_disable_interrupt ( struct adc_module *const  module_inst,
enum adc_interrupt_flag  interrupt 
)
inlinestatic

Disable interrupt.

Disable the given interrupt request from the ADC module.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]interruptInterrupt to disable

References Assert.

Referenced by _adc_interrupt_handler(), adc_abort_job(), and adc_disable_callback().

static void adc_disable_positive_input_sequence ( struct adc_module *const  module_inst)
inlinestatic

Disable positive input in the sequence.

Disable positive input in the sequence.

Parameters
[in]module_instPointer to the ADC software instance struct

References Assert.

static enum status_code adc_enable ( struct adc_module *const  module_inst)
inlinestatic

Enables the ADC module.

Enables an ADC module that has previously been configured. If any internal reference is selected it will be enabled.

Parameters
[in]module_instPointer to the ADC software instance struct

References _adc_get_inst_index(), Assert, STATUS_OK, system_interrupt_enable(), and SYSTEM_INTERRUPT_MODULE_ADC.

Referenced by run_adc_init_test(), setup_adc_average_mode_test(), and setup_adc_window_mode_test().

static void adc_enable_callback ( struct adc_module *const  module,
enum adc_callback  callback_type 
)
inlinestatic

Enables callback.

Enables the callback function registered by adc_register_callback. The callback function will be called from the interrupt handler when the conditions for the callback type are met.

Parameters
[in]modulePointer to ADC software instance struct
[in]callback_typeCallback type given by an enum
Returns
Status of the operation.
Return values
STATUS_OKIf operation was completed
STATUS_ERR_INVALIDIf operation was not completed, due to invalid callback_type

References ADC_CALLBACK_ERROR, ADC_CALLBACK_WINDOW, adc_enable_interrupt(), ADC_INTERRUPT_OVERRUN, ADC_INTERRUPT_WINDOW, and Assert.

Referenced by setup_adc_callback_mode_test(), and setup_adc_window_mode_test().

static void adc_enable_events ( struct adc_module *const  module_inst,
struct adc_events *const  events 
)
inlinestatic

Enables an ADC event input or output.

Enables one or more input or output events to or from the ADC module. See Struct adc_events for a list of events this module supports.

Note
Events cannot be altered while the module is enabled.
Parameters
[in]module_instSoftware instance for the ADC peripheral
[in]eventsStruct containing flags of events to enable

References Assert, adc_events::generate_event_on_conversion_done, and adc_events::generate_event_on_window_monitor.

static void adc_enable_interrupt ( struct adc_module *const  module_inst,
enum adc_interrupt_flag  interrupt 
)
inlinestatic

Enable interrupt.

Enable the given interrupt request from the ADC module.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]interruptInterrupt to enable

References Assert.

Referenced by adc_enable_callback(), and adc_read_buffer_job().

static void adc_enable_positive_input_sequence ( struct adc_module *const  module_inst,
uint32_t  positive_input_sequence_mask_enable 
)
inlinestatic

Enable positive input sequence mask for conversion.

The sequence start from the lowest input, and go to the next enabled input automatically when the conversion is done. If no bits are set the sequence is disabled.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]eanble_seq_maskSequence mask

References Assert.

static void adc_flush ( struct adc_module *const  module_inst)
inlinestatic

Flushes the ADC pipeline.

Flushes the pipeline and restarts the ADC clock on the next peripheral clock edge. All conversions in progress will be lost. When flush is complete, the module will resume where it left off.

Parameters
[in]module_instPointer to the ADC software instance struct

References Assert.

Referenced by run_adc_polled_mode_test().

void adc_get_config_defaults ( struct adc_config *const  config)

Initializes an ADC configuration structure to defaults.

Initializes a given ADC configuration struct to a set of known default values. This function should be called on any new instance of the configuration struct before being modified by the user application.

The default configuration is as follows:

  • GCLK generator 0 (GCLK main) clock source
  • Internal bandgap reference
  • Div 2 clock prescaler
  • 12-bit resolution
  • Window monitor disabled
  • Positive input on ADC PIN 1
  • Negative input on Internal ground
  • Averaging disabled
  • Oversampling disabled
  • Right adjust data
  • Single-ended mode
  • Free running disabled
  • All events (input and generation) disabled
  • ADC run in standby disabled
  • ADC On demand disabled
  • No sampling time compensation
  • Disable the positive input sequense
  • No reference compensation
  • No gain/offset correction
  • No added sampling time
Parameters
[out]configPointer to configuration struct to initialize to default values

References adc_config::accumulate_samples, ADC_ACCUMULATE_DISABLE, ADC_CLOCK_PRESCALER_DIV2, ADC_DIVIDE_RESULT_DISABLE, ADC_EVENT_ACTION_DISABLED, ADC_NEGATIVE_INPUT_GND, ADC_POSITIVE_INPUT_PIN1, ADC_POSITIVE_INPUT_PIN6, ADC_REFERENCE_INTREF, ADC_RESOLUTION_12BIT, ADC_WINDOW_MODE_DISABLE, Assert, adc_config::clock_prescaler, adc_config::clock_source, adc_config::correction, adc_correction_config::correction_enable, adc_config::differential_mode, adc_config::divide_result, adc_config::event_action, adc_config::freerunning, adc_correction_config::gain_correction, GCLK_GENERATOR_0, adc_config::left_adjust, adc_config::negative_input, adc_correction_config::offset_correction, adc_config::on_demand, adc_config::positive_input, adc_config::positive_input_sequence_mask_enable, adc_config::reference, adc_config::reference_compensation_enable, adc_config::resolution, adc_config::run_in_standby, adc_config::sample_length, adc_config::sampling_time_compensation_enable, adc_config::window, adc_window_config::window_lower_value, adc_window_config::window_mode, and adc_window_config::window_upper_value.

Referenced by run_adc_init_test(), setup_adc_average_mode_test(), and setup_adc_window_mode_test().

enum status_code adc_get_job_status ( struct adc_module module_inst,
enum adc_job_type  type 
)

Gets the status of a job.

Gets the status of an ongoing or the last job.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]typeType of to get status
Returns
Status of the job.

References ADC_JOB_READ_BUFFER, Assert, and STATUS_ERR_INVALID_ARG.

static void adc_get_sequence_status ( struct adc_module *const  module_inst,
bool is_sequence_busy,
uint8_t *  sequence_state 
)
inlinestatic

Get ADC sequence status.

Check if a sequence is done and get last conversion done in the sequence.

Parameters
[in]module_instPointer to the ADC software instance struct
[out]is_sequence_busySequence busy status
[out]sequence_stateThis value identifies the last conversion done in the sequence

References Assert.

static uint32_t adc_get_status ( struct adc_module *const  module_inst)
inlinestatic

Retrieves the current module status.

Retrieves the status of the module, giving overall state information.

Parameters
[in]module_instPointer to the ADC software instance struct
Returns
Bitmask of ADC_STATUS_* flags.
Return values
ADC_STATUS_RESULT_READYADC result is ready to be read
ADC_STATUS_WINDOWADC has detected a value inside the set window range
ADC_STATUS_OVERRUNADC result has overrun

References ADC_STATUS_OVERRUN, ADC_STATUS_RESULT_READY, ADC_STATUS_WINDOW, and Assert.

Referenced by adc_read().

enum status_code adc_init ( struct adc_module *const  module_inst,
Adc *  hw,
struct adc_config config 
)

Initializes the ADC.

Initializes the ADC device struct and the hardware module based on the given configuration struct values.

Parameters
[out]module_instPointer to the ADC software instance struct
[in]hwPointer to the ADC module instance
[in]configPointer to the configuration struct
Returns
Status of the initialization procedure.
Return values
STATUS_OKThe initialization was successful
STATUS_ERR_INVALID_ARGInvalid argument(s) were provided
STATUS_BUSYThe module is busy with a reset operation
STATUS_ERR_DENIEDThe module is enabled

References _adc_get_inst_index(), _adc_instances, _adc_set_config(), ADC_EVENT_ACTION_DISABLED, ADC_REFERENCE_INTREF, Assert, adc_config::event_action, adc_config::freerunning, adc_config::reference, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_OK, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBC, SYSTEM_CLOCK_APB_APBD, system_voltage_reference_enable(), and SYSTEM_VOLTAGE_REFERENCE_OUTPUT.

Referenced by run_adc_init_test(), setup_adc_average_mode_test(), and setup_adc_window_mode_test().

static enum status_code adc_read ( struct adc_module *const  module_inst,
uint16_t *  result 
)
inlinestatic

Reads the ADC result.

Reads the result from an ADC conversion that was previously started.

Parameters
[in]module_instPointer to the ADC software instance struct
[out]resultPointer to store the result value in
Returns
Status of the ADC read request.
Return values
STATUS_OKThe result was retrieved successfully
STATUS_BUSYA conversion result was not ready
STATUS_ERR_OVERFLOWThe result register has been overwritten by the ADC module before the result was read by the software

References adc_clear_status(), adc_get_status(), ADC_STATUS_OVERRUN, ADC_STATUS_RESULT_READY, Assert, STATUS_BUSY, STATUS_ERR_OVERFLOW, and STATUS_OK.

Referenced by run_adc_average_mode_test(), and run_adc_polled_mode_test().

enum status_code adc_read_buffer_job ( struct adc_module *const  module_inst,
uint16_t *  buffer,
uint16_t  samples 
)

Read multiple samples from ADC.

Read samples from the ADC into the buffer. If there is no hardware trigger defined (event action) the driver will retrigger the ADC conversion whenever a conversion is complete until samples has been acquired. To avoid jitter in the sampling frequency using an event trigger is advised.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]samplesNumber of samples to acquire
[out]bufferBuffer to store the ADC samples
Returns
Status of the job start.
Return values
STATUS_OKThe conversion job was started successfully and is in progress
STATUS_BUSYThe ADC is already busy with another job

References adc_enable_interrupt(), ADC_INTERRUPT_RESULT_READY, adc_start_conversion(), Assert, STATUS_BUSY, and STATUS_OK.

Referenced by run_adc_callback_mode_test().

void adc_register_callback ( struct adc_module *const  module,
adc_callback_t  callback_func,
enum adc_callback  callback_type 
)

Registers a callback.

Registers a callback function which is implemented by the user.

Note
The callback must be enabled for the interrupt handler to call it when the condition for the callback is met.
Parameters
[in]modulePointer to ADC software instance struct
[in]callback_funcPointer to callback function
[in]callback_typeCallback type given by an enum

References Assert.

Referenced by setup_adc_callback_mode_test(), and setup_adc_window_mode_test().

static enum status_code adc_reset ( struct adc_module *const  module_inst)
inlinestatic

Resets the ADC module.

Resets an ADC module, clearing all module state, and registers to their default values.

Parameters
[in]module_instPointer to the ADC software instance struct

References adc_disable(), Assert, and STATUS_OK.

static void adc_set_master_slave_mode ( struct adc_module *const  master_inst,
struct adc_module *const  slave_inst,
enum adc_dual_mode_trigger_selection  dualsel 
)
inlinestatic

Set ADC master and slave mode.

Enable ADC module Master-Slave Operation and select dual mode trigger.

Parameters
[in]master_instPointer to the master ADC software instance struct
[in]slave_instPointer to the slave ADC software instance struct
[in]dualselDual mode trigger selection

References Assert.

static void adc_set_negative_input ( struct adc_module *const  module_inst,
const enum adc_negative_input  negative_input 
)
inlinestatic

Sets negative ADC input pin for differential mode.

Sets the negative ADC input pin, when the ADC is configured in differential mode.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]negative_inputNegative input pin

References Assert.

static void adc_set_positive_input ( struct adc_module *const  module_inst,
const enum adc_positive_input  positive_input 
)
inlinestatic

Sets positive ADC input pin.

Sets the positive ADC input pin selection.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]positive_inputPositive input pin

References Assert.

void adc_set_window_mode ( struct adc_module *const  module_inst,
const enum adc_window_mode  window_mode,
const int16_t  window_lower_value,
const int16_t  window_upper_value 
)

Sets the ADC window mode.

Sets the ADC window mode to a given mode and value range.

Parameters
[in]module_instPointer to the ADC software instance struct
[in]window_modeWindow monitor mode to set
[in]window_lower_valueLower window monitor threshold value
[in]window_upper_valueUpper window monitor threshold value

References Assert.

static void adc_start_conversion ( struct adc_module *const  module_inst)
inlinestatic

Starts an ADC conversion.

Starts a new ADC conversion.

Parameters
[in]module_instPointer to the ADC software instance struct

References Assert.

Referenced by _adc_interrupt_handler(), adc_read_buffer_job(), run_adc_average_mode_test(), run_adc_polled_mode_test(), and setup_adc_window_mode_test().

void adc_unregister_callback ( struct adc_module *const  module,
enum adc_callback  callback_type 
)

Unregisters a callback.

Unregisters a callback function which is implemented by the user.

Parameters
[in]modulePointer to ADC software instance struct
[in]callback_typeCallback type given by an enum

References Assert.

Referenced by cleanup_adc_callback_mode_test(), and cleanup_adc_window_mode_test().