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