wdtimer(9DDI)

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES

NAME

wdtimer- Watchdog TIMER Device Driver Interface

SYNOPSIS

#include <ddi/wdtimer/wdtimer.h>

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

DDI

DESCRIPTION

Provides an interface for watchdog timer device drivers.

EXTENDED DESCRIPTION

Service Routines

In general, a watchdog timer device can operate in two different modes, reset and interrupt.

When operating in reset mode, the watchdog device asserts a board reset signal if a watchdog time-out occurs. When operating in the interrupt mode, the watchdog device asserts an interrupt line if a watchdog time-out occurs. Some watchdog devices are hardwired to operate only in one mode, interrupt or reset. Others may be software configured to operate in either mode. The watchdog timer driver interface considers both modes.

The character string wdtimer names the timer device class. The driver client uses the device class name to get the driver service routines from the device registry by invoking svDeviceLookup().

The watchdog timer driver is a mono-client driver. The driver registry prevents multiple look-ups to be done on the same driver instance.

The WdtimerDevOps structure specifies the interface of the watchdog timer driver service routines.

State-to-state transactions and actions taken by each service routine, with respect to the current state, are as follows:

unarmed

The initial state of the driver after initialization

armed in reset mode state

The device is configured to operate in reset mode and the watchdog timer is armed with a given time-out period. Note that the watchdog timer not running.

armed in interrupt mode state

The device is configured to operate in interrupt mode and the watchdog timer is armed with a given time-out period. Note that the watchdog timer not running.

running in reset mode state

The device is running. When the time-out period is exhausted, the board reset occurs.

running in interrupt mode state

The device is running. When the time-out period is exhausted, an interrupt handler is called.

The watchdog timer handler contains the arm_reset(), arm_interrupt(), get_period(), start() and stop() service routines:

typedef void (*WdtimerHandler) (void* cookie);

typedef struct WdtimerDevOps {

     WdtimerVersion version;

        KnError
    (*arm_reset) (WdtimerId  id,
                  KnTimeVal* period);

        KnError
    (*arm_interrupt) (WdtimerId       id,
                      KnTimeVal*      period,
                      WdtimerHandler  handler,
                      void*           cookie);

        void
    (*get_period) (WdtimerId  id,
                   KnTimeVal* period);

        void
    (*start) (WdtimerId id);

        void
    (*stop) (WdtimerId id);

} WdtimerDevOps;

version

This field specifies the highest version number of the watchdog timer driver interface supported by the driver. Currently, only one version is available and therefore the version field must be set to zero, WDTIMER_VERSION_INITIAL. If the watchdog timer driver interface is extended, backward compatibility is guaranteed. Extra methods might be appended to the WdtimerDevOps structure but the existing methods will remain the same. This allows the device driver client adapt to different versions of the watchdog timer driver interface.

arm_reset()

configures the watchdog device to operate in reset mode and arms the watchdog timer with a given time-out period.

This routine must be called at base level only.

The id argument, given by the device registry entry, specifies the watchdog device identifier. The period argument specifies a requested watchdog time-out value.

Note that the driver may be unable to arm the timer with the requested time-out period. In such cases, the driver arms the timer with the closest possible value, greater than the requested one. The effectively armed time-out period may be examined calling the get_period() routine.

The limitations are watchdog device specific. For example, for the M48T559 watchdog timer, the minimal time-out period is 1/16 seconds and the maximal time-out period is 4*31 seconds. So, if a client of such a watchdog timer requests to set the time-out period to 3 minutes, the driver will return an error because the device cannot be programmed for a time-out of greater than 2 minutes and 4 seconds.

The time-out period is specified by a KnTimeVal structure:

typedef struct KnTimeVal {
    long tmSec;      /* seconds     */
    long tmNSec;     /* nanosecodns */
} KnTimeVal;

The tmSec field represents the number of seconds, and the tmNSec field represents the number of additional nanoseconds.

The following table shows the how actions taken by arm_reset() effect the state of the device.

Old State	New State	Action
Unarmed	Armed in reset mode	Setup reset mode and arm timer with a given period
Armed in reset mode	Armed in reset mode	Arm timer with a given period
Armed in interrupt mode	Armed in reset mode	Setup reset mode and arm timer with a given period
Running in reset mode	Armed in reset mode	Stop timer and arm timer with a given period
Running in interrupt mode	Armed in reset mode	Stop timer, setup reset mode and arm timer with a given period

arm_reset() returns K_OK on success. The K_EFAIL error code is returned if the driver is not able to arm the timer with a value greater than the requested time-out period (the requested time-out period is too long). The K_ENOTIMP error code is returned if the driver does not support reset mode.  

arm_interrupt()

This configures the watchdog device to operate in interrupt mode and arms the watchdog timer with a given time-out period.

This routine must be called at base level only.

The id argument, given by the device registry entry, specifies the watchdog device identifier. The period argument specifies a requested watchdog time-out value. The handler argument specifies the interrupt handler called when a watchdog interrupt occurs. The cookie argument specifies a cookie which is passed back to the interrupt handler. Note that when the interrupt handler is invoked, the watchdog timer is not running.

If a cyclic interrupt mode is desired, the watchdog timer should be remain in a running state by iteratively calling the start routine, after each watchdog interrupt has occured. The cyclic interrupt mode means that the driver client wishes to trigger the watchdog interrupt again, in the time-out period, once the watchdog interrupt has occurred. In other words, the driver client wishes to restart the watchdog timer within the watchdog interrupt handler. Such a cyclic interrupt mode might be used by the driver client in order to implement a watchdog interrupt time-out period which is greater than the watchdog hardware permits.

Note that the driver may be unable to arm the timer with the requested time-out period. In this case, the driver arms the timer with the closest possible value, greater than the requested one. The effectively armed time-out period may be examined by calling the get_period() routine. As previously mentioned, if the driver client needs a time-out period greater than the hardware permits, a cyclic interrupt schema might be implemented by the client.

In practice, the watchdog timer device provides reasonable limits. In addition, the interrupt mode is typically used in a two level watchdog model. In such a model, the system uses two watchdog timers: one programmed in interrupt mode and the other programmed in reset mode. Note that the interrupt time-out period is less than the reset time-out period. So, the resulting watchdog time-out period is still limited by the watchdog timer hardware running in reset mode.

The following table shows the how actions taken by arm_interrupt() effect the state of the device.

Old State	New State	Action
Unarmed	Armed in interrupt mode	Setup interrupt mode and arm timer with a given period
Armed in reset mode	Armed in interrupt mode	Setup interrupt mode and arm timer with a given period
Armed in interrupt mode	Armed in interrupt mode	Arm timer with a given period
Running in reset mode	Armed in interrupt mode	Stop timer, setup interrupt mode and arm timer with a given period
Running in interrupt mode	Armed in interrupt mode	Stop timer and arm timer with a given period

arm_interrupt() returns K_OK on success. The K_EFAIL error code is returned if the driver is not able to arm the timer with a value greater than the requested time-out period (the requested time-out period is too long). The K_ENOTIMP error code is returned if the driver does not support interrupt mode.  

get_period()

This returns the currently armed watchdog time-out period. The returned period specifies the initially configured time-out period.

This routine must be called at base level only.

The id argument, given by the device registry entry, specifies the watchdog device identifier. In the period output argument the driver returns the currently armed time-out period if the timer is armed, otherwise a zero value is returned.

Table 3 shows state transactions caused by the get_period invocation as well as period value returned in each state.

The following table shows the values returned by get_period() as a result of state transactions.

Old State	New State	Period value
Unarmed	Unarmed	Zero
Armed in reset mode	Armed in reset mode	Currently armed time-out
Armed in interrupt mode	Armed in interrupt mode	Currently armed time-out
Running in reset mode	Running in reset mode	Currently armed time-out
Running in interrupt mode	Running in interrupt mode	Currently armed time-out

Note that get_period() does not return an error code. Typically, get_period() does not access the watchdog hardware at all. It simply retrieves the time-out period, initially configured by arm_reset() or arm_interrupt(), from the driver's local data. get_period() indicates an operation failure by returning a zero value.

start()

Starts, or restarts, the watchdog timer. A watchdog reset or interrupt occurs if the driver has not been put in the armed state during the time-out period, since the last start invocation in the armed or running state.

This routine may be called at interrupt level.

The id argument, given by the device registry entry, specifies the watchdog device identifier.

The following table shows the how actions taken by start() effect the state of the device.

Old State	New State	Action
Unarmed	Unarmed	No action
Armed in reset mode	Running in reset mode	Start the timer
Armed in interrupt mode	Running in interrupt mode	Start the timer
Running in reset mode	Running in reset mode	Restart the timer
Running in interrupt mode	Running in interrupt mode	Restart the timer

stop()

Stops the watchdog timer, preventing a watchdog reset or interrupt occuring.

This routine may be called at interrupt level.

The id argument, given by the device registry entry, specifies the watchdog device identifier.

The following table shows the how actions taken by stop() effect the state of the device.

Old State	New State	Action
Unarmed	Unarmed	No action
Armed in reset mode	Armed in reset mode	No action
Armed in interrupt mode	Armed in interrupt mode	No action
Running in reset mode	Armed in reset mode	Stop the timer
Running in interrupt mode	Armed in interrupt mode	Stop the timer

Device Node Properties

Properties attached to the watchdog device node give the driver client certain physical characteristics of the watchdog timer. The driver client may consider such characteristics to determine whether this particular watchdog timer is appropriate.  

reset-mode

This property, WDTIMER_PROP_RESET_MODE, indicates that reset mode is supported by the watchdog timer driver. The property has no value.

intr-mode

This property, WDTIMER_PROP_INTR_MODE, indicates that the interrupt mode is supported by the watchdog timer driver. The property has no value.  

limits

The property, WDTIMER_PROP_LIMITS, specifies the allowed watchdog time-out limits. The property value is a WdtimerPropLimits structure, specifying the minimal and maximal allowed values.

typedef struct WdtimerPropLimits {
    KnTimeVal min;      /* minimal allowed time-out period */
    KnTimeVal max;      /* maximal allowed time-out period */
} WdtimerPropLimits;

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES