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

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