Merge branch 'feat/lwip_netif_callbacks' into 'master'

[lwip]: Add support for netif link callback

Closes IDFGH-16317

See merge request espressif/esp-idf!42097

Author: david-cermak

components/lwip/Kconfig

@@ -560,6 +560,12 @@ menu "LWIP"
         help
             Enable callbacks when the network interface is up/down and addresses are changed.
 
+    config LWIP_NETIF_LINK_CALLBACK
+        bool "Enable link callback for network interfaces"
+        default n
+        help
+            Enable callbacks when the physical network link is up/down.
+
     menuconfig LWIP_NETIF_LOOPBACK
         bool "Support per-interface loopback"
         default y

components/lwip/port/include/lwipopts.h

@@ -3,7 +3,7 @@
  *
  * SPDX-License-Identifier: BSD-3-Clause
  *
- * SPDX-FileContributor: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileContributor: 2015-2025 Espressif Systems (Shanghai) CO LTD
  */
 #ifndef LWIP_HDR_ESP_LWIPOPTS_H
 #define LWIP_HDR_ESP_LWIPOPTS_H
@@ -725,6 +725,16 @@ static inline uint32_t timeout_from_offered(uint32_t lease, uint32_t min)
 #define LWIP_NETIF_STATUS_CALLBACK      0
 #endif
 
+/**
+ * LWIP_NETIF_LINK_CALLBACK==1: Support a callback function from an interface
+ * whenever the link changes its up/down status.
+ */
+#ifdef CONFIG_LWIP_NETIF_LINK_CALLBACK
+#define LWIP_NETIF_LINK_CALLBACK       1
+#else
+#define LWIP_NETIF_LINK_CALLBACK       0
+#endif
+
 /**
  * LWIP_NETIF_EXT_STATUS_CALLBACK==1: Support an extended callback function
  * for several netif related event that supports multiple subscribers.

docs/en/api-guides/lwip.rst

@@ -507,6 +507,12 @@ This approach may not work for function-like macros, as there is no guarantee th
 
 Alternatively, you can define your function-like macro in a header file which will be pre-included as an lwIP hook file, see :ref:`lwip-custom-hooks`.
 
+Network Interface Callbacks
+---------------------------
+
+- Status Callback (:ref:`CONFIG_LWIP_NETIF_STATUS_CALLBACK`): Enables `netif_set_status_callback()` to notify when an interface comes up/down and when IPv4/IPv6 addresses change.
+- Link Callback (:ref:`CONFIG_LWIP_NETIF_LINK_CALLBACK`): Enables `netif_set_link_callback()` to notify when the physical link goes up/down. The callback is triggered by `netif_set_link_up()` / `netif_set_link_down()` calls in drivers or virtual interfaces. Can be used alongside `LWIP_NETIF_EXT_STATUS_CALLBACK` for richer eventing.
+
 .. _lwip-limitations:
 
 Limitations

docs/zh_CN/api-guides/lwip.rst

@@ -507,6 +507,12 @@ ESP-IDF 提供了其他可覆盖的 lwIP 钩子，例如：
 
 另一种方法是在头文件中定义函数式宏，该头文件将预先包含在 lwIP 钩子文件中，请参考 :ref:`lwip-custom-hooks`。
 
+网络接口回调
+-----------------
+
+- 状态回调 (:ref:`CONFIG_LWIP_NETIF_STATUS_CALLBACK`)：启用 `netif_set_status_callback()`，在接口上下线以及 IPv4/IPv6 地址发生变化时通知。
+- 链路回调 (:ref:`CONFIG_LWIP_NETIF_LINK_CALLBACK`)：启用 `netif_set_link_callback()`，在物理链路上下线时通知。该回调由驱动或虚拟接口调用 `netif_set_link_up()` / `netif_set_link_down()` 触发。可与 `LWIP_NETIF_EXT_STATUS_CALLBACK` 配合使用，以获取更丰富的事件通知。
+
 .. _lwip-limitations:
 
 限制