1 /* 2 * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #pragma once 7 8 #include <stdbool.h> 9 #include <stdint.h> 10 #include "sdkconfig.h" 11 #include "soc/soc_caps.h" 12 #include "esp_attr.h" 13 14 /** 15 * @brief ADC unit enumeration. 16 * 17 * @note For ADC digital controller (DMA mode), ESP32 doesn't support `ADC_UNIT_2`, `ADC_UNIT_BOTH`, `ADC_UNIT_ALTER`. 18 */ 19 typedef enum { 20 ADC_UNIT_1 = 1, /*!< SAR ADC 1. */ 21 ADC_UNIT_2 = 2, /*!< SAR ADC 2. */ 22 ADC_UNIT_BOTH = 3, /*!< SAR ADC 1 and 2. */ 23 ADC_UNIT_ALTER = 7, /*!< SAR ADC 1 and 2 alternative mode. */ 24 ADC_UNIT_MAX, 25 } adc_unit_t; 26 27 /** 28 * @brief ADC channels handle. See ``adc1_channel_t``, ``adc2_channel_t``. 29 * 30 * @note For ESP32 ADC1, don't use `ADC_CHANNEL_8`, `ADC_CHANNEL_9`. See ``adc1_channel_t``. 31 */ 32 typedef enum { 33 ADC_CHANNEL_0 = 0, /*!< ADC channel */ 34 ADC_CHANNEL_1, /*!< ADC channel */ 35 ADC_CHANNEL_2, /*!< ADC channel */ 36 ADC_CHANNEL_3, /*!< ADC channel */ 37 ADC_CHANNEL_4, /*!< ADC channel */ 38 ADC_CHANNEL_5, /*!< ADC channel */ 39 ADC_CHANNEL_6, /*!< ADC channel */ 40 ADC_CHANNEL_7, /*!< ADC channel */ 41 ADC_CHANNEL_8, /*!< ADC channel */ 42 ADC_CHANNEL_9, /*!< ADC channel */ 43 ADC_CHANNEL_MAX, 44 } adc_channel_t; 45 46 /** 47 * @brief ADC attenuation parameter. Different parameters determine the range of the ADC. See ``adc1_config_channel_atten``. 48 */ 49 typedef enum { 50 ADC_ATTEN_DB_0 = 0, /*!<No input attenumation, ADC can measure up to approx. 800 mV. */ 51 ADC_ATTEN_DB_2_5 = 1, /*!<The input voltage of ADC will be attenuated extending the range of measurement by about 2.5 dB (1.33 x) */ 52 ADC_ATTEN_DB_6 = 2, /*!<The input voltage of ADC will be attenuated extending the range of measurement by about 6 dB (2 x) */ 53 ADC_ATTEN_DB_11 = 3, /*!<The input voltage of ADC will be attenuated extending the range of measurement by about 11 dB (3.55 x) */ 54 ADC_ATTEN_MAX, 55 } adc_atten_t; 56 57 /** 58 * @brief ADC resolution setting option. 59 * @note Only used in single read mode 60 */ 61 typedef enum { 62 #if CONFIG_IDF_TARGET_ESP32 63 ADC_WIDTH_BIT_9 = 0, /*!< ADC capture width is 9Bit. */ 64 ADC_WIDTH_BIT_10 = 1, /*!< ADC capture width is 10Bit. */ 65 ADC_WIDTH_BIT_11 = 2, /*!< ADC capture width is 11Bit. */ 66 ADC_WIDTH_BIT_12 = 3, /*!< ADC capture width is 12Bit. */ 67 #elif SOC_ADC_MAX_BITWIDTH == 12 68 ADC_WIDTH_BIT_12 = 3, /*!< ADC capture width is 12Bit. */ 69 #elif SOC_ADC_MAX_BITWIDTH == 13 70 ADC_WIDTH_BIT_13 = 4, /*!< ADC capture width is 13Bit. */ 71 #endif 72 ADC_WIDTH_MAX, 73 } adc_bits_width_t; 74 75 /** 76 * @brief ADC digital controller (DMA mode) work mode. 77 */ 78 typedef enum { 79 ADC_CONV_SINGLE_UNIT_1 = 1, ///< Only use ADC1 for conversion 80 ADC_CONV_SINGLE_UNIT_2 = 2, ///< Only use ADC2 for conversion 81 ADC_CONV_BOTH_UNIT = 3, ///< Use Both ADC1 and ADC2 for conversion simultaneously 82 ADC_CONV_ALTER_UNIT = 7, ///< Use both ADC1 and ADC2 for conversion by turn. e.g. ADC1 -> ADC2 -> ADC1 -> ADC2 ..... 83 ADC_CONV_UNIT_MAX, 84 } adc_digi_convert_mode_t; 85 86 /** 87 * @brief ADC digital controller (DMA mode) output data format option. 88 */ 89 typedef enum { 90 ADC_DIGI_FORMAT_12BIT __attribute__((deprecated)), /*!<ADC to DMA data format, [15:12]-channel, [11: 0]-12 bits ADC data (`adc_digi_output_data_t`). Note: For single convert mode. */ 91 ADC_DIGI_FORMAT_11BIT __attribute__((deprecated)), /*!<ADC to DMA data format, [15]-adc unit, [14:11]-channel, [10: 0]-11 bits ADC data (`adc_digi_output_data_t`). Note: For multi or alter convert mode. */ 92 ADC_DIGI_FORMAT_MAX __attribute__((deprecated)), 93 94 ADC_DIGI_OUTPUT_FORMAT_TYPE1, ///< See `adc_digi_output_data_t.type1` 95 ADC_DIGI_OUTPUT_FORMAT_TYPE2, ///< See `adc_digi_output_data_t.type2` 96 } adc_digi_output_format_t; 97 98 /** 99 * @brief ADC digital controller pattern configuration 100 */ 101 typedef struct { 102 uint8_t atten; ///< Attenuation of this ADC channel 103 uint8_t channel; ///< ADC channel 104 uint8_t unit; ///< ADC unit 105 uint8_t bit_width; ///< ADC output bit width 106 } adc_digi_pattern_config_t; 107 108 /*--------------------------------------------------------------- 109 Output Format 110 ---------------------------------------------------------------*/ 111 #if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 112 /** 113 * @brief ADC digital controller (DMA mode) output data format. 114 * Used to analyze the acquired ADC (DMA) data. 115 * @note ESP32: Only `type1` is valid. ADC2 does not support DMA mode. 116 * @note ESP32-S2: Member `channel` can be used to judge the validity of the ADC data, 117 * because the role of the arbiter may get invalid ADC data. 118 */ 119 typedef struct { 120 union { 121 struct { 122 uint16_t data: 12; /*!<ADC real output data info. Resolution: 12 bit. */ 123 uint16_t channel: 4; /*!<ADC channel index info. */ 124 } type1; 125 struct { 126 uint16_t data: 11; /*!<ADC real output data info. Resolution: 11 bit. */ 127 uint16_t channel: 4; /*!<ADC channel index info. For ESP32-S2: 128 If (channel < ADC_CHANNEL_MAX), The data is valid. 129 If (channel > ADC_CHANNEL_MAX), The data is invalid. */ 130 uint16_t unit: 1; /*!<ADC unit index info. 0: ADC1; 1: ADC2. */ 131 } type2; /*!<When the configured output format is 11bit. `ADC_DIGI_FORMAT_11BIT` */ 132 uint16_t val; /*!<Raw data value */ 133 }; 134 } adc_digi_output_data_t; 135 136 #elif CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32H2 137 /** 138 * @brief ADC digital controller (DMA mode) output data format. 139 * Used to analyze the acquired ADC (DMA) data. 140 */ 141 typedef struct { 142 union { 143 struct { 144 uint32_t data: 12; /*!<ADC real output data info. Resolution: 12 bit. */ 145 uint32_t reserved12: 1; /*!<Reserved12. */ 146 uint32_t channel: 3; /*!<ADC channel index info. 147 If (channel < ADC_CHANNEL_MAX), The data is valid. 148 If (channel > ADC_CHANNEL_MAX), The data is invalid. */ 149 uint32_t unit: 1; /*!<ADC unit index info. 0: ADC1; 1: ADC2. */ 150 uint32_t reserved17_31: 15; /*!<Reserved17. */ 151 } type2; /*!<When the configured output format is 12bit. `ADC_DIGI_FORMAT_11BIT` */ 152 uint32_t val; /*!<Raw data value */ 153 }; 154 } adc_digi_output_data_t; 155 156 #elif CONFIG_IDF_TARGET_ESP32S3 157 /** 158 * @brief ADC digital controller (DMA mode) output data format. 159 * Used to analyze the acquired ADC (DMA) data. 160 */ 161 typedef struct { 162 union { 163 struct { 164 uint32_t data: 13; /*!<ADC real output data info. Resolution: 13 bit. */ 165 uint32_t channel: 4; /*!<ADC channel index info. 166 If (channel < ADC_CHANNEL_MAX), The data is valid. 167 If (channel > ADC_CHANNEL_MAX), The data is invalid. */ 168 uint32_t unit: 1; /*!<ADC unit index info. 0: ADC1; 1: ADC2. */ 169 uint32_t reserved17_31: 14; /*!<Reserved17. */ 170 } type2; /*!<When the configured output format is 12bit. `ADC_DIGI_FORMAT_11BIT` */ 171 uint32_t val; /*!<Raw data value */ 172 }; 173 } adc_digi_output_data_t; 174 #endif 175 176 177 #if SOC_ADC_ARBITER_SUPPORTED 178 /*--------------------------------------------------------------- 179 Arbiter 180 ---------------------------------------------------------------*/ 181 /** 182 * @brief ADC arbiter work mode option. 183 * 184 * @note ESP32-S2: Only ADC2 support arbiter. 185 */ 186 typedef enum { 187 ADC_ARB_MODE_SHIELD,/*!<Force shield arbiter, Select the highest priority controller to work. */ 188 ADC_ARB_MODE_FIX, /*!<Fixed priority switch controller mode. */ 189 ADC_ARB_MODE_LOOP, /*!<Loop priority switch controller mode. Each controller has the same priority, 190 and the arbiter will switch to the next controller after the measurement is completed. */ 191 } adc_arbiter_mode_t; 192 193 /** 194 * @brief ADC arbiter work mode and priority setting. 195 * 196 * @note ESP32-S2: Only ADC2 support arbiter. 197 */ 198 typedef struct { 199 adc_arbiter_mode_t mode; /*!<Refer to ``adc_arbiter_mode_t``. Note: only support ADC2. */ 200 uint8_t rtc_pri; /*!<RTC controller priority. Range: 0 ~ 2. */ 201 uint8_t dig_pri; /*!<Digital controller priority. Range: 0 ~ 2. */ 202 uint8_t pwdet_pri; /*!<Wi-Fi controller priority. Range: 0 ~ 2. */ 203 } adc_arbiter_t; 204 205 /** 206 * @brief ADC arbiter default configuration. 207 * 208 * @note ESP32S2: Only ADC2 supports (needs) an arbiter. 209 */ 210 #define ADC_ARBITER_CONFIG_DEFAULT() { \ 211 .mode = ADC_ARB_MODE_FIX, \ 212 .rtc_pri = 1, \ 213 .dig_pri = 0, \ 214 .pwdet_pri = 2, \ 215 } 216 #endif //#if SOC_ADC_ARBITER_SUPPORTED 217 218 #if SOC_ADC_FILTER_SUPPORTED 219 /*--------------------------------------------------------------- 220 Filter 221 ---------------------------------------------------------------*/ 222 /** 223 * @brief ADC digital controller (DMA mode) filter index options. 224 * 225 * @note For ESP32-S2, The filter object of the ADC is fixed. 226 */ 227 typedef enum { 228 ADC_DIGI_FILTER_IDX0 = 0, /*!<The filter index 0. 229 For ESP32-S2, It can only be used to filter all enabled channels of ADC1 unit at the same time. */ 230 ADC_DIGI_FILTER_IDX1, /*!<The filter index 1. 231 For ESP32-S2, It can only be used to filter all enabled channels of ADC2 unit at the same time. */ 232 ADC_DIGI_FILTER_IDX_MAX 233 } adc_digi_filter_idx_t; 234 235 /** 236 * @brief ADC digital controller (DMA mode) filter type options. 237 * Expression: filter_data = (k-1)/k * last_data + new_data / k. 238 */ 239 typedef enum { 240 #if CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32H2 241 ADC_DIGI_FILTER_DIS = -1, /*!< Disable filter */ 242 #endif 243 ADC_DIGI_FILTER_IIR_2 = 0, /*!<The filter mode is first-order IIR filter. The coefficient is 2. */ 244 ADC_DIGI_FILTER_IIR_4, /*!<The filter mode is first-order IIR filter. The coefficient is 4. */ 245 ADC_DIGI_FILTER_IIR_8, /*!<The filter mode is first-order IIR filter. The coefficient is 8. */ 246 ADC_DIGI_FILTER_IIR_16, /*!<The filter mode is first-order IIR filter. The coefficient is 16. */ 247 ADC_DIGI_FILTER_IIR_64, /*!<The filter mode is first-order IIR filter. The coefficient is 64. */ 248 ADC_DIGI_FILTER_IIR_MAX 249 } adc_digi_filter_mode_t; 250 251 /** 252 * @brief ADC digital controller (DMA mode) filter configuration. 253 * 254 * @note For ESP32-S2, The filter object of the ADC is fixed. 255 * @note For ESP32-S2, The filter object is always all enabled channels. 256 */ 257 typedef struct { 258 adc_unit_t adc_unit; /*!<Set adc unit number for filter. 259 For ESP32-S2, Filter IDX0/IDX1 can only be used to filter all enabled channels of ADC1/ADC2 unit at the same time. */ 260 adc_channel_t channel; /*!<Set adc channel number for filter. 261 For ESP32-S2, it's always `ADC_CHANNEL_MAX` */ 262 adc_digi_filter_mode_t mode;/*!<Set adc filter mode for filter. See ``adc_digi_filter_mode_t``. */ 263 } adc_digi_filter_t; 264 #endif // #if SOC_ADC_FILTER_SUPPORTED 265 266 #if SOC_ADC_MONITOR_SUPPORTED 267 /*--------------------------------------------------------------- 268 Monitor 269 ---------------------------------------------------------------*/ 270 /** 271 * @brief ADC digital controller (DMA mode) monitor index options. 272 * 273 * @note For ESP32-S2, The monitor object of the ADC is fixed. 274 */ 275 typedef enum { 276 ADC_DIGI_MONITOR_IDX0 = 0, /*!<The monitor index 0. 277 For ESP32-S2, It can only be used to monitor all enabled channels of ADC1 unit at the same time. */ 278 ADC_DIGI_MONITOR_IDX1, /*!<The monitor index 1. 279 For ESP32-S2, It can only be used to monitor all enabled channels of ADC2 unit at the same time. */ 280 ADC_DIGI_MONITOR_IDX_MAX 281 } adc_digi_monitor_idx_t; 282 283 /** 284 * @brief Set monitor mode of adc digital controller. 285 * MONITOR_HIGH:If ADC_OUT > threshold, Generates monitor interrupt. 286 * MONITOR_LOW: If ADC_OUT < threshold, Generates monitor interrupt. 287 */ 288 typedef enum { 289 #if CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32H2 290 ADC_DIGI_MONITOR_DIS = 0, /*!<Disable monitor. */ 291 ADC_DIGI_MONITOR_EN, /*!<If ADC_OUT < threshold, Generates monitor interrupt. */ 292 /*!<If ADC_OUT > threshold, Generates monitor interrupt. */ 293 #else 294 ADC_DIGI_MONITOR_HIGH = 0, /*!<If ADC_OUT > threshold, Generates monitor interrupt. */ 295 ADC_DIGI_MONITOR_LOW, /*!<If ADC_OUT < threshold, Generates monitor interrupt. */ 296 #endif 297 ADC_DIGI_MONITOR_MAX 298 } adc_digi_monitor_mode_t; 299 300 /** 301 * @brief ADC digital controller (DMA mode) monitor configuration. 302 * 303 * @note For ESP32-S2, The monitor object of the ADC is fixed. 304 * @note For ESP32-S2, The monitor object is always all enabled channels. 305 */ 306 typedef struct { 307 adc_unit_t adc_unit; /*!<Set adc unit number for monitor. 308 For ESP32-S2, monitor IDX0/IDX1 can only be used to monitor all enabled channels of ADC1/ADC2 unit at the same time. */ 309 adc_channel_t channel; /*!<Set adc channel number for monitor. 310 For ESP32-S2, it's always `ADC_CHANNEL_MAX` */ 311 adc_digi_monitor_mode_t mode; /*!<Set adc monitor mode. See ``adc_digi_monitor_mode_t``. */ 312 #if CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32H2 313 uint32_t h_threshold; /*!<Set monitor threshold of adc digital controller. */ 314 uint32_t l_threshold; /*!<Set monitor threshold of adc digital controller. */ 315 #else 316 uint32_t threshold; /*!<Set monitor threshold of adc digital controller. */ 317 #endif 318 } adc_digi_monitor_t; 319 #endif //#if SOC_ADC_MONITOR_SUPPORTED 320 321 /*--------------------------------------------------------------- 322 To Be Deprecated TODO: IDF-3610 323 ---------------------------------------------------------------*/ 324 #ifdef CONFIG_IDF_TARGET_ESP32 325 /** 326 * @brief ESP32 ADC DMA source selection. 327 */ 328 #else 329 /** 330 * @brief ESP32 ADC DMA source selection. 331 * 332 * @deprecated Not applicable on ESP32-S2 because ESP32-S2 doesn't use I2S DMA. 333 */ 334 #endif 335 typedef enum { 336 ADC_I2S_DATA_SRC_IO_SIG = 0, /*!< I2S data from GPIO matrix signal */ 337 ADC_I2S_DATA_SRC_ADC = 1, /*!< I2S data from ADC */ 338 ADC_I2S_DATA_SRC_MAX, 339 } adc_i2s_source_t; 340 341 #if CONFIG_IDF_TARGET_ESP32S2 342 /** 343 * @brief ADC digital controller (DMA mode) clock system setting. 344 * Calculation formula: controller_clk = (`APLL` or `APB`) / (div_num + div_a / div_b + 1). 345 * 346 * @note: The clocks of the DAC digital controller use the ADC digital controller clock divider. 347 */ 348 typedef struct { 349 bool use_apll; /*!<true: use APLL clock; false: use APB clock. */ 350 uint32_t div_num; /*!<Division factor. Range: 0 ~ 255. 351 Note: When a higher frequency clock is used (the division factor is less than 9), 352 the ADC reading value will be slightly offset. */ 353 uint32_t div_b; /*!<Division factor. Range: 1 ~ 63. */ 354 uint32_t div_a; /*!<Division factor. Range: 0 ~ 63. */ 355 } adc_digi_clk_t; 356 #endif 357
