HAL_Watchdog (changes)

Showing changes from revision #1 to #2: Added | Removed | Changed

Hardware Abstraction Layer

HAL entry points from RISC OS

» HAL_Watchdog

HAL_Watchdog

(HAL entry #121)

int HAL_Watchdog(int reason, ...)

This is a multi-function entry point which has different parameters and return values depending on the reason code.

Reason 0 – Report capabilities

WDinfo *HAL_Watchdog(int reason)

typedef struct
{
    int WDFlags;       // Flags, as defined below
    int WDResolution;  // unit size in ms for timeouts
    int WDMaxTimeout;  // in WDResolution steps
    int WDMaxTOWarn;   // WDResolution steps for early warning IRQ (0 if not supported)
    int IRQNum;        // IRQ number if relevant
    int NTickle;       // number of tickle values that follow
    int TickleData[0]; // Tickle values (variable-length array)
} WDinfo;

#define WDFlag_HardReset    (1<<0)
#define WDFlag_HasTimeout   (1<<1)
#define WDFlag_HasWarnIRQ   (1<<2)
#define WDFlag_WontTurnOff  (1<<3)

If the WDFlag_HardReset flag is set then it indicates that the watchdog performs the equivalent of a hard reset, e.g. as if the machine’s physical reset button had been pressed. If the flag is clear then it indicates another reset mechanism is used (to be defined in later versions of the spec).

Similarly, if WDFlag_HasTimeout is set then it indicates that the watchdog will fire after a given timeout period. If the flag is clear then situations under which the watchdog fires are unspecified.

If WDFlag_HasWarnIRQ is set then it indicates that the watchdog is capable of generating a warning interrupt if the watchdog timer hasn’t been reset for a given period of time. time prior to the watchdog timeout firing.

If WDFlag_WontTurnOff is set then it indicates that once started, the watchdog timer cannot be stopped (except by hard reset or power-off)

Reason 1 – Start/stop watchdog timer

void HAL_Watchdog(int reason, int timeout, int warning, int magic)

Use

This call can be used to enable or disable the watchdog timer. If magic is not 0xdeaddead then the call will do nothing.

If timeout is zero (and the watchdog can be stopped) then both the watchdog and the warning IRQ timer will be stopped.

If timeout is non-zero then it must be a value between 1 and WDMaxTimeout, specifying the time (in units of WDResolution milliseconds) until the watchdog will fire. If warning is zero then the warning IRQ timer will be left disabled. Otherwise, if the warning timer is supported, warning must be a value between 1 and WDMaxTOWarn specifying the time (in units of WDResolution) until that the warningIRQ will fire. fire prior to watchdog timeout.

This call can also be used to adjust the timeout values for a running watchdog. Once the new timeout values have been set, they will only take effect once the current tickle sequence has been completed.

Reason 2 – Write watchdog tickle address

void HAL_Watchdog(int reason, int tickle)

Use

Once the watchdog has been started, this call must be made at regular intervals in order to ‘tickle’ the watchdog and prevent it from firing. Once the full sequence of tickle values (as defined in the WDinfo struct) have been written, both the watchdog timer and warning timer will reset to their initial value as set via the watchdog start call. Failure to write the full sequence in time will result in the reset action and/or firing. warning TheIRQ firing. will fire if the full sequence has not been written by the time it is due. This is an early warning of timeout, and should ideally lead to recovery before the watchdog actually fires.

Exact behaviour if tickle values are written out-of-sequence is undefined. The current tickle state will not advance, but other side-effects may occur (e.g. tickle state reset to start of sequence, or immediate system reset)

Reason 3 – Acknowledge timeout warning IRQ

void HAL_Watchdog(int reason)

Use

If the timeout warning IRQ fires then this call should be used to acknowledge the IRQ state within the watchdog. The IRQ will not fire again until the current tickle sequence has been completed and the warning timer begins to run again.

After making this call, HAL_IRQClear/HAL_FIQClear must also be called to clear any latching in the interrupt controller.