begriffs open source - cmsis/blob - CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Kernel.txt

   1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   2 //  ==== Kernel Control ====
   3 /**
   4 \addtogroup CMSIS_RTOS_KernelCtrl Kernel Information and Control
   5 \ingroup CMSIS_RTOS
   6 \brief Provides version/system information and starts/controls the RTOS Kernel.
   7 \details
   8 The kernel Information and Control function group allows to:
   9   - obtain information about the system and the underlying kernel.
  10   - obtain version information about the CMSIS-RTOS API.
  11   - initialize of the RTOS kernel for creating objects.
  12   - start the RTOS kernel and thread switching.
  13   - check the execution status of the RTOS kernel.
  14
  15 \note The kernel information and control functions cannot be called from
  16 \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  17 \note The kernel initialization for RTX5 is documented in \ref SystemStartup.
  18
  19 <b>Code Example</b>
  20 \code
  21 /*----------------------------------------------------------------------------
  22  * Application main thread
  23  *---------------------------------------------------------------------------*/
  24 void app_main (void *argument) {
  25
  26   // ...
  27   for (;;) {}
  28 }
  29
  30 int main (void) {
  31
  32   // System Initialization
  33   SystemCoreClockUpdate();
  34 #ifdef RTE_Compiler_EventRecorder
  35   // Initialize and start Event Recorder
  36   EventRecorderInitialize(EventRecordError, 1U);
  37 #endif
  38   // ...
  39
  40   osKernelInitialize();                 // Initialize CMSIS-RTOS
  41   osThreadNew(app_main, NULL, NULL);    // Create application main thread
  42   osKernelStart();                      // Start thread execution
  43   for (;;) {}
  44 }
  45 \endcode
  46 @{
  47 */
  48 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  49 /**
  50 \struct osVersion_t
  51 \details
  52 Identifies the underlying RTOS kernel and API version number. The version is represented in a combined decimal number in the
  53 format: major.minor.rev: mmnnnrrrr
  54
  55 Use \ref osKernelGetInfo to retrieve the version numbers.
  56 */
  57
  58 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  59 /**
  60 \enum osKernelState_t
  61 \details
  62 State of the kernel as retrieved by \ref osKernelGetState. In case \b osKernelGetState fails or if it is called from an ISR,
  63 it will return \c osKernelError, otherwise it returns the kernel state.
  64 */
  65
  66 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  67 /**
  68 \fn osStatus_t osKernelInitialize (void)
  69 \details
  70 The function \b osKernelInitialize initializes the RTOS Kernel. Before it is successfully executed, only the functions
  71 \ref osKernelGetInfo and \ref osKernelGetState may be called.
  72
  73 Possible \ref osStatus_t return values:
  74   - \em 'osOK', in case of success
  75   - \em 'osError', if the kernel is not in state \em 'osRtxKernelInactive'
  76
  77   - \em 'osError', if the thread stack size is lower than 64U+8U
  78
  79   - \em 'osError', if (osRtxConfig.isr_queue.data == NULL) || (osRtxConfig.isr_queue.max == 0U)
  80
  81   - \em 'osErrorISR', if IRQ is masked
  82
  83   - \em 'osErrorISR', if in IRQ mode.
  84
  85
  86 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  87
  88 <b> Code Example</b>
  89 \code
  90 #include "RTE_Components.h"
  91 #include  CMSIS_device_header
  92 #include "cmsis_os2.h"
  93
  94 /*----------------------------------------------------------------------------
  95  * Application main thread
  96  *---------------------------------------------------------------------------*/
  97 void app_main (void *argument) {
  98
  99   // ...
 100   for (;;) {}
 101 }
 102
 103 int main (void) {
 104
 105   // System Initialization
 106   SystemCoreClockUpdate();
 107   // ...
 108
 109   osKernelInitialize();                 // Initialize CMSIS-RTOS
 110   osThreadNew(app_main, NULL, NULL);    // Create application main thread
 111   osKernelStart();                      // Start thread execution
 112   for (;;) {}
 113 }
 114 \endcode
 115 */
 116
 117 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 118 /**
 119 \fn osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size)
 120 \details
 121 The function \b  osKernelGetInfo retrieves the API and kernel version of the underlying RTOS kernel and a human readable
 122 identifier string for the kernel. It can be safely called before the RTOS is initialized or started (call to
 123 \ref osKernelInitialize or \ref osKernelStart).
 124 The function shall return the first 'size' characters of of the kernel id in the output parameter id_buf.
 125
 126 Possible \ref osStatus_t return values:
 127 - \em 'osOK', in case of success
 128 - \em 'osErrorISR', if IRQ is masked
 129 - \em 'osErrorISR', if in IRQ mode.
 130
 131 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 132
 133 <b>Code Example</b>
 134 \code
 135 void info (void) {
 136   char infobuf[100];
 137   osVersion_t osv;
 138   osStatus_t status;
 139
 140   status = osKernelGetInfo(&osv, infobuf, sizeof(infobuf));
 141   if(status == osOK) {
 142     printf("Kernel Information: %s\r\n", infobuf);
 143     printf("Kernel Version    : %d\r\n", osv.kernel);
 144     printf("Kernel API Version: %d\r\n", osv.api);
 145   }
 146 }
 147 \endcode
 148 */
 149
 150 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 151 /**
 152 \fn osKernelState_t osKernelGetState (void)
 153 \details
 154 The function \b osKernelGetState returns the current state of the kernel and can be safely called before the RTOS is
 155 initialized or started (call to \ref osKernelInitialize or \ref osKernelStart).
 156
 157 Possible \ref osKernelState_t return values:
 158 - \ref osKernelError, if an unspecific error occurred
 159 - the kernel state otherwise.
 160
 161 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 162
 163 <b>Code Example</b>
 164 \code
 165 int main (void) {
 166   // System Initialization
 167   SystemCoreClockUpdate();
 168   // ...
 169   if(osKernelGetState() == osKernelInactive) {     // Is the kernel initialized?
 170      osKernelInitialize();                         // Initialize CMSIS-RTOS kernel
 171   }
 172   ;
 173 }
 174 \endcode
 175
 176 */
 177 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 178 /**
 179 \fn osStatus_t osKernelStart (void)
 180 \details
 181 The function \b osKernelStart starts the RTOS kernel and begins thread switching. It will not return to its calling function
 182 in case of success. Before it is successfully executed, only the functions \ref osKernelGetInfo, \ref osKernelGetState, and
 183 object creation functions (\b osXxxNew) may be called.
 184
 185 At least one initial thread should be created prior osKernelStart, see \ref osThreadNew.
 186
 187 Possible \ref osStatus_t return values:
 188 - \em 'osOk', in case of success
 189 - \em 'osError', if the kernel is not in state \em 'osRtxKernelReady'
 190 - \em 'osError', if no threads are in state \em 'osRtxThreadReady'
 191 - \em 'osError', if timer thread or idle thread could not be started
 192 - \em 'osError', if the RTOS tick could not be set up
 193 - \em 'osErrorISR', if IRQ is masked
 194 - \em 'osErrorISR', if in IRQ mode.
 195
 196
 197 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 198
 199 <b>Code Example</b>
 200 \code
 201 int main (void) {
 202   // System Initialization
 203   SystemCoreClockUpdate();
 204   // ...
 205   if(osKernelGetState() == osKernelInactive) {
 206     osKernelInitialize();
 207   }
 208   ; // ... Start Threads
 209   if (osKernelGetState() == osKernelReady) {        // If kernel is ready to run...
 210     osKernelStart();                                // ... start thread execution
 211     }
 212
 213   while(1);                                         // only reached in case of error
 214 }
 215 \endcode
 216 */
 217
 218 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 219 /**
 220 \fn int32_t osKernelLock (void)
 221 \details
 222 The function \b osKernelLock allows to lock all task switches. It returns the previous value of the lock state (\token{1} if
 223 it was locked, \token{0} if it was unlocked), or a negative number representing an error code otherwise (refer to
 224 \ref osStatus_t).
 225
 226 Possible return values:
 227 - \em
 228 1, if the kernel is locked
 229
 230 - \em 0, if the kernel is running
 231 - \em 'osErrorISR', if IRQ is masked
 232
 233 - \em 'osErrorISR', if in IRQ mode
 234 - \em 'osError', if an unspecified error occured.
 235
 236 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 237
 238 <b>Code Example</b>
 239 \code
 240   int32_t state = osKernelLock();
 241   // ... critical code
 242   osKernelRestore(state);
 243 \endcode
 244 */
 245
 246 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 247 /**
 248 \fn int32_t osKernelUnlock (void)
 249 \details
 250 The function \b osKernelUnlock resumes from \ref osKernelLock. It returns the previous value of the lock state (\token{1} if
 251 it was locked, \token{0} if it was unlocked), or a negative number representing an error code otherwise (refer to
 252 \ref osStatus_t).
 253
 254 Possible return values:
 255 - \em 1, if the state of the kernel is \em 'osRtxKernelLocked'
 256 - \em 0, if the state of the kernel is \em 'osRtxKernelRunning'
 257 - \em 'osError', if the kernel is not in state \em 'osRtxKernelLocked' and not in state \em 'osRtxKernelRunning'
 258 - \em 'osErrorISR', if IRQ is masked
 259 - \em 'osErrorISR', if in IRQ mode.
 260
 261
 262 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 263
 264 <b>Code Example</b>
 265 \code
 266   int32_t sl = osKernelLock();
 267   // ... critical code
 268   {
 269     int32_t su = osKernelUnlock();
 270     // ... uncritical code
 271     osKernelRestoreLock(su);
 272   }
 273   // ... critical code
 274   osKernelRestoreLock(sl);
 275 \endcode
 276 */
 277
 278 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 279 /**
 280 \fn int32_t osKernelRestoreLock (int32_t lock)
 281 \details
 282 The function \b osKernelRestoreLock restores the previous lock state after \ref osKernelLock or \ref osKernelUnlock.
 283
 284 The argument \a lock specifies the lock state as obtained by \ref osKernelLock or \ref osKernelUnlock.
 285
 286 The function returns the new value of the lock state (\token{1} if it was locked, \token{0} if it was unlocked), or a
 287 negative number representing an error code otherwise (refer to \ref osStatus_t).
 288
 289 Possible return values:
 290 - \em '1', if kernel was locked
 291 - \em '0', if kernel was not locked
 292 - \em 'osError', unspecified error occurred
 293 - \em 'osErrorISR', if IRQ is masked
 294 - \em 'osErrorISR', if in IRQ mode.
 295
 296
 297 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 298
 299 <b>Code Example</b>
 300 \code
 301   int32_t sl = osKernelLock();
 302   // ... critical code
 303   {
 304     int32_t su = osKernelUnlock();
 305     // ... uncritical code
 306     osKernelRestoreLock(su);
 307   }
 308   // ... critical code
 309   osKernelRestoreLock(sl);
 310 \endcode
 311 */
 312
 313 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 314 /**
 315 \fn uint32_t osKernelSuspend (void)
 316 \details
 317 CMSIS-RTOS provides extension for tick-less operation which is useful for applications that use extensively low-power modes
 318 where the SysTick timer is also disabled. To provide a time-tick in such power-saving modes a wake-up timer is used to derive
 319 timer intervals. The function \b osKernelSuspend suspends the RTX kernel scheduler and thus enables sleep modes.
 320
 321 The return value can be used to determine the amount of system ticks until the next tick-based kernel event will occure, i.e.
 322 a delayed thread becomed ready again. It is recommended to set up the low power timer to generate a wake-up interrupt based
 323 on this return value.
 324
 325 Possible return values:
 326 - amount of system ticks, in case of success
 327 - \em 'osErrorISR', if IRQ is masked
 328 - \em 'osErrorISR', if in IRQ mode.
 329
 330 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 331
 332 <b>Code Example</b>
 333 \code
 334 void osRtxIdleThread (void) {
 335                                                /* The idle thread is running
 336                                                   when no other thread is ready
 337                                                   to run.                      */
 338   unsigned int sleep;
 339
 340   for (;;) {
 341                                                /* HERE: include optional user
 342                                                   code to be executed when no
 343                                                   task runs.                   */
 344     sleep = osKernelSuspend();                 /* Suspend RTX thread scheduler */
 345
 346     if (sleep) {                               /* How long can we sleep?       */
 347                                                /* "sleep" is in RTX Timer Ticks
 348                                                   which is 1ms in this
 349                                                   configuration                */
 350
 351                                                /* Setup wake-up e.g. watchdog  */
 352
 353       __WFE();                                 /* Enter Power-down mode        */
 354
 355                                                /* After Wake-up                */
 356       sleep = tc;                              /* Adjust with cycles slept     */
 357     }
 358
 359     osKernelResume(sleep);                     /* Resume thread scheduler      */
 360   }
 361 }
 362 \endcode
 363 */
 364
 365 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 366 /**
 367 \fn void osKernelResume (uint32_t sleep_ticks)
 368 \details
 369 CMSIS-RTOS provides extension for tick-less operation which is useful for applications that use extensively low-power modes
 370 where the SysTick timer is also disabled. To provide a time-tick in such power-saving modes a wake-up timer is used to derive
 371 timer intervals. The function \b osKernelResume enables the RTX kernel scheduler and thus wakes up the system from sleep
 372 mode.
 373
 374 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 375
 376 <b>Code Example</b>
 377 \code
 378 void osRtxIdleThread (void) {
 379                                                /* The idle thread is running
 380                                                   when no other thread is ready
 381                                                   to run.                      */
 382   unsigned int sleep;
 383
 384   for (;;) {
 385                                                /* HERE: include optional user
 386                                                   code to be executed when no
 387                                                   task runs.                   */
 388     sleep = osKernelSuspend();                 /* Suspend RTX thread scheduler */
 389
 390     if (sleep) {                               /* How long can we sleep?       */
 391                                                /* "sleep" is in RTX Timer Ticks
 392                                                   which is 1ms in this
 393                                                   configuration                */
 394
 395                                                /* Setup wake-up e.g. watchdog  */
 396
 397       __WFE();                                 /* Enter Power-down mode        */
 398
 399                                                /* After Wake-up                */
 400       sleep = tc;                              /* Adjust with cycles slept     */
 401     }
 402
 403     osKernelResume(sleep);                     /* Resume thread scheduler      */
 404   }
 405 }
 406 \endcode
 407
 408 */
 409 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 410 /**
 411 \fn uint32_t osKernelGetTickCount (void)
 412 \details
 413 The function \b osKernelGetTickCount returns the current RTOS kernel tick count.
 414
 415 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 416
 417 \b Code \b Example
 418 \code
 419 #include "cmsis_os2.h"
 420
 421 void Thread_1 (void *arg)  {                // Thread function
 422   uint32_t tick;
 423
 424   tick = osKernelGetTickCount();            // retrieve the number of system ticks
 425   for (;;) {
 426     tick += 1000;                           // delay 1000 ticks periodically
 427     osDelayUntil(tick);
 428     // ...
 429   }
 430 }\endcode
 431
 432 Due to the limited value range used for the tick count it may overflow during runtime,
 433 i.e. after 2<sup>32</sup> ticks which are roughly 49days @ 1ms. Typically one has not to
 434 take special care of this unless a monotonic counter is needed. For such a case an additional
 435 64bit tick counter can be implemented as follows. The given example needs GetTick() called at
 436 least twice per tick overflow to work properly.
 437
 438 \b Code \b Example
 439 \code
 440 uint64_t GetTick(void) {
 441   static uint32_t tick_h = 0U;
 442   static uint32_t tick_l = 0U;
 443          uint32_t tick;
 444
 445   tick = osKernelGetTickCount();
 446   if (tick < tick_l) {
 447     tick_h++;
 448   }
 449   tick_l = tick;
 450
 451   return (((uint64_t)tick_h << 32) | tick_l);
 452 }
 453 \endcode
 454 */
 455
 456 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 457 /**
 458 \fn uint32_t osKernelGetTickFreq (void)
 459 \details
 460 The function \b osKernelGetTickFreq returns the frequency of the current RTOS kernel tick.
 461
 462 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 463 */
 464
 465 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 466 /**
 467 \fn uint32_t osKernelGetSysTimerCount (void)
 468 \details
 469 The function \b osKernelGetSysTimerCount returns the current RTOS kernel system timer as a 32-bit value.
 470
 471 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 472 */
 473
 474 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 475 /**
 476 \fn uint32_t osKernelGetSysTimerFreq (void)
 477 \details
 478 The function \b osKernelGetSysTimerFreq returns the frequency of the current RTOS kernel system timer.
 479
 480 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 481 */
 482 /// @}
 483
 484 // these struct members must stay outside the group to avoid double entries in documentation
 485 /**
 486 \var osKernelState_t::osKernelInactive
 487 \details
 488 The kernel is not ready yet. \ref osKernelInitialize needs to be executed successfully.
 489
 490 \var osKernelState_t::osKernelReady
 491 \details
 492 The kernel is not yet running. \ref osKernelStart transfers the kernel to the running state.
 493
 494 \var osKernelState_t::osKernelRunning
 495 \details
 496 The kernel is initialized and running.
 497
 498 \var osKernelState_t::osKernelLocked
 499 \details
 500 The kernel was locked with \ref osKernelLock. The functions \ref osKernelUnlock or \ref osKernelRestoreLock unlocks it.
 501
 502 \var osKernelState_t::osKernelSuspended
 503 \details
 504 The kernel was suspended using \ref osKernelSuspend. The function \ref osKernelResume returns to normal operation.
 505
 506 \var osKernelState_t::osKernelError
 507 \details
 508 An error occurred.
 509
 510 \var osKernelState_t::osKernelReserved
 511 \details
 512 Reserved.
 513 */
 514