1 /*
2 * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #include <stdint.h>
8 #include "esp_types.h"
9 #include "driver/adc.h"
10 #include "soc/efuse_periph.h"
11 #include "esp_err.h"
12 #include "assert.h"
13 #include "esp_adc_cal.h"
14
15 /* ----------------------------- Configuration ------------------------------ */
16 #ifdef CONFIG_ADC_CAL_EFUSE_TP_ENABLE
17 #define EFUSE_TP_ENABLED 1
18 #else
19 #define EFUSE_TP_ENABLED 0
20 #endif
21
22 #ifdef CONFIG_ADC_CAL_EFUSE_VREF_ENABLE
23 #define EFUSE_VREF_ENABLED 1
24 #else
25 #define EFUSE_VREF_ENABLED 0
26 #endif
27
28 #ifdef CONFIG_ADC_CAL_LUT_ENABLE
29 #define LUT_ENABLED 1
30 #else
31 #define LUT_ENABLED 0
32 #endif
33
34 /* ESP32s with both Two Point Values and Vref burned into eFuse are required to
35 * also also burn the EFUSE_BLK3_PART_RESERVE flag. A limited set of ESP32s
36 * (not available through regular sales channel) DO NOT have the
37 * EFUSE_BLK3_PART_RESERVE burned. Moreover, this set of ESP32s represents Vref
38 * in Two's Complement format. If this is the case, modify the preprocessor
39 * definitions below as follows...
40 * #define CHECK_BLK3_FLAG 0 //Do not check BLK3 flag as it is not burned
41 * #define VREF_FORMAT 1 //eFuse Vref is in Two's Complement format
42 */
43 #define CHECK_BLK3_FLAG 1
44 #define VREF_FORMAT 0
45
46 /* ------------------------------ eFuse Access ----------------------------- */
47 #define BLK3_RESERVED_REG EFUSE_BLK0_RDATA3_REG
48
49 #define VREF_REG EFUSE_BLK0_RDATA4_REG
50 #define VREF_MASK 0x1F
51 #define VREF_STEP_SIZE 7
52 #define VREF_OFFSET 1100
53
54 #define TP_REG EFUSE_BLK3_RDATA3_REG
55 #define TP_LOW1_OFFSET 278
56 #define TP_LOW2_OFFSET 421
57 #define TP_LOW_MASK 0x7F
58 #define TP_LOW_VOLTAGE 150
59 #define TP_HIGH1_OFFSET 3265
60 #define TP_HIGH2_OFFSET 3406
61 #define TP_HIGH_MASK 0x1FF
62 #define TP_HIGH_VOLTAGE 850
63 #define TP_STEP_SIZE 4
64
65 /* ----------------------- Raw to Voltage Constants ------------------------- */
66 #define LIN_COEFF_A_SCALE 65536
67 #define LIN_COEFF_A_ROUND (LIN_COEFF_A_SCALE/2)
68
69 #define LUT_VREF_LOW 1000
70 #define LUT_VREF_HIGH 1200
71 #define LUT_ADC_STEP_SIZE 64
72 #define LUT_POINTS 20
73 #define LUT_LOW_THRESH 2880
74 #define LUT_HIGH_THRESH (LUT_LOW_THRESH + LUT_ADC_STEP_SIZE)
75 #define ADC_12_BIT_RES 4096
76
77 /* ------------------------ Characterization Constants ---------------------- */
78 static const uint32_t adc1_tp_atten_scale[4] = {65504, 86975, 120389, 224310};
79 static const uint32_t adc2_tp_atten_scale[4] = {65467, 86861, 120416, 224708};
80 static const uint32_t adc1_tp_atten_offset[4] = {0, 1, 27, 54};
81 static const uint32_t adc2_tp_atten_offset[4] = {0, 9, 26, 66};
82
83 static const uint32_t adc1_vref_atten_scale[4] = {57431, 76236, 105481, 196602};
84 static const uint32_t adc2_vref_atten_scale[4] = {57236, 76175, 105678, 197170};
85 static const uint32_t adc1_vref_atten_offset[4] = {75, 78, 107, 142};
86 static const uint32_t adc2_vref_atten_offset[4] = {63, 66, 89, 128};
87
88 //20 Point lookup tables, covering ADC readings from 2880 to 4096, step size of 64
89 static const uint32_t lut_adc1_low[LUT_POINTS] = {2240, 2297, 2352, 2405, 2457, 2512, 2564, 2616, 2664, 2709,
90 2754, 2795, 2832, 2868, 2903, 2937, 2969, 3000, 3030, 3060};
91 static const uint32_t lut_adc1_high[LUT_POINTS] = {2667, 2706, 2745, 2780, 2813, 2844, 2873, 2901, 2928, 2956,
92 2982, 3006, 3032, 3059, 3084, 3110, 3135, 3160, 3184, 3209};
93 static const uint32_t lut_adc2_low[LUT_POINTS] = {2238, 2293, 2347, 2399, 2451, 2507, 2561, 2613, 2662, 2710,
94 2754, 2792, 2831, 2869, 2904, 2937, 2968, 2999, 3029, 3059};
95 static const uint32_t lut_adc2_high[LUT_POINTS] = {2657, 2698, 2738, 2774, 2807, 2838, 2867, 2894, 2921, 2946,
96 2971, 2996, 3020, 3043, 3067, 3092, 3116, 3139, 3162, 3185};
97
98 /* ----------------------- EFuse Access Functions --------------------------- */
check_efuse_vref(void)99 static bool check_efuse_vref(void)
100 {
101 //Check if Vref is burned in eFuse
102 return (REG_GET_FIELD(VREF_REG, EFUSE_RD_ADC_VREF) != 0) ? true : false;
103 }
104
check_efuse_tp(void)105 static bool check_efuse_tp(void)
106 {
107 //Check if Two Point values are burned in eFuse
108 if (CHECK_BLK3_FLAG && (REG_GET_FIELD(BLK3_RESERVED_REG, EFUSE_RD_BLK3_PART_RESERVE) == 0)) {
109 return false;
110 }
111 //All TP cal values must be non zero
112 if ((REG_GET_FIELD(TP_REG, EFUSE_RD_ADC1_TP_LOW) != 0) &&
113 (REG_GET_FIELD(TP_REG, EFUSE_RD_ADC2_TP_LOW) != 0) &&
114 (REG_GET_FIELD(TP_REG, EFUSE_RD_ADC1_TP_HIGH) != 0) &&
115 (REG_GET_FIELD(TP_REG, EFUSE_RD_ADC2_TP_HIGH) != 0)) {
116 return true;
117 } else {
118 return false;
119 }
120 }
121
decode_bits(uint32_t bits,uint32_t mask,bool is_twos_compl)122 static inline int decode_bits(uint32_t bits, uint32_t mask, bool is_twos_compl)
123 {
124 int ret;
125 if (bits & (~(mask >> 1) & mask)) { //Check sign bit (MSB of mask)
126 //Negative
127 if (is_twos_compl) {
128 ret = -(((~bits) + 1) & (mask >> 1)); //2's complement
129 } else {
130 ret = -(bits & (mask >> 1)); //Sign-magnitude
131 }
132 } else {
133 //Positive
134 ret = bits & (mask >> 1);
135 }
136 return ret;
137 }
138
read_efuse_vref(void)139 static uint32_t read_efuse_vref(void)
140 {
141 //eFuse stores deviation from ideal reference voltage
142 uint32_t ret = VREF_OFFSET; //Ideal vref
143 uint32_t bits = REG_GET_FIELD(VREF_REG, EFUSE_ADC_VREF);
144 ret += decode_bits(bits, VREF_MASK, VREF_FORMAT) * VREF_STEP_SIZE;
145 return ret; //ADC Vref in mV
146 }
147
read_efuse_tp_low(adc_unit_t adc_num)148 static uint32_t read_efuse_tp_low(adc_unit_t adc_num)
149 {
150 //ADC reading at 150mV stored in two's complement format
151 uint32_t ret;
152 uint32_t bits;
153
154 if (adc_num == ADC_UNIT_1) {
155 ret = TP_LOW1_OFFSET;
156 bits = REG_GET_FIELD(TP_REG, EFUSE_RD_ADC1_TP_LOW);
157 } else {
158 ret = TP_LOW2_OFFSET;
159 bits = REG_GET_FIELD(TP_REG, EFUSE_RD_ADC2_TP_LOW);
160 }
161 ret += decode_bits(bits, TP_LOW_MASK, true) * TP_STEP_SIZE;
162 return ret; //Reading of ADC at 150mV
163 }
164
read_efuse_tp_high(adc_unit_t adc_num)165 static uint32_t read_efuse_tp_high(adc_unit_t adc_num)
166 {
167 //ADC reading at 850mV stored in two's complement format
168 uint32_t ret;
169 uint32_t bits;
170
171 if (adc_num == ADC_UNIT_1) {
172 ret = TP_HIGH1_OFFSET;
173 bits = REG_GET_FIELD(TP_REG, EFUSE_RD_ADC1_TP_HIGH);
174 } else {
175 ret = TP_HIGH2_OFFSET;
176 bits = REG_GET_FIELD(TP_REG, EFUSE_RD_ADC2_TP_HIGH);
177 }
178 ret += decode_bits(bits, TP_HIGH_MASK, true) * TP_STEP_SIZE;
179 return ret; //Reading of ADC at 850mV
180 }
181
182 /* ----------------------- Characterization Functions ----------------------- */
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)183 static void characterize_using_two_point(adc_unit_t adc_num,
184 adc_atten_t atten,
185 uint32_t high,
186 uint32_t low,
187 uint32_t *coeff_a,
188 uint32_t *coeff_b)
189 {
190 const uint32_t *atten_scales;
191 const uint32_t *atten_offsets;
192
193 if (adc_num == ADC_UNIT_1) { //Using ADC 1
194 atten_scales = adc1_tp_atten_scale;
195 atten_offsets = adc1_tp_atten_offset;
196 } else { //Using ADC 2
197 atten_scales = adc2_tp_atten_scale;
198 atten_offsets = adc2_tp_atten_offset;
199 }
200 //Characterize ADC-Voltage curve as y = (coeff_a * x) + coeff_b
201 uint32_t delta_x = high - low;
202 uint32_t delta_v = TP_HIGH_VOLTAGE - TP_LOW_VOLTAGE;
203 //Where coeff_a = (delta_v/delta_x) * atten_scale
204 *coeff_a = (delta_v * atten_scales[atten] + (delta_x / 2)) / delta_x; //+(delta_x/2) for rounding
205 //Where coeff_b = high_v - ((delta_v/delta_x) * high_x) + atten_offset
206 *coeff_b = TP_HIGH_VOLTAGE - ((delta_v * high + (delta_x / 2)) / delta_x) + atten_offsets[atten];
207 }
208
characterize_using_vref(adc_unit_t adc_num,adc_atten_t atten,uint32_t vref,uint32_t * coeff_a,uint32_t * coeff_b)209 static void characterize_using_vref(adc_unit_t adc_num,
210 adc_atten_t atten,
211 uint32_t vref,
212 uint32_t *coeff_a,
213 uint32_t *coeff_b)
214 {
215 const uint32_t *atten_scales;
216 const uint32_t *atten_offsets;
217
218 if (adc_num == ADC_UNIT_1) { //Using ADC 1
219 atten_scales = adc1_vref_atten_scale;
220 atten_offsets = adc1_vref_atten_offset;
221 } else { //Using ADC 2
222 atten_scales = adc2_vref_atten_scale;
223 atten_offsets = adc2_vref_atten_offset;
224 }
225 //Characterize ADC-Voltage curve as y = (coeff_a * x) + coeff_b
226 //Where coeff_a = (vref/4096) * atten_scale
227 *coeff_a = (vref * atten_scales[atten]) / (ADC_12_BIT_RES);
228 *coeff_b = atten_offsets[atten];
229 }
230
231 /* ------------------------ Conversion Functions --------------------------- */
calculate_voltage_linear(uint32_t adc_reading,uint32_t coeff_a,uint32_t coeff_b)232 static uint32_t calculate_voltage_linear(uint32_t adc_reading, uint32_t coeff_a, uint32_t coeff_b)
233 {
234 //Where voltage = coeff_a * adc_reading + coeff_b
235 return (((coeff_a * adc_reading) + LIN_COEFF_A_ROUND) / LIN_COEFF_A_SCALE) + coeff_b;
236 }
237
238 //Only call when ADC reading is above threshold
calculate_voltage_lut(uint32_t adc,uint32_t vref,const uint32_t * low_vref_curve,const uint32_t * high_vref_curve)239 static uint32_t calculate_voltage_lut(uint32_t adc, uint32_t vref, const uint32_t *low_vref_curve, const uint32_t *high_vref_curve)
240 {
241 //Get index of lower bound points of LUT
242 uint32_t i = (adc - LUT_LOW_THRESH) / LUT_ADC_STEP_SIZE;
243
244 //Let the X Axis be Vref, Y axis be ADC reading, and Z be voltage
245 int x2dist = LUT_VREF_HIGH - vref; //(x2 - x)
246 int x1dist = vref - LUT_VREF_LOW; //(x - x1)
247 int y2dist = ((i + 1) * LUT_ADC_STEP_SIZE) + LUT_LOW_THRESH - adc; //(y2 - y)
248 int y1dist = adc - ((i * LUT_ADC_STEP_SIZE) + LUT_LOW_THRESH); //(y - y1)
249
250 //For points for bilinear interpolation
251 int q11 = low_vref_curve[i]; //Lower bound point of low_vref_curve
252 int q12 = low_vref_curve[i + 1]; //Upper bound point of low_vref_curve
253 int q21 = high_vref_curve[i]; //Lower bound point of high_vref_curve
254 int q22 = high_vref_curve[i + 1]; //Upper bound point of high_vref_curve
255
256 //Bilinear interpolation
257 //Where z = 1/((x2-x1)*(y2-y1)) * ( (q11*x2dist*y2dist) + (q21*x1dist*y2dist) + (q12*x2dist*y1dist) + (q22*x1dist*y1dist) )
258 int voltage = (q11 * x2dist * y2dist) + (q21 * x1dist * y2dist) + (q12 * x2dist * y1dist) + (q22 * x1dist * y1dist);
259 voltage += ((LUT_VREF_HIGH - LUT_VREF_LOW) * LUT_ADC_STEP_SIZE) / 2; //Integer division rounding
260 voltage /= ((LUT_VREF_HIGH - LUT_VREF_LOW) * LUT_ADC_STEP_SIZE); //Divide by ((x2-x1)*(y2-y1))
261 return (uint32_t)voltage;
262 }
263
interpolate_two_points(uint32_t y1,uint32_t y2,uint32_t x_step,uint32_t x)264 static inline uint32_t interpolate_two_points(uint32_t y1, uint32_t y2, uint32_t x_step, uint32_t x)
265 {
266 //Interpolate between two points (x1,y1) (x2,y2) between 'lower' and 'upper' separated by 'step'
267 return ((y1 * x_step) + (y2 * x) - (y1 * x) + (x_step / 2)) / x_step;
268 }
269
270 /* ------------------------- Public API ------------------------------------- */
esp_adc_cal_check_efuse(esp_adc_cal_value_t source)271 esp_err_t esp_adc_cal_check_efuse(esp_adc_cal_value_t source)
272 {
273 if (source == ESP_ADC_CAL_VAL_EFUSE_TP) {
274 return (check_efuse_tp()) ? ESP_OK : ESP_ERR_NOT_SUPPORTED;
275 } else if (source == ESP_ADC_CAL_VAL_EFUSE_VREF) {
276 return (check_efuse_vref()) ? ESP_OK : ESP_ERR_NOT_SUPPORTED;
277 } else {
278 return ESP_ERR_INVALID_ARG;
279 }
280 }
281
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)282 esp_adc_cal_value_t esp_adc_cal_characterize(adc_unit_t adc_num,
283 adc_atten_t atten,
284 adc_bits_width_t bit_width,
285 uint32_t default_vref,
286 esp_adc_cal_characteristics_t *chars)
287 {
288 //Check parameters
289 assert((adc_num == ADC_UNIT_1) || (adc_num == ADC_UNIT_2));
290 assert(chars != NULL);
291 assert(bit_width < ADC_WIDTH_MAX);
292
293 //Check eFuse if enabled to do so
294 bool efuse_tp_present = check_efuse_tp();
295 bool efuse_vref_present = check_efuse_vref();
296 esp_adc_cal_value_t ret;
297
298 if (efuse_tp_present && EFUSE_TP_ENABLED) {
299 //Characterize based on Two Point values
300 uint32_t high = read_efuse_tp_high(adc_num);
301 uint32_t low = read_efuse_tp_low(adc_num);
302 characterize_using_two_point(adc_num, atten, high, low, &chars->coeff_a, &chars->coeff_b);
303 ret = ESP_ADC_CAL_VAL_EFUSE_TP;
304 } else if (efuse_vref_present && EFUSE_VREF_ENABLED) {
305 //Characterize based on eFuse Vref
306 uint32_t vref = read_efuse_vref();
307 characterize_using_vref(adc_num, atten, vref, &chars->coeff_a, &chars->coeff_b);
308 ret = ESP_ADC_CAL_VAL_EFUSE_VREF;
309 } else {
310 //Characterized based on default Vref
311 characterize_using_vref(adc_num, atten, default_vref, &chars->coeff_a, &chars->coeff_b);
312 ret = ESP_ADC_CAL_VAL_DEFAULT_VREF;
313 }
314
315 //Initialized remaining fields
316 chars->adc_num = adc_num;
317 chars->atten = atten;
318 chars->bit_width = bit_width;
319 chars->vref = (EFUSE_VREF_ENABLED && efuse_vref_present) ? read_efuse_vref() : default_vref;
320 //Initialize fields for lookup table if necessary
321 if (LUT_ENABLED && atten == ADC_ATTEN_DB_12) {
322 chars->low_curve = (adc_num == ADC_UNIT_1) ? lut_adc1_low : lut_adc2_low;
323 chars->high_curve = (adc_num == ADC_UNIT_1) ? lut_adc1_high : lut_adc2_high;
324 } else {
325 chars->low_curve = NULL;
326 chars->high_curve = NULL;
327 }
328 return ret;
329 }
330
esp_adc_cal_raw_to_voltage(uint32_t adc_reading,const esp_adc_cal_characteristics_t * chars)331 uint32_t esp_adc_cal_raw_to_voltage(uint32_t adc_reading, const esp_adc_cal_characteristics_t *chars)
332 {
333 assert(chars != NULL);
334
335 //Scale adc_rading if not 12 bits wide
336 adc_reading = (adc_reading << (ADC_WIDTH_BIT_12 - chars->bit_width));
337 if (adc_reading > ADC_12_BIT_RES - 1) {
338 adc_reading = ADC_12_BIT_RES - 1; //Set to 12bit res max
339 }
340
341 if (LUT_ENABLED && (chars->atten == ADC_ATTEN_DB_12) && (adc_reading >= LUT_LOW_THRESH)) { //Check if in non-linear region
342 //Use lookup table to get voltage in non linear portion of ADC_ATTEN_DB_12
343 uint32_t lut_voltage = calculate_voltage_lut(adc_reading, chars->vref, chars->low_curve, chars->high_curve);
344 if (adc_reading <= LUT_HIGH_THRESH) { //If ADC is transitioning from linear region to non-linear region
345 //Linearly interpolate between linear voltage and lut voltage
346 uint32_t linear_voltage = calculate_voltage_linear(adc_reading, chars->coeff_a, chars->coeff_b);
347 return interpolate_two_points(linear_voltage, lut_voltage, LUT_ADC_STEP_SIZE, (adc_reading - LUT_LOW_THRESH));
348 } else {
349 return lut_voltage;
350 }
351 } else {
352 return calculate_voltage_linear(adc_reading, chars->coeff_a, chars->coeff_b);
353 }
354 }
355
