Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge branch 'bugfix/doc_spi_flash' into 'master'

Browse source 
spi_flash: Update docs

See merge request idf/esp-idf!1961
This commit is contained in:
Angus Gratton 2018-02-22 11:09:17 +08:00
parent 672f8b057e b52b4ea2cc
commit e99b6ed79c
2 changed files with 79 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
components/spi_flash/README.rst
View file

@ -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

75
components/spi_flash/include/esp_spi_flash.h
View file

@ -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);
/**