1 /** 2 * @file wut.h 3 * @brief Wakeup Timer (WUT) function prototypes and data types. 4 */ 5 6 /****************************************************************************** 7 * 8 * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by 9 * Analog Devices, Inc.), 10 * Copyright (C) 2023-2024 Analog Devices, Inc. 11 * 12 * Licensed under the Apache License, Version 2.0 (the "License"); 13 * you may not use this file except in compliance with the License. 14 * You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, software 19 * distributed under the License is distributed on an "AS IS" BASIS, 20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 * See the License for the specific language governing permissions and 22 * limitations under the License. 23 * 24 ******************************************************************************/ 25 26 /* Define to prevent redundant inclusion */ 27 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32680_WUT_H_ 28 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32680_WUT_H_ 29 30 /* **** Includes **** */ 31 #include "mxc_device.h" 32 #include "wut_regs.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 * @defgroup wut Wakeup Timer (WUT) 40 * @ingroup periphlibs 41 * @{ 42 */ 43 44 /** 45 * @brief Wakeup Timer prescaler values 46 */ 47 typedef enum { 48 MXC_WUT_PRES_1 = MXC_S_WUT_CTRL_PRES_DIV1, /// Divide input clock by 1 49 MXC_WUT_PRES_2 = MXC_S_WUT_CTRL_PRES_DIV2, /// Divide input clock by 2 50 MXC_WUT_PRES_4 = MXC_S_WUT_CTRL_PRES_DIV4, /// Divide input clock by 4 51 MXC_WUT_PRES_8 = MXC_S_WUT_CTRL_PRES_DIV8, /// Divide input clock by 8 52 MXC_WUT_PRES_16 = MXC_S_WUT_CTRL_PRES_DIV16, /// Divide input clock by 16 53 MXC_WUT_PRES_32 = MXC_S_WUT_CTRL_PRES_DIV32, /// Divide input clock by 32 54 MXC_WUT_PRES_64 = MXC_S_WUT_CTRL_PRES_DIV64, /// Divide input clock by 64 55 MXC_WUT_PRES_128 = MXC_S_WUT_CTRL_PRES_DIV128, /// Divide input clock by 128 56 MXC_WUT_PRES_256 = MXC_F_WUT_CTRL_PRES3 | 57 MXC_S_WUT_CTRL_PRES_DIV1, /// Divide input clock by 256 58 MXC_WUT_PRES_512 = MXC_F_WUT_CTRL_PRES3 | 59 MXC_S_WUT_CTRL_PRES_DIV2, /// Divide input clock by 512 60 MXC_WUT_PRES_1024 = MXC_F_WUT_CTRL_PRES3 | 61 MXC_S_WUT_CTRL_PRES_DIV4, /// Divide input clock by 1024 62 MXC_WUT_PRES_2048 = MXC_F_WUT_CTRL_PRES3 | 63 MXC_S_WUT_CTRL_PRES_DIV8, /// Divide input clock by 2048 64 MXC_WUT_PRES_4096 = MXC_F_WUT_CTRL_PRES3 | 65 MXC_S_WUT_CTRL_PRES_DIV16 /// Divide input clock by 4096 66 } mxc_wut_pres_t; 67 68 /** 69 * @brief Wakeup Timer modes 70 */ 71 typedef enum { 72 MXC_WUT_MODE_ONESHOT = MXC_V_WUT_CTRL_TMODE_ONESHOT, /// Wakeup Timer Mode ONESHOT 73 MXC_WUT_MODE_CONTINUOUS = MXC_V_WUT_CTRL_TMODE_CONTINUOUS, /// Wakeup Timer Mode CONTINUOUS 74 MXC_WUT_MODE_COUNTER = MXC_V_WUT_CTRL_TMODE_COUNTER, /// Wakeup Timer Mode COUNTER 75 MXC_WUT_MODE_CAPTURE = MXC_V_WUT_CTRL_TMODE_CAPTURE, /// Wakeup Timer Mode CAPTURE 76 MXC_WUT_MODE_COMPARE = MXC_V_WUT_CTRL_TMODE_COMPARE, /// Wakeup Timer Mode COMPARE 77 MXC_WUT_MODE_GATED = MXC_V_WUT_CTRL_TMODE_GATED, /// Wakeup Timer Mode GATED 78 MXC_WUT_MODE_CAPTURE_COMPARE = 79 MXC_V_WUT_CTRL_TMODE_CAPTURECOMPARE /// Wakeup Timer Mode CAPTURECOMPARE 80 } mxc_wut_mode_t; 81 82 /** 83 * @brief Wakeup Timer units of time enumeration 84 */ 85 typedef enum { 86 MXC_WUT_UNIT_NANOSEC = 0, /**< Nanosecond Unit Indicator. */ 87 MXC_WUT_UNIT_MICROSEC, /**< Microsecond Unit Indicator. */ 88 MXC_WUT_UNIT_MILLISEC, /**< Millisecond Unit Indicator. */ 89 MXC_WUT_UNIT_SEC /**< Second Unit Indicator. */ 90 } mxc_wut_unit_t; 91 92 /** 93 * @brief Wakeup Timer Configuration 94 */ 95 typedef struct { 96 mxc_wut_mode_t mode; /// Desired timer mode 97 uint32_t cmp_cnt; /// Compare register value in timer ticks 98 } mxc_wut_cfg_t; 99 100 /** 101 * @brief The callback routine used by the MXC_WUT_TrimCrystalAsync() 102 * function to indicate the transaction has completed. 103 * 104 * @param result Error code. 105 */ 106 typedef void (*mxc_wut_complete_cb_t)(int result); 107 108 /* **** Definitions **** */ 109 110 /* **** Function Prototypes **** */ 111 112 /** 113 * @brief Initialize timer module clock. 114 * @param wut Pointer to Wakeup Timer instance to initialize. 115 * @param pres Prescaler value. 116 */ 117 void MXC_WUT_Init(mxc_wut_regs_t *wut, mxc_wut_pres_t pres); 118 119 /** 120 * @brief Shutdown timer module clock. 121 * @param wut Pointer to Wakeup Timer instance to shutdown. 122 */ 123 void MXC_WUT_Shutdown(mxc_wut_regs_t *wut); 124 125 /** 126 * @brief Enable the timer. 127 * @param wut Pointer to Wakeup Timer instance to enable. 128 */ 129 void MXC_WUT_Enable(mxc_wut_regs_t *wut); 130 131 /** 132 * @brief Disable the timer. 133 * @param wut Pointer to Wakeup Timer instance to disable. 134 */ 135 void MXC_WUT_Disable(mxc_wut_regs_t *wut); 136 137 /** 138 * @brief Configure the timer. 139 * @param wut Pointer to Wakeup Timer instance to configure. 140 * @param cfg Pointer to timer configuration struct. 141 */ 142 void MXC_WUT_Config(mxc_wut_regs_t *wut, const mxc_wut_cfg_t *cfg); 143 144 /** 145 * @brief Get the timer compare count. 146 * @param wut Pointer to Wakeup Timer instance to get compare value from. 147 * @return Returns the current compare count. 148 */ 149 uint32_t MXC_WUT_GetCompare(mxc_wut_regs_t *wut); 150 151 /** 152 * @brief Get the timer count. 153 * @param wut Pointer to Wakeup Timer instance to get count value from. 154 * @return Returns the current count. 155 */ 156 uint32_t MXC_WUT_GetCount(mxc_wut_regs_t *wut); 157 158 /** 159 * @brief Clear the timer interrupt. 160 * @param wut Pointer to Wakeup Timer instance to clear interrupts for. 161 */ 162 void MXC_WUT_IntClear(mxc_wut_regs_t *wut); 163 164 /** 165 * @brief Get the timer interrupt status. 166 * @param wut Pointer to Wakeup Timer instance to get interrupt status from. 167 * @return Returns the interrupt status. 1 if interrupt has occurred. 168 */ 169 uint32_t MXC_WUT_IntStatus(mxc_wut_regs_t *wut); 170 171 /** 172 * @brief Set the timer compare count. 173 * @param wut Pointer to Wakeup Timer instance to set compare value for. 174 * @param cmp_cnt New compare count. 175 * @note This function does not protect against output glitches in PWM mode. 176 * Use MXC_WUT_PWMSetPeriod when in PWM mode. 177 */ 178 void MXC_WUT_SetCompare(mxc_wut_regs_t *wut, uint32_t cmp_cnt); 179 180 /** 181 * @brief Set the timer count. 182 * @param wut Pointer to Wakeup Timer instance to set count valeu for. 183 * @param cnt New count. 184 */ 185 void MXC_WUT_SetCount(mxc_wut_regs_t *wut, uint32_t cnt); 186 187 /** 188 * @brief Convert real time to timer ticks. 189 * @param wut Pointer to Wakeup Timer instance to get tick count from. 190 * @param time Number of units of time. 191 * @param units Which units of time you want to convert. 192 * @param ticks Pointer to store the number of ticks calculated. 193 * @return #E_NO_ERROR If everything is successful. 194 * @return @ref MXC_Error_Codes If function is unsuccessful. 195 */ 196 int MXC_WUT_GetTicks(mxc_wut_regs_t *wut, uint32_t time, mxc_wut_unit_t units, uint32_t *ticks); 197 198 /** 199 * @brief Convert timer ticks to real time. 200 * @param wut Pointer to Wakeup Timer instance to get time from. 201 * @param ticks Number of ticks. 202 * @param time Pointer to store number of units of time. 203 * @param units Pointer to store the units that time represents. 204 * @return #E_NO_ERROR If everything is successful. 205 * @return @ref MXC_Error_Codes If function is unsuccessful. 206 */ 207 int MXC_WUT_GetTime(mxc_wut_regs_t *wut, uint32_t ticks, uint32_t *time, mxc_wut_unit_t *units); 208 209 /** 210 * @brief Wait for an edge of the WUT count register. 211 * @param wut Pointer to Wakeup Timer instance to wait on. 212 */ 213 void MXC_WUT_Edge(mxc_wut_regs_t *wut); 214 215 /** 216 * @brief Store the count and snapshot values. 217 * @param wut Pointer to Wakeup Timer instance to store count and snapshot values for. 218 */ 219 void MXC_WUT_Store(mxc_wut_regs_t *wut); 220 221 /** 222 * @brief Restore the DBB clock with the stored count and snapshot values. 223 * @param wut Pointer to Wakeup Timer instance to restore count and snapshot values for. 224 * @param dbbFreq Frequency of DBB clock. 225 */ 226 void MXC_WUT_RestoreBBClock(mxc_wut_regs_t *wut, uint32_t dbbFreq); 227 228 /** 229 * @brief Get the difference between the stored counter value 230 * and the current counter value. 231 * @param wut Pointer to Wakeup Timer instance to get current sleep ticks from. 232 * @return Returns the current counter value - stored counter value. 233 */ 234 uint32_t MXC_WUT_GetSleepTicks(mxc_wut_regs_t *wut); 235 236 /** 237 * @brief Delays for the given number of milliseconds. 238 * @param wut Pointer to Wakeup Timer instance to use as the delay timer. 239 * @param waitMs Number of milliseconds to wait. 240 */ 241 void MXC_WUT_Delay_MS(mxc_wut_regs_t *wut, uint32_t waitMs); 242 243 /** 244 * @brief Trim the 32 kHz crystal load settings, blocks until complete. 245 * @details This procedure uses the WUT and the BLE DBB, driven by the 32 MHz crystal, 246 * to trim the load settings of the 32 kHz crystal. This procedure will only 247 * work if the BLE DBB is initialized and running. 248 * 249 * @param wut Pointer to Wakeup Timer instance to trim. 250 * 251 * @return #E_NO_ERROR If everything is successful. 252 */ 253 int MXC_WUT_TrimCrystal(mxc_wut_regs_t *wut); 254 255 /** 256 * @brief Trim the 32 kHz crystal load settings, non-blocking interrupt based. 257 * @details This procedure uses the WUT and the BLE DBB, driven by the 32 MHz crystal, 258 * to trim the load settings of the 32 kHz crystal. This procedure will only 259 * work if the BLE DBB is initialized and running. 260 * 261 * @param wut Pointer to Wakeup Timer instance to trim. 262 * @param cb Callback for when the trim is complete. 263 * @return #E_NO_ERROR If everything is successful. 264 */ 265 int MXC_WUT_TrimCrystalAsync(mxc_wut_regs_t *wut, mxc_wut_complete_cb_t cb); 266 267 /** 268 * @brief Check to see if the trim procedure is ongoing. 269 * @details Must leave the 32 MHz clock and BLE DBB running while the trim procedure is pending. 270 * @param wut Pointer to Wakeup Timer instance to check trim status for. 271 * @return #E_NO_ERROR If trim is complete, E_BUSY if trim procedure is ongoing. 272 */ 273 int MXC_WUT_TrimPending(mxc_wut_regs_t *wut); 274 275 /** 276 * @brief Interrupt handler for trim procedure. 277 * @param wut Pointer to Wakeup Timer instance to handle interrupts for. 278 * @return #E_NO_ERROR If trim is complete, E_BUSY if trim procedure is ongoing. 279 */ 280 int MXC_WUT_Handler(mxc_wut_regs_t *wut); 281 282 /**@} end of group wut */ 283 284 #ifdef __cplusplus 285 } 286 #endif 287 288 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32680_WUT_H_ 289
