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