From e7ab36ebbf6b0b6f6552cd149be5dc9cc9307228 Mon Sep 17 00:00:00 2001 From: luweike Date: Tue, 5 Nov 2024 10:46:49 +0800 Subject: [PATCH] docs: Provide CN translation for partition tables --- docs/en/api-guides/partition-tables.rst | 4 +- docs/zh_CN/api-guides/partition-tables.rst | 52 +++++++++++++++++----- 2 files changed, 42 insertions(+), 14 deletions(-) diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index e2c5ec148b..61c6412ae1 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -228,11 +228,11 @@ Two flags are currently supported, ``encrypted`` and ``readonly``: - type ``data`` and subtype ``ota``, - type ``data`` and subtype ``nvs_keys``. - - If ``readonly`` flag is set, the partition will be read-only. This flag is only supported for ``data`` type partitions except ``ota``` and ``coredump``` subtypes. This flag can help to protect against accidental writes to a partition that contains critical device-specific configuration data, e.g., factory data partition. + - If ``readonly`` flag is set, the partition will be read-only. This flag is only supported for ``data`` type partitions except ``ota`` and ``coredump`` subtypes. This flag can help to protect against accidental writes to a partition that contains critical device-specific configuration data, e.g., factory data partition. .. note:: - Using C file I/O API to open a file (``fopen```) in any write mode (``w``, ``w+``, ``a``, ``a+``, ``r+``) will fail and return ``NULL``. Using ``open`` with any other flag than ``O_RDONLY`` will fail and return ``-1`` while ``errno`` global variable will be set to ``EROFS``. This is also true for any other POSIX syscall function performing write or erase operations. Opening a handle in read-write mode for NVS on a read-only partition will fail and return :c:macro:`ESP_ERR_NOT_ALLOWED` error code. Using a lower level API like ``esp_partition``, ``spi_flash``, etc. to write to a read-only partition will result in :c:macro:`ESP_ERR_NOT_ALLOWED` error code. + Using C file I/O API to open a file (``fopen``) in any write mode (``w``, ``w+``, ``a``, ``a+``, ``r+``) will fail and return ``NULL``. Using ``open`` with any other flag than ``O_RDONLY`` will fail and return ``-1`` while ``errno`` global variable will be set to ``EROFS``. This is also true for any other POSIX syscall function performing write or erase operations. Opening a handle in read-write mode for NVS on a read-only partition will fail and return :c:macro:`ESP_ERR_NOT_ALLOWED` error code. Using a lower level API like ``esp_partition``, ``spi_flash``, etc. to write to a read-only partition will result in :c:macro:`ESP_ERR_NOT_ALLOWED` error code. You can specify multiple flags by separating them with a colon. For example, ``encrypted:readonly``. diff --git a/docs/zh_CN/api-guides/partition-tables.rst b/docs/zh_CN/api-guides/partition-tables.rst index 735cfbe1ac..f6f95aec2c 100644 --- a/docs/zh_CN/api-guides/partition-tables.rst +++ b/docs/zh_CN/api-guides/partition-tables.rst @@ -73,6 +73,20 @@ CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文 * CSV 文件中的每个非注释行均为一个分区定义。 * 每个分区的 ``Offset`` 字段可以为空，``gen_esp32part.py`` 工具会从分区表位置的后面开始自动计算并填充该分区的偏移地址，同时确保每个分区的偏移地址正确对齐。 +下面是一个包含引导加载程序和分区表分区的 CSV 分区表示例： + +.. code-block:: none + + # ESP-IDF Partition Table + # Name, Type, SubType, Offset, Size, Flags + bootloader, bootloader, primary, N/A, N/A, + partition_table, partition_table, primary, N/A, N/A, + nvs, data, nvs, , 0x6000, + phy_init, data, phy, , 0x1000, + factory, app, factory, , 1M, + +``gen_esp32part.py`` 工具将根据所选的 Kconfig 选项将每个 ``N/A`` 替换为适当的值：引导加载程序的偏移地址为 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}，分区表的偏移地址见 :ref:`CONFIG_PARTITION_TABLE_OFFSET`。 + Name 字段 ~~~~~~~~~ @@ -83,10 +97,10 @@ Type 字段 Type 字段可以指定为名称或数字 0～254（或者十六进制 0x00-0xFE）。注意，不得使用预留给 ESP-IDF 核心功能的 0x00-0x3F。 -- ``app`` (0x00)。 -- ``data`` (0x01)。 -- ``bootloader`` (0x02)。该分区为可选项且不会影响系统功能，因此默认情况下，该分区不会出现在任何 CSV 分区表文件中，仅在引导加载程序 OTA 更新时有用。即使 CSV 文件中没有该分区，仍然可以执行 OTA。请注意，如果在 CSV 文件中指定了该分区，其地址和大小必须与 Kconfig 设置相匹配。 -- ``partition_table`` (0x03)。 +- ``app`` (0x00)， +- ``data`` (0x01)， +- ``bootloader`` (0x02)。该分区为可选项且不会影响系统功能，因此默认情况下，该分区不会出现在 ESP-IDF 的任何 CSV 分区表文件中，仅在引导加载程序 OTA 更新和 flash 分区时有用。即使 CSV 文件中没有该分区，仍然可以执行 OTA。 +- ``partition_table`` (0x03)。默认情况下，该分区也不会出现在 ESP-IDF 的任何 CSV 分区表文件中。 - 0x40-0xFE 预留给 **自定义分区类型**。如果你的应用程序需要以 ESP-IDF 尚未支持的格式存储数据，请在 0x40-0xFE 内添加一个自定义分区类型。 关于 ``app`` 和 ``data`` 分区的枚举定义，请参考 :cpp:type:`esp_partition_type_t`。 @@ -120,15 +134,19 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，ESP * 当 Type 定义为 ``bootloader`` 时，可以将 SubType 字段指定为： - - ``primary`` (0x00)，即二级引导加载程序，放置在 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 地址处。目前 ``gen_esp32part.py`` 不支持在 CSV 文件中包含该分区。 - - ``ota`` (0x01)，是一个临时的引导加载程序分区，在 OTA 更新期间可用于下载新的引导加载程序镜像。 + - ``primary`` (0x00)，即二级引导加载程序，位于 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 地址处。工具会自动确定此子类型的适当大小和偏移量，因此为此子类型指定的任何大小或偏移量将被忽略。你可以将这些字段留空或使用 ``N/A`` 作为占位符。 + - ``ota`` (0x01)，是一个临时的引导加载程序分区，在 OTA 更新期间可用于下载新的引导加载程序镜像。工具会忽略此子类型的大小，你可以将其留空或使用 ``N/A``。你只能指定一个偏移量，或者将其留空，工具将根据先前使用的分区的偏移量进行计算。 + + 引导加载程序的大小由 ``gen_esp32part.py`` 工具根据指定的 ``--offset`` (分区表偏移量) 和 ``--primary-partition-offset`` 参数计算。具体而言，引导加载程序的大小定义为 (:ref:`CONFIG_PARTITION_TABLE_OFFSET` - {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH})。此计算的大小适用于引导加载程序的所有子类型。 * 当 Type 定义为 ``partition_table`` 时，可以将 SubType 字段指定为： - - ``primary`` (0x00)。这是主分区表，放置在 flash 的 :ref:`CONFIG_PARTITION_TABLE_OFFSET` 地址处。目前 ``gen_esp32part.py`` 不支持在 CSV 文件中包含该分区。 - - ``ota`` (0x01)。这是一个临时的分区表分区，在 OTA 更新期间可用于下载新的分区表镜像。 + - ``primary`` (0x00)，是主分区表，位于 flash 的 :ref:`CONFIG_PARTITION_TABLE_OFFSET` 地址处。工具会自动确定此子类型的适当大小和偏移量，因此为此子类型指定的任何大小或偏移量将被忽略。你可以将这些字段留空或使用 ``N/A`` 作为占位符。 + - ``ota`` (0x01)，是一个临时的分区表分区，在 OTA 更新期间可用于下载新的分区表镜像。工具会忽略此子类型的大小，你可以将其留空或使用 ``N/A``。你可以指定一个偏移量，或者将其留空，工具将根据先前分配的分区的偏移量进行计算。 -* 当 Type 定义为 ``data`` 时，SubType 字段可以指定为 ``ota`` (0x00)、``phy`` (0x01)、``nvs`` (0x02)、``nvs_keys`` (0x04) 或者其他组件特定的子类型（请参考 :cpp:type:`子类型枚举 `). + ``partition_table`` 的大小固定为 ``0x1000``，适用于 ``partition_table`` 的所有子类型。 + +* 当 Type 定义为 ``data`` 时，SubType 字段可以指定为 ``ota`` (0x00)、``phy`` (0x01)、``nvs`` (0x02)、``nvs_keys`` (0x04) 或者其他组件特定的子类型（请参考 :cpp:type:`子类型枚举 `）。 - ``ota`` (0) 即 :ref:`OTA 数据分区 ` ，用于存储当前所选的 OTA 应用程序的信息。这个分区的大小需要设定为 0x2000。更多详细信息，请参考 :doc:`OTA 文档 <../api-reference/system/ota>` 。 - ``phy`` (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。 @@ -184,8 +202,10 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，ESP - 若 CSV 文件中的分区偏移地址为空，则该分区会接在前一个分区之后；若为首个分区，则将接在分区表之后。 - ``app`` 分区的偏移地址必须与 0x10000 (64 KB) 对齐。如果偏移字段留空，则 ``gen_esp32part.py`` 工具会自动计算得到一个满足对齐要求的偏移地址。如果 ``app`` 分区的偏移地址没有与 0x10000 (64 KB) 对齐，则该工具会报错。 - ``app`` 分区的大小必须与 flash 扇区大小对齐。为 ``app`` 分区指定未对齐的大小将返回错误。 - :SOC_SECURE_BOOT_V1: - 若启用了安全启动 V1，则 ``app`` 分区的大小需与 0x10000 (64 KB) 对齐。 + :SOC_SECURE_BOOT_V1: - 若启用了 Secure Boot V1，则 ``app`` 分区的大小需与 0x10000 (64 KB) 对齐。 + :SOC_SECURE_BOOT_V1: - ``bootloader`` 的偏移量和大小不受 Secure Boot V1 选项的影响。无论是否启用 Secure Boot V1，引导加载程序的大小保持不变，并且不包括安全摘要，安全摘要位于 flash 的 0x0 偏移地址处，占用一个扇区（4096 字节）。 - ``app`` 分区的大小和偏移地址可以采用十进制数或是以 0x 为前缀的十六进制数，且支持 K 或 M 的倍数单位（K 和 M 分别代表 1024 和 1024*1024 字节）。 + - 对于 ``bootloader`` 和 ``partition_table``，在 CSV 文件中将大小和偏移量指定为 ``N/A`` 意味着这些值将由工具自动确定，无法手动定义。这需要设置 ``gen_esp32part.py`` 工具的 ``--offset`` 和 ``--primary-partition-offset`` 参数。 如果你希望允许分区表中的分区采用任意起始偏移量 (:ref:`CONFIG_PARTITION_TABLE_OFFSET`)，请将分区表（CSV 文件）中所有分区的偏移字段都留空。注意，此时，如果你更改了分区表中任意分区的偏移地址，则其他分区的偏移地址也会跟着改变。这种情况下，如果你之前还曾设定某个分区采用固定偏移地址，则可能造成分区表冲突，从而导致报错。 @@ -198,13 +218,21 @@ Flags 字段 .. note:: - 无论是否设置 Flags 字段，``app`` 分区都将保持加密。 + 无论是否设置 Flags 字段，当启用了 :doc:`/security/flash-encryption` 功能时，以下类型的分区将始终保持加密状态。 + + .. list:: + + - ``app``， + - ``bootloader``， + - ``partition_table``， + - type ``data`` 和 subtype ``ota``， + - type ``data`` 和 subtype ``nvs_keys``。 - 如果 Flags 字段设置为 ``readonly``，则该分区为只读分区。``readonly`` 标记仅支持除 ``ota`` 和 ``coredump`` 子类型外的 ``data`` 分区。使用该标记，防止意外写入如出厂数据分区等包含关键设备特定配置数据的分区。 .. note:: - 在任何写入模式下 (``w``、``w+``、``a``、``a+``、``r+``)，尝试通过 C 文件 I/O API 打开文件 (``fopen```) 的操作都将失败并返回 ``NULL``。除 ``O_RDONLY`` 外，``open`` 与任何标志一同使用都将失败并返回 ``-1``，全局变量 ``errno`` 也将设置为 ``EROFS``。上述情况同样适用于通过其他 POSIX 系统调用函数执行写入或擦除的操作。在只读分区上，以读写模式打开 NVS 的句柄将失败并返回 :c:macro:`ESP_ERR_NOT_ALLOWED` 错误代码，使用 ``esp_partition`` 或 ``spi_flash`` 等较低级别的 API 进行写入操作也将返回 :c:macro:`ESP_ERR_NOT_ALLOWED` 错误代码。 + 在任何写入模式下 (``w``、``w+``、``a``、``a+``、``r+``)，尝试通过 C 文件 I/O API 打开文件 (``fopen``) 的操作都将失败并返回 ``NULL``。除 ``O_RDONLY`` 外，``open`` 与任何标志一同使用都将失败并返回 ``-1``，全局变量 ``errno`` 也将设置为 ``EROFS``。上述情况同样适用于通过其他 POSIX 系统调用函数执行写入或擦除的操作。在只读分区上，以读写模式打开 NVS 的句柄将失败并返回 :c:macro:`ESP_ERR_NOT_ALLOWED` 错误代码，使用 ``esp_partition`` 或 ``spi_flash`` 等较低级别的 API 进行写入操作也将返回 :c:macro:`ESP_ERR_NOT_ALLOWED` 错误代码。 可以使用冒号连接不同的标记，来同时指定多个标记，如 ``encrypted:readonly``。