kopia lustrzana https://github.com/espressif/esp-idf
Merge branch 'bugfix/doc_spi_flash' into 'master'
spi_flash: Update docs See merge request idf/esp-idf!1961pull/1593/merge
Angus Gratton
commit
e99b6ed79c
|
|
@ -18,14 +18,14 @@ SPI flash access APIs
|
|||
|
||||
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
|
||||
--------------
|
||||
|
|
@ -35,8 +35,8 @@ image header, flashed at offset 0x1000.
|
|||
|
||||
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
|
||||
|
|
@ -47,10 +47,14 @@ Concurrency Constraints
|
|||
-----------------------
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -99,6 +103,8 @@ handler reads from the flash cache during a flash operation, it will cause a
|
|||
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
|
||||
--------------------
|
||||
|
||||
|
|
@ -109,20 +115,21 @@ More information about partition tables can be found :doc:`here </api-guides/par
|
|||
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
|
||||
--------------------
|
||||
|
|
@ -151,14 +158,14 @@ Decryption is performed at hardware level.
|
|||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -77,12 +77,16 @@ esp_err_t spi_flash_erase_range(size_t start_address, size_t size);
|
|||
/**
|
||||
* @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
|
||||
*/
|
||||
|
|
@ -103,9 +107,9 @@ esp_err_t spi_flash_write(size_t dest_addr, const void *src, size_t size);
|
|||
* 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
|
||||
*/
|
||||
|
|
@ -114,10 +118,22 @@ esp_err_t spi_flash_write_encrypted(size_t dest_addr, const void *src, size_t si
|
|||
/**
|
||||
* @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);
|
||||
|
|
@ -155,19 +171,20 @@ typedef uint32_t spi_flash_mmap_handle_t;
|
|||
/**
|
||||
* @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
|
||||
*
|
||||
|
|
@ -179,17 +196,16 @@ esp_err_t spi_flash_mmap(size_t src_addr, size_t size, spi_flash_mmap_memory_t m
|
|||
/**
|
||||
* @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
|
||||
*
|
||||
|
|
@ -226,7 +242,7 @@ void spi_flash_mmap_dump();
|
|||
/**
|
||||
* @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.
|
||||
*
|
||||
|
|
@ -248,7 +264,7 @@ size_t spi_flash_cache2phys(const void *cached);
|
|||
* 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.
|
||||
|
|
@ -264,6 +280,7 @@ bool spi_flash_cache_enabled();
|
|||
|
||||
/**
|
||||
* @brief SPI flash critical section enter function.
|
||||
*
|
||||
*/
|
||||
typedef void (*spi_flash_guard_start_func_t)(void);
|
||||
/**
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue