/*
* SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include "sdkconfig.h"
#include <stdint.h>
#include <stdbool.h>
#include "esp_rom_spiflash_defs.h"
#ifdef __cplusplus
extern "C" {
#endif
typedef enum {
ESP_ROM_SPIFLASH_QIO_MODE = 0,
ESP_ROM_SPIFLASH_QOUT_MODE,
ESP_ROM_SPIFLASH_DIO_MODE,
ESP_ROM_SPIFLASH_DOUT_MODE,
ESP_ROM_SPIFLASH_FASTRD_MODE,
ESP_ROM_SPIFLASH_SLOWRD_MODE,
ESP_ROM_SPIFLASH_OPI_STR_MODE,
ESP_ROM_SPIFLASH_OPI_DTR_MODE,
ESP_ROM_SPIFLASH_OOUT_MODE,
ESP_ROM_SPIFLASH_OIO_STR_MODE,
ESP_ROM_SPIFLASH_OIO_DTR_MODE,
ESP_ROM_SPIFLASH_QPI_MODE,
} esp_rom_spiflash_read_mode_t;
typedef struct {
uint32_t device_id;
uint32_t chip_size; // chip size in bytes
uint32_t block_size;
uint32_t sector_size;
uint32_t page_size;
uint32_t status_mask;
} esp_rom_spiflash_chip_t;
typedef enum {
ESP_ROM_SPIFLASH_RESULT_OK,
ESP_ROM_SPIFLASH_RESULT_ERR,
ESP_ROM_SPIFLASH_RESULT_TIMEOUT
} esp_rom_spiflash_result_t;
/**
* @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: always keeping false.
*
* @return None
*/
void esp_rom_spiflash_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 esp_rom_spiflash_chip_t *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 ESP_ROM_SPIFLASH_RESULT_OK : read OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : read error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_read_status(esp_rom_spiflash_chip_t *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 esp_rom_spiflash_chip_t *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 ESP_ROM_SPIFLASH_RESULT_OK : read OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : read error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_read_statushigh(esp_rom_spiflash_chip_t *spi, uint32_t *status);
/**
* @brief Write status to Flash status register.
* Please do not call this function in SDK.
*
* @param esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file.
*
* @param uint32_t status_value : Value to .
*
* @return ESP_ROM_SPIFLASH_RESULT_OK : write OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : write error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : write timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_write_status(esp_rom_spiflash_chip_t *spi, uint32_t status_value);
/**
* @brief Use a command to Read Flash status register.
* Please do not call this function in SDK.
*
* @param esp_rom_spiflash_chip_t *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 ESP_ROM_SPIFLASH_RESULT_OK : read OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : read error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_read_user_cmd(uint32_t *status, uint8_t cmd);
/**
* @brief Config SPI Flash read mode when init.
* Please do not call this function in SDK.
*
* @param esp_rom_spiflash_read_mode_t mode : QIO/QOUT/DIO/DOUT/FastRD/SlowRD.
*
* This function does not try to set the QIO Enable bit in the status register, caller is responsible for this.
*
* @return ESP_ROM_SPIFLASH_RESULT_OK : config OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : config error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : config timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_config_readmode(esp_rom_spiflash_read_mode_t 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 ESP_ROM_SPIFLASH_RESULT_OK : config OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : config error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : config timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_config_clk(uint8_t freqdiv, uint8_t spi);
/**
* @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 ESP_ROM_SPIFLASH_RESULT_OK : Update OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : Update error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Update timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_config_param(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 ESP_ROM_SPIFLASH_RESULT_OK : Erase OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : Erase error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_erase_chip(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 ESP_ROM_SPIFLASH_RESULT_OK : Erase OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : Erase error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_erase_block(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 ESP_ROM_SPIFLASH_RESULT_OK : Erase OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : Erase error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_erase_sector(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 ESP_ROM_SPIFLASH_RESULT_OK : Erase OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : Erase error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_erase_area(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 ESP_ROM_SPIFLASH_RESULT_OK : Write OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : Write error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Write timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_write(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 ESP_ROM_SPIFLASH_RESULT_OK : Read OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : Read error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Read timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_read(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 esp_rom_spiflash_write_encrypted_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 ESP_ROM_SPIFLASH_RESULT_OK : Prepare OK.
* ESP_ROM_SPIFLASH_RESULT_ERR : Prepare error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Prepare timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_prepare_encrypted_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 esp_rom_spiflash_write_encrypted_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 ESP_ROM_SPIFLASH_RESULT_OK : Data written successfully.
* ESP_ROM_SPIFLASH_RESULT_ERR : Encryption write error.
* ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Encrypto write timeout.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_write_encrypted(uint32_t flash_addr, uint32_t *data, uint32_t len);
/** @brief Wait until SPI flash write operation is complete
*
* @note Please do not call this function in SDK.
*
* Reads the Write In Progress bit of the SPI flash status register,
* repeats until this bit is zero (indicating write complete).
*
* @return ESP_ROM_SPIFLASH_RESULT_OK : Write is complete
* ESP_ROM_SPIFLASH_RESULT_ERR : Error while reading status.
*/
esp_rom_spiflash_result_t esp_rom_spiflash_wait_idle(esp_rom_spiflash_chip_t *spi);
/** @brief Enable Quad I/O pin functions
*
* @note Please do not call this function in SDK.
*
* Sets the HD & WP pin functions for Quad I/O modes, based on the
* efuse SPI pin configuration.
*
* @param wp_gpio_num - Number of the WP pin to reconfigure for quad I/O.
*
* @param spiconfig - Pin configuration, as returned from ets_efuse_get_spiconfig().
* - If this parameter is 0, default SPI pins are used and wp_gpio_num parameter is ignored.
* - If this parameter is 1, default HSPI pins are used and wp_gpio_num parameter is ignored.
* - For other values, this parameter encodes the HD pin number and also the CLK pin number. CLK pin selection is used
* to determine if HSPI or SPI peripheral will be used (use HSPI if CLK pin is the HSPI clock pin, otherwise use SPI).
* Both HD & WP pins are configured via GPIO matrix to map to the selected peripheral.
*/
void esp_rom_spiflash_select_qio_pins(uint8_t wp_gpio_num, uint32_t spiconfig);
/**
* @brief Clear WEL bit unconditionally.
*
* @return always ESP_ROM_SPIFLASH_RESULT_OK
*/
esp_rom_spiflash_result_t esp_rom_spiflash_write_disable(void);
/**
* @brief Set WREN bit.
*
* @param esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file.
*
* @return always ESP_ROM_SPIFLASH_RESULT_OK
*/
esp_rom_spiflash_result_t esp_rom_spiflash_write_enable(esp_rom_spiflash_chip_t *spi);
/* Flash data defined in ROM*/
#if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2
extern esp_rom_spiflash_chip_t g_rom_flashchip;
extern uint8_t g_rom_spiflash_dummy_len_plus[];
#else
typedef struct {
esp_rom_spiflash_chip_t chip;
uint8_t dummy_len_plus[3];
uint8_t sig_matrix;
} esp_rom_spiflash_legacy_data_t;
extern esp_rom_spiflash_legacy_data_t *rom_spiflash_legacy_data;
#define g_rom_flashchip (rom_spiflash_legacy_data->chip)
#define g_rom_spiflash_dummy_len_plus (rom_spiflash_legacy_data->dummy_len_plus)
#endif
#ifdef __cplusplus
}
#endif