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 ADC driver API \n 16 * 17 * History: \n 18 * 2022-09-16, Create file. \n 19 */ 20 21 #ifndef ADC_H 22 #define ADC_H 23 24 #include <stdint.h> 25 #include <stdbool.h> 26 #include "errcode.h" 27 28 #ifdef __cplusplus 29 #if __cplusplus 30 extern "C" { 31 #endif /* __cplusplus */ 32 #endif /* __cplusplus */ 33 34 /** 35 * @defgroup drivers_driver_adc ADC 36 * @ingroup drivers_driver 37 * @{ 38 */ 39 40 /** 41 * @if Eng 42 * @brief ADC once sample need 16 clocks period, so the sample rate = adc_clk / 16. 43 * @else 44 * @brief ADC一次采样需要16个时钟周期，因此采样速率 = adc_clk / 16。 45 * @endif 46 */ 47 typedef enum adc_clock { 48 ADC_CLOCK_500KHZ = 0, /*!< @if Eng ADC clock: 500KHZ. 49 @else ADC时钟频率： 500KHZ。 @endif */ 50 ADC_CLOCK_250KHZ = 1, /*!< @if Eng ADC clock: 250KHZ. 51 @else ADC时钟频率： 250KHZ。 @endif */ 52 ADC_CLOCK_125KHZ = 2, /*!< @if Eng ADC clock: 125KHZ. 53 @else ADC时钟频率： 125KHZ。 @endif */ 54 ADC_CLOCK_015KHZ = 3, /*!< @if Eng ADC clock: 015KHZ. 55 @else ADC时钟频率： 015KHZ。 @endif */ 56 ADC_CLOCK_MAX, 57 ADC_CLOCK_NONE = ADC_CLOCK_MAX 58 } adc_clock_t; 59 60 /** 61 * @if Eng 62 * @brief The scan mode of ADC. 63 * @else 64 * @brief ADC的扫描模式。 65 * @endif 66 */ 67 typedef enum afe_scan_mode { 68 AFE_GADC_MODE = 0, /*!< @if Eng Analog Front-End ADC General precision mode. 69 @else 模拟前端ADC常规精度模式。 @endif */ 70 #if defined (CONFIG_ADC_SUPPORT_HAFE) 71 AFE_HADC_MODE, /*!< @if Eng Analog Front-End ADC High precision mode. 72 @else 模拟前端ADC高精度模式。 @endif */ 73 #elif (defined CONFIG_ADC_SUPPORT_AMIC) 74 AFE_AMIC_MODE, /*!< @if Eng Analog Front-End ADC microphone mode. 75 @else 模拟前端ADC麦克风模式。 @endif */ 76 AFE_BIO_MODE, /*!< @if Eng Analog Front-End ADC biologic mode. 77 @else 模拟前端ADC生物测量模式。 @endif */ 78 #endif 79 AFE_SCAN_MODE_MAX_NUM 80 } afe_scan_mode_t; 81 82 /** 83 * @if Eng 84 * @brief ADC scan configuration. 85 * @else 86 * @brief ADC扫描配置。 87 * @endif 88 */ 89 typedef struct adc_scan_config { 90 uint8_t type; /*!< @if Eng Scan when the FIFO is full or exceeds the threshold. 91 @else FIFO全扫描或阈值扫描。 @endif */ 92 93 float threshold_l; /*!< @if Eng Lower threshold of scanning voltage (v). 94 @else 阈值扫描电压（v）下限。 @endif */ 95 96 float threshold_h; /*!< @if Eng Upper threshold of scanning voltage (v). 97 @else 阈值扫描电压（v）上限。 @endif */ 98 99 uint8_t freq; /*!< @if Eng ADC scan frequency for all channels. 100 @else ADC扫描频率，用于所有频道。 @endif */ 101 #if defined(CONFIG_ADC_SUPPORT_LONG_SAMPLE) 102 uint32_t long_sample_time; /*!< @if Eng ADC long sample report cycle [ms]. 103 @else ADC长采样上报周期（单位：毫秒）。 @endif */ 104 #endif 105 } adc_scan_config_t; 106 107 /** 108 * @if Eng 109 * @brief Pointer to the ADC automatic scanning callback function. 110 * @param [in] channel Automatic scanning channel. 111 * @param [out] buffer Automatic scanning sample result buffer. 112 * @param [in] length When scanning failed, length is 0; \n 113 * when FIFO full scan, length is 128; \n 114 * when threshold scan, length is 1. 115 * @param [out] next Continue automatic scanning or stop automatic scanning. 116 * @else 117 * @brief ADC自动扫描回调函数指针。 118 * @param [in] channel 自动扫描通道。 119 * @param [out] buffer 自动扫描采样结果存放。 120 * @param [in] length 扫描失败时，长度为0； \n 121 * fifo全扫描时，长度为128；\n 122 * 阈值扫描时，长度为1。 123 * @param [out] next 继续自动扫描或停止自动扫描。 124 * @endif 125 */ 126 typedef void (*adc_callback_t)(uint8_t channel, uint32_t *buffer, uint32_t length, bool *next); 127 128 /** 129 * @if Eng 130 * @brief Initialize the ADC. 131 * @param [in] clock The clock which is used for ADC sample, ADC source clock is 2MHz. 132 * @retval ERRCODE_SUCC Success. 133 * @retval Other Failure. For details, see @ref errcode_t. 134 * @else 135 * @brief 初始化ADC。 136 * @param [in] clock ADC采样的时钟，ADC源时钟为2MHz。 137 * @retval ERRCODE_SUCC 成功。 138 * @retval Other 失败。参考 @ref errcode_t 。 139 * @endif 140 */ 141 errcode_t uapi_adc_init(adc_clock_t clock); 142 143 /** 144 * @if Eng 145 * @brief Deinitialize the ADC. 146 * @retval ERRCODE_SUCC Success. 147 * @retval Other Failure. For details, see @ref errcode_t. 148 * @else 149 * @brief 去初始化ADC。 150 * @retval ERRCODE_SUCC 成功。 151 * @retval Other 失败。参考 @ref errcode_t 。 152 * @endif 153 */ 154 errcode_t uapi_adc_deinit(void); 155 156 /** 157 * @if Eng 158 * @brief Power on/off and enable/disable ADC. 159 * @param [in] afe_scan_mode AFE mode to use. 160 * @param [in] en Power on or off. 161 * @else 162 * @brief 上下电并启用或关闭ADC。 163 * @param [in] afe_scan_mode 选择使用的AFE精度模式。 164 * @param [in] en 上电或下电。 165 * @endif 166 */ 167 void uapi_adc_power_en(afe_scan_mode_t afe_scan_mode, bool en); 168 169 /** 170 * @if Eng 171 * @brief Check if the ADC is in using or not. 172 * @retval true Is in using. 173 * @retval false Is not in using. 174 * @else 175 * @brief 检查ADC是否正在使用。 176 * @retval true 使用中。 177 * @retval false 未使用。 178 * @endif 179 */ 180 bool uapi_adc_is_using(void); 181 182 /** 183 * @if Eng 184 * @brief Open an ADC channel. 185 * @param [in] channel The ADC channel. 186 * @retval ERRCODE_SUCC Success. 187 * @retval Other Failure. For details, see @ref errcode_t. 188 * @else 189 * @brief 开启一个ADC通道。 190 * @param [in] channel ADC通道。 191 * @retval ERRCODE_SUCC 成功。 192 * @retval Other 失败。参考 @ref errcode_t 。 193 * @endif 194 */ 195 errcode_t uapi_adc_open_channel(uint8_t channel); 196 197 /** 198 * @if Eng 199 * @brief Close an ADC channel. 200 * @param [in] channel The ADC channel. 201 * @retval ERRCODE_SUCC Success. 202 * @retval Other Failure. For details, see @ref errcode_t. 203 * @else 204 * @brief 关闭一个ADC通道。 205 * @param [in] channel ADC通道。 206 * @retval ERRCODE_SUCC 成功。 207 * @retval Other 失败。参考 @ref errcode_t 。 208 * @endif 209 */ 210 errcode_t uapi_adc_close_channel(uint8_t channel); 211 212 #if defined(CONFIG_ADC_SUPPORT_DIFFERENTIAL) 213 /** 214 * @if Eng 215 * @brief Open differential ADC channels. 216 * @param [in] postive_ch The postive ADC channel. 217 * @param [in] negative_ch The negative ADC channel. 218 * @retval ERRCODE_SUCC Success. 219 * @retval Other Failure. For details, see @ref errcode_t. 220 * @else 221 * @brief 开启ADC差分通道。 222 * @param [in] postive_ch ADC正极通道。 223 * @param [in] negative_ch ADC负极通道。 224 * @retval ERRCODE_SUCC 成功。 225 * @retval Other 失败。参考 @ref errcode_t 。 226 * @endif 227 */ 228 errcode_t uapi_adc_open_differential_channel(uint8_t postive_ch, uint8_t negative_ch); 229 230 /** 231 * @if Eng 232 * @brief Close differential ADC channels. 233 * @param [in] postive_ch The postive ADC channel. 234 * @param [in] negative_ch The negative ADC channel. 235 * @retval ERRCODE_SUCC Success. 236 * @retval Other Failure. For details, see @ref errcode_t. 237 * @else 238 * @brief 关闭ADC差分通道。 239 * @param [in] postive_ch ADC正极通道。 240 * @param [in] negative_ch ADC负极通道。 241 * @retval ERRCODE_SUCC 成功。 242 * @retval Other 失败。参考 @ref errcode_t 。 243 * @endif 244 */ 245 errcode_t uapi_adc_close_differential_channel(uint8_t postive_ch, uint8_t negative_ch); 246 #endif 247 248 #if defined(CONFIG_ADC_SUPPORT_AUTO_SCAN) 249 /** 250 * @if Eng 251 * @brief Enable ADC automatic scanning channel, need power on ADC before enable automatic scanning. 252 * @param [in] channel The ADC channel. 253 * @param [in] config Automatic scanning configuration, FIFO full scan or threshold scan. 254 * For details, see @ref adc_scan_config_t. 255 * @param [in] callback Automatic scanning interrupt callback. 256 * For details, see @ref adc_callback_t. 257 * @retval ERRCODE_SUCC Success. 258 * @retval Other Failure. For details, see @ref errcode_t. 259 * @else 260 * @brief 启用ADC自动扫描通道，在启用自动扫描之前，需要打开ADC电源。 261 * @param [in] channel ADC通道。 262 * @param [in] config 自动扫描配置、fifo全扫描或阈值扫描。参考 @ref adc_scan_config_t 。 263 * @param [in] callback 自动扫描中断回调。参考 @ref adc_callback_t 。 264 * @retval ERRCODE_SUCC 成功。 265 * @retval Other 失败。参考 @ref errcode_t 。 266 * @endif 267 */ 268 errcode_t uapi_adc_auto_scan_ch_enable(uint8_t channel, adc_scan_config_t config, adc_callback_t callback); 269 270 /** 271 * @if Eng 272 * @brief Disable automatic scanning channel. 273 * @param [in] channel The ADC channel. 274 * @retval ERRCODE_SUCC Success. 275 * @retval Other Failure. For details, see @ref errcode_t. 276 * @else 277 * @brief 手动禁用单通道自动扫描。 278 * @param [in] channel ADC通道。 279 * @retval ERRCODE_SUCC 成功。 280 * @retval Other 失败。参考 @ref errcode_t 。 281 * @endif 282 */ 283 errcode_t uapi_adc_auto_scan_ch_disable(uint8_t channel); 284 285 /** 286 * @if Eng 287 * @brief Disable automatic scanning, which will disable all scanning channel, and power off the ADC. 288 * @else 289 * @brief 手动禁用自动扫描，禁用所有扫描通道，并关闭ADC电源。 290 * @endif 291 */ 292 void uapi_adc_auto_scan_disable(void); 293 294 /** 295 * @if Eng 296 * @brief Get automatic scanning status. 297 * @retval true enabled. 298 * @retval false disable. 299 * @else 300 * @brief 获取自动扫描状态。 301 * @retval true 使能。 302 * @retval false 未使能。 303 * @endif 304 */ 305 bool uapi_adc_auto_scan_is_enabled(void); 306 #endif /* CONFIG_ADC_SUPPORT_AUTO_SCAN */ 307 308 /** 309 * @if Eng 310 * @brief Trigger ADC manual sample. 311 * @param [in] channel The ADC channel. 312 * @return ADC sample stick. 313 * @else 314 * @brief ADC手动采样。 315 * @param [in] channel ADC通道。 316 * @return ADC采样值。 317 * @endif 318 */ 319 int32_t uapi_adc_manual_sample(uint8_t channel); 320 321 #if defined(CONFIG_ADC_SUPPORT_AFE) 322 /** 323 * @if Eng 324 * @brief Trigger ADC auto sample. 325 * @param [in] channel The ADC channel. 326 * @retval ADC sample stick. 327 * @else 328 * @brief ADC自动采样。 329 * @param [in] channel ADC通道。 330 * @retval ADC采样值。 331 * @endif 332 */ 333 int32_t uapi_adc_auto_sample(uint8_t channel); 334 #endif /* CONFIG_ADC_SUPPORT_AFE */ 335 336 /** 337 * @} 338 */ 339 340 #ifdef __cplusplus 341 #if __cplusplus 342 } 343 #endif /* __cplusplus */ 344 #endif /* __cplusplus */ 345 346 #endif 347