Nut/OS  4.10.3
API Reference
Timer Management

Asynchronous timer support. More...

Collaboration diagram for Timer Management:

Functions

void NutTimerInit (void)
 Initialize system timer.
void NutMicroDelay (uint32_t us)
 Loop for a specified number of microseconds.
void NutDelay (uint8_t ms)
 Loop for a specified number of milliseconds.
void NutTimerInsert (NUTTIMERINFO *tn)
 Insert a new timer in the global timer list.
void NutTimerProcessElapsed (void)
 Process elapsed timers.
NUTTIMERINFONutTimerCreate (uint32_t ticks, void(*callback)(HANDLE, void *), void *arg, uint8_t flags)
 Create a new system timer.
HANDLE NutTimerStartTicks (uint32_t ticks, void(*callback)(HANDLE, void *), void *arg, uint8_t flags)
 Start a system timer.
HANDLE NutTimerStart (uint32_t ms, void(*callback)(HANDLE, void *), void *arg, uint8_t flags)
 Start a system timer.
void NutSleep (uint32_t ms)
 Temporarily suspends the current thread.
void NutTimerStop (HANDLE handle)
 Stop a specified timer.
uint32_t NutGetTickCount (void)
 Return the number of system timer ticks.
uint32_t NutGetSeconds (void)
 Return the seconds counter value.
uint32_t NutGetMillis (void)
 Return the milliseconds counter value.
int NutClockSet (int idx, uint32_t freq)
 Return the specified clock frequency.
uint32_t NutGetCpuClock (void)
 Return the CPU clock frequency.

Variables

NUTTIMERINFOnutTimerList
 Double linked list of all system timers.
volatile uint32_t nut_ticks
 System tick counter.
uint32_t nut_delay_loops
 Loops per microsecond.

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.


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.

Definition at line 306 of file timer.c.

References nut_delay_loops, NutEnableTimerIrq, NutGetTickCount(), and NutRegisterTimer().

Referenced by NutIdle().

Here is the call graph for this function:

void NutMicroDelay ( uint32_t  us)

Loop for a specified number of microseconds.

This routine can be used for short delays below the system tick time, mainly when driving external hardware, where the resolution of NutSleep() wouldn't fit, a thread switch would be undesirable or in early system initialization stage, where the system timer is not available. In all other cases NutSleep() should be used.

This call will not release the CPU and will not switch to another thread. However, interrupts are not disabled and introduce some jitter. Furthermore, unless NUT_DELAYLOOPS is not defined, the deviation may be greater than 10%.

For delays below 100 microseconds, the deviation may increase above 200%. In any case the delay should always be at least as large as specified. If in doubt, use a simple port bit toggle routine to check the result with an oscilloscope or frequency counter and adjust NUT_DELAYLOOPS accordingly.

In any case, if you need exact timing, use timer/counter hardware instead.

Parameters:
usDelay time in microseconds. Values above 255 milliseconds may not work.
Todo:
Overflow handling.

Definition at line 373 of file timer.c.

References _NOP, and nut_delay_loops.

Referenced by NutDelay(), and TapTargetReset().

void NutDelay ( uint8_t  ms)

Loop for a specified number of milliseconds.

This call will not release the CPU and will not switch to another thread. Because of absent thread switching, the delay time is more exact than with NutSleep().

Parameters:
msDelay time in milliseconds, maximum is 255.
Deprecated:
New applications should use NutMicroDelay().

Definition at line 397 of file timer.c.

References NutMicroDelay().

Referenced by cs8900Init(), CSNicInit(), CSSoftwareWakeup(), SpiFlashErase(), SpiFlashWriteByte(), VsBeep(), VsMemoryTest(), VsPlayerInit(), and VsPlayerReset().

Here is the call graph for this function:

void NutTimerInsert ( NUTTIMERINFO tn)

Insert a new timer in the global timer list.

Applications should not call this function.

Parameters:
tnPointer to the timer structure to insert.
Todo:
Make this local function static.

Definition at line 411 of file timer.c.

References NUTASSERT, _NUTTIMERINFO::tn_next, _NUTTIMERINFO::tn_prev, and _NUTTIMERINFO::tn_ticks_left.

Referenced by NutTimerProcessElapsed(), NutTimerStartTicks(), and NutTimerStop().

void NutTimerProcessElapsed ( void  )

Process elapsed timers.

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

Definition at line 444 of file timer.c.

References NutGetTickCount(), NutHeapFree, NutTimerInsert(), nutTimerList, _NUTTIMERINFO::tn_arg, _NUTTIMERINFO::tn_callback, _NUTTIMERINFO::tn_next, _NUTTIMERINFO::tn_prev, _NUTTIMERINFO::tn_ticks, and _NUTTIMERINFO::tn_ticks_left.

Referenced by NutThreadResume().

Here is the call graph for this function:

NUTTIMERINFO* NutTimerCreate ( uint32_t  ticks,
void(*)(HANDLE, void *)  callback,
void *  arg,
uint8_t  flags 
)

Create a new system timer.

Applications should not call this function.

Parameters:
ticksSpecifies the timer interval in system ticks.
callbackIdentifies the function to be called on each timer interval.
argThe argument passed to the callback function.
flagsIf 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().

Definition at line 511 of file timer.c.

References NutGetTickCount(), NutHeapAlloc, TM_ONESHOT, _NUTTIMERINFO::tn_arg, _NUTTIMERINFO::tn_callback, _NUTTIMERINFO::tn_ticks, and _NUTTIMERINFO::tn_ticks_left.

Referenced by NutTimerStartTicks().

Here is the call graph for this function:

HANDLE NutTimerStartTicks ( uint32_t  ticks,
void(*)(HANDLE, void *)  callback,
void *  arg,
uint8_t  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:
ticksSpecifies the timer interval in system ticks.
callbackIdentifies the function to be called on each timer interval.
argThe argument passed to the callback function.
flagsIf 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.

Definition at line 562 of file timer.c.

References NutTimerCreate(), and NutTimerInsert().

Referenced by NutTimerStart().

Here is the call graph for this function:

HANDLE NutTimerStart ( uint32_t  ms,
void(*)(HANDLE, void *)  callback,
void *  arg,
uint8_t  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:
msSpecifies the timer interval in milliseconds. The resolution is limited to the granularity of the system timer.
callbackIdentifies the function to be called on each timer interval.
argThe argument passed to the callback function.
flagsIf 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.

Definition at line 602 of file timer.c.

References NutTimerMillisToTicks(), and NutTimerStartTicks().

Referenced by main(), NutEventWait(), NutMsgQStartTimer(), NutRegisterKey(), NutRegisterLed(), and NutSleep().

Here is the call graph for this function:

void NutSleep ( uint32_t  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:
msMilliseconds 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.

Definition at line 628 of file timer.c.

References NutThreadRemoveQueue(), NutThreadResume(), NutThreadWake(), NutThreadYield(), NutTimerStart(), runningThread, runQueue, _NUTTHREADINFO::td_qnxt, _NUTTHREADINFO::td_queue, _NUTTHREADINFO::td_state, _NUTTHREADINFO::td_timer, TDS_RUNNING, TDS_SLEEP, TM_ONESHOT, TRACE_ADD_ITEM, and TRACE_TAG_THREAD_SLEEP.

Referenced by AhdlcRx(), At45dbWaitReady(), At45dNodeWaitReady(), AvrTargetPollReady(), CFChange(), CSNICrx(), DiscoveryResponder(), EmacRxThread(), FeederThread(), High(), Low(), main(), NicInit(), NicRx(), NicRxAsix(), NicRxLanc(), NotifyTask(), NutDhcpIfConfig(), NutFtpTransferFile(), NutPppInput(), NutPppOutput(), NutPppSm(), Service(), Sleeper1(), Sleeper2(), Sleeper3(), Sleeper4(), SNTP_resync(), SSDPTask(), Thread1(), Thread2(), TwMasterTransact(), VsCodecMode(), wlandrv_ProbeDevice(), and X12Init().

Here is the call graph for this function:

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:
handleIdentifies the timer to be stopped. This handle must have been created by calling NutTimerStart() or NutTimerStartTicks().

Definition at line 665 of file timer.c.

References NUTASSERT, NutTimerInsert(), _NUTTIMERINFO::tn_callback, _NUTTIMERINFO::tn_next, _NUTTIMERINFO::tn_prev, _NUTTIMERINFO::tn_ticks, and _NUTTIMERINFO::tn_ticks_left.

Referenced by main(), NutEventPostAsync(), and NutMsgQStopTimer().

Here is the call graph for this function:

uint32_t 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.

Definition at line 699 of file timer.c.

References nut_ticks, NutEnterCritical, and NutExitCritical.

Referenced by DiscoveryResponder(), main(), NutGetMillis(), NutGetSeconds(), NutTcpCreateSocket(), NutTimerCreate(), NutTimerInit(), and NutTimerProcessElapsed().

uint32_t 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.

Definition at line 731 of file timer.c.

References NutGetTickClock(), and NutGetTickCount().

Referenced by DhcpStateDebug(), NutDhcpClient(), stime(), and time().

Here is the call graph for this function:

uint32_t 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 32 bit tick counter (4294967296). With the default 1024 ticks/s this will happen after 49.71 days. 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.

Definition at line 752 of file timer.c.

References NutGetTickClock(), and NutGetTickCount().

Referenced by NutConditionTimedWait(), NutDhcpClient(), NutGetKeyTime(), NutTcpCalcRtt(), NutTcpOutput(), NutTcpSm(), NutTcpStateRetranTimeout(), sys_key(), and sys_led().

Here is the call graph for this function:

int NutClockSet ( int  idx,
uint32_t  freq 
)

Return the specified clock frequency.

If only 1 hardware clock is defined, then this function is mapped to NutGetCpuClock().

The number of available hardware clocks depends on the target harware and is specified by NUT_HWCLK_MAX + 1.

Parameters:
idxIndex of the hardware clock. Can be any of the following:
  • NUT_HWCLK_CPU
  • NUT_HWCLK_PERIPHERAL
Returns:
CPU clock frequency in Hertz.

Set the specified clock frequency.

In the future this may be used to set any hardware clock. For now, this simply clears the clock value cache and must be called after changing any clock frequency.

Parameters:
idxIndex of the hardware clock, currently ignored. Set to -1 (all clocks) to maintain upward compatibility.
freqClock frequency in Hertz, currently ignored. Set to NUT_CACHE_LVALID (release cached value) to maintain upward compatibility.
Returns:
Always 0.

Definition at line 801 of file timer.c.

References memset().

Here is the call graph for this function:

uint32_t NutGetCpuClock ( void  )

Return the CPU clock frequency.

Same as NutClockGet(NUT_HWCLK_CPU) but faster, specially when NUT_CPU_FREQ is defined.

Returns:
CPU clock frequency in Hertz.

Definition at line 818 of file timer.c.

References NUT_CACHE_LVALID, NUT_CPU_FREQ, NUT_HWCLK_CPU, NutArchClockGet(), and NutClockGet.

Referenced by AhdlcAt91Init(), AhdlcAt91IOCtl(), AhdlcAvrIOCtl(), At91WatchDogStart(), IrblastFreq2Ocr(), IrblastPeriod2Ocr(), main(), NutGetTickClock(), NutInit(), NutRegisterTimer(), Sbbi0SetSpeed(), SpiDigitalInit(), Sppi0SetSpeed(), TwIOCtl(), and UartAvrIOCtl().

Here is the call graph for this function:


Variable Documentation

Double linked list of all system timers.

Definition at line 245 of file timer.c.

Referenced by NutDumpTimerList(), and NutTimerProcessElapsed().

volatile uint32_t nut_ticks

System tick counter.

Definition at line 255 of file timer.c.

Referenced by NutGetTickCount().

Loops per microsecond.

Definition at line 267 of file timer.c.

Referenced by NutMicroDelay(), and NutTimerInit().