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