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