SYSTIMER: Methods

Arduino SYSTIMER

SYSTIMER
Methods
SYSTIMER_STATUS_t SYSTIMER_Init (SYSTIMER_t *handle)
 Initializes SYSTIMER APP.
uint32_t SYSTIMER_CreateTimer (uint32_t period, SYSTIMER_MODE_t mode, SYSTIMER_CALLBACK_t callback, void *args)
 Creates a new software timer.
SYSTIMER_STATUS_t SYSTIMER_StartTimer (uint32_t id)
 Starts the software timer.
SYSTIMER_STATUS_t SYSTIMER_StopTimer (uint32_t id)
 Stops the software timer.
SYSTIMER_STATUS_t SYSTIMER_RestartTimer (uint32_t id, uint32_t microsec)
 Function to modify the time interval and restart the timer for the new time interval.

SYSTIMER_STATUS_t SYSTIMER_DeleteTimer (uint32_t id)
 Deletes the software timer from the timer list.
uint32_t SYSTIMER_GetTime (void)
 Gives the current hardware SysTick time in microsecond since start of hardware SysTick timer.
uint32_t SYSTIMER_GetTickCount (void)
 Gives the SysTick count.
SYSTIMER_STATE_t SYSTIMER_GetTimerState (uint32_t id)
 Gives the current state of software timer.
DAVE_APP_VERSION_t SYSTIMER_GetAppVersion (void)
 Get SYSTIMER APP version.

Methods


Function Documentation

uint32_t SYSTIMER_CreateTimer ( uint32_t  period,
SYSTIMER_MODE_t  mode,
SYSTIMER_CALLBACK_t  callback,
void *  args 
)

Creates a new software timer.

Parameters:
periodtimer period value in microseconds. Range: (SYSTIMER_TICK_PERIOD_US) to pow(2,32).
modeMode of timer(ONE_SHOT/PERIODIC). Refer SYSTIMER_MODE_t for details.
callbackCall back function of the timer(No Macros are allowed).
argsCall back function parameter.
Returns:
uint32_t returns timer ID if timer created successfully otherwise returns 0 if timer creation failed. Range: 0 to 16, 0: Invalid timer ID, 1-16: Valid timer ID.
Description:
API for creating a new software timer instance. This also add created software timer to timer list.
Note :
1. This APP uses SysTick exception for controlling the timer list. Call back function registered through this function will be called in SysTick exception when the software timer is expired i.e the software timers callback is executed in the interrupt context.
2. Due to time at which software timer creation asked by user will not be in synchronize with Hardware SysTick timer, the count value used during creation of software timer will not create starting/initial period same as expected value. It is decided to add one extra count(HW_TIMER_ADDITIONAL_CNT) with Software timer. Impact of this additional count(HW_TIMER_ADDITIONAL_CNT) is, first SW timer period(Initial one) is always equal to or more than expected/configured.
3. Callbacks are executed in round robin manner if more than one software timers are created with same period value. Last created software is having higher priority and its associated callback is executed first.
4. Avoid any call to wait, infinitive while loop, blocking calls or creating software timer in ISR because their behavior could be corrupted when called from an ISR.
5. Software timers are based on 24-bit Hardware SysTick counters, so maximum counts can achieve is pow(2,24) *(1/fCPU) * 1E6, where fCPU is in hertz. Software timers are designed for times between microseconds and seconds. For longer times, application code need to ensure to take necessary action.
6. Software timer period value must be equal to SysTick Interval or integer multiple of a number with SysTick interval (i.e. SysTick Interval * n, where n is integer number, n can be 1,2,3,4... but n should not be fractional or float number). And also software timer period value should not be 0 or less than Hardware SysTick Interval.
Example Usage:
  #include <DAVE.h>
  #define ONESEC 1000000U
  void LED_Toggle_EverySec(void)
  {
    // Add user code here
  }

  int main(void)
  {
    uint32_t TimerId;
    // ... Initializes APPs configuration ...
    DAVE_Init(); // SYSTIMER APP Initialized during DAVE Initialization
    // Create Software timer
    TimerId = (uint32_t)SYSTIMER_CreateTimer(ONESEC,SYSTIMER_MODE_PERIODIC,(void*)LED_Toggle_EverySec,NULL);
    if (TimerId != 0U)
    {
      //software timer is created successfully
      //Add user code here
    }
    else
    {
      // //software timer creation is failed
    }
    while (1)
    {

    }
    return (1);
  }


Definition at line 390 of file SYSTIMER.c.

References g_timer_tbl, SYSTIMER_MODE_ONE_SHOT, SYSTIMER_MODE_PERIODIC, and SYSTIMER_STATE_STOPPED.

Deletes the software timer from the timer list.

Parameters:
idtimer ID obtained from SYSTIMER_CreateTimer. Range : 1 to 16
Returns:
SYSTIMER_STATUS_t APP status. Refer SYSTIMER_STATUS_t for details.
Description:
API for deleting the created software timer instance from timer list.
Note : This API must be called after software timer is created using SYSTIMER_CreateTimer API with generated ID and enable XMC_ASSERT for better understanding of API behavioral in run time.
Example Usage:
  #include <DAVE.h>
  #define ONESEC 1000000U
  void LED_Toggle_EverySec(void)
  {
    // Add user code here
  }

  int main(void)
  {
    uint32_t TimerId;
    SYSTIMER_STATUS_t status;
    // ... Initializes APPs configuration ...
    DAVE_Init(); // SYSTIMER APP Initialized during DAVE Initialization
    // Create Software timer
    TimerId = (uint32_t)SYSTIMER_CreateTimer(ONESEC,SYSTIMER_MODE_PERIODIC,(void*)LED_Toggle_EverySec,NULL);
    if (TimerId != 0U)
    {
      //timer is created successfully, now start/run software timer
      status = SYSTIMER_StartTimer(TimerId);
      if (status == SYSTIMER_STATUS_SUCCESS)
      {

      // User code


      status = SYSTIMER_StopTimer(TimerId);
      //User code

        if (status == SYSTIMER_STATUS_SUCCESS)
        {
          //User code


          status = SYSTIMER_DeleteTimer(TimerId);
          if (status == SYSTIMER_STATUS_SUCCESS)
          {
            // Software timer has deleted
          }
          else
          {
            // Error during software timer delete operation
          }
        }
        else
        {
           // Error during software timer stop operation
        }
      }
      else
      {
        // Error during software timer start operation
      }
    }
    else
    {
      // timer ID Can not be zero
    }
    // ... infinite loop ...
    while (1)
    {

    }
    return (1);
  }


Definition at line 541 of file SYSTIMER.c.

References g_timer_tbl, SYSTIMER_STATE_NOT_INITIALIZED, SYSTIMER_STATE_STOPPED, SYSTIMER_STATUS_FAILURE, and SYSTIMER_STATUS_SUCCESS.

DAVE_APP_VERSION_t SYSTIMER_GetAppVersion ( void  )

Get SYSTIMER APP version.

Returns:
DAVE_APP_VERSION_t APP version information (major, minor and patch number).
Description:
The function can be used to check application software compatibility with a specific version of the APP.
 #include <DAVE.h>

 int main(void)
 {
  DAVE_Init();
  DAVE_APP_VERSION_t systimer_version;
  systimer_version = SYSTIMER_GetAppVersion();
  if ((systimer_version.major == 4U) && (systimer_version.minor == 1U))
  {
    // Add application code here
    while (1)
   {
   }
  }
   return(1);
 }

Definition at line 332 of file SYSTIMER.c.

uint32_t SYSTIMER_GetTickCount ( void  )

Gives the SysTick count.

Returns:
uint32_t returns SysTick count. Range: 0 to pow(2,32).
Description:
API to get hardware SysTick counts since start of hardware SysTick timer.
Example Usage:
  #include <DAVE.h>
  #include <DAVE.h>
  #define ONESEC 1000000U
  void LED_Toggle_EverySec(void)
  {
    // Add user code here
  }


  int main(void)
  {
    uint32_t TimerId;
    uint32_t SysTick_Count;
    SYSTIMER_STATUS_t status;
    // ... Initializes APPs configuration ...
    DAVE_Init(); // SYSTIMER APP Initialized during DAVE Initialization
    // Create Software timer
    TimerId = (uint32_t)SYSTIMER_CreateTimer(ONESEC,SYSTIMER_MODE_PERIODIC,(void*)LED_Toggle_EverySec,NULL);
    if (TimerId != 0U)
    {
      //timer is created successfully, now start/run software timer
      status = SYSTIMER_StartTimer(TimerId);
      if (status == SYSTIMER_STATUS_SUCCESS)
      {
        // Add user code here


         SysTick_Count = SYSTIMER_GetTickCount();
         // Add user code here

      }
      else
      {
      // Error during software timer start operation
      }
    }
    else
    {
      // timer ID Can not be zero
    }
    // ... infinite loop ...
    while (1)
    {

    }
    return (1);
  }


Definition at line 585 of file SYSTIMER.c.

uint32_t SYSTIMER_GetTime ( void  )

Gives the current hardware SysTick time in microsecond since start of hardware SysTick timer.

Returns:
uint32_t returns current SysTick time in microsecond. Range: (SYSTIMER_TICK_PERIOD_US) to pow(2,32).
Description:
API to get current hardware SysTick time in microsecond since start of hardware SysTick timer.
Example Usage:
  #include <DAVE.h>
  #define ONESEC 1000000U
  void LED_Toggle_EverySec(void)
  {
    // Add user code here
  }

  int main(void)
  {
    uint32_t TimerId;
    uint32_t SysTick_Time;
    SYSTIMER_STATUS_t status;
    // ... Initializes APPs configuration ...
    DAVE_Init(); // SYSTIMER APP Initialized during DAVE Initialization
    // Create Software timer
    TimerId = (uint32_t)SYSTIMER_CreateTimer(ONESEC,SYSTIMER_MODE_PERIODIC,(void*)LED_Toggle_EverySec,NULL);
    if (TimerId != 0U)
    {
      //timer is created successfully, now start/run software timer
      status = SYSTIMER_StartTimer(TimerId);
      if (status == SYSTIMER_STATUS_SUCCESS)
      {
        // Add user code here


         SysTick_Time = SYSTIMER_GetTime();
         // Add user code here

      }
      else
      {
      // Error during software timer start operation
      }
    }
    else
    {
      // timer ID Can not be zero
    }
    // ... infinite loop ...
    while (1)
    {

    }
    return (1);
  }


Definition at line 577 of file SYSTIMER.c.

Gives the current state of software timer.

Parameters:
idtimer ID obtained from SYSTIMER_CreateTimer. Range : 1 to 16
Returns:
SYSTIMER_STATE_t Software timer state. Refer SYSTIMER_STATE_t for details.
Description:
API to get current software timer state.
Example Usage:
  #include <DAVE.h>
  #define ONESEC 1000000U
  #define NEW_INTERVAL (ONESEC * 10U)
  void LED_Toggle_EverySec(void)
  {
    // Add user code here
  }

  int main(void)
  {
    uint32_t TimerId;
    SYSTIMER_STATUS_t status;
    SYSTIMER_STATE_t timer_state;
    // ... Initializes APPs configuration ...
    DAVE_Init(); // SYSTIMER APP Initialized during DAVE Initialization
    // Create Software timer
    TimerId = (uint32_t)SYSTIMER_CreateTimer(ONESEC,SYSTIMER_MODE_PERIODIC,(void*)LED_Toggle_EverySec,NULL);
    if (TimerId != 0U)
    {
      //timer is created successfully, now start/run software timer
      status = SYSTIMER_StartTimer(TimerId);
      timer_state = SYSTIMER_GetTimerState(TimerId);  // use case scenario 1
      if (timer_state == SYSTIMER_STATE_RUNNING)
      {
        // software timer start operation is successful
        // Add user code here
      }
      else
      {
        // Error during software timer start operation
      }

      // Add user code here

      // user decided to change software interval, oops but user don't know the timer state

      timer_state = SYSTIMER_GetTimerState(TimerId);   // use case scenario 2
      if (timer_state == SYSTIMER_STATE_RUNNING)
      {
        status = SYSTIMER_StopTimer(TimerId);
        status = SYSTIMER_RestartTimer(TimerId,NEW_INTERVAL);
        // Add user code here
      }
      else if (timer_state == SYSTIMER_STATE_STOPPED)
      {
        status = SYSTIMER_RestartTimer(TimerId,NEW_INTERVAL);
      }
      else if (timer_state == SYSTIMER_STATE_NOT_INITIALIZED)
      {
       // user has already deleted this software timer but need to recreate
       TimerId = (uint32_t)SYSTIMER_CreateTimer(NEW_INTERVAL,SYSTIMER_MODE_PERIODIC,(void*)LED_Toggle_EverySec,NULL);
       status = SYSTIMER_StartTimer(TimerId);
       // Add user code here

      }
    }
    else
    {
      // timer ID Can not be zero
    }
    // ... infinite loop ...
    while (1)
    {

    }
    return (1);
  }


Definition at line 593 of file SYSTIMER.c.

References g_timer_tbl.

Initializes SYSTIMER APP.

Parameters:
handlePointer pointing to SYSTIMER APP data structure. Refer SYSTIMER_t for details.
Returns:
SYSTIMER_STATUS_t APP status. Refer SYSTIMER_STATUS_t for details.
Description:
Initializes the SysTick counter as per the SysTick interval specified by the user and start the SysTick counter. It also initializes global variables.
Example Usage:
   #include <DAVE.h>         //Declarations from DAVE Code Generation (includes SFR declaration)

   int main(void)
   {
     SYSTIMER_STATUS_t init_status;

     init_status = (SYSTIMER_STATUS_t)SYSTIMER_Init(&SYSTIMER_0); // Initialization of SYSTIMER APP
     if (init_status == SYSTIMER_STATUS_SUCCESS)
     {
       // Add application code here
       while(1)
       {
       }
     }
     else
     {
      XMC_DEBUG("main: Application initialization failed");
      while(1)
      {
      }
     }
      return (1);
  }

Definition at line 346 of file SYSTIMER.c.

References SYSTIMER::init_status, SYSTIMER_STATUS_FAILURE, and SYSTIMER_STATUS_SUCCESS.

SYSTIMER_STATUS_t SYSTIMER_RestartTimer ( uint32_t  id,
uint32_t  microsec 
)

Function to modify the time interval and restart the timer for the new time interval.

Parameters:
idID of already created system timer. Range : 1 to 16
microsecnew time interval. Range: (SYSTIMER_TICK_PERIOD_US) to pow(2,32).
Returns:
SYSTIMER_STATUS_t APP status. Refer SYSTIMER_STATUS_t for details.
Description:
API for restarting the created software timer instance with new time interval.
Note : This API must be called after software timer is created using SYSTIMER_CreateTimer API with generated ID and enable XMC_ASSERT for better understanding of API behavioral in run time.
Example Usage:
Demonstrate SYSTIMER_RestartTimer API
  #include <DAVE.h>
  #define ONESEC 1000000U
  #define NEW_INTERVAL (ONESEC * 10U)
  void LED_Toggle_EverySec(void)
  {
    // Add user code here
  }

  int main(void)
  {
    uint32_t TimerId;
    SYSTIMER_STATUS_t status;
    // ... Initializes APPs configuration ...
    DAVE_Init(); // SYSTIMER APP Initialized during DAVE Initialization
    // Create Software timer
    TimerId = (uint32_t)SYSTIMER_CreateTimer(ONESEC,SYSTIMER_MODE_PERIODIC,(void*)LED_Toggle_EverySec,NULL);
    if (TimerId != 0U)
    {
      //timer is created successfully
      // Start/Run Software timer
      status = SYSTIMER_StartTimer(TimerId);
      if (status == SYSTIMER_STATUS_SUCCESS)
      {

        // User code


        status = SYSTIMER_StopTimer(TimerId);
        //User code

        if (status == SYSTIMER_STATUS_SUCCESS)
        {
          //User code


          status = SYSTIMER_RestartTimer(TimerId,NEW_INTERVAL);
          if (status == SYSTIMER_STATUS_SUCCESS)
          {
            // timer configured with the new time interval and is running
          }
          else
          {
            // Error during software timer restart operation
          }
        }
        else
        {
           // Error during software timer stop operation
        }
      }
      else
      {
        // Error during software timer start operation
      }
    }
    else
    {
      // timer ID can not be zero
    }
    while (1)
    {

    }
    return (1);
  }


Definition at line 501 of file SYSTIMER.c.

References g_timer_tbl, SYSTIMER_StartTimer(), SYSTIMER_STATE_NOT_INITIALIZED, SYSTIMER_STATE_STOPPED, SYSTIMER_STATUS_FAILURE, SYSTIMER_STATUS_SUCCESS, and SYSTIMER_StopTimer().

Starts the software timer.

Parameters:
idtimer ID obtained from SYSTIMER_CreateTimer. Range : 1 to 16
Returns:
SYSTIMER_STATUS_t APP status. Refer SYSTIMER_STATUS_t for details.
Description:
API for starting a software timer instance.
Note : This API must be called after software timer is created using SYSTIMER_CreateTimer API with generated ID and enable XMC_ASSERT for better understanding of API behavioral in run time.
Example Usage:
  #include <DAVE.h>
  #define ONESEC 1000000U
  void LED_Toggle_EverySec(void)
  {
    // Add user code here
  }

  int main(void)
  {
    uint32_t TimerId;
    SYSTIMER_STATUS_t status;
    // ... Initializes APPs configuration ...
    DAVE_Init(); // SYSTIMER APP Initialized during DAVE Initialization
    // Create Software timer
    TimerId = (uint32_t)SYSTIMER_CreateTimer(ONESEC,SYSTIMER_MODE_PERIODIC,(void*)LED_Toggle_EverySec,NULL);
    if (TimerId != 0U)
    {
      //timer is created successfully, now start/run software timer
      status = SYSTIMER_StartTimer(TimerId);
      if (status == SYSTIMER_STATUS_SUCCESS)
      {
        // Software timer is running
        // Add user code here
      }
      else
      {
        // Error during software timer start operation
      }
    }
    else
    {
      // timer ID Can not be zero
    }
    // ... infinite loop ...
    while (1)
    {

    }
    return (1);
  }


Definition at line 444 of file SYSTIMER.c.

References g_timer_tbl, SYSTIMER_STATE_RUNNING, SYSTIMER_STATE_STOPPED, SYSTIMER_STATUS_FAILURE, and SYSTIMER_STATUS_SUCCESS.

Referenced by SYSTIMER_RestartTimer().

Stops the software timer.

Parameters:
idtimer ID obtained from SYSTIMER_CreateTimer. Range : 1 to 16
Returns:
SYSTIMER_STATUS_t APP status. Refer SYSTIMER_STATUS_t for details.
Description:
API to stop created software timer instance.
Note : This API must be called after software timer is created using SYSTIMER_CreateTimer API with generated ID and enable XMC_ASSERT for better understanding of API behavioral in run time.
Example Usage:
  #include <DAVE.h>
  #define ONESEC 1000000U
  void LED_Toggle_EverySec(void)
  {
    // Add user code here
  }

  int main(void)
  {
    uint32_t TimerId;
    SYSTIMER_STATUS_t status;
    // ... Initializes APPs configuration ...
    DAVE_Init(); // SYSTIMER APP Initialized during DAVE Initialization
    // Create Software timer
    TimerId = (uint32_t)SYSTIMER_CreateTimer(ONESEC,SYSTIMER_MODE_PERIODIC,(void*)LED_Toggle_EverySec,NULL);
    if (TimerId != 0U)
    {
      //timer is created successfully, now start/run software timer
      status = SYSTIMER_StartTimer(TimerId);
      if (status == SYSTIMER_STATUS_SUCCESS)
      {
        // Software timer is running
        // Add user code here



        //stop the timer
        status = SYSTIMER_StopTimer(TimerId);
        if (status == SYSTIMER_STATUS_SUCCESS)
        {
          //Software timer has stopped
        }
        else
        {
           // Error during software timer stop operation
        }
      }
      else
      {
        // Error during software timer start operation
      }
    }
    else
    {
      // timer ID Can not be zero
    }
    // ... infinite loop ...
    while (1)
    {

    }
    return (1);
  }


Definition at line 470 of file SYSTIMER.c.

References g_timer_tbl, SYSTIMER_STATE_NOT_INITIALIZED, SYSTIMER_STATE_RUNNING, SYSTIMER_STATE_STOPPED, SYSTIMER_STATUS_FAILURE, and SYSTIMER_STATUS_SUCCESS.

Referenced by SYSTIMER_RestartTimer().