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
