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