wdLib VxWorks Reference Manual : Libraries wdLib NAME wdLib - watchdog timer library ROUTINES wdCreate( ) - create a watchdog timer wdDelete( ) - delete a watchdog timer wdStart( ) - start a watchdog timer wdCancel( ) - cancel a currently counting watchdog DESCRIPTION This library provides a general watchdog timer facility. Any task may create a watchdog timer and use it to run a specified routine in the context of the system-clock ISR, after a specified delay. Once a timer has been created with wdCreate( ), it can be started with wdStart( ). The wdStart( ) routine specifies what routine to run, a parameter for that routine, and the amount of time (in ticks) before the routine is to be called. (The timeout value is in ticks as determined by the system clock; see sysClkRateSet( ) for more information.) After the specified delay ticks have elapsed (unless wdCancel( ) is called first to cancel the timer) the timeout routine is invoked with the parameter specified in the wdStart( ) call. The timeout routine is invoked whether the task which started the watchdog is running, suspended, or deleted. The timeout routine executes only once per wdStart( ) invocation; there is no need to cancel a timer with wdCancel( ) after it has expired, or in the expiration callback itself. Note that the timeout routine is invoked at interrupt level, rather than in the context of the task. Thus, there are restrictions on what the routine may do. Watchdog routines are constrained to the same rules as interrupt service routines. For example, they may not take semaphores, issue other calls that may block, or use I/O system routines like printf( ). EXAMPLE In the fragment below, if maybeSlowRoutine( ) takes more than 60 ticks, logMsg( ) will be called with the string as a parameter, causing the message to be printed on the console. Normally, of course, more significant corrective action would be taken. WDOG_ID wid = wdCreate (); wdStart (wid, 60, logMsg, "Help, I've timed out!"); maybeSlowRoutine (); /* user-supplied routine */ wdCancel (wid); INCLUDE FILES wdLib.h SEE ALSO wdLib, logLib, VxWorks Programmer's Guide: Basic OS Libraries : Routines wdCreate( ) NAME wdCreate( ) - create a watchdog timer SYNOPSIS WDOG_ID wdCreate (void) DESCRIPTION This routine creates a watchdog timer by allocating a WDOG structure in memory. RETURNS The ID for the watchdog created, or NULL if memory is insufficient. SEE ALSO wdLib, wdDelete( ) Libraries : Routines wdDelete( ) NAME wdDelete( ) - delete a watchdog timer SYNOPSIS STATUS wdDelete ( WDOG_ID wdId /* ID of watchdog to delete */ ) DESCRIPTION This routine de-allocates a watchdog timer. The watchdog will be removed from the timer queue if it has been started. This routine complements wdCreate( ). RETURNS OK, or ERROR if the watchdog timer cannot be de-allocated. SEE ALSO wdLib, wdCreate( ) Libraries : Routines wdStart( ) NAME wdStart( ) - start a watchdog timer SYNOPSIS STATUS wdStart ( WDOG_ID wdId, /* watchdog ID */ int delay, /* delay count, in ticks */ FUNCPTR pRoutine, /* routine to call on time-out */ int parameter /* parameter with which to call routine */ ) DESCRIPTION This routine adds a watchdog timer to the system tick queue. The specified watchdog routine will be called from interrupt level after the specified number of ticks has elapsed. Watchdog timers may be started from interrupt level. To replace either the timeout delay or the routine to be executed, call wdStart( ) again with the same wdId; only the most recent wdStart( ) on a given watchdog ID has any effect. (If your application requires multiple watchdog routines, use wdCreate( ) to generate separate a watchdog ID for each.) To cancel a watchdog timer before the specified tick count is reached, call wdCancel( ). Watchdog timers execute only once, but some applications require periodically executing timers. To achieve this effect, the timer routine itself must call wdStart( ) to restart the timer on each invocation. WARNING The watchdog routine runs in the context of the system-clock ISR; thus, it is subject to all ISR restrictions. RETURNS OK, or ERROR if the watchdog timer cannot be started. SEE ALSO wdLib, wdCancel( ) Libraries : Routines wdCancel( ) NAME wdCancel( ) - cancel a currently counting watchdog SYNOPSIS STATUS wdCancel ( WDOG_ID wdId /* ID of watchdog to cancel */ ) DESCRIPTION This routine cancels a currently running watchdog timer by zeroing its delay count. Watchdog timers may be canceled from interrupt level. RETURNS OK, or ERROR if the watchdog timer cannot be canceled. SEE ALSO wdLib, wdStart( )
