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