begriffs open source - cmsis/blob - CMSIS/RTOS2/Include/cmsis_os2.h

   1 /*
   2  * Copyright (c) 2013-2016 ARM Limited. All rights reserved.
   3  *
   4  * SPDX-License-Identifier: Apache-2.0
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the License); you may
   7  * not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
  14  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * ----------------------------------------------------------------------
  19  *
  20  * $Date:        30. June 2016
  21  * $Revision:    V2.0
  22  *
  23  * Project:      CMSIS-RTOS2 API
  24  * Title:        cmsis_os2.h header file
  25  *
  26  * Version 2.0
  27  *    Initial Release
  28  *---------------------------------------------------------------------------*/
  29
  30 #ifndef __CMSIS_OS2_H
  31 #define __CMSIS_OS2_H
  32
  33 #if   defined(__CC_ARM)
  34 #define __NO_RETURN __declspec(noreturn)
  35 #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)
  36 #define __NO_RETURN __attribute__((noreturn))
  37 #elif defined(__GNUC__)
  38 #define __NO_RETURN __attribute__((noreturn))
  39 #elif defined(__ICCARM__)
  40 #define __NO_RETURN __noreturn
  41 #else
  42 #define __NO_RETURN
  43 #endif
  44
  45 #include <stdint.h>
  46 #include <stddef.h>
  47
  48 #ifdef  __cplusplus
  49 extern "C"
  50 {
  51 #endif
  52
  53
  54 //  ==== Enumerations, structures, defines ====
  55
  56 /// Version information.
  57 typedef struct osVersion_s {
  58   uint32_t                       api;   ///< API version (major.minor.rev: mmnnnrrrr dec).
  59   uint32_t                    kernel;   ///< Kernel version (major.minor.rev: mmnnnrrrr dec).
  60 } osVersion_t;
  61
  62 /// Kernel state.
  63 typedef enum {
  64   osKernelInactive        =  0,         ///< Inactive.
  65   osKernelReady           =  1,         ///< Ready.
  66   osKernelRunning         =  2,         ///< Running.
  67   osKernelLocked          =  3,         ///< Locked.
  68   osKernelSuspended       =  4,         ///< Suspended.
  69   osKernelError           = -1,         ///< Error.
  70   osKernelReserved        = 0x7FFFFFFFU ///< Prevents enum down-size compiler optimization.
  71 } osKernelState_t;
  72
  73 /// Thread state.
  74 typedef enum {
  75   osThreadInactive        =  0,         ///< Inactive.
  76   osThreadReady           =  1,         ///< Ready.
  77   osThreadRunning         =  2,         ///< Running.
  78   osThreadWaiting         =  3,         ///< Waiting.
  79   osThreadSuspended       =  4,         ///< Suspended.
  80   osThreadTerminated      =  5,         ///< Terminated.
  81   osThreadError           = -1,         ///< Error.
  82   osThreadReserved        = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
  83 } osThreadState_t;
  84
  85 /// Priority values.
  86 typedef enum {
  87   osPriorityNone          =  0,         ///< No priority (not initialized).
  88   osPriorityIdle          =  1,         ///< Reserved for Idle thread.
  89   osPriorityLow           =  8,         ///< Priority: low
  90   osPriorityLow1          =  8+1,       ///< Priority: low + 1
  91   osPriorityLow2          =  8+2,       ///< Priority: low + 2
  92   osPriorityLow3          =  8+3,       ///< Priority: low + 3
  93   osPriorityLow4          =  8+4,       ///< Priority: low + 4
  94   osPriorityLow5          =  8+5,       ///< Priority: low + 5
  95   osPriorityLow6          =  8+6,       ///< Priority: low + 6
  96   osPriorityLow7          =  8+7,       ///< Priority: low + 7
  97   osPriorityBelowNormal   = 16,         ///< Priority: below normal
  98   osPriorityBelowNormal1  = 16+1,       ///< Priority: below normal + 1
  99   osPriorityBelowNormal2  = 16+2,       ///< Priority: below normal + 2
 100   osPriorityBelowNormal3  = 16+3,       ///< Priority: below normal + 3
 101   osPriorityBelowNormal4  = 16+4,       ///< Priority: below normal + 4
 102   osPriorityBelowNormal5  = 16+5,       ///< Priority: below normal + 5
 103   osPriorityBelowNormal6  = 16+6,       ///< Priority: below normal + 6
 104   osPriorityBelowNormal7  = 16+7,       ///< Priority: below normal + 7
 105   osPriorityNormal        = 24,         ///< Priority: normal
 106   osPriorityNormal1       = 24+1,       ///< Priority: normal + 1
 107   osPriorityNormal2       = 24+2,       ///< Priority: normal + 2
 108   osPriorityNormal3       = 24+3,       ///< Priority: normal + 3
 109   osPriorityNormal4       = 24+4,       ///< Priority: normal + 4
 110   osPriorityNormal5       = 24+5,       ///< Priority: normal + 5
 111   osPriorityNormal6       = 24+6,       ///< Priority: normal + 6
 112   osPriorityNormal7       = 24+7,       ///< Priority: normal + 7
 113   osPriorityAboveNormal   = 32,         ///< Priority: above normal
 114   osPriorityAboveNormal1  = 32+1,       ///< Priority: above normal + 1
 115   osPriorityAboveNormal2  = 32+2,       ///< Priority: above normal + 2
 116   osPriorityAboveNormal3  = 32+3,       ///< Priority: above normal + 3
 117   osPriorityAboveNormal4  = 32+4,       ///< Priority: above normal + 4
 118   osPriorityAboveNormal5  = 32+5,       ///< Priority: above normal + 5
 119   osPriorityAboveNormal6  = 32+6,       ///< Priority: above normal + 6
 120   osPriorityAboveNormal7  = 32+7,       ///< Priority: above normal + 7
 121   osPriorityHigh          = 40,         ///< Priority: high
 122   osPriorityHigh1         = 40+1,       ///< Priority: high + 1
 123   osPriorityHigh2         = 40+2,       ///< Priority: high + 2
 124   osPriorityHigh3         = 40+3,       ///< Priority: high + 3
 125   osPriorityHigh4         = 40+4,       ///< Priority: high + 4
 126   osPriorityHigh5         = 40+5,       ///< Priority: high + 5
 127   osPriorityHigh6         = 40+6,       ///< Priority: high + 6
 128   osPriorityHigh7         = 40+7,       ///< Priority: high + 7
 129   osPriorityRealtime      = 48,         ///< Priority: realtime
 130   osPriorityRealtime1     = 48+1,       ///< Priority: realtime + 1
 131   osPriorityRealtime2     = 48+2,       ///< Priority: realtime + 2
 132   osPriorityRealtime3     = 48+3,       ///< Priority: realtime + 3
 133   osPriorityRealtime4     = 48+4,       ///< Priority: realtime + 4
 134   osPriorityRealtime5     = 48+5,       ///< Priority: realtime + 5
 135   osPriorityRealtime6     = 48+6,       ///< Priority: realtime + 6
 136   osPriorityRealtime7     = 48+7,       ///< Priority: realtime + 7
 137   osPriorityISR           = 56,         ///< Reserved for ISR deferred thread.
 138   osPriorityError         = -1,         ///< System cannot determine priority or illegal priority.
 139   osPriorityReserved      = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
 140 } osPriority_t;
 141
 142 /// Entry point of a thread.
 143 typedef void *(*os_thread_func_t) (void *argument);
 144
 145 /// Entry point of a timer call back function.
 146 typedef void (*os_timer_func_t) (void *argument);
 147
 148 /// Timer type.
 149 typedef enum {
 150   osTimerOnce             = 0,          ///< One-shot timer.
 151   osTimerPeriodic         = 1           ///< Repeating timer.
 152 } osTimerType_t;
 153
 154 /// Timeout value.
 155 #define osWaitForever       0xFFFFFFFFU ///< Wait forever timeout value.
 156
 157 /// Flags options (\ref osThreadFlagsWait and \ref osEventFlagsWait).
 158 #define osFlagsWaitAny      0x00000000U ///< Wait for any flag (default).
 159 #define osFlagsWaitAll      0x00000001U ///< Wait for all flags.
 160 #define osFlagsAutoClear    0x00000002U ///< Clear flags which have been specified to wait for.
 161
 162 /// Thread attributes (attr_bits in \ref osThreadAttr_t).
 163 #define osThreadJoinable    0x00000000U ///< Thread created in joinable state (default)
 164 #define osThreadDetached    0x00000001U ///< Thread created in detached state
 165
 166 /// Mutex attributes (attr_bits in \ref osMutexAttr_t).
 167 #define osMutexRecursive    0x00000001U ///< Recursive mutex.
 168 #define osMutexPrioInherit  0x00000002U ///< Priority inherit protocol.
 169 #define osMutexRobust       0x00000008U ///< Robust mutex.
 170
 171 /// Status code values returned by CMSIS-RTOS functions.
 172 typedef enum {
 173   osOK                    =  0,         ///< Operation completed successfully.
 174   osError                 = -1,         ///< Unspecified RTOS error: run-time error but no other error message fits.
 175   osErrorTimeout          = -2,         ///< Operation not completed within the timeout period.
 176   osErrorResource         = -3,         ///< Resource not available.
 177   osErrorParameter        = -4,         ///< Parameter error.
 178   osErrorNoMemory         = -5,         ///< System is out of memory: it was impossible to allocate or reserve memory for the operation.
 179   osErrorISR              = -6,         ///< Not allowed in ISR context: the function cannot be called from interrupt service routines.
 180   osStatusReserved        = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
 181 } osStatus_t;
 182
 183
 184 /// \details Thread ID identifies the thread.
 185 typedef uint32_t osThreadId_t;
 186
 187 /// \details Timer ID identifies the timer.
 188 typedef uint32_t osTimerId_t;
 189
 190 /// \details Event Flags ID identifies the event flags.
 191 typedef uint32_t osEventFlagsId_t;
 192
 193 /// \details Mutex ID identifies the mutex.
 194 typedef uint32_t osMutexId_t;
 195
 196 /// \details Semaphore ID identifies the semaphore.
 197 typedef uint32_t osSemaphoreId_t;
 198
 199 /// \details Memory Pool ID identifies the memory pool.
 200 typedef uint32_t osMemoryPoolId_t;
 201
 202 /// \details Message Queue ID identifies the message queue.
 203 typedef uint32_t osMessageQueueId_t;
 204
 205
 206 /// Attributes structure for thread.
 207 typedef struct osThreadAttr_s {
 208   const char                   *name;   ///< name of the thread
 209   uint32_t                 attr_bits;   ///< attribute bits
 210   void                      *cb_mem;    ///< memory for control block
 211   uint32_t                   cb_size;   ///< size of provided memory for control block
 212   void                   *stack_mem;    ///< memory for stack
 213   uint32_t                stack_size;   ///< size of stack
 214   osPriority_t              priority;   ///< initial thread priority (default: osPriorityNormal)
 215   uint32_t               reserved[2];   ///< reserved (must be 0)
 216 } osThreadAttr_t;
 217
 218 /// Attributes structure for timer.
 219 typedef struct osTimerAttr_s {
 220   const char                   *name;   ///< name of the timer
 221   uint32_t                 attr_bits;   ///< attribute bits
 222   void                      *cb_mem;    ///< memory for control block
 223   uint32_t                   cb_size;   ///< size of provided memory for control block
 224 } osTimerAttr_t;
 225
 226 /// Attributes structure for event flags.
 227 typedef struct osEventFlagsAttr_s {
 228   const char                   *name;   ///< name of the event flags
 229   uint32_t                 attr_bits;   ///< attribute bits
 230   void                      *cb_mem;    ///< memory for control block
 231   uint32_t                   cb_size;   ///< size of provided memory for control block
 232 } osEventFlagsAttr_t;
 233
 234 /// Attributes structure for mutex.
 235 typedef struct osMutexAttr_s {
 236   const char                   *name;   ///< name of the mutex
 237   uint32_t                 attr_bits;   ///< attribute bits
 238   void                      *cb_mem;    ///< memory for control block
 239   uint32_t                   cb_size;   ///< size of provided memory for control block
 240 } osMutexAttr_t;
 241
 242 /// Attributes structure for semaphore.
 243 typedef struct osSemaphoreAttr_s {
 244   const char                   *name;   ///< name of the semaphore
 245   uint32_t                 attr_bits;   ///< attribute bits
 246   void                      *cb_mem;    ///< memory for control block
 247   uint32_t                   cb_size;   ///< size of provided memory for control block
 248 } osSemaphoreAttr_t;
 249
 250 /// Attributes structure for memory pool.
 251 typedef struct osMemoryPoolAttr_s {
 252   const char                   *name;   ///< name of the memory pool
 253   uint32_t                 attr_bits;   ///< attribute bits
 254   void                      *cb_mem;    ///< memory for control block
 255   uint32_t                   cb_size;   ///< size of provided memory for control block
 256   void                      *mp_mem;    ///< memory for data storage
 257   uint32_t                   mp_size;   ///< size of provided memory for data storage
 258 } osMemoryPoolAttr_t;
 259
 260 /// Attributes structure for message queue.
 261 typedef struct osMessageQueueAttr_s {
 262   const char                   *name;   ///< name of the message queue
 263   uint32_t                 attr_bits;   ///< attribute bits
 264   void                      *cb_mem;    ///< memory for control block
 265   uint32_t                   cb_size;   ///< size of provided memory for control block
 266   void                      *mq_mem;    ///< memory for data storage
 267   uint32_t                   mq_size;   ///< size of provided memory for data storage
 268 } osMessageQueueAttr_t;
 269
 270
 271 //  ==== Kernel Management Functions ====
 272
 273 /// Initialize the RTOS Kernel.
 274 /// \return status code that indicates the execution status of the function.
 275 osStatus_t osKernelInitialize (void);
 276
 277 ///  Get RTOS Kernel Information.
 278 /// \param[out]    version       pointer to buffer for retrieving version information.
 279 /// \param[out]    id_buf        pointer to buffer for retrieving kernel identification string.
 280 /// \param[in]     id_size       size of buffer for kernel identification string.
 281 /// \return status code that indicates the execution status of the function.
 282 osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size);
 283
 284 /// Get the current RTOS Kernel state.
 285 /// \return current RTOS Kernel state.
 286 osKernelState_t osKernelGetState (void);
 287
 288 /// Start the RTOS Kernel scheduler.
 289 /// \return status code that indicates the execution status of the function.
 290 osStatus_t osKernelStart (void);
 291
 292 /// Lock the RTOS Kernel scheduler.
 293 /// \return 0 already locked, 1 locked.
 294 uint32_t osKernelLock (void);
 295
 296 /// Unlock the RTOS Kernel scheduler.
 297 void osKernelUnlock (void);
 298
 299 /// Suspend the RTOS Kernel scheduler.
 300 /// \return time in millisec, for how long the system can sleep or power-down.
 301 uint32_t osKernelSuspend (void);
 302
 303 /// Resume the RTOS Kernel scheduler.
 304 /// \param[in]     sleep_time    time in millisec for how long the system was in sleep or power-down mode.
 305 void osKernelResume (uint32_t sleep_time);
 306
 307 /// Get the RTOS kernel time.
 308 /// \return RTOS kernel current time in millisec.
 309 uint64_t osKernelGetTime (void);
 310
 311 /// Get the RTOS kernel system timer counter.
 312 /// \return RTOS kernel system timer as 32-bit value.
 313 uint32_t osKernelGetTick (void);
 314
 315 /// Convert a microseconds value to a RTOS kernel system timer value.
 316 /// \param         microsec     time value in microseconds.
 317 /// \return time value normalized to the system timer ticks.
 318 uint32_t osKernelTickMicroSec (uint32_t microsec);
 319
 320
 321 //  ==== Thread Management Functions ====
 322
 323 /// Create a thread and add it to Active Threads.
 324 /// \param[in]     func          thread function.
 325 /// \param[in]     argument      pointer that is passed to the thread function as start argument.
 326 /// \param[in]     attr          thread attributes; NULL: default values.
 327 /// \return thread ID for reference by other functions or NULL in case of error.
 328 osThreadId_t osThreadNew (os_thread_func_t func, void *argument, const osThreadAttr_t *attr);
 329
 330 /// Return the thread ID of the current running thread.
 331 /// \return thread ID for reference by other functions or NULL in case of error.
 332 osThreadId_t osThreadGetId (void);
 333
 334 /// Get current thread state of a thread.
 335 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 336 /// \return current thread state of the specified thread.
 337 osThreadState_t osThreadGetState (osThreadId_t thread_id);
 338
 339 /// Change priority of a thread.
 340 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 341 /// \param[in]     priority      new priority value for the thread function.
 342 /// \return status code that indicates the execution status of the function.
 343 osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority);
 344
 345 /// Get current priority of a thread.
 346 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 347 /// \return current priority value of the specified thread.
 348 osPriority_t osThreadGetPriority (osThreadId_t thread_id);
 349
 350 /// Pass control to next thread that is in state \b READY.
 351 /// \return status code that indicates the execution status of the function.
 352 osStatus_t osThreadYield (void);
 353
 354 /// Abort waiting operation of a thread.
 355 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 356 /// \return status code that indicates the execution status of the function.
 357 osStatus_t osThreadAbortWait (osThreadId_t thread_id);
 358
 359 /// Suspend execution of a thread.
 360 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 361 /// \return status code that indicates the execution status of the function.
 362 osStatus_t osThreadSuspend (osThreadId_t thread_id);
 363
 364 /// Resume execution of a thread.
 365 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 366 /// \return status code that indicates the execution status of the function.
 367 osStatus_t osThreadResume (osThreadId_t thread_id);
 368
 369 /// Detach a thread (thread storage can be reclaimed when thread terminates).
 370 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 371 /// \return status code that indicates the execution status of the function.
 372 osStatus_t osThreadDetach (osThreadId_t thread_id);
 373
 374 /// Wait for specified thread to terminate.
 375 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 376 /// \param[out]    exit_ptr      pointer to thread exit pointer value.
 377 /// \return status code that indicates the execution status of the function.
 378 osStatus_t osThreadJoin (osThreadId_t thread_id, void **exit_ptr);
 379
 380 /// Terminate execution of current running thread.
 381 /// \param[in]     exit_ptr      thread exit pointer value.
 382 __NO_RETURN void osThreadExit (void *exit_ptr);
 383
 384 /// Terminate execution of a thread.
 385 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 386 /// \return status code that indicates the execution status of the function.
 387 osStatus_t osThreadTerminate (osThreadId_t thread_id);
 388
 389
 390 //  ==== Thread Flags Functions ====
 391
 392 /// Set the specified Thread Flags of a thread.
 393 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 394 /// \param[in]     flags         specifies the flags of the thread that shall be set.
 395 /// \return thread flags after setting or error code if negative.
 396 int32_t osThreadFlagsSet (osThreadId_t thread_id, int32_t flags);
 397
 398 /// Clear the specified Thread Flags of a thread.
 399 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 400 /// \param[in]     flags         specifies the flags of the thread that shall be cleared.
 401 /// \return thread flags before clearing or error code if negative.
 402 int32_t osThreadFlagsClear (osThreadId_t thread_id, int32_t flags);
 403
 404 /// Get the current Thread Flags of a thread.
 405 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
 406 /// \return current thread flags.
 407 int32_t osThreadFlagsGet (osThreadId_t thread_id);
 408
 409 /// Wait for one or more Thread Flags of the current running thread to become signaled.
 410 /// \param[in]     flags         specifies the flags to wait for.
 411 /// \param[in]     options       specifies flags options (osFlagsXxxx).
 412 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 413 /// \return thread flags before clearing or error code if negative.
 414 int32_t osThreadFlagsWait (int32_t flags, uint32_t options, uint32_t millisec);
 415
 416
 417 //  ==== Generic Wait Functions ====
 418
 419 /// Wait for Timeout (Time Delay).
 420 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue "time delay" value
 421 /// \return status code that indicates the execution status of the function.
 422 osStatus_t osDelay (uint32_t millisec);
 423
 424 /// Wait until specified time.
 425 /// \param[in]     millisec      absolute time in millisec
 426 /// \return status code that indicates the execution status of the function.
 427 osStatus_t osDelayUntil (uint64_t millisec);
 428
 429
 430 //  ==== Timer Management Functions ====
 431
 432 /// Create and Initialize a timer.
 433 /// \param[in]     func          start address of a timer call back function.
 434 /// \param[in]     type          osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
 435 /// \param[in]     argument      argument to the timer call back function.
 436 /// \param[in]     attr          timer attributes; NULL: default values.
 437 /// \return timer ID for reference by other functions or NULL in case of error.
 438 osTimerId_t osTimerNew (os_timer_func_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr);
 439
 440 /// Start or restart a timer.
 441 /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
 442 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue "time delay" value of the timer.
 443 /// \return status code that indicates the execution status of the function.
 444 osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t millisec);
 445
 446 /// Stop a timer.
 447 /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
 448 /// \return status code that indicates the execution status of the function.
 449 osStatus_t osTimerStop (osTimerId_t timer_id);
 450
 451 /// Check if a timer is running.
 452 /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
 453 /// \return 0 not running, 1 running.
 454 uint32_t osTimerIsRunning (osTimerId_t timer_id);
 455
 456 /// Delete a timer.
 457 /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
 458 /// \return status code that indicates the execution status of the function.
 459 osStatus_t osTimerDelete (osTimerId_t timer_id);
 460
 461
 462 //  ==== Event Flags Management Functions ====
 463
 464 /// Create and Initialize an Event Flags object.
 465 /// \param[in]     attr          event flags attributes; NULL: default values.
 466 /// \return event flags ID for reference by other functions or NULL in case of error.
 467 osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr);
 468
 469 /// Set the specified Event Flags.
 470 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
 471 /// \param[in]     flags         specifies the flags that shall be set.
 472 /// \return event flags after setting or error code if negative.
 473 int32_t osEventFlagsSet (osEventFlagsId_t ef_id, int32_t flags);
 474
 475 /// Clear the specified Event Flags.
 476 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
 477 /// \param[in]     flags         specifies the flags that shall be cleared.
 478 /// \return event flags before clearing or error code if negative.
 479 int32_t osEventFlagsClear (osEventFlagsId_t ef_id, int32_t flags);
 480
 481 /// Get the current Event Flags.
 482 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
 483 /// \return current event flags.
 484 int32_t osEventFlagsGet (osEventFlagsId_t ef_id);
 485
 486 /// Wait for one or more Event Flags to become signaled.
 487 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
 488 /// \param[in]     flags         specifies the flags to wait for.
 489 /// \param[in]     options       specifies flags options (osFlagsXxxx).
 490 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 491 /// \return event flags before clearing or error code if negative.
 492 int32_t osEventFlagsWait (osEventFlagsId_t ef_id, int32_t flags, uint32_t options, uint32_t millisec);
 493
 494 /// Delete an Event Flags object.
 495 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
 496 /// \return status code that indicates the execution status of the function.
 497 osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id);
 498
 499
 500 //  ==== Mutex Management Functions ====
 501
 502 /// Create and Initialize a Mutex object.
 503 /// \param[in]     attr          mutex attributes; NULL: default values.
 504 /// \return mutex ID for reference by other functions or NULL in case of error.
 505 osMutexId_t osMutexNew (const osMutexAttr_t *attr);
 506
 507 /// Acquire a Mutex or timeout if it is locked.
 508 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
 509 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 510 /// \return status code that indicates the execution status of the function.
 511 osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t millisec);
 512
 513 /// Release a Mutex that was acquired by \ref osMutexAcquire.
 514 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
 515 /// \return status code that indicates the execution status of the function.
 516 osStatus_t osMutexRelease (osMutexId_t mutex_id);
 517
 518 /// Get Thread which owns a Mutex object.
 519 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
 520 /// \return thread ID of owner thread or NULL when mutex was not acquired.
 521 osThreadId_t osMutexGetOwner (osMutexId_t mutex_id);
 522
 523 /// Delete a Mutex object.
 524 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
 525 /// \return status code that indicates the execution status of the function.
 526 osStatus_t osMutexDelete (osMutexId_t mutex_id);
 527
 528
 529 //  ==== Semaphore Management Functions ====
 530
 531 /// Create and Initialize a Semaphore object.
 532 /// \param[in]     max_count     maximum number of available tokens.
 533 /// \param[in]     initial_count initial number of available tokens.
 534 /// \param[in]     attr          semaphore attributes; NULL: default values.
 535 /// \return semaphore ID for reference by other functions or NULL in case of error.
 536 osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr);
 537
 538 /// Acquire a Semaphore token or timeout if no tokens are available.
 539 /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
 540 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 541 /// \return status code that indicates the execution status of the function.
 542 osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t millisec);
 543
 544 /// Release a Semaphore token that was acquired by \ref osSemaphoreAcquire.
 545 /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
 546 /// \return status code that indicates the execution status of the function.
 547 osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id);
 548
 549 /// Get current Semaphore token count.
 550 /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
 551 /// \return number of tokens available.
 552 uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id);
 553
 554 /// Delete a Semaphore object.
 555 /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
 556 /// \return status code that indicates the execution status of the function.
 557 osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id);
 558
 559
 560 //  ==== Memory Pool Management Functions ====
 561
 562 /// Create and Initialize a Memory Pool object.
 563 /// \param[in]     block_count   maximum number of memory blocks in memory pool.
 564 /// \param[in]     block_size    memory block size in bytes.
 565 /// \param[in]     attr          memory pool attributes; NULL: default values.
 566 /// \return memory pool ID for reference by other functions or NULL in case of error.
 567 osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr);
 568
 569 /// Allocate a memory block from a Memory Pool.
 570 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
 571 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 572 /// \return address of the allocated memory block or NULL in case of no memory is available.
 573 void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t millisec);
 574
 575 /// Return an allocated memory block back to a Memory Pool.
 576 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
 577 /// \param[in]     block         address of the allocated memory block to be returned to the memory pool.
 578 /// \return status code that indicates the execution status of the function.
 579 osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block);
 580
 581 /// Get maximum number of memory blocks in a Memory Pool.
 582 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
 583 /// \return maximum number of memory blocks.
 584 uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id);
 585
 586 /// Get memory block size in a Memory Pool.
 587 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
 588 /// \return memory block size in bytes.
 589 uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id);
 590
 591 /// Get number of memory blocks used in a Memory Pool.
 592 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
 593 /// \return number of memory blocks used.
 594 uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id);
 595
 596 /// Get number of memory blocks available in a Memory Pool.
 597 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
 598 /// \return number of memory blocks available.
 599 uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id);
 600
 601 /// Delete a Memory Pool object.
 602 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
 603 /// \return status code that indicates the execution status of the function.
 604 osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id);
 605
 606
 607 //  ==== Message Queue Management Functions ====
 608
 609 /// Create and Initialize a Message Queue object.
 610 /// \param[in]     msg_count     maximum number of messages in queue.
 611 /// \param[in]     msg_size      maximum message size in bytes.
 612 /// \param[in]     attr          message queue attributes; NULL: default values.
 613 /// \return message queue ID for reference by other functions or NULL in case of error.
 614 osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr);
 615
 616 /// Put a Message into a Queue or timeout if Queue is full.
 617 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
 618 /// \param[in]     msg_ptr       pointer to buffer with message to put into a queue.
 619 /// \param[in]     msg_prio      message priority.
 620 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 621 /// \return status code that indicates the execution status of the function.
 622 osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t millisec);
 623
 624 /// Get a Message from a Queue or timeout if Queue is empty.
 625 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
 626 /// \param[out]    msg_ptr       pointer to buffer for message to get from a queue.
 627 /// \param[out]    msg_prio      pointer to buffer for message priority or NULL.
 628 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 629 /// \return status code that indicates the execution status of the function.
 630 osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t millisec);
 631
 632 /// Get maximum number of messages in a Message Queue.
 633 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
 634 /// \return maximum number of messages.
 635 uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id);
 636
 637 /// Get maximum message size in a Memory Pool.
 638 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
 639 /// \return maximum message size in bytes.
 640 uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id);
 641
 642 /// Get number of queued messages in a Message Queue.
 643 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
 644 /// \return number of queued messages.
 645 uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id);
 646
 647 /// Get number of available slots for messages in a Message Queue.
 648 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
 649 /// \return number of available slots for messages.
 650 uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id);
 651
 652 /// Reset a Message Queue to initial empty state.
 653 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
 654 /// \return status code that indicates the execution status of the function.
 655 osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id);
 656
 657 /// Delete a Message Queue object.
 658 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
 659 /// \return status code that indicates the execution status of the function.
 660 osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id);
 661
 662
 663 #ifdef  __cplusplus
 664 }
 665 #endif
 666
 667 #endif  // __CMSIS_OS2_H