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