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 #include "RTE_Components.h"
  68 #include  CMSIS_device_header
  69 #include "cmsis_os2.h"
  70
  71 /*----------------------------------------------------------------------------
  72  * Application main thread
  73  *---------------------------------------------------------------------------*/
  74 void app_main (void *argument) {
  75
  76   // ...
  77   for (;;) {}
  78 }
  79
  80 int main (void) {
  81
  82   // System Initialization
  83   SystemCoreClockUpdate();
  84   // ...
  85
  86   osKernelInitialize();                 // Initialize CMSIS-RTOS
  87   osThreadNew(app_main, NULL, NULL);    // Create application main thread
  88   osKernelStart();                      // Start thread execution
  89   for (;;) {}
  90 }
  91 \endcode
  92
  93 */
  94 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  95 /**
  96 \fn osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size)
  97 \details
  98 Retrieve API and kernel version of the underlying RTOS kernel and a human readable identifier string for the kernel.
  99
 100 <b>Code Example:</b>
 101 \code{.c}
 102 void info (void) {
 103   char infobuf[100];
 104   osVersion_t osv;
 105   osStatus_t status;
 106
 107   status = osKernelGetInfo(&osv, infobuf, 100);
 108   if(status == osOK) {
 109     printf("Kernel Information: %s\r\n", infobuf);
 110                 printf("Kernel Version    : %d\r\n", osv.kernel);
 111                 printf("Kernel API Version: %d\r\n", osv.api);
 112         }
 113 }
 114 \endcode
 115 */
 116 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 117 /**
 118 \fn osKernelState_t osKernelGetState (void)
 119 \details
 120 \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.
 121
 122 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 123 Calling \ref osKernelGetState from an ISR will return \ref osKernelError.
 124
 125 <b>Code Example:</b>
 126 \code{.c}
 127 int main (void) {
 128   // System Initialization
 129   SystemCoreClockUpdate();
 130   // ...
 131   if(osKernelGetState() == osKernelInactive) {     // Is the kernel initialized?
 132      osKernelInitialize();                          // Initialize CMSIS-RTOS kernel
 133   }
 134   ;
 135 }
 136 \endcode
 137
 138 */
 139 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 140 /**
 141 \fn osStatus_t osKernelStart (void)
 142 \details
 143 Start the RTOS Kernel and begin thread switching.
 144 The function osKernelStart will not return to its calling function in case of success.
 145
 146 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines". Calling \ref osKernelStart from an ISR will return \ref osErrorISR.
 147
 148 <b>Code Example:</b>
 149 \code{.c}
 150 int main (void) {
 151   // System Initialization
 152   SystemCoreClockUpdate();
 153   // ...
 154         if(osKernelGetState() == osKernelInactive) {
 155     osKernelInitialize();
 156         }
 157    ; // ... Start Threads
 158   if (osKernelGetState() == osKernelReady) {        // If kernel is ready to run...
 159     osKernelStart();                                // ... start thread execution
 160   }
 161
 162   while(1);                                         // only reached in case of error
 163 }
 164 \endcode
 165 */
 166
 167 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 168 /**
 169 \fn uint32_t osKernelLock (void)
 170 \details
 171 Allows to lock all task switches.
 172 <b>Code Example:</b>
 173 \code{.c}
 174 uint32_t lock;
 175
 176 lock = osKernelLock();
 177 …
 178 if (lock) {
 179   osKernelUnlock();
 180 }
 181 \endcode
 182
 183 */
 184 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 185 /**
 186 \fn void osKernelUnlock (void)
 187 \details
 188 Resumes from \ref osKernelLock.
 189 */
 190 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 191 /**
 192 \fn uint32_t osKernelSuspend (void)
 193 \details
 194 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.
 195
 196 <b>Code Example:</b>
 197 \code{.c}
 198 void os_idle_demon (void) {
 199   /* The idle demon is a system thread, running when no other thread is       */
 200   /* ready to run.                                                            */
 201   unsigned int sleep;
 202
 203   for (;;) {
 204   /* HERE: include optional user code to be executed when no task runs.*/
 205     sleep = os_suspend();                      /* Suspend RTX thread scheduler */
 206
 207     if (sleep) {                               /* How long can we sleep?       */
 208       /* "sleep" is in RTX Timer Ticks which is 1ms in this configuration      */
 209
 210       /* Setup wake-up e.g. watchdog */
 211
 212       /* Enter Power-down mode */
 213       __WFE();                                 /* Enter Power-down mode        */
 214
 215       /* After Wake-up */
 216       sleep = tc;                              /* Adjust with cycles slept     */
 217     }
 218
 219     os_resume(sleep);                          /* Resume thread scheduler      */
 220   }
 221 }
 222 \endcode
 223
 224 */
 225 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 226 /**
 227 \fn void osKernelResume (uint32_t sleep_ticks)
 228 \details
 229 See \ref osKernelSuspend.
 230
 231 */
 232 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 233 /**
 234 \fn uint64_t osKernelGetTickCount (void)
 235 \details
 236
 237 */
 238 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 239 /**
 240 \fn uint32_t osKernelGetTickFreq (void)
 241 \details
 242
 243 */
 244 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 245 /**
 246 \fn uint32_t osKernelGetSysTimerCount (void)
 247 \details
 248
 249 */
 250 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 251 /**
 252 \fn uint32_t osKernelGetSysTimerFreq (void)
 253 \details
 254
 255 */
 256 /// @}
 257
 258 // these struct members must stay outside the group to avoid double entries in documentation
 259 /**
 260 \var osKernelState_t::osKernelInactive
 261 \details
 262 The kernel is not ready yet. \ref osKernelInitialize needs to be executed successfully.
 263
 264 \var osKernelState_t::osKernelReady
 265 \details
 266 The kernel is not yet running. \ref osKernelStart transfers the kernel to the running state.
 267
 268 \var osKernelState_t::osKernelRunning
 269 \details
 270 The kernel is initialized and running.
 271
 272 \var osKernelState_t::osKernelLocked
 273 \details
 274 The kernel was locked with \ref osKernelLock. The function \ref osKernelUnlock unlocks it.
 275
 276 \var osKernelState_t::osKernelSuspended
 277 \details
 278 The kernel was suspended using \ref osKernelSuspend. The function \ref osKernelResume returns to normal operation.
 279
 280 \var osKernelState_t::osKernelError
 281 \details
 282 An error occurred. The kernel error handler should have been called in this state.
 283
 284 \var osKernelState_t::osKernelReserved
 285 \details
 286 Reserved.
 287 */
 288