cmsis_os.h

Go to the documentation of this file.

// clang-format off
/* ----------------------------------------------------------------------
 * $Date:        5. February 2013
 * $Revision:    V1.02
 *
 * Project:      CMSIS-RTOS API
 * Title:        cmsis_os.h template header file
 *
 * Version 0.02
 *    Initial Proposal Phase
 * Version 0.03
 *    osKernelStart added, optional feature: main started as thread
 *    osSemaphores have standard behaviour
 *    osTimerCreate does not start the timer, added osTimerStart
 *    osThreadPass is renamed to osThreadYield
 * Version 1.01
 *    Support for C++ interface
 *     - const attribute removed from the osXxxxDef_t typedef's
 *     - const attribute added to the osXxxxDef macros
 *    Added: osTimerDelete, osMutexDelete, osSemaphoreDelete
 *    Added: osKernelInitialize
 * Version 1.02
 *    Control functions for short timeouts in microsecond resolution:
 *    Added: osKernelSysTick, osKernelSysTickFrequency, osKernelSysTickMicroSec
 *    Removed: osSignalGet
 *----------------------------------------------------------------------------
 *
 * Copyright (c) 2013 ARM LIMITED
 * All rights reserved.
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *  - Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  - Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *  - Neither the name of ARM  nor the names of its contributors may be used
 *    to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *---------------------------------------------------------------------------*/
 
/*
 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
 * Copyright (c) 2016-2025 Liviu Ionescu. All rights reserved.
 *
 * Permission to use, copy, modify, and/or distribute this software
 * for any purpose is hereby granted, under the terms of the MIT license.
 *
 * If a copy of the license was not distributed with this file, it can
 * be obtained from https://opensource.org/licenses/mit.
 */
 
/*
 * The code exposes a fully compliant ARM CMSIS API in the
 * context of the µOS++.
 */
 
/*
 * Calls from Interrupt Service Routines
 *
 * The following CMSIS-RTOS functions can be called both from threads and
 * Interrupt Service Routines (ISR):
 *
 * - osKernelRunning
 * - osSignalSet
 * - osSemaphoreRelease
 * - osPoolAlloc, osPoolCAlloc, osPoolFree
 * - osMessagePut, osMessageGet
 * - osMailAlloc, osMailCAlloc, osMailGet, osMailPut, osMailFree
 */
 
#ifndef CMSIS_OS_H_
#define CMSIS_OS_H_
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wpadded"
#elif defined(__GNUC__)
#if !defined(__cplusplus)
#pragma GCC diagnostic ignored "-Wc++-compat"
#endif
#pragma GCC diagnostic ignored "-Wpadded"
#endif
 
#define osCMSIS           0x00010002 
#define osCMSIS_KERNEL    0x00010000 
#define osKernelSystemId "µOS++" 
#define osFeature_MainThread   0 
#define osFeature_Pool         1 
#define osFeature_MailQ        1 
#define osFeature_MessageQ     1 
#define osFeature_Signals      8 
#define osFeature_Semaphore    30 
#define osFeature_Wait         1 
#define osFeature_SysTick      1 
// Include the µOS++ C API structures declarations.
#include <cmsis-plus/rtos/os-c-decls.h>
 
#include <stdint.h>
#include <stddef.h>
 
#ifdef  __cplusplus
extern "C"
{
#endif
 
// ==== Enumeration, structures, defines ====
 
  typedef enum
  {
    osPriorityIdle = os_thread_priority_idle, 
    osPriorityLow = os_thread_priority_low, 
    osPriorityBelowNormal = os_thread_priority_below_normal, 
    osPriorityNormal = os_thread_priority_normal, 
    osPriorityAboveNormal = os_thread_priority_above_normal, 
    osPriorityHigh = os_thread_priority_high, 
    osPriorityRealtime = os_thread_priority_realtime, 
    osPriorityError = os_thread_priority_error 
  } osPriority;
 
#define osWaitForever     0xFFFFFFFF 
  typedef enum
  {
    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 
  } osStatus;
 
  typedef enum
  {
    osTimerOnce = os_timer_once, 
    osTimerPeriodic = os_timer_periodic 
  } os_timer_type;
 
  typedef void
  (*os_pthread) (void const *argument);
 
  typedef void
  (*os_ptimer) (void const *argument);
 
  // Redefine some µOS++ struct's to the legacy code.
  typedef os_thread_t osThread;
  typedef os_thread_attr_t osThreadAttr;
 
  typedef os_timer_t osTimer;
  typedef os_timer_attr_t osTimerAttr;
 
  typedef os_mutex_t osMutex;
  typedef os_mutex_attr_t osMutexAttr;
 
  typedef os_semaphore_t osSemaphore;
  typedef os_semaphore_attr_t osSemaphoreAttr;
 
  typedef os_mempool_t osPool;
  typedef os_mempool_attr_t osPoolAttr;
 
  typedef os_mqueue_t osMessageQ;
  typedef os_mqueue_attr_t osMessageQAttr;
 
  typedef struct os_mail_queue_s
  {
    os_mempool_t pool;
    os_mqueue_t queue;
  } os_mail_queue_t;
 
  typedef os_mail_queue_t osMailQ;
 
  typedef osThread* osThreadId;
 
  typedef osTimer* osTimerId;
 
  typedef osMutex* osMutexId;
 
  typedef osSemaphore* osSemaphoreId;
 
  typedef osPool* osPoolId;
 
  typedef osMessageQ* osMessageQId;
 
  typedef osMailQ* osMailQId;
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wpadded"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wpadded"
#endif
 
  typedef struct os_thread_def
  {
    const char* name;
    os_pthread pthread; 
    osPriority tpriority; 
    uint32_t instances; 
    uint32_t stacksize; 
    osThread* data;
    uint64_t* stack; // align the stack at 8 bytes
  } osThreadDef_t;
 
#pragma GCC diagnostic pop
 
  typedef struct os_timer_def
  {
    const char* name;
    os_ptimer ptimer; 
    osTimer* data;
  } osTimerDef_t;
 
  typedef struct os_mutex_def
  {
    const char* name;
    osMutex* data;
  } osMutexDef_t;
 
  typedef struct os_semaphore_def
  {
    const char* name;
    osSemaphore* data;
  } osSemaphoreDef_t;
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wpadded"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wpadded"
#endif
 
  typedef struct os_pool_def
  {
    const char* name;
    uint32_t items; 
    uint32_t item_sz; 
    void* pool; 
    uint32_t pool_sz;
    osPool* data;
  } osPoolDef_t;
 
  typedef struct os_messageQ_def
  {
    const char* name;
    uint32_t items; 
    uint32_t item_sz; 
    void* queue; 
    uint32_t queue_sz;
    osMessageQ* data;
  } osMessageQDef_t;
 
  typedef struct os_mailQ_def
  {
    const char* name;
    uint32_t items; 
    uint32_t pool_item_sz; 
    uint32_t queue_item_sz; 
    void* pool; 
    uint32_t pool_sz;
    void* queue; 
    uint32_t queue_sz;
    osMailQ* data;
  } osMailQDef_t;
 
  typedef struct
  {
    osStatus status; 
    union
    {
      uint32_t v; 
      void* p; 
      int32_t signals; 
    } value; 
    union
    {
      osMailQId mail_id; 
      osMessageQId message_id; 
    } def; 
  } osEvent;
 
#pragma GCC diagnostic pop
 
//  ==== Kernel Control Functions ====
 
  osStatus
  osKernelInitialize (void);
 
  osStatus
  osKernelStart (void);
 
  int32_t
  osKernelRunning (void);
 
#if (defined (osFeature_SysTick)  &&  (osFeature_SysTick != 0))     // System Timer available
 
  uint32_t
  osKernelSysTick (void);
 
#define osKernelSysTickFrequency (OS_INTEGER_SYSTICK_FREQUENCY_HZ)
 
#define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
 
#endif    // System Timer available
 
//  ==== Thread Management ====
 
#if defined (osObjectsExternal)  // object is external
#define osThreadDef(name, priority, instances, stacksz)  \
extern const osThreadDef_t os_thread_def_##name
#else                            // define the object
#define osThreadAllocatedDef(name, priority, instances, stacksz)  \
struct { \
    osThread data[instances]; \
} os_thread_##name; \
const osThreadDef_t os_thread_def_##name = \
{ \
    #name, \
    (os_pthread)(name), \
    (priority), \
    (instances), \
    (stacksz), \
    &os_thread_##name.data[0], \
    0 \
}
#define osThreadStaticDef(name, priority, instances, stacksz)  \
struct { \
    uint64_t stack[(instances)*((stacksz+sizeof(uint64_t)-1)/sizeof(uint64_t))]; \
    osThread data[instances]; \
} os_thread_##name; \
const osThreadDef_t os_thread_def_##name = \
{ \
    #name, \
    (os_pthread)(name), \
    (priority), \
    (instances), \
    (stacksz), \
    &os_thread_##name.data[0], \
    &os_thread_##name.stack[0] \
}
#if defined(osObjectsStatic)
#define osThreadDef(name, priority, instances, stacksz)  osThreadStaticDef(name, priority, instances, stacksz)
#else
#define osThreadDef(name, priority, instances, stacksz)  osThreadAllocatedDef(name, priority, instances, stacksz)
#endif
#endif
 
#define osThread(name)  \
&os_thread_def_##name
 
  osThreadId
  osThreadCreate (const osThreadDef_t* thread_def, void* args);
 
  osThreadId
  osThreadGetId (void);
 
  osStatus
  osThreadTerminate (osThreadId thread_id);
 
  osStatus
  osThreadYield (void);
 
  osStatus
  osThreadSetPriority (osThreadId thread_id, osPriority priority);
 
  osPriority
  osThreadGetPriority (osThreadId thread_id);
 
//  ==== Generic Wait Functions ====
 
  osStatus
  osDelay (uint32_t millisec);
 
#if (defined (osFeature_Wait)  &&  (osFeature_Wait != 0))     // Generic Wait available
 
  osEvent
  osWait (uint32_t millisec);
 
#endif  // Generic Wait available
 
//  ==== Timer Management Functions ====
 
#if defined (osObjectsExternal)  // object is external
#define osTimerDef(name, function)  \
extern const osTimerDef_t os_timer_def_##name
#else                            // define the object
#define osTimerDef(name, function)  \
struct { \
    osTimer data; \
} os_timer_##name; \
const osTimerDef_t os_timer_def_##name = \
{ \
    #name, \
    (os_ptimer)(function), \
    &os_timer_##name.data \
}
#endif
 
#define osTimer(name) \
&os_timer_def_##name
 
  osTimerId
  osTimerCreate (const osTimerDef_t* timer_def, os_timer_type type, void* args);
 
  osStatus
  osTimerStart (osTimerId timer_id, uint32_t millisec);
 
  osStatus
  osTimerStop (osTimerId timer_id);
 
  osStatus
  osTimerDelete (osTimerId timer_id);
 
//  ==== Signal Management ====
 
  int32_t
  osSignalSet (osThreadId thread_id, int32_t signals);
 
  int32_t
  osSignalClear (osThreadId thread_id, int32_t signals);
 
  osEvent
  osSignalWait (int32_t signals, uint32_t millisec);
 
//  ==== Mutex Management ====
 
#if defined (osObjectsExternal)  // object is external
#define osMutexDef(name)  \
extern const osMutexDef_t os_mutex_def_##name
#else                            // define the object
#define osMutexDef(name)  \
osMutex os_mutex_data_##name; \
const osMutexDef_t os_mutex_def_##name = \
{ \
    #name, \
    &os_mutex_data_##name \
}
#endif
 
#define osMutex(name)  \
&os_mutex_def_##name
 
  osMutexId
  osMutexCreate (const osMutexDef_t* mutex_def);
 
  osStatus
  osMutexWait (osMutexId mutex_id, uint32_t millisec);
 
  osStatus
  osMutexRelease (osMutexId mutex_id);
 
  osStatus
  osMutexDelete (osMutexId mutex_id);
 
//  ==== Semaphore Management Functions ====
 
#if (defined (osFeature_Semaphore)  &&  (osFeature_Semaphore != 0))     // Semaphore available
 
#if defined (osObjectsExternal)  // object is external
#define osSemaphoreDef(name)  \
extern const osSemaphoreDef_t os_semaphore_def_##name
#else                            // define the object
#define osSemaphoreDef(name)  \
osSemaphore os_semaphore_data_##name; \
const osSemaphoreDef_t os_semaphore_def_##name = \
{ \
    #name, \
    &os_semaphore_data_##name \
}
#endif
 
#define osSemaphore(name)  \
&os_semaphore_def_##name
 
  osSemaphoreId
  osSemaphoreCreate (const osSemaphoreDef_t* semaphore_def, int32_t count);
 
  int32_t
  osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec);
 
  osStatus
  osSemaphoreRelease (osSemaphoreId semaphore_id);
 
  osStatus
  osSemaphoreDelete (osSemaphoreId semaphore_id);
 
#endif     // Semaphore available
 
//  ==== Memory Pool Management Functions ====
 
#if (defined (osFeature_Pool)  &&  (osFeature_Pool != 0))  // Memory Pool Management available
 
#if defined (osObjectsExternal)  // object is external
#define osPoolDef(name, no, type)   \
extern const osPoolDef_t os_pool_def_##name
#else                            // define the object
#define osPoolAllocatedDef(name, items, type)   \
struct { \
    osPool data; \
} os_pool_##name; \
const osPoolDef_t os_pool_def_##name = \
{ \
    #name, \
    (items), \
    sizeof(type), \
    0, \
    0, \
    &os_pool_##name.data \
}
#define osPoolStaticDef(name, items, type)   \
struct { \
    osPool data; \
    struct { \
      type pool[items]; \
    } storage; \
} os_pool_##name; \
const osPoolDef_t os_pool_def_##name = \
{ \
    #name, \
    (items), \
    sizeof(type), \
    &os_pool_##name.storage, \
    sizeof(os_pool_##name.storage), \
    &os_pool_##name.data \
}
#if defined(osObjectsStatic)
#define osPoolDef(name, items, type) osPoolStaticDef(name, items, type)
#else
#define osPoolDef(name, items, type) osPoolAllocatedDef(name, items, type)
#endif
#endif
 
#define osPool(name) \
&os_pool_def_##name
 
  osPoolId
  osPoolCreate (const osPoolDef_t* pool_def);
 
  void*
  osPoolAlloc (osPoolId pool_id);
 
  void*
  osPoolCAlloc (osPoolId pool_id);
 
  osStatus
  osPoolFree (osPoolId pool_id, void* block);
 
#endif   // Memory Pool Management available
 
//  ==== Message Queue Management Functions ====
 
#if (defined (osFeature_MessageQ)  &&  (osFeature_MessageQ != 0))     // Message Queues available
 
#if defined (osObjectsExternal)  // object is external
#define osMessageQDef(name, queue_sz, type)   \
extern const osMessageQDef_t os_messageQ_def_##name
#else                            // define the object
#define osMessageQAllocatedDef(name, items, type)   \
struct { \
    osMessageQ data; \
} os_messageQ_##name; \
const osMessageQDef_t os_messageQ_def_##name = { \
    #name, \
    (items), \
    sizeof (void*), \
    0, \
    0, \
    &os_messageQ_##name.data \
}
#define osMessageQStaticDef(name, items, type)   \
struct { \
    osMessageQ data; \
    struct { \
      void* queue[items]; \
      os_mqueue_index_t links[2 * items]; \
      os_mqueue_prio_t prios[items]; \
    } storage; \
} os_messageQ_##name; \
const osMessageQDef_t os_messageQ_def_##name = { \
    #name, \
    (items), \
    sizeof (void*), \
    &os_messageQ_##name.storage, \
    sizeof(os_messageQ_##name.storage), \
    &os_messageQ_##name.data \
}
 
#if defined(osObjectsStatic)
#define osMessageQDef(name, items, type) osMessageQStaticDef(name, items, type)
#else
#define osMessageQDef(name, items, type) osMessageQAllocatedDef(name, items, type)
#endif
#endif
 
#define osMessageQ(name) \
&os_messageQ_def_##name
 
  osMessageQId
  osMessageCreate (const osMessageQDef_t* queue_def, osThreadId thread_id);
 
  osStatus
  osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec);
 
  osEvent
  osMessageGet (osMessageQId queue_id, uint32_t millisec);
 
#endif     // Message Queues available
 
//  ==== Mail Queue Management Functions ====
 
#if (defined (osFeature_MailQ)  &&  (osFeature_MailQ != 0))     // Mail Queues available
 
#if defined (osObjectsExternal)  // object is external
#define osMailQDef(name, queue_sz, type) \
extern const osMailQDef_t os_mailQ_def_##name
#else                            // define the object
#define osMailQAllocatedDef(name, items, type) \
struct { \
    osMailQ data; \
    struct { \
      type pool[items]; \
    } pool_storage; \
    struct { \
      void* queue[items]; \
      os_mqueue_index_t links[2 * items]; \
      os_mqueue_prio_t prios[items]; \
    } queue_storage; \
} os_mailQ_##name; \
const osMailQDef_t os_mailQ_def_##name = { \
    #name, \
    (items), \
    sizeof (type), \
    sizeof (void*), \
    0, \
    0, \
    0, \
    0, \
    &os_mailQ_##name.data \
}
#define osMailQStaticDef(name, items, type) \
struct { \
    osMailQ data; \
    struct { \
      type pool[items]; \
    } pool_storage; \
    struct { \
      void* queue[items]; \
      os_mqueue_index_t links[2 * items]; \
      os_mqueue_prio_t prios[items]; \
    } queue_storage; \
} os_mailQ_##name; \
const osMailQDef_t os_mailQ_def_##name = { \
    #name, \
    (items), \
    sizeof (type), \
    sizeof (void*), \
    &os_mailQ_##name.pool_storage, \
    sizeof(os_mailQ_##name.pool_storage), \
    &os_mailQ_##name.queue_storage, \
    sizeof(os_mailQ_##name.queue_storage), \
    &os_mailQ_##name.data \
}
#if defined(osObjectsStatic)
#define osMailQDef(name, items, type) osMailQStaticDef(name, items, type)
#else
#define osMailQDef(name, items, type) osMailQAllocatedDef(name, items, type)
#endif
#endif
 
#define osMailQ(name)  \
&os_mailQ_def_##name
 
  osMailQId
  osMailCreate (const osMailQDef_t* mail_def, osThreadId thread_id);
 
  void*
  osMailAlloc (osMailQId mail_id, uint32_t millisec);
 
  void*
  osMailCAlloc (osMailQId mail_id, uint32_t millisec);
 
  osStatus
  osMailPut (osMailQId mail_id, void* mail);
 
  osEvent
  osMailGet (osMailQId mail_id, uint32_t millisec);
 
  osStatus
  osMailFree (osMailQId mail_id, void* mail);
 
#endif  // Mail Queues available
 
#ifdef  __cplusplus
}
#endif
 
#pragma GCC diagnostic pop
 
#endif  /* CMSIS_OS_H_ */