Merge branch 'bugfix/adc_full_scale_voltages_v4.2' into 'release/v4.2'

docs: Update full-scale voltages for ESP32-S2 chip (v4.2)

See merge request espressif/esp-idf!12208

components/driver/include/driver/adc_common.h

@@ -144,58 +144,48 @@ 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 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
+ * @brief Set the attenuation of a particular channel on ADC1, and configure its associated GPIO pin mux.
+ *
+ * The default ADC voltage is for attenuation 0 dB and listed in the table below.
+ * By setting higher attenuation it is possible to read higher voltages.
+ *
+ * Due to ADC characteristics, most accurate results are obtained within the "suggested range"
+ * shown in the following table.
+ *
+ *     +----------+-------------+-----------------+
+ *     |          | attenuation | suggested range |
+ *     |    SoC   |     (dB)    |      (mV)       |
+ *     +==========+=============+=================+
+ *     |          |       0     |    100 ~  950   |
+ *     |          +-------------+-----------------+
+ *     |          |       2.5   |    100 ~ 1250   |
+ *     |   ESP32  +-------------+-----------------+
+ *     |          |       6     |    150 ~ 1750   |
+ *     |          +-------------+-----------------+
+ *     |          |      11     |    150 ~ 2450   |
+ *     +----------+-------------+-----------------+
+ *     |          |       0     |      0 ~  750   |
+ *     |          +-------------+-----------------+
+ *     |          |       2.5   |      0 ~ 1050   |
+ *     | ESP32-S2 +-------------+-----------------+
+ *     |          |       6     |      0 ~ 1300   |
+ *     |          +-------------+-----------------+
+ *     |          |      11     |      0 ~ 2500   |
+ *     +----------+-------------+-----------------+
+ *
+ * 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. 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);
 
@@ -292,26 +282,40 @@ esp_err_t adc2_pad_get_io_num(adc2_channel_t channel, gpio_num_t *gpio_num);
 /**
  * @brief Configure the ADC2 channel, including setting attenuation.
  *
- *        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_0db) gives full-scale voltage 1.1 V
- *        - 2.5 dB attenuation (ADC_ATTEN_2_5db) gives full-scale voltage 1.5 V
- *        - 6 dB attenuation (ADC_ATTEN_6db) gives full-scale voltage 2.2 V
- *        - 11 dB attenuation (ADC_ATTEN_11db) gives full-scale voltage 3.9 V (see note below)
+ * The default ADC voltage is for attenuation 0 dB and listed in the table below.
+ * By setting higher attenuation it is possible to read higher voltages.
+ *
+ * Due to ADC characteristics, most accurate results are obtained within the "suggested range"
+ * shown in the following table.
+ *
+ *     +----------+-------------+-----------------+
+ *     |          | attenuation | suggested range |
+ *     |    SoC   |     (dB)    |      (mV)       |
+ *     +==========+=============+=================+
+ *     |          |       0     |    100 ~  950   |
+ *     |          +-------------+-----------------+
+ *     |          |       2.5   |    100 ~ 1250   |
+ *     |   ESP32  +-------------+-----------------+
+ *     |          |       6     |    150 ~ 1750   |
+ *     |          +-------------+-----------------+
+ *     |          |      11     |    150 ~ 2450   |
+ *     +----------+-------------+-----------------+
+ *     |          |       0     |      0 ~  750   |
+ *     |          +-------------+-----------------+
+ *     |          |       2.5   |      0 ~ 1050   |
+ *     | ESP32-S2 +-------------+-----------------+
+ *     |          |       6     |      0 ~ 1300   |
+ *     |          +-------------+-----------------+
+ *     |          |      11     |      0 ~ 2500   |
+ *     +----------+-------------+-----------------+
+ *
+ * For maximum accuracy, use the ADC calibration APIs and measure voltages within these recommended ranges.
  *
  * @note This function also configures the input GPIO pin mux to
  *       connect it to the ADC2 channel. It must be called before calling
  *       ``adc2_get_raw()`` for this channel.
  *
- * @note The full-scale voltage is the voltage corresponding to a maximum reading
- *       (depending on ADC2 configured bit width,
- *       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 VDDA, not the full scale voltage.
+ * @note For any given channel, this function must be called before the first time ``adc2_get_raw()`` is called for that channel.
  *
  * @param channel ADC2 channel to configure
  * @param atten  Attenuation level