doc/adc: modifications in the adc documentation and adc headers

components/driver/include/driver/adc_common.h

@@ -76,7 +76,7 @@ typedef enum {
 /**
  * @brief ADC digital controller encode option.
  *
- * @deprecated The ESP32S2 don't use I2S DMA. Call ``adc_digi_output_format_t`` instead.
+ * @deprecated The ESP32-S2 doesn't use I2S DMA. Call ``adc_digi_output_format_t`` instead.
  */
 typedef enum {
     ADC_ENCODE_12BIT,        /*!< ADC to DMA data format,          , [15:12]-channel [11:0]-12 bits ADC data */
@@ -126,45 +126,58 @@ esp_err_t adc_gpio_init(adc_unit_t adc_unit, adc_channel_t channel);
 esp_err_t adc1_pad_get_io_num(adc1_channel_t channel, gpio_num_t *gpio_num);
 
 /**
- * @brief Set the attenuation of a particular channel on ADC1, and configure its associated GPIO pin mux.
- *
- *        The default ADC full-scale voltage is 1.1 V. To read higher voltages (up to the pin maximum voltage,
- *        usually 3.3 V) requires setting >0 dB signal attenuation for that ADC channel.
- *
- *        When VDD_A is 3.3 V:
- *
- *        - 0 dB attenuation (ADC_ATTEN_DB_0) gives full-scale voltage 1.1 V
- *        - 2.5 dB attenuation (ADC_ATTEN_DB_2_5) gives full-scale voltage 1.5 V
- *        - 6 dB attenuation (ADC_ATTEN_DB_6) gives full-scale voltage 2.2 V
- *        - 11 dB attenuation (ADC_ATTEN_DB_11) gives full-scale voltage 3.9 V (see note below)
- *
- * @note The full-scale voltage is the voltage corresponding to a maximum reading (depending on ADC1 configured bit width,
- *       this value in ESP32 is: 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits.
- *       this value in ESP32S2 is: 8191 for 13-bits.)
- *
- * @note At 11 dB attenuation the maximum voltage is limited by VDD_A, not the full scale voltage.
- *
- * @note For ESP32:
- *       Due to ADC characteristics, most accurate results are obtained within the following approximate voltage ranges:
- *
- *       - 0 dB attenuation (ADC_ATTEN_DB_0) between 100 and 950 mV
- *       - 2.5 dB attenuation (ADC_ATTEN_DB_2_5) between 100 and 1250 mV
- *       - 6 dB attenuation (ADC_ATTEN_DB_6) between 150 to 1750 mV
- *       - 11 dB attenuation (ADC_ATTEN_DB_11) between 150 to 2450 mV
- *
- *       For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges.
- *
- * @note For any given channel, this function must be called before the first time ``adc1_get_raw()`` is called for that channel.
- *
- * @note This function can be called multiple times to configure multiple
- *       ADC channels simultaneously. ``adc1_get_raw()`` can then be called for any configured channel.
- *
- * @param channel ADC1 channel to configure
- * @param atten  Attenuation level
- *
- * @return
- *     - ESP_OK success
- *     - ESP_ERR_INVALID_ARG Parameter error
+  * @brief Set the attenuation of a particular channel on ADC1, and configure its associated GPIO pin mux.
+  *
+  *        The default ADC full-scale voltage is 1.1 V. To read higher voltages (up to the pin maximum voltage,
+  *        usually 3.3 V) requires setting >0 dB signal attenuation for that ADC channel.
+  *
+  *        When the analog voltage supply (VDDA) is 3.3 V:
+  *
+  *        - 0 dB attenuation (ADC_ATTEN_DB_0) gives full-scale voltage 1.1 V
+  *        - 2.5 dB attenuation (ADC_ATTEN_DB_2_5) gives full-scale voltage 1.5 V
+  *        - 6 dB attenuation (ADC_ATTEN_DB_6) gives full-scale voltage 2.2 V
+  *        - 11 dB attenuation (ADC_ATTEN_DB_11) gives full-scale voltage 3.9 V (see note below)
+  * 
+  * Due to ADC characteristics, most accurate results are obtained within the following approximate voltage ranges:
+  *
+  *         +----------+------------+--------------------------+
+  *         |   SoC    | attenuation|   suggested range (mV)   |
+  *         +==========+============+==========================+
+  *         |          |  0         |     100 ~ 950            |
+  *         |          +------------+--------------------------+
+  *         |          |  2.5       |     100 ~ 1250           |
+  *         |   ESP32  +------------+--------------------------+
+  *         |          |  6         |     150 ~ 1750           |
+  *         |          +------------+--------------------------+
+  *         |          |  11        |     150 ~ 2450           |
+  *         +----------+------------+--------------------------+
+  *         |          |  0         |     100 ~ 800            |
+  *         |          +------------+--------------------------+
+  *         |          |  2.5       |     100 ~ 1100           |
+  *         | ESP32-S2 +------------+--------------------------+
+  *         |          |  6         |     150 ~ 1350           |
+  *         |          +------------+--------------------------+
+  *         |          |  11        |     150 ~ 2600           |
+  *         +----------+------------+--------------------------+
+  * 
+  * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges.
+  * @note The full-scale voltage is the voltage corresponding to a maximum reading (depending on ADC1 configured bit width,
+  *       this value in ESP32 is 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits.
+  *       this value in ESP32-S2 is 8191 for 13-bits.)
+  *
+  * @note At 11 dB attenuation the maximum voltage is limited by VDDA, not the full scale voltage.
+  *
+  * @note For any given channel, this function must be called before the first time ``adc1_get_raw()`` is called for that channel.
+  *
+  * @note This function can be called multiple times to configure multiple
+  *       ADC channels simultaneously. You may call ``adc1_get_raw()`` only after configuring a channel.
+  *
+  * @param channel ADC1 channel to configure
+  * @param atten  Attenuation level
+  *
+  * @return
+  *     - ESP_OK success
+  *     - ESP_ERR_INVALID_ARG Parameter error
  */
 esp_err_t adc1_config_channel_atten(adc1_channel_t channel, adc_atten_t atten);
 
@@ -223,10 +236,10 @@ esp_err_t adc_set_clk_div(uint8_t clk_div);
 /**
  * @brief Configure ADC capture width.
  *
- * @note  For ESP32S2, only support ``ADC_WIDTH_BIT_13``.
+ * @note  ESP32-S2 only supports ``ADC_WIDTH_BIT_13``.
  *
  * @param adc_unit ADC unit index
- * @param width_bit Bit capture width for ADC unit. For ESP32S2, only support ``ADC_WIDTH_BIT_13``.
+ * @param width_bit Bit capture width for ADC unit. ESP32-S2 only supports ``ADC_WIDTH_BIT_13``.
  *
  * @return
  *     - ESP_OK success
@@ -264,7 +277,7 @@ esp_err_t adc2_pad_get_io_num(adc2_channel_t channel, gpio_num_t *gpio_num);
  *        The default ADC full-scale voltage is 1.1 V. To read higher voltages (up to the pin maximum voltage,
  *        usually 3.3 V) requires setting >0 dB signal attenuation for that ADC channel.
  *
- *        When VDD_A is 3.3 V:
+ *        When the analog voltage supply (VDDA) is 3.3 V:
  *
  *        - 0 dB attenuation (ADC_ATTEN_0db) gives full-scale voltage 1.1 V
  *        - 2.5 dB attenuation (ADC_ATTEN_2_5db) gives full-scale voltage 1.5 V
@@ -277,10 +290,10 @@ esp_err_t adc2_pad_get_io_num(adc2_channel_t channel, gpio_num_t *gpio_num);
  *
  * @note The full-scale voltage is the voltage corresponding to a maximum reading
  *       (depending on ADC2 configured bit width,
- *       this value of ESP32 is: 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits.
- *       this value of ESP32S2 is: 8191 for 13-bits.)
+ *       this value for ESP32 is: 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits.
+ *       this value for ESP32-S2 is: 8191 for 13-bits.)
  *
- * @note At 11 dB attenuation the maximum voltage is limited by VDD_A, not the full scale voltage.
+ * @note At 11 dB attenuation the maximum voltage is limited by VDDA, not the full scale voltage.
  *
  * @param channel ADC2 channel to configure
  * @param atten  Attenuation level
@@ -305,12 +318,12 @@ esp_err_t adc2_config_channel_atten(adc2_channel_t channel, adc_atten_t atten);
  *       must be called before the first time this function is called. If Wi-Fi is started via ``esp_wifi_start()``, this
  *       function will always fail with ``ESP_ERR_TIMEOUT``.
  *
- * @note ESP32S2:
+ * @note ESP32-S2:
  *       ADC2 support hardware arbiter. The arbiter is to improve the use efficiency of ADC2. After the control right is robbed by the high priority,
  *       the low priority controller will read the invalid ADC2 data. Default priority: Wi-Fi > RTC > Digital;
  *
  * @param channel ADC2 channel to read
- * @param width_bit Bit capture width for ADC2. For ESP32S2, only support ``ADC_WIDTH_BIT_13``.
+ * @param width_bit Bit capture width for ADC2. ESP32-S2 only supports ``ADC_WIDTH_BIT_13``.
  * @param raw_out the variable to hold the output data.
  *
  * @return

components/soc/include/hal/adc_types.h

@@ -5,9 +5,9 @@
 #include <stdbool.h>
 
 /**
- * @brief ADC units selected handle.
+ * @brief ADC unit enumeration.
  *
- * @note  For ADC digital controller(DMA mode), ESP32 don't support `ADC_UNIT_2`, `ADC_UNIT_BOTH`, `ADC_UNIT_ALTER`.
+ * @note  For ADC digital controller (DMA mode), ESP32 doesn't support `ADC_UNIT_2`, `ADC_UNIT_BOTH`, `ADC_UNIT_ALTER`.
  */
 typedef enum {
     ADC_UNIT_1 = 1,          /*!< SAR ADC 1. */
@@ -20,7 +20,7 @@ typedef enum {
 /**
  * @brief ADC channels handle. See ``adc1_channel_t``, ``adc2_channel_t``.
  *
- * @note  For ESP32 ADC1, don't support `ADC_CHANNEL_8`, `ADC_CHANNEL_9`. See ``adc1_channel_t``.
+ * @note  For ESP32 ADC1, don't use `ADC_CHANNEL_8`, `ADC_CHANNEL_9`. See ``adc1_channel_t``.
  */
 typedef enum {
     ADC_CHANNEL_0 = 0, /*!< ADC channel */
@@ -40,18 +40,24 @@ typedef enum {
  * @brief ADC attenuation parameter. Different parameters determine the range of the ADC. See ``adc1_config_channel_atten``.
  */
 typedef enum {
-    ADC_ATTEN_DB_0   = 0,  /*!<The input voltage of ADC will be reduced to about 1/1 */
-    ADC_ATTEN_DB_2_5 = 1,  /*!<The input voltage of ADC will be reduced to about 1/1.34 */
-    ADC_ATTEN_DB_6   = 2,  /*!<The input voltage of ADC will be reduced to about 1/2 */
-    ADC_ATTEN_DB_11  = 3,  /*!<The input voltage of ADC will be reduced to about 1/3.6*/
+    ADC_ATTEN_DB_0   = 0,  /*!<No input attenumation, ADC can measure up to approx. 800 mV. */
+    ADC_ATTEN_DB_2_5 = 1,  /*!<The input voltage of ADC will be attenuated, extending the range of measurement to up to approx. 1100 mV. */
+    ADC_ATTEN_DB_6   = 2,  /*!<The input voltage of ADC will be attenuated, extending the range of measurement to up to  approx. 1350 mV. */
+    ADC_ATTEN_DB_11  = 3,  /*!<The input voltage of ADC will be attenuated, extending the range of measurement to up to  approx. 2600 mV. */
     ADC_ATTEN_MAX,
 } adc_atten_t;
 
+#ifdef CONFIG_IDF_TARGET_ESP32
+/**
+ * @brief ESP32 ADC DMA source selection.
+ */
+#else
 /**
  * @brief ESP32 ADC DMA source selection.
  *
- * @note  It's be deprecated in ESP32S2. Beacause ESP32S2 don't use I2S DMA.
+ * @deprecated  Not applicable on ESP32-S2 because ESP32-S2 doesn't use I2S DMA.
  */
+#endif
 typedef enum {
     ADC_I2S_DATA_SRC_IO_SIG = 0, /*!< I2S data from GPIO matrix signal  */
     ADC_I2S_DATA_SRC_ADC = 1,    /*!< I2S data from ADC */
@@ -61,16 +67,16 @@ typedef enum {
 /**
  * @brief ADC resolution setting option.
  *
- * @note  For ESP32S2. Only support 13 bit resolution.
- *        For ESP32.   Don't support 13 bit resolution.
+ * @note  For ESP32-S2. Only 13 bit resolution is supported.
+ *        For ESP32.   13 bit resolution is not supported.
  */
 typedef enum {
     ADC_WIDTH_BIT_9  = 0, /*!< ADC capture width is 9Bit. Only ESP32 is supported. */
     ADC_WIDTH_BIT_10 = 1, /*!< ADC capture width is 10Bit. Only ESP32 is supported. */
     ADC_WIDTH_BIT_11 = 2, /*!< ADC capture width is 11Bit. Only ESP32 is supported. */
     ADC_WIDTH_BIT_12 = 3, /*!< ADC capture width is 12Bit. Only ESP32 is supported. */
-#ifdef CONFIG_IDF_TARGET_ESP32S2
-    ADC_WIDTH_BIT_13 = 4, /*!< ADC capture width is 13Bit. Only ESP32S2 is supported. */
+#if !CONFIG_IDF_TARGET_ESP32
+    ADC_WIDTH_BIT_13 = 4, /*!< ADC capture width is 13Bit. Only ESP32-S2 is supported. */
 #endif
     ADC_WIDTH_MAX,
 } adc_bits_width_t;
@@ -98,11 +104,11 @@ typedef enum {
 typedef struct {
     union {
         struct {
-            uint8_t atten:     2;   /*!< ADC sampling voltage attenuation configuration.
-                                         0: input voltage * 1;
-                                         1: input voltage * 1/1.34;
-                                         2: input voltage * 1/2;
-                                         3: input voltage * 1/3.6. */
+            uint8_t atten:     2;   /*!< ADC sampling voltage attenuation configuration. Modification of attenuation affects the range of measurements.
+                                         0: measurement range 0 - 800mV,
+                                         1: measurement range 0 - 1100mV,
+                                         2: measurement range 0 - 1350mV,
+                                         3: measurement range 0 - 2600mV. */
 #ifdef CONFIG_IDF_TARGET_ESP32
             uint8_t bit_width: 2;   /*!< ADC resolution.
 -                                         0: 9 bit;
@@ -123,9 +129,9 @@ typedef struct {
  */
 typedef enum {
     ADC_DIGI_FORMAT_12BIT,   /*!<ADC to DMA data format,                [15:12]-channel, [11: 0]-12 bits ADC data (`adc_digi_output_data_t`).
-                                 Note: In single convert mode. */
+                                 Note: For single convert mode. */
     ADC_DIGI_FORMAT_11BIT,   /*!<ADC to DMA data format, [15]-adc unit, [14:11]-channel, [10: 0]-11 bits ADC data (`adc_digi_output_data_t`).
-                                 Note: In multi or alter convert mode. */
+                                 Note: For multi or alter convert mode. */
     ADC_DIGI_FORMAT_MAX,
 } adc_digi_output_format_t;
 
@@ -133,20 +139,20 @@ typedef enum {
  * @brief ADC digital controller (DMA mode) output data format.
  *        Used to analyze the acquired ADC (DMA) data.
  *
- * @note  ESP32S2:
+ * @note  ESP32-S2:
  *        Member `channel` can be used to judge the validity of the ADC data, because the role of the arbiter may get invalid ADC data.
  */
 typedef struct {
     union {
         struct {
             uint16_t data:     12;  /*!<ADC real output data info. Resolution: 12 bit. */
-            uint16_t channel:   4;  /*!<ADC channel index info. For ESP32S2:
+            uint16_t channel:   4;  /*!<ADC channel index info. For ESP32-S2:
                                         If (channel < ADC_CHANNEL_MAX), The data is valid.
                                         If (channel > ADC_CHANNEL_MAX), The data is invalid. */
         } type1;                    /*!<When the configured output format is 12bit. `ADC_DIGI_FORMAT_12BIT` */
         struct {
             uint16_t data:     11;  /*!<ADC real output data info. Resolution: 11 bit. */
-            uint16_t channel:   4;  /*!<ADC channel index info. For ESP32S2:
+            uint16_t channel:   4;  /*!<ADC channel index info. For ESP32-S2:
                                         If (channel < ADC_CHANNEL_MAX), The data is valid.
                                         If (channel > ADC_CHANNEL_MAX), The data is invalid. */
             uint16_t unit:      1;  /*!<ADC unit index info. 0: ADC1; 1: ADC2.  */
@@ -159,7 +165,7 @@ typedef struct {
 
 /**
  * @brief ADC digital controller (DMA mode) clock system setting.
- *        Expression: controller_clk = (`APLL` or `APB`) / (div_num + div_a / div_b + 1).
+ *        Calculation formula: controller_clk = (`APLL` or `APB`) / (div_num + div_a / div_b + 1).
  *
  * @note: The clocks of the DAC digital controller use the ADC digital controller clock divider.
  */
@@ -172,37 +178,39 @@ typedef struct {
     uint32_t div_a;     /*!<Division factor. Range: 0 ~ 63. */
 } adc_digi_clk_t;
 
-#endif //CONFIG_IDF_TARGET_ESP32S2
+#endif //!CONFIG_IDF_TARGET_ESP32
 
 /**
- * @brief ADC digital controller (DMA mode) configuration parameters.
- *
- * ESP32S2: Example setting: Use ADC1 channel0 to measure voltage, the sampling rate is required to be 1KHz:
- *     +---------------------+--------+--------+--------+
- *     | sample rate         |  1KHz  |  1KHz  |  1KHz  |
- *     +---------------------+--------+--------+--------+
- *     | conv_mode           | single |  both  |  alter |
- *     | adc1_pattern_len    |    1   |    1   |    1   |
- *     | dig_clk.use_apll    |    0   |    0   |    0   |
- *     | dig_clk.div_num     |   99   |   99   |   99   |
- *     | dig_clk.div_b       |    0   |    0   |    0   |
- *     | dig_clk.div_a       |    0   |    0   |    0   |
- *     | interval            |  400   |  400   |  200   |
- *     +---------------------+--------+--------+--------+
- *     | `trigger_meas_freq` |  1KHz  |  1KHz  |  2KHz  |
- *     +---------------------+--------+--------+--------+
- *
- * ESP32S2: Explain the relationship between `conv_limit_num`, `dma_eof_num` and the number of DMA output:
- *     +---------------------+--------+--------+--------+
- *     | conv_mode           | single |  both  |  alter |
- *     +---------------------+--------+--------+--------+
- *     | trigger meas times  |    1   |    1   |    1   |
- *     +---------------------+--------+--------+--------+
- *     | conv_limit_num      |   +1   |   +1   |   +1   |
- *     | dma_eof_num         |   +1   |   +2   |   +1   |
- *     | dma output (byte)   |   +2   |   +4   |   +2   |
- *     +---------------------+--------+--------+--------+
- */
+  * @brief ADC digital controller (DMA mode) configuration parameters.
+  *
+  * Example setting: When using ADC1 channel0 to measure voltage, the sampling rate is required to be 1 kHz:
+  *
+  *     +---------------------+--------+--------+--------+
+  *     | sample rate         | 1 kHz  | 1 kHz  | 1 kHz  |
+  *     +---------------------+--------+--------+--------+
+  *     | conv_mode           | single |  both  |  alter |
+  *     | adc1_pattern_len    |    1   |    1   |    1   |
+  *     | dig_clk.use_apll    |    0   |    0   |    0   |
+  *     | dig_clk.div_num     |   99   |   99   |   99   |
+  *     | dig_clk.div_b       |    0   |    0   |    0   |
+  *     | dig_clk.div_a       |    0   |    0   |    0   |
+  *     | interval            |  400   |  400   |  200   |
+  *     +---------------------+--------+--------+--------+
+  *     | `trigger_meas_freq` | 1 kHz  | 1 kHz  | 2 kHz  |
+  *     +---------------------+--------+--------+--------+
+  *
+  * Explanation of the relationship between `conv_limit_num`, `dma_eof_num` and the number of DMA outputs:
+  *
+  *     +---------------------+--------+--------+--------+
+  *     | conv_mode           | single |  both  |  alter |
+  *     +---------------------+--------+--------+--------+
+  *     | trigger meas times  |    1   |    1   |    1   |
+  *     +---------------------+--------+--------+--------+
+  *     | conv_limit_num      |   +1   |   +1   |   +1   |
+  *     | dma_eof_num         |   +1   |   +2   |   +1   |
+  *     | dma output (byte)   |   +2   |   +4   |   +2   |
+  *     +---------------------+--------+--------+--------+
+  */
 typedef struct {
     bool conv_limit_en;         /*!<Enable the function of limiting ADC conversion times.
                                     If the number of ADC conversion trigger count is equal to the `limit_num`, the conversion is stopped. */
@@ -229,12 +237,11 @@ typedef struct {
 #endif
 } adc_digi_config_t;
 
-#ifdef CONFIG_IDF_TARGET_ESP32S2
-
+#if CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
 /**
  * @brief ADC arbiter work mode option.
  *
- * @note ESP32S2: Only ADC2 support arbiter.
+ * @note ESP32-S2: Only ADC2 support arbiter.
  */
 typedef enum {
     ADC_ARB_MODE_SHIELD,/*!<Force shield arbiter, Select the highest priority controller to work. */
@@ -246,7 +253,7 @@ typedef enum {
 /**
  * @brief ADC arbiter work mode and priority setting.
  *
- * @note ESP32S2: Only ADC2 support arbiter.
+ * @note ESP32-S2: Only ADC2 support arbiter.
  */
 typedef struct {
     adc_arbiter_mode_t mode; /*!<Refer to ``adc_arbiter_mode_t``. Note: only support ADC2. */
@@ -258,7 +265,7 @@ typedef struct {
 /**
  * @brief ADC arbiter default configuration.
  *
- * @note ESP32S2: Only ADC2 support arbiter.
+ * @note ESP32S2: Only ADC2 supports (needs) an arbiter.
  */
 #define ADC_ARBITER_CONFIG_DEFAULT() { \
     .mode = ADC_ARB_MODE_FIX, \
@@ -279,13 +286,13 @@ typedef enum {
 /**
  * @brief ADC digital controller (DMA mode) filter index options.
  *
- * @note  For ESP32S2, The filter object of the ADC is fixed.
+ * @note  For ESP32-S2, The filter object of the ADC is fixed.
  */
 typedef enum {
     ADC_DIGI_FILTER_IDX0 = 0, /*!<The filter index 0.
-                                  For ESP32S2, It can only be used to filter all enabled channels of ADC1 unit at the same time. */
+                                  For ESP32-S2, It can only be used to filter all enabled channels of ADC1 unit at the same time. */
     ADC_DIGI_FILTER_IDX1,     /*!<The filter index 1.
-                                  For ESP32S2, It can only be used to filter all enabled channels of ADC2 unit at the same time. */
+                                  For ESP32-S2, It can only be used to filter all enabled channels of ADC2 unit at the same time. */
     ADC_DIGI_FILTER_IDX_MAX
 } adc_digi_filter_idx_t;
 
@@ -305,27 +312,27 @@ typedef enum {
 /**
  * @brief ADC digital controller (DMA mode) filter configuration.
  *
- * @note  For ESP32S2, The filter object of the ADC is fixed.
- * @note  For ESP32S2, The filter object is always all enabled channels.
+ * @note  For ESP32-S2, The filter object of the ADC is fixed.
+ * @note  For ESP32-S2, The filter object is always all enabled channels.
  */
 typedef struct {
     adc_unit_t adc_unit;        /*!<Set adc unit number for filter.
-                                    For ESP32S2, Filter IDX0/IDX1 can only be used to filter all enabled channels of ADC1/ADC2 unit at the same time. */
+                                    For ESP32-S2, Filter IDX0/IDX1 can only be used to filter all enabled channels of ADC1/ADC2 unit at the same time. */
     adc_channel_t channel;      /*!<Set adc channel number for filter.
-                                    For ESP32S2, it's always `ADC_CHANNEL_MAX` */
+                                    For ESP32-S2, it's always `ADC_CHANNEL_MAX` */
     adc_digi_filter_mode_t mode;/*!<Set adc filter mode for filter. See ``adc_digi_filter_mode_t``. */
 } adc_digi_filter_t;
 
 /**
  * @brief ADC digital controller (DMA mode) monitor index options.
  *
- * @note  For ESP32S2, The monitor object of the ADC is fixed.
+ * @note  For ESP32-S2, The monitor object of the ADC is fixed.
  */
 typedef enum {
     ADC_DIGI_MONITOR_IDX0 = 0, /*!<The monitor index 0.
-                                  For ESP32S2, It can only be used to monitor all enabled channels of ADC1 unit at the same time. */
+                                  For ESP32-S2, It can only be used to monitor all enabled channels of ADC1 unit at the same time. */
     ADC_DIGI_MONITOR_IDX1,     /*!<The monitor index 1.
-                                  For ESP32S2, It can only be used to monitor all enabled channels of ADC2 unit at the same time. */
+                                  For ESP32-S2, It can only be used to monitor all enabled channels of ADC2 unit at the same time. */
     ADC_DIGI_MONITOR_IDX_MAX
 } adc_digi_monitor_idx_t;
 
@@ -343,14 +350,14 @@ typedef enum {
 /**
  * @brief ADC digital controller (DMA mode) monitor configuration.
  *
- * @note  For ESP32S2, The monitor object of the ADC is fixed.
- * @note  For ESP32S2, The monitor object is always all enabled channels.
+ * @note  For ESP32-S2, The monitor object of the ADC is fixed.
+ * @note  For ESP32-S2, The monitor object is always all enabled channels.
  */
 typedef struct {
     adc_unit_t adc_unit;            /*!<Set adc unit number for monitor.
-                                        For ESP32S2, monitor IDX0/IDX1 can only be used to monitor all enabled channels of ADC1/ADC2 unit at the same time. */
+                                        For ESP32-S2, monitor IDX0/IDX1 can only be used to monitor all enabled channels of ADC1/ADC2 unit at the same time. */
     adc_channel_t channel;          /*!<Set adc channel number for monitor.
-                                        For ESP32S2, it's always `ADC_CHANNEL_MAX` */
+                                        For ESP32-S2, it's always `ADC_CHANNEL_MAX` */
     adc_digi_monitor_mode_t mode;   /*!<Set adc monitor mode. See ``adc_digi_monitor_mode_t``. */
     uint32_t threshold;             /*!<Set monitor threshold of adc digital controller. */
 } adc_digi_monitor_t;

components/soc/src/esp32/include/hal/adc_ll.h

@@ -452,36 +452,6 @@ static inline void adc_ll_set_sar_clk_div(adc_ll_num_t adc_n, uint32_t div)
 
 /**
  * Set the attenuation of a particular channel on ADCn.
- *
- * @note For any given channel, this function must be called before the first time conversion.
- *
- * The default ADC full-scale voltage is 1.1V. To read higher voltages (up to the pin maximum voltage,
- * usually 3.3V) requires setting >0dB signal attenuation for that ADC channel.
- *
- * When VDD_A is 3.3V:
- *
- * - 0dB attenuation (ADC_ATTEN_DB_0) gives full-scale voltage 1.1V
- * - 2.5dB attenuation (ADC_ATTEN_DB_2_5) gives full-scale voltage 1.5V
- * - 6dB attenuation (ADC_ATTEN_DB_6) gives full-scale voltage 2.2V
- * - 11dB attenuation (ADC_ATTEN_DB_11) gives full-scale voltage 3.9V (see note below)
- *
- * @note The full-scale voltage is the voltage corresponding to a maximum reading (depending on ADC1 configured
- * bit width, this value is: 4095 for 12-bits, 2047 for 11-bits, 1023 for 10-bits, 511 for 9 bits.)
- *
- * @note At 11dB attenuation the maximum voltage is limited by VDD_A, not the full scale voltage.
- *
- * Due to ADC characteristics, most accurate results are obtained within the following approximate voltage ranges:
- *
- * - 0dB attenuation (ADC_ATTEN_DB_0) between 100 and 950mV
- * - 2.5dB attenuation (ADC_ATTEN_DB_2_5) between 100 and 1250mV
- * - 6dB attenuation (ADC_ATTEN_DB_6) between 150 to 1750mV
- * - 11dB attenuation (ADC_ATTEN_DB_11) between 150 to 2450mV
- *
- * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges.
- *
- * @param adc_n ADC unit.
- * @param channel ADCn channel number.
- * @param atten The attenuation option.
  */
 static inline void adc_ll_set_atten(adc_ll_num_t adc_n, adc_channel_t channel, adc_atten_t atten)
 {

docs/en/api-reference/peripherals/adc.rst

@@ -10,7 +10,7 @@ Overview
 
 .. only:: esp32
 
-    The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 18 measurement channels (analog enabled pins).
+    The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs, supporting a total of 18 measurement channels (analog enabled pins).
 
     The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application:
 
@@ -22,11 +22,11 @@ Overview
 
 .. only:: esp32s2
 
-    The {IDF_TARGET_NAME} integrates two 13-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 20 measurement channels (analog enabled pins).
+    The {IDF_TARGET_NAME} integrates two 13-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs, supporting a total of 20 measurement channels (analog enabled pins).
 
     The ADC driver API supports ADC1 (10 channels, attached to GPIOs 1 - 10), and ADC2 (10 channels, attached to GPIOs 11 - 20). However, the usage of ADC2 has some restrictions for the application:
 
-    1. Different from ADC1, the hardware arbiter function is added to ADC2, so when using the API of ADC2 to obtain the sampling voltage, you need to judge whether the result is successfully arbitrated.
+    1. Different from ADC1, the hardware arbiter function is added to ADC2, so when using the API of ADC2 to obtain the sampling voltage, you need to check whether the reading is successful.
 
 Configuration and Reading ADC
 -----------------------------
@@ -73,8 +73,8 @@ Reading voltage on ADC1 channel 0 ({IDF_TARGET_ADC1_CH0})::
         adc1_config_channel_atten(ADC1_CHANNEL_0,ADC_ATTEN_DB_0);
         int val = adc1_get_raw(ADC1_CHANNEL_0);
 
-The input voltage in above example is from 0 to 1.1V (0 dB attenuation). The input range can be extended by setting higher attenuation, see :cpp:type:`adc_atten_t`.
-An example using the ADC driver including calibration (discussed below) is available in esp-idf: :example:`peripherals/adc`
+The input voltage in the above example is from 0 to 1.1 V (0 dB attenuation). The input range can be extended by setting a higher attenuation, see :cpp:type:`adc_atten_t`.
+An example of using the ADC driver including calibration (discussed below) is available at esp-idf: :example:`peripherals/adc`
 
 Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7})::
 
@@ -131,7 +131,7 @@ The {IDF_TARGET_NAME} ADC can be sensitive to noise leading to large discrepanci
 ADC Calibration
 ---------------
 
-The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different {IDF_TARGET_NAME}s.
+The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100 mV, however the true reference voltage can range from 1000 mV to 1200 mV amongst different {IDF_TARGET_NAME}s.
 
 .. figure:: ../../../_static/adc-vref-graph.jpg
     :align: center
@@ -144,50 +144,62 @@ Correcting ADC readings using this API involves characterizing one of the ADCs a
 Calibration Values
 ^^^^^^^^^^^^^^^^^^
 
-Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular {IDF_TARGET_NAME}. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the {IDF_TARGET_NAME} chip/module.
+Calibration values are used to generate characteristic curves that account for the variation of ADC reference voltage of a particular {IDF_TARGET_NAME} chip. There are currently three sources of calibration values on ESP32, and one source on ESP32-S2. The availability of these calibration values will depend on the type and production date of the {IDF_TARGET_NAME} chip/module.
 
-* **Two Point** values represent each of the ADCs’ readings at 150mV and 850mV. To obtain more accurate calibration results these values should be measured by user and burned into eFuse ``BLOCK3``.
+.. only:: esp32
 
-* **eFuse Vref** represents the true ADC reference voltage. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration.
+    * **Two Point** values represent each of the ADCs’ readings at 150 mV and 850 mV. To obtain more accurate calibration results these values should be measured by user and burned into eFuse ``BLOCK3``.
 
-* **Default Vref** is an estimate of the ADC reference voltage provided by the user as a parameter during characterization. If Two Point or eFuse Vref values are unavailable, **Default Vref** will be used.
+    * **eFuse Vref** represents the true ADC reference voltage. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration.
 
-.. only:: esp32
+    * **Default Vref** is an estimate of the ADC reference voltage provided by the user as a parameter during characterization. If Two Point or eFuse Vref values are unavailable, **Default Vref** will be used.
 
-    Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below).
+        Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below).
 
-    .. figure:: ../../../_static/chip_surface_marking.png
-        :align: center
-        :alt: ESP32 Chip Surface Marking
+        .. figure:: ../../../_static/chip_surface_marking.png
+            :align: center
+            :alt: ESP32 Chip Surface Marking
 
-        ESP32 Chip Surface Marking
+            ESP32 Chip Surface Marking
 
-    If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly.
+        If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly.
 
-    .. highlight:: none
+        .. highlight:: none
 
-    If you are unable to check the date code (i.e. the chip may be enclosed inside a canned module, etc.), you can still verify if **eFuse Vref** is present by running `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_  tool with ``adc_info`` parameter ::
+        If you are unable to check the date code (i.e. the chip may be enclosed inside a canned module, etc.), you can still verify if **eFuse Vref** is present by running the `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_  tool with ``adc_info`` parameter ::
 
-        $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info
+            $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info
 
-    Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name.
+        Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name.
+
+        A chip that has specific **eFuse Vref** value programmed (in this case 1093 mV) will be reported as follows::
 
-    A chip that has specific **eFuse Vref** value programmed (in this case 1093mV) will be reported as follows::
+            ADC VRef calibration: 1093 mV
 
-        ADC VRef calibration: 1093mV
+        In another example below the **eFuse Vref** is not programmed::
 
-    In another example below the **eFuse Vref** is not programmed::
+            ADC VRef calibration: None (1100 mV nominal)
 
-        ADC VRef calibration: None (1100mV nominal)
+        For a chip with two point calibration the message will look similar to::
 
-    For a chip with two point calibration the message will look similar to::
+            ADC VRef calibration: 1149 mV
+            ADC readings stored in efuse BLK3:
+                ADC1 Low reading  (150 mV): 306
+                ADC1 High reading (850 mV): 3153
+                ADC2 Low reading  (150 mV): 389
+                ADC2 High reading (850 mV): 3206
+
+.. only:: esp32s2
 
-        ADC VRef calibration: 1149mV
-        ADC readings stored in efuse BLK3:
-            ADC1 Low reading  (150mV): 306
-            ADC1 High reading (850mV): 3153
-            ADC2 Low reading  (150mV): 389
-            ADC2 High reading (850mV): 3206
+    * **eFuse Two Point** values calibrates the ADC output at two different voltages. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration on newly manufactured ESP32-S2 chips and modules. If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly.
+
+    .. highlight:: none
+
+    You can verify if **eFuse Two Point** is present by running the `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_  tool with ``adc_info`` parameter ::
+
+        $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info
+
+    Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name.
 
 Application Example
 ^^^^^^^^^^^^^^^^^^^