From 6734aa1544ebb330159738a050c0acab354900a3 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Mon, 23 Feb 2026 21:24:29 -0600 Subject: [PATCH] comments --- esphome/core/lwip_fast_select.c | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/esphome/core/lwip_fast_select.c b/esphome/core/lwip_fast_select.c index 87baf449cb..7995a60f8d 100644 --- a/esphome/core/lwip_fast_select.c +++ b/esphome/core/lwip_fast_select.c @@ -15,6 +15,21 @@ // via the original callback under SYS_ARCH_PROTECT/UNPROTECT mutex) // 3. Background tasks — call wake_main_loop // +// LwIP source references (STABLE-2_2_0_RELEASE): +// https://github.com/lwip-tcpip/lwip/blob/STABLE-2_2_0_RELEASE/src/api/sockets.c +// - event_callback (static, same for all sockets): line 619 +// - DEFAULT_SOCKET_EVENTCB = event_callback: line 622 +// - lwip_socket_dbg_get_socket (direct array lookup, no locking): line 654 +// - tryget_socket_unconn_nouse (the array lookup helper): line 1008 +// - All socket types use DEFAULT_SOCKET_EVENTCB: lines 3309-3325 +// - event_callback SYS_ARCH_PROTECT before rcvevent switch: line 3685 +// - sock->rcvevent++ (NETCONN_EVT_RCVPLUS case): line 3688 +// - SYS_ARCH_UNPROTECT after switch: line 3720 +// https://github.com/lwip-tcpip/lwip/blob/STABLE-2_2_0_RELEASE/src/include/lwip/sys.h +// - SYS_ARCH_PROTECT calls sys_arch_protect(): line 557 +// - SYS_ARCH_UNPROTECT calls sys_arch_unprotect(): line 568 +// (ESP-IDF implements sys_arch_protect/unprotect as FreeRTOS mutex lock/unlock) +// // Shared state and safety rationale: // // s_main_loop_task (TaskHandle_t, 4 bytes): @@ -33,7 +48,7 @@ // // sock->conn->callback (netconn_callback, 4-byte function pointer): // Written by main loop in hook_socket(). Never restored — all LwIP sockets share -// the same static event_callback, so the wrapper stays in place permanently. +// the same static event_callback (line 619, 622), so the wrapper stays permanently. // Read by TCP/IP thread when invoking the callback. // Safe: 32-bit aligned pointer writes are atomic on Xtensa and RISC-V (ESP32). // The TCP/IP thread will see either the old or new pointer atomically — never a @@ -41,14 +56,13 @@ // (the wrapper itself calls the original), so either value is correct. // // sock->rcvevent (s16_t, 2 bytes): -// Written by TCP/IP thread in event_callback under SYS_ARCH_PROTECT/UNPROTECT. +// Written by TCP/IP thread in event_callback under SYS_ARCH_PROTECT (line 3685). // Read by main loop in has_data() via volatile cast. -// Safe: SYS_ARCH_UNPROTECT releases a FreeRTOS mutex (sys_mutex_unlock), which -// internally uses a critical section with memory barrier (rsync on Xtensa), -// ensuring the write is committed before the mutex is released. The volatile -// cast prevents the compiler from caching the read. Aligned 16-bit reads are -// single-instruction loads on Xtensa (L16SI) and RISC-V (LH), which cannot -// produce torn values. +// Safe: SYS_ARCH_UNPROTECT (line 3720) releases a FreeRTOS mutex, which internally +// uses a critical section with memory barrier (rsync on Xtensa), ensuring the write +// is committed before the mutex is released. The volatile cast prevents the compiler +// from caching the read. Aligned 16-bit reads are single-instruction loads on +// Xtensa (L16SI) and RISC-V (LH), which cannot produce torn values. // // FreeRTOS task notification value: // Written by TCP/IP thread (xTaskNotifyGive in callback) and background tasks