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