Timer Management

µC/TCP-IP manages software timers used to keep track of various network-related timeouts. Timer management functions are found in net_tmr.*. Timers are required for:

Of the three mandatory µC/TCP-IP tasks, one of them, the timer task, is used to manage and update timers. The timer task updates timers periodically. NET_TMR_CFG_TASK_FREQ determines how often (in Hz) network timers are to be updated. This value must not be configured as a floating-point number. This value is typically set to 10 Hz.

NET_TMR_CFG_NBR_TMR determines the number of timers that µC/TCP-IP will be managing. Of course, the number of timers affect the amount of RAM required by µC/TCP-IP. Each timer requires 12 bytes plus 4 pointers. 

It is recommended to set NET_TMR_CFG_NBR_TMR with at least 12 timers, but a better starting point may be to allocate the maximum number of timers for all resources.

For instance, if 10 ARP caches are configured (NET_ARP_CFG_CACHE_NBR = 10), 10 NDP caches are configured (NET_NDP_CFG_CACHE_NBR= 10) and 10 TCP connections are configured (NET_TCP_CFG_NBR_CONN = 10); the maximum number of timers for these resources is 1 for the Network Performance Monitor, 1 for the Link State Handler, (10 * 1) for the ARP caches, (10 * 1) for the NDP caches and (10 * 7) for TCP connections:

# Timers = 1 + 1 + (10 * 1) + (10 * 1) + (10 * 7) = 92

The flags field is currently unused.

Network timers are managed by the Timer task in a doubly-linked Timer List. The function that executes these operation is the NetTmr_TaskHandler() function. This function is an operating system (OS) function and should be called only by appropriate network-operating system port function(s). NetTmr_TaskHandler() is blocked until network initialization completes.

NetTmr_TaskHandler() handles the network timers in the Timer List by acquiring the global network lock first. This function blocks all other network protocol tasks by pending on and acquiring the global network lock. Then it handles every network timer in Timer List by decrementing the network timer(s) and for any timer that expires, execute the timer's callback function and free the timer from Timer List. When a network timer expires, the timer is be freed prior to executing the timer callback function. This ensures that at least one timer is available if the timer callback function requires a timer. Finally, NetTmr_TaskHandler() releases the global network lock.

New timers are added at the head of the Timer List. As timers are added into the list, older timers migrate to the tail of the Timer List. Once a timer expires or is discarded, it is removed.

NetTmr_TaskHandler() handles of all the valid timers in the Timer List, up to the first corrupted timer. If a corrupted timer is detected, the timer is discarded/unlinked from the List. Consequently, any remaining valid timers are unlinked from Timer List and are not handled. Finally, the Timer task is aborted.

Since NetTmr_TaskHandler() is asynchronous to ANY timer Get/Set, one additional tick is added to each timer's count-down so that the requested timeout is always satisfied. This additional tick is added by NOT checking for zero ticks after decrementing; any timer that expires is recognized at the next tick.

A timer value of 0 ticks/seconds is allowed. The next tick will expire the timer.

The NetTmr_***() functions are internal functions and should not be called by application functions. This is the reason they are not described here or in TCPIP API Reference Core. For more details on these functions, please refer to the net_tmr.* files.