CMSIS-RTOS: Timer Management

| CMSIS-RTOS Version 1.03 Real-Time Operating System: API and RTX Reference Implementation.

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Enumerations | Functions
Timer Management
CMSIS-RTOS API

Create and control timer and timer callback functions. More...

## Macros
#define | osTimerDef(name, function)
| Define a Timer object. More...
#define | osTimer(name) &os_timer_def_##name
| Access a Timer definition. More...

## Enumerations
enum | os_timer_type { osTimerOnce = 0, osTimerPeriodic = 1 }

## Functions
osTimerId | osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument)
| Create a timer. More...
osStatus | osTimerStart (osTimerId timer_id, uint32_t millisec)
| Start or restart a timer. More...
osStatus | osTimerStop (osTimerId timer_id)
| Stop the timer. More...
osStatus | osTimerDelete (osTimerId timer_id)
| Delete a timer that was created by osTimerCreate. More...

## Description

In addition to the Generic Wait Functions CMSIS-RTOS also supports virtual timer objects. These timer objects can trigger the execution of a function (not threads). When a timer expires, a callback function is executed to run associated code with the timer. The timer number is passed as a parameter to the callback function. Each timer can be configured as a one-shot or a periodic timer. A periodic timer repeats its operation until it is deleted or stopped. All timers can be started, restarted, or stopped.

Timers are handled in the thread osTimerThread. Callback functions run under control of this thread and may use other CMSIS-RTOS API calls.

The figure below shows the behavior of a periodic timer. For one-shot timers, the timer stops after execution of the callback function.

Behavior of a Periodic Timer

## Working with Timers

The following steps are required to use a timer:

1. Define the timers:
   osTimerDef(one_shot, start_machine); // when the timer expires, the function start_machine is called
   osTimerDef(periodic, toggle_power); // when the timer expires, the function toggle_power is called
   osTimerId one_shot_id, periodic_id;
2. Instantiate and start the timers in an RTOS thread:
   one_shot_id = osTimerCreate(osTimer(one_shot), osTimerOnce, (void *)0); // creates a one-shot timer;
   // (void*)0 is passed as an argument to the callback function
   periodic_id = osTimerCreate(osTimer(periodic), osTimerPeriodic, (void *)5); // creates a periodic timer;
   // (void*)5 is passed as an argument to the callback function
   osTimerStart(one_shot_id, 500);
   osTimerStart(periodic, 1500);

## Macro Definition Documentation

#define osTimer | ( |  | name | ) | &os_timer_def_##name

Access to the timer definition for the function osTimerCreate.

Parameters

  name | name of the timer object.

Note
  CAN BE CHANGED: The parameter to osTimer shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

#define osTimerDef | ( |  | name,
|  |  | function
| ) |  |

Define the attributes of a timer.

Parameters

  name | name of the timer object.
  function | name of the timer call back function.

Note
  CAN BE CHANGED: The parameter to osTimerDef shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

## Enumeration Type Documentation

enum os_timer_type

Note
  MUST REMAIN UNCHANGED: os_timer_type shall be consistent in every CMSIS-RTOS. The os_timer_type specifies the a repeating (periodic) or one-shot timer for the function osTimerCreate.

Enumerator
osTimerOnce | one-shot timer
osTimerPeriodic | repeating timer

## Function Documentation

osTimerId osTimerCreate | ( | const osTimerDef_t * | timer_def,
|  | os_timer_type | type,
|  | void * | argument
| ) |  |

Parameters

  [in] | timer_def | timer object referenced with osTimer.
  [in] | type | osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
  [in] | argument | argument to the timer call back function.

Returns
  timer ID for reference by other functions or NULL in case of error.

Note
  MUST REMAIN UNCHANGED: osTimerCreate shall be consistent in every CMSIS-RTOS.

Create a one-shot or periodic timer and associate it with a callback function argument. The timer is in stopped until it is started with osTimerStart.

Note
  Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
void Timer1_Callback (void const *arg); // prototypes for timer callback function
void Timer2_Callback (void const *arg);
osTimerDef (Timer1, Timer1_Callback); // define timers
osTimerDef (Timer2, Timer2_Callback);
uint32_t exec1; // argument for the timer call back function
uint32_t exec2; // argument for the timer call back function
void TimerCreate_example (void) {
osTimerId id1; // timer id
osTimerId id2; // timer id
// Create one-shoot timer
exec1 = 1;
id1 = osTimerCreate (osTimer(Timer1), osTimerOnce, &exec1);
if (id1 != NULL) {
// One-shoot timer created
}
// Create periodic timer
exec2 = 2;
id2 = osTimerCreate (osTimer(Timer2), osTimerPeriodic, &exec2);
if (id2 != NULL) {
// Periodic timer created
}
:
}

osStatus osTimerDelete | ( | osTimerId | timer_id | ) |

Parameters

  [in] | timer_id | timer ID obtained by osTimerCreate.

Returns
  status code that indicates the execution status of the function.

Note
  MUST REMAIN UNCHANGED: osTimerDelete shall be consistent in every CMSIS-RTOS.

Delete the timer object.

Status and Error Codes

- osOK: the specified timer has been deleted.
- osErrorISR: osTimerDelete cannot be called from interrupt service routines.
- osErrorParameter: timer_id is incorrect.

Note
  Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
void Timer_Callback (void const *arg); // prototype for timer callback function
osTimerDef (Timer, Timer_Callback); // define timer
void TimerDelete_example (void) {
osTimerId id; // timer id
osStatus status; // function return status
// Create periodic timer
exec = 1;
id = osTimerCreate (osTimer(Timer2), osTimerPeriodic, NULL);
osTimerStart (id, 1000UL); // start timer
:
status = osTimerDelete (id); // stop and delete timer
if (status != osOK) {
// Timer could not be deleted
}
:
}

osStatus osTimerStart | ( | osTimerId | timer_id,
|  | uint32_t | millisec
| ) |  |

Parameters

  [in] | timer_id | timer ID obtained by osTimerCreate.
  [in] | millisec | time delay value of the timer.

Returns
  status code that indicates the execution status of the function.

Note
  MUST REMAIN UNCHANGED: osTimerStart shall be consistent in every CMSIS-RTOS.

Start or restart the timer.

Status and Error Codes

- osOK: the specified timer has been started or restarted.
- osErrorISR: osTimerStart cannot be called from interrupt service routines.
- osErrorParameter: timer_id is incorrect.

Note
  Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
void Time_Callback (void const *arg) { // timer callback function
// arg contains &exec
// called every second after osTimerStart
}
osTimerDef (Timer, Time_Callback); // define timer
uint32_t exec; // argument for the timer call back function
void TimerStart_example (void) {
osTimerId id; // timer id
uint32_t timerDelay; // timer value
osStatus status; // function return status
// Create periodic timer
exec = 1;
id = osTimerCreate (osTimer(Timer), osTimerPeriodic, &exec);
if (id) {
timerDelay = 1000;
status = osTimerStart (id, timerDelay); // start timer
if (status != osOK) {
// Timer could not be started
}
}
:
}

osStatus osTimerStop | ( | osTimerId | timer_id | ) |

Parameters

  [in] | timer_id | timer ID obtained by osTimerCreate.

Returns
  status code that indicates the execution status of the function.

Note
  MUST REMAIN UNCHANGED: osTimerStop shall be consistent in every CMSIS-RTOS.

Stop the timer.

Status and Error Codes

- osOK: the specified timer has been stopped.
- osErrorISR: osTimerStop cannot be called from interrupt service routines.
- osErrorParameter: timer_id is incorrect.
- osErrorResource: the timer is not started.

Note
  Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
void Timer_Callback (void const *arg); // prototype for timer callback function
osTimerDef (Timer, Timer_Callback); // define timer
void TimerStop_example (void) {
osTimerId id; // timer id
osStatus status; // function return status
// Create periodic timer
exec = 1;
id = osTimerCreate (osTimer(Timer2), osTimerPeriodic, NULL);
osTimerStart (id, 1000); // start timer
:
status = osTimerStop (id); // stop timer
if (status != osOK) {
// Timer could not be stopped
}
:
osTimerStart (id, 1000); // start timer again
:
}