CMSIS-RTOS2: Generic Wait Functions

| 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
Functions
Generic Wait Functions
CMSIS-RTOS API v2

Wait for a certain period of time. More...

## Functions
osStatus_t | osDelay (uint32_t ticks)
| Wait for Timeout (Time Delay). More...
osStatus_t | osDelayUntil (uint32_t ticks)
| Wait until specified time. More...

## Description

The generic wait functions provide means for a time delay.

Note
  Generic wait functions cannot be called from Interrupt Service Routines.

## Function Documentation

osStatus_t osDelay | ( | uint32_t | ticks | ) |

Parameters

  [in] | ticks | time ticks value

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

The function osDelay waits for a time period specified in kernel ticks. For a value of 1 the system waits until the next timer tick occurs. The actual time delay may be up to one timer tick less than specified, i.e. calling `osDelay(1)` right before the next system tick occurs the thread is rescheduled immediately.

The delayed thread is put into the BLOCKED state and a context switch occurs immediately. The thread is automatically put back to the READY state after the given amount of ticks has elapsed. If the thread will have the highest priority in READY state it will being scheduled immediately.

Possible osStatus_t return values:

- osOK: the time delay is executed.
- osErrorISR: osDelay cannot be called from Interrupt Service Routines.

Note
  This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
void Thread_1 (void *arg) { // Thread function
osStatus_t status; // capture the return status
uint32_t delayTime; // delay time in milliseconds
delayTime = 1000; // delay 1 second
status = osDelay (delayTime); // suspend thread execution
}

osStatus_t osDelayUntil | ( | uint32_t | ticks | ) |

Parameters

  [in] | ticks | absolute time in ticks

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

The function osDelayUntil waits until an absolute time (specified in kernel ticks) is reached.

The corner case when the kernel tick counter overflows is handled by osDelayUntil. Thus it is absolutely legal to provide a value which is lower than the current tick value, i.e. returned by osKernelGetTickCount. Typically as a user you do not have to take care about the overflow. The only limitation you have to have in mind is that the maximum delay is limited to (231)-1 ticks.

The delayed thread is put into the BLOCKED state and a context switch occurs immediately. The thread is automatically put back to the READY state when the given time is reached. If the thread will have the highest priority in READY state it will being scheduled immediately.

Possible osStatus_t return values:

- osOK: the time delay is executed.
- osParameter: the time cannot be handled (out of bounds).
- osErrorISR: osDelayUntil cannot be called from Interrupt Service Routines.

Note
  This function cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os2.h"
void Thread_1 (void *arg) { // Thread function
uint32_t tick;
tick = osKernelGetTickCount(); // retrieve the number of system ticks
for (;;) {
tick += 1000; // delay 1000 ticks periodically
osDelayUntil(tick);
// ...
}
}