tool/mbed/mbed-sdk/libraries/rtos/rtx/TARGET_CORTEX_M/cmsis_os.h

   1 /* ----------------------------------------------------------------------
   2  * Copyright (C) 2012 ARM Limited. All rights reserved.
   3  *
   4  * $Date:        5. June 2012
   5  * $Revision:    V1.01
   6  *
   7  * Project:      CMSIS-RTOS API
   8  * Title:        cmsis_os.h RTX header file
   9  *
  10  * Version 0.02
  11  *    Initial Proposal Phase
  12  * Version 0.03
  13  *    osKernelStart added, optional feature: main started as thread
  14  *    osSemaphores have standard behavior
  15  *    osTimerCreate does not start the timer, added osTimerStart
  16  *    osThreadPass is renamed to osThreadYield
  17  * Version 1.01
  18  *    Support for C++ interface
  19  *     - const attribute removed from the osXxxxDef_t typedef's
  20  *     - const attribute added to the osXxxxDef macros
  21  *    Added: osTimerDelete, osMutexDelete, osSemaphoreDelete
  22  *    Added: osKernelInitialize
  23  * -------------------------------------------------------------------- */
  24
  25 /**
  26 \page cmsis_os_h Header File Template: cmsis_os.h
  27
  28 The file \b cmsis_os.h is a template header file for a CMSIS-RTOS compliant Real-Time Operating System (RTOS).
  29 Each RTOS that is compliant with CMSIS-RTOS shall provide a specific \b cmsis_os.h header file that represents
  30 its implementation.
  31
  32 The file cmsis_os.h contains:
  33  - CMSIS-RTOS API function definitions
  34  - struct definitions for parameters and return types
  35  - status and priority values used by CMSIS-RTOS API functions
  36  - macros for defining threads and other kernel objects
  37
  38
  39 <b>Name conventions and header file modifications</b>
  40
  41 All definitions are prefixed with \b os to give an unique name space for CMSIS-RTOS functions.
  42 Definitions that are prefixed \b os_ are not used in the application code but local to this header file.
  43 All definitions and functions that belong to a module are grouped and have a common prefix, i.e. \b osThread.
  44
  45 Definitions that are marked with <b>CAN BE CHANGED</b> can be adapted towards the needs of the actual CMSIS-RTOS implementation.
  46 These definitions can be specific to the underlying RTOS kernel.
  47
  48 Definitions that are marked with <b>MUST REMAIN UNCHANGED</b> cannot be altered. Otherwise the CMSIS-RTOS implementation is no longer
  49 compliant to the standard. Note that some functions are optional and need not to be provided by every CMSIS-RTOS implementation.
  50
  51
  52 <b>Function calls from interrupt service routines</b>
  53
  54 The following CMSIS-RTOS functions can be called from threads and interrupt service routines (ISR):
  55   - \ref osSignalSet
  56   - \ref osSemaphoreRelease
  57   - \ref osPoolAlloc, \ref osPoolCAlloc, \ref osPoolFree
  58   - \ref osMessagePut, \ref osMessageGet
  59   - \ref osMailAlloc, \ref osMailCAlloc, \ref osMailGet, \ref osMailPut, \ref osMailFree
  60
  61 Functions that cannot be called from an ISR are verifying the interrupt status and return in case that they are called
  62 from an ISR context the status code \b osErrorISR. In some implementations this condition might be caught using the HARD FAULT vector.
  63
  64 Some CMSIS-RTOS implementations support CMSIS-RTOS function calls from multiple ISR at the same time.
  65 If this is impossible, the CMSIS-RTOS rejects calls by nested ISR functions with the status code \b osErrorISRRecursive.
  66
  67
  68 <b>Define and reference object definitions</b>
  69
  70 With <b>\#define osObjectsExternal</b> objects are defined as external symbols. This allows to create a consistent header file
  71 that is used throughout a project as shown below:
  72
  73 <i>Header File</i>
  74 \code
  75 #include <cmsis_os.h>                                         // CMSIS RTOS header file
  76
  77 // Thread definition
  78 extern void thread_sample (void const *argument);             // function prototype
  79 osThreadDef (thread_sample, osPriorityBelowNormal, 1, 100);
  80
  81 // Pool definition
  82 osPoolDef(MyPool, 10, long);
  83 \endcode
  84
  85
  86 This header file defines all objects when included in a C/C++ source file. When <b>\#define osObjectsExternal</b> is
  87 present before the header file, the objects are defined as external symbols. A single consistent header file can therefore be
  88 used throughout the whole project.
  89
  90 <i>Example</i>
  91 \code
  92 #include "osObjects.h"     // Definition of the CMSIS-RTOS objects
  93 \endcode
  94
  95 \code
  96 #define osObjectExternal   // Objects will be defined as external symbols
  97 #include "osObjects.h"     // Reference to the CMSIS-RTOS objects
  98 \endcode
  99
 100 */
 101
 102 #ifndef _CMSIS_OS_H
 103 #define _CMSIS_OS_H
 104
 105 /// \note MUST REMAIN UNCHANGED: \b osCMSIS identifies the CMSIS-RTOS API version.
 106 #define osCMSIS           0x10001      ///< API version (main [31:16] .sub [15:0])
 107
 108 /// \note CAN BE CHANGED: \b osCMSIS_KERNEL identifies the underlying RTOS kernel and version number.
 109 #define osCMSIS_RTX     ((4<<16)|61)   ///< RTOS identification and version (main [31:16] .sub [15:0])
 110
 111 /// \note MUST REMAIN UNCHANGED: \b osKernelSystemId shall be consistent in every CMSIS-RTOS.
 112 #define osKernelSystemId "RTX V4.61"   ///< RTOS identification string
 113
 114
 115 #define CMSIS_OS_RTX
 116
 117 // The stack space occupied is mainly dependent on the underling C standard library
 118 #if defined(TOOLCHAIN_GCC) || defined(TOOLCHAIN_ARM_STD) || defined(TOOLCHAIN_IAR)
 119 #    define WORDS_STACK_SIZE   512
 120 #elif defined(TOOLCHAIN_ARM_MICRO)
 121 #    define WORDS_STACK_SIZE   128
 122 #endif
 123
 124 #define DEFAULT_STACK_SIZE         (WORDS_STACK_SIZE*4)
 125
 126
 127 /// \note MUST REMAIN UNCHANGED: \b osFeature_xxx shall be consistent in every CMSIS-RTOS.
 128 #define osFeature_MainThread   1       ///< main thread      1=main can be thread, 0=not available
 129 #define osFeature_Pool         1       ///< Memory Pools:    1=available, 0=not available
 130 #define osFeature_MailQ        1       ///< Mail Queues:     1=available, 0=not available
 131 #define osFeature_MessageQ     1       ///< Message Queues:  1=available, 0=not available
 132 #define osFeature_Signals      16      ///< maximum number of Signal Flags available per thread
 133 #define osFeature_Semaphore    65535   ///< maximum count for \ref osSemaphoreCreate function
 134 #define osFeature_Wait         0       ///< osWait function: 1=available, 0=not available
 135
 136 #if defined (__CC_ARM)
 137 #define os_InRegs __value_in_regs      // Compiler specific: force struct in registers
 138 #elif defined (__ICCARM__)
 139 #define os_InRegs __value_in_regs      // Compiler specific: force struct in registers
 140 #else
 141 #define os_InRegs
 142 #endif
 143
 144 #include <stdint.h>
 145 #include <stddef.h>
 146
 147 #ifdef  __cplusplus
 148 extern "C"
 149 {
 150 #endif
 151
 152 #include "os_tcb.h"
 153
 154 // ==== Enumeration, structures, defines ====
 155
 156 /// Priority used for thread control.
 157 /// \note MUST REMAIN UNCHANGED: \b osPriority shall be consistent in every CMSIS-RTOS.
 158 typedef enum  {
 159   osPriorityIdle          = -3,          ///< priority: idle (lowest)
 160   osPriorityLow           = -2,          ///< priority: low
 161   osPriorityBelowNormal   = -1,          ///< priority: below normal
 162   osPriorityNormal        =  0,          ///< priority: normal (default)
 163   osPriorityAboveNormal   = +1,          ///< priority: above normal
 164   osPriorityHigh          = +2,          ///< priority: high
 165   osPriorityRealtime      = +3,          ///< priority: realtime (highest)
 166   osPriorityError         =  0x84        ///< system cannot determine priority or thread has illegal priority
 167 } osPriority;
 168
 169 /// Timeout value.
 170 /// \note MUST REMAIN UNCHANGED: \b osWaitForever shall be consistent in every CMSIS-RTOS.
 171 #define osWaitForever     0xFFFFFFFF     ///< wait forever timeout value
 172
 173 /// Status code values returned by CMSIS-RTOS functions.
 174 /// \note MUST REMAIN UNCHANGED: \b osStatus shall be consistent in every CMSIS-RTOS.
 175 typedef enum  {
 176   osOK                    =     0,       ///< function completed; no error or event occurred.
 177   osEventSignal           =  0x08,       ///< function completed; signal event occurred.
 178   osEventMessage          =  0x10,       ///< function completed; message event occurred.
 179   osEventMail             =  0x20,       ///< function completed; mail event occurred.
 180   osEventTimeout          =  0x40,       ///< function completed; timeout occurred.
 181   osErrorParameter        =  0x80,       ///< parameter error: a mandatory parameter was missing or specified an incorrect object.
 182   osErrorResource         =  0x81,       ///< resource not available: a specified resource was not available.
 183   osErrorTimeoutResource  =  0xC1,       ///< resource not available within given time: a specified resource was not available within the timeout period.
 184   osErrorISR              =  0x82,       ///< not allowed in ISR context: the function cannot be called from interrupt service routines.
 185   osErrorISRRecursive     =  0x83,       ///< function called multiple times from ISR with same object.
 186   osErrorPriority         =  0x84,       ///< system cannot determine priority or thread has illegal priority.
 187   osErrorNoMemory         =  0x85,       ///< system is out of memory: it was impossible to allocate or reserve memory for the operation.
 188   osErrorValue            =  0x86,       ///< value of a parameter is out of range.
 189   osErrorOS               =  0xFF,       ///< unspecified RTOS error: run-time error but no other error message fits.
 190   os_status_reserved      =  0x7FFFFFFF  ///< prevent from enum down-size compiler optimization.
 191 } osStatus;
 192
 193
 194 /// Timer type value for the timer definition.
 195 /// \note MUST REMAIN UNCHANGED: \b os_timer_type shall be consistent in every CMSIS-RTOS.
 196 typedef enum  {
 197   osTimerOnce             =     0,       ///< one-shot timer
 198   osTimerPeriodic         =     1        ///< repeating timer
 199 } os_timer_type;
 200
 201 /// Entry point of a thread.
 202 /// \note MUST REMAIN UNCHANGED: \b os_pthread shall be consistent in every CMSIS-RTOS.
 203 typedef void (*os_pthread) (void const *argument);
 204
 205 /// Entry point of a timer call back function.
 206 /// \note MUST REMAIN UNCHANGED: \b os_ptimer shall be consistent in every CMSIS-RTOS.
 207 typedef void (*os_ptimer) (void const *argument);
 208
 209 // >>> the following data type definitions may shall adapted towards a specific RTOS
 210
 211 /// Thread ID identifies the thread (pointer to a thread control block).
 212 /// \note CAN BE CHANGED: \b os_thread_cb is implementation specific in every CMSIS-RTOS.
 213 typedef struct os_thread_cb *osThreadId;
 214
 215 /// Timer ID identifies the timer (pointer to a timer control block).
 216 /// \note CAN BE CHANGED: \b os_timer_cb is implementation specific in every CMSIS-RTOS.
 217 typedef struct os_timer_cb *osTimerId;
 218
 219 /// Mutex ID identifies the mutex (pointer to a mutex control block).
 220 /// \note CAN BE CHANGED: \b os_mutex_cb is implementation specific in every CMSIS-RTOS.
 221 typedef struct os_mutex_cb *osMutexId;
 222
 223 /// Semaphore ID identifies the semaphore (pointer to a semaphore control block).
 224 /// \note CAN BE CHANGED: \b os_semaphore_cb is implementation specific in every CMSIS-RTOS.
 225 typedef struct os_semaphore_cb *osSemaphoreId;
 226
 227 /// Pool ID identifies the memory pool (pointer to a memory pool control block).
 228 /// \note CAN BE CHANGED: \b os_pool_cb is implementation specific in every CMSIS-RTOS.
 229 typedef struct os_pool_cb *osPoolId;
 230
 231 /// Message ID identifies the message queue (pointer to a message queue control block).
 232 /// \note CAN BE CHANGED: \b os_messageQ_cb is implementation specific in every CMSIS-RTOS.
 233 typedef struct os_messageQ_cb *osMessageQId;
 234
 235 /// Mail ID identifies the mail queue (pointer to a mail queue control block).
 236 /// \note CAN BE CHANGED: \b os_mailQ_cb is implementation specific in every CMSIS-RTOS.
 237 typedef struct os_mailQ_cb *osMailQId;
 238
 239
 240 /// Thread Definition structure contains startup information of a thread.
 241 /// \note CAN BE CHANGED: \b os_thread_def is implementation specific in every CMSIS-RTOS.
 242 typedef struct os_thread_def  {
 243   os_pthread               pthread;      ///< start address of thread function
 244   osPriority             tpriority;      ///< initial thread priority
 245   uint32_t               stacksize;      ///< stack size requirements in bytes
 246   uint32_t               *stack_pointer;  ///< pointer to the stack memory block
 247   struct OS_TCB          tcb;
 248 } osThreadDef_t;
 249
 250 /// Timer Definition structure contains timer parameters.
 251 /// \note CAN BE CHANGED: \b os_timer_def is implementation specific in every CMSIS-RTOS.
 252 typedef struct os_timer_def  {
 253   os_ptimer                 ptimer;    ///< start address of a timer function
 254   void                      *timer;    ///< pointer to internal data
 255 } osTimerDef_t;
 256
 257 /// Mutex Definition structure contains setup information for a mutex.
 258 /// \note CAN BE CHANGED: \b os_mutex_def is implementation specific in every CMSIS-RTOS.
 259 typedef struct os_mutex_def  {
 260   void                      *mutex;    ///< pointer to internal data
 261 } osMutexDef_t;
 262
 263 /// Semaphore Definition structure contains setup information for a semaphore.
 264 /// \note CAN BE CHANGED: \b os_semaphore_def is implementation specific in every CMSIS-RTOS.
 265 typedef struct os_semaphore_def  {
 266   void                  *semaphore;    ///< pointer to internal data
 267 } osSemaphoreDef_t;
 268
 269 /// Definition structure for memory block allocation.
 270 /// \note CAN BE CHANGED: \b os_pool_def is implementation specific in every CMSIS-RTOS.
 271 typedef struct os_pool_def  {
 272   uint32_t                 pool_sz;    ///< number of items (elements) in the pool
 273   uint32_t                 item_sz;    ///< size of an item
 274   void                       *pool;    ///< pointer to memory for pool
 275 } osPoolDef_t;
 276
 277 /// Definition structure for message queue.
 278 /// \note CAN BE CHANGED: \b os_messageQ_def is implementation specific in every CMSIS-RTOS.
 279 typedef struct os_messageQ_def  {
 280   uint32_t                queue_sz;    ///< number of elements in the queue
 281   void                       *pool;    ///< memory array for messages
 282 } osMessageQDef_t;
 283
 284 /// Definition structure for mail queue.
 285 /// \note CAN BE CHANGED: \b os_mailQ_def is implementation specific in every CMSIS-RTOS.
 286 typedef struct os_mailQ_def  {
 287   uint32_t                queue_sz;    ///< number of elements in the queue
 288   uint32_t                 item_sz;    ///< size of an item
 289   void                       *pool;    ///< memory array for mail
 290 } osMailQDef_t;
 291
 292 /// Event structure contains detailed information about an event.
 293 /// \note MUST REMAIN UNCHANGED: \b os_event shall be consistent in every CMSIS-RTOS.
 294 ///       However the struct may be extended at the end.
 295 typedef struct  {
 296   osStatus                 status;     ///< status code: event or error information
 297   union  {
 298     uint32_t                    v;     ///< message as 32-bit value
 299     void                       *p;     ///< message or mail as void pointer
 300     int32_t               signals;     ///< signal flags
 301   } value;                             ///< event value
 302   union  {
 303     osMailQId             mail_id;     ///< mail id obtained by \ref osMailCreate
 304     osMessageQId       message_id;     ///< message id obtained by \ref osMessageCreate
 305   } def;                               ///< event definition
 306 } osEvent;
 307
 308
 309 //  ==== Kernel Control Functions ====
 310
 311 /// Initialize the RTOS Kernel for creating objects.
 312 /// \return status code that indicates the execution status of the function.
 313 /// \note MUST REMAIN UNCHANGED: \b osKernelInitialize shall be consistent in every CMSIS-RTOS.
 314 osStatus osKernelInitialize (void);
 315
 316 /// Start the RTOS Kernel.
 317 /// \return status code that indicates the execution status of the function.
 318 /// \note MUST REMAIN UNCHANGED: \b osKernelStart shall be consistent in every CMSIS-RTOS.
 319 osStatus osKernelStart (void);
 320
 321 /// Check if the RTOS kernel is already started.
 322 /// \note MUST REMAIN UNCHANGED: \b osKernelRunning shall be consistent in every CMSIS-RTOS.
 323 /// \return 0 RTOS is not started, 1 RTOS is started.
 324 int32_t osKernelRunning(void);
 325
 326
 327 //  ==== Thread Management ====
 328
 329 /// Create a Thread Definition with function, priority, and stack requirements.
 330 /// \param         name         name of the thread function.
 331 /// \param         priority     initial priority of the thread function.
 332 /// \param         stacksz      stack size (in bytes) requirements for the thread function.
 333 /// \note CAN BE CHANGED: The parameters to \b osThreadDef shall be consistent but the
 334 ///       macro body is implementation specific in every CMSIS-RTOS.
 335 #if defined (osObjectsExternal)  // object is external
 336 #define osThreadDef(name, priority, stacksz)  \
 337 extern osThreadDef_t os_thread_def_##name
 338 #else                            // define the object
 339 #define osThreadDef(name, priority, stacksz)  \
 340 uint32_t os_thread_def_stack_##name [stacksz / sizeof(uint32_t)]; \
 341 osThreadDef_t os_thread_def_##name = \
 342 { (name), (priority), (stacksz), (os_thread_def_stack_##name)}
 343 #endif
 344
 345 /// Access a Thread definition.
 346 /// \param         name          name of the thread definition object.
 347 /// \note CAN BE CHANGED: The parameter to \b osThread shall be consistent but the
 348 ///       macro body is implementation specific in every CMSIS-RTOS.
 349 #define osThread(name)  \
 350 &os_thread_def_##name
 351
 352 /// Create a thread and add it to Active Threads and set it to state READY.
 353 /// \param[in]     thread_def    thread definition referenced with \ref osThread.
 354 /// \param[in]     argument      pointer that is passed to the thread function as start argument.
 355 /// \return thread ID for reference by other functions or NULL in case of error.
 356 /// \note MUST REMAIN UNCHANGED: \b osThreadCreate shall be consistent in every CMSIS-RTOS.
 357 osThreadId osThreadCreate (osThreadDef_t *thread_def, void *argument);
 358
 359 /// Return the thread ID of the current running thread.
 360 /// \return thread ID for reference by other functions or NULL in case of error.
 361 /// \note MUST REMAIN UNCHANGED: \b osThreadGetId shall be consistent in every CMSIS-RTOS.
 362 osThreadId osThreadGetId (void);
 363
 364 /// Terminate execution of a thread and remove it from Active Threads.
 365 /// \param[in]     thread_id   thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 366 /// \return status code that indicates the execution status of the function.
 367 /// \note MUST REMAIN UNCHANGED: \b osThreadTerminate shall be consistent in every CMSIS-RTOS.
 368 osStatus osThreadTerminate (osThreadId thread_id);
 369
 370 /// Pass control to next thread that is in state \b READY.
 371 /// \return status code that indicates the execution status of the function.
 372 /// \note MUST REMAIN UNCHANGED: \b osThreadYield shall be consistent in every CMSIS-RTOS.
 373 osStatus osThreadYield (void);
 374
 375 /// Change priority of an active thread.
 376 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 377 /// \param[in]     priority      new priority value for the thread function.
 378 /// \return status code that indicates the execution status of the function.
 379 /// \note MUST REMAIN UNCHANGED: \b osThreadSetPriority shall be consistent in every CMSIS-RTOS.
 380 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority);
 381
 382 /// Get current priority of an active thread.
 383 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 384 /// \return current priority value of the thread function.
 385 /// \note MUST REMAIN UNCHANGED: \b osThreadGetPriority shall be consistent in every CMSIS-RTOS.
 386 osPriority osThreadGetPriority (osThreadId thread_id);
 387
 388
 389 //  ==== Generic Wait Functions ====
 390
 391 /// Wait for Timeout (Time Delay).
 392 /// \param[in]     millisec      time delay value
 393 /// \return status code that indicates the execution status of the function.
 394 osStatus osDelay (uint32_t millisec);
 395
 396 #if (defined (osFeature_Wait)  &&  (osFeature_Wait != 0))     // Generic Wait available
 397
 398 /// Wait for Signal, Message, Mail, or Timeout.
 399 /// \param[in] millisec          timeout value or 0 in case of no time-out
 400 /// \return event that contains signal, message, or mail information or error code.
 401 /// \note MUST REMAIN UNCHANGED: \b osWait shall be consistent in every CMSIS-RTOS.
 402 os_InRegs osEvent osWait (uint32_t millisec);
 403
 404 #endif  // Generic Wait available
 405
 406
 407 //  ==== Timer Management Functions ====
 408 /// Define a Timer object.
 409 /// \param         name          name of the timer object.
 410 /// \param         function      name of the timer call back function.
 411 /// \note CAN BE CHANGED: The parameter to \b osTimerDef shall be consistent but the
 412 ///       macro body is implementation specific in every CMSIS-RTOS.
 413 #if defined (osObjectsExternal)  // object is external
 414 #define osTimerDef(name, function)  \
 415 extern osTimerDef_t os_timer_def_##name
 416 #else                            // define the object
 417 #define osTimerDef(name, function)  \
 418 uint32_t os_timer_cb_##name[5]; \
 419 osTimerDef_t os_timer_def_##name = \
 420 { (function), (os_timer_cb_##name) }
 421 #endif
 422
 423 /// Access a Timer definition.
 424 /// \param         name          name of the timer object.
 425 /// \note CAN BE CHANGED: The parameter to \b osTimer shall be consistent but the
 426 ///       macro body is implementation specific in every CMSIS-RTOS.
 427 #define osTimer(name) \
 428 &os_timer_def_##name
 429
 430 /// Create a timer.
 431 /// \param[in]     timer_def     timer object referenced with \ref osTimer.
 432 /// \param[in]     type          osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
 433 /// \param[in]     argument      argument to the timer call back function.
 434 /// \return timer ID for reference by other functions or NULL in case of error.
 435 /// \note MUST REMAIN UNCHANGED: \b osTimerCreate shall be consistent in every CMSIS-RTOS.
 436 osTimerId osTimerCreate (osTimerDef_t *timer_def, os_timer_type type, void *argument);
 437
 438 /// Start or restart a timer.
 439 /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
 440 /// \param[in]     millisec      time delay value of the timer.
 441 /// \return status code that indicates the execution status of the function.
 442 /// \note MUST REMAIN UNCHANGED: \b osTimerStart shall be consistent in every CMSIS-RTOS.
 443 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec);
 444
 445 /// Stop the timer.
 446 /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
 447 /// \return status code that indicates the execution status of the function.
 448 /// \note MUST REMAIN UNCHANGED: \b osTimerStop shall be consistent in every CMSIS-RTOS.
 449 osStatus osTimerStop (osTimerId timer_id);
 450
 451 /// Delete a timer that was created by \ref osTimerCreate.
 452 /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
 453 /// \return status code that indicates the execution status of the function.
 454 /// \note MUST REMAIN UNCHANGED: \b osTimerDelete shall be consistent in every CMSIS-RTOS.
 455 osStatus osTimerDelete (osTimerId timer_id);
 456
 457
 458 //  ==== Signal Management ====
 459
 460 /// Set the specified Signal Flags of an active thread.
 461 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 462 /// \param[in]     signals       specifies the signal flags of the thread that should be set.
 463 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
 464 /// \note MUST REMAIN UNCHANGED: \b osSignalSet shall be consistent in every CMSIS-RTOS.
 465 int32_t osSignalSet (osThreadId thread_id, int32_t signals);
 466
 467 /// Clear the specified Signal Flags of an active thread.
 468 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 469 /// \param[in]     signals       specifies the signal flags of the thread that shall be cleared.
 470 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
 471 /// \note MUST REMAIN UNCHANGED: \b osSignalClear shall be consistent in every CMSIS-RTOS.
 472 int32_t osSignalClear (osThreadId thread_id, int32_t signals);
 473
 474 /// Get Signal Flags status of an active thread.
 475 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 476 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
 477 /// \note MUST REMAIN UNCHANGED: \b osSignalGet shall be consistent in every CMSIS-RTOS.
 478 int32_t osSignalGet (osThreadId thread_id);
 479
 480 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread.
 481 /// \param[in]     signals       wait until all specified signal flags set or 0 for any single signal flag.
 482 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
 483 /// \return event flag information or error code.
 484 /// \note MUST REMAIN UNCHANGED: \b osSignalWait shall be consistent in every CMSIS-RTOS.
 485 os_InRegs osEvent osSignalWait (int32_t signals, uint32_t millisec);
 486
 487
 488 //  ==== Mutex Management ====
 489
 490 /// Define a Mutex.
 491 /// \param         name          name of the mutex object.
 492 /// \note CAN BE CHANGED: The parameter to \b osMutexDef shall be consistent but the
 493 ///       macro body is implementation specific in every CMSIS-RTOS.
 494 #if defined (osObjectsExternal)  // object is external
 495 #define osMutexDef(name)  \
 496 extern osMutexDef_t os_mutex_def_##name
 497 #else                            // define the object
 498 #define osMutexDef(name)  \
 499 uint32_t os_mutex_cb_##name[3]; \
 500 osMutexDef_t os_mutex_def_##name = { (os_mutex_cb_##name) }
 501 #endif
 502
 503 /// Access a Mutex definition.
 504 /// \param         name          name of the mutex object.
 505 /// \note CAN BE CHANGED: The parameter to \b osMutex shall be consistent but the
 506 ///       macro body is implementation specific in every CMSIS-RTOS.
 507 #define osMutex(name)  \
 508 &os_mutex_def_##name
 509
 510 /// Create and Initialize a Mutex object.
 511 /// \param[in]     mutex_def     mutex definition referenced with \ref osMutex.
 512 /// \return mutex ID for reference by other functions or NULL in case of error.
 513 /// \note MUST REMAIN UNCHANGED: \b osMutexCreate shall be consistent in every CMSIS-RTOS.
 514 osMutexId osMutexCreate (osMutexDef_t *mutex_def);
 515
 516 /// Wait until a Mutex becomes available.
 517 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
 518 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
 519 /// \return status code that indicates the execution status of the function.
 520 /// \note MUST REMAIN UNCHANGED: \b osMutexWait shall be consistent in every CMSIS-RTOS.
 521 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec);
 522
 523 /// Release a Mutex that was obtained by \ref osMutexWait.
 524 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
 525 /// \return status code that indicates the execution status of the function.
 526 /// \note MUST REMAIN UNCHANGED: \b osMutexRelease shall be consistent in every CMSIS-RTOS.
 527 osStatus osMutexRelease (osMutexId mutex_id);
 528
 529 /// Delete a Mutex that was created by \ref osMutexCreate.
 530 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
 531 /// \return status code that indicates the execution status of the function.
 532 /// \note MUST REMAIN UNCHANGED: \b osMutexDelete shall be consistent in every CMSIS-RTOS.
 533 osStatus osMutexDelete (osMutexId mutex_id);
 534
 535
 536 //  ==== Semaphore Management Functions ====
 537
 538 #if (defined (osFeature_Semaphore)  &&  (osFeature_Semaphore != 0))     // Semaphore available
 539
 540 /// Define a Semaphore object.
 541 /// \param         name          name of the semaphore object.
 542 /// \note CAN BE CHANGED: The parameter to \b osSemaphoreDef shall be consistent but the
 543 ///       macro body is implementation specific in every CMSIS-RTOS.
 544 #if defined (osObjectsExternal)  // object is external
 545 #define osSemaphoreDef(name)  \
 546 extern osSemaphoreDef_t os_semaphore_def_##name
 547 #else                            // define the object
 548 #define osSemaphoreDef(name)  \
 549 uint32_t os_semaphore_cb_##name[2]; \
 550 osSemaphoreDef_t os_semaphore_def_##name = { (os_semaphore_cb_##name) }
 551 #endif
 552
 553 /// Access a Semaphore definition.
 554 /// \param         name          name of the semaphore object.
 555 /// \note CAN BE CHANGED: The parameter to \b osSemaphore shall be consistent but the
 556 ///       macro body is implementation specific in every CMSIS-RTOS.
 557 #define osSemaphore(name)  \
 558 &os_semaphore_def_##name
 559
 560 /// Create and Initialize a Semaphore object used for managing resources.
 561 /// \param[in]     semaphore_def semaphore definition referenced with \ref osSemaphore.
 562 /// \param[in]     count         number of available resources.
 563 /// \return semaphore ID for reference by other functions or NULL in case of error.
 564 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreCreate shall be consistent in every CMSIS-RTOS.
 565 osSemaphoreId osSemaphoreCreate (osSemaphoreDef_t *semaphore_def, int32_t count);
 566
 567 /// Wait until a Semaphore token becomes available.
 568 /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
 569 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
 570 /// \return number of available tokens, or -1 in case of incorrect parameters.
 571 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreWait shall be consistent in every CMSIS-RTOS.
 572 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec);
 573
 574 /// Release a Semaphore token.
 575 /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
 576 /// \return status code that indicates the execution status of the function.
 577 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreRelease shall be consistent in every CMSIS-RTOS.
 578 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id);
 579
 580 /// Delete a Semaphore that was created by \ref osSemaphoreCreate.
 581 /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
 582 /// \return status code that indicates the execution status of the function.
 583 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreDelete shall be consistent in every CMSIS-RTOS.
 584 osStatus osSemaphoreDelete (osSemaphoreId semaphore_id);
 585
 586 #endif     // Semaphore available
 587
 588
 589 //  ==== Memory Pool Management Functions ====
 590
 591 #if (defined (osFeature_Pool)  &&  (osFeature_Pool != 0))  // Memory Pool Management available
 592
 593 /// \brief Define a Memory Pool.
 594 /// \param         name          name of the memory pool.
 595 /// \param         no            maximum number of blocks (objects) in the memory pool.
 596 /// \param         type          data type of a single block (object).
 597 /// \note CAN BE CHANGED: The parameter to \b osPoolDef shall be consistent but the
 598 ///       macro body is implementation specific in every CMSIS-RTOS.
 599 #if defined (osObjectsExternal)  // object is external
 600 #define osPoolDef(name, no, type)   \
 601 extern osPoolDef_t os_pool_def_##name
 602 #else                            // define the object
 603 #define osPoolDef(name, no, type)   \
 604 uint32_t os_pool_m_##name[3+((sizeof(type)+3)/4)*(no)]; \
 605 osPoolDef_t os_pool_def_##name = \
 606 { (no), sizeof(type), (os_pool_m_##name) }
 607 #endif
 608
 609 /// \brief Access a Memory Pool definition.
 610 /// \param         name          name of the memory pool
 611 /// \note CAN BE CHANGED: The parameter to \b osPool shall be consistent but the
 612 ///       macro body is implementation specific in every CMSIS-RTOS.
 613 #define osPool(name) \
 614 &os_pool_def_##name
 615
 616 /// Create and Initialize a memory pool.
 617 /// \param[in]     pool_def      memory pool definition referenced with \ref osPool.
 618 /// \return memory pool ID for reference by other functions or NULL in case of error.
 619 /// \note MUST REMAIN UNCHANGED: \b osPoolCreate shall be consistent in every CMSIS-RTOS.
 620 osPoolId osPoolCreate (osPoolDef_t *pool_def);
 621
 622 /// Allocate a memory block from a memory pool.
 623 /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
 624 /// \return address of the allocated memory block or NULL in case of no memory available.
 625 /// \note MUST REMAIN UNCHANGED: \b osPoolAlloc shall be consistent in every CMSIS-RTOS.
 626 void *osPoolAlloc (osPoolId pool_id);
 627
 628 /// Allocate a memory block from a memory pool and set memory block to zero.
 629 /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
 630 /// \return address of the allocated memory block or NULL in case of no memory available.
 631 /// \note MUST REMAIN UNCHANGED: \b osPoolCAlloc shall be consistent in every CMSIS-RTOS.
 632 void *osPoolCAlloc (osPoolId pool_id);
 633
 634 /// Return an allocated memory block back to a specific memory pool.
 635 /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
 636 /// \param[in]     block         address of the allocated memory block that is returned to the memory pool.
 637 /// \return status code that indicates the execution status of the function.
 638 /// \note MUST REMAIN UNCHANGED: \b osPoolFree shall be consistent in every CMSIS-RTOS.
 639 osStatus osPoolFree (osPoolId pool_id, void *block);
 640
 641 #endif   // Memory Pool Management available
 642
 643
 644 //  ==== Message Queue Management Functions ====
 645
 646 #if (defined (osFeature_MessageQ)  &&  (osFeature_MessageQ != 0))     // Message Queues available
 647
 648 /// \brief Create a Message Queue Definition.
 649 /// \param         name          name of the queue.
 650 /// \param         queue_sz      maximum number of messages in the queue.
 651 /// \param         type          data type of a single message element (for debugger).
 652 /// \note CAN BE CHANGED: The parameter to \b osMessageQDef shall be consistent but the
 653 ///       macro body is implementation specific in every CMSIS-RTOS.
 654 #if defined (osObjectsExternal)  // object is external
 655 #define osMessageQDef(name, queue_sz, type)   \
 656 extern osMessageQDef_t os_messageQ_def_##name
 657 #else                            // define the object
 658 #define osMessageQDef(name, queue_sz, type)   \
 659 uint32_t os_messageQ_q_##name[4+(queue_sz)]; \
 660 osMessageQDef_t os_messageQ_def_##name = \
 661 { (queue_sz), (os_messageQ_q_##name) }
 662 #endif
 663
 664 /// \brief Access a Message Queue Definition.
 665 /// \param         name          name of the queue
 666 /// \note CAN BE CHANGED: The parameter to \b osMessageQ shall be consistent but the
 667 ///       macro body is implementation specific in every CMSIS-RTOS.
 668 #define osMessageQ(name) \
 669 &os_messageQ_def_##name
 670
 671 /// Create and Initialize a Message Queue.
 672 /// \param[in]     queue_def     queue definition referenced with \ref osMessageQ.
 673 /// \param[in]     thread_id     thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
 674 /// \return message queue ID for reference by other functions or NULL in case of error.
 675 /// \note MUST REMAIN UNCHANGED: \b osMessageCreate shall be consistent in every CMSIS-RTOS.
 676 osMessageQId osMessageCreate (osMessageQDef_t *queue_def, osThreadId thread_id);
 677
 678 /// Put a Message to a Queue.
 679 /// \param[in]     queue_id      message queue ID obtained with \ref osMessageCreate.
 680 /// \param[in]     info          message information.
 681 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
 682 /// \return status code that indicates the execution status of the function.
 683 /// \note MUST REMAIN UNCHANGED: \b osMessagePut shall be consistent in every CMSIS-RTOS.
 684 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec);
 685
 686 /// Get a Message or Wait for a Message from a Queue.
 687 /// \param[in]     queue_id      message queue ID obtained with \ref osMessageCreate.
 688 /// \param[in]     millisec      timeout value or 0 in case of no time-out.
 689 /// \return event information that includes status code.
 690 /// \note MUST REMAIN UNCHANGED: \b osMessageGet shall be consistent in every CMSIS-RTOS.
 691 os_InRegs osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec);
 692
 693 #endif     // Message Queues available
 694
 695
 696 //  ==== Mail Queue Management Functions ====
 697
 698 #if (defined (osFeature_MailQ)  &&  (osFeature_MailQ != 0))     // Mail Queues available
 699
 700 /// \brief Create a Mail Queue Definition.
 701 /// \param         name          name of the queue
 702 /// \param         queue_sz      maximum number of messages in queue
 703 /// \param         type          data type of a single message element
 704 /// \note CAN BE CHANGED: The parameter to \b osMailQDef shall be consistent but the
 705 ///       macro body is implementation specific in every CMSIS-RTOS.
 706 #if defined (osObjectsExternal)  // object is external
 707 #define osMailQDef(name, queue_sz, type) \
 708 extern osMailQDef_t os_mailQ_def_##name
 709 #else                            // define the object
 710 #define osMailQDef(name, queue_sz, type) \
 711 uint32_t os_mailQ_q_##name[4+(queue_sz)]; \
 712 uint32_t os_mailQ_m_##name[3+((sizeof(type)+3)/4)*(queue_sz)]; \
 713 void *   os_mailQ_p_##name[2] = { (os_mailQ_q_##name), os_mailQ_m_##name }; \
 714 osMailQDef_t os_mailQ_def_##name =  \
 715 { (queue_sz), sizeof(type), (os_mailQ_p_##name) }
 716 #endif
 717
 718 /// \brief Access a Mail Queue Definition.
 719 /// \param         name          name of the queue
 720 /// \note CAN BE CHANGED: The parameter to \b osMailQ shall be consistent but the
 721 ///       macro body is implementation specific in every CMSIS-RTOS.
 722 #define osMailQ(name)  \
 723 &os_mailQ_def_##name
 724
 725 /// Create and Initialize mail queue.
 726 /// \param[in]     queue_def     reference to the mail queue definition obtain with \ref osMailQ
 727 /// \param[in]     thread_id     thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
 728 /// \return mail queue ID for reference by other functions or NULL in case of error.
 729 /// \note MUST REMAIN UNCHANGED: \b osMailCreate shall be consistent in every CMSIS-RTOS.
 730 osMailQId osMailCreate (osMailQDef_t *queue_def, osThreadId thread_id);
 731
 732 /// Allocate a memory block from a mail.
 733 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 734 /// \param[in]     millisec      timeout value or 0 in case of no time-out
 735 /// \return pointer to memory block that can be filled with mail or NULL in case of error.
 736 /// \note MUST REMAIN UNCHANGED: \b osMailAlloc shall be consistent in every CMSIS-RTOS.
 737 void *osMailAlloc (osMailQId queue_id, uint32_t millisec);
 738
 739 /// Allocate a memory block from a mail and set memory block to zero.
 740 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 741 /// \param[in]     millisec      timeout value or 0 in case of no time-out
 742 /// \return pointer to memory block that can be filled with mail or NULL in case of error.
 743 /// \note MUST REMAIN UNCHANGED: \b osMailCAlloc shall be consistent in every CMSIS-RTOS.
 744 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec);
 745
 746 /// Put a mail to a queue.
 747 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 748 /// \param[in]     mail          memory block previously allocated with \ref osMailAlloc or \ref osMailCAlloc.
 749 /// \return status code that indicates the execution status of the function.
 750 /// \note MUST REMAIN UNCHANGED: \b osMailPut shall be consistent in every CMSIS-RTOS.
 751 osStatus osMailPut (osMailQId queue_id, void *mail);
 752
 753 /// Get a mail from a queue.
 754 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 755 /// \param[in]     millisec      timeout value or 0 in case of no time-out
 756 /// \return event that contains mail information or error code.
 757 /// \note MUST REMAIN UNCHANGED: \b osMailGet shall be consistent in every CMSIS-RTOS.
 758 os_InRegs osEvent osMailGet (osMailQId queue_id, uint32_t millisec);
 759
 760 /// Free a memory block from a mail.
 761 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 762 /// \param[in]     mail          pointer to the memory block that was obtained with \ref osMailGet.
 763 /// \return status code that indicates the execution status of the function.
 764 /// \note MUST REMAIN UNCHANGED: \b osMailFree shall be consistent in every CMSIS-RTOS.
 765 osStatus osMailFree (osMailQId queue_id, void *mail);
 766
 767 #endif  // Mail Queues available
 768
 769
 770 #ifdef  __cplusplus
 771 }
 772 #endif
 773
 774 #endif  // _CMSIS_OS_H