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