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 This function \b 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 This function \b 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 This function \b 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 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 344
 345 <b>Code Example</b>
 346 \code
 347 #include "cmsis_os2.h"
 348
 349 void Thread_1 (void const *arg)  {                          // Thread function
 350   osThreadId_t id;                                          // id for the currently running thread
 351   osStatus_t   status;                                      // status of the executed function
 352
 353   :
 354   id = osThreadGetId ();                                    // Obtain ID of current running thread
 355
 356   status = osThreadSetPriority (id, osPriorityBelowNormal); // Set thread priority
 357   if (status == osOK)  {
 358     // Thread priority changed to BelowNormal
 359   }
 360   else {
 361     // Failed to set the priority
 362   }
 363   :
 364 }
 365 \endcode
 366 */
 367 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 368 /**
 369 \fn osPriority_t osThreadGetPriority (osThreadId_t thread_id)
 370 \details
 371 The function \b osThreadGetPriority returns the priority of an active thread specified by the parameter \a thread_id.
 372
 373 Possible \ref osPriority_t return values:
 374     - \em priority: the priority of the specified thread.
 375     - \em osPriorityError: priority cannot be determined or is illegal. It is also returned when the function is called from
 376       \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 377
 378 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 379
 380 <b>Code Example</b>
 381 \code
 382 #include "cmsis_os2.h"
 383
 384 void Thread_1 (void const *arg)  {                         // Thread function
 385   osThreadId_t id;                                         // id for the currently running thread
 386   osPriority_t priority;                                   // thread priority
 387
 388   id = osThreadGetId ();                                   // Obtain ID of current running thread
 389   priority = osThreadGetPriority (id);                     // Obtain the thread priority
 390 }
 391 \endcode
 392 */
 393 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 394 /**
 395 \fn osStatus_t osThreadYield (void)
 396 \details
 397 The function \b osThreadYield passes control to the next thread that is in the \b READY state. If there is no other thread in
 398 state \b READY, then the current thread continues execution and no thread switching occurs.
 399
 400 Possible \ref osStatus_t return values:
 401     - \em osOK: control has been passed to the next thread successfully.
 402     - \em osError: an unspecified error has occurred.
 403     - \em osErrorISR: the function \b osThreadYield cannot be called from interrupt service routines.
 404
 405 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 406
 407 <b>Code Example</b>
 408 \code
 409 #include "cmsis_os2.h"
 410
 411 void Thread_1 (void const *arg)  {                         // Thread function
 412   osStatus_t   status;                                     // status of the executed function
 413   :
 414   while (1)  {
 415     status = osThreadYield();                              //
 416     if (status != osOK)  {
 417       // an error occurred
 418     }
 419   }
 420 }
 421 \endcode
 422 */
 423 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 424 /**
 425 \fn osStatus_t osThreadSuspend (osThreadId_t thread_id)
 426 \details
 427 The function \b osThreadSuspend suspends the execution of the thread identified by parameter \em thread_id. The thread is put
 428 into the \em BLOCKED state (\ref osThreadBlocked). The thread is not executed until restarted with the function
 429 \ref osThreadResume. Threads that are already \em BLOCKED are suspended and become ready after they are resumed.
 430
 431 Possible \ref osStatus_t return values:
 432     - \em osOK: the thread has been suspended successfully.
 433     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 434     - \em osErrorResource: thread specified by parameter \em thread_id is in an invalid thread state.
 435     - \em osErrorISR: the function \b osThreadSuspend cannot be called from interrupt service routines.
 436
 437 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 438 */
 439
 440 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 441 /**
 442 \fn osStatus_t osThreadResume (osThreadId_t thread_id)
 443 \details
 444 The function \b osThreadResume forces a thread (specified with \em thread_id) in \em BLOCKED state to resume operation.
 445
 446 Functions that will put a thread into \em BLOCKED state are:
 447 \ref osEventFlagsWait and \ref osThreadFlagsWait,
 448 \ref osDelay and \ref osDelayUntil,
 449 \ref osMutexAcquire and \ref osSemaphoreAcquire,
 450 \ref osMessageQueueGet,
 451 \ref osMemoryPoolAlloc,
 452 \ref osThreadJoin,
 453 \ref osThreadSuspend.
 454
 455 Possible \ref osStatus_t return values:
 456     - \em osOK: the thread has been resumed successfully.
 457     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 458     - \em osErrorResource: thread specified by parameter \em thread_id is in an invalid thread state.
 459     - \em osErrorISR: the function \b osThreadResume cannot be called from interrupt service routines.
 460
 461 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 462 */
 463
 464 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 465 /**
 466 \fn osStatus_t osThreadDetach (osThreadId_t thread_id)
 467 \details
 468 The function \b osThreadDetach changes the attribute of a thread (specified by \em thread_id) to \ref osThreadDetached.
 469 Detached threads are not joinable with \ref osThreadJoin. When a detached thread is terminated, all resources are returned to
 470 the system. The behavior of \ref osThreadDetach on an already detached thread is undefined.
 471
 472 Possible \ref osStatus_t return values:
 473     - \em osOK: the attribute of the specified thread has been changed to detached successfully.
 474     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 475     - \em osErrorResource: thread specified by parameter \em thread_id is in an invalid thread state.
 476     - \em osErrorISR: the function \b osThreadDetach cannot be called from interrupt service routines.
 477
 478 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 479 */
 480
 481 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 482 /**
 483 \fn osStatus_t osThreadJoin (osThreadId_t thread_id)
 484 \details
 485 The function \b osThreadJoin waits for the thread specified by \em thread_id to terminate. If that thread has already
 486 terminated, then \ref osThreadJoin returns immediately. The thread must be joinable. By default threads are created with the
 487 attribute \ref osThreadJoinable.
 488
 489 Possible \ref osStatus_t return values:
 490     - \em osOK: if the thread has already been terminated and joined or once the thread has been terminated and the join
 491       operations succeeds.
 492     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 493     - \em osErrorResource: parameter \em thread_id is \token{NULL} or refers to a thread that is not an active thread or the
 494       thread is not joinable.
 495     - \em osErrorISR: the function \b osThreadJoin cannot be called from interrupt service routines.
 496
 497 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 498 */
 499
 500 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 501 /**
 502 \fn __NO_RETURN void osThreadExit (void)
 503 \details
 504
 505 The function \b osThreadExit terminates the calling thread. This allows the thread to be synchronized with \ref osThreadJoin.
 506
 507 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 508
 509 \b Code \b Example
 510 \code
 511 __NO_RETURN void worker (void *argument) {
 512   // do something
 513   osDelay(1000);
 514   osThreadExit();
 515 }
 516 \endcode
 517 */
 518
 519 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 520 /**
 521 \fn osStatus_t osThreadTerminate (osThreadId_t thread_id)
 522 \details
 523 The function \b osThreadTerminate removes the thread specified by parameter \a thread_id from the list of active threads. If
 524 the thread is currently \b RUNNING, the thread terminates and the execution continues with the next \b READY thread. If no
 525 such thread exists, the function will not terminate the running thread, but return \em osErrorResource.
 526
 527 Possible \ref osStatus_t return values:
 528     - \em osOK: the specified thread has been removed from the active thread list successfully.
 529     - \em osErrorParameter: \a thread_id is \token{NULL} or invalid.
 530     - \em osErrorResource: thread specified by parameter \em thread_id is in an invalid thread state or no
 531       other \b READY thread exists.
 532     - \em osErrorISR: the function \b osThreadTerminate cannot be called from interrupt service routines.
 533
 534 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 535 \note Avoid calling the function with a \em thread_id that does not exist or has been terminated already.
 536
 537 <b>Code Example</b>
 538 \code
 539 #include "cmsis_os2.h"
 540
 541 void Thread_1 (void *arg);                             // function prototype for Thread_1
 542
 543 void ThreadTerminate_example (void) {
 544   osStatus_t status;
 545   osThreadId_t id;
 546
 547   id = osThreadNew (Thread_1, NULL, NULL);             // create the thread
 548                                                        // do something
 549   status = osThreadTerminate (id);                     // stop the thread
 550   if (status == osOK) {
 551                                                        // Thread was terminated successfully
 552     }
 553   else {
 554                                                        // Failed to terminate a thread
 555     }
 556 }
 557 \endcode
 558 */
 559
 560 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 561 /**
 562 \fn uint32_t osThreadGetStackSize (osThreadId_t thread_id)
 563 \details
 564 The function \b osThreadGetStackSize returns the stack size of the thread specified by parameter \a thread_id. In case of an
 565 error, it returns \token{0}.
 566
 567 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 568 */
 569
 570 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 571 /**
 572 \fn uint32_t osThreadGetStackSpace (osThreadId_t thread_id);
 573 \details
 574 The function \b osThreadGetStackSpace returns the size of unused stack space for the thread specified by parameter
 575 \a thread_id. Stack watermark recording during execution needs to be enabled (refer to \ref threadConfig). In case of an
 576 error, it returns \token{0}.
 577
 578 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 579 */
 580
 581 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 582 /**
 583 \fn uint32_t osThreadGetCount (void)
 584 \details
 585 The function \b osThreadGetCount returns the number of active threads or \token{0} in case of an error.
 586
 587 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 588 */
 589
 590 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 591 /**
 592 \fn uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items)
 593 \details
 594 The function \b osThreadEnumerate returns the number of enumerated threads or \token{0} in case of an error.
 595
 596 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 597 */
 598
 599 /// @}
 600
 601
 602 // these struct members must stay outside the group to avoid double entries in documentation
 603 /**
 604 \var osThreadAttr_t::attr_bits
 605 \details
 606 The following predefined bit masks can be assigned to set options for a thread object.
 607
 608 Bit Mask                |   Description
 609 :-----------------------|:-----------------------------------------
 610 osThreadJoinable        | Thread is created in a join-able state.
 611 osThreadDetached        | Thread is created in a detached state (default).
 612
 613 \var osThreadAttr_t::cb_mem
 614 \details
 615 Pointer to a memory location for the thread object. This can optionally be used for custom memory management systems.
 616 Specify \token{NULL} to use the kernel memory management.
 617
 618 \var osThreadAttr_t::cb_size
 619 \details
 620 The size of the memory block passed with \ref cb_mem. Must be the size of a thread control block object or larger.
 621
 622 \var osThreadAttr_t::name
 623 \details
 624 String with a human readable name of the thread object.
 625
 626 \var osThreadAttr_t::priority
 627 \details
 628 Specifies the initial thread priority with a value from #osPriority_t.
 629
 630 \var osThreadAttr_t::reserved
 631 \details
 632 Reserved for future use. Must be \token{0}.
 633
 634 \var osThreadAttr_t::stack_mem
 635 \details
 636 Pointer to a memory location for the thread stack. This can optionally be used for custom memory management systems.
 637 Specify \token{NULL} to use the kernel memory management.
 638
 639 \var osThreadAttr_t::tz_module
 640 \details
 641 TrustZone Thread Context Management Identifier to allocate context memory for threads. The RTOS kernel that runs in
 642 non-secure state calls the interface functions defined by the header file TZ_context.h.
 643 See <a href="../../Core/html/group__context__trustzone__functions.html">TrustZone RTOS Context Management</a>.
 644
 645 \var osThreadAttr_t::stack_size
 646 \details
 647 The size of the stack in Bytes.
 648 */