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