S32 SDK

Detailed Description

Analog to Digital Converter Peripheral Driver.

Hardware background

The ADC of the S32K144 is a selectable resolution (8, 10, 12-bit), single-ended, SAR converter. It has 20 selectable input channels (16 external, 4 internal) and 16 control channels (each with a result register, a channel selection and interrupt enable).

Sample time is configurable through selection of A/D clock and a configurable sample time (in A/D clocks).

Also provided are the Hardware Average and Hardware Compare Features.

Hardware Average will sample a selectable number of measurements and average them before signaling a Conversion Complete.

Hardware Compare can be used to signal if an input channel goes outside (or inside) of a predefined range.

The Calibration features can be used to automatically calibrate or fine-tune the ADC before use.

Driver consideration

The ADC Driver provides access to all features, but not all need to be configured to use the ADC. The user application can use the default for most settings, changing only what is necessary. For example, if Compare or Average features are not used, the user does not need to configure them.

The Driver uses structures for configuration. Each structure contains members that are specific to its respective functionality. There is a converter structure, a hardware compare structure, a hardware average structure and a calibration structure. Each struct has a corresponding InitStruct() method that can be used to initialize the members to reset values, so the user can change only the values that are specific to the application.

All methods that access the hardware layer will return an error code to signal if the operation succeeded or failed. These values are defined by the adc_drv_status_t enumeration, and the possible values are:

Interrupt handling

The ADC Driver in S32 SDK does not use interrupts internally. These can be defined by the user application. There are two ways to add an ADC interrupt:

  1. Using the weak symbols defined by start-up code. if the methods ADCx_Handler(void) (x denotes instance number) are not defined, the linker use a default ISR. An error will be generated if methods with the same name are defined multiple times. This method works regardless of the placement of the interrupt vector table (Flash or RAM).
  2. Using the Interrupt Manager's INT_SYS_InstallHandler() method. This can be used to dynamically change the ISR at run-time. This method works only if the interrupt vector table is located in RAM (S32 SDK behavior). To get the ADC instance's interrupt number, use ADC_DRV_GetInterruptNumber().

Clocking and pin configuration

The ADC Driver does not handle clock setup (from PCC) or any kind of pin configuration (done by PORT module). This is handled by the Clock Manager and PORT module, respectively. The driver assumes that correct clock configurations have been made, so it is the user's responsibility to set up clocking and pin configurations correctly.

Data Structures

struct  adc_converter_config_t
 Defines the converter configuration. More...
 
struct  adc_compare_config_t
 Defines the hardware compare configuration. More...
 
struct  adc_average_config_t
 Defines the hardware average configuration. More...
 
struct  adc_chan_config_t
 Defines the control channel configuration. More...
 
struct  adc_calibration_t
 Defines the user calibration configuration. More...
 

Enumerations

enum  adc_latch_clear_t { ADC_LATCH_CLEAR_WAIT, ADC_LATCH_CLEAR_FORCE }
 Defines the trigger latch clear method Implements : adc_latch_clear_t_Class. More...
 

Converter

Converter specific methods. These are used to configure and use the A/D Converter specific functionality, including:

  • clock input and divider
  • sample time in A/D clocks
  • resolution
  • trigger source
  • voltage reference
  • enable DMA
  • enable continuous conversion on one channel

To start a conversion, a control channel (see Channel Configuration) and a trigger source must be configured. Once a conversion is started, the user application can wait for it to be finished by calling the ADC_DRV_WaitConvDone() function.

Only the first control channel can be triggered by software. To start a conversion in this case, an input channel must be written in the channel selection register using the ADC_DRV_ConfigChan() method. Writing a value to the control channel while a conversion is being performed on that channel will start a new conversion.

void ADC_DRV_InitConverterStruct (adc_converter_config_t *const config)
 Initializes the converter configuration structure. More...
 
void ADC_DRV_ConfigConverter (const uint32_t instance, const adc_converter_config_t *const config)
 Configures the converter with the given configuration structure. More...
 
void ADC_DRV_GetConverterConfig (const uint32_t instance, adc_converter_config_t *const config)
 Gets the current converter configuration. More...
 
void ADC_DRV_Reset (const uint32_t instance)
 Resets the converter (sets all configurations to reset values) More...
 
void ADC_DRV_WaitConvDone (const uint32_t instance)
 Waits for a conversion/calibration to finish. More...
 

Hardware Compare

The Hardware Compare feature of the S32K144 ADC is a versatile mechanism that can be used to monitor that a value is within certain values. Measurements can be monitored to be within certain ranges:

  • less than/ greater than a fixed value
  • inside or outside of a certain range

Two compare values can be configured (the second value is used only for range function mode). The compare values must be written in 12-bit resolution mode regardless of the actual used resolution mode.

Once the hardware compare feature is enabled, a conversion is considered complete only when the measured value is within the allowable range set by the configuration.

void ADC_DRV_InitHwCompareStruct (adc_compare_config_t *const config)
 Initializes the Hardware Compare configuration structure. More...
 
void ADC_DRV_ConfigHwCompare (const uint32_t instance, const adc_compare_config_t *const config)
 Configures the Hardware Compare feature with the given configuration structure. More...
 
void ADC_DRV_GetHwCompareConfig (const uint32_t instance, adc_compare_config_t *const config)
 Gets the current Hardware Compare configuration. More...
 

Hardware Average

The Hardware Average feature of the S32K144 allows for a set of measurements to be averaged together as a single conversion. The number of samples to be averaged is selectable (4, 8, 16 or 32 samples).

void ADC_DRV_InitHwAverageStruct (adc_average_config_t *const config)
 Initializes the Hardware Average configuration structure. More...
 
void ADC_DRV_ConfigHwAverage (const uint32_t instance, const adc_average_config_t *const config)
 Configures the Hardware Average feature with the given configuration structure. More...
 
void ADC_DRV_GetHwAverageConfig (const uint32_t instance, adc_average_config_t *const config)
 Gets the current Hardware Average configuration. More...
 

Channel configuration

Control register specific functions. These functions control configurations for each control channel (input channel selection and interrupt enable).

When software triggering is enabled, calling the ADC_DRV_ConfigChan() method for control channel 0 starts a new conversion.

After a conversion is finished, the result can be retrieved using the ADC_DRV_GetChanResult() method.

void ADC_DRV_InitChanStruct (adc_chan_config_t *const config)
 Initializes the control channel configuration structure. More...
 
void ADC_DRV_ConfigChan (const uint32_t instance, const uint8_t chanIndex, const adc_chan_config_t *const config)
 Configures the selected control channel with the given configuration structure. More...
 
void ADC_DRV_GetChanConfig (const uint32_t instance, const uint8_t chanIndex, adc_chan_config_t *const config)
 Gets the current control channel configuration for the selected channel index. More...
 
void ADC_DRV_GetChanResult (const uint32_t instance, const uint8_t chanIndex, uint16_t *const result)
 Gets the last result for the selected control channel. More...
 

Automatic Calibration

These methods control the Calibration feature of the ADC.

The ADC_DRV_AutoCalibration() method can be called to execute a calibration sequence, or a calibration can be retrieved with the ADC_DRV_GetUserCalibration() and saved to non-volatile storage, to avoid calibration on every power-on. The calibration structure can be written with the ADC_DRV_ConfigUserCalibration() method.

void ADC_DRV_AutoCalibration (const uint32_t instance)
 Executes an Auto-Calibration. More...
 
void ADC_DRV_InitUserCalibrationStruct (adc_calibration_t *const config)
 Initializes the User Calibration configuration structure. More...
 
void ADC_DRV_ConfigUserCalibration (const uint32_t instance, const adc_calibration_t *const config)
 Configures the User Calibration feature with the given configuration structure. More...
 
void ADC_DRV_GetUserCalibration (const uint32_t instance, adc_calibration_t *const config)
 Gets the current User Calibration configuration. More...
 

Interrupts

This method returns the interrupt number for an ADC instance, which can be used to configure the interrupt, like in Interrupt Manager.

IRQn_Type ADC_DRV_GetInterruptNumber (const uint32_t instance)
 Returns the interrupt number for the ADC instance. More...
 

Latched triggers processing

These functions provide basic operations for using the trigger latch mechanism.

void ADC_DRV_ClearLatchedTriggers (const uint32_t instance, const adc_latch_clear_t clearMode)
 Clear latched triggers under processing. More...
 
void ADC_DRV_ClearTriggerErrors (const uint32_t instance)
 Clear all latch trigger error. More...
 
uint32_t ADC_DRV_GetTriggerErrorFlags (const uint32_t instance)
 This function returns the trigger error flags bits of the ADC instance. More...
 

Enumeration Type Documentation

Defines the trigger latch clear method Implements : adc_latch_clear_t_Class.

Enumerator
ADC_LATCH_CLEAR_WAIT 

Clear by waiting all latched triggers to be processed

ADC_LATCH_CLEAR_FORCE 

Process current trigger and clear all latched

Definition at line 119 of file adc_driver.h.

Function Documentation

void ADC_DRV_AutoCalibration ( const uint32_t  instance)

Executes an Auto-Calibration.

This functions executes an Auto-Calibration sequence. It is recommended to run this sequence before using the ADC converter.

Parameters
[in]instanceinstance number

Definition at line 370 of file adc_driver.c.

void ADC_DRV_ClearLatchedTriggers ( const uint32_t  instance,
const adc_latch_clear_t  clearMode 
)

Clear latched triggers under processing.

This function clears all trigger latched flags of the ADC instance. This function must be called after the hardware trigger source for the ADC has been deactivated.

Parameters
[in]instanceinstance number of the ADC
[in]clearModeThe clearing method for the latched triggers
  • ADC_LATCH_CLEAR_WAIT : Wait for all latched triggers to be processed.
  • ADC_LATCH_CLEAR_FORCE : Clear latched triggers and wait for trigger being process to finish.

Definition at line 485 of file adc_driver.c.

void ADC_DRV_ClearTriggerErrors ( const uint32_t  instance)

Clear all latch trigger error.

This function clears all trigger error flags of the ADC instance.

Parameters
[in]instanceinstance number of the ADC

Definition at line 510 of file adc_driver.c.

void ADC_DRV_ConfigChan ( const uint32_t  instance,
const uint8_t  chanIndex,
const adc_chan_config_t *const  config 
)

Configures the selected control channel with the given configuration structure.

This function sets a control channel configuration. In Software Trigger mode, only control channel (chanIndex) 0 can start conversions.

Parameters
[in]instanceinstance number
[in]chanIndexthe control channel index
[in]configthe configuration structure

Definition at line 289 of file adc_driver.c.

void ADC_DRV_ConfigConverter ( const uint32_t  instance,
const adc_converter_config_t *const  config 
)

Configures the converter with the given configuration structure.

This function configures the ADC converter with the options provided in the provided structure.

Parameters
[in]instanceinstance number
[in]configthe configuration structure

Definition at line 81 of file adc_driver.c.

void ADC_DRV_ConfigHwAverage ( const uint32_t  instance,
const adc_average_config_t *const  config 
)

Configures the Hardware Average feature with the given configuration structure.

This function sets the configuration for the Hardware Average feature.

Parameters
[in]instanceinstance number
[in]configthe configuration structure

Definition at line 232 of file adc_driver.c.

void ADC_DRV_ConfigHwCompare ( const uint32_t  instance,
const adc_compare_config_t *const  config 
)

Configures the Hardware Compare feature with the given configuration structure.

This functions sets the configuration for the Hardware Compare feature using the configuration structure.

Parameters
[in]instanceinstance number
[in]configthe configuration structure

Definition at line 169 of file adc_driver.c.

void ADC_DRV_ConfigUserCalibration ( const uint32_t  instance,
const adc_calibration_t *const  config 
)

Configures the User Calibration feature with the given configuration structure.

This function sets the configuration for the user calibration registers.

Parameters
[in]instanceinstance number
[in]configthe configuration structure

Definition at line 431 of file adc_driver.c.

void ADC_DRV_GetChanConfig ( const uint32_t  instance,
const uint8_t  chanIndex,
adc_chan_config_t *const  config 
)

Gets the current control channel configuration for the selected channel index.

This function returns the configuration for a control channel

Parameters
[in]instanceinstance number
[in]chanIndexthe control channel index
[out]configthe configuration structure

Definition at line 310 of file adc_driver.c.

void ADC_DRV_GetChanResult ( const uint32_t  instance,
const uint8_t  chanIndex,
uint16_t *const  result 
)

Gets the last result for the selected control channel.

This function returns the conversion result from a control channel.

Parameters
[in]instanceinstance number
[in]chanIndexthe converter control channel index
[out]resultthe result raw value

Definition at line 350 of file adc_driver.c.

void ADC_DRV_GetConverterConfig ( const uint32_t  instance,
adc_converter_config_t *const  config 
)

Gets the current converter configuration.

This functions returns the configuration for converter in the form of a configuration structure.

Parameters
[in]instanceinstance number
[out]configthe configuration structure

Definition at line 106 of file adc_driver.c.

void ADC_DRV_GetHwAverageConfig ( const uint32_t  instance,
adc_average_config_t *const  config 
)

Gets the current Hardware Average configuration.

This function returns the configuration for the Hardware Average feature.

Parameters
[in]instanceinstance number
[out]configthe configuration structure

Definition at line 251 of file adc_driver.c.

void ADC_DRV_GetHwCompareConfig ( const uint32_t  instance,
adc_compare_config_t *const  config 
)

Gets the current Hardware Compare configuration.

This function returns the configuration for the Hardware Compare feature.

Parameters
[in]instanceinstance number
[out]configthe configuration structure

Definition at line 191 of file adc_driver.c.

IRQn_Type ADC_DRV_GetInterruptNumber ( const uint32_t  instance)

Returns the interrupt number for the ADC instance.

This function returns the interrupt number for the specified ADC instance.

Parameters
[in]instanceinstance number of the ADC
Returns
irq_number: the interrupt number (index) of the ADC instance, used to configure the interrupt

Definition at line 468 of file adc_driver.c.

uint32_t ADC_DRV_GetTriggerErrorFlags ( const uint32_t  instance)

This function returns the trigger error flags bits of the ADC instance.

Parameters
[in]instanceinstance number of the ADC
Returns
trigErrorFlags The Trigger Error Flags bit-mask

Definition at line 525 of file adc_driver.c.

void ADC_DRV_GetUserCalibration ( const uint32_t  instance,
adc_calibration_t *const  config 
)

Gets the current User Calibration configuration.

This function returns the current user calibration register values.

Parameters
[in]instanceinstance number
[out]configthe configuration structure

Definition at line 450 of file adc_driver.c.

void ADC_DRV_InitChanStruct ( adc_chan_config_t *const  config)

Initializes the control channel configuration structure.

This function initializes the control channel configuration structure to default values (Reference Manual resets). This function should be called on a structure before using it to configure a channel (ADC_DRV_ConfigChan), otherwise all members must be written by the caller. This function insures that all members are written with safe values, so the user can modify only the desired members.

Parameters
[out]configthe configuration structure

Definition at line 273 of file adc_driver.c.

void ADC_DRV_InitConverterStruct ( adc_converter_config_t *const  config)

Initializes the converter configuration structure.

This function initializes the members of the adc_converter_config_t structure to default values (Reference Manual resets). This function should be called on a structure before using it to configure the converter with ADC_DRV_ConfigConverter(), otherwise all members must be written (initialized) by the user. This function insures that all members are written with safe values, so the user can modify only the desired members.

Parameters
[out]configthe configuration structure

Definition at line 59 of file adc_driver.c.

void ADC_DRV_InitHwAverageStruct ( adc_average_config_t *const  config)

Initializes the Hardware Average configuration structure.

This function initializes the Hardware Average configuration structure to default values (Reference Manual resets). This function should be called before configuring the Hardware Average feature (ADC_DRV_ConfigHwAverage), otherwise all members must be written by the caller. This function insures that all members are written with safe values, so the user can modify the desired members.

Parameters
[out]configthe configuration structure

Definition at line 216 of file adc_driver.c.

void ADC_DRV_InitHwCompareStruct ( adc_compare_config_t *const  config)

Initializes the Hardware Compare configuration structure.

This function initializes the Hardware Compare configuration structure to default values (Reference Manual resets). This function should be called before configuring the Hardware Compare feature (ADC_DRV_ConfigHwCompare), otherwise all members must be written by the caller. This function insures that all members are written with safe values, so the user can modify the desired members.

Parameters
[out]configthe configuration structure

Definition at line 150 of file adc_driver.c.

void ADC_DRV_InitUserCalibrationStruct ( adc_calibration_t *const  config)

Initializes the User Calibration configuration structure.

This function initializes the User Calibration configuration structure to default values (Reference Manual resets). This function should be called on a structure before using it to configure the User Calibration feature (ADC_DRV_ConfigUserCalibration), otherwise all members must be written by the caller. This function insures that all members are written with safe values, so the user can modify only the desired members.

Parameters
[out]configthe configuration structure

Definition at line 415 of file adc_driver.c.

void ADC_DRV_Reset ( const uint32_t  instance)

Resets the converter (sets all configurations to reset values)

This function resets all the internal ADC registers to reset values.

Parameters
[in]instanceinstance number

Definition at line 131 of file adc_driver.c.

void ADC_DRV_WaitConvDone ( const uint32_t  instance)

Waits for a conversion/calibration to finish.

This functions waits for a conversion to complete by continuously polling the Conversion Active Flag.

Parameters
[in]instanceinstance number

Definition at line 331 of file adc_driver.c.