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 9 #ifndef CONFIG_IDF_TARGET_ESP32S2 10 #error This file should only be included for ESP32-S2 target 11 #endif 12 13 #include <stdint.h> 14 #include <stdbool.h> 15 #include "esp_attr.h" 16 #include "soc/spi_mem_reg.h" 17 #include "esp_rom_spiflash.h" 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 /************************************************************* 24 * Note 25 ************************************************************* 26 * 1. ESP32 chip have 4 SPI slave/master, however, SPI0 is 27 * used as an SPI master to access Flash and ext-SRAM by 28 * Cache module. It will support Decryto read for Flash, 29 * read/write for ext-SRAM. And SPI1 is also used as an 30 * SPI master for Flash read/write and ext-SRAM read/write. 31 * It will support Encrypto write for Flash. 32 * 2. As an SPI master, SPI support Highest clock to 80M, 33 * however, Flash with 80M Clock should be configured 34 * for different Flash chips. If you want to use 80M 35 * clock We should use the SPI that is certified by 36 * Espressif. However, the certification is not started 37 * at the time, so please use 40M clock at the moment. 38 * 3. SPI Flash can use 2 lines or 4 lines mode. If you 39 * use 2 lines mode, you can save two pad SPIHD and 40 * SPIWP for gpio. ESP32 support configured SPI pad for 41 * Flash, the configuration is stored in efuse and flash. 42 * However, the configurations of pads should be certified 43 * by Espressif. If you use this function, please use 40M 44 * clock at the moment. 45 * 4. ESP32 support to use Common SPI command to configure 46 * Flash to QIO mode, if you failed to configure with fix 47 * command. With Common SPI Command, ESP32 can also provide 48 * a way to use same Common SPI command groups on different 49 * Flash chips. 50 * 5. This functions are not protected by packeting, Please use the 51 ************************************************************* 52 */ 53 54 #define PERIPHS_SPI_FLASH_CMD SPI_MEM_CMD_REG(1) 55 #define PERIPHS_SPI_FLASH_ADDR SPI_MEM_ADDR_REG(1) 56 #define PERIPHS_SPI_FLASH_CTRL SPI_MEM_CTRL_REG(1) 57 #define PERIPHS_SPI_FLASH_CTRL1 SPI_MEM_CTRL1_REG(1) 58 #define PERIPHS_SPI_FLASH_STATUS SPI_MEM_RD_STATUS_REG(1) 59 #define PERIPHS_SPI_FLASH_USRREG SPI_MEM_USER_REG(1) 60 #define PERIPHS_SPI_FLASH_USRREG1 SPI_MEM_USER1_REG(1) 61 #define PERIPHS_SPI_FLASH_USRREG2 SPI_MEM_USER2_REG(1) 62 #define PERIPHS_SPI_FLASH_C0 SPI_MEM_W0_REG(1) 63 #define PERIPHS_SPI_FLASH_C1 SPI_MEM_W1_REG(1) 64 #define PERIPHS_SPI_FLASH_C2 SPI_MEM_W2_REG(1) 65 #define PERIPHS_SPI_FLASH_C3 SPI_MEM_W3_REG(1) 66 #define PERIPHS_SPI_FLASH_C4 SPI_MEM_W4_REG(1) 67 #define PERIPHS_SPI_FLASH_C5 SPI_MEM_W5_REG(1) 68 #define PERIPHS_SPI_FLASH_C6 SPI_MEM_W6_REG(1) 69 #define PERIPHS_SPI_FLASH_C7 SPI_MEM_W7_REG(1) 70 #define PERIPHS_SPI_FLASH_TX_CRC SPI_MEM_TX_CRC_REG(1) 71 72 #define SPI0_R_QIO_DUMMY_CYCLELEN 5 73 #define SPI0_R_QIO_ADDR_BITSLEN 23 74 #define SPI0_R_FAST_DUMMY_CYCLELEN 7 75 #define SPI0_R_DIO_DUMMY_CYCLELEN 3 76 #define SPI0_R_FAST_ADDR_BITSLEN 23 77 #define SPI0_R_SIO_ADDR_BITSLEN 23 78 79 #define SPI1_R_QIO_DUMMY_CYCLELEN 5 80 #define SPI1_R_QIO_ADDR_BITSLEN 23 81 #define SPI1_R_FAST_DUMMY_CYCLELEN 7 82 #define SPI1_R_DIO_DUMMY_CYCLELEN 3 83 #define SPI1_R_DIO_ADDR_BITSLEN 23 84 #define SPI1_R_FAST_ADDR_BITSLEN 23 85 #define SPI1_R_SIO_ADDR_BITSLEN 23 86 87 #define ESP_ROM_SPIFLASH_W_SIO_ADDR_BITSLEN 23 88 89 #define ESP_ROM_SPIFLASH_TWO_BYTE_STATUS_EN SPI_MEM_WRSR_2B 90 91 //SPI address register 92 #define ESP_ROM_SPIFLASH_BYTES_LEN 24 93 #define ESP_ROM_SPIFLASH_BUFF_BYTE_WRITE_NUM 32 94 #define ESP_ROM_SPIFLASH_BUFF_BYTE_READ_NUM 16 95 #define ESP_ROM_SPIFLASH_BUFF_BYTE_READ_BITS 0xf 96 97 typedef struct { 98 uint8_t data_length; 99 uint8_t read_cmd0; 100 uint8_t read_cmd1; 101 uint8_t write_cmd; 102 uint16_t data_mask; 103 uint16_t data; 104 } esp_rom_spiflash_common_cmd_t; 105 106 /** 107 * @brief SPI Flash init, clock divisor is 4, use 1 line Slow read mode. 108 * Please do not call this function in SDK. 109 * 110 * @param uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping 111 * else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd 112 * 113 * @param uint8_t legacy: always keeping false. 114 * 115 * @return None 116 */ 117 void esp_rom_spiflash_attach(uint32_t ishspi, bool legacy); 118 119 /** 120 * @brief SPI Read Flash status register. We use CMD 0x05 (RDSR). 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_status(esp_rom_spiflash_chip_t *spi, uint32_t *status); 132 133 /** 134 * @brief SPI Read Flash status register bits 8-15. We use CMD 0x35 (RDSR2). 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 : The pointer to which to return the Flash status value. 140 * 141 * @return ESP_ROM_SPIFLASH_RESULT_OK : read OK. 142 * ESP_ROM_SPIFLASH_RESULT_ERR : read error. 143 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout. 144 */ 145 esp_rom_spiflash_result_t esp_rom_spiflash_read_statushigh(esp_rom_spiflash_chip_t *spi, uint32_t *status); 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 a 64KB block of flash 238 * Uses SPI flash command D8H. 239 * Please do not call this function in SDK. 240 * 241 * @param uint32_t block_num : Which block to erase. 242 * 243 * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK. 244 * ESP_ROM_SPIFLASH_RESULT_ERR : Erase error. 245 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout. 246 */ 247 esp_rom_spiflash_result_t esp_rom_spiflash_erase_block(uint32_t block_num); 248 249 /** 250 * @brief Erase a sector of flash. 251 * Uses SPI flash command 20H. 252 * Please do not call this function in SDK. 253 * 254 * @param uint32_t sector_num : Which sector to erase. 255 * 256 * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK. 257 * ESP_ROM_SPIFLASH_RESULT_ERR : Erase error. 258 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout. 259 */ 260 esp_rom_spiflash_result_t esp_rom_spiflash_erase_sector(uint32_t sector_num); 261 262 /** 263 * @brief Erase some sectors. 264 * Please do not call this function in SDK. 265 * 266 * @param uint32_t start_addr : Start addr to erase, should be sector aligned. 267 * 268 * @param uint32_t area_len : Length to erase, should be sector aligned. 269 * 270 * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK. 271 * ESP_ROM_SPIFLASH_RESULT_ERR : Erase error. 272 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout. 273 */ 274 esp_rom_spiflash_result_t esp_rom_spiflash_erase_area(uint32_t start_addr, uint32_t area_len); 275 276 /** 277 * @brief Write Data to Flash, you should Erase it yourself if need. 278 * Please do not call this function in SDK. 279 * 280 * @param uint32_t dest_addr : Address to write, should be 4 bytes aligned. 281 * 282 * @param const uint32_t *src : The pointer to data which is to write. 283 * 284 * @param uint32_t len : Length to write, should be 4 bytes aligned. 285 * 286 * @return ESP_ROM_SPIFLASH_RESULT_OK : Write OK. 287 * ESP_ROM_SPIFLASH_RESULT_ERR : Write error. 288 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Write timeout. 289 */ 290 esp_rom_spiflash_result_t esp_rom_spiflash_write(uint32_t dest_addr, const uint32_t *src, int32_t len); 291 292 /** 293 * @brief Read Data from Flash, you should Erase it yourself if need. 294 * Please do not call this function in SDK. 295 * 296 * @param uint32_t src_addr : Address to read, should be 4 bytes aligned. 297 * 298 * @param uint32_t *dest : The buf to read the data. 299 * 300 * @param uint32_t len : Length to read, should be 4 bytes aligned. 301 * 302 * @return ESP_ROM_SPIFLASH_RESULT_OK : Read OK. 303 * ESP_ROM_SPIFLASH_RESULT_ERR : Read error. 304 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Read timeout. 305 */ 306 esp_rom_spiflash_result_t esp_rom_spiflash_read(uint32_t src_addr, uint32_t *dest, int32_t len); 307 308 /** 309 * @brief SPI1 go into encrypto mode. 310 * Please do not call this function in SDK. 311 * 312 * @param None 313 * 314 * @return None 315 */ 316 void esp_rom_spiflash_write_encrypted_enable(void); 317 318 /** 319 * @brief SPI1 go out of encrypto mode. 320 * Please do not call this function in SDK. 321 * 322 * @param None 323 * 324 * @return None 325 */ 326 void esp_rom_spiflash_write_encrypted_disable(void); 327 328 /** 329 * @brief Write data to flash with transparent encryption. 330 * @note Sectors to be written should already be erased. 331 * 332 * @note Please do not call this function in SDK. 333 * 334 * @param uint32_t flash_addr : Address to write, should be 32 byte aligned. 335 * 336 * @param uint32_t *data : The pointer to data to write. Note, this pointer must 337 * be 32 bit aligned and the content of the data will be 338 * modified by the encryption function. 339 * 340 * @param uint32_t len : Length to write, should be 32 bytes aligned. 341 * 342 * @return ESP_ROM_SPIFLASH_RESULT_OK : Data written successfully. 343 * ESP_ROM_SPIFLASH_RESULT_ERR : Encryption write error. 344 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Encrypto write timeout. 345 */ 346 esp_rom_spiflash_result_t esp_rom_spiflash_write_encrypted(uint32_t flash_addr, uint32_t *data, uint32_t len); 347 348 349 /** @brief Wait until SPI flash write operation is complete 350 * 351 * @note Please do not call this function in SDK. 352 * 353 * Reads the Write In Progress bit of the SPI flash status register, 354 * repeats until this bit is zero (indicating write complete). 355 * 356 * @return ESP_ROM_SPIFLASH_RESULT_OK : Write is complete 357 * ESP_ROM_SPIFLASH_RESULT_ERR : Error while reading status. 358 */ 359 esp_rom_spiflash_result_t esp_rom_spiflash_wait_idle(esp_rom_spiflash_chip_t *spi); 360 361 362 /** @brief Enable Quad I/O pin functions 363 * 364 * @note Please do not call this function in SDK. 365 * 366 * Sets the HD & WP pin functions for Quad I/O modes, based on the 367 * efuse SPI pin configuration. 368 * 369 * @param wp_gpio_num - Number of the WP pin to reconfigure for quad I/O. 370 * 371 * @param spiconfig - Pin configuration, as returned from ets_efuse_get_spiconfig(). 372 * - If this parameter is 0, default SPI pins are used and wp_gpio_num parameter is ignored. 373 * - If this parameter is 1, default HSPI pins are used and wp_gpio_num parameter is ignored. 374 * - For other values, this parameter encodes the HD pin number and also the CLK pin number. CLK pin selection is used 375 * to determine if HSPI or SPI peripheral will be used (use HSPI if CLK pin is the HSPI clock pin, otherwise use SPI). 376 * Both HD & WP pins are configured via GPIO matrix to map to the selected peripheral. 377 */ 378 void esp_rom_spiflash_select_qio_pins(uint8_t wp_gpio_num, uint32_t spiconfig); 379 380 /** 381 * @brief Clear WEL bit unconditionally. 382 * 383 * @return always ESP_ROM_SPIFLASH_RESULT_OK 384 */ 385 esp_rom_spiflash_result_t esp_rom_spiflash_write_disable(void); 386 387 /** 388 * @brief Set WREN bit. 389 * 390 * @param esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file. 391 * 392 * @return always ESP_ROM_SPIFLASH_RESULT_OK 393 */ 394 esp_rom_spiflash_result_t esp_rom_spiflash_write_enable(esp_rom_spiflash_chip_t *spi); 395 396 /** 397 * @brief Fix the bug in SPI hardware communication with Flash/Ext-SRAM in High Speed. 398 * Please do not call this function in SDK. 399 * 400 * @param uint8_t spi: 0 for SPI0(Cache Access), 1 for SPI1(Flash read/write). 401 * 402 * @param uint8_t freqdiv: Pll is 80M, 4 for 20M, 3 for 26.7M, 2 for 40M, 1 for 80M. 403 * 404 * @return None 405 */ 406 void esp_rom_spiflash_fix_dummylen(uint8_t spi, uint8_t freqdiv); 407 408 /** 409 * @brief Set SPI Flash pad drivers. 410 * Please do not call this function in SDK. 411 * 412 * @param uint8_t wp_gpio_num: WP gpio number. 413 * 414 * @param uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping 415 * else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd 416 * 417 * @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 418 * drvs[2]-bit[3:0] for spihd, drvs[2]-bit[7:4] for spiwp. 419 * Values usually read from falsh by rom code, function usually callde by rom code. 420 * if value with bit(3) set, the value is valid, bit[2:0] is the real value. 421 * 422 * @return None 423 */ 424 void esp_rom_spiflash_set_drvs(uint8_t wp_gpio_num, uint32_t ishspi, uint8_t *drvs); 425 426 /** 427 * @brief Select SPI Flash function for pads. 428 * Please do not call this function in SDK. 429 * 430 * @param uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping 431 * else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd 432 * 433 * @return None 434 */ 435 void esp_rom_spiflash_select_padsfunc(uint32_t ishspi); 436 437 /** 438 * @brief Send CommonCmd to Flash so that is can go into QIO mode, some Flash use different CMD. 439 * Please do not call this function in SDK. 440 * 441 * @param esp_rom_spiflash_common_cmd_t *cmd : A struct to show the action of a command. 442 * 443 * @return uint16_t 0 : do not send command any more. 444 * 1 : go to the next command. 445 * n > 1 : skip (n - 1) commands. 446 */ 447 uint16_t esp_rom_spiflash_common_cmd(esp_rom_spiflash_common_cmd_t *cmd); 448 449 #ifdef __cplusplus 450 } 451 #endif 452
