include/wdt.h

   1 /*
   2  * Copyright 2017 Google, Inc
   3  *
   4  * SPDX-License-Identifier:     GPL-2.0+
   5  */
   6
   7 #ifndef _WDT_H_
   8 #define _WDT_H_
   9
  10 /*
  11  * Implement a simple watchdog uclass. Watchdog is basically a timer that
  12  * is used to detect or recover from malfunction. During normal operation
  13  * the watchdog would be regularly reset to prevent it from timing out.
  14  * If, due to a hardware fault or program error, the computer fails to reset
  15  * the watchdog, the timer will elapse and generate a timeout signal.
  16  * The timeout signal is used to initiate corrective action or actions,
  17  * which typically include placing the system in a safe, known state.
  18  */
  19
  20 /*
  21  * Start the timer
  22  *
  23  * @dev: WDT Device
  24  * @timeout_ms: Number of ticks (milliseconds) before timer expires
  25  * @flags: Driver specific flags. This might be used to specify
  26  * which action needs to be executed when the timer expires
  27  * @return: 0 if OK, -ve on error
  28  */
  29 int wdt_start(struct udevice *dev, u64 timeout_ms, ulong flags);
  30
  31 /*
  32  * Stop the timer, thus disabling the Watchdog. Use wdt_start to start it again.
  33  *
  34  * @dev: WDT Device
  35  * @return: 0 if OK, -ve on error
  36  */
  37 int wdt_stop(struct udevice *dev);
  38
  39 /*
  40  * Reset the timer, typically restoring the counter to
  41  * the value configured by start()
  42  *
  43  * @dev: WDT Device
  44  * @return: 0 if OK, -ve on error
  45  */
  46 int wdt_reset(struct udevice *dev);
  47
  48 /*
  49  * Expire the timer, thus executing its action immediately.
  50  * This is typically used to reset the board or peripherals.
  51  *
  52  * @dev: WDT Device
  53  * @flags: Driver specific flags
  54  * @return 0 if OK -ve on error. If wdt action is system reset,
  55  * this function may never return.
  56  */
  57 int wdt_expire_now(struct udevice *dev, ulong flags);
  58
  59 /*
  60  * struct wdt_ops - Driver model wdt operations
  61  *
  62  * The uclass interface is implemented by all wdt devices which use
  63  * driver model.
  64  */
  65 struct wdt_ops {
  66         /*
  67          * Start the timer
  68          *
  69          * @dev: WDT Device
  70          * @timeout_ms: Number of ticks (milliseconds) before the timer expires
  71          * @flags: Driver specific flags. This might be used to specify
  72          * which action needs to be executed when the timer expires
  73          * @return: 0 if OK, -ve on error
  74          */
  75         int (*start)(struct udevice *dev, u64 timeout_ms, ulong flags);
  76         /*
  77          * Stop the timer
  78          *
  79          * @dev: WDT Device
  80          * @return: 0 if OK, -ve on error
  81          */
  82         int (*stop)(struct udevice *dev);
  83         /*
  84          * Reset the timer, typically restoring the counter to
  85          * the value configured by start()
  86          *
  87          * @dev: WDT Device
  88          * @return: 0 if OK, -ve on error
  89          */
  90         int (*reset)(struct udevice *dev);
  91         /*
  92          * Expire the timer, thus executing the action immediately (optional)
  93          *
  94          * If this function is not provided, a default implementation
  95          * will be used, which sets the counter to 1
  96          * and waits forever. This is good enough for system level
  97          * reset, where the function is not expected to return, but might not be
  98          * good enough for other use cases.
  99          *
 100          * @dev: WDT Device
 101          * @flags: Driver specific flags
 102          * @return 0 if OK -ve on error. May not return.
 103          */
 104         int (*expire_now)(struct udevice *dev, ulong flags);
 105 };
 106
 107 #endif  /* _WDT_H_ */