ESP32-H4 eFuse 全字段速查：解读 idf.py efuse-summary 输出与 H4 芯片 eFuse 布局-开发者社区

ESP32-H4 eFuse 全字段速查：解读 idf.py efuse-summary 输出与 H4 芯片 eFuse 布局

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf

ESP32-H4 芯片内部的 eFuse 是一组一次性可编程（OTP）的熔丝位，用于固化 MAC 地址、芯片版本、Secure Boot / Flash 加密密钥、调试口禁用策略、电源管理参数等关键信息。本文基于 ESP-IDF 官方文档中的 ESP32-H4efuse-summary命令输出样例，逐字段完整解读 Config、Flash、Identity、Jtag、Mac、Security、Usb、Vdd、Wdt 九大类 eFuse 的取值含义，并结合仓库中的 eFuse 字段定义表与文档，帮助你在量产烧录、安全部署与现场诊断时快速读懂并正确操作 H4 芯片的 eFuse。

1. 命令入口：如何得到这份 eFuse 摘要

摘要输出由esptool套件中的espefuse工具生成，idf.py将其中常用功能直接暴露为子命令：

idf.py -p PORT efuse-summary

该命令与espefuse summary --chip esp32h4等价（见 eFuse Manager 文档中 "espefuse" 小节）。执行后会输出=== Run "summary" command ===标题，随后按类别列出每个字段：

EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value)

各行末尾的R/W表示该字段当前可读、可写；(Hex Value)列给出原始位值。本文以下内容即对该样例输出（存档于 espefuse_summary_ESP32-H4.rst）的完整继承与逐字段解读。

若需要查看全部 eFuse 块的原始 32 位寄存器转储，使用：

idf.py -p PORT efuse-dump

H4 的样例输出（见 espefuse_summary_ESP32-H4_dump.rst）如下，展示了 11 个块各自的全零状态与块名：

BLOCK0 ( ) [0 ] dump: 00000000 00000000 00000000 00000000 00000000 00000000 MAC_SPI_8M_0 (BLOCK1 ) [1 ] dump: a0ed57cc 000030ed 00000000 00040000 00000000 00000000 BLOCK_SYS_DATA (BLOCK2 ) [2 ] dump: 00000000 ...（共 8 组 32 位） BLOCK_USR_DATA (BLOCK3 ) [3 ] dump: 00000000 ... BLOCK_KEY0..KEY5 (BLOCK4-BLOCK9) [4-9] dump: 00000000 ... BLOCK_SYS_DATA2 (BLOCK10 ) [10] dump: 00000000 ...

从 eFuse Manager 文档的 "Hardware Description" 小节可知，H4 与多数新一代 Espressif 芯片一致，拥有 11 个 256 位 eFuse 块（每块再分为 8 个 32 位寄存器）：

块	用途
EFUSE_BLK0	系统参数（配置、安全、JTAG、USB 等控制位）
EFUSE_BLK1	系统参数（MAC、版本、电源调节等）
EFUSE_BLK2	系统参数（Unique ID、ADC 校准等）
EFUSE_BLK3（EFUSE_BLK_USER_DATA）	用户参数（含自定义 MAC 区段）
EFUSE_BLK4~BLK9（EFUSE_BLK_KEY0~KEY5）	存放 Secure Boot / Flash 加密等密钥；若均未使用可作用户数据
EFUSE_BLK10（EFUSE_BLK_SYS_DATA_PART2）	系统保留

每个 eFuse 位烧成 1 后不可逆，因此量产烧录前务必先用efuse-summary/efuse-dump确认目标位当前状态。

2. 字段定义来源：从 CSV 表格到 C 代码

H4 的全部 eFuse 字段（块号、位偏移、位宽、描述）定义在 CSV 表格 esp_efuse_table.csv 中，格式为：

field_name, efuse_block(EFUSE_BLK0..EFUSE_BLK10), bit_start(0..255), bit_count(1..256), comment

该表格由 efuse_table_gen.py 生成 C 结构体（字段枚举与 esp_efuse_fields.c），前缀ESP_EFUSE_会自动加入字段名，供 C APIesp_efuse_read_field()/esp_efuse_write_field()使用。CSV 文件头部注释也提示：修改表格后需手动执行idf.py efuse-common-table重新生成源码再整体编译。下表各小节的"位偏移"信息即取自该 CSV，可与摘要输出对照，帮助你在二进制层面定位字段。

3. Config fuses：系统配置类字段

摘要输出中Config fuses:分组的完整字段（示例值来自文档样例，H4 出厂默认全零/全关）：

字段	块	位偏移/位宽（CSV）	含义	示例值
WR_DIS	BLOCK0	0 / 32	逐位禁止对相关 eFuse 的再次烧写（永久写保护），每位对应一个受保护字段	0，R/W
RD_DIS	BLOCK0	32 / 7	禁止读取 BLOCK4~BLOCK10（即 6 个 KEY 块 + SYS_DATA2）	0，R/W
DIS_TWAI	BLOCK0	43 / 1	永久禁用 TWAI（CAN）外设。1: 禁用，0: 使能	False，R/W
PVT_GLITCH_EN	BLOCK0	50 / 1	使能 PVT 电源浪涌监控功能	False，R/W
PVT_GLITCH_MODE	BLOCK0	52 / 2	配置浪涌监控模式	0，R/W
DIS_CORE1	BLOCK0	54 / 1	禁用 CPU Core1（H4 为双核 RISC-V，烧 1 后芯片永久变单核）	False，R/W
ECC_FORCE_CONST_TIME	BLOCK0	99 / 1	强制 ECC 以常数时间模式运算（安全加固）	False，R/W
KM_DISABLE_DEPLOY_MODE	BLOCK0	103 / 5	Key Manager 各密钥（ECDSA/XTS-AES/HMAC/DS）的新部署模式禁用位	0，R/W
KM_RND_SWITCH_CYCLE	BLOCK0	108 / 2	Key Manager 随机数切换周期：0 由寄存器控制，1/2/3 对应 8/16/32 个时钟周期	0，R/W
KM_DEPLOY_ONLY_ONCE	BLOCK0	110 / 5	对应密钥是否只允许部署一次（按 ECDSA/XTS-AES/HMAC/DS 分位）	0，R/W
DIS_DIRECT_BOOT	BLOCK0	128 / 1	禁用 direct boot（直接启动）模式	False，R/W
UART_PRINT_CONTROL	BLOCK0	132 / 2	UART 打印控制：00 强制开；01 GPIO8 低电平复位时开；10 GPIO8 高电平复位时开；11 强制关	0，R/W
HUK_GEN_STATE	BLOCK0	151 / 5	HUK（硬件独有密钥）生成模式有效性，按"1 的个数为偶数"判定有效	0，R/W
DCDC_CCM_EN	BLOCK0	183 / 1	将 DCDC 切换到 CCM（连续导通）模式	False，R/W
PVT_LIMIT	BLOCK1	64 / 16	电源浪涌监控阈值	0，R/W
PVT_CELL_SELECT	BLOCK1	80 / 7	电源浪涌监控的 PVT 单元选择	0，R/W
PVT_PUMP_LIMIT	BLOCK1	87 / 8	电荷泵电压监控上限	0，R/W
PUMP_DRV	BLOCK1	96 / 4	电荷泵电压增益	0，R/W
HYS_EN_PAD	BLOCK1	102 / 1	使能对应 PAD 的回差（hysteresis）功能	False，R/W
PVT_GLITCH_CHARGE_RESET	BLOCK1	103 / 1	发生 PVT 电源浪涌时触发动作：1 触发电荷泵，0 触发复位	False，R/W
PSRAM_CAP	BLOCK1	133 / 3	PSRAM 容量等级	0，R/W
PSRAM_VENDOR	BLOCK1	136 / 2	PSRAM 厂商标识	0，R/W
TEMP	BLOCK1	138 / 2	片内嵌温度参数	0，R/W
ADJUST_1V2	BLOCK1	148 / 4	SPI LDO 1.2V 调节	0，R/W
ADJUST_1V8	BLOCK1	152 / 4	SPI LDO 1.8V 调节	0，R/W
ACTIVE_DCDC_1V25	BLOCK1	156 / 4	DCDC 1.25V DBIAS 校准	0，R/W
ACTIVE_DCDC_1V35	BLOCK1	160 / 4	DCDC 1.35V DBIAS 校准	0，R/W
SLP_DCDC	BLOCK1	164 / 5	睡眠模式下 DCDC DBIAS 校准	0，R/W
VDD_3V4_DOUT	BLOCK2	144 / 10	3.4V 供电的 ADC 采样校准值	0，R/W
INITCODE_DIFF_1P8_3P3	BLOCK2	241 / 5	IO LDO 1.8V 与 3.3V 之间的 Initcode 差值校准	0，R/W
HI_DOUT_DIFF_1P8_3P3	BLOCK2	246 / 5	IO LDO 1.8V 与 3.3V 之间的 HI dout 差值校准	0，R/W
BLOCK_USR_DATA	BLOCK3	0 / 256	用户数据块（整个 BLK3 均可供用户参数使用）	32 字节全零，R/W
BLOCK_SYS_DATA2	BLOCK10	0 / 256	系统数据保留块（reserved）	32 字节全零，R/W

要点：

WR_DIS/RD_DIS是 H4 的两大保护字段。从 CSV 可看到WR_DIS是 32 位字段，每一位分别锁定一个具体字段（如WR_DIS.SECURE_BOOT_EN、WR_DIS.BLOCK_KEY0等），RD_DIS的 7 位则分别对应 BLOCK4~10 的读保护。
efuse.rst 的 "Deferred WR_DIS Burning" 小节专门说明：烧写 BLOCK0 暂存数据时，WR_DIS各位会在其他 BLOCK0 数据全部烧写成功后单独烧写，以确保烧写失败时可通过重试机制恢复，写保护只在数据烧写成功后才施加。
DIS_CORE1、DIS_TWAI、DIS_DOWNLOAD_MODE这类位一旦烧 1 即为永久功能裁剪，量产前需在 efuse 文档指引下谨慎决策。

4. Flash fuses：Flash 上电与 LDO 参数

字段	块	位偏移/位宽（CSV）	含义	示例值
FLASH_TPUW	BLOCK0	123 / 3	上电后等待 Flash ready 的时间（单位 ms）；值小于 15 时即为编程值，否则取 2 倍	0，R/W
FORCE_SEND_RESUME	BLOCK0	134 / 1	SPI 启动时是否强制 ROM 发送 resume 命令	False，R/W
FLASH_LDO_EFUSE_SEL	BLOCK0	156 / 1	Flash LDO 默认电压选择源：1 用 eFuse，0 用 strapping 引脚	False，R/W
FLASH_LDO_POWER_SEL	BLOCK1	113 / 1	选择 Flash LDO 档位：1 为 1.2V，0 为 1.8V	False，R/W
FLASH_CAP	BLOCK1	127 / 3	Flash 容量等级	0，R/W
FLASH_VENDOR	BLOCK1	130 / 3	Flash 厂商标识	0，R/W

这些字段主要由芯片出厂标定写入，用于 ROM 阶段确定 Flash 供电时序与电压；用户一般只读不写，但排查 Flash 读取异常时可对照efuse-dump确认。

5. Identity fuses：芯片身份与版本

字段	块	位偏移/位宽（CSV）	含义	示例值
WAFER_VERSION_MINOR	BLOCK1	114 / 4	芯片小版本号	1
WAFER_VERSION_MAJOR	BLOCK1	118 / 2	芯片大版本号	0
DISABLE_WAFER_VERSION_MAJOR	BLOCK1	120 / 1	关闭 wafer 大版本检查	False
DISABLE_BLK_VERSION_MAJOR	BLOCK1	121 / 1	关闭 block 大版本检查	False
BLK_VERSION_MINOR	BLOCK1	122 / 3	BLOCK2 的小版本号	0
BLK_VERSION_MAJOR	BLOCK1	125 / 2	BLOCK2 的大版本号	0
PKG_VERSION	BLOCK1	140 / 3	封装版本	0
OPTIONAL_UNIQUE_ID	BLOCK2	0 / 128	可选的 128 位唯一 ID（出厂默认全零，可由用户烧写）	16 字节全零，R/W

WAFER_VERSION_MAJOR/MINOR与BLK_VERSION是芯片步进（stepping）识别依据，ESP-IDF 的版本兼容性检查依赖它们；OPTIONAL_UNIQUE_ID与 BLK3 用户区一样可写入自定义标识，常用于设备序列号。

6. Jtag fuses：调试口裁剪

字段	块	位偏移/位宽（CSV）	含义	示例值
JTAG_SEL_ENABLE	BLOCK0	44 / 1	当`DIS_PAD_JTAG`与`DIS_USB_JTAG`均为 0 时，是否允许通过 strapping GPIO15 选择 usb_to_jtag 或 pad_to_jtag	False
DIS_PAD_JTAG	BLOCK0	45 / 1	硬（永久）禁用 JTAG。1: 禁用，0: 使能	False
SOFT_DIS_JTAG	BLOCK0	171 / 3	软禁用 JTAG，按奇偶判定：奇数值禁用，偶数值使能	0

配合下一节 Usb fuses 中的DIS_USB_JTAG，H4 提供了"物理 JTAG 硬关 + USB-JTAG 软关"两级调试口控制；JTAG_SEL_ENABLE则决定两者都存在时以哪个 strapping 脚裁决。

7. Mac fuses：MAC 地址

字段	块	位偏移/位宽（CSV）	含义	示例值
MAC	BLOCK1	0 / 48	出厂 MAC 地址（CSV 中按 8 位×6 段拼合）	30:ed:a0:ed:57:cc (OK)
MAC_EXT	BLOCK1	48 / 16	MAC 扩展位	00:00 (OK)
CUSTOM_MAC	BLOCK3	200 / 48	用户自定义 MAC（覆盖工厂 MAC）	00:00:00:00:00:00 (OK)
MAC_EUI64	BLOCK1	派生	按公式 MAC[0]:MAC[1]:MAC[2]:MAC_EXT[0]:MAC_EXT[1]:MAC[3]:MAC[4]:MAC[5] 计算的 EUI-64	30:ed:a0:00:00:ed:57:cc (OK)

从 CSV 可见 H4 的工厂 MAC 占据 BLK1 的第 0~47 位，且WR_DIS.MAC（位 20）提供对它的永久写保护。注意样例中的 MAC 为30前缀的 OUI，符合 Espressif 厂商标识；(OK)表示校验通过。EUI-64 是 IPv6/Thread 等协议常用的全局地址推导依据。

8. Security fuses：Secure Boot、Flash 加密与 Key Manager

这是摘要中最关键的一组，H4 样例输出如下（对应 CSV 位偏移一并给出）：

字段	块	位偏移/位宽（CSV）	含义	示例值
DIS_FORCE_DOWNLOAD	BLOCK0	41 / 1	禁用"强制进入 download 模式"功能（strapping 失效）	False
SPI_DOWNLOAD_MSPI_DIS	BLOCK0	42 / 1	download 模式下禁用 SPI0 控制器	False
DIS_DOWNLOAD_MANUAL_ENCRYPT	BLOCK0	46 / 1	禁用手动开启 Flash 加密功能（SPI boot 模式除外）	False
SPI_BOOT_CRYPT_CNT	BLOCK0	55 / 3	有效值含 1 或 3 个位时启用 Flash 加密，否则禁用（CSV 映射：0 Disable / 1 Enable / 3 Disable / 7 Enable）	Disable
SECURE_BOOT_KEY_REVOKE0/1/2	BLOCK0	58,59,60 / 1	依次吊销第 1/2/3 代 Secure Boot 密钥	均 False
KEY_PURPOSE_0 ~ KEY_PURPOSE_5	BLOCK0	64 起每 5 位	各密钥块（BLK4~9）的用途，如 USER、Secure Boot、Flash 加密、DS（数字签名）等	均 USER
SEC_DPA_LEVEL	BLOCK0	94 / 2	通过时钟随机分频配置的侧信道（DPA）防护等级	0
XTS_DPA_PSEUDO_LEVEL	BLOCK0	96 / 2	XTS-AES 抗 DPA 攻击伪轮数等级：3 High / 2 Moderate / 1 Low / 0 Disabled	0
XTS_DPA_CLK_ENABLE	BLOCK0	98 / 1	使能 XTS-AES 抗 DPA 时钟	False
SECURE_BOOT_SHA384_EN	BLOCK0	100 / 1	芯片是否支持使用 SHA-384 的 Secure Boot	False
SECURE_BOOT_EN	BLOCK0	101 / 1	使能 Secure Boot	False
SECURE_BOOT_AGGRESSIVE_REVOKE	BLOCK0	102 / 1	使能激进的 Secure Boot 吊销机制	False
FORCE_USE_KEY_MANAGER_KEY	BLOCK0	115 / 5	对应密钥（ECDSA/XTS-AES/HMAC/DS）是否必须来自 Key Manager	0
FORCE_DISABLE_SW_INIT_KEY	BLOCK0	120 / 1	禁止使用软件写入的初始化密钥，强制使用`efuse_init_key`	False
KM_XTS_KEY_LENGTH_256	BLOCK0	121 / 1	Flash 加密使用的密钥长度：0 为 XTS-AES-256，1 为 XTS-AES-128	False
LOCK_KM_KEY	BLOCK0	122 / 1	Key Manager 中的密钥部署后是否锁定	False
DIS_DOWNLOAD_MODE	BLOCK0	127 / 1	永久禁用 download 模式（烧 1 后无法再进入烧录模式）	False
ENABLE_SECURITY_DOWNLOAD	BLOCK0	131 / 1	使能安全下载模式	False
SECURE_VERSION	BLOCK0	135 / 16	ESP-IDF 防回滚（anti-rollback）使用的版本号	0
BLOCK_KEY0	BLOCK4	0 / 256	Key0 或用户数据	32 字节全零，R/W
BLOCK_KEY1	BLOCK5	0 / 256	Key1 或用户数据	32 字节全零，R/W
BLOCK_KEY2	BLOCK6	0 / 256	Key2 或用户数据	32 字节全零，R/W
BLOCK_KEY3	BLOCK7	0 / 256	Key3 或用户数据	32 字节全零，R/W
BLOCK_KEY4	BLOCK8	0 / 256	Key4 或用户数据	32 字节全零，R/W
BLOCK_KEY5	BLOCK9	0 / 256	Key5 或用户数据	32 字节全零，R/W

解读要点：

6 个 256 位密钥块（BLK4~9）默认KEY_PURPOSE_x = USER，即可当作用户数据；一旦烧入密钥并通过WR_DIS锁定对应位，其用途即固化，不可回退。
SECURE_VERSION是防回滚的单调递增版本：新固件版本必须大于已烧写值才能通过校验，部署后不可减小。
RD_DIS与WR_DIS共同构成密钥块的"读写双保险"：RD_DIS.BLOCK_KEYx（位 32~37）烧 1 后连 eFuse Manager 也无法读出密钥块内容。
Key Manager 相关字段（KM_*、FORCE_USE_KEY_MANAGER_KEY、LOCK_KM_KEY）属于 H4 新增的硬件密钥管理能力，配合 esp_security 相关组件使用。

9. Usb fuses 与 Vdd fuses：USB 引脚交换和 Flash LDO 电压

字段	块	位偏移/位宽（CSV）	含义	示例值
DIS_USB_JTAG	BLOCK0	39 / 1	永久禁用 USB 切换为 JTAG（USB-JTAG）功能	False
DIS_USB_SERIAL_JTAG_ROM_PRINT	BLOCK0	129 / 1	禁用 USB-Serial-JTAG 的 ROM 打印（烧录日志）	False
DIS_USB_SERIAL_JTAG_DOWNLOAD_MODE	BLOCK0	130 / 1	禁用 USB-Serial-JTAG 下载功能	False
USB_EXCHG_PINS	BLOCK0	168 / 1	交换 USB_SERIAL_JTAG PHY 的 D+/D- 引脚	False
USB_OTG_FS_EXCHG_PINS	BLOCK0	169 / 1	交换 USB_OTG_FS PHY 的 D+/D- 引脚	False
USB_PHY_SEL	BLOCK0	170 / 1	交换 USB_SERIAL_JTAG PHY 与 USB_OTG_FS PHY	False
VDD_SPI_LDO_ADJUST	BLOCK1	105 / 8	Flash LDO 模式与电压配置	0

H4 上 USB-Serial-JTAG 是默认调试/烧录通道，三个DIS_USB_SERIAL_JTAG_*字段允许在产品阶段分粒度关闭 ROM 打印与下载能力；USB_EXCHG_PINS等引脚交换位则是针对硬件设计（D+/D- 交叉布线）的适配手段，仅在原理图要求时使用。

10. Wdt fuses：RTC 看门狗超时调节

字段	块	位偏移/位宽（CSV）	含义	示例值
WDT_DELAY_SEL	BLOCK1	100 / 2	RTC 看门狗 STG0 超时阈值倍率：0 为 ×2，1 为 ×4，2 为 ×8，3 为 ×16（相对原始阈值配置值）	0

该字段用于补偿不同工艺/温度下 RTC 振荡器偏差，避免看门狗误复位，属于出厂/工程标定项。

11. 实战建议：把 eFuse 状态纳入构建与产线流程

除了命令行，ESP-IDF 还支持在构建阶段获取 eFuse 状态。efuse 文档给出两个 CMake 函数：

espefuse_get_json_summary()：调用espefuse summary --format json，返回 JSON 字符串；
espefuse_get_efuse()：从 JSON 中取出指定 eFuse 的属性。

JSON 中每个字段的属性包括bit_len、block、category、description、efuse_type、name、pos、readable、value、word、writeable等，与本文各表格一一对应。示例（摘自 system/efuse 示例 CMakeLists.txt）：

project(hello_world) espefuse_get_json_summary(efuse_json) espefuse_get_efuse(ret_data ${efuse_json} "MAC" "value") message("MAC:" ${ret_data})

结合本文的字段表，可以据此实现：

烧录前门禁：产线脚本先跑idf.py -p PORT efuse-summary，检查WR_DIS、KEY_PURPOSE_x、SECURE_VERSION等敏感位是否为 0，避免对已锁定芯片重复烧写。
固件自适应：构建期读取MAC/OPTIONAL_UNIQUE_ID等字段值，生成设备标识代码。
安全部署核对：Secure Boot / Flash 加密烧录完成后，再跑一次efuse-summary，确认SECURE_BOOT_EN、SPI_BOOT_CRYPT_CNT与 6 个BLOCK_KEYx状态符合预期；需要原始位级核对时辅以efuse-dump。
离线诊断：当 UART 下载被禁用、Secure Boot 已部署导致主机工具无法直读时，可在设备上用文档所述的 token dump 机制（EFSR/EFSW/EFSRW令牌，含 CRC32 校验）把 eFuse 状态随日志带出，再在主机侧用espefuse --token EFS... summary离线解码，详见 efuse 文档 Token Dump 小节。

12. 小结

idf.py -p PORT efuse-summary是读懂 H4 芯片 eFuse 的第一入口，输出按 Config / Flash / Identity / Jtag / Mac / Security / Usb / Vdd / Wdt 九类组织，本文已逐字段给出位偏移、位宽与取值语义，可直接作为产线与研发的速查表。
H4 的 eFuse 布局（11 个 256 位块、6 个密钥块、128 位 Unique ID、BLK1 中的 MAC）与所有字段定义均可在 esp_efuse_table.csv 中复核，修改后需执行idf.py efuse-common-table重新生成 C 源码。
所有 eFuse 位均为一次性可编程：烧写DIS_*、KEY_PURPOSE_*、SECURE_VERSION、WR_DIS/RD_DIS等字段前，务必先efuse-summary/efuse-dump确认现状，并在虚拟 eFuse（CONFIG_EFUSE_VIRTUAL）模式下先行验证脚本流程。

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考