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