begriffs open source - cmsis/blob - CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Thread.txt

   1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   2 //  ==== Thread Management ====
   3 /**
   4 \addtogroup CMSIS_RTOS_ThreadMgmt Thread Management
   5 \ingroup CMSIS_RTOS CMSIS_RTOSv2
   6 \brief Define, create, and control thread functions.
   7 \details
   8 The Thread Management function group allows defining, creating, and controlling thread functions in the system.
   9
  10 \note Thread management functions cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  11
  12 \anchor ThreadStates
  13 Thread states
  14 -------------
  15 Threads can be in the following states:
  16
  17  - \b RUNNING: The thread that is currently running is in the \ref ThreadStates "RUNNING" state. Only one thread at a time can be in this
  18    state.
  19  - \b READY: Threads which are ready to run are in the \ref ThreadStates "READY" state. Once the \ref ThreadStates "RUNNING" thread has terminated, or is
  20    \ref ThreadStates "BLOCKED", the next \ref ThreadStates "READY" thread with the highest priority becomes the \ref ThreadStates "RUNNING" thread.
  21  - \b BLOCKED: Threads that are blocked either delayed, waiting for an event to occur or suspended are in the \ref ThreadStates "BLOCKED"
  22    state.
  23  - \b TERMINATED: When \ref osThreadTerminate is called, threads are \ref ThreadStates "TERMINATED" with resources not yet released.
  24  - \b INACTIVE: Threads that are not created or have been terminated with all resources released are in the \ref ThreadStates "INACTIVE" state.
  25
  26 \image html "ThreadStatus.png" "Thread State and State Transitions"
  27
  28
  29 A CMSIS-RTOS assumes that threads are scheduled as shown in the figure <b>Thread State and State Transitions</b>. The thread
  30 states change as follows:
  31  - A thread is created using the function \ref osThreadNew. This puts the thread into the \ref ThreadStates "READY" or \ref ThreadStates "RUNNING" state
  32    (depending on the thread priority).
  33  - CMSIS-RTOS is preemptive. The active thread with the highest priority becomes the \ref ThreadStates "RUNNING" thread provided it does not
  34    wait for any event. The initial priority of a thread is defined with the \ref osThreadAttr_t but may be changed during
  35    execution using the function \ref osThreadSetPriority.
  36  - The \ref ThreadStates "RUNNING" thread transfers into the \ref ThreadStates "BLOCKED" state when it is delayed, waiting for an event or suspended.
  37  - Active threads can be terminated any time using the function \ref osThreadTerminate. Threads can terminate also by just
  38    returning from the thread function. Threads that are terminated are in the \ref ThreadStates "INACTIVE" state and typically do not consume
  39    any dynamic memory resources.
  40
  41 \note
  42 Refer to \ref threadConfig for RTX5 configuration options.
  43
  44 \anchor thread_examples
  45 Thread Examples
  46 ===============
  47 The following examples show various scenarios to create threads:
  48
  49 <b>Example 1 - Create a simple thread</b>
  50
  51 Create a thread out of the function thread1 using all default values for thread attributes and memory from the
  52 \ref GlobalMemoryPool.
  53
  54 \code
  55 __NO_RETURN void thread1 (void *argument) {
  56   // ...
  57   for (;;) {}
  58 }
  59
  60 int main (void) {
  61   osKernelInitialize();
  62   ;
  63   osThreadNew(thread1, NULL, NULL);    // Create thread with default settings
  64   ;
  65   osKernelStart();
  66 }
  67 \endcode
  68
  69 <b>Example 2 - Create thread with stack non-default stack size</b>
  70
  71 Similar to the simple thread all attributes are default. The stack is dynamically allocated from the \ref GlobalMemoryPool
  72
  73 \ref osThreadAttr_t.stack_size is used to pass the stack size in Bytes to osThreadNew.
  74
  75 \code
  76 __NO_RETURN void thread1 (void *argument) {
  77   // ...
  78   for (;;) {}
  79 }
  80
  81 const osThreadAttr_t thread1_attr = {
  82   .stack_size = 1024                             // Create the thread stack with a size of 1024 bytes
  83 };
  84
  85 int main (void) {
  86   ;
  87   osThreadNew(thread1, NULL, &thread1_attr);     // Create thread with custom sized stack memory
  88   ;
  89 }
  90 \endcode
  91
  92 <b>Example 3 - Create thread with statically allocated stack</b>
  93
  94 Similar to the simple thread all attributes are default. The stack is statically allocated using the \c uint64_t array
  95 \c thread1_stk_1. This allocates 64*8 Bytes (=512 Bytes) with an alignment of 8 Bytes (mandatory for Cortex-M stack memory).
  96
  97 \ref osThreadAttr_t.stack_mem holds a pointer to the stacks lowest address.
  98
  99 \ref osThreadAttr_t.stack_size is used to pass the stack size in Bytes to osThreadNew.
 100
 101 \code
 102 __NO_RETURN void thread1 (void *argument) {
 103   // ...
 104   for (;;) {}
 105 }
 106
 107 static uint64_t thread1_stk_1[64];
 108
 109 const osThreadAttr_t thread1_attr = {
 110   .stack_mem  = &thread1_stk_1[0],
 111   .stack_size = sizeof(thread1_stk_1)
 112 };
 113
 114 int main (void) {
 115   ;
 116   osThreadNew(thread1, NULL, &thread1_attr);    // Create thread with statically allocated stack memory
 117   ;
 118 }
 119 \endcode
 120
 121 <b>Example 4 - Thread with statically allocated task control block</b>
 122
 123 Typically this method is chosen together with a statically allocated stack as shown in Example 2.
 124 \code
 125 #include "cmsis_os2.h"
 126
 127 //include rtx_os.h for types of RTX objects
 128 #include "rtx_os.h"
 129
 130 __NO_RETURN void thread1 (void *argument) {
 131   // ...
 132   for (;;) {}
 133 }
 134
 135 static osRtxThread_t thread1_tcb;
 136
 137 const osThreadAttr_t thread1_attr = {
 138   .cb_mem  = &thread1_tcb,
 139   .cb_size = sizeof(thread1_tcb),
 140 };
 141
 142 int main (void) {
 143   ;
 144   osThreadNew(thread1, NULL, &thread1_attr);    // Create thread with custom tcb memory
 145   ;
 146 }
 147 \endcode
 148
 149 <b>Example 5 - Create thread with a different priority</b>
 150
 151 The default priority of RTX is \ref osPriorityNormal. Often you want to run a task with a higher or lower priority. Using the
 152 \ref osThreadAttr_t control structure you can set any initial priority required.
 153
 154 \code
 155 __NO_RETURN void thread1 (void *argument) {
 156   // ...
 157   for (;;) {}
 158 }
 159
 160 const osThreadAttr_t thread1_attr = {
 161   .priority = osPriorityHigh            //Set initial thread priority to high
 162 };
 163
 164 int main (void) {
 165   ;
 166   osThreadNew(thread1, NULL, &thread1_attr);
 167   ;
 168 }
 169 \endcode
 170
 171 \anchor joinable_threads
 172 <b>Example 6 - Joinable threads</b>
 173
 174 In this example a master thread creates four threads with the \ref osThreadJoinable attribute. These will do some work and
 175 return using the \ref osThreadExit call after finished. \ref osThreadJoin is used to synchronize the thread termination.
 176
 177
 178 \code
 179 __NO_RETURN void worker (void *argument) {
 180     ; // work a lot on data[]
 181     osDelay(1000);
 182     osThreadExit();
 183 }
 184
 185 __NO_RETURN void thread1 (void *argument) {
 186   osThreadAttr_t worker_attr;
 187   osThreadId_t worker_ids[4];
 188   uint8_t data[4][10];
 189
 190   memset(&worker_attr, 0, sizeof(worker_attr));
 191   worker_attr.attr_bits = osThreadJoinable;
 192
 193   worker_ids[0] = osThreadNew(worker, &data[0][0], &worker_attr);
 194   worker_ids[1] = osThreadNew(worker, &data[1][0], &worker_attr);
 195   worker_ids[2] = osThreadNew(worker, &data[2][0], &worker_attr);
 196   worker_ids[3] = osThreadNew(worker, &data[3][0], &worker_attr);
 197
 198   osThreadJoin(worker_ids[0]);
 199   osThreadJoin(worker_ids[1]);
 200   osThreadJoin(worker_ids[2]);
 201   osThreadJoin(worker_ids[3]);
 202
 203   osThreadExit();
 204 }
 205 \endcode
 206
 207 @{
 208 */
 209 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 210 /**
 211 \enum osThreadState_t
 212 \details
 213 State of a thread as retrieved by \ref osThreadGetState. In case \b osThreadGetState fails or if it is called from an ISR, it
 214 will return \c osThreadError, otherwise it returns the thread state.
 215
 216 \var osThreadState_t::osThreadInactive
 217 \details The thread is created but not actively used, or has been terminated.
 218
 219 \var osThreadState_t::osThreadReady
 220 \details The thread is ready for execution but not currently running.
 221
 222 \var osThreadState_t::osThreadRunning
 223 \details The thread is currently running.
 224
 225 \var osThreadState_t::osThreadBlocked
 226 \details The thread is currently blocked (delayed, waiting for an event or suspended).
 227
 228 \var osThreadState_t::osThreadTerminated
 229 \details The thread is terminated and all its resources are freed.
 230
 231 \var osThreadState_t::osThreadError
 232 \details The thread thread has raised an error condition and cannot be scheduled.
 233 */
 234
 235 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 236 /**
 237 \enum osPriority_t
 238 \details
 239
 240 The \b osPriority_t value specifies the priority for a thread. The default thread priority should be \a osPriorityNormal.
 241 If an active thread becomes ready that has a higher priority than the currently running thread then a thread switch occurs
 242 immediately. The system continues executing the thread with the higher priority.
 243
 244 To prevent from a priority inversion, a CMSIS-RTOS compliant OS may optionally implement a <b>priority inheritance</b>
 245 method. A priority inversion occurs when a high priority thread is waiting for a resource or event that is controlled by a
 246 thread with a lower priority. Thus causing the high priority thread potentially beeing blocked forever by another thread
 247 with lower priority. To come over this issue the low priority thread controlling the resource should be treated as having
 248 the higher priority until it releases the resource.
 249
 250 \note Priority inheritance only applies to mutexes.
 251
 252 \var osPriority_t::osPriorityIdle
 253 \details This lowest priority should not be used for any other thread.
 254
 255 \var osPriority_t::osPriorityISR
 256 \details This highest priority might be used by the RTOS implementation but must not be used for any user thread.
 257 */
 258
 259 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 260 /**
 261 \typedef void (*osThreadFunc_t) (void *argument)
 262 \details Entry function for threads. Setting up a new thread (\ref osThreadNew) will start execution with a call into this
 263 entry function. The optional argument can be used to hand over arbitrary user data to the thread, i.e. to identify the thread
 264 or for runtime parameters.
 265
 266 \param[in] argument Arbitrary user data set on \ref osThreadNew.
 267 */
 268
 269 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 270 /**
 271 \typedef osThreadId_t
 272 \details Returned by:
 273 - \ref osThreadNew
 274 - \ref osThreadGetId
 275 - \ref osThreadEnumerate
 276 - \ref osMutexGetOwner
 277 */
 278
 279 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 280 /**
 281 \struct osThreadAttr_t
 282 \details
 283 Specifies the following attributes for the \ref osThreadNew function.
 284 */
 285
 286 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 287 /**
 288 \def osThreadJoinable
 289 \details
 290 A thread in this state can be joined using \ref osThreadJoin.
 291 */
 292
 293 /**
 294 \def osThreadDetached
 295 \details
 296 A thread in this state cannot be joined using \ref osThreadJoin.
 297 */
 298
 299 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 300 /**
 301 \fn osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr)
 302 \details
 303 The function \b osThreadNew starts a thread function by adding it to the list of active threads and sets it to state
 304 \ref ThreadStates "READY". Arguments for the thread function are passed using the parameter pointer \a *argument. When the priority of the
 305 created thread function is higher than the current \ref ThreadStates "RUNNING" thread, the created thread function starts instantly and
 306 becomes the new \ref ThreadStates "RUNNING" thread. Thread attributes are defined with the parameter pointer \a attr. Attributes include
 307 settings for thread priority, stack size, or memory allocation.
 308
 309 The function can be safely called before the RTOS is
 310 started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
 311
 312 The function \b osThreadNew returns the pointer to the thread object identifier or \token{NULL} in case of an error.
 313
 314 Possible \ref osThreadId_t return values:
 315 - pointer to the thread object, in case of success
 316 - \em NULL, if the priority level is outside the permitted range: \em osPriorityIdle ... \em osPriorityISR.
 317 - \em NULL, if the \em stack_mem is not \em NULL but:
 318   - \em stack_mem is not a multiple of 8 bytes
 319   - \em stack_size equals 0
 320 - \em NULL, if \em stack_size is lower smaller than 72 bytes
 321 - \em NULL, if \em stack_size is not zero and not a multiple of 8
 322 - \em NULL, if the control block (attr->cb_mem) is not large enough to hold a thread control block
 323 - \em NULL, if the control block (attr->cb_mem) is not 4 byte aligned
 324 - \em NULL, if the maximum number of threads have been created already
 325 - \em NULL, if the thread function \em func is \em NULL
 326 - \em 'osErrorISR', if IRQ is masked
 327 - \em 'osErrorISR', in IRQ mode.
 328
 329 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 330
 331 \b Code \b Example
 332
 333 Refer to the \ref thread_examples "Thread Examples" section.
 334 */
 335
 336 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 337 /**
 338 \fn const char *osThreadGetName (osThreadId_t thread_id)
 339 \details
 340 The function \b osThreadGetName returns the pointer to the name string of the thread identified by parameter \a thread_id or
 341 \token{NULL} in case of an error.
 342
 343 Possible return values:
 344 - pointer to the name string, in case of success
 345 - \em NULL, if no name has been defined
 346 - \em NULL, if a thread specified by \a thread_id does not exist
 347 - \em NULL, if thread_id is \em NULL.
 348
 349
 350 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 351
 352 <b>Code Example</b>
 353 \code
 354 void ThreadGetName_example (void)  {
 355   osThreadId_t thread_id = osThreadGetId ();
 356   const char* name = osThreadGetName (thread_id);
 357   if (name == NULL) {
 358     // Failed to get the thread name; not in a thread
 359   }
 360 }
 361 \endcode
 362 */
 363
 364 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 365 /**
 366 \fn osThreadId_t osThreadGetId (void)
 367 \details
 368 The function \b osThreadGetId returns the thread object ID of the currently running thread or NULL in case of an error.
 369
 370 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 371
 372 <b>Code Example</b>
 373 \code
 374 void ThreadGetId_example (void)  {
 375   osThreadId_t id;                                           // id for the currently running thread
 376
 377   id = osThreadGetId ();
 378   if (id == NULL) {
 379     // Failed to get the id; not in a thread
 380   }
 381 }
 382 \endcode
 383 */
 384 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 385 /**
 386 \fn osThreadState_t osThreadGetState (osThreadId_t thread_id)
 387 \details
 388 The function \b osThreadGetState returns the state of the thread identified by parameter \a thread_id. In case it fails or
 389 if it is called from an ISR, it will return \c osThreadError, otherwise it returns the thread state (refer to
 390 \ref osThreadState_t for the list of thread states).
 391
 392 Possible \ref osThreadState_t return values:
 393 - the state of the thread specified by \a thread_id, in case of success
 394 - \em 'osThreadError', if the thread specified by \a thread_id is \em NULL
 395
 396 - \em 'osThreadError', if if a thread specified by \a thread_id does not exist
 397 - \em 'osThreadError', if IRQ is masked
 398
 399 - \em 'osThreadError', if in IRQ mode.
 400
 401 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 402 */
 403
 404 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 405 /**
 406 \fn osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority)
 407 \details
 408 The function \b osThreadSetPriority changes the priority of an active thread specified by the parameter \a thread_id to the
 409 priority specified by the parameter \a priority.
 410
 411 Possible \ref osStatus_t return values:
 412 - \em 'osOK', if the priority of thread specified by \a thread_id  has been changed successfully
 413 - \em 'osErrorParameter', if the thread specified by \a thread_id is \em NULL
 414 - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
 415 - \em 'osErrorParameter', if \em osPriorityIdle < \em priority or \em priority > \em osPriorityISR
 416 - \em 'osErrorResource', if the thread is in state \em 'osThreadInactive' or \em 'osThreadTerminated'
 417 - \em 'osErrorISR', if IRQ is masked
 418 - \em 'osErrorISR', if in IRQ mode.
 419
 420 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 421
 422 <b>Code Example</b>
 423 \code
 424 #include "cmsis_os2.h"
 425
 426 void Thread_1 (void const *arg)  {                          // Thread function
 427   osThreadId_t id;                                          // id for the currently running thread
 428   osStatus_t   status;                                      // status of the executed function
 429
 430   :
 431   id = osThreadGetId ();                                    // Obtain ID of current running thread
 432
 433   status = osThreadSetPriority (id, osPriorityBelowNormal); // Set thread priority
 434   if (status == osOK)  {
 435     // Thread priority changed to BelowNormal
 436   }
 437   else {
 438     // Failed to set the priority
 439   }
 440   :
 441 }
 442 \endcode
 443 */
 444 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 445 /**
 446 \fn osPriority_t osThreadGetPriority (osThreadId_t thread_id)
 447 \details
 448 The function \b osThreadGetPriority returns the priority of an active thread specified by the parameter \a thread_id.
 449
 450 Possible \ref osPriority_t return values:
 451 - the priority of the thread specified by \em thread_id, in case of success
 452 - \em 'osPriorityError', if the threads specified by \em thread_id is in state \em 'osRtxObjectInactive' or \em 'osRtxObjectTerminated'
 453 - \em 'osPriorityError', if a thread specified by \em thread_id does not exist
 454 - \em 'osPriorityError', if the thread is \em NULL.
 455
 456 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 457
 458 <b>Code Example</b>
 459 \code
 460 #include "cmsis_os2.h"
 461
 462 void Thread_1 (void const *arg)  {                         // Thread function
 463   osThreadId_t id;                                         // id for the currently running thread
 464   osPriority_t priority;                                   // thread priority
 465
 466   id = osThreadGetId ();                                   // Obtain ID of current running thread
 467   priority = osThreadGetPriority (id);                     // Obtain the thread priority
 468 }
 469 \endcode
 470 */
 471 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 472 /**
 473 \fn osStatus_t osThreadYield (void)
 474 \details
 475 The function \b osThreadYield passes control to the next thread with the same priority that is in the \ref ThreadStates "READY" state.
 476 If there is no other thread with the same priority in state \ref ThreadStates "READY", then the current thread continues execution and
 477 no thread switch occurs. \b osThreadYield does not set the thread to state \ref ThreadStates "BLOCKED". Thus no thread with a lower
 478 priority will be scheduled even if threads in state \ref ThreadStates "READY" are available.
 479
 480 Possible \ref osStatus_t return values:
 481 - \em 'osOK', if control has been passed to the next thread successfully
 482 - \em 'osErrorISR', if IRQ is masked
 483 - \em 'osErrorISR', if in IRQ mode.
 484
 485
 486 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 487 \note This function <b>has no impact</b> when called when the kernel is locked, see \ref osKernelLock.
 488
 489 <b>Code Example</b>
 490 \code
 491 #include "cmsis_os2.h"
 492
 493 void Thread_1 (void const *arg)  {                         // Thread function
 494   osStatus_t   status;                                     // status of the executed function
 495   :
 496   while (1)  {
 497     status = osThreadYield();                              //
 498     if (status != osOK)  {
 499       // an error occurred
 500     }
 501   }
 502 }
 503 \endcode
 504 */
 505 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 506 /**
 507 \fn osStatus_t osThreadSuspend (osThreadId_t thread_id)
 508 \details
 509 The function \b osThreadSuspend suspends the execution of the thread identified by parameter \em thread_id. The thread is put
 510 into the \ref ThreadStates "BLOCKED" state (\ref osThreadBlocked). Suspending the running thread will cause a context switch to another
 511 thread in \ref ThreadStates "READY" state immediately. The suspended thread is not executed until explicitly resumed with the function \ref osThreadResume.
 512
 513 Threads that are already \ref ThreadStates "BLOCKED" are removed from any wait list and become ready when they are resumed.
 514 Thus it is not recommended to suspend an already blocked thread.
 515
 516 Possible \ref osStatus_t return values:
 517  - \em 'osOK', if the thread has been suspended successfully
 518  - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
 519  - \em 'osErrorParameter', if the thread specified by \a thread_id is NULL
 520
 521  - \em 'osErrorResource', if no thread is in state \em 'osRtxThreadReady' or the kernel is not running
 522
 523  - \em 'osErrorResource', the the thread specified by \a thread_id is in state \em 'osRtxThreadInactive'
 524
 525  - \em 'osErrorResource', the the thread specified by \a thread_id is in state \em 'osRtxThreadTerminated'
 526
 527  - \em 'osErrorISR', if IRQ is masked
 528
 529  - \em 'osErrorISR', if in IRQ mode.
 530
 531
 532 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 533 \note This function <b>must not</b> be called to suspend the running thread when the kernel is locked, i.e. \ref osKernelLock.
 534
 535 */
 536
 537 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 538 /**
 539 \fn osStatus_t osThreadResume (osThreadId_t thread_id)
 540 \details
 541 The function \b osThreadResume puts the thread identified by parameter \em thread_id (which has to be in \ref ThreadStates "BLOCKED" state)
 542 back to the \ref ThreadStates "READY" state. If the resumed thread has a higher priority than the running thread a context switch occurs immediately.
 543
 544 The thread becomes ready regardless of the reason why the thread was blocked. Thus it is not recommended to resume a thread not suspended
 545 by \ref osThreadSuspend.
 546
 547 Functions that will put a thread into \ref ThreadStates "BLOCKED" state are:
 548 \ref osEventFlagsWait and \ref osThreadFlagsWait,
 549 \ref osDelay and \ref osDelayUntil,
 550 \ref osMutexAcquire and \ref osSemaphoreAcquire,
 551 \ref osMessageQueueGet,
 552 \ref osMemoryPoolAlloc,
 553 \ref osThreadJoin,
 554 \ref osThreadSuspend.
 555
 556 Possible \ref osStatus_t return values:
 557  - \em 'osOK', if the thread specified by \a thread_id has been resumed successfully
 558  - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
 559  - \em 'osErrorParameter', if the thread specified by \a thread_id is \em NULL
 560  - \em 'osErrorResource', if the state of the thread specified by \a thread_id is not 'Blocked'.
 561  - \em 'osErrorISR', if IRQ is masked
 562  - \em 'osErrorISR', in IRQ mode.
 563
 564 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 565 \note This function <b>may be</b> called when kernel is locked (\ref osKernelLock). Under this circumstances
 566         a potential context switch is delayed until the kernel gets unlocked, i.e. \ref osKernelUnlock or \ref osKernelRestoreLock.
 567
 568 */
 569
 570 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 571 /**
 572 \fn osStatus_t osThreadDetach (osThreadId_t thread_id)
 573 \details
 574 The function \b osThreadDetach changes the attribute of a thread (specified by \em thread_id) to \ref osThreadDetached.
 575 Detached threads are not joinable with \ref osThreadJoin. When a detached thread is terminated, all resources are returned to
 576 the system. The behavior of \ref osThreadDetach on an already detached thread is undefined.
 577
 578 Possible \ref osStatus_t return values:
 579  - \em 'osOK', if the attribute of the thread specified by \a thread_id has been changed to detached successfully.
 580  - \em 'osErrorParameter', if \em thread_id is \em NULL
 581  - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
 582  - \em 'osErrorResource', if the thread is in state \em 'osRtxThreadInactive'
 583  - \em 'osErrorResource', if the thread is marked as \em 'osThreadDetached'
 584  - \em 'osErrorISR', if IRQ is masked
 585  - \em 'osErrorISR', if in IRQ mode.
 586
 587
 588 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 589 */
 590
 591 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 592 /**
 593 \fn osStatus_t osThreadJoin (osThreadId_t thread_id)
 594 \details
 595 The function \b osThreadJoin waits for the thread specified by \em thread_id to terminate. If that thread has already
 596 terminated, then \ref osThreadJoin returns immediately. The thread must be joinable. By default threads are created with the
 597 attribute \ref osThreadDetached.
 598
 599 Possible \ref osStatus_t return values:
 600    - \em 'osOK', in case of success
 601    - \em 'osErrorParameter', if the thread is \em NULL
 602    - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
 603    - \em 'osErrorResource', if the thread specified by \a thread_id is marked as not joinable
 604
 605    - \em 'osErrorResource', if the state of the thread is \em 'osRtxThreadInactive' or \em 'osRtxThreadRunning'
 606    - \em 'osErrorResource', if the kernel is not running
 607    - \em 'osErrorISR', if IRQ is masked
 608
 609    - \em 'osErrorISR', if in IRQ mode.
 610
 611 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 612 */
 613
 614 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 615 /**
 616 \fn __NO_RETURN void osThreadExit (void)
 617 \details
 618
 619 The function \b osThreadExit terminates the calling thread. This allows the thread to be synchronized with \ref osThreadJoin.
 620
 621 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 622
 623 \b Code \b Example
 624 \code
 625 __NO_RETURN void worker (void *argument) {
 626   // do something
 627   osDelay(1000);
 628   osThreadExit();
 629 }
 630 \endcode
 631 */
 632
 633 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 634 /**
 635 \fn osStatus_t osThreadTerminate (osThreadId_t thread_id)
 636 \details
 637 The function \b osThreadTerminate removes the thread specified by parameter \a thread_id from the list of active threads. If
 638 the thread is currently \ref ThreadStates "RUNNING", the thread terminates and the execution continues with the next \ref ThreadStates "READY" thread. If no
 639 such thread exists, the function will not terminate the running thread, but return \em osErrorResource.
 640
 641 Possible \ref osStatus_t return values:
 642 - \em 'osOK', if the thread specified by \a thread_id has been removed from the active thread list successfully
 643 - \em 'osErrorParameter', if the thread specified by \a thread_id does not exist
 644 - \em 'osErrorParameter', if a thread with \em thread_id is \em NULL
 645 - \em 'osErrorResource', if the thread is in state \em 'osRtxThreadInactive' or \em 'osRtxThreadTerminated'
 646 - \em 'osErrorResource', if no thread is in state \em 'osRtxThreadReady' that can run next
 647 - \em 'osErrorResource', if the kernel is not running
 648 - \em 'osErrorISR', if IRQ is masked
 649
 650 - \em 'osErrorISR', if in IRQ mode.
 651
 652
 653 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 654 \note Avoid calling the function with a \em thread_id that does not exist or has been terminated already.
 655
 656 <b>Code Example</b>
 657 \code
 658 #include "cmsis_os2.h"
 659
 660 void Thread_1 (void *arg);                             // function prototype for Thread_1
 661
 662 void ThreadTerminate_example (void) {
 663   osStatus_t status;
 664   osThreadId_t id;
 665
 666   id = osThreadNew (Thread_1, NULL, NULL);             // create the thread
 667                                                        // do something
 668   status = osThreadTerminate (id);                     // stop the thread
 669   if (status == osOK) {
 670                                                        // Thread was terminated successfully
 671     }
 672   else {
 673                                                        // Failed to terminate a thread
 674     }
 675 }
 676 \endcode
 677 */
 678
 679 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 680 /**
 681 \fn uint32_t osThreadGetStackSize (osThreadId_t thread_id)
 682 \details
 683 The function \b osThreadGetStackSize returns the stack size of the thread specified by parameter \a thread_id. In case of an
 684 error, it returns \token{0}.
 685 /*
 686 New definition
 687 */
 688 Possible return values:
 689 - the stack size of the thread
 690 - \em 0, if a thread specified by \a thread_id does not exist
 691 - \em 0, if the thread specified by \em thread_id is \em NULL
 692 - \em 0, if the thread is in state \em 'osRtxObjectInactive'
 693 - \em 0, if IRQ is masked
 694 - \em 0, if in IRQ mode.
 695
 696
 697 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 698 */
 699
 700 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 701 /**
 702 \fn uint32_t osThreadGetStackSpace (osThreadId_t thread_id);
 703 \details
 704 The function \b osThreadGetStackSpace returns the size of unused stack space for the thread specified by parameter
 705 \a thread_id. Stack watermark recording during execution needs to be enabled (refer to \ref threadConfig). In case of an
 706 error, it returns \token{0}.
 707
 708 Possible return values:
 709 - the size of unused stack space, in case of success
 710 - \em 0, if a thread specified by \a thread_id does not exist
 711 - \em 0, if the thread with \em thread_id is \em NULL
 712 - \em 0, if the thread is in state \em 'osRtxObjectInactive'
 713 - \em 0, if stack watermark is not enabled
 714 - \em 0, if IRQ is masked
 715 - \em 0, if in IRQ mode
 716
 717
 718 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 719 */
 720
 721 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 722 /**
 723 \fn uint32_t osThreadGetCount (void)
 724 \details
 725 The function \b osThreadGetCount returns the number of active threads or \token{0} in case of an error.
 726
 727 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 728 */
 729
 730 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 731 /**
 732 \fn uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items)
 733 \details
 734 The function \b osThreadEnumerate returns the number of enumerated threads or \token{0} in case of an error.
 735
 736 Possible return values:
 737 - number of enumerated threads, in case of success
 738 - \em 0, if \em thread_array is \em NULL
 739 - \em 0, if \em array_items = 0
 740 - \em 0, if IRQ is masked
 741 - \em 0, if in IRQ mode.
 742
 743 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 744 */
 745
 746 /// @}
 747
 748
 749 // these struct members must stay outside the group to avoid double entries in documentation
 750 /**
 751 \var osThreadAttr_t::attr_bits
 752 \details
 753 The following bit masks can be used to set options:
 754  - \ref osThreadDetached : create thread in a detached mode (default).
 755  - \ref osThreadJoinable : create thread in \ref joinable_threads "joinable mode".
 756
 757 \var osThreadAttr_t::cb_mem
 758 \details
 759 Pointer to a memory for the thread control block object. Refer to \ref StaticObjectMemory for more information.
 760
 761 Default: \token{NULL} to use \ref CMSIS_RTOS_MemoryMgmt_Automatic for the thread control block.
 762
 763 \var osThreadAttr_t::cb_size
 764 \details
 765 The size (in bytes) of memory block passed with \ref cb_mem. For RTX, the minimum value is defined with \ref osRtxThreadCbSize (higher values are permitted).
 766
 767 Default: \token{0} as the default is no memory provided with \ref cb_mem.
 768
 769 \var osThreadAttr_t::name
 770 \details
 771 Pointer to a constant string with a human readable name (displayed during debugging) of the thread object.
 772
 773 Default: \token{NULL} no name specified (debugger may display function name instead).
 774
 775 \var osThreadAttr_t::priority
 776 \details
 777 Specifies the initial thread priority with a value from #osPriority_t.
 778
 779 Default: \token{osPriorityNormal}.
 780
 781 \var osThreadAttr_t::reserved
 782 \details
 783 Reserved for future use.
 784
 785 \var osThreadAttr_t::stack_mem
 786 \details
 787 Pointer to a memory location for the thread stack (64-bit aligned).
 788
 789 Default: \token{NULL} to allocate stack from a fixed-size memory pool using \ref ThreadStack.
 790
 791 \var osThreadAttr_t::stack_size
 792 \details
 793 The size (in bytes) of the stack specified by \ref stack_mem.
 794
 795 Default: \token{0} as the default is no memory provided with \ref stack_mem.
 796
 797 \var osThreadAttr_t::tz_module
 798 \details
 799 TrustZone Thread Context Management Identifier to allocate context memory for threads. The RTOS kernel that runs in
 800 non-secure state calls the interface functions defined by the header file TZ_context.h. Can safely be set to zero
 801 for threads not using secure calls at all.
 802 See <a href="../../Core/html/group__context__trustzone__functions.html">TrustZone RTOS Context Management</a>.
 803
 804 Default: token{0} not thread context specified.
 805
 806 */