Merge branch 'feat/codeowner_spi_flash_docs' into 'master'

docs/spi_flash: add peripherals to codowner of spi_flash doc pages

See merge request espressif/esp-idf!20311

components/driver/include/driver/rmt_encoder.h

@@ -15,10 +15,9 @@
 extern "C" {
 #endif
 
-/**
- * @brief Type of RMT encoder
- */
+/** @cond */
 typedef struct rmt_encoder_t rmt_encoder_t;
+/** @endcond */
 
 /**
  * @brief RMT encoding state

components/driver/include/driver/spi_master.h

@@ -45,7 +45,9 @@ extern "C"
 #define SPI_DEVICE_DDRCLK                  (1<<7)
 #define SPI_DEVICE_NO_RETURN_RESULT        (1<<8)  ///< Don't return the descriptor to the host on completion (use post_cb to notify instead)
 
+/** @cond */
 typedef struct spi_transaction_t spi_transaction_t;
+/** @endcond */
 typedef void(*transaction_cb_t)(spi_transaction_t *trans);
 
 /**

components/driver/include/driver/spi_slave.h

@@ -25,7 +25,9 @@ extern "C"
 #define SPI_SLAVE_BIT_LSBFIRST            (SPI_SLAVE_TXBIT_LSBFIRST|SPI_SLAVE_RXBIT_LSBFIRST) ///< Transmit and receive LSB first
 #define SPI_SLAVE_NO_RETURN_RESULT        (1<<2)  ///< Don't return the descriptor to the host on completion (use `post_trans_cb` to notify instead)
 
+/** @cond */
 typedef struct spi_slave_transaction_t spi_slave_transaction_t;
+/** @endcond */
 typedef void(*slave_transaction_cb_t)(spi_slave_transaction_t *trans);
 
 /**

components/spi_flash/include/esp_flash.h

@@ -18,7 +18,9 @@ extern "C" {
 struct spi_flash_chip_t;
 typedef struct spi_flash_chip_t spi_flash_chip_t;
 
+/** @cond */
 typedef struct esp_flash_t esp_flash_t;
+/** @endcond */
 
 /** @brief Structure for describing a region of flash */
 typedef struct {

docs/en/api-guides/build-system.rst

@@ -610,7 +610,7 @@ Adding Link-Time Dependencies
 
 .. highlight:: cmake
 
-The ESP-IDF CMake helper function ``idf_component_add_link_dependency`` adds a link-only dependency between one component and another. In almost all cases, it is better to use the ``PRIV_REQUIRES`` feature in ``idf_component_register`` to create a dependency. However, in some cases, it's necessary to add the link-time dependency of another component to this component, i.e., the reverse order to ``PRIV_REQUIRES`` (for example: :doc:`/api-reference/storage/spi_flash_override_driver`).
+The ESP-IDF CMake helper function ``idf_component_add_link_dependency`` adds a link-only dependency between one component and another. In almost all cases, it is better to use the ``PRIV_REQUIRES`` feature in ``idf_component_register`` to create a dependency. However, in some cases, it's necessary to add the link-time dependency of another component to this component, i.e., the reverse order to ``PRIV_REQUIRES`` (for example: :doc:`/api-reference/peripherals/spi_flash/spi_flash_override_driver`).
 
 To make another component depend on this component at link time::
 

docs/en/api-reference/peripherals/index.rst

@@ -29,6 +29,7 @@ Peripherals API
     sdspi_host
     :SOC_SDIO_SLAVE_SUPPORTED: sdio_slave
     :SOC_SDM_SUPPORTED: sdm
+    spi_flash/index
     spi_master
     spi_slave
     :esp32: secure_element

docs/en/api-reference/storage/spi_flash.rst → docs/en/api-reference/peripherals/spi_flash/index.rst

@@ -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.
 
-    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.
+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 (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

docs/en/api-reference/storage/index.rst

@@ -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/index>` 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.
+

docs/en/api-reference/storage/partition.rst

@@ -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/index>`.
+
+.. _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

docs/en/api-reference/system/ota.rst

@@ -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/index>`
 * :doc:`ESP HTTPS OTA <esp_https_ota>`
 
 Application Example

docs/en/api-reference/system/wdts.rst

@@ -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/index>`.
 
 The following config options control TWDT configuration. They are all enabled by default:
 

docs/page_redirects.txt

@@ -23,6 +23,12 @@ api-reference/wifi/esp_smartconfig              api-reference/network/esp_smartc
 api-reference/wifi/esp_wifi                     api-reference/network/esp_wifi
 api-reference/system/tcpip_adapter              migration-guides/tcpip-adapter
 api-reference/system/esp_pthread                api-reference/system/pthread
+api-reference/storage/spi_flash                 api-reference/peripherals/spi_flash/index
+api-reference/storage/spi_flash_concurrency     api-reference/peripherals/spi_flash/spi_flash_concurrency
+api-reference/storage/spi_flash_override_driver api-reference/peripherals/spi_flash/spi_flash_override_driver
+api-reference/storage/spi_flash_optional_feature    api-reference/peripherals/spi_flash/spi_flash_optional_feature
+
+
 get-started/idf-monitor                         api-guides/tools/idf-monitor
 get-started-cmake/idf-monitor                   api-guides/tools/idf-monitor
 get-started/get-started-devkitc                 hw-reference/esp32/get-started-devkitc

docs/sphinx-known-warnings.txt

@@ -9,12 +9,6 @@
 idf-component-manager.rst: WARNING: Badly formated string substitution: {IDF_TARGET}
 esp_ble_mesh_defs.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/bluetooth/esp-ble-mesh:line.
 Declaration is '.. cpp:member:: uint16_t model_id'.
-rmt_encoder.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/peripherals/rmt:line.
-Declaration is '.. cpp:type:: struct rmt_encoder_t rmt_encoder_t'.
-spi_master.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/peripherals/spi_master:line.
-Declaration is '.. cpp:type:: struct spi_transaction_t spi_transaction_t'.
-spi_slave.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/peripherals/spi_slave:line.
-Declaration is '.. cpp:type:: struct spi_slave_transaction_t spi_slave_transaction_t'.
 mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/protocols/mqtt:line.
 Declaration is '.. cpp:type:: struct esp_mqtt_event_t esp_mqtt_event_t'.
 mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/protocols/mqtt:line.
@@ -29,8 +23,6 @@ mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at api-re
 Declaration is '.. cpp:enum:: esp_mqtt_transport_t'.
 mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/protocols/mqtt:line.
 Declaration is '.. cpp:enum:: esp_mqtt_protocol_ver_t'.
-esp_flash.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/spi_flash:line.
-Declaration is '.. cpp:type:: struct esp_flash_t esp_flash_t'.
 wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
 Declaration is '.. cpp:struct:: esp_vfs_fat_mount_config_t'.
 wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.

docs/zh_CN/api-guides/build-system.rst

@@ -610,7 +610,7 @@ CMake 通常会在链接器命令行上重复两次组件库名称来自动处
 
 .. highlight:: cmake
 
-ESP-IDF 的 CMake 辅助函数 ``idf_component_add_link_dependency`` 可以在组件之间添加仅作用于链接时的依赖关系。绝大多数情况下，我们都建议您使用 ``idf_component_register`` 中的 ``PRIV_REQUIRES`` 功能来构建依赖关系。然而在某些情况下，还是有必要添加另一个组件对当前组件的链接时依赖，即反转 ``PRIV_REQUIRES`` 中的依赖关系（参考示例：:doc:`/api-reference/storage/spi_flash_override_driver`）。
+ESP-IDF 的 CMake 辅助函数 ``idf_component_add_link_dependency`` 可以在组件之间添加仅作用于链接时的依赖关系。绝大多数情况下，我们都建议您使用 ``idf_component_register`` 中的 ``PRIV_REQUIRES`` 功能来构建依赖关系。然而在某些情况下，还是有必要添加另一个组件对当前组件的链接时依赖，即反转 ``PRIV_REQUIRES`` 中的依赖关系（参考示例：:doc:`/api-reference/peripherals/spi_flash/spi_flash_override_driver`）。
 
 要使另一个组件在链接时依赖于这个组件::
 

docs/zh_CN/api-reference/peripherals/index.rst

@@ -29,6 +29,7 @@
     sdspi_host
     :SOC_SDIO_SLAVE_SUPPORTED: sdio_slave
     :SOC_SDM_SUPPORTED: sdm
+    spi_flash/index
     spi_master
     spi_slave
     :esp32: secure_element

docs/zh_CN/api-reference/storage/spi_flash.rst → docs/zh_CN/api-reference/peripherals/spi_flash/index.rst

@@ -5,13 +5,18 @@ SPI Flash API
 
 概述
 --------
-spi_flash 组件提供外部 flash 数据读取、写入、擦除和内存映射相关的 API 函数，同时也提供了更高层级的、面向分区的 API 函数（定义在 :doc:`分区表 </api-guides/partition-tables>` 中）。
+spi_flash 组件提供外部 flash 数据读取、写入、擦除和内存映射相关的 API 函数。
 
-与 ESP-IDF V4.0 之前的 API 不同，这一版 `esp_flash_*` API 功能并不局限于主 SPI flash 芯片（即运行程序的 SPI flash 芯片）。使用不同的芯片指针，您可以访问连接到 SPI0/1 或 SPI2 总线的外部 flash 芯片。
+关于更多高层次的用于访问分区（分区表定义于 :doc:`分区表 </api-guides/partition-tables>`）的 API 函数，参见 :doc:`/api-reference/storage/partition` 。
 
 .. note::
+    访问主 flash 芯片时，建议使用上述 ``esp_partition_*`` API 函数，而非低层级的 ``esp_flash_*`` API 函数。分区表 API 函数根据存储在分区表中的数据，进行边界检查并计算在 flash 中的正确偏移量。不过，您仍可以使用 ``esp_flash_*`` 函数直接访问外部（额外）的 SPI flash 芯片。
 
-    大多数 `esp_flash_*` API 使用 SPI1，SPI2 等外设而非通过 SPI0 上的 cache。这使得它们不仅能访问主 flash，也能访问外部 flash 。
+与 ESP-IDF V4.0 之前的 API 不同，这一版 ``esp_flash_*`` API 功能并不局限于主 SPI flash 芯片（即运行程序的 SPI flash 芯片）。使用不同的芯片指针，您可以访问连接到 SPI0/1 或 SPI2 总线的外部 flash 芯片。
+
+.. note::
+
+    大多数 ``esp_flash_*`` API 使用 SPI1，SPI2 等外设而非通过 SPI0 上的 cache。这使得它们不仅能访问主 flash，也能访问外部 flash 。
 
     而由于 cache 的限制，所有经过 cache 的操作都只能对主 flash 进行。这些操作的地址同样受到 cache 能力的限制。Cache 无法访问外部 flash 或者高于它能力的地址段。这些 cache 操作包括：mmap ，加密读写，执行代码或者访问在 flash 中的变量。
 
@@ -123,26 +128,6 @@ SPI1 Flash 并发约束
 
     指令/数据 cache（用以执行固件）与 SPI1 外设（由像 SPI flash 驱动一样的驱动程序控制）共享 SPI0/1 总线。因此，在 SPI1 总线上调用 SPI flash API（包括访问主 flash）会对整个系统造成显著的影响。请参阅 :doc:`spi_flash_concurrency`，查看详细信息。
 
-.. _flash-partition-apis:
-
-分区表 API
--------------------
-
-ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导程序、各种应用程序二进制文件、数据及文件系统等。请参阅 :doc:`分区表 </api-guides/partition-tables>`，查看详细信息。
-
-该组件在 ``esp_partition.h`` 中声明了一些 API 函数，用以枚举在分区表中找到的分区，并对这些分区执行操作：
-
-- :cpp:func:`esp_partition_find`：在分区表中查找特定类型的条目，返回一个不透明迭代器；
-- :cpp:func:`esp_partition_get`：返回一个结构体，描述给定迭代器的分区；
-- :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:`esp_flash_read`、:cpp:func:`esp_flash_write` 和 :cpp:func:`esp_flash_erase_region`，但在分区边界内执行。
-
-.. note::
-    请在应用程序代码中使用上述 ``esp_partition_*`` API 函数，而非低层级的 ``esp_flash_*`` API 函数。分区表 API 函数根据存储在分区表中的数据，进行边界检查并计算在 flash 中的正确偏移量。
-
-
 SPI Flash 加密
 --------------------
 
@@ -240,14 +225,6 @@ OS 函数层目前支持访问锁和延迟的方法。
 
 3. 在开发过程中，请根据项目对擦除 flash 的具体要求和时间限制，谨慎进行 flash 操作。在配置 flash 擦除超时周期时，请在实际产品要求的基础上留出合理的冗余时间，从而提高产品的可靠性。
 
-另请参考
-------------
-
-- :doc:`分区表 <../../api-guides/partition-tables>`
-- :doc:`OTA API <../system/ota>` 提供了高层 API 用于更新存储在 flash 中的 app 固件。
-- :doc:`NVS API <nvs_flash>` 提供了结构化 API 用于存储 SPI flash 中的碎片数据。
-
-
 .. _spi-flash-implementation-details:
 
 实现细节
@@ -278,11 +255,6 @@ SPI Flash API 参考
 
 .. _api-reference-partition-table:
 
-分区表 API 参考
--------------------------------
-
-.. include-build-file:: inc/esp_partition.inc
-
 Flash 加密 API 参考
 -----------------------------
 

docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst

@@ -0,0 +1 @@
+.. include:: /../en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst

docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst

@@ -0,0 +1 @@
+.. include:: /../en/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst

docs/zh_CN/api-reference/storage/index.rst

@@ -3,6 +3,19 @@
 
 :link_to_translation:`en:[English]`
 
+本节提供高层次的存储 API 的参考文档。这些 API 基于如 SPI Flash、SD/MMC 等低层次驱动。
+
+- :doc:`分区表 API <partition>` 基于 :doc:`分区表 </api-guides/partition-tables>` ，允许以块为单位访问 SPI Flash 。
+- :doc:`非易失性存储库 (NVS) <nvs_flash>` 在 SPI NOR Flash 上实现了一个有容错性，和磨损均衡功能的键值对存储。
+- :doc:`虚拟文件系统 (VFS) <vfs>` 库提供了一个用于注册文件系统驱动的接口。 SPIFFS 、 FAT 以及多种其他的文件系统库都基于 VFS 。
+- :doc:`SPIFFS <spiffs>` 是一个专为 SPI NOR Flash 优化的磨损均衡的文件系统，非常适用于小分区和低吞吐率的应用。
+- :doc:`FAT <fatfs>` 是一个可用于 SPI Flash 或者 SD/MMC 存储卡的标准文件系统。
+- :doc:`磨损均衡 <wear-levelling>` 库实现了一个适用于 SPI NOR Flash 的 Flash 翻译层 (FTL) 。它被用于 Flash 中的 FAT 分区的容器。
+
+.. note::
+    建议使用高层次的 API （ ``esp_partition`` 或者文件系统）而非低层次驱动 API 去访问 SPI NOR Flash 。
+
+    由于 NOR Flash 和乐鑫硬件的一些限制，访问主 Flash 会影响各个系统的性能。关于这些限制的更多信息，参见 :doc:`SPI Flash Documents </api-reference/peripherals/spi_flash/index>` 。
 .. toctree::
    :maxdepth: 1
 
@@ -12,7 +25,7 @@
    nvs_partition_gen.rst
    nvs_partition_parse.rst
    sdmmc
-   spi_flash
+   partition
    spiffs
    vfs
    wear-levelling

docs/zh_CN/api-reference/storage/partition.rst

@@ -0,0 +1,36 @@
+分区 API
+========
+
+概述
+--------
+``esp_partition`` 组件提供了高层次的 API 函数，用于访问定义在 :doc:`分区表 </api-guides/partition-tables>` 中的分区。这些 API 基于 :doc:`SPI Flash 驱动 </api-reference/peripherals/spi_flash/index>` 提供的低层次 API。
+
+
+
+.. _flash-partition-apis:
+
+分区表 API
+-------------------
+
+ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导程序、各种应用程序二进制文件、数据及文件系统等。请参阅 :doc:`分区表 </api-guides/partition-tables>`，查看详细信息。
+
+该组件在 ``esp_partition.h`` 中声明了一些 API 函数，用以枚举在分区表中找到的分区，并对这些分区执行操作：
+
+- :cpp:func:`esp_partition_find`：在分区表中查找特定类型的条目，返回一个不透明迭代器；
+- :cpp:func:`esp_partition_get`：返回一个结构体，描述给定迭代器的分区；
+- :cpp:func:`esp_partition_next`：将迭代器移至下一个找到的分区；
+- :cpp:func:`esp_partition_iterator_release`：释放 :cpp:func:`esp_partition_find` 中返回的迭代器；
+- :cpp:func:`esp_partition_find_first`：返回描述 :cpp:func:`esp_partition_find` 中找到的第一个分区的结构；
+- :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`，但在分区边界内执行。
+
+另请参考
+------------
+
+- :doc:`分区表 <../../api-guides/partition-tables>`
+- :doc:`OTA API <../system/ota>` 提供了高层 API 用于更新存储在 flash 中的 app 固件。
+- :doc:`NVS API <nvs_flash>` 提供了结构化 API 用于存储 SPI flash 中的碎片数据。
+
+分区表 API 参考
+-------------------------------
+
+.. include-build-file:: inc/esp_partition.inc

docs/zh_CN/api-reference/storage/spi_flash_optional_feature.rst

@@ -1 +0,0 @@
-.. include:: ../../../en/api-reference/storage/spi_flash_optional_feature.rst

docs/zh_CN/api-reference/storage/spi_flash_override_driver.rst

@@ -1 +0,0 @@
-.. include:: ../../../en/api-reference/storage/spi_flash_override_driver.rst

docs/zh_CN/api-reference/system/ota.rst

@@ -295,7 +295,8 @@ Python API
 --------
 
 * :doc:`分区表 <../../api-guides/partition-tables>`
-* :doc:`SPI Flash 和分区 API <../storage/spi_flash>`
+* :doc:`分区表 API <../storage/partition>`
+* :doc:`低层 SPI Flash API <../peripherals/spi_flash/index>`
 * :doc:`ESP HTTPS OTA <esp_https_ota>`
 
 应用程序示例