From 16b02aeb7a805de671ca92c0c7630eda091794ce Mon Sep 17 00:00:00 2001
From: David Cermak <cermak@espressif.com>
Date: Mon, 22 Sep 2025 17:04:22 +0200
Subject: [PATCH] feat(lwip): Add support for netif link callback

---
 components/lwip/Kconfig                 |  6 ++++++
 components/lwip/port/include/lwipopts.h | 12 +++++++++++-
 docs/en/api-guides/lwip.rst             |  6 ++++++
 docs/zh_CN/api-guides/lwip.rst          |  6 ++++++
 4 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/components/lwip/Kconfig b/components/lwip/Kconfig
index ae6bf83e69..608bf2493e 100644
--- a/components/lwip/Kconfig
+++ b/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
diff --git a/components/lwip/port/include/lwipopts.h b/components/lwip/port/include/lwipopts.h
index 4927f9b01c..4fb79b6177 100644
--- a/components/lwip/port/include/lwipopts.h
+++ b/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.
diff --git a/docs/en/api-guides/lwip.rst b/docs/en/api-guides/lwip.rst
index 523a8504b9..a8f28955fa 100644
--- a/docs/en/api-guides/lwip.rst
+++ b/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
diff --git a/docs/zh_CN/api-guides/lwip.rst b/docs/zh_CN/api-guides/lwip.rst
index d9f9997919..338d548e21 100644
--- a/docs/zh_CN/api-guides/lwip.rst
+++ b/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:
 
 限制