1 /* 2 * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef _ROM_EFUSE_H_ 8 #define _ROM_EFUSE_H_ 9 10 #ifdef __cplusplus 11 extern "C" { 12 #endif 13 14 #include <stdint.h> 15 #include <stddef.h> 16 #include <stdbool.h> 17 18 /** \defgroup efuse_APIs efuse APIs 19 * @brief ESP32 efuse read/write APIs 20 * @attention 21 * 22 */ 23 24 /** For ESP32-C2, there's no key purpose region for efuse keys, In order to maintain 25 * compatibility with the previous apis, we should set the parameter of 'ets_efuse_purpose_t' 26 * as default value ETS_EFUSE_KEY_PURPOSE_INVALID. 27 * (In fact, this parameter can be any value, the api in the rom will not process key_purpose region) 28 */ 29 typedef enum { 30 ETS_EFUSE_KEY_PURPOSE_INVALID = -1, 31 } ets_efuse_purpose_t; 32 33 typedef enum { 34 ETS_EFUSE_BLOCK0 = 0, 35 ETS_EFUSE_BLOCK_SYS_DATA1 = 1, 36 ETS_EFUSE_BLOCK_SYS_DATA2 = 2, 37 ETS_EFUSE_BLOCK_KEY0 = 3, 38 ETS_EFUSE_BLOCK_MAX, 39 } ets_efuse_block_t; 40 41 /** 42 * @brief set timing accroding the apb clock, so no read error or write error happens. 43 * 44 * @param clock: apb clock in HZ, only accept 5M(in FPGA), 10M(in FPGA), 20M, 40M, 80M. 45 * 46 * @return : 0 if success, others if clock not accepted 47 */ 48 int ets_efuse_set_timing(uint32_t clock); 49 50 /** 51 * @brief Efuse read operation: copies data from physical efuses to efuse read registers. 52 * 53 * @param null 54 * 55 * @return : 0 if success, others if apb clock is not accepted 56 */ 57 int ets_efuse_read(void); 58 59 /** 60 * @brief Efuse write operation: Copies data from efuse write registers to efuse. Operates on a single block of efuses at a time. 61 * 62 * @note This function does not update read efuses, call ets_efuse_read() once all programming is complete. 63 * 64 * @return : 0 if success, others if apb clock is not accepted 65 */ 66 int ets_efuse_program(ets_efuse_block_t block); 67 68 /** 69 * @brief Set all Efuse program registers to zero. 70 * 71 * Call this before writing new data to the program registers. 72 */ 73 void ets_efuse_clear_program_registers(void); 74 75 /** 76 * @brief Program a block of key data to an efuse block 77 * 78 * @param key_block Block to read purpose for. Must be in range ETS_EFUSE_BLOCK_KEY0 to ETS_EFUSE_BLOCK_KEY6. Key block must be unused (@ref ets_efuse_key_block_unused). 79 * @param purpose Purpose to set for this key. Purpose must be already unset. 80 * @param data Pointer to data to write. 81 * @param data_len Length of data to write. 82 * 83 * @note This function also calls ets_efuse_program() for the specified block, and for block 0 (setting the purpose) 84 */ 85 int ets_efuse_write_key(ets_efuse_block_t key_block, ets_efuse_purpose_t purpose, const void *data, size_t data_len); 86 87 88 /* @brief Return the address of a particular efuse block's first read register 89 * 90 * @param block Index of efuse block to look up 91 * 92 * @return 0 if block is invalid, otherwise a numeric read register address 93 * of the first word in the block. 94 */ 95 uint32_t ets_efuse_get_read_register_address(ets_efuse_block_t block); 96 97 /** 98 * @brief Return the current purpose set for an efuse key block 99 * 100 * @param key_block Block to read purpose for. Must be in range ETS_EFUSE_BLOCK_KEY0 to ETS_EFUSE_BLOCK_KEY6. 101 */ 102 ets_efuse_purpose_t ets_efuse_get_key_purpose(ets_efuse_block_t key_block); 103 104 /** 105 * @brief Find a key block with the particular purpose set 106 * 107 * @param purpose Purpose to search for. 108 * @param[out] key_block Pointer which will be set to the key block if found. Can be NULL, if only need to test the key block exists. 109 * @return true if found, false if not found. If false, value at key_block pointer is unchanged. 110 */ 111 bool ets_efuse_find_purpose(ets_efuse_purpose_t purpose, ets_efuse_block_t *key_block); 112 113 /** 114 * Return true if the key block is unused, false otherwise. 115 * 116 * An unused key block is all zero content, not read or write protected, 117 * and has purpose 0 (ETS_EFUSE_KEY_PURPOSE_USER) 118 * 119 * @param key_block key block to check. 120 * 121 * @return true if key block is unused, false if key block or used 122 * or the specified block index is not a key block. 123 */ 124 bool ets_efuse_key_block_unused(ets_efuse_block_t key_block); 125 126 127 /** 128 * @brief Search for an unused key block and return the first one found. 129 * 130 * See @ref ets_efuse_key_block_unused for a description of an unused key block. 131 * 132 * @return First unused key block, or ETS_EFUSE_BLOCK_MAX if no unused key block is found. 133 */ 134 ets_efuse_block_t ets_efuse_find_unused_key_block(void); 135 136 /** 137 * @brief Return the number of unused efuse key blocks (0-6) 138 */ 139 unsigned ets_efuse_count_unused_key_blocks(void); 140 141 /** 142 * @brief Calculate Reed-Solomon Encoding values for a block of efuse data. 143 * 144 * @param data Pointer to data buffer (length 32 bytes) 145 * @param rs_values Pointer to write encoded data to (length 12 bytes) 146 */ 147 void ets_efuse_rs_calculate(const void *data, void *rs_values); 148 149 /** 150 * @brief Read if download mode disabled from Efuse 151 * 152 * @return 153 * - true for efuse disable download mode. 154 * - false for efuse doesn't disable download mode. 155 */ 156 bool ets_efuse_download_modes_disabled(void); 157 158 /** 159 * @brief Read if uart print control value from Efuse 160 * 161 * @return 162 * - 0 for uart force print. 163 * - 1 for uart print when GPIO8 is low when digital reset. 164 * 2 for uart print when GPIO8 is high when digital reset. 165 * 3 for uart force slient 166 */ 167 uint32_t ets_efuse_get_uart_print_control(void); 168 169 /** 170 * @brief Read if security download modes enabled from Efuse 171 * 172 * @return 173 * - true for efuse enable security download mode. 174 * - false for efuse doesn't enable security download mode. 175 */ 176 bool ets_efuse_security_download_modes_enabled(void); 177 178 /** 179 * @brief Return true if secure boot is enabled in EFuse 180 */ 181 bool ets_efuse_secure_boot_enabled(void); 182 183 /** 184 * @brief Return true if secure boot aggressive revoke is enabled in EFuse 185 */ 186 bool ets_efuse_secure_boot_aggressive_revoke_enabled(void); 187 188 /** 189 * @brief Return true if cache encryption (flash, etc) is enabled from boot via EFuse 190 */ 191 bool ets_efuse_cache_encryption_enabled(void); 192 193 /** 194 * @brief Return true if EFuse indicates to send a flash resume command. 195 */ 196 bool ets_efuse_force_send_resume(void); 197 198 /** 199 * @brief return the time in us ROM boot need wait flash to power on from Efuse 200 * 201 * @return 202 * - uint32_t the time in us. 203 */ 204 uint32_t ets_efuse_get_flash_delay_us(void); 205 206 #define EFUSE_SPICONFIG_SPI_DEFAULTS 0 207 #define EFUSE_SPICONFIG_HSPI_DEFAULTS 1 208 209 #define EFUSE_SPICONFIG_RET_SPICLK_MASK 0x3f 210 #define EFUSE_SPICONFIG_RET_SPICLK_SHIFT 0 211 #define EFUSE_SPICONFIG_RET_SPICLK(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPICLK_SHIFT) & EFUSE_SPICONFIG_RET_SPICLK_MASK) 212 213 #define EFUSE_SPICONFIG_RET_SPIQ_MASK 0x3f 214 #define EFUSE_SPICONFIG_RET_SPIQ_SHIFT 6 215 #define EFUSE_SPICONFIG_RET_SPIQ(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPIQ_SHIFT) & EFUSE_SPICONFIG_RET_SPIQ_MASK) 216 217 #define EFUSE_SPICONFIG_RET_SPID_MASK 0x3f 218 #define EFUSE_SPICONFIG_RET_SPID_SHIFT 12 219 #define EFUSE_SPICONFIG_RET_SPID(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPID_SHIFT) & EFUSE_SPICONFIG_RET_SPID_MASK) 220 221 #define EFUSE_SPICONFIG_RET_SPICS0_MASK 0x3f 222 #define EFUSE_SPICONFIG_RET_SPICS0_SHIFT 18 223 #define EFUSE_SPICONFIG_RET_SPICS0(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPICS0_SHIFT) & EFUSE_SPICONFIG_RET_SPICS0_MASK) 224 225 226 #define EFUSE_SPICONFIG_RET_SPIHD_MASK 0x3f 227 #define EFUSE_SPICONFIG_RET_SPIHD_SHIFT 24 228 #define EFUSE_SPICONFIG_RET_SPIHD(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPIHD_SHIFT) & EFUSE_SPICONFIG_RET_SPIHD_MASK) 229 230 /** 231 * @brief A crc8 algorithm used for MAC addresses in efuse 232 * 233 * @param unsigned char const *p : Pointer to original data. 234 * 235 * @param unsigned int len : Data length in byte. 236 * 237 * @return unsigned char: Crc value. 238 */ 239 unsigned char esp_crc8(unsigned char const *p, unsigned int len); 240 241 /** 242 * @} 243 */ 244 245 #ifdef __cplusplus 246 } 247 #endif 248 249 #endif /* _ROM_EFUSE_H_ */ 250
