esp-idf/components/esp_adc_cal/esp_adc_cal_esp32s2.c

// Copyright 2019-2020 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at

//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#include <stdint.h>
#include "esp_types.h"
#include "driver/adc.h"
#include "soc/efuse_periph.h"
#include "esp_err.h"
#include "assert.h"
#include "esp_adc_cal.h"
#include "esp_efuse.h"

#define ADC_CAL_CHECK(cond, ret) ({                                         \
            if(!(cond)){                                                    \
                return ret;                                                 \
            }                                                               \
})
/* ------------------------ Characterization Constants ---------------------- */
#define ADC_CHAR_VERSION1_EFUSEVAL 1

static const uint32_t adc1_D_mean_low[] = {2231, 1643, 1290, 701};
static const uint32_t adc2_D_mean_low[] = {2305, 1693, 1343, 723};
static const uint32_t adc1_D_mean_high[] = {5775, 5692, 5725, 6209};
static const uint32_t adc2_D_mean_high[] = {5817, 5703, 5731, 6157};

static const int Dlow_data_length = 6;
static const int Dhigh_data_length = 8;

static const int adc_efuse_block = 2;
static const int adc_calib_ver_block = 2;
static const int adc_calib_ver_word_loc = 4;
static const int adc_calib_ver_offset = 4;
static const int adc_calib_ver_len = 3;

static const int adc1_atten0_Dlow_word_loc = 6;
static const int adc2_atten0_Dlow_word_loc = 7;
static const int adc1_atten0_Dhigh_word_loc = 4;
static const int adc2_atten0_Dhigh_word_loc = 5;

static const int adc1_atten0_Dlow_offset = 16;
static const int adc2_atten0_Dlow_offset = 8;
static const int adc1_atten0_Dhigh_offset = 16;
static const int adc2_atten0_Dhigh_offset = 16;
/* ----------------------- EFuse Access Functions --------------------------- */
/**
 *  Convenience function that reads a few bits from efuse and assembles them.
 *  For example, if the contents of the EFuse are:
 *   Word2: 0x1234 Word3:0x5678
 *   Then, setting base=2, offset=24, len=24 will yield 0x456.
 *  @note does not check for boundaries, make sure parameters are correct
 *  @param blk EFuse Block
 *  @param base the starting word
 *  @param offset the bit offset in the starting word
 *  @param bit how many consecutive bits to fetch
 *  @return the assembled number
 */
static uint32_t get_consecutive_bits_from_blk(int blk, uint32_t base, int offset, int len)
{

    base += offset / 32;
    offset %= 32;
    if (offset + len <= 32 || base == 7) {
        uint32_t result = esp_efuse_read_reg(blk, base);
        result <<= (32 - offset - len);
        result >>= (32 - len);
        return result;
    } else {
        // need to fetch both bytes.
        uint64_t result = ((uint64_t)esp_efuse_read_reg(blk, base + 1) << 32) + esp_efuse_read_reg(blk, base);
        result &= ((uint64_t)1 << (offset + len)) - 1;
        result >>= offset;
        return result;
    }
}

/**
 *  To save space in EFuse, the calibration values for adc are compressed.
 *  The compression scheme is: for X bits of ADC Efuse data,
 *  The actual ADC reading is: BASE_VALUE + 4*ADC_OFFSET
 *  where ADC_OFFSET = bits X-1:0 in Efuse, the highest bit is the sign bit (0:+, 1:-).
 *
 *  The following functions do this conversion.
 *  @param efuse_val raw values read from efuse.
 *  @param adc_num Specifies the channel number. The 2 adc channels each have different calibration values.
 *  @param attem Specifies the attenuation. Different attenuation level have different calibration values.
 */
static uint32_t efuse_low_val_to_d(uint16_t efuse_val, adc_unit_t adc_num, adc_atten_t atten)
{
    // efuse_val is 5 bits + 6th sign bit.
    int32_t rawoffsetval = efuse_val & ((1 << (Dlow_data_length - 1)) - 1);
    // if the sign bit is 1, it means it is a negative sign.
    int32_t offset = (efuse_val & (1 << (Dlow_data_length - 1))) ? (-rawoffsetval * 4) : (rawoffsetval * 4);
    if (adc_num == ADC_UNIT_1) {
        return offset + adc1_D_mean_low[atten - ADC_ATTEN_DB_0];
    } else {
        return offset + adc2_D_mean_low[atten - ADC_ATTEN_DB_0];
    }
}

static uint32_t efuse_high_val_to_d (uint16_t efuse_val, adc_unit_t adc_num, adc_atten_t atten)
{
    // efuse_val is 7 bits + 8th sign bit.
    int32_t rawoffsetval = efuse_val & ((1 << (Dhigh_data_length - 1)) - 1);
    int32_t offset = (efuse_val & (1 << (Dhigh_data_length - 1))) ? (-rawoffsetval * 4) : (rawoffsetval * 4);
    if (adc_num == ADC_UNIT_1) {
        return offset + adc1_D_mean_high[atten - ADC_ATTEN_DB_0];
    } else {
        return offset + adc2_D_mean_high[atten - ADC_ATTEN_DB_0];
    }

}

/**
 *  To save space in EFuse, the calibration values for adc are compressed.
 *  The compression scheme is: for X bits of ADC Efuse data,
 *  The actual ADC reading is: BASE_VALUE + 4*ADC_OFFSET
 *  where ADC_OFFSET = bits X-1:0 in Efuse, the highest bit is the sign bit (0:+, 1:-).
 *
 *  The following functions do the reading.
 *  @param efuse_val raw values read from efuse.
 *  @param adc_num Specifies the channel number. The 2 adc channels each have different calibration values.
 *  @param attem Specifies the attenuation. Different attenuation level have different calibration values.
 */
static uint32_t read_efuse_tp_low(adc_unit_t adc_num, adc_atten_t atten)
{
    // this fcn retrieves and decodes the calibration value stored in efuse.
    uint32_t base;
    int offset;
    // may need to move magic numbers out
    if (adc_num == ADC_UNIT_1) {
        // the first value is at the 16th bit of the 6th word of the efuse block 2, each value is 6 bits long.
        base = adc1_atten0_Dlow_word_loc;
        offset = adc1_atten0_Dlow_offset + Dlow_data_length * (atten - ADC_ATTEN_DB_0);

    } else {
        // the first value is at the 8th bit of the 7th word of the efuse block 2, each value is 6 bits long.
        base = adc2_atten0_Dlow_word_loc;
        offset = adc2_atten0_Dlow_offset + Dlow_data_length * (atten - ADC_ATTEN_DB_0);
    }
    uint32_t read_result = get_consecutive_bits_from_blk(adc_efuse_block, base, offset, Dlow_data_length);
    return read_result;
}

static uint32_t read_efuse_tp_high(adc_unit_t adc_num, adc_atten_t atten)
{
    // this fcn retrieves and decodes the calibration value stored in efuse.
    uint32_t base;
    int offset;

    if (adc_num == ADC_UNIT_1) {
        // the first value is at the 16th bit of the 4th word of the efuse block 2, each value is 8 bits long.
        base = adc1_atten0_Dhigh_word_loc;
        offset = adc1_atten0_Dhigh_offset + Dhigh_data_length * (atten - ADC_ATTEN_DB_0);

    } else {
        // the first value is at the 16th bit of the 5th word of the efuse block 2, each value is 8 bits long.
        base = adc2_atten0_Dhigh_word_loc;
        offset = adc2_atten0_Dhigh_offset + Dhigh_data_length * (atten - ADC_ATTEN_DB_0);
    }
    uint32_t read_result = get_consecutive_bits_from_blk(adc_efuse_block, base, offset, Dhigh_data_length);
    return read_result;
}

/* ----------------------- Characterization Functions ----------------------- */

// coeff_a and coeff_b are actually floats
// they are scaled to put them into uint32_t so that the headers do not have to be changed
static const int coeff_a_scaling = 65536;
static const int coeff_b_scaling = 1024;

/**
 *  The Two Point calibration measures the reading at two specific input voltages, and calculates the (assumed linear) relation
 *  between input voltage and ADC response. (Response = A * Vinput + B)
 *  A and B are scaled ints.
 *  @param high The ADC response at the higher voltage of the corresponding attenuation (600mV, 800mV, 1000mV, 2000mV).
 *  @param low The ADC response at the lower voltage of the corresponding attenuation (all 250mV).
 *
 */
static void characterize_using_two_point(adc_unit_t adc_num,
        adc_atten_t atten,
        uint32_t high,
        uint32_t low,
        uint32_t *coeff_a,
        uint32_t *coeff_b)
{
    // once we have recovered the reference high(Dhigh) and low(Dlow) readings, we can calculate a and b from
    // the measured high and low readings
    static const uint32_t v_high[] = {600, 800, 1000, 2000};
    static const uint32_t v_low = 250;
    *coeff_a = coeff_a_scaling * (v_high[atten] - v_low) / (high - low);
    *coeff_b = coeff_b_scaling * (v_low * high - v_high[atten] * low) / (high - low);
}


/* ------------------------- Public API ------------------------------------- */
esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t source)
{
    if (source != ESP_ADC_CAL_VAL_EFUSE_TP) {
        return ESP_ERR_NOT_SUPPORTED;
    }
    uint8_t adc1_atten0_dh = get_consecutive_bits_from_blk(adc_efuse_block, adc1_atten0_Dhigh_word_loc, adc1_atten0_Dhigh_offset, Dhigh_data_length);
    uint8_t adc2_atten0_dh = get_consecutive_bits_from_blk(adc_efuse_block, adc2_atten0_Dhigh_word_loc, adc2_atten0_Dhigh_offset, Dhigh_data_length);
    if (!adc1_atten0_dh || !adc2_atten0_dh) {
        return ESP_ERR_NOT_SUPPORTED;
    }
    uint8_t adc_encoding_version = get_consecutive_bits_from_blk(adc_calib_ver_block, adc_calib_ver_word_loc, adc_calib_ver_offset, adc_calib_ver_len);
    if (adc_encoding_version != 1) {
        // current version only accepts encoding ver 1.
        return ESP_ERR_INVALID_VERSION;
    }
    return ESP_OK;
}

esp_adc_cal_value_t esp_adc_cal_characterize(adc_unit_t adc_num,
        adc_atten_t atten,
        adc_bits_width_t bit_width,
        uint32_t default_vref,
        esp_adc_cal_characteristics_t *chars)
{
    // Check parameters
    assert((adc_num == ADC_UNIT_1) || (adc_num == ADC_UNIT_2));
    assert(chars != NULL);
    assert(bit_width == ADC_WIDTH_BIT_13);

    // Characterize based on efuse Two Point values. If these values are not present in efuse,
    // or efuse values are of a version that we do not recognize, automatically assume default values.
    uint32_t adc_calib_high, adc_calib_low;
    if (esp_adc_cal_check_efuse(ESP_ADC_CAL_VAL_EFUSE_TP) == ESP_OK) {
        adc_calib_high = read_efuse_tp_high(adc_num, atten);
        adc_calib_low = read_efuse_tp_low(adc_num, atten);
    } else {
        adc_calib_high = 0;
        adc_calib_low = 0;
    }
    uint32_t high = efuse_high_val_to_d(adc_calib_high, adc_num, atten);
    uint32_t low = efuse_low_val_to_d(adc_calib_low, adc_num, atten);
    characterize_using_two_point(adc_num, atten, high, low, &(chars->coeff_a), &(chars->coeff_b));
    // Initialize remaining fields
    chars->adc_num = adc_num;
    chars->atten = atten;
    chars->bit_width = bit_width;

    // these values are not used as the corresponding calibration themes are deprecated.
    chars->vref = 0;
    chars->low_curve = NULL;
    chars->high_curve = NULL;

    // in esp32s2 we only use the two point method to calibrate the adc.
    return ESP_ADC_CAL_VAL_EFUSE_TP;
}

uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, const esp_adc_cal_characteristics_t *chars)
{
    ADC_CAL_CHECK(chars != NULL, ESP_ERR_INVALID_ARG);

    return adc_reading * chars->coeff_a / coeff_a_scaling + chars->coeff_b / coeff_b_scaling;
}

esp_err_t esp_adc_cal_get_voltage(adc_channel_t channel,
                                  const esp_adc_cal_characteristics_t *chars,
                                  uint32_t *voltage)
{
    // Check parameters
    ADC_CAL_CHECK(chars != NULL, ESP_ERR_INVALID_ARG);
    ADC_CAL_CHECK(voltage != NULL, ESP_ERR_INVALID_ARG);

    int adc_reading;
    if (chars->adc_num == ADC_UNIT_1) {
        //Check if channel is valid on ADC1
        ADC_CAL_CHECK((adc1_channel_t)channel < ADC1_CHANNEL_MAX, ESP_ERR_INVALID_ARG);
        adc_reading = adc1_get_raw(channel);
    } else {
        //Check if channel is valid on ADC2
        ADC_CAL_CHECK((adc2_channel_t)channel < ADC2_CHANNEL_MAX, ESP_ERR_INVALID_ARG);
        if (adc2_get_raw(channel, chars->bit_width, &adc_reading) != ESP_OK) {
            return ESP_ERR_TIMEOUT;     //Timed out waiting for ADC2
        }
    }
    *voltage = esp_adc_cal_raw_to_voltage((uint32_t)adc_reading, chars);
    return ESP_OK;
}