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 17 #include <stdint.h> 18 #include "esp_flash.h" 19 #include "spi_flash_chip_driver.h" 20 21 22 /* 23 * The 'chip_generic' SPI flash operations are a lowest common subset of SPI 24 * flash commands, that work across most chips. 25 * 26 * These can be used as-is via the esp_flash_common_chip_driver chip_drv, or 27 * they can be used as "base chip_drv" functions when creating a new 28 * spi_flash_host_driver_t chip_drv structure. 29 * 30 * All of the functions in this header are internal functions, not part of a 31 * public API. See esp_flash.h for the public API. 32 */ 33 34 /** 35 * @brief Generic probe function 36 * 37 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 38 * @param flash_id expected manufacture id. 39 * 40 * @return ESP_OK if the id read from chip->drv_read_id matches (always). 41 */ 42 esp_err_t spi_flash_chip_generic_probe(esp_flash_t *chip, uint32_t flash_id); 43 44 /** 45 * @brief Generic reset function 46 * 47 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 48 * 49 * @return ESP_OK if sending success, or error code passed from ``common_command`` or ``wait_idle`` functions of host driver. 50 */ 51 esp_err_t spi_flash_chip_generic_reset(esp_flash_t *chip); 52 53 /** 54 * @brief Generic size detection function 55 * 56 * Tries to detect the size of chip by using the lower 4 bits of the chip->drv->read_id result = N, and assuming size is 2 ^ N. 57 * 58 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 59 * @param size Output of the detected size 60 * 61 * @return 62 * - ESP_OK if success 63 * - ESP_ERR_FLASH_UNSUPPORTED_CHIP if the manufacturer id is not correct, which may means an error in the reading 64 * - or other error passed from the ``read_id`` function of host driver 65 */ 66 esp_err_t spi_flash_chip_generic_detect_size(esp_flash_t *chip, uint32_t *size); 67 68 /** 69 * @brief Erase chip by using the generic erase chip command. 70 * 71 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 72 * 73 * @return 74 * - ESP_OK if success 75 * - ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent. 76 * - or other error passed from the ``set_write_protect``, ``wait_idle`` or ``erase_chip`` function of host driver 77 */ 78 esp_err_t spi_flash_chip_generic_erase_chip(esp_flash_t *chip); 79 80 /** 81 * @brief Erase sector by using the generic sector erase command. 82 * 83 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 84 * @param start_address Start address of the sector to erase 85 * 86 * @return 87 * - ESP_OK if success 88 * - ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent. 89 * - or other error passed from the ``set_write_protect``, ``wait_idle`` or ``erase_sector`` function of host driver 90 */ 91 esp_err_t spi_flash_chip_generic_erase_sector(esp_flash_t *chip, uint32_t start_address); 92 93 /** 94 * @brief Erase block by the generic 64KB block erase command 95 * 96 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 97 * @param start_address Start address of the block to erase 98 * 99 * @return 100 * - ESP_OK if success 101 * - ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent. 102 * - or other error passed from the ``set_write_protect``, ``wait_idle`` or ``erase_block`` function of host driver 103 */ 104 esp_err_t spi_flash_chip_generic_erase_block(esp_flash_t *chip, uint32_t start_address); 105 106 /** 107 * @brief Read from flash by using a read command that matches the programmed 108 * read mode. 109 * 110 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 111 * @param buffer Buffer to hold the data read from flash 112 * @param address Start address of the data on the flash 113 * @param length Length to read 114 * 115 * @return always ESP_OK currently 116 */ 117 esp_err_t spi_flash_chip_generic_read(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length); 118 119 /** 120 * @brief Perform a page program using the page program command. 121 * 122 * @note Length of each call should not excced the limitation in 123 * ``chip->host->max_write_bytes``. This function is called in 124 * ``spi_flash_chip_generic_write`` recursively until the whole page is 125 * programmed. Strongly suggest to call ``spi_flash_chip_generic_write`` 126 * instead. 127 * 128 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 129 * @param buffer Buffer holding the data to program 130 * @param address Start address to write to flash 131 * @param length Length to write, no longer than ``chip->host->max_write_bytes``. 132 * 133 * @return 134 * - ESP_OK if success 135 * - ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent. 136 * - or other error passed from the ``wait_idle`` or ``program_page`` function of host driver 137 */ 138 esp_err_t 139 spi_flash_chip_generic_page_program(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length); 140 141 /** 142 * @brief Perform a generic write. Split the write buffer into page program 143 * operations, and call chip->chip_drv->page-program() for each. 144 * 145 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 146 * @param buffer Buffer holding the data to program 147 * @param address Start address to write to flash 148 * @param length Length to write 149 * 150 * @return 151 * - ESP_OK if success 152 * - or other error passed from the ``wait_idle`` or ``program_page`` function of host driver 153 */ 154 esp_err_t spi_flash_chip_generic_write(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length); 155 156 /** 157 * @brief Perform a write using on-chip flash encryption. Not implemented yet. 158 * 159 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 160 * @param buffer Buffer holding the data to program 161 * @param address Start address to write to flash 162 * @param length Length to write 163 * 164 * @return always ESP_ERR_FLASH_UNSUPPORTED_HOST. 165 */ 166 esp_err_t 167 spi_flash_chip_generic_write_encrypted(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length); 168 169 /** 170 * @brief Send the write enable or write disable command and verify the expected bit (1) in 171 * the status register is set. 172 * 173 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 174 * @param write_protect true to enable write protection, false to send write enable. 175 * 176 * @return 177 * - ESP_OK if success 178 * - or other error passed from the ``wait_idle``, ``read_status`` or 179 * ``set_write_protect`` function of host driver 180 */ 181 esp_err_t spi_flash_chip_generic_set_write_protect(esp_flash_t *chip, bool write_protect); 182 183 /** 184 * @brief Check whether WEL (write enable latch) bit is set in the Status Register read from RDSR. 185 * 186 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 187 * @param out_write_protect Output of whether the write protect is set. 188 * 189 * @return 190 * - ESP_OK if success 191 * - or other error passed from the ``read_status`` function of host driver 192 */ 193 esp_err_t spi_flash_chip_generic_get_write_protect(esp_flash_t *chip, bool *out_write_protect); 194 195 #define ESP_FLASH_CHIP_GENERIC_NO_TIMEOUT -1 196 /** 197 * @brief Send commands to read one of the reg of the chip 198 * 199 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 200 * @param reg_id Type of the register to read 201 * @param out_reg Output of the register value 202 * @return esp_err_t Error code passed from the ``read_status`` function of host driver. 203 */ 204 esp_err_t spi_flash_chip_generic_read_reg(esp_flash_t* chip, spi_flash_register_t reg_id, uint32_t* out_reg); 205 206 /** 207 * @brief Read flash status via the RDSR command and wait for bit 0 (write in 208 * progress bit) to be cleared. 209 * 210 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 211 * @param timeout_us Time to wait before timeout, in us. 212 * 213 * @return 214 * - ESP_OK if success 215 * - ESP_ERR_TIMEOUT if not idle before timeout 216 * - or other error passed from the ``wait_idle`` or ``read_status`` function of host driver 217 */ 218 esp_err_t spi_flash_chip_generic_wait_idle(esp_flash_t *chip, uint32_t timeout_us); 219 220 /** 221 * @brief Set the specified SPI read mode according to the data in the chip 222 * context. Set quad enable status register bit if needed. 223 * 224 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 225 * 226 * @return 227 * - ESP_OK if success 228 * - ESP_ERR_TIMEOUT if not idle before timeout 229 * - or other error passed from the ``set_write_protect`` or ``common_command`` function of host driver 230 */ 231 esp_err_t spi_flash_chip_generic_set_io_mode(esp_flash_t *chip); 232 233 /** 234 * Get whether the Quad Enable (QE) is set. 235 * 236 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 237 * @param out_quad_mode Pointer to store the output mode. 238 * - SPI_FLASH_QOUT: QE is enabled 239 * - otherwise: QE is disabled 240 * 241 * @return 242 * - ESP_OK if success 243 * - or other error passed from the ``common_command`` function of host driver 244 */ 245 esp_err_t spi_flash_chip_generic_get_io_mode(esp_flash_t *chip, esp_flash_io_mode_t* out_quad_mode); 246 247 /** 248 * Generic SPI flash chip_drv, uses all the above functions for its operations. 249 * In default autodetection, this is used as a catchall if a more specific 250 * chip_drv is not found. 251 */ 252 extern const spi_flash_chip_t esp_flash_chip_generic; 253 254 /******************************************************************************* 255 * Utilities 256 *******************************************************************************/ 257 258 /// Function pointer type for reading status register with QE bit. 259 typedef esp_err_t (*esp_flash_rdsr_func_t)(esp_flash_t* chip, uint32_t* out_sr); 260 261 /** 262 * Use RDSR2 (35H) to read bit 15-8 of the SR, and RDSR (05H) to read bit 7-0. 263 * 264 * @param chip Pointer to SPI flash chip to use. 265 * @param out_sr Pointer to buffer to hold the status register, 16 bits. 266 * 267 * @return ESP_OK if success, otherwise error code passed from the 268 * `common_command` function of the host driver. 269 */ 270 esp_err_t spi_flash_common_read_status_16b_rdsr_rdsr2(esp_flash_t* chip, uint32_t* out_sr); 271 272 /** 273 * Use RDSR2 (35H) to read bit 15-8 of the SR. 274 * 275 * @param chip Pointer to SPI flash chip to use. 276 * @param out_sr Pointer to buffer to hold the status register, 8 bits. 277 * 278 * @return ESP_OK if success, otherwise error code passed from the 279 * `common_command` function of the host driver. 280 */ 281 esp_err_t spi_flash_common_read_status_8b_rdsr2(esp_flash_t* chip, uint32_t* out_sr); 282 283 /** 284 * Use RDSR (05H) to read bit 7-0 of the SR. 285 * 286 * @param chip Pointer to SPI flash chip to use. 287 * @param out_sr Pointer to buffer to hold the status register, 8 bits. 288 * 289 * @return ESP_OK if success, otherwise error code passed from the 290 * `common_command` function of the host driver. 291 */ 292 esp_err_t spi_flash_common_read_status_8b_rdsr(esp_flash_t* chip, uint32_t* out_sr); 293 294 /// Function pointer type for writing status register with QE bit. 295 typedef esp_err_t (*esp_flash_wrsr_func_t)(esp_flash_t* chip, uint32_t sr); 296 297 /** 298 * Use WRSR (01H) to write bit 7-0 of the SR. 299 * 300 * @param chip Pointer to SPI flash chip to use. 301 * @param sr Value of the status register to write, 8 bits. 302 * 303 * @return ESP_OK if success, otherwise error code passed from the 304 * `common_command` function of the host driver. 305 */ 306 esp_err_t spi_flash_common_write_status_8b_wrsr(esp_flash_t* chip, uint32_t sr); 307 308 /** 309 * Use WRSR (01H) to write bit 15-0 of the SR. 310 * 311 * @param chip Pointer to SPI flash chip to use. 312 * @param sr Value of the status register to write, 16 bits. 313 * 314 * @return ESP_OK if success, otherwise error code passed from the 315 * `common_command` function of the host driver. 316 */ 317 esp_err_t spi_flash_common_write_status_16b_wrsr(esp_flash_t* chip, uint32_t sr); 318 319 /** 320 * Use WRSR2 (31H) to write bit 15-8 of the SR. 321 * 322 * @param chip Pointer to SPI flash chip to use. 323 * @param sr Value of the status register to write, 8 bits. 324 * 325 * @return ESP_OK if success, otherwise error code passed from the 326 * `common_command` function of the host driver. 327 */ 328 esp_err_t spi_flash_common_write_status_8b_wrsr2(esp_flash_t* chip, uint32_t sr); 329 330 /** 331 * @brief Utility function for set_read_mode chip_drv function. If required, 332 * set and check the QE bit in the flash chip to enable the QIO/QOUT mode. 333 * 334 * Most chip QE enable follows a common pattern, though commands to read/write 335 * the status register may be different, as well as the position of QE bit. 336 * 337 * Registers to actually do Quad transtions and command to be sent in reading 338 * should also be configured via 339 * spi_flash_chip_generic_config_host_io_mode(). 340 * 341 * Note that the bit length and qe position of wrsr_func, rdsr_func and 342 * qe_sr_bit should be consistent. 343 * 344 * @param chip Pointer to SPI flash chip to use. 345 * @param wrsr_func Function pointer for writing the status register 346 * @param rdsr_func Function pointer for reading the status register 347 * @param qe_sr_bit status with the qe bit only. 348 * 349 * @return always ESP_OK (currently). 350 */ 351 esp_err_t spi_flash_common_set_io_mode(esp_flash_t *chip, esp_flash_wrsr_func_t wrsr_func, esp_flash_rdsr_func_t rdsr_func, uint32_t qe_sr_bit); 352 353 /** 354 * @brief Configure the host registers to use the specified read mode set in 355 * the ``chip->read_mode``. 356 * 357 * Usually called in chip_drv read() functions before actual reading 358 * transactions. Also prepare the command to be sent in read functions. 359 * 360 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 361 * @param addr_32bit Whether 32 bit commands will be used (Currently only W25Q256 is supported) 362 * 363 * @return 364 * - ESP_OK if success 365 * - ESP_ERR_FLASH_NOT_INITIALISED if chip not initialized properly 366 * - or other error passed from the ``configure_host_mode`` function of host driver 367 */ 368 esp_err_t spi_flash_chip_generic_config_host_io_mode(esp_flash_t *chip, bool addr_32bit); 369 370 /** 371 * @brief Handle explicit yield requests 372 * 373 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 374 * @param wip Write (erase) in progress, `true` if this function is called during waiting idle of a erase/write command; else `false`. 375 * @return ESP_OK if success, otherwise failed. 376 */ 377 esp_err_t spi_flash_chip_generic_yield(esp_flash_t* chip, uint32_t wip); 378 379 /** 380 * @brief Setup for flash suspend command configuration. 381 * 382 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 383 * @return ESP_OK 384 */ 385 esp_err_t spi_flash_chip_generic_suspend_cmd_conf(esp_flash_t *chip); 386 387 /// Default timeout configuration used by most chips 388 const flash_chip_op_timeout_t spi_flash_chip_generic_timeout; 389