cmsis_os.h

Go to the documentation of this file.

/* ----------------------------------------------------------------------
 * $Date:        5. February 2013
 * $Revision:    V1.02
 *
 * Project:      CMSIS-RTOS API
 * Title:        cmsis_os.h header file
 *
 * Version 0.02
 *    Initial Proposal Phase
 * Version 0.03
 *    osKernelStart added, optional feature: main started as thread
 *    osSemaphores have standard behavior
 *    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 
 *    
 *  
 *----------------------------------------------------------------------------
 *
 * Portions Copyright © 2016 STMicroelectronics International N.V. All rights reserved.
 * Portions 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.
 *---------------------------------------------------------------------------*/

 #if   defined ( __CC_ARM )
  #define __ASM            __asm                                      
  #define __INLINE         __inline                                   
  #define __STATIC_INLINE  static __inline
#elif defined ( __ICCARM__ )
  #define __ASM            __asm                                      
  #define __INLINE         inline                                     
  #define __STATIC_INLINE  static inline
#elif defined ( __GNUC__ )
  #define __ASM            __asm                                      
  #define __INLINE         inline                                     
  #define __STATIC_INLINE  static inline
#endif

#include <stdint.h>
#include <stddef.h>
#include "core_cmFunc.h"
    
#include "FreeRTOS.h"
#include "task.h"
#include "timers.h"
#include "queue.h"
#include "semphr.h"
#include "event_groups.h"

#ifndef _CMSIS_OS_H
#define _CMSIS_OS_H

#define osCMSIS           0x10002      

#define osCMSIS_KERNEL    0x10000      

#define osKernelSystemId "KERNEL V1.00"   

#define osFeature_MainThread   1       
#define osFeature_Pool         1       
#define osFeature_MailQ        1       
#define osFeature_MessageQ     1       
#define osFeature_Signals      8       
#define osFeature_Semaphore    1      
#define osFeature_Wait         0       
#define osFeature_SysTick      1       

#ifdef  __cplusplus
extern "C"
{
#endif


// ==== Enumeration, structures, defines ====

typedef enum  {
  osPriorityIdle          = -3,          
  osPriorityLow           = -2,          
  osPriorityBelowNormal   = -1,          
  osPriorityNormal        =  0,          
  osPriorityAboveNormal   = +1,          
  osPriorityHigh          = +2,          
  osPriorityRealtime      = +3,          
  osPriorityError         =  0x84        
} 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;

#if ( INCLUDE_eTaskGetState == 1 )
/* Thread state returned by osThreadGetState */
typedef enum {
    osThreadRunning   = 0x0,          /* A thread is querying the state of itself, so must be running. */
    osThreadReady     = 0x1 ,                   /* The thread being queried is in a read or pending ready list. */
    osThreadBlocked   = 0x2,                /* The thread being queried is in the Blocked state. */
    osThreadSuspended = 0x3,          /* The thread being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */
    osThreadDeleted   = 0x4,                  /* The thread being queried has been deleted, but its TCB has not yet been freed. */   
  osThreadError     = 0x7FFFFFFF
} osThreadState;
#endif /* INCLUDE_eTaskGetState */

typedef enum  {
  osTimerOnce             =     0,       
  osTimerPeriodic         =     1        
} os_timer_type;

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

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

// >>> the following data type definitions may shall adapted towards a specific RTOS

typedef TaskHandle_t osThreadId;

typedef TimerHandle_t osTimerId;

typedef SemaphoreHandle_t osMutexId;

typedef SemaphoreHandle_t osSemaphoreId;

typedef struct os_pool_cb *osPoolId;

typedef QueueHandle_t osMessageQId;

typedef struct os_mailQ_cb *osMailQId;


typedef struct os_thread_def  {
  char                   *name;        
  os_pthread             pthread;      
  osPriority             tpriority;    
  uint32_t               instances;    
  uint32_t               stacksize;    
} osThreadDef_t;

typedef struct os_timer_def  {
  os_ptimer                 ptimer;    
} osTimerDef_t;

typedef struct os_mutex_def  {
  uint32_t                   dummy;    
} osMutexDef_t;

typedef struct os_semaphore_def  {
  uint32_t                   dummy;    
} osSemaphoreDef_t;

typedef struct os_pool_def  {
  uint32_t                 pool_sz;    
  uint32_t                 item_sz;    
  void                       *pool;    
} osPoolDef_t;

typedef struct os_messageQ_def  {
  uint32_t                queue_sz;    
  uint32_t                 item_sz;    
  //void                       *pool;    ///< memory array for messages
} osMessageQDef_t;

typedef struct os_mailQ_def  {
  uint32_t                queue_sz;    
  uint32_t                 item_sz;    
  struct os_mailQ_cb **cb;
} 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;


//  ==== 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      (configTICK_RATE_HZ)

#define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)

#endif    // System Timer available

//  ==== Thread Management ====

#if defined (osObjectsExternal)  // object is external
#define osThreadDef(name, thread, priority, instances, stacksz)  \
extern const osThreadDef_t os_thread_def_##name
#else                            // define the object
#define osThreadDef(name, thread, priority, instances, stacksz)  \
const osThreadDef_t os_thread_def_##name = \
{ #name, (thread), (priority), (instances), (stacksz)  }
#endif

#define osThread(name)  \
&os_thread_def_##name

osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument);

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)  \
const osTimerDef_t os_timer_def_##name = \
{ (function) }
#endif

#define osTimer(name) \
&os_timer_def_##name

osTimerId osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument);

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)  \
const osMutexDef_t os_mutex_def_##name = { 0 }
#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)  \
const osSemaphoreDef_t os_semaphore_def_##name = { 0 }
#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 osPoolDef(name, no, type)   \
const osPoolDef_t os_pool_def_##name = \
{ (no), sizeof(type), NULL }
#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 osMessageQDef(name, queue_sz, type)   \
const osMessageQDef_t os_messageQ_def_##name = \
{ (queue_sz), sizeof (type)  }
#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 struct os_mailQ_cb *os_mailQ_cb_##name \
extern osMailQDef_t os_mailQ_def_##name
#else                            // define the object
#define osMailQDef(name, queue_sz, type) \
struct os_mailQ_cb *os_mailQ_cb_##name; \
const osMailQDef_t os_mailQ_def_##name =  \
{ (queue_sz), sizeof (type), (&os_mailQ_cb_##name) }
#endif

#define osMailQ(name)  \
&os_mailQ_def_##name

osMailQId osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id);

void *osMailAlloc (osMailQId queue_id, uint32_t millisec);

void *osMailCAlloc (osMailQId queue_id, uint32_t millisec);

osStatus osMailPut (osMailQId queue_id, void *mail);

osEvent osMailGet (osMailQId queue_id, uint32_t millisec);

osStatus osMailFree (osMailQId queue_id, void *mail);

#endif  // Mail Queues available

/*************************** Additional specific APIs to Free RTOS ************/
void osSystickHandler(void);

#if ( INCLUDE_eTaskGetState == 1 )

osThreadState osThreadGetState(osThreadId thread_id);
#endif /* INCLUDE_eTaskGetState */

#if ( INCLUDE_eTaskGetState == 1 )

osStatus osThreadIsSuspended(osThreadId thread_id);

#endif /* INCLUDE_eTaskGetState */

osStatus osThreadSuspend (osThreadId thread_id);

osStatus osThreadResume (osThreadId thread_id);

osStatus osThreadSuspendAll (void);

osStatus osThreadResumeAll (void);

osStatus osDelayUntil (uint32_t *PreviousWakeTime, uint32_t millisec);

osStatus osThreadList (uint8_t *buffer);

osEvent osMessagePeek (osMessageQId queue_id, uint32_t millisec);

osMutexId osRecursiveMutexCreate (const osMutexDef_t *mutex_def);

osStatus osRecursiveMutexRelease (osMutexId mutex_id);

osStatus osRecursiveMutexWait (osMutexId mutex_id, uint32_t millisec);

#ifdef  __cplusplus
}
#endif

#endif  // _CMSIS_OS_H