CANopen Slave Documentation
Version 6.16.04
Loading...
Searching...
No Matches
mc_tmr.h File Reference

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

TmrHandler_fn

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

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,
// ....
if(tvTmrResultT > 0)
{
//------------------------------------------------
// start one-shot function timer now
//
McTmrFunctionStart(tvTmrResultT);
}
}
int32_t Status_tv
Data type for status value.
Definition mc_compiler.h:268
@ eTMR_CTRL_START
Definition mc_tmr.h:164
@ eTMR_CTRL_STOP
Definition mc_tmr.h:161
@ eTMR_CTRL_ONESHOT
Definition mc_tmr.h:167
Status_tv McTmrFunctionStart(uint8_t ubTmrNumV)
Start function timer.
Status_tv McTmrFunctionInit(TmrHandler_fn fnHandlerV, uint32_t ulTicksV, uint8_t ubControlV)
Initialise function timer.

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