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 The function \b main is a special thread function that may be started at system initialization. In this case it has the
  16 initial priority \a osPriorityNormal.
  17
  18 When reaching \b main, it is necessary to:
  19 -# Call osKernelInitialize() to initialize the CMSIS-RTOS Kernel
  20 -# Setup device peripherals and create other RTOS objects using the \b os*New functions.
  21 -# Start the Kernel and begin thread switching by calling osKernelStart().
  22
  23 <b>Code Example</b>
  24 \code{.c}
  25 int main (void) {
  26   osKernelInitialize ();                    // initialize CMSIS-RTOS
  27
  28   // initialize peripherals here
  29
  30   // create 'thread' functions that start executing,
  31   // example: tid_name = osThreadNew(thread, NULL, NULL);
  32
  33   osKernelStart ();                         // start thread execution
  34 }
  35 \endcode
  36 @{
  37 */
  38 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  39 /**
  40 \struct osVersion_t
  41 \details
  42 Identifies the underlying RTOS kernel and API version number.
  43 The Version is represented in a combined decimal number in the format: major.minor.rev: mmnnnrrrr
  44
  45 Use \ref osKernelGetInfo to retrieve the version numbers
  46
  47 */
  48 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  49 /**
  50 \enum osKernelState_t
  51 \details
  52 State of the Kernel. Can be retrieved by \ref osKernelGetState.
  53 */
  54 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  55 /**
  56 \fn osStatus_t osKernelInitialize (void)
  57 \details
  58
  59 \return Returns \ref osStatus_t with \ref osOK in case of success.
  60 \return Returns \ref osError if an internal error prevents the kernel initialization.
  61
  62 Initialize the RTOS Kernel. Before osKernelInitialize is successfully executed no RTOS function may be called.
  63
  64 The RTOS kernel does not start thread switching until the function osKernelStart is called.
  65
  66 <b> Code Example:</b>
  67 \code{.c}
  68 #include "RTE_Components.h"
  69 #include  CMSIS_device_header
  70 #include "cmsis_os2.h"
  71
  72 /*----------------------------------------------------------------------------
  73  * Application main thread
  74  *---------------------------------------------------------------------------*/
  75 void app_main (void *argument) {
  76
  77   // ...
  78   for (;;) {}
  79 }
  80
  81 int main (void) {
  82
  83   // System Initialization
  84   SystemCoreClockUpdate();
  85   // ...
  86
  87   osKernelInitialize();                 // Initialize CMSIS-RTOS
  88   osThreadNew(app_main, NULL, NULL);    // Create application main thread
  89   osKernelStart();                      // Start thread execution
  90   for (;;) {}
  91 }
  92 \endcode
  93
  94 */
  95 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  96 /**
  97 \fn osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size)
  98 \details
  99 Retrieve API and kernel version of the underlying RTOS kernel and a human readable identifier string for the kernel.
 100
 101 <b>Code Example:</b>
 102 \code{.c}
 103 void info (void) {
 104   char infobuf[100];
 105   osVersion_t osv;
 106   osStatus_t status;
 107
 108   status = osKernelGetInfo(&osv, infobuf, 100);
 109   if(status == osOK) {
 110     printf("Kernel Information: %s\r\n", infobuf);
 111                 printf("Kernel Version    : %d\r\n", osv.kernel);
 112                 printf("Kernel API Version: %d\r\n", osv.api);
 113         }
 114 }
 115 \endcode
 116 */
 117 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 118 /**
 119 \fn osKernelState_t osKernelGetState (void)
 120 \details
 121 \return The state of the kernel is represented in the \ref osKernelState_t enum. \ref osKernelGetState can be safely called before the RTOS is initialized.
 122
 123 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 124 Calling \ref osKernelGetState from an ISR will return \ref osKernelError.
 125
 126 <b>Code Example:</b>
 127 \code{.c}
 128 int main (void) {
 129   // System Initialization
 130   SystemCoreClockUpdate();
 131   // ...
 132   if(osKernelGetState() == osKernelInactive) {     // Is the kernel initialized?
 133      osKernelInitialize();                          // Initialize CMSIS-RTOS kernel
 134   }
 135   ;
 136 }
 137 \endcode
 138
 139 */
 140 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 141 /**
 142 \fn osStatus_t osKernelStart (void)
 143 \details
 144 Start the RTOS Kernel and begin thread switching.
 145 The function osKernelStart will not return to its calling function in case of success.
 146
 147 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines". Calling \ref osKernelStart from an ISR will return \ref osErrorISR.
 148
 149 <b>Code Example:</b>
 150 \code{.c}
 151 int main (void) {
 152   // System Initialization
 153   SystemCoreClockUpdate();
 154   // ...
 155         if(osKernelGetState() == osKernelInactive) {
 156     osKernelInitialize();
 157         }
 158    ; // ... Start Threads
 159   if (osKernelGetState() == osKernelReady) {        // If kernel is ready to run...
 160     osKernelStart();                                // ... start thread execution
 161   }
 162
 163   while(1);                                         // only reached in case of error
 164 }
 165 \endcode
 166 */
 167
 168 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 169 /**
 170 \fn uint32_t osKernelLock (void)
 171 \details
 172 Allows to lock all task switches.
 173 <b>Code Example:</b>
 174 \code{.c}
 175 uint32_t lock;
 176
 177 lock = osKernelLock();
 178 …
 179 if (lock) {
 180   osKernelUnlock();
 181 }
 182 \endcode
 183
 184 */
 185 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 186 /**
 187 \fn void osKernelUnlock (void)
 188 \details
 189 Resumes from \ref osKernelLock.
 190 */
 191 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 192 /**
 193 \fn uint32_t osKernelSuspend (void)
 194 \details
 195 CMSIS-RTOS provides extension for tick-less operation which is useful for applications that use extensively low-power modes 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 timer intervals. The functions osKernelSuspend and osKernelResume control the tick-less operation.
 196
 197 <b>Code Example:</b>
 198 \code{.c}
 199 void os_idle_demon (void) {
 200   /* The idle demon is a system thread, running when no other thread is       */
 201   /* ready to run.                                                            */
 202   unsigned int sleep;
 203
 204   for (;;) {
 205   /* HERE: include optional user code to be executed when no task runs.*/
 206     sleep = os_suspend();                      /* Suspend RTX thread scheduler */
 207
 208     if (sleep) {                               /* How long can we sleep?       */
 209       /* "sleep" is in RTX Timer Ticks which is 1ms in this configuration      */
 210
 211       /* Setup wake-up e.g. watchdog */
 212
 213       /* Enter Power-down mode */
 214       __WFE();                                 /* Enter Power-down mode        */
 215
 216       /* After Wake-up */
 217       sleep = tc;                              /* Adjust with cycles slept     */
 218     }
 219
 220     os_resume(sleep);                          /* Resume thread scheduler      */
 221   }
 222 }
 223 \endcode
 224
 225 */
 226 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 227 /**
 228 \fn void osKernelResume (uint32_t sleep_ticks)
 229 \details
 230 See \ref osKernelSuspend.
 231
 232 */
 233 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 234 /**
 235 \fn uint64_t osKernelGetTickCount (void)
 236 \details
 237
 238 */
 239 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 240 /**
 241 \fn uint32_t osKernelGetTickFreq (void)
 242 \details
 243
 244 */
 245 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 246 /**
 247 \fn uint32_t osKernelGetSysTimerCount (void)
 248 \details
 249
 250 */
 251 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 252 /**
 253 \fn uint32_t osKernelGetSysTimerFreq (void)
 254 \details
 255
 256 */
 257 /// @}
 258
 259 // these struct members must stay outside the group to avoid double entries in documentation
 260 /**
 261 \var osKernelState_t::osKernelInactive
 262 \details
 263 The kernel is not ready yet. \ref osKernelInitialize needs to be executed successfully.
 264
 265 \var osKernelState_t::osKernelReady
 266 \details
 267 The kernel is not yet running. \ref osKernelStart transfers the kernel to the running state.
 268
 269 \var osKernelState_t::osKernelRunning
 270 \details
 271 The kernel is initialized and running.
 272
 273 \var osKernelState_t::osKernelLocked
 274 \details
 275 The kernel was locked with \ref osKernelLock. The function \ref osKernelUnlock unlocks it.
 276
 277 \var osKernelState_t::osKernelSuspended
 278 \details
 279 The kernel was suspended using \ref osKernelSuspend. The function \ref osKernelResume returns to normal operation.
 280
 281 \var osKernelState_t::osKernelError
 282 \details
 283 An error occurred. The kernel error handler should have been called in this state.
 284
 285 \var osKernelState_t::osKernelReserved
 286 \details
 287 Reserved.
 288 */
 289