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 \b 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 \b READY state. Once the \b RUNNING thread has terminated, or is
  20    \b BLOCKED, the next \b READY thread with the highest priority becomes the \b RUNNING thread.
  21  - \b BLOCKED: Threads that are blocked either delayed, waiting for an event to occur or suspended are in the \b BLOCKED
  22    state.
  23  - \b TERMINATED: When \ref osThreadTerminate is called, threads are \b 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 \b 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 \b READY or \b RUNNING state
  32    (depending on the thread priority).
  33  - CMSIS-RTOS is pre-emptive. The active thread with the highest priority becomes the \b 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 \b RUNNING thread transfers into the \b 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 \b 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 Thread Examples
  45 ===============
  46 The following examples show various scenarios to create threads:
  47
  48 <b>Example 1 - Create a simple thread</b>
  49
  50 Create a thread out of the function thread1 using all default values for thread attributes and memory from the
  51 \ref GlobalMemoryPool.
  52
  53 \code
  54 __NO_RETURN void thread1 (void *argument) {
  55   // ...
  56   for (;;) {}
  57 }
  58
  59 int main (void) {
  60   osKernelInitialize();
  61   ;
  62   osThreadNew(thread1, NULL, NULL);    // Create thread with default settings
  63   ;
  64   osKernelStart();
  65 }
  66 \endcode
  67
  68 <b>Example 2 - Create thread with stack non-default stack size</b>
  69
  70 Similar to the simple thread all attributes are default. The stack is dynamically allocated from the \ref GlobalMemoryPool
  71
  72 \ref osThreadAttr_t.stack_size is used to pass the stack size in Bytes to osThreadNew.
  73
  74 \code
  75 __NO_RETURN void thread1 (void *argument) {
  76   // ...
  77   for (;;) {}
  78 }
  79
  80 const osThreadAttr_t thread1_attr = {
  81   .stack_size = 1024                             // Create the thread stack with a size of 1024 bytes
  82 };
  83
  84 int main (void) {
  85   ;
  86   osThreadNew(thread1, NULL, &thread1_attr);     // Create thread with custom sized stack memory
  87   ;
  88 }
  89 \endcode
  90
  91 <b>Example 3 - Create thread with statically allocated stack</b>
  92
  93 Similar to the simple thread all attributes are default. The stack is statically allocated using the \c uint64_t array
  94 \c thread1_stk_1. This allocates 64*8 Bytes (=512 Bytes) with an alignment of 8 Bytes (mandatory for Cortex-M stack memory).
  95
  96 \ref osThreadAttr_t.stack_mem holds a pointer to the stacks lowest address.
  97
  98 \ref osThreadAttr_t.stack_size is used to pass the stack size in Bytes to osThreadNew.
  99
 100 \code
 101 __NO_RETURN void thread1 (void *argument) {
 102   // ...
 103   for (;;) {}
 104 }
 105
 106 static uint64_t thread1_stk_1[64];
 107
 108 const osThreadAttr_t thread1_attr = {
 109   .stack_mem  = &thread1_stk_1[0],
 110   .stack_size = sizeof(thread1_stk_1)
 111 };
 112
 113 int main (void) {
 114   ;
 115   osThreadNew(thread1, NULL, &thread1_attr);    // Create thread with statically allocated stack memory
 116   ;
 117 }
 118 \endcode
 119
 120 <b>Example 4 - Thread with statically allocated task control block</b>
 121
 122 Typically this method is chosen together with a statically allocated stack as shown in Example 2.
 123 \code
 124 #include "cmsis_os2.h"
 125
 126 //include rtx_os.h for types of RTX objects
 127 #include "rtx_os.h"
 128
 129 __NO_RETURN void thread1 (void *argument) {
 130   // ...
 131   for (;;) {}
 132 }
 133
 134 static osRtxThread_t thread1_tcb;
 135
 136 const osThreadAttr_t thread1_attr = {
 137   .cb_mem  = &thread1_tcb,
 138   .cb_size = sizeof(thread1_tcb),
 139 };
 140
 141 int main (void) {
 142   ;
 143   osThreadNew(thread1, NULL, &thread1_attr);    // Create thread with custom tcb memory
 144   ;
 145 }
 146 \endcode
 147
 148 <b>Example 5 - Create thread with a different priority</b>
 149
 150 The default priority of RTX is \ref osPriorityNormal. Often you want to run a task with a higher or lower priority. Using the
 151 \ref osThreadAttr_t control structure you can set any initial priority required.
 152
 153 \code
 154 __NO_RETURN void thread1 (void *argument) {
 155   // ...
 156   for (;;) {}
 157 }
 158
 159 const osThreadAttr_t thread1_attr = {
 160   .priority = osPriorityHigh            //Set initial thread priority to high
 161 };
 162
 163 int main (void) {
 164   ;
 165   osThreadNew(thread1, NULL, &thread1_attr);
 166   ;
 167 }
 168 \endcode
 169
 170 <b>Example 6 - Joinable threads</b>
 171
 172 In this example a master thread creates four threads with the \ref osThreadJoinable attribute. These will do some work and
 173 return using the \ref osThreadExit call after finished. \ref osThreadJoin is used to synchronize the thread termination.
 174
 175
 176 \code
 177 __NO_RETURN void worker (void *argument) {
 178     ; // work a lot on data[]
 179     osDelay(1000);
 180     osThreadExit();
 181 }
 182
 183 __NO_RETURN void thread1 (void *argument) {
 184   osThreadAttr_t worker_attr;
 185   osThreadId_t worker_ids[4];
 186   uint8_t data[4][10];
 187
 188   memset(&worker_attr, 0, sizeof(worker_attr));
 189   worker_attr.attr_bits = osThreadJoinable;
 190
 191   worker_ids[0] = osThreadNew(worker, &data[0][0], &worker_attr);
 192   worker_ids[1] = osThreadNew(worker, &data[1][0], &worker_attr);
 193   worker_ids[2] = osThreadNew(worker, &data[2][0], &worker_attr);
 194   worker_ids[3] = osThreadNew(worker, &data[3][0], &worker_attr);
 195
 196   osThreadJoin(worker_ids[0]);
 197   osThreadJoin(worker_ids[1]);
 198   osThreadJoin(worker_ids[2]);
 199   osThreadJoin(worker_ids[3]);
 200
 201   osThreadExit();
 202 }
 203 \endcode
 204
 205 @{
 206 */
 207 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 208 /**
 209 \enum osThreadState_t
 210 \details
 211 State of a thread as retrieved by \ref osThreadGetState. In case \b osThreadGetState fails or if it is called from an ISR, it
 212 will return \c osThreadError, otherwise it returns the thread state.
 213 */
 214
 215 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 216 /**
 217 \enum osPriority_t
 218 \details
 219
 220 The \b osPriority_t value specifies the priority for a thread. The default thread priority should be \a osPriorityNormal.
 221 If a Thread is active that has a higher priority than the currently executing thread, then a thread switch occurs immediately
 222 to execute the new task.
 223
 224 To prevent from a priority inversion, a CMSIS-RTOS compliant OS may optionally implement a <b>priority inheritance</b>
 225 method. A priority inversion occurs when a high priority thread is waiting for a resource or event that is controlled by a
 226 thread with a lower priority.
 227
 228 \note Priority inheritance only applies to mutexes.
 229 */
 230
 231 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 232 /**
 233 \typedef void (*osThreadFunc_t) (void *argument)
 234 \details
 235 */
 236
 237 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 238 /**
 239 \typedef osThreadId_t
 240 */
 241
 242 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 243 /**
 244 \struct osThreadAttr_t
 245 */
 246
 247 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 248 /**
 249 \def osThreadJoinable
 250 \details
 251
 252 See \ref osThreadJoin.
 253 */
 254
 255 /**
 256 \def osThreadDetached
 257 \details
 258
 259 A thread in this state cannot be joined using \ref osThreadJoin.
 260
 261 */
 262 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 263 /**
 264 \fn osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr)
 265 \details
 266 The function \b osThreadNew starts a thread function by adding it to the list of active threads and sets it to state
 267 \b READY. Arguments for the thread function are passed using the parameter pointer \a *argument. When the priority of the
 268 created thread function is higher than the current \b RUNNING thread, the created thread function starts instantly and
 269 becomes the new \b RUNNING thread. Thread attributes are defined with the parameter pointer \a attr. Attributes include
 270 settings for thread priority, stack size, or memory allocation.
 271
 272 The function \b osThreadNew returns the pointer to the thread object identifier or \token{NULL} in case of an error.
 273
 274 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 275 */
 276
 277 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 278 /**
 279 \fn const char *osThreadGetName (osThreadId_t thread_id)
 280 \details
 281 The function \b osThreadGetName returns the pointer to the name string of the thread identified by parameter \a thread_id or
 282 \token{NULL} in case of an error.
 283
 284 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 285
 286 <b>Code Example</b>
 287 \code
 288 void ThreadGetName_example (void)  {
 289   char id;                                           // id for the currently running thread
 290
 291   id = osThreadGetName ();
 292   if (id == NULL) {
 293     // Failed to get the thread name; not in a thread
 294   }
 295 }
 296 \endcode
 297 */
 298
 299 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 300 /**
 301 \fn osThreadId_t osThreadGetId (void)
 302 \details
 303 The function \b osThreadGetId returns the thread object ID of the currently running thread or NULL in case of an error.
 304
 305 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 306
 307 <b>Code Example</b>
 308 \code
 309 void ThreadGetId_example (void)  {
 310   osThreadId_t id;                                           // id for the currently running thread
 311
 312   id = osThreadGetId ();
 313   if (id == NULL) {
 314     // Failed to get the id; not in a thread
 315   }
 316 }
 317 \endcode
 318 */
 319 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 320 /**
 321 \fn osThreadState_t osThreadGetState (osThreadId_t thread_id)
 322 \details
 323 The function \b osThreadGetState returns the state of the thread identified by parameter \a thread_id. In case it fails or
 324 if it is called from an ISR, it will return \c osThreadError, otherwise it returns the thread state (refer to
 325 \ref osThreadState_t for the list of thread states).
 326
 327 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 328 */
 329
 330 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 331 /**
 332 \fn osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority)
 333 \details
 334 The function \b osThreadSetPriority changes the priority of an active thread specified by the parameter \a thread_id to the
 335 priority specified by the parameter \a priority.
 336
 337 Possible \ref osStatus_t return values:
 338     - \em osOK: the priority of the specified thread has been changed successfully.
 339     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid or \a priority is incorrect.
 340     - \em osErrorResource: thread specified by parameter \em thread_id is in an invalid thread state.
 341     - \em osErrorISR: the function \b osThreadSetPriority cannot be called from interrupt service routines.
 342
 343 <b>Code Example</b>
 344 \code
 345 #include "cmsis_os2.h"
 346
 347 void Thread_1 (void const *arg)  {                          // Thread function
 348   osThreadId_t id;                                          // id for the currently running thread
 349   osStatus_t   status;                                      // status of the executed function
 350
 351   :
 352   id = osThreadGetId ();                                    // Obtain ID of current running thread
 353
 354   status = osThreadSetPriority (id, osPriorityBelowNormal); // Set thread priority
 355   if (status == osOK)  {
 356     // Thread priority changed to BelowNormal
 357   }
 358   else {
 359     // Failed to set the priority
 360   }
 361   :
 362 }
 363 \endcode
 364 */
 365 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 366 /**
 367 \fn osPriority_t osThreadGetPriority (osThreadId_t thread_id)
 368 \details
 369 The function \b osThreadGetPriority returns the priority of an active thread specified by the parameter \a thread_id.
 370
 371 Possible \ref osPriority_t return values:
 372     - \em priority: the priority of the specified thread.
 373     - \em osPriorityError: priority cannot be determined or is illegal.
 374     - \em osPriorityErrorISR: the function \b osThreadGetPriority cannot be called from interrupt service routines.
 375
 376 <b>Code Example</b>
 377 \code
 378 #include "cmsis_os2.h"
 379
 380 void Thread_1 (void const *arg)  {                         // Thread function
 381   osThreadId_t id;                                         // id for the currently running thread
 382   osPriority_t priority;                                   // thread priority
 383
 384   id = osThreadGetId ();                                   // Obtain ID of current running thread
 385   priority = osThreadGetPriority (id);                     // Obtain the thread priority
 386 }
 387 \endcode
 388 */
 389 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 390 /**
 391 \fn osStatus_t osThreadYield (void)
 392 \details
 393 The function \b osThreadYield passes control to the next thread that is in the \b READY state. If there is no other thread in
 394 state \b READY, then the current thread continues execution and no thread switching occurs.
 395
 396 Possible \ref osStatus_t return values:
 397     - \em osOK: control has been passed to the next thread successfully.
 398     - \em osError: an unspecified error has occurred.
 399     - \em osErrorISR: the function \b osThreadYield cannot be called from interrupt service routines.
 400
 401 <b>Code Example</b>
 402 \code
 403 #include "cmsis_os2.h"
 404
 405 void Thread_1 (void const *arg)  {                         // Thread function
 406   osStatus_t   status;                                     // status of the executed function
 407   :
 408   while (1)  {
 409     status = osThreadYield();                              //
 410     if (status != osOK)  {
 411       // an error occurred
 412     }
 413   }
 414 }
 415 \endcode
 416 */
 417 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 418 /**
 419 \fn osStatus_t osThreadSuspend (osThreadId_t thread_id)
 420 \details
 421 The function \b osThreadSuspend suspends the execution of the thread identified by parameter \em thread_id. The thread is put
 422 into the \em BLOCKED state (\ref osThreadBlocked). The thread is not executed until restarted with the function
 423 \ref osThreadResume. Threads that are already \em BLOCKED are suspended and become ready after they are resumed.
 424
 425 Possible \ref osStatus_t return values:
 426     - \em osOK: the thread has been suspended successfully.
 427     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 428     - \em osErrorResource: thread specified by parameter \em thread_id is in an invalid thread state.
 429     - \em osErrorISR: the function \b osThreadSuspend cannot be called from interrupt service routines.
 430 */
 431
 432 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 433 /**
 434 \fn osStatus_t osThreadResume (osThreadId_t thread_id)
 435 \details
 436 The function \b osThreadResume forces a thread (specified with \em thread_id) in \em BLOCKED state to resume operation.
 437
 438 Functions that will put a thread into \em BLOCKED state are:
 439 \ref osEventFlagsWait and \ref osThreadFlagsWait,
 440 \ref osDelay and \ref osDelayUntil,
 441 \ref osMutexAcquire and \ref osSemaphoreAcquire,
 442 \ref osMessageQueueGet,
 443 \ref osMemoryPoolAlloc,
 444 \ref osThreadJoin,
 445 \ref osThreadSuspend.
 446
 447 Possible \ref osStatus_t return values:
 448     - \em osOK: the thread has been resumed successfully.
 449     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 450     - \em osErrorResource: thread specified by parameter \em thread_id is in an invalid thread state.
 451     - \em osErrorISR: the function \b osThreadResume cannot be called from interrupt service routines.
 452 */
 453
 454 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 455 /**
 456 \fn osStatus_t osThreadDetach (osThreadId_t thread_id)
 457 \details
 458 The function \b osThreadDetach changes the attribute of a thread (specified by \em thread_id) to \ref osThreadDetached.
 459 Detached threads are not joinable with \ref osThreadJoin. When a detached thread is terminated, all resources are returned to
 460 the system. The behavior of \ref osThreadDetach on an already detached thread is undefined.
 461
 462 Possible \ref osStatus_t return values:
 463     - \em osOK: the attribute of the specified thread has been changed to detached successfully.
 464     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 465     - \em osErrorResource: thread specified by parameter \em thread_id is in an invalid thread state.
 466     - \em osErrorISR: the function \b osThreadDetach cannot be called from interrupt service routines.
 467 */
 468
 469 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 470 /**
 471 \fn osStatus_t osThreadJoin (osThreadId_t thread_id)
 472 \details
 473 The function \b osThreadJoin waits for the thread specified by \em thread_id to terminate. If that thread has already
 474 terminated, then \ref osThreadJoin returns immediately. The thread must be joinable. By default threads are created with the
 475 attribute \ref osThreadJoinable.
 476
 477 Possible \ref osStatus_t return values:
 478     - \em osOK: if the thread has already been terminated and joined or once the thread has been terminated and the join
 479       operations succeeds.
 480     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 481     - \em osErrorResource: parameter \em thread_id is \token{NULL} or refers to a thread that is not an active thread or the
 482       thread is not joinable.
 483     - \em osErrorISR: the function \b osThreadJoin cannot be called from interrupt service routines.
 484 */
 485
 486 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 487 /**
 488 \fn __NO_RETURN void osThreadExit (void)
 489 \details
 490
 491 The function \b osThreadExit terminates the calling thread. This allows the thread to be synchronized with \ref osThreadJoin.
 492
 493 \b Code \b Example
 494 \code
 495 __NO_RETURN void worker (void *argument) {
 496   // do something
 497   osDelay(1000);
 498   osThreadExit();
 499 }
 500 \endcode
 501 */
 502
 503 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 504 /**
 505 \fn osStatus_t osThreadTerminate (osThreadId_t thread_id)
 506 \details
 507 The function \b osThreadTerminate removes the thread specified by parameter \a thread_id from the list of active threads. If
 508 the thread is currently \b RUNNING, the thread terminates and the execution continues with the next \b READY thread. If no
 509 such thread exists, the function will not terminate the running thread, but return \em osErrorResource.
 510
 511 Possible \ref osStatus_t return values:
 512     - \em osOK: the specified thread has been removed from the active thread list successfully.
 513     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 514     - \em osErrorResource: thread specified by parameter \em thread_id is in an invalid thread state or no
 515       other \b READY thread exists.
 516     - \em osErrorISR: the function \b osThreadTerminate cannot be called from interrupt service routines.
 517
 518 <b>Code Example</b>
 519 \code
 520 #include "cmsis_os2.h"
 521
 522 void Thread_1 (void *arg);                             // function prototype for Thread_1
 523
 524 void ThreadTerminate_example (void) {
 525   osStatus_t status;
 526   osThreadId_t id;
 527
 528   id = osThreadNew (Thread_1, NULL, NULL);             // create the thread
 529                                                        // do something
 530   status = osThreadTerminate (id);                     // stop the thread
 531   if (status == osOK) {
 532                                                        // Thread was terminated successfully
 533     }
 534   else {
 535                                                        // Failed to terminate a thread
 536     }
 537 }
 538 \endcode
 539 */
 540
 541 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 542 /**
 543 \fn uint32_t osThreadGetStackSize (osThreadId_t thread_id)
 544 \details
 545 The function \b osThreadGetStackSize returns the stack size of the thread specified by parameter \a thread_id. In case of an
 546 error, it returns \token{0}.
 547
 548 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 549 */
 550
 551 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 552 /**
 553 \fn uint32_t osThreadGetStackSpace (osThreadId_t thread_id);
 554 \details
 555 The function \b osThreadGetStackSpace returns the size of unused stack space for the thread specified by parameter
 556 \a thread_id. Stack watermark recording during execution needs to be enabled (refer to \ref threadConfig). In case of an
 557 error, it returns \token{0}.
 558
 559 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 560 */
 561
 562 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 563 /**
 564 \fn uint32_t osThreadGetCount (void)
 565 \details
 566 The function \b osThreadGetCount returns the number of active threads or \token{0} in case of an error.
 567
 568 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 569 */
 570
 571 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 572 /**
 573 \fn uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items)
 574 \details
 575 The function \b osThreadEnumerate returns the number of enumerated threads or \token{0} in case of an error.
 576
 577 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 578 */
 579
 580 /// @}
 581
 582
 583 // these struct members must stay outside the group to avoid double entries in documentation
 584 /**
 585 \var osThreadAttr_t::attr_bits
 586 \details
 587 The following predefined bit masks can be assigned to set options for a thread object.
 588
 589 Bit Mask                |   Description
 590 :-----------------------|:-----------------------------------------
 591 osThreadJoinable        | Thread is created in a join-able state.
 592 osThreadDetached        | Thread is created in a detached state (default).
 593
 594 \var osThreadAttr_t::cb_mem
 595 \details
 596 Pointer to a memory location for the thread object. This can optionally be used for custom memory management systems.
 597 Specify \token{NULL} to use the kernel memory management.
 598
 599 \var osThreadAttr_t::cb_size
 600 \details
 601 The size of the memory block passed with \ref cb_mem. Must be the size of a thread control block object or larger.
 602
 603 \var osThreadAttr_t::name
 604 \details
 605 String with a human readable name of the thread object.
 606
 607 \var osThreadAttr_t::priority
 608 \details
 609 Specifies the initial thread priority with a value from #osPriority_t.
 610
 611 \var osThreadAttr_t::reserved
 612 \details
 613 Reserved for future use. Must be \token{0}.
 614
 615 \var osThreadAttr_t::stack_mem
 616 \details
 617 Pointer to a memory location for the thread stack. This can optionally be used for custom memory management systems.
 618 Specify \token{NULL} to use the kernel memory management.
 619
 620 \var osThreadAttr_t::tz_module
 621 \details
 622 TrustZone Thread Context Management Identifier to allocate context memory for threads. The RTOS kernel that runs in
 623 non-secure state calls the interface functions defined by the header file TZ_context.h.
 624 See <a href="../../Core/html/group__context__trustzone__functions.html">TrustZone RTOS Context Management</a>.
 625
 626 \var osThreadAttr_t::stack_size
 627 \details
 628 The size of the stack specified by \ref stack_mem in Bytes.
 629 */