1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup RTC 11 * @{ 12 * 13 * @brief Provides standard real-time clock (RTC) APIs. 14 * 15 * These APIs allow you to perform operations such as reading or writing system time, reading or writing alarm time, 16 * setting alarm interrupts, registering alarm callbacks, setting the external frequency, resetting the RTC driver, 17 * and customizing RTC configurations. \n 18 * The RTC driver provides precise real time for the operating system (OS). If the OS is powered off, the RTC driver 19 * continues to keep track of the system time using an external battery. 20 * 21 * @since 1.0 22 */ 23 24 /** 25 * @file rtc_if.h 26 * 27 * @brief Declares the standard RTC APIs. 28 * 29 * @since 1.0 30 */ 31 32 #ifndef RTC_IF_H 33 #define RTC_IF_H 34 35 #include "platform_if.h" 36 37 #ifdef __cplusplus 38 #if __cplusplus 39 extern "C" { 40 #endif 41 #endif /* __cplusplus */ 42 43 /** 44 * @brief Enumerates alarm indexes. 45 * 46 * The alarm indexes will be used when you perform operations related to alarms. 47 * 48 * @since V1.0 49 */ 50 enum RtcAlarmIndex { 51 RTC_ALARM_INDEX_A = 0, /**< Index of alarm A */ 52 RTC_ALARM_INDEX_B = 1, /**< Index of alarm B */ 53 }; 54 55 /** 56 * @brief Defines a callback that will be invoked when an alarm is generated at the specified time. 57 * 58 */ 59 typedef int32_t (*RtcAlarmCallback)(enum RtcAlarmIndex); 60 61 /** 62 * @brief Defines the RTC information. 63 * 64 * The RTC information includes the year, month, day, day of the week, hour, minute, second, and millisecond. 65 * The start time is 1970/01/01 Thursday 00:00:00 (UTC). 66 */ 67 struct RtcTime { 68 uint8_t second; /**< Second. The value ranges from 0 to 59. */ 69 uint8_t minute; /**< Minute. The value ranges from 0 to 59. */ 70 uint8_t hour; /**< Hour. The value ranges from 0 to 23. */ 71 uint8_t day; /**< Day. The value ranges from 1 to 31. */ 72 uint8_t weekday; /**< Day of the week. The value ranges from 1 to 7, representing Monday to Sunday. */ 73 uint8_t month; /**< Month. The value ranges from 1 to 12. */ 74 uint16_t year; /**< Year. The value is greater than or equal to 1970. */ 75 uint16_t millisecond; /**< Millisecond. The value ranges from 0 to 990, with a precision of 10 milliseconds. */ 76 }; 77 78 /** 79 * @brief Enumerates RTC I/O commands. 80 * 81 * @since 1.0 82 */ 83 enum RtcIoCmd { 84 RTC_IO_READTIME = 0, /**< Read time. */ 85 RTC_IO_WRITETIME, /**< Write format-compliant time. */ 86 RTC_IO_READALARM, /**< Read the RTC alarm time. */ 87 RTC_IO_WRITEALARM, /**< Write the RTC alarm time. */ 88 RTC_IO_REGISTERALARMCALLBACK, /**< Registers that will be invoked when an alarm 89 is generated at the specified time. */ 90 RTC_IO_ALARMINTERRUPTENABLE, /**< Enables or disables alarm interrupts. */ 91 RTC_IO_GETFREQ, /**< Get the RTC external frequency. */ 92 RTC_IO_SETFREQ, /**< Set the oscillation frequency of RTC external crystal. */ 93 RTC_IO_RESET, /**< Reset the RTC device. */ 94 RTC_IO_READREG, /**< Reads the configuration of a custom RTC register. */ 95 RTC_IO_WRITEREG, /**< Writes the configuration of a custom RTC register. */ 96 }; 97 98 /** 99 * @brief Opens the RTC device to obtain its handle. 100 * 101 * The OS supports only one RTC device. 102 * 103 * @return Returns {@link DevHandle} if the operation is successful; returns <b>NULL</b> if the operation fails. 104 * @since 1.0 105 */ 106 DevHandle RtcOpen(void); 107 108 /** 109 * @brief Releases a specified handle of the RTC device. 110 * 111 * @param handle Indicates the pointer to the RTC device handle to release, which is created via {@link RtcGetHandle}. 112 * 113 * @since 1.0 114 */ 115 void RtcClose(DevHandle handle); 116 117 /** 118 * @brief Reads time from the RTC driver. 119 * 120 * The time information includes the year, month, day, day of the week, hour, minute, second, and millisecond. 121 * 122 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 123 * @param time Indicates the pointer to the time information read from the RTC driver. 124 * For details, see {@link RtcTime}. 125 * 126 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 127 * For details, see {@link HDF_STATUS}. 128 * @since 1.0 129 */ 130 int32_t RtcReadTime(DevHandle handle, struct RtcTime *time); 131 132 /** 133 * @brief Writes format-compliant time to the RTC driver. 134 * 135 * Note that the RTC start time is 1970/01/01 Thursday 00:00:00 (UTC). Set the maximum value of <b>year</b> based on 136 * the requirements specified in the product manual of the in-use component. 137 * 138 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 139 * @param time Indicates the pointer to the time information to write. For details, see {@link RtcTime}. 140 * 141 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 142 * For details, see {@link HDF_STATUS}. 143 * @since 1.0 144 */ 145 int32_t RtcWriteTime(DevHandle handle, const struct RtcTime *time); 146 147 /** 148 * @brief Reads the RTC alarm time that was set last time. 149 * 150 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 151 * @param alarmIndex Indicates the RTC alarm index. For details, see {@link RtcAlarmIndex}. 152 * @param time Indicates the pointer to the RTC alarm time information. For details, see {@link RtcTime}. 153 * 154 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 155 * For details, see {@link HDF_STATUS}. 156 * @since 1.0 157 */ 158 int32_t RtcReadAlarm(DevHandle handle, enum RtcAlarmIndex alarmIndex, struct RtcTime *time); 159 160 /** 161 * @brief Writes the RTC alarm time based on the alarm index. 162 * 163 * Note that the RTC start time is 1970/01/01 Thursday 00:00:00 (UTC). Set the maximum value of <b>year</b> based on 164 * the requirements specified in the product manual of the in-use component. 165 * 166 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 167 * @param alarmIndex Indicates the RTC alarm index. For details, see {@link RtcAlarmIndex}. 168 * @param tm Indicates the pointer to the RTC alarm time information. For details, see {@link RtcTime}. 169 * 170 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 171 * For details, see {@link HDF_STATUS}. 172 * @since 1.0 173 */ 174 int32_t RtcWriteAlarm(DevHandle handle, enum RtcAlarmIndex alarmIndex, const struct RtcTime *time); 175 176 /** 177 * @brief Registers {@link RtcAlarmCallback} that will be invoked when an alarm is generated at the specified time. 178 * 179 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 180 * @param alarmIndex Indicates the RTC alarm index. For details, see {@link RtcAlarmIndex}. 181 * @param cb Indicates the callback to register. For details, see {@link RtcAlarmCallback}. 182 * 183 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 184 * For details, see {@link HDF_STATUS}. 185 * @since 1.0 186 */ 187 int32_t RtcRegisterAlarmCallback(DevHandle handle, enum RtcAlarmIndex alarmIndex, RtcAlarmCallback cb); 188 189 /** 190 * @brief Enables or disables alarm interrupts. 191 * 192 * Before performing alarm operations, you need to call this function to enable alarm interrupts, 193 * so that the {@link RtcRegisterAlarmCallback} will be called when the alarm is not generated upon a timeout. 194 * 195 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 196 * @param alarmIndex Indicates the RTC alarm index. For details, see {@link RtcAlarmIndex}. 197 * @param enable Specifies whether to enable RTC alarm interrupts. The value <b>1</b> means to 198 * enable alarm interrupts and value <b>0</b> means to disable alarm interrupts. 199 * 200 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 201 * For details, see {@link HDF_STATUS}. 202 * @since 1.0 203 */ 204 int32_t RtcAlarmInterruptEnable(DevHandle handle, enum RtcAlarmIndex alarmIndex, uint8_t enable); 205 206 /** 207 * @brief Reads the RTC external frequency. 208 * 209 * This function reads the frequency of the external crystal oscillator connected to the RTC driver. 210 * 211 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 212 * @param freq Indicates the pointer to the frequency of the external crystal oscillator, in Hz. 213 * 214 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 215 * For details, see {@link HDF_STATUS}. 216 * @since 1.0 217 */ 218 int32_t RtcGetFreq(DevHandle handle, uint32_t *freq); 219 220 /** 221 * @brief Sets the frequency of the external crystal oscillator connected to the RTC driver. 222 * 223 * Note that the frequency must be configured in accordance with the requirements specified in the product manual of 224 * the in-use component. 225 * 226 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 227 * @param freq Indicates the frequency to set for the external crystal oscillator, in Hz. 228 * 229 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 230 * For details, see {@link HDF_STATUS}. 231 * @since 1.0 232 */ 233 int32_t RtcSetFreq(DevHandle handle, uint32_t freq); 234 235 /** 236 * @brief Resets the RTC driver. 237 * 238 * After the reset, the configuration registers are restored to the default values. 239 * 240 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 241 * 242 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 243 * For details, see {@link HDF_STATUS}. 244 * @since 1.0 245 */ 246 int32_t RtcReset(DevHandle handle); 247 248 /** 249 * @brief Reads the configuration of a custom RTC register based on the register index. 250 * 251 * One index corresponds to one byte of the configuration value. 252 * 253 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 254 * @param usrDefIndex Indicates the index of the custom register. 255 * @param value Indicates the pointer to the configuration value of the specified register index. 256 * 257 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 258 * For details, see {@link HDF_STATUS}. 259 * @since 1.0 260 */ 261 int32_t RtcReadReg(DevHandle handle, uint8_t usrDefIndex, uint8_t *value); 262 263 /** 264 * @brief Writes the configuration of a custom RTC register based on the register index. 265 * 266 * One index corresponds to one byte of the configuration value. 267 * 268 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 269 * @param usrDefIndex Indicates the index of the custom register. 270 * @param value Indicates the configuration value to write at the index of the register. 271 * 272 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 273 * For details, see {@link HDF_STATUS}. 274 * @since 1.0 275 */ 276 int32_t RtcWriteReg(DevHandle handle, uint8_t usrDefIndex, uint8_t value); 277 278 #ifdef __cplusplus 279 #if __cplusplus 280 } 281 #endif 282 #endif /* __cplusplus */ 283 284 #endif /* RTC_IF_H */ 285 /** @} */ 286 287