<commit_before>

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
//  ==== Timer Management Functions ====
/** 
\addtogroup CMSIS_RTOS_TimerMgmt Timer Management
\ingroup CMSIS_RTOS
\brief Create and control timer and timer callback functions.
\details 
In addition to the \ref CMSIS_RTOS_Wait CMSIS-RTOS also supports virtual timer objects. These timer objects can
trigger the execution of a function (not threads). When a timer expires, a callback function is executed to run associated
code with the timer. Each timer can be configured as a one-shot or a  periodic timer. A periodic timer repeats its operation
until it is \ref osTimerDelete "deleted" or \ref osTimerStop "stopped". All timers can be
\ref osTimerStart "started, restarted", or \ref osTimerStop "stopped".

\note RTX handles Timers in the thread \b osRtxTimerThread. Callback functions run under control of this thread and may use
other CMSIS-RTOS API calls. The \b osRtxTimerThread is configured in \ref timerConfig.
\note Timer management functions cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

The figure below shows the behavior of a periodic timer. For one-shot timers, the timer stops after execution of the
callback function.

\image html "Timer.png" "Behavior of a Periodic Timer"


Working with Timers
--------------------
The following steps are required to use a software timer:
-# Define the timers:
\code
osTimerId_t one_shot_id, periodic_id;
\endcode
-# Define callback functions:
\code
static void one_shot_Callback (void *argument) {
    int32_t arg = (int32_t)argument; // cast back argument '0' 
    // do something, i.e. set thread/event flags
}
static void periodic_Callback (void *argument) {
    int32_t arg = (int32_t)argument; // cast back argument '5'
    // do something, i.e. set thread/event flags
}
\endcode
-# Instantiate and start the timers:
\code
// creates a one-shot timer:
one_shot_id = osTimerNew(one_shot_Callback, osTimerOnce, (void *)0, NULL);     // (void*)0 is passed as an argument
                                                                               // to the callback function
// creates a periodic timer:
periodic_id = osTimerNew(periodic_Callback, osTimerPeriodic, (void *)5, NULL); // (void*)5 is passed as an argument
                                                                               // to the callback function
osTimerStart(one_shot_id, 500);
osTimerStart(periodic_id, 1500);
\endcode

@{
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\enum osTimerType_t
\details
The \ref osTimerType_t specifies the a repeating (periodic) or one-shot timer for the function \ref osTimerNew.

\var osTimerType_t::osTimerOnce
\details
The timer is not automatically restarted once it has elapsed.

\var osTimerType_t::osTimerPeriodic
\details 
The timer repeats automatically and triggers the callback continuously.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\typedef osTimerId_t 
\details
Instances of this type hold a reference to a timer object. \n
Returned by:
- \ref osTimerNew
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\typedef void (*osTimerFunc_t) (void *argument)
\details
The timer callback function is called everytime the timer elapses.

The callback might be executed either in a dedicated timer thread or in interrupt context. Thus it is recommended to only
use ISR callable functions from the timer callback.

\param[in] argument The argument provided to \ref osTimerNew.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\struct osTimerAttr_t 
\details
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr)
\details
The function \b osTimerNew creates an one-shot or periodic timer and associates it with a callback function with \a argument.
The timer is in stopped state until it is started with \ref osTimerStart. The function can be safely called before the RTOS
is started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).

The function \b osTimerNew returns the pointer to the timer object identifier or \token{NULL} in case of an error.

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

<b>Code Example</b>
\code
#include "cmsis_os2.h"
 
void Timer1_Callback (void *arg);                          // prototypes for timer callback function
void Timer2_Callback (void *arg);                   
 
uint32_t  exec1;                                           // argument for the timer call back function
uint32_t  exec2;                                           // argument for the timer call back function
 
void TimerCreate_example (void)  {
  osTimerId_t id1;                                         // timer id
  osTimerId_t id2;                                         // timer id
 
  // Create one-shoot timer
  exec1 = 1;
  id1 = osTimerNew (Timer1_Callback, osTimerOnce, &exec1, NULL);
  if (id1 != NULL)  {
    // One-shoot timer created
  }
 
  // Create periodic timer
  exec2 = 2;
  id2 = osTimerNew (Timer2_Callback, osTimerPeriodic, &exec2, NULL);
  if (id2 != NULL)  {
    // Periodic timer created
  }
  :
}
\endcode
*/
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn const char *osTimerGetName (osTimerId_t timer_id)
\details
The function \b osTimerGetName returns the pointer to the name string of the timer identified by parameter \a timer_id or
\token{NULL} in case of an error.

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

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks)
\details
The function \b osTimerStart starts or restarts a timer specified by the parameter \a timer_id. The parameter \a ticks
specifies the value of the timer in \ref CMSIS_RTOS_TimeOutValue "time ticks".

Possible \ref osStatus_t return values:
 - \em osOK: the specified timer has been started or restarted.
 - \em osErrorISR: \b osTimerStart cannot be called from interrupt service routines.
 - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid or \a ticks is incorrect.
 - \em osErrorResource: the timer specified by parameter \a timer_id is in an invalid timer state.

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

<b>Code Example</b>
\code
#include "cmsis_os2.h"
  
void Timer_Callback (void *arg)  {                          // timer callback function
                                                            // arg contains &exec
                                                            // called every second after osTimerStart
} 
 
uint32_t  exec;                                             // argument for the timer call back function
 
void TimerStart_example (void)  {
  osTimerId_t id;                                           // timer id
  uint32_t    timerDelay;                                   // timer value
  osStatus_t  status;                                       // function return status
 
  // Create periodic timer
  exec = 1;
  id = osTimerNew (Timer_Callback, osTimerPeriodic, &exec, NULL);
  if (id)  {
    timerDelay = 1000;
    status = osTimerStart (id, timerDelay);                 // start timer
    if (status != osOK)  {
      // Timer could not be started
    } 
  }
  ;
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn osStatus_t osTimerStop (osTimerId_t timer_id)
\details
The function \b osTimerStop stops a timer specified by the parameter \a timer_id.

Possible \ref osStatus_t return values:
 - \em osOK: the specified timer has been stopped.
 - \em osErrorISR: \b osTimerStop cannot be called from interrupt service routines.
 - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
 - \em osErrorResource: the timer specified by parameter \a timer_id is not running (you can only stop a running timer).

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

<b>Code Example</b>
\code
#include "cmsis_os2.h"
 
void Timer_Callback (void *arg);                           // prototype for timer callback function
 
uint32_t  exec;                                            // argument for the timer call back function

void TimerStop_example (void) {
  osTimerId_t id;                                          // timer id
  osStatus_t  status;                                      // function return status
 
  // Create periodic timer
  exec = 1;
  id = osTimerNew (Timer_Callback, osTimerPeriodic, &exec, NULL);
  osTimerStart (id, 1000);                                 // start timer
  :
  status = osTimerStop (id);                               // stop timer
  if (status != osOK) {
    // Timer could not be stopped
  } 
  ;
  osTimerStart (id, 1000);                                 // start timer again
  ;
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn uint32_t osTimerIsRunning (osTimerId_t timer_id)
\details
The function \b osTimerIsRunning checks whether a timer specified by parameter \a timer_id is running. It returns \token{1}
if the timer is running and \token{0} if the timer is stopped or an error occurred.

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

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn osStatus_t osTimerDelete (osTimerId_t timer_id)
\details
The function \b osTimerDelete deletes the timer specified by parameter \a timer_id.

Possible \ref osStatus_t return values:
 - \em osOK: the specified timer has been deleted.
 - \em osErrorISR: \b osTimerDelete cannot be called from interrupt service routines.
 - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
 - \em osErrorResource: the timer specified by parameter \a timer_id is in an invalid timer state.

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

<b>Code Example</b>
\code
#include "cmsis_os2.h"

void Timer_Callback (void *arg);                           // prototype for timer callback function
 
uint32_t  exec;                                            // argument for the timer call back function

void TimerDelete_example (void) {
  osTimerId_t id;                                          // timer id
  osStatus_t  status;                                      // function return status  
 
  // Create periodic timer
  exec = 1;
  id = osTimerNew (Timer_Callback, osTimerPeriodic, &exec, NULL);
  osTimerStart (id, 1000UL);                               // start timer
  ;
  status = osTimerDelete (id);                             // stop and delete timer
  if (status != osOK) {
    // Timer could not be deleted
  } 
  ;
}
\endcode
*/
/// @}

// these struct members must stay outside the group to avoid double entries in documentation
/**
\var osTimerAttr_t::attr_bits
\details
Reserved for future use (set to '0').\n
Default: \token{0}.

\var osTimerAttr_t::cb_mem
\details
Pointer to a memory location for the timer control block object. This can optionally be used for custom memory management systems.\n
Default: \token{NULL} (uses kernel memory management).


\var osTimerAttr_t::cb_size
\details
The size of the memory block passed with \ref cb_mem. Must be the size of a timer control block object or larger.

\var osTimerAttr_t::name
\details
Pointer to a string with a human readable name of the timer object.\n
Default: \token{NULL}.
*/
<commit_msg>RTOS2: Enhanced RTOS timer documentation and example.<commit_after>

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
//  ==== Timer Management Functions ====
/** 
\addtogroup CMSIS_RTOS_TimerMgmt Timer Management
\ingroup CMSIS_RTOS
\brief Create and control timer and timer callback functions.
\details 
In addition to the \ref CMSIS_RTOS_Wait CMSIS-RTOS also supports virtual timer objects. These timer objects can
trigger the execution of a function (not threads). When a timer expires, a callback function is executed to run associated
code with the timer. Each timer can be configured as a one-shot or a  periodic timer. A periodic timer repeats its operation
until it is \ref osTimerDelete "deleted" or \ref osTimerStop "stopped". All timers can be
\ref osTimerStart "started, restarted", or \ref osTimerStop "stopped".

\note RTX handles Timers in the thread \b osRtxTimerThread. Callback functions run under control of this thread and may use
other CMSIS-RTOS API calls. The \b osRtxTimerThread is configured in \ref timerConfig.
\note Timer management functions cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

The figure below shows the behavior of a periodic timer. For one-shot timers, the timer stops after execution of the
callback function.

\image html "Timer.png" "Behavior of a Periodic Timer"


Working with Timers
--------------------
The following steps are required to use a software timer:
-# Define the timers:
\code
osTimerId_t one_shot_id, periodic_id;
\endcode
-# Define callback functions:
\code
static void one_shot_Callback (void *argument) {
    int32_t arg = (int32_t)argument; // cast back argument '0' 
    // do something, i.e. set thread/event flags
}
static void periodic_Callback (void *argument) {
    int32_t arg = (int32_t)argument; // cast back argument '5'
    // do something, i.e. set thread/event flags
}
\endcode
-# Instantiate and start the timers:
\code
// creates a one-shot timer:
one_shot_id = osTimerNew(one_shot_Callback, osTimerOnce, (void *)0, NULL);     // (void*)0 is passed as an argument
                                                                               // to the callback function
// creates a periodic timer:
periodic_id = osTimerNew(periodic_Callback, osTimerPeriodic, (void *)5, NULL); // (void*)5 is passed as an argument
                                                                               // to the callback function
osTimerStart(one_shot_id, 500);
osTimerStart(periodic_id, 1500);
 
// start the one-shot timer again after it has triggered the first time:
osTimerStart(one_shot_id, 500);
 
// when timers are not needed any longer free the resources:
osTimerDelete(one_shot_id);
osTimerDelete(periodic_id);
\endcode

@{
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\enum osTimerType_t
\details
The \ref osTimerType_t specifies the a repeating (periodic) or one-shot timer for the function \ref osTimerNew.

\var osTimerType_t::osTimerOnce
\details
The timer is not automatically restarted once it has elapsed. It can be restarted manually using \ref osTimerStart as needed.

\var osTimerType_t::osTimerPeriodic
\details 
The timer repeats automatically and triggers the callback continuously while running, see \ref osTimerStart and \ref osTimerStop.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\typedef osTimerId_t 
\details
Instances of this type hold a reference to a timer object. \n
Returned by:
- \ref osTimerNew
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\typedef void (*osTimerFunc_t) (void *argument)
\details
The timer callback function is called everytime the timer elapses.

The callback might be executed either in a dedicated timer thread or in interrupt context. Thus it is recommended to only
use ISR callable functions from the timer callback.

\param[in] argument The argument provided to \ref osTimerNew.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\struct osTimerAttr_t 
\details
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr)
\details
The function \b osTimerNew creates an one-shot or periodic timer and associates it with a callback function with \a argument.
The timer is in stopped state until it is started with \ref osTimerStart. The function can be safely called before the RTOS
is started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).

The function \b osTimerNew returns the pointer to the timer object identifier or \token{NULL} in case of an error.

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

<b>Code Example</b>
\code
#include "cmsis_os2.h"
 
void Timer1_Callback (void *arg);                          // prototypes for timer callback function
void Timer2_Callback (void *arg);                   
 
uint32_t  exec1;                                           // argument for the timer call back function
uint32_t  exec2;                                           // argument for the timer call back function
 
void TimerCreate_example (void)  {
  osTimerId_t id1;                                         // timer id
  osTimerId_t id2;                                         // timer id
 
  // Create one-shoot timer
  exec1 = 1;
  id1 = osTimerNew (Timer1_Callback, osTimerOnce, &exec1, NULL);
  if (id1 != NULL)  {
    // One-shoot timer created
  }
 
  // Create periodic timer
  exec2 = 2;
  id2 = osTimerNew (Timer2_Callback, osTimerPeriodic, &exec2, NULL);
  if (id2 != NULL)  {
    // Periodic timer created
  }
  :
}
\endcode
*/
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn const char *osTimerGetName (osTimerId_t timer_id)
\details
The function \b osTimerGetName returns the pointer to the name string of the timer identified by parameter \a timer_id or
\token{NULL} in case of an error.

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

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks)
\details
The function \b osTimerStart starts or restarts a timer specified by the parameter \a timer_id. The parameter \a ticks
specifies the value of the timer in \ref CMSIS_RTOS_TimeOutValue "time ticks".

Possible \ref osStatus_t return values:
 - \em osOK: the specified timer has been started or restarted.
 - \em osErrorISR: \b osTimerStart cannot be called from interrupt service routines.
 - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid or \a ticks is incorrect.
 - \em osErrorResource: the timer specified by parameter \a timer_id is in an invalid timer state.

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

<b>Code Example</b>
\code
#include "cmsis_os2.h"
  
void Timer_Callback (void *arg)  {                          // timer callback function
                                                            // arg contains &exec
                                                            // called every second after osTimerStart
} 
 
uint32_t  exec;                                             // argument for the timer call back function
 
void TimerStart_example (void)  {
  osTimerId_t id;                                           // timer id
  uint32_t    timerDelay;                                   // timer value
  osStatus_t  status;                                       // function return status
 
  // Create periodic timer
  exec = 1;
  id = osTimerNew (Timer_Callback, osTimerPeriodic, &exec, NULL);
  if (id)  {
    timerDelay = 1000;
    status = osTimerStart (id, timerDelay);                 // start timer
    if (status != osOK)  {
      // Timer could not be started
    } 
  }
  ;
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn osStatus_t osTimerStop (osTimerId_t timer_id)
\details
The function \b osTimerStop stops a timer specified by the parameter \a timer_id.

Possible \ref osStatus_t return values:
 - \em osOK: the specified timer has been stopped.
 - \em osErrorISR: \b osTimerStop cannot be called from interrupt service routines.
 - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
 - \em osErrorResource: the timer specified by parameter \a timer_id is not running (you can only stop a running timer).

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

<b>Code Example</b>
\code
#include "cmsis_os2.h"
 
void Timer_Callback (void *arg);                           // prototype for timer callback function
 
uint32_t  exec;                                            // argument for the timer call back function

void TimerStop_example (void) {
  osTimerId_t id;                                          // timer id
  osStatus_t  status;                                      // function return status
 
  // Create periodic timer
  exec = 1;
  id = osTimerNew (Timer_Callback, osTimerPeriodic, &exec, NULL);
  osTimerStart (id, 1000);                                 // start timer
  :
  status = osTimerStop (id);                               // stop timer
  if (status != osOK) {
    // Timer could not be stopped
  } 
  ;
  osTimerStart (id, 1000);                                 // start timer again
  ;
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn uint32_t osTimerIsRunning (osTimerId_t timer_id)
\details
The function \b osTimerIsRunning checks whether a timer specified by parameter \a timer_id is running. It returns \token{1}
if the timer is running and \token{0} if the timer is stopped or an error occurred.

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

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** 
\fn osStatus_t osTimerDelete (osTimerId_t timer_id)
\details
The function \b osTimerDelete deletes the timer specified by parameter \a timer_id.

Possible \ref osStatus_t return values:
 - \em osOK: the specified timer has been deleted.
 - \em osErrorISR: \b osTimerDelete cannot be called from interrupt service routines.
 - \em osErrorParameter: parameter \a timer_id is either \token{NULL} or invalid.
 - \em osErrorResource: the timer specified by parameter \a timer_id is in an invalid timer state.

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

<b>Code Example</b>
\code
#include "cmsis_os2.h"

void Timer_Callback (void *arg);                           // prototype for timer callback function
 
uint32_t  exec;                                            // argument for the timer call back function

void TimerDelete_example (void) {
  osTimerId_t id;                                          // timer id
  osStatus_t  status;                                      // function return status  
 
  // Create periodic timer
  exec = 1;
  id = osTimerNew (Timer_Callback, osTimerPeriodic, &exec, NULL);
  osTimerStart (id, 1000UL);                               // start timer
  ;
  status = osTimerDelete (id);                             // stop and delete timer
  if (status != osOK) {
    // Timer could not be deleted
  } 
  ;
}
\endcode
*/
/// @}

// these struct members must stay outside the group to avoid double entries in documentation
/**
\var osTimerAttr_t::attr_bits
\details
Reserved for future use (set to '0').\n
Default: \token{0}.

\var osTimerAttr_t::cb_mem
\details
Pointer to a memory location for the timer control block object. This can optionally be used for custom memory management systems.\n
Default: \token{NULL} (uses kernel memory management).


\var osTimerAttr_t::cb_size
\details
The size of the memory block passed with \ref cb_mem. Must be the size of a timer control block object or larger.

\var osTimerAttr_t::name
\details
Pointer to a string with a human readable name of the timer object.\n
Default: \token{NULL}.
*/

{'fraction_non_alphanumeric': 0.16507986466283736, 'fraction_numerical': 0.01699582972696514, 'mean_word_length': 2.875438329013569, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 82, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6877383', 'n_tokens_mistral': 7323, 'n_tokens_neox': 6759, 'n_words': 2642}