Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Analog Comparator (AC) Driver

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Analog Comparator functionality, for the comparison of analog voltages against a known reference voltage to determine its relative level.

The following driver API modes are covered by this manual:

The following peripherals are 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

The Analog Comparator module provides an interface for the comparison of one or more analog voltage inputs (sourced from external or internal inputs) against a known reference voltage, to determine if the unknown voltage is higher or lower than the reference. Additionally, window functions are provided so that two comparators can be connected together to determine if an input is below, inside, above, or outside the two reference points of the window.

Each comparator requires two analog input voltages, a positive and negative channel input. The result of the comparison is a binary true if the comparator's positive channel input is higher than the comparator's negative input channel, and false if otherwise.

Driver Feature Macro Definition

Driver Feature Macro Supported devices
FEATURE_AC_HYSTERESIS_LEVEL SAM L21/L22/C20/C21/R34/R35
FEATURE_AC_SYNCBUSY_SCHEME_VERSION_2 SAM L21/L22/C20/C21/R34/R35
FEATURE_AC_RUN_IN_STANDY_EACH_COMPARATOR SAM L21/L22/C20/C21/R34/R35
FEATURE_AC_RUN_IN_STANDY_PAIR_COMPARATOR SAM D20/L22/D21/D10/D11/R21/DA1/HA1/R34/R35
Note
The specific features are only available in the driver when the selected device supports those features.

Window Comparators and Comparator Pairs

Each comparator module contains one or more comparator pairs, a set of two distinct comparators which can be used independently or linked together for Window Comparator mode. In this latter mode, the two comparator units in a comparator pair are linked together to allow the module to detect if an input voltage is below, inside, above, or outside a window set by the upper and lower threshold voltages set by the two comparators. If not required, window comparison mode can be turned off and the two comparator units can be configured and used separately.

Positive and Negative Input MUXes

Each comparator unit requires two input voltages, a positive and a negative channel (note that these names refer to the logical operation that the unit performs, and both voltages should be above GND), which are then compared with one another. Both the positive and the negative channel inputs are connected to a pair of multiplexers (MUXes), which allows one of several possible inputs to be selected for each comparator channel.

The exact channels available for each comparator differ for the positive and the negative inputs, but the same MUX choices are available for all comparator units (i.e. all positive MUXes are identical, all negative MUXes are identical). This allows the user application to select which voltages are compared to one another.

When used in window mode, both comparators in the window pair should have their positive channel input MUXes configured to the same input channel, with the negative channel input MUXes used to set the lower and upper window bounds.

Output Filtering

The output of each comparator unit can either be used directly with no filtering (giving a lower latency signal, with potentially more noise around the comparison threshold) or be passed through a multiple stage digital majority filter. Several filter lengths are available, with the longer stages producing a more stable result, at the expense of a higher latency.

When output filtering is used in single shot mode, a single trigger of the comparator will automatically perform the required number of samples to produce a correctly filtered result.

Input Hysteresis

To prevent unwanted noise around the threshold where the comparator unit's positive and negative input channels are close in voltage to one another, an optional hysteresis can be used to widen the point at which the output result flips. This mode will prevent a change in the comparison output unless the inputs cross one another beyond the hysteresis gap introduces by this mode.

Single Shot and Continuous Sampling Modes

Comparators can be configured to run in either Single Shot or Continuous sampling modes; when in Single Shot mode, the comparator will only perform a comparison (and any resulting filtering, see Output Filtering) when triggered via a software or event trigger. This mode improves the power efficiency of the system by only performing comparisons when actually required by the application.

For systems requiring a lower latency or more frequent comparisons, continuous mode will place the comparator into continuous sampling mode, which increases the module's power consumption, but decreases the latency between each comparison result by automatically performing a comparison on every cycle of the module's clock.

Events

Each comparator unit is capable of being triggered by both software and hardware triggers. Hardware input events allow for other peripherals to automatically trigger a comparison on demand - for example, a timer output event could be used to trigger comparisons at a desired regular interval.

The module's output events can similarly be used to trigger other hardware modules each time a new comparison result is available. This scheme allows for reduced levels of CPU usage in an application and lowers the overall system response latency by directly triggering hardware peripherals from one another without requiring software intervention.

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.

Physical Connection

Physically, the modules are interconnected within the device as shown in the diagram below.

Special Considerations

The number of comparator pairs (and, thus, window comparators) within a single hardware instance of the Analog Comparator module is device-specific. Some devices will contain a single comparator pair, while others may have two pairs; refer to your device specific datasheet for details.

Extra Information

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

Examples

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

API Overview

Modules

 

Data Structures

struct  ac_chan_config
 Analog Comparator Comparator channel configuration structure. More...
 
struct  ac_config
 Analog Comparator module configuration structure. More...
 
struct  ac_events
 AC event enable/disable structure. More...
 
struct  ac_module
 AC software device instance structure. More...
 
struct  ac_win_config
 Analog Comparator Window configuration structure. More...
 

Typedefs

typedef void(* ac_callback_t )(struct ac_module *const module_inst)
 Type definition for a AC module callback function. More...
 

Enumerations

enum  ac_callback {
  AC_CALLBACK_COMPARATOR_0 = 0,
  AC_CALLBACK_COMPARATOR_1 = 1,
  AC_CALLBACK_WINDOW_0 = 4
}
 Enum for possible callback types for the AC module. More...
 
enum  ac_chan_channel {
  AC_CHAN_CHANNEL_0 = 0,
  AC_CHAN_CHANNEL_1 = 1,
  AC_CHAN_CHANNEL_2 = 2,
  AC_CHAN_CHANNEL_3 = 3
}
 AC comparator channel selection enum. More...
 
enum  ac_chan_filter {
  AC_CHAN_FILTER_NONE = AC_COMPCTRL_FLEN_OFF,
  AC_CHAN_FILTER_MAJORITY_3 = AC_COMPCTRL_FLEN_MAJ3,
  AC_CHAN_FILTER_MAJORITY_5 = AC_COMPCTRL_FLEN_MAJ5
}
 AC channel output filtering configuration enum. More...
 
enum  ac_chan_interrupt_selection {
  AC_CHAN_INTERRUPT_SELECTION_TOGGLE = AC_COMPCTRL_INTSEL_TOGGLE,
  AC_CHAN_INTERRUPT_SELECTION_RISING = AC_COMPCTRL_INTSEL_RISING,
  AC_CHAN_INTERRUPT_SELECTION_FALLING = AC_COMPCTRL_INTSEL_FALLING,
  AC_CHAN_INTERRUPT_SELECTION_END_OF_COMPARE = AC_COMPCTRL_INTSEL_EOC
}
 Channel interrupt selection enum. More...
 
enum  ac_chan_neg_mux {
  AC_CHAN_NEG_MUX_PIN0 = AC_COMPCTRL_MUXNEG_PIN0,
  AC_CHAN_NEG_MUX_PIN1 = AC_COMPCTRL_MUXNEG_PIN1,
  AC_CHAN_NEG_MUX_PIN2 = AC_COMPCTRL_MUXNEG_PIN2,
  AC_CHAN_NEG_MUX_PIN3 = AC_COMPCTRL_MUXNEG_PIN3,
  AC_CHAN_NEG_MUX_GND = AC_COMPCTRL_MUXNEG_GND,
  AC_CHAN_NEG_MUX_SCALED_VCC = AC_COMPCTRL_MUXNEG_VSCALE,
  AC_CHAN_NEG_MUX_BANDGAP = AC_COMPCTRL_MUXNEG_BANDGAP,
  AC_CHAN_NEG_MUX_DAC0 = AC_COMPCTRL_MUXNEG_DAC
}
 AC channel negative comparator pin input configuration enum. More...
 
enum  ac_chan_output {
  AC_CHAN_OUTPUT_INTERNAL = AC_COMPCTRL_OUT_OFF,
  AC_CHAN_OUTPUT_ASYNCRONOUS = AC_COMPCTRL_OUT_ASYNC,
  AC_CHAN_OUTPUT_SYNCHRONOUS = AC_COMPCTRL_OUT_SYNC
}
 AC channel GPIO output routing configuration enum. More...
 
enum  ac_chan_pos_mux {
  AC_CHAN_POS_MUX_PIN0 = AC_COMPCTRL_MUXPOS_PIN0,
  AC_CHAN_POS_MUX_PIN1 = AC_COMPCTRL_MUXPOS_PIN1,
  AC_CHAN_POS_MUX_PIN2 = AC_COMPCTRL_MUXPOS_PIN2,
  AC_CHAN_POS_MUX_PIN3 = AC_COMPCTRL_MUXPOS_PIN3
}
 AC channel positive comparator pin input configuration enum. More...
 
enum  ac_chan_sample_mode {
  AC_CHAN_MODE_CONTINUOUS = 0,
  AC_CHAN_MODE_SINGLE_SHOT = AC_COMPCTRL_SINGLE
}
 AC channel input sampling mode configuration enum. More...
 
enum  ac_hysteresis_level {
  AC_HYSTERESIS_LEVEL_50 = 0,
  AC_HYSTERESIS_LEVEL_70,
  AC_HYSTERESIS_LEVEL_90,
  AC_HYSTERESIS_LEVEL_110
}
 Enum for possible hysteresis level types for AC module. More...
 
enum  ac_win_channel {
  AC_WIN_CHANNEL_0 = 0,
  AC_WIN_CHANNEL_1 = 1
}
 AC window channel selection enum. More...
 
enum  ac_win_interrupt_selection {
  AC_WIN_INTERRUPT_SELECTION_ABOVE = AC_WINCTRL_WINTSEL0_ABOVE,
  AC_WIN_INTERRUPT_SELECTION_INSIDE = AC_WINCTRL_WINTSEL0_INSIDE,
  AC_WIN_INTERRUPT_SELECTION_BELOW = AC_WINCTRL_WINTSEL0_BELOW,
  AC_WIN_INTERRUPT_SELECTION_OUTSIDE = AC_WINCTRL_WINTSEL0_OUTSIDE
}
 Window interrupt selection enum. More...
 

Driver Feature Definition

Define AC driver feature set according to different device family.

#define FEATURE_AC_HYSTERESIS_LEVEL
 Setting of hysteresis level. More...
 
#define FEATURE_AC_SYNCBUSY_SCHEME_VERSION_2
 SYNCBUSY scheme version 2. More...
 
#define FEATURE_AC_RUN_IN_STANDY_EACH_COMPARATOR
 Run in standby feature for each comparator. More...
 

AC Window Channel Status Flags

AC window channel status flags, returned by ac_win_get_status().

#define AC_WIN_STATUS_UNKNOWN   (1UL << 0)
 Unknown output state; the comparator window channel was not ready. More...
 
#define AC_WIN_STATUS_ABOVE   (1UL << 1)
 Window Comparator's input voltage is above the window. More...
 
#define AC_WIN_STATUS_INSIDE   (1UL << 2)
 Window Comparator's input voltage is inside the window. More...
 
#define AC_WIN_STATUS_BELOW   (1UL << 3)
 Window Comparator's input voltage is below the window. More...
 
#define AC_WIN_STATUS_INTERRUPT_SET   (1UL << 4)
 This state reflects the window interrupt flag. More...
 

AC Channel Status Flags

AC channel status flags, returned by ac_chan_get_status().

#define AC_CHAN_STATUS_UNKNOWN   (1UL << 0)
 Unknown output state; the comparator channel was not ready. More...
 
#define AC_CHAN_STATUS_NEG_ABOVE_POS   (1UL << 1)
 Comparator's negative input pin is higher in voltage than the positive input pin. More...
 
#define AC_CHAN_STATUS_POS_ABOVE_NEG   (1UL << 2)
 Comparator's positive input pin is higher in voltage than the negative input pin. More...
 
#define AC_CHAN_STATUS_INTERRUPT_SET   (1UL << 3)
 This state reflects the channel interrupt flag. More...
 

Configuration and Initialization

enum status_code ac_reset (struct ac_module *const module_inst)
 Resets and disables the Analog Comparator driver. More...
 
enum status_code ac_init (struct ac_module *const module_inst, Ac *const hw, struct ac_config *const config)
 Initializes and configures the Analog Comparator driver. More...
 
static bool ac_is_syncing (struct ac_module *const module_inst)
 Determines if the hardware module(s) are currently synchronizing to the bus. More...
 
static void ac_get_config_defaults (struct ac_config *const config)
 Initializes all members of an Analog Comparator configuration structure to safe defaults. More...
 
static void ac_enable (struct ac_module *const module_inst)
 Enables an Analog Comparator that was previously configured. More...
 
static void ac_disable (struct ac_module *const module_inst)
 Disables an Analog Comparator that was previously enabled. More...
 
static void ac_enable_events (struct ac_module *const module_inst, struct ac_events *const events)
 Enables an Analog Comparator event input or output. More...
 
static void ac_disable_events (struct ac_module *const module_inst, struct ac_events *const events)
 Disables an Analog Comparator event input or output. More...
 

Channel Configuration and Initialization

static void ac_chan_get_config_defaults (struct ac_chan_config *const config)
 Initializes all members of an Analog Comparator channel configuration structure to safe defaults. More...
 
enum status_code ac_chan_set_config (struct ac_module *const module_inst, const enum ac_chan_channel channel, struct ac_chan_config *const config)
 Writes an Analog Comparator channel configuration to the hardware module. More...
 
static void ac_chan_enable (struct ac_module *const module_inst, const enum ac_chan_channel channel)
 Enables an Analog Comparator channel that was previously configured. More...
 
static void ac_chan_disable (struct ac_module *const module_inst, const enum ac_chan_channel channel)
 Disables an Analog Comparator channel that was previously enabled. More...
 

Channel Control

static void ac_chan_trigger_single_shot (struct ac_module *const module_inst, const enum ac_chan_channel channel)
 Triggers a comparison on a comparator that is configured in single shot mode. More...
 
static bool ac_chan_is_ready (struct ac_module *const module_inst, const enum ac_chan_channel channel)
 Determines if a given comparator channel is ready for comparisons. More...
 
static uint8_t ac_chan_get_status (struct ac_module *const module_inst, const enum ac_chan_channel channel)
 Determines the output state of a comparator channel. More...
 
static void ac_chan_clear_status (struct ac_module *const module_inst, const enum ac_chan_channel channel)
 Clears an interrupt status flag. More...
 

Window Mode Configuration and Initialization

static void ac_win_get_config_defaults (struct ac_win_config *const config)
 Initializes an Analog Comparator window configuration structure to defaults. More...
 
enum status_code ac_win_set_config (struct ac_module *const module_inst, enum ac_win_channel const win_channel, struct ac_win_config *const config)
 Function used to setup interrupt selection of a window. More...
 
enum status_code ac_win_enable (struct ac_module *const module_inst, const enum ac_win_channel win_channel)
 Enables an Analog Comparator window channel that was previously configured. More...
 
void ac_win_disable (struct ac_module *const module_inst, const enum ac_win_channel win_channel)
 Disables an Analog Comparator window channel that was previously enabled. More...
 

Window Mode Control

static bool ac_win_is_ready (struct ac_module *const module_inst, const enum ac_win_channel win_channel)
 Determines if a given Window Comparator is ready for comparisons. More...
 
uint8_t ac_win_get_status (struct ac_module *const module_inst, const enum ac_win_channel win_channel)
 Determines the state of a specified Window Comparator. More...
 
static void ac_win_clear_status (struct ac_module *const module_inst, const enum ac_win_channel win_channel)
 Clears an interrupt status flag. More...
 

#define AC_CHAN_STATUS_INTERRUPT_SET   (1UL << 3)

This state reflects the channel interrupt flag.

When the interrupt flag should be set is configured in ac_chan_set_config(). This state needs to be cleared by the of ac_chan_clear_status().

Referenced by ac_chan_get_status().

#define AC_CHAN_STATUS_NEG_ABOVE_POS   (1UL << 1)

Comparator's negative input pin is higher in voltage than the positive input pin.

Referenced by ac_chan_get_status(), main(), and run_ac_single_shot_test().

#define AC_CHAN_STATUS_POS_ABOVE_NEG   (1UL << 2)

Comparator's positive input pin is higher in voltage than the negative input pin.

Referenced by ac_chan_get_status(), and run_ac_single_shot_test().

#define AC_CHAN_STATUS_UNKNOWN   (1UL << 0)

Unknown output state; the comparator channel was not ready.

Referenced by ac_chan_get_status(), main(), and run_ac_single_shot_test().

#define AC_WIN_STATUS_ABOVE   (1UL << 1)

Window Comparator's input voltage is above the window.

Referenced by ac_win_get_status(), and run_ac_window_mode_test().

#define AC_WIN_STATUS_BELOW   (1UL << 3)

Window Comparator's input voltage is below the window.

Referenced by ac_win_get_status(), and run_ac_window_mode_test().

#define AC_WIN_STATUS_INSIDE   (1UL << 2)

Window Comparator's input voltage is inside the window.

Referenced by ac_win_get_status(), and run_ac_window_mode_test().

#define AC_WIN_STATUS_INTERRUPT_SET   (1UL << 4)

This state reflects the window interrupt flag.

When the interrupt flag should be set is configured in ac_win_set_config(). This state needs to be cleared by the of ac_win_clear_status().

Referenced by ac_win_get_status().

#define AC_WIN_STATUS_UNKNOWN   (1UL << 0)

Unknown output state; the comparator window channel was not ready.

Referenced by ac_win_get_status(), and run_ac_window_mode_test().

#define FEATURE_AC_HYSTERESIS_LEVEL

Setting of hysteresis level.

#define FEATURE_AC_RUN_IN_STANDY_EACH_COMPARATOR

Run in standby feature for each comparator.

#define FEATURE_AC_SYNCBUSY_SCHEME_VERSION_2

SYNCBUSY scheme version 2.

typedef void(* ac_callback_t)(struct ac_module *const module_inst)

Type definition for a AC module callback function.

Enum for possible callback types for the AC module.

Enumerator
AC_CALLBACK_COMPARATOR_0 

Callback for comparator 0.

AC_CALLBACK_COMPARATOR_1 

Callback for comparator 1.

AC_CALLBACK_WINDOW_0 

Callback for window 0.

AC comparator channel selection enum.

Enum for the possible comparator channels.

Enumerator
AC_CHAN_CHANNEL_0 

Comparator channel 0 (Pair 0, Comparator 0)

AC_CHAN_CHANNEL_1 

Comparator channel 1 (Pair 0, Comparator 1)

AC_CHAN_CHANNEL_2 

Comparator channel 2 (Pair 1, Comparator 0)

AC_CHAN_CHANNEL_3 

Comparator channel 3 (Pair 1, Comparator 1)

AC channel output filtering configuration enum.

Enum for the possible channel output filtering configurations of an Analog Comparator channel.

Enumerator
AC_CHAN_FILTER_NONE 

No output filtering is performed on the comparator channel.

AC_CHAN_FILTER_MAJORITY_3 

Comparator channel output is passed through a Majority-of-Three filter.

AC_CHAN_FILTER_MAJORITY_5 

Comparator channel output is passed through a Majority-of-Five filter.

Channel interrupt selection enum.

This enum is used to select when a channel interrupt should occur.

Enumerator
AC_CHAN_INTERRUPT_SELECTION_TOGGLE 

An interrupt will be generated when the comparator level is passed.

AC_CHAN_INTERRUPT_SELECTION_RISING 

An interrupt will be generated when the measurement goes above the compare level.

AC_CHAN_INTERRUPT_SELECTION_FALLING 

An interrupt will be generated when the measurement goes below the compare level.

AC_CHAN_INTERRUPT_SELECTION_END_OF_COMPARE 

An interrupt will be generated when a new measurement is complete.

Interrupts will only be generated in single shot mode. This state needs to be cleared by the use of ac_chan_cleare_status()

AC channel negative comparator pin input configuration enum.

Enum for the possible channel negative pin input of an Analog Comparator channel.

Enumerator
AC_CHAN_NEG_MUX_PIN0 

Negative comparator input is connected to physical AC input pin 0.

AC_CHAN_NEG_MUX_PIN1 

Negative comparator input is connected to physical AC input pin 1.

AC_CHAN_NEG_MUX_PIN2 

Negative comparator input is connected to physical AC input pin 2.

AC_CHAN_NEG_MUX_PIN3 

Negative comparator input is connected to physical AC input pin 3.

AC_CHAN_NEG_MUX_GND 

Negative comparator input is connected to the internal ground plane.

AC_CHAN_NEG_MUX_SCALED_VCC 

Negative comparator input is connected to the channel's internal VCC plane voltage scalar.

AC_CHAN_NEG_MUX_BANDGAP 

Negative comparator input is connected to the internal band gap voltage reference.

AC_CHAN_NEG_MUX_DAC0 

For SAM D20/D21/D10/D11/R21/DA1/HA1: Negative comparator input is connected to the channel's internal DAC channel 0 output.

For SAM L21/C20/C21: Negative comparator input is connected to the channel's internal DAC channel 0 output for Comparator 0 or OPAMP output for Comparator 1.

AC channel GPIO output routing configuration enum.

Enum for the possible channel GPIO output routing configurations of an Analog Comparator channel.

Enumerator
AC_CHAN_OUTPUT_INTERNAL 

Comparator channel output is not routed to a physical GPIO pin, and is used internally only.

AC_CHAN_OUTPUT_ASYNCRONOUS 

Comparator channel output is routed to its matching physical GPIO pin, via an asynchronous path.

AC_CHAN_OUTPUT_SYNCHRONOUS 

Comparator channel output is routed to its matching physical GPIO pin, via a synchronous path.

AC channel positive comparator pin input configuration enum.

Enum for the possible channel positive pin input of an Analog Comparator channel.

Enumerator
AC_CHAN_POS_MUX_PIN0 

Positive comparator input is connected to physical AC input pin 0.

AC_CHAN_POS_MUX_PIN1 

Positive comparator input is connected to physical AC input pin 1.

AC_CHAN_POS_MUX_PIN2 

Positive comparator input is connected to physical AC input pin 2.

AC_CHAN_POS_MUX_PIN3 

Positive comparator input is connected to physical AC input pin 3.

AC channel input sampling mode configuration enum.

Enum for the possible channel sampling modes of an Analog Comparator channel.

Enumerator
AC_CHAN_MODE_CONTINUOUS 

Continuous sampling mode; when the channel is enabled the comparator output is available for reading at any time.

AC_CHAN_MODE_SINGLE_SHOT 

Single shot mode; when used the comparator channel must be triggered to perform a comparison before reading the result.

Enum for possible hysteresis level types for AC module.

Enumerator
AC_HYSTERESIS_LEVEL_50 

Hysteresis level of 50mV.

AC_HYSTERESIS_LEVEL_70 

Hysteresis level of 70mV.

AC_HYSTERESIS_LEVEL_90 

Hysteresis level of 90mV.

AC_HYSTERESIS_LEVEL_110 

Hysteresis level of 110mV.

AC window channel selection enum.

Enum for the possible window comparator channels.

Enumerator
AC_WIN_CHANNEL_0 

Window channel 0 (Pair 0, Comparators 0 and 1)

AC_WIN_CHANNEL_1 

Window channel 1 (Pair 1, Comparators 2 and 3)

Window interrupt selection enum.

This enum is used to select when a window interrupt should occur.

Enumerator
AC_WIN_INTERRUPT_SELECTION_ABOVE 

Interrupt is generated when the compare value goes above the window.

AC_WIN_INTERRUPT_SELECTION_INSIDE 

Interrupt is generated when the compare value goes inside the window.

AC_WIN_INTERRUPT_SELECTION_BELOW 

Interrupt is generated when the compare value goes below the window.

AC_WIN_INTERRUPT_SELECTION_OUTSIDE 

Interrupt is generated when the compare value goes outside the window.

static void ac_chan_clear_status ( struct ac_module *const  module_inst,
const enum ac_chan_channel  channel 
)
inlinestatic

Clears an interrupt status flag.

This function is used to clear the AC_CHAN_STATUS_INTERRUPT_SET flag it will clear the flag for the channel indicated by the channel argument.

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]channelComparator channel to clear

References Assert.

Referenced by run_ac_single_shot_test(), and run_ac_window_mode_test().

static void ac_chan_disable ( struct ac_module *const  module_inst,
const enum ac_chan_channel  channel 
)
inlinestatic

Disables an Analog Comparator channel that was previously enabled.

Stops an Analog Comparator channel that was previously started via a call to ac_chan_enable().

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]channelComparator channel to disable

References ac_is_syncing(), and Assert.

static void ac_chan_enable ( struct ac_module *const  module_inst,
const enum ac_chan_channel  channel 
)
inlinestatic

Enables an Analog Comparator channel that was previously configured.

Enables an Analog Comparator channel that was previously configured via a call to ac_chan_set_config().

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]channelComparator channel to enable

References ac_is_syncing(), and Assert.

Referenced by configure_ac_channel(), run_ac_init_test(), setup_ac_callback_mode_test(), and setup_ac_window_mode_test().

static void ac_chan_get_config_defaults ( struct ac_chan_config *const  config)
inlinestatic

Initializes all members of an Analog Comparator channel configuration structure to safe defaults.

Initializes all members of an Analog Comparator channel configuration structure to safe defaults. This function should be called on all new instances of these configuration structures before being modified by the user application.

The default configuration is as follows:

  • Continuous sampling mode
  • Majority of five sample output filter
  • Comparator disabled during sleep mode (if has this feature)
  • Hysteresis enabled on the input pins
  • Hysteresis level of 50mV if having this feature
  • Internal comparator output mode
  • Comparator pin multiplexer 0 selected as the positive input
  • Scaled VCC voltage selected as the negative input
  • VCC voltage scaler set for a division factor of two
  • Channel interrupt set to occur when the compare threshold is passed
Parameters
[out]configChannel configuration structure to initialize to default values

References AC_CHAN_FILTER_MAJORITY_5, AC_CHAN_INTERRUPT_SELECTION_TOGGLE, AC_CHAN_MODE_CONTINUOUS, AC_CHAN_NEG_MUX_SCALED_VCC, AC_CHAN_OUTPUT_INTERNAL, AC_CHAN_POS_MUX_PIN0, AC_HYSTERESIS_LEVEL_50, Assert, ac_chan_config::enable_hysteresis, ac_chan_config::filter, ac_chan_config::hysteresis_level, ac_chan_config::interrupt_selection, ac_chan_config::negative_input, ac_chan_config::output_mode, ac_chan_config::positive_input, ac_chan_config::run_in_standby, ac_chan_config::sample_mode, and ac_chan_config::vcc_scale_factor.

Referenced by configure_ac_channel(), run_ac_init_test(), setup_ac_callback_mode_test(), and setup_ac_window_mode_test().

static uint8_t ac_chan_get_status ( struct ac_module *const  module_inst,
const enum ac_chan_channel  channel 
)
inlinestatic

Determines the output state of a comparator channel.

Retrieves the last comparison value (after filtering) of a given comparator. If the comparator was not ready at the time of the check, the comparison result will be indicated as being unknown.

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]channelComparator channel to test
Returns
Bit mask of comparator channel status flags.

References ac_chan_is_ready(), AC_CHAN_STATUS_INTERRUPT_SET, AC_CHAN_STATUS_NEG_ABOVE_POS, AC_CHAN_STATUS_POS_ABOVE_NEG, AC_CHAN_STATUS_UNKNOWN, and Assert.

Referenced by main(), and run_ac_single_shot_test().

static bool ac_chan_is_ready ( struct ac_module *const  module_inst,
const enum ac_chan_channel  channel 
)
inlinestatic

Determines if a given comparator channel is ready for comparisons.

Checks a comparator channel to see if the comparator is currently ready to begin comparisons.

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]channelComparator channel to test
Returns
Comparator channel readiness state.

References Assert.

Referenced by ac_chan_get_status(), ac_win_is_ready(), main(), and run_ac_single_shot_test().

enum status_code ac_chan_set_config ( struct ac_module *const  module_inst,
const enum ac_chan_channel  channel,
struct ac_chan_config *const  config 
)

Writes an Analog Comparator channel configuration to the hardware module.

Writes a given Analog Comparator channel configuration to the hardware module.

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]channelAnalog Comparator channel to configure
[in]configPointer to the channel configuration struct

References ac_is_syncing(), Assert, ac_chan_config::filter, ac_chan_config::interrupt_selection, ac_chan_config::negative_input, ac_chan_config::output_mode, ac_chan_config::positive_input, ac_chan_config::run_in_standby, ac_chan_config::sample_mode, STATUS_OK, and ac_chan_config::vcc_scale_factor.

Referenced by configure_ac_channel(), run_ac_init_test(), setup_ac_callback_mode_test(), and setup_ac_window_mode_test().

static void ac_chan_trigger_single_shot ( struct ac_module *const  module_inst,
const enum ac_chan_channel  channel 
)
inlinestatic

Triggers a comparison on a comparator that is configured in single shot mode.

Triggers a single conversion on a comparator configured to compare on demand (single shot mode) rather than continuously.

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]channelComparator channel to trigger

References Assert.

Referenced by main(), run_ac_single_shot_test(), and run_ac_window_mode_test().

static void ac_disable ( struct ac_module *const  module_inst)
inlinestatic

Disables an Analog Comparator that was previously enabled.

Disables an Analog Comparator that was previously started via a call to ac_enable().

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral

References ac_is_syncing(), and Assert.

Referenced by ac_reset().

static void ac_disable_events ( struct ac_module *const  module_inst,
struct ac_events *const  events 
)
inlinestatic

Disables an Analog Comparator event input or output.

Disables one or more input or output events to or from the Analog Comparator module. See ac_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 Analog Comparator peripheral
[in]eventsStruct containing flags of events to disable

References Assert, ac_events::generate_event_on_state, ac_events::generate_event_on_window, i, and ac_events::on_event_sample.

static void ac_enable ( struct ac_module *const  module_inst)
inlinestatic

Enables an Analog Comparator that was previously configured.

Enables an Analog Comparator that was previously configured via a call to ac_init().

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral

References ac_is_syncing(), and Assert.

Referenced by main(), run_ac_init_test(), setup_ac_callback_mode_test(), and setup_ac_window_mode_test().

static void ac_enable_events ( struct ac_module *const  module_inst,
struct ac_events *const  events 
)
inlinestatic

Enables an Analog Comparator event input or output.

Enables one or more input or output events to or from the Analog Comparator module. See ac_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 Analog Comparator peripheral
[in]eventsStruct containing flags of events to enable

References Assert, ac_events::generate_event_on_state, ac_events::generate_event_on_window, i, and ac_events::on_event_sample.

static void ac_get_config_defaults ( struct ac_config *const  config)
inlinestatic

Initializes all members of an Analog Comparator configuration structure to safe defaults.

Initializes all members of a given Analog Comparator configuration structure to safe known default values. This function should be called on all new instances of these configuration structures before being modified by the user application.

The default configuration is as follows:

  • All comparator pairs disabled during sleep mode (if has this feature)
  • Generator 0 is the default GCLK generator
Parameters
[out]configConfiguration structure to initialize to default values

References Assert, GCLK_GENERATOR_0, GCLK_GENERATOR_3, i, and ac_config::source_generator.

Referenced by configure_ac(), run_ac_init_test(), setup_ac_callback_mode_test(), and setup_ac_window_mode_test().

enum status_code ac_init ( struct ac_module *const  module_inst,
Ac *const  hw,
struct ac_config *const  config 
)

Initializes and configures the Analog Comparator driver.

Initializes the Analog Comparator driver, configuring it to the user supplied configuration parameters, ready for use. This function should be called before enabling the Analog Comparator.

Note
Once called the Analog Comparator will not be running; to start the Analog Comparator call ac_enable() after configuring the module.
Parameters
[out]module_instPointer to the AC software instance struct
[in]hwPointer to the AC module instance
[in]configPointer to the config struct, created by the user application

References _ac_instance, _ac_set_config(), Assert, i, module_inst, NULL, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBC, and SYSTEM_CLOCK_APB_APBD.

Referenced by configure_ac(), run_ac_init_test(), setup_ac_callback_mode_test(), and setup_ac_window_mode_test().

static bool ac_is_syncing ( struct ac_module *const  module_inst)
inlinestatic

Determines if the hardware module(s) are currently synchronizing to the bus.

Checks to see if the underlying hardware peripheral module(s) are currently synchronizing across multiple clock domains to the hardware bus. This function can be used to delay further operations on a module until such time that it is ready, to prevent blocking delays for synchronization in the user application.

Parameters
[in]module_instPointer to the AC software instance struct
Returns
Synchronization status of the underlying hardware module(s).
Return values
falseIf the module has completed synchronization
tureIf the module synchronization is ongoing

References Assert.

Referenced by ac_chan_disable(), ac_chan_enable(), ac_chan_set_config(), ac_disable(), ac_enable(), ac_reset(), ac_win_disable(), and ac_win_enable().

enum status_code ac_reset ( struct ac_module *const  module_inst)

Resets and disables the Analog Comparator driver.

Resets and disables the Analog Comparator driver, resets the internal states and registers of the hardware module to their power-on defaults.

Parameters
[out]module_instPointer to the AC software instance struct

References ac_disable(), ac_is_syncing(), Assert, and STATUS_OK.

Referenced by setup_ac_callback_mode_test(), and setup_ac_window_mode_test().

static void ac_win_clear_status ( struct ac_module *const  module_inst,
const enum ac_win_channel  win_channel 
)
inlinestatic

Clears an interrupt status flag.

This function is used to clear the AC_WIN_STATUS_INTERRUPT_SET flag it will clear the flag for the channel indicated by the win_channel argument.

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]win_channelWindow channel to clear

References Assert.

Referenced by run_ac_window_mode_test().

void ac_win_disable ( struct ac_module *const  module_inst,
const enum ac_win_channel  win_channel 
)

Disables an Analog Comparator window channel that was previously enabled.

Stops an Analog Comparator window channel that was previously started via a call to ac_win_enable().

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]win_channelComparator window channel to disable

References ac_is_syncing(), AC_WIN_CHANNEL_0, AC_WIN_CHANNEL_1, and Assert.

enum status_code ac_win_enable ( struct ac_module *const  module_inst,
const enum ac_win_channel  win_channel 
)

Enables an Analog Comparator window channel that was previously configured.

Enables and starts an Analog Comparator window channel.

Note
The comparator channels used by the window channel must be configured and enabled before calling this function. The two comparator channels forming each window comparator pair must have identical configurations other than the negative pin multiplexer setting.
Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]win_channelComparator window channel to enable
Returns
Status of the window enable procedure.
Return values
STATUS_OKThe window comparator was enabled
STATUS_ERR_IOOne or both comparators in the window comparator pair is disabled
STATUS_ERR_BAD_FORMATThe comparator channels in the window pair were not configured correctly

References ac_is_syncing(), AC_WIN_CHANNEL_0, AC_WIN_CHANNEL_1, Assert, STATUS_ERR_BAD_FORMAT, STATUS_ERR_IO, and STATUS_OK.

Referenced by setup_ac_window_mode_test().

static void ac_win_get_config_defaults ( struct ac_win_config *const  config)
inlinestatic

Initializes an Analog Comparator window configuration structure to defaults.

Initializes a given Analog Comparator channel configuration structure to a set of known default values. This function should be called if window interrupts are needed and before ac_win_set_config().

The default configuration is as follows:

  • Channel interrupt set to occur when the measurement is above the window
Parameters
[out]configWindow configuration structure to initialize to default values

References AC_WIN_INTERRUPT_SELECTION_ABOVE, Assert, and ac_win_config::interrupt_selection.

Referenced by setup_ac_window_mode_test().

uint8_t ac_win_get_status ( struct ac_module *const  module_inst,
const enum ac_win_channel  win_channel 
)

Determines the state of a specified Window Comparator.

Retrieves the current window detection state, indicating what the input signal is currently comparing to relative to the window boundaries.

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]win_channelComparator Window channel to test
Returns
Bit mask of Analog Comparator window channel status flags.

References ac_win_is_ready(), AC_WIN_STATUS_ABOVE, AC_WIN_STATUS_BELOW, AC_WIN_STATUS_INSIDE, AC_WIN_STATUS_INTERRUPT_SET, AC_WIN_STATUS_UNKNOWN, and Assert.

Referenced by run_ac_window_mode_test().

static bool ac_win_is_ready ( struct ac_module *const  module_inst,
const enum ac_win_channel  win_channel 
)
inlinestatic

Determines if a given Window Comparator is ready for comparisons.

Checks a Window Comparator to see if the both comparators used for window detection is currently ready to begin comparisons.

Parameters
[in]module_instSoftware instance for the Analog Comparator peripheral
[in]win_channelWindow Comparator channel to test
Returns
Window Comparator channel readiness state.

References ac_chan_is_ready(), and Assert.

Referenced by ac_win_get_status(), and run_ac_window_mode_test().

enum status_code ac_win_set_config ( struct ac_module *const  module_inst,
enum ac_win_channel const  win_channel,
struct ac_win_config *const  config 
)

Function used to setup interrupt selection of a window.

This function is used to setup when an interrupt should occur for a given window.

Note
This must be done before enabling the channel.
Parameters
[in]module_instPointer to software instance struct
[in]win_channelWindow channel to setup
[in]configConfiguration for the given window channel
Return values
STATUS_OKFunction exited successful
STATUS_ERR_INVALID_ARGwin_channel argument incorrect

References AC_WIN_CHANNEL_0, AC_WIN_CHANNEL_1, Assert, ac_win_config::interrupt_selection, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by setup_ac_window_mode_test().