1 // Copyright 2015-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 #include "esp_flash.h" 17 #include "esp_attr.h" 18 19 struct esp_flash_t; 20 typedef struct esp_flash_t esp_flash_t; 21 22 typedef struct spi_flash_chip_t spi_flash_chip_t; 23 24 /** Timeout configurations for flash operations, all in us */ 25 typedef struct { 26 uint32_t idle_timeout; ///< Default timeout for other commands to be sent by host and get done by flash 27 uint32_t chip_erase_timeout; ///< Timeout for chip erase operation 28 uint32_t block_erase_timeout; ///< Timeout for block erase operation 29 uint32_t sector_erase_timeout; ///< Timeout for sector erase operation 30 uint32_t page_program_timeout; ///< Timeout for page program operation 31 } flash_chip_op_timeout_t; 32 33 typedef enum { 34 SPI_FLASH_REG_STATUS = 1, 35 } spi_flash_register_t; 36 37 typedef enum { 38 SPI_FLASH_CHIP_CAP_SUSPEND = BIT(0), ///< Flash chip support suspend feature. 39 SPI_FLASH_CHIP_CAP_32MB_SUPPORT = BIT(1), ///< Flash chip driver support flash size larger than 32M Bytes. 40 SPI_FLASH_CHIP_CAP_UNIQUE_ID = BIT(2), ///< Flash chip driver support read the flash unique id. 41 } spi_flash_caps_t; 42 FLAG_ATTR(spi_flash_caps_t) 43 44 /** @brief SPI flash chip driver definition structure. 45 * 46 * The chip driver structure contains chip-specific pointers to functions to perform SPI flash operations, and some 47 * chip-specific numeric values. 48 * 49 * @note This is not a public API. These functions are called from the public API (declared in 50 * esp_flash.h). They assume the caller has already validated arguments and enabled relevant protections 51 * (disabling flash cache, prevent concurrent SPI access, etc.) 52 * 53 * Do not call chip driver functions directly in other contexts. 54 * 55 * A generic driver for generic chips and its related operations are defined in 56 * spi_flash_chip_generic.h which can be used as building blocks for written 57 * new/specific SPI flash chip drivers. 58 * 59 * @note All of these functions may be called with SPI flash cache disabled, so must only ever access IRAM/DRAM/ROM. 60 */ 61 struct spi_flash_chip_t { 62 const char *name; ///< Name of the chip driver 63 const flash_chip_op_timeout_t *timeout; ///< Timeout configuration for this chip 64 /* Probe to detect if a supported SPI flash chip is found. 65 * 66 * Attempts to configure 'chip' with these operations and probes for a matching SPI flash chip. 67 * 68 * Auto-detection of a SPI flash chip calls this function in turn on each registered driver (see esp_flash_registered_flash_drivers). 69 * 70 * ID - as read by spi_flash_generic_read_id() - is supplied so each probe 71 * function doesn't need to unnecessarily read ID, but probe is permitted 72 * to interrogate flash in any non-destructive way. 73 * 74 * It is permissible for the driver to modify the 'chip' structure if probing succeeds (specifically, to assign something to the 75 * driver_data pointer if that is useful for the driver.) 76 * 77 * @return ESP_OK if probing was successful, an error otherwise. Driver may 78 * assume that returning ESP_OK means it has claimed this chip. 79 */ 80 esp_err_t (*probe)(esp_flash_t *chip, uint32_t flash_id); 81 82 esp_err_t (*reset)(esp_flash_t *chip); 83 84 85 /* Detect SPI flash size 86 * 87 * Interrogate the chip to detect its size. 88 */ 89 esp_err_t (*detect_size)(esp_flash_t *chip, uint32_t *size); 90 91 /* Erase the entire chip 92 93 Caller has verified the chip is not write protected. 94 */ 95 esp_err_t (*erase_chip)(esp_flash_t *chip); 96 97 /* Erase a sector of the chip. Sector size is specified in the 'sector_size' field. 98 99 sector_address is an offset in bytes. 100 101 Caller has verified that this sector should be non-write-protected. 102 */ 103 esp_err_t (*erase_sector)(esp_flash_t *chip, uint32_t sector_address); 104 105 /* Erase a multi-sector block of the chip. Block size is specified in the 'block_erase_size' field. 106 sector_address is an offset in bytes. 107 108 Caller has verified that this block should be non-write-protected. 109 */ 110 esp_err_t (*erase_block)(esp_flash_t *chip, uint32_t block_address); 111 112 uint32_t sector_size; /* Sector is minimum erase size */ 113 uint32_t block_erase_size; /* Optimal (fastest) block size for multi-sector erases on this chip */ 114 115 /* Read the write protect status of the entire chip. */ 116 esp_err_t (*get_chip_write_protect)(esp_flash_t *chip, bool *out_write_protected); 117 118 /* Set the write protect status of the entire chip. */ 119 esp_err_t (*set_chip_write_protect)(esp_flash_t *chip, bool chip_write_protect); 120 121 /* Number of individually write protectable regions on this chip. Range 0-63. */ 122 uint8_t num_protectable_regions; 123 /* Pointer to an array describing each protectable region. Should have num_protectable_regions elements. */ 124 const esp_flash_region_t *protectable_regions; 125 /* Get a bitmask describing all protectable regions on the chip. Each bit represents one entry in the 126 protectable_regions array, ie bit (1<<N) is set then the region at array entry N is write protected. */ 127 esp_err_t (*get_protected_regions)(esp_flash_t *chip, uint64_t *regions); 128 129 /* Set protectable regions on the chip. Each bit represents on entry in the protectable regions array. */ 130 esp_err_t (*set_protected_regions)(esp_flash_t *chip, uint64_t regions); 131 132 /* Read data from the chip. 133 * 134 * Before calling this function, the caller will have called chip->drv->set_read_mode(chip) in order to configure the chip's read mode correctly. 135 */ 136 esp_err_t (*read)(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length); 137 138 /* Write any amount of data to the chip. 139 */ 140 esp_err_t (*write)(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length); 141 142 143 /* Use the page program command to write data to the chip. 144 * 145 * This function is expected to be called by chip->drv->write (if the 146 * chip->drv->write implementation doesn't call it then it can be left as NULL.) 147 * 148 * - The length argument supplied to this function is at most 'page_size' bytes. 149 * 150 * - The region between 'address' and 'address + length' will not cross a page_size aligned boundary (the write 151 * implementation is expected to split such a write into two before calling page_program.) 152 */ 153 esp_err_t (*program_page)(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length); 154 155 /* Page size as written by the page_program function. Usually 256 bytes. */ 156 uint32_t page_size; 157 158 /* Perform an encrypted write to the chip, using internal flash encryption hardware. */ 159 esp_err_t (*write_encrypted)(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length); 160 161 162 /* Wait for the SPI flash chip to be idle (any write operation to be complete.) This function is both called from the higher-level API functions, and from other functions in this structure. 163 164 timeout_ms should be a timeout (in milliseconds) before the function returns ESP_ERR_TIMEOUT. This is useful to avoid hanging 165 if the chip is otherwise unresponsive (ie returns all 0xFF or similar.) 166 */ 167 esp_err_t (*wait_idle)(esp_flash_t *chip, uint32_t timeout_us); 168 169 /* Configure both the SPI host and the chip for the read mode specified in chip->read_mode. 170 * 171 * This function is called by the higher-level API before the 'read' function is called. 172 * 173 * Can return ESP_ERR_FLASH_UNSUPPORTED_HOST or ESP_ERR_FLASH_UNSUPPORTED_CHIP if the specified mode is unsupported. 174 */ 175 esp_err_t (*set_io_mode)(esp_flash_t *chip); 176 177 /* 178 * Get whether the Quad Enable (QE) is set. (*out_io_mode)=SPI_FLASH_QOUT if 179 * enabled, otherwise disabled 180 */ 181 esp_err_t (*get_io_mode)(esp_flash_t *chip, esp_flash_io_mode_t* out_io_mode); 182 183 /* 184 * Read the chip ID. Called when chip driver is set, but we want to know the exact chip id (to 185 * get the size, etc.). 186 */ 187 esp_err_t (*read_id)(esp_flash_t *chip, uint32_t* out_chip_id); 188 189 /* 190 * Read the requested register (status, etc.). 191 */ 192 esp_err_t (*read_reg)(esp_flash_t *chip, spi_flash_register_t reg_id, uint32_t* out_reg); 193 194 /** Yield to other tasks. Called during erase operations. */ 195 esp_err_t (*yield)(esp_flash_t *chip, uint32_t wip); 196 197 /** Setup flash suspend configuration. */ 198 esp_err_t (*sus_setup)(esp_flash_t *chip); 199 200 /** 201 * Read the chip unique ID. 202 */ 203 esp_err_t (*read_unique_id)(esp_flash_t *chip, uint64_t* flash_unique_id); 204 205 /** 206 * Get the capabilities of the flash chip. See SPI_FLASH_CHIP_CAP_* macros as reference. 207 */ 208 spi_flash_caps_t (*get_chip_caps)(esp_flash_t *chip); 209 210 /** 211 * Configure the host registers to use the specified read mode set in the ``chip->read_mode``. 212 */ 213 esp_err_t (*config_host_io_mode)(esp_flash_t *chip, uint32_t flags); 214 }; 215 216 /* Pointer to an array of pointers to all known drivers for flash chips. This array is used 217 by esp_flash_init() to detect the flash chip driver, if none is supplied by the caller. 218 219 Array is terminated with a NULL pointer. 220 221 This pointer can be overwritten with a pointer to a new array, to update the list of known flash chips. 222 */ 223 extern const spi_flash_chip_t **esp_flash_registered_chips; 224
