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-`` 命令为 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 `_。 ``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