mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-20 00:36:01 -04:00
583 lines
31 KiB
ReStructuredText
583 lines
31 KiB
ReStructuredText
eFuse 管理器
|
||
=============
|
||
|
||
:link_to_translation:`en:[English]`
|
||
|
||
{IDF_TARGET_CODING_SCHEMES:default="Reed-Solomon", esp32="3/4 或 Repeat"}
|
||
|
||
|
||
简介
|
||
------------
|
||
|
||
eFuse 是一种微型的一次性可编程保险丝，可以通过“烧录”（即编程）将数据存储到 {IDF_TARGET_NAME} 中。eFuse 位组成不同的数据字段，用于系统参数（即 {IDF_TARGET_NAME} 的 ESP-IDF 使用的数据参数）或用户自定义参数。
|
||
|
||
eFuse 管理器组件中集合了多种工具和 API，可帮助定义、烧录和访问 eFuse 参数。常用的工具和 API 包括：
|
||
|
||
* 表格格式，用于在 CSV 文件中定义 eFuse 数据字段
|
||
* ``efuse_table_gen.py`` 工具，用于生成 CSV 文件指定的 eFuse 数据字段对应的 C 结构体
|
||
* 用于读/写 eFuse 数据字段的 C API 集合
|
||
|
||
eFuse Manager 与 ``idf.py``
|
||
---------------------------
|
||
|
||
``idf.py`` 通过 ``idf.py efuse-<subcommand>`` 命令为 eFuse 管理器提供了部分功能。本文档主要使用基于 ``idf.py`` 的命令，只有在涉及高级功能或罕见情况时，会使用基于 ``espefuse.py`` 的命令。要查看所有可用的命令，请运行 ``idf.py --help`` 并搜索以 ``efuse-`` 为前缀的命令。
|
||
|
||
硬件描述
|
||
--------------------
|
||
|
||
{IDF_TARGET_NAME} 有多个 eFuse，可用于存储系统参数和用户参数。每个 eFuse 都是一个一位字段，可以烧写为 1，之后就不能再恢复为 0。eFuse 位被分成了多个 256 位的块，每个块又被分成 8 个 32 位寄存器。部分块保留用于系统参数，其它块可用于用户参数。
|
||
|
||
如需了解更多内容，请参阅 *{IDF_TARGET_NAME} 技术参考手册* > *eFuse 控制器 (eFuse)* [`PDF <{IDF_TARGET_TRM_CN_URL}#efuse>`__]。
|
||
|
||
.. only:: esp32
|
||
|
||
{IDF_TARGET_NAME} 有 4 个 eFuse 块，每个块的大小为 256 位（并非所有位都可用于用户参数）：
|
||
|
||
* EFUSE_BLK0 完全用于系统用途；
|
||
* EFUSE_BLK1 用于 flash 加密密钥。如果不使用 flash 加密功能，此块也可以用于用户参数；
|
||
* EFUSE_BLK2 用于安全启动密钥。如果不使用安全启动功能，此块也可以用于用户参数；
|
||
* EFUSE_BLK3 可以部分保留，以存储自定义 MAC 地址，或者完全用于用户参数。请注意，一些位已经用于 ESP-IDF。
|
||
|
||
.. only:: not esp32 and not esp32c2
|
||
|
||
{IDF_TARGET_NAME} 有 11 个 eFuse 块，每个块的大小为 256 位（并非所有位都可用于用户参数）：
|
||
|
||
.. list::
|
||
|
||
* EFUSE_BLK0 完全用于系统参数；
|
||
* EFUSE_BLK1 完全用于系统参数；
|
||
* EFUSE_BLK2 完全用于系统参数；
|
||
* EFUSE_BLK3（也称为 EFUSE_BLK_USER_DATA）可用于用户参数；
|
||
* EFUSE_BLK4 至 EFUSE_BLK8（即 EFUSE_BLK_KEY0 至 EFUSE_BLK_KEY4）可以存储安全启动或 flash 加密的密钥。不使用这两个功能时，可以用于用户参数。
|
||
:SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK and SOC_ECDSA_SUPPORTED: * EFUSE_BLK9（即 EFUSE_BLK_KEY5）可用于任何用途，但由于硬件问题，不能用于 flash 加密或 ECDSA；
|
||
:SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK and not SOC_ECDSA_SUPPORTED: * EFUSE_BLK9（即 EFUSE_BLK_KEY5）可用于任何用途，但由于硬件问题，不能用于 flash 加密；
|
||
:not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK: * EFUSE_BLK9（即 EFUSE_BLK_KEY5）可用于存储安全启动或 flash 加密的密钥。不使用这两个功能时，可用于用户参数。
|
||
* EFUSE_BLK10（即 EFUSE_BLK_SYS_DATA_PART2）保留用于系统参数。
|
||
|
||
.. only:: esp32c2
|
||
|
||
{IDF_TARGET_NAME} 有 4 个 eFuse 块，每个块的大小为 256 位（并非所有位都可用于用户参数）：
|
||
|
||
* EFUSE_BLK0 完全用于系统参数
|
||
* EFUSE_BLK1 完全用于系统参数
|
||
* EFUSE_BLK2 完全用于系统参数
|
||
* EFUSE_BLK3（即 EFUSE_BLK_KEY0）可用于存储安全启动或 flash 加密的密钥。不使用这两个功能时，可用于用户参数。
|
||
|
||
定义 eFuse 字段
|
||
-----------------------
|
||
|
||
eFuse 字段通过 CSV 文件中特定格式的表格进行定义。通过这种格式，可定义任意长度和任意位数的 eFuse 字段。
|
||
|
||
另外，通过这种格式，可以结构化地定义由子字段组成的 eFuse 字段，这意味着一个父 eFuse 字段可能由占用相同 eFuse 位的多个子 eFuse 字段组成。
|
||
|
||
定义格式
|
||
^^^^^^^^^^^^^^^^^^
|
||
|
||
一般情况下，每个记录在定义表格中占据一行，每行包含以下值（也就是列）：
|
||
|
||
{IDF_TARGET_MAX_EFUSE_BLK:default = "EFUSE_BLK10", esp32 = "EFUSE_BLK3", esp32c2 = "EFUSE_BLK3"}
|
||
|
||
.. code-block:: none
|
||
|
||
# field_name, efuse_block(EFUSE_BLK0..{IDF_TARGET_MAX_EFUSE_BLK}), bit_start(0..255), bit_count(1..256), comment
|
||
|
||
- ``field_name``
|
||
|
||
- eFuse 字段的名称。
|
||
- 字段名称前会自动添加 ``ESP_EFUSE_`` 前缀，在 C 代码中，可通过此名称来访问 eFuse 字段。
|
||
- 对于每个 eFuse 字段，``field_name`` 必须唯一。
|
||
- 如果此值为空，说明该行与前一行合并。这样就可以定义任意位排序的 eFuse 字段（例如通用表中的 ``MAC_FACTORY`` 字段）。
|
||
- 使用 ``.`` 来定义一个子 eFuse 字段。详情请参考 :ref:`structured-efuse-fields`。
|
||
|
||
- ``efuse_block``
|
||
|
||
- eFuse 字段的块号。例如 EFUSE_BLK0 到 {IDF_TARGET_MAX_EFUSE_BLK}。
|
||
- 这一字段决定了 eFuse 字段在哪个块中。
|
||
|
||
- ``bit_start``
|
||
|
||
- eFuse 字段在块内的位置偏移（0 至 255 位）。
|
||
- ``bit_start`` 是可选项，可省略。
|
||
|
||
- 当省略时，如果上一条记录位于同一个 eFuse 块中，``bit_start`` 会被设置为上一条记录的 ``bit_start + bit_count``。
|
||
- 如果上一条记录位于不同的 eFuse 块中，则会报错。
|
||
|
||
- ``bit_count``
|
||
|
||
- eFuse 字段的大小，以位为单位（1 至 N）。
|
||
- ``bit_count`` 不能省略
|
||
- 如将其设置为 ``MAX_BLK_LEN``，则此 eFuse 字段为块中允许的最大 eFuse 字段大小。
|
||
|
||
.. only:: esp32
|
||
|
||
- ``MAX_BLK_LEN`` 考虑了 eFuse 的编码方案。
|
||
- 根据 :ref:`CONFIG_EFUSE_CODE_SCHEME_SELECTOR` 选择的编码方案，``MAX_BLK_LEN`` 可能是 256("None")、192 ("3/4") 或 128 ("REPEAT") 位。
|
||
|
||
- ``comment``
|
||
|
||
- 描述 eFuse 字段的注释。
|
||
- 此注释会逐字复制到 C 头文件中。
|
||
|
||
如果一个 eFuse 字段需要非顺序位序，那么该 eFuse 字段将占用多行。应在第一行的 ``field_name`` 处定该 eFuse 字段的名称，并且将其他行的 ``field_name`` 留空。这样就表明这些行属于同一个 eFuse 字段。
|
||
|
||
以下示例中定义了两个 eFuse 字段。首先定义非连续的 eFuse 字段 ``MAC_FACTORY``，然后定义了常规 eFuse 字段 ``MAC_FACTORY_CRC``：
|
||
|
||
.. code-block:: none
|
||
|
||
# Factory MAC address #
|
||
#######################
|
||
MAC_FACTORY, EFUSE_BLK0, 72, 8, Factory MAC addr [0]
|
||
, EFUSE_BLK0, 64, 8, Factory MAC addr [1]
|
||
, EFUSE_BLK0, 56, 8, Factory MAC addr [2]
|
||
, EFUSE_BLK0, 48, 8, Factory MAC addr [3]
|
||
, EFUSE_BLK0, 40, 8, Factory MAC addr [4]
|
||
, EFUSE_BLK0, 32, 8, Factory MAC addr [5]
|
||
MAC_FACTORY_CRC, EFUSE_BLK0, 80, 8, CRC8 for factory MAC address
|
||
|
||
在 C 代码中，可以通过 ``ESP_EFUSE_MAC_FACTORY`` 和 ``ESP_EFUSE_MAC_FACTORY_CRC`` 使用这两个字段。
|
||
|
||
.. _structured-efuse-fields:
|
||
|
||
结构化 eFuse 字段
|
||
-----------------------
|
||
|
||
通常情况下，一个 eFuse 字段代表一个特定的参数。不过，在某些情况下，一个 eFuse 字段可能由多个子字段组成，因此有必要隔离访问这些子字段。例如，如果一个 eFuse 字段包含一个浮点参数，则可以将浮点的符号、指数和尾数字段作为单独的 eFuse 字段进行访问。
|
||
|
||
因此，可以在 ``field_name`` 中使用 ``.`` 操作符，以结构化的方式定义 eFuse 字段。例如，``XX.YY.ZZ`` 定义了一个 eFuse 字段 ``ZZ``，它是 eFuse 字段 ``YY`` 的子字段，而 ``YY`` 又是 eFuse 字段 ``XX`` 的子字段。
|
||
|
||
以下示例展示了如何以定义结构化 eFuse 字段：
|
||
|
||
.. code-block:: none
|
||
|
||
WR_DIS, EFUSE_BLK0, 0, 32, Write protection
|
||
WR_DIS.RD_DIS, EFUSE_BLK0, 0, 1, Write protection for RD_DIS
|
||
WR_DIS.FIELD_1, EFUSE_BLK0, 1, 1, Write protection for FIELD_1
|
||
WR_DIS.FIELD_2, EFUSE_BLK0, 2, 4, Write protection for FIELD_2 (includes B1 and B2)
|
||
WR_DIS.FIELD_2.B1, EFUSE_BLK0, 2, 2, Write protection for FIELD_2.B1
|
||
WR_DIS.FIELD_2.B2, EFUSE_BLK0, 4, 2, Write protection for FIELD_2.B2
|
||
WR_DIS.FIELD_3, EFUSE_BLK0, 5, 1, Write protection for FIELD_3
|
||
WR_DIS.FIELD_3.ALIAS, EFUSE_BLK0, 5, 1, Write protection for FIELD_3 (just a alias for WR_DIS.FIELD_3)
|
||
WR_DIS.FIELD_4, EFUSE_BLK0, 7, 1, Write protection for FIELD_4
|
||
|
||
在上例中可以看出：
|
||
|
||
* ``WR_DIS`` 为父 eFuse 字段。其他所有行的 ``field_name`` 都具有 ``WR_DIS.`` 前缀，因此都是 ``WR_DIS`` 的子字段。
|
||
* 子字段必须与父字段使用相同的位。注意子字段和父字段的 ``bit_start`` 和 ``bit_count``：
|
||
|
||
* 子字段的位总是在其父字段范围内。例如，``WR_DIS.RD_DIS`` 和 ``WR_DIS.RD_DIS`` 占用了 ``WR_DIS`` 的第一位和第二位。
|
||
* 子字段使用的位不能重叠（子字段有别名时除外）。
|
||
|
||
* 可以将别名创建为子字段。例如，``WR_DIS.FIELD_3.ALIAS`` 既是 ``WR_DIS.FIELD_3`` 的子字段，又是别名，因为它们占用的位相同。
|
||
|
||
所有 eFuse 字段最终都会通过 ``efuse_table_gen.py`` 工具转换为 C 结构体。每个 C 结构体从 eFuse 字段的 ``field_name`` 中衍生出标识符，并用 ``_`` 替换所有的 ``.`` 符号。以 ``WR_DIS.RD_DIS`` 和 ``WR_DIS.FIELD_2.B1`` 为例，这两个 eFuse 字段用 C 语言分别表示为 ``ESP_EFUSE_WR_DIS_RD_DIS`` 和 ``ESP_EFUSE_WR_DIS_FIELD_2_B1``。
|
||
|
||
``efuse_table_gen.py`` 工具还会检查字段是否相互重叠并在字段范围内。如有违反，会生成以下错误：
|
||
|
||
.. code-block:: none
|
||
|
||
Field at USER_DATA, EFUSE_BLK3, 0, 256 intersected with SERIAL_NUMBER, EFUSE_BLK3, 0, 32
|
||
|
||
要解决此问题，可使用 ``USER_DATA.SERIAL_NUMBER``，让 ``SERIAL_NUMBER`` 成为 ``USER_DATA`` 的子字段。
|
||
|
||
.. code-block:: none
|
||
|
||
Field at FIELD, EFUSE_BLK3, 0, 50 out of range FIELD.MAJOR_NUMBER, EFUSE_BLK3, 60, 32
|
||
|
||
要解决此问题，可将 ``FIELD.MAJOR_NUMBER`` 的 ``bit_start`` 从 ``60`` 改为 ``0``，使 ``MAJOR_NUMBER`` 与 ``FIELD`` 重叠。
|
||
|
||
``efuse_table_gen.py`` 工具
|
||
---------------------------
|
||
|
||
``efuse_table_gen.py`` 工具能够从 CSV 文件生成 C 源文件，其中包含 CSV 文件中定义的 eFuse 字段的对应 C 结构体（类型为 :cpp:type:`esp_efuse_desc_t`）。此外，该工具还会在生成 C 源文件前对 CSV 文件进行检查，以确保：
|
||
|
||
- eFuse 字段的名称唯一
|
||
- eFuse 字段使用的位不重叠
|
||
|
||
如前所述，eFuse 字段可用于存储系统参数或用户参数。由于系统参数 eFuse 字段是 ESP-IDF 和 {IDF_TARGET_NAME} 的内在要求，这些 eFuse 字段被定义在 **通用** CSV 文件中，即 ``esp_efuse_table.csv`` 中，是 ESP-IDF 的一部分。对于用户参数 eFuse 字段，用户应在 **自定义** CSV 文件（如 ``esp_efuse_custom_table.csv``）中进行定义。
|
||
|
||
要从 **通用** CSV 文件生成 C 源文件，运行 ``idf.py efuse-common-table`` 或以下命令：
|
||
|
||
.. code-block:: bash
|
||
|
||
cd $IDF_PATH/components/efuse/
|
||
./efuse_table_gen.py --idf_target {IDF_TARGET_PATH_NAME} {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv
|
||
|
||
然后，就会在路径 ``$IDF_PATH/components/efuse/{IDF_TARGET_PATH_NAME}`` 中生成以下 C 源文件/头文件：
|
||
|
||
* ``esp_efuse_table.c`` 文件，包含系统参数 eFuse 字段的 C 结构体。
|
||
* ``esp_efuse_table.h`` 文件，位于 ``include`` 文件夹。应用程序可包含该头文件，以使用上述 C 结构体。
|
||
|
||
要使用 **自定义** CSV 文件生成 C 源文件，请运行 ``idf.py efuse-custom-table`` 或以下命令：
|
||
|
||
.. code-block:: bash
|
||
|
||
cd $IDF_PATH/components/efuse/
|
||
./efuse_table_gen.py --idf_target {IDF_TARGET_PATH_NAME} {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv
|
||
|
||
然后在 ``PROJECT_PATH/main`` 路径下生成 C 源/头文件：
|
||
|
||
* ``esp_efuse_custom_table.c`` 文件，包含用户参数 eFuse 字段的 C 结构体。
|
||
* ``esp_efuse_custom_table.h`` 文件，位于 ``include`` 文件夹。应用程序可包含该头文件，以使用上述 C 结构体。
|
||
|
||
要使用生成的字段，需添加以下头文件：
|
||
|
||
.. code-block:: c
|
||
|
||
#include "esp_efuse.h"
|
||
#include "esp_efuse_table.h" // 或 "esp_efuse_custom_table.h"
|
||
|
||
|
||
支持的编码方式
|
||
-----------------------
|
||
|
||
eFuse 支持各种编码方式，能够检测或纠正错误，保护 eFuse 数据不受损坏。
|
||
|
||
.. only:: esp32
|
||
|
||
{IDF_TARGET_NAME} 支持以下 eFuse 编码方式：
|
||
|
||
* ``非编码`` 方式（值为 0），即不采用编码方式。
|
||
* ``3/4 编码`` 方式（值为 1）。
|
||
* ``重复编码`` 方式（值为 2）。不完全受到 IDF 支持，不推荐使用。
|
||
|
||
以上编码方案对每个 eFuse 块进行单独编码。此外，只有 EFUSE_BLK1、EFUSE_BLK2 和 EFUSE_BLK3 将被编码，这意味着 EUSE_BLK0 始终采用 ``非编码`` 方式。
|
||
|
||
编码方案要求将 eFuse 块中的某些位用作开销。因此，采用编码方案后，每个 eFuse 块的 256 位中只有一部分可用于 eFuse 字段。
|
||
|
||
* ``非编码``：256 位
|
||
* ``3/4 编码``：192 位
|
||
* ``重复编码``：128 位
|
||
|
||
当使用一种编码方式时，可以写入的有效载荷长度是有限的。如需了解更多内容，请参考 *{IDF_TARGET_NAME} 技术参考手册* > *章节 20 eFuse 控制器 (eFuse)* [`PDF <{IDF_TARGET_TRM_CN_URL}#efuse>`__] > *章节 20.3.1.3 系统参数 coding_scheme*。
|
||
|
||
通过以下步骤查看芯片的编码方式：
|
||
|
||
* 运行 ``idf.py efuse-summary`` 命令。
|
||
* 在烧录期间从 ``esptool`` 应用程序日志中查看。
|
||
* 在应用程序中调用 :cpp:func:`esp_efuse_get_coding_scheme` 函数查看 EFUSE_BLK3 块的编码方式。
|
||
|
||
CSV 文件中指定的 eFuse 字段必须始终符合芯片使用的 eFuse 编码方案。可以通过 :ref:`CONFIG_EFUSE_CODE_SCHEME_SELECTOR` 选择 CSV 文件使用的编码方案。生成源文件时，如果 CSV 文件中的内容不符合编码方案，则会显示错误信息。在这种情况下，必须调整错误行的 ``bit_start`` 和 ``bit_count``，以满足所选编码方案的限制。
|
||
|
||
.. note::
|
||
|
||
更改编码方式后，运行 ``efuse_common_table`` 和 ``efuse_custom_table`` 命令以查看采用新编码方式的 CSV 表格。
|
||
|
||
如果程序是用 ``非编码`` 方式编译的，而芯片中使用的是 ``3/4 编码`` 方式，那么调用 eFuse API 时可能会出现 ``ESP_ERR_CODING`` 错误（字段超出块边界）。如果字段符合新的块边界，则 API 会正常运行。
|
||
|
||
``非编码`` 方式
|
||
^^^^^^^^^^^^^^^^^
|
||
|
||
``非编码`` 方式表示不使用编码方案，因此 eFuse 数据块的 256 位都可以使用。不过，这中方式无法防止 eFuse 位的数据损坏。
|
||
|
||
``3/4 编码`` 方式
|
||
^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
``3/4 编码`` 方式会限制写入一个编码单元的位数。长度为 256 位的块被划分为 4 个编码单元，每个编码单元包含 6 字节的有用数据和 2 字节的服务数据。这 2 字节的服务数据中存储了前 6 个数据字节的校验和。
|
||
|
||
由于要计算每个编码单元的校验和，写入过程必须根据不同的编码单元进行划分。在这种情况下，通过多个写入操作分别烧录各 eFuse 位（ ``非编码`` 方式的烧录方法）的常规做法将不再适用，必须一次性同时烧写该编码单元的 eFuse 字段数据和校验和。这就是所谓的批量写入模式。
|
||
|
||
由于采用批量写入模式，一个编码单元只能写入一次，禁止在同一编码单元重复写入。这意味着，在运行时写入的编码单元中只能包含一个 eFuse 字段。但是，如果事先通过 CSV 文件指定了编码单元的 eFuse 字段，或通过 :cpp:func:`esp_efuse_write_block` 写入编码单元的 eFuse 字段，那么一个编码单元中仍可包含多个 eFuse 字段。
|
||
|
||
|
||
``重复编码`` 方式
|
||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||
``重复编码`` 方式只是简单重复每个 eFuse 位，不会像 ``3/4 编码`` 方式那样受到批量写入模式的限制。不过，这样做会产生很大的开销，每个 eFuse 块中只有 128 个位可用。
|
||
|
||
.. only:: not esp32
|
||
|
||
{IDF_TARGET_NAME} 不支持选择编码方式，会自动将以下编码方案应用于各 eFuse 块：
|
||
|
||
* ``非编码`` 方式，应用于 EFUSE_BLK0。
|
||
* ``RS 编码`` 方式。应用于 EFUSE_BLK1 - {IDF_TARGET_MAX_EFUSE_BLK}。
|
||
|
||
``非编码`` 方式
|
||
^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
``非编码`` 方式会自动应用于 EFUSE_BLK0。此方式不涉及任何编码，只是在硬件中维护 EFUSE_BLK0 的四个备份，因此，每个位实际存储四次，EFUSE_BLK0 也可以多次写入。
|
||
|
||
该方案由硬件自动应用，软件中不可见。
|
||
|
||
``RS 编码`` 方式
|
||
^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* ``RS 编码`` 方式，即 Reed-Solomon 编码方式，会自动应用于 EFUSE_BLK1 至 {IDF_TARGET_MAX_EFUSE_BLK}。该编码方式支持至多 6 个字节的自动纠错。
|
||
|
||
软件使用 ``RS(44, 32)`` 对 32 字节的 EFUSE_BLKx 进行编码，生成一个 12 字节的校验码，然后将 EFUSE_BLKx 和校验码同时烧录到 eFuse 中。
|
||
|
||
在回读 eFuse 块时，eFuse 控制器会对 ``RS 编码`` 进行自动解码和纠错。因为 ``RS`` 校验码是根据整个 256 位 eFuse 块生成的，所以每个块只能写入一次，且必须采用批量写入模式。
|
||
|
||
批量写入模式
|
||
^^^^^^^^^^^^
|
||
|
||
如需在运行时写入 eFuse 字段，可能要采用批量写入模式，具体取决于 eFuse 块使用的编码方案。批量写入模式的使用步骤如下：
|
||
|
||
#. 调用 :cpp:func:`esp_efuse_batch_write_begin` 启用批量写入模式。
|
||
#. 使用各 ``esp_efuse_write_...`` 函数，按照常规方法写入 eFuse 字段。
|
||
#. 完成所有写入后，调用 :cpp:func:`esp_efuse_batch_write_commit` 将准备好的数据烧录到 eFuse 块中。
|
||
|
||
.. warning::
|
||
|
||
如果 eFuse 块中已经存在通过 ``{IDF_TARGET_CODING_SCHEMES}`` 编码方案预先写入的数据，则无法在不破坏先前数据校验和/校验符号的情况下，写入额外的内容（即使需要写入的位为空）。
|
||
|
||
先前的校验和/校验符号会被新的校验和/校验符号覆盖，并完全销毁。（但不会损坏有效负载 eFuse）。
|
||
|
||
如发现在 CUSTOM_MAC、SPI_PAD_CONFIG_HD、SPI_PAD_CONFIG_CS 等块中存在预写入数据，请联系乐鑫获取所需的预烧录 eFuse。
|
||
|
||
仅供测试（不推荐）：可以忽略或抑制违反编码方式数据的错误，从而在 eFuse 块中烧录必要的位。
|
||
|
||
.. _efuse_API:
|
||
|
||
eFuse API
|
||
---------
|
||
|
||
可以通过指向描述结构的指针来访问 eFuse 字段。API 函数可以实现一些基本操作：
|
||
|
||
* :cpp:func:`esp_efuse_read_field_blob` - 返回读取的 eFuse 位的数组。
|
||
* :cpp:func:`esp_efuse_read_field_cnt` - 返回烧写为 “1” 的位的数量。
|
||
* :cpp:func:`esp_efuse_write_field_blob` - 写入一个数组。
|
||
* :cpp:func:`esp_efuse_write_field_cnt` - 将所需数量的位写为 “1”。
|
||
* :cpp:func:`esp_efuse_get_field_size` - 返回字段的位数。
|
||
* :cpp:func:`esp_efuse_read_reg` - 返回 eFuse 寄存器的值。
|
||
* :cpp:func:`esp_efuse_write_reg` - 将值写入 eFuse 寄存器。
|
||
* :cpp:func:`esp_efuse_get_coding_scheme` - 返回块的 eFuse 编码方式。
|
||
* :cpp:func:`esp_efuse_read_block` - 从指定偏移位置开始读取指定大小的 eFuse 块中的密钥。
|
||
* :cpp:func:`esp_efuse_write_block` - 从指定偏移位置开始将密钥写入指定大小的 eFuse 块中。
|
||
* :cpp:func:`esp_efuse_batch_write_begin` - 设置字段写入的批处理模式。
|
||
* :cpp:func:`esp_efuse_batch_write_commit` - 写入所有为批处理写入模式准备的数据，并重置批处理写入模式。
|
||
* :cpp:func:`esp_efuse_batch_write_cancel` - 重置批处理写入模式和准备的数据。
|
||
* :cpp:func:`esp_efuse_get_key_dis_read` - 返回密钥块的读保护状态。
|
||
* :cpp:func:`esp_efuse_set_key_dis_read` - 设置密钥块的读保护状态。
|
||
* :cpp:func:`esp_efuse_get_key_dis_write` - 返回密钥块的写保护状态。
|
||
* :cpp:func:`esp_efuse_set_key_dis_write` - 设置密钥块的写保护状态。
|
||
* :cpp:func:`esp_efuse_get_key_purpose` - 返回 eFuse 密钥块当前设置的用途。
|
||
* :cpp:func:`esp_efuse_write_key` - 将一块密钥数据烧写到一个 eFuse 块。
|
||
* :cpp:func:`esp_efuse_write_keys` - 将密钥烧写到未使用的 eFuse 块。
|
||
* :cpp:func:`esp_efuse_find_purpose` - 查找设置为特定用途的密钥块。
|
||
* :cpp:func:`esp_efuse_get_keypurpose_dis_write` - 返回 eFuse 密钥块的密钥用途字段的写保护状态（对于 esp32 始终为 true）。
|
||
* :cpp:func:`esp_efuse_key_block_unused` - 如果密钥块未使用，则返回 true，否则返回 false。
|
||
* :cpp:func:`esp_efuse_destroy_block` - 销毁此 eFuse 块中的数据。该函数有两个作用：(1) 如果未开启写保护，则将不为 1 的位都烧写为 1；(2) 如果未开启读保护，则开启读保护。
|
||
|
||
经常使用的字段有专门的函数可供使用，例如 :cpp:func:`esp_efuse_get_pkg_ver`。
|
||
|
||
.. only:: SOC_EFUSE_KEY_PURPOSE_FIELD or SOC_SUPPORT_SECURE_BOOT_REVOKE_KEY
|
||
|
||
eFuse 密钥 API
|
||
------------------
|
||
|
||
.. only:: SOC_EFUSE_KEY_PURPOSE_FIELD
|
||
|
||
EFUSE_BLK_KEY0 - EFUSE_BLK_KEY5 可以保存 6 个长度为 256 位的密钥。每个密钥都有一个 ``ESP_EFUSE_KEY_PURPOSE_x`` 字段说明密钥用途。用途字段描述见 :cpp:type:`esp_efuse_purpose_t`。
|
||
|
||
类似 ``ESP_EFUSE_KEY_PURPOSE_XTS_AES_...`` 的用途用于 flash 加密。
|
||
|
||
类似 ``ESP_EFUSE_KEY_PURPOSE_SECURE_BOOT_DIGEST...`` 的用途用于安全启动。
|
||
|
||
一些 eFuse API 可用于处理密钥状态：
|
||
|
||
* :cpp:func:`esp_efuse_get_purpose_field` - 返回一个指向 eFuse 密钥块的密钥用途的指针。
|
||
* :cpp:func:`esp_efuse_get_key` - 返回一个指向密钥块的指针。
|
||
* :cpp:func:`esp_efuse_set_key_purpose` - 为一个 eFuse 密钥块设置密钥用途。
|
||
* :cpp:func:`esp_efuse_set_keypurpose_dis_write` - 为 eFuse 密钥块的密钥用途字段设置写保护。
|
||
* :cpp:func:`esp_efuse_find_unused_key_block` - 搜索未使用的密钥块并返回找到的第一个结果。
|
||
* :cpp:func:`esp_efuse_count_unused_key_blocks` - 返回 EFUSE_BLK_KEY0..EFUSE_BLK_KEY_MAX 范围中未使用的 eFuse 密钥块数量。
|
||
|
||
.. only:: SOC_SUPPORT_SECURE_BOOT_REVOKE_KEY
|
||
|
||
* :cpp:func:`esp_efuse_get_digest_revoke` - 返回安全启动公钥摘要撤销位的状态。
|
||
* :cpp:func:`esp_efuse_set_digest_revoke` - 设置安全启动公钥摘要撤销位。
|
||
* :cpp:func:`esp_efuse_get_write_protect_of_digest_revoke` - 返回安全启动公钥摘要撤销位的写保护。
|
||
* :cpp:func:`esp_efuse_set_write_protect_of_digest_revoke` - 设置安全启动公钥摘要撤销位的写保护。
|
||
|
||
|
||
如何添加新字段
|
||
----------------------
|
||
|
||
1. 为新字段查找空闲位。运行 ``idf.py show-efuse-table`` 查看 ``esp_efuse_table.csv`` 文件，或运行以下命令：
|
||
|
||
.. include:: inc/show-efuse-table_{IDF_TARGET_NAME}.rst
|
||
|
||
不包含在方括号中的位是空闲的（一些位是乐鑫的保留位）。已检查所有字段的位重叠情况。
|
||
|
||
要在现有字段中添加子字段，请参考 :ref:`structured-efuse-fields`。例如，可使用 ``.`` 操作符将字段 ``SERIAL_NUMBER``、``MODEL_NUMBER`` 和 ``HARDWARE_REV`` 添加到现有的 ``USER_DATA`` 字段中，如下所示：
|
||
|
||
.. code-block:: none
|
||
|
||
USER_DATA.SERIAL_NUMBER, EFUSE_BLK3, 0, 32,
|
||
USER_DATA.MODEL_NUMBER, EFUSE_BLK3, 32, 10,
|
||
USER_DATA.HARDWARE_REV, EFUSE_BLK3, 42, 10,
|
||
|
||
通常按照如下步骤添加新的 eFuse 字段：
|
||
|
||
#. 在 CSV 文件中为每个 eFuse 字段添加一行记录。
|
||
#. 运行 ``show_efuse_table`` 命令检查 eFuse 表。
|
||
#. 如要生成源文件，运行 ``efuse_common_table`` 或 ``efuse_custom_table`` 命令。
|
||
|
||
如果遇到 ``intersects with`` 或 ``out of range`` 等错误，请参阅 :ref:`structured-efuse-fields` 中的解决办法。
|
||
|
||
位序
|
||
----
|
||
|
||
eFuse 位序采取小字节序（参见下方示例），这说明 eFuse 位按照从 LSB 到 MSB 的顺序进行读写：
|
||
|
||
.. code-block:: none
|
||
|
||
$ idf.py efuse-dump
|
||
|
||
USER_DATA (BLOCK3 ) [3 ] read_regs: 03020100 07060504 0B0A0908 0F0E0D0C 13121111 17161514 1B1A1918 1F1E1D1C
|
||
BLOCK4 (BLOCK4 ) [4 ] read_regs: 03020100 07060504 0B0A0908 0F0E0D0C 13121111 17161514 1B1A1918 1F1E1D1C
|
||
|
||
where is the register representation:
|
||
|
||
EFUSE_RD_USR_DATA0_REG = 0x03020100
|
||
EFUSE_RD_USR_DATA1_REG = 0x07060504
|
||
EFUSE_RD_USR_DATA2_REG = 0x0B0A0908
|
||
EFUSE_RD_USR_DATA3_REG = 0x0F0E0D0C
|
||
EFUSE_RD_USR_DATA4_REG = 0x13121111
|
||
EFUSE_RD_USR_DATA5_REG = 0x17161514
|
||
EFUSE_RD_USR_DATA6_REG = 0x1B1A1918
|
||
EFUSE_RD_USR_DATA7_REG = 0x1F1E1D1C
|
||
|
||
where is the byte representation:
|
||
|
||
byte[0] = 0x00, byte[1] = 0x01, ... byte[3] = 0x03, byte[4] = 0x04, ..., byte[31] = 0x1F
|
||
|
||
例如，CSV 文件描述了 ``USER_DATA`` 字段，该字段占用 256 位，即一个完整的块。
|
||
|
||
.. code-block:: none
|
||
|
||
USER_DATA, EFUSE_BLK3, 0, 256, User data
|
||
USER_DATA.FIELD1, EFUSE_BLK3, 16, 16, Field1
|
||
|
||
ID, EFUSE_BLK4, 8, 3, ID bit[0..2]
|
||
, EFUSE_BLK4, 16, 2, ID bit[3..4]
|
||
, EFUSE_BLK4, 32, 3, ID bit[5..7]
|
||
|
||
因此，读取如上 eFuse ``USER_DATA`` 块会得到以下结果：
|
||
|
||
.. code-block:: c
|
||
|
||
uint8_t buf[32] = { 0 };
|
||
esp_efuse_read_field_blob(ESP_EFUSE_USER_DATA, &buf, sizeof(buf) * 8);
|
||
// buf[0] = 0x00, buf[1] = 0x01, ... buf[31] = 0x1F
|
||
|
||
uint32_t field1 = 0;
|
||
size_t field1_size = ESP_EFUSE_USER_DATA[0]->bit_count; // 可以用于这种情况，因为它只包含一个条目
|
||
esp_efuse_read_field_blob(ESP_EFUSE_USER_DATA, &field1, field1_size);
|
||
// field1 = 0x0302
|
||
|
||
uint32_t field1_1 = 0;
|
||
esp_efuse_read_field_blob(ESP_EFUSE_USER_DATA, &field1_1, 2); // 只读取前两位
|
||
// field1 = 0x0002
|
||
|
||
uint8_t id = 0;
|
||
size_t id_size = esp_efuse_get_field_size(ESP_EFUSE_ID); // 返回 6
|
||
// size_t id_size = ESP_EFUSE_USER_DATA[0]->bit_count; // 不能用于这种情况，因为其中包含 3 个条目，会返回 3 而不是 6
|
||
esp_efuse_read_field_blob(ESP_EFUSE_ID, &id, id_size);
|
||
// id = 0x91
|
||
// b'100 10 001
|
||
// [3] [2] [3]
|
||
|
||
uint8_t id_1 = 0;
|
||
esp_efuse_read_field_blob(ESP_EFUSE_ID, &id_1, 3);
|
||
// id = 0x01
|
||
// b'001
|
||
|
||
|
||
在构建阶段获取 eFuse 状态
|
||
-------------------------
|
||
|
||
要在项目的构建阶段获取 eFuse 状态，可以使用以下两个 CMake 函数：
|
||
|
||
* ``espefuse_get_json_summary()`` - 调用 ``espefuse.py summary --format json`` 命令并返回一个 JSON 字符串（该字符串不存储在文件中）。
|
||
* ``espefuse_get_efuse()`` - 在此 JSON 字符串中找到给定的 eFuse 名称并返回其属性。
|
||
|
||
该 JSON 字符串具有以下属性：
|
||
|
||
.. code-block:: json
|
||
|
||
{
|
||
"MAC": {
|
||
"bit_len": 48,
|
||
"block": 0,
|
||
"category": "identity",
|
||
"description": "Factory MAC Address",
|
||
"efuse_type": "bytes:6",
|
||
"name": "MAC",
|
||
"pos": 0,
|
||
"readable": true,
|
||
"value": "94:b9:7e:5a:6e:58 (CRC 0xe2 OK)",
|
||
"word": 1,
|
||
"writeable": true
|
||
},
|
||
}
|
||
|
||
可以通过项目顶层目录下的 ``CMakeLists.txt`` (:example_file:`system/efuse/CMakeLists.txt`) 来使用这些函数：
|
||
|
||
.. code-block:: cmake
|
||
|
||
# ...
|
||
project(hello_world)
|
||
|
||
espefuse_get_json_summary(efuse_json)
|
||
espefuse_get_efuse(ret_data ${efuse_json} "MAC" "value")
|
||
message("MAC:" ${ret_data})
|
||
|
||
``value`` 属性的格式与 ``espefuse.py summary`` 或 ``idf.py efuse-summary`` 中显示的格式相同。
|
||
|
||
.. code-block:: none
|
||
|
||
MAC:94:b9:7e:5a:6e:58 (CRC 0xe2 OK)
|
||
|
||
在示例测试 :example_file:`system/efuse/CMakeLists.txt` 中，添加了一个自定义目标 ``efuse-filter``。这样，不仅在项目构建阶段，而在任何时候都可以运行 ``idf.py efuse-filter`` 命令读取所需的 eFuse（在 ``efuse_names`` 列表中指定）。
|
||
|
||
调试 eFuse & 单元测试
|
||
------------------------
|
||
|
||
.. _virtual-efuses:
|
||
|
||
虚拟 eFuse
|
||
^^^^^^^^^^^^^^
|
||
|
||
Kconfig 选项 :ref:`CONFIG_EFUSE_VIRTUAL` 在 eFuse 管理器中虚拟了 eFuse 值，因此写入操作是仿真操作，不会永久更改 eFuse 值。这对于应用程序调试和单元测试很有用处。
|
||
|
||
在启动时，eFuses 被复制到 RAM 中。此时，所有的 eFuse 操作（读和写）都是通过 RAM 执行，而不是通过实际的 eFuse 寄存器执行的。
|
||
|
||
除了 :ref:`CONFIG_EFUSE_VIRTUAL` 选项外，还有 :ref:`CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH` 选项，该选项可将 eFuse 保留在 flash 内存中。要使用此模式，partition_table 在 ``partition.csv`` 中包含名为 ``efuse`` 的分区：
|
||
|
||
.. code-block:: none
|
||
|
||
efuse_em, data, efuse, , 0x2000,
|
||
|
||
在启动阶段，eFuse 会从 flash 中复制到 RAM 中，在 flash 为空的情况下，则从实际的 eFuse 复制到 RAM 中，然后更新 flash。此选项能够在重启后仍然保留 eFuse，用于测试安全启动和 flash 加密功能。
|
||
|
||
flash 加密测试
|
||
""""""""""""""
|
||
|
||
flash 加密是一项硬件功能，需要物理烧录 eFuse ``key`` 和 ``FLASH_CRYPT_CNT``。如果 flash 加密实际未启用，那么启用 :ref:`CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH` 选项只是提供了测试的可能性，而不会加密 flash 中的任何内容，即使日志中显示了加密操作。
|
||
|
||
为此，可使用 :cpp:func:`bootloader_flash_write` 函数。但是，如果运行应用程序时芯片已启用 flash 加密，或者以 :ref:`CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH` 选项创建了启动加载程序，则 flash 加密/解密操作会正常进行。这意味着数据写入加密 flash 分区时被加密，从加密分区读取时被解密。
|
||
|
||
``espefuse.py``
|
||
^^^^^^^^^^^^^^^
|
||
|
||
esptool 中包含一个用于读取/写入 {IDF_TARGET_NAME} eFuse 位的有用工具： `espefuse.py <https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/espefuse/index.html>`_。
|
||
|
||
``idf.py`` 命令也可以直接提供上述工具的部分功能。例如，运行 ``idf.py efuse-summary`` 命令，效果等同于 ``espefuse.py summary``。
|
||
|
||
.. include:: inc/espefuse_summary_{IDF_TARGET_NAME}.rst
|
||
|
||
获取所有 eFuse 寄存器的转储数据。
|
||
|
||
.. include:: inc/espefuse_summary_{IDF_TARGET_NAME}_dump.rst
|
||
|
||
应用示例
|
||
-----------------
|
||
|
||
- :example:`system/efuse` 演示了如何在 {IDF_TARGET_NAME} 上使用 eFuse API，展示了从通用和自定义 eFuse 表中读取和写入字段的操作，并解释了虚拟 eFuse 在调试中的用途。
|
||
|
||
API 参考
|
||
----------------
|
||
|
||
.. include-build-file:: inc/esp_efuse_chip.inc
|
||
.. include-build-file:: inc/esp_efuse.inc
|