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