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