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 \todo MH: examples with control block memory and size supplied.
  42
  43 By using sizeof on the object control block.
  44
  45 For example RTX5 has the following internal defines (starting with os_ which is not RTOS prefix but rather RTX implementation prefix):
  46 /// Control Block sizes
  47 \#define os_ThreadCbSize         sizeof(os_thread_t)
  48 \#define os_TimerCbSize          sizeof(os_timer_t)
  49 \#define os_EventFlagsCbSize     sizeof(os_event_flags_t)
  50 \#define os_MutexCbSize          sizeof(os_mutex_t)
  51 \#define os_SemaphoreCbSize      sizeof(os_semaphore_t)
  52 \#define os_MemoryPoolCbSize     sizeof(os_memory_pool_t)
  53 \#define os_MessageQueueCbSize   sizeof(os_message_queue_t)
  54
  55
  56 @{
  57 */
  58 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  59 /**
  60 \enum osThreadState_t
  61 \details
  62
  63 */
  64 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  65 /**
  66 \enum osPriority_t
  67 \details
  68
  69 The \b osPriority_t value specifies the priority for a thread. The default thread priority should be \a osPriorityNormal.
  70 If a Thread is active that has a higher priority than the currently executing thread, then a thread switch occurs immediately
  71 to execute the new task.
  72
  73 To prevent from a priority inversion, a CMSIS-RTOS compliant OS may optionally implement a <b>priority inheritance</b> method.
  74 A priority inversion occurs when a high priority thread is waiting for a resource or event that is controlled by a thread
  75 with a lower priority.
  76
  77 \note
  78 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  79
  80 */
  81 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  82 /**
  83 \typedef void *(*os_thread_func_t) (void *argument)
  84 \details
  85
  86
  87 */
  88 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  89 /**
  90 \typedef osThreadId_t
  91
  92 */
  93 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  94 /**
  95 \struct osThreadAttr_t
  96
  97 */
  98 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  99 /**
 100 \def osThreadJoinable
 101 \details
 102
 103 */
 104 /**
 105 \def osThreadDetached
 106 \details
 107
 108 */
 109 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 110 /**
 111 \fn osThreadId_t osThreadNew (os_thread_func_t func, void *argument, const osThreadAttr_t *attr)
 112 \details
 113
 114 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
 115 using the parameter pointer \em *argument. When the priority of the created thread function is higher than the current \b RUNNING thread,
 116 the created thread function starts instantly and becomes the new \b RUNNING thread. Thread attributes are defined with the parameter pointer \em attr.
 117 Attributes include settings for thread priority, stack size, or memory allocation.
 118
 119 \note
 120 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 121
 122
 123 */
 124 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 125 /**
 126 \fn const char *osThreadGetName (osThreadId_t thread_id)
 127 \details
 128
 129 */
 130
 131 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 132 /**
 133 \fn osThreadId_t osThreadGetId (void)
 134 \details
 135
 136 Get the thread ID of the current running thread.
 137
 138 \note
 139 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 140
 141 \b Example:
 142 \code
 143 void ThreadGetId_example (void)  {
 144   osThreadId id;                                           // id for the currently running thread
 145
 146   id = osThreadGetId ();
 147   if (id == NULL) {
 148     // Failed to get the id; not in a thread
 149   }
 150 }
 151 \endcode
 152 */
 153 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 154 /**
 155 \fn osThreadState_t osThreadGetState (osThreadId_t thread_id)
 156 \details
 157
 158 Return the state of the thread identified by parameter \em thread_id.
 159 See \ref osThreadState_t for possible states.
 160
 161 */
 162 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 163 /**
 164 \fn osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority)
 165 \details
 166
 167 Change the priority of an active thread.
 168
 169 \ref osStatus_t return values:
 170     - \em osOK: the priority of the specified thread has been changed successfully.
 171     - \em osErrorParameter: the value of the parameter \em thread_id or parameter \em priority is incorrect.
 172     - \em osErrorResource: parameter \em thread_id refers to a thread that is not an active thread.
 173     - \em osErrorISR: the function \b osThreadSetPriority cannot be called from interrupt service routines.
 174
 175 \note
 176 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 177
 178 \b Example:
 179 \code
 180 #include "cmsis_os2.h"
 181
 182 void Thread_1 (void const *arg)  {                         // Thread function
 183   osThreadId_t id;                                         // id for the currently running thread
 184   osStatus   status;                                       // status of the executed function
 185
 186   :
 187   id = osThreadGetId ();                                   // Obtain ID of current running thread
 188
 189   if (id != NULL) {
 190     status = osThreadSetPriority (id, osPriorityBelowNormal);
 191     if (status == osOK)  {
 192       // Thread priority changed to BelowNormal
 193     }
 194     else {
 195       // Failed to set the priority
 196     }
 197   }
 198   else  {
 199     // Failed to get the id
 200   }
 201   :
 202 }
 203 \endcode
 204 */
 205 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 206 /**
 207 \fn osPriority_t osThreadGetPriority (osThreadId_t thread_id)
 208 \details
 209
 210 Get the priority of an active thread. In case of failure, the value \b osPriorityError is returned.
 211
 212 \note
 213 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 214
 215 \b Example:
 216 \code
 217 #include "cmsis_os2.h"
 218
 219 void Thread_1 (void const *arg)  {                         // Thread function
 220   osThreadId_t id;                                         // id for the currently running thread
 221   osPriority_t priority;                                   // thread priority
 222
 223   id = osThreadGetId ();                                   // Obtain ID of current running thread
 224
 225   if (id != NULL)  {
 226     priority = osThreadGetPriority (id);
 227   }
 228   else  {
 229     // Failed to get the id
 230   }
 231 }
 232 \endcode
 233 */
 234 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 235 /**
 236 \fn osStatus_t osThreadYield (void)
 237 \details
 238
 239 Pass control to the next thread that is in state \b READY. If there is no other thread in state \b READY,
 240 then the current thread continues execution and no thread switching occurs.
 241
 242 \note
 243 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 244
 245 \b Example:
 246 \code
 247 #include "cmsis_os2.h"
 248
 249 void Thread_1 (void const *arg)  {                         // Thread function
 250   osStatus_t   status;                                     // status of the executed function
 251   :
 252   while (1)  {
 253     status = osThreadYield();                              //
 254     if (status != osOK)  {
 255       // thread switch not occurred, not in a thread function
 256     }
 257   }
 258 }
 259 \endcode
 260 */
 261 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 262 /**
 263 \fn osStatus_t osThreadSuspend (osThreadId_t thread_id)
 264 \details
 265 Suspends execution of the thread identified by parameter \em thread_id. Thread is put into the state \em Blocked (\ref osThreadBlocked).
 266 The thread is not executed until restarted with the function \ref osThreadResume.
 267
 268 */
 269 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 270 /**
 271 \fn osStatus_t osThreadResume (osThreadId_t thread_id)
 272 \details
 273 Forces a thread in BLOCKED state, specified with \em thread_id, to resume operation.
 274 Functions that will put a thread into BLOCKED state are:
 275 \ref osEventFlagsWait and \ref osThreadFlagsWait,
 276 \ref osDelay and \ref osDelayUntil,
 277 \ref osMutexAcquire and \ref osSemaphoreAcquire,
 278 \ref osMessageQueueGet,
 279 \ref osThreadJoin,
 280 \ref osThreadSuspend.
 281
 282 */
 283 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 284 /**
 285 \fn osStatus_t osThreadDetach (osThreadId_t thread_id)
 286 \details
 287 Changes the attribute of a thread specified in \em thread_id to \ref osThreadDetached. Detached threads are not joinable with \ref osThreadJoin.
 288 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.
 289
 290 \todo : describe
 291
 292 \note
 293 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 294 */
 295 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 296 /**
 297 \fn osStatus_t osThreadJoin (osThreadId_t thread_id)
 298 \details
 299 Waits for the thread specified by \em thread_id to terminate.
 300 If that thread has already terminated, then \ref osThreadJoin returns immediately.
 301 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.
 302
 303 \note
 304 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 305
 306
 307 \b Example:
 308 \todo this example may not compile....  void *worker ???
 309 \code
 310 #include "cmsis_os2.h"
 311
 312 void *worker(void *arg)
 313 {
 314   .. // work work work
 315   return 0;
 316 }
 317
 318
 319 int join_threads(void)
 320 {
 321     osThreadId_t th1, th2;
 322
 323     th1 = osThreadNew(worker, &param, NULL);
 324     th2 = osThreadNew(worker, &param, NULL);
 325
 326     (void) osThreadJoin(th1, NULL);
 327     (void) osThreadJoin(th2, NULL);
 328     return 0;
 329 }
 330 \endcode
 331
 332 */
 333 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 334 /**
 335 \fn __NO_RETURN void osThreadExit (void)
 336 \details
 337
 338 Exit the \b RUNNING thread an exit point defined by parameter pointer \em exit_ptr.
 339
 340 \note
 341 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 342 */
 343 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 344 /**
 345 \fn osStatus_t osThreadTerminate (osThreadId_t thread_id)
 346 \details
 347 Remove the thread function from the active thread list. If the thread is currently /b RUNNING the execution stops and the thread
 348 terminates.
 349
 350 \note
 351 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 352
 353 \code
 354 #include "cmsis_os2.h"
 355
 356 void *Thread_1 (void c*arg);                           // function prototype for Thread_1
 357
 358 void ThreadTerminate_example (void) {
 359   osStatus_t status;
 360   osThreadId_t id;
 361
 362   id = osThreadNew (Thread_1, NULL, NULL);             // create the thread
 363   :
 364   status = osThreadTerminate (id);                     // stop the thread
 365   if (status == osOK) {
 366     // Thread was terminated successfully
 367   }
 368   else {
 369     // Failed to terminate a thread
 370   }
 371 }
 372 \endcode
 373 */
 374 /// @}
 375
 376
 377 // these struct members must stay outside the group to avoid double entries in documentation
 378 /**
 379 \var osThreadAttr_t::attr_bits
 380 \details
 381 The following predefined bit masks can be assigned to set options for a thread object.
 382
 383 Bit Mask                |   Description
 384 :-----------------------|:-----------------------------------------
 385 osThreadJoinable        | Thread is created in a join-able state (default).
 386 osThreadDettached       | Thread is created in a detached state.
 387
 388 \var osThreadAttr_t::cb_mem
 389 \details
 390 Pointer to a memory location for the thread object. This can optionally be used for custom memory management systems.
 391 Specify \token{NULL} to use the kernel memory management.
 392
 393 \var osThreadAttr_t::cb_size
 394 \details
 395 The size of the memory block passed with \ref cb_mem. Must be the size of a thread control block object or larger.
 396
 397 \var osThreadAttr_t::name
 398 \details
 399 String with a human readable name of the thread object.
 400
 401 \var osThreadAttr_t::priority
 402 \details
 403 Specifies the initial thread priority with a value from #osPriority_t.
 404
 405 \var osThreadAttr_t::reserved
 406 \details
 407 Reserved for future use. Must be \token{0}.
 408
 409 \var osThreadAttr_t::stack_mem
 410 \details
 411 Pointer to a memory location for the thread stack. This can optionally be used for custom memory management systems.
 412 Specify \token{NULL} to use the kernel memory management.
 413
 414 \var osThreadAttr_t::stack_size
 415 \details
 416 The size of the stack specified by \ref stack_mem in Bytes.
 417
 418 */