1 /*
2  * SPDX-FileCopyrightText: 2020-2023 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 "soc/clk_tree_defs.h"
13 #include "esp_attr.h"
14 
15 /**
16  * @brief ADC unit
17  */
18 typedef enum {
19     ADC_UNIT_1,        ///< SAR ADC 1
20     ADC_UNIT_2,        ///< SAR ADC 2
21 } adc_unit_t;
22 
23 /**
24  * @brief ADC channels
25  */
26 typedef enum {
27     ADC_CHANNEL_0,     ///< ADC channel
28     ADC_CHANNEL_1,     ///< ADC channel
29     ADC_CHANNEL_2,     ///< ADC channel
30     ADC_CHANNEL_3,     ///< ADC channel
31     ADC_CHANNEL_4,     ///< ADC channel
32     ADC_CHANNEL_5,     ///< ADC channel
33     ADC_CHANNEL_6,     ///< ADC channel
34     ADC_CHANNEL_7,     ///< ADC channel
35     ADC_CHANNEL_8,     ///< ADC channel
36     ADC_CHANNEL_9,     ///< ADC channel
37 } adc_channel_t;
38 
39 /**
40  * @brief ADC attenuation parameter. Different parameters determine the range of the ADC.
41  */
42 typedef enum {
43     ADC_ATTEN_DB_0   = 0,  ///<No input attenuation, ADC can measure up to approx.
44     ADC_ATTEN_DB_2_5 = 1,  ///<The input voltage of ADC will be attenuated extending the range of measurement by about 2.5 dB
45     ADC_ATTEN_DB_6   = 2,  ///<The input voltage of ADC will be attenuated extending the range of measurement by about 6 dB
46     ADC_ATTEN_DB_12  = 3,  ///<The input voltage of ADC will be attenuated extending the range of measurement by about 12 dB
47     ADC_ATTEN_DB_11 __attribute__((deprecated)) = ADC_ATTEN_DB_12,  ///<This is deprecated, it behaves the same as `ADC_ATTEN_DB_12`
48 } adc_atten_t;
49 
50 typedef enum {
51     ADC_BITWIDTH_DEFAULT = 0, ///< Default ADC output bits, max supported width will be selected
52     ADC_BITWIDTH_9  = 9,      ///< ADC output width is 9Bit
53     ADC_BITWIDTH_10 = 10,     ///< ADC output width is 10Bit
54     ADC_BITWIDTH_11 = 11,     ///< ADC output width is 11Bit
55     ADC_BITWIDTH_12 = 12,     ///< ADC output width is 12Bit
56     ADC_BITWIDTH_13 = 13,     ///< ADC output width is 13Bit
57 } adc_bitwidth_t;
58 
59 typedef enum {
60     ADC_ULP_MODE_DISABLE = 0, ///< ADC ULP mode is disabled
61     ADC_ULP_MODE_FSM     = 1, ///< ADC is controlled by ULP FSM
62     ADC_ULP_MODE_RISCV   = 2, ///< ADC is controlled by ULP RISCV
63 } adc_ulp_mode_t;
64 
65 /**
66  * @brief ADC digital controller (DMA mode) work mode.
67  */
68 typedef enum {
69     ADC_CONV_SINGLE_UNIT_1 = 1,  ///< Only use ADC1 for conversion
70     ADC_CONV_SINGLE_UNIT_2 = 2,  ///< Only use ADC2 for conversion
71     ADC_CONV_BOTH_UNIT     = 3,  ///< Use Both ADC1 and ADC2 for conversion simultaneously
72     ADC_CONV_ALTER_UNIT    = 7,  ///< Use both ADC1 and ADC2 for conversion by turn. e.g. ADC1 -> ADC2 -> ADC1 -> ADC2 .....
73 } adc_digi_convert_mode_t;
74 
75 /**
76  * @brief ADC digital controller (DMA mode) output data format option.
77  */
78 typedef enum {
79     ADC_DIGI_OUTPUT_FORMAT_TYPE1,   ///< See `adc_digi_output_data_t.type1`
80     ADC_DIGI_OUTPUT_FORMAT_TYPE2,   ///< See `adc_digi_output_data_t.type2`
81 } adc_digi_output_format_t;
82 
83 #if SOC_ADC_DIG_CTRL_SUPPORTED && !SOC_ADC_RTC_CTRL_SUPPORTED
84 typedef soc_periph_adc_digi_clk_src_t    adc_oneshot_clk_src_t;     ///< Clock source type of oneshot mode which uses digital controller
85 typedef soc_periph_adc_digi_clk_src_t    adc_continuous_clk_src_t;  ///< Clock source type of continuous mode which uses digital controller
86 #elif SOC_ADC_RTC_CTRL_SUPPORTED
87 typedef soc_periph_adc_rtc_clk_src_t     adc_oneshot_clk_src_t;     ///< Clock source type of oneshot mode which uses RTC controller
88 typedef soc_periph_adc_digi_clk_src_t    adc_continuous_clk_src_t;  ///< Clock source type of continuous mode which uses digital controller
89 #endif
90 
91 /**
92  * @brief ADC digital controller pattern configuration
93  */
94 typedef struct {
95     uint8_t atten;      ///< Attenuation of this ADC channel
96     uint8_t channel;    ///< ADC channel
97     uint8_t unit;       ///< ADC unit
98     uint8_t bit_width;  ///< ADC output bit width
99 } adc_digi_pattern_config_t;
100 
101 /**
102  * @brief ADC IIR Filter ID
103  */
104 typedef enum {
105     ADC_DIGI_IIR_FILTER_0,  ///< Filter 0
106     ADC_DIGI_IIR_FILTER_1,  ///< Filter 1
107 } adc_digi_iir_filter_t;
108 
109 /**
110  * @brief IIR Filter Coefficient
111  */
112 typedef enum {
113     ADC_DIGI_IIR_FILTER_COEFF_2,     ///< The filter coefficient is 2
114     ADC_DIGI_IIR_FILTER_COEFF_4,     ///< The filter coefficient is 4
115     ADC_DIGI_IIR_FILTER_COEFF_8,     ///< The filter coefficient is 8
116     ADC_DIGI_IIR_FILTER_COEFF_16,    ///< The filter coefficient is 16
117     ADC_DIGI_IIR_FILTER_COEFF_64,    ///< The filter coefficient is 64
118 } adc_digi_iir_filter_coeff_t;
119 
120 /*---------------------------------------------------------------
121                     Output Format
122 ---------------------------------------------------------------*/
123 #if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2
124 /**
125  * @brief ADC digital controller (DMA mode) output data format.
126  *        Used to analyze the acquired ADC (DMA) data.
127  * @note  ESP32: Only `type1` is valid. ADC2 does not support DMA mode.
128  * @note  ESP32-S2: Member `channel` can be used to judge the validity of the ADC data,
129  *                  because the role of the arbiter may get invalid ADC data.
130  */
131 typedef struct {
132     union {
133         struct {
134             uint16_t data:     12;  /*!<ADC real output data info. Resolution: 12 bit. */
135             uint16_t channel:   4;  /*!<ADC channel index info. */
136         } type1;                    /*!<ADC type1 */
137         struct {
138             uint16_t data:     11;  /*!<ADC real output data info. Resolution: 11 bit. */
139             uint16_t channel:   4;  /*!<ADC channel index info. For ESP32-S2:
140                                         If (channel < ADC_CHANNEL_MAX), The data is valid.
141                                         If (channel > ADC_CHANNEL_MAX), The data is invalid. */
142             uint16_t unit:      1;  /*!<ADC unit index info. 0: ADC1; 1: ADC2.  */
143         } type2;                    /*!<When the configured output format is 11bit.*/
144         uint16_t val;               /*!<Raw data value */
145     };
146 } adc_digi_output_data_t;
147 
148 #elif CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32C2
149 /**
150  * @brief ADC digital controller (DMA mode) output data format.
151  *        Used to analyze the acquired ADC (DMA) data.
152  */
153 typedef struct {
154     union {
155         struct {
156             uint32_t data:          12; /*!<ADC real output data info. Resolution: 12 bit. */
157             uint32_t reserved12:    1;  /*!<Reserved12. */
158             uint32_t channel:       3;  /*!<ADC channel index info.
159                                             If (channel < ADC_CHANNEL_MAX), The data is valid.
160                                             If (channel > ADC_CHANNEL_MAX), The data is invalid. */
161             uint32_t unit:          1;  /*!<ADC unit index info. 0: ADC1; 1: ADC2.  */
162             uint32_t reserved17_31: 15; /*!<Reserved17. */
163         } type2;                        /*!<When the configured output format is 12bit. */
164         uint32_t val;                   /*!<Raw data value */
165     };
166 } adc_digi_output_data_t;
167 
168 #elif CONFIG_IDF_TARGET_ESP32S3
169 /**
170  * @brief ADC digital controller (DMA mode) output data format.
171  *        Used to analyze the acquired ADC (DMA) data.
172  */
173 typedef struct {
174     union {
175         struct {
176             uint32_t data:          12; /*!<ADC real output data info. Resolution: 12 bit. */
177             uint32_t reserved12:    1;  /*!<Reserved12. */
178             uint32_t channel:       4;  /*!<ADC channel index info.
179                                             If (channel < ADC_CHANNEL_MAX), The data is valid.
180                                             If (channel > ADC_CHANNEL_MAX), The data is invalid. */
181             uint32_t unit:          1;  /*!<ADC unit index info. 0: ADC1; 1: ADC2.  */
182             uint32_t reserved17_31: 14; /*!<Reserved17. */
183         } type2;                        /*!<When the configured output format is 12bit. */
184         uint32_t val;                   /*!<Raw data value */
185     };
186 } adc_digi_output_data_t;
187 
188 #elif CONFIG_IDF_TARGET_ESP32C6 || CONFIG_IDF_TARGET_ESP32H2
189 /**
190  * @brief ADC digital controller (DMA mode) output data format.
191  *        Used to analyze the acquired ADC (DMA) data.
192  */
193 typedef struct {
194     union {
195         struct {
196             uint32_t data:          12; /*!<ADC real output data info. Resolution: 12 bit. */
197             uint32_t reserved12:    1;  /*!<Reserved12. */
198             uint32_t channel:       4;  /*!<ADC channel index info.
199                                             If (channel < ADC_CHANNEL_MAX), The data is valid.
200                                             If (channel > ADC_CHANNEL_MAX), The data is invalid. */
201             uint32_t reserved17_31: 15; /*!<Reserved 17-31. */
202         } type2;                        /*!<When the configured output format is 12bit. */
203         uint32_t val;                   /*!<Raw data value */
204     };
205 } adc_digi_output_data_t;
206 
207 #endif
208 
209 #if CONFIG_IDF_TARGET_ESP32S2
210 /**
211  * @brief ADC digital controller (DMA mode) clock system setting.
212  *        Calculation formula: controller_clk = (`APLL` or `APB`) / (div_num + div_a / div_b + 1).
213  *
214  * @note: The clocks of the DAC digital controller use the ADC digital controller clock divider.
215  */
216 typedef struct {
217     bool use_apll;      /*!<true: use APLL clock; false: use APB clock. */
218     uint32_t div_num;   /*!<Division factor. Range: 0 ~ 255.
219                             Note: When a higher frequency clock is used (the division factor is less than 9),
220                             the ADC reading value will be slightly offset. */
221     uint32_t div_b;     /*!<Division factor. Range: 1 ~ 63. */
222     uint32_t div_a;     /*!<Division factor. Range: 0 ~ 63. */
223 } adc_digi_clk_t;
224 #endif
225