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 } spi_flash_trans_t; 41 42 /** 43 * @brief SPI flash clock speed values, always refer to them by the enum rather 44 * than the actual value (more speed may be appended into the list). 45 * 46 * A strategy to select the maximum allowed speed is to enumerate from the 47 * ``ESP_FLSH_SPEED_MAX-1`` or highest frequency supported by your flash, and 48 * decrease the speed until the probing success. 49 */ 50 typedef enum { 51 ESP_FLASH_5MHZ = 0, ///< The flash runs under 5MHz 52 ESP_FLASH_10MHZ, ///< The flash runs under 10MHz 53 ESP_FLASH_20MHZ, ///< The flash runs under 20MHz 54 ESP_FLASH_26MHZ, ///< The flash runs under 26MHz 55 ESP_FLASH_40MHZ, ///< The flash runs under 40MHz 56 ESP_FLASH_80MHZ, ///< The flash runs under 80MHz 57 ESP_FLASH_SPEED_MAX, ///< The maximum frequency supported by the host is ``ESP_FLASH_SPEED_MAX-1``. 58 } esp_flash_speed_t; 59 60 ///Lowest speed supported by the driver, currently 5 MHz 61 #define ESP_FLASH_SPEED_MIN ESP_FLASH_5MHZ 62 63 // These bits are not quite like "IO mode", but are able to be appended into the io mode and used by the HAL. 64 #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) 65 66 /** @brief Mode used for reading from SPI flash */ 67 typedef enum { 68 SPI_FLASH_SLOWRD = 0, ///< Data read using single I/O, some limits on speed 69 SPI_FLASH_FASTRD, ///< Data read using single I/O, no limit on speed 70 SPI_FLASH_DOUT, ///< Data read using dual I/O 71 SPI_FLASH_DIO, ///< Both address & data transferred using dual I/O 72 SPI_FLASH_QOUT, ///< Data read using quad I/O 73 SPI_FLASH_QIO, ///< Both address & data transferred using quad I/O 74 75 SPI_FLASH_READ_MODE_MAX, ///< The fastest io mode supported by the host is ``ESP_FLASH_READ_MODE_MAX-1``. 76 } esp_flash_io_mode_t; 77 78 /// Configuration structure for the flash chip suspend feature. 79 typedef struct { 80 uint32_t sus_mask; ///< SUS/SUS1/SUS2 bit in flash register. 81 struct { 82 uint32_t cmd_rdsr :8; ///< Read flash status register(2) command. 83 uint32_t sus_cmd :8; ///< Flash suspend command. 84 uint32_t res_cmd :8; ///< Flash resume command. 85 uint32_t reserved :8; ///< Reserved, set to 0. 86 }; 87 } spi_flash_sus_cmd_conf; 88 89 ///Slowest io mode supported by ESP32, currently SlowRd 90 #define SPI_FLASH_READ_MODE_MIN SPI_FLASH_SLOWRD 91 92 struct spi_flash_host_driver_s; 93 typedef struct spi_flash_host_driver_s spi_flash_host_driver_t; 94 95 /** SPI Flash Host driver instance */ 96 typedef struct { 97 const struct spi_flash_host_driver_s* driver; ///< Pointer to the implementation function table 98 // Implementations can wrap this structure into their own ones, and append other data here 99 } spi_flash_host_inst_t ; 100 101 102 /** Host driver configuration and context structure. */ 103 struct spi_flash_host_driver_s { 104 /** 105 * Configure the device-related register before transactions. This saves 106 * some time to re-configure those registers when we send continuously 107 */ 108 esp_err_t (*dev_config)(spi_flash_host_inst_t *host); 109 /** 110 * Send an user-defined spi transaction to the device. 111 */ 112 esp_err_t (*common_command)(spi_flash_host_inst_t *host, spi_flash_trans_t *t); 113 /** 114 * Read flash ID. 115 */ 116 esp_err_t (*read_id)(spi_flash_host_inst_t *host, uint32_t *id); 117 /** 118 * Erase whole flash chip. 119 */ 120 void (*erase_chip)(spi_flash_host_inst_t *host); 121 /** 122 * Erase a specific sector by its start address. 123 */ 124 void (*erase_sector)(spi_flash_host_inst_t *host, uint32_t start_address); 125 /** 126 * Erase a specific block by its start address. 127 */ 128 void (*erase_block)(spi_flash_host_inst_t *host, uint32_t start_address); 129 /** 130 * Read the status of the flash chip. 131 */ 132 esp_err_t (*read_status)(spi_flash_host_inst_t *host, uint8_t *out_sr); 133 /** 134 * Disable write protection. 135 */ 136 esp_err_t (*set_write_protect)(spi_flash_host_inst_t *host, bool wp); 137 /** 138 * Program a page of the flash. Check ``max_write_bytes`` for the maximum allowed writing length. 139 */ 140 void (*program_page)(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length); 141 /** Check whether given buffer can be directly used to write */ 142 bool (*supports_direct_write)(spi_flash_host_inst_t *host, const void *p); 143 /** 144 * Slicer for write data. The `program_page` should be called iteratively with the return value 145 * of this function. 146 * 147 * @param address Beginning flash address to write 148 * @param len Length request to write 149 * @param align_addr Output of the aligned address to write to 150 * @param page_size Physical page size of the flash chip 151 * @return Length that can be actually written in one `program_page` call 152 */ 153 int (*write_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, 154 uint32_t page_size); 155 /** 156 * Read data from the flash. Check ``max_read_bytes`` for the maximum allowed reading length. 157 */ 158 esp_err_t (*read)(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len); 159 /** Check whether given buffer can be directly used to read */ 160 bool (*supports_direct_read)(spi_flash_host_inst_t *host, const void *p); 161 /** 162 * Slicer for read data. The `read` should be called iteratively with the return value 163 * of this function. 164 * 165 * @param address Beginning flash address to read 166 * @param len Length request to read 167 * @param align_addr Output of the aligned address to read 168 * @param page_size Physical page size of the flash chip 169 * @return Length that can be actually read in one `read` call 170 */ 171 int (*read_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size); 172 /** 173 * Check the host status, 0:busy, 1:idle, 2:suspended. 174 */ 175 uint32_t (*host_status)(spi_flash_host_inst_t *host); 176 /** 177 * Configure the host to work at different read mode. Responsible to compensate the timing and set IO mode. 178 */ 179 esp_err_t (*configure_host_io_mode)(spi_flash_host_inst_t *host, uint32_t command, 180 uint32_t addr_bitlen, int dummy_bitlen_base, 181 esp_flash_io_mode_t io_mode); 182 /** 183 * Internal use, poll the HW until the last operation is done. 184 */ 185 void (*poll_cmd_done)(spi_flash_host_inst_t *host); 186 /** 187 * For some host (SPI1), they are shared with a cache. When the data is 188 * modified, the cache needs to be flushed. Left NULL if not supported. 189 */ 190 esp_err_t (*flush_cache)(spi_flash_host_inst_t* host, uint32_t addr, uint32_t size); 191 192 /** 193 * Suspend check erase/program operation, reserved for ESP32-C3 and ESP32-S3 spi flash ROM IMPL. 194 */ 195 void (*check_suspend)(spi_flash_host_inst_t *host); 196 197 /** 198 * Resume flash from suspend manually 199 */ 200 void (*resume)(spi_flash_host_inst_t *host); 201 202 /** 203 * Set flash in suspend status manually 204 */ 205 void (*suspend)(spi_flash_host_inst_t *host); 206 207 /** 208 * Suspend feature setup for setting cmd and status register mask. 209 */ 210 esp_err_t (*sus_setup)(spi_flash_host_inst_t *host, const spi_flash_sus_cmd_conf *sus_conf); 211 }; 212 213 #ifdef __cplusplus 214 } 215 #endif 216