BREAKING: FreeRTOS as a define, allow full multithread/core TCP/IP (#3063)

With the expanded performance and memory of the Pico 2, having a full
operating system with threads could really improve developer life and
get the best possible algorithm performance.

This commit includes a large number of changes, all related and not
really separable into smaller bits due to the refactoring involved.
No changes should have been done to bare metal LWIP processing.

* Adds a new ` __FREERTOS` define at the IDE/platform.IO level. This
  new define is required to build FreeRTOS apps and a breaking change.

* Moves FreeRTOS into the cores/rp2040 subdirectory, allowing the core
  to use it without hokey weak-linked wrapper functions

* Splits the FreeRTOS variantHooks into multiple files focused on a
  particular bit of management instead of a random blob of stuff.

* All LWIP calls now will be wrapped into a work queue entry and
  sent to the new LWIP task.

* Enable LWIP debugging to be turned on through the menus

* New LWIP task started which handles *all* LWIP calls and Ethernet
  polling via callbacks.  This ensures that even with multiple cores
  and multiple tasks, LWIP stays in sync and only runs on core 0.
  It also ensures no LWIP processing is done at IRQ levels, allowing
  for malloc/new/free/delete calls and full API access.  The LWIP
  task also takes care of sys_check_timeouts.  It is critically
  important that *ALL* LWIP calls go through this task via the
  work queue or a crash will happen at some later point in time.
  The wrappers take care of this already for every LWIP function
  used in the core.

* Note that LWIP callbacks run in the LWIP thread and block other
  LWIP operations.  So for an absolutely parallel web server, you'd
  want to have your tcp_recv/sent/err/poll just take the response
  data and put it into a work queue for your own task and return
  before processing.

* Split Ethernet interrupt handling into an IRQ acknowledge and a
  posted message to the LWIP process to actually read out a packet.
  Adds a hardware semaphore which protects just the bits of code where
  a packet is being read of written from the HW (and not around any
  LWIP send/receive calls).

* Fix race condition in WiFiServer where under heavy load with
  multithreading a connection gets a tcp_abort just before tcp_accept
  will be called.  When we abort, we clear the this pointer, and so
  when we try and recover our object we crash.  Check for aborted
  connections (and ignore) on WiFiServer, like we do in WiFiClient.

* WiFiClient/WiFiUDP connection list (used for stopAll) adds mutex
  protection so it can safely work in parallel.

* Just panic() on FreeRTOS fatal error, don't try and be fancy and
  blink a LED.  GDB shows exactly where the crash is, now.

* Rewrite CYW43 driver for LWIP thread processing.  The SDK really
  wants to use an async_context, but that only works if the CYW43
  driver is the only one there (it handles *both* Ethernet and IP
  with the same context).  NULL out the context pointer and wrap
  the driver calls to the taskless FreeRTOS Ethernet architecture.

* Includes the async_contexts for freertos and bare metal as part
  of the core build process.  Users can use their own
  async_context_freertos if they so desire, instead of being stuck
  with the wrong one (bare metal) under FreeRTOS.

Author: earlephilhower

.github/workflows/pull-request.yml

@@ -20,8 +20,8 @@ jobs:
     - name: Run codespell
       uses: codespell-project/actions-codespell@v2
       with:
-        skip: ./ArduinoCore-API,./libraries/ESP8266SdFat,./libraries/Adafruit_TinyUSB_Arduino,./libraries/LittleFS/lib,./tools/pyserial,./pico-sdk,./.github,./docs/i2s.rst,./cores/rp2040/api,./libraries/FreeRTOS,./tools/libbearssl/bearssl,./include,./libraries/WiFi/examples/BearSSL_Server,./ota/uzlib,./libraries/http-parser/lib,./libraries/WebServer/examples/HelloServerBearSSL/HelloServerBearSSL.ino,./libraries/HTTPUpdateServer/examples/SecureBearSSLUpdater/SecureBearSSLUpdater.ino,./.git,./libraries/FatFS/lib/fatfs,./libraries/FatFS/src/diskio.h,./libraries/FatFS/src/ff.cpp,./libraries/FatFS/src/ffconf.h,./libraries/FatFS/src/ffsystem.cpp,./libraries/FatFS/src/ff.h,./libraries/lwIP_WINC1500/src/driver,./libraries/lwIP_WINC1500/src/common,./libraries/lwIP_WINC1500/src/bus_wrapper,./libraries/lwIP_WINC1500/src/spi_flash,./libraries/WiFi/examples/BearSSL_Validation/certs.h
-        ignore_words_list: ser,dout,shiftIn,acount,froms
+        skip: ./ArduinoCore-API,./libraries/ESP8266SdFat,./libraries/Adafruit_TinyUSB_Arduino,./libraries/LittleFS/lib,./tools/pyserial,./pico-sdk,./.github,./docs/i2s.rst,./cores/rp2040/api,./FreeRTOS,./tools/libbearssl/bearssl,./include,./libraries/WiFi/examples/BearSSL_Server,./ota/uzlib,./libraries/http-parser/lib,./libraries/WebServer/examples/HelloServerBearSSL/HelloServerBearSSL.ino,./libraries/HTTPUpdateServer/examples/SecureBearSSLUpdater/SecureBearSSLUpdater.ino,./.git,./libraries/FatFS/lib/fatfs,./libraries/FatFS/src/diskio.h,./libraries/FatFS/src/ff.cpp,./libraries/FatFS/src/ffconf.h,./libraries/FatFS/src/ffsystem.cpp,./libraries/FatFS/src/ff.h,./libraries/lwIP_WINC1500/src/driver,./libraries/lwIP_WINC1500/src/common,./libraries/lwIP_WINC1500/src/bus_wrapper,./libraries/lwIP_WINC1500/src/spi_flash,./libraries/WiFi/examples/BearSSL_Validation/certs.h
+        ignore_words_list: ser,dout,shiftIn,acount,froms,ThirdParty
     - name: Check boards.txt was not edited after makeboards.py
       run: |
         ./tools/makeboards.py

.gitmodules

@@ -23,7 +23,7 @@
 	path = libraries/Adafruit_TinyUSB_Arduino
 	url = https://github.com/adafruit/Adafruit_TinyUSB_Arduino.git
 [submodule "libraries/FreeRTOS/lib/FreeRTOS-Kernel"]
-	path = libraries/FreeRTOS/lib/FreeRTOS-Kernel
+	path = FreeRTOS-Kernel
 	url = https://github.com/earlephilhower/FreeRTOS-Kernel.git
 [submodule "tools/libbearssl/bearssl"]
 	path = tools/libbearssl/bearssl
@@ -49,3 +49,6 @@
 [submodule "libraries/SdFat"]
 	path = libraries/SdFat
 	url = https://github.com/greiman/SdFat.git
+[submodule "FreeRTOS-Kernel"]
+	path = FreeRTOS-Kernel
+	url = https://github.com/earlephilhower/FreeRTOS-Kernel.git

libraries/FreeRTOS/lib/FreeRTOS-Kernel renamed to FreeRTOS-Kernel

@@ -109,9 +109,6 @@ void analogWriteResolution(int res);
 } // extern "C"
 #endif
 
-// FreeRTOS potential calls
-extern bool __isFreeRTOS;
-
 // Ancient AVR defines
 #define HAVE_HWSERIAL0
 #define HAVE_HWSERIAL1

boards.txt

@@ -26,9 +26,9 @@ static bool __no_inline_not_in_flash_func(get_bootsel_button)() {
 
     // Must disable interrupts, as interrupt handlers may be in flash, and we
     // are about to temporarily disable flash access!
-    if (!__isFreeRTOS) {
-        noInterrupts();
-    }
+#ifndef __FREERTOS
+    noInterrupts();
+#endif
     rp2040.idleOtherCore();
 
     // Set chip select to Hi-Z
@@ -55,9 +55,9 @@ static bool __no_inline_not_in_flash_func(get_bootsel_button)() {
                     IO_QSPI_GPIO_QSPI_SS_CTRL_OEOVER_BITS);
 
     rp2040.resumeOtherCore();
-    if (!__isFreeRTOS) {
-        interrupts();
-    }
+#ifndef __FREERTOS
+    interrupts();
+#endif
 
     return button_state;
 }

cores/rp2040/Arduino.h

@@ -28,45 +28,46 @@ CoreMutex::CoreMutex(mutex_t *mutex, uint8_t option) {
     _mutex = mutex;
     _acquired = false;
     _option = option;
+#ifdef __FREERTOS
     _pxHigherPriorityTaskWoken = 0; // pdFALSE
-    if (__isFreeRTOS) {
-        auto m = __get_freertos_mutex_for_ptr(mutex);
+    auto m = __get_freertos_mutex_for_ptr(mutex);
 
-        if (__freertos_check_if_in_isr()) {
-            if (!__freertos_mutex_take_from_isr(m, &_pxHigherPriorityTaskWoken)) {
-                return;
-            }
-            // At this point we have the mutex in ISR
-        } else {
-            // Grab the mutex normally, possibly waking other tasks to get it
-            __freertos_mutex_take(m);
+    if (portCHECK_IF_IN_ISR()) {
+        if (!xSemaphoreTakeFromISR(m, &_pxHigherPriorityTaskWoken)) {
+            return;
         }
+        // At this point we have the mutex in ISR
     } else {
-        uint32_t owner;
-        if (!mutex_try_enter(_mutex, &owner)) {
-            if (owner == get_core_num()) { // Deadlock!
-                if (_option & DebugEnable) {
-                    DEBUGCORE("CoreMutex - Deadlock detected!\n");
-                }
-                return;
+        // Grab the mutex normally, possibly waking other tasks to get it
+        xSemaphoreTake(m, portMAX_DELAY);
+    }
+#else
+    uint32_t owner;
+    if (!mutex_try_enter(_mutex, &owner)) {
+        if (owner == get_core_num()) { // Deadlock!
+            if (_option & DebugEnable) {
+                DEBUGCORE("CoreMutex - Deadlock detected!\n");
             }
-            mutex_enter_blocking(_mutex);
+            return;
         }
+        mutex_enter_blocking(_mutex);
     }
+#endif
     _acquired = true;
 }
 
 CoreMutex::~CoreMutex() {
     if (_acquired) {
-        if (__isFreeRTOS) {
-            auto m = __get_freertos_mutex_for_ptr(_mutex);
-            if (__freertos_check_if_in_isr()) {
-                __freertos_mutex_give_from_isr(m, &_pxHigherPriorityTaskWoken);
-            } else {
-                __freertos_mutex_give(m);
-            }
+#ifdef __FREERTOS
+        auto m = __get_freertos_mutex_for_ptr(_mutex);
+        if (portCHECK_IF_IN_ISR()) {
+            xSemaphoreGiveFromISR(m, &_pxHigherPriorityTaskWoken);
+            portYIELD_FROM_ISR(_pxHigherPriorityTaskWoken);
         } else {
-            mutex_exit(_mutex);
+            xSemaphoreGive(m);
         }
+#else
+        mutex_exit(_mutex);
+#endif
     }
 }

cores/rp2040/Bootsel.cpp

@@ -43,5 +43,7 @@ class CoreMutex {
     mutex_t *_mutex;
     bool _acquired;
     uint8_t _option;
+#ifdef __FREERTOS
     BaseType_t _pxHigherPriorityTaskWoken;
+#endif
 };

cores/rp2040/CoreMutex.cpp

@@ -72,17 +72,18 @@ class _MFIFO {
     }
 
     void registerCore() {
-        if (!__isFreeRTOS) {
-            multicore_fifo_clear_irq();
+#ifndef __FREERTOS
+        multicore_fifo_clear_irq();
 #ifdef PICO_RP2350
-            irq_set_exclusive_handler(SIO_IRQ_FIFO, _irq);
-            irq_set_enabled(SIO_IRQ_FIFO, true);
+        irq_set_exclusive_handler(SIO_IRQ_FIFO, _irq);
+        irq_set_enabled(SIO_IRQ_FIFO, true);
 #else
-            irq_set_exclusive_handler(SIO_IRQ_PROC0 + get_core_num(), _irq);
-            irq_set_enabled(SIO_IRQ_PROC0 + get_core_num(), true);
+        irq_set_exclusive_handler(SIO_IRQ_PROC0 + get_core_num(), _irq);
+        irq_set_enabled(SIO_IRQ_PROC0 + get_core_num(), true);
 #endif
-        }
+#else
         // FreeRTOS port.c will handle the IRQ hooking
+#endif
     }
 
     void push(uint32_t val) {
@@ -113,14 +114,14 @@ class _MFIFO {
         if (!_multicore) {
             return;
         }
-        if (__isFreeRTOS) {
-            __freertos_idle_other_core();
-        } else {
-            mutex_enter_blocking(&_idleMutex);
-            __otherCoreIdled = false;
-            multicore_fifo_push_blocking(_GOTOSLEEP);
-            while (!__otherCoreIdled) { /* noop */ }
-        }
+#ifdef __FREERTOS
+        __freertos_idle_other_core();
+#else
+        mutex_enter_blocking(&_idleMutex);
+        __otherCoreIdled = false;
+        multicore_fifo_push_blocking(_GOTOSLEEP);
+        while (!__otherCoreIdled) { /* noop */ }
+#endif
     }
 
     void resumeOtherCore() {
@@ -129,9 +130,9 @@ class _MFIFO {
         }
         mutex_exit(&_idleMutex);
         __otherCoreIdled = false;
-        if (__isFreeRTOS) {
-            __freertos_resume_other_core();
-        }
+#ifdef __FREERTOS
+        __freertos_resume_other_core();
+#endif
 
         // Other core will exit busy-loop and return to operation
         // once __otherCoreIdled == false.
@@ -151,18 +152,18 @@ class _MFIFO {
 
 private:
     static void __no_inline_not_in_flash_func(_irq)() {
-        if (!__isFreeRTOS) {
-            multicore_fifo_clear_irq();
-            noInterrupts(); // We need total control, can't run anything
-            while (multicore_fifo_rvalid()) {
-                if (_GOTOSLEEP == multicore_fifo_pop_blocking()) {
-                    __otherCoreIdled = true;
-                    while (__otherCoreIdled) { /* noop */ }
-                    break;
-                }
+#ifndef __FREERTOS
+        multicore_fifo_clear_irq();
+        noInterrupts(); // We need total control, can't run anything
+        while (multicore_fifo_rvalid()) {
+            if (_GOTOSLEEP == multicore_fifo_pop_blocking()) {
+                __otherCoreIdled = true;
+                while (__otherCoreIdled) { /* noop */ }
+                break;
             }
-            interrupts();
         }
+        interrupts();
+#endif
     }
 
     bool _multicore = false;
@@ -192,23 +193,19 @@ class RP2040 {
 
     void begin(int cpuid) {
         _epoch[cpuid] = 0;
-#if !defined(__riscv) && !defined(__PROFILE)
-        if (!__isFreeRTOS) {
-            // Enable SYSTICK exception
-            exception_set_exclusive_handler(SYSTICK_EXCEPTION, _SystickHandler);
-            systick_hw->csr = 0x7;
-            systick_hw->rvr = 0x00FFFFFF;
-        } else {
-#endif
-            // Only start 1 instance of the PIO SM
-            if (cpuid == 0) {
-                int off = 0;
-                _ccountPgm = new PIOProgram(&ccount_program);
-                _ccountPgm->prepare(&_pio, &_sm, &off);
-                ccount_program_init(_pio, _sm, off);
-                pio_sm_set_enabled(_pio, _sm, true);
-            }
-#if !defined(__riscv) && !defined(__PROFILE)
+#if !defined(__riscv) && !defined(__PROFILE) && !defined(__FREERTOS)
+        // Enable SYSTICK exception
+        exception_set_exclusive_handler(SYSTICK_EXCEPTION, _SystickHandler);
+        systick_hw->csr = 0x7;
+        systick_hw->rvr = 0x00FFFFFF;
+#else
+        // Only start 1 instance of the PIO SM
+        if (cpuid == 0) {
+            int off = 0;
+            _ccountPgm = new PIOProgram(&ccount_program);
+            _ccountPgm->prepare(&_pio, &_sm, &off);
+            ccount_program_init(_pio, _sm, off);
+            pio_sm_set_enabled(_pio, _sm, true);
         }
 #endif
     }
@@ -255,21 +252,17 @@ class RP2040 {
         @returns CPU clock cycles since power up
     */
     inline uint32_t getCycleCount() {
-#if !defined(__riscv) && !defined(__PROFILE)
+#if !defined(__riscv) && !defined(__PROFILE) && !defined(__FREERTOS)
         // Get CPU cycle count.  Needs to do magic to extend 24b HW to something longer
-        if (!__isFreeRTOS) {
-            uint32_t epoch;
-            uint32_t ctr;
-            do {
-                epoch = (uint32_t)_epoch[sio_hw->cpuid];
-                ctr = systick_hw->cvr;
-            } while (epoch != (uint32_t)_epoch[sio_hw->cpuid]);
-            return epoch + (1 << 24) - ctr; /* CTR counts down from 1<<24-1 */
-        } else {
-#endif
-            return ccount_read(_pio, _sm);
-#if !defined(__riscv) && !defined(__PROFILE)
-        }
+        uint32_t epoch;
+        uint32_t ctr;
+        do {
+            epoch = (uint32_t)_epoch[sio_hw->cpuid];
+            ctr = systick_hw->cvr;
+        } while (epoch != (uint32_t)_epoch[sio_hw->cpuid]);
+        return epoch + (1 << 24) - ctr; /* CTR counts down from 1<<24-1 */
+#else
+        return ccount_read(_pio, _sm);
 #endif
     }
     /**
@@ -278,20 +271,16 @@ class RP2040 {
         @returns CPU clock cycles since power up
     */
     inline uint64_t getCycleCount64() {
-#if !defined(__riscv) && !defined(__PROFILE)
-        if (!__isFreeRTOS) {
-            uint64_t epoch;
-            uint64_t ctr;
-            do {
-                epoch = _epoch[sio_hw->cpuid];
-                ctr = systick_hw->cvr;
-            } while (epoch != _epoch[sio_hw->cpuid]);
-            return epoch + (1LL << 24) - ctr;
-        } else {
-#endif
-            return ccount_read(_pio, _sm);
-#if !defined(__riscv) && !defined(__PROFILE)
-        }
+#if !defined(__riscv) && !defined(__PROFILE) && !defined(__FREERTOS)
+        uint64_t epoch;
+        uint64_t ctr;
+        do {
+            epoch = _epoch[sio_hw->cpuid];
+            ctr = systick_hw->cvr;
+        } while (epoch != _epoch[sio_hw->cpuid]);
+        return epoch + (1LL << 24) - ctr;
+#else
+        return ccount_read(_pio, _sm);
 #endif
     }
 

cores/rp2040/CoreMutex.h

@@ -181,9 +181,9 @@ static int _bps = 115200;
 static bool _rebooting = false;
 static void CheckSerialReset() {
     if (!_rebooting && (_bps == 1200) && (!_dtr)) {
-        if (__isFreeRTOS) {
-            __freertos_idle_other_core();
-        }
+#ifdef __FREERTOS
+        __freertos_idle_other_core();
+#endif
         _rebooting = true;
         // Disable NVIC IRQ, so that we don't get bothered anymore
         irq_set_enabled(USBCTRL_IRQ, false);