1 /*
2 * SPDX-FileCopyrightText: 2022-2023 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_heap_caps.h"
15 #include "esp_efuse_rtc_calib.h"
16 #include "soc/soc_caps.h"
17 #include "esp_adc/adc_cali_scheme.h"
18 #include "adc_cali_interface.h"
19
20
21 /**
22 * This file contains Line Fitting Calibration Scheme for ESP32C2.
23 *
24 * If ESP EFuse Line Fitting Calibration Scheme on future chips are similar to the scheme in this file, we can:
25 *
26 * 1. Rename this file to `adc_cali_line_fitting_v2.c`, as the Line Fitting Scheme on ESP32 and ESP32S2 are different to this.
27 * 2. Move this file to common directory
28 * 3. Still support `ADC_CALI_SCHEME_LINE_FITTING_SUPPORTED`
29 * 4. Add a new internal maccro `ADC_CALI_SCHEME_LINE_FITTING_V2_SUPPORTED`
30 * 5. Only build this file, when `ADC_CALI_SCHEME_LINE_FITTING_V2_SUPPORTED == true`
31 */
32
33
34 // coeff_a is actually a float number
35 // it is scaled to put them into uint32_t so that the headers do not have to be changed
36 static const int coeff_a_scaling = 65536;
37 const static char *TAG = "adc_cali";
38
39 typedef struct {
40 adc_unit_t unit_id;
41 adc_atten_t atten;
42 uint32_t coeff_a; ///< Gradient of ADC-Voltage characteristics
43 uint32_t coeff_b; ///< Offset of ADC-Voltage characteristics
44 } cali_chars_line_fitting_t;
45
46
47 /* ------------------------ Interface Functions --------------------------- */
48 static esp_err_t cali_raw_to_voltage(void *arg, int raw, int *voltage);
49 static esp_err_t check_valid(const adc_cali_line_fitting_config_t *config);
50
51 /* ------------------------- Public API ------------------------------------- */
adc_cali_create_scheme_line_fitting(const adc_cali_line_fitting_config_t * config,adc_cali_handle_t * ret_handle)52 esp_err_t adc_cali_create_scheme_line_fitting(const adc_cali_line_fitting_config_t *config, adc_cali_handle_t *ret_handle)
53 {
54 esp_err_t ret = ESP_OK;
55 ESP_RETURN_ON_FALSE(config && ret_handle, ESP_ERR_INVALID_ARG, TAG, "invalid arg: null pointer");
56 ret = check_valid(config);
57 if (ret != ESP_OK) {
58 return ret;
59 }
60
61 //current version only accepts encoding version: ESP_EFUSE_ADC_CALIB_VER_MIN <= adc_encoding_version <= ESP_EFUSE_ADC_CALIB_VER_MAX.
62 uint8_t adc_cali_version = esp_efuse_rtc_calib_get_ver();
63 ESP_RETURN_ON_FALSE((adc_cali_version >= ESP_EFUSE_ADC_CALIB_VER_MIN) &&
64 (adc_cali_version <= ESP_EFUSE_ADC_CALIB_VER_MAX), ESP_ERR_NOT_SUPPORTED, TAG, "Calibration required eFuse bits not burnt");
65
66 adc_cali_scheme_t *scheme = (adc_cali_scheme_t *)heap_caps_calloc(1, sizeof(adc_cali_scheme_t), MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT);
67 ESP_RETURN_ON_FALSE(scheme, ESP_ERR_NO_MEM, TAG, "no mem for adc calibration scheme");
68
69 cali_chars_line_fitting_t *chars = (cali_chars_line_fitting_t *)heap_caps_calloc(1, sizeof(cali_chars_line_fitting_t), MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT);
70 ESP_GOTO_ON_FALSE(chars, ESP_ERR_NO_MEM, err, TAG, "no memory for the calibration characteristics");
71
72 scheme->raw_to_voltage = cali_raw_to_voltage;
73 scheme->ctx = chars;
74
75 chars->unit_id = config->unit_id;
76 chars->atten = config->atten;
77
78 uint32_t voltage_mv = 0;
79 uint32_t digi_val = 0;
80 ret = esp_efuse_rtc_calib_get_cal_voltage(adc_cali_version, chars->unit_id, chars->atten, &digi_val, &voltage_mv);
81 assert(ret == ESP_OK);
82 chars->coeff_a = coeff_a_scaling * voltage_mv / digi_val;
83 chars->coeff_b = 0;
84 ESP_LOGV(TAG, "Calib V1, Cal Voltage = %"PRId32", Digi out = %"PRId32", Coef_a = %"PRId32"\n", voltage_mv, digi_val, chars->coeff_a);
85
86 *ret_handle = scheme;
87
88 return ESP_OK;
89
90 err:
91 if (scheme) {
92 heap_caps_free(scheme);
93 }
94 return ret;
95 }
96
adc_cali_delete_scheme_line_fitting(adc_cali_handle_t handle)97 esp_err_t adc_cali_delete_scheme_line_fitting(adc_cali_handle_t handle)
98 {
99 ESP_RETURN_ON_FALSE(handle, ESP_ERR_INVALID_ARG, TAG, "invalid argument: null pointer");
100
101 heap_caps_free(handle->ctx);
102 handle->ctx = NULL;
103
104 heap_caps_free(handle);
105 handle = NULL;
106
107 return ESP_OK;
108 }
109
110
111 /* ------------------------ Interface Functions --------------------------- */
cali_raw_to_voltage(void * arg,int raw,int * voltage)112 static esp_err_t cali_raw_to_voltage(void *arg, int raw, int *voltage)
113 {
114 //pointers are checked in the upper layer
115
116 cali_chars_line_fitting_t *ctx = arg;
117 *voltage = raw * ctx->coeff_a / coeff_a_scaling + ctx->coeff_b;
118
119 return ESP_OK;
120 }
121
check_valid(const adc_cali_line_fitting_config_t * config)122 static esp_err_t check_valid(const adc_cali_line_fitting_config_t *config)
123 {
124 ESP_RETURN_ON_FALSE(config->unit_id < SOC_ADC_PERIPH_NUM, ESP_ERR_INVALID_ARG, TAG, "invalid ADC unit");
125 ESP_RETURN_ON_FALSE((config->atten == ADC_ATTEN_DB_0 || config->atten == ADC_ATTEN_DB_12), ESP_ERR_NOT_SUPPORTED, TAG, "only ADC_ATTEN_DB_0 and ADC_ATTEN_DB_12 are supported");
126 if (config->atten == ADC_ATTEN_DB_0) {
127 ESP_LOGW(TAG, "Experimental: ADC Atten 0 calibration can now only used for inputs lower than 950mV. Calibration Scheme may get updated, DON'T USE FOR MASS PRODUCTION!");
128 }
129
130 bool available_oneshot_bitwidth = (config->bitwidth >= SOC_ADC_RTC_MIN_BITWIDTH && config->bitwidth <= SOC_ADC_RTC_MAX_BITWIDTH);
131 bool available_dma_bitwidth = (config->bitwidth >= SOC_ADC_DIGI_MIN_BITWIDTH && config->bitwidth <= SOC_ADC_DIGI_MAX_BITWIDTH);
132 bool default_bitwidth_mark = (config->bitwidth == ADC_BITWIDTH_DEFAULT);
133 bool available_bitwidth = (available_oneshot_bitwidth || available_dma_bitwidth || default_bitwidth_mark);
134 ESP_RETURN_ON_FALSE(available_bitwidth, ESP_ERR_INVALID_ARG, TAG, "invalid bitwidth");
135
136 return ESP_OK;
137 }
138
