1 // Copyright (C) 2022 Beken Corporation 2 // 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 #pragma once 16 17 #include <common/bk_include.h> 18 #include <driver/adc_types.h> 19 #include <driver/hal/hal_adc_types.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /* @brief Overview about this API header 26 * 27 */ 28 29 /** 30 * @brief ADC API 31 * @defgroup bk_api_adc ADC API group 32 * @{ 33 */ 34 35 /** 36 * @brief Init the ADC driver 37 * 38 * This API init the resoure common to all ADC id: 39 * - Init ADC driver control memory 40 * 41 * @attention 1. This API should be called before any other ADC APIs. 42 * 43 * @return 44 * - BK_OK: succeed 45 * - others: other errors. 46 */ 47 bk_err_t bk_adc_driver_init(void); 48 49 /** 50 * @brief lock the runing ADC channel 51 * 52 * This API lock ADC channel which is runing. 53 * 54 * @param id ADC id 55 * 56 * @return 57 * - BK_OK: succeed 58 * - others: other errors. 59 */ 60 bk_err_t bk_adc_acquire(void); 61 62 /** 63 * @brief release the runing ADC channel 64 * 65 * This API release ADC channel which is runing. 66 * 67 * @param id ADC id 68 * 69 * @return 70 * - BK_OK: succeed 71 * - others: other errors. 72 */ 73 bk_err_t bk_adc_release(); 74 75 /** 76 * @brief Deinit the ADC driver 77 * 78 * This API free all resource related to ADC and power down all ADC. 79 * 80 * @return 81 * - BK_OK: succeed 82 * - others: other errors. 83 */ 84 bk_err_t bk_adc_driver_deinit(void); 85 86 /** 87 * @brief Init the ADC 88 * 89 * This API init the ADC: 90 * - Power up the ADC 91 * - Map the ADC id to dedicated GPIO port 92 * - Set adc work channel 93 * 94 * @param id ADC channel 95 * @param size ADC recieve data size 96 * 97 * @return 98 * - BK_OK: succeed 99 * - BK_ERR_ADC_NOT_INIT: ADC driver not init 100 * - BK_ERR_ADC_INVALID_ID: ADC id is invalid 101 * - others: other errors. 102 */ 103 bk_err_t bk_adc_init(adc_chan_t adc_id); 104 105 /** 106 * @brief Deinit the ADC id 107 * 108 * This API deinit the ADC id: 109 * - Stop the ADC 110 * - Disable the ADC id interrupt 111 * - Power down the ADC 112 * - Unmap gpio id 113 * 114 * @param id ADC id 115 * 116 * @attention 1. This API should be called before use adc. 117 * 118 * @return 119 * - BK_OK: succeed 120 * - BK_ERR_ADC_NOT_INIT: ADC driver not init 121 * - BK_ERR_ADC_INVALID_ID: ADC id is invalid 122 * - others: other errors. 123 */ 124 bk_err_t bk_adc_deinit(adc_chan_t id); 125 126 /** 127 * @brief Start the ADC 128 * 129 * This API start adc: 130 * - enable the ADC id interrupt 131 * 132 * 133 * @return 134 * - BK_OK: succeed 135 * - BK_ERR_ADC_BUSY: ADC is busy 136 * - others: other errors. 137 */ 138 bk_err_t bk_adc_start(void); 139 140 /** 141 * @brief Stop the ADC 142 * 143 * This API stop adc: 144 * - disable the ADC en bit 145 * 146 * @return 147 * - BK_OK: succeed 148 * - BK_ERR_ADC_BUSY: ADC is busy 149 * - others: other errors. 150 */ 151 bk_err_t bk_adc_stop(void); 152 153 /** 154 * @brief Start read the raw ADC data 155 * 156 * @attention 1. The read_buf is in unit of uint16_t, the application needs to 157 * malloc (size * 2) bytes for read_buf. 158 * @attention 2. The maximum value of size is CONFIG_ADC_BUF_SIZE, if the size 159 * exceeds CONFIG_ADC_BUF_SIZE, the API returns BK_ERR_ADC_SIZE_TOO_BIG. 160 * 161 * @param read_buf application malloc buffer which save the current adc value 162 * @param size the size of read_buf, the unit of size is uint16_t 163 * @param timeout adc read semaphore timeout 164 * 165 * @return 166 * - BK_ERR_ADC_BUSY: ADC is busy 167 * - BK_ERR_ADC_INVALID_MODE: ADC mode is invalid 168 * - BK_ERR_ADC_SIZE_TOO_BIG: size is too big 169 * - others: other errors. 170 */ 171 bk_err_t bk_adc_read_raw(uint16_t* read_buf, uint32_t size, uint32_t timeout); 172 173 /** 174 * @brief Start read the average value of sampling data 175 * 176 * @param data store the average value of all sample values in ADC software buffers 177 * @param timeout adc read semaphore timeout 178 * 179 * @return 180 181 * - BK_ERR_ADC_BUSY: ADC is busy 182 * - BK_ERR_ADC_INVALID_MODE: ADC mode is invalid 183 * - others: other errors. 184 */ 185 bk_err_t bk_adc_read(uint16_t* data, uint32_t timeout); 186 187 /** 188 * @brief Register the adc interrupt service routine 189 * 190 * @param isr ADC intterrupt callback 191 * @param param ADC sample data size which depend on user 192 * 193 * @return 194 * - BK_OK: succeed 195 * - BK_ERR_ADC_NOT_INIT: adc not init 196 * - others: other errors. 197 */ 198 bk_err_t bk_adc_register_isr(adc_isr_t isr, uint32_t param); 199 200 /** 201 * @brief set ADC source clock and work frequence 202 * 203 * This API set adc clock source and frequence 204 * 205 * @param src_clk adc source clock 206 * @param clk adc work clock :adc clk 207 * 208 * @return 209 * - BK_OK: succeed 210 * - BK_ERR_ADC_INVALID_SCLK_MODE: ADC source clock is invalid 211 * - others: other errors. 212 */ 213 bk_err_t bk_adc_set_clk(adc_src_clk_t src_clk, uint32_t clk); 214 215 /** 216 * @brief set ADC work channel 217 * 218 * This API set adc work channel 219 * 220 * @param adc_id adc channel 221 * 222 * @return 223 * - BK_OK: succeed 224 * - BK_ERR_ADC_INVALID_ID: ADC invalid id 225 * - others: other errors. 226 */ 227 bk_err_t bk_adc_set_channel(adc_chan_t adc_id); 228 229 /** 230 * @brief set ADC sample rate 231 * 232 * This API set adc work sample rate, period = (16 + sample_rate)*adc_clk 233 * mcu output 16 adc_clks every period 234 235 * 236 * @param sample_rate adc sample rate 237 * 238 * @return 239 * - BK_OK: succeed 240 * - others: other errors. 241 */ 242 bk_err_t bk_adc_set_sample_rate(uint32_t sample_rate); 243 244 /** 245 * @brief set ADC filter 246 * 247 * This API set adc filter, the value default < 64, 248 * data output rate = period/(filter + 1) 249 * 250 * @param filter adc filter 251 * 252 * @return 253 * - BK_OK: succeed 254 * - others: other errors. 255 */ 256 bk_err_t bk_adc_set_filter(uint32_t filter); 257 258 /** 259 * @brief set ADC steady time 260 * 261 * This API set adc filter, adc wait (steady_ctrl +1)*8 adc_clks to send valid 262 * 263 * @param steady_ctrl adc steady time 264 * 265 * @return 266 * - BK_OK: succeed 267 * - others: other errors. 268 */ 269 bk_err_t bk_adc_set_steady_time(uint32_t steady_ctrl); 270 271 /** 272 * @brief set ADC sample cnt 273 * 274 * This API sets ADC sample cnt per-interrupt, the ADC raises the interrupt 275 * when every time it samples number of cnt times. The maximum value of 276 * cnt is 32. 277 * 278 * @param cnt per-interrupt sample cnt 279 * 280 * @return 281 * - BK_OK: succeed 282 * - others: other errors. 283 */ 284 bk_err_t bk_adc_set_sample_cnt(uint32_t cnt); 285 286 287 /** 288 * @brief set adc saturate 289 * 290 * This API set adc saturate, auto process adc fifo data in cpu ,just get the data from reg ADC_DATA_16 291 * 292 * @param mode adc saturate 293 * 294 * @return 295 * - BK_OK: succeed 296 * - others: other errors. 297 */ 298 bk_err_t bk_adc_set_saturate_mode(adc_saturate_mode_t mode); 299 300 /** 301 * @brief get adc saturate 302 * 303 * This API get adc saturate 304 * 305 * @return 306 * - adc_saturate_mode_t: adc saturate mode 307 */ 308 bk_err_t bk_adc_get_saturate(adc_saturate_mode_t *mode); 309 310 /** 311 * @brief enable ADC bypass calibration 312 * 313 * @return 314 * - BK_OK: succeed 315 */ 316 bk_err_t bk_adc_enable_bypass_clalibration(void); 317 318 /** 319 * @brief disable ADC bypass calibration 320 * 321 * @return 322 * - BK_OK: succeed 323 */ 324 bk_err_t bk_adc_disable_bypass_clalibration(void); 325 326 327 /** 328 * @brief adc set config 329 * 330 * This API config adc params 331 * 332 * @param config adc parameter settings 333 334 * @return 335 * - BK_OK: succeed 336 * - BK_ERR_NULL_PARAM : param is null 337 * - BK_ERR_ADC_INVALID_MODE:adc invalid mode 338 * - BK_ERR_ADC_INVALID_SCLK_MODE: ADC source clock is invalid 339 * - BK_ERR_ADC_INVALID_ID: ADC id is invalid 340 * - others: other errors. 341 */ 342 bk_err_t bk_adc_set_config(adc_config_t *config); 343 344 /** 345 * @brief adc set mode 346 * 347 * This API config adc mode 348 * 349 * @param mode : adc mode: 350 * - 0: sleep mode: adc is power down in this mode 351 * - 1: single step mode: adc finish sample data convesion once after enable adc 352 * and wait mcu to read sample data. The mode will turn to sleep mode after mcu read this sample date 353 * It must be enabled again when you want to sample next data. 354 * - 2: software control mode: adc gengerate interrupt after sample data convesion 355 * wait mcu to read sample data. adc will convert sample data after mcu reading this sample date from data register 356 * and software cleaning int flag. 357 * - 3: continous mode:adc wait adc_setting time to sample data, and generate int flag after 358 * finish sample data convesion, then always repeat last sample way. This mode don't depend on muc reading data register. 359 * @return 360 * - BK_OK: succeed 361 * - BK_ERR_ADC_INVALID_MODE:adc invalid mode 362 * - others: other errors. 363 */ 364 bk_err_t bk_adc_set_mode(adc_mode_t adc_mode); 365 366 /** 367 * @brief get adc mode 368 * 369 * This API get adc work mode 370 * 371 * 372 * @return 373 * - adc_mode_t: adc_mode 374 */ 375 adc_mode_t bk_adc_get_mode(void); 376 377 /** 378 * @brief only use for saradc 379 */ 380 #if SARADC_AUTOTEST 381 int saradc_hal_is_fifo_empty(void); 382 void saradc_hal_start_enable(void); 383 bk_err_t bk_saradc_start_int_disable(void); 384 bk_err_t bk_saradc_set_config(adc_config_t *config, uint32_t div); 385 uint32_t bk_saradc_read_raw_data(uint32_t timeout); 386 #endif 387 /** 388 * @} 389 */ 390 391 #ifdef __cplusplus 392 } 393 #endif 394 395