1 /* 2 * SPDX-FileCopyrightText: 2015-2023 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 <stdlib.h> 15 #include <stdbool.h> 16 17 /** \defgroup efuse_APIs efuse APIs 18 * @brief ESP32 efuse read/write APIs 19 * @attention 20 * 21 */ 22 23 /** @addtogroup efuse_APIs 24 * @{ 25 */ 26 27 typedef enum { 28 ETS_EFUSE_KEY_PURPOSE_USER = 0, 29 ETS_EFUSE_KEY_PURPOSE_RESERVED = 1, 30 ETS_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_1 = 2, 31 ETS_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_2 = 3, 32 ETS_EFUSE_KEY_PURPOSE_XTS_AES_128_KEY = 4, 33 ETS_EFUSE_KEY_PURPOSE_HMAC_DOWN_ALL = 5, 34 ETS_EFUSE_KEY_PURPOSE_HMAC_DOWN_JTAG = 6, 35 ETS_EFUSE_KEY_PURPOSE_HMAC_DOWN_DIGITAL_SIGNATURE = 7, 36 ETS_EFUSE_KEY_PURPOSE_HMAC_UP = 8, 37 ETS_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST0 = 9, 38 ETS_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST1 = 10, 39 ETS_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST2 = 11, 40 ETS_EFUSE_KEY_PURPOSE_MAX, 41 } ets_efuse_purpose_t; 42 43 typedef enum { 44 ETS_EFUSE_BLOCK0 = 0, 45 ETS_EFUSE_MAC_SPI_SYS_0 = 1, 46 ETS_EFUSE_BLOCK_SYS_DATA = 2, 47 ETS_EFUSE_BLOCK_USR_DATA = 3, 48 ETS_EFUSE_BLOCK_KEY0 = 4, 49 ETS_EFUSE_BLOCK_KEY1 = 5, 50 ETS_EFUSE_BLOCK_KEY2 = 6, 51 ETS_EFUSE_BLOCK_KEY3 = 7, 52 ETS_EFUSE_BLOCK_KEY4 = 8, 53 ETS_EFUSE_BLOCK_KEY5 = 9, 54 ETS_EFUSE_BLOCK_KEY6 = 10, 55 ETS_EFUSE_BLOCK_MAX, 56 } ets_efuse_block_t; 57 58 /** 59 * @brief set timing accroding the apb clock, so no read error or write error happens. 60 * 61 * @param clock: apb clock in HZ, only accept 20M, 40M, 80M. 62 * 63 * @return : 0 if success, others if clock not accepted 64 */ 65 int ets_efuse_set_timing(uint32_t clock); 66 67 /** 68 * @brief Enable efuse subsystem. Called after reset. Doesn't need to be called again. 69 */ 70 void ets_efuse_start(void); 71 72 /** 73 * @brief Efuse read operation: copies data from physical efuses to efuse read registers. 74 * 75 * @param null 76 * 77 * @return : 0 is success, others if apb clock is not accepted 78 */ 79 int ets_efuse_read(void); 80 81 /** 82 * @brief Efuse write operation: Copies data from efuse write registers to efuse. Operates on a single block of efuses at a time. 83 * 84 * @note This function does not update read efuses, call ets_efuse_read() once all programming is complete. 85 * 86 * @return : 0 is success, others if apb clock is not accepted 87 */ 88 int ets_efuse_program(ets_efuse_block_t block); 89 90 /** 91 * @brief Set all Efuse program registers to zero. 92 * 93 * Call this before writing new data to the program registers. 94 */ 95 void ets_efuse_clear_program_registers(void); 96 97 /** 98 * @brief Program a block of key data to an efuse block 99 * 100 * @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). 101 * @param purpose Purpose to set for this key. Purpose must be already unset. 102 * @param data Pointer to data to write. 103 * @param data_len Length of data to write. 104 * 105 * @note This function also calls ets_efuse_program() for the specified block, and for block 0 (setting the purpose) 106 */ 107 int ets_efuse_write_key(ets_efuse_block_t key_block, ets_efuse_purpose_t purpose, const void *data, size_t data_len); 108 109 110 /* @brief Return the address of a particular efuse block's first read register 111 * 112 * @param block Index of efuse block to look up 113 * 114 * @return 0 if block is invalid, otherwise a numeric read register address 115 * of the first word in the block. 116 */ 117 uint32_t ets_efuse_get_read_register_address(ets_efuse_block_t block); 118 119 /** 120 * @brief Return the current purpose set for an efuse key block 121 * 122 * @param key_block Block to read purpose for. Must be in range ETS_EFUSE_BLOCK_KEY0 to ETS_EFUSE_BLOCK_KEY6. 123 */ 124 ets_efuse_purpose_t ets_efuse_get_key_purpose(ets_efuse_block_t key_block); 125 126 /** 127 * @brief Find a key block with the particular purpose set 128 * 129 * @param purpose Purpose to search for. 130 * @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. 131 * @return true if found, false if not found. If false, value at key_block pointer is unchanged. 132 */ 133 bool ets_efuse_find_purpose(ets_efuse_purpose_t purpose, ets_efuse_block_t *key_block); 134 135 /** 136 * Return true if the key block is unused, false otherwise. 137 * 138 * An unused key block is all zero content, not read or write protected, 139 * and has purpose 0 (ETS_EFUSE_KEY_PURPOSE_USER) 140 * 141 * @param key_block key block to check. 142 * 143 * @return true if key block is unused, false if key block or used 144 * or the specified block index is not a key block. 145 */ 146 bool ets_efuse_key_block_unused(ets_efuse_block_t key_block); 147 148 149 /** 150 * @brief Search for an unused key block and return the first one found. 151 * 152 * See @ref ets_efuse_key_block_unused for a description of an unused key block. 153 * 154 * @return First unused key block, or ETS_EFUSE_BLOCK_MAX if no unused key block is found. 155 */ 156 ets_efuse_block_t ets_efuse_find_unused_key_block(void); 157 158 /** 159 * @brief Return the number of unused efuse key blocks (0-6) 160 */ 161 unsigned ets_efuse_count_unused_key_blocks(void); 162 163 /** 164 * @brief Calculate Reed-Solomon Encoding values for a block of efuse data. 165 * 166 * @param data Pointer to data buffer (length 32 bytes) 167 * @param rs_values Pointer to write encoded data to (length 12 bytes) 168 */ 169 void ets_efuse_rs_calculate(const void *data, void *rs_values); 170 171 /** 172 * @brief Read spi flash pads configuration from Efuse 173 * 174 * @return 175 * - 0 for default SPI pins. 176 * - 1 for default HSPI pins. 177 * - Other values define a custom pin configuration mask. Pins are encoded as per the EFUSE_SPICONFIG_RET_SPICLK, 178 * EFUSE_SPICONFIG_RET_SPIQ, EFUSE_SPICONFIG_RET_SPID, EFUSE_SPICONFIG_RET_SPICS0, EFUSE_SPICONFIG_RET_SPIHD macros. 179 * WP pin (for quad I/O modes) is not saved in efuse and not returned by this function. 180 */ 181 uint32_t ets_efuse_get_spiconfig(void); 182 183 /** 184 * @brief Read spi flash wp pad from Efuse 185 * 186 * @return 187 * - 0x3f for invalid. 188 * - 0~46 is valid. 189 */ 190 uint32_t ets_efuse_get_wp_pad(void); 191 192 /** 193 * @brief Read opi flash pads configuration from Efuse 194 * 195 * @return 196 * - 0 for default SPI pins. 197 * - Other values define a custom pin configuration mask. From the LSB, every 6 bits represent a GPIO number which stand for: 198 * DQS, D4, D5, D6, D7 accordingly. 199 */ 200 uint32_t ets_efuse_get_opiconfig(void); 201 202 /** 203 * @brief Read if download mode disabled from Efuse 204 * 205 * @return 206 * - true for efuse disable download mode. 207 * - false for efuse doesn't disable download mode. 208 */ 209 bool ets_efuse_download_modes_disabled(void); 210 211 /** 212 * @brief Read if legacy spi flash boot mode disabled from Efuse 213 * 214 * @return 215 * - true for efuse disable legacy spi flash boot mode. 216 * - false for efuse doesn't disable legacy spi flash boot mode. 217 */ 218 bool ets_efuse_legacy_spi_boot_mode_disabled(void); 219 220 /** 221 * @brief Read if uart print control value from Efuse 222 * 223 * @return 224 * - 0 for uart force print. 225 * - 1 for uart print when GPIO46 is low when digital reset. 226 * 2 for uart print when GPIO46 is high when digital reset. 227 * 3 for uart force slient 228 */ 229 uint32_t ets_efuse_get_uart_print_control(void); 230 231 /** 232 * @brief Read which channel will used by ROM to print 233 * 234 * @return 235 * - 0 for UART0. 236 * - 1 for UART1. 237 */ 238 uint32_t ets_efuse_get_uart_print_channel(void); 239 240 /** 241 * @brief Read if usb download mode disabled from Efuse 242 * 243 * (Also returns true if security download mode is enabled, as this mode 244 * disables USB download.) 245 * 246 * @return 247 * - true for efuse disable usb download mode. 248 * - false for efuse doesn't disable usb download mode. 249 */ 250 bool ets_efuse_usb_download_mode_disabled(void); 251 252 253 /** 254 * @brief Read if usb module disabled from Efuse 255 * 256 * @return 257 * - true for efuse disable usb module. 258 * - false for efuse doesn't disable usb module. 259 */ 260 bool ets_efuse_usb_module_disabled(void); 261 262 /** 263 * @brief Read if security download modes enabled from Efuse 264 * 265 * @return 266 * - true for efuse enable security download mode. 267 * - false for efuse doesn't enable security download mode. 268 */ 269 bool ets_efuse_security_download_modes_enabled(void); 270 271 /** 272 * @brief Return true if secure boot is enabled in EFuse 273 */ 274 bool ets_efuse_secure_boot_enabled(void); 275 276 /** 277 * @brief Return true if secure boot aggressive revoke is enabled in EFuse 278 */ 279 bool ets_efuse_secure_boot_aggressive_revoke_enabled(void); 280 281 /** 282 * @brief Return true if cache encryption (flash, PSRAM, etc) is enabled from boot via EFuse 283 */ 284 bool ets_efuse_cache_encryption_enabled(void); 285 286 /** 287 * @brief Return true if EFuse indicates an external phy needs to be used for USB 288 */ 289 bool ets_efuse_usb_use_ext_phy(void); 290 291 /** 292 * @brief Return true if EFuse indicates USB device persistence is disabled 293 */ 294 bool ets_efuse_usb_force_nopersist(void); 295 296 /** 297 * @brief Return true if OPI pins GPIO33-37 are powered by VDDSPI, otherwise by VDD33CPU 298 */ 299 bool ets_efuse_flash_opi_5pads_power_sel_vddspi(void); 300 301 /** 302 * @brief Return true if EFuse indicates an opi flash is attached. 303 */ 304 bool ets_efuse_flash_opi_mode(void); 305 306 /** 307 * @brief Return true if EFuse indicates to send a flash resume command. 308 */ 309 bool ets_efuse_force_send_resume(void); 310 311 /** 312 * @brief return the time in us ROM boot need wait flash to power on from Efuse 313 * 314 * @return 315 * - uint32_t the time in us. 316 */ 317 uint32_t ets_efuse_get_flash_delay_us(void); 318 319 #define EFUSE_SPICONFIG_SPI_DEFAULTS 0 320 #define EFUSE_SPICONFIG_HSPI_DEFAULTS 1 321 322 #define EFUSE_SPICONFIG_RET_SPICLK_MASK 0x3f 323 #define EFUSE_SPICONFIG_RET_SPICLK_SHIFT 0 324 #define EFUSE_SPICONFIG_RET_SPICLK(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPICLK_SHIFT) & EFUSE_SPICONFIG_RET_SPICLK_MASK) 325 326 #define EFUSE_SPICONFIG_RET_SPIQ_MASK 0x3f 327 #define EFUSE_SPICONFIG_RET_SPIQ_SHIFT 6 328 #define EFUSE_SPICONFIG_RET_SPIQ(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPIQ_SHIFT) & EFUSE_SPICONFIG_RET_SPIQ_MASK) 329 330 #define EFUSE_SPICONFIG_RET_SPID_MASK 0x3f 331 #define EFUSE_SPICONFIG_RET_SPID_SHIFT 12 332 #define EFUSE_SPICONFIG_RET_SPID(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPID_SHIFT) & EFUSE_SPICONFIG_RET_SPID_MASK) 333 334 #define EFUSE_SPICONFIG_RET_SPICS0_MASK 0x3f 335 #define EFUSE_SPICONFIG_RET_SPICS0_SHIFT 18 336 #define EFUSE_SPICONFIG_RET_SPICS0(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPICS0_SHIFT) & EFUSE_SPICONFIG_RET_SPICS0_MASK) 337 338 339 #define EFUSE_SPICONFIG_RET_SPIHD_MASK 0x3f 340 #define EFUSE_SPICONFIG_RET_SPIHD_SHIFT 24 341 #define EFUSE_SPICONFIG_RET_SPIHD(ret) (((ret) >> EFUSE_SPICONFIG_RET_SPIHD_SHIFT) & EFUSE_SPICONFIG_RET_SPIHD_MASK) 342 343 /** 344 * @brief Enable JTAG temporarily by writing a JTAG HMAC "key" into 345 * the JTAG_CTRL registers. 346 * 347 * Works if JTAG has been "soft" disabled by burning the EFUSE_SOFT_DIS_JTAG efuse. 348 * 349 * Will enable the HMAC module to generate a "downstream" HMAC value from a key already saved in efuse, and then write the JTAG HMAC "key" which will enable JTAG if the two keys match. 350 * 351 * @param jtag_hmac_key Pointer to a 32 byte array containing a valid key. Supplied by user. 352 * @param key_block Index of a key block containing the source for this key. 353 * 354 * @return ETS_FAILED if HMAC operation fails or invalid parameter, ETS_OK otherwise. ETS_OK doesn't necessarily mean that JTAG was enabled. 355 */ 356 int ets_jtag_enable_temporarily(const uint8_t *jtag_hmac_key, ets_efuse_block_t key_block); 357 358 /** 359 * @brief A crc8 algorithm used for MAC addresses in efuse 360 * 361 * @param unsigned char const *p : Pointer to original data. 362 * 363 * @param unsigned int len : Data length in byte. 364 * 365 * @return unsigned char: Crc value. 366 */ 367 unsigned char esp_crc8(unsigned char const *p, unsigned int len); 368 369 /** 370 * @} 371 */ 372 373 #ifdef __cplusplus 374 } 375 #endif 376 377 #endif /* _ROM_EFUSE_H_ */ 378
