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 <esp_types.h> 10 #include <esp_bit_defs.h> 11 #include "esp_flash_err.h" 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /** Definition of a common transaction. Also holds the return value. */ 18 typedef struct { 19 uint8_t reserved; ///< Reserved, must be 0. 20 uint8_t mosi_len; ///< Output data length, in bytes 21 uint8_t miso_len; ///< Input data length, in bytes 22 uint8_t address_bitlen; ///< Length of address in bits, set to 0 if command does not need an address 23 uint32_t address; ///< Address to perform operation on 24 const uint8_t *mosi_data; ///< Output data to salve 25 uint8_t *miso_data; ///< [out] Input data from slave, little endian 26 uint32_t flags; ///< Flags for this transaction. Set to 0 for now. 27 #define SPI_FLASH_TRANS_FLAG_CMD16 BIT(0) ///< Send command of 16 bits 28 #define SPI_FLASH_TRANS_FLAG_IGNORE_BASEIO BIT(1) ///< Not applying the basic io mode configuration for this transaction 29 #define SPI_FLASH_TRANS_FLAG_BYTE_SWAP BIT(2) ///< Used for DTR mode, to swap the bytes of a pair of rising/falling edge 30 uint16_t command; ///< Command to send 31 uint8_t dummy_bitlen; ///< Basic dummy bits to use 32 uint32_t io_mode; ///< Flash working mode when `SPI_FLASH_IGNORE_BASEIO` is specified. 33 } spi_flash_trans_t; 34 35 /** 36 * @brief SPI flash clock speed values, always refer to them by the enum rather 37 * than the actual value (more speed may be appended into the list). 38 * 39 * A strategy to select the maximum allowed speed is to enumerate from the 40 * ``ESP_FLSH_SPEED_MAX-1`` or highest frequency supported by your flash, and 41 * decrease the speed until the probing success. 42 */ 43 typedef enum esp_flash_speed_s { 44 ESP_FLASH_5MHZ = 5, ///< The flash runs under 5MHz 45 ESP_FLASH_10MHZ = 10, ///< The flash runs under 10MHz 46 ESP_FLASH_20MHZ = 20, ///< The flash runs under 20MHz 47 ESP_FLASH_26MHZ = 26, ///< The flash runs under 26MHz 48 ESP_FLASH_40MHZ = 40, ///< The flash runs under 40MHz 49 ESP_FLASH_80MHZ = 80, ///< The flash runs under 80MHz 50 ESP_FLASH_120MHZ = 120, ///< The flash runs under 120MHz, 120MHZ can only be used by main flash after timing tuning in system. Do not use this directely in any API. 51 ESP_FLASH_SPEED_MAX, ///< The maximum frequency supported by the host is ``ESP_FLASH_SPEED_MAX-1``. 52 } esp_flash_speed_t __attribute__((deprecated)); 53 54 // These bits are not quite like "IO mode", but are able to be appended into the io mode and used by the HAL. 55 #define SPI_FLASH_CONFIG_CONF_BITS BIT(31) ///< OR the io_mode with this mask, to enable the dummy output feature or replace the first several dummy bits into address to meet the requirements of conf bits. (Used in DIO/QIO/OIO mode) 56 57 /** @brief Mode used for reading from SPI flash */ 58 typedef enum { 59 SPI_FLASH_SLOWRD = 0, ///< Data read using single I/O, some limits on speed 60 SPI_FLASH_FASTRD, ///< Data read using single I/O, no limit on speed 61 SPI_FLASH_DOUT, ///< Data read using dual I/O 62 SPI_FLASH_DIO, ///< Both address & data transferred using dual I/O 63 SPI_FLASH_QOUT, ///< Data read using quad I/O 64 SPI_FLASH_QIO, ///< Both address & data transferred using quad I/O 65 #define SPI_FLASH_OPI_FLAG 16 ///< A flag for flash work in opi mode, the io mode below are opi, above are SPI/QSPI mode. DO NOT use this value in any API. 66 SPI_FLASH_OPI_STR = SPI_FLASH_OPI_FLAG,///< Only support on OPI flash, flash read and write under STR mode 67 SPI_FLASH_OPI_DTR,///< Only support on OPI flash, flash read and write under DTR mode 68 SPI_FLASH_READ_MODE_MAX, ///< The fastest io mode supported by the host is ``ESP_FLASH_READ_MODE_MAX-1``. 69 } esp_flash_io_mode_t; 70 71 /// Configuration structure for the flash chip suspend feature. 72 typedef struct { 73 uint32_t sus_mask; ///< SUS/SUS1/SUS2 bit in flash register. 74 struct { 75 uint32_t cmd_rdsr :8; ///< Read flash status register(2) command. 76 uint32_t sus_cmd :8; ///< Flash suspend command. 77 uint32_t res_cmd :8; ///< Flash resume command. 78 uint32_t reserved :8; ///< Reserved, set to 0. 79 }; 80 } spi_flash_sus_cmd_conf; 81 82 /// Structure for flash encryption operations. 83 typedef struct 84 { 85 /** 86 * @brief Enable the flash encryption 87 */ 88 void (*flash_encryption_enable)(void); 89 /** 90 * @brief Disable the flash encryption 91 */ 92 void (*flash_encryption_disable)(void); 93 /** 94 * Prepare flash encryption before operation. 95 * 96 * @param address The destination address in flash for the write operation. 97 * @param buffer Data for programming 98 * @param size Size to program. 99 * 100 * @note address and buffer must be 8-word aligned. 101 */ 102 void (*flash_encryption_data_prepare)(uint32_t address, const uint32_t* buffer, uint32_t size); 103 /** 104 * @brief flash data encryption operation is done. 105 */ 106 void (*flash_encryption_done)(void); 107 /** 108 * Destroy encrypted result 109 */ 110 void (*flash_encryption_destroy)(void); 111 /** 112 * Check if is qualified to encrypt the buffer 113 * 114 * @param address the address of written flash partition. 115 * @param length Buffer size. 116 */ 117 bool (*flash_encryption_check)(uint32_t address, uint32_t length); 118 } spi_flash_encryption_t; 119 120 ///Slowest io mode supported by ESP32, currently SlowRd 121 #define SPI_FLASH_READ_MODE_MIN SPI_FLASH_SLOWRD 122 123 struct spi_flash_host_driver_s; 124 typedef struct spi_flash_host_driver_s spi_flash_host_driver_t; 125 126 /** SPI Flash Host driver instance */ 127 typedef struct { 128 const struct spi_flash_host_driver_s* driver; ///< Pointer to the implementation function table 129 // Implementations can wrap this structure into their own ones, and append other data here 130 } spi_flash_host_inst_t ; 131 132 133 /** Host driver configuration and context structure. */ 134 struct spi_flash_host_driver_s { 135 /** 136 * Configure the device-related register before transactions. This saves 137 * some time to re-configure those registers when we send continuously 138 */ 139 esp_err_t (*dev_config)(spi_flash_host_inst_t *host); 140 /** 141 * Send an user-defined spi transaction to the device. 142 */ 143 esp_err_t (*common_command)(spi_flash_host_inst_t *host, spi_flash_trans_t *t); 144 /** 145 * Read flash ID. 146 */ 147 esp_err_t (*read_id)(spi_flash_host_inst_t *host, uint32_t *id); 148 /** 149 * Erase whole flash chip. 150 */ 151 void (*erase_chip)(spi_flash_host_inst_t *host); 152 /** 153 * Erase a specific sector by its start address. 154 */ 155 void (*erase_sector)(spi_flash_host_inst_t *host, uint32_t start_address); 156 /** 157 * Erase a specific block by its start address. 158 */ 159 void (*erase_block)(spi_flash_host_inst_t *host, uint32_t start_address); 160 /** 161 * Read the status of the flash chip. 162 */ 163 esp_err_t (*read_status)(spi_flash_host_inst_t *host, uint8_t *out_sr); 164 /** 165 * Disable write protection. 166 */ 167 esp_err_t (*set_write_protect)(spi_flash_host_inst_t *host, bool wp); 168 /** 169 * Program a page of the flash. Check ``max_write_bytes`` for the maximum allowed writing length. 170 */ 171 void (*program_page)(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length); 172 /** 173 * @brief Check whether the SPI host supports direct write 174 * 175 * When cache is disabled, SPI1 doesn't support directly write when buffer isn't internal. 176 */ 177 bool (*supports_direct_write)(spi_flash_host_inst_t *host, const void *p); 178 /** 179 * Slicer for write data. The `program_page` should be called iteratively with the return value 180 * of this function. 181 * 182 * @param address Beginning flash address to write 183 * @param len Length request to write 184 * @param align_addr Output of the aligned address to write to 185 * @param page_size Physical page size of the flash chip 186 * @return Length that can be actually written in one `program_page` call 187 */ 188 int (*write_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, 189 uint32_t page_size); 190 /** 191 * Read data from the flash. Check ``max_read_bytes`` for the maximum allowed reading length. 192 */ 193 esp_err_t (*read)(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len); 194 /** 195 * @brief Check whether the SPI host supports direct read 196 * 197 * When cache is disabled, SPI1 doesn't support directly read when the given buffer isn't internal. 198 */ 199 bool (*supports_direct_read)(spi_flash_host_inst_t *host, const void *p); 200 /** 201 * Slicer for read data. The `read` should be called iteratively with the return value 202 * of this function. 203 * 204 * @param address Beginning flash address to read 205 * @param len Length request to read 206 * @param align_addr Output of the aligned address to read 207 * @param page_size Physical page size of the flash chip 208 * @return Length that can be actually read in one `read` call 209 */ 210 int (*read_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size); 211 /** 212 * Check the host status, 0:busy, 1:idle, 2:suspended. 213 */ 214 uint32_t (*host_status)(spi_flash_host_inst_t *host); 215 /** 216 * Configure the host to work at different read mode. Responsible to compensate the timing and set IO mode. 217 */ 218 esp_err_t (*configure_host_io_mode)(spi_flash_host_inst_t *host, uint32_t command, 219 uint32_t addr_bitlen, int dummy_bitlen_base, 220 esp_flash_io_mode_t io_mode); 221 /** 222 * Internal use, poll the HW until the last operation is done. 223 */ 224 void (*poll_cmd_done)(spi_flash_host_inst_t *host); 225 /** 226 * For some host (SPI1), they are shared with a cache. When the data is 227 * modified, the cache needs to be flushed. Left NULL if not supported. 228 */ 229 esp_err_t (*flush_cache)(spi_flash_host_inst_t* host, uint32_t addr, uint32_t size); 230 231 /** 232 * Suspend check erase/program operation, reserved for ESP32-C3 and ESP32-S3 spi flash ROM IMPL. 233 */ 234 void (*check_suspend)(spi_flash_host_inst_t *host); 235 236 /** 237 * Resume flash from suspend manually 238 */ 239 void (*resume)(spi_flash_host_inst_t *host); 240 241 /** 242 * Set flash in suspend status manually 243 */ 244 void (*suspend)(spi_flash_host_inst_t *host); 245 246 /** 247 * Suspend feature setup for setting cmd and status register mask. 248 */ 249 esp_err_t (*sus_setup)(spi_flash_host_inst_t *host, const spi_flash_sus_cmd_conf *sus_conf); 250 }; 251 252 #ifdef __cplusplus 253 } 254 #endif 255
