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

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::

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::