1 /*
2  * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #pragma once
8 
9 #include <stdint.h>
10 #include <stdbool.h>
11 #include "esp_attr.h"
12 #include "esp_rom_spiflash.h"
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 #define PERIPHS_SPI_FLASH_CMD                 SPI_MEM_CMD_REG(1)
19 #define PERIPHS_SPI_FLASH_ADDR                SPI_MEM_ADDR_REG(1)
20 #define PERIPHS_SPI_FLASH_CTRL                SPI_MEM_CTRL_REG(1)
21 #define PERIPHS_SPI_FLASH_CTRL1               SPI_MEM_CTRL1_REG(1)
22 #define PERIPHS_SPI_FLASH_STATUS              SPI_MEM_RD_STATUS_REG(1)
23 #define PERIPHS_SPI_FLASH_USRREG              SPI_MEM_USER_REG(1)
24 #define PERIPHS_SPI_FLASH_USRREG1             SPI_MEM_USER1_REG(1)
25 #define PERIPHS_SPI_FLASH_USRREG2             SPI_MEM_USER2_REG(1)
26 #define PERIPHS_SPI_FLASH_C0                  SPI_MEM_W0_REG(1)
27 #define PERIPHS_SPI_FLASH_C1                  SPI_MEM_W1_REG(1)
28 #define PERIPHS_SPI_FLASH_C2                  SPI_MEM_W2_REG(1)
29 #define PERIPHS_SPI_FLASH_C3                  SPI_MEM_W3_REG(1)
30 #define PERIPHS_SPI_FLASH_C4                  SPI_MEM_W4_REG(1)
31 #define PERIPHS_SPI_FLASH_C5                  SPI_MEM_W5_REG(1)
32 #define PERIPHS_SPI_FLASH_C6                  SPI_MEM_W6_REG(1)
33 #define PERIPHS_SPI_FLASH_C7                  SPI_MEM_W7_REG(1)
34 #define PERIPHS_SPI_FLASH_TX_CRC              SPI_MEM_TX_CRC_REG(1)
35 
36 #define SPI0_R_QIO_DUMMY_CYCLELEN             5
37 #define SPI0_R_QIO_ADDR_BITSLEN               23
38 #define SPI0_R_FAST_DUMMY_CYCLELEN            7
39 #define SPI0_R_DIO_DUMMY_CYCLELEN             3
40 #define SPI0_R_FAST_ADDR_BITSLEN              23
41 #define SPI0_R_SIO_ADDR_BITSLEN               23
42 
43 #define SPI1_R_QIO_DUMMY_CYCLELEN             5
44 #define SPI1_R_QIO_ADDR_BITSLEN               23
45 #define SPI1_R_FAST_DUMMY_CYCLELEN            7
46 #define SPI1_R_DIO_DUMMY_CYCLELEN             3
47 #define SPI1_R_DIO_ADDR_BITSLEN               23
48 #define SPI1_R_FAST_ADDR_BITSLEN              23
49 #define SPI1_R_SIO_ADDR_BITSLEN               23
50 
51 #define ESP_ROM_SPIFLASH_W_SIO_ADDR_BITSLEN   23
52 
53 #define ESP_ROM_SPIFLASH_TWO_BYTE_STATUS_EN   SPI_MEM_WRSR_2B
54 
55 //SPI address register
56 #define ESP_ROM_SPIFLASH_BYTES_LEN            24
57 #define ESP_ROM_SPIFLASH_BUFF_BYTE_WRITE_NUM  32
58 #define ESP_ROM_SPIFLASH_BUFF_BYTE_READ_NUM   16
59 #define ESP_ROM_SPIFLASH_BUFF_BYTE_READ_BITS  0xf
60 
61 typedef void (* spi_flash_func_t)(void);
62 typedef esp_rom_spiflash_result_t (* spi_flash_op_t)(void);
63 typedef esp_rom_spiflash_result_t (* spi_flash_erase_t)(uint32_t);
64 typedef esp_rom_spiflash_result_t (* spi_flash_rd_t)(uint32_t, uint32_t*, int);
65 typedef esp_rom_spiflash_result_t (* spi_flash_wr_t)(uint32_t, const uint32_t*, int);
66 typedef esp_rom_spiflash_result_t (* spi_flash_ewr_t)(uint32_t, const void*, uint32_t);
67 typedef esp_rom_spiflash_result_t (* spi_flash_wren_t)(void*);
68 
69 typedef struct {
70     uint32_t read_sub_len;
71     uint32_t write_sub_len;
72     spi_flash_op_t unlock;
73     spi_flash_erase_t erase_sector;
74     spi_flash_erase_t erase_block;
75     spi_flash_rd_t read;
76     spi_flash_wr_t write;
77     spi_flash_ewr_t encrypt_write;
78     spi_flash_func_t check_sus;
79     spi_flash_wren_t wren;
80     spi_flash_op_t wait_idle;
81 } spiflash_legacy_funcs_t;
82 
83 typedef struct {
84     uint8_t  data_length;
85     uint8_t  read_cmd0;
86     uint8_t  read_cmd1;
87     uint8_t  write_cmd;
88     uint16_t data_mask;
89     uint16_t data;
90 } esp_rom_spiflash_common_cmd_t;
91 
92 /**
93   * @brief SPI Flash init, clock divisor is 4, use 1 line Slow read mode.
94   *    Please do not call this function in SDK.
95   *
96   * @param  uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping
97   *              else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd
98   *
99   * @param  uint8_t legacy: always keeping false.
100   *
101   * @return None
102   */
103 void esp_rom_spiflash_attach(uint32_t ishspi, bool legacy);
104 
105 /**
106   * @brief SPI Read Flash status register. We use CMD 0x05 (RDSR).
107   *    Please do not call this function in SDK.
108   *
109   * @param  esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file.
110   *
111   * @param  uint32_t *status : The pointer to which to return the Flash status value.
112   *
113   * @return ESP_ROM_SPIFLASH_RESULT_OK : read OK.
114   *         ESP_ROM_SPIFLASH_RESULT_ERR : read error.
115   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout.
116   */
117 esp_rom_spiflash_result_t esp_rom_spiflash_read_status(esp_rom_spiflash_chip_t *spi, uint32_t *status);
118 
119 /**
120   * @brief SPI Read Flash status register bits 8-15. We use CMD 0x35 (RDSR2).
121   *        Please do not call this function in SDK.
122   *
123   * @param  esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file.
124   *
125   * @param  uint32_t *status : The pointer to which to return the Flash status value.
126   *
127   * @return ESP_ROM_SPIFLASH_RESULT_OK : read OK.
128   *         ESP_ROM_SPIFLASH_RESULT_ERR : read error.
129   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout.
130   */
131 esp_rom_spiflash_result_t esp_rom_spiflash_read_statushigh(esp_rom_spiflash_chip_t *spi, uint32_t *status);
132 
133 /**
134   * @brief Write status to Flash status register.
135   *        Please do not call this function in SDK.
136   *
137   * @param  esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file.
138   *
139   * @param  uint32_t status_value : Value to .
140   *
141   * @return ESP_ROM_SPIFLASH_RESULT_OK : write OK.
142   *         ESP_ROM_SPIFLASH_RESULT_ERR : write error.
143   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : write timeout.
144   */
145 esp_rom_spiflash_result_t esp_rom_spiflash_write_status(esp_rom_spiflash_chip_t *spi, uint32_t status_value);
146 
147 /**
148   * @brief Use a command to Read Flash status register.
149   *        Please do not call this function in SDK.
150   *
151   * @param  esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file.
152   *
153   * @param  uint32_t*status : The pointer to which to return the Flash status value.
154   *
155   * @return ESP_ROM_SPIFLASH_RESULT_OK : read OK.
156   *         ESP_ROM_SPIFLASH_RESULT_ERR : read error.
157   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout.
158   */
159 esp_rom_spiflash_result_t esp_rom_spiflash_read_user_cmd(uint32_t *status, uint8_t cmd);
160 
161 /**
162   * @brief Config SPI Flash read mode when init.
163   *        Please do not call this function in SDK.
164   *
165   * @param  esp_rom_spiflash_read_mode_t mode : QIO/QOUT/DIO/DOUT/FastRD/SlowRD.
166   *
167   * This function does not try to set the QIO Enable bit in the status register, caller is responsible for this.
168   *
169   * @return ESP_ROM_SPIFLASH_RESULT_OK : config OK.
170   *         ESP_ROM_SPIFLASH_RESULT_ERR : config error.
171   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : config timeout.
172   */
173 esp_rom_spiflash_result_t esp_rom_spiflash_config_readmode(esp_rom_spiflash_read_mode_t mode);
174 
175 /**
176   * @brief Config SPI Flash clock divisor.
177   *        Please do not call this function in SDK.
178   *
179   * @param  uint8_t freqdiv: clock divisor.
180   *
181   * @param  uint8_t spi: 0 for SPI0, 1 for SPI1.
182   *
183   * @return ESP_ROM_SPIFLASH_RESULT_OK : config OK.
184   *         ESP_ROM_SPIFLASH_RESULT_ERR : config error.
185   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : config timeout.
186   */
187 esp_rom_spiflash_result_t esp_rom_spiflash_config_clk(uint8_t freqdiv, uint8_t spi);
188 
189 /**
190   * @brief Clear all SR bits except QE bit.
191   *        Please do not call this function in SDK.
192   *
193   * @param  None.
194   *
195   * @return ESP_ROM_SPIFLASH_RESULT_OK : Unlock OK.
196   *         ESP_ROM_SPIFLASH_RESULT_ERR : Unlock error.
197   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Unlock timeout.
198   */
199 esp_rom_spiflash_result_t esp_rom_spiflash_clear_bp(void);
200 
201 /**
202   * @brief Clear all SR bits except QE bit.
203   *        Please do not call this function in SDK.
204   *
205   * @param  None.
206   *
207   * @return ESP_ROM_SPIFLASH_RESULT_OK : Unlock OK.
208   *         ESP_ROM_SPIFLASH_RESULT_ERR : Unlock error.
209   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Unlock timeout.
210   */
211 esp_rom_spiflash_result_t esp_rom_spiflash_unlock(void);
212 
213 /**
214   * @brief Update SPI Flash parameter.
215   *        Please do not call this function in SDK.
216   *
217   * @param  uint32_t deviceId : Device ID read from SPI, the low 32 bit.
218   *
219   * @param  uint32_t chip_size : The Flash size.
220   *
221   * @param  uint32_t block_size : The Flash block size.
222   *
223   * @param  uint32_t sector_size : The Flash sector size.
224   *
225   * @param  uint32_t page_size : The Flash page size.
226   *
227   * @param  uint32_t status_mask : The Mask used when read status from Flash(use single CMD).
228   *
229   * @return ESP_ROM_SPIFLASH_RESULT_OK : Update OK.
230   *         ESP_ROM_SPIFLASH_RESULT_ERR : Update error.
231   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Update timeout.
232   */
233 esp_rom_spiflash_result_t esp_rom_spiflash_config_param(uint32_t deviceId, uint32_t chip_size, uint32_t block_size,
234                                                         uint32_t sector_size, uint32_t page_size, uint32_t status_mask);
235 
236 /**
237   * @brief Erase whole flash chip.
238   *        Please do not call this function in SDK.
239   *
240   * @param  None
241   *
242   * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK.
243   *         ESP_ROM_SPIFLASH_RESULT_ERR : Erase error.
244   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout.
245   */
246 esp_rom_spiflash_result_t esp_rom_spiflash_erase_chip(void);
247 
248 /**
249   * @brief Erase a 64KB block of flash
250   *        Uses SPI flash command D8H.
251   *        Please do not call this function in SDK.
252   *
253   * @param  uint32_t block_num : Which block to erase.
254   *
255   * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK.
256   *         ESP_ROM_SPIFLASH_RESULT_ERR : Erase error.
257   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout.
258   */
259 esp_rom_spiflash_result_t esp_rom_spiflash_erase_block(uint32_t block_num);
260 
261 /**
262   * @brief Erase a sector of flash.
263   *        Uses SPI flash command 20H.
264   *        Please do not call this function in SDK.
265   *
266   * @param  uint32_t sector_num : Which sector to erase.
267   *
268   * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK.
269   *         ESP_ROM_SPIFLASH_RESULT_ERR : Erase error.
270   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout.
271   */
272 esp_rom_spiflash_result_t esp_rom_spiflash_erase_sector(uint32_t sector_num);
273 
274 /**
275   * @brief Erase some sectors.
276   *        Please do not call this function in SDK.
277   *
278   * @param  uint32_t start_addr : Start addr to erase, should be sector aligned.
279   *
280   * @param  uint32_t area_len : Length to erase, should be sector aligned.
281   *
282   * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK.
283   *         ESP_ROM_SPIFLASH_RESULT_ERR : Erase error.
284   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout.
285   */
286 esp_rom_spiflash_result_t esp_rom_spiflash_erase_area(uint32_t start_addr, uint32_t area_len);
287 
288 /**
289   * @brief Write Data to Flash, you should Erase it yourself if need.
290   *        Please do not call this function in SDK.
291   *
292   * @param  uint32_t dest_addr : Address to write, should be 4 bytes aligned.
293   *
294   * @param  const uint32_t *src : The pointer to data which is to write.
295   *
296   * @param  uint32_t len : Length to write, should be 4 bytes aligned.
297   *
298   * @return ESP_ROM_SPIFLASH_RESULT_OK : Write OK.
299   *         ESP_ROM_SPIFLASH_RESULT_ERR : Write error.
300   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Write timeout.
301   */
302 esp_rom_spiflash_result_t esp_rom_spiflash_write(uint32_t dest_addr, const uint32_t *src, int32_t len);
303 
304 /**
305   * @brief Read Data from Flash, you should Erase it yourself if need.
306   *        Please do not call this function in SDK.
307   *
308   * @param  uint32_t src_addr : Address to read, should be 4 bytes aligned.
309   *
310   * @param  uint32_t *dest : The buf to read the data.
311   *
312   * @param  uint32_t len : Length to read, should be 4 bytes aligned.
313   *
314   * @return ESP_ROM_SPIFLASH_RESULT_OK : Read OK.
315   *         ESP_ROM_SPIFLASH_RESULT_ERR : Read error.
316   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Read timeout.
317   */
318 esp_rom_spiflash_result_t esp_rom_spiflash_read(uint32_t src_addr, uint32_t *dest, int32_t len);
319 
320 /**
321   * @brief SPI1 go into encrypto mode.
322   *        Please do not call this function in SDK.
323   *
324   * @param  None
325   *
326   * @return None
327   */
328 void esp_rom_spiflash_write_encrypted_enable(void);
329 
330 /**
331   * @brief SPI1 go out of encrypto mode.
332   *        Please do not call this function in SDK.
333   *
334   * @param  None
335   *
336   * @return None
337   */
338 void esp_rom_spiflash_write_encrypted_disable(void);
339 
340 /**
341   * @brief Write data to flash with transparent encryption.
342   * @note Sectors to be written should already be erased.
343   *
344   * @note Please do not call this function in SDK.
345   *
346   * @param  uint32_t flash_addr : Address to write, should be 32 byte aligned.
347   *
348   * @param  uint32_t *data : The pointer to data to write. Note, this pointer must
349   *                          be 32 bit aligned and the content of the data will be
350   *                          modified by the encryption function.
351   *
352   * @param  uint32_t len : Length to write, should be 32 bytes aligned.
353   *
354   * @return ESP_ROM_SPIFLASH_RESULT_OK : Data written successfully.
355   *         ESP_ROM_SPIFLASH_RESULT_ERR : Encryption write error.
356   *         ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Encrypto write timeout.
357   */
358 esp_rom_spiflash_result_t esp_rom_spiflash_write_encrypted(uint32_t flash_addr, uint32_t *data, uint32_t len);
359 
360 
361 /** @brief Wait until SPI flash write operation is complete
362  *
363  * @note Please do not call this function in SDK.
364  *
365  * Reads the Write In Progress bit of the SPI flash status register,
366  * repeats until this bit is zero (indicating write complete).
367  *
368  * @return ESP_ROM_SPIFLASH_RESULT_OK : Write is complete
369  *         ESP_ROM_SPIFLASH_RESULT_ERR : Error while reading status.
370  */
371 esp_rom_spiflash_result_t esp_rom_spiflash_wait_idle(esp_rom_spiflash_chip_t *spi);
372 
373 
374 /** @brief Enable Quad I/O pin functions
375  *
376  * @note Please do not call this function in SDK.
377  *
378  * Sets the HD & WP pin functions for Quad I/O modes, based on the
379  * efuse SPI pin configuration.
380  *
381  * @param wp_gpio_num - Number of the WP pin to reconfigure for quad I/O.
382  *
383  * @param spiconfig - Pin configuration, as returned from ets_efuse_get_spiconfig().
384  * - If this parameter is 0, default SPI pins are used and wp_gpio_num parameter is ignored.
385  * - If this parameter is 1, default HSPI pins are used and wp_gpio_num parameter is ignored.
386  * - For other values, this parameter encodes the HD pin number and also the CLK pin number. CLK pin selection is used
387  *   to determine if HSPI or SPI peripheral will be used (use HSPI if CLK pin is the HSPI clock pin, otherwise use SPI).
388  *   Both HD & WP pins are configured via GPIO matrix to map to the selected peripheral.
389  */
390 void esp_rom_spiflash_select_qio_pins(uint8_t wp_gpio_num, uint32_t spiconfig);
391 
392 /**
393  * @brief Clear WEL bit unconditionally.
394  *
395  * @return always ESP_ROM_SPIFLASH_RESULT_OK
396  */
397 esp_rom_spiflash_result_t esp_rom_spiflash_write_disable(void);
398 
399 /**
400  * @brief Set WREN bit.
401  *
402  * @param  esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file.
403  *
404  * @return always ESP_ROM_SPIFLASH_RESULT_OK
405  */
406 esp_rom_spiflash_result_t esp_rom_spiflash_write_enable(esp_rom_spiflash_chip_t *spi);
407 
408 /**
409   * @brief Fix the bug in SPI hardware communication with Flash/Ext-SRAM in High Speed.
410   *    Please do not call this function in SDK.
411   *
412   * @param  uint8_t spi: 0 for SPI0(Cache Access), 1 for SPI1(Flash read/write).
413   *
414   * @param  uint8_t freqdiv: Pll is 80M, 4 for 20M, 3 for 26.7M, 2 for 40M, 1 for 80M.
415   *
416   * @return None
417   */
418 void esp_rom_spiflash_fix_dummylen(uint8_t spi, uint8_t freqdiv);
419 
420 /**
421   * @brief Set SPI Flash pad drivers.
422   *    Please do not call this function in SDK.
423   *
424   * @param  uint8_t wp_gpio_num: WP gpio number.
425   *
426   * @param  uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping
427   *              else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd
428   *
429   * @param  uint8_t *drvs: drvs[0]-bit[3:0] for cpiclk, bit[7:4] for spiq, drvs[1]-bit[3:0] for spid, drvs[1]-bit[7:4] for spid
430   *            drvs[2]-bit[3:0] for spihd, drvs[2]-bit[7:4] for spiwp.
431   *                        Values usually read from falsh by rom code, function usually callde by rom code.
432   *                        if value with bit(3) set, the value is valid, bit[2:0] is the real value.
433   *
434   * @return None
435   */
436 void esp_rom_spiflash_set_drvs(uint8_t wp_gpio_num, uint32_t ishspi, uint8_t *drvs);
437 
438 /**
439   * @brief Select SPI Flash function for pads.
440   *    Please do not call this function in SDK.
441   *
442   * @param  uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping
443   *              else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd
444   *
445   * @return None
446   */
447 void esp_rom_spiflash_select_padsfunc(uint32_t ishspi);
448 
449 /**
450   * @brief Send CommonCmd to Flash so that is can go into QIO mode, some Flash use different CMD.
451   *        Please do not call this function in SDK.
452   *
453   * @param  esp_rom_spiflash_common_cmd_t *cmd : A struct to show the action of a command.
454   *
455   * @return uint16_t  0 : do not send command any more.
456   *                   1 : go to the next command.
457   *                   n > 1 : skip (n - 1) commands.
458   */
459 uint16_t esp_rom_spiflash_common_cmd(esp_rom_spiflash_common_cmd_t *cmd);
460 
461 extern const spiflash_legacy_funcs_t *rom_spiflash_legacy_funcs;
462 
463 #ifdef __cplusplus
464 }
465 #endif
466