From 40081e5ae723e15870d56f5464a8e559dd71599c Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Fri, 10 Apr 2026 13:13:05 -1000
Subject: [PATCH] [rp2040] Fix W5500 Ethernet pbuf corruption by mirroring
 LWIPMutex semantics (#15624)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 esphome/components/rp2040/helpers.cpp | 31 +++++++++++++++++++++------
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/esphome/components/rp2040/helpers.cpp b/esphome/components/rp2040/helpers.cpp
index 8cb5f7c18d..6e5ddad236 100644
--- a/esphome/components/rp2040/helpers.cpp
+++ b/esphome/components/rp2040/helpers.cpp
@@ -9,7 +9,7 @@
 #include <WiFi.h>
 #include <pico/cyw43_arch.h>  // For cyw43_arch_lwip_begin/end (LwIPLock)
 #elif defined(USE_ETHERNET)
-#include <LwipEthernet.h>  // For ethernet_arch_lwip_begin/end (LwIPLock)
+#include <lwip_wrap.h>  // For LWIPMutex — LwIPLock mirrors its semantics (see below)
 #include "esphome/components/ethernet/ethernet_component.h"
 #endif
 #include <hardware/structs/rosc.h>
@@ -43,9 +43,18 @@ IRAM_ATTR InterruptLock::~InterruptLock() { restore_interrupts(state_); }
 // main loop, corrupting the shared rx_buf_ pbuf chain (use-after-free, pbuf_cat
 // assertion failures). See esphome#10681.
 //
-// WiFi uses cyw43_arch_lwip_begin/end; Ethernet uses ethernet_arch_lwip_begin/end.
-// Both acquire the async_context recursive mutex to prevent IRQ callbacks from
-// firing during critical sections.
+// WiFi uses cyw43_arch_lwip_begin/end.
+//
+// For wired Ethernet, taking only the async_context lock is NOT enough. The
+// W5500 GPIO IRQ path (LwipIntfDev::_irq) checks arduino-pico's `__inLWIP`
+// counter to decide whether to defer packet processing. If we hold the
+// async_context lock without bumping `__inLWIP`, an interrupt-driven packet
+// arrival re-enters lwIP from IRQ context and corrupts pbufs (the `pbuf_cat`
+// assertion crash on wiznet-w5500-evb-pico). We mirror arduino-pico's
+// LWIPMutex (cores/rp2040/lwip_wrap.h) exactly: bump `__inLWIP`, take the
+// lock, and on release re-unmask any GPIO IRQs that were deferred while we
+// held it. We can't `using LwIPLock = LWIPMutex;` in helpers.h because
+// pulling lwip_wrap.h there poisons many TUs with lwIP types.
 //
 // When neither WiFi nor Ethernet is configured, this is a no-op since
 // there's no network stack and no lwip callbacks to race with.
@@ -53,8 +62,18 @@ IRAM_ATTR InterruptLock::~InterruptLock() { restore_interrupts(state_); }
 LwIPLock::LwIPLock() { cyw43_arch_lwip_begin(); }
 LwIPLock::~LwIPLock() { cyw43_arch_lwip_end(); }
 #elif defined(USE_ETHERNET)
-LwIPLock::LwIPLock() { ethernet_arch_lwip_begin(); }
-LwIPLock::~LwIPLock() { ethernet_arch_lwip_end(); }
+LwIPLock::LwIPLock() {
+  __inLWIP++;
+  ethernet_arch_lwip_begin();
+}
+LwIPLock::~LwIPLock() {
+  ethernet_arch_lwip_end();
+  __inLWIP--;
+  if (__needsIRQEN && !__inLWIP) {
+    __needsIRQEN = false;
+    ethernet_arch_lwip_gpio_unmask();
+  }
+}
 #else
 LwIPLock::LwIPLock() {}
 LwIPLock::~LwIPLock() {}