// Copyright 2010-2016 Espressif Systems (Shanghai) PTE LTD // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #ifndef _ROM_SPI_FLASH_H_ #define _ROM_SPI_FLASH_H_ #include #include #include "esp_attr.h" #include "soc/spi_reg.h" #ifdef __cplusplus extern "C" { #endif /** \defgroup spi_flash_apis, spi flash operation related apis * @brief spi_flash apis */ /** @addtogroup spi_flash_apis * @{ */ /************************************************************* * Note ************************************************************* * 1. ESP32 chip have 4 SPI slave/master, however, SPI0 is * used as an SPI master to access Flash and ext-SRAM by * Cache module. It will support Decryto read for Flash, * read/write for ext-SRAM. And SPI1 is also used as an * SPI master for Flash read/write and ext-SRAM read/write. * It will support Encrypto write for Flash. * 2. As an SPI master, SPI support Highest clock to 80M, * however, Flash with 80M Clock should be configured * for different Flash chips. If you want to use 80M * clock We should use the SPI that is certified by * Espressif. However, the certification is not started * at the time, so please use 40M clock at the moment. * 3. SPI Flash can use 2 lines or 4 lines mode. If you * use 2 lines mode, you can save two pad SPIHD and * SPIWP for gpio. ESP32 support configured SPI pad for * Flash, the configuration is stored in efuse and flash. * However, the configurations of pads should be certified * by Espressif. If you use this function, please use 40M * clock at the moment. * 4. ESP32 support to use Common SPI command to configure * Flash to QIO mode, if you failed to configure with fix * command. With Common SPI Command, ESP32 can also provide * a way to use same Common SPI command groups on different * Flash chips. * 5. This functions are not protected by packeting, Please use the ************************************************************* */ #define PERIPHS_SPI_FLASH_CMD SPI_CMD(1) #define PERIPHS_SPI_FLASH_ADDR SPI_ADDR(1) #define PERIPHS_SPI_FLASH_CTRL SPI_CTRL(1) #define PERIPHS_SPI_FLASH_CTRL1 SPI_CTRL1(1) #define PERIPHS_SPI_FLASH_STATUS SPI_RD_STATUS(1) #define PERIPHS_SPI_FLASH_USRREG SPI_USER(1) #define PERIPHS_SPI_FLASH_USRREG1 SPI_USER1(1) #define PERIPHS_SPI_FLASH_USRREG2 SPI_USER2(1) #define PERIPHS_SPI_FLASH_C0 SPI_W0(1) #define PERIPHS_SPI_FLASH_C1 SPI_W1(1) #define PERIPHS_SPI_FLASH_C2 SPI_W2(1) #define PERIPHS_SPI_FLASH_C3 SPI_W3(1) #define PERIPHS_SPI_FLASH_C4 SPI_W4(1) #define PERIPHS_SPI_FLASH_C5 SPI_W5(1) #define PERIPHS_SPI_FLASH_C6 SPI_W6(1) #define PERIPHS_SPI_FLASH_C7 SPI_W7(1) #define PERIPHS_SPI_FLASH_TX_CRC SPI_TX_CRC(1) #define SPI0_R_QIO_DUMMY_CYCLELEN 3 #define SPI0_R_QIO_ADDR_BITSLEN 31 #define SPI0_R_FAST_DUMMY_CYCLELEN 7 #define SPI0_R_DIO_DUMMY_CYCLELEN 3 #define SPI0_R_FAST_ADDR_BITSLEN 23 #define SPI0_R_SIO_ADDR_BITSLEN 23 #define SPI1_R_QIO_DUMMY_CYCLELEN 3 #define SPI1_R_QIO_ADDR_BITSLEN 31 #define SPI1_R_FAST_DUMMY_CYCLELEN 7 #define SPI1_R_DIO_DUMMY_CYCLELEN 3 #define SPI1_R_DIO_ADDR_BITSLEN 31 #define SPI1_R_FAST_ADDR_BITSLEN 23 #define SPI1_R_SIO_ADDR_BITSLEN 23 #define SPI_W_SIO_ADDR_BITSLEN 23 #define TWO_BYTE_STATUS_EN SPI_WRSR_2B //SPI address register #define SPI_FLASH_BYTES_LEN 24 #define SPI_BUFF_BYTE_WRITE_NUM 32 #define SPI_BUFF_BYTE_READ_NUM 64 #define SPI_BUFF_BYTE_READ_BITS 0x3f //SPI status register #define SPI_FLASH_BUSY_FLAG BIT0 #define SPI_FLASH_WRENABLE_FLAG BIT1 #define SPI_FLASH_BP0 BIT2 #define SPI_FLASH_BP1 BIT3 #define SPI_FLASH_BP2 BIT4 #define FLASH_WR_PROTECT (SPI_FLASH_BP0|SPI_FLASH_BP1|SPI_FLASH_BP2) #define SPI_FLASH_QE BIT9 typedef enum { SPI_FLASH_QIO_MODE = 0, SPI_FLASH_QOUT_MODE, SPI_FLASH_DIO_MODE, SPI_FLASH_DOUT_MODE, SPI_FLASH_FASTRD_MODE, SPI_FLASH_SLOWRD_MODE } SpiFlashRdMode; typedef enum { SPI_FLASH_RESULT_OK, SPI_FLASH_RESULT_ERR, SPI_FLASH_RESULT_TIMEOUT } SpiFlashOpResult; typedef struct { uint32_t deviceId; uint32_t chip_size; // chip size in bytes uint32_t block_size; uint32_t sector_size; uint32_t page_size; uint32_t status_mask; } SpiFlashChip; typedef struct { uint8_t data_length; uint8_t read_cmd0; uint8_t read_cmd1; uint8_t write_cmd; uint16_t data_mask; uint16_t data; } SpiCommonCmd; /** * @brief Fix the bug in SPI hardware communication with Flash/Ext-SRAM in High Speed. * Please do not call this function in SDK. * * @param uint8_t spi: 0 for SPI0(Cache Access), 1 for SPI1(Flash read/write). * * @param uint8_t freqdiv: Pll is 80M, 4 for 20M, 3 for 26.7M, 2 for 40M, 1 for 80M. * * @return None */ void spi_dummy_len_fix(uint8_t spi, uint8_t freqdiv); /** * @brief Select SPI Flash to QIO mode when WP pad is read from Flash. * Please do not call this function in SDK. * * @param uint8_t wp_gpio_num: WP gpio number. * * @param uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping * else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd * * @return None */ void SelectSpiQIO(uint8_t wp_gpio_num, uint32_t ishspi); /** * @brief Set SPI Flash pad drivers. * Please do not call this function in SDK. * * @param uint8_t wp_gpio_num: WP gpio number. * * @param uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping * else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd * * @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 * drvs[2]-bit[3:0] for spihd, drvs[2]-bit[7:4] for spiwp. * Values usually read from falsh by rom code, function usually callde by rom code. * if value with bit(3) set, the value is valid, bit[2:0] is the real value. * * @return None */ void SetSpiDrvs(uint8_t wp_gpio_num, uint32_t ishspi, uint8_t *drvs); /** * @brief Select SPI Flash function for pads. * Please do not call this function in SDK. * * @param uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping * else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd * * @return None */ void SelectSpiFunction(uint32_t ishspi); /** * @brief SPI Flash init, clock divisor is 4, use 1 line Slow read mode. * Please do not call this function in SDK. * * @param uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping * else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd * * @param uint8_t legacy: In legacy mode, more SPI command is used in line. * * @return None */ void spi_flash_attach(uint32_t ishspi, bool legacy); /** * @brief SPI Read Flash status register. We use CMD 0x05 (RDSR). * Please do not call this function in SDK. * * @param SpiFlashChip *spi : The information for Flash, which is exported from ld file. * * @param uint32_t *status : The pointer to which to return the Flash status value. * * @return SPI_FLASH_RESULT_OK : read OK. * SPI_FLASH_RESULT_ERR : read error. * SPI_FLASH_RESULT_TIMEOUT : read timeout. */ SpiFlashOpResult SPI_read_status(SpiFlashChip *spi, uint32_t *status); /** * @brief SPI Read Flash status register bits 8-15. We use CMD 0x35 (RDSR2). * Please do not call this function in SDK. * * @param SpiFlashChip *spi : The information for Flash, which is exported from ld file. * * @param uint32_t *status : The pointer to which to return the Flash status value. * * @return SPI_FLASH_RESULT_OK : read OK. * SPI_FLASH_RESULT_ERR : read error. * SPI_FLASH_RESULT_TIMEOUT : read timeout. */ SpiFlashOpResult SPI_read_status_high(uint32_t *status); /** * @brief Write status to Falsh status register. * Please do not call this function in SDK. * * @param SpiFlashChip *spi : The information for Flash, which is exported from ld file. * * @param uint32_t status_value : Value to . * * @return SPI_FLASH_RESULT_OK : write OK. * SPI_FLASH_RESULT_ERR : write error. * SPI_FLASH_RESULT_TIMEOUT : write timeout. */ SpiFlashOpResult SPI_write_status(SpiFlashChip *spi, uint32_t status_value); /** * @brief Use a command to Read Flash status register. * Please do not call this function in SDK. * * @param SpiFlashChip *spi : The information for Flash, which is exported from ld file. * * @param uint32_t*status : The pointer to which to return the Flash status value. * * @return SPI_FLASH_RESULT_OK : read OK. * SPI_FLASH_RESULT_ERR : read error. * SPI_FLASH_RESULT_TIMEOUT : read timeout. */ SpiFlashOpResult SPI_user_command_read(uint32_t *status, uint8_t cmd); /** * @brief Config SPI Flash read mode when init. * Please do not call this function in SDK. * * @param SpiFlashRdMode mode : QIO/QOUT/DIO/DOUT/FastRD/SlowRD. * * @param uint8_t legacy: In legacy mode, more SPI command is used in line. * * @return SPI_FLASH_RESULT_OK : config OK. * SPI_FLASH_RESULT_ERR : config error. * SPI_FLASH_RESULT_TIMEOUT : config timeout. */ SpiFlashOpResult SPIReadModeCnfig(SpiFlashRdMode mode, bool legacy); /** * @brief Config SPI Flash read mode when Flash is running in some mode. * Please do not call this function in SDK. * * @param SpiFlashRdMode mode : QIO/QOUT/DIO/DOUT/FastRD/SlowRD. * * @return SPI_FLASH_RESULT_OK : config OK. * SPI_FLASH_RESULT_ERR : config error. * SPI_FLASH_RESULT_TIMEOUT : config timeout. */ SpiFlashOpResult SPIMasterReadModeCnfig(SpiFlashRdMode mode); /** * @brief Config SPI Flash clock divisor. * Please do not call this function in SDK. * * @param uint8_t freqdiv: clock divisor. * * @param uint8_t spi: 0 for SPI0, 1 for SPI1. * * @return SPI_FLASH_RESULT_OK : config OK. * SPI_FLASH_RESULT_ERR : config error. * SPI_FLASH_RESULT_TIMEOUT : config timeout. */ SpiFlashOpResult SPIClkConfig(uint8_t freqdiv, uint8_t spi); /** * @brief Send CommonCmd to Flash so that is can go into QIO mode, some Flash use different CMD. * Please do not call this function in SDK. * * @param SpiCommonCmd *cmd : A struct to show the action of a command. * * @return uint16_t 0 : do not send command any more. * 1 : go to the next command. * n > 1 : skip (n - 1) commands. */ uint16_t SPI_Common_Command(SpiCommonCmd *cmd); /** * @brief Unlock SPI write protect. * Please do not call this function in SDK. * * @param None. * * @return SPI_FLASH_RESULT_OK : Unlock OK. * SPI_FLASH_RESULT_ERR : Unlock error. * SPI_FLASH_RESULT_TIMEOUT : Unlock timeout. */ SpiFlashOpResult SPIUnlock(void); /** * @brief SPI write protect. * Please do not call this function in SDK. * * @param None. * * @return SPI_FLASH_RESULT_OK : Lock OK. * SPI_FLASH_RESULT_ERR : Lock error. * SPI_FLASH_RESULT_TIMEOUT : Lock timeout. */ SpiFlashOpResult SPILock(void); /** * @brief Update SPI Flash parameter. * Please do not call this function in SDK. * * @param uint32_t deviceId : Device ID read from SPI, the low 32 bit. * * @param uint32_t chip_size : The Flash size. * * @param uint32_t block_size : The Flash block size. * * @param uint32_t sector_size : The Flash sector size. * * @param uint32_t page_size : The Flash page size. * * @param uint32_t status_mask : The Mask used when read status from Flash(use single CMD). * * @return SPI_FLASH_RESULT_OK : Update OK. * SPI_FLASH_RESULT_ERR : Update error. * SPI_FLASH_RESULT_TIMEOUT : Update timeout. */ SpiFlashOpResult SPIParamCfg(uint32_t deviceId, uint32_t chip_size, uint32_t block_size, uint32_t sector_size, uint32_t page_size, uint32_t status_mask); /** * @brief Erase whole flash chip. * Please do not call this function in SDK. * * @param None * * @return SPI_FLASH_RESULT_OK : Erase OK. * SPI_FLASH_RESULT_ERR : Erase error. * SPI_FLASH_RESULT_TIMEOUT : Erase timeout. */ SpiFlashOpResult SPIEraseChip(void); /** * @brief Erase a 64KB block of flash * Uses SPI flash command D8H. * Please do not call this function in SDK. * * @param uint32_t block_num : Which block to erase. * * @return SPI_FLASH_RESULT_OK : Erase OK. * SPI_FLASH_RESULT_ERR : Erase error. * SPI_FLASH_RESULT_TIMEOUT : Erase timeout. */ SpiFlashOpResult SPIEraseBlock(uint32_t block_num); /** * @brief Erase a sector of flash. * Uses SPI flash command 20H. * Please do not call this function in SDK. * * @param uint32_t sector_num : Which sector to erase. * * @return SPI_FLASH_RESULT_OK : Erase OK. * SPI_FLASH_RESULT_ERR : Erase error. * SPI_FLASH_RESULT_TIMEOUT : Erase timeout. */ SpiFlashOpResult SPIEraseSector(uint32_t sector_num); /** * @brief Erase some sectors. * Please do not call this function in SDK. * * @param uint32_t start_addr : Start addr to erase, should be sector aligned. * * @param uint32_t area_len : Length to erase, should be sector aligned. * * @return SPI_FLASH_RESULT_OK : Erase OK. * SPI_FLASH_RESULT_ERR : Erase error. * SPI_FLASH_RESULT_TIMEOUT : Erase timeout. */ SpiFlashOpResult SPIEraseArea(uint32_t start_addr, uint32_t area_len); /** * @brief Write Data to Flash, you should Erase it yourself if need. * Please do not call this function in SDK. * * @param uint32_t dest_addr : Address to write, should be 4 bytes aligned. * * @param const uint32_t *src : The pointer to data which is to write. * * @param uint32_t len : Length to write, should be 4 bytes aligned. * * @return SPI_FLASH_RESULT_OK : Write OK. * SPI_FLASH_RESULT_ERR : Write error. * SPI_FLASH_RESULT_TIMEOUT : Write timeout. */ SpiFlashOpResult SPIWrite(uint32_t dest_addr, const uint32_t *src, int32_t len); /** * @brief Read Data from Flash, you should Erase it yourself if need. * Please do not call this function in SDK. * * @param uint32_t src_addr : Address to read, should be 4 bytes aligned. * * @param uint32_t *dest : The buf to read the data. * * @param uint32_t len : Length to read, should be 4 bytes aligned. * * @return SPI_FLASH_RESULT_OK : Read OK. * SPI_FLASH_RESULT_ERR : Read error. * SPI_FLASH_RESULT_TIMEOUT : Read timeout. */ SpiFlashOpResult SPIRead(uint32_t src_addr, uint32_t *dest, int32_t len); /** * @brief SPI1 go into encrypto mode. * Please do not call this function in SDK. * * @param None * * @return None */ void SPI_Write_Encrypt_Enable(void); /** * @brief Prepare 32 Bytes data to encrpto writing, you should Erase it yourself if need. * Please do not call this function in SDK. * * @param uint32_t flash_addr : Address to write, should be 32 bytes aligned. * * @param uint32_t *data : The pointer to data which is to write. * * @return SPI_FLASH_RESULT_OK : Prepare OK. * SPI_FLASH_RESULT_ERR : Prepare error. * SPI_FLASH_RESULT_TIMEOUT : Prepare timeout. */ SpiFlashOpResult SPI_Prepare_Encrypt_Data(uint32_t flash_addr, uint32_t *data); /** * @brief SPI1 go out of encrypto mode. * Please do not call this function in SDK. * * @param None * * @return None */ void SPI_Write_Encrypt_Disable(void); /** * @brief Write data to flash with transparent encryption. * @note Sectors to be written should already be erased. * * @note Please do not call this function in SDK. * * @param uint32_t flash_addr : Address to write, should be 32 byte aligned. * * @param uint32_t *data : The pointer to data to write. Note, this pointer must * be 32 bit aligned and the content of the data will be * modified by the encryption function. * * @param uint32_t len : Length to write, should be 32 bytes aligned. * * @return SPI_FLASH_RESULT_OK : Data written successfully. * SPI_FLASH_RESULT_ERR : Encrypto write error. * SPI_FLASH_RESULT_TIMEOUT : Encrypto write timeout. */ SpiFlashOpResult SPI_Encrypt_Write(uint32_t flash_addr, uint32_t *data, uint32_t len); /** @brief Global SpiFlashChip structure used by ROM functions * */ extern SpiFlashChip g_rom_flashchip; /** * @} */ #ifdef __cplusplus } #endif #endif /* _ROM_SPI_FLASH_H_ */