CMSIS-RTOS2: Timer Management

| CMSIS-RTOS2 Version 2.1.3 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
Data Structures | Typedefs | Enumerations | Enumerator | Functions
Timer Management
CMSIS-RTOS API v2

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

## Data Structures
struct | osTimerAttr_t
| Attributes structure for timer. More...

## Typedefs
typedef void * | osTimerId_t
typedef void(* | osTimerFunc_t )(void *argument)
| Timer callback function. More...

## Enumerations
enum | osTimerType_t { osTimerOnce = 0, osTimerPeriodic = 1 }
| Timer type. More...

## Functions
osTimerId_t | osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr)
| Create and Initialize a timer. More...
const char * | osTimerGetName (osTimerId_t timer_id)
| Get name of a timer. More...
osStatus_t | osTimerStart (osTimerId_t timer_id, uint32_t ticks)
| Start or restart a timer. More...
osStatus_t | osTimerStop (osTimerId_t timer_id)
| Stop a timer. More...
uint32_t | osTimerIsRunning (osTimerId_t timer_id)
| Check if a timer is running. More...
osStatus_t | osTimerDelete (osTimerId_t timer_id)
| Delete a timer. 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. 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.

Note
  RTX handles Timers in the thread osRtxTimerThread. Callback functions run under control of this thread and may use other CMSIS-RTOS API calls. The osRtxTimerThread is configured in Timer Configuration.
  Timer management functions cannot be called from Interrupt Service Routines.

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 software timer:

1. Define the timers:
   osTimerId_t one_shot_id, periodic_id;
2. Define callback functions:
   static void one_shot_Callback (void *argument) {
   int32_t arg = (int32_t)argument; // cast back argument '0'
   // do something, i.e. set thread/event flags
   }
   static void periodic_Callback (void *argument) {
   int32_t arg = (int32_t)argument; // cast back argument '5'
   // do something, i.e. set thread/event flags
   }
3. Instantiate and start the timers:
   // creates a one-shot timer:
   one_shot_id = osTimerNew(one_shot_Callback, osTimerOnce, (void *)0, NULL); // (void*)0 is passed as an argument
   // to the callback function
   // creates a periodic timer:
   periodic_id = osTimerNew(periodic_Callback, osTimerPeriodic, (void *)5, NULL); // (void*)5 is passed as an argument
   // to the callback function
   osTimerStart(one_shot_id, 500U);
   osTimerStart(periodic_id, 1500U);
   // start the one-shot timer again after it has triggered the first time:
   osTimerStart(one_shot_id, 500U);
   // when timers are not needed any longer free the resources:
   osTimerDelete(one_shot_id);
   osTimerDelete(periodic_id);

## Data Structure Documentation

struct osTimerAttr_t

Specifies the following attributes for the osTimerNew function.

Data Fields
const char * | name | name of the timer Pointer to a constant string with a human readable name (displayed during debugging) of the timer object. Default: NULL no name specified.
uint32_t | attr_bits | attribute bits Reserved for future use (must be set to '0' for future compatibility).
void * | cb_mem | memory for control block Pointer to a memory for the timer control block object. Refer to Static Object Memory for more information. Default: NULL to use Automatic Dynamic Allocation for the timer control block.
uint32_t | cb_size | size of provided memory for control block The size (in bytes) of memory block passed with cb_mem. For RTX, the minimum value is defined with osRtxTimerCbSize (higher values are permitted). Default: 0 as the default is no memory provided with cb_mem.

## Typedef Documentation

osTimerId_t

Timer ID identifies the timer.

Instances of this type hold a reference to a timer object.
Returned by:

- osTimerNew

void(* osTimerFunc_t)(void *argument)

The timer callback function is called every time the timer elapses.

The callback might be executed either in a dedicated timer thread or in interrupt context. Thus it is recommended to only use ISR callable functions from the timer callback.

Parameters

  [in] | argument | The argument provided to osTimerNew.

## Enumeration Type Documentation

enum osTimerType_t

The osTimerType_t specifies the a repeating (periodic) or one-shot timer for the function osTimerNew.

Enumerator
osTimerOnce | One-shot timer. The timer is not automatically restarted once it has elapsed. It can be restarted manually using osTimerStart as needed.
osTimerPeriodic | Repeating timer. The timer repeats automatically and triggers the callback continuously while running, see osTimerStart and osTimerStop.

## Function Documentation

osTimerId_t osTimerNew | ( | osTimerFunc_t | func,
|  | osTimerType_t | type,
|  | void * | argument,
|  | const osTimerAttr_t * | attr
| ) |  |

Parameters

  [in] | func | function pointer to callback function.
  [in] | type | osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
  [in] | argument | argument to the timer callback function.
  [in] | attr | timer attributes; NULL: default values.

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

The function osTimerNew creates an one-shot or periodic timer and associates it with a callback function with argument. The timer is in stopped state until it is started with osTimerStart. The function can be safely called before the RTOS is started (call to osKernelStart), but not before it is initialized (call to osKernelInitialize).

The function osTimerNew returns the pointer to the timer object identifier or NULL in case of an error.

Note
  This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
void Timer1_Callback (void *arg); // prototypes for timer callback function
void Timer2_Callback (void *arg); // prototypes for timer callback function
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_t id1; // timer id
osTimerId_t id2; // timer id
// Create one-shoot timer
exec1 = 1U;
id1 = osTimerNew(Timer1_Callback, osTimerOnce, &exec1, NULL);
if (id1 != NULL) {
// One-shoot timer created
}
// Create periodic timer
exec2 = 2U;
id2 = osTimerNew(Timer2_Callback, osTimerPeriodic, &exec2, NULL);
if (id2 != NULL) {
// Periodic timer created
}
:
}

*const char * osTimerGetName | ( | osTimerId_t | timer_id | ) |

Parameters

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

Returns
  name as null-terminated string.

The function osTimerGetName returns the pointer to the name string of the timer identified by parameter timer_id or NULL in case of an error.

Note
  This function cannot be called from Interrupt Service Routines.

osStatus_t osTimerStart | ( | osTimerId_t | timer_id,
|  | uint32_t | ticks
| ) |  |

Parameters

  [in] | timer_id | timer ID obtained by osTimerNew.
  [in] | ticks | time ticks value of the timer.

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

The function osTimerStart starts or restarts a timer specified by the parameter timer_id. The parameter ticks specifies the value of the timer in time ticks.

Possible osStatus_t return values:

- osOK: the specified timer has been started or restarted.
- osErrorISR: osTimerStart cannot be called from interrupt service routines.
- osErrorParameter: parameter timer_id is either NULL or invalid or ticks is incorrect.
- osErrorResource: the timer is in an invalid state.

Note
  This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
void Timer_Callback (void *arg) { // timer callback function
// arg contains &exec
// called every second after osTimerStart
}
uint32_t exec; // argument for the timer call back function
void TimerStart_example (void) {
osTimerId_t id; // timer id
uint32_t timerDelay; // timer value
osStatus_t status; // function return status
// Create periodic timer
exec = 1U;
id = osTimerNew(Timer_Callback, osTimerPeriodic, &exec, NULL);
if (id != NULL) {
timerDelay = 1000U;
status = osTimerStart(id, timerDelay); // start timer
if (status != osOK) {
// Timer could not be started
}
}
;
}

osStatus_t osTimerStop | ( | osTimerId_t | timer_id | ) |

Parameters

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

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

The function osTimerStop stops a timer specified by the parameter timer_id.

Possible osStatus_t return values:

- osOK: the specified timer has been stopped.
- osErrorISR: osTimerStop cannot be called from interrupt service routines.
- osErrorParameter: parameter timer_id is either NULL or invalid.
- osErrorResource: the timer is not running (you can only stop a running timer).

Note
  This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
void Timer_Callback (void *arg); // prototype for timer callback function
uint32_t exec; // argument for the timer call back function
void TimerStop_example (void) {
osTimerId_t id; // timer id
osStatus_t status; // function return status
// Create periodic timer
exec = 1U;
id = osTimerNew(Timer_Callback, osTimerPeriodic, &exec, NULL);
osTimerStart(id, 1000U); // start timer
:
status = osTimerStop(id); // stop timer
if (status != osOK) {
// Timer could not be stopped
}
;
osTimerStart(id, 1000U); // start timer again
;
}

uint32_t osTimerIsRunning | ( | osTimerId_t | timer_id | ) |

Parameters

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

Returns
  0 not running, 1 running.

The function osTimerIsRunning checks whether a timer specified by parameter timer_id is running. It returns 1 if the timer is running and 0 if the timer is stopped or an error occurred.

Note
  This function cannot be called from Interrupt Service Routines.

osStatus_t osTimerDelete | ( | osTimerId_t | timer_id | ) |

Parameters

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

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

The function osTimerDelete deletes the timer specified by parameter timer_id.

Possible osStatus_t return values:

- osOK: the specified timer has been deleted.
- osErrorISR: osTimerDelete cannot be called from interrupt service routines.
- osErrorParameter: parameter timer_id is either NULL or invalid.
- osErrorResource: the timer is in an invalid state.

Note
  This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
void Timer_Callback (void *arg); // prototype for timer callback function
uint32_t exec; // argument for the timer call back function
void TimerDelete_example (void) {
osTimerId_t id; // timer id
osStatus_t status; // function return status
// Create periodic timer
exec = 1U;
id = osTimerNew(Timer_Callback, osTimerPeriodic, &exec, NULL);
osTimerStart(id, 1000U); // start timer
;
status = osTimerDelete(id); // stop and delete timer
if (status != osOK) {
// Timer could not be deleted
}
;
}