Timing - Peripheral Abstraction Layer (TIMING PAL)

Detailed Description

The S32 SDK provides a Peripheral Abstraction Layer for timer modules of S32 SDK devices.

The TIMING PAL driver allows to generate period event. It was designed to be portable across all platforms and IPs which support LPIT, PIT, LPTMR, FTM, STM.

How to integrate TIMING PAL in your application

Unlike the other drivers, TIMING PAL modules need to include a configuration file named timing_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 TIMING IPs.

#ifndef TIMING_PAL_CFG_H
#define TIMING_PAL_CFG_H
/* Define which IP instance will be used in current project */
#define TIMING_OVER_LPIT
#define TIMING_OVER_FTM
#define TIMING_OVER_LPTMR
#endif /* TIMING_PAL_CFG_H */

The following table contains the matching between platforms and available IPs

IP/MCU S32K116S32K118S32K142S32K144S32K146S32K148S32V234MPC5748GMPC5746CMPC5744P
LPIT_TIMING YES YES YES YES YES YES NO NO NO NO
LPTMR_TIMING YES YES YES YES YES YES NO NO NO NO
FTM_TIMING YES YES YES YES YES YES YES NO NO NO
PIT_TIMING NO NO NO NO NO NO YES YES YES YES
STM_TIMING NO NO NO NO NO NO YES YES YES YES

Features

Functionality

Initialization

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

Start/Stop a timer channel counting with new period

After initialization, a timer channel can be started by calling TIMING_StartChannel function. The input period unit is ticks, the max value of period depends on which timer is used for timing. The TIMING_StartChannel function can be called consecutively, it starts new period immediately but in case LPIT, PIT_TIMING when timer channel is running, to abort the current timer channel period and start a timer channel period with a new value, the timer channel must be stopped and started again. A timer channel can be stop by calling TIMING_StopChannel function.

Get elapsed and remaining time

When a timer channel is running, the elapsed and remaining timer can be got by calling TIMING_GetElapsed and TIMING_GetRemaining function. The elapsed and remaining time in nanosecond, microsecond or millisecond is the result of this function multiplies by the result of the TIMING_GetResolution.

Important Notes

Example code

/* The timer channel number */
#define TIMER_CHANNEL 0U
/* The timer channel period by nanosecond */
#define TIMER_PERIOD_NANO 1000000000U
/* Counting variable */
uint32_t count = 0;
/* Callback function */
void My_Callback(void * data)
{
(void)data;
count = count + 1;
}
/* Configure timer channel */
timer_chan_config_t timing_pal1_channelArray[] =
{
{
TIMER_CHANNEL,
My_Callback,
NULL
}
};
/* Configure FTM clock source */
extension_ftm_for_timer_t timing_pal1_ftmExtention =
{
0xFFFF
};
/* Configure TIMING instance */
timer_config_t timing_pal1_InitConfig =
{
timing_pal1_channelArray,
1,
&timing_pal1_ftmExtention
};
/* TIMING instance number structure */
timing_instance_t instance =
{
0U
};
int main(void)
{
uint64_t resolution;
uint32_t elapsedTime;
/* Initialize TIMING */
TIMING_Init(&instance, &timing_pal1_InitConfig);
/* Get tick resolution in nanosecond */
/* Start channel counting with period is 1 second */
TIMING_StartChannel(&instance, TIMER_CHANNEL, (TIMER_PERIOD_NANO / resolution));
....
/* Get elapsed time in ticks */
elapsedTime = TIMING_GetElapsed(&instance, TIMER_CHANNEL);
/* Get elapsed time in nanosecond */
elapsedTime = elapsedTime * resolution;
/* De-initialize TIMING */
TIMING_Deinit(&instance);
}

Data Structures

struct  timer_chan_config_t
 Structure to configure the channel timer notification. More...
 
struct  timer_config_t
 Timer configuration structure. More...
 

Enumerations

enum  timer_resolution_type_t { TIMER_RESOLUTION_TYPE_NANOSECOND, TIMER_RESOLUTION_TYPE_MICROSECOND, TIMER_RESOLUTION_TYPE_MILISECOND }
 Type options available for tick resolution. More...
 
enum  timer_chan_type_t { TIMER_CHAN_TYPE_CONTINUOUS, TIMER_CHAN_TYPE_ONESHOT }
 Type options available for timer channel notification. More...
 

Functions

status_t TIMING_Init (const timing_instance_t *const instance, const timer_config_t *const config)
 Initialize the timer instance and timer channels with value from input configuration structure. More...
 
void TIMING_Deinit (const timing_instance_t *const instance)
 De-initialize a timer instance. More...
 
void TIMING_StartChannel (const timing_instance_t *const instance, const uint8_t channel, const uint32_t periodTicks)
 Starts the timer channel counting. More...
 
void TIMING_StopChannel (const timing_instance_t *const instance, const uint8_t channel)
 Stop the timer channel counting. More...
 
uint32_t TIMING_GetElapsed (const timing_instance_t *const instance, const uint8_t channel)
 Get elapsed ticks. More...
 
uint32_t TIMING_GetRemaining (const timing_instance_t *const instance, const uint8_t channel)
 Get remaining ticks. More...
 
void TIMING_EnableNotification (const timing_instance_t *const instance, const uint8_t channel)
 Enable channel notifications. More...
 
void TIMING_DisableNotification (const timing_instance_t *const instance, const uint8_t channel)
 Disable channel notifications. More...
 
status_t TIMING_GetResolution (const timing_instance_t *const instance, const timer_resolution_type_t type, uint64_t *const resolution)
 Get tick resolution. More...
 
status_t TIMING_GetMaxPeriod (const timing_instance_t *const instance, const timer_resolution_type_t type, uint64_t *const maxPeriod)
 Get max period in engineering units. More...
 

Enumeration Type Documentation

Type options available for timer channel notification.

Implements : timer_chan_type_t_Class

Enumerator
TIMER_CHAN_TYPE_CONTINUOUS 

Timer channel creates continuous notification

TIMER_CHAN_TYPE_ONESHOT 

Timer channel creates one-shot notification

Definition at line 56 of file timing_pal.h.

Type options available for tick resolution.

Implements : timer_resolution_type_t_Class

Enumerator
TIMER_RESOLUTION_TYPE_NANOSECOND 

Tick resolution is nanosecond

TIMER_RESOLUTION_TYPE_MICROSECOND 

Tick resolution is microsecond

TIMER_RESOLUTION_TYPE_MILISECOND 

Tick resolution is millisecond

Definition at line 44 of file timing_pal.h.

Function Documentation

void TIMING_Deinit ( const timing_instance_t *const  instance)

De-initialize a timer instance.

This function de-initializes timer instance. In order to use the timer instance again, TIMING_Init must be called.

Parameters
[in]instanceThe pointer to timer instance number structure

Definition at line 562 of file timing_pal.c.

void TIMING_DisableNotification ( const timing_instance_t *const  instance,
const uint8_t  channel 
)

Disable channel notifications.

This function disables channel notification.

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

Definition at line 1223 of file timing_pal.c.

void TIMING_EnableNotification ( const timing_instance_t *const  instance,
const uint8_t  channel 
)

Enable channel notifications.

This function enables channel notification.

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

Definition at line 1133 of file timing_pal.c.

uint32_t TIMING_GetElapsed ( const timing_instance_t *const  instance,
const uint8_t  channel 
)

Get elapsed ticks.

This function gets elapsed time since the last notification by ticks. The elapsed time by nanosecond, microsecond or millisecond is the result of this function multiplies by the result of the TIMING_GetResolution function.

Parameters
[in]instanceThe pointer to timer instance number structure
[in]channelThe channel number
Returns
Number of ticks elapsed since last notification

Definition at line 884 of file timing_pal.c.

status_t TIMING_GetMaxPeriod ( const timing_instance_t *const  instance,
const timer_resolution_type_t  type,
uint64_t *const  maxPeriod 
)

Get max period in engineering units.

This function gets max period in engineering units.

Parameters
[in]instanceThe pointer to timer instance number structure
[in]typeResolution type
[out]maxPeriodThe pointer to max period in engineering units
Returns
Operation status
  • STATUS_SUCCESS: Operation was successful
  • STATUS_ERROR : The timer frequency is not fit to resolution type

Definition at line 1489 of file timing_pal.c.

uint32_t TIMING_GetRemaining ( const timing_instance_t *const  instance,
const uint8_t  channel 
)

Get remaining ticks.

This function gets remaining time to next notification by ticks. The remaining time by nanosecond, microsecond or millisecond is the result of this function multiplies by the result of the TIMING_GetResolution function.

Parameters
[in]instanceThe pointer to timer instance number structure
[in]channelThe channel number
Returns
Number of ticks remaining to next notification

Definition at line 1009 of file timing_pal.c.

status_t TIMING_GetResolution ( const timing_instance_t *const  instance,
const timer_resolution_type_t  type,
uint64_t *const  resolution 
)

Get tick resolution.

This function gets tick resolution in engineering units (nanosecond, microsecond or millisecond). The result of this function is used to calculate period, remaining time or elapsed time in engineering units.

Parameters
[in]instanceThe pointer to timer instance number structure
[in]typeResolution type
[out]resolutionThe pointer to resolution in engineering units
Returns
Operation status
  • STATUS_SUCCESS: Operation was successful
  • STATUS_ERROR : The timer frequency is not fit to resolution type

Definition at line 1310 of file timing_pal.c.

status_t TIMING_Init ( const timing_instance_t *const  instance,
const timer_config_t *const  config 
)

Initialize the timer instance and timer channels with value from input configuration structure.

This function initializes clock source, prescaler of the timer instance(except LPIT, PIT), the final value of counter (only FTM). This function also setups notification type and callback function of timer channel. The timer instance number and its configuration structure shall be passed as arguments. Timer channels do not start counting by default after calling this function. The function TIMING_StartChannel must be called to start the timer channel counting.

Parameters
[in]instanceThe pointer to timer instance number structure
[in]configThe pointer to configuration structure
Returns
Operation status
  • STATUS_SUCCESS: Operation was successful
  • STATUS_ERROR : Operation was fail if the timer instance is out of range For example: Timing over LPIT but the instance is not LPIT instance(TIMING_OVER_LPIT0_INSTANCE)
  • STATUS_ERROR : Operation was fail if the FTM instance has been initialized

Definition at line 484 of file timing_pal.c.

void TIMING_StartChannel ( const timing_instance_t *const  instance,
const uint8_t  channel,
const uint32_t  periodTicks 
)

Starts the timer channel counting.

This function starts channel counting with a new period in ticks. Note that:

  • If the timer is PIT or LPIT, to abort the current timer channel period and start a timer channel period with a new value, the timer channel must be stopped and started again.
  • If the timer is FTM, this function start channel by enable channel interrupt generation.
  • LPTMR and FTM is 16 bit timer, so the input period must be smaller than 65535.
  • LPTMR and FTM is 16 bit timer, so the input period must be smaller than 65535.
Parameters
[in]instanceThe pointer to timer instance number structure
[in]channelThe channel number
[in]periodTicksThe input period in ticks

Definition at line 632 of file timing_pal.c.

void TIMING_StopChannel ( const timing_instance_t *const  instance,
const uint8_t  channel 
)

Stop the timer channel counting.

This function stop channel counting. Note that if the timer is FTM, this function stop channel by disable channel interrupt generation.

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

Definition at line 788 of file timing_pal.c.