Merge branch 'docs/c2_storage_update' into 'master'

docs: update storage and sleep docs for C2

Closes IDF-4207

See merge request espressif/esp-idf!19453
This commit is contained in:
Marius Vikhammer 2022-08-23 23:56:56 +08:00
commit 8bf4af572b
12 changed files with 37 additions and 49 deletions

View File

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

View File

@ -82,14 +82,14 @@ Data stored in NVS partitions can be encrypted using AES-XTS in the manner simil
The NVS Encryption is enabled by default when :doc:`Flash Encryption <../../security/flash-encryption>` is enabled. This is done because Wi-Fi driver stores credentials (like SSID and passphrase) in the default NVS partition. It is important to encrypt them as default choice if platform level encryption is already enabled.
For using NVS encryption, the partition table must contain the :ref:`nvs_key_partition`. Two partition tables containing the :ref:`nvs_key_partition` are provided for NVS encryption under the partition table option (menuconfig->Partition Table). They can be selected with the project configuration menu (``idf.py menuconfig``). Please refer to the example :example:`security/flash_encryption` for how to configure and use NVS encryption feature.
For using NVS encryption, the partition table must contain the :ref:`nvs_key_partition`. Two partition tables containing the :ref:`nvs_key_partition` are provided for NVS encryption under the partition table option (``menuconfig`` > ``Partition Table``). They can be selected with the project configuration menu (``idf.py menuconfig``). Please refer to the example :example:`security/flash_encryption` for how to configure and use NVS encryption feature.
.. _nvs_key_partition:
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

View File

@ -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.
@ -286,4 +286,5 @@ API Reference - Partition Table
API Reference - Flash Encrypt
-----------------------------
.. include-build-file:: inc/esp_flash_encrypt.inc
.. include-build-file:: inc/esp_flash_encrypt.inc

View File

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

View File

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

View File

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

View File

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

View File

@ -82,14 +82,14 @@ NVS 分区内存储的数据可使用 AES-XTS 进行加密,类似于 IEEE P161
启用 :doc:`Flash 加密 <../../security/flash-encryption>` 时,默认启用 NVS 加密。这是因为 Wi-Fi 驱动在默认的 NVS 分区中存储了凭证(如 SSID 和密码)。如已启用平台级加密,那么同时默认启用 NVS 加密有其必要性。
使用 NVS 加密,分区表必须包含 :ref:`nvs_key_partition`。在分区表选项 (menuconfig->Partition Table) 下,为 NVS 加密提供了两个包含 :ref:`nvs_key_partition` 的分区表,您可以通过工程配置菜单 (``idf.py menuconfig``) 进行选择。请参考 :example:`security/flash_encryption` 中的例子,了解如何配置和使用 NVS 加密功能。
使用 NVS 加密,分区表必须包含 :ref:`nvs_key_partition`。在分区表选项 (``menuconfig`` > ``Partition Table``) 下,为 NVS 加密提供了两个包含 :ref:`nvs_key_partition` 的分区表,您可以通过工程配置菜单 (``idf.py menuconfig``) 进行选择。请参考 :example:`security/flash_encryption` 中的例子,了解如何配置和使用 NVS 加密功能。
.. _nvs_key_partition:
NVS 密钥分区
^^^^^^^^^^^^^^^^^
应用程序如果想使用 NVS 加密,则需要编译进一个类型为 `data`,子类型为 `key` 的密钥分区。该分区应标记为 `已加密` 且最小为 4096 字节。如需了解更多详细信息,请参考 :doc:`分区表 <../../api-guides/partition-tables>`。在分区表选项 (menuconfig->Partition Table) 下提供了两个包含 :ref:`nvs_key_partition` 的额外分区表,可以直接用于 :ref:`nvs_encryption`。这些分区的具体结构见下表:
应用程序如果想使用 NVS 加密,则需要编译进一个类型为 `data`,子类型为 `key` 的密钥分区。该分区应标记为 `已加密` 且最小为 4096 字节。如需了解更多详细信息,请参考 :doc:`分区表 <../../api-guides/partition-tables>`。在分区表选项 (``menuconfig`` > ``Partition Table``) 下提供了两个包含 :ref:`nvs_key_partition` 的额外分区表,可以直接用于 :ref:`nvs_encryption`。这些分区的具体结构见下表:
.. highlight:: none

View File

@ -153,7 +153,7 @@ SPI Flash 加密
内存映射 API
------------------
{IDF_TARGET_CACHE_SIZE:default="64 KB"}
{IDF_TARGET_CACHE_SIZE:default="64 KB",esp32c2=16~64 KB}
{IDF_TARGET_NAME} 的内存硬件可以将 flash 部分区域映射到指令地址空间和数据地址空间。此映射仅用于读操作,不能通过写入 flash 映射的存储区域来改变 flash 中的内容。
@ -286,4 +286,4 @@ SPI Flash API 参考
Flash 加密 API 参考
-----------------------------
.. include-build-file:: inc/esp_flash_encrypt.inc
.. include-build-file:: inc/esp_flash_encrypt.inc

View File

@ -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>`
工具
-----

View File

@ -1,27 +1,29 @@
{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` |
| | | 为二者设置最小值 |

View File

@ -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) 处于高阻态。
@ -267,7 +266,7 @@ UART 输出处理
- :example:`system/deep_sleep`:如何使用 Deep-sleep 唤醒触发器和 ULP 协处理器编程。
.. only:: esp32c3
.. only:: esp32c3 or esp32c2
- :example:`system/deep_sleep`:如何通过定时器触发 Deep-sleep 唤醒。