Analog to Digital Converter - Peripheral Abstraction Layer (ADC PAL).
The ADC PAL is an interface abstraction layer for multiple Analog to Digital Converter peripherals.
The ADC PAL allows configuration of groups of successive conversions started by a single trigger event.
Each conversion in a group is mapped to an ADC input channel - the conversion group is actually defined by an array of input channels, which is a member of the adc_group_config_t structure. The order of the input channels will also give the order of execution of the conversions within the group.
Note: all conversion groups need to be configured at PAL initialization time.
The trigger event for a group can be SW or HW, and needs to be selected at configuration time.
Each group needs to have associated a result buffer which needs to be allocated by the PAL user. The length of the result buffer is defined by two configuration parameters:
* numChannels - defines also the size of the inputChannelArray
* numSetsResultBuffer - defines the number of sets of results which can be stored in the result buffer.
The length of the result buffer = numChannels * numSetsResultBuffer. Each time a group of conversions finishes execution, a set of results for all conversions in the group will be copied by the PAL into the corresponding result buffer. The PAL considers the result buffer as circular, with the length configured via previously described.
On some platforms, HW triggered groups may support delay(s) between the occurrence of the HW trigger event and the actual start of conversions. This feature can be controlled for each HW triggered group via delayType and delayArray parameters in adc_group_config_t. For SW triggered groups, these parameters are ignored. For details please refer to ADC PAL platform specific information.
Each group can also have associated a notification callback which will be executed when all conversions finish execution. The callback shall receive as parameter a pointer to adc_callback_info_t containing the group index for which the notification is called, and result buffer tail - offset of the most recent conversion result in the result buffer. Notifications can be enabled and disabled using ADC_EnableNotification() and ADC_DisableNotification(). By default the notification is set to active when enabling a HW triggered group or starting a SW triggered group.
Note: The notification callback may be set to NULL and thus it will not be called.
For SW triggered groups, continuous mode can be enabled at configuration time.
E.g.: a group with 3 conversions InputCh0, InputCh1, InputCh2 -> with continuous mode enabled will continuously repeat the series of conversions until it is stopped: InputCh0, InputCh1, InputCh2, InputCh0, InputCh1, InputCh2,...
The user needs to dimension accordingly the result buffer, such that it has sufficient time to read the results before they are overwritten.
For HW triggered groups, continuous mode parameter is not available.
The ADC PAL implicitly configures and uses other peripherals besides ADC - these resources should not be used simultaneously from other parts of the application. For details please refer to the platform specific details.
The ADC PAL module needs to include a configuration file named adc_pal_cfg.h, which defines which IPs are used.
The ADC PAL allows configuration of platform specific parameters via a pointer to a platform specific structure, following the naming convention: extension_adc_<platform>_t. E.g.: extension_adc_s32k1xx_t
The ADC PAL configuration structure passed via reference to ADC_Init(), including all arrays referenced by structure members, must be persistent throughout the usage of the ADC PAL. Storing them to memory sections which get freed or altered during ADC PAL usage, will lead to unpredictable behavior.
On these platforms, each instance of ADC PAL uses:
Important details:
Group delay support:
On these platforms, each instance of ADC PAL uses:
Group delay support:
Important details:
On these platforms, each instance of ADC PAL uses:
Group delay support:
Important details:
Data Structures | |
struct | adc_group_config_t |
Defines the configuration structure for an ADC PAL conversion group. More... | |
struct | adc_config_t |
Defines the configuration structure for ADC PAL. More... | |
Enumerations | |
enum | adc_delay_type_t { ADC_DELAY_TYPE_NO_DELAY = 0u, ADC_DELAY_TYPE_GROUP_DELAY = 1u, ADC_DELAY_TYPE_INDIVIDUAL_DELAY = 2u } |
Defines an enumeration which contains the types of delay configurations for ADC conversions within a group. More... | |
Functions | |
status_t | ADC_Init (const adc_instance_t *const instance, const adc_config_t *const config) |
Initializes the ADC PAL instance. More... | |
status_t | ADC_Deinit (const adc_instance_t *const instance) |
Deinitializes the ADC PAL instance. More... | |
status_t | ADC_EnableHardwareTrigger (const adc_instance_t *const instance, const uint32_t groupIdx) |
Enables the selected HW trigger for a conversion group, if the conversion group has support for HW trigger. More... | |
status_t | ADC_DisableHardwareTrigger (const adc_instance_t *const instance, const uint32_t groupIdx, const uint32_t timeout) |
Disables the selected HW trigger for a conversion group, if the conversion group is HW triggered. More... | |
status_t | ADC_StartGroupConversion (const adc_instance_t *const instance, const uint32_t groupIdx) |
Starts the execution of a selected SW triggered ADC conversion group. More... | |
status_t | ADC_StopGroupConversion (const adc_instance_t *const instance, const uint32_t groupIdx, const uint32_t timeout) |
Stops the selected SW triggered ADC conversion group execution. More... | |
status_t | ADC_EnableNotification (const adc_instance_t *const instance, const uint32_t groupIdx) |
Enables the notification callback for a configured group. More... | |
status_t | ADC_DisableNotification (const adc_instance_t *const instance, const uint32_t groupIdx) |
Disables the notification callback for a configured group. More... | |
enum adc_delay_type_t |
Defines an enumeration which contains the types of delay configurations for ADC conversions within a group.
Implements : adc_delay_type_t_Class
status_t ADC_Deinit | ( | const adc_instance_t *const | instance | ) |
Deinitializes the ADC PAL instance.
This function resets the ADC PAL instance, including the other platform specific HW units used together with ADC, if there are no active conversions.
[in] | instance | Pointer to ADC PAL instance number structure |
status_t ADC_DisableHardwareTrigger | ( | const adc_instance_t *const | instance, |
const uint32_t | groupIdx, | ||
const uint32_t | timeout | ||
) |
Disables the selected HW trigger for a conversion group, if the conversion group is HW triggered.
This function disables the HW trigger for a configured conversion group and also may stop its execution (depending on platform), if called when a conversion group is executing. If stopping is supported, the execution shall be stopped according to device specific procedures. The function shall wait for the procedures to complete within the given timeout interval and return error code if they do not succeed. : the function prevents new conversions from the group from starting, then waits until the current active conversion finishes execution (if the function call occurred while an ADC conversion from the group is executing) or timeout occurs. : the execution of a HW triggered group of conversions cannot be stopped, so the function shall wait until it is complete or timeout occurs. : the function always returns STATUS_SUCCESS (even if a conversion is still executing) and doesn't use 'timeout' parameter. If it is called during a control cycle, between MRS and actual group conversion start, there will be an additional execution of the group, without callback.
[in] | instance | Pointer to ADC PAL instance number structure |
[in] | groupIdx | Index of the selected group configured via groupConfigArray in adc_config_t |
[in] | timeout | Timeout interval in milliseconds |
status_t ADC_DisableNotification | ( | const adc_instance_t *const | instance, |
const uint32_t | groupIdx | ||
) |
Disables the notification callback for a configured group.
This function disables the notification callback for a selected group of ADC conversions.
[in] | instance | Pointer to ADC PAL instance number structure |
[in] | groupIdx | Index of the selected group configured via groupConfigArray in adc_config_t |
status_t ADC_EnableHardwareTrigger | ( | const adc_instance_t *const | instance, |
const uint32_t | groupIdx | ||
) |
Enables the selected HW trigger for a conversion group, if the conversion group has support for HW trigger.
Enables the selected HW trigger for a conversion group, if the conversion group has support for HW trigger. The function will return an error code if there is a conversion group already active. If the function succeeds, the conversion group will be triggered for execution when the selected HW trigger occurs.
[in] | instance | Pointer to ADC PAL instance number structure |
[in] | groupIdx | Index of the selected group configured via groupConfigArray in adc_config_t |
status_t ADC_EnableNotification | ( | const adc_instance_t *const | instance, |
const uint32_t | groupIdx | ||
) |
Enables the notification callback for a configured group.
This function enables the notification callback for a selected group of ADC conversions.
[in] | instance | Pointer to ADC PAL instance number structure |
[in] | groupIdx | Index of the selected group configured via groupConfigArray in adc_config_t |
status_t ADC_Init | ( | const adc_instance_t *const | instance, |
const adc_config_t *const | config | ||
) |
Initializes the ADC PAL instance.
This function initializes the ADC PAL instance, including the other platform specific HW units used together with ADC. Notifications are default enabled after init.
[in] | instance | Pointer to ADC PAL instance number structure |
[in] | config | The ADC PAL configuration structure |
status_t ADC_StartGroupConversion | ( | const adc_instance_t *const | instance, |
const uint32_t | groupIdx | ||
) |
Starts the execution of a selected SW triggered ADC conversion group.
This function starts execution of a selected ADC conversion group, if there is no other conversion group active. Conversion groups started by ADC_StartGroupConversion shall not be preempted by HW triggered conversion groups.
[in] | instance | Pointer to ADC PAL instance number structure |
[in] | groupIdx | Index of the selected group configured via groupConfigArray in adc_config_t |
status_t ADC_StopGroupConversion | ( | const adc_instance_t *const | instance, |
const uint32_t | groupIdx, | ||
const uint32_t | timeout | ||
) |
Stops the selected SW triggered ADC conversion group execution.
This function stops the execution of a SW triggered conversion group. The execution shall be stopped according to device specific procedures. The function shall wait for the procedures to complete within the given timeout interval and return error code if they do not succeed. For MPC574xP and MPC574xC_G_R a conversion already started for execution cannot be stopped, so the function shall wait until it finishes or timeout occurs.
[in] | instance | Pointer to ADC PAL instance number structure |
[in] | groupIdx | Index of the selected group configured via groupConfigArray in adc_config_t |
[in] | timeout | Timeout interval in milliseconds |