This is the set of APIs for working with data in flash:
-- ``spi_flash_read`` used to read data from flash to RAM
-- ``spi_flash_write`` used to write data from RAM to flash
-- ``spi_flash_erase_sector`` used to erase individual sectors of flash
-- ``spi_flash_erase_range`` used to erase range of addresses in flash
-- ``spi_flash_get_chip_size`` returns flash chip size, in bytes, as configured in menuconfig
+- :cpp:func:`spi_flash_read` used to read data from flash to RAM
+- :cpp:func:`spi_flash_write` used to write data from RAM to flash
+- :cpp:func:`spi_flash_erase_sector` used to erase individual sectors of flash
+- :cpp:func:`spi_flash_erase_range` used to erase range of addresses in flash
+- :cpp:func:`spi_flash_get_chip_size` returns flash chip size, in bytes, as configured in menuconfig
Generally, try to avoid using the raw SPI flash functions in favour of
-partition-specific functions.
+:ref:`partition-specific functions <flash-partition-apis>`.
SPI Flash Size
--------------
By default, the SPI flash size is detected by esptool.py when this bootloader is
written to flash, and the header is updated with the correct
-size. Alternatively, it is possible to generate a fixed flash size by disabling
-detection in ``make menuconfig`` (under Serial Flasher Config).
+size. Alternatively, it is possible to generate a fixed flash size by setting
+:ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``.
If it is necessary to override the configured flash size at runtime, is is
possible to set the ``chip_size`` member of ``g_rom_flashchip`` structure. This
-----------------------
Because the SPI flash is also used for firmware execution (via the instruction &
-data caches), these caches much be disabled while reading/writing/erasing. This
+data caches), these caches must be disabled while reading/writing/erasing. This
means that both CPUs must be running code from IRAM and only reading data from
DRAM while flash write operations occur.
+If you use the APIs documented here, then this happens automatically and
+transparently. However note that it will have some performance impact on other
+tasks in the system.
+
Refer to the :ref:`application memory layout <memory-layout>` documentation for
an explanation of the differences between IRAM, DRAM and flash cache.
crash due to Illegal Instruction exception (for code which should be in IRAM) or
garbage data to be read (for constant data which should be in DRAM).
+.. _flash-partition-apis:
+
Partition table APIs
--------------------
This component provides APIs to enumerate partitions found in the partition table
and perform operations on them. These functions are declared in ``esp_partition.h``:
-- ``esp_partition_find`` used to search partition table for entries with
+- :cpp:func:`esp_partition_find` used to search partition table for entries with
specific type, returns an opaque iterator
-- ``esp_partition_get`` returns a structure describing the partition, for the given iterator
-- ``esp_partition_next`` advances iterator to the next partition found
-- ``esp_partition_iterator_release`` releases iterator returned by ``esp_partition_find``
-- ``esp_partition_find_first`` is a convenience function which returns structure
+- :cpp:func:`esp_partition_get` returns a structure describing the partition, for the given iterator
+- :cpp:func:`esp_partition_next` advances iterator to the next partition found
+- :cpp:func:`esp_partition_iterator_release` releases iterator returned by ``esp_partition_find``
+- :cpp:func:`esp_partition_find_first` is a convenience function which returns structure
describing the first partition found by esp_partition_find
-- ``esp_partition_read``, ``esp_partition_write``, ``esp_partition_erase_range``
- are equivalent to ``spi_flash_read``, ``spi_flash_write``,
- ``spi_flash_erase_range``, but operate within partition boundaries
+- :cpp:func:`esp_partition_read`, :cpp:func:`esp_partition_write`, :cpp:func:`esp_partition_erase_range`
+ are equivalent to :cpp:func:`spi_flash_read`, :cpp:func:`spi_flash_write`,
+ :cpp:func:`spi_flash_erase_range`, but operate within partition boundaries
-Most application code should use ``esp_partition_*`` APIs instead of lower level
-``spi_flash_*`` APIs. Partition APIs do bounds checking and calculate correct
-offsets in flash based on data stored in partition table.
+.. note::
+ Most application code should use these ``esp_partition_*`` APIs instead of lower level
+ ``spi_flash_*`` APIs. Partition APIs do bounds checking and calculate correct
+ offsets in flash based on data stored in partition table.
SPI Flash Encryption
--------------------
Memory mapping APIs are declared in ``esp_spi_flash.h`` and ``esp_partition.h``:
-- ``spi_flash_mmap`` maps a region of physical flash addresses into instruction space or data space of the CPU
-- ``spi_flash_munmap`` unmaps previously mapped region
-- ``esp_partition_mmap`` maps part of a partition into the instruction space or data space of the CPU
+- :cpp:func:`spi_flash_mmap` maps a region of physical flash addresses into instruction space or data space of the CPU
+- :cpp:func:`spi_flash_munmap` unmaps previously mapped region
+- :cpp:func:`esp_partition_mmap` maps part of a partition into the instruction space or data space of the CPU
-Differences between ``spi_flash_mmap`` and ``esp_partition_mmap`` are as follows:
+Differences between :cpp:func:`spi_flash_mmap` and :cpp:func:`esp_partition_mmap` are as follows:
-- ``spi_flash_mmap`` must be given a 64KB aligned physical address
-- ``esp_partition_mmap`` may be given an arbitrary offset within the partition,
+- :cpp:func:`spi_flash_mmap` must be given a 64KB aligned physical address
+- :cpp:func:`esp_partition_mmap` may be given any arbitrary offset within the partition,
it will adjust returned pointer to mapped memory as necessary
Note that because memory mapping happens in 64KB blocks, it may be possible to
/**
* @brief Write data to Flash.
*
- * @note If source address is in DROM, this function will return
- * ESP_ERR_INVALID_ARG.
+ * @note For fastest write performance, write a 4 byte aligned size at a
+ * 4 byte aligned offset in flash from a source buffer in DRAM. Varying any of
+ * these parameters will still work, but will be slower due to buffering.
*
- * @param dest_addr destination address in Flash. Must be a multiple of 4 bytes.
- * @param src pointer to the source buffer.
- * @param size length of data, in bytes. Must be a multiple of 4 bytes.
+ * @note Writing more than 8KB at a time will be split into multiple
+ * write operations to avoid disrupting other tasks in the system.
+ *
+ * @param dest_addr Destination address in Flash.
+ * @param src Pointer to the source buffer.
+ * @param size Length of data, in bytes.
*
* @return esp_err_t
*/
* absolute best performance, both dest_addr and size arguments should
* be multiples of 32 bytes.
*
- * @param dest_addr destination address in Flash. Must be a multiple of 16 bytes.
- * @param src pointer to the source buffer.
- * @param size length of data, in bytes. Must be a multiple of 16 bytes.
+ * @param dest_addr Destination address in Flash. Must be a multiple of 16 bytes.
+ * @param src Pointer to the source buffer.
+ * @param size Length of data, in bytes. Must be a multiple of 16 bytes.
*
* @return esp_err_t
*/
/**
* @brief Read data from Flash.
*
+ * @note For fastest read performance, all parameters should be
+ * 4 byte aligned. If source address and read size are not 4 byte
+ * aligned, read may be split into multiple flash operations. If
+ * destination buffer is not 4 byte aligned, a temporary buffer will
+ * be allocated on the stack.
+ *
+ * @note Reading more than 16KB of data at a time will be split
+ * into multiple reads to avoid disruption to other tasks in the
+ * system. Consider using spi_flash_mmap() to read large amounts
+ * of data.
+ *
* @param src_addr source address of the data in Flash.
* @param dest pointer to the destination buffer
* @param size length of data
*
+ *
* @return esp_err_t
*/
esp_err_t spi_flash_read(size_t src_addr, void *dest, size_t size);
/**
* @brief Map region of flash memory into data or instruction address space
*
- * This function allocates sufficient number of 64k MMU pages and configures
- * them to map request region of flash memory into data address space or into
- * instruction address space. It may reuse MMU pages which already provide
- * required mapping. As with any allocator, there is possibility of fragmentation
- * of address space if mmap/munmap are heavily used. To troubleshoot issues with
- * page allocation, use spi_flash_mmap_dump function.
+ * This function allocates sufficient number of 64kB MMU pages and configures
+ * them to map the requested region of flash memory into the address space.
+ * It may reuse MMU pages which already provide the required mapping.
+ *
+ * As with any allocator, if mmap/munmap are heavily used then the address space
+ * may become fragmented. To troubleshoot issues with page allocation, use
+ * spi_flash_mmap_dump() function.
*
* @param src_addr Physical address in flash where requested region starts.
* This address *must* be aligned to 64kB boundary
- * (SPI_FLASH_MMU_PAGE_SIZE).
- * @param size Size of region which has to be mapped. This size will be rounded
- * up to a 64k boundary.
- * @param memory Memory space where the region should be mapped
+ * (SPI_FLASH_MMU_PAGE_SIZE)
+ * @param size Size of region to be mapped. This size will be rounded
+ * up to a 64kB boundary
+ * @param memory Address space where the region should be mapped (data or instruction)
* @param out_ptr Output, pointer to the mapped memory region
* @param out_handle Output, handle which should be used for spi_flash_munmap call
*
/**
* @brief Map sequences of pages of flash memory into data or instruction address space
*
- * This function allocates sufficient number of 64k MMU pages and configures
- * them to map the indicated pages of flash memory contiguously into data address
- * space or into instruction address space. In this respect, it works in a similar
- * way as spi_flash_mmap but it allows mapping a (maybe non-contiguous) set of pages
- * into a contiguous region of memory.
+ * This function allocates sufficient number of 64kB MMU pages and configures
+ * them to map the indicated pages of flash memory contiguously into address space.
+ * In this respect, it works in a similar way as spi_flash_mmap() but it allows mapping
+ * a (maybe non-contiguous) set of pages into a contiguous region of memory.
*
- * @param pages An array of numbers indicating the 64K pages in flash to be mapped
- * contiguously into memory. These indicate the indexes of the 64K pages,
+ * @param pages An array of numbers indicating the 64kB pages in flash to be mapped
+ * contiguously into memory. These indicate the indexes of the 64kB pages,
* not the byte-size addresses as used in other functions.
- * @param pagecount Size of the pages array
- * @param memory Memory space where the region should be mapped
+ * @param pagecount Number of entries in the pages array
+ * @param memory Address space where the region should be mapped (instruction or data)
* @param out_ptr Output, pointer to the mapped memory region
* @param out_handle Output, handle which should be used for spi_flash_munmap call
*
/**
* @brief Given a memory address where flash is mapped, return the corresponding physical flash offset.
*
- * Cache address does not have have been assigned via spi_flash_mmap(), any address in flash map space can be looked up.
+ * Cache address does not have have been assigned via spi_flash_mmap(), any address in memory mapped flash space can be looked up.
*
* @param cached Pointer to flashed cached memory.
*
* phys_offs is not 4-byte aligned, then reading from the returned pointer will result in a crash.
*
* @param phys_offs Physical offset in flash memory to look up.
- * @param memory Memory type to look up a flash cache address mapping for (IROM or DROM)
+ * @param memory Address space type to look up a flash cache address mapping for (instruction or data)
*
* @return
* - NULL if the physical address is invalid or not mapped to flash cache of the specified memory type.
/**
* @brief SPI flash critical section enter function.
+ *
*/
typedef void (*spi_flash_guard_start_func_t)(void);
/**
projects / esp-idf / commitdiff