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