1 /*
2  * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #include <stdint.h>
8 #include <stdbool.h>
9 #include <string.h>
10 #include "esp_types.h"
11 #include "esp_err.h"
12 #include "esp_log.h"
13 #include "esp_check.h"
14 #include "hal/adc_types.h"
15 #include "esp_efuse_rtc_calib.h"
16 #include "hal/adc_types.h"
17 #include "driver/adc_types_legacy.h"
18 #include "esp_adc_cal_types_legacy.h"
19 #include "../esp_adc_cal_internal_legacy.h"
20 
21 const static char LOG_TAG[] = "ADC_CALI";
22 
23 /* ------------------------ Characterization Constants ---------------------- */
24 
25 //coeff_a is actually a float number
26 //it is scaled to put them into uint32_t so that the headers do not have to be changed
27 static const int coeff_a_scaling = 1000000;
28 
29 /**
30  * @note Error Calculation
31  * Coefficients for calculating the reading voltage error.
32  * Four sets of coefficients for atten0 ~ atten3 respectively.
33  *
34  * For each item, first element is the Coefficient, second element is the Multiple. (Coefficient / Multiple) is the real coefficient.
35  *
36  * @note {0,0} stands for unused item
37  * @note In case of the overflow, these coeffcients are recorded as Absolute Value
38  * @note For atten0 ~ 2, error = (K0 * X^0) + (K1 * X^1) + (K2 * X^2); For atten3, error = (K0 * X^0) + (K1 * X^1)  + (K2 * X^2) + (K3 * X^3) + (K4 * X^4);
39  * @note Above formula is rewritten from the original documentation, please note that the coefficients are re-ordered.
40  */
41 const static uint64_t adc1_error_coef_atten[4][5][2] = {
42                                                             {{27856531419538344, 1e16}, {50871540569528, 1e16}, {9798249589, 1e15}, {0, 0}, {0, 0}},                       //ADC1 atten0
43                                                             {{29831022915028695, 1e16}, {49393185868806, 1e16}, {101379430548, 1e16}, {0, 0}, {0, 0}},                     //ADC1 atten1
44                                                             {{23285545746296417, 1e16}, {147640181047414, 1e16}, {208385525314, 1e16}, {0, 0}, {0, 0}},                    //ADC1 atten2
45                                                             {{644403418269478, 1e15}, {644334888647536, 1e16}, {1297891447611, 1e16}, {70769718, 1e15}, {13515, 1e15}}     //ADC1 atten3
46                                                         };
47 const static uint64_t adc2_error_coef_atten[4][5][2] = {
48                                                             {{25668651654328927, 1e16}, {1353548869615, 1e16}, {36615265189, 1e16}, {0, 0}, {0, 0}},                       //ADC2 atten0
49                                                             {{23690184690298404, 1e16}, {66319894226185, 1e16}, {118964995959, 1e16}, {0, 0}, {0, 0}},                     //ADC2 atten1
50                                                             {{9452499397020617, 1e16}, {200996773954387, 1e16}, {259011467956, 1e16}, {0, 0}, {0, 0}},                     //ADC2 atten2
51                                                             {{12247719764336924,1e16}, {755717904943462, 1e16}, {1478791187119, 1e16}, {79672528, 1e15}, {15038, 1e15}}    //ADC2 atten3
52                                                         };
53 /**
54  * Term sign
55  */
56 const static int32_t adc1_error_sign[4][5] = {
57                                                 {-1, -1, 1, 0,  0},  //ADC1 atten0
58                                                 {-1, -1, 1, 0,  0},  //ADC1 atten1
59                                                 {-1, -1, 1, 0,  0},  //ADC1 atten2
60                                                 {-1, -1, 1, -1, 1}   //ADC1 atten3
61                                             };
62 const static int32_t adc2_error_sign[4][5] = {
63                                                 {-1,  1, 1,  0, 0},  //ADC2 atten0
64                                                 {-1, -1, 1,  0, 0},  //ADC2 atten1
65                                                 {-1, -1, 1,  0, 0},  //ADC2 atten2
66                                                 { 1, -1, 1, -1, 1}   //ADC2 atten3
67                                             };
68 
69 /* -------------------- Characterization Helper Data Types ------------------ */
70 typedef struct {
71     uint32_t voltage;
72     uint32_t digi;
73 } adc_calib_data_ver1_t;
74 
75 typedef struct {
76     char version_num;
77     adc_unit_t adc_num;
78     adc_atten_t atten_level;
79     union {
80         adc_calib_data_ver1_t ver1;
81     } ref_data;
82 } adc_calib_info_t;
83 
84 
85 //To get the reference point (Dout, Vin)
get_reference_point(int version_num,adc_unit_t adc_num,adc_atten_t atten,adc_calib_info_t * calib_info)86 static esp_err_t get_reference_point(int version_num, adc_unit_t adc_num, adc_atten_t atten, adc_calib_info_t *calib_info)
87 {
88     assert(version_num == 1);
89     esp_err_t ret;
90 
91     calib_info->version_num = version_num;
92     calib_info->adc_num = adc_num;
93     calib_info->atten_level = atten;
94 
95     uint32_t voltage = 0;
96     uint32_t digi = 0;
97     ret = esp_efuse_rtc_calib_get_cal_voltage(version_num, adc_num, atten, &digi, &voltage);
98     assert(ret == ESP_OK);
99     calib_info->ref_data.ver1.voltage = voltage;
100     calib_info->ref_data.ver1.digi = digi;
101     return ret;
102 }
103 
esp_adc_cal_check_efuse(esp_adc_cal_value_t source)104 esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t source)
105 {
106     if (source != ESP_ADC_CAL_VAL_EFUSE_TP_FIT) {
107         return ESP_ERR_NOT_SUPPORTED;
108     }
109     uint8_t adc_encoding_version = esp_efuse_rtc_calib_get_ver();
110     if (adc_encoding_version != 1) {
111         // current version only accepts encoding ver 1.
112         return ESP_ERR_INVALID_VERSION;
113     }
114     return ESP_OK;
115 }
116 
117 /*
118  * Get an expected linear relationship btwn Vin and Dout
119  */
calculate_characterization_coefficients(const adc_calib_info_t * parsed_data,esp_adc_cal_characteristics_t * chars)120 static void calculate_characterization_coefficients(const adc_calib_info_t *parsed_data, esp_adc_cal_characteristics_t *chars)
121 {
122     chars->coeff_a = coeff_a_scaling * parsed_data->ref_data.ver1.voltage / parsed_data->ref_data.ver1.digi;
123     chars->coeff_b = 0;
124     ESP_LOGV(LOG_TAG, "Calib V1, Cal Voltage = %"PRId32", Digi out = %"PRId32", Coef_a = %"PRId32"\n", parsed_data->ref_data.ver1.voltage, parsed_data->ref_data.ver1.digi, chars->coeff_a);
125 }
126 
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)127 esp_adc_cal_value_t esp_adc_cal_characterize(adc_unit_t adc_num,
128         adc_atten_t atten,
129         adc_bits_width_t bit_width,
130         uint32_t default_vref,
131         esp_adc_cal_characteristics_t *chars)
132 {
133     (void) default_vref;
134 
135     // Check parameters
136     ESP_RETURN_ON_FALSE(adc_num == ADC_UNIT_1 || adc_num == ADC_UNIT_2, ESP_ADC_CAL_VAL_NOT_SUPPORTED, LOG_TAG, "Invalid unit num");
137     ESP_RETURN_ON_FALSE(chars != NULL, ESP_ADC_CAL_VAL_NOT_SUPPORTED, LOG_TAG, "Ivalid characteristic");
138     ESP_RETURN_ON_FALSE(atten < SOC_ADC_ATTEN_NUM, ESP_ADC_CAL_VAL_NOT_SUPPORTED, LOG_TAG, "Invalid attenuation");
139 
140     int version_num = esp_efuse_rtc_calib_get_ver();
141     ESP_RETURN_ON_FALSE(version_num == 1, ESP_ADC_CAL_VAL_NOT_SUPPORTED, LOG_TAG, "No calibration efuse burnt");
142 
143     memset(chars, 0, sizeof(esp_adc_cal_characteristics_t));
144 
145     adc_calib_info_t calib_info = {0};
146     // make sure adc is calibrated.
147     get_reference_point(version_num, adc_num, atten, &calib_info);
148     calculate_characterization_coefficients(&calib_info, chars);
149 
150     // Initialize remaining fields
151     chars->adc_num = adc_num;
152     chars->atten = atten;
153     chars->bit_width = bit_width;
154 
155     return ESP_ADC_CAL_VAL_EFUSE_TP_FIT;
156 }
157 
esp_adc_cal_raw_to_voltage(uint32_t adc_reading,const esp_adc_cal_characteristics_t * chars)158 uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, const esp_adc_cal_characteristics_t *chars)
159 {
160     assert(chars != NULL);
161 
162     //ADC reading won't exceed 4096. Otherwise the raw reading result is wrong, the next calculation will overflow.
163     assert(adc_reading < 4096);
164 
165     uint32_t voltage = 0;
166     int32_t error = 0;
167     uint64_t v_cali_1 = 0;
168 
169     //raw * gradient * 1000000
170     v_cali_1 = (uint64_t)adc_reading * chars->coeff_a;
171     //convert to real number
172     v_cali_1 = v_cali_1 / coeff_a_scaling;
173     ESP_LOGV(LOG_TAG, "v_cali_1 is %llu", v_cali_1);
174 
175     //Curve Fitting error correction
176     esp_adc_error_calc_param_t param = {
177         .v_cali_input = v_cali_1,
178         .term_num = (chars->atten == 3) ? 5 : 3,
179         .coeff = (chars->adc_num == ADC_UNIT_1) ? &adc1_error_coef_atten : &adc2_error_coef_atten,
180         .sign = (chars->adc_num == ADC_UNIT_1) ? &adc1_error_sign : &adc2_error_sign,
181     };
182     error = esp_adc_cal_get_reading_error(&param, chars->atten);
183 
184     voltage = (int32_t)v_cali_1 - error;
185 
186     return voltage;
187 }
188