docs: update storage and sleep docs for C2

2024-10-05 20:47:46 -04:00 · 2022-08-09 10:11:11 +08:00 · 2022-08-09 10:11:11 +08:00 · 26dc5fe188
commit 26dc5fe188
parent 50819ca05a
10 changed files with 30 additions and 42 deletions
--- a/docs/docs_not_updated/esp32c2.txt
+++ b/docs/docs_not_updated/esp32c2.txt
@ -4,22 +4,7 @@ api-guides/esp-ble-mesh/ble-mesh-feature-list
 api-guides/esp-ble-mesh/ble-mesh-terminology
 api-guides/esp-ble-mesh/ble-mesh-architecture
 api-guides/esp-ble-mesh/ble-mesh-faq
-api-reference/storage/vfs
-api-reference/storage/spiffs
-api-reference/storage/wear-levelling
-api-reference/storage/fatfs
-api-reference/storage/nvs_partition_gen
-api-reference/storage/spi_flash_concurrency
-api-reference/storage/spi_flash
-api-reference/storage/spi_flash_override_driver
-api-reference/storage/nvs_flash
-api-reference/storage/sdmmc
-api-reference/storage/mass_mfg
-api-reference/storage/index
-api-reference/system/sleep_modes
-api-reference/system/power_management
 api-reference/system/wdts
-api-reference/system/inc/power_management_esp32s2_and_later
 api-reference/bluetooth/esp_spp
 api-reference/bluetooth/esp_avrc
 api-reference/bluetooth/controller_vhci
--- a/docs/en/api-reference/storage/nvs_flash.rst
+++ b/docs/en/api-reference/storage/nvs_flash.rst
@ -89,7 +89,7 @@ For using NVS encryption, the partition table must contain the :ref:`nvs_key_par
 NVS Key Partition
 ^^^^^^^^^^^^^^^^^

-    An application requiring NVS encryption support needs to be compiled with a key-partition of the type `data` and subtype `key`. This partition should be marked as `encrypted` and its size should be the minimum partition size (4KB). Refer to :doc:`Partition Tables <../../api-guides/partition-tables>` for more details. Two additional partition tables which contain the :ref:`nvs_key_partition` are provided under the partition table option (menuconfig->Partition Table). They can be directly used for :ref:`nvs_encryption`. The structure of these partitions is depicted below.
+An application requiring NVS encryption support needs to be compiled with a key-partition of the type `data` and subtype `key`. This partition should be marked as `encrypted` and its size should be the minimum partition size (4KB). Refer to :doc:`Partition Tables <../../api-guides/partition-tables>` for more details. Two additional partition tables which contain the :ref:`nvs_key_partition` are provided under the partition table option (menuconfig->Partition Table). They can be directly used for :ref:`nvs_encryption`. The structure of these partitions is depicted below.

 .. highlight:: none

--- a/docs/en/api-reference/storage/spi_flash.rst
+++ b/docs/en/api-reference/storage/spi_flash.rst
@ -153,7 +153,7 @@ Refer to the :doc:`Flash Encryption documentation </security/flash-encryption>`
 Memory Mapping API
 ------------------

-{IDF_TARGET_CACHE_SIZE:default="64 KB"}
+{IDF_TARGET_CACHE_SIZE:default="64 KB",esp32c2=16~64 KB}

 {IDF_TARGET_NAME} 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.

--- a/docs/en/api-reference/storage/spiffs.rst
+++ b/docs/en/api-reference/storage/spiffs.rst
@ -17,7 +17,7 @@ Notes
 - SPIFFS is able to reliably utilize only around 75% of assigned partition space.
 - When the filesystem is running out of space, the garbage collector is trying to find free space by scanning the filesystem multiple times, which can take up to several seconds per write function call, depending on required space. This is caused by the SPIFFS design and the issue has been reported multiple times (e.g. `here <https://github.com/espressif/esp-idf/issues/1737>`_) and in the official `SPIFFS github repository <https://github.com/pellepl/spiffs/issues/>`_. The issue can be partially mitigated by the `SPIFFS configuration <https://github.com/pellepl/spiffs/wiki/Configure-spiffs>`_.
 - Deleting a file does not always remove the whole file, which leaves unusable sections throughout the filesystem.
- - When ESP32 experiences a power loss during a file system operation it could result in SPIFFS corruption. However the file system still might be recovered via ``esp_spiffs_check`` function. More details in the official SPIFFS `FAQ <https://github.com/pellepl/spiffs/wiki/FAQ>`.
+ - When the chip experiences a power loss during a file system operation it could result in SPIFFS corruption. However the file system still might be recovered via ``esp_spiffs_check`` function. More details in the official SPIFFS `FAQ <https://github.com/pellepl/spiffs/wiki/FAQ>`.

 Tools
 -----
--- a/docs/en/api-reference/system/inc/power_management_esp32.rst
+++ b/docs/en/api-reference/system/inc/power_management_esp32.rst
@ -1,5 +1,5 @@
 +---------------+---------------------------------------+-------------------------------------+
-| Max CPU       |            Lock Acquisition           | CPU and APB Frequncies              |
+| Max CPU       |            Lock Acquisition           | CPU and APB Frequencies             |
 | Frequency Set |                                       |                                     |
 +---------------+---------------------------------------+-------------------------------------+
 |      240      | | Any of ``ESP_PM_CPU_FREQ_MAX``      |                                     |
--- a/docs/en/api-reference/system/inc/power_management_esp32s2_and_later.rst
+++ b/docs/en/api-reference/system/inc/power_management_esp32s2_and_later.rst
@ -1,27 +1,29 @@
+{IDF_TARGET_APB_FREQ: default="80 Mhz", esp32c2="40 MHz"}
+
 +---------------+---------------------------------------+-------------------------------------+
-| Max CPU       |            Lock Acquisition           | CPU and APB Frequncies              |
+| Max CPU       |            Lock Acquisition           | CPU and APB Frequencies             |
 | Frequency Set |                                       |                                     |
 +---------------+---------------------------------------+-------------------------------------+
 |      240      | ``ESP_PM_CPU_FREQ_MAX`` acquired      | | CPU: 240 MHz                      |
-|               |                                       | | APB: 80 MHz                       |
+|               |                                       | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               | ``ESP_PM_APB_FREQ_MAX`` acquired,     | | CPU: 80 MHz                       |
-|               | ``ESP_PM_CPU_FREQ_MAX`` not acquired  | | APB: 80 MHz                       |
+|               | ``ESP_PM_CPU_FREQ_MAX`` not acquired  | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               |                  None                 | Min values for both frequencies set |
 |               |                                       | with :cpp:func:`esp_pm_configure`   |
 +---------------+---------------------------------------+-------------------------------------+
 |      160      | ``ESP_PM_CPU_FREQ_MAX`` acquired      | | CPU: 160 MHz                      |
-|               |                                       | | APB: 80 MHz                       |
+|               |                                       | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               | ``ESP_PM_APB_FREQ_MAX`` acquired,     | | CPU: 80 MHz                       |
-|               | ``ESP_PM_CPU_FREQ_MAX`` not acquired  | | APB: 80 MHz                       |
+|               | ``ESP_PM_CPU_FREQ_MAX`` not acquired  | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               |                  None                 | Min values for both frequencies set |
 |               |                                       | with :cpp:func:`esp_pm_configure`   |
 +---------------+---------------------------------------+-------------------------------------+
 |       80      | | Any of ``ESP_PM_CPU_FREQ_MAX``      | | CPU: 80 MHz                       |
-|               | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | APB: 80 MHz                       |
+|               | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               |                  None                 | Min values for both frequencies set |
 |               |                                       | with :cpp:func:`esp_pm_configure`   |
--- a/docs/en/api-reference/system/sleep_modes.rst
+++ b/docs/en/api-reference/system/sleep_modes.rst
@ -16,9 +16,8 @@ In Deep-sleep mode, the CPUs, most of the RAM, and all digital peripherals that
    .. list::

        - RTC controller
-        - RTC peripherals
        :SOC_ULP_SUPPORTED: - ULP coprocessor
-        - RTC fast memory
+        :SOC_RTC_FAST_MEM_SUPPORTED: - RTC fast memory
        :SOC_RTC_SLOW_MEM_SUPPORTED: - RTC slow memory

 There are several wakeup sources in Deep-sleep and Light-sleep modes. These sources can also be combined so that the chip will wake up when any of the sources are triggered. Wakeup sources can be enabled using ``esp_sleep_enable_X_wakeup`` APIs and can be disabled using :cpp:func:`esp_sleep_disable_wakeup_source` API. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering Light-sleep or Deep-sleep mode.
@ -164,7 +163,7 @@ By default, :cpp:func:`esp_deep_sleep_start` and :cpp:func:`esp_light_sleep_star

    If some variables in the program are placed into RTC slow memory (for example, using ``RTC_DATA_ATTR`` attribute), RTC slow memory will be kept powered on by default. This can be overridden using :cpp:func:`esp_sleep_pd_config` function, if desired.

-.. only:: not SOC_RTC_SLOW_MEM_SUPPORTED
+.. only:: not SOC_RTC_SLOW_MEM_SUPPORTED and SOC_RTC_FAST_MEM_SUPPORTED

    In {IDF_TARGET_NAME}, there is only RTC fast memory, so if some variables in the program are marked by ``RTC_DATA_ATTR``, ``RTC_SLOW_ATTR`` or ``RTC_FAST_ATTR`` attributes, all of them go to RTC fast memory. It will be kept powered on by default. This can be overridden using :cpp:func:`esp_sleep_pd_config` function, if desired.

@ -213,7 +212,7 @@ Configuring IOs

 Some {IDF_TARGET_NAME} IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in Deep-sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns.

-.. only:: not esp32c3
+.. only:: SOC_RTCIO_HOLD_SUPPORTED

    To isolate a pin to prevent extra current draw, call :cpp:func:`rtc_gpio_isolate` function.

@ -223,7 +222,7 @@ Some {IDF_TARGET_NAME} IOs have internal pullups or pulldowns, which are enabled

 	rtc_gpio_isolate(GPIO_NUM_12);

-.. only:: esp32c3
+.. only:: esp32c2 or esp32c3

    In Deep-sleep mode:
        - digital GPIOs (GPIO6 ~ 21) are in a high impedance state.
@ -267,7 +266,7 @@ Application Example

    - :example:`system/deep_sleep`: the usage of various Deep-sleep wakeup triggers and ULP coprocessor programming.

-.. only:: esp32c3
+.. only:: esp32c3 or esp32c2

    - :example:`system/deep_sleep`: the usage of Deep-sleep wakeup triggered by timer.

--- a/docs/zh_CN/api-reference/storage/spiffs.rst
+++ b/docs/zh_CN/api-reference/storage/spiffs.rst
@ -17,7 +17,7 @@ SPIFFS 是一个用于 SPI NOR flash 设备的嵌入式文件系统，支持磨
 - SPIFFS 只能稳定地使用约 75% 的指定分区容量。
 - 当文件系统空间不足时，垃圾收集器会尝试多次扫描文件系统来寻找可用空间。根据所需空间的不同，写操作会被调用多次，每次函数调用将花费几秒。同一操作可能会花费不同时长的问题缘于 SPIFFS 的设计，且已在官方的 `SPIFFS github 仓库 <https://github.com/pellepl/spiffs/issues/>`_ 或是 <https://github.com/espressif/esp-idf/issues/1737>`_ 中被多次报告。这个问题可以通过 `SPIFFS 配置 <https://github.com/pellepl/spiffs/wiki/Configure-spiffs>`_ 部分缓解。
 - 被删除文件通常不会被完全清除，会在文件系统中遗留下无法使用的部分。
- - 如果 ESP32 在文件系统操作期间断电，可能会导致 SPIFFS 损坏。但是仍可通过 ``esp_spiffs_check`` 函数恢复文件系统。详情请参阅官方 SPIFFS `FAQ <https://github.com/pellepl/spiffs/wiki/FAQ>`。
+ - 如果 {IDF_TARGET_NAME} 在文件系统操作期间断电，可能会导致 SPIFFS 损坏。但是仍可通过 ``esp_spiffs_check`` 函数恢复文件系统。详情请参阅官方 SPIFFS `FAQ <https://github.com/pellepl/spiffs/wiki/FAQ>`。

 工具
 -----
--- a/docs/zh_CN/api-reference/system/inc/power_management_esp32s2_and_later.rst
+++ b/docs/zh_CN/api-reference/system/inc/power_management_esp32s2_and_later.rst
@ -1,27 +1,30 @@
+{IDF_TARGET_APB_FREQ: default="80 Mhz", esp32c2="40 MHz"}
+
+
 +---------------+---------------------------------------+-------------------------------------+
 | CPU 最高频率  |            电源管理锁获取情况         | APB 频率和 CPU 频率                 |
 |               |                                       |                                     |
 +---------------+---------------------------------------+-------------------------------------+
 |      240      | 获取 ``ESP_PM_CPU_FREQ_MAX``          | | CPU: 240 MHz                      |
-|               |                                       | | APB: 80 MHz                       |
+|               |                                       | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               | | 获取 ``ESP_PM_APB_FREQ_MAX``,       | | CPU: 80 MHz                       |
-|               | | 未获得 ``ESP_PM_CPU_FREQ_MAX``      | | APB: 80 MHz                       |
+|               | | 未获得 ``ESP_PM_CPU_FREQ_MAX``      | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               |                  无                   | 使用 :cpp:func:`esp_pm_configure`   |
 |               |                                       | 为二者设置最小值                    |
 +---------------+---------------------------------------+-------------------------------------+
 |      160      | 获取 ``ESP_PM_CPU_FREQ_MAX``          | | CPU: 160 MHz                      |
-|               |                                       | | APB: 80 MHz                       |
+|               |                                       | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               | | 获取 ``ESP_PM_APB_FREQ_MAX``,       | | CPU: 80 MHz                       |
-|               | | 未获得 ``ESP_PM_CPU_FREQ_MAX``      | | APB: 80 MHz                       |
+|               | | 未获得 ``ESP_PM_CPU_FREQ_MAX``      | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               |                  无                   | 使用 :cpp:func:`esp_pm_configure`   |
 |               |                                       | 为二者设置最小值                    |
 +---------------+---------------------------------------+-------------------------------------+
 |       80      | | 获取  ``ESP_PM_CPU_FREQ_MAX``       | | CPU: 80 MHz                       |
-|               | | 或 ``ESP_PM_APB_FREQ_MAX``          | | APB: 80 MHz                       |
+|               | | 或 ``ESP_PM_APB_FREQ_MAX``          | | APB: {IDF_TARGET_APB_FREQ}                       |
 +               +---------------------------------------+-------------------------------------+
 |               |                  无                   | 使用 :cpp:func:`esp_pm_configure`   |
 |               |                                       | 为二者设置最小值                    |
--- a/docs/zh_CN/api-reference/system/sleep_modes.rst
+++ b/docs/zh_CN/api-reference/system/sleep_modes.rst
@ -16,9 +16,8 @@
    .. list::

        - RTC 控制器
-        - RTC 外设
        :SOC_ULP_SUPPORTED: - ULP 协处理器
-        - RTC 高速内存
+        :SOC_RTC_FAST_MEM_SUPPORTED: - RTC 高速内存
        :SOC_RTC_SLOW_MEM_SUPPORTED: - RTC 低速内存

 Light-sleep 和 Deep-sleep 模式有多种唤醒源。这些唤醒源也可以组合在一起，此时任何一个唤醒源都可以触发唤醒。通过 API ``esp_sleep_enable_X_wakeup`` 可启用唤醒源，通过 API :cpp:func:`esp_sleep_disable_wakeup_source` 可禁用唤醒源，详见下一小节。在系统进入 Light-sleep 或 Deep-sleep 模式前，可以在任意时刻配置唤醒源。
@ -164,7 +163,7 @@ RTC 外设和内存断电

    如果程序中的某些值被放入 RTC 低速内存中（例如使用 ``RTC_DATA_ATTR`` 属性），RTC 低速内存将默认保持供电。如果有需要，也可以使用函数 :cpp:func:`esp_sleep_pd_config` 对其进行修改。

-.. only:: not SOC_RTC_SLOW_MEM_SUPPORTED
+.. only:: not SOC_RTC_SLOW_MEM_SUPPORTED and SOC_RTC_FAST_MEM_SUPPORTED

    {IDF_TARGET_NAME} 中只有 RTC 高速内存，因此，如果程序中的某些值被标记为 ``RTC_DATA_ATTR``、``RTC_SLOW_ATTR`` 或 ``RTC_FAST_ATTR`` 属性，那么所有这些值都将被存入 RTC 高速内存，默认情况下保持供电。如果有需要，您也可以使用函数 :cpp:func:`esp_sleep_pd_config` 对其进行修改。

@ -213,7 +212,7 @@ Flash 断电

 一些 {IDF_TARGET_NAME} IO 在默认情况下启用内部上拉或下拉电阻。如果这些管脚在 Deep-sleep 模式下中受外部电路驱动，电流流经这些上下拉电阻时，可能会增加电流消耗。

-.. only:: not esp32c3
+.. only:: SOC_RTCIO_HOLD_SUPPORTED

    想要隔离这些管脚以避免额外的电流消耗，请调用 :cpp:func:`rtc_gpio_isolate` 函数。

@ -223,7 +222,7 @@ Flash 断电

 	rtc_gpio_isolate(GPIO_NUM_12);

-.. only:: esp32c3
+.. only:: esp32c2 or esp32c3

    在 Deep-sleep 模式中：
        - 数字 GPIO (GPIO6 ~ 21) 处于高阻态。