Add W5100, W5500, and ECN28J60 interrupt-driven mode (#1986)

No polling needed and massively reduces latency by using the GPIO interrupt to
signal the Pico to read a received packet.  Also drops CPU load when no packets
are incoming.

Author: earlephilhower

cores/rp2040/lwip_wrap.cpp

@@ -33,12 +33,17 @@
 
 extern void ethernet_arch_lwip_begin() __attribute__((weak));
 extern void ethernet_arch_lwip_end() __attribute__((weak));
+extern void ethernet_arch_lwip_gpio_mask() __attribute__((weak));
+extern void ethernet_arch_lwip_gpio_unmask() __attribute__((weak));
 
 auto_init_recursive_mutex(__lwipMutex); // Only for case with no Ethernet or PicoW, but still doing LWIP (PPP?)
 
 class LWIPMutex {
 public:
     LWIPMutex() {
+        if (ethernet_arch_lwip_gpio_mask)  {
+            ethernet_arch_lwip_gpio_mask();
+        }
 #if defined(ARDUINO_RASPBERRY_PI_PICO_W)
         if (rp2040.isPicoW()) {
             cyw43_arch_lwip_begin();
@@ -56,13 +61,18 @@ class LWIPMutex {
 #if defined(ARDUINO_RASPBERRY_PI_PICO_W)
         if (rp2040.isPicoW()) {
             cyw43_arch_lwip_end();
-            return;
+        } else {
+#endif
+            if (ethernet_arch_lwip_end) {
+                ethernet_arch_lwip_end();
+            } else {
+                recursive_mutex_exit(&__lwipMutex);
+            }
+#if defined(ARDUINO_RASPBERRY_PI_PICO_W)
         }
 #endif
-        if (ethernet_arch_lwip_end) {
-            ethernet_arch_lwip_end();
-        } else {
-            recursive_mutex_exit(&__lwipMutex);
+        if (ethernet_arch_lwip_gpio_unmask) {
+            ethernet_arch_lwip_gpio_unmask();
         }
     }
 };

docs/ethernet.rst

@@ -86,6 +86,19 @@ Pico may not have enough time to service the Ethernet port before the timer fire
 leading to a lock up and hang.
 
 
+Using Interrupt-Driven Handling
+-------------------------------
+
+The WizNet and ENC28J60 devices support generating an interrupt when a packet is received,
+removing the need for polling and decreasing latency.  Simply specify the SPI object to use and the
+interrupt pin when instantiating the Ethernet object:
+
+.. code:: cpp
+
+    #include <W5100lwIP.h>
+    Wiznet5100lwIP eth(SS /* Chip Select*/, SPI /* SPI interface */, 17 /* Interrupt GPIO */ );
+
+
 Adjusting SPI Speed
 -------------------
 
@@ -114,12 +127,12 @@ For example, to set the W5500 to use a 30MHZ clock:
 Using the WIZnet W5100S-EVB-Pico
 --------------------------------
 
-You can use the onboard Ethernet chip with these drivers by utilizing the following options:
+You can use the onboard Ethernet chip with these drivers, in interrupt mode, by utilizing the following options:
 
 .. code:: cpp
 
     #include <W5100lwIP.h>
-    Wiznet5100lwIP eth(17);  // Note chip select is **17**
+    Wiznet5100lwIP eth(17, SPI, 21);  // Note chip select is **17**
 
     void setup() {
         // Set SPI to the onboard Wiznet chip

libraries/lwIP_Ethernet/src/LwipEthernet.cpp

@@ -72,6 +72,45 @@ void __removeEthernetPacketHandler(int id) {
     ethernet_arch_lwip_end();
 }
 
+#define GPIOSTACKSIZE 8
+static uint32_t gpioMaskStack[GPIOSTACKSIZE][4];
+static uint32_t gpioMask[4] = {0xffffffff, 0xffffffff, 0xffffffff, 0xffffffff};
+
+void ethernet_arch_lwip_gpio_mask() {
+    noInterrupts();
+    memmove(gpioMaskStack[1], gpioMaskStack[0], 4 * sizeof(uint32_t) * (GPIOSTACKSIZE - 1)); // Push down the stack
+    io_irq_ctrl_hw_t *irq_ctrl_base = get_core_num() ? &iobank0_hw->proc1_irq_ctrl : &iobank0_hw->proc0_irq_ctrl;
+    for (int i = 0; i < 4; i++) {
+        gpioMaskStack[0][i] = irq_ctrl_base->inte[i];
+        irq_ctrl_base->inte[i] = irq_ctrl_base->inte[i] & gpioMask[i];
+    }
+    interrupts();
+}
+
+void ethernet_arch_lwip_gpio_unmask() {
+    noInterrupts();
+    io_irq_ctrl_hw_t *irq_ctrl_base = get_core_num() ? &iobank0_hw->proc1_irq_ctrl : &iobank0_hw->proc0_irq_ctrl;
+    for (int i = 0; i < 4; i++) {
+        irq_ctrl_base->inte[i] = gpioMaskStack[0][i];
+    }
+    memmove(gpioMaskStack[0], gpioMaskStack[1],  4 * sizeof(uint32_t) * (GPIOSTACKSIZE - 1)); // Pop up the stack
+    interrupts();
+}
+
+// To be called after IRQ is set, so we can just rad from the IOREG instead of duplicating the calculation
+void __addEthernetGPIO(int pin) {
+    int idx = pin / 8;
+    int off = (pin % 8) * 4;
+    gpioMask[idx] &= ~(0xf << off);
+}
+
+void __removeEthernetGPIO(int pin) {
+    int idx = pin / 8;
+    int off = (pin % 8) * 4;
+    gpioMask[idx] |= 0xf << off;
+}
+
+
 static volatile bool _dns_lookup_pending = false;
 
 static void _dns_found_callback(const char *name, const ip_addr_t *ipaddr, void *callback_arg) {
@@ -134,6 +173,7 @@ static uint32_t _pollingPeriod = 20;
 static void ethernet_timeout_reached(__unused async_context_t *context, __unused async_at_time_worker_t *worker) {
     assert(worker == &ethernet_timeout_worker);
     __ethernet_timeout_reached_calls++;
+    ethernet_arch_lwip_gpio_mask(); // Ensure non-polled devices won't interrupt us
     for (auto handlePacket : _handlePacketList) {
         handlePacket.second();
     }
@@ -144,6 +184,7 @@ static void ethernet_timeout_reached(__unused async_context_t *context, __unused
 #else
     sys_check_timeouts();
 #endif
+    ethernet_arch_lwip_gpio_unmask();
 }
 
 static void update_next_timeout(async_context_t *context, async_when_pending_worker_t *worker) {

libraries/lwIP_Ethernet/src/LwipEthernet.h

@@ -27,6 +27,11 @@
 
 void ethernet_arch_lwip_begin() __attribute__((weak));
 void ethernet_arch_lwip_end() __attribute__((weak));
+void ethernet_arch_lwip_gpio_mask() __attribute__((weak));
+void ethernet_arch_lwip_gpio_unmask() __attribute__((weak));
+
+void __addEthernetGPIO(int pin);
+void __removeEthernetGPIO(int pin);
 
 // Internal Ethernet helper functions
 void __startEthernetContext();

libraries/lwIP_Ethernet/src/LwipIntfDev.h

@@ -144,6 +144,7 @@ class LwipIntfDev: public LwipIntf, public RawDev {
         return _packetsSent;
     }
 
+
     // ESP8266WiFi API compatibility
 
     wl_status_t status();
@@ -156,6 +157,7 @@ class LwipIntfDev: public LwipIntf, public RawDev {
     static err_t netif_init_s(netif* netif);
     static err_t linkoutput_s(netif* netif, struct pbuf* p);
     static void  netif_status_callback_s(netif* netif);
+    static void _irq(void *param);
 public:
     // called on a regular basis or on interrupt
     err_t handlePackets();
@@ -358,7 +360,9 @@ bool LwipIntfDev<RawDev>::begin(const uint8_t* macAddress, const uint16_t mtu) {
         return false;
     }
 
-    _phID = __addEthernetPacketHandler([this] { this->handlePackets(); });
+    if (_intrPin < 0) {
+        _phID = __addEthernetPacketHandler([this] { this->handlePackets(); });
+    }
 
     if (localIP().v4() == 0) {
         // IP not set, starting DHCP
@@ -393,7 +397,11 @@ bool LwipIntfDev<RawDev>::begin(const uint8_t* macAddress, const uint16_t mtu) {
 
     if (_intrPin >= 0) {
         if (RawDev::interruptIsPossible()) {
-            // attachInterrupt(_intrPin, [&]() { this->handlePackets(); }, FALLING);
+            noInterrupts(); // Ensure this is atomically set up
+            pinMode(_intrPin, INPUT);
+            attachInterruptParam(_intrPin, _irq, LOW, (void*)this);
+            __addEthernetGPIO(_intrPin);
+            interrupts();
         } else {
             ::printf((PGM_P)F(
                          "lwIP_Intf: Interrupt not implemented yet, enabling transparent polling\r\n"));
@@ -406,7 +414,12 @@ bool LwipIntfDev<RawDev>::begin(const uint8_t* macAddress, const uint16_t mtu) {
 
 template<class RawDev>
 void LwipIntfDev<RawDev>::end() {
-    __removeEthernetPacketHandler(_phID);
+    if (_intrPin < 0) {
+        __removeEthernetPacketHandler(_phID);
+    } else {
+        detachInterrupt(_intrPin);
+        __removeEthernetGPIO(_intrPin);
+    }
 
     RawDev::end();
 
@@ -415,6 +428,14 @@ void LwipIntfDev<RawDev>::end() {
     _started = false;
 }
 
+template<class RawDev>
+void LwipIntfDev<RawDev>::_irq(void *param) {
+    LwipIntfDev *d = static_cast<LwipIntfDev*>(param);
+    ethernet_arch_lwip_begin();
+    d->handlePackets();
+    sys_check_timeouts();
+    ethernet_arch_lwip_end();
+}
 
 template<class RawDev>
 wl_status_t LwipIntfDev<RawDev>::status() {

libraries/lwIP_enc28j60/src/utility/enc28j60.cpp

@@ -69,6 +69,9 @@
 #define ECON2_AUTOINC 0x80
 #define ECON2_PKTDEC 0x40
 
+#define EIE_PKTIE 0x40
+#define EIE_INTIE 0x80
+
 #define EIR_TXIF 0x08
 
 #define ERXTX_BANK 0x00
@@ -153,8 +156,7 @@
 // The ENC28J60 SPI Interface supports clock speeds up to 20 MHz
 static const SPISettings spiSettings(20000000, MSBFIRST, SPI_MODE0);
 
-ENC28J60::ENC28J60(int8_t cs, SPIClass& spi, int8_t intr) : _bank(ERXTX_BANK), _cs(cs), _spi(spi) {
-    (void)intr;
+ENC28J60::ENC28J60(int8_t cs, SPIClass& spi, int8_t intr) : _bank(ERXTX_BANK), _cs(cs), _intr(intr), _spi(spi) {
 }
 
 void ENC28J60::enc28j60_arch_spi_select(void) {
@@ -488,6 +490,12 @@ bool ENC28J60::reset(void) {
     /* Turn on autoincrement for buffer access */
     setregbitfield(ECON2, ECON2_AUTOINC);
 
+    /* Enable interrupt on packet receive if desired */
+    if (_intr >= 0) {
+        setregbitfield(EIE, EIE_PKTIE);
+        setregbitfield(EIE, EIE_INTIE);
+    }
+
     /* Turn on reception */
     writereg(ECON1, ECON1_RXEN);
 
@@ -511,6 +519,8 @@ bool ENC28J60::begin(const uint8_t* address, netif *net) {
 uint16_t ENC28J60::sendFrame(const uint8_t* data, uint16_t datalen) {
     uint16_t dataend;
 
+    ethernet_arch_lwip_gpio_mask(); // So we don't fire an IRQ and interrupt the send w/a receive!
+
     /*
         1. Appropriately program the ETXST pointer to point to an unused
          location in memory. It will point to the per packet control
@@ -582,6 +592,8 @@ uint16_t ENC28J60::sendFrame(const uint8_t* data, uint16_t datalen) {
     }
 #endif
 
+    ethernet_arch_lwip_gpio_unmask();
+
     // sent_packets++;
     // PRINTF("enc28j60: sent_packets %d\n", sent_packets);
     return datalen;

libraries/lwIP_enc28j60/src/utility/enc28j60.h

@@ -99,7 +99,7 @@ class ENC28J60 {
     netif *_netif;
 protected:
     static constexpr bool interruptIsPossible() {
-        return false;
+        return true;
     }
 
     /**
@@ -154,6 +154,7 @@ class ENC28J60 {
 
     uint8_t   _bank;
     int8_t    _cs;
+    int8_t    _intr;
     SPIClass& _spi;
 
     const uint8_t* _localMac;

libraries/lwIP_w5100/examples/WiFiClient-W5100/WiFiClient-W5100.ino

@@ -9,6 +9,8 @@ const char* host = "djxmmx.net";
 const uint16_t port = 17;
 
 Wiznet5100lwIP eth(1 /* chip select */);
+// To use Interrupt-driven mode, pass in an SPI object and an IRQ pin like so:
+// Wiznet5100lwIP eth(17, SPI, 21);
 
 void setup() {
   // Set up SPI pinout to match your HW

libraries/lwIP_w5100/src/utility/w5100.cpp

@@ -34,6 +34,7 @@
 
 #include <SPI.h>
 #include "w5100.h"
+#include <LwipEthernet.h>
 
 uint8_t Wiznet5100::wizchip_read(uint16_t address) {
     uint8_t ret;
@@ -178,8 +179,7 @@ void Wiznet5100::wizchip_sw_reset() {
     setSHAR(_mac_address);
 }
 
-Wiznet5100::Wiznet5100(int8_t cs, SPIClass& spi, int8_t intr) : _spi(spi), _cs(cs) {
-    (void)intr;
+Wiznet5100::Wiznet5100(int8_t cs, SPIClass& spi, int8_t intr) : _spi(spi), _cs(cs), _intr(intr) {
 }
 
 bool Wiznet5100::begin(const uint8_t* mac_address, netif *net) {
@@ -189,13 +189,6 @@ bool Wiznet5100::begin(const uint8_t* mac_address, netif *net) {
     pinMode(_cs, OUTPUT);
     wizchip_cs_deselect();
 
-#if 0
-    _spi.begin();
-    _spi.setClockDivider(SPI_CLOCK_DIV4); // 4 MHz?
-    _spi.setBitOrder(MSBFIRST);
-    _spi.setDataMode(SPI_MODE0);
-#endif
-
     wizchip_sw_reset();
 
     // Set the size of the Rx and Tx buffers
@@ -213,6 +206,11 @@ bool Wiznet5100::begin(const uint8_t* mac_address, netif *net) {
         return false;
     }
 
+    if (_intr >= 0) {
+        setSn_IR(0xff); // Clear everything
+        setIMR(IM_IR0);
+    }
+
     // Success
     return true;
 }
@@ -245,6 +243,8 @@ uint16_t Wiznet5100::readFrame(uint8_t* buffer, uint16_t bufsize) {
 }
 
 uint16_t Wiznet5100::readFrameSize() {
+    setSn_IR(Sn_IR_RECV);
+
     uint16_t len = getSn_RX_RSR();
 
     if (len == 0) {
@@ -273,25 +273,18 @@ uint16_t Wiznet5100::readFrameData(uint8_t* buffer, uint16_t framesize) {
     wizchip_recv_data(buffer, framesize);
     setSn_CR(Sn_CR_RECV);
 
-#if 1
     // let lwIP deal with mac address filtering
     return framesize;
-#else
-    // W5100 doesn't have any built-in MAC address filtering
-    if ((buffer[0] & 0x01) || memcmp(&buffer[0], _mac_address, 6) == 0) {
-        // Addressed to an Ethernet multicast address or our unicast address
-        return framesize;
-    } else {
-        return 0;
-    }
-#endif
 }
 
 uint16_t Wiznet5100::sendFrame(const uint8_t* buf, uint16_t len) {
+    ethernet_arch_lwip_gpio_mask(); // So we don't fire an IRQ and interrupt the send w/a receive!
+
     // Wait for space in the transmit buffer
     while (1) {
         uint16_t freesize = getSn_TX_FSR();
         if (getSn_SR() == SOCK_CLOSED) {
+            ethernet_arch_lwip_gpio_unmask();
             return -1;
         }
         if (len <= freesize) {
@@ -311,9 +304,11 @@ uint16_t Wiznet5100::sendFrame(const uint8_t* buf, uint16_t len) {
         } else if (tmp & Sn_IR_TIMEOUT) {
             setSn_IR(Sn_IR_TIMEOUT);
             // There was a timeout
+            ethernet_arch_lwip_gpio_unmask();
             return -1;
         }
     }
 
+    ethernet_arch_lwip_gpio_unmask();
     return len;
 }