diff --git a/docs/en/api-reference/storage/nvs_flash.rst b/docs/en/api-reference/storage/nvs_flash.rst index b5798ec922..7a7f8c71e8 100644 --- a/docs/en/api-reference/storage/nvs_flash.rst +++ b/docs/en/api-reference/storage/nvs_flash.rst @@ -111,7 +111,7 @@ The XTS encryption keys in the :ref:`nvs_key_partition` can be generated in one The API functions :cpp:func:`nvs_flash_secure_init` and :cpp:func:`nvs_flash_secure_init_partition` do not generate the keys internally. When these API functions are used for initializing encrypted NVS partitions, the keys can be generated after startup using the :cpp:func:`nvs_flash_generate_keys` API function provided by ``nvs_flash.h``. The API function will then write those keys onto the key-partition in encrypted form. - .. note:: Please note that `nvs_keys` partition must be completely erased before starting the application in this approach. Otherwise the application may generate :c:macro:`ESP_ERR_NVS_CORRUPT_KEY_PART` error code assuming that `nvs_keys` partition was not empty and contains malformatted data. You can use the following command for this: + .. note:: Please note that `nvs_keys` partition must be completely erased before you start the application in this approach. Otherwise the application may generate :c:macro:`ESP_ERR_NVS_CORRUPT_KEY_PART` error code assuming that `nvs_keys` partition is not empty and contains malformatted data. You can use the following command for this: :: parttool.py --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET erase_partition --partition-type=data --partition-subtype=nvs_keys diff --git a/docs/en/api-reference/storage/spi_flash_concurrency.rst b/docs/en/api-reference/storage/spi_flash_concurrency.rst index deb26a0e82..adb95766ad 100644 --- a/docs/en/api-reference/storage/spi_flash_concurrency.rst +++ b/docs/en/api-reference/storage/spi_flash_concurrency.rst @@ -1,29 +1,29 @@ .. _concurrency-constraints-flash: -Concurrency Constraints for flash on SPI1 +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, operations to SPI1 will cause significant influence to the whole system. This kind of operations include calling SPI Flash API or other drivers on SPI1 bus, any operations like read/write/erase or other user defined SPI operations, regardless to the main flash or other SPI slave devices. .. only:: not (esp32c3 or SOC_SPIRAM_XIP_SUPPORTED) - On {IDF_TARGET_NAME}, these caches must be disabled while reading/writing/erasing. + On {IDF_TARGET_NAME}, these caches must be disabled while reading/writing/erasing. .. only:: esp32c3 On {IDF_TARGET_NAME}, the config option :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` (enabled by default) allows the cache to read flash concurrently with SPI1 operations. See :ref:`auto-suspend` for more details. - If this option is disabled, the caches must be disabled while reading/writing/erasing operations. There are some constraints using driver on the SPI1 bus, see :ref:`impact_disabled_cache`. This constraints will cause more IRAM/DRAM usages. + If this option is disabled, the caches must be disabled while reading/writing/erasing operations. There are some constraints using driver on the SPI1 bus, see :ref:`impact_disabled_cache`. These constraints will cause more IRAM/DRAM usages. .. only:: SOC_SPIRAM_XIP_SUPPORTED - On {IDF_TARGET_NAME}, the config option :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` (disabled by default) and :ref:`CONFIG_SPIRAM_RODATA` (disabled by default) allow the cache to read/write PSRAM concurrently with SPI1 operations. See :ref:`xip_from_psram` for more details. + On {IDF_TARGET_NAME}, the config options :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` (disabled by default) and :ref:`CONFIG_SPIRAM_RODATA` (disabled by default) allow the cache to read/write PSRAM concurrently with SPI1 operations. See :ref:`xip_from_psram` for more details. - If this option is disabled, the caches must be disabled while reading/writing/erasing operations. There are some constraints using driver on the SPI1 bus, see :ref:`impact_disabled_cache`. This constraints will cause more IRAM/DRAM usages. + If these options are disabled, the caches must be disabled while reading/writing/erasing operations. There are some constraints using driver on the SPI1 bus, see :ref:`impact_disabled_cache`. These constraints will cause more IRAM/DRAM usages. .. _impact_disabled_cache: -When the caches are disabled +When the Caches Are Disabled ---------------------------- Under this condition, all CPUs should always execute code and access data from internal RAM. The APIs documented in this file will disable the caches automatically and transparently. diff --git a/docs/zh_CN/api-reference/storage/nvs_flash.rst b/docs/zh_CN/api-reference/storage/nvs_flash.rst index 25f19a1c2b..8b72e839b1 100644 --- a/docs/zh_CN/api-reference/storage/nvs_flash.rst +++ b/docs/zh_CN/api-reference/storage/nvs_flash.rst @@ -111,6 +111,11 @@ NVS 密钥分区 API 函数 :cpp:func:`nvs_flash_secure_init` 和 :cpp:func:`nvs_flash_secure_init_partition` 不在内部产生密钥。当这些 API 函数用于初始化加密的 NVS 分区时，可以在启动后使用 `nvs_flash.h` 提供的 :cpp:func:`nvs_flash_generate_keys` API 函数生成密钥，以加密的形式把密钥写到密钥分区上。 + .. note:: 请注意，使用该方法启动应用前，必须先完全擦除 `nvs_keys` 分区，否则该应用可能会认为 `nvs_keys` 分区不为空，并且包含数据格式错误，从而导致 :c:macro:`ESP_ERR_NVS_CORRUPT_KEY_PART` 报错。如果遇到这种情况，可以使用以下命令： + :: + + parttool.py --port PORT --partition-table-file=PARTITION_TABLE_FILE --partition-table-offset PARTITION_TABLE_OFFSET erase_partition --partition-type=data --partition-subtype=nvs_keys + 2. 使用预先生成的密钥分区： 若 :ref:`nvs_key_partition` 中的密钥不是由应用程序生成，则需要使用预先生成的密钥分区。可以使用 :doc:`NVS 分区生成工具 ` 生成包含 XTS 加密密钥的 :ref:`nvs_key_partition`。用户可以借助以下两个命令，将预先生成的密钥分区储存在 flash 上： diff --git a/docs/zh_CN/api-reference/storage/spi_flash_concurrency.rst b/docs/zh_CN/api-reference/storage/spi_flash_concurrency.rst index 086ee3a39c..160cf9f49a 100644 --- a/docs/zh_CN/api-reference/storage/spi_flash_concurrency.rst +++ b/docs/zh_CN/api-reference/storage/spi_flash_concurrency.rst @@ -1,20 +1,25 @@ .. _concurrency-constraints-flash: -SPI1 Flash 并发约束 +SPI1 flash 并发约束 ========================================= -指令/数据 cache （用以执行固件）与 SPI1 外设（由像 SPI Flash 驱动一样的驱动程序控制）共享 SPI0/1 总线。因此，对 SPI1 外设的操作会对整个系统造成显著的影响。这类操作包括调用 SPI Flash API 或者其他 SPI1 总线上的驱动，任何 flash 操作（如读取、写入、擦除）或者其他用户定义的 SPI 操作，无论是对主 flash 或者其他各类的 SPI 从机。 +指令/数据 cache（用以执行固件）与 SPI1 外设（由像 SPI flash 驱动一样的驱动程序控制）共享 SPI0/1 总线。因此，SPI1 外设上的操作会对整个系统造成显著的影响。这类操作包括调用 SPI flash API 或者 SPI1 总线上的其他驱动、任何 flash 操作（如读取、写入、擦除）或是由其他用户定义的 SPI 操作（对主 flash 或是其他 SPI 从机）。 -.. only:: not esp32c3 +.. only:: not (esp32c3 or SOC_SPIRAM_XIP_SUPPORTED) - 在 {IDF_TARGET_NAME} 上，flash 读取/写入/擦除时 cache 必须被禁用。 + 在 {IDF_TARGET_NAME} 上，flash 读取/写入/擦除时，cache 必须被禁用。 .. only:: esp32c3 - 在 {IDF_TARGET_NAME} 上，默认启用的配置选项 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 允许 flash/PSRAM 的 cache 访问和 SPI1 的操作存并发地执行。请参阅 :ref:`auto-suspend`，查看详细信息。 + 在 {IDF_TARGET_NAME} 上，默认启用的配置选项 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 允许 flash/PSRAM 的 cache 访问和 SPI1 的操作并发执行。请参阅 :ref:`auto-suspend`，查看详细信息。 在该选项被禁用的情况下，读取/写入/擦除 flash 时，cache 必须被禁用。使用驱动访问 SPI1 的相关约束参见 :ref:`impact_disabled_cache`。这些约束会带来更多的 IRAM/DRAM 消耗。 +.. only:: SOC_SPIRAM_XIP_SUPPORTED + + 在 {IDF_TARGET_NAME} 上，启用配置选项 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` （默认禁用）和 :ref:`CONFIG_SPIRAM_RODATA` （默认禁用）后将允许 flash/PSRAM 的 cache 访问和 SPI1 的操作并发执行。请参阅 :ref:`xip_from_psram`，查看详细信息。 + + 在上述选项被禁用的情况下，读取/写入/擦除 flash 时，cache 必须被禁用。使用驱动访问 SPI1 的相关约束参见 :ref:`impact_disabled_cache`。这些约束会带来更多的 IRAM/DRAM 消耗。 .. _impact_disabled_cache: @@ -25,7 +30,15 @@ SPI1 Flash 并发约束 .. only:: esp32c3 - 然而，启用 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 时，cache 不会被禁用，其中的操作将通过硬件来协调。 + .. note:: + + 启用 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 时，cache 不会被禁用，其中的操作将通过硬件仲裁器来协调。 + +.. only:: SOC_SPIRAM_XIP_SUPPORTED + + .. note:: + + 同时启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 和 :ref:`CONFIG_SPIRAM_RODATA` 选项后，cache 不会被禁用。 .. only:: not CONFIG_FREERTOS_UNICORE @@ -37,7 +50,7 @@ SPI1 Flash 并发约束 另请参阅 :ref:`esp_flash_os_func` 和 :ref:`spi_bus_lock`。 -除 SPI0/1 以外，SPI 总线上的其它 flash 芯片则不受这种限制。 +除 SPI0/1 以外，SPI 总线上的其他 flash 芯片则不受这种限制。 请参阅 :ref:`应用程序内存分布 `，查看内部 RAM（如 IRAM、DRAM）和 flash cache 的区别。 @@ -66,3 +79,7 @@ IRAM 安全中断处理程序 .. only:: esp32c3 .. include:: auto_suspend.inc + +.. only:: SOC_SPIRAM_XIP_SUPPORTED + + .. include:: xip_from_psram.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/storage/xip_from_psram.inc b/docs/zh_CN/api-reference/storage/xip_from_psram.inc index e69de29bb2..0ab88d805b 100644 --- a/docs/zh_CN/api-reference/storage/xip_from_psram.inc +++ b/docs/zh_CN/api-reference/storage/xip_from_psram.inc @@ -0,0 +1,12 @@ +.. _xip_from_psram: + +在 PSRAM 中执行代码 +---------------------- + +启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 选项后，flash 中 ``.text`` 部分的数据（用于指令）将被放入 PSRAM。 + +启用 :ref:`CONFIG_SPIRAM_RODATA` 选项后，flash 中 ``.rodata`` 部分的数据（用于只读数据）将被放入 PSRAM。 + +相应的虚拟内存地址将被重新映射到 PSRAM。 + +如果同时启用以上两个选项，则在 SPI1 flash 操作期间 cache 不会被禁用，无需确保 ISR、ISR 回调及相关数据放置在内部 RAM 中。