1 // Copyright 2017-2018 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include <string.h> 22 #include "esp_types.h" 23 #include "esp_err.h" 24 #include "esp_efuse.h" 25 #include "sdkconfig.h" 26 #if CONFIG_IDF_TARGET_ESP32 27 #include "esp32/esp_efuse_utility.h" 28 #elif CONFIG_IDF_TARGET_ESP32S2 29 #include "esp32s2/esp_efuse_utility.h" 30 #elif CONFIG_IDF_TARGET_ESP32S3 31 #include "esp32s3/esp_efuse_utility.h" 32 #elif CONFIG_IDF_TARGET_ESP32C3 33 #include "esp32c3/esp_efuse_utility.h" 34 #endif 35 36 /** 37 * @brief Structure range address by blocks 38 */ 39 typedef struct { 40 uint32_t start; 41 uint32_t end; 42 } esp_efuse_range_addr_t; 43 44 /** 45 * @brief This is type of function that will handle the efuse field register. 46 * 47 * @param[in] num_reg The register number in the block. 48 * @param[in] efuse_block Block number. 49 * @param[in] bit_start Start bit in the register. 50 * @param[in] bit_count The number of bits used in the register. 51 * @param[in/out] arr A pointer to an array or variable. 52 * @param[in/out] bits_counter Counter bits. 53 * 54 * @return 55 * - ESP_OK: The operation was successfully completed. 56 * - other efuse component errors. 57 */ 58 typedef esp_err_t (*efuse_func_proc_t) (unsigned int num_reg, esp_efuse_block_t efuse_block, int starting_bit_num_in_reg, int num_bits_used_in_reg, void* arr, int* bits_counter); 59 60 /** 61 * @brief This function processes the field by calling the passed function. 62 * 63 * This function selects the field, checks the length, and calls the register processing function. 64 * @param[in] field A pointer to the structure describing the fields of efuse. 65 * @param[in/out] ptr A pointer to an array that is used to read / write from / to the efuse field. 66 * @param[in] ptr_size_bits The size of the data in bits for the efuse field. if = 0 then read all field bits. 67 * @param[in] func_proc This is the function that will handle the efuse fields. 68 * 69 * @return 70 * - ESP_OK: The operation was successfully completed. 71 * - other efuse component errors. 72 */ 73 esp_err_t esp_efuse_utility_process(const esp_efuse_desc_t* field[], void* ptr, size_t ptr_size_bits, efuse_func_proc_t func_proc); 74 75 /** 76 * @brief Write register with the required number of "1" bits. 77 * @param[in/out] cnt The number of bits you need to set in the field. 78 */ 79 esp_err_t esp_efuse_utility_write_cnt(unsigned int num_reg, esp_efuse_block_t efuse_block, int bit_start, int bit_count, void* cnt, int* bits_counter); 80 81 /** 82 * @brief Fill registers from array for writing. 83 * @param[in] arr_in A pointer to an array in which the data for the writing. 84 */ 85 esp_err_t esp_efuse_utility_write_blob(unsigned int num_reg, esp_efuse_block_t efuse_block, int bit_start, int bit_count, void* arr_in, int* bits_counter); 86 87 /** 88 * @brief Count a set bits in register. 89 * @param[in/out] out_cnt A pointer to size_t variable which will contain the number of "1" bits. 90 */ 91 esp_err_t esp_efuse_utility_count_once(unsigned int num_reg, esp_efuse_block_t efuse_block, int bit_start, int bit_count, void* out_cnt, int* bits_counter); 92 93 /** 94 * @brief Read efuse register and write this value to array. 95 * @param[out] arr_out A pointer to array that will contain the result of reading. 96 */ 97 esp_err_t esp_efuse_utility_fill_buff(unsigned int num_reg, esp_efuse_block_t efuse_block, int bit_start, int bit_count, void* arr_out, int* bits_counter); 98 99 /** 100 * @brief Burn values written to the efuse write registers. 101 * 102 * If CONFIG_EFUSE_VIRTUAL is set, writing will not be performed. 103 * After the function is completed, the writing registers are cleared. 104 */ 105 void esp_efuse_utility_burn_efuses(void); 106 107 /** 108 * @brief Returns the number of array elements for placing these "bits" in an array with the length of each element equal to "size_of_base". 109 */ 110 int esp_efuse_utility_get_number_of_items(int bits, int size_of_base); 111 112 /** 113 * @brief Reading efuse register. 114 */ 115 uint32_t esp_efuse_utility_read_reg(esp_efuse_block_t blk, unsigned int num_reg); 116 117 /** 118 * @brief Writing efuse register with checking of repeated programming of programmed bits. 119 */ 120 esp_err_t esp_efuse_utility_write_reg(unsigned int num_reg, esp_efuse_block_t efuse_block, uint32_t reg_to_write); 121 122 /* @brief Reset efuse write registers 123 * 124 * Efuse write registers are written to zero, to negate 125 * any changes that have been staged here. 126 */ 127 void esp_efuse_utility_reset(void); 128 129 /** 130 * @brief Fills the virt_blocks array by values from efuse_Rdata. 131 */ 132 void esp_efuse_utility_update_virt_blocks(void); 133 134 /** 135 * @brief Prints efuse values for all registers. 136 */ 137 void esp_efuse_utility_debug_dump_blocks(void); 138 139 /** 140 * @brief Erase the virt_blocks array. 141 */ 142 void esp_efuse_utility_erase_virt_blocks(void); 143 144 /** 145 * @brief Apply coding_scheme to write registers. 146 * 147 * @return 148 * - ESP_OK: The operation was successfully completed. 149 * - ESP_ERR_CODING: Error range of data does not match the coding scheme. 150 */ 151 esp_err_t esp_efuse_utility_apply_new_coding_scheme(void); 152 153 /** 154 * @brief Efuse read operation: copies data from physical efuses to efuse read registers. 155 */ 156 void esp_efuse_utility_clear_program_registers(void); 157 158 #ifdef __cplusplus 159 } 160 #endif 161
