/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
//  ==== Kernel Control ====
/** 
\addtogroup CMSIS_RTOS_KernelCtrl Kernel Information and Control
\ingroup CMSIS_RTOS
\brief Provides version/system information and starts/controls the RTOS Kernel.
\details 
The kernel Information and Control function group allows to:
  - obtain information about the system and the underlying kernel.
  - obtain version information about the CMSIS-RTOS API.
  - initialize of the RTOS kernel for creating objects.
  - start the RTOS kernel and thread switching.
  - check the execution status of the RTOS kernel.

\note The kernel information and control functions cannot be called from
\ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
\note The kernel initialization for RTX5 is documented in \ref SystemStartup.

<b>Code Example</b>
\code
/*----------------------------------------------------------------------------
 * Application main thread
 *---------------------------------------------------------------------------*/
void app_main (void *argument) {
 
  // ...
  for (;;) {}
}
 
int main (void) {
 
  // System Initialization
  SystemCoreClockUpdate();
#ifdef RTE_Compiler_EventRecorder
  // Initialize and start Event Recorder
  EventRecorderInitialize(EventRecordError, 1U);
#endif
  // ...
 
  osKernelInitialize();                 // Initialize CMSIS-RTOS
  osThreadNew(app_main, NULL, NULL);    // Create application main thread
  osKernelStart();                      // Start thread execution
  for (;;) {}
}
\endcode
@{
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\struct osVersion_t
\details
Identifies the underlying RTOS kernel and API version number. The version is represented in a combined decimal number in the
format: major.minor.rev: mmnnnrrrr 

Use \ref osKernelGetInfo to retrieve the version numbers.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\enum osKernelState_t
\details
State of the kernel as retrieved by \ref osKernelGetState. In case \b osKernelGetState fails or if it is called from an ISR,
it will return \c osKernelError, otherwise it returns the kernel state.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osStatus_t osKernelInitialize (void)
\details
The function \b osKernelInitialize initializes the RTOS Kernel. Before it is successfully executed, only the functions
\ref osKernelGetInfo and \ref osKernelGetState may be called.
 
Possible \ref osStatus_t return values:
- \em osOK in case of success.
- \em osError if an unspecific error occurred.
- \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".
- \em osErrorNoMemory if no memory could be reserved for the operation.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b> Code Example</b>
\code
#include "RTE_Components.h"
#include  CMSIS_device_header
#include "cmsis_os2.h"
 
/*----------------------------------------------------------------------------
 * Application main thread
 *---------------------------------------------------------------------------*/
void app_main (void *argument) {
 
  // ...
  for (;;) {}
}
 
int main (void) {
 
  // System Initialization
  SystemCoreClockUpdate();
  // ...
 
  osKernelInitialize();                 // Initialize CMSIS-RTOS
  osThreadNew(app_main, NULL, NULL);    // Create application main thread
  osKernelStart();                      // Start thread execution
  for (;;) {}
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size)
\details
The function \b  osKernelGetInfo retrieves the API and kernel version of the underlying RTOS kernel and a human readable
identifier string for the kernel. It can be safely called before the RTOS is initialized or started (call to
\ref osKernelInitialize or \ref osKernelStart).

Possible \ref osStatus_t return values:
- \em osOK in case of success.
- \em osError if an unspecific error occurred.

\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
void info (void) {
  char infobuf[100];
  osVersion_t osv;
  osStatus_t status;
 
  status = osKernelGetInfo(&osv, infobuf, sizeof(infobuf));
  if(status == osOK) {
    printf("Kernel Information: %s\r\n", infobuf);
    printf("Kernel Version    : %d\r\n", osv.kernel);
    printf("Kernel API Version: %d\r\n", osv.api);
  }
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osKernelState_t osKernelGetState (void)
\details
The function \b osKernelGetState returns the current state of the kernel and can be safely called before the RTOS is
initialized or started (call to \ref osKernelInitialize or \ref osKernelStart). In case it fails it will return \c osKernelError,
otherwise it returns the kernel state (refer to \ref osKernelState_t for the list of kernel states).

Possible \ref osKernelState_t return values:
- \ref osKernelError if an unspecific error occurred.
- the actual kernel state otherwise.

\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
int main (void) {
  // System Initialization
  SystemCoreClockUpdate();
  // ...
  if(osKernelGetState() == osKernelInactive) {     // Is the kernel initialized?
     osKernelInitialize();                         // Initialize CMSIS-RTOS kernel
  }
  ;
}
\endcode

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osStatus_t osKernelStart (void)
\details
The function \b osKernelStart starts the RTOS kernel and begins thread switching. It will not return to its calling function
in case of success. Before it is successfully executed, only the functions \ref osKernelGetInfo, \ref osKernelGetState, and
object creation functions (\b osXxxNew) may be called.

At least one initial thread should be created prior osKernelStart, see \ref osThreadNew.

Possible \ref osStatus_t return values:
- \em osError if an unspecific error occurred.
- \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".
 
\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
int main (void) {
  // System Initialization
  SystemCoreClockUpdate();
  // ...
  if(osKernelGetState() == osKernelInactive) {
    osKernelInitialize();
  }
  ; // ... Start Threads
  if (osKernelGetState() == osKernelReady) {        // If kernel is ready to run...
    osKernelStart();                                // ... start thread execution
    }
  
  while(1);                                         // only reached in case of error
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn int32_t osKernelLock (void)
\details
The function \b osKernelLock allows to lock all task switches. It returns the previous value of the lock state (\token{1} if
it was locked, \token{0} if it was unlocked), or a negative number representing an error code otherwise (refer to
\ref osStatus_t).

Possible \ref osStatus_t return values:
- \em osError if an unspecific error occurred.
- \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
  uint32_t state = osKernelLock();
  // ... critical code
  osKernelRestore(state);
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn int32_t osKernelUnlock (void)
\details
The function \b osKernelUnlock resumes from \ref osKernelLock. It returns the previous value of the lock state (\token{1} if
it was locked, \token{0} if it was unlocked), or a negative number representing an error code otherwise (refer to
\ref osStatus_t).

Possible \ref osStatus_t return values:
- \em osError if an unspecific error occurred.
- \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
  uint32_t sl = osKernelLock();
  // ... critical code
  {
    unint32_t su = osKernelUnlock();
    // ... uncritical code
    osKernelRestoreLock(su);
  }
  // ... critical code
  osKernelRestoreLock(sl);
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn int32_t osKernelRestoreLock (int32_t lock)
\details
The function \b osKernelRestoreLock restores the previous lock state after \ref osKernelLock or \ref osKernelUnlock.

The argument \a lock specifies the lock state as obtained by \ref osKernelLock or \ref osKernelUnlock.

The function returns the new value of the lock state (\token{1} if it was locked, \token{0} if it was unlocked), or a
negative number representing an error code otherwise (refer to \ref osStatus_t).

Possible \ref osStatus_t return values:
- \em osError if an unspecific error occurred.
- \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
  uint32_t sl = osKernelLock();
  // ... critical code
  {
    unint32_t su = osKernelUnlock();
    // ... uncritical code
    osKernelRestoreLock(su);
  }
  // ... critical code
  osKernelRestoreLock(sl);
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn uint32_t osKernelSuspend (void)
\details
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 function \b osKernelSuspend suspends the RTX kernel scheduler and thus enables sleep modes.

The return value can be used to determine the amount of system ticks until the next tick-based kernel event will occure, i.e.
a delayed thread becomed ready again. It is recommended to set up the low power timer to generate a wake-up interrupt based
on this return value.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
void osRtxIdleThread (void) {
                                               /* The idle thread is running
                                                  when no other thread is ready
                                                  to run.                      */
  unsigned int sleep;
 
  for (;;) {
                                               /* HERE: include optional user
                                                  code to be executed when no
                                                  task runs.                   */
    sleep = osKernelSuspend();                 /* Suspend RTX thread scheduler */
 
    if (sleep) {                               /* How long can we sleep?       */
                                               /* "sleep" is in RTX Timer Ticks
                                                  which is 1ms in this
                                                  configuration                */
       
                                               /* Setup wake-up e.g. watchdog  */
 
      __WFE();                                 /* Enter Power-down mode        */
      
                                               /* After Wake-up                */
      sleep = tc;                              /* Adjust with cycles slept     */  
    }
 
    osKernelResume(sleep);                     /* Resume thread scheduler      */
  }
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn void osKernelResume (uint32_t sleep_ticks)
\details
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 function \b osKernelResume enables the RTX kernel scheduler and thus wakes up the system from sleep
mode.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
void osRtxIdleThread (void) {
                                               /* The idle thread is running
                                                  when no other thread is ready
                                                  to run.                      */
  unsigned int sleep;
 
  for (;;) {
                                               /* HERE: include optional user
                                                  code to be executed when no
                                                  task runs.                   */
    sleep = osKernelSuspend();                 /* Suspend RTX thread scheduler */
 
    if (sleep) {                               /* How long can we sleep?       */
                                               /* "sleep" is in RTX Timer Ticks
                                                  which is 1ms in this
                                                  configuration                */
       
                                               /* Setup wake-up e.g. watchdog  */
 
      __WFE();                                 /* Enter Power-down mode        */
      
                                               /* After Wake-up                */
      sleep = tc;                              /* Adjust with cycles slept     */  
    }
 
    osKernelResume(sleep);                     /* Resume thread scheduler      */
  }
}
\endcode

*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn uint32_t osKernelGetTickCount (void)
\details
The function \b osKernelGetTickCount returns the current RTOS kernel tick count.

\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

\b Code \b Example
\code
#include "cmsis_os2.h"
 
void Thread_1 (void *arg)  {                // Thread function
  uint32_t tick;

  tick = osKernelGetTickCount();            // retrieve the number of system ticks
  for (;;) {
    tick += 1000;                           // delay 1000 ticks periodically
    osDelayUntil(tick);
    // ...
  }
}\endcode

Due to the limited value range used for the tick count it may overflow during runtime,
i.e. after 2<sup>32</sup> ticks which are roughly 49days @ 1ms. Typically one has not to
take special care of this unless a monotonic counter is needed. For such a case an additional
64bit tick counter can be implemented as follows. The given example needs GetTick() called at
least twice per tick overflow to work properly.

\b Code \b Example
\code
uint64_t GetTick(void) {
  static uint32_t tick_h = 0U;
  static uint32_t tick_l = 0U;
         uint32_t tick;

  tick = osKernelGetTickCount();
  if (tick < tick_l) {
    tick_h++;
  }
  tick_l = tick;

  return (((uint64_t)tick_h << 32) | tick_l);
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn uint32_t osKernelGetTickFreq (void)
\details
The function \b osKernelGetTickFreq returns the frequency of the current RTOS kernel tick.

\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn uint32_t osKernelGetSysTimerCount (void)
\details
The function \b osKernelGetSysTimerCount returns the current RTOS kernel system timer as a 32-bit value.

\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn uint32_t osKernelGetSysTimerFreq (void)
\details
The function \b osKernelGetSysTimerFreq returns the frequency of the current RTOS kernel system timer.

\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
*/
/// @}

// these struct members must stay outside the group to avoid double entries in documentation
/**
\var osKernelState_t::osKernelInactive
\details
The kernel is not ready yet. \ref osKernelInitialize needs to be executed successfully.

\var osKernelState_t::osKernelReady
\details
The kernel is not yet running. \ref osKernelStart transfers the kernel to the running state.

\var osKernelState_t::osKernelRunning
\details
The kernel is initialized and running.

\var osKernelState_t::osKernelLocked
\details
The kernel was locked with \ref osKernelLock. The functions \ref osKernelUnlock or \ref osKernelRestoreLock unlocks it.

\var osKernelState_t::osKernelSuspended
\details
The kernel was suspended using \ref osKernelSuspend. The function \ref osKernelResume returns to normal operation.

\var osKernelState_t::osKernelError
\details
An error occurred.

\var osKernelState_t::osKernelReserved
\details
Reserved. 
*/