From b5cd9ce7faac882a2465090fe4f63a8c31b5a81a Mon Sep 17 00:00:00 2001 From: Jack Date: Mon, 6 Jul 2026 18:06:24 +0800 Subject: [PATCH] docs(esp_hw_support): document one-universal-MAC scheme and esp32s31 Four-option constraint Add help text to the esp32h2/esp32h21/esp32h4 Kconfig.mac explaining that these chips only consume one universally administered MAC address: the IEEE 802.154 EUI-64 is derived from the base MAC and MAC_EXT, and Bluetooth reuses the base MAC as-is (no BT offset, since there is no Wi-Fi). Add a matching 1-MAC derivation table and note to misc_system_api.rst (EN and zh_CN) under a new `.. only:: esp32h2 or esp32h21 or esp32h4` block, and exclude these targets from the generic 4/2 table. Add an esp32s31-only note stating that the "Four" option may only be used with a customer-provided custom base MAC range, since ESP32-S31 only provides two universally administered MAC addresses in eFuse. Co-authored-by: Cursor (cherry picked from commit e3bc260178417ce6ec1f70d35e89628caf44563e) --- .../esp_hw_support/port/esp32h2/Kconfig.mac | 8 ++++ .../esp_hw_support/port/esp32h21/Kconfig.mac | 8 ++++ .../esp_hw_support/port/esp32h4/Kconfig.mac | 8 ++++ .../api-reference/system/misc_system_api.rst | 45 ++++++++++++++++++- .../api-reference/system/misc_system_api.rst | 45 ++++++++++++++++++- 5 files changed, 112 insertions(+), 2 deletions(-) diff --git a/components/esp_hw_support/port/esp32h2/Kconfig.mac b/components/esp_hw_support/port/esp32h2/Kconfig.mac index cc4cd68ae9c..a3829ec3bb8 100644 --- a/components/esp_hw_support/port/esp32h2/Kconfig.mac +++ b/components/esp_hw_support/port/esp32h2/Kconfig.mac @@ -6,6 +6,14 @@ choice ESP32H2_UNIVERSAL_MAC_ADDRESSES During initialization, MAC addresses for each network interface are generated or derived from a single base MAC address. + ESP32-H2 provides a single universally administered MAC address in eFuse + (MAC_FACTORY, 6 bytes) plus the MAC_EXT field used to build the IEEE 802.154 + EUI-64. Only one universal MAC address is consumed: + - IEEE 802.154 EUI-64 is derived from the base MAC and MAC_EXT + (base_mac[0:3] || MAC_EXT || base_mac[3:6], MAC_EXT defaults to ff:fe); + - Bluetooth reuses the base MAC as-is. The BT offset is not applied because + ESP32-H2 has no Wi-Fi, so no second universal MAC slot is required. + config ESP32H2_UNIVERSAL_MAC_ADDRESSES_ONE bool "One" select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_ONE diff --git a/components/esp_hw_support/port/esp32h21/Kconfig.mac b/components/esp_hw_support/port/esp32h21/Kconfig.mac index a1a0795cc1e..33d385be1b8 100644 --- a/components/esp_hw_support/port/esp32h21/Kconfig.mac +++ b/components/esp_hw_support/port/esp32h21/Kconfig.mac @@ -6,6 +6,14 @@ choice ESP32H21_UNIVERSAL_MAC_ADDRESSES During initialization, MAC addresses for each network interface are generated or derived from a single base MAC address. + ESP32-H21 provides a single universally administered MAC address in eFuse + (MAC_FACTORY, 6 bytes) plus the MAC_EXT field used to build the IEEE 802.154 + EUI-64. Only one universal MAC address is consumed: + - IEEE 802.154 EUI-64 is derived from the base MAC and MAC_EXT + (base_mac[0:3] || MAC_EXT || base_mac[3:6], MAC_EXT defaults to ff:fe); + - Bluetooth reuses the base MAC as-is. The BT offset is not applied because + ESP32-H21 has no Wi-Fi, so no second universal MAC slot is required. + config ESP32H21_UNIVERSAL_MAC_ADDRESSES_ONE bool "One" select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_ONE diff --git a/components/esp_hw_support/port/esp32h4/Kconfig.mac b/components/esp_hw_support/port/esp32h4/Kconfig.mac index 24371cb6303..713782a94ca 100644 --- a/components/esp_hw_support/port/esp32h4/Kconfig.mac +++ b/components/esp_hw_support/port/esp32h4/Kconfig.mac @@ -6,6 +6,14 @@ choice ESP32H4_UNIVERSAL_MAC_ADDRESSES During initialization, MAC addresses for each network interface are generated or derived from a single base MAC address. + ESP32-H4 provides a single universally administered MAC address in eFuse + (MAC_FACTORY, 6 bytes) plus the MAC_EXT field used to build the IEEE 802.154 + EUI-64. Only one universal MAC address is consumed: + - IEEE 802.154 EUI-64 is derived from the base MAC and MAC_EXT + (base_mac[0:3] || MAC_EXT || base_mac[3:6], MAC_EXT defaults to ff:fe); + - Bluetooth reuses the base MAC as-is. The BT offset is not applied because + ESP32-H4 has no Wi-Fi, so no second universal MAC slot is required. + config ESP32H4_UNIVERSAL_MAC_ADDRESSES_ONE bool "One" select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_ONE diff --git a/docs/en/api-reference/system/misc_system_api.rst b/docs/en/api-reference/system/misc_system_api.rst index 5f709db72f6..10dca299ce9 100644 --- a/docs/en/api-reference/system/misc_system_api.rst +++ b/docs/en/api-reference/system/misc_system_api.rst @@ -54,7 +54,7 @@ In ESP-IDF, the MAC addresses for the various network interfaces are calculated On ESP32-P4, :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` is fixed to one universally administered MAC address. -.. only:: (not esp32s2) and (not esp32p4) +.. only:: (not esp32s2) and (not esp32p4) and (not esp32h2) and (not esp32h21) and (not esp32h4) and (not esp32s31) .. list-table:: :widths: 20 40 40 @@ -80,6 +80,49 @@ In ESP-IDF, the MAC addresses for the various network interfaces are calculated The :ref:`configuration ` configures the number of universally administered MAC addresses that are provided by Espressif. +.. only:: esp32s31 + + .. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - Interface + - MAC Address (2 universally administered, default) + - MAC Address (4 universally administered) + * - Wi-Fi Station + - base_mac + - base_mac + * - Wi-Fi SoftAP + - :ref:`Local MAC ` (derived from Wi-Fi Station MAC) + - base_mac, +1 to the last octet + * - Bluetooth + - base_mac, +1 to the last octet + - base_mac, +2 to the last octet + * - Ethernet + - :ref:`Local MAC ` (derived from Bluetooth MAC) + - base_mac, +3 to the last octet + + .. note:: + + ESP32-S31 only provides two universally administered MAC addresses in eFuse, so :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` defaults to two. The "Four" option may only be used when a customer-provided custom base MAC range is used (see :ref:`Custom Base MAC `), where four universally administered MAC addresses are allocated per device. Using "Four" with the default Espressif eFuse base MAC leads to SoftAP and Ethernet consuming global MAC slots (base+1/+3) that are not allocated on this chip and may collide with the Bluetooth MAC. + +.. only:: esp32h2 or esp32h21 or esp32h4 + + .. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Interface + - MAC Address (1 universally administered, default) + * - IEEE 802.154 + - EUI-64 derived from base_mac and MAC_EXT (base_mac[0:3] ‖ MAC_EXT ‖ base_mac[3:6], MAC_EXT defaults to ff:fe) + * - Bluetooth + - base_mac + + .. note:: + + {IDF_TARGET_NAME} provides a single universally administered MAC address in eFuse (MAC_FACTORY) plus the MAC_EXT field used to build the IEEE 802.154 EUI-64. :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` is fixed to one. Bluetooth reuses the base MAC as-is — the BT offset is not applied because {IDF_TARGET_NAME} has no Wi-Fi, so no second universal MAC slot is required. + .. only:: esp32s2 .. list-table:: diff --git a/docs/zh_CN/api-reference/system/misc_system_api.rst b/docs/zh_CN/api-reference/system/misc_system_api.rst index d0b8bda17ec..9d27429cc18 100644 --- a/docs/zh_CN/api-reference/system/misc_system_api.rst +++ b/docs/zh_CN/api-reference/system/misc_system_api.rst @@ -54,7 +54,7 @@ MAC 地址 在 ESP32-P4 上，:ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 固定为单个通用管理型 MAC 地址。 -.. only:: (not esp32s2) and (not esp32p4) +.. only:: (not esp32s2) and (not esp32p4) and (not esp32h2) and (not esp32h21) and (not esp32h4) and (not esp32s31) .. list-table:: :widths: 20 40 40 @@ -80,6 +80,49 @@ MAC 地址 :ref:`配置选项 ` 配置了乐鑫提供的全局 MAC 地址的数量。 +.. only:: esp32s31 + + .. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - 接口 + - MAC 地址（默认 2 个全局地址） + - MAC 地址（4 个全局地址） + * - Wi-Fi Station + - base_mac + - base_mac + * - Wi-Fi SoftAP + - :ref:`本地 MAC ` （由 Wi-Fi Station MAC 生成） + - base_mac 最后一组字节后加 1 + * - 蓝牙 + - base_mac 最后一组字节后加 1 + - base_mac 最后一组字节后加 2 + * - 以太网 + - :ref:`本地 MAC ` （由蓝牙 MAC 生成） + - base_mac 最后一组字节后加 3 + + .. note:: + + ESP32-S31 在 eFuse 中仅提供两个全局管理型 MAC 地址，因此 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 默认为两个。其中的“四个”选项仅在使用客户自定义基准 MAC 范围时可用（参见 :ref:`自定义基准 MAC `），且该范围内每个设备需分配 4 个全局管理型 MAC 地址。若在使用乐鑫 eFuse 默认基准 MAC 时选择“四个”，SoftAP 和以太网会占用 base+1/+3 的全局 MAC 槽位，而这些槽位在本芯片上并未分配，可能与蓝牙 MAC 发生冲突。 + +.. only:: esp32h2 or esp32h21 or esp32h4 + + .. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - 接口 + - MAC 地址（1 个默认的通用管理地址） + * - IEEE 802.154 + - 由 base_mac 和 MAC_EXT 派生的 EUI-64（base_mac[0:3] ‖ MAC_EXT ‖ base_mac[3:6]，MAC_EXT 默认为 ff:fe） + * - 蓝牙 + - base_mac + + .. note:: + + {IDF_TARGET_NAME} 在 eFuse 中仅提供一个全局管理型 MAC 地址（MAC_FACTORY），以及用于构造 IEEE 802.154 EUI-64 的 MAC_EXT 字段。:ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 固定为 1。蓝牙直接复用基准 MAC —— 由于 {IDF_TARGET_NAME} 没有 Wi-Fi，BT 偏移不会生效，因此不需要第二个全局 MAC 槽位。 + .. only:: esp32s2 .. list-table::