CMSIS-RTOS: cmsis_os.h File Reference

| CMSIS-RTOS Version 1.02 CMSIS-RTOS API: Generic RTOS interface for Cortex-M processor-based devices.

- Main Page
- Usage and Description
- Reference

Data Structures | Macros | Typedefs | Enumerations | Functions
cmsis_os.h File Reference

## Data Structures

struct | osThreadDef_t
| Thread Definition structure contains startup information of a thread. More...
struct | osTimerDef_t
| Timer Definition structure contains timer parameters. More...
struct | osMutexDef_t
| Mutex Definition structure contains setup information for a mutex. More...
struct | osSemaphoreDef_t
| Semaphore Definition structure contains setup information for a semaphore. More...
struct | osPoolDef_t
| Definition structure for memory block allocation. More...
struct | osMessageQDef_t
| Definition structure for message queue. More...
struct | osMailQDef_t
| Definition structure for mail queue. More...
struct | osEvent
| Event structure contains detailed information about an event. More...

## Macros

#define | osCMSIS 0x10002
| API version (main [31:16] .sub [15:0])
#define | osCMSIS_KERNEL 0x10000
| RTOS identification and version (main [31:16] .sub [15:0])
#define | osKernelSystemId "KERNEL V1.00"
| RTOS identification string.
#define | osFeature_MainThread 1
| main thread 1=main can be thread, 0=not available
#define | osFeature_Pool 1
| Memory Pools: 1=available, 0=not available.
#define | osFeature_MailQ 1
| Mail Queues: 1=available, 0=not available.
#define | osFeature_MessageQ 1
| Message Queues: 1=available, 0=not available.
#define | osFeature_Signals 8
| maximum number of Signal Flags available per thread
#define | osFeature_Semaphore 30
| maximum count for osSemaphoreCreate function
#define | osFeature_Wait 1
| osWait function: 1=available, 0=not available
#define | osFeature_SysTick 1
| osKernelSysTick functions: 1=available, 0=not available
#define | osWaitForever 0xFFFFFFFF
| Timeout value.
#define | osKernelSysTickFrequency 100000000
| The RTOS kernel system timer frequency in Hz.
#define | osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
| Convert a microseconds value to a RTOS kernel system timer value.
#define | osThreadDef(name, priority, instances, stacksz)
| Create a Thread Definition with function, priority, and stack requirements.
#define | osThread(name) &os_thread_def_##name
| Access a Thread definition.
#define | osTimerDef(name, function)
| Define a Timer object.
#define | osTimer(name) &os_timer_def_##name
| Access a Timer definition.
#define | osMutexDef(name) const osMutexDef_t os_mutex_def_##name = { 0 }
| Define a Mutex.
#define | osMutex(name) &os_mutex_def_##name
| Access a Mutex definition.
#define | osSemaphoreDef(name) const osSemaphoreDef_t os_semaphore_def_##name = { 0 }
| Define a Semaphore object.
#define | osSemaphore(name) &os_semaphore_def_##name
| Access a Semaphore definition.
#define | osPoolDef(name, no, type)
| Define a Memory Pool.
#define | osPool(name) &os_pool_def_##name
| Access a Memory Pool definition.
#define | osMessageQDef(name, queue_sz, type)
| Create a Message Queue Definition.
#define | osMessageQ(name) &os_messageQ_def_##name
| Access a Message Queue Definition.
#define | osMailQDef(name, queue_sz, type)
| Create a Mail Queue Definition.
#define | osMailQ(name) &os_mailQ_def_##name
| Access a Mail Queue Definition.

## Typedefs

typedef void(* | os_pthread )(void const *argument)
| Entry point of a thread.
typedef void(* | os_ptimer )(void const *argument)
| Entry point of a timer call back function.
typedef struct os_thread_cb * | osThreadId
| Thread ID identifies the thread (pointer to a thread control block).
typedef struct os_timer_cb * | osTimerId
| Timer ID identifies the timer (pointer to a timer control block).
typedef struct os_mutex_cb * | osMutexId
| Mutex ID identifies the mutex (pointer to a mutex control block).
typedef struct os_semaphore_cb * | osSemaphoreId
| Semaphore ID identifies the semaphore (pointer to a semaphore control block).
typedef struct os_pool_cb * | osPoolId
| Pool ID identifies the memory pool (pointer to a memory pool control block).
typedef struct os_messageQ_cb * | osMessageQId
| Message ID identifies the message queue (pointer to a message queue control block).
typedef struct os_mailQ_cb * | osMailQId
| Mail ID identifies the mail queue (pointer to a mail queue control block).

## Enumerations

enum | osPriority { osPriorityIdle = -3, osPriorityLow = -2, osPriorityBelowNormal = -1, osPriorityNormal = 0,
osPriorityAboveNormal = +1,
osPriorityHigh = +2,
osPriorityRealtime = +3,
osPriorityError = 0x84
}
| Priority used for thread control. More...
enum | osStatus { osOK = 0, osEventSignal = 0x08, osEventMessage = 0x10, osEventMail = 0x20,
osEventTimeout = 0x40,
osErrorParameter = 0x80,
osErrorResource = 0x81,
osErrorTimeoutResource = 0xC1,
osErrorISR = 0x82,
osErrorISRRecursive = 0x83,
osErrorPriority = 0x84,
osErrorNoMemory = 0x85,
osErrorValue = 0x86,
osErrorOS = 0xFF,
os_status_reserved = 0x7FFFFFFF
}
| Status code values returned by CMSIS-RTOS functions. More...
enum | os_timer_type { osTimerOnce = 0, osTimerPeriodic = 1 }
| Timer type value for the timer definition. More...

## Functions

osStatus | osKernelInitialize (void)
| Initialize the RTOS Kernel for creating objects.
osStatus | osKernelStart (void)
| Start the RTOS Kernel.
int32_t | osKernelRunning (void)
| Check if the RTOS kernel is already started.
uint32_t | osKernelSysTick (void)
| Get the RTOS kernel system timer counter.
osThreadId | osThreadCreate (const osThreadDef_t *thread_def, void *argument)
| Create a thread and add it to Active Threads and set it to state READY.
osThreadId | osThreadGetId (void)
| Return the thread ID of the current running thread.
osStatus | osThreadTerminate (osThreadId thread_id)
| Terminate execution of a thread and remove it from Active Threads.
osStatus | osThreadYield (void)
| Pass control to next thread that is in state READY.
osStatus | osThreadSetPriority (osThreadId thread_id, osPriority priority)
| Change priority of an active thread.
osPriority | osThreadGetPriority (osThreadId thread_id)
| Get current priority of an active thread.
osStatus | osDelay (uint32_t millisec)
| Wait for Timeout (Time Delay).
osEvent | osWait (uint32_t millisec)
| Wait for Signal, Message, Mail, or Timeout.
osTimerId | osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument)
| Create a timer.
osStatus | osTimerStart (osTimerId timer_id, uint32_t millisec)
| Start or restart a timer.
osStatus | osTimerStop (osTimerId timer_id)
| Stop the timer.
osStatus | osTimerDelete (osTimerId timer_id)
| Delete a timer that was created by osTimerCreate.
int32_t | osSignalSet (osThreadId thread_id, int32_t signals)
| Set the specified Signal Flags of an active thread.
int32_t | osSignalClear (osThreadId thread_id, int32_t signals)
| Clear the specified Signal Flags of an active thread.
osEvent | osSignalWait (int32_t signals, uint32_t millisec)
| Wait for one or more Signal Flags to become signaled for the current RUNNING thread.
osMutexId | osMutexCreate (const osMutexDef_t *mutex_def)
| Create and Initialize a Mutex object.
osStatus | osMutexWait (osMutexId mutex_id, uint32_t millisec)
| Wait until a Mutex becomes available.
osStatus | osMutexRelease (osMutexId mutex_id)
| Release a Mutex that was obtained by osMutexWait.
osStatus | osMutexDelete (osMutexId mutex_id)
| Delete a Mutex that was created by osMutexCreate.
osSemaphoreId | osSemaphoreCreate (const osSemaphoreDef_t *semaphore_def, int32_t count)
| Create and Initialize a Semaphore object used for managing resources.
int32_t | osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec)
| Wait until a Semaphore token becomes available.
osStatus | osSemaphoreRelease (osSemaphoreId semaphore_id)
| Release a Semaphore token.
osStatus | osSemaphoreDelete (osSemaphoreId semaphore_id)
| Delete a Semaphore that was created by osSemaphoreCreate.
osPoolId | osPoolCreate (const osPoolDef_t *pool_def)
| Create and Initialize a memory pool.
void * | osPoolAlloc (osPoolId pool_id)
| Allocate a memory block from a memory pool.
void * | osPoolCAlloc (osPoolId pool_id)
| Allocate a memory block from a memory pool and set memory block to zero.
osStatus | osPoolFree (osPoolId pool_id, void *block)
| Return an allocated memory block back to a specific memory pool.
osMessageQId | osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id)
| Create and Initialize a Message Queue.
osStatus | osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec)
| Put a Message to a Queue.
osEvent | osMessageGet (osMessageQId queue_id, uint32_t millisec)
| Get a Message or Wait for a Message from a Queue.
osMailQId | osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id)
| Create and Initialize mail queue.
void * | osMailAlloc (osMailQId queue_id, uint32_t millisec)
| Allocate a memory block from a mail.
void * | osMailCAlloc (osMailQId queue_id, uint32_t millisec)
| Allocate a memory block from a mail and set memory block to zero.
osStatus | osMailPut (osMailQId queue_id, void *mail)
| Put a mail to a queue.
osEvent | osMailGet (osMailQId queue_id, uint32_t millisec)
| Get a mail from a queue.
osStatus | osMailFree (osMailQId queue_id, void *mail)
| Free a memory block from a mail.

## Macro Definition Documentation

#define osWaitForever 0xFFFFFFFF

Note
  MUST REMAIN UNCHANGED: osWaitForever shall be consistent in every CMSIS-RTOS. wait forever timeout value

## Typedef Documentation

typedef void(* os_pthread)(void const *argument)

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

typedef void(* os_ptimer)(void const *argument)

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

typedef struct os_mailQ_cb* osMailQId

Note
  CAN BE CHANGED: os_mailQ_cb is implementation specific in every CMSIS-RTOS.

typedef struct os_messageQ_cb* osMessageQId

Note
  CAN BE CHANGED: os_messageQ_cb is implementation specific in every CMSIS-RTOS.

typedef struct os_mutex_cb* osMutexId

Note
  CAN BE CHANGED: os_mutex_cb is implementation specific in every CMSIS-RTOS.

typedef struct os_pool_cb* osPoolId

Note
  CAN BE CHANGED: os_pool_cb is implementation specific in every CMSIS-RTOS.

typedef struct os_semaphore_cb* osSemaphoreId

Note
  CAN BE CHANGED: os_semaphore_cb is implementation specific in every CMSIS-RTOS.

typedef struct os_thread_cb* osThreadId

Note
  CAN BE CHANGED: os_thread_cb is implementation specific in every CMSIS-RTOS.

typedef struct os_timer_cb* osTimerId

Note
  CAN BE CHANGED: os_timer_cb 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.

Enumerator:

  osTimerOnce | one-shot timer
  osTimerPeriodic | repeating timer

enum osPriority

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

Enumerator:

  osPriorityIdle | priority: idle (lowest)
  osPriorityLow | priority: low
  osPriorityBelowNormal | priority: below normal
  osPriorityNormal | priority: normal (default)
  osPriorityAboveNormal | priority: above normal
  osPriorityHigh | priority: high
  osPriorityRealtime | priority: realtime (highest)
  osPriorityError | system cannot determine priority or thread has illegal priority

enum osStatus

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

Enumerator:

  osOK | function completed; no error or event occurred.
  osEventSignal | function completed; signal event occurred.
  osEventMessage | function completed; message event occurred.
  osEventMail | function completed; mail event occurred.
  osEventTimeout | function completed; timeout occurred.
  osErrorParameter | parameter error: a mandatory parameter was missing or specified an incorrect object.
  osErrorResource | resource not available: a specified resource was not available.
  osErrorTimeoutResource | resource not available within given time: a specified resource was not available within the timeout period.
  osErrorISR | not allowed in ISR context: the function cannot be called from interrupt service routines.
  osErrorISRRecursive | function called multiple times from ISR with same object.
  osErrorPriority | system cannot determine priority or thread has illegal priority.
  osErrorNoMemory | system is out of memory: it was impossible to allocate or reserve memory for the operation.
  osErrorValue | value of a parameter is out of range.
  osErrorOS | unspecified RTOS error: run-time error but no other error message fits.
  os_status_reserved | prevent from enum down-size compiler optimization.