1 /*
2  * SPDX-FileCopyrightText: 2019-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 "esp_efuse_rtc_calib.h"
15 #include "hal/adc_ll.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 
24 /* ------------------------ Characterization Constants ---------------------- */
25 
26 // coeff_a is actually a float number
27 // it is scaled to put them into uint32_t so that the headers do not have to be changed
28 static const int coeff_a_scaling = 65536;
29 
30 /**
31  * @note Error Calculation
32  * Coefficients for calculating the reading voltage error.
33  * Four sets of coefficients for atten0 ~ atten3 respectively.
34  *
35  * For each item, first element is the Coefficient, second element is the Multiple. (Coefficient / Multiple) is the real coefficient.
36  *
37  * @note {0,0} stands for unused item
38  * @note In case of the overflow, these coeffcients are recorded as Absolute Value
39  * @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);
40  * @note Above formula is rewritten from the original documentation, please note that the coefficients are re-ordered.
41  * @note ADC1 and ADC2 use same coeffients
42  */
43 const static uint64_t adc_error_coef_atten[4][5][2] = {
44                                                         {{225966470500043, 1e15}, {7265418501948, 1e16}, {109410402681, 1e16}, {0, 0}, {0, 0}},                         //atten0
45                                                         {{4229623392600516, 1e16}, {731527490903, 1e16}, {88166562521, 1e16}, {0, 0}, {0, 0}},                          //atten1
46                                                         {{1017859239236435, 1e15}, {97159265299153, 1e16}, {149794028038, 1e16}, {0, 0}, {0, 0}},                       //atten2
47                                                         {{14912262772850453, 1e16}, {228549975564099, 1e16}, {356391935717, 1e16}, {179964582, 1e16}, {42046, 1e16}}    //atten3
48                                                        };
49 /**
50  * Term sign
51  * @note ADC1 and ADC2 use same coeffients
52  */
53 const static int32_t adc_error_sign[4][5] = {
54                                                 {-1, -1, 1,  0,  0}, //atten0
55                                                 { 1, -1, 1,  0,  0}, //atten1
56                                                 {-1, -1, 1,  0,  0}, //atten2
57                                                 {-1, -1, 1, -1,  1}  //atten3
58                                              };
59 
60 /* -------------------- Characterization Helper Data Types ------------------ */
61 typedef struct {
62     uint32_t voltage;
63     uint32_t digi;
64 } adc_calib_data_ver1;
65 
66 typedef struct {
67     char version_num;
68     adc_unit_t adc_num;
69     adc_atten_t atten_level;
70     union {
71         adc_calib_data_ver1 ver1;
72     } efuse_data;
73 } adc_calib_parsed_info_t;
74 
prepare_calib_data_for(int version_num,adc_unit_t adc_num,adc_atten_t atten,adc_calib_parsed_info_t * parsed_data_storage)75 static esp_err_t prepare_calib_data_for(int version_num, adc_unit_t adc_num, adc_atten_t atten, adc_calib_parsed_info_t *parsed_data_storage)
76 {
77     assert(version_num == 1);
78     esp_err_t ret;
79 
80     parsed_data_storage->version_num = version_num;
81     parsed_data_storage->adc_num = adc_num;
82     parsed_data_storage->atten_level = atten;
83     uint32_t voltage, digi;
84     /**
85      * V1 we don't have calibration data for ADC2, using the efuse data of ADC1.
86      * Here passing the `adc_num` is just for compatibility
87      */
88     ret = esp_efuse_rtc_calib_get_cal_voltage(version_num, adc_num, atten, &digi, &voltage);
89     if (ret != ESP_OK) {
90         return ret;
91     }
92     parsed_data_storage->efuse_data.ver1.voltage = voltage;
93     parsed_data_storage->efuse_data.ver1.digi = digi;
94     return ret;
95 }
96 
97 /* ----------------------- Characterization Functions ----------------------- */
98 /*
99  * Estimate the (assumed) linear relationship btwn the measured raw value and the voltage
100  * with the previously done measurement when the chip was manufactured.
101  */
calculate_characterization_coefficients(const adc_calib_parsed_info_t * parsed_data,esp_adc_cal_characteristics_t * chars)102 static void calculate_characterization_coefficients(const adc_calib_parsed_info_t *parsed_data, esp_adc_cal_characteristics_t *chars)
103 {
104     ESP_LOGD(LOG_TAG, "Calib V1, Cal Voltage = %"PRId32", Digi out = %"PRId32, parsed_data->efuse_data.ver1.voltage, parsed_data->efuse_data.ver1.digi);
105 
106     chars->coeff_a = coeff_a_scaling * parsed_data->efuse_data.ver1.voltage / parsed_data->efuse_data.ver1.digi;
107     chars->coeff_b = 0;
108 }
109 
110 /* ------------------------- Public API ------------------------------------- */
esp_adc_cal_check_efuse(esp_adc_cal_value_t source)111 esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t source)
112 {
113     if (source != ESP_ADC_CAL_VAL_EFUSE_TP) {
114         return ESP_ERR_NOT_SUPPORTED;
115     }
116     uint8_t adc_encoding_version = esp_efuse_rtc_calib_get_ver();
117     if (adc_encoding_version != 1) {
118         // current version only accepts encoding ver 1.
119         return ESP_ERR_INVALID_VERSION;
120     }
121     return ESP_OK;
122 }
123 
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)124 esp_adc_cal_value_t esp_adc_cal_characterize(adc_unit_t adc_num,
125         adc_atten_t atten,
126         adc_bits_width_t bit_width,
127         uint32_t default_vref,
128         esp_adc_cal_characteristics_t *chars)
129 {
130     esp_err_t ret;
131     adc_calib_parsed_info_t efuse_parsed_data = {0};
132     // Check parameters
133     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");
134     ESP_RETURN_ON_FALSE(chars != NULL, ESP_ADC_CAL_VAL_NOT_SUPPORTED, LOG_TAG, "Ivalid characteristic");
135     ESP_RETURN_ON_FALSE(bit_width == ADC_WIDTH_BIT_12, ESP_ADC_CAL_VAL_NOT_SUPPORTED, LOG_TAG, "Invalid bit_width");
136     ESP_RETURN_ON_FALSE(atten < SOC_ADC_ATTEN_NUM, ESP_ADC_CAL_VAL_NOT_SUPPORTED, LOG_TAG, "Invalid attenuation");
137 
138     int version_num = esp_efuse_rtc_calib_get_ver();
139     ESP_RETURN_ON_FALSE(version_num == 1, ESP_ADC_CAL_VAL_NOT_SUPPORTED, LOG_TAG, "No calibration efuse burnt");
140 
141     memset(chars, 0, sizeof(esp_adc_cal_characteristics_t));
142 
143     // make sure adc is calibrated.
144     ret = prepare_calib_data_for(version_num, adc_num, atten, &efuse_parsed_data);
145     if (ret != ESP_OK) {
146         abort();
147     }
148 
149     calculate_characterization_coefficients(&efuse_parsed_data, chars);
150     ESP_LOGD(LOG_TAG, "adc%d (atten leven %d) calibration done: A:%"PRId32" B:%"PRId32, adc_num, atten, chars->coeff_a, chars->coeff_b);
151 
152     // Initialize remaining fields
153     chars->adc_num = adc_num;
154     chars->atten = atten;
155     chars->bit_width = bit_width;
156 
157     // in esp32c3 we only use the two point method to calibrate the adc.
158     return ESP_ADC_CAL_VAL_EFUSE_TP;
159 }
160 
esp_adc_cal_raw_to_voltage(uint32_t adc_reading,const esp_adc_cal_characteristics_t * chars)161 uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, const esp_adc_cal_characteristics_t *chars)
162 {
163     assert(chars != NULL);
164 
165     int32_t error = 0;
166     uint64_t v_cali_1 = (uint64_t)adc_reading * chars->coeff_a / coeff_a_scaling;
167     esp_adc_error_calc_param_t param = {
168         .v_cali_input = v_cali_1,
169         .term_num = (chars->atten == 3) ? 5 : 3,
170         .coeff = &adc_error_coef_atten,
171         .sign = &adc_error_sign,
172     };
173     error = esp_adc_cal_get_reading_error(&param, chars->atten);
174 
175     return (int32_t)v_cali_1 - error;
176 }
177