mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-03 03:31:41 +03:00
docs(kconfig): update kconfig ref links to use menuitem
This commit is contained in:
Marius Vikhammer
@@ -81,23 +81,23 @@ FatFs 组件提供了便利的封装函数，用于通过 VFS 层挂载文件系
|
||||
|
||||
FatFs 组件提供以下配置选项：
|
||||
|
||||
* ``CONFIG_FATFS_LONG_FILENAMES`` - 选择 FatFs 库如何处理长文件名 (LFN) 支持。可用选项包括 :ref:`CONFIG_FATFS_LFN_NONE <CONFIG_FATFS_LFN_NONE>` 以禁用 LFN 支持并将名称限制为 `8.3 格式 <https://en.wikipedia.org/wiki/8.3_filename>`_ （仅 SFN）， :ref:`CONFIG_FATFS_LFN_HEAP <CONFIG_FATFS_LFN_HEAP>` 以启用 LFN 支持并将 LFN 工作缓冲区存储在堆上（默认），以及 :ref:`CONFIG_FATFS_LFN_STACK <CONFIG_FATFS_LFN_STACK>` 以启用 LFN 支持并将 LFN 工作缓冲区存储在栈上。详细信息请参阅 `FatFs 文件名 <http://elm-chan.org/fsw/ff/doc/filename.html>`_。
|
||||
* :ref:`CONFIG_FATFS_VOLUME_COUNT` - 设置逻辑 FatFs 卷的数量。增加此值可能会增加基础内存使用量。
|
||||
* :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` - 如果启用，FatFs 库在分配内部缓冲区时优先使用外部 RAM。如果外部 RAM 分配失败，则回退到内部 RAM。这可能会对热 I/O 路径产生明显的性能开销。禁用此选项可优先考虑性能；启用可减少内部 RAM 使用量。
|
||||
* :ref:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS` - 如果启用，FatFs 库首先尝试在支持 DMA、缓存对齐的内存中分配堆工作缓冲区，以便 SDMMC 传输避免额外的拷贝。此选项在使用 PSRAM 和 SDMMC DMA 的目标芯片上（例如 ESP32-P4）非常有用。如果同时启用此选项和 :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM`，FatFs 库会先尝试支持 DMA 的 RAM，然后是外部 RAM，最后是内部 RAM。
|
||||
* :ref:`CONFIG_FATFS_USE_DYN_BUFFERS` - 如果启用，FatFs 库会单独分配实例缓冲区，并根据每个已挂载卷的逻辑扇区大小调整其大小。当多个 FatFs 实例使用不同的逻辑扇区大小时，此选项非常有用，因为它可以减少内存使用量。如果禁用，所有实例都使用为最大配置逻辑扇区大小调整大小的缓冲区。
|
||||
* :ref:`CONFIG_FATFS_PER_FILE_CACHE` - 如果启用，每个打开的文件使用单独的缓存缓冲区。这提高了 I/O 性能，但当多个文件打开时会增加 RAM 使用量。如果禁用，则使用单个共享缓存，这减少了 RAM 使用量，但可能会增加存储读写操作。
|
||||
* :ref:`CONFIG_FATFS_USE_FASTSEEK` - 如果启用，POSIX :cpp:func:`lseek` 运行更快。快速定位不适用于以写入模式打开的文件。要使用快速查找，请以只读模式打开文件，或关闭后以只读模式重新打开。
|
||||
* :ref:`CONFIG_FATFS_FAST_SEEK_BUFFER_SIZE` - 设置当 :ref:`CONFIG_FATFS_USE_FASTSEEK` 启用时快速查找使用的 CLMT（簇链接映射表）缓冲区大小。较大的缓冲区可以改善较大文件上的查找行为，但会使用更多 RAM。
|
||||
* :ref:`CONFIG_FATFS_VFS_FSTAT_BLKSIZE` - 设置通过 VFS 使用的默认 stdio 文件缓冲区块大小。此选项主要与基于 stdio 的 I/O（例如 ``fread``/``fgets``）相关，不是直接 POSIX ``read``/``write`` 路径的主要调整参数。较大的值可以提高缓冲读取吞吐量，但会增加堆使用量。
|
||||
* :ref:`CONFIG_FATFS_IMMEDIATE_FSYNC` - 如果启用，FatFs 库会在每次调用 :cpp:func:`write`、:cpp:func:`pwrite`、:cpp:func:`link`、:cpp:func:`truncate` 和 :cpp:func:`ftruncate` 后自动调用 :cpp:func:`f_sync`。此选项提高了文件一致性和大小报告的准确性，但由于会触发频繁的磁盘操作而降低了性能。
|
||||
* :ref:`CONFIG_FATFS_LINK_LOCK` - 如果启用，此选项保证 :cpp:func:`link` 函数的 API 线程安全。禁用此选项可以帮助执行频繁小文件操作（例如文件日志记录）的应用程序。禁用时，:cpp:func:`link` 执行的拷贝是非原子的。在这种情况下，从另一个任务在同一卷上对大文件使用 :cpp:func:`link` 不保证线程安全。
|
||||
* 其他相关选项包括 :ref:`CONFIG_FATFS_FS_LOCK`、:ref:`CONFIG_FATFS_TIMEOUT_MS` 和 ``CONFIG_FATFS_CHOOSE_CODEPAGE`` （特别是 ``CONFIG_FATFS_CODEPAGE_DYNAMIC`` 对代码大小的影响）。其他选项包括 ``CONFIG_FATFS_SECTOR_SIZE``、``CONFIG_FATFS_MAX_LFN``、``CONFIG_FATFS_API_ENCODING`` 和 ``CONFIG_FATFS_USE_STRFUNC_CHOICE``。
|
||||
* ``CONFIG_FATFS_LONG_FILENAMES`` - 选择 FatFs 库如何处理长文件名 (LFN) 支持。可用选项包括 :menuitem:`CONFIG_FATFS_LFN_NONE <CONFIG_FATFS_LFN_NONE>` 以禁用 LFN 支持并将名称限制为 `8.3 格式 <https://en.wikipedia.org/wiki/8.3_filename>`_ （仅 SFN）， :menuitem:`CONFIG_FATFS_LFN_HEAP <CONFIG_FATFS_LFN_HEAP>` 以启用 LFN 支持并将 LFN 工作缓冲区存储在堆上（默认），以及 :menuitem:`CONFIG_FATFS_LFN_STACK <CONFIG_FATFS_LFN_STACK>` 以启用 LFN 支持并将 LFN 工作缓冲区存储在栈上。详细信息请参阅 `FatFs 文件名 <http://elm-chan.org/fsw/ff/doc/filename.html>`_。
|
||||
* :menuitem:`CONFIG_FATFS_VOLUME_COUNT` - 设置逻辑 FatFs 卷的数量。增加此值可能会增加基础内存使用量。
|
||||
* :menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` - 如果启用，FatFs 库在分配内部缓冲区时优先使用外部 RAM。如果外部 RAM 分配失败，则回退到内部 RAM。这可能会对热 I/O 路径产生明显的性能开销。禁用此选项可优先考虑性能；启用可减少内部 RAM 使用量。
|
||||
* :menuitem:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS` - 如果启用，FatFs 库首先尝试在支持 DMA、缓存对齐的内存中分配堆工作缓冲区，以便 SDMMC 传输避免额外的拷贝。此选项在使用 PSRAM 和 SDMMC DMA 的目标芯片上（例如 ESP32-P4）非常有用。如果同时启用此选项和 :menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM`，FatFs 库会先尝试支持 DMA 的 RAM，然后是外部 RAM，最后是内部 RAM。
|
||||
* :menuitem:`CONFIG_FATFS_USE_DYN_BUFFERS` - 如果启用，FatFs 库会单独分配实例缓冲区，并根据每个已挂载卷的逻辑扇区大小调整其大小。当多个 FatFs 实例使用不同的逻辑扇区大小时，此选项非常有用，因为它可以减少内存使用量。如果禁用，所有实例都使用为最大配置逻辑扇区大小调整大小的缓冲区。
|
||||
* :menuitem:`CONFIG_FATFS_PER_FILE_CACHE` - 如果启用，每个打开的文件使用单独的缓存缓冲区。这提高了 I/O 性能，但当多个文件打开时会增加 RAM 使用量。如果禁用，则使用单个共享缓存，这减少了 RAM 使用量，但可能会增加存储读写操作。
|
||||
* :menuitem:`CONFIG_FATFS_USE_FASTSEEK` - 如果启用，POSIX :cpp:func:`lseek` 运行更快。快速定位不适用于以写入模式打开的文件。要使用快速查找，请以只读模式打开文件，或关闭后以只读模式重新打开。
|
||||
* :menuitem:`CONFIG_FATFS_FAST_SEEK_BUFFER_SIZE` - 设置当 :menuitem:`CONFIG_FATFS_USE_FASTSEEK` 启用时快速查找使用的 CLMT（簇链接映射表）缓冲区大小。较大的缓冲区可以改善较大文件上的查找行为，但会使用更多 RAM。
|
||||
* :menuitem:`CONFIG_FATFS_VFS_FSTAT_BLKSIZE` - 设置通过 VFS 使用的默认 stdio 文件缓冲区块大小。此选项主要与基于 stdio 的 I/O（例如 ``fread``/``fgets``）相关，不是直接 POSIX ``read``/``write`` 路径的主要调整参数。较大的值可以提高缓冲读取吞吐量，但会增加堆使用量。
|
||||
* :menuitem:`CONFIG_FATFS_IMMEDIATE_FSYNC` - 如果启用，FatFs 库会在每次调用 :cpp:func:`write`、:cpp:func:`pwrite`、:cpp:func:`link`、:cpp:func:`truncate` 和 :cpp:func:`ftruncate` 后自动调用 :cpp:func:`f_sync`。此选项提高了文件一致性和大小报告的准确性，但由于会触发频繁的磁盘操作而降低了性能。
|
||||
* :menuitem:`CONFIG_FATFS_LINK_LOCK` - 如果启用，此选项保证 :cpp:func:`link` 函数的 API 线程安全。禁用此选项可以帮助执行频繁小文件操作（例如文件日志记录）的应用程序。禁用时，:cpp:func:`link` 执行的拷贝是非原子的。在这种情况下，从另一个任务在同一卷上对大文件使用 :cpp:func:`link` 不保证线程安全。
|
||||
* 其他相关选项包括 :menuitem:`CONFIG_FATFS_FS_LOCK`、:menuitem:`CONFIG_FATFS_TIMEOUT_MS` 和 ``CONFIG_FATFS_CHOOSE_CODEPAGE`` （特别是 ``CONFIG_FATFS_CODEPAGE_DYNAMIC`` 对代码大小的影响）。其他选项包括 ``CONFIG_FATFS_SECTOR_SIZE``、``CONFIG_FATFS_MAX_LFN``、``CONFIG_FATFS_API_ENCODING`` 和 ``CONFIG_FATFS_USE_STRFUNC_CHOICE``。
|
||||
|
||||
这些选项控制 FatFs 库如何计算和报告可用空间：
|
||||
|
||||
* :ref:`CONFIG_FATFS_DONT_TRUST_FREE_CLUSTER_CNT` - 如果设置为 1，FatFs 库忽略空闲簇计数。默认值为 0。
|
||||
* :ref:`CONFIG_FATFS_DONT_TRUST_LAST_ALLOC` - 如果设置为 1，FatFs 库忽略上次分配编号。默认值为 0。
|
||||
* :menuitem:`CONFIG_FATFS_DONT_TRUST_FREE_CLUSTER_CNT` - 如果设置为 1，FatFs 库忽略空闲簇计数。默认值为 0。
|
||||
* :menuitem:`CONFIG_FATFS_DONT_TRUST_LAST_ALLOC` - 如果设置为 1，FatFs 库忽略上次分配编号。默认值为 0。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -324,9 +324,9 @@ exFAT 使用不同的元数据布局。除了 FAT 区域外，它还需要一个
|
||||
|
||||
影响行为的主要变量是：
|
||||
|
||||
* 缓冲区位置和大小（:ref:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS`、:ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM`、:ref:`CONFIG_FATFS_USE_DYN_BUFFERS`、:ref:`CONFIG_FATFS_PER_FILE_CACHE` 和应用程序 I/O 缓冲区大小）。
|
||||
* 缓冲区位置和大小（:menuitem:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS`、:menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM`、:menuitem:`CONFIG_FATFS_USE_DYN_BUFFERS`、:menuitem:`CONFIG_FATFS_PER_FILE_CACHE` 和应用程序 I/O 缓冲区大小）。
|
||||
* 磨损均衡逻辑扇区大小和模式（``CONFIG_WL_SECTOR_SIZE_*`` 和 ``CONFIG_WL_SECTOR_MODE_*``）。
|
||||
* 同步策略（:ref:`CONFIG_FATFS_IMMEDIATE_FSYNC`）。
|
||||
* 同步策略（:menuitem:`CONFIG_FATFS_IMMEDIATE_FSYNC`）。
|
||||
* 工作负载模式（事务大小、顺序访问与随机访问、读取与写入比率）。
|
||||
|
||||
优化 I/O 性能
|
||||
@@ -334,15 +334,15 @@ exFAT 使用不同的元数据布局。除了 FAT 区域外，它还需要一个
|
||||
|
||||
对于面向吞吐量的工作负载：
|
||||
|
||||
* 除非一致性要求需要，否则保持禁用 :ref:`CONFIG_FATFS_IMMEDIATE_FSYNC`。
|
||||
* 如果峰值速度是最高优先级，请禁用 :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM`，以便缓冲区保留在内部 RAM 中。
|
||||
* 除非一致性要求需要，否则保持禁用 :menuitem:`CONFIG_FATFS_IMMEDIATE_FSYNC`。
|
||||
* 如果峰值速度是最高优先级，请禁用 :menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM`，以便缓冲区保留在内部 RAM 中。
|
||||
* 优先选择较大的读写事务大小，而不是许多小操作。
|
||||
* 尽可能将事务大小与活动扇区大小（例如 512 B 或 4096 B）对齐，并在需要时填充写入以减少部分扇区开销。
|
||||
* 对于带磨损均衡的 SPI flash，当 RAM 预算允许时，优先选择 ``CONFIG_WL_SECTOR_SIZE_4096``，因为它通常更高效。
|
||||
* 如果使用 512 字节的 WL 扇区，当应用程序可以接受 flash 扇区擦除期间更高的断电风险时，请使用 ``CONFIG_WL_SECTOR_MODE_PERF``。
|
||||
* 在热路径上尽可能优先选择 POSIX ``read``/``write`` 而不是 ``fread``/``fwrite``。有关更广泛的速度指导，请参阅 :doc:`最大化执行速度 <../../api-guides/performance/speed>`。
|
||||
* 在 SDMMC DMA 目标（例如带有 PSRAM 的 ESP32-P4）上，启用 :ref:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS` 以减少额外的缓冲区拷贝。
|
||||
* 对于具有长反向查找的读取密集型工作负载，启用 :ref:`CONFIG_FATFS_USE_FASTSEEK`。
|
||||
* 在 SDMMC DMA 目标（例如带有 PSRAM 的 ESP32-P4）上，启用 :menuitem:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS` 以减少额外的缓冲区拷贝。
|
||||
* 对于具有长反向查找的读取密集型工作负载，启用 :menuitem:`CONFIG_FATFS_USE_FASTSEEK`。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -351,14 +351,14 @@ exFAT 使用不同的元数据布局。除了 FAT 区域外，它还需要一个
|
||||
优化内存使用
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* 当减少 RAM 使用是优先事项时，禁用 :ref:`CONFIG_FATFS_PER_FILE_CACHE` 以使用单个共享缓存。
|
||||
* 当减少 RAM 使用是优先事项时，禁用 :menuitem:`CONFIG_FATFS_PER_FILE_CACHE` 以使用单个共享缓存。
|
||||
* 尽可能低地调整 ``esp_vfs_fat_mount_config_t.max_files`` （参见 :ref:`挂载和使用 FatFs <fatfs-mount-and-use>`）；每个同时打开的文件都会增加 RAM 使用量。
|
||||
* 如果启用了 :ref:`CONFIG_FATFS_PER_FILE_CACHE`，优先选择 ``CONFIG_WL_SECTOR_SIZE_512`` 以减少每文件缓存大小。
|
||||
* 如果禁用了 :ref:`CONFIG_FATFS_PER_FILE_CACHE`，``CONFIG_WL_SECTOR_SIZE_4096`` 可能是更好的权衡。
|
||||
* 在支持外部 RAM 的目标上启用 :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` 以减少内部 RAM 压力，但预计 I/O 性能会降低。
|
||||
* 如果启用了 :menuitem:`CONFIG_FATFS_PER_FILE_CACHE`，优先选择 ``CONFIG_WL_SECTOR_SIZE_512`` 以减少每文件缓存大小。
|
||||
* 如果禁用了 :menuitem:`CONFIG_FATFS_PER_FILE_CACHE`，``CONFIG_WL_SECTOR_SIZE_4096`` 可能是更好的权衡。
|
||||
* 在支持外部 RAM 的目标上启用 :menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` 以减少内部 RAM 压力，但预计 I/O 性能会降低。
|
||||
* 当 SFN (8.3) 文件名可接受时，考虑使用 ``CONFIG_FATFS_LONG_FILENAMES = CONFIG_FATFS_LFN_NONE``。
|
||||
* 如果需要长文件名，将 ``CONFIG_FATFS_MAX_LFN`` 减小到满足需求的最小值。
|
||||
* 启用 :ref:`CONFIG_FATFS_USE_DYN_BUFFERS`，以便每个挂载的卷使用根据其实际扇区大小调整大小的缓冲区。
|
||||
* 启用 :menuitem:`CONFIG_FATFS_USE_DYN_BUFFERS`，以便每个挂载的卷使用根据其实际扇区大小调整大小的缓冲区。
|
||||
|
||||
优化存储效率
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -31,7 +31,7 @@
|
||||
|
||||
.. note::
|
||||
|
||||
在使用基于 HMAC 的方案进行上述流程时，可以直接调用 :cpp:func:`nvs_flash_secure_init` API 对默认和自定义 NVS 分区进行加密，而无需启用 NVS 加密相关配置选项（如 :ref:`CONFIG_NVS_ENCRYPTION`， :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC``， :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID`）。
|
||||
在使用基于 HMAC 的方案进行上述流程时，可以直接调用 :cpp:func:`nvs_flash_secure_init` API 对默认和自定义 NVS 分区进行加密，而无需启用 NVS 加密相关配置选项（如 :menuitem:`CONFIG_NVS_ENCRYPTION`， :menuitem:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC``， :menuitem:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID`）。
|
||||
|
||||
|
||||
应用示例
|
||||
|
||||
@@ -12,7 +12,7 @@ NVS 加密
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
根据要使用的具体方案，可以选择启用 :ref:`CONFIG_NVS_ENCRYPTION` 和 :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` > ``CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC`` 或 ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC`` 实现 NVS 加密。
|
||||
根据要使用的具体方案，可以选择启用 :menuitem:`CONFIG_NVS_ENCRYPTION` 和 :menuitem:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` > ``CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC`` 或 ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC`` 实现 NVS 加密。
|
||||
|
||||
.. _nvs_encr_flash_enc_scheme:
|
||||
|
||||
@@ -120,13 +120,13 @@ NVS 密钥分区
|
||||
|
||||
注意，此方案使用一个 eFuse 块来存储获取加密密钥所需的 HMAC 密钥。
|
||||
|
||||
- NVS 加密启用时后，可用 API 函数 :cpp:func:`nvs_flash_init` 来初始化加密的默认 NVS 分区。该 API 函数首先检查 :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` 处是否存在一个 HMAC 密钥。
|
||||
- NVS 加密启用时后，可用 API 函数 :cpp:func:`nvs_flash_init` 来初始化加密的默认 NVS 分区。该 API 函数首先检查 :menuitem:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` 处是否存在一个 HMAC 密钥。
|
||||
|
||||
.. note::
|
||||
|
||||
:ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` 配置的有效范围为 ``0`` (:cpp:enumerator:`hmac_key_id_t::HMAC_KEY0`) 到 ``5`` (:cpp:enumerator:`hmac_key_id_t::HMAC_KEY5`)。默认情况下该配置为 ``-1``，须在构建用户应用程序之前进行修改。
|
||||
:menuitem:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` 配置的有效范围为 ``0`` (:cpp:enumerator:`hmac_key_id_t::HMAC_KEY0`) 到 ``5`` (:cpp:enumerator:`hmac_key_id_t::HMAC_KEY5`)。默认情况下该配置为 ``-1``，须在构建用户应用程序之前进行修改。
|
||||
|
||||
- 如果找不到密钥，会内部生成一个密钥，并储存在 :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` 指定的 eFuse 块中。
|
||||
- 如果找不到密钥，会内部生成一个密钥，并储存在 :menuitem:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` 指定的 eFuse 块中。
|
||||
- 如果找到用于 :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_HMAC_UP` 的密钥，该密钥也会用于 XTS 加密密钥的生成。
|
||||
- 如果指定的 eFuse 块被 :cpp:enumerator:`esp_efuse_purpose_t::ESP_EFUSE_KEY_PURPOSE_HMAC_UP` 以外目的的密钥占用，则会引发错误。
|
||||
|
||||
@@ -146,13 +146,13 @@ NVS API 函数 ``nvs_get_*`` 或 ``nvs_set_*`` 也可用于读取和写入加密
|
||||
|
||||
**加密默认的 NVS 分区**
|
||||
|
||||
- 要为默认 NVS 分区启用加密，无需额外的步骤。在启用 :ref:`CONFIG_NVS_ENCRYPTION` 时，API 函数 :cpp:func:`nvs_flash_init` 会根据使用的方案（由 :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` 设置）在内部执行一些额外步骤，为默认的 NVS 分区启用加密。
|
||||
- 要为默认 NVS 分区启用加密，无需额外的步骤。在启用 :menuitem:`CONFIG_NVS_ENCRYPTION` 时，API 函数 :cpp:func:`nvs_flash_init` 会根据使用的方案（由 :menuitem:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` 设置）在内部执行一些额外步骤，为默认的 NVS 分区启用加密。
|
||||
|
||||
- 在基于 flash 加密的方案中，加密密钥由找到的第一个 :ref:`nvs_encr_key_partition` 生成。
|
||||
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
在 HMAC 方案中，密钥由 :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` 中烧录的 HMAC 密钥生成（参考 API 文档以了解更多详细信息）。
|
||||
在 HMAC 方案中，密钥由 :menuitem:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` 中烧录的 HMAC 密钥生成（参考 API 文档以了解更多详细信息）。
|
||||
|
||||
另外，还可使用 API 函数 :cpp:func:`nvs_flash_secure_init` 为默认 NVS 分区启用加密。
|
||||
|
||||
@@ -211,7 +211,7 @@ NVS API 函数 ``nvs_get_*`` 或 ``nvs_set_*`` 也可用于读取和写入加密
|
||||
.. only:: SOC_HMAC_SUPPORTED
|
||||
|
||||
.. note::
|
||||
在采用基于 HMAC 的方案时，可以在不启用任何 NVS 加密的配置选项的情况下开始上述工作流：:ref:`CONFIG_NVS_ENCRYPTION`，:ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> `CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC` 和 :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID`，以使用 :cpp:func:`nvs_flash_secure_init` API 加密默认分区及自定义的 NVS 分区。
|
||||
在采用基于 HMAC 的方案时，可以在不启用任何 NVS 加密的配置选项的情况下开始上述工作流：:menuitem:`CONFIG_NVS_ENCRYPTION`，:menuitem:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> `CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC` 和 :menuitem:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID`，以使用 :cpp:func:`nvs_flash_secure_init` API 加密默认分区及自定义的 NVS 分区。
|
||||
|
||||
|
||||
NVS Security Provider
|
||||
@@ -225,7 +225,7 @@ NVS Security Provider
|
||||
|
||||
.. note::
|
||||
|
||||
如果不希望使用 :component: `nvs_sec_provider` 组件的默认实现，而使用自定义方式生成或者保护 NVS 加密密钥，请选择 :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_NONE`` 配置项。
|
||||
如果不希望使用 :component: `nvs_sec_provider` 组件的默认实现，而使用自定义方式生成或者保护 NVS 加密密钥，请选择 :menuitem:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_NONE`` 配置项。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
@@ -21,7 +21,7 @@ NVS 使用分区表中类型为 ``data``、子类型为 ``nvs`` 的分区。该
|
||||
|
||||
.. note::
|
||||
|
||||
启用 :ref:`CONFIG_NVS_BDL_STACK` 后，NVS 也可以通过块设备层 (BDL) 运行，从而支持标准 flash 分区以外的其他存储后端。在 BDL 模式下，:cpp:func:`nvs_flash_init_partition_ptr` 不可用，但 :cpp:func:`nvs_flash_init_partition_bdl` 可用于自定义块设备初始化。详情见 :ref:`nvs_internals` > :ref:`nvs_underlying_storage`。
|
||||
启用 :menuitem:`CONFIG_NVS_BDL_STACK` 后，NVS 也可以通过块设备层 (BDL) 运行，从而支持标准 flash 分区以外的其他存储后端。在 BDL 模式下，:cpp:func:`nvs_flash_init_partition_ptr` 不可用，但 :cpp:func:`nvs_flash_init_partition_bdl` 可用于自定义块设备初始化。详情见 :ref:`nvs_internals` > :ref:`nvs_underlying_storage`。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -167,9 +167,9 @@ NVS 中的大量数据
|
||||
|
||||
默认情况下，内部 NVS 会在内部 RAM 中分配堆内存。对于较大的 NVS 分区或大量键，应用程序可能仅因 NVS 的开销就耗尽内部 RAM 的堆内存。
|
||||
|
||||
如果应用程序所使用的模组配备了通过 SPI 连接的 PSRAM，则可通过启用 Kconfig 选项 :ref:`CONFIG_NVS_ALLOCATE_CACHE_IN_SPIRAM` 来克服这一限制。该选项会将 RAM 分配重定向到通过 SPI 连接的 PSRAM。
|
||||
如果应用程序所使用的模组配备了通过 SPI 连接的 PSRAM，则可通过启用 Kconfig 选项 :menuitem:`CONFIG_NVS_ALLOCATE_CACHE_IN_SPIRAM` 来克服这一限制。该选项会将 RAM 分配重定向到通过 SPI 连接的 PSRAM。
|
||||
|
||||
当启用 SPIRAM 且 :ref:`CONFIG_SPIRAM_USE` 设为 ``CONFIG_SPIRAM_USE_CAPS_ALLOC`` 时，此选项可在 menuconfig 菜单的 nvs_flash 组件中使用。
|
||||
当启用 SPIRAM 且 :menuitem:`CONFIG_SPIRAM_USE` 设为 ``CONFIG_SPIRAM_USE_CAPS_ALLOC`` 时，此选项可在 menuconfig 菜单的 nvs_flash 组件中使用。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -180,7 +180,7 @@ NVS 中的大量数据
|
||||
|
||||
当 NVS 用于弱电源或不稳定电源系统（如太阳能或电池供电系统）时，flash 擦除操作可能偶尔无法彻底完成，而应用程序无法检测到这一问题。这会导致实际 flash 内容与预留页面的预期布局不一致。在极少数情况下（特别是在意外断电时），可能造成可用 NVS 页面耗尽，导致分区初始化失败并返回 ``ESP_ERR_NVS_NO_FREE_PAGES`` 错误。
|
||||
|
||||
为解决此问题，可通过 Kconfig 选项 :ref:`CONFIG_NVS_FLASH_VERIFY_ERASE` 启用 flash 擦除操作的验证机制，通过回读受影响页面进行检测。若在 ``flash_erase`` 操作后页面未完全擦除为 ``0xFF``，系统将重试擦除操作直至页面被正确清空。包括首次尝试在内的擦除尝试总次数可通过 Kconfig 选项 :ref:`CONFIG_NVS_FLASH_ERASE_ATTEMPTS` 进行配置。
|
||||
为解决此问题，可通过 Kconfig 选项 :menuitem:`CONFIG_NVS_FLASH_VERIFY_ERASE` 启用 flash 擦除操作的验证机制，通过回读受影响页面进行检测。若在 ``flash_erase`` 操作后页面未完全擦除为 ``0xFF``，系统将重试擦除操作直至页面被正确清空。包括首次尝试在内的擦除尝试总次数可通过 Kconfig 选项 :menuitem:`CONFIG_NVS_FLASH_ERASE_ATTEMPTS` 进行配置。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -526,7 +526,7 @@ NVS 正常运行所需的默认最小空间为 12 KiB (``0x3000``)，即至少
|
||||
底层存储
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
在构建时，可以配置 NVS 访问其底层存储的模式。menuconfig 选项 :ref:`CONFIG_NVS_BDL_STACK` 提供了两种模式。
|
||||
在构建时，可以配置 NVS 访问其底层存储的模式。menuconfig 选项 :menuitem:`CONFIG_NVS_BDL_STACK` 提供了两种模式。
|
||||
|
||||
**ESP 分区 API（默认）**：NVS 使用 :ref:`esp_partition <flash-partition-apis>` 访问存储。这是默认运行模式，其中 NVS 使用由分区表定义的 SPI flash 分区。在此模式下：
|
||||
|
||||
|
||||
@@ -172,7 +172,7 @@ VFS 组件支持通过 :cpp:func:`select` 进行同步输入/输出多路复用
|
||||
|
||||
.. note::
|
||||
|
||||
如果 :cpp:func:`select` 用于套接字文件描述符，可以禁用 :ref:`CONFIG_VFS_SUPPORT_SELECT` 选项来减少代码量，提高性能。
|
||||
如果 :cpp:func:`select` 用于套接字文件描述符，可以禁用 :menuitem:`CONFIG_VFS_SUPPORT_SELECT` 选项来减少代码量，提高性能。
|
||||
|
||||
不要在 :cpp:func:`select` 调用过程中更改套接字驱动，否则会出现一些未定义行为。
|
||||
|
||||
@@ -232,8 +232,8 @@ VFS 对文件路径长度没有限制，但文件系统路径前缀受 ``ESP_VFS
|
||||
IDF 定义了多个可供应用程序使用的 VFS 设备。这些设备包括：
|
||||
|
||||
* ``/dev/uart/<UART NUMBER>`` - 此文件映射到使用 VFS 驱动程序打开的 UART 中。UART 编号是 UART 外设的编号。
|
||||
* ``/dev/null`` - 此文件丢弃所有写入的数据，并在读取时返回 EOF。启用 :ref:`CONFIG_VFS_INITIALIZE_DEV_NULL` 会自动创建此文件。
|
||||
* ``/dev/console`` - 此文件连接到在 menuconfig 中由 :ref:`CONFIG_ESP_CONSOLE_UART` 和 :ref:`CONFIG_ESP_CONSOLE_SECONDARY` 指定的主输出和次输出。更多信息请参考 :doc:`../../api-guides/stdio`。
|
||||
* ``/dev/null`` - 此文件丢弃所有写入的数据，并在读取时返回 EOF。启用 :menuitem:`CONFIG_VFS_INITIALIZE_DEV_NULL` 会自动创建此文件。
|
||||
* ``/dev/console`` - 此文件连接到在 menuconfig 中由 :menuitem:`CONFIG_ESP_CONSOLE_UART` 和 :menuitem:`CONFIG_ESP_CONSOLE_SECONDARY` 指定的主输出和次输出。更多信息请参考 :doc:`../../api-guides/stdio`。
|
||||
|
||||
|
||||
应用示例
|
||||
|
||||
Reference in New Issue
Block a user