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