Merge branch 'backport/support_two_MAC_esp32s31_v6.1' into 'release/v6.1'

fix(esp32s31): restrict UNIVERSAL_MAC_ADDRESSES to Two (backport v6.1) See merge request espressif/esp-idf!50571
2026-09-22 13:01:16 +03:00 · 2026-07-16 12:07:20 +08:00
parent 6cb467a433 7ca1369ffc
commit cc979db24b
6 changed files with 134 additions and 21 deletions
--- a/components/esp_hw_support/port/esp32h2/Kconfig.mac
+++ b/components/esp_hw_support/port/esp32h2/Kconfig.mac
@@ -1,18 +1,27 @@
 choice ESP32H2_UNIVERSAL_MAC_ADDRESSES
    bool "Number of universally administered (by IEEE) MAC address"
-    default ESP32H2_UNIVERSAL_MAC_ADDRESSES_TWO
+    default ESP32H2_UNIVERSAL_MAC_ADDRESSES_ONE
    help
        Configure the number of universally administered (by IEEE) MAC addresses.
        During initialization, MAC addresses for each network interface are generated or derived from a
        single base MAC address.

-    config ESP32H2_UNIVERSAL_MAC_ADDRESSES_TWO
-        bool "Two"
-        select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_TWO
+        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.15.4
+        EUI-64. Only one universal MAC address is consumed:
+
+        - IEEE 802.15.4 EUI-64 is derived from the base MAC and MAC_EXT
+          (base_mac[0:2] || MAC_EXT || base_mac[3:5], 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
        select ESP_MAC_ADDR_UNIVERSE_IEEE802154
        select ESP_MAC_ADDR_UNIVERSE_BT
 endchoice

 config ESP32H2_UNIVERSAL_MAC_ADDRESSES
    int
-    default 2 if ESP32H2_UNIVERSAL_MAC_ADDRESSES_TWO
+    default 1 if ESP32H2_UNIVERSAL_MAC_ADDRESSES_ONE
--- a/components/esp_hw_support/port/esp32h21/Kconfig.mac
+++ b/components/esp_hw_support/port/esp32h21/Kconfig.mac
@@ -1,18 +1,27 @@
 choice ESP32H21_UNIVERSAL_MAC_ADDRESSES
    bool "Number of universally administered (by IEEE) MAC address"
-    default ESP32H21_UNIVERSAL_MAC_ADDRESSES_TWO
+    default ESP32H21_UNIVERSAL_MAC_ADDRESSES_ONE
    help
        Configure the number of universally administered (by IEEE) MAC addresses.
        During initialization, MAC addresses for each network interface are generated or derived from a
        single base MAC address.

-    config ESP32H21_UNIVERSAL_MAC_ADDRESSES_TWO
-        bool "Two"
-        select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_TWO
+        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.15.4
+        EUI-64. Only one universal MAC address is consumed:
+
+        - IEEE 802.15.4 EUI-64 is derived from the base MAC and MAC_EXT
+          (base_mac[0:2] || MAC_EXT || base_mac[3:5], 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
        select ESP_MAC_ADDR_UNIVERSE_IEEE802154
        select ESP_MAC_ADDR_UNIVERSE_BT
 endchoice

 config ESP32H21_UNIVERSAL_MAC_ADDRESSES
    int
-    default 2 if ESP32H21_UNIVERSAL_MAC_ADDRESSES_TWO
+    default 1 if ESP32H21_UNIVERSAL_MAC_ADDRESSES_ONE
--- a/components/esp_hw_support/port/esp32h4/Kconfig.mac
+++ b/components/esp_hw_support/port/esp32h4/Kconfig.mac
@@ -1,18 +1,27 @@
 choice ESP32H4_UNIVERSAL_MAC_ADDRESSES
    bool "Number of universally administered (by IEEE) MAC address"
-    default ESP32H4_UNIVERSAL_MAC_ADDRESSES_TWO
+    default ESP32H4_UNIVERSAL_MAC_ADDRESSES_ONE
    help
        Configure the number of universally administered (by IEEE) MAC addresses.
        During initialization, MAC addresses for each network interface are generated or derived from a
        single base MAC address.

-    config ESP32H4_UNIVERSAL_MAC_ADDRESSES_TWO
-        bool "Two"
-        select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_TWO
+        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.15.4
+        EUI-64. Only one universal MAC address is consumed:
+
+        - IEEE 802.15.4 EUI-64 is derived from the base MAC and MAC_EXT
+          (base_mac[0:2] || MAC_EXT || base_mac[3:5], 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
        select ESP_MAC_ADDR_UNIVERSE_IEEE802154
        select ESP_MAC_ADDR_UNIVERSE_BT
 endchoice

 config ESP32H4_UNIVERSAL_MAC_ADDRESSES
    int
-    default 2 if ESP32H4_UNIVERSAL_MAC_ADDRESSES_TWO
+    default 1 if ESP32H4_UNIVERSAL_MAC_ADDRESSES_ONE
--- a/components/esp_hw_support/port/esp32s31/Kconfig.mac
+++ b/components/esp_hw_support/port/esp32s31/Kconfig.mac
@@ -1,6 +1,6 @@
 choice ESP32S31_UNIVERSAL_MAC_ADDRESSES
    bool "Number of universally administered (by IEEE) MAC address"
-    default ESP32S31_UNIVERSAL_MAC_ADDRESSES_FOUR
+    default ESP32S31_UNIVERSAL_MAC_ADDRESSES_TWO
    help
        Configure the number of universally administered (by IEEE) MAC addresses.
        During initialization, MAC addresses for each network interface are generated or derived from a
@@ -13,9 +13,9 @@ choice ESP32S31_UNIVERSAL_MAC_ADDRESSES
        and 1 (respectively) to the base MAC address. The remaining two interfaces (WiFi softap and Ethernet)
        receive local MAC addresses. These are derived from the universal WiFi station and Bluetooth MAC
        addresses, respectively.
-        When using the default (Espressif-assigned) base MAC address, either setting can be used. When using
-        a custom universal MAC address range, the correct setting will depend on the allocation of MAC
-        addresses in this range (either 2 or 4 per device.)
+        ESP32-S31 only provides two universally administered MAC addresses in eFuse, so "Two" is the
+        recommended and default setting. "Four" is only intended for use with a custom base MAC range
+        where four universally administered MAC addresses are allocated per device.

    config ESP32S31_UNIVERSAL_MAC_ADDRESSES_TWO
        bool "Two"
--- 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 <CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES>` 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 <local-mac-addresses>` (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 <local-mac-addresses>` (derived from Bluetooth MAC)
+          - base_mac, +3 to the last octet
+
+    .. note::
+
+        {IDF_TARGET_NAME} 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 <MAC-Address-Allocation>`), 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.15.4
+          - EUI-64 derived from base_mac and MAC_EXT (base_mac[0:2] ‖ MAC_EXT ‖ base_mac[3:5], 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.15.4 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::
--- 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:`配置选项 <CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES>` 配置了乐鑫提供的全局 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 <local-mac-addresses>` （由 Wi-Fi Station MAC 生成）
+          - base_mac 最后一组字节后加 1
+        * - 蓝牙
+          - base_mac 最后一组字节后加 1
+          - base_mac 最后一组字节后加 2
+        * - 以太网
+          - :ref:`本地 MAC <local-mac-addresses>` （由蓝牙 MAC 生成）
+          - base_mac 最后一组字节后加 3
+
+    .. note::
+
+        {IDF_TARGET_NAME} 在 eFuse 中仅提供两个全局管理型 MAC 地址，因此 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 默认为两个。其中的“四个”选项仅在使用客户自定义基准 MAC 范围时可用（参见 :ref:`自定义基准 MAC <MAC-Address-Allocation>`），且该范围内每个设备需分配 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.15.4
+          - 由 base_mac 和 MAC_EXT 派生的 EUI-64（base_mac[0:2] ‖ MAC_EXT ‖ base_mac[3:5]，MAC_EXT 默认为 ff:fe）
+        * - 蓝牙
+          - base_mac
+
+    .. note::
+
+        {IDF_TARGET_NAME} 在 eFuse 中仅提供一个全局管理型 MAC 地址（MAC_FACTORY），以及用于构造 IEEE 802.15.4 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::