Detailed Description

This header file includes macros and definitions to access the timer resource of a microcontroller. The general timer resource is initialised with the function McTmrInit(). One timer period is equal to one timer tick.

Functions which rely on the general timer resource always take timer ticks as function parameter. In order to convert a time period into timer ticks the function McTmrTimeToTicks() is provided.

Include dependency graph for mc_tmr.h:

Data Structures
struct	McTmrFunc_s

struct	McTmrSoft_s

Macros
#define	MC_TMR_FUNCTION 4

#define	MC_TMR_FUNCTION_INT 0

#define	MC_TMR_MAX 4

#define	MC_TMR_PERIOD 1000

Typedefs
typedef void(*	TmrHandler_fn) (void)

Enumerations
enum	TMR_ERR_e { eTMR_ERR_OK = 0 , eTMR_ERR_RUN , eTMR_ERR_START , eTMR_ERR_PARM_INVALID , eTMR_ERR_RES_INVALID , eTMR_ERR_RES_FULL }

enum	TMR_CTRL_e { eTMR_CTRL_STOP = 0 , eTMR_CTRL_START = 1 , eTMR_CTRL_ONESHOT = 2 }

enum	TMR_HRES_TICK_e { eTMR_HRES_TICK_50ns = 1 , eTMR_HRES_TICK_100ns , eTMR_HRES_TICK_200ns , eTMR_HRES_TICK_500ns , eTMR_HRES_TICK_1us , eTMR_HRES_TICK_2us , eTMR_HRES_TICK_5us , eTMR_HRES_TICK_10us , eTMR_HRES_TICK_20us , eTMR_HRES_TICK_50us }

Functions
Status_tv	McTmrFunctionInit (TmrHandler_fn fnHandlerV, uint32_t ulTicksV, uint8_t ubControlV)

void	McTmrFunctionProcess (void)

Status_tv	McTmrFunctionRelease (uint8_t ubTmrNumV)

Status_tv	McTmrFunctionStart (uint8_t ubTmrNumV)

Status_tv	McTmrFunctionStop (uint8_t ubTmrNumV)

Status_tv	McTmrHResInit (uint8_t ubTickPeriodV)

void	McTmrHResStart (void)

uint32_t	McTmrHResTick (void)

void	McTmrInit (void)

Status_tv	McTmrPeriodRelease (uint8_t ubTmrNumV)

Status_tv	McTmrPeriodExpired (uint8_t ubTmrNumV)

Status_tv	McTmrPeriodStart (uint32_t ulTicksV)

void	McTmrStart (void)

void	McTmrStop (void)

uint32_t	McTmrTick (void)

uint32_t	McTmrTicksToTime (uint32_t ulTickV)

uint32_t	McTmrTimeToTicks (uint32_t ulTimeV)

Macro Definition Documentation

◆ MC_TMR_FUNCTION

#define MC_TMR_FUNCTION 4

Number of function timers.

This symbol defines the maximum number of function timers. The default value is set to 4.

◆ MC_TMR_FUNCTION_INT

#define MC_TMR_FUNCTION_INT 0

Handle timer function within timer interrupt.

If this define is set to 1, than timer function will be handles within timer interrupt. In other case this timer function processing have to be triggered by calling McTmrFunctionProcess() from main loop. In this case the timer interrupt will be quit as possible, not further handlers will be called within it!

◆ MC_TMR_MAX

#define MC_TMR_MAX 4

Number of software timers.

This symbol defines the maximum number of software timers. The default value is set to 4.

◆ MC_TMR_PERIOD

#define MC_TMR_PERIOD 1000

Period of timer interrupt.

This symbol defines the period of the timer interrupt. The value is a multiple of 1 microsecond. It is used for timing services. Please set this value to the timer interrupt period of the target system.

Typedef Documentation

◆ TmrHandler_fn

typedef void(* TmrHandler_fn) (void)

Timer callback function.

Functions can be called periodically by the timer or in a one-shot mode. The functions do not carry any parameters. They do not return any value. The declaration of a timer function is:

void MyTimerFunction(void);

Enumeration Type Documentation

◆ TMR_CTRL_e

enum TMR_CTRL_e

The mode of a timer can be controlled with the values taken from the TMR_CTRL_e enumeration.

Enumerator
eTMR_CTRL_STOP	stop the timer
eTMR_CTRL_START	start the timer
eTMR_CTRL_ONESHOT	timer is in one-shot mode

◆ TMR_ERR_e

enum TMR_ERR_e

The error codes of the timer services have the prefix TMR_ERR_e.

Enumerator
eTMR_ERR_OK	eTMR_ERR_OK no error
eTMR_ERR_RUN	eTMR_ERR_RUN timer is running
eTMR_ERR_START	eTMR_ERR_START timer is NOT started/initialised
eTMR_ERR_PARM_INVALID	eTMR_ERR_PARM_INVALID timer parameter is not valid or out of range
eTMR_ERR_RES_INVALID	eTMR_ERR_RES_INVALID timer resource is not valid
eTMR_ERR_RES_FULL	eTMR_ERR_RES_FULL timer resource is full

◆ TMR_HRES_TICK_e

enum TMR_HRES_TICK_e

The timer tick period of the optional high-resolution timer (McTmrHResInit())is defined by this enumeration.

Enumerator
eTMR_HRES_TICK_50ns	50 ns
eTMR_HRES_TICK_100ns	100 ns
eTMR_HRES_TICK_200ns	200 ns
eTMR_HRES_TICK_500ns	500 ns
eTMR_HRES_TICK_1us	1 us
eTMR_HRES_TICK_2us	2 us
eTMR_HRES_TICK_5us	5 us
eTMR_HRES_TICK_10us	10 us
eTMR_HRES_TICK_20us	20 us
eTMR_HRES_TICK_50us	50 us

Function Documentation

◆ McTmrFunctionInit()

Status_tv McTmrFunctionInit	(	TmrHandler_fn	fnHandlerV,
		uint32_t	ulTicksV,
		uint8_t	ubControlV )

Initialise function timer.

Parameters

fnHandlerV	- pointer to function callback
ulTicksV	- number of timer ticks
ubControlV	- configuration parameter

Returns: Negative value in case of an error, a positive value denotes the associated timer number

See also: McTmrFunctionRelease()

The function fnHandlerV is registered to the timer. It is called after a period of ulTmrTicksV. The time period of one timer tick depends on the implementation and hardware limitations. The default value shall be 1 millisecond. The function McTmrTicksToTime() can be used to evaluate the time period of one timer tick.

The parameter ubControlV is defined by the enumeration TMR_CTRL_e. The timer associated to the function can initially be in stopped state (eTMR_CTRL_STOP) or active state (eTMR_CTRL_START). In addition it is possible to call the function only one time (eTMR_CTRL_ONESHOT). In this case ulTicksV defines a delay.

The function returns a positive timer resource number that can be used to release the function fnHandlerV with McTmrFunctionRelease().

void MyPeriodicFunction(void)
{
   // ... do some periodic stuff
}
 
void MyOneShotFunction(void)
{
   // ... do something only once
}
 
void ApplicationTimerInit(void)
{
   Status_tv  tvTmrResultT;
 
   //-------------------------------------------------------------
   // call periodic function every 10 timer ticks
   //
   McTmrFunctionInit(MyPeriodicFunction, 10, eTMR_CTRL_START);
 
   //-------------------------------------------------------------
   // call one-shot function after 20 timer ticks
   // It will be started later with McTmrFunctionStart()
   //
   tvTmrResultT = McTmrFunctionInit(MyOneShotFunction, 20,
                                    eTMR_CTRL_STOP | eTMR_CTRL_ONESHOT);
 
   // ....
 
   if(tvTmrResultT > 0)
   {
      //------------------------------------------------
      // start one-shot function timer now
      //
      McTmrFunctionStart(tvTmrResultT);
   }
 
}

◆ McTmrFunctionProcess()

void McTmrFunctionProcess ( void )

Process Timer Functions outside of timer interrupt.

See also: McTmrFunctionInit()

In some cases it is not allowed to call some functions within of an interrupt, like timer interrupt. In that case user can set

◆ McTmrFunctionRelease()

Status_tv McTmrFunctionRelease ( uint8_t ubTmrNumV )

Release function timer.

Parameters

ubTmrNumV - function timer number

Returns: eTMR_ERR_OK or negative value taken from TMR_ERR_e

See also: McTmrFunctionInit()

This function releases the timer function with number ubTmrNumV. initialises a timer resource of the microcontroller. The function returns eTMR_ERR_RES_INVALID if the parameter ubTmrNumV is not valid.

◆ McTmrFunctionStart()

Status_tv McTmrFunctionStart ( uint8_t ubTmrNumV )

Start function timer.

Parameters

ubTmrNumV - function timer number

Returns: eTMR_ERR_OK or negative value taken from TMR_ERR_e

See also: McTmrFunctionInit()

This function starts the timer function with number ubTmrNumV. The function returns eTMR_ERR_RES_INVALID if the parameter ubTmrNumV is not valid.

◆ McTmrFunctionStop()

Status_tv McTmrFunctionStop ( uint8_t ubTmrNumV )

Stop function timer.

Parameters

ubTmrNumV - function timer number

Returns: eTMR_ERR_OK or negative value taken from TMR_ERR_e

See also: McTmrFunctionInit()

This function stops the timer function with number ubTmrNumV. The function returns eTMR_ERR_RES_INVALID if the parameter ubTmrNumV is not valid.

◆ McTmrHResInit()

Status_tv McTmrHResInit ( uint8_t ubTickPeriodV )

Initialise High-Resolution timer.

Parameters

ubTickPeriodV - Tick period taken from TMR_HRES_TICK_e

Returns: eTMR_ERR_OK or negative error value taken from TMR_ERR_e

The function initialises the optional high-resolution timer with the tick period given by ubTickPeriodV. If the requested tick period is not supported the function returns -eTMR_ERR_RES_INVALID. The high-resolution timer is started by calling McTmrHResStart().

◆ McTmrHResStart()

void McTmrHResStart ( void )

Start High-Resolution time measurement.

This function starts the high-resolution time measurement, i.e. it starts the tick counter with an initial value of 0. The actual tick value can be evaluated with McTmrHResTick().

◆ McTmrHResTick()

uint32_t McTmrHResTick ( void )

Get High-Resolution tick value.

Returns: High-Resolution tick value

This function returns the high-resolution tick value.

◆ McTmrInit()

void McTmrInit ( void )

Initialise Timer.

This function initialises the general timer resource of the microcontroller.

The timer can be stopped by calling McTmrStop().

◆ McTmrPeriodExpired()

Status_tv McTmrPeriodExpired ( uint8_t ubTmrNumV )

Check if software timer expired.

Parameters

ubTmrNumV - Timer number

Returns: eTMR_ERR_OK or negative error value taken from TMR_ERR_e

This function checks for the expiration of a time period which has been started by calling McTmrPeriodStart(). The function returns eTMR_ERR_OK if the time period has elapsed or -eTMR_ERR_RUN if the timer is still active. When timer expired and returned eTMR_ERR_OK value, so this timer will be released for further usage.

◆ McTmrPeriodRelease()

Status_tv McTmrPeriodRelease ( uint8_t ubTmrNumV )

Release a software timer.

Parameters

ubTmrNumV - Timer number

Returns: eTMR_ERR_OK or negative error value taken from TMR_ERR_e

This function releases a software timer. A software timer that is in use will be stopped and released for further usage.

◆ McTmrPeriodStart()

Status_tv McTmrPeriodStart ( uint32_t ulTicksV )

Start a timer period.

Parameters

ulTicksV - ticks before timer elapse

Returns: Timer number or negative error value taken from TMR_ERR_e

This function configures a software timer that expires after a total count of ulTicksV. The function returns a negative value taken from the enumeration TMR_ERR_e in case of an error. A positive return value denotes the associated software timer number, which is necessary for testing with McTmrPeriodExpired(). The number of software timers is limited to MC_TMR_MAX.

Attention: When timer expired, it will be NOT released by default.

◆ McTmrStart()

void McTmrStart ( void )

Start Timer.

See also: McTmrStop()

This function starts the timer. The timer continues to count from where it has been stopped the last time.

◆ McTmrStop()

void McTmrStop ( void )

Stop Timer.

See also: McTmrStart()

This function stops the timer. The contents of the internal timer register remains unchanged.

◆ McTmrTick()

uint32_t McTmrTick ( void )

Get timer tick.

Returns: Current timer tick value

The function returns the current timer tick value. It can be used to check in the program main loop if the event "timer tick" occurred.

◆ McTmrTicksToTime()

uint32_t McTmrTicksToTime ( uint32_t ulTickV )

Convert tick value to time.

Parameters

ulTickV - Tick value

Returns: Equivalent time in microseconds

See also: McTmrTimeToTicks()

The function converts the parameter ulTickV into the equivalent time value. The returned time value is given in microseconds.

◆ McTmrTimeToTicks()

uint32_t McTmrTimeToTicks ( uint32_t ulTimeV )

Convert time value to ticks.

Parameters

ulTimeV - Time value in microseconds

Returns: Equivalent number of timer ticks

See also: McTmrTicksToTime()

The function converts the parameter ulTimeV, which is a multiple of 1 microsecond, into the equivalent number of timer ticks. If the time value is not a multiple of one timer tick, the return value is rounded to the next lower possible time value.

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ MC_TMR_FUNCTION

◆ MC_TMR_FUNCTION_INT

◆ MC_TMR_MAX

◆ MC_TMR_PERIOD

Typedef Documentation

◆ TmrHandler_fn

Enumeration Type Documentation

◆ TMR_CTRL_e

◆ TMR_ERR_e

◆ TMR_HRES_TICK_e

Function Documentation

◆ McTmrFunctionInit()

◆ McTmrFunctionProcess()

◆ McTmrFunctionRelease()

◆ McTmrFunctionStart()

◆ McTmrFunctionStop()

◆ McTmrHResInit()

◆ McTmrHResStart()

◆ McTmrHResTick()

◆ McTmrInit()

◆ McTmrPeriodExpired()

◆ McTmrPeriodRelease()

◆ McTmrPeriodStart()

◆ McTmrStart()

◆ McTmrStop()

◆ McTmrTick()

◆ McTmrTicksToTime()

◆ McTmrTimeToTicks()