include/wdt.h

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