1 /** 2 * @file rtc.h 3 * @brief Real Time Clock (RTC) functions and prototypes. 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_MAX32665_RTC_H_ 28 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32665_RTC_H_ 29 30 /* **** Includes **** */ 31 #include <stdint.h> 32 #include "mxc_device.h" 33 #include "mxc_sys.h" 34 #include "rtc_regs.h" 35 #include "tmr.h" 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /** 42 * @defgroup rtc Real Time Clock (RTC) 43 * @ingroup periphlibs 44 * @{ 45 */ 46 47 #define MXC_RTC_MAX_SSEC (MXC_F_RTC_SSEC_SSEC + 1) 48 #define MXC_RTC_TRIM_TMR_IRQ MXC_F_TMR_INTR_IRQ 49 50 /* **** Definitions **** */ 51 /** 52 * @brief Bitmasks for each of the RTC's Frequency. 53 */ 54 typedef enum { 55 MXC_RTC_F_1HZ = MXC_S_RTC_CTRL_FT_FREQ1HZ, ///< 1Hz (Compensated) 56 MXC_RTC_F_512HZ = MXC_S_RTC_CTRL_FT_FREQ512HZ, ///< 512Hz (Compensated) 57 MXC_RTC_F_4KHZ = MXC_S_RTC_CTRL_FT_FREQ4KHZ, ///< 4Khz 58 MXC_RTC_F_32KHZ = 32, ///< 32Khz 59 } mxc_rtc_freq_sel_t; 60 61 /** 62 * @brief Bitmasks for each of the RTC's interrupt enables. 63 */ 64 typedef enum { 65 MXC_RTC_INT_EN_LONG = MXC_F_RTC_CTRL_ADE, ///< Long-interval alarm interrupt enable 66 MXC_RTC_INT_EN_SHORT = MXC_F_RTC_CTRL_ASE, ///< Short-interval alarm interrupt enable 67 MXC_RTC_INT_EN_READY = MXC_F_RTC_CTRL_RDYE, ///< Timer ready interrupt enable 68 } mxc_rtc_int_en_t; 69 70 /** 71 * @brief Bitmasks for each of the RTC's interrupt flags. 72 */ 73 typedef enum { 74 MXC_RTC_INT_FL_LONG = MXC_F_RTC_CTRL_ALDF, ///< Long-interval alarm interrupt flag 75 MXC_RTC_INT_FL_SHORT = MXC_F_RTC_CTRL_ALSF, ///< Short-interval alarm interrupt flag 76 MXC_RTC_INT_FL_READY = MXC_F_RTC_CTRL_RDY, ///< Timer ready interrupt flag 77 } mxc_rtc_int_fl_t; 78 79 /** 80 * @brief Set Time-of-Day alarm value and enable Interrupt 81 * @param ras 20-bit value 0-0xFFFFF 82 * @retval returns Success or Fail, see \ref MXC_Error_Codes 83 */ 84 int MXC_RTC_SetTimeofdayAlarm(uint32_t ras); 85 86 /** 87 * @brief Set Sub-Second alarm value and enable interrupt, 88 * @brief this is to be called after the init_rtc() function 89 * @param rssa 32-bit value 0-0xFFFFFFFF 90 * @retval returns Success or Fail, see \ref MXC_Error_Codes 91 */ 92 int MXC_RTC_SetSubsecondAlarm(uint32_t rssa); 93 94 /** 95 * @brief Start the Real Time Clock 96 * @retval returns Success or Fail, see \ref MXC_Error_Codes 97 */ 98 int MXC_RTC_Start(void); 99 /** 100 * @brief Stop the Real Time Clock (Blocking function) 101 * @retval returns Success or Fail, see \ref MXC_Error_Codes 102 */ 103 int MXC_RTC_Stop(void); 104 105 /** 106 * @brief Initialize the sec and ssec registers and enable RTC (Blocking function) 107 * @param sec set the RTC Sec counter (32-bit) 108 * @param ssec set the RTC Sub-second counter (12-bit) 109 * @retval returns Success or Fail, see \ref MXC_Error_Codes 110 */ 111 int MXC_RTC_Init(uint32_t sec, uint16_t ssec); 112 113 /** 114 * @brief Allow generation of Square Wave on the SQW pin (Blocking function) 115 * @param fq Frequency output selection 116 * @retval returns Success or Fail, see \ref MXC_Error_Codes 117 */ 118 int MXC_RTC_SquareWaveStart(mxc_rtc_freq_sel_t fq); 119 120 /** 121 * @brief Stop the generation of square wave (Blocking function) 122 * @retval returns Success or Fail, see \ref MXC_Error_Codes 123 */ 124 int MXC_RTC_SquareWaveStop(void); 125 126 /** 127 * @brief Set Trim register value (Blocking function) 128 * @param trm set the RTC Trim (8-bit, +/- 127) 129 * @retval returns Success or Fail, see \ref MXC_Error_Codes 130 */ 131 int MXC_RTC_Trim(int8_t trm); 132 133 /** 134 * @brief Enable Interurpts (Blocking function) 135 * @param mask The bitwise OR of interrupts to enable. 136 * See #mxc_rtc_int_en_t for available choices. 137 * @retval returns Success or Fail, see \ref MXC_Error_Codes 138 */ 139 int MXC_RTC_EnableInt(uint32_t mask); 140 141 /** 142 * @brief Disable Interurpts (Blocking function) 143 * @param mask The mask of interrupts to disable. 144 * See #mxc_rtc_int_en_t for available choices. 145 * @retval returns Success or Fail, see \ref MXC_Error_Codes 146 */ 147 int MXC_RTC_DisableInt(uint32_t mask); 148 149 /** 150 * @brief Gets interrupt flags. 151 * @retval The bitwise OR of any interrupts flags that are 152 * currently set. See \ref mxc_rtc_int_fl_t for the list 153 * of possible flags. 154 */ 155 int MXC_RTC_GetFlags(void); 156 157 /** 158 * @brief Clear interrupt flags. 159 * @param flags The bitwise OR of the interrupts flags to cleear. 160 * See #mxc_rtc_int_fl_t for the list of possible flags. 161 * @retval returns Success or Fail, see \ref MXC_Error_Codes 162 */ 163 int MXC_RTC_ClearFlags(int flags); 164 165 /** 166 * @brief Get SubSecond or E_BUSY, see /ref MXC_ERROR_CODES 167 * @retval Returns subsecond value 168 */ 169 #ifdef __GNUC__ 170 __attribute__((deprecated("Use MXC_RTC_GetSubSeconds() instead."))) 171 #endif 172 int MXC_RTC_GetSubSecond(void); 173 174 /** 175 * @brief This function stores the current value of the sub-seconds counter into a 176 * pointer if the RTC is not busy. If the RTC is busy, an error is returned. 177 * @param ssec Pointer to the variable to store the current sub-seconds value. 178 * @retval E_NO_ERROR if successful, otherwise an error code (see /ref MXC_ERROR_CODES). 179 */ 180 int MXC_RTC_GetSubSeconds(uint32_t *ssec); 181 182 /** 183 * @brief Get Second or E_BUSY, see /ref MXC_ERROR_CODES 184 * @retval returns second value 185 */ 186 #ifdef __GNUC__ 187 __attribute__((deprecated("Use MXC_RTC_GetSeconds() instead."))) 188 #endif 189 int MXC_RTC_GetSecond(void); 190 191 /** 192 * @brief This function stores the current value of the seconds counter into a 193 * pointer if the RTC is not busy. If the RTC is busy, an error is returned. 194 * @param sec Pointer to the variable to store the current seconds value. 195 * @retval E_NO_ERROR if successful, otherwise an error code (see /ref MXC_ERROR_CODES). 196 */ 197 int MXC_RTC_GetSeconds(uint32_t *sec); 198 199 /** 200 * @brief Get the current second and sub-second counts 201 * @param sec pointer to store seconds value 202 * @param subsec pointer to store subseconds value 203 * @retval returns Success or Fail, see \ref MXC_Error_Codes 204 */ 205 int MXC_RTC_GetTime(uint32_t *sec, uint32_t *subsec); 206 207 /** 208 * @brief Get RTC busy flag. 209 * @retval returns Success or E_BUSY, see /ref MXC_ERROR_CODES 210 */ 211 int MXC_RTC_GetBusyFlag(void); 212 213 /** 214 * @brief Calculate and set the appropriate RTC trim value based on an accurate reference clock 215 * 216 * @param tmr Timer available to be used to measure known time periods over which the RTC ticks are counted 217 * 218 * @retval returns Success or Fail, see \ref MXC_Error_Codes 219 * 220 * @note If RTC running before calling this function and interrupts enabled, accuracy of trimming could be affected 221 * @note External 32MHz must be installed and calibrated properly for this function to be successful 222 */ 223 int MXC_RTC_TrimCrystal(mxc_tmr_regs_t *tmr); 224 225 /**@} end of group rtc */ 226 #ifdef __cplusplus 227 } 228 #endif 229 230 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32665_RTC_H_ 231
