From d61680b2110ac17861ff2a0983b035f4214164d1 Mon Sep 17 00:00:00 2001 From: morris Date: Wed, 10 Oct 2018 09:43:31 +0800 Subject: [PATCH 1/2] doc/partition-tables: translation of zh_CN 1. Translated partition-tables.rst into Chinese. 2. Fixed some error in the English version. --- docs/en/api-guides/partition-tables.rst | 10 +- docs/zh_CN/api-guides/index.rst | 2 +- docs/zh_CN/api-guides/partition-tables.rst | 188 ++++++++++++++++++++- 3 files changed, 193 insertions(+), 7 deletions(-) diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index b2d1108db6..151d445d10 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -6,7 +6,7 @@ Overview A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset `) 0x8000 in the flash. -Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table. +Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table. Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded. @@ -42,8 +42,7 @@ Here is the summary printed for the "Factory app, two OTA definitions" configura ota_0, 0, ota_0, 0x110000, 1M, ota_1, 0, ota_1, 0x210000, 1M, -* There are now three app partition definitions. -* The type of all three are set as "app", but the subtype varies between the factory app at 0x10000 and the next two "OTA" apps. +* There are now three app partition definitions. The type of the factory app (at 0x10000) and the next two "OTA" apps are all set to "app", but their subtypes are different. * There is also a new "ota data" slot, which holds the data for OTA updates. The bootloader consults this data in order to know which app to execute. If "ota data" is empty, it will execute the factory app. Creating Custom Tables @@ -102,7 +101,7 @@ When type is "app", the subtype field can be specified as factory (0), ota_0 (0x Data Subtypes ~~~~~~~~~~~~~ -When type is "data", the subtype field can be specified as ota (0), phy (1), nvs (2). +When type is "data", the subtype field can be specified as ota (0), phy (1), nvs (2) or nvs_keys (4). - ota (0) is the :ref:`OTA data partition ` which stores information about the currently selected OTA application. This partition should be 0x2000 bytes in size. Refer to the :ref:`OTA documentation ` for more details. - phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware. @@ -116,7 +115,8 @@ When type is "data", the subtype field can be specified as ota (0), phy (1), nvs - The NVS API can also be used for other application data. - It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project. - If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes. -- keys (4) is for the NVS key partition. See :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>` for more details. +- nvs_keys (4) is for the NVS key partition. See :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>` for more details. + - It is used to store NVS encryption keys when `NVS Encryption` feature is enabled. - The size of this partition should be 4096 bytes (minimum partition size). diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index e4f7504677..bd4d6ee5c5 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -17,7 +17,7 @@ API 指南 High Level Interrupts JTAG Debugging Bootloader - Partition Tables + 分区表 Secure Boot <../security/secure-boot> ULP Coprocessor ULP Coprocessor (CMake) diff --git a/docs/zh_CN/api-guides/partition-tables.rst b/docs/zh_CN/api-guides/partition-tables.rst index 10eca64086..d07f3424ed 100644 --- a/docs/zh_CN/api-guides/partition-tables.rst +++ b/docs/zh_CN/api-guides/partition-tables.rst @@ -1 +1,187 @@ -.. include:: ../../en/api-guides/partition-tables.rst \ No newline at end of file +分区表 +====== + +概述 +---- + +单个 ESP32 的闪存可以包含多个应用程序，以及多种不同类型的数据（例如校准数据、文件系统、参数存储器等）。因此，我们需要在闪存的 :ref:`默认偏移地址 ` 0x8000 处烧写一张分区表。 + +分区表的长度为 0xC00 字节（最多可以保存 95 个分区表条目），在分区表数据的后面保存着它的 MD5 校验和，它用于验证分区表的完整性。如果使用了ESP32的 :doc:`安全启动 ` 功能，那么分区表还会被签名，该签名被附加在分区表的后面。 + +分区表中的每个条目都会包含名称（标签）、类型（应用程序、数据等）、子类型以及在闪存中的偏移量（分区的加载地址）。 + +使用分区表最简单的方法就是通过 `make menuconfig` 选择一张预定义的分区表： + +- "Single factory app, no OTA" +- "Factory app, two OTA definitions" + +在这两种情况下，出厂应用程序被烧写到闪存的 0x10000 偏移地址处，运行 ``make partition_table`` 命令可以打印出当前使用的分区表的信息摘要。 + +内置分区表 +------------ + +以下是 "Single factory app, no OTA" 配置打印的信息摘要： + +.. code:: bash + + # Espressif ESP32 Partition Table + # Name, Type, SubType, Offset, Size, Flags + nvs, data, nvs, 0x9000, 0x6000, + phy_init, data, phy, 0xf000, 0x1000, + factory, app, factory, 0x10000, 1M, + +- 闪存的 0x10000 (64KB) 偏移地址处存放二进制应用程序，它被标记为 "factory"，引导程序默认会加载运行该分区的应用程序。 +- 分区表中还定义了两个数据区域，分别用于存储 NVS 库专用分区和 PHY 初始化数据。 + +以下是 "Factory app, two OTA definitions" 配置打印的信息摘要： + +.. code:: bash + + # Espressif ESP32 Partition Table + # Name, Type, SubType, Offset, Size, Flags + nvs, data, nvs, 0x9000, 0x4000, + otadata, data, ota, 0xd000, 0x2000, + phy_init, data, phy, 0xf000, 0x1000, + factory, app, factory, 0x10000, 1M, + ota_0, app, ota_0, 0x110000, 1M, + ota_1, app, ota_1, 0x210000, 1M, + +- 分区表中定义了三个应用程序分区，这三个分区的类型都被设置为 “app”，但是子类型不同。出厂应用程序（factory）位于 0x10000 偏移地址处，其余两个是 OTA 应用程序（ota_0，ota_1）。 +- 新增了一个名为 “otadata” 的数据分区，用于保存 OTA 升级时候需要的数据。引导程序会查询该分区的数据用以判断该从哪个 OTA 应用程序分区加载程序。如果 “otadata” 分区是空的，则会执行出厂程序。 + +创建自定义分区表 +---------------- + +如果在 menuconfig 中选择了 “Custom partition table CSV”，则还需要输入该分区表的 CSV 文件在项目中的路径。CSV 文件可以根据需要描述任意数量的分区信息。 + +CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文件中并非所有字段都是必需的。例如下面是一个自定义的 OTA 分区表的 CSV 文件： + +.. code:: bash + + # Name, Type, SubType, Offset, Size, Flags + nvs, data, nvs, 0x9000, 0x4000 + otadata, data, ota, 0xd000, 0x2000 + phy_init, data, phy, 0xf000, 0x1000 + factory, app, factory, 0x10000, 1M + ota_0, app, ota_0, , 1M + ota_1, app, ota_1, , 1M + nvs_key, data, nvs_keys, , 0x1000 + +- 字段之间的空格会被忽略，任何以 ``#`` 开头的行（注释）也会被忽略。 +- CSV 文件中的每个非注释行都定义了一个分区。 +- 每个分区的 ``Offset`` 字段可以为空，``gen_esp32part.py`` 工具会从分区表位置的后面开始自动计算并填充该分区的偏移地址，同时确保每个分区的偏移地址正确对齐。 + +Name 字段 +~~~~~~~~~ + +Name 字段可以是任何有意义的名称，这对 ESP32 来说并不是特别重要。超过 16 个字符长度的名字将会被截断。 + +Type 字段 +~~~~~~~~~ + +Type 字段可以指定为 app (0) 或者 data (1)，甚至可以直接使用数字 0-254（或者十六进制 0x00-0xFE）来指定。类型 0x00-0x3F 被保留用于 esp-idf 的核心功能。 + +如果您的应用程序需要保存数据，请在 0x40-0xFE 的范围内添加自定义的分区类型。 + +引导程序会忽略 app (0) 和 data (1) 以外的任何分区类型。 + +SubType 字段 +~~~~~~~~~~~~ + +8 比特的子类型字段与给定的分区类型有关，esp-idf 目前仅仅指定了 “app” 和 “data” 分区的子类型字段。 + +app 子类型 +~~~~~~~~~~~~ + +当类型被定义为 ``app`` 时，子类型字段可以指定为 factory (0)，ota_0 (0x10) ... ota_15 (0x1F) 或者 test (0x20)。 + +- factory (0) 是默认的 app 分区，如果不存在 data/ota 分区，引导程序会运行 app/factory 分区中的程序。如果存在 data/ota 分区，则会读取该分区的数据，进而判断应该启动哪个 OTA 镜像。 + + - OTA 升级永远都不会更新 factory 分区中的程序。 + - 如果想节省 OTA 项目中的闪存，可以删除 factory 分区，使用 ota_0 分区替代。 +- ota_0 (0x10) ... ota_15 (0x1F) 便是 OTA 应用程序分区，引导程序根据 OTA 数据分区中的数据来决定从哪个 OTA 应用程序分区中加载程序。如果使用了 OTA 功能，那么至少需要包含两个 OTA 应用程序分区（ota_0 和 ota_1）。更多详细信息请参考 :doc:`OTA 文档 ` 。 +- test (0x2) 是工厂测试过程的保留子类型，当前 esp-idf 的引导程序并不支持这种子类型。 + +data 子类型 +~~~~~~~~~~~~~ + +当类型被定义为 ``data`` 时，子类型字段可以指定为 ota (0)，phy (1)，nvs (2) 和 nvs_keys (4)。 + +- ota (0) 即 :ref:`OTA 数据分区 ` ，用于存储当前所选的 OTA 应用程序的信息。这个分区的大小需要设定为 0x2000。更多详细信息请参考 :doc:`OTA 文档 <../api-reference/system/ota>` 。 +- phy (1) 分区用于存放 PHY 初始化数据，这样就可以为每个设备（而不是在固件中）单独配置 PHY，而不是在固件中设定好PHY的初始化数据。 + + - 在默认的配置中并不使用 phy 分区， PHY 的初始化数据被编译进了应用程序中。因此可以从分区表中删除此分区以节省空间。 + - 如果要从此分区加载 PHY 初始化数据，请运行 ``make menuconfig`` 并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。您还需要将 PHY 的初始化数据手动烧写到闪存中，esp-idf 编译系统不会自动完成该操作。 +- nvs (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。 + + - NVS 用于存储每台设备的 PHY 校准数据（区别于 PHY 初始化数据）。 + - NVS 用于存储 WiFi 数据（如果使用了 :cpp:func:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) ` 初始化函数）。 + - NVS API 还可以用于其他应用程序数据。 + - 强烈建议您在项目中分配至少 0x3000 字节的空间给 NVS 分区。 + - 如果使用 NVS API 来存储大量数据，请增加 NVS 分区的大小（默认是 0x6000 字节）。 +- nvs_keys (4) 是 NVS 秘钥分区。详细信息请参考 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 文档。 + + - 它用于在启用 `NVS 加密` 功能的时候存储加密密钥。 + - 此分区的大小需要设定为 4096 字节（即最小的分区大小）。 + +其它数据子类型保留给未来的 esp-idf 使用。 + +Offset 和 Size 字段 +~~~~~~~~~~~~~~~~~~~ + +没有指定偏移地址的分区会紧跟在前一个分区之后，如果第一个分区没有指定偏移地址，那么该分区会紧跟在分区表之后。 + +应用程序分区的偏移地址必须要与 0x10000 (64K) 对齐，如果将偏移字段留空， ``gen_esp32part.py`` 工具会自动计算得到一个满足对齐要求的偏移地址。如果给应用程序的分区指定了未对齐的偏移地址，该工具会报错。 + +大小和偏移可以以十进制形式指定，也可以以 0x 为前缀的十六进制形式指定，或者以 K 或 M 作为单位指定（分别代表 1024 和 1024*1024 字节）。 + +如果希望分区表中的分区可以使用任何的起始偏移量 (:ref:`CONFIG_PARTITION_TABLE_OFFSET`)，请将分区表（CSV文件）中所有分区的偏移字段都留空。类似的，如果更改了分区表的偏移地址，则要注意所有留空的分区偏移可能会被更改到新的合适的位置，此时一些固定的偏移地址可能会与分区表冲突，从而导致错误。 + +Flags 字段 +~~~~~~~~~~ + +当前仅支持 ``encrypted`` 标记，如果标记字段被设置为了 ``encrypted``，那么该分区将会被加密（假如启用了 :doc:`闪存加密 ` 的功能）。 + +.. note:: ``app`` 分区始终会被加密，不管标记字段是否被设置。 + +生成二进制分区表 +---------------- + +烧写到 ESP32 中的分区表是二进制格式的，而不是 CSV 文件本身。:component_file:`partition_table/gen_esp32part.py` 工具可以用来在 CSV 文件和二进制文件之间进行转换。 + +如果您在 ``make menuconfig`` 中指定了 CSV 分区表的名称，然后执行 ``make partition_table`` 那么该转化过程会在编译的过程中自动完成。 + +手动将 CSV 转换为 二进制文件： + +.. code:: bash + + python gen_esp32part.py input_partitions.csv binary_partitions.bin + +将二进制文件转换为 CSV 文件： + +.. code:: bash + + python gen_esp32part.py binary_partitions.bin input_partitions.csv + +在标准输出（stdout）上打印二进制分区表的内容（这正是执行 ``make partition_table`` 时显示的信息摘要）： + +.. code:: bash + + python gen_esp32part.py binary_partitions.bin + +MD5 校验和 +~~~~~~~~~~ + +二进制格式的分区表中包含有基于分区表计算得到的 MD5 校验和，此校验和用于在程序引导阶段检查分区表的完整性。 + +可以通过 ``gen_esp32part.py`` 的 ``--disable-md5sum`` 选项或者 ``menuconfig`` 中的 :ref:`CONFIG_PARTITION_TABLE_MD5` 选项来禁止生成 MD5 校验和。当老版本的引导程序无法处理 MD5 校验和而失败，并且打印错误信息 ``invalid magic number 0xebeb`` 的时候就需要禁止 MD5 。 + +烧写分区表 +---------- + +- ``make partition_table-flash`` ：使用 esptool.py 工具烧写分区表。 +- ``make flash`` ：会烧写所有内容，包括分区表。 + +手动烧写的命令会作为 ``make partition_table`` 命令执行过程的一部分被打印在终端上。 + +.. note:: 更新分区表的时候不会删除旧分区表存储的数据，您可以使用 ``make erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除整块闪存的内容。 From 9894d3583988d04eaf2d6991889a3cfd96cc4056 Mon Sep 17 00:00:00 2001 From: liying Date: Fri, 2 Nov 2018 18:51:20 +0800 Subject: [PATCH 2/2] (doc)update_CN/EN_partition_tables --- docs/en/api-guides/partition-tables.rst | 60 ++++----- docs/zh_CN/api-guides/partition-tables.rst | 136 ++++++++++----------- 2 files changed, 89 insertions(+), 107 deletions(-) diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index 151d445d10..19ae39bd4a 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -6,7 +6,7 @@ Overview A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset `) 0x8000 in the flash. -Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table. +Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table, is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table. Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded. @@ -43,7 +43,7 @@ Here is the summary printed for the "Factory app, two OTA definitions" configura ota_1, 0, ota_1, 0x210000, 1M, * There are now three app partition definitions. The type of the factory app (at 0x10000) and the next two "OTA" apps are all set to "app", but their subtypes are different. -* There is also a new "ota data" slot, which holds the data for OTA updates. The bootloader consults this data in order to know which app to execute. If "ota data" is empty, it will execute the factory app. +* There is also a new "otadata" slot, which holds the data for OTA updates. The bootloader consults this data in order to know which app to execute. If "ota data" is empty, it will execute the factory app. Creating Custom Tables ---------------------- @@ -79,46 +79,38 @@ If your application needs to store data, please add a custom partition type in t The bootloader ignores any partition types other than app (0) & data (1). -Subtype +SubType ~~~~~~~ -The 8-bit subtype field is specific to a given partition type. +The 8-bit subtype field is specific to a given partition type. esp-idf currently only specifies the meaning of the subtype field for "app" and "data" partition types. -esp-idf currently only specifies the meaning of the subtype field for "app" and "data" partition types. +* When type is "app", the subtype field can be specified as factory (0), ota_0 (0x10) ... ota_15 (0x1F) or test (0x20). -App Subtypes -~~~~~~~~~~~~ + - factory (0) is the default app partition. The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot. -When type is "app", the subtype field can be specified as factory (0), ota_0 (0x10) ... ota_15 (0x1F) or test (0x20). + - OTA never updates the factory partition. + - If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ota_0 instead. + - ota_0 (0x10) ... ota_15 (0x1F) are the OTA app slots. Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details, which then use the OTA data partition to configure which app slot the bootloader should boot. If using OTA, an application should have at least two OTA application slots (ota_0 & ota_1). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details. + - test (0x2) is a reserved subtype for factory test procedures. It is not currently supported by the esp-idf bootloader. -- factory (0) is the default app partition. The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot. +* When type is "data", the subtype field can be specified as ota (0), phy (1), nvs (2), or nvs_keys (4). - - OTA never updates the factory partition. - - If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ota_0 instead. -- ota_0 (0x10) ... ota_15 (0x1F) are the OTA app slots. Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details, which then use the OTA data partition to configure which app slot the bootloader should boot. If using OTA, an application should have at least two OTA application slots (ota_0 & ota_1). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details. -- test (0x2) is a reserved subtype for factory test procedures. It is not currently supported by the esp-idf bootloader. + - ota (0) is the :ref:`OTA data partition ` which stores information about the currently selected OTA application. This partition should be 0x2000 bytes in size. Refer to the :ref:`OTA documentation ` for more details. + - phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware. -Data Subtypes -~~~~~~~~~~~~~ + - In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space. + - To load PHY data from this partition, run ``make menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically. + - nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`. -When type is "data", the subtype field can be specified as ota (0), phy (1), nvs (2) or nvs_keys (4). + - NVS is used to store per-device PHY calibration data (different to initialisation data). + - NVS is used to store WiFi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/wifi/esp_wifi>` initialisation function is used. + - The NVS API can also be used for other application data. + - It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project. + - If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes. + - nvs_keys (4) is for the NVS key partition. See :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>` for more details. -- ota (0) is the :ref:`OTA data partition ` which stores information about the currently selected OTA application. This partition should be 0x2000 bytes in size. Refer to the :ref:`OTA documentation ` for more details. -- phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware. - - - In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space. - - To load PHY data from this partition, run ``make menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically. -- nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`. - - - NVS is used to store per-device PHY calibration data (different to initialisation data). - - NVS is used to store WiFi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/wifi/esp_wifi>` initialisation function is used. - - The NVS API can also be used for other application data. - - It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project. - - If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes. -- nvs_keys (4) is for the NVS key partition. See :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>` for more details. - - - It is used to store NVS encryption keys when `NVS Encryption` feature is enabled. - - The size of this partition should be 4096 bytes (minimum partition size). + - It is used to store NVS encryption keys when `NVS Encryption` feature is enabled. + - The size of this partition should be 4096 bytes (minimum partition size). Other data subtypes are reserved for future esp-idf uses. @@ -127,7 +119,7 @@ Offset & Size Partitions with blank offsets will start after the previous partition, or after the partition table in the case of the first partition. -App partitions have to be at offsets aligned to 0x10000 (64K). If you leave the offset field blank, the tool will automatically align the partition. If you specify an unaligned offset for an app partition, the tool will return an error. +App partitions have to be at offsets aligned to 0x10000 (64K). If you leave the offset field blank, ``gen_esp32part.py`` will automatically align the partition. If you specify an unaligned offset for an app partition, the tool will return an error. Sizes and offsets can be specified as decimal numbers, hex numbers with the prefix 0x, or size multipliers K or M (1024 and 1024*1024 bytes). @@ -151,7 +143,7 @@ To convert CSV to Binary manually:: python gen_esp32part.py input_partitions.csv binary_partitions.bin -To convert binary format back to CSV:: +To convert binary format back to CSV manually:: python gen_esp32part.py binary_partitions.bin input_partitions.csv diff --git a/docs/zh_CN/api-guides/partition-tables.rst b/docs/zh_CN/api-guides/partition-tables.rst index d07f3424ed..d06f8ece43 100644 --- a/docs/zh_CN/api-guides/partition-tables.rst +++ b/docs/zh_CN/api-guides/partition-tables.rst @@ -4,25 +4,24 @@ 概述 ---- -单个 ESP32 的闪存可以包含多个应用程序，以及多种不同类型的数据（例如校准数据、文件系统、参数存储器等）。因此，我们需要在闪存的 :ref:`默认偏移地址 ` 0x8000 处烧写一张分区表。 +每片 ESP32 的 flash 可以包含多个应用程序，以及多种不同类型的数据（例如校准数据、文件系统数据、参数存储器数据等）。因此，我们需要引入分区表的概念。 -分区表的长度为 0xC00 字节（最多可以保存 95 个分区表条目），在分区表数据的后面保存着它的 MD5 校验和，它用于验证分区表的完整性。如果使用了ESP32的 :doc:`安全启动 ` 功能，那么分区表还会被签名，该签名被附加在分区表的后面。 +具体来说，ESP32 在 flash 的 :ref:`默认偏移地址 ` 0x8000 处烧写一张分区表。该分区表的长度为 0xC00 字节（最多可以保存 95 条分区表条目）。分区表数据后还保存着该表的 MD5 校验和，用于验证分区表的完整性。此外，如果芯片使能了 :doc:`安全启动 ` 功能，则该分区表后还会保存签名信息。 -分区表中的每个条目都会包含名称（标签）、类型（应用程序、数据等）、子类型以及在闪存中的偏移量（分区的加载地址）。 +分区表中的每个条目都包括以下几个部分：Name（标签）、Type（app、data 等）、SubType 以及在 flash 中的偏移量（分区的加载地址）。 -使用分区表最简单的方法就是通过 `make menuconfig` 选择一张预定义的分区表： +在使用分区表时，最简单的方法就是用 `make menuconfig` 选择一张预定义的分区表： - "Single factory app, no OTA" - "Factory app, two OTA definitions" -在这两种情况下，出厂应用程序被烧写到闪存的 0x10000 偏移地址处，运行 ``make partition_table`` 命令可以打印出当前使用的分区表的信息摘要。 +在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `make partition_table` ，即可以打印当前使用分区表的信息摘要。 内置分区表 ------------ -以下是 "Single factory app, no OTA" 配置打印的信息摘要： +以下是 "Single factory app, no OTA" 选项的分区表信息摘要： -.. code:: bash # Espressif ESP32 Partition Table # Name, Type, SubType, Offset, Size, Flags @@ -30,12 +29,10 @@ phy_init, data, phy, 0xf000, 0x1000, factory, app, factory, 0x10000, 1M, -- 闪存的 0x10000 (64KB) 偏移地址处存放二进制应用程序，它被标记为 "factory"，引导程序默认会加载运行该分区的应用程序。 +- flash 的 0x10000 (64KB) 偏移地址处存放一个标记为 "factory" 的二进制应用程序，且 Bootloader 将默认加载这个应用程序。 - 分区表中还定义了两个数据区域，分别用于存储 NVS 库专用分区和 PHY 初始化数据。 -以下是 "Factory app, two OTA definitions" 配置打印的信息摘要： - -.. code:: bash +以下是 "Factory app, two OTA definitions" 选项的分区表信息摘要： # Espressif ESP32 Partition Table # Name, Type, SubType, Offset, Size, Flags @@ -46,18 +43,16 @@ ota_0, app, ota_0, 0x110000, 1M, ota_1, app, ota_1, 0x210000, 1M, -- 分区表中定义了三个应用程序分区，这三个分区的类型都被设置为 “app”，但是子类型不同。出厂应用程序（factory）位于 0x10000 偏移地址处，其余两个是 OTA 应用程序（ota_0，ota_1）。 -- 新增了一个名为 “otadata” 的数据分区，用于保存 OTA 升级时候需要的数据。引导程序会查询该分区的数据用以判断该从哪个 OTA 应用程序分区加载程序。如果 “otadata” 分区是空的，则会执行出厂程序。 +- 分区表中定义了三个应用程序分区，这三个分区的类型都被设置为 “app”，但具体 app 类型不同。其中，位于 0x10000 偏移地址处的为出厂应用程序（factory），其余两个为 OTA 应用程序（ota_0，ota_1）。 +- 新增了一个名为 “otadata” 的数据分区，用于保存 OTA 升级时候需要的数据。Bootloader 会查询该分区的数据，以判断该从哪个 OTA 应用程序分区加载程序。如果 “otadata” 分区为空，则会执行出厂程序。 创建自定义分区表 ---------------- -如果在 menuconfig 中选择了 “Custom partition table CSV”，则还需要输入该分区表的 CSV 文件在项目中的路径。CSV 文件可以根据需要描述任意数量的分区信息。 +如果在 ``menuconfig`` 中选择了 “Custom partition table CSV”，则还需要输入该分区表的 CSV 文件在项目中的路径。CSV 文件可以根据需要，描述任意数量的分区信息。 CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文件中并非所有字段都是必需的。例如下面是一个自定义的 OTA 分区表的 CSV 文件： -.. code:: bash - # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x4000 otadata, data, ota, 0xd000, 0x2000 @@ -68,113 +63,104 @@ CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文 nvs_key, data, nvs_keys, , 0x1000 - 字段之间的空格会被忽略，任何以 ``#`` 开头的行（注释）也会被忽略。 -- CSV 文件中的每个非注释行都定义了一个分区。 +- CSV 文件中的每个非注释行均为一个分区定义。 - 每个分区的 ``Offset`` 字段可以为空，``gen_esp32part.py`` 工具会从分区表位置的后面开始自动计算并填充该分区的偏移地址，同时确保每个分区的偏移地址正确对齐。 Name 字段 ~~~~~~~~~ -Name 字段可以是任何有意义的名称，这对 ESP32 来说并不是特别重要。超过 16 个字符长度的名字将会被截断。 +Name 字段可以是任何有意义的名称，但不能超过 16 个字符（之后的内容将被截断）。该字段对 ESP32 并不是特别重要。 Type 字段 ~~~~~~~~~ -Type 字段可以指定为 app (0) 或者 data (1)，甚至可以直接使用数字 0-254（或者十六进制 0x00-0xFE）来指定。类型 0x00-0x3F 被保留用于 esp-idf 的核心功能。 +Type 字段可以指定为 app (0) 或者 data (1)，也可以直接使用数字 0-254（或者十六进制 0x00-0xFE）。注意，0x00-0x3F 不得使用（预留给 esp-idf 的核心功能）。 -如果您的应用程序需要保存数据，请在 0x40-0xFE 的范围内添加自定义的分区类型。 +如果您的应用程序需要保存数据，请在 0x40-0xFE 内添加一个自定义分区类型。 + +注意，bootloader 将忽略 app (0) 和 data (1) 以外的其他分区类型。 -引导程序会忽略 app (0) 和 data (1) 以外的任何分区类型。 SubType 字段 ~~~~~~~~~~~~ -8 比特的子类型字段与给定的分区类型有关，esp-idf 目前仅仅指定了 “app” 和 “data” 分区的子类型字段。 +SubType 字段长度为 8 bit，内容与具体 Type 有关。目前，esp-idf 仅仅规定了 “app” 和 “data” 两种子类型。 + +* 当 Type 定义为 ``app`` 时，SubType 字段可以指定为 factory (0)，ota_0 (0x10) ... ota_15 (0x1F) 或者 test (0x20)。 -app 子类型 -~~~~~~~~~~~~ + - factory (0) 是默认的 app 分区。Bootloader 将默认加在该应用程序。但如果存在类型为 data/ota 分区，则 Bootloader 将加载 data/ota 分区中的数据，进而判断启动哪个 OTA 镜像文件。 + - OTA 升级永远都不会更新 factory 分区中的内容。 + - 如果您希望在 OTA 项目中预留更多 flash，可以删除 factory 分区，转而使用 ota_0 分区。 -当类型被定义为 ``app`` 时，子类型字段可以指定为 factory (0)，ota_0 (0x10) ... ota_15 (0x1F) 或者 test (0x20)。 + - ota_0 (0x10) ... ota_15 (0x1F) 为 OTA 应用程序分区，Bootloader 将根据 OTA 数据分区中的数据来决定加载哪个 OTA 应用程序分区中的程序。在使用 OTA 功能时，应用程序应至少拥有 2 个 OTA 应用程序分区（ota_0 和 ota_1）。更多详细信息，请参考 :doc:`OTA 文档 ` 。 + - test (0x2) 为预留 app 子类型，用于工厂测试过程。注意，目前，esp-idf 并不支持这种子类型。 + +* 当 Type 定义为 ``data`` 时，SubType 字段可以指定为 ota (0)，phy (1)，nvs (2) 或者 nvs_keys (4)。 -- factory (0) 是默认的 app 分区，如果不存在 data/ota 分区，引导程序会运行 app/factory 分区中的程序。如果存在 data/ota 分区，则会读取该分区的数据，进而判断应该启动哪个 OTA 镜像。 + - ota (0) 即 :ref:`OTA 数据分区 ` ，用于存储当前所选的 OTA 应用程序的信息。这个分区的大小需要设定为 0x2000。更多详细信息，请参考 :doc:`OTA 文档 <../api-reference/system/ota>` 。 + - phy (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。 + + - 默认配置下，phy 分区并不启用，而是直接将 phy 初始化数据编译至应用程序中，从而节省分区表空间（直接将此分区删掉）。 + - 如果需要从此分区加载 phy 初始化数据，请运行 ``make menuconfig``，并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。此时，您还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。 + - nvs (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。 - - OTA 升级永远都不会更新 factory 分区中的程序。 - - 如果想节省 OTA 项目中的闪存，可以删除 factory 分区，使用 ota_0 分区替代。 -- ota_0 (0x10) ... ota_15 (0x1F) 便是 OTA 应用程序分区，引导程序根据 OTA 数据分区中的数据来决定从哪个 OTA 应用程序分区中加载程序。如果使用了 OTA 功能，那么至少需要包含两个 OTA 应用程序分区（ota_0 和 ota_1）。更多详细信息请参考 :doc:`OTA 文档 ` 。 -- test (0x2) 是工厂测试过程的保留子类型，当前 esp-idf 的引导程序并不支持这种子类型。 + - 用于存储每台设备的 PHY 校准数据（注意，并不是 PHY 初始化数据）。 + - 用于存储 Wi-Fi 数据（如果使用了 :cpp:func:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) ` 初始化函数）。 + - NVS API 还可以用于其他应用程序数据。 + - 强烈建议您应为 NVS 分区分配至少 0x3000 字节空间。 + - 如果使用 NVS API 存储大量数据，请增加 NVS 分区的大小（默认是 0x6000 字节）。 + - nvs_keys (4) 是 NVS 秘钥分区。详细信息，请参考 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 文档。 -data 子类型 -~~~~~~~~~~~~~ + - 用于存储加密密钥（如果启用了 `NVS 加密` 功能）。 + - 此分区应至少设定为 4096 字节。 -当类型被定义为 ``data`` 时，子类型字段可以指定为 ota (0)，phy (1)，nvs (2) 和 nvs_keys (4)。 - -- ota (0) 即 :ref:`OTA 数据分区 ` ，用于存储当前所选的 OTA 应用程序的信息。这个分区的大小需要设定为 0x2000。更多详细信息请参考 :doc:`OTA 文档 <../api-reference/system/ota>` 。 -- phy (1) 分区用于存放 PHY 初始化数据，这样就可以为每个设备（而不是在固件中）单独配置 PHY，而不是在固件中设定好PHY的初始化数据。 - - - 在默认的配置中并不使用 phy 分区， PHY 的初始化数据被编译进了应用程序中。因此可以从分区表中删除此分区以节省空间。 - - 如果要从此分区加载 PHY 初始化数据，请运行 ``make menuconfig`` 并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。您还需要将 PHY 的初始化数据手动烧写到闪存中，esp-idf 编译系统不会自动完成该操作。 -- nvs (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。 - - - NVS 用于存储每台设备的 PHY 校准数据（区别于 PHY 初始化数据）。 - - NVS 用于存储 WiFi 数据（如果使用了 :cpp:func:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) ` 初始化函数）。 - - NVS API 还可以用于其他应用程序数据。 - - 强烈建议您在项目中分配至少 0x3000 字节的空间给 NVS 分区。 - - 如果使用 NVS API 来存储大量数据，请增加 NVS 分区的大小（默认是 0x6000 字节）。 -- nvs_keys (4) 是 NVS 秘钥分区。详细信息请参考 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 文档。 - - - 它用于在启用 `NVS 加密` 功能的时候存储加密密钥。 - - 此分区的大小需要设定为 4096 字节（即最小的分区大小）。 - -其它数据子类型保留给未来的 esp-idf 使用。 +其它数据子类型已预留给 esp-idf 的未来使用。 Offset 和 Size 字段 ~~~~~~~~~~~~~~~~~~~ -没有指定偏移地址的分区会紧跟在前一个分区之后，如果第一个分区没有指定偏移地址，那么该分区会紧跟在分区表之后。 +分区若为指定偏移地址，则会紧跟着前一个分区之后开始。若此分区为首个分区，则将紧跟着分区表开始。 -应用程序分区的偏移地址必须要与 0x10000 (64K) 对齐，如果将偏移字段留空， ``gen_esp32part.py`` 工具会自动计算得到一个满足对齐要求的偏移地址。如果给应用程序的分区指定了未对齐的偏移地址，该工具会报错。 +app 分区的偏移地址必须要与 0x10000 (64K) 对齐，如果将偏移字段留空，``gen_esp32part.py`` 工具会自动计算得到一个满足对齐要求的偏移地址。如果 app 分区的偏移地址没有与 0x10000 (64K) 对齐，则该工具会报错。 -大小和偏移可以以十进制形式指定，也可以以 0x 为前缀的十六进制形式指定，或者以 K 或 M 作为单位指定（分别代表 1024 和 1024*1024 字节）。 +app 分区的大小和偏移地址可以采用十进制数、以 0x 为前缀的十六进制数，且支持 K 或 M 的倍数单位（分别代表 1024 和 1024*1024 字节）。 -如果希望分区表中的分区可以使用任何的起始偏移量 (:ref:`CONFIG_PARTITION_TABLE_OFFSET`)，请将分区表（CSV文件）中所有分区的偏移字段都留空。类似的，如果更改了分区表的偏移地址，则要注意所有留空的分区偏移可能会被更改到新的合适的位置，此时一些固定的偏移地址可能会与分区表冲突，从而导致错误。 +如果您希望允许分区表中的分区采用任意起始偏移量 (:ref:`CONFIG_PARTITION_TABLE_OFFSET`)，请将分区表（CSV 文件）中所有分区的偏移字段都留空。注意，此时，如果您更改了分区表中任意分区的偏移地址，则其他分区的偏移地址也会跟着改变。这种情况下，如果您之前还曾设定某个分区采用固定偏移地址，则可能造成分区表冲突，从而导致报错。 Flags 字段 ~~~~~~~~~~ -当前仅支持 ``encrypted`` 标记，如果标记字段被设置为了 ``encrypted``，那么该分区将会被加密（假如启用了 :doc:`闪存加密 ` 的功能）。 +当前仅支持 ``encrypted`` 标记。如果 Flags 字段设置为 ``encrypted``，且已启用 :doc:`Flash Encryption ` 功能，则该分区将会被加密。 -.. note:: ``app`` 分区始终会被加密，不管标记字段是否被设置。 +.. note:: + + ``app`` 分区始终会被加密，不管 Flags 字段是否设置。 生成二进制分区表 ---------------- -烧写到 ESP32 中的分区表是二进制格式的，而不是 CSV 文件本身。:component_file:`partition_table/gen_esp32part.py` 工具可以用来在 CSV 文件和二进制文件之间进行转换。 +烧写到 ESP32 中的分区表采用二进制格式，而不是 CSV 文件本身。此时，:component_file:`partition_table/gen_esp32part.py` 工具可以实现 CSV 和二进制文件之间的转换。 -如果您在 ``make menuconfig`` 中指定了 CSV 分区表的名称，然后执行 ``make partition_table`` 那么该转化过程会在编译的过程中自动完成。 +如果您在 ``make menuconfig`` 指定了分区表 CSV 文件的名称，然后执行 ``make partition_table``。这时，转换将在编译过程中自动完成。 -手动将 CSV 转换为 二进制文件： - -.. code:: bash +手动将 CSV 文件转换为二进制文件: python gen_esp32part.py input_partitions.csv binary_partitions.bin -将二进制文件转换为 CSV 文件： - -.. code:: bash +手动将二进制文件转换为 CSV 文件: python gen_esp32part.py binary_partitions.bin input_partitions.csv -在标准输出（stdout）上打印二进制分区表的内容（这正是执行 ``make partition_table`` 时显示的信息摘要）： - -.. code:: bash +在标准输出（stdout）上，打印二进制分区表的内容（在运行 ``make partition_table`` 时，我们正是这样打印上文展示的信息摘要的）: python gen_esp32part.py binary_partitions.bin MD5 校验和 ~~~~~~~~~~ -二进制格式的分区表中包含有基于分区表计算得到的 MD5 校验和，此校验和用于在程序引导阶段检查分区表的完整性。 +二进制格式的分区表中含有一个 MD5 校验和。这个 MD5 校验和是根据分区表内容计算的，可在设备启动阶段，用于验证分区表的完整性。 -可以通过 ``gen_esp32part.py`` 的 ``--disable-md5sum`` 选项或者 ``menuconfig`` 中的 :ref:`CONFIG_PARTITION_TABLE_MD5` 选项来禁止生成 MD5 校验和。当老版本的引导程序无法处理 MD5 校验和而失败，并且打印错误信息 ``invalid magic number 0xebeb`` 的时候就需要禁止 MD5 。 +注意，一些版本较老的 bootloader 无法支持 MD5 校验，如果发现 MD5 校验和则将报错 ``invalid magic number 0xebeb``。此时，用户可通过 ``gen_esp32part.py`` 的 ``--disable-md5sum`` 选项或者 ``menuconfig`` 的 :ref:`CONFIG_PARTITION_TABLE_MD5` 选项关闭 MD5 校验。 烧写分区表 ---------- @@ -182,6 +168,10 @@ MD5 校验和 - ``make partition_table-flash`` ：使用 esptool.py 工具烧写分区表。 - ``make flash`` ：会烧写所有内容，包括分区表。 -手动烧写的命令会作为 ``make partition_table`` 命令执行过程的一部分被打印在终端上。 +在执行 ``make partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。 -.. note:: 更新分区表的时候不会删除旧分区表存储的数据，您可以使用 ``make erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除整块闪存的内容。 +.. note:: + + 分区表的更新并不会擦除根据之前分区表存储的数据。此时，您可以使用 ``make erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。 + +.. _secure boot: security/secure-boot.rst