14 Watchdog Timers

The com.oracle.deviceaccess.power package contains interfaces and classes for using system watchdog timers (WDT).

A watchdog timer is used to reset or reboot the system in case of hang or critical failure from a unresponsive state to a normal state. A watchdog timer can be set with a time interval. Continuously refreshing the watchdog timer within the specified time interval prevents the a reset or reboot. If the watchdog timer has not been refreshed within the specified time interval, a critical failure is assumed and a system reset or reboot is carried out. Note that a windowed watchdog timer must be refreshed within an open time window. If the watchdog is refreshed too soon, during the closed window, or if it is refreshed too late, after the watchdog timeout has expired, the device will be rebooted.

A watchdog timer can be created using its ID.

 WatchdogTimer wdt = (WatchdogTimer)PeripheralManager.open(8);

A watchdog timer can also be created using its name and interface.

 WatchdogTimer wdt = (WatchdogTimer) PeripheralManager.open("WDT",
     WatchdogTimer.class, null);

Here is an example of how to create a windowed watchdog timer.

 WindowedWatchdogTimer wdt = (WindowedWatchdogTimer)
     PeripheralManager.open("WWDT", WindowedWatchdogTimer.class, null);

Once the peripheral opened, the application can start using it and can especially start the timer using the WatchdogTimer.start() method and subsequently refresh the timer periodically using the WatchdogTimer.refresh() method, as shown here:

 wdt.start(1000);
 ...
 wdt.refresh();

When done, the application should call the WatchdogTimer.close() method to release the watchdog timer.

 wdt.close();

Example 14-1 gives a demonstration of using the watchdog timer API.

Example 14-1 Using the Watchdog API

import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.PeripheralNotAvailableException;
import com.oracle.deviceaccess.PeripheralNotFoundException;
import com.oracle.deviceaccess.watchdog.WatchdogTimer;
import java.io.IOException;
 
public class WatchdogExample {
 
    public boolean checkSomeStatus() {
        // check some status....
        // if status is ok then return true to kick watch dog timer.
        return true;
    }
 
    public void test_loop() {
        try {
            WatchdogTimer watchdogTimer = (WatchdogTimer)
                 PeripheralManager.open(30);
            watchdogTimer.start(180000); 
            // Start watch dog timer with 3 min duration.
 
            while (true) {
                if (checkSomeStatus() == true) {
                    // Everything goes fine, timer will be kick.
                    watchdogTimer.refresh();
                    // do something more...
                } else {
                    // Something goes wrong. Timer will not be kick.
                    // If status not recovered within 2-3 turns then
                    // system will be reboot.
                }
                try {
                    Thread.sleep(60000); // sleep for 1 min.
                } catch (InterruptedException ex) {
                    ex.printStackTrace();
                }
            }
        } catch (PeripheralNotAvailableException ex) {
            ex.printStackTrace();
        } catch (PeripheralNotFoundException ex) {
            ex.printStackTrace();
        } catch (IOException ex) {
            ex.printStackTrace();
        }
    }
}

Watchdog timers are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open() methods. The com.oracle.deviceaccess.watchdog permission allows access to be granted to watchdog timers devices as a whole. This permission must be requested in the JAD file under MIDlet-Permissions or MIDlet-Permissions-Opt, and the application must be digitally signed by a trusted authority to gain access to the APIs. Alternatively, the permission may be allowed for all applications in the untrusted domain of the security policy file (policy.txt).

The WatchdogTimer Interface

The WatchdogTimer interface provides methods for controlling a watchdog timer that can be used to force the device to reboot (or depending on the platform, the Java Virtual Machine to restart).

A WatchdogTimer instance may represent a virtual watchdog timer. If the device has a single physical watchdog timer, all of the virtual watchdog timers are mapped onto this one physical watchdog timer. This timer is set to expire when the virtual watchdog with the earliest timeout is scheduled to expire. The corresponding watchdog timer peripheral is therefore shared and several applications can concurrently acquire the same watchdog timer peripheral.

Each watchdog timer is identified by a numerical ID and by a name. If a watchdog timer is virtualized, a particular platform implementation may allow for several WatchdogTimer instances representing each a virtual instance of that same physical watchdog timer to be opened concurrently. Alternatively, it may assign each virtual watchdog timer instance a distinct peripheral ID and optionally a common name.

A WatchdogTimer instance can be opened by a call to one of the PeripheralManager.open() methods. Once the peripheral opened, the application can start using it and can especially start the timer using the WatchdogTimer.start() method and subsequently refresh the timer periodically using the WatchdogTimer.refresh() method

When done, an application should call the WatchdogTimer.close() method to release the watchdog timer. Any further attempt to access or control a watchdog timer which has been closed will result in a PeripheralNotAvailableException been thrown.

The WatchdogTimer interface contains six methods.

void start(long timeout) throws java.io.IOException, PeripheralNotAvailableException

This method starts the watchdog timer with the specified timeout. If the watchdog timer is not refreshed by a call to refresh() prior to the watchdog timing out, the device will be rebooted (or the JVM restarted).
void refresh() throws java.io.IOException, PeripheralNotAvailableException

This method refreshes the watchdog timer. This method must be called periodically to prevent the watchdog from timing out.
void stop() throws java.io.IOException, PeripheralNotAvailableException

This method stops this watchdog timer.
long getTimeout() throws java.io.IOException, PeripheralNotAvailableException

This method returns the current timeout for the watchdog timer. A value of zero (0) indicates that the watchdog timer is disabled.
long getMaxTimeout() throws java.io.IOException, PeripheralNotAvailableException

This method returns the maximum timeout that can be set for the watchdog timer.
boolean causedLastReboot() throws java.io.IOException, PeripheralNotAvailableException

This method checks if the last device reboot (or JVM restart) was caused by the watchdog timing out.

The WindowedWatchdogTimer Interface

The WindowedWatchdogTimer interface provides methods for controlling a watchdog timer that can be used to force the device to reboot (or depending on the platform, the Java Virtual Machine to restart). A windowed watchdog timer must be refreshed within an open time window. If the watchdog is refreshed too soon, during the closed window, or if it is refreshed too late, after the watchdog timeout has expired, the device will be rebooted

A WindowedWatchdogTimer instance may represent a virtual windowed watchdog timer. If the device has a single physical windowed watchdog timer, all of the virtual watchdog timers are mapped onto this one physical watchdog timer. It gets set with a refresh window starting when the virtual windowed watchdog with the longest closed window delay is scheduled to end and ending when the virtual windowed watchdog with the earliest timeout is scheduled to expire. The corresponding watchdog timer peripheral is therefore shared and several applications can concurrently acquire the same watchdog timer peripheral.

The WindowedWatchdogTimer class consists of three methods:

void start(long timeout) throws java.io.IOException, PeripheralNotAvailableException

This method starts the watchdog timer with the specified timeout and with a closed window delay set to zero (0). If the watchdog timer is not refreshed by a call to WatchdogTimer.refresh() prior to the watchdog timing out, the device will be rebooted (or the JVM restarted).
void start(long closedWindowDelay, long timeout) throws java.io.IOException, PeripheralNotAvailableException

This method starts a windowed watchdog timer with the specified closed window time and timeout. If the WatchdogTimer.refresh() method is called too soon, within the closed window delay, or is called too late, not prior to the watchdog timing out, the watchdog timer will not be reset.
long getClosedWindowTimeout() throws java.io.IOException, PeripheralNotAvailableException

This method returns the current closed window delay for the watchdog timer.