mirror of
https://github.com/espressif/esp-idf.git
synced 2026-05-19 23:45:28 +02:00
docs: split spi_flash api-reference documents to peripherals folder
This commit is contained in:
Michael (XIAO Xufeng)
@@ -29,6 +29,7 @@ Peripherals API
|
||||
sdspi_host
|
||||
:SOC_SDIO_SLAVE_SUPPORTED: sdio_slave
|
||||
:SOC_SDM_SUPPORTED: sdm
|
||||
spi_flash/spi_flash
|
||||
spi_master
|
||||
spi_slave
|
||||
:esp32: secure_element
|
||||
|
||||
+9
-38
@@ -5,13 +5,18 @@ SPI Flash API
|
||||
|
||||
Overview
|
||||
--------
|
||||
The spi_flash component contains API functions related to reading, writing, erasing, memory mapping for data in the external 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>`.
|
||||
The spi_flash component contains API functions related to reading, writing, erasing, memory mapping for data in the external flash.
|
||||
|
||||
Different from the API before IDF v4.0, the functionality of `esp_flash_*` APIs is not limited to the "main" SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access external flash chips connected to not only SPI0/1 but also other SPI buses like SPI2.
|
||||
For higher-level API functions which work with partitions defined in the :doc:`partition table </api-guides/partition-tables>`, see :doc:`/api-reference/storage/partition`
|
||||
|
||||
.. note::
|
||||
``esp_partition_*`` APIs are recommended to be used instead of the lower level ``esp_flash_*`` API functions when accessing the main SPI Flash chip, since they do bounds checking and are guaranteed to calculate correct offsets in flash based on the information in the partition table. ``esp_flash_*`` functions can still be used directly when accessing an external (secondary) SPI flash chip.
|
||||
|
||||
Different from the API before IDF v4.0, the functionality of ``esp_flash_*`` APIs is not limited to the "main" SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access external flash chips connected to not only SPI0/1 but also other SPI buses like SPI2.
|
||||
|
||||
.. note::
|
||||
|
||||
Instead of going through the cache connected to the SPI0 peripheral, most `esp_flash_*` APIs go through other SPI peripherals like SPI1, SPI2, etc. This makes them able to access not only the main flash, but also external flash.
|
||||
Instead of going through the cache connected to the SPI0 peripheral, most ``esp_flash_*`` APIs go through other SPI peripherals like SPI1, SPI2, etc. This makes them able to access not only the main flash, but also external (secondary) flash.
|
||||
|
||||
However, due to limitations of the cache, operations through the cache are limited to the main flash. The address range limitation for these operations are also on the cache side. The cache is not able to access external flash chips or address range above its capabilities. These cache operations include: mmap, encrypted read/write, executing code or access to variables in the flash.
|
||||
|
||||
@@ -123,24 +128,6 @@ Concurrency Constraints for Flash on SPI1
|
||||
|
||||
The SPI0/1 bus is shared between the instruction & data cache (for firmware execution) and the SPI1 peripheral (controlled by the drivers including this SPI flash driver). Hence, calling SPI Flash API on SPI1 bus (including the main flash) will cause significant influence to the whole system. See :doc:`spi_flash_concurrency` for more details.
|
||||
|
||||
.. _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 can be found in :doc:`Partition Tables </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` 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:`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.
|
||||
|
||||
|
||||
SPI Flash Encryption
|
||||
@@ -240,14 +227,6 @@ It's pretty hard to totally eliminate this risk, because the erasing time varies
|
||||
|
||||
3. During your development, please carefully review the actual flash operation according to the specific requirements and time limits on erasing flash memory of your projects. Always allow reasonable redundancy based on your specific product requirements when configuring the flash erasing timeout threshold, thus improving the reliability of your product.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
|
||||
- :doc:`Over The Air Update (OTA) API <../system/ota>` provides high-level API for updating app firmware stored in flash.
|
||||
- :doc:`Non-Volatile Storage (NVS) API <nvs_flash>` provides a structured API for storing small pieces of data in SPI flash.
|
||||
|
||||
|
||||
.. _spi-flash-implementation-details:
|
||||
|
||||
Implementation Details
|
||||
@@ -276,15 +255,7 @@ API Reference - SPI Flash
|
||||
.. include-build-file:: inc/spi_flash_types.inc
|
||||
.. include-build-file:: inc/esp_flash_err.inc
|
||||
|
||||
.. _api-reference-partition-table:
|
||||
|
||||
API Reference - Partition Table
|
||||
-------------------------------
|
||||
|
||||
.. include-build-file:: inc/esp_partition.inc
|
||||
|
||||
API Reference - Flash Encrypt
|
||||
-----------------------------
|
||||
|
||||
.. include-build-file:: inc/esp_flash_encrypt.inc
|
||||
|
||||
.. include-build-file:: inc/esp_flash_encrypt.inc
|
||||
@@ -3,6 +3,21 @@ Storage API
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
|
||||
This section contains reference of the high-level storage APIs. They are based on low-level drivers such as SPI Flash, SD/MMC.
|
||||
|
||||
- :doc:`Partitions API <partition>` allow block based access to SPI Flash according to the :doc:`Partition Table </api-guides/partition-tables>`.
|
||||
- :doc:`Non-Volatile Storage library (NVS) <nvs_flash>` implements a fault-tolerant wear-levelled key-value storage in SPI NOR Flash.
|
||||
- :doc:`Virtual File System (VFS) <vfs>` library provides an interface for registration of file system drivers. SPIFFS, FAT and various other file system libraries are based on the VFS.
|
||||
- :doc:`SPIFFS <spiffs>` is a wear-levelled file system optimized for SPI NOR Flash, well suited for small partition sizes and low throughput
|
||||
- :doc:`FAT <fatfs>` is a standard file system which can be used in SPI Flash or on SD/MMC cards
|
||||
- :doc:`Wear Levelling <wear-levelling>` library implements a flash translation layer (FTL) suitable for SPI NOR Flash. It is used as a container for FAT partitions in Flash.
|
||||
|
||||
.. note::
|
||||
It's suggested to use high-level APIs (``esp_partition`` or file system) instead of low-level driver APIs to access the SPI NOR Flash.
|
||||
|
||||
Due to the restriction of NOR Flash and ESP hardware, accessing the main flash will affect the performance of the whole system. See :doc:`SPI Flash Documents </api-reference/peripherals/spi_flash/spi_flash>` to learn more about the limitations.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
@@ -12,11 +27,10 @@ Storage API
|
||||
nvs_partition_gen.rst
|
||||
nvs_partition_parse.rst
|
||||
sdmmc
|
||||
spi_flash
|
||||
partition
|
||||
spiffs
|
||||
vfs
|
||||
wear-levelling
|
||||
|
||||
|
||||
|
||||
Code examples for this API section are provided in the :example:`storage` directory of ESP-IDF examples.
|
||||
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
Partitions API
|
||||
==============
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ``esp_partition`` component has higher-level API functions which work with partitions defined in the :doc:`partition table </api-guides/partition-tables>`. These APIs are based on lower level API provided by :doc:`SPI Flash driver </api-reference/peripherals/spi_flash/spi_flash>`.
|
||||
|
||||
.. _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 can be found in :doc:`Partition Tables </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 :cpp:func:`esp_partition_find`.
|
||||
- :cpp:func:`esp_partition_find_first` is a convenience function which returns the structure describing the first partition found by :cpp:func:`esp_partition_find`.
|
||||
- :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.
|
||||
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
|
||||
- :doc:`Over The Air Update (OTA) API <../system/ota>` provides high-level API for updating applications stored in flash.
|
||||
- :doc:`Non-Volatile Storage (NVS) API <nvs_flash>` provides a structured API for storing small pieces of data in SPI flash.
|
||||
|
||||
|
||||
.. _api-reference-partition-table:
|
||||
|
||||
API Reference - Partition Table
|
||||
-------------------------------
|
||||
|
||||
.. include-build-file:: inc/esp_partition.inc
|
||||
@@ -295,7 +295,8 @@ See also
|
||||
--------
|
||||
|
||||
* :doc:`Partition Table documentation <../../api-guides/partition-tables>`
|
||||
* :doc:`Lower-Level SPI Flash/Partition API <../storage/spi_flash>`
|
||||
* :doc:`Partition API <../storage/partition>`
|
||||
* :doc:`Lower-Level SPI Flash API <../peripherals/spi_flash/spi_flash>`
|
||||
* :doc:`ESP HTTPS OTA <esp_https_ota>`
|
||||
|
||||
Application Example
|
||||
|
||||
@@ -99,7 +99,7 @@ The default timeout period for the TWDT is set using config item :ref:`CONFIG_ES
|
||||
- Increase :ref:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` in menuconfig for a larger watchdog timeout period.
|
||||
- You can also call :cpp:func:`esp_task_wdt_init` to increase the watchdog timeout period before erasing a large flash area.
|
||||
|
||||
For more information, you can refer to :doc:`SPI Flash <../storage/spi_flash>`.
|
||||
For more information, you can refer to :doc:`SPI Flash <../peripherals/spi_flash/spi_flash>`.
|
||||
|
||||
The following config options control TWDT configuration. They are all enabled by default:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user