cmsis_os2.h

Go to the documentation of this file.

/*
 * Copyright (c) 2013-2023 Arm Limited. All rights reserved.
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the License); you may
 * not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * ----------------------------------------------------------------------
 *
 * $Date:        30. June 2023
 * $Revision:    V2.3.0
 *
 * Project:      CMSIS-RTOS2 API
 * Title:        cmsis_os2.h header file
 *
 * Version 2.3.0
 *    Added provisional support for processor affinity in SMP systems:
      - osThreadAttr_t: affinity_mask
 *    - osThreadSetAffinityMask, osThreadGetAffinityMask
 * Version 2.2.0
 *    Added support for Process Isolation (Functional Safety):
 *    - Kernel Management: osKernelProtect, osKernelDestroyClass
 *    - Thread Management: osThreadGetClass, osThreadGetZone,
 *                         osThreadSuspendClass, osThreadResumeClass
 *                         osThreadTerminateZone,
 *                         osThreadFeedWatchdog,
 *                         osThreadProtectPrivileged
 *    - Thread attributes: osThreadZone, osThreadUnprivileged/osThreadPrivileged
 *    - Object attributes: osSafetyClass
 *    - Handler functions: osWatchdogAlarm_Handler
 *    - Zone Management: osZoneSetup_Callback
 *    - Exception Faults: osFaultResume
 *    Additional functions allowed to be called from Interrupt Service Routines:
 *    - osThreadGetName, osTimerGetName, osEventFlagsGetName, osMutexGetName,
 *      osSemaphoreGetName, osMemoryPoolGetName, osMessageQueueGetName
 * Version 2.1.3
 *    Additional functions allowed to be called from Interrupt Service Routines:
 *    - osThreadGetId
 * Version 2.1.2
 *    Additional functions allowed to be called from Interrupt Service Routines:
 *    - osKernelGetInfo, osKernelGetState
 * Version 2.1.1
 *    Additional functions allowed to be called from Interrupt Service Routines:
 *    - osKernelGetTickCount, osKernelGetTickFreq
 *    Changed Kernel Tick type to uint32_t:
 *    - updated: osKernelGetTickCount, osDelayUntil
 * Version 2.1.0
 *    Support for critical and uncritical sections (nesting safe):
 *    - updated: osKernelLock, osKernelUnlock
 *    - added: osKernelRestoreLock
 *    Updated Thread and Event Flags:
 *    - changed flags parameter and return type from int32_t to uint32_t
 * Version 2.0.0
 *    Initial Release
 *---------------------------------------------------------------------------*/
 
#ifndef CMSIS_OS2_H_
#define CMSIS_OS2_H_
 
#ifndef __NO_RETURN
#if   defined(__CC_ARM)
#define __NO_RETURN __declspec(noreturn)
#elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)
#define __NO_RETURN __attribute__((__noreturn__))
#elif defined(__GNUC__)
#define __NO_RETURN __attribute__((__noreturn__))
#elif defined(__ICCARM__)
#define __NO_RETURN __noreturn
#else
#define __NO_RETURN
#endif
#endif
 
#include <stdint.h>
#include <stddef.h>

 
#ifdef  __cplusplus
extern "C"
{
#endif
 
 
//  ==== Enumerations, structures, defines ====
 
typedef struct {
  uint32_t                       api;   
  uint32_t                    kernel;   
} osVersion_t;
 
typedef enum {
  osKernelInactive        =  0,         
  osKernelReady           =  1,         
  osKernelRunning         =  2,         
  osKernelLocked          =  3,         
  osKernelSuspended       =  4,         
  osKernelError           = -1,         
  osKernelReserved        = 0x7FFFFFFF  
} osKernelState_t;
 
typedef enum {
  osThreadInactive        =  0,         
  osThreadReady           =  1,         
  osThreadRunning         =  2,         
  osThreadBlocked         =  3,         
  osThreadTerminated      =  4,         
  osThreadError           = -1,         
  osThreadReserved        = 0x7FFFFFFF  
} osThreadState_t;
 
typedef enum {
  osPriorityNone          =  0,         
  osPriorityIdle          =  1,         
  osPriorityLow           =  8,         
  osPriorityLow1          =  8+1,       
  osPriorityLow2          =  8+2,       
  osPriorityLow3          =  8+3,       
  osPriorityLow4          =  8+4,       
  osPriorityLow5          =  8+5,       
  osPriorityLow6          =  8+6,       
  osPriorityLow7          =  8+7,       
  osPriorityBelowNormal   = 16,         
  osPriorityBelowNormal1  = 16+1,       
  osPriorityBelowNormal2  = 16+2,       
  osPriorityBelowNormal3  = 16+3,       
  osPriorityBelowNormal4  = 16+4,       
  osPriorityBelowNormal5  = 16+5,       
  osPriorityBelowNormal6  = 16+6,       
  osPriorityBelowNormal7  = 16+7,       
  osPriorityNormal        = 24,         
  osPriorityNormal1       = 24+1,       
  osPriorityNormal2       = 24+2,       
  osPriorityNormal3       = 24+3,       
  osPriorityNormal4       = 24+4,       
  osPriorityNormal5       = 24+5,       
  osPriorityNormal6       = 24+6,       
  osPriorityNormal7       = 24+7,       
  osPriorityAboveNormal   = 32,         
  osPriorityAboveNormal1  = 32+1,       
  osPriorityAboveNormal2  = 32+2,       
  osPriorityAboveNormal3  = 32+3,       
  osPriorityAboveNormal4  = 32+4,       
  osPriorityAboveNormal5  = 32+5,       
  osPriorityAboveNormal6  = 32+6,       
  osPriorityAboveNormal7  = 32+7,       
  osPriorityHigh          = 40,         
  osPriorityHigh1         = 40+1,       
  osPriorityHigh2         = 40+2,       
  osPriorityHigh3         = 40+3,       
  osPriorityHigh4         = 40+4,       
  osPriorityHigh5         = 40+5,       
  osPriorityHigh6         = 40+6,       
  osPriorityHigh7         = 40+7,       
  osPriorityRealtime      = 48,         
  osPriorityRealtime1     = 48+1,       
  osPriorityRealtime2     = 48+2,       
  osPriorityRealtime3     = 48+3,       
  osPriorityRealtime4     = 48+4,       
  osPriorityRealtime5     = 48+5,       
  osPriorityRealtime6     = 48+6,       
  osPriorityRealtime7     = 48+7,       
  osPriorityISR           = 56,         
  osPriorityError         = -1,         
  osPriorityReserved      = 0x7FFFFFFF  
} osPriority_t;
 
typedef void (*osThreadFunc_t) (void *argument);
 
typedef void (*osTimerFunc_t) (void *argument);
 
typedef enum {
  osTimerOnce             = 0,          
  osTimerPeriodic         = 1           
} osTimerType_t;
 
// Timeout value.
#define osWaitForever           0xFFFFFFFFU 
 
// Flags options (\ref osThreadFlagsWait and \ref osEventFlagsWait).
#define osFlagsWaitAny          0x00000000U 
#define osFlagsWaitAll          0x00000001U 
#define osFlagsNoClear          0x00000002U 
 
// Flags errors (returned by osThreadFlagsXxxx and osEventFlagsXxxx).
#define osFlagsError            0x80000000U 
#define osFlagsErrorUnknown     0xFFFFFFFFU 
#define osFlagsErrorTimeout     0xFFFFFFFEU 
#define osFlagsErrorResource    0xFFFFFFFDU 
#define osFlagsErrorParameter   0xFFFFFFFCU 
#define osFlagsErrorISR         0xFFFFFFFAU 
#define osFlagsErrorSafetyClass 0xFFFFFFF9U 
 
// Thread attributes (attr_bits in \ref osThreadAttr_t).
#define osThreadDetached        0x00000000U 
#define osThreadJoinable        0x00000001U 
#define osThreadUnprivileged    0x00000002U 
#define osThreadPrivileged      0x00000004U 
 
#define osThreadZone_Pos        8U                            
#define osThreadZone_Msk        (0x3FUL << osThreadZone_Pos)  
#define osThreadZone_Valid      (0x80UL << osThreadZone_Pos)  
#define osThreadZone(n)         ((((n) << osThreadZone_Pos) & osThreadZone_Msk) | \
                                 osThreadZone_Valid)          
 
// Thread processor affinity (affinity_mask in \ref osThreadAttr_t).
#define osThreadProcessor(n)    (1UL << (n))    
 
// Mutex attributes (attr_bits in \ref osMutexAttr_t).
#define osMutexRecursive        0x00000001U 
#define osMutexPrioInherit      0x00000002U 
#define osMutexRobust           0x00000008U 
 
// Object attributes (attr_bits in all objects).
#define osSafetyClass_Pos       16U                           
#define osSafetyClass_Msk       (0x0FUL << osSafetyClass_Pos) 
#define osSafetyClass_Valid     (0x10UL << osSafetyClass_Pos) 
#define osSafetyClass(n)        ((((n) << osSafetyClass_Pos) & osSafetyClass_Msk) | \
                                 osSafetyClass_Valid)         
 
// Safety mode (\ref osThreadSuspendClass, \ref osThreadResumeClass and \ref osKernelDestroyClass).
#define osSafetyWithSameClass   0x00000001U 
#define osSafetyWithLowerClass  0x00000002U 
 
// Error indication (returned by \ref osThreadGetClass and \ref osThreadGetZone).
#define osErrorId               0xFFFFFFFFU 
 
typedef enum {
  osOK                    =  0,         
  osError                 = -1,         
  osErrorTimeout          = -2,         
  osErrorResource         = -3,         
  osErrorParameter        = -4,         
  osErrorNoMemory         = -5,         
  osErrorISR              = -6,         
  osErrorSafetyClass      = -7,         
  osStatusReserved        = 0x7FFFFFFF  
} osStatus_t;
 
 
typedef void *osThreadId_t;
 
typedef void *osTimerId_t;
 
typedef void *osEventFlagsId_t;
 
typedef void *osMutexId_t;
 
typedef void *osSemaphoreId_t;
 
typedef void *osMemoryPoolId_t;
 
typedef void *osMessageQueueId_t;
 
 
#ifndef TZ_MODULEID_T
#define TZ_MODULEID_T
typedef uint32_t TZ_ModuleId_t;
#endif
 
 
typedef struct {
  const char                   *name;   
  uint32_t                 attr_bits;   
  void                      *cb_mem;    
  uint32_t                   cb_size;   
  void                   *stack_mem;    
  uint32_t                stack_size;   
  osPriority_t              priority;   
  TZ_ModuleId_t            tz_module;   
  uint32_t             affinity_mask;   
} osThreadAttr_t;
 
typedef struct {
  const char                   *name;   
  uint32_t                 attr_bits;   
  void                      *cb_mem;    
  uint32_t                   cb_size;   
} osTimerAttr_t;
 
typedef struct {
  const char                   *name;   
  uint32_t                 attr_bits;   
  void                      *cb_mem;    
  uint32_t                   cb_size;   
} osEventFlagsAttr_t;
 
typedef struct {
  const char                   *name;   
  uint32_t                 attr_bits;   
  void                      *cb_mem;    
  uint32_t                   cb_size;   
} osMutexAttr_t;
 
typedef struct {
  const char                   *name;   
  uint32_t                 attr_bits;   
  void                      *cb_mem;    
  uint32_t                   cb_size;   
} osSemaphoreAttr_t;
 
typedef struct {
  const char                   *name;   
  uint32_t                 attr_bits;   
  void                      *cb_mem;    
  uint32_t                   cb_size;   
  void                      *mp_mem;    
  uint32_t                   mp_size;   
} osMemoryPoolAttr_t;
 
typedef struct {
  const char                   *name;   
  uint32_t                 attr_bits;   
  void                      *cb_mem;    
  uint32_t                   cb_size;   
  void                      *mq_mem;    
  uint32_t                   mq_size;   
} osMessageQueueAttr_t;
 
 
//  ==== Kernel Management Functions ====
 
osStatus_t osKernelInitialize (void);
 
osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size);
 
osKernelState_t osKernelGetState (void);
 
osStatus_t osKernelStart (void);
 
int32_t osKernelLock (void);
 
int32_t osKernelUnlock (void);
 
int32_t osKernelRestoreLock (int32_t lock);
 
uint32_t osKernelSuspend (void);
 
void osKernelResume (uint32_t sleep_ticks);
 
osStatus_t osKernelProtect (uint32_t safety_class);
 
osStatus_t osKernelDestroyClass (uint32_t safety_class, uint32_t mode); 
 
uint32_t osKernelGetTickCount (void);
 
uint32_t osKernelGetTickFreq (void);
 
uint32_t osKernelGetSysTimerCount (void);

uint64_t osKernelGetSysTimerCount64(void);
 
uint32_t osKernelGetSysTimerFreq (void);
 
 
//  ==== Thread Management Functions ====
 
osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr);
 
const char *osThreadGetName (osThreadId_t thread_id);
 
uint32_t osThreadGetClass (osThreadId_t thread_id);
 
uint32_t osThreadGetZone (osThreadId_t thread_id);
 
osThreadId_t osThreadGetId (void);
 
osThreadState_t osThreadGetState (osThreadId_t thread_id);
 
uint32_t osThreadGetStackSize (osThreadId_t thread_id);
 
uint32_t osThreadGetStackSpace (osThreadId_t thread_id);
 
osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority);
 
osPriority_t osThreadGetPriority (osThreadId_t thread_id);
 
osStatus_t osThreadYield (void);
 
osStatus_t osThreadSuspend (osThreadId_t thread_id);
 
osStatus_t osThreadResume (osThreadId_t thread_id);
 
osStatus_t osThreadDetach (osThreadId_t thread_id);
 
osStatus_t osThreadJoin (osThreadId_t thread_id);
 
__NO_RETURN void osThreadExit (void);
 
osStatus_t osThreadTerminate (osThreadId_t thread_id);
 
osStatus_t osThreadFeedWatchdog (uint32_t ticks);
 
osStatus_t osThreadProtectPrivileged (void);
 
osStatus_t osThreadSuspendClass (uint32_t safety_class, uint32_t mode);
 
osStatus_t osThreadResumeClass (uint32_t safety_class, uint32_t mode);
 
osStatus_t osThreadTerminateZone (uint32_t zone);
 
osStatus_t osThreadSetAffinityMask (osThreadId_t thread_id, uint32_t affinity_mask);
 
uint32_t osThreadGetAffinityMask (osThreadId_t thread_id);
 
uint32_t osThreadGetCount (void);
 
uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items);
 
 
//  ==== Thread Flags Functions ====
 
uint32_t osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags);
 
uint32_t osThreadFlagsClear (uint32_t flags);
 
uint32_t osThreadFlagsGet (void);
 
uint32_t osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout);
 
 
//  ==== Generic Wait Functions ====
 
osStatus_t osDelay (uint32_t ticks);
 
osStatus_t osDelayUntil (uint32_t ticks);
 
 
//  ==== Timer Management Functions ====
 
osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr);
 
const char *osTimerGetName (osTimerId_t timer_id);
 
osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks);
 
osStatus_t osTimerStop (osTimerId_t timer_id);
 
uint32_t osTimerIsRunning (osTimerId_t timer_id);
 
osStatus_t osTimerDelete (osTimerId_t timer_id);
 
 
//  ==== Event Flags Management Functions ====
 
osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr);
 
const char *osEventFlagsGetName (osEventFlagsId_t ef_id);
 
uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags);
 
uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags);
 
uint32_t osEventFlagsGet (osEventFlagsId_t ef_id);
 
uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout);
 
osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id);
 
 
//  ==== Mutex Management Functions ====
 
osMutexId_t osMutexNew (const osMutexAttr_t *attr);
 
const char *osMutexGetName (osMutexId_t mutex_id);
 
osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout);
 
osStatus_t osMutexRelease (osMutexId_t mutex_id);
 
osThreadId_t osMutexGetOwner (osMutexId_t mutex_id);
 
osStatus_t osMutexDelete (osMutexId_t mutex_id);
 
 
//  ==== Semaphore Management Functions ====
 
osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr);
 
const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id);
 
osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout);
 
osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id);
 
uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id);
 
osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id);
 
 
//  ==== Memory Pool Management Functions ====
 
osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr);
 
const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id);
 
void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout);
 
osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block);
 
uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id);
 
uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id);
 
uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id);
 
uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id);
 
osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id);
 
 
//  ==== Message Queue Management Functions ====
 
osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr);
 
const char *osMessageQueueGetName (osMessageQueueId_t mq_id);
 
osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout);
 
osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout);
 
uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id);
 
uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id);
 
uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id);
 
uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id);
 
osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id);
 
osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id);
 
 
//  ==== Handler Functions ====
 
uint32_t osWatchdogAlarm_Handler (osThreadId_t thread_id);
 
 
// ==== Zone Management Function ====
 
void osZoneSetup_Callback (uint32_t zone);
 
 
//  ==== Exception Faults ====
 
void osFaultResume (void);
 
 
#ifdef  __cplusplus
}
#endif

 
#endif  // CMSIS_OS2_H_