CMSIS-RTOS: cmsis_os.h File Reference

| 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
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...
union | osEvent.value
union | osEvent.def

## Macros

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

## Typedefs

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

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

## Data Structure Documentation

struct osThreadDef_t

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

Data Fields
uint32_t | instances | maximum number of instances of that thread function
os_pthread | pthread | start address of thread function
uint32_t | stacksize | stack size requirements in bytes; 0 is default stack size
osPriority | tpriority | initial thread priority

struct osTimerDef_t

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

Data Fields
os_ptimer | ptimer | start address of a timer function

struct osMutexDef_t

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

Data Fields
uint32_t | dummy | dummy value.

struct osSemaphoreDef_t

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

Data Fields
uint32_t | dummy | dummy value.

struct osPoolDef_t

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

Data Fields
uint32_t | item_sz | size of an item
void * | pool | pointer to memory for pool
uint32_t | pool_sz | number of items (elements) in the pool

struct osMessageQDef_t

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

Data Fields
uint32_t | item_sz | size of an item
void * | pool | memory array for messages
uint32_t | queue_sz | number of elements in the queue

struct osMailQDef_t

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

Data Fields
uint32_t | item_sz | size of an item
void * | pool | memory array for mail
uint32_t | queue_sz | number of elements in the queue

## 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 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.