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