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 * @brief Read the chip unique ID. 249 * 250 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 251 * @param flash_unique_id Pointer to store output unique id. 252 * 253 * @return 254 * - ESP_OK if success 255 * - ESP_ERR_NOT_SUPPORTED if the chip doesn't support read id. 256 */ 257 esp_err_t spi_flash_chip_generic_read_unique_id(esp_flash_t *chip, uint64_t* flash_unique_id); 258 259 /** 260 * Generic SPI flash chip_drv, uses all the above functions for its operations. 261 * In default autodetection, this is used as a catchall if a more specific 262 * chip_drv is not found. 263 */ 264 extern const spi_flash_chip_t esp_flash_chip_generic; 265 266 /******************************************************************************* 267 * Utilities 268 *******************************************************************************/ 269 270 /// Function pointer type for reading status register with QE bit. 271 typedef esp_err_t (*esp_flash_rdsr_func_t)(esp_flash_t* chip, uint32_t* out_sr); 272 273 /** 274 * Use RDSR2 (35H) to read bit 15-8 of the SR, and RDSR (05H) to read bit 7-0. 275 * 276 * @param chip Pointer to SPI flash chip to use. 277 * @param out_sr Pointer to buffer to hold the status register, 16 bits. 278 * 279 * @return ESP_OK if success, otherwise error code passed from the 280 * `common_command` function of the host driver. 281 */ 282 esp_err_t spi_flash_common_read_status_16b_rdsr_rdsr2(esp_flash_t* chip, uint32_t* out_sr); 283 284 /** 285 * Use RDSR2 (35H) to read bit 15-8 of the SR. 286 * 287 * @param chip Pointer to SPI flash chip to use. 288 * @param out_sr Pointer to buffer to hold the status register, 8 bits. 289 * 290 * @return ESP_OK if success, otherwise error code passed from the 291 * `common_command` function of the host driver. 292 */ 293 esp_err_t spi_flash_common_read_status_8b_rdsr2(esp_flash_t* chip, uint32_t* out_sr); 294 295 /** 296 * Use RDSR (05H) to read bit 7-0 of the SR. 297 * 298 * @param chip Pointer to SPI flash chip to use. 299 * @param out_sr Pointer to buffer to hold the status register, 8 bits. 300 * 301 * @return ESP_OK if success, otherwise error code passed from the 302 * `common_command` function of the host driver. 303 */ 304 esp_err_t spi_flash_common_read_status_8b_rdsr(esp_flash_t* chip, uint32_t* out_sr); 305 306 /// Function pointer type for writing status register with QE bit. 307 typedef esp_err_t (*esp_flash_wrsr_func_t)(esp_flash_t* chip, uint32_t sr); 308 309 /** 310 * Use WRSR (01H) to write bit 7-0 of the SR. 311 * 312 * @param chip Pointer to SPI flash chip to use. 313 * @param sr Value of the status register to write, 8 bits. 314 * 315 * @return ESP_OK if success, otherwise error code passed from the 316 * `common_command` function of the host driver. 317 */ 318 esp_err_t spi_flash_common_write_status_8b_wrsr(esp_flash_t* chip, uint32_t sr); 319 320 /** 321 * Use WRSR (01H) to write bit 15-0 of the SR. 322 * 323 * @param chip Pointer to SPI flash chip to use. 324 * @param sr Value of the status register to write, 16 bits. 325 * 326 * @return ESP_OK if success, otherwise error code passed from the 327 * `common_command` function of the host driver. 328 */ 329 esp_err_t spi_flash_common_write_status_16b_wrsr(esp_flash_t* chip, uint32_t sr); 330 331 /** 332 * Use WRSR2 (31H) to write bit 15-8 of the SR. 333 * 334 * @param chip Pointer to SPI flash chip to use. 335 * @param sr Value of the status register to write, 8 bits. 336 * 337 * @return ESP_OK if success, otherwise error code passed from the 338 * `common_command` function of the host driver. 339 */ 340 esp_err_t spi_flash_common_write_status_8b_wrsr2(esp_flash_t* chip, uint32_t sr); 341 342 /** 343 * @brief Utility function for set_read_mode chip_drv function. If required, 344 * set and check the QE bit in the flash chip to enable the QIO/QOUT mode. 345 * 346 * Most chip QE enable follows a common pattern, though commands to read/write 347 * the status register may be different, as well as the position of QE bit. 348 * 349 * Registers to actually do Quad transtions and command to be sent in reading 350 * should also be configured via 351 * spi_flash_chip_generic_config_host_io_mode(). 352 * 353 * Note that the bit length and qe position of wrsr_func, rdsr_func and 354 * qe_sr_bit should be consistent. 355 * 356 * @param chip Pointer to SPI flash chip to use. 357 * @param wrsr_func Function pointer for writing the status register 358 * @param rdsr_func Function pointer for reading the status register 359 * @param qe_sr_bit status with the qe bit only. 360 * 361 * @return always ESP_OK (currently). 362 */ 363 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); 364 365 /** 366 * @brief Configure the host registers to use the specified read mode set in 367 * the ``chip->read_mode``. 368 * 369 * Usually called in chip_drv read() functions before actual reading 370 * transactions. Also prepare the command to be sent in read functions. 371 * 372 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 373 * @param flags Special rules to configure io mode, (i.e. Whether 32 bit commands will be used (Currently only W25Q256 and GD25Q256 are supported)) 374 * 375 * @return 376 * - ESP_OK if success 377 * - ESP_ERR_FLASH_NOT_INITIALISED if chip not initialized properly 378 * - or other error passed from the ``configure_host_mode`` function of host driver 379 */ 380 esp_err_t spi_flash_chip_generic_config_host_io_mode(esp_flash_t *chip, uint32_t flags); 381 #define SPI_FLASH_CONFIG_IO_MODE_32B_ADDR BIT(0) 382 383 /** 384 * @brief Handle explicit yield requests 385 * 386 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 387 * @param wip Write (erase) in progress, `true` if this function is called during waiting idle of a erase/write command; else `false`. 388 * @return ESP_OK if success, otherwise failed. 389 */ 390 esp_err_t spi_flash_chip_generic_yield(esp_flash_t* chip, uint32_t wip); 391 392 /** 393 * @brief Setup for flash suspend command configuration. 394 * 395 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. 396 * @return ESP_OK 397 */ 398 esp_err_t spi_flash_chip_generic_suspend_cmd_conf(esp_flash_t *chip); 399 400 /** 401 * 402 * @brief Read the chip unique ID unsupported function. 403 * 404 * @param chip Pointer to SPI flash chip to use. 405 * @param flash_unique_id Pointer to store output unique id (Although this function is an unsupported function, but the parameter should be kept for the consistence of the function pointer). 406 * @return Always ESP_ERR_NOT_SUPPORTED. 407 */ 408 esp_err_t spi_flash_chip_generic_read_unique_id_none(esp_flash_t *chip, uint64_t* flash_unique_id); 409 410 /// Default timeout configuration used by most chips 411 extern const flash_chip_op_timeout_t spi_flash_chip_generic_timeout; 412
