Timer Management
[Nut/OS API]

Collaboration diagram for Timer Management:

---

Detailed Description

Asynchronous timer support.

The timer management provides functions to start and stop asynchronous timers, determine the CPU speed and let a thread give up the CPU for a specified time period.

Functions
void	NutTimerInit (void)
	Initialize system timer.
void	NutTimerInsert (NUTTIMERINFO *tn)
	Insert a new timer in the global timer list.
void	NutTimerProcessElapsed (void)
	Process elapsed timers.
NUTTIMERINFO *	NutTimerCreate (u_long ticks, void(*callback)(HANDLE, void *), void *arg, u_char flags)
	Create a new system timer.
HANDLE	NutTimerStartTicks (u_long ticks, void(*callback)(HANDLE, void *), void *arg, u_char flags)
	Start a system timer.
HANDLE	NutTimerStart (u_long ms, void(*callback)(HANDLE, void *), void *arg, u_char flags)
	Start a system timer.
void	NutSleep (u_long ms)
	Temporarily suspends the current thread.
void	NutTimerStop (HANDLE handle)
	Stop a specified timer.
u_long	NutGetTickCount (void)
	Return the number of system timer ticks.
u_long	NutGetSeconds (void)
	Return the seconds counter value.
u_long	NutGetMillis (void)
	Return the milliseconds counter value.
Variables
NUTTIMERINFO *	nutTimerList
	Double linked list of all system timers.
volatile u_long	nut_ticks
	System tick counter.

---

Function Documentation

void NutTimerInit (  void   )

Initialize system timer. This function is automatically called by Nut/OS during system initialization. It calls the hardware dependent layer to initialze the timer hardware and register a timer interrupt handler.

void NutTimerInsert (  NUTTIMERINFO *  tn  )

Insert a new timer in the global timer list. Applications should not call this function. Parameters: tn  Pointer to the timer structure to insert. Todo: Make this local function static.

void NutTimerProcessElapsed (  void   )

Process elapsed timers. This routine is called during context switch processing. Applications should not use this function.

NUTTIMERINFO* NutTimerCreate (  u_long  ticks, void(*)(HANDLE, void *)  callback, void *  arg, u_char  flags )

Create a new system timer. Applications should not call this function. Parameters: ticks  Specifies the timer interval in system ticks. callback  Identifies the function to be called on each timer interval. arg  The argument passed to the callback function. flags  If set to TM_ONESHOT, the timer will be stopped after the first interval. Set to 0 for periodic timers. Returns: Timer handle if successfull, 0 otherwise. The handle may be used to release the timer by calling TimerStop. Todo: Make this local function static or directly integrate it into NutTimerStartTicks().

HANDLE NutTimerStartTicks (  u_long  ticks, void(*)(HANDLE, void *)  callback, void *  arg, u_char  flags )

Start a system timer. The function returns immediately, while the timer runs asynchronously in the background. The timer counts for a specified number of ticks, then calls the callback routine with a given argument. Even after the timer elapsed, the callback function is not executed before the currently running thread is ready to give up the CPU. Thus, system timers may not fulfill the required accuracy. For precise or high resolution timing, native timer interrupt routines are a better choice. Parameters: ticks  Specifies the timer interval in system ticks. callback  Identifies the function to be called on each timer interval. arg  The argument passed to the callback function. flags  If set to TM_ONESHOT, the timer will be stopped after the first interval. Set to 0 for periodic timers. Returns: Timer handle if successfull, 0 otherwise. The handle may be used to stop the timer by calling TimerStop.

HANDLE NutTimerStart (  u_long  ms, void(*)(HANDLE, void *)  callback, void *  arg, u_char  flags )

Start a system timer. The function returns immediately, while the timer runs asynchronously in the background. The timer counts for a specified number of milliseconds, then calls the callback routine with a given argument. Even after the timer elapsed, the callback function is not executed before the currently running thread is ready to give up the CPU. Thus, system timers may not fulfill the required accuracy. For precise or high resolution timing, native timer interrupt routines are a better choice. Parameters: ms  Specifies the timer interval in milliseconds. The resolution is limited to the granularity of the system timer. callback  Identifies the function to be called on each timer interval. arg  The argument passed to the callback function. flags  If set to TM_ONESHOT, the timer will be stopped after the first interval. Set to 0 for periodic timers. Returns: Timer handle if successfull, 0 otherwise. The handle may be used to stop the timer by calling TimerStop.

void NutSleep (  u_long  ms  )

Temporarily suspends the current thread. Causes the current thread to wait for a specified interval or, if the specified interval is zero, to give up the CPU for another thread with higher or same priority. This function may switch to another application thread, that got the same or a higher priority and is ready to run. Note: Threads may sleep longer than the specified number of milliseconds, depending on the number of threads with higher or equal priority, which are ready to run. Parameters: ms  Milliseconds to sleep. If 0, the current thread will not sleep, but may give up the CPU. The resolution is limited to the granularity of the system timer. Todo: Code size can be reduced by trying to create the timer before removing the thread from the run queue.

void NutTimerStop (  HANDLE  handle  )

Stop a specified timer. Only periodic timers need to be stopped. One-shot timers are automatically stopped by the timer management after ther first timer interval. Anyway, long running one-shot timers may be stopped to release the occupied memory. Parameters: handle  Identifies the timer to be stopped. This handle must have been created by calling NutTimerStart() or NutTimerStartTicks().

u_long NutGetTickCount (  void   )

Return the number of system timer ticks. This function returns the number of system ticks since the system was started. Returns: Number of ticks.

u_long NutGetSeconds (  void   )

Return the seconds counter value. This function returns the value of a counter, which is incremented every second. During system start, the counter is cleared to zero. Note: There is intentionally no provision to modify the seconds counter. Callers can rely on a continuous update and use this value for system tick independend timeout calculations. Applications, which want to use this counter for date and time functions, should use an offset value. Returns: Value of the seconds counter.

u_long NutGetMillis (  void   )

Return the milliseconds counter value. This function returns the value of a counter, which is incremented every system timer tick. During system start, the counter is cleared to zero and will overflow with the 64 bit tick counter (4294967296). With the default 1024 ticks/s this will happen after 7.9 years. The resolution is also given by the system ticks. Note: There is intentionally no provision to modify the seconds counter. Callers can rely on a continuous update and use this value for system tick independend timeout calculations. Depending on Returns: Value of the seconds counter.

---