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