1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup WATCHDOG 11 * @{ 12 * 13 * @brief Provides watchdog APIs, such as setting the watchdog timeout duration and feeding a watchdog (resetting 14 * a watchdog timer). 15 * 16 * If an error occurs in the main program of the system, for example, if the program crashes or the watchdog timer 17 * is not reset in time, the watchdog timer generates a reset signal, and the system restores from the suspending 18 * state to the normal state. 19 * 20 * @since 1.0 21 */ 22 23 /** 24 * @file watchdog_if.h 25 * 26 * @brief Declares standard watchdog APIs. 27 * 28 * @since 1.0 29 */ 30 31 #ifndef WATCHDOG_IF_H 32 #define WATCHDOG_IF_H 33 34 #include "platform_if.h" 35 36 #ifdef __cplusplus 37 #if __cplusplus 38 extern "C" { 39 #endif 40 #endif /* __cplusplus */ 41 42 /** 43 * @brief Enumerates watchdog statuses. 44 * 45 * To obtain the watchdog status, call the {@link WatchdogGetStatus} function. 46 * 47 * @since 1.0 48 */ 49 enum WatchdogStatus { 50 WATCHDOG_STOP, /**< Stopped */ 51 WATCHDOG_START, /**< Started */ 52 }; 53 54 /** 55 * @brief Enumerates WATCHDOG I/O commands. 56 * 57 * @since 1.0 58 */ 59 enum WatchdogIoCmd { 60 WATCHDOG_IO_GET_PRIV = 0, /**< Get the WATCHDOG device priv. */ 61 WATCHDOG_IO_RELEASE_PRIV, /**< Release the WATCHDOG device priv. */ 62 WATCHDOG_IO_GET_STATUS, /**< Get status. */ 63 WATCHDOG_IO_START, /**< Start. */ 64 WATCHDOG_IO_STOP, /**< Stop */ 65 WATCHDOG_IO_SET_TIMEOUT, /**< Set timrout. */ 66 WATCHDOG_IO_GET_TIMEOUT, /**< Get timeout. */ 67 WATCHDOG_IO_FEED, /**< Feed. */ 68 }; 69 70 /** 71 * @brief Opens a watchdog. 72 * 73 * Before operating a watchdog, you must call this function to open it and obtain its device handle. 74 * 75 * @param wdtId Indicates the watchdog ID. 76 * 77 * @return Returns the pointer to the device handle of the watch dog if the operation is successful; 78 * returns <b>NULL</b> otherwise. 79 * 80 * @since 1.0 81 */ 82 int32_t WatchdogOpen(int16_t wdtId, DevHandle *handle); 83 84 /** 85 * @brief Closes a watchdog. 86 * 87 * If you no longer need a watchdog, call this function to close it and release its device handle to prevent 88 * unnecessary use of memory resources. 89 * 90 * @param handle Indicates the pointer to the watchdog device handle. 91 * 92 * @since 1.0 93 */ 94 void WatchdogClose(DevHandle handle); 95 96 /** 97 * @brief Obtains the watchdog status. 98 * 99 * For the available watchdog statuses, see {@link WatchdogStatus}. 100 * 101 * @param handle Indicates the pointer to the watchdog handle, which is obtained via {@link WatchdogOpen}. 102 * @param status Indicates the pointer to the watchdog status. 103 * 104 * @return Returns <b>0</b> if the watchdog status is obtained; returns a negative value otherwise. 105 * 106 * @since 1.0 107 */ 108 int32_t WatchdogGetStatus(DevHandle handle, int32_t *status); 109 110 /** 111 * @brief Starts a watchdog. 112 * 113 * This function starts the watchdog timer. You must feed the watchdog periodically; otherwise, the watchdog hardware 114 * will reset the system upon a timeout. 115 * 116 * @param handle Indicates the pointer to the watchdog handle, which is obtained via {@link WatchdogOpen}. 117 * 118 * @return Returns <b>0</b> if the watchdog is successfully started; returns a negative value otherwise. 119 * @attention If the watchdog timer has started before this function is called, calling this function will succeed; 120 * however, the watchdog hardware determines whether to reset the timer. 121 * 122 * @since 1.0 123 */ 124 int32_t WatchdogStart(DevHandle handle); 125 126 /** 127 * @brief Stops a watchdog. 128 * 129 * If the watchdog has stopped before this function is called, calling this function will succeed. 130 * 131 * @param handle Indicates the pointer to the watchdog handle, which is obtained via {@link WatchdogOpen}. 132 * 133 * @return Returns <b>0</b> if the watchdog is successfully stopped; returns a negative value otherwise. 134 * @since 1.0 135 */ 136 int32_t WatchdogStop(DevHandle handle); 137 138 /** 139 * @brief Sets the watchdog timeout duration. 140 * 141 * @param handle Indicates the pointer to the watchdog handle, which is obtained via {@link WatchdogOpen}. 142 * @param seconds Indicates the timeout duration, in seconds. 143 * 144 * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise. 145 * @since 1.0 146 */ 147 int32_t WatchdogSetTimeout(DevHandle handle, uint32_t seconds); 148 149 /** 150 * @brief Obtains the watchdog timeout duration. 151 * 152 * @param handle Indicates the pointer to the watchdog handle, which is obtained via {@link WatchdogOpen}. 153 * @param seconds Indicates the pointer to the timeout duration, in seconds. 154 * 155 * @return Returns <b>0</b> if the watchdog timeout duration is obtained; returns a negative value otherwise. 156 * @since 1.0 157 */ 158 int32_t WatchdogGetTimeout(DevHandle handle, uint32_t *seconds); 159 160 /** 161 * @brief Feeds a watchdog, that is, resets a watchdog timer. 162 * 163 * After a watchdog is started, you must feed it to reset the watchdog timer periodically. 164 * If you do not do so, the watchdog hardware will reset the system upon a timeout. 165 * 166 * @param handle Indicates the pointer to the watchdog handle, which is obtained via {@link WatchdogOpen}. 167 * 168 * @return Returns <b>0</b> if the watchdog is fed; returns a negative value otherwise. 169 * @since 1.0 170 */ 171 int32_t WatchdogFeed(DevHandle handle); 172 173 /** 174 * @brief The following watchdog interfaces are only available for the mini platform 175 * 176 * @since 1.0 177 */ 178 179 int32_t WatchdogBark(DevHandle handle); 180 181 int32_t WatchdogEnable(DevHandle handle, bool enable); 182 183 int32_t WatchdogGetEnable(DevHandle handle, bool *enable); 184 185 #ifdef __cplusplus 186 #if __cplusplus 187 } 188 #endif 189 #endif /* __cplusplus */ 190 191 #endif /* WATCHDOG_IF_H */ 192 /** @} */ 193