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 #include <stdlib.h>
16 #include <stdio.h>
17 #include <sys/param.h>
18 #include <string.h>
19
20 #include "spi_flash_chip_driver.h"
21 #include "memspi_host_driver.h"
22 #include "esp_log.h"
23 #include "sdkconfig.h"
24 #include "esp_flash_internal.h"
25 #include "spi_flash_defs.h"
26
27 static const char TAG[] = "spi_flash";
28
29 #ifdef CONFIG_SPI_FLASH_WRITE_CHUNK_SIZE
30 #define MAX_WRITE_CHUNK CONFIG_SPI_FLASH_WRITE_CHUNK_SIZE /* write in chunks */
31 #else
32 #define MAX_WRITE_CHUNK 8192 /* write in chunks */
33 #endif // CONFIG_SPI_FLASH_WRITE_CHUNK_SIZE
34
35 #define MAX_READ_CHUNK 16384
36
37
38 #ifdef CONFIG_SPI_FLASH_DANGEROUS_WRITE_ABORTS
39 #define UNSAFE_WRITE_ADDRESS abort()
40 #else
41 #define UNSAFE_WRITE_ADDRESS return ESP_ERR_INVALID_ARG
42 #endif
43
44 /* CHECK_WRITE_ADDRESS macro to fail writes which land in the
45 bootloader, partition table, or running application region.
46 */
47 #if CONFIG_SPI_FLASH_DANGEROUS_WRITE_ALLOWED
48 #define CHECK_WRITE_ADDRESS(CHIP, ADDR, SIZE)
49 #else /* FAILS or ABORTS */
50 #define CHECK_WRITE_ADDRESS(CHIP, ADDR, SIZE) do { \
51 if (CHIP && CHIP->os_func->region_protected && CHIP->os_func->region_protected(CHIP->os_func_data, ADDR, SIZE)) { \
52 UNSAFE_WRITE_ADDRESS; \
53 } \
54 } while(0)
55 #endif // CONFIG_SPI_FLASH_DANGEROUS_WRITE_ALLOWED
56
57 #define IO_STR_LEN 7
58
59 static const char io_mode_str[][IO_STR_LEN] = {
60 "slowrd",
61 "fastrd",
62 "dout",
63 "dio",
64 "qout",
65 "qio",
66 };
67
68 _Static_assert(sizeof(io_mode_str)/IO_STR_LEN == SPI_FLASH_READ_MODE_MAX, "the io_mode_str should be consistent with the esp_flash_io_mode_t defined in spi_flash_ll.h");
69
70 esp_err_t esp_flash_read_chip_id(esp_flash_t* chip, uint32_t* flash_id);
71
72 #ifndef CONFIG_SPI_FLASH_ROM_IMPL
73 static esp_err_t spiflash_start_default(esp_flash_t *chip);
74 static esp_err_t spiflash_end_default(esp_flash_t *chip, esp_err_t err);
75 static esp_err_t check_chip_pointer_default(esp_flash_t **inout_chip);
76 static esp_err_t flash_end_flush_cache(esp_flash_t* chip, esp_err_t err, bool bus_acquired, uint32_t address, uint32_t length);
77 #endif //CONFIG_SPI_FLASH_ROM_IMPL
78
79 typedef struct {
80 esp_err_t (*start)(esp_flash_t *chip);
81 esp_err_t (*end)(esp_flash_t *chip, esp_err_t err);
82 esp_err_t (*chip_check)(esp_flash_t **inout_chip);
83 esp_err_t (*flash_end_flush_cache)(esp_flash_t* chip, esp_err_t err, bool bus_acquired, uint32_t address, uint32_t length);
84 } rom_spiflash_api_func_t;
85
86 #ifndef CONFIG_SPI_FLASH_ROM_IMPL
87 // These functions can be placed in the ROM. For now we use the code in IDF.
88 DRAM_ATTR static rom_spiflash_api_func_t default_spiflash_rom_api = {
89 .start = spiflash_start_default,
90 .end = spiflash_end_default,
91 .chip_check = check_chip_pointer_default,
92 .flash_end_flush_cache = flash_end_flush_cache,
93 };
94
95 DRAM_ATTR rom_spiflash_api_func_t *rom_spiflash_api_funcs = &default_spiflash_rom_api;
96 #else
97 extern rom_spiflash_api_func_t *esp_flash_api_funcs;
98 #define rom_spiflash_api_funcs esp_flash_api_funcs
99 #endif // CONFIG_SPI_FLASH_ROM_IMPL
100
101 /* Static function to notify OS of a new SPI flash operation.
102
103 If returns an error result, caller must abort. If returns ESP_OK, caller must
104 call rom_spiflash_api_funcs->end() before returning.
105 */
106 #ifndef CONFIG_SPI_FLASH_ROM_IMPL
spiflash_start_default(esp_flash_t * chip)107 static esp_err_t IRAM_ATTR spiflash_start_default(esp_flash_t *chip)
108 {
109 if (chip->os_func != NULL && chip->os_func->start != NULL) {
110 esp_err_t err = chip->os_func->start(chip->os_func_data);
111 if (err != ESP_OK) {
112 return err;
113 }
114 }
115 chip->host->driver->dev_config(chip->host);
116 return ESP_OK;
117 }
118
119 /* Static function to notify OS that SPI flash operation is complete.
120 */
spiflash_end_default(esp_flash_t * chip,esp_err_t err)121 static esp_err_t IRAM_ATTR spiflash_end_default(esp_flash_t *chip, esp_err_t err)
122 {
123 if (chip->os_func != NULL
124 && chip->os_func->end != NULL) {
125 esp_err_t end_err = chip->os_func->end(chip->os_func_data);
126 if (err == ESP_OK) {
127 err = end_err; // Only return the 'end' error if we haven't already failed
128 }
129 }
130 return err;
131 }
132
133 // check that the 'chip' parameter is properly initialised
check_chip_pointer_default(esp_flash_t ** inout_chip)134 static esp_err_t check_chip_pointer_default(esp_flash_t **inout_chip)
135 {
136 esp_flash_t *chip = *inout_chip;
137 if (chip == NULL) {
138 chip = esp_flash_default_chip;
139 }
140 *inout_chip = chip;
141 if (chip == NULL || !esp_flash_chip_driver_initialized(chip)) {
142 return ESP_ERR_FLASH_NOT_INITIALISED;
143 }
144 return ESP_OK;
145 }
146
flash_end_flush_cache(esp_flash_t * chip,esp_err_t err,bool bus_acquired,uint32_t address,uint32_t length)147 static IRAM_ATTR esp_err_t flash_end_flush_cache(esp_flash_t* chip, esp_err_t err, bool bus_acquired, uint32_t address, uint32_t length)
148 {
149 if (!bus_acquired) {
150 // Try to acquire the bus again to flush the cache before exit.
151 esp_err_t acquire_err = rom_spiflash_api_funcs->start(chip);
152 if (acquire_err != ESP_OK) {
153 return (err == ESP_OK)? acquire_err: err;
154 }
155 }
156
157 if (chip->host->driver->flush_cache) {
158 esp_err_t flush_err = chip->host->driver->flush_cache(chip->host, address, length);
159 if (err == ESP_OK) {
160 err = flush_err;
161 }
162 }
163 return rom_spiflash_api_funcs->end(chip, err);
164 }
165 #endif //CONFIG_SPI_FLASH_ROM_IMPL
166
167 /* Top-level API functions, calling into chip_drv functions via chip->drv */
168
169 static esp_err_t detect_spi_flash_chip(esp_flash_t *chip);
170
esp_flash_chip_driver_initialized(const esp_flash_t * chip)171 bool esp_flash_chip_driver_initialized(const esp_flash_t *chip)
172 {
173 if (!chip->chip_drv) return false;
174 return true;
175 }
176
esp_flash_init(esp_flash_t * chip)177 esp_err_t IRAM_ATTR esp_flash_init(esp_flash_t *chip)
178 {
179 // Chip init flow
180 // 1. Read chip id
181 // 2. (optional) Detect chip vendor
182 // 3. Get basic parameters of the chip (size, dummy count, etc.)
183 // 4. Init chip into desired mode (without breaking the cache!)
184 esp_err_t err = ESP_OK;
185 if (chip == NULL || chip->host == NULL || chip->host->driver == NULL ||
186 ((memspi_host_inst_t*)chip->host)->spi == NULL) {
187 return ESP_ERR_INVALID_ARG;
188 }
189
190 //read chip id
191 uint32_t flash_id;
192 int retries = 10;
193 do {
194 err = esp_flash_read_chip_id(chip, &flash_id);
195 } while (err == ESP_ERR_FLASH_NOT_INITIALISED && retries-- > 0);
196
197 if (err != ESP_OK) {
198 return err;
199 }
200 chip->chip_id = flash_id;
201
202 if (!esp_flash_chip_driver_initialized(chip)) {
203 // Detect chip_drv
204 err = detect_spi_flash_chip(chip);
205 if (err != ESP_OK) {
206 return err;
207 }
208 }
209
210 // Detect flash size
211 uint32_t size;
212 err = esp_flash_get_size(chip, &size);
213 if (err != ESP_OK) {
214 ESP_LOGE(TAG, "failed to get chip size");
215 return err;
216 }
217
218 ESP_LOGI(TAG, "flash io: %s", io_mode_str[chip->read_mode]);
219 err = rom_spiflash_api_funcs->start(chip);
220 if (err != ESP_OK) {
221 return err;
222 }
223
224 if (err == ESP_OK) {
225 // Try to set the flash mode to whatever default mode was chosen
226 err = chip->chip_drv->set_io_mode(chip);
227 if (err == ESP_ERR_FLASH_NO_RESPONSE && !esp_flash_is_quad_mode(chip)) {
228 //some chips (e.g. Winbond) don't support to clear QE, treat as success
229 err = ESP_OK;
230 }
231 }
232 // Done: all fields on 'chip' are initialised
233 return rom_spiflash_api_funcs->end(chip, err);
234 }
235
read_id_core(esp_flash_t * chip,uint32_t * out_id,bool sanity_check)236 static esp_err_t IRAM_ATTR read_id_core(esp_flash_t* chip, uint32_t* out_id, bool sanity_check)
237 {
238 bool installed = esp_flash_chip_driver_initialized(chip);
239 esp_err_t err = rom_spiflash_api_funcs->start(chip);
240 if (err != ESP_OK) {
241 return err;
242 }
243
244 esp_err_t (*read_id_func)(void*, uint32_t*);
245 void* read_id_arg;
246 if (installed && chip->chip_drv->read_id) {
247 read_id_func = (void*)chip->chip_drv->read_id;
248 read_id_arg = (void*)chip;
249 } else {
250 //default option if the chip is not detected/chosen yet.
251 read_id_func = (void*)chip->host->driver->read_id;
252 read_id_arg = (void*)chip->host;
253 }
254
255 // Inner function fails if it sees all-ones or all-zeroes.
256 err = read_id_func(read_id_arg, out_id);
257
258 if (sanity_check && err == ESP_OK) {
259 // Send RDID command twice, check for a matching result and retry in case we just powered on
260 uint32_t new_id;
261 err = read_id_func(read_id_arg, &new_id);
262 if (err == ESP_OK && (new_id != *out_id)) {
263 err = ESP_ERR_FLASH_NOT_INITIALISED;
264 }
265 }
266
267 return rom_spiflash_api_funcs->end(chip, err);
268 }
269
270 // Faster version with sanity check.
271 // Called in esp_flash_init and unit test (though not public)
esp_flash_read_chip_id(esp_flash_t * chip,uint32_t * out_id)272 esp_err_t esp_flash_read_chip_id(esp_flash_t* chip, uint32_t* out_id)
273 {
274 return read_id_core(chip, out_id, true);
275 }
276
277 #ifndef CONFIG_SPI_FLASH_ROM_IMPL
esp_flash_read_id(esp_flash_t * chip,uint32_t * out_id)278 esp_err_t esp_flash_read_id(esp_flash_t* chip, uint32_t* out_id)
279 {
280 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
281 //Accept uninitialized chip when reading chip id
282 if (err != ESP_OK && !(err == ESP_ERR_FLASH_NOT_INITIALISED && chip != NULL)) return err;
283 if (out_id == NULL) return ESP_ERR_INVALID_ARG;
284
285 return read_id_core(chip, out_id, false);
286 }
287 #endif //CONFIG_SPI_FLASH_ROM_IMPL
288
detect_spi_flash_chip(esp_flash_t * chip)289 static esp_err_t IRAM_ATTR detect_spi_flash_chip(esp_flash_t *chip)
290 {
291 esp_err_t err;
292 uint32_t flash_id = chip->chip_id;
293
294 // Detect the chip and set the chip_drv structure for it
295 const spi_flash_chip_t **drivers = esp_flash_registered_chips;
296 while (*drivers != NULL && !esp_flash_chip_driver_initialized(chip)) {
297 chip->chip_drv = *drivers;
298 // start/end SPI operation each time, for multitasking
299 // and also so esp_flash_registered_flash_drivers can live in flash
300 ESP_LOGD(TAG, "trying chip: %s", chip->chip_drv->name);
301
302 err = rom_spiflash_api_funcs->start(chip);
303 if (err != ESP_OK) {
304 return err;
305 }
306
307 if (chip->chip_drv->probe(chip, flash_id) != ESP_OK) {
308 chip->chip_drv = NULL;
309 }
310 // if probe succeeded, chip->drv stays set
311 drivers++;
312
313 err = rom_spiflash_api_funcs->end(chip, err);
314 if (err != ESP_OK) {
315 return err;
316 }
317 }
318 if (!esp_flash_chip_driver_initialized(chip)) {
319 return ESP_ERR_NOT_FOUND;
320 }
321 ESP_LOGI(TAG, "detected chip: %s", chip->chip_drv->name);
322 return ESP_OK;
323 }
324
325 #ifndef CONFIG_SPI_FLASH_ROM_IMPL
326
327 /* Convenience macro for beginning of all API functions.
328 * Check the return value of `rom_spiflash_api_funcs->chip_check` is correct,
329 * and the chip supports the operation in question.
330 */
331 #define VERIFY_CHIP_OP(OP) do { \
332 if (err != ESP_OK) return err; \
333 if (chip->chip_drv->OP == NULL) { \
334 return ESP_ERR_FLASH_UNSUPPORTED_CHIP; \
335 } \
336 } while (0)
337
338 /* Return true if regions 'a' and 'b' overlap at all, based on their start offsets and lengths. */
339 inline static bool regions_overlap(uint32_t a_start, uint32_t a_len,uint32_t b_start, uint32_t b_len);
340
esp_flash_get_size(esp_flash_t * chip,uint32_t * out_size)341 esp_err_t IRAM_ATTR esp_flash_get_size(esp_flash_t *chip, uint32_t *out_size)
342 {
343 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
344 VERIFY_CHIP_OP(detect_size);
345 if (out_size == NULL) {
346 return ESP_ERR_INVALID_ARG;
347 }
348 if (chip->size != 0) {
349 *out_size = chip->size;
350 return ESP_OK;
351 }
352
353 err = rom_spiflash_api_funcs->start(chip);
354 if (err != ESP_OK) {
355 return err;
356 }
357 uint32_t detect_size;
358 err = chip->chip_drv->detect_size(chip, &detect_size);
359 if (err == ESP_OK) {
360 chip->size = detect_size;
361 }
362 return rom_spiflash_api_funcs->end(chip, err);
363 }
364
esp_flash_erase_chip(esp_flash_t * chip)365 esp_err_t IRAM_ATTR esp_flash_erase_chip(esp_flash_t *chip)
366 {
367 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
368 VERIFY_CHIP_OP(erase_chip);
369 CHECK_WRITE_ADDRESS(chip, 0, chip->size);
370
371 //check before the operation, in case this is called too close to the last operation
372 if (chip->chip_drv->yield) {
373 err = chip->chip_drv->yield(chip, 0);
374 if (err != ESP_OK) {
375 return err;
376 }
377 }
378
379 err = rom_spiflash_api_funcs->start(chip);
380 if (err != ESP_OK) {
381 return err;
382 }
383
384 err = chip->chip_drv->erase_chip(chip);
385 if (chip->host->driver->flush_cache) {
386 esp_err_t flush_cache_err = chip->host->driver->flush_cache(chip->host, 0, chip->size);
387 if (err == ESP_OK) {
388 err = flush_cache_err;
389 }
390 }
391 return rom_spiflash_api_funcs->end(chip, err);
392 }
393
esp_flash_erase_region(esp_flash_t * chip,uint32_t start,uint32_t len)394 esp_err_t IRAM_ATTR esp_flash_erase_region(esp_flash_t *chip, uint32_t start, uint32_t len)
395 {
396 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
397 VERIFY_CHIP_OP(erase_sector);
398 VERIFY_CHIP_OP(erase_block);
399 CHECK_WRITE_ADDRESS(chip, start, len);
400
401 uint32_t block_erase_size = chip->chip_drv->erase_block == NULL ? 0 : chip->chip_drv->block_erase_size;
402 uint32_t sector_size = chip->chip_drv->sector_size;
403
404 if (sector_size == 0 || (block_erase_size % sector_size) != 0) {
405 return ESP_ERR_FLASH_NOT_INITIALISED;
406 }
407 if (start > chip->size || start + len > chip->size) {
408 return ESP_ERR_INVALID_ARG;
409 }
410 if ((start % chip->chip_drv->sector_size) != 0 || (len % chip->chip_drv->sector_size) != 0) {
411 // Can only erase multiples of the sector size, starting at sector boundary
412 return ESP_ERR_INVALID_ARG;
413 }
414
415 err = ESP_OK;
416 // Check for write protected regions overlapping the erase region
417 if (chip->chip_drv->get_protected_regions != NULL &&
418 chip->chip_drv->num_protectable_regions > 0) {
419
420 err = rom_spiflash_api_funcs->start(chip);
421 if (err != ESP_OK) {
422 return err;
423 }
424 uint64_t protected = 0;
425 err = chip->chip_drv->get_protected_regions(chip, &protected);
426 if (err == ESP_OK && protected != 0) {
427 for (int i = 0; i < chip->chip_drv->num_protectable_regions && err == ESP_OK; i++) {
428 const esp_flash_region_t *region = &chip->chip_drv->protectable_regions[i];
429 if ((protected & BIT64(i))
430 && regions_overlap(start, len, region->offset, region->size)) {
431 err = ESP_ERR_FLASH_PROTECTED;
432 }
433 }
434 }
435 // Don't lock the SPI flash for the entire erase, as this may be very long
436 err = rom_spiflash_api_funcs->end(chip, err);
437 }
438 if (err != ESP_OK) {
439 return err;
440 }
441
442 uint32_t erase_addr = start;
443 uint32_t len_remain = len;
444 // Indicate whether the bus is acquired by the driver, needs to be released before return
445 bool bus_acquired = false;
446 while (1) {
447 //check before the operation, in case this is called too close to the last operation
448 if (chip->chip_drv->yield) {
449 err = chip->chip_drv->yield(chip, 0);
450 if (err != ESP_OK) {
451 return err;
452 }
453 }
454
455 err = rom_spiflash_api_funcs->start(chip);
456 if (err != ESP_OK) {
457 break;
458 }
459 bus_acquired = true;
460
461 #ifndef CONFIG_SPI_FLASH_BYPASS_BLOCK_ERASE
462 // If possible erase an entire multi-sector block
463 if (block_erase_size > 0 && len_remain >= block_erase_size && (erase_addr % block_erase_size) == 0) {
464 err = chip->chip_drv->erase_block(chip, erase_addr);
465 erase_addr += block_erase_size;
466 len_remain -= block_erase_size;
467 } else
468 #endif
469 {
470 // Otherwise erase individual sector only
471 err = chip->chip_drv->erase_sector(chip, erase_addr);
472 erase_addr += sector_size;
473 len_remain -= sector_size;
474 }
475
476 if (err != ESP_OK || len_remain == 0) {
477 // On ESP32, the cache re-enable is in the end() function, while flush_cache should
478 // happen when the cache is still disabled on ESP32. Break before the end() function and
479 // do end() later
480 assert(bus_acquired);
481 break;
482 }
483
484 err = rom_spiflash_api_funcs->end(chip, ESP_OK);
485 if (err != ESP_OK) {
486 break;
487 }
488 bus_acquired = false;
489 }
490
491 return rom_spiflash_api_funcs->flash_end_flush_cache(chip, err, bus_acquired, start, len);
492 }
493
esp_flash_get_chip_write_protect(esp_flash_t * chip,bool * out_write_protected)494 esp_err_t IRAM_ATTR esp_flash_get_chip_write_protect(esp_flash_t *chip, bool *out_write_protected)
495 {
496 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
497 VERIFY_CHIP_OP(get_chip_write_protect);
498 if (out_write_protected == NULL) {
499 return ESP_ERR_INVALID_ARG;
500 }
501
502 err = rom_spiflash_api_funcs->start(chip);
503 if (err != ESP_OK) {
504 return err;
505 }
506
507 err = chip->chip_drv->get_chip_write_protect(chip, out_write_protected);
508
509 return rom_spiflash_api_funcs->end(chip, err);
510 }
511
esp_flash_set_chip_write_protect(esp_flash_t * chip,bool write_protect)512 esp_err_t IRAM_ATTR esp_flash_set_chip_write_protect(esp_flash_t *chip, bool write_protect)
513 {
514 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
515 VERIFY_CHIP_OP(set_chip_write_protect);
516 //TODO: skip writing if already locked or unlocked
517
518 err = rom_spiflash_api_funcs->start(chip);
519 if (err != ESP_OK) {
520 return err;
521 }
522
523 err = chip->chip_drv->set_chip_write_protect(chip, write_protect);
524
525 return rom_spiflash_api_funcs->end(chip, err);
526 }
527
esp_flash_get_protectable_regions(const esp_flash_t * chip,const esp_flash_region_t ** out_regions,uint32_t * out_num_regions)528 esp_err_t esp_flash_get_protectable_regions(const esp_flash_t *chip, const esp_flash_region_t **out_regions, uint32_t *out_num_regions)
529 {
530 if(out_num_regions != NULL) {
531 *out_num_regions = 0; // In case caller doesn't check result
532 }
533 esp_err_t err = rom_spiflash_api_funcs->chip_check((esp_flash_t **)&chip);
534 VERIFY_CHIP_OP(get_protected_regions);
535
536 if(out_regions == NULL || out_num_regions == NULL) {
537 return ESP_ERR_INVALID_ARG;
538 }
539
540 *out_num_regions = chip->chip_drv->num_protectable_regions;
541 *out_regions = chip->chip_drv->protectable_regions;
542 return ESP_OK;
543 }
544
find_region(const esp_flash_t * chip,const esp_flash_region_t * region,uint8_t * index)545 static esp_err_t find_region(const esp_flash_t *chip, const esp_flash_region_t *region, uint8_t *index)
546 {
547 if (region == NULL) {
548 return ESP_ERR_INVALID_ARG;
549 }
550
551 for(*index = 0; *index < chip->chip_drv->num_protectable_regions; (*index)++) {
552 if (memcmp(&chip->chip_drv->protectable_regions[*index],
553 region, sizeof(esp_flash_region_t)) == 0) {
554 return ESP_OK;
555 }
556 }
557
558 return ESP_ERR_NOT_FOUND;
559 }
560
esp_flash_get_protected_region(esp_flash_t * chip,const esp_flash_region_t * region,bool * out_protected)561 esp_err_t IRAM_ATTR esp_flash_get_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool *out_protected)
562 {
563 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
564 VERIFY_CHIP_OP(get_protected_regions);
565
566 if (out_protected == NULL) {
567 return ESP_ERR_INVALID_ARG;
568 }
569
570 uint8_t index;
571 err = find_region(chip, region, &index);
572 if (err != ESP_OK) {
573 return err;
574 }
575
576 uint64_t protection_mask = 0;
577 err = rom_spiflash_api_funcs->start(chip);
578 if (err != ESP_OK) {
579 return err;
580 }
581
582 err = chip->chip_drv->get_protected_regions(chip, &protection_mask);
583 if (err == ESP_OK) {
584 *out_protected = protection_mask & (1LL << index);
585 }
586
587 return rom_spiflash_api_funcs->end(chip, err);
588 }
589
esp_flash_set_protected_region(esp_flash_t * chip,const esp_flash_region_t * region,bool protect)590 esp_err_t IRAM_ATTR esp_flash_set_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool protect)
591 {
592 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
593 VERIFY_CHIP_OP(set_protected_regions);
594
595 uint8_t index;
596 err = find_region(chip, region, &index);
597 if (err != ESP_OK) {
598 return err;
599 }
600
601 uint64_t protection_mask = 0;
602 err = rom_spiflash_api_funcs->start(chip);
603 if (err != ESP_OK) {
604 return err;
605 }
606
607 err = chip->chip_drv->get_protected_regions(chip, &protection_mask);
608 if (err == ESP_OK) {
609 if (protect) {
610 protection_mask |= (1LL << index);
611 } else {
612 protection_mask &= ~(1LL << index);
613 }
614 err = chip->chip_drv->set_protected_regions(chip, protection_mask);
615 }
616
617 return rom_spiflash_api_funcs->end(chip, err);
618 }
619
esp_flash_read(esp_flash_t * chip,void * buffer,uint32_t address,uint32_t length)620 esp_err_t IRAM_ATTR esp_flash_read(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length)
621 {
622 if (length == 0) {
623 return ESP_OK;
624 }
625 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
626 VERIFY_CHIP_OP(read);
627 if (buffer == NULL || address > chip->size || address+length > chip->size) {
628 return ESP_ERR_INVALID_ARG;
629 }
630
631 //when the cache is disabled, only the DRAM can be read, check whether we need to receive in another buffer in DRAM.
632 bool direct_read = chip->host->driver->supports_direct_read(chip->host, buffer);
633 uint8_t* temp_buffer = NULL;
634
635 //each time, we at most read this length
636 //after that, we release the lock to allow some other operations
637 size_t read_chunk_size = MIN(MAX_READ_CHUNK, length);
638
639 if (!direct_read) {
640 size_t actual_len = 0;
641 if (chip->os_func->get_temp_buffer != NULL) {
642 temp_buffer = chip->os_func->get_temp_buffer(chip->os_func_data, read_chunk_size, &actual_len);
643 read_chunk_size = actual_len;
644 }
645 if (temp_buffer == NULL) {
646 return ESP_ERR_NO_MEM;
647 }
648 }
649
650 err = ESP_OK;
651 do {
652 err = rom_spiflash_api_funcs->start(chip);
653 if (err != ESP_OK) {
654 break;
655 }
656 //if required (dma buffer allocated), read to the buffer instead of the original buffer
657 uint8_t* buffer_to_read = (temp_buffer)? temp_buffer : buffer;
658
659 // Length we will read this iteration is either the chunk size or the remaining length, whichever is smaller
660 size_t length_to_read = MIN(read_chunk_size, length);
661
662 if (err == ESP_OK) {
663 err = chip->chip_drv->read(chip, buffer_to_read, address, length_to_read);
664 }
665 if (err != ESP_OK) {
666 rom_spiflash_api_funcs->end(chip, err);
667 break;
668 }
669 //even if this is failed, the data is still valid, copy before quit
670 err = rom_spiflash_api_funcs->end(chip, err);
671
672 //copy back to the original buffer
673 if (temp_buffer) {
674 memcpy(buffer, temp_buffer, length_to_read);
675 }
676 address += length_to_read;
677 length -= length_to_read;
678 buffer = (void*)((intptr_t)buffer + length_to_read);
679 } while (err == ESP_OK && length > 0);
680
681 if (chip->os_func->release_temp_buffer != NULL) {
682 chip->os_func->release_temp_buffer(chip->os_func_data, temp_buffer);
683 }
684 return err;
685 }
686
esp_flash_write(esp_flash_t * chip,const void * buffer,uint32_t address,uint32_t length)687 esp_err_t IRAM_ATTR esp_flash_write(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length)
688 {
689 if (length == 0) {
690 return ESP_OK;
691 }
692 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
693 VERIFY_CHIP_OP(write);
694 CHECK_WRITE_ADDRESS(chip, address, length);
695 if (buffer == NULL || address > chip->size || address+length > chip->size) {
696 return ESP_ERR_INVALID_ARG;
697 }
698
699 //when the cache is disabled, only the DRAM can be read, check whether we need to copy the data first
700 bool direct_write = chip->host->driver->supports_direct_write(chip->host, buffer);
701
702 // Indicate whether the bus is acquired by the driver, needs to be released before return
703 bool bus_acquired = false;
704 err = ESP_OK;
705 /* Write output in chunks, either by buffering on stack or
706 by artificially cutting into MAX_WRITE_CHUNK parts (in an OS
707 environment, this prevents writing from causing interrupt or higher priority task
708 starvation.) */
709 uint32_t write_addr = address;
710 uint32_t len_remain = length;
711 while (1) {
712 uint32_t write_len;
713 const void *write_buf;
714 uint32_t temp_buf[8];
715 if (direct_write) {
716 write_len = MIN(len_remain, MAX_WRITE_CHUNK);
717 write_buf = buffer;
718 } else {
719 write_len = MIN(len_remain, sizeof(temp_buf));
720 memcpy(temp_buf, buffer, write_len);
721 write_buf = temp_buf;
722 }
723
724 //check before the operation, in case this is called too close to the last operation
725 if (chip->chip_drv->yield) {
726 err = chip->chip_drv->yield(chip, 0);
727 if (err != ESP_OK) {
728 return err;
729 }
730 }
731
732 err = rom_spiflash_api_funcs->start(chip);
733 if (err != ESP_OK) {
734 break;
735 }
736 bus_acquired = true;
737
738 err = chip->chip_drv->write(chip, write_buf, write_addr, write_len);
739 len_remain -= write_len;
740
741 if (err != ESP_OK || len_remain == 0) {
742 // On ESP32, the cache re-enable is in the end() function, while flush_cache should
743 // happen when the cache is still disabled on ESP32. Break before the end() function and
744 // do end() later
745 assert(bus_acquired);
746 break;
747 }
748
749 err = rom_spiflash_api_funcs->end(chip, err);
750 if (err != ESP_OK) {
751 break;
752 }
753 bus_acquired = false;
754
755 write_addr += write_len;
756 buffer = (void *)((intptr_t)buffer + write_len);
757 }
758
759 return rom_spiflash_api_funcs->flash_end_flush_cache(chip, err, bus_acquired, address, length);
760 }
761
762 //currently the legacy implementation is used, from flash_ops.c
763 esp_err_t spi_flash_write_encrypted(size_t dest_addr, const void *src, size_t size);
764
esp_flash_write_encrypted(esp_flash_t * chip,uint32_t address,const void * buffer,uint32_t length)765 esp_err_t IRAM_ATTR esp_flash_write_encrypted(esp_flash_t *chip, uint32_t address, const void *buffer, uint32_t length)
766 {
767 /*
768 * Since currently this feature is supported only by the hardware, there
769 * is no way to support non-standard chips. We use the legacy
770 * implementation and skip the chip and driver layers.
771 */
772 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
773 if (err != ESP_OK) return err;
774 if (buffer == NULL || address > chip->size || address+length > chip->size) {
775 return ESP_ERR_INVALID_ARG;
776 }
777 return spi_flash_write_encrypted(address, buffer, length);
778 }
779
regions_overlap(uint32_t a_start,uint32_t a_len,uint32_t b_start,uint32_t b_len)780 inline static IRAM_ATTR bool regions_overlap(uint32_t a_start, uint32_t a_len,uint32_t b_start, uint32_t b_len)
781 {
782 uint32_t a_end = a_start + a_len;
783 uint32_t b_end = b_start + b_len;
784 return (a_end > b_start && b_end > a_start);
785 }
786
787 //currently the legacy implementation is used, from flash_ops.c
788 esp_err_t spi_flash_read_encrypted(size_t src, void *dstv, size_t size);
789
esp_flash_read_encrypted(esp_flash_t * chip,uint32_t address,void * out_buffer,uint32_t length)790 esp_err_t IRAM_ATTR esp_flash_read_encrypted(esp_flash_t *chip, uint32_t address, void *out_buffer, uint32_t length)
791 {
792 /*
793 * Since currently this feature is supported only by the hardware, there
794 * is no way to support non-standard chips. We use the legacy
795 * implementation and skip the chip and driver layers.
796 */
797 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
798 if (err != ESP_OK) return err;
799 return spi_flash_read_encrypted(address, out_buffer, length);
800 }
801
802 // test only, non-public
esp_flash_get_io_mode(esp_flash_t * chip,bool * qe)803 IRAM_ATTR esp_err_t esp_flash_get_io_mode(esp_flash_t* chip, bool* qe)
804 {
805 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
806 VERIFY_CHIP_OP(get_io_mode);
807 esp_flash_io_mode_t io_mode;
808
809 err = rom_spiflash_api_funcs->start(chip);
810 if (err != ESP_OK) {
811 return err;
812 }
813 err = chip->chip_drv->get_io_mode(chip, &io_mode);
814 err = rom_spiflash_api_funcs->end(chip, err);
815 if (err == ESP_OK) {
816 *qe = (io_mode == SPI_FLASH_QOUT);
817 }
818 return err;
819 }
820
esp_flash_set_io_mode(esp_flash_t * chip,bool qe)821 IRAM_ATTR esp_err_t esp_flash_set_io_mode(esp_flash_t* chip, bool qe)
822 {
823 esp_err_t err = rom_spiflash_api_funcs->chip_check(&chip);
824 VERIFY_CHIP_OP(set_io_mode);
825
826 chip->read_mode = (qe? SPI_FLASH_QOUT: SPI_FLASH_SLOWRD);
827 err = rom_spiflash_api_funcs->start(chip);
828 if (err != ESP_OK) {
829 return err;
830 }
831 err = chip->chip_drv->set_io_mode(chip);
832 return rom_spiflash_api_funcs->end(chip, err);
833 }
834 #endif //CONFIG_SPI_FLASH_ROM_IMPL
835
836 //init suspend mode cmd, uses internal.
esp_flash_suspend_cmd_init(esp_flash_t * chip)837 esp_err_t esp_flash_suspend_cmd_init(esp_flash_t* chip)
838 {
839 ESP_EARLY_LOGW(TAG, "Flash suspend feature is enabled");
840 return chip->chip_drv->sus_setup(chip);
841 }
842
843 #ifndef CONFIG_SPI_FLASH_USE_LEGACY_IMPL
esp_flash_app_disable_protect(bool disable)844 esp_err_t esp_flash_app_disable_protect(bool disable)
845 {
846 if (disable) {
847 return esp_flash_app_disable_os_functions(esp_flash_default_chip);
848 } else {
849 return esp_flash_app_enable_os_functions(esp_flash_default_chip);
850 }
851 }
852 #endif
853
854 /*------------------------------------------------------------------------------
855 Adapter layer to original api before IDF v4.0
856 ------------------------------------------------------------------------------*/
857
858 #ifndef CONFIG_SPI_FLASH_USE_LEGACY_IMPL
859
860 /* Translate any ESP_ERR_FLASH_xxx error code (new API) to a generic ESP_ERR_xyz error code
861 */
spi_flash_translate_rc(esp_err_t err)862 static IRAM_ATTR esp_err_t spi_flash_translate_rc(esp_err_t err)
863 {
864 switch (err) {
865 case ESP_OK:
866 case ESP_ERR_INVALID_ARG:
867 case ESP_ERR_NO_MEM:
868 return err;
869
870 case ESP_ERR_FLASH_NOT_INITIALISED:
871 case ESP_ERR_FLASH_PROTECTED:
872 return ESP_ERR_INVALID_STATE;
873
874 case ESP_ERR_NOT_FOUND:
875 case ESP_ERR_FLASH_UNSUPPORTED_HOST:
876 case ESP_ERR_FLASH_UNSUPPORTED_CHIP:
877 return ESP_ERR_NOT_SUPPORTED;
878
879 case ESP_ERR_FLASH_NO_RESPONSE:
880 return ESP_ERR_INVALID_RESPONSE;
881
882 default:
883 ESP_EARLY_LOGE(TAG, "unexpected spi flash error code: 0x%x", err);
884 abort();
885 }
886 }
887
spi_flash_erase_range(uint32_t start_addr,uint32_t size)888 esp_err_t IRAM_ATTR spi_flash_erase_range(uint32_t start_addr, uint32_t size)
889 {
890 esp_err_t err = esp_flash_erase_region(NULL, start_addr, size);
891 return spi_flash_translate_rc(err);
892 }
893
spi_flash_write(size_t dst,const void * srcv,size_t size)894 esp_err_t IRAM_ATTR spi_flash_write(size_t dst, const void *srcv, size_t size)
895 {
896 esp_err_t err = esp_flash_write(NULL, srcv, dst, size);
897 return spi_flash_translate_rc(err);
898 }
899
spi_flash_read(size_t src,void * dstv,size_t size)900 esp_err_t IRAM_ATTR spi_flash_read(size_t src, void *dstv, size_t size)
901 {
902 esp_err_t err = esp_flash_read(NULL, dstv, src, size);
903 return spi_flash_translate_rc(err);
904 }
905
906 #endif // CONFIG_SPI_FLASH_USE_LEGACY_IMPL
907
