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