mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
spi_flash: Modify documentations
This commit is contained in:
Cao Sen Miao
parent
64147c3794
commit
d9b4b82edc
@ -1,3 +1 @@
|
||||
See the spi_flash.rst in the programming guide folder for more details.
|
||||
|
||||
The docs above is for the new SPI Flash API above 4.0, for legacy implementation (CONFIG_SPI_FLASH_USE_LEGACY_IMPL enabled), read README_legayc.rst in the same folder with this readme.
|
||||
|
||||
@ -1,108 +0,0 @@
|
||||
SPI Flash API (Legacy)
|
||||
========================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
This is the readme for the APIs before IDF v4.0. Enable the kconfig option ``SPI_FLASH_USE_LEGACY_IMPL`` to use the
|
||||
legacy implementation.
|
||||
|
||||
The spi_flash component contains API functions related to reading, writing, erasing, memory mapping for data in the external SPI flash. The spi_flash component also has higher-level API functions which work with partitions defined in the :doc:`partition table </api-guides/partition-tables>`.
|
||||
|
||||
Note that all the functionality is limited to the "main" SPI flash chip, the same SPI flash chip from which programs are runs. For ``spi_flash_*`` functions, this is a software limitation. The underlying ROM functions which work with SPI flash do not have provisions for working with flash chips attached to SPI peripherals other than SPI0.
|
||||
|
||||
SPI flash access API
|
||||
--------------------
|
||||
|
||||
This is the set of API functions for working with data in flash:
|
||||
|
||||
- :cpp:func:`spi_flash_read` reads data from flash to RAM
|
||||
- :cpp:func:`spi_flash_write` writes data from RAM to flash
|
||||
- :cpp:func:`spi_flash_erase_sector` erases individual sectors of flash
|
||||
- :cpp:func:`spi_flash_erase_range` erases ranges 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 favor of :ref:`partition-specific functions <flash-partition-apis>`.
|
||||
|
||||
SPI Flash Size
|
||||
--------------
|
||||
|
||||
The SPI flash size is configured by writing a field in the software bootloader 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 setting :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in project configuration.
|
||||
|
||||
If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``spi_flash_*`` functions (in both software & ROM) to check the bounds.
|
||||
|
||||
Concurrency Constraints
|
||||
-----------------------
|
||||
|
||||
Because the SPI flash is also used for firmware execution via the instruction & data caches, these caches must be disabled while reading/writing/erasing. This means that both CPUs must be running code from IRAM and must only be reading data from DRAM while flash write operations occur.
|
||||
|
||||
If you use the API functions documented here, then these constraints are applied automatically and transparently. However, note that it will have some performance impact on other tasks in the system.
|
||||
|
||||
For differences between IRAM, DRAM, and flash cache, please refer to the :ref:`application memory layout <memory-layout>` documentation.
|
||||
|
||||
To avoid reading flash cache accidentally, when one CPU initiates a flash write or erase operation, the other CPU is put into a blocked state, and all non-IRAM-safe interrupts are disabled on both CPUs until the flash operation completes.
|
||||
|
||||
If one CPU initiates a flash write or erase operation, the other CPU is put into a blocked state to avoid reading flash cache accidentally. All interrupts not safe for IRAM are disabled on both CPUs until the flash operation completes.
|
||||
|
||||
.. _iram-safe-interrupt-handlers:
|
||||
|
||||
IRAM-Safe Interrupt Handlers
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you have an interrupt handler that you want to execute while a flash operation is in progress (for example, for low latency operations), set the ``ESP_INTR_FLAG_IRAM`` flag when the :doc:`interrupt handler is registered </api-reference/system/intr_alloc>`.
|
||||
|
||||
You must ensure that all data and functions accessed by these interrupt handlers, including the ones that handlers call, are located in IRAM or DRAM. See :ref:`how-to-place-code-in-iram`.
|
||||
|
||||
If a function or symbol is not correctly put into IRAM/DRAM, and the interrupt 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 API
|
||||
-------------------
|
||||
|
||||
ESP-IDF projects use a partition table to maintain information about various regions of SPI flash memory (bootloader, various application binaries, data, filesystems). More information on partition tables can be found :doc:`here </api-guides/partition-tables>`.
|
||||
|
||||
This component provides API functions to enumerate partitions found in the partition table and perform operations on them. These functions are declared in ``esp_partition.h``:
|
||||
|
||||
- :cpp:func:`esp_partition_find` checks a partition table for entries with specific type, returns an opaque iterator.
|
||||
- :cpp:func:`esp_partition_get` returns a structure describing the partition for a given iterator.
|
||||
- :cpp:func:`esp_partition_next` shifts the iterator to the next found partition.
|
||||
- :cpp:func:`esp_partition_iterator_release` releases iterator returned by ``esp_partition_find``.
|
||||
- :cpp:func:`esp_partition_find_first` - a convenience function which returns the structure describing the first partition found by ``esp_partition_find``.
|
||||
- :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.
|
||||
|
||||
.. note::
|
||||
Application code should mostly use these ``esp_partition_*`` API functions instead of lower level ``spi_flash_*`` API functions. Partition table API functions do bounds checking and calculate correct offsets in flash, based on data stored in a partition table.
|
||||
|
||||
SPI Flash Encryption
|
||||
--------------------
|
||||
|
||||
It is possible to encrypt the contents of SPI flash and have it transparently decrypted by hardware.
|
||||
|
||||
Refer to the :doc:`Flash Encryption documentation </security/flash-encryption>` for more details.
|
||||
|
||||
Memory mapping API
|
||||
------------------
|
||||
|
||||
ESP32 features memory hardware which allows regions of flash memory to be mapped into instruction and data address spaces. This mapping works only for read operations. It is not possible to modify contents of flash memory by writing to a mapped memory region.
|
||||
|
||||
Mapping happens in 64KB pages. Memory mapping hardware can map up to four megabytes of flash into data address space and up to 16 megabytes of flash into instruction address space. See the technical reference manual for more details about memory mapping hardware.
|
||||
|
||||
Note that some 64KB pages are used to map the application itself into memory, so the actual number of available 64KB pages may be less.
|
||||
|
||||
Reading data from flash using a memory mapped region is the only way to decrypt contents of flash when :doc:`flash encryption </security/flash-encryption>` is enabled. Decryption is performed at the hardware level.
|
||||
|
||||
Memory mapping API are declared in ``esp_spi_flash.h`` and ``esp_partition.h``:
|
||||
|
||||
- :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 :cpp:func:`spi_flash_mmap` and :cpp:func:`esp_partition_mmap` are as follows:
|
||||
|
||||
- :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 the returned pointer to mapped memory as necessary
|
||||
|
||||
Note that since memory mapping happens in 64KB blocks, it may be possible to read data outside of the partition provided to ``esp_partition_mmap``.
|
||||
@ -206,7 +206,7 @@ INPUT = \
|
||||
$(PROJECT_PATH)/components/spi_flash/include/esp_flash.h \
|
||||
$(PROJECT_PATH)/components/spi_flash/include/esp_flash_spi_init.h \
|
||||
$(PROJECT_PATH)/components/spi_flash/include/esp_partition.h \
|
||||
$(PROJECT_PATH)/components/spi_flash/include/esp_spi_flash.h \
|
||||
$(PROJECT_PATH)/components/spi_flash/include/spi_flash_mmap.h \
|
||||
$(PROJECT_PATH)/components/spiffs/include/esp_spiffs.h \
|
||||
$(PROJECT_PATH)/components/tinyusb/additions/include/tinyusb.h \
|
||||
$(PROJECT_PATH)/components/tinyusb/additions/include/tinyusb_types.h \
|
||||
|
||||
@ -1034,7 +1034,7 @@ For example, in the ``foo/CMakeLists.txt`` file::
|
||||
add_library(foo bar.c fizz.cpp buzz.cpp)
|
||||
|
||||
if(ESP_PLATFORM)
|
||||
# On ESP-IDF, bar.c needs to include esp_spi_flash.h from the spi_flash component
|
||||
# On ESP-IDF, bar.c needs to include esp_flash.h from the spi_flash component
|
||||
target_link_libraries(foo PRIVATE idf::spi_flash)
|
||||
endif()
|
||||
|
||||
|
||||
@ -19,10 +19,9 @@ Different from the API before IDF v4.0, the functionality of `esp_flash_*` APIs
|
||||
|
||||
Flash APIs after ESP-IDF v4.0 are no longer *atomic*. If a write operation occurs during another on-going read operation, and the flash addresses of both operations overlap, the data returned from the read operation may contain both old data and new data (that was updated written by the write operation).
|
||||
|
||||
.. note::
|
||||
|
||||
Kconfig option :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL` can be used to switch ``spi_flash_*`` functions back to the implementation before ESP-IDF v4.0. However, the code size may get bigger if you use the new API and the old API at the same time.
|
||||
|
||||
Encrypted reads and writes use the old implementation, even if :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL` is not enabled. As such, encrypted flash operations are only supported with the main flash chip (and not with other flash chips, that is on SPI1 with different CS, or on other SPI buses). Reading through cache is only supported on the main flash, which is determined by the HW.
|
||||
Encrypted flash operations are only supported with the main flash chip (and not with other flash chips, that is on SPI1 with different CS, or on other SPI buses). Reading through cache is only supported on the main flash, which is determined by the HW.
|
||||
|
||||
Support for Features of Flash Chips
|
||||
-----------------------------------
|
||||
@ -138,7 +137,7 @@ This component provides API functions to enumerate partitions found in the parti
|
||||
- :cpp:func:`esp_partition_next` shifts the iterator to the next found partition.
|
||||
- :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 the structure describing the first partition found by ``esp_partition_find``.
|
||||
- :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.
|
||||
- :cpp:func:`esp_partition_read`, :cpp:func:`esp_partition_write`, :cpp:func:`esp_partition_erase_range` are equivalent to :cpp:func:`esp_flash_read`, :cpp:func:`esp_flash_write`, :cpp:func:`esp_flash_erase_region`, but operate within partition boundaries.
|
||||
|
||||
.. note::
|
||||
Application code should mostly use these ``esp_partition_*`` API functions instead of lower level ``esp_flash_*`` API functions. Partition table API functions do bounds checking and calculate correct offsets in flash, based on data stored in a partition table.
|
||||
@ -164,7 +163,7 @@ Note that some pages are used to map the application itself into memory, so the
|
||||
|
||||
Reading data from flash using a memory mapped region is the only way to decrypt contents of flash when :doc:`flash encryption </security/flash-encryption>` is enabled. Decryption is performed at the hardware level.
|
||||
|
||||
Memory mapping API are declared in ``esp_spi_flash.h`` and ``esp_partition.h``:
|
||||
Memory mapping API are declared in ``spi_flash_mmap.h`` and ``esp_partition.h``:
|
||||
|
||||
- :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.
|
||||
@ -273,7 +272,7 @@ API Reference - SPI Flash
|
||||
|
||||
.. include-build-file:: inc/esp_flash_spi_init.inc
|
||||
.. include-build-file:: inc/esp_flash.inc
|
||||
.. include-build-file:: inc/esp_spi_flash.inc
|
||||
.. include-build-file:: inc/spi_flash_mmap.inc
|
||||
.. include-build-file:: inc/spi_flash_types.inc
|
||||
.. include-build-file:: inc/esp_flash_err.inc
|
||||
|
||||
|
||||
@ -32,6 +32,20 @@ ENUM type ``esp_flash_speed_t`` has been deprecated. From now on, you can direct
|
||||
// Other members
|
||||
};
|
||||
|
||||
Breaking changes in legacy APIs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to make spi_flash driver more stable, legacy spi_flash driver is removed on v5.0. Legacy spi_flash driver refers to default spi_flash driver since v3.0 and spi_flash driver with configuration option ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` switched on on v4.0 series. The major breaking change is we don't support legacy spi_flash driver on v5.0 anymore. Therefore, the configuration option ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` is removed. After that, following functions will no longer exist. But meanwhile, you can use our new APIs instead.
|
||||
|
||||
- ``spi_flash_erase_sector`` is replaced by ``esp_flash_erase_region``.
|
||||
- ``spi_flash_erase_range`` is replaced by ``esp_flash_erase_region``.
|
||||
- ``spi_flash_write`` is replaced by ``esp_flash_write``.
|
||||
- ``spi_flash_read`` is replaced by ``esp_flash_read``.
|
||||
- ``spi_flash_write_encrypted`` is replaced by ``esp_flash_write_encrypted``
|
||||
- ``spi_flash_read_encrypted`` is replaced by ``esp_flash_read_encrypted``
|
||||
|
||||
Header ``esp_spi_flash.h`` has been deprecated, system functions are no longer public. To make use of flash memory mapping APIs, you should include ``spi_flash_mmap.h`` instead.
|
||||
|
||||
ADC
|
||||
---
|
||||
|
||||
|
||||
@ -1034,7 +1034,7 @@ CMake 在许多开源的 C/C++ 项目中广泛使用，用户可以在自己的
|
||||
add_library(foo bar.c fizz.cpp buzz.cpp)
|
||||
|
||||
if(ESP_PLATFORM)
|
||||
# 在 ESP-IDF 中、 bar.c 需要包含 spi_flash 组件中的 esp_spi_flash.h
|
||||
# 在 ESP-IDF 中、 bar.c 需要包含 spi_flash 组件中的 esp_flash.h
|
||||
target_link_libraries(foo PRIVATE idf::spi_flash)
|
||||
endif()
|
||||
|
||||
|
||||
@ -19,10 +19,9 @@ spi_flash 组件提供外部 flash 数据读取、写入、擦除和内存映射
|
||||
|
||||
ESP-IDF V4.0 之后的 flash API 不再是 *原子* 的。因此，如果读操作执行过程中发生写操作，且读操作和写操作的 flash 地址出现重叠，读操作返回的数据可能会包含旧数据和新数据 (新数据为写操作更新产生的数据)。
|
||||
|
||||
.. note::
|
||||
|
||||
Kconfig 选项 :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL` 可将 ``spi_flash_*`` 函数切换至 ESP-IDF V4.0 之前的实现。但是，如果同时使用新旧 API，代码量可能会增多。
|
||||
|
||||
即使未启用 :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL`，加密读取和加密写入操作也均使用旧实现。因此，仅有主 flash 芯片支持加密操作，外接（经 SPI1 使用其他不同片选访问，或经其它 SPI 总线访问）的 flash 芯片则不支持加密操作。硬件的限制也决定了仅有主 flash 支持从 cache 当中读取。
|
||||
仅有主 flash 芯片支持加密操作，外接（经 SPI1 使用其他不同片选访问，或经其它 SPI 总线访问）的 flash 芯片则不支持加密操作。硬件的限制也决定了仅有主 flash 支持从 cache 当中读取。
|
||||
|
||||
Flash 功能支持情况
|
||||
-----------------------------------
|
||||
@ -138,7 +137,7 @@ ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导程序
|
||||
- :cpp:func:`esp_partition_next`：将迭代器移至下一个找到的分区；
|
||||
- :cpp:func:`esp_partition_iterator_release`：释放 ``esp_partition_find`` 中返回的迭代器；
|
||||
- :cpp:func:`esp_partition_find_first`：返回描述 ``esp_partition_find`` 中找到的第一个分区的结构；
|
||||
- :cpp:func:`esp_partition_read`、:cpp:func:`esp_partition_write` 和 :cpp:func:`esp_partition_erase_range` 等同于 :cpp:func:`spi_flash_read`、:cpp:func:`spi_flash_write` 和 :cpp:func:`spi_flash_erase_range`，但在分区边界内执行。
|
||||
- :cpp:func:`esp_partition_read`、:cpp:func:`esp_partition_write` 和 :cpp:func:`esp_partition_erase_range` 等同于 :cpp:func:`esp_flash_read`、:cpp:func:`esp_flash_write` 和 :cpp:func:`esp_flash_erase_region`，但在分区边界内执行。
|
||||
|
||||
.. note::
|
||||
请在应用程序代码中使用上述 ``esp_partition_*`` API 函数，而非低层级的 ``esp_flash_*`` API 函数。分区表 API 函数根据存储在分区表中的数据，进行边界检查并计算在 flash 中的正确偏移量。
|
||||
@ -164,7 +163,7 @@ Flash 在 {IDF_TARGET_CACHE_SIZE} 页进行映射。内存映射硬件既可将
|
||||
|
||||
启用 :doc:`Flash 加密 </security/flash-encryption>` 时，使用内存映射区域从 flash 读取数据是解密 flash 的唯一方法，解密需在硬件层进行。
|
||||
|
||||
内存映射 API 在 ``esp_spi_flash.h`` 和 ``esp_partition.h`` 中声明：
|
||||
内存映射 API 在 ``spi_flash_mmap.h`` 和 ``esp_partition.h`` 中声明：
|
||||
|
||||
- :cpp:func:`spi_flash_mmap`：将 flash 物理地址区域映射到 CPU 指令空间或数据空间；
|
||||
- :cpp:func:`spi_flash_munmap`：取消上述区域的映射；
|
||||
@ -273,7 +272,7 @@ SPI Flash API 参考
|
||||
|
||||
.. include-build-file:: inc/esp_flash_spi_init.inc
|
||||
.. include-build-file:: inc/esp_flash.inc
|
||||
.. include-build-file:: inc/esp_spi_flash.inc
|
||||
.. include-build-file:: inc/spi_flash_mmap.inc
|
||||
.. include-build-file:: inc/spi_flash_types.inc
|
||||
.. include-build-file:: inc/esp_flash_err.inc
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user