1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * 15 * Description: Provides RTC driver api \n 16 * 17 * History: \n 18 * 2023-03-06, Create file. \n 19 */ 20 #ifndef RTC_H 21 #define RTC_H 22 23 #include <stdint.h> 24 #include "errcode.h" 25 #include "hal_rtc.h" 26 27 #ifdef __cplusplus 28 #if __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 #endif /* __cplusplus */ 32 33 /** 34 * @defgroup drivers_driver_rtc RTC 35 * @ingroup drivers_driver 36 * @{ 37 */ 38 39 /** 40 * @if Eng 41 * @brief Handle of RTC. 42 * @else 43 * @brief RTC定时器句柄。 44 * @endif 45 */ 46 typedef void *rtc_handle_t; 47 48 /** 49 * @if Eng 50 * @brief RTC callback function. 51 * @param [in] data RTC callback function. 52 * @else 53 * @brief RTC定时器回调函数。 54 * @param [in] data RTC定时器的回调函数。 55 * @endif 56 */ 57 typedef void (*rtc_callback_t)(uintptr_t data); 58 59 /** 60 * @if Eng 61 * @brief Initialize the RTC. 62 * @retval ERRCODE_SUCC Success. 63 * @retval Other Failure. For details, see @ref errcode_t. 64 * @else 65 * @brief 初始化RTC定时器。 66 * @retval ERRCODE_SUCC 成功。 67 * @retval Other 失败，参考 @ref errcode_t 。 68 * @endif 69 */ 70 errcode_t uapi_rtc_init(void); 71 72 /** 73 * @if Eng 74 * @brief Adapt the RTC. 75 * @param [in] index Index of the low layer RTC. 76 * @param [in] int_id Interrupt ID of the low layer RTC. 77 * @param [in] int_priority RTC interrupt priority. 78 * @retval ERRCODE_SUCC Success. 79 * @retval Other Failure. For details, see @ref errcode_t. 80 * @else 81 * @brief 适配RTC定时器。 82 * @param [in] index 底层RTC定时器索引。 83 * @param [in] int_id 底层RTC定时器中断ID。 84 * @param [in] int_priority RTC定时器中断优先级。 85 * @retval ERRCODE_SUCC 成功。 86 * @retval Other 失败，参考 @ref errcode_t 。 87 * @endif 88 */ 89 errcode_t uapi_rtc_adapter(rtc_index_t index, uint32_t int_id, uint16_t int_priority); 90 91 /** 92 * @if Eng 93 * @brief Deinitialize the RTC. 94 * @retval ERRCODE_SUCC Success. 95 * @retval Other Failure. For details, see @ref errcode_t. 96 * @else 97 * @brief 去初始化RTC定时器。 98 * @retval ERRCODE_SUCC 成功。 99 * @retval Other 失败，参考 @ref errcode_t 。 100 * @endif 101 */ 102 errcode_t uapi_rtc_deinit(void); 103 104 /** 105 * @if Eng 106 * @brief Create a RTC. 107 * @param [in] index Index of the low layer RTC. 108 * @param [out] rtc RTC handle that returned. 109 * @retval ERRCODE_SUCC Success. 110 * @retval Other Failure. For details, see @ref errcode_t. 111 * @else 112 * @brief 创建RTC定时器。 113 * @param [in] index 底层RTC定时器索引。 114 * @param [out] rtc RTC定时器处理返回值。 115 * @retval ERRCODE_SUCC 成功。 116 * @retval Other 失败，参考 @ref errcode_t 。 117 * @endif 118 */ 119 errcode_t uapi_rtc_create(rtc_index_t index, rtc_handle_t *rtc); 120 121 /** 122 * @if Eng 123 * @brief Delete a RTC. 124 * @param [in] rtc RTC handle which created by @ref uapi_rtc_create. 125 * @retval ERRCODE_SUCC Success. 126 * @retval Other Failure. For details, see @ref errcode_t. 127 * @else 128 * @brief 删除RTC定时器。 129 * @param [in] rtc 被 @ref uapi_rtc_create 创建的RTC定时器。 130 * @retval ERRCODE_SUCC 成功。 131 * @retval Other 失败，参考 @ref errcode_t 。 132 * @endif 133 */ 134 errcode_t uapi_rtc_delete(rtc_handle_t rtc); 135 136 /** 137 * @if Eng 138 * @brief Start a RTC. 139 * @param [in] rtc RTC handle which created by @ref uapi_rtc_create. 140 * @param [in] rtc_ms RTC expiration time. see @ref uapi_rtc_get_max_ms obtains the maximum time. 141 * @param [in] callback The callback function of the RTC. 142 * @param [in] data Input parameter of the RTC callback function. 143 * @retval ERRCODE_SUCC Success. 144 * @retval Other Failure. For details, see @ref errcode_t. 145 * @else 146 * @brief 启动指定的RTC定时器。 147 * @param [in] rtc 被 @ref uapi_rtc_create 创建的RTC定时器。 148 * @param [in] rtc_ms RTC定时器超时时间。参考 @ref uapi_rtc_get_max_ms 函数获取最大时间。 149 * @param [in] callback RTC定时器回调函数。 150 * @param [in] data RTC定时器参数，用于传递给RTC定时器回调函数。 151 * @retval ERRCODE_SUCC 成功。 152 * @retval Other 失败，参考 @ref errcode_t 。 153 * @endif 154 */ 155 errcode_t uapi_rtc_start(rtc_handle_t rtc, uint32_t rtc_ms, rtc_callback_t callback, uintptr_t data); 156 157 /** 158 * @if Eng 159 * @brief Stop a RTC. the callback passed in by the user will not be called. 160 * @param [in] rtc RTC handle which created by @ref uapi_rtc_create. 161 * @retval ERRCODE_SUCC Success. 162 * @retval Other Failure. For details, see @ref errcode_t. 163 * @else 164 * @brief 停止指定的RTC定时器, 不会调用用户传入的callback。 165 * @param [in] rtc 被 @ref uapi_rtc_create 创建的RTC定时器。 166 * @retval ERRCODE_SUCC 成功。 167 * @retval Other 失败，参考 @ref errcode_t 。 168 * @endif 169 */ 170 errcode_t uapi_rtc_stop(rtc_handle_t rtc); 171 172 /** 173 * @if Eng 174 * @brief Access the maximum settable delay time of the RTC(ms). 175 * @retval Delay time(ms). 176 * @else 177 * @brief 用户可以获取到RTC最大可以设置的延时时间(ms)。 178 * @retval 延时时间(ms)。 179 * @endif 180 */ 181 uint32_t uapi_rtc_get_max_ms(void); 182 183 /** 184 * @if Eng 185 * @brief Obtains the number of interrupts. 186 * @retval IRQ counts. 187 * @else 188 * @brief 获取发生中断的次数。 189 * @retval 中断次数。 190 * @endif 191 */ 192 uint32_t uapi_rtc_int_cnt_record_get(rtc_index_t index); 193 194 /** 195 * @if Eng 196 * @brief Get current count of the low layer RTC. 197 * @param [in] index Index of the low layer RTC. 198 * @param [in] current_time_count Current count of the low layer RTC. 199 * @retval ERRCODE_SUCC Success. 200 * @retval Other Failure. For details, see @ref errcode_t. 201 * @else 202 * @brief 获取指定底层RTC定时器的当前计数。 203 * @param [in] index 底层RTC定时器索引。 204 * @param [in] current_time_count 底层RTC定时器当前计数值。 205 * @retval ERRCODE_SUCC 成功。 206 * @retval Other 失败，参考 @ref errcode_t 。 207 * @endif 208 */ 209 errcode_t uapi_rtc_get_current_time_count(rtc_index_t index, uint64_t *current_time_count); 210 211 /** 212 * @if Eng 213 * @brief Get current time of the low layer RTC. 214 * @param [in] index Index of the low layer RTC. 215 * @param [in] current_time_us Current time (us) of the low layer RTC. 216 * @retval ERRCODE_SUCC Success. 217 * @retval Other Failure. For details, see @ref errcode_t. 218 * @else 219 * @brief 获取指定底层RTC定时器的当前时间。 220 * @param [in] index 底层RTC定时器索引。 221 * @param [in] current_time_us 底层RTC定时器当前时间us值。 222 * @retval ERRCODE_SUCC 成功。 223 * @retval Other 失败，参考 @ref errcode_t 。 224 * @endif 225 */ 226 errcode_t uapi_rtc_get_current_time_us(rtc_index_t index, uint32_t *current_time_us); 227 228 /** 229 * @if Eng 230 * @brief Start a low layer RTC for timing, will not process interrupt. 231 * @attention When using low layer RTC for timing, the index that is already in use cannot be used. 232 * @param [in] index Index of the low layer RTC. 233 * @param [in] rtc_ms RTC expiration time. RTC_HW_MAX_MS obtains the maximum time. 234 * @retval ERRCODE_SUCC Success. 235 * @retval Other Failure. For details, see @ref errcode_t. 236 * @else 237 * @brief 启动指定底层RTC定时器，用于计时，不会处理中断。 238 * @attention 直接使用底层RTC计时的时候，不能使用已经在使用中的index。 239 * @param [in] index 底层RTC定时器索引。 240 * @param [in] rtc_ms RTC定时器超时时间。RTC_HW_MAX_MS 函数获取最大时间。 241 * @retval ERRCODE_SUCC 成功。 242 * @retval Other 失败，参考 @ref errcode_t 。 243 * @endif 244 */ 245 errcode_t uapi_rtc_start_hw_rtc(rtc_index_t index, uint64_t rtc_ms); 246 247 /** 248 * @if Eng 249 * @brief Stop a low layer RTC. 250 * @param [in] index Index of the low layer RTC. 251 * @retval ERRCODE_SUCC Success. 252 * @retval Other Failure. For details, see @ref errcode_t. 253 * @else 254 * @brief 停止指定底层RTC定时器。 255 * @param [in] index 底层RTC定时器索引。 256 * @retval ERRCODE_SUCC 成功。 257 * @retval Other 失败，参考 @ref errcode_t 。 258 * @endif 259 */ 260 errcode_t uapi_rtc_stop_hw_rtc(rtc_index_t index); 261 262 #if defined(CONFIG_RTC_SUPPORT_LPM) 263 /** 264 * @if Eng 265 * @brief Obtains the latest timeout interval of all RTCs. 266 * @retval The latest timeout, in milliseconds. 267 * @else 268 * @brief 获取所有RTC最近的超时时间。 269 * @retval 最近的超时时间(毫秒)。 270 * @endif 271 */ 272 uint32_t uapi_rtc_get_latest_timeout(void); 273 274 /** 275 * @if Eng 276 * @brief Suspend the RTC. 277 * @param [in] arg Argument for suspend. 278 * @retval ERRCODE_SUCC Success. 279 * @retval Other Failure. For details, see @ref errcode_t. 280 * @else 281 * @brief 挂起RTC。 282 * @param [in] arg 挂起所需要的参数。 283 * @retval ERRCODE_SUCC 成功。 284 * @retval Other 失败，参考 @ref errcode_t 。 285 * @endif 286 */ 287 errcode_t uapi_rtc_suspend(uintptr_t val); 288 289 /** 290 * @if Eng 291 * @brief Resume the RTC. 292 * @param [in] arg Argument for resume. 293 * @retval ERRCODE_SUCC Success. 294 * @retval Other Failure. For details, see @ref errcode_t. 295 * @else 296 * @brief 恢复RTC。 297 * @param [in] arg 恢复所需要的参数。 298 * @retval ERRCODE_SUCC 成功。 299 * @retval Other 失败，参考 @ref errcode_t 。 300 * @endif 301 */ 302 errcode_t uapi_rtc_resume(uintptr_t val); 303 #endif 304 305 /** 306 * @} 307 */ 308 309 #ifdef __cplusplus 310 #if __cplusplus 311 } 312 #endif /* __cplusplus */ 313 #endif /* __cplusplus */ 314 315 #endif