cmsis_os.h

00001 /* ----------------------------------------------------------------------  
00002  * Copyright (C) 2012 ARM Limited. All rights reserved.  
00003  *  
00004  * $Date:        5. June 2012
00005  * $Revision:    V1.01
00006  *  
00007  * Project:      CMSIS-RTOS API
00008  * Title:        cmsis_os.h RTX header file
00009  *  
00010  * Version 0.02
00011  *    Initial Proposal Phase 
00012  * Version 0.03
00013  *    osKernelStart added, optional feature: main started as thread
00014  *    osSemaphores have standard behavior
00015  *    osTimerCreate does not start the timer, added osTimerStart
00016  *    osThreadPass is renamed to osThreadYield
00017  * Version 1.01
00018  *    Support for C++ interface
00019  *     - const attribute removed from the osXxxxDef_t typedef's 
00020  *     - const attribute added to the osXxxxDef macros
00021  *    Added: osTimerDelete, osMutexDelete, osSemaphoreDelete
00022  *    Added: osKernelInitialize
00023  * -------------------------------------------------------------------- */ 
00024 
00025 /**
00026 \page cmsis_os_h Header File Template: cmsis_os.h
00027 
00028 The file \b cmsis_os.h is a template header file for a CMSIS-RTOS compliant Real-Time Operating System (RTOS).
00029 Each RTOS that is compliant with CMSIS-RTOS shall provide a specific \b cmsis_os.h header file that represents
00030 its implementation.
00031 
00032 The file cmsis_os.h contains:
00033  - CMSIS-RTOS API function definitions
00034  - struct definitions for parameters and return types
00035  - status and priority values used by CMSIS-RTOS API functions
00036  - macros for defining threads and other kernel objects
00037 
00038 
00039 <b>Name conventions and header file modifications</b>
00040 
00041 All definitions are prefixed with \b os to give an unique name space for CMSIS-RTOS functions.
00042 Definitions that are prefixed \b os_ are not used in the application code but local to this header file.
00043 All definitions and functions that belong to a module are grouped and have a common prefix, i.e. \b osThread.
00044  
00045 Definitions that are marked with <b>CAN BE CHANGED</b> can be adapted towards the needs of the actual CMSIS-RTOS implementation. 
00046 These definitions can be specific to the underlying RTOS kernel.
00047 
00048 Definitions that are marked with <b>MUST REMAIN UNCHANGED</b> cannot be altered. Otherwise the CMSIS-RTOS implementation is no longer
00049 compliant to the standard. Note that some functions are optional and need not to be provided by every CMSIS-RTOS implementation.
00050 
00051 
00052 <b>Function calls from interrupt service routines</b>
00053 
00054 The following CMSIS-RTOS functions can be called from threads and interrupt service routines (ISR):
00055   - \ref osSignalSet
00056   - \ref osSemaphoreRelease
00057   - \ref osPoolAlloc, \ref osPoolCAlloc, \ref osPoolFree
00058   - \ref osMessagePut, \ref osMessageGet
00059   - \ref osMailAlloc, \ref osMailCAlloc, \ref osMailGet, \ref osMailPut, \ref osMailFree
00060 
00061 Functions that cannot be called from an ISR are verifying the interrupt status and return in case that they are called 
00062 from an ISR context the status code \b osErrorISR. In some implementations this condition might be caught using the HARD FAULT vector.
00063 
00064 Some CMSIS-RTOS implementations support CMSIS-RTOS function calls from multiple ISR at the same time.
00065 If this is impossible, the CMSIS-RTOS rejects calls by nested ISR functions with the status code \b osErrorISRRecursive.
00066 
00067 
00068 <b>Define and reference object definitions</b>
00069 
00070 With <b>\#define osObjectsExternal</b> objects are defined as external symbols. This allows to create a consistent header file
00071 that is used throughout a project as shown below:
00072 
00073 <i>Header File</i>
00074 \code
00075 #include <cmsis_os.h>                                         // CMSIS RTOS header file
00076 
00077 // Thread definition
00078 extern void thread_sample (void const *argument);             // function prototype
00079 osThreadDef (thread_sample, osPriorityBelowNormal, 1, 100);
00080 
00081 // Pool definition
00082 osPoolDef(MyPool, 10, long);                      
00083 \endcode
00084 
00085 
00086 This header file defines all objects when included in a C/C++ source file. When <b>\#define osObjectsExternal</b> is 
00087 present before the header file, the objects are defined as external symbols. A single consistent header file can therefore be
00088 used throughout the whole project.
00089 
00090 <i>Example</i>
00091 \code
00092 #include "osObjects.h"     // Definition of the CMSIS-RTOS objects
00093 \endcode
00094 
00095 \code
00096 #define osObjectExternal   // Objects will be defined as external symbols
00097 #include "osObjects.h"     // Reference to the CMSIS-RTOS objects
00098 \endcode
00099 
00100 */
00101  
00102 #ifndef _CMSIS_OS_H
00103 #define _CMSIS_OS_H
00104 
00105 /// \note MUST REMAIN UNCHANGED: \b osCMSIS identifies the CMSIS-RTOS API version.
00106 #define osCMSIS           0x10001      ///< API version (main [31:16] .sub [15:0])
00107 
00108 /// \note CAN BE CHANGED: \b osCMSIS_KERNEL identifies the underlying RTOS kernel and version number.
00109 #define osCMSIS_RTX     ((4<<16)|61)   ///< RTOS identification and version (main [31:16] .sub [15:0])
00110 
00111 /// \note MUST REMAIN UNCHANGED: \b osKernelSystemId shall be consistent in every CMSIS-RTOS.
00112 #define osKernelSystemId "RTX V4.61"   ///< RTOS identification string
00113 
00114 
00115 #define CMSIS_OS_RTX
00116 
00117 // The stack space occupied is mainly dependent on the underling C standard library
00118 #if defined(TOOLCHAIN_GCC) || defined(TOOLCHAIN_ARM_STD)
00119 #    define WORDS_STACK_SIZE   512
00120 #elif defined(TOOLCHAIN_ARM_MICRO)
00121 #    define WORDS_STACK_SIZE   128
00122 #endif
00123 
00124 #define DEFAULT_STACK_SIZE         (WORDS_STACK_SIZE*4)
00125 
00126 
00127 /// \note MUST REMAIN UNCHANGED: \b osFeature_xxx shall be consistent in every CMSIS-RTOS.
00128 #define osFeature_MainThread   1       ///< main thread      1=main can be thread, 0=not available
00129 #define osFeature_Pool         1       ///< Memory Pools:    1=available, 0=not available
00130 #define osFeature_MailQ        1       ///< Mail Queues:     1=available, 0=not available
00131 #define osFeature_MessageQ     1       ///< Message Queues:  1=available, 0=not available
00132 #define osFeature_Signals      16      ///< maximum number of Signal Flags available per thread
00133 #define osFeature_Semaphore    65535   ///< maximum count for \ref osSemaphoreCreate function
00134 #define osFeature_Wait         0       ///< osWait function: 1=available, 0=not available
00135 
00136 #if defined (__CC_ARM)
00137 #define os_InRegs __value_in_regs      // Compiler specific: force struct in registers
00138 #else
00139 #define os_InRegs
00140 #endif
00141 
00142 #include <stdint.h>
00143 #include <stddef.h>
00144 
00145 #ifdef  __cplusplus
00146 extern "C"
00147 {
00148 #endif
00149 
00150 #include "os_tcb.h"
00151 
00152 // ==== Enumeration, structures, defines ====
00153 
00154 /// Priority used for thread control.
00155 /// \note MUST REMAIN UNCHANGED: \b osPriority shall be consistent in every CMSIS-RTOS.
00156 typedef enum  {
00157   osPriorityIdle          = -3,          ///< priority: idle (lowest)
00158   osPriorityLow           = -2,          ///< priority: low
00159   osPriorityBelowNormal   = -1,          ///< priority: below normal
00160   osPriorityNormal        =  0,          ///< priority: normal (default)
00161   osPriorityAboveNormal   = +1,          ///< priority: above normal
00162   osPriorityHigh          = +2,          ///< priority: high 
00163   osPriorityRealtime      = +3,          ///< priority: realtime (highest)
00164   osPriorityError         =  0x84        ///< system cannot determine priority or thread has illegal priority
00165 } osPriority;
00166 
00167 /// Timeout value.
00168 /// \note MUST REMAIN UNCHANGED: \b osWaitForever shall be consistent in every CMSIS-RTOS.
00169 #define osWaitForever     0xFFFFFFFF     ///< wait forever timeout value
00170 
00171 /// Status code values returned by CMSIS-RTOS functions.
00172 /// \note MUST REMAIN UNCHANGED: \b osStatus shall be consistent in every CMSIS-RTOS.
00173 typedef enum  {
00174   osOK                    =     0,       ///< function completed; no error or event occurred.
00175   osEventSignal           =  0x08,       ///< function completed; signal event occurred.
00176   osEventMessage          =  0x10,       ///< function completed; message event occurred.
00177   osEventMail             =  0x20,       ///< function completed; mail event occurred.
00178   osEventTimeout          =  0x40,       ///< function completed; timeout occurred.
00179   osErrorParameter        =  0x80,       ///< parameter error: a mandatory parameter was missing or specified an incorrect object.
00180   osErrorResource         =  0x81,       ///< resource not available: a specified resource was not available.
00181   osErrorTimeoutResource  =  0xC1,       ///< resource not available within given time: a specified resource was not available within the timeout period.
00182   osErrorISR              =  0x82,       ///< not allowed in ISR context: the function cannot be called from interrupt service routines.
00183   osErrorISRRecursive     =  0x83,       ///< function called multiple times from ISR with same object.
00184   osErrorPriority         =  0x84,       ///< system cannot determine priority or thread has illegal priority.
00185   osErrorNoMemory         =  0x85,       ///< system is out of memory: it was impossible to allocate or reserve memory for the operation.
00186   osErrorValue            =  0x86,       ///< value of a parameter is out of range.
00187   osErrorOS               =  0xFF,       ///< unspecified RTOS error: run-time error but no other error message fits.
00188   os_status_reserved      =  0x7FFFFFFF  ///< prevent from enum down-size compiler optimization.
00189 } osStatus; 
00190 
00191 
00192 /// Timer type value for the timer definition.
00193 /// \note MUST REMAIN UNCHANGED: \b os_timer_type shall be consistent in every CMSIS-RTOS.
00194 typedef enum  {
00195   osTimerOnce             =     0,       ///< one-shot timer 
00196   osTimerPeriodic         =     1        ///< repeating timer 
00197 } os_timer_type; 
00198 
00199 /// Entry point of a thread.
00200 /// \note MUST REMAIN UNCHANGED: \b os_pthread shall be consistent in every CMSIS-RTOS.
00201 typedef void (*os_pthread) (void const *argument); 
00202 
00203 /// Entry point of a timer call back function.
00204 /// \note MUST REMAIN UNCHANGED: \b os_ptimer shall be consistent in every CMSIS-RTOS.
00205 typedef void (*os_ptimer) (void const *argument); 
00206 
00207 // >>> the following data type definitions may shall adapted towards a specific RTOS
00208 
00209 /// Thread ID identifies the thread (pointer to a thread control block).
00210 /// \note CAN BE CHANGED: \b os_thread_cb is implementation specific in every CMSIS-RTOS.
00211 typedef struct os_thread_cb *osThreadId;
00212 
00213 /// Timer ID identifies the timer (pointer to a timer control block).
00214 /// \note CAN BE CHANGED: \b os_timer_cb is implementation specific in every CMSIS-RTOS.
00215 typedef struct os_timer_cb *osTimerId;
00216 
00217 /// Mutex ID identifies the mutex (pointer to a mutex control block).
00218 /// \note CAN BE CHANGED: \b os_mutex_cb is implementation specific in every CMSIS-RTOS.
00219 typedef struct os_mutex_cb *osMutexId;
00220 
00221 /// Semaphore ID identifies the semaphore (pointer to a semaphore control block).
00222 /// \note CAN BE CHANGED: \b os_semaphore_cb is implementation specific in every CMSIS-RTOS.
00223 typedef struct os_semaphore_cb *osSemaphoreId;
00224 
00225 /// Pool ID identifies the memory pool (pointer to a memory pool control block).
00226 /// \note CAN BE CHANGED: \b os_pool_cb is implementation specific in every CMSIS-RTOS.
00227 typedef struct os_pool_cb *osPoolId;
00228 
00229 /// Message ID identifies the message queue (pointer to a message queue control block).
00230 /// \note CAN BE CHANGED: \b os_messageQ_cb is implementation specific in every CMSIS-RTOS.
00231 typedef struct os_messageQ_cb *osMessageQId;
00232 
00233 /// Mail ID identifies the mail queue (pointer to a mail queue control block).
00234 /// \note CAN BE CHANGED: \b os_mailQ_cb is implementation specific in every CMSIS-RTOS.
00235 typedef struct os_mailQ_cb *osMailQId;
00236 
00237 
00238 /// Thread Definition structure contains startup information of a thread.
00239 /// \note CAN BE CHANGED: \b os_thread_def is implementation specific in every CMSIS-RTOS.
00240 typedef struct os_thread_def  {
00241   os_pthread               pthread;      ///< start address of thread function
00242   osPriority             tpriority;      ///< initial thread priority
00243   uint32_t               stacksize;      ///< stack size requirements in bytes
00244   unsigned char         *stack_pointer;  ///< pointer to the stack memory block
00245   struct OS_TCB          tcb;
00246 } osThreadDef_t;
00247 
00248 /// Timer Definition structure contains timer parameters.
00249 /// \note CAN BE CHANGED: \b os_timer_def is implementation specific in every CMSIS-RTOS.
00250 typedef struct os_timer_def  {
00251   os_ptimer                 ptimer;    ///< start address of a timer function
00252   void                      *timer;    ///< pointer to internal data
00253 } osTimerDef_t;
00254 
00255 /// Mutex Definition structure contains setup information for a mutex.
00256 /// \note CAN BE CHANGED: \b os_mutex_def is implementation specific in every CMSIS-RTOS.
00257 typedef struct os_mutex_def  {
00258   void                      *mutex;    ///< pointer to internal data
00259 } osMutexDef_t;
00260 
00261 /// Semaphore Definition structure contains setup information for a semaphore.
00262 /// \note CAN BE CHANGED: \b os_semaphore_def is implementation specific in every CMSIS-RTOS.
00263 typedef struct os_semaphore_def  {
00264   void                  *semaphore;    ///< pointer to internal data
00265 } osSemaphoreDef_t;
00266 
00267 /// Definition structure for memory block allocation.
00268 /// \note CAN BE CHANGED: \b os_pool_def is implementation specific in every CMSIS-RTOS.
00269 typedef struct os_pool_def  {
00270   uint32_t                 pool_sz;    ///< number of items (elements) in the pool
00271   uint32_t                 item_sz;    ///< size of an item 
00272   void                       *pool;    ///< pointer to memory for pool
00273 } osPoolDef_t;
00274 
00275 /// Definition structure for message queue.
00276 /// \note CAN BE CHANGED: \b os_messageQ_def is implementation specific in every CMSIS-RTOS.
00277 typedef struct os_messageQ_def  {
00278   uint32_t                queue_sz;    ///< number of elements in the queue
00279   void                       *pool;    ///< memory array for messages
00280 } osMessageQDef_t;
00281 
00282 /// Definition structure for mail queue.
00283 /// \note CAN BE CHANGED: \b os_mailQ_def is implementation specific in every CMSIS-RTOS.
00284 typedef struct os_mailQ_def  {
00285   uint32_t                queue_sz;    ///< number of elements in the queue
00286   uint32_t                 item_sz;    ///< size of an item 
00287   void                       *pool;    ///< memory array for mail
00288 } osMailQDef_t;
00289 
00290 /// Event structure contains detailed information about an event. 
00291 /// \note MUST REMAIN UNCHANGED: \b os_event shall be consistent in every CMSIS-RTOS. 
00292 ///       However the struct may be extended at the end.
00293 typedef struct  {
00294   osStatus                 status;     ///< status code: event or error information
00295   union  {
00296     uint32_t                    v;     ///< message as 32-bit value 
00297     void                       *p;     ///< message or mail as void pointer
00298     int32_t               signals;     ///< signal flags 
00299   } value;                             ///< event value
00300   union  {
00301     osMailQId             mail_id;     ///< mail id obtained by \ref osMailCreate 
00302     osMessageQId       message_id;     ///< message id obtained by \ref osMessageCreate 
00303   } def;                               ///< event definition
00304 } osEvent;
00305 
00306 
00307 //  ==== Kernel Control Functions ====
00308 
00309 /// Initialize the RTOS Kernel for creating objects.
00310 /// \return status code that indicates the execution status of the function.
00311 /// \note MUST REMAIN UNCHANGED: \b osKernelInitialize shall be consistent in every CMSIS-RTOS. 
00312 osStatus osKernelInitialize (void);
00313 
00314 /// Start the RTOS Kernel.
00315 /// \return status code that indicates the execution status of the function.
00316 /// \note MUST REMAIN UNCHANGED: \b osKernelStart shall be consistent in every CMSIS-RTOS. 
00317 osStatus osKernelStart (void);
00318 
00319 /// Check if the RTOS kernel is already started.
00320 /// \note MUST REMAIN UNCHANGED: \b osKernelRunning shall be consistent in every CMSIS-RTOS. 
00321 /// \return 0 RTOS is not started, 1 RTOS is started.
00322 int32_t osKernelRunning(void);
00323 
00324 
00325 //  ==== Thread Management ====
00326 
00327 /// Create a Thread Definition with function, priority, and stack requirements.
00328 /// \param         name         name of the thread function.
00329 /// \param         priority     initial priority of the thread function.
00330 /// \param         stacksz      stack size (in bytes) requirements for the thread function.
00331 /// \note CAN BE CHANGED: The parameters to \b osThreadDef shall be consistent but the 
00332 ///       macro body is implementation specific in every CMSIS-RTOS.
00333 #if defined (osObjectsExternal)  // object is external
00334 #define osThreadDef(name, priority, stacksz)  \
00335 extern osThreadDef_t os_thread_def_##name
00336 #else                            // define the object
00337 #define osThreadDef(name, priority, stacksz)  \
00338 unsigned char os_thread_def_stack_##name [stacksz]; \
00339 osThreadDef_t os_thread_def_##name = \
00340 { (name), (priority), (stacksz), (os_thread_def_stack_##name)}
00341 #endif
00342 
00343 /// Access a Thread definition.
00344 /// \param         name          name of the thread definition object.
00345 /// \note CAN BE CHANGED: The parameter to \b osThread shall be consistent but the 
00346 ///       macro body is implementation specific in every CMSIS-RTOS.
00347 #define osThread(name)  \
00348 &os_thread_def_##name
00349 
00350 /// Create a thread and add it to Active Threads and set it to state READY.
00351 /// \param[in]     thread_def    thread definition referenced with \ref osThread.
00352 /// \param[in]     argument      pointer that is passed to the thread function as start argument.
00353 /// \return thread ID for reference by other functions or NULL in case of error.
00354 /// \note MUST REMAIN UNCHANGED: \b osThreadCreate shall be consistent in every CMSIS-RTOS.
00355 osThreadId osThreadCreate (osThreadDef_t *thread_def, void *argument);
00356 
00357 /// Return the thread ID of the current running thread.
00358 /// \return thread ID for reference by other functions or NULL in case of error.
00359 /// \note MUST REMAIN UNCHANGED: \b osThreadGetId shall be consistent in every CMSIS-RTOS.
00360 osThreadId osThreadGetId (void);
00361 
00362 /// Terminate execution of a thread and remove it from Active Threads.
00363 /// \param[in]     thread_id   thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
00364 /// \return status code that indicates the execution status of the function.
00365 /// \note MUST REMAIN UNCHANGED: \b osThreadTerminate shall be consistent in every CMSIS-RTOS.
00366 osStatus osThreadTerminate (osThreadId thread_id);
00367 
00368 /// Pass control to next thread that is in state \b READY.
00369 /// \return status code that indicates the execution status of the function.
00370 /// \note MUST REMAIN UNCHANGED: \b osThreadYield shall be consistent in every CMSIS-RTOS.
00371 osStatus osThreadYield (void);
00372 
00373 /// Change priority of an active thread.  
00374 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
00375 /// \param[in]     priority      new priority value for the thread function.
00376 /// \return status code that indicates the execution status of the function.
00377 /// \note MUST REMAIN UNCHANGED: \b osThreadSetPriority shall be consistent in every CMSIS-RTOS.
00378 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority);
00379 
00380 /// Get current priority of an active thread.
00381 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
00382 /// \return current priority value of the thread function.
00383 /// \note MUST REMAIN UNCHANGED: \b osThreadGetPriority shall be consistent in every CMSIS-RTOS.
00384 osPriority osThreadGetPriority (osThreadId thread_id);
00385 
00386 
00387 //  ==== Generic Wait Functions ====
00388 
00389 /// Wait for Timeout (Time Delay).
00390 /// \param[in]     millisec      time delay value 
00391 /// \return status code that indicates the execution status of the function.
00392 osStatus osDelay (uint32_t millisec);
00393 
00394 #if (defined (osFeature_Wait)  &&  (osFeature_Wait != 0))     // Generic Wait available
00395 
00396 /// Wait for Signal, Message, Mail, or Timeout.
00397 /// \param[in] millisec          timeout value or 0 in case of no time-out
00398 /// \return event that contains signal, message, or mail information or error code.
00399 /// \note MUST REMAIN UNCHANGED: \b osWait shall be consistent in every CMSIS-RTOS.
00400 os_InRegs osEvent osWait (uint32_t millisec);
00401 
00402 #endif  // Generic Wait available
00403 
00404 
00405 //  ==== Timer Management Functions ====
00406 /// Define a Timer object.
00407 /// \param         name          name of the timer object.
00408 /// \param         function      name of the timer call back function.
00409 /// \note CAN BE CHANGED: The parameter to \b osTimerDef shall be consistent but the 
00410 ///       macro body is implementation specific in every CMSIS-RTOS.
00411 #if defined (osObjectsExternal)  // object is external
00412 #define osTimerDef(name, function)  \
00413 extern osTimerDef_t os_timer_def_##name
00414 #else                            // define the object
00415 #define osTimerDef(name, function)  \
00416 uint32_t os_timer_cb_##name[5]; \
00417 osTimerDef_t os_timer_def_##name = \
00418 { (function), (os_timer_cb_##name) }
00419 #endif
00420 
00421 /// Access a Timer definition.
00422 /// \param         name          name of the timer object.
00423 /// \note CAN BE CHANGED: The parameter to \b osTimer shall be consistent but the 
00424 ///       macro body is implementation specific in every CMSIS-RTOS.
00425 #define osTimer(name) \
00426 &os_timer_def_##name
00427 
00428 /// Create a timer.
00429 /// \param[in]     timer_def     timer object referenced with \ref osTimer.
00430 /// \param[in]     type          osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
00431 /// \param[in]     argument      argument to the timer call back function.
00432 /// \return timer ID for reference by other functions or NULL in case of error.
00433 /// \note MUST REMAIN UNCHANGED: \b osTimerCreate shall be consistent in every CMSIS-RTOS.
00434 osTimerId osTimerCreate (osTimerDef_t *timer_def, os_timer_type type, void *argument);
00435 
00436 /// Start or restart a timer.
00437 /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
00438 /// \param[in]     millisec      time delay value of the timer.
00439 /// \return status code that indicates the execution status of the function.
00440 /// \note MUST REMAIN UNCHANGED: \b osTimerStart shall be consistent in every CMSIS-RTOS.
00441 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec);
00442 
00443 /// Stop the timer.
00444 /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
00445 /// \return status code that indicates the execution status of the function.
00446 /// \note MUST REMAIN UNCHANGED: \b osTimerStop shall be consistent in every CMSIS-RTOS.
00447 osStatus osTimerStop (osTimerId timer_id);
00448 
00449 /// Delete a timer that was created by \ref osTimerCreate.
00450 /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
00451 /// \return status code that indicates the execution status of the function.
00452 /// \note MUST REMAIN UNCHANGED: \b osTimerDelete shall be consistent in every CMSIS-RTOS.
00453 osStatus osTimerDelete (osTimerId timer_id);
00454 
00455 
00456 //  ==== Signal Management ====
00457 
00458 /// Set the specified Signal Flags of an active thread.
00459 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
00460 /// \param[in]     signals       specifies the signal flags of the thread that should be set.
00461 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
00462 /// \note MUST REMAIN UNCHANGED: \b osSignalSet shall be consistent in every CMSIS-RTOS.
00463 int32_t osSignalSet (osThreadId thread_id, int32_t signals);
00464 
00465 /// Clear the specified Signal Flags of an active thread.
00466 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
00467 /// \param[in]     signals       specifies the signal flags of the thread that shall be cleared.
00468 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
00469 /// \note MUST REMAIN UNCHANGED: \b osSignalClear shall be consistent in every CMSIS-RTOS.
00470 int32_t osSignalClear (osThreadId thread_id, int32_t signals);
00471 
00472 /// Get Signal Flags status of an active thread.
00473 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
00474 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
00475 /// \note MUST REMAIN UNCHANGED: \b osSignalGet shall be consistent in every CMSIS-RTOS.
00476 int32_t osSignalGet (osThreadId thread_id);
00477 
00478 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread.
00479 /// \param[in]     signals       wait until all specified signal flags set or 0 for any single signal flag.
00480 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
00481 /// \return event flag information or error code.
00482 /// \note MUST REMAIN UNCHANGED: \b osSignalWait shall be consistent in every CMSIS-RTOS.
00483 os_InRegs osEvent osSignalWait (int32_t signals, uint32_t millisec);
00484 
00485 
00486 //  ==== Mutex Management ====
00487 
00488 /// Define a Mutex.
00489 /// \param         name          name of the mutex object.
00490 /// \note CAN BE CHANGED: The parameter to \b osMutexDef shall be consistent but the 
00491 ///       macro body is implementation specific in every CMSIS-RTOS.
00492 #if defined (osObjectsExternal)  // object is external
00493 #define osMutexDef(name)  \
00494 extern osMutexDef_t os_mutex_def_##name
00495 #else                            // define the object
00496 #define osMutexDef(name)  \
00497 uint32_t os_mutex_cb_##name[3]; \
00498 osMutexDef_t os_mutex_def_##name = { (os_mutex_cb_##name) }
00499 #endif
00500 
00501 /// Access a Mutex definition.
00502 /// \param         name          name of the mutex object.
00503 /// \note CAN BE CHANGED: The parameter to \b osMutex shall be consistent but the 
00504 ///       macro body is implementation specific in every CMSIS-RTOS.
00505 #define osMutex(name)  \
00506 &os_mutex_def_##name
00507 
00508 /// Create and Initialize a Mutex object.
00509 /// \param[in]     mutex_def     mutex definition referenced with \ref osMutex.
00510 /// \return mutex ID for reference by other functions or NULL in case of error.
00511 /// \note MUST REMAIN UNCHANGED: \b osMutexCreate shall be consistent in every CMSIS-RTOS.
00512 osMutexId osMutexCreate (osMutexDef_t *mutex_def);
00513 
00514 /// Wait until a Mutex becomes available.
00515 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
00516 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
00517 /// \return status code that indicates the execution status of the function.
00518 /// \note MUST REMAIN UNCHANGED: \b osMutexWait shall be consistent in every CMSIS-RTOS.
00519 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec);
00520 
00521 /// Release a Mutex that was obtained by \ref osMutexWait.
00522 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
00523 /// \return status code that indicates the execution status of the function.
00524 /// \note MUST REMAIN UNCHANGED: \b osMutexRelease shall be consistent in every CMSIS-RTOS.
00525 osStatus osMutexRelease (osMutexId mutex_id);
00526 
00527 /// Delete a Mutex that was created by \ref osMutexCreate.
00528 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
00529 /// \return status code that indicates the execution status of the function.
00530 /// \note MUST REMAIN UNCHANGED: \b osMutexDelete shall be consistent in every CMSIS-RTOS.
00531 osStatus osMutexDelete (osMutexId mutex_id);
00532 
00533 
00534 //  ==== Semaphore Management Functions ====
00535 
00536 #if (defined (osFeature_Semaphore)  &&  (osFeature_Semaphore != 0))     // Semaphore available
00537 
00538 /// Define a Semaphore object.
00539 /// \param         name          name of the semaphore object.
00540 /// \note CAN BE CHANGED: The parameter to \b osSemaphoreDef shall be consistent but the 
00541 ///       macro body is implementation specific in every CMSIS-RTOS.
00542 #if defined (osObjectsExternal)  // object is external
00543 #define osSemaphoreDef(name)  \
00544 extern osSemaphoreDef_t os_semaphore_def_##name
00545 #else                            // define the object
00546 #define osSemaphoreDef(name)  \
00547 uint32_t os_semaphore_cb_##name[2]; \
00548 osSemaphoreDef_t os_semaphore_def_##name = { (os_semaphore_cb_##name) }
00549 #endif
00550 
00551 /// Access a Semaphore definition.
00552 /// \param         name          name of the semaphore object.
00553 /// \note CAN BE CHANGED: The parameter to \b osSemaphore shall be consistent but the 
00554 ///       macro body is implementation specific in every CMSIS-RTOS.
00555 #define osSemaphore(name)  \
00556 &os_semaphore_def_##name
00557 
00558 /// Create and Initialize a Semaphore object used for managing resources.
00559 /// \param[in]     semaphore_def semaphore definition referenced with \ref osSemaphore.
00560 /// \param[in]     count         number of available resources.
00561 /// \return semaphore ID for reference by other functions or NULL in case of error.
00562 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreCreate shall be consistent in every CMSIS-RTOS.
00563 osSemaphoreId osSemaphoreCreate (osSemaphoreDef_t *semaphore_def, int32_t count);
00564 
00565 /// Wait until a Semaphore token becomes available.
00566 /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
00567 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
00568 /// \return number of available tokens, or -1 in case of incorrect parameters.
00569 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreWait shall be consistent in every CMSIS-RTOS.
00570 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec);
00571 
00572 /// Release a Semaphore token.
00573 /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
00574 /// \return status code that indicates the execution status of the function.
00575 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreRelease shall be consistent in every CMSIS-RTOS.
00576 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id);
00577 
00578 /// Delete a Semaphore that was created by \ref osSemaphoreCreate.
00579 /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
00580 /// \return status code that indicates the execution status of the function.
00581 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreDelete shall be consistent in every CMSIS-RTOS.
00582 osStatus osSemaphoreDelete (osSemaphoreId semaphore_id);
00583 
00584 #endif     // Semaphore available
00585 
00586  
00587 //  ==== Memory Pool Management Functions ====
00588 
00589 #if (defined (osFeature_Pool)  &&  (osFeature_Pool != 0))  // Memory Pool Management available
00590 
00591 /// \brief Define a Memory Pool.
00592 /// \param         name          name of the memory pool.
00593 /// \param         no            maximum number of blocks (objects) in the memory pool.
00594 /// \param         type          data type of a single block (object).
00595 /// \note CAN BE CHANGED: The parameter to \b osPoolDef shall be consistent but the 
00596 ///       macro body is implementation specific in every CMSIS-RTOS.
00597 #if defined (osObjectsExternal)  // object is external
00598 #define osPoolDef(name, no, type)   \
00599 extern osPoolDef_t os_pool_def_##name
00600 #else                            // define the object
00601 #define osPoolDef(name, no, type)   \
00602 uint32_t os_pool_m_##name[3+((sizeof(type)+3)/4)*(no)]; \
00603 osPoolDef_t os_pool_def_##name = \
00604 { (no), sizeof(type), (os_pool_m_##name) }
00605 #endif
00606 
00607 /// \brief Access a Memory Pool definition.
00608 /// \param         name          name of the memory pool
00609 /// \note CAN BE CHANGED: The parameter to \b osPool shall be consistent but the 
00610 ///       macro body is implementation specific in every CMSIS-RTOS.
00611 #define osPool(name) \
00612 &os_pool_def_##name
00613 
00614 /// Create and Initialize a memory pool.
00615 /// \param[in]     pool_def      memory pool definition referenced with \ref osPool.
00616 /// \return memory pool ID for reference by other functions or NULL in case of error.
00617 /// \note MUST REMAIN UNCHANGED: \b osPoolCreate shall be consistent in every CMSIS-RTOS.
00618 osPoolId osPoolCreate (osPoolDef_t *pool_def);
00619 
00620 /// Allocate a memory block from a memory pool.
00621 /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
00622 /// \return address of the allocated memory block or NULL in case of no memory available.
00623 /// \note MUST REMAIN UNCHANGED: \b osPoolAlloc shall be consistent in every CMSIS-RTOS.
00624 void *osPoolAlloc (osPoolId pool_id);
00625 
00626 /// Allocate a memory block from a memory pool and set memory block to zero.
00627 /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
00628 /// \return address of the allocated memory block or NULL in case of no memory available.
00629 /// \note MUST REMAIN UNCHANGED: \b osPoolCAlloc shall be consistent in every CMSIS-RTOS.
00630 void *osPoolCAlloc (osPoolId pool_id);
00631 
00632 /// Return an allocated memory block back to a specific memory pool.
00633 /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
00634 /// \param[in]     block         address of the allocated memory block that is returned to the memory pool.
00635 /// \return status code that indicates the execution status of the function.
00636 /// \note MUST REMAIN UNCHANGED: \b osPoolFree shall be consistent in every CMSIS-RTOS.
00637 osStatus osPoolFree (osPoolId pool_id, void *block);
00638 
00639 #endif   // Memory Pool Management available
00640 
00641 
00642 //  ==== Message Queue Management Functions ====
00643 
00644 #if (defined (osFeature_MessageQ)  &&  (osFeature_MessageQ != 0))     // Message Queues available
00645 
00646 /// \brief Create a Message Queue Definition.
00647 /// \param         name          name of the queue.
00648 /// \param         queue_sz      maximum number of messages in the queue.
00649 /// \param         type          data type of a single message element (for debugger).
00650 /// \note CAN BE CHANGED: The parameter to \b osMessageQDef shall be consistent but the 
00651 ///       macro body is implementation specific in every CMSIS-RTOS.
00652 #if defined (osObjectsExternal)  // object is external
00653 #define osMessageQDef(name, queue_sz, type)   \
00654 extern osMessageQDef_t os_messageQ_def_##name
00655 #else                            // define the object
00656 #define osMessageQDef(name, queue_sz, type)   \
00657 uint32_t os_messageQ_q_##name[4+(queue_sz)]; \
00658 osMessageQDef_t os_messageQ_def_##name = \
00659 { (queue_sz), (os_messageQ_q_##name) }
00660 #endif
00661 
00662 /// \brief Access a Message Queue Definition.
00663 /// \param         name          name of the queue
00664 /// \note CAN BE CHANGED: The parameter to \b osMessageQ shall be consistent but the 
00665 ///       macro body is implementation specific in every CMSIS-RTOS.
00666 #define osMessageQ(name) \
00667 &os_messageQ_def_##name
00668 
00669 /// Create and Initialize a Message Queue.
00670 /// \param[in]     queue_def     queue definition referenced with \ref osMessageQ.
00671 /// \param[in]     thread_id     thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
00672 /// \return message queue ID for reference by other functions or NULL in case of error.
00673 /// \note MUST REMAIN UNCHANGED: \b osMessageCreate shall be consistent in every CMSIS-RTOS.
00674 osMessageQId osMessageCreate (osMessageQDef_t *queue_def, osThreadId thread_id);
00675 
00676 /// Put a Message to a Queue.
00677 /// \param[in]     queue_id      message queue ID obtained with \ref osMessageCreate.
00678 /// \param[in]     info          message information.
00679 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
00680 /// \return status code that indicates the execution status of the function.
00681 /// \note MUST REMAIN UNCHANGED: \b osMessagePut shall be consistent in every CMSIS-RTOS.
00682 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec);
00683 
00684 /// Get a Message or Wait for a Message from a Queue.
00685 /// \param[in]     queue_id      message queue ID obtained with \ref osMessageCreate.
00686 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
00687 /// \return event information that includes status code.
00688 /// \note MUST REMAIN UNCHANGED: \b osMessageGet shall be consistent in every CMSIS-RTOS.
00689 os_InRegs osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec);
00690 
00691 #endif     // Message Queues available
00692 
00693 
00694 //  ==== Mail Queue Management Functions ====
00695 
00696 #if (defined (osFeature_MailQ)  &&  (osFeature_MailQ != 0))     // Mail Queues available
00697 
00698 /// \brief Create a Mail Queue Definition.
00699 /// \param         name          name of the queue
00700 /// \param         queue_sz      maximum number of messages in queue
00701 /// \param         type          data type of a single message element
00702 /// \note CAN BE CHANGED: The parameter to \b osMailQDef shall be consistent but the 
00703 ///       macro body is implementation specific in every CMSIS-RTOS.
00704 #if defined (osObjectsExternal)  // object is external
00705 #define osMailQDef(name, queue_sz, type) \
00706 extern osMailQDef_t os_mailQ_def_##name
00707 #else                            // define the object
00708 #define osMailQDef(name, queue_sz, type) \
00709 uint32_t os_mailQ_q_##name[4+(queue_sz)]; \
00710 uint32_t os_mailQ_m_##name[3+((sizeof(type)+3)/4)*(queue_sz)]; \
00711 void *   os_mailQ_p_##name[2] = { (os_mailQ_q_##name), os_mailQ_m_##name }; \
00712 osMailQDef_t os_mailQ_def_##name =  \
00713 { (queue_sz), sizeof(type), (os_mailQ_p_##name) }
00714 #endif
00715      
00716 /// \brief Access a Mail Queue Definition.
00717 /// \param         name          name of the queue
00718 /// \note CAN BE CHANGED: The parameter to \b osMailQ shall be consistent but the 
00719 ///       macro body is implementation specific in every CMSIS-RTOS.
00720 #define osMailQ(name)  \
00721 &os_mailQ_def_##name
00722 
00723 /// Create and Initialize mail queue.
00724 /// \param[in]     queue_def     reference to the mail queue definition obtain with \ref osMailQ
00725 /// \param[in]     thread_id     thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
00726 /// \return mail queue ID for reference by other functions or NULL in case of error.
00727 /// \note MUST REMAIN UNCHANGED: \b osMailCreate shall be consistent in every CMSIS-RTOS.
00728 osMailQId osMailCreate (osMailQDef_t *queue_def, osThreadId thread_id);
00729 
00730 /// Allocate a memory block from a mail.
00731 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
00732 /// \param[in]     millisec      timeout value or 0 in case of no time-out
00733 /// \return pointer to memory block that can be filled with mail or NULL in case of error.
00734 /// \note MUST REMAIN UNCHANGED: \b osMailAlloc shall be consistent in every CMSIS-RTOS.
00735 void *osMailAlloc (osMailQId queue_id, uint32_t millisec);
00736 
00737 /// Allocate a memory block from a mail and set memory block to zero.
00738 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
00739 /// \param[in]     millisec      timeout value or 0 in case of no time-out
00740 /// \return pointer to memory block that can be filled with mail or NULL in case of error.
00741 /// \note MUST REMAIN UNCHANGED: \b osMailCAlloc shall be consistent in every CMSIS-RTOS.
00742 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec);
00743 
00744 /// Put a mail to a queue.
00745 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
00746 /// \param[in]     mail          memory block previously allocated with \ref osMailAlloc or \ref osMailCAlloc.
00747 /// \return status code that indicates the execution status of the function.
00748 /// \note MUST REMAIN UNCHANGED: \b osMailPut shall be consistent in every CMSIS-RTOS.
00749 osStatus osMailPut (osMailQId queue_id, void *mail);
00750 
00751 /// Get a mail from a queue.
00752 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
00753 /// \param[in]     millisec      timeout value or 0 in case of no time-out
00754 /// \return event that contains mail information or error code.
00755 /// \note MUST REMAIN UNCHANGED: \b osMailGet shall be consistent in every CMSIS-RTOS.
00756 os_InRegs osEvent osMailGet (osMailQId queue_id, uint32_t millisec);
00757 
00758 /// Free a memory block from a mail.
00759 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
00760 /// \param[in]     mail          pointer to the memory block that was obtained with \ref osMailGet.
00761 /// \return status code that indicates the execution status of the function.
00762 /// \note MUST REMAIN UNCHANGED: \b osMailFree shall be consistent in every CMSIS-RTOS.
00763 osStatus osMailFree (osMailQId queue_id, void *mail);
00764                             
00765 #endif  // Mail Queues available
00766 
00767 
00768 #ifdef  __cplusplus
00769 }
00770 #endif
00771 
00772 #endif  // _CMSIS_OS_H