1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 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 #ifndef __ADC_HAL_H__ 16 #define __ADC_HAL_H__ 17 18 #pragma once 19 20 #include "soc/soc_caps.h" 21 #include "hal/adc_types.h" 22 #include "hal/adc_ll.h" 23 #include "esp_err.h" 24 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif /* __cplusplus */ 29 30 #if CONFIG_IDF_TARGET_ESP32C3 31 #include "soc/gdma_struct.h" 32 #include "hal/gdma_ll.h" 33 #include "hal/dma_types.h" 34 #include "hal/adc_ll.h" 35 #include "hal/dma_types.h" 36 #include "esp_err.h" 37 38 //For ADC module, each conversion contains 4 bytes 39 #define ADC_HAL_DATA_LEN_PER_CONV 4 40 41 /** 42 * @brief Enum for DMA descriptor status 43 */ 44 typedef enum adc_hal_dma_desc_status_t { 45 ADC_HAL_DMA_DESC_VALID = 0, ///< This DMA descriptor is written by HW already 46 ADC_HAL_DMA_DESC_WAITING = 1, ///< This DMA descriptor is not written by HW yet 47 ADC_HAL_DMA_DESC_NULL = 2 ///< This DMA descriptor is NULL 48 } adc_hal_dma_desc_status_t; 49 50 /** 51 * @brief Configuration of the HAL 52 */ 53 typedef struct adc_hal_config_t { 54 uint32_t desc_max_num; ///< Number of the descriptors linked once 55 uint32_t dma_chan; ///< DMA channel to be used 56 uint32_t eof_num; ///< Bytes between 2 in_suc_eof interrupts 57 } adc_hal_config_t; 58 59 /** 60 * @brief Context of the HAL 61 */ 62 typedef struct adc_hal_context_t { 63 /**< this needs to be malloced by the driver layer first */ 64 dma_descriptor_t *rx_desc; ///< DMA descriptors 65 66 /**< these will be assigned by hal layer itself */ 67 gdma_dev_t *dev; ///< GDMA address 68 dma_descriptor_t desc_dummy_head; ///< Dummy DMA descriptor for ``cur_desc_ptr`` to start 69 dma_descriptor_t *cur_desc_ptr; ///< Pointer to the current descriptor 70 71 /**< these need to be configured by `adc_hal_config_t` via driver layer*/ 72 uint32_t desc_max_num; ///< Number of the descriptors linked once 73 uint32_t dma_chan; ///< DMA channel to be used 74 uint32_t eof_num; ///< Words between 2 in_suc_eof interrupts 75 } adc_hal_context_t; 76 #endif 77 78 /*--------------------------------------------------------------- 79 Common setting 80 ---------------------------------------------------------------*/ 81 /** 82 * ADC module initialization. 83 */ 84 void adc_hal_init(void); 85 86 /** 87 * Set ADC module power management. 88 * 89 * @prarm manage Set ADC power status. 90 */ 91 #define adc_hal_set_power_manage(manage) adc_ll_set_power_manage(manage) 92 93 /** 94 * ADC module clock division factor setting. ADC clock devided from APB clock. 95 * 96 * @prarm div Division factor. 97 */ 98 #define adc_hal_digi_set_clk_div(div) adc_ll_digi_set_clk_div(div) 99 100 #if !CONFIG_IDF_TARGET_ESP32C3 101 /** 102 * ADC SAR clock division factor setting. ADC SAR clock devided from `RTC_FAST_CLK`. 103 * 104 * @prarm div Division factor. 105 */ 106 #define adc_hal_set_sar_clk_div(adc_n, div) adc_ll_set_sar_clk_div(adc_n, div) 107 108 /** 109 * Set ADC module controller. 110 * There are five SAR ADC controllers: 111 * Two digital controller: Continuous conversion mode (DMA). High performance with multiple channel scan modes; 112 * Two RTC controller: Single conversion modes (Polling). For low power purpose working during deep sleep; 113 * the other is dedicated for Power detect (PWDET / PKDET), Only support ADC2. 114 * 115 * @prarm adc_n ADC unit. 116 * @prarm ctrl ADC controller. 117 */ 118 #define adc_hal_set_controller(adc_n, ctrl) adc_ll_set_controller(adc_n, ctrl) 119 #endif //#if !CONFIG_IDF_TARGET_ESP32C3 120 121 #if CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3 122 /** 123 * Get the attenuation of a particular channel on ADCn. 124 * 125 * @param adc_n ADC unit. 126 * @param channel ADCn channel number. 127 * @return atten The attenuation option. 128 */ 129 #define adc_hal_get_atten(adc_n, channel) adc_ll_get_atten(adc_n, channel) 130 #endif 131 132 #if CONFIG_IDF_TARGET_ESP32 133 /** 134 * Close ADC AMP module if don't use it for power save. 135 */ 136 #define adc_hal_amp_disable() adc_ll_amp_disable() 137 #endif 138 139 /*--------------------------------------------------------------- 140 PWDET(Power detect) controller setting 141 ---------------------------------------------------------------*/ 142 143 /** 144 * Set adc cct for PWDET controller. 145 * 146 * @note Capacitor tuning of the PA power monitor. cct set to the same value with PHY. 147 * @prarm cct Range: 0 ~ 7. 148 */ 149 #define adc_hal_pwdet_set_cct(cct) adc_ll_pwdet_set_cct(cct) 150 151 /** 152 * Get adc cct for PWDET controller. 153 * 154 * @note Capacitor tuning of the PA power monitor. cct set to the same value with PHY. 155 * @return cct Range: 0 ~ 7. 156 */ 157 #define adc_hal_pwdet_get_cct() adc_ll_pwdet_get_cct() 158 159 /*--------------------------------------------------------------- 160 RTC controller setting 161 ---------------------------------------------------------------*/ 162 #if !CONFIG_IDF_TARGET_ESP32C3 163 /** 164 * Set adc output data format for RTC controller. 165 * 166 * @prarm adc_n ADC unit. 167 * @prarm bits Output data bits width option. 168 */ 169 #define adc_hal_rtc_set_output_format(adc_n, bits) adc_ll_rtc_set_output_format(adc_n, bits) 170 171 /** 172 * ADC module output data invert or not. 173 * 174 * @prarm adc_n ADC unit. 175 */ 176 #define adc_hal_rtc_output_invert(adc_n, inv_en) adc_ll_rtc_output_invert(adc_n, inv_en) 177 #endif //#if !CONFIG_IDF_TARGET_ESP32C3 178 179 /** 180 * Enable/disable the output of ADCn's internal reference voltage to one of ADC2's channels. 181 * 182 * This function routes the internal reference voltage of ADCn to one of 183 * ADC2's channels. This reference voltage can then be manually measured 184 * for calibration purposes. 185 * 186 * @note ESP32 only supports output of ADC2's internal reference voltage. 187 * @param[in] adc ADC unit select 188 * @param[in] channel ADC2 channel number 189 * @param[in] en Enable/disable the reference voltage output 190 */ 191 #define adc_hal_vref_output(adc, channel, en) adc_ll_vref_output(adc, channel, en) 192 193 /*--------------------------------------------------------------- 194 Digital controller setting 195 ---------------------------------------------------------------*/ 196 /** 197 * Digital controller deinitialization. 198 */ 199 void adc_hal_digi_deinit(void); 200 201 /** 202 * Setting the digital controller. 203 * 204 * @param cfg Pointer to digital controller paramter. 205 */ 206 void adc_hal_digi_controller_config(const adc_digi_config_t *cfg); 207 208 /** 209 * Reset the pattern table pointer, then take the measurement rule from table header in next measurement. 210 * 211 * @param adc_n ADC unit. 212 */ 213 #define adc_hal_digi_clear_pattern_table(adc_n) adc_ll_digi_clear_pattern_table(adc_n) 214 215 /*--------------------------------------------------------------- 216 ADC Single Read 217 ---------------------------------------------------------------*/ 218 #if !CONFIG_IDF_TARGET_ESP32C3 219 /** 220 * Set the attenuation of a particular channel on ADCn. 221 * 222 * @note For any given channel, this function must be called before the first time conversion. 223 * 224 * The default ADC full-scale voltage is 1.1V. To read higher voltages (up to the pin maximum voltage, 225 * usually 3.3V) requires setting >0dB signal attenuation for that ADC channel. 226 * 227 * When VDD_A is 3.3V: 228 * 229 * - 0dB attenuaton (ADC_ATTEN_DB_0) gives full-scale voltage 1.1V 230 * - 2.5dB attenuation (ADC_ATTEN_DB_2_5) gives full-scale voltage 1.5V 231 * - 6dB attenuation (ADC_ATTEN_DB_6) gives full-scale voltage 2.2V 232 * - 11dB attenuation (ADC_ATTEN_DB_11) gives full-scale voltage 3.9V (see note below) 233 * 234 * @note The full-scale voltage is the voltage corresponding to a maximum reading (depending on ADC1 configured 235 * bit width, this value is: 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits.) 236 * 237 * @note At 11dB attenuation the maximum voltage is limited by VDD_A, not the full scale voltage. 238 * 239 * Due to ADC characteristics, most accurate results are obtained within the following approximate voltage ranges: 240 * 241 * - 0dB attenuaton (ADC_ATTEN_DB_0) between 100 and 950mV 242 * - 2.5dB attenuation (ADC_ATTEN_DB_2_5) between 100 and 1250mV 243 * - 6dB attenuation (ADC_ATTEN_DB_6) between 150 to 1750mV 244 * - 11dB attenuation (ADC_ATTEN_DB_11) between 150 to 2450mV 245 * 246 * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges. 247 * 248 * @param adc_n ADC unit. 249 * @param channel ADCn channel number. 250 * @param atten ADC attenuation. See ``adc_atten_t`` 251 */ 252 #define adc_hal_set_atten(adc_n, channel, atten) adc_ll_set_atten(adc_n, channel, atten) 253 254 #else // CONFIG_IDF_TARGET_ESP32C3 255 /** 256 * Set the attenuation for ADC to single read 257 * 258 * @note All ADC units and channels will share the setting. So PLEASE DO save your attenuations and reset them by calling this API again in your driver 259 * 260 * @param adc_n Not used, leave here for chip version compatibility 261 * @param channel Not used, leave here for chip version compatibility 262 * @param atten ADC attenuation. See ``adc_atten_t`` 263 */ 264 #define adc_hal_set_atten(adc_n, channel, atten) adc_ll_onetime_set_atten(atten) 265 #endif 266 267 /** 268 * Start an ADC conversion and get the converted value. 269 * 270 * @note It may be block to wait conversion finish. 271 * 272 * @param adc_n ADC unit. 273 * @param channel ADC channel number. 274 * @param[out] out_raw ADC converted result 275 * 276 * @return 277 * - ESP_OK: The value is valid. 278 * - ESP_ERR_INVALID_STATE: The value is invalid. 279 */ 280 esp_err_t adc_hal_convert(adc_ll_num_t adc_n, int channel, int *out_raw); 281 282 /*--------------------------------------------------------------- 283 ADC calibration setting 284 ---------------------------------------------------------------*/ 285 #if SOC_ADC_HW_CALIBRATION_V1 286 // ESP32-S2 and C3 support HW offset calibration. 287 288 /** 289 * @brief Initialize default parameter for the calibration block. 290 * 291 * @param adc_n ADC index numer 292 */ 293 void adc_hal_calibration_init(adc_ll_num_t adc_n); 294 295 /** 296 * Set the calibration result (initial data) to ADC. 297 * 298 * @note Different ADC units and different attenuation options use different calibration data (initial data). 299 * 300 * @param adc_n ADC index number. 301 * @param param the calibration parameter to configure 302 */ 303 void adc_hal_set_calibration_param(adc_ll_num_t adc_n, uint32_t param); 304 305 /** 306 * Calibrate the ADC using internal connections. 307 * 308 * @note Different ADC units and different attenuation options use different calibration data (initial data). 309 * 310 * @param adc_n ADC index number. 311 * @param channel adc channel number. 312 * @param atten The attenuation for the channel 313 * @param internal_gnd true: Disconnect from the IO port and use the internal GND as the calibration voltage. 314 * false: Use IO external voltage as calibration voltage. 315 * 316 * @return 317 * - The calibration result (initial data) to ADC, use `adc_hal_set_calibration_param` to set. 318 */ 319 uint32_t adc_hal_self_calibration(adc_ll_num_t adc_n, adc_channel_t channel, adc_atten_t atten, bool internal_gnd); 320 321 #endif //SOC_ADC_HW_CALIBRATION_V1 322 323 #if CONFIG_IDF_TARGET_ESP32C3 324 /*--------------------------------------------------------------- 325 DMA setting 326 ---------------------------------------------------------------*/ 327 /** 328 * @brief Initialize the hal context 329 * 330 * @param hal Context of the HAL 331 * @param config Configuration of the HAL 332 */ 333 void adc_hal_context_config(adc_hal_context_t *hal, const adc_hal_config_t *config); 334 335 /** 336 * @brief Initialize the HW 337 * 338 * @param hal Context of the HAL 339 */ 340 void adc_hal_digi_init(adc_hal_context_t *hal); 341 342 /** 343 * @brief Reset ADC / DMA fifo 344 * 345 * @param hal Context of the HAL 346 */ 347 void adc_hal_fifo_reset(adc_hal_context_t *hal); 348 349 /** 350 * @brief Start DMA 351 * 352 * @param hal Context of the HAL 353 * @param data_buf Pointer to the data buffer, the length should be multiple of ``desc_max_num`` and ``eof_num`` in ``adc_hal_context_t`` 354 */ 355 void adc_hal_digi_rxdma_start(adc_hal_context_t *hal, uint8_t *data_buf); 356 357 /** 358 * @brief Start ADC 359 * 360 * @param hal Context of the HAL 361 */ 362 void adc_hal_digi_start(adc_hal_context_t *hal); 363 364 /** 365 * @brief Get the ADC reading result 366 * 367 * @param hal Context of the HAL 368 * @param eof_desc_addr The last descriptor that is finished by HW. Should be got from DMA 369 * @param[out] cur_desc The descriptor with ADC reading result (from the 1st one to the last one (``eof_desc_addr``)) 370 * 371 * @return See ``adc_hal_dma_desc_status_t`` 372 */ 373 adc_hal_dma_desc_status_t adc_hal_get_reading_result(adc_hal_context_t *hal, const intptr_t eof_desc_addr, dma_descriptor_t **cur_desc); 374 375 /** 376 * @brief Stop DMA 377 * 378 * @param hal Context of the HAL 379 */ 380 void adc_hal_digi_rxdma_stop(adc_hal_context_t *hal); 381 382 /** 383 * @brief Clear interrupt 384 * 385 * @param hal Context of the HAL 386 * @param mask mask of the interrupt 387 */ 388 void adc_hal_digi_clr_intr(adc_hal_context_t *hal, uint32_t mask); 389 390 /** 391 * @brief Enable interrupt 392 * 393 * @param hal Context of the HAL 394 * @param mask mask of the interrupt 395 */ 396 void adc_hal_digi_dis_intr(adc_hal_context_t *hal, uint32_t mask); 397 398 /** 399 * @brief Stop ADC 400 * 401 * @param hal Context of the HAL 402 */ 403 void adc_hal_digi_stop(adc_hal_context_t *hal); 404 405 #endif //#if CONFIG_IDF_TARGET_ESP32C3 406 407 #ifdef __cplusplus 408 } 409 #endif /* __cplusplus */ 410 #endif /* __ADC_HAL_H__ */