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 #pragma pack(push, 4) 68 struct RtcTime { 69 uint8_t second; /**< Second. The value ranges from 0 to 59. */ 70 uint8_t minute; /**< Minute. The value ranges from 0 to 59. */ 71 uint8_t hour; /**< Hour. The value ranges from 0 to 23. */ 72 uint8_t day; /**< Day. The value ranges from 1 to 31. */ 73 uint8_t weekday; /**< Day of the week. The value ranges from 1 to 7, representing Monday to Sunday. */ 74 uint8_t month; /**< Month. The value ranges from 1 to 12. */ 75 uint16_t year; /**< Year. The value is greater than or equal to 1970. */ 76 uint16_t millisecond; /**< Millisecond. The value ranges from 0 to 990, with a precision of 10 milliseconds. */ 77 }; 78 #pragma pack(pop) 79 80 /** 81 * @brief Enumerates RTC I/O commands. 82 * 83 * @since 1.0 84 */ 85 enum RtcIoCmd { 86 RTC_IO_READTIME = 0, /**< Read time. */ 87 RTC_IO_WRITETIME, /**< Write format-compliant time. */ 88 RTC_IO_READALARM, /**< Read the RTC alarm time. */ 89 RTC_IO_WRITEALARM, /**< Write the RTC alarm time. */ 90 RTC_IO_REGISTERALARMCALLBACK, /**< Registers that will be invoked when an alarm 91 is generated at the specified time. */ 92 RTC_IO_ALARMINTERRUPTENABLE, /**< Enables or disables alarm interrupts. */ 93 RTC_IO_GETFREQ, /**< Get the RTC external frequency. */ 94 RTC_IO_SETFREQ, /**< Set the oscillation frequency of RTC external crystal. */ 95 RTC_IO_RESET, /**< Reset the RTC device. */ 96 RTC_IO_READREG, /**< Reads the configuration of a custom RTC register. */ 97 RTC_IO_WRITEREG, /**< Writes the configuration of a custom RTC register. */ 98 }; 99 100 /** 101 * @brief Opens the RTC device to obtain its handle. 102 * 103 * The OS supports only one RTC device. 104 * 105 * @return Returns {@link DevHandle} if the operation is successful; returns <b>NULL</b> if the operation fails. 106 * @since 1.0 107 */ 108 DevHandle RtcOpen(void); 109 110 /** 111 * @brief Releases a specified handle of the RTC device. 112 * 113 * @param handle Indicates the pointer to the RTC device handle to release, which is created via {@link RtcGetHandle}. 114 * 115 * @since 1.0 116 */ 117 void RtcClose(DevHandle handle); 118 119 /** 120 * @brief Reads time from the RTC driver. 121 * 122 * The time information includes the year, month, day, day of the week, hour, minute, second, and millisecond. 123 * 124 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 125 * @param time Indicates the pointer to the time information read from the RTC driver. 126 * For details, see {@link RtcTime}. 127 * 128 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 129 * For details, see {@link HDF_STATUS}. 130 * @since 1.0 131 */ 132 int32_t RtcReadTime(DevHandle handle, struct RtcTime *time); 133 134 /** 135 * @brief Writes format-compliant time to the RTC driver. 136 * 137 * 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 138 * the requirements specified in the product manual of the in-use component. 139 * 140 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 141 * @param time Indicates the pointer to the time information to write. For details, see {@link RtcTime}. 142 * 143 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 144 * For details, see {@link HDF_STATUS}. 145 * @since 1.0 146 */ 147 int32_t RtcWriteTime(DevHandle handle, const struct RtcTime *time); 148 149 /** 150 * @brief Reads the RTC alarm time that was set last time. 151 * 152 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 153 * @param alarmIndex Indicates the RTC alarm index. For details, see {@link RtcAlarmIndex}. 154 * @param time Indicates the pointer to the RTC alarm time information. For details, see {@link RtcTime}. 155 * 156 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 157 * For details, see {@link HDF_STATUS}. 158 * @since 1.0 159 */ 160 int32_t RtcReadAlarm(DevHandle handle, enum RtcAlarmIndex alarmIndex, struct RtcTime *time); 161 162 /** 163 * @brief Writes the RTC alarm time based on the alarm index. 164 * 165 * 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 166 * the requirements specified in the product manual of the in-use component. 167 * 168 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 169 * @param alarmIndex Indicates the RTC alarm index. For details, see {@link RtcAlarmIndex}. 170 * @param tm Indicates the pointer to the RTC alarm time information. For details, see {@link RtcTime}. 171 * 172 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 173 * For details, see {@link HDF_STATUS}. 174 * @since 1.0 175 */ 176 int32_t RtcWriteAlarm(DevHandle handle, enum RtcAlarmIndex alarmIndex, const struct RtcTime *time); 177 178 /** 179 * @brief Registers {@link RtcAlarmCallback} that will be invoked when an alarm is generated at the specified time. 180 * 181 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 182 * @param alarmIndex Indicates the RTC alarm index. For details, see {@link RtcAlarmIndex}. 183 * @param cb Indicates the callback to register. For details, see {@link RtcAlarmCallback}. 184 * 185 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 186 * For details, see {@link HDF_STATUS}. 187 * @since 1.0 188 */ 189 int32_t RtcRegisterAlarmCallback(DevHandle handle, enum RtcAlarmIndex alarmIndex, RtcAlarmCallback cb); 190 191 /** 192 * @brief Enables or disables alarm interrupts. 193 * 194 * Before performing alarm operations, you need to call this function to enable alarm interrupts, 195 * so that the {@link RtcRegisterAlarmCallback} will be called when the alarm is not generated upon a timeout. 196 * 197 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 198 * @param alarmIndex Indicates the RTC alarm index. For details, see {@link RtcAlarmIndex}. 199 * @param enable Specifies whether to enable RTC alarm interrupts. The value <b>1</b> means to 200 * enable alarm interrupts and value <b>0</b> means to disable alarm interrupts. 201 * 202 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 203 * For details, see {@link HDF_STATUS}. 204 * @since 1.0 205 */ 206 int32_t RtcAlarmInterruptEnable(DevHandle handle, enum RtcAlarmIndex alarmIndex, uint8_t enable); 207 208 /** 209 * @brief Reads the RTC external frequency. 210 * 211 * This function reads the frequency of the external crystal oscillator connected to the RTC driver. 212 * 213 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 214 * @param freq Indicates the pointer to the frequency of the external crystal oscillator, in Hz. 215 * 216 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 217 * For details, see {@link HDF_STATUS}. 218 * @since 1.0 219 */ 220 int32_t RtcGetFreq(DevHandle handle, uint32_t *freq); 221 222 /** 223 * @brief Sets the frequency of the external crystal oscillator connected to the RTC driver. 224 * 225 * Note that the frequency must be configured in accordance with the requirements specified in the product manual of 226 * the in-use component. 227 * 228 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 229 * @param freq Indicates the frequency to set for the external crystal oscillator, in Hz. 230 * 231 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 232 * For details, see {@link HDF_STATUS}. 233 * @since 1.0 234 */ 235 int32_t RtcSetFreq(DevHandle handle, uint32_t freq); 236 237 /** 238 * @brief Resets the RTC driver. 239 * 240 * After the reset, the configuration registers are restored to the default values. 241 * 242 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 243 * 244 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 245 * For details, see {@link HDF_STATUS}. 246 * @since 1.0 247 */ 248 int32_t RtcReset(DevHandle handle); 249 250 /** 251 * @brief Reads the configuration of a custom RTC register based on the register index. 252 * 253 * One index corresponds to one byte of the configuration value. 254 * 255 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 256 * @param usrDefIndex Indicates the index of the custom register. 257 * @param value Indicates the pointer to the configuration value of the specified register index. 258 * 259 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 260 * For details, see {@link HDF_STATUS}. 261 * @since 1.0 262 */ 263 int32_t RtcReadReg(DevHandle handle, uint8_t usrDefIndex, uint8_t *value); 264 265 /** 266 * @brief Writes the configuration of a custom RTC register based on the register index. 267 * 268 * One index corresponds to one byte of the configuration value. 269 * 270 * @param handle Indicates the pointer to the RTC device handle, which is obtained via {@link RtcGetHandle}. 271 * @param usrDefIndex Indicates the index of the custom register. 272 * @param value Indicates the configuration value to write at the index of the register. 273 * 274 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 275 * For details, see {@link HDF_STATUS}. 276 * @since 1.0 277 */ 278 int32_t RtcWriteReg(DevHandle handle, uint8_t usrDefIndex, uint8_t value); 279 280 /** 281 * @brief The following rtc interfaces are only available for the mini platform 282 * 283 * @since 1.0 284 */ 285 int32_t RtcSetTimeZone(int32_t timeZone); 286 287 int32_t RtcGetTimeZone(int32_t *timeZone); 288 289 #ifdef __cplusplus 290 #if __cplusplus 291 } 292 #endif 293 #endif /* __cplusplus */ 294 295 #endif /* RTC_IF_H */ 296 /** @} */ 297 298