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