cmsis_os.h

/* ----------------------------------------------------------------------
 * $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 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 
 *----------------------------------------------------------------------------
 *
 * 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.
 *---------------------------------------------------------------------------*/
 
 
#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    30      
#define osFeature_Wait         1       
#define osFeature_SysTick      1       
 
#include <stdint.h>
#include <stddef.h>
 
#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;
 
 
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 struct os_thread_cb *osThreadId;
 
typedef struct os_timer_cb *osTimerId;
 
typedef struct os_mutex_cb *osMutexId;
 
typedef struct os_semaphore_cb *osSemaphoreId;
 
typedef struct os_pool_cb *osPoolId;
 
typedef struct os_messageQ_cb *osMessageQId;
 
typedef struct os_mailQ_cb *osMailQId;
 
 
typedef struct os_thread_def  {
  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;    
} osMessageQDef_t;
 
typedef struct os_mailQ_def  {
  uint32_t                queue_sz;    
  uint32_t                 item_sz;    
  void                       *pool;    
} 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 100000000
 
#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 osThreadDef(name, priority, instances, stacksz)  \
const osThreadDef_t os_thread_def_##name = \
{ (name), (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 const osMailQDef_t os_mailQ_def_##name
#else                            // define the object
#define osMailQDef(name, queue_sz, type) \
const osMailQDef_t os_mailQ_def_##name =  \
{ (queue_sz), sizeof (type) }
#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
 
 
#ifdef  __cplusplus
}
#endif
 
#endif  // _CMSIS_OS_H