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
