Input Capture - Peripheral Abstraction Layer (IC PAL)

Detailed Description

The S32 SDK provides a Peripheral Abstraction Layer for the input capture mode of S32 SDK devices.

The IC PAL driver allows to detect the input signal and measure pulse width or period of the channel input signal. It was designed to be portable across all platforms and IPs which support FTM , eMIOS and ETIMER.

How to integrate IC PAL in your application

Unlike the other drivers, IC PAL modules need to include a configuration file named ic_pal_cfg.h, which allows the user to specify which IPs are used. The following code example shows how to configure one instance for each available IC IPs.

#ifndef IC_PAL_CFG_H
#define IC_PAL_CFG_H
/* Define which IP instance will be used in current project */
#define IC_PAL_OVER_FTM
#endif /* IC_PAL_CFG_H */

The following table contains the matching between platforms and available IPs

IP/MCU S32K116S32K118S32K142S32K144S32K146S32K148MPC5748GMPC5746CMPC5744P
FTM_IC YES YES YES YES YES YES NO NO NO
eMIOS_IC NO NO NO NO NO NO YES YES NO
ETIMER NO NO NO NO NO NO NO NO YES

Features

Functionality

Initialization

In order to use the IC PAL driver it must be first initialized, using IC_Init() function. Once initialized, it should be de-initialized before initialized again for the same IC module instance, using IC_Deinit(). The initialization function does the following operations:

Example:

/*PAL instance information */
ic_instance_t ic_pal1_instance = { IC_INST_TYPE_FTM, 0U };
ic_input_ch_param_t icPalChnConfig[1] =
{
{
.hwChannelId = 0U,
.inputCaptureMode = IC_DETECT_RISING_EDGE,
.filterEn = false,
.filterValue = 0U,
.channelExtension = &ftmChnExtension0,
.channelCallbackParams = NULL,
.channelCallbacks = ic_pal1_channel_callBack0
}
};
channel_extension_ftm_for_ic_t ftmChnExtension0 =
{
.continuousModeEn = true
};
extension_ftm_for_ic_t ftmExtensionConfig =
{
.ftmClockSource = FTM_CLOCK_SOURCE_SYSTEMCLK,
.ftmPrescaler = FTM_CLOCK_DIVID_BY_1
};
ic_config_t icPal1_InitConfig =
{
.nNumChannels = 1U,
.inputChConfig = icPalChnConfig,
.extension = &ftmExtensionConfig
};
/* Initialize input capture mode */
IC_Init(&ic_pal1_instance, &icPal1_InitConfig);

De-initialize a input capture instance

This function will disable the input capture mode. The driver can't be used again until reinitialized. All register are reset to default value and counter is stopped.

Example:

/* De-initialize input capture mode */
IC_Deinit(&ic_pal1_instance);

Start the channel in the input capture mode

This function will set the channel is in the input capture mode.

Example:

uint8_t hwChannel = icPal1_InitConfig.inputChConfig[0].hwChannelId;
/* Start channel in the input capture mode */
IC_StartChannel(&ic_pal1_instance, hwChannel);

Stop the channel in the input capture mode

This function will set the channel is used in GPIO mode or other peripheral.

Example:

uint8_t hwChannel = icPal1_InitConfig.inputChConfig[0].hwChannelId;
/* Stop channel in the input capture mode */
IC_StopChannel(&ic_pal1_instance, hwChannel);

Get the measured value

The pulse width measurement and the period measurement can be made after the channel input is in the input capture mode. The value is last captured by count. Note that to get true value of measurement at the first of pulse, please use the IC_GetValueMeasurement function in interrupt.

Example:

uint16_t retResult = 0U;
uint8_t hwChannel = icPal1_InitConfig.inputChConfig[0].hwChannelId;
/* Get the last captured value */
retResult = IC_GetMeasurement(&ic_pal1_instance, hwChannel);

Enable notifications on the channel

The notification is executed in the callback application with the IC_EVENT_MEASUREMENT_COMPLETE event which indicates that the measurement of input signal is completed.

Example:

uint8_t hwChannel = icPal1_InitConfig.inputChConfig[0].hwChannelId;
/* Enable the notification */
IC_EnableNotification(&ic_pal1_instance, hwChannel);

Disable notifications on the channel

The callback application will be not executed when the notification is disabled.

Example:

uint8_t hwChannel = icPal1_InitConfig.inputChConfig[0].hwChannelId;
/* Disable the notification */
IC_DisableNotification(&ic_pal1_instance, hwChannel);

Important Notes

Data Structures

struct  ic_input_ch_param_t
 The configuration structure of input capture parameters for each channel. More...
 
struct  ic_config_t
 Defines the configuration structures are used in the input capture mode. More...
 
struct  ic_pal_state_t
 The internal context structure. More...
 

Enumerations

enum  ic_option_mode_t {
  IC_DISABLE_OPERATION = 0x00U, IC_TIMESTAMP_RISING_EDGE = 0x01U, IC_TIMESTAMP_FALLING_EDGE = 0x02U, IC_TIMESTAMP_BOTH_EDGES = 0x03U,
  IC_MEASURE_RISING_EDGE_PERIOD = 0x04U, IC_MEASURE_FALLING_EDGE_PERIOD = 0x05U, IC_MEASURE_PULSE_HIGH = 0x06U, IC_MEASURE_PULSE_LOW = 0x07U
}
 The measurement type for input capture mode Implements : ic_option_mode_t_Class. More...
 

Functions

status_t IC_Init (const ic_instance_t *const instance, const ic_config_t *configPtr)
 Initializes the input capture mode. More...
 
status_t IC_Deinit (const ic_instance_t *const instance)
 De-initialize a input capture instance. More...
 
void IC_StartChannel (const ic_instance_t *const instance, uint8_t channel)
 Start the counter. More...
 
void IC_StopChannel (const ic_instance_t *const instance, uint8_t channel)
 Stop the counter. More...
 
status_t IC_SetChannelMode (const ic_instance_t *const instance, uint8_t channel, ic_option_mode_t channelMode)
 Get the measured value. More...
 
uint16_t IC_GetMeasurement (const ic_instance_t *const instance, uint8_t channel)
 Get the measured value. More...
 
void IC_EnableNotification (const ic_instance_t *const instance, uint8_t channel)
 Enable channel notifications. More...
 
void IC_DisableNotification (const ic_instance_t *const instance, uint8_t channel)
 Disable channel notifications. More...
 

Enumeration Type Documentation

The measurement type for input capture mode Implements : ic_option_mode_t_Class.

Enumerator
IC_DISABLE_OPERATION 

Have no operation

IC_TIMESTAMP_RISING_EDGE 

Rising edge trigger

IC_TIMESTAMP_FALLING_EDGE 

Falling edge trigger

IC_TIMESTAMP_BOTH_EDGES 

Rising and falling edge trigger

IC_MEASURE_RISING_EDGE_PERIOD 

Period measurement between two consecutive rising edges

IC_MEASURE_FALLING_EDGE_PERIOD 

Period measurement between two consecutive falling edges

IC_MEASURE_PULSE_HIGH 

The time measurement taken for the pulse to remain ON or HIGH state

IC_MEASURE_PULSE_LOW 

The time measurement taken for the pulse to remain OFF or LOW state

Definition at line 117 of file ic_pal.h.

Function Documentation

status_t IC_Deinit ( const ic_instance_t *const  instance)

De-initialize a input capture instance.

This function will disable the input capture mode. The driver can't be used again until reinitialized. The context structure is no longer needed by the driver and can be freed after calling this function.

Parameters
[in]instanceThe pointer to instance number structure.
Returns
Operation status
  • STATUS_SUCCESS: Operation was successful

Definition at line 736 of file ic_pal.c.

void IC_DisableNotification ( const ic_instance_t *const  instance,
uint8_t  channel 
)

Disable channel notifications.

This function disables channel notification.

Parameters
[in]instanceThe pointer to instance number structure.
[in]channelThe channel number.

Definition at line 1064 of file ic_pal.c.

void IC_EnableNotification ( const ic_instance_t *const  instance,
uint8_t  channel 
)

Enable channel notifications.

This function enables channel notification.

Parameters
[in]instanceThe pointer to instance number structure.
[in]channelThe channel number.

Definition at line 1035 of file ic_pal.c.

uint16_t IC_GetMeasurement ( const ic_instance_t *const  instance,
uint8_t  channel 
)

Get the measured value.

This function will get the value of measured signal in ticks.

Parameters
[in]instanceThe pointer to instance number structure.
[in]channelThe channel number.
Returns
The last value of measured signal in ticks.

Definition at line 987 of file ic_pal.c.

status_t IC_Init ( const ic_instance_t *const  instance,
const ic_config_t configPtr 
)

Initializes the input capture mode.

This function will initialize the IC PAL instance, including the other platform specific HW units used together in the input capture mode. This function configures a group of channels in instance to detect or measure the input signal.

Parameters
[in]instanceThe pointer to instance number structure.
[in]configPtrThe pointer to configuration structure.
Returns
Operation status
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.

Definition at line 677 of file ic_pal.c.

status_t IC_SetChannelMode ( const ic_instance_t *const  instance,
uint8_t  channel,
ic_option_mode_t  channelMode 
)

Get the measured value.

This function will get the value of measured signal in ticks.

Parameters
[in]instanceThe pointer to instance number structure.
[in]channelThe channel number.
Returns
The last value of measured signal in ticks.

Definition at line 886 of file ic_pal.c.

void IC_StartChannel ( const ic_instance_t *const  instance,
uint8_t  channel 
)

Start the counter.

This function start channel counting.

Parameters
[in]instanceThe pointer to instance number structure.
[in]channelThe channel number.

Definition at line 805 of file ic_pal.c.

void IC_StopChannel ( const ic_instance_t *const  instance,
uint8_t  channel 
)

Stop the counter.

This function stop channel counting.

Parameters
[in]instanceThe pointer to instance number structure.
[in]channelThe channel number.

Definition at line 849 of file ic_pal.c.