1 /***************************************************************************//** 2 * \file cyhal_wdt.h 3 * 4 * \brief 5 * Provides a high level interface for interacting with the Watchdog Timer. 6 * This interface abstracts out the chip specific details. If any chip specific 7 * functionality is necessary, or performance is critical the low level functions 8 * can be used directly. 9 * 10 ******************************************************************************** 11 * \copyright 12 * Copyright 2019-2021 Cypress Semiconductor Corporation (an Infineon company) or 13 * an affiliate of Cypress Semiconductor Corporation 14 * 15 * SPDX-License-Identifier: Apache-2.0 16 * 17 * Licensed under the Apache License, Version 2.0 (the "License"); 18 * you may not use this file except in compliance with the License. 19 * You may obtain a copy of the License at 20 * 21 * http://www.apache.org/licenses/LICENSE-2.0 22 * 23 * Unless required by applicable law or agreed to in writing, software 24 * distributed under the License is distributed on an "AS IS" BASIS, 25 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 26 * See the License for the specific language governing permissions and 27 * limitations under the License. 28 *******************************************************************************/ 29 30 /** 31 * \addtogroup group_hal_wdt WDT (Watchdog Timer) 32 * \ingroup group_hal 33 * \{ 34 * High level interface to the Watchdog Timer (WDT). 35 * 36 * The WDT can be used for recovering from a CPU or firmware failure. 37 * The WDT is initialized with a timeout interval. Once the WDT is started, \ref 38 * cyhal_wdt_kick must be called at least once within each timeout interval to 39 * reset the count. In case the firmware fails to do so, it is considered to be a 40 * CPU crash or firmware failure and the device will be reset. 41 * 42 *\section subsection_wdt_features Features 43 * WDT resets the device if the WDT is not "kicked" using \ref cyhal_wdt_kick 44 * within the configured timeout interval. 45 * 46 * \section subsection_wdt_quickstart Quick Start 47 * 48 * \ref cyhal_wdt_init() is used to initialize the WDT by providing the WDT object 49 * (**obj**) and the timeout (**timeout_ms**) value in milliseconds. 50 * The timeout parameter can have a minimum value of 1ms. The maximum value of the 51 * timeout parameter can be obtained using the cyhal_wdt_get_max_timeout_ms(). 52 * 53 * \section subsection_wdt_snippet Code Snippet 54 * 55 * \subsection subsection_wdt_snippet1 Snippet 1: Initialize the WDT and kick periodically 56 * The following snippet initializes the WDT and illustrates how to reset the WDT within 57 * the timeout interval. 58 * \snippet hal_wdt.c snippet_cyhal_wdt_init_and_reset 59 */ 60 61 #pragma once 62 63 #include "cyhal_hwmgr.h" 64 #include "cy_result.h" 65 66 #if defined(__cplusplus) 67 extern "C" { 68 #endif 69 70 /** \addtogroup group_hal_results_wdt WDT HAL Results 71 * WDT specific return codes 72 * \ingroup group_hal_results 73 * \{ *//** 74 */ 75 76 /** WDT timeout out of range */ 77 #define CY_RSLT_WDT_INVALID_TIMEOUT \ 78 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_WDT, 0)) 79 /** WDT already initialized */ 80 #define CY_RSLT_WDT_ALREADY_INITIALIZED \ 81 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_WDT, 1)) 82 83 /** 84 * \} 85 */ 86 87 /** Initialize and start the WDT 88 * 89 * \note The specified timeout must be at least 1ms and at most the WDT's maximum timeout (see cyhal_wdt_get_max_timeout_ms()). 90 * 91 * @param[out] obj Pointer to a WDT object. The caller must allocate the memory 92 * for this object but the init function will initialize its contents. 93 * @param[inout] timeout_ms The time in milliseconds before the WDT times out (1ms - max) (see cyhal_wdt_get_max_timeout_ms()) 94 * @return The status of the init request 95 * 96 * Returns \ref CY_RSLT_SUCCESS if the operation was successfull. 97 */ 98 cy_rslt_t cyhal_wdt_init(cyhal_wdt_t *obj, uint32_t timeout_ms); 99 100 /** Free the WDT 101 * 102 * Powers down the WDT. Releases object (obj). 103 * After calling this function no other WDT functions should be called except 104 * cyhal_wdt_init(). 105 * 106 * @param[inout] obj The WDT object 107 */ 108 void cyhal_wdt_free(cyhal_wdt_t *obj); 109 110 /** Resets the WDT 111 * 112 * This function must be called periodically to prevent the WDT from timing out and resetting the device. 113 * 114 * See \ref subsection_wdt_snippet1 115 * 116 * @param[inout] obj The WDT object 117 */ 118 void cyhal_wdt_kick(cyhal_wdt_t *obj); 119 120 /** Start (enable) the WDT 121 * 122 * @param[inout] obj The WDT object 123 */ 124 void cyhal_wdt_start(cyhal_wdt_t *obj); 125 126 /** Stop (disable) the WDT 127 * 128 * @param[inout] obj The WDT object 129 */ 130 void cyhal_wdt_stop(cyhal_wdt_t *obj); 131 132 /** Get the WDT timeout 133 * 134 * Gets the configured time, in milliseconds, before the WDT times out. 135 * 136 * @param[in] obj The WDT object 137 * @return The time in milliseconds before the WDT times out 138 */ 139 uint32_t cyhal_wdt_get_timeout_ms(cyhal_wdt_t *obj); 140 141 /** Gets the maximum WDT timeout in milliseconds 142 * 143 * @return The maximum timeout for the WDT 144 */ 145 uint32_t cyhal_wdt_get_max_timeout_ms(void); 146 147 /** Check if WDT is enabled 148 * 149 * This will return true after \ref cyhal_wdt_start is called. It will return false before the WDT is started, or after \ref cyhal_wdt_stop is called. 150 * 151 * @param[in] obj The WDT object 152 * @return The status of WDT is_enabled request */ 153 bool cyhal_wdt_is_enabled(cyhal_wdt_t *obj); 154 155 #if defined(__cplusplus) 156 } 157 #endif 158 159 #ifdef CYHAL_WDT_IMPL_HEADER 160 #include CYHAL_WDT_IMPL_HEADER 161 #endif /* CYHAL_WDT_IMPL_HEADER */ 162 163 /** \} group_hal_wdt */ 164
