Analog to Digital Converter - Peripheral Abstraction Layer (ADC PAL)

Detailed Description

Analog to Digital Converter - Peripheral Abstraction Layer (ADC PAL).

ADC PAL general consideration

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.

  1. Execution of SW triggered groups may be started/stopped by calling a dedicated function ADC_StartGroupConversion(), ADC_StopGroupConversion().
  2. HW triggered groups need to be enabled for execution by calling a dedicated function - the actual execution will be started by the occurrence of the selected hardware trigger event ADC_EnableHardwareTrigger(), ADC_DisableHardwareTrigger().
    Note: for HW triggered groups the ADC PAL does not configure the peripherals which provide the triggering events (timers, counters, etc.) - they will need to be configured separately by the ADC PAL user.

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

Important note

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.

Platform specific details

S32K1xx device family

On these platforms, each instance of ADC PAL uses:

Important details:

  1. The PAL supports configuring any number of conversion groups at PAL initialization time, but every time a HW/SW triggered group is enabled/started, the underlying hardware peripherals are reconfigured.
  2. The same input channel may appear multiple times in a group.

Group delay support:

MPC5746C and MPC5748G device families

On these platforms, each instance of ADC PAL uses:

Group delay support:

Important details:

  1. The PAL supports any number of SW triggered conversion groups at PAL initialization time. SW triggered groups will be configured directly in ADC, each time ADC_StartGroupConversion() is called.
  2. The maximum supported number of HW triggered conversion groups is expressed in two steps:
    • for groups which include a minimum of 2 conversions: the total number of conversions within all these groups shall be less than or equal with the number of BCTU LIST HW registers. (E.g. 1 group of 8 conversions & 1 group of 24 conversions: 8 + 24 <= 32)
    • for groups which include a single conversion: the total number of such groups shall be less than or equal with the total number of BCTU Triggers minus the number of configured groups with at least 2 conversions
  3. An input channel may only appear once in the group, otherwise the last conversion result will appear for each occurrence of the channel index in the group. This is a platform limitation: BCTU has only a single result register per ADC instance, and the ADC has a single result register per channel.
  4. A conversion group (SW and HW triggered) can target only conversions on a single ADC instance.
  5. The same trigger source cannot be assigned to multiple HW triggered groups.
  6. Multiple HW triggered groups may be enabled simultaneously.
    However, the user must make sure that the actual HW trigger events do not occur simultaneously and that conversions from multiple groups do not overlap in time. Otherwise hardware errors may occur and results may be overwritten.

MPC574xP device family

On these platforms, each instance of ADC PAL uses:

Group delay support:

Important details:

  1. The PAL supports any number of SW triggered conversion groups at PAL initialization time. SW triggered groups will be configured directly in ADC, each time ADC_StartGroupConversion() is called.
  2. The maximum supported number of HW triggered conversion groups is equal with the number of CTU result FIFOs - defined in platform header file as CTU_FR_COUNT. The total number of conversions in all HW triggered groups must be <= the length of the CTU ADC command list - defined in platform header file as CTU_CHANNEL_COUNT.
  3. A conversion group (SW and HW triggered) can target only conversions on a single ADC instance.
  4. An input channel may only appear once in a SW triggered group, otherwise the last conversion result will appear for each occurrence of the channel index in the group. This is a platform limitation: the ADC has a single result register per channel. For HW triggered groups this restriction doesn't apply.
  5. All HW triggered groups can be enabled simultaneously.
    However, the user must make sure that the actual HW trigger events do not occur simultaneously and that conversions from multiple groups do not overlap in time. Otherwise hardware errors may occur and results may be overwritten.
  6. Each HW triggered group has assigned a CTU result FIFO. The number of channels in each group must be less than the CTU result FIFO length - note that not all FIFOs have the same length. FIFOs are assigned in the same order in which the HW triggered groups are configured in the PAL init state: FIFO#0 assigned to first group, FIFO#1 to second, etc.
  7. The trigger sources enabled for a group can implicitly start also the rest of the enabled HW triggered groups.
    E.g. SourceX configured for group0, sourceY configured for group1. If both groups are enabled, when event from sourceX occurs, both group0 and group1 will execute; the same when event from sourceY occurs.

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...
 

Enumeration Type Documentation

Defines an enumeration which contains the types of delay configurations for ADC conversions within a group.

Implements : adc_delay_type_t_Class

Enumerator
ADC_DELAY_TYPE_NO_DELAY 

First conversion can start right after the trigger occurrence, and the rest of conversions execute one after another

ADC_DELAY_TYPE_GROUP_DELAY 

Delay only first conversion, and the rest execute one after another

ADC_DELAY_TYPE_INDIVIDUAL_DELAY 

Individual delay for each conversion in the group (each measured from the occurrence of the trigger)

Definition at line 117 of file adc_pal.h.

Function Documentation

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.

Parameters
[in]instancePointer to ADC PAL instance number structure
Returns
status:
- STATUS_BUSY: there is already a HW triggered group enabled or executing, or a SW triggered group executing
- STATUS_SUCCESS: ADC PAL initialized successfully

Definition at line 310 of file adc_pal.c.

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.

Parameters
[in]instancePointer to ADC PAL instance number structure
[in]groupIdxIndex of the selected group configured via groupConfigArray in adc_config_t
[in]timeoutTimeout interval in milliseconds
Returns
status:
- STATUS_TIMEOUT: the operation did not complete successfully within the provided timeout interval
- STATUS_SUCCESS: the operation completed successfully within the provided timeout interval

Definition at line 500 of file adc_pal.c.

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.

Parameters
[in]instancePointer to ADC PAL instance number structure
[in]groupIdxIndex of the selected group configured via groupConfigArray in adc_config_t
Returns
status:
- STATUS_ERROR: the selected group is not active (SW triggered running or HW triggered running or enabled)
- STATUS_SUCCESS: the notification has been disabled successfully

Definition at line 835 of file adc_pal.c.

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.

Parameters
[in]instancePointer to ADC PAL instance number structure
[in]groupIdxIndex of the selected group configured via groupConfigArray in adc_config_t
Returns
status:
- STATUS_BUSY: there is already a HW triggered group enabled or executing, or a SW triggered group executing
- STATUS_SUCCESS: HW trigger enabled successfully for the selected conversion group

Definition at line 408 of file adc_pal.c.

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.

Parameters
[in]instancePointer to ADC PAL instance number structure
[in]groupIdxIndex of the selected group configured via groupConfigArray in adc_config_t
Returns
status:
- STATUS_ERROR: the selected group is not active (SW triggered running or HW triggered running or enabled)
- STATUS_SUCCESS: the notification has been enabled successfully

Definition at line 786 of file adc_pal.c.

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.

Parameters
[in]instancePointer to ADC PAL instance number structure
[in]configThe ADC PAL configuration structure
Returns
status:
- STATUS_ERROR: error initializing one of the HW modules used by ADC PAL. On MPC574x: also returned if number of HW triggered conversion groups is larger than the maximum number of supported hardware triggers
- STATUS_SUCCESS: ADC PAL initialized successfully

Definition at line 228 of file adc_pal.c.

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.

Parameters
[in]instancePointer to ADC PAL instance number structure
[in]groupIdxIndex of the selected group configured via groupConfigArray in adc_config_t
Returns
status:
- STATUS_BUSY: there is already a HW triggered group enabled or executing, or a SW triggered group executing
- STATUS_SUCCESS: group conversion successfully triggered

Definition at line 607 of file adc_pal.c.

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.

Parameters
[in]instancePointer to ADC PAL instance number structure
[in]groupIdxIndex of the selected group configured via groupConfigArray in adc_config_t
[in]timeoutTimeout interval in milliseconds
Returns
status:
- STATUS_TIMEOUT: the operation did not complete successfully within the provided timeout interval
- STATUS_SUCCESS: the operation completed successfully within the provided timeout interval

Definition at line 686 of file adc_pal.c.