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

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