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 HAL adc \n 16 * 17 * History: \n 18 * 2022-09-16， Create file. \n 19 */ 20 #ifndef HAL_ADC_H 21 #define HAL_ADC_H 22 23 #include <stdint.h> 24 #include <stdbool.h> 25 #include "errcode.h" 26 #include "adc_porting.h" 27 28 #ifdef __cplusplus 29 #if __cplusplus 30 extern "C" { 31 #endif /* __cplusplus */ 32 #endif /* __cplusplus */ 33 34 /** 35 * @defgroup drivers_hal_adc_api ADC 36 * @ingroup drivers_hal_adc 37 * @{ 38 */ 39 40 typedef port_adc_scan_freq_t hal_adc_scan_freq_t; 41 42 /** 43 * @if Eng 44 * @brief ADC scan type. 45 * @else 46 * @brief adc扫描类型。 47 * @endif 48 */ 49 typedef enum { 50 /** @if Eng Interrupt will be triggered when fifo is full(128 word). 51 * @else 当fifo满（128字）时，将触发中断。 52 * @endif */ 53 HAL_ADC_SCAN_TYPE_FIFO_FULL, 54 /** @if Eng Interrupt will be triggered when sample result out of volatage range(v) \n 55 * threshold_l ~ threshold_h. 56 * @else 当样本结果超出电压范围（v）时，将触发中断， \n 57 * 阈值_l~阈值_h。 58 * @endif */ 59 HAL_ADC_SCAN_TYPE_THRESHOLD 60 } hal_adc_scan_type_t; 61 62 /** 63 * @if Eng 64 * @brief ADC scan config. 65 * @else 66 * @brief adc扫描配置。 67 * @endif 68 */ 69 typedef struct { 70 /** @if Eng Fifo full scan or threshold scan. 71 * @else Fifo全扫描或阈值扫描。 72 * @endif */ 73 hal_adc_scan_type_t type; 74 /** @if Eng ADC scan frequency, is public used for all channel. 75 * @else adc扫描频率，用于所有频道。 76 * @endif */ 77 hal_adc_scan_freq_t freq; 78 /** @if Eng Threshold scan volatage(v) lower limit. 79 * @else 阈值扫描电压（v）下限。 80 * @endif */ 81 float threshold_l; 82 /** @if Eng Threshold scan volatage(v) upper limit. 83 * @else 阈值扫描电压（v）上限。 84 * @endif */ 85 float threshold_h; 86 #if defined(CONFIG_ADC_SUPPORT_LONG_SAMPLE) 87 /** @if Eng ADC long sample report cycle [ms]. 88 * @else ADC长采样上报周期（单位：毫秒）。 89 * @endif */ 90 uint32_t long_sample_time; 91 #endif 92 } hal_adc_scan_config_t; 93 94 /** 95 * @if Eng 96 * @brief ADC channel type. 97 * @else 98 * @brief adc通道类型。 99 * @endif 100 */ 101 typedef enum { 102 /** @if Eng differential with buffer channel. 103 * @else 带缓冲通道的差分。 104 * @endif */ 105 HAL_ADC_CHANNEL_TYPE_DIF_BUF, 106 /** @if Eng single with buffer channel. 107 * @else 带缓冲通道的单通道。 108 * @endif */ 109 HAL_ADC_CHANNEL_TYPE_SIN_BUF, 110 /** @if Eng single without buffer channel. 111 * @else 单通道无缓冲通道。 112 * @endif */ 113 HAL_ADC_CHANNEL_TYPE_SIN_NOBUF, 114 HAL_ADC_CHANNEL_TYPE_NONE 115 } hal_adc_channel_type_t; 116 117 /** 118 * @if Eng 119 * @brief ADC buffer type. 120 * @else 121 * @brief adc缓存类型。 122 * @endif 123 */ 124 typedef enum { 125 HAL_ADC_BUFFER_OFF = 0, 126 HAL_ADC_BUFFER_ON = 0x1, 127 HAL_ADC_BUFFER_DIFF = 0x3, 128 HAL_ADC_BUFFER_MAX, 129 HAL_ADC_BUFFER_NONE = HAL_ADC_BUFFER_MAX 130 } hal_adc_buffer_t; 131 132 /** 133 * @if Eng 134 * @brief ADC auto scan discard number. 135 * @else 136 * @brief adc自动扫描丢弃次数。 137 * @endif 138 */ 139 typedef enum { 140 HAL_ADC_SCAN_DIS_8, 141 HAL_ADC_SCAN_DIS_16, 142 HAL_ADC_SCAN_DIS_32, 143 HAL_ADC_SCAN_DIS_64, 144 HAL_ADC_SCAN_DIS_128, 145 HAL_ADC_SCAN_DIS_256, 146 HAL_ADC_SCAN_DIS_512, 147 HAL_ADC_SCAN_DIS_1024, 148 HAL_ADC_SCAN_DIS_MAX, 149 HAL_ADC_SCAN_DIS_NONE = HAL_ADC_SCAN_DIS_MAX 150 } hal_adc_scan_dis_t; 151 152 /** 153 * @if Eng 154 * @brief ADC auto scan average number. 155 * @else 156 * @brief adc自动扫描平均次数。 157 * @endif 158 */ 159 typedef enum { 160 HAL_ADC_SCAN_AVG_2, 161 HAL_ADC_SCAN_AVG_4, 162 HAL_ADC_SCAN_AVG_8, 163 HAL_ADC_SCAN_AVG_16, 164 HAL_ADC_SCAN_AVG_MAX, 165 HAL_ADC_SCAN_AVG_NONE = HAL_ADC_SCAN_AVG_MAX 166 } hal_adc_scan_avg_t; 167 168 /** 169 * @if Eng 170 * @brief Auto scan callback for hal adc. 171 * @param [in] channel Auto scan channel. 172 * @param [out] buffer Auto scan sample result buffer. 173 * @param [in] length When scan failed, length is 0; \n 174 when fifo full scan, length is 128; \n 175 when threshold scan, length is 1. 176 * @param [out] next Continue auto scan or stop auto scan. 177 * @else 178 * @param [in] channel 自动扫描通道。 179 * @param [out] buffer 自动扫描采样结果存放。 180 * @param [in] length 扫描失败时，长度为0;fifo全扫描时，长度为128；阈值扫描时，长度为1。 181 * @param [out] next 继续自动扫描或停止自动扫描。 182 * @endif 183 */ 184 typedef void (*hal_adc_callback_t)(uint8_t channel, uint32_t *buffer, uint32_t length, bool *next); 185 186 /** 187 * @if Eng 188 * @brief Initialize device for hal adc. 189 * @retval ERRCODE_SUCC Success. 190 * @retval Other Failure. For details, see @ref errcode_t. 191 * @else 192 * @brief HAL层adc的初始化接口。 193 * @retval ERRCODE_SUCC 成功。 194 * @retval Other 失败，参考 @ref errcode_t 。 195 * @endif 196 */ 197 typedef errcode_t (*hal_adc_init_t)(void); 198 199 /** 200 * @if Eng 201 * @brief Deinitialize device for hal adc. 202 * @retval ERRCODE_SUCC Success. 203 * @retval Other Failure. For details, see @ref errcode_t. 204 * @else 205 * @brief HAL层adc的去初始化接口。 206 * @retval ERRCODE_SUCC 成功。 207 * @retval Other 失败，参考 @ref errcode_t 。 208 * @endif 209 */ 210 typedef errcode_t (*hal_adc_deinit_t)(void); 211 212 /** 213 * @if Eng 214 * @brief Power on/off interface for hal adc. 215 * @param [in] on flag of power on or off. 216 * @else 217 * @brief HAL层adc上下电接口。 218 * @param [in] on 上下电标志。 219 * @endif 220 */ 221 typedef void (*hal_adc_power_en_t)(afe_scan_mode_t afe_scan_mode, bool on); 222 223 /** 224 * @if Eng 225 * @brief Channel select interface for hal adc. 226 * @param [in] ch The adc channel. For details, see @ref adc_channel_t. 227 * @param [in] on flag of enable or disable. 228 * @retval ERRCODE_SUCC Success. 229 * @retval Other Failure. For details, see @ref errcode_t. 230 * @else 231 * @brief HAL层通道选择接口。 232 * @param [in] ch adc通道 参考 @ref adc_channel_t 。 233 * @param [in] on 使能/去使能标志。 234 * @retval ERRCODE_SUCC 成功。 235 * @retval Other 失败，参考 @ref errcode_t 。 236 * @endif 237 */ 238 typedef errcode_t (*hal_adc_set_t)(adc_channel_t ch, bool on); 239 240 #if defined(CONFIG_ADC_SUPPORT_DIFFERENTIAL) 241 /** 242 * @if Eng 243 * @brief Channel select differential interface for hal adc. 244 * @param [in] postive_ch The postive adc channel. For details, see @ref adc_channel_t. 245 * @param [in] negative_ch The negative adc channel. For details, see @ref adc_channel_t. 246 * @param [in] on flag of enable or disable. 247 * @retval ERRCODE_SUCC Success. 248 * @retval Other Failure. For details, see @ref errcode_t. 249 * @else 250 * @brief HAL层通道选择差分接口。 251 * @param [in] postive_ch adc正通道 参考 @ref adc_channel_t 。 252 * @param [in] negative_ch adc负通道 参考 @ref adc_channel_t 。 253 * @param [in] on 使能/去使能标志。 254 * @retval ERRCODE_SUCC 成功。 255 * @retval Other 失败，参考 @ref errcode_t 。 256 * @endif 257 */ 258 typedef errcode_t (*hal_adc_diff_set_t)(adc_channel_t postive_ch, adc_channel_t negative_ch, bool on); 259 #endif 260 261 #if defined(CONFIG_ADC_SUPPORT_AUTO_SCAN) 262 /** 263 * @if Eng 264 * @brief Configure channel auto scan interface for hal adc. 265 * @param [in] ch The adc channel. For details, see @ref adc_channel_t. 266 * @param [in] adc_config Auto scan config. For details, see @ref adc_scan_config_t. 267 * @param [in] callback Auto scan interrupt callback. For details, see @ref hal_adc_callback_t. 268 * @retval ERRCODE_SUCC Success. 269 * @retval Other Failure. For details, see @ref errcode_t. 270 * @else 271 * @brief HAL层单个通道的自动扫描配置接口。 272 * @param [in] ch adc通道 参考 @ref adc_channel_t 。 273 * @param [in] adc_config 自动扫描配置信息 参考 @ref adc_scan_config_t 。 274 * @param [in] callback 自动扫描中断回调函数 参考 @ref hal_adc_callback_t 。 275 * @retval ERRCODE_SUCC 成功。 276 * @retval Other 失败，参考 @ref errcode_t 。 277 * @endif 278 */ 279 typedef errcode_t (*hal_adc_ch_config_t)(adc_channel_t ch, hal_adc_scan_config_t *adc_config, 280 hal_adc_callback_t callback); 281 282 /** 283 * @if Eng 284 * @brief Channel auto scan enable/disable interface for hal adc. 285 * @param [in] ch The adc channel. For details, see @ref adc_channel_t. 286 * @param [in] en The adc channel auto scan enable flag. 287 * @retval ERRCODE_SUCC Success. 288 * @retval Other Failure. For details, see @ref errcode_t. 289 * @else 290 * @brief HAL层单个通道的自动扫描使能/去使能接口。 291 * @param [in] ch adc通道 参考 @ref adc_channel_t 。 292 * @param [in] en adc通道自动扫描使能标志。 293 * @retval ERRCODE_SUCC 成功。 294 * @retval Other 失败，参考 @ref errcode_t 。 295 * @endif 296 */ 297 typedef errcode_t (*hal_adc_ch_enable_t)(adc_channel_t ch, bool en); 298 299 /** 300 * @if Eng 301 * @brief Auto scan control enable/disable interface for hal adc. 302 * @param [in] en adc auto scan control enable flag. 303 * @else 304 * @brief HAL层自动扫描总控制使能/去使能接口。 305 * @param [in] en adc自动扫描总控制使能标志。 306 * @endif 307 */ 308 typedef void (*hal_adc_enable_t)(bool en); 309 310 /** 311 * @if Eng 312 * @brief Auto scan enable judgment interface for hal adc. 313 * @retval true enabled. 314 * @retval false disable. 315 * @else 316 * @brief HAL层自动扫描总控制判断接口。 317 * @retval true 使能。 318 * @retval false 未使能。 319 * @endif 320 */ 321 typedef bool (*hal_adc_isenable_t)(void); 322 #endif /* CONFIG_ADC_SUPPORT_AUTO_SCAN */ 323 324 #if defined(CONFIG_ADC_SUPPORT_AFE) 325 /** 326 * @if Eng 327 * @brief ADC auto sample interface for hal adc. 328 * @param [in] channel The adc channel. For details, see @ref adc_channel_t. 329 * @retval ADC sample stick. 330 * @else 331 * @brief HAL层自动采样接口接口。 332 * @param [in] channel adc通道 参考 @ref adc_channel_t 。 333 * @retval ADC自动采样值。 334 * @endif 335 */ 336 typedef int32_t (*hal_adc_auto_sample_t)(adc_channel_t channel); 337 #endif /* CONFIG_ADC_SUPPORT_AFE */ 338 339 /** 340 * @if Eng 341 * @brief ADC manual sample interface for hal adc. 342 * @retval ADC sample stick. 343 * @else 344 * @brief HAL层手动采样接口接口。 345 * @retval 采样值。 346 * @endif 347 */ 348 typedef int32_t (*hal_adc_manual_t)(adc_channel_t channel); 349 350 /** 351 * @if Eng 352 * @brief Interface between ADC driver and ADC hal. 353 * @else 354 * @brief Driver层adc和HAL层adc的接口。 355 * @endif 356 */ 357 typedef struct { 358 hal_adc_init_t init; /*!< @if Eng Init device interface. 359 @else HAL层adc的初始化接口。 @endif */ 360 hal_adc_deinit_t deinit; /*!< @if Eng Deinit device interface. 361 @else HAL层adc去初始化接口。 @endif */ 362 hal_adc_power_en_t power_en; /*!< @if Eng Power on/off device interface. 363 @else HAL层adc上下电接口 。@endif */ 364 hal_adc_set_t ch_set; /*!< @if Eng Channel select device interface. 365 @else HAL层adc通道选择接口。 @endif */ 366 #if defined(CONFIG_ADC_SUPPORT_DIFFERENTIAL) 367 hal_adc_diff_set_t diff_ch_set; /*!< @if Eng Channel select diff device interface. 368 @else HAL层adc差分通道选择接口。 @endif */ 369 #endif 370 #if defined(CONFIG_ADC_SUPPORT_AUTO_SCAN) 371 hal_adc_ch_config_t ch_config; /*!< @if Eng Channel auto scan enable device interface. 372 @else HAL层adc单个通道的自动扫描使能接口。 @endif */ 373 hal_adc_ch_enable_t ch_enable; /*!< @if Eng Channel auto scan disable device interface. 374 @else HAL层adc单个通道的自动扫描去使能接口。 @endif */ 375 hal_adc_enable_t enable; /*!< @if Eng Auto scan control enable/disable device interface. 376 @else HAL层adc自动扫描总控制开关使能/去使能接口。 @endif */ 377 hal_adc_isenable_t isenable; /*!< @if Eng Auto scan control enabled device interface. 378 @else HAL层adc判断是否已经使能自动扫描总控制接口。 @endif */ 379 #endif /* CONFIG_ADC_SUPPORT_AUTO_SCAN */ 380 #if defined(CONFIG_ADC_SUPPORT_AFE) 381 hal_adc_auto_sample_t auto_sample; /*!< @if Eng Auto sample based on pre-configured parameters. 382 @else HAL层adc依据前序配置的参数自动采样。 @endif */ 383 #endif /* CONFIG_ADC_SUPPORT_AFE */ 384 hal_adc_manual_t manual; /*!< @if Eng Manual sample device interface. 385 @else HAL层adc手动采样获取采样值接口。 @endif */ 386 } hal_adc_funcs_t; 387 388 /** 389 * @if Eng 390 * @brief Register @ref hal_adc_funcs_t into the g_hal_adcs_funcs. 391 * @param [out] funcs Interface between adc driver and adc hal. 392 * @retval ERRCODE_SUCC Success. 393 * @retval Other Failure. For details, see @ref errcode_t. 394 * @else 395 * @brief 注册 @ref hal_adc_funcs_t 到 g_hal_adcs_funcs 。 396 * @param [out] funcs Driver层adc和HAL层adc的接口实例。 397 * @retval ERRCODE_SUCC 成功。 398 * @retval Other 失败，参考 @ref errcode_t 。 399 * @endif 400 */ 401 errcode_t hal_adc_register_funcs(hal_adc_funcs_t *funcs); 402 403 /** 404 * @if Eng 405 * @brief Unregister @ref hal_adc_funcs_t from the g_hal_adcs_funcs. 406 * @return ERRCODE_SUCC Success. 407 * @retval Other Failure. For details, see @ref errcode_t. 408 * @else 409 * @brief 从g_hal_adcs_funcs注销 @ref hal_adc_funcs_t 。 410 * @return ERRCODE_SUCC 成功。 411 * @retval Other 失败，参考 @ref errcode_t 。 412 * @endif 413 */ 414 errcode_t hal_adc_unregister_funcs(void); 415 416 /** 417 * @if Eng 418 * @brief Get interface between adc driver and adc hal, see @ref hal_adc_funcs_t. 419 * @return Interface between adc driver and adc hal, see @ref hal_adc_funcs_t. 420 * @else 421 * @brief 获取Driver层adc和HAL层adc的接口实例，参考 @ref hal_adc_funcs_t 。 422 * @return Driver层adc和HAL层adc的接口实例，参考 @ref hal_adc_funcs_t 。 423 * @endif 424 */ 425 hal_adc_funcs_t *hal_adc_get_funcs(void); 426 427 /** 428 * @} 429 */ 430 431 #ifdef __cplusplus 432 #if __cplusplus 433 } 434 #endif /* __cplusplus */ 435 #endif /* __cplusplus */ 436 437 #endif