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 Provide version/system information and start 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, no RTOS function may be called.
  71
  72 Possible \ref osStatus_t return values:
  73 - \em osOK in case of success.
  74 - \em osError if an unspecific error occurred.
  75 - \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".
  76 - \em osErrorNoMemory if no memory could be reserved for the operation.
  77
  78 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  79
  80 <b> Code Example</b>
  81 \code
  82 #include "RTE_Components.h"
  83 #include  CMSIS_device_header
  84 #include "cmsis_os2.h"
  85
  86 /*----------------------------------------------------------------------------
  87  * Application main thread
  88  *---------------------------------------------------------------------------*/
  89 void app_main (void *argument) {
  90
  91   // ...
  92   for (;;) {}
  93 }
  94
  95 int main (void) {
  96
  97   // System Initialization
  98   SystemCoreClockUpdate();
  99   // ...
 100
 101   osKernelInitialize();                 // Initialize CMSIS-RTOS
 102   osThreadNew(app_main, NULL, NULL);    // Create application main thread
 103   osKernelStart();                      // Start thread execution
 104   for (;;) {}
 105 }
 106 \endcode
 107 */
 108
 109 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 110 /**
 111 \fn osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size)
 112 \details
 113 The function \b  osKernelGetInfo retrieves the API and kernel version of the underlying RTOS kernel and a human readable identifier string for the kernel.
 114
 115 Possible \ref osStatus_t return values:
 116 - \em osOK in case of success.
 117 - \em osError if an unspecific error occurred.
 118 - \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".
 119
 120 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 121
 122 <b>Code Example</b>
 123 \code
 124 void info (void) {
 125   char infobuf[100];
 126   osVersion_t osv;
 127   osStatus_t status;
 128
 129   status = osKernelGetInfo(&osv, infobuf, sizeof(infobuf));
 130   if(status == osOK) {
 131     printf("Kernel Information: %s\r\n", infobuf);
 132     printf("Kernel Version    : %d\r\n", osv.kernel);
 133     printf("Kernel API Version: %d\r\n", osv.api);
 134   }
 135 }
 136 \endcode
 137 */
 138
 139 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 140 /**
 141 \fn osKernelState_t osKernelGetState (void)
 142 \details
 143 The function \b osKernelGetState returns the current state of the kernel and can be safely called before the RTOS is
 144 initialized. In case it fails or if it is called from an ISR, it will return \c osKernelError, otherwise it returns the
 145 kernel state (refer to \ref osKernelState_t for the list of kernel states).
 146
 147 Possible \ref osKernelState_t return values:
 148 - \ref osKernelError if an unspecific error occurred or it has been called from an
 149   \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".
 150 - the actual kernel state otherwise.
 151
 152 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 153
 154 <b>Code Example</b>
 155 \code
 156 int main (void) {
 157   // System Initialization
 158   SystemCoreClockUpdate();
 159   // ...
 160   if(osKernelGetState() == osKernelInactive) {     // Is the kernel initialized?
 161      osKernelInitialize();                         // Initialize CMSIS-RTOS kernel
 162   }
 163   ;
 164 }
 165 \endcode
 166
 167 */
 168 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 169 /**
 170 \fn osStatus_t osKernelStart (void)
 171 \details
 172 The function \b osKernelStart starts the RTOS kernel and begins thread switching. It will not return to its calling function in case of success.
 173
 174 Possible \ref osStatus_t return values:
 175 - \em osOK in case of success.
 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 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 209
 210 <b>Code Example</b>
 211 \code
 212   uint32_t state = osKernelLock();
 213   // ... critical code
 214   osKernelRestore(state);
 215 \endcode
 216 */
 217
 218 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 219 /**
 220 \fn int32_t osKernelUnlock (void)
 221 \details
 222 The function \b osKernelUnlock resumes from \ref osKernelLock. 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 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 227
 228 <b>Code Example</b>
 229 \code
 230   uint32_t sl = osKernelLock();
 231   // ... critical code
 232   {
 233     unint32_t su = osKernelUnlock();
 234     // ... uncritical code
 235     osKernelRestoreLock(su);
 236   }
 237   // ... critical code
 238   osKernelRestoreLock(sl);
 239 \endcode
 240 */
 241
 242 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 243 /**
 244 \fn int32_t osKernelRestoreLock (int32_t lock)
 245 \details
 246 The function \b osKernelRestoreLock restores the previous lock state after \ref osKernelLock or \ref osKernelUnlock.
 247
 248 The argument \a lock specifies the lock state as obtained by \ref osKernelLock or \ref osKernelUnlock.
 249
 250 The function returns the new value of the lock state (\token{1} if it was locked, \token{0} if it was unlocked), or a
 251 negative number representing an error code otherwise (refer to \ref osStatus_t).
 252
 253 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 254
 255 <b>Code Example</b>
 256 \code
 257   uint32_t sl = osKernelLock();
 258   // ... critical code
 259   {
 260     unint32_t su = osKernelUnlock();
 261     // ... uncritical code
 262     osKernelRestoreLock(su);
 263   }
 264   // ... critical code
 265   osKernelRestoreLock(sl);
 266 \endcode
 267 */
 268
 269 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 270 /**
 271 \fn uint32_t osKernelSuspend (void)
 272 \details
 273 CMSIS-RTOS provides extension for tick-less operation which is useful for applications that use extensively low-power modes
 274 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
 275 timer intervals. The function \b osKernelSuspend suspends the RTX kernel scheduler and thus enables sleep modes.
 276
 277 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 278
 279 <b>Code Example</b>
 280 \code
 281 void osRtxIdleThread (void) {
 282                                                /* The idle thread is running
 283                                                   when no other thread is ready
 284                                                   to run.                      */
 285   unsigned int sleep;
 286
 287   for (;;) {
 288                                                /* HERE: include optional user
 289                                                   code to be executed when no
 290                                                   task runs.                   */
 291     sleep = osKernelSuspend();                 /* Suspend RTX thread scheduler */
 292
 293     if (sleep) {                               /* How long can we sleep?       */
 294                                                /* "sleep" is in RTX Timer Ticks
 295                                                   which is 1ms in this
 296                                                   configuration                */
 297
 298                                                /* Setup wake-up e.g. watchdog  */
 299
 300       __WFE();                                 /* Enter Power-down mode        */
 301
 302                                                /* After Wake-up                */
 303       sleep = tc;                              /* Adjust with cycles slept     */
 304     }
 305
 306     osKernelResume(sleep);                     /* Resume thread scheduler      */
 307   }
 308 }
 309 \endcode
 310 */
 311
 312 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 313 /**
 314 \fn void osKernelResume (uint32_t sleep_ticks)
 315 \details
 316 CMSIS-RTOS provides extension for tick-less operation which is useful for applications that use extensively low-power modes
 317 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
 318 timer intervals. The function \b osKernelResume enables the RTX kernel scheduler and thus wakes up the system from sleep
 319 mode.
 320
 321 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 322
 323 <b>Code Example</b>
 324 \code
 325 void osRtxIdleThread (void) {
 326                                                /* The idle thread is running
 327                                                   when no other thread is ready
 328                                                   to run.                      */
 329   unsigned int sleep;
 330
 331   for (;;) {
 332                                                /* HERE: include optional user
 333                                                   code to be executed when no
 334                                                   task runs.                   */
 335     sleep = osKernelSuspend();                 /* Suspend RTX thread scheduler */
 336
 337     if (sleep) {                               /* How long can we sleep?       */
 338                                                /* "sleep" is in RTX Timer Ticks
 339                                                   which is 1ms in this
 340                                                   configuration                */
 341
 342                                                /* Setup wake-up e.g. watchdog  */
 343
 344       __WFE();                                 /* Enter Power-down mode        */
 345
 346                                                /* After Wake-up                */
 347       sleep = tc;                              /* Adjust with cycles slept     */
 348     }
 349
 350     osKernelResume(sleep);                     /* Resume thread scheduler      */
 351   }
 352 }
 353 \endcode
 354
 355 */
 356 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 357 /**
 358 \fn uint64_t osKernelGetTickCount (void)
 359 \details
 360 The function \b osKernelGetTickCount returns the current RTOS kernel tick count or \token{0} in case of a failure.
 361
 362 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 363 */
 364
 365 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 366 /**
 367 \fn uint32_t osKernelGetTickFreq (void)
 368 \details
 369 The function \b osKernelGetTickFreq returns the frequency of the current RTOS kernel tick or \token{0} in case of a failure.
 370
 371 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 372 */
 373
 374 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 375 /**
 376 \fn uint32_t osKernelGetSysTimerCount (void)
 377 \details
 378 The function \b osKernelGetSysTimerCount returns the current RTOS kernel system timer as a 32-bit value or \token{0} in case of a failure.
 379
 380 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 381 */
 382
 383 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 384 /**
 385 \fn uint32_t osKernelGetSysTimerFreq (void)
 386 \details
 387 The function \b osKernelGetSysTimerFreq returns the frequency of the current RTOS kernel system timer or \token{0} in case of a failure.
 388
 389 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 390 */
 391 /// @}
 392
 393 // these struct members must stay outside the group to avoid double entries in documentation
 394 /**
 395 \var osKernelState_t::osKernelInactive
 396 \details
 397 The kernel is not ready yet. \ref osKernelInitialize needs to be executed successfully.
 398
 399 \var osKernelState_t::osKernelReady
 400 \details
 401 The kernel is not yet running. \ref osKernelStart transfers the kernel to the running state.
 402
 403 \var osKernelState_t::osKernelRunning
 404 \details
 405 The kernel is initialized and running.
 406
 407 \var osKernelState_t::osKernelLocked
 408 \details
 409 The kernel was locked with \ref osKernelLock. The functions \ref osKernelUnlock or \ref osKernelRestoreLock unlocks it.
 410
 411 \var osKernelState_t::osKernelSuspended
 412 \details
 413 The kernel was suspended using \ref osKernelSuspend. The function \ref osKernelResume returns to normal operation.
 414
 415 \var osKernelState_t::osKernelError
 416 \details
 417 An error occurred.
 418
 419 \var osKernelState_t::osKernelReserved
 420 \details
 421 Reserved.
 422 */
 423