Use static FreeRTOS task creation for forte threads

Migrates CFreeRTOSThread to xTaskCreateStatic(), explicitly allocating stack memory (StackType_t array via new) and TCB (StaticTask_t via pvPortMalloc). This eliminates reliance on FreeRTOS's internal heap for task creation, improving determinism and avoiding heap fragmentation.

On systems with PSRAM (e.g. ESP32-S3), the stack can be placed in PSRAM while the TCB is guaranteed to remain in internal SRAM via pvPortMalloc(), which FreeRTOS requires. Internal SRAM is scarce; future extensions (OPC-UA for example) will require moving more data to the heap — controllers in the field will otherwise stop working once SRAM is exhausted.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Author: 2 people

core/arch/common/include/forte/arch/threadbase.h

@@ -90,6 +90,10 @@ namespace forte::arch {
       }
 
     protected:
+      constexpr long getStackSize() const {
+        return mStackSize;
+      }
+
       explicit CThreadBase(long paStackSize);
 
       virtual ~CThreadBase();
@@ -136,6 +140,7 @@ namespace forte::arch {
 
       /*! \brief create the thread and return a handle to it
        *
+       * @param paStackSize size of the stack in bytes to allocate for this thread
        * @return handle to the newly created thread
        */
       virtual TThreadHandleType createThread(long paStackSize) = 0;

core/arch/freeRTOS/include/forte/arch/forte_thread.h

@@ -1,5 +1,5 @@
 /************************************************************************************
- * Copyright (c) 2016 fortiss GmbH
+ * Copyright (c) 2016 fortiss GmbH, HR Agartechnik GmbH
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License 2.0 which is available at
  * http://www.eclipse.org/legal/epl-2.0.
@@ -15,6 +15,8 @@
 
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
+#include <memory>
+#include <vector>
 
 #include "forte/datatype.h"
 #include "forte/util/devlog.h"
@@ -63,7 +65,6 @@ namespace forte::arch {
        *
        * @param pa_miliSeconds The miliseconds for the thread to sleep
        */
-
       static void sleepThread(unsigned int paMilliSeconds);
 
     protected:
@@ -87,7 +88,23 @@ namespace forte::arch {
        */
       virtual TThreadHandleType createThread(long paStackSize);
 
+      /*! \brief Convert a stack size in bytes to a FreeRTOS stack depth in words.
+       *
+       * FreeRTOS expects the stack depth as the number of StackType_t words, not bytes.
+       * @param paStackSize stack size in bytes
+       * @return stack depth in StackType_t words
+       */
+      constexpr size_t getStackDepth() {
+        return static_cast<size_t>(getStackSize()) / sizeof(StackType_t);
+      }
+
+      void deleteFreeRTOSTask();
+
       static const int scmForteTaskPriority;
+
+      std::vector<StackType_t> mFreeRTOSStack;
+      std::unique_ptr<StaticTask_t, decltype([](StaticTask_t *paTask) { vPortFree(paTask); })> mTask;
+      TaskHandle_t mFreeRTOSThreadHandle = nullptr;
   };
 
   typedef CFreeRTOSThread CThread; // allows that doxygen can generate better documenation

core/arch/freeRTOS/src/forte_thread.cpp

@@ -1,5 +1,5 @@
 /************************************************************************************
- * Copyright (c) 2016 - 2018 fortiss GmbH
+ * Copyright (c) 2016 fortiss GmbH, HR Agartechnik GmbH
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License 2.0 which is available at
  * http://www.eclipse.org/legal/epl-2.0.
@@ -20,32 +20,65 @@ namespace forte::arch {
    */
   const int CFreeRTOSThread::scmForteTaskPriority = tskIDLE_PRIORITY + 4;
 
-  CFreeRTOSThread::CFreeRTOSThread(long paStackSize) : CThreadBase(paStackSize) {
+  CFreeRTOSThread::CFreeRTOSThread(long paStackSize) :
+      CThreadBase(paStackSize),
+      mFreeRTOSStack(getStackDepth()),
+      /* Allocate the TCB via pvPortMalloc(), not as a member or via new, because
+       * on systems with PSRAM (e.g. ESP32-S3) the CFreeRTOSThread object itself
+       * may reside in PSRAM. FreeRTOS requires the TCB to be in internal SRAM;
+       * pvPortMalloc() guarantees MALLOC_CAP_INTERNAL on ESP-IDF. */
+      mTask{static_cast<StaticTask_t *>(pvPortMalloc(sizeof(StaticTask_t)))} {
+  }
+
+  void CFreeRTOSThread::deleteFreeRTOSTask() {
+    if (mFreeRTOSThreadHandle != nullptr) {
+      /* On SMP (dual-core ESP32) there is a narrow window between runThread() signalling
+       * mJoinSem and threadFunction() actually reaching vTaskDelay(). Calling vTaskDelete
+       * on a Running task across cores hangs on ESP-IDF SMP, so we wait. */
+      while (eTaskGetState(mFreeRTOSThreadHandle) == eRunning) {
+        vTaskDelay(1);
+      }
+      vTaskDelete(mFreeRTOSThreadHandle);
+      mFreeRTOSThreadHandle = nullptr;
+    }
   }
 
   CFreeRTOSThread::~CFreeRTOSThread() {
+    end();
+    /* After end(), run() has returned and join() completed, but the FreeRTOS task is
+     * still alive and parked in vTaskDelay(). Delete it now that TCB and stack are no
+     * longer needed. */
+    deleteFreeRTOSTask();
   }
 
   void CFreeRTOSThread::threadFunction(void *paData) {
-    CThreadBase::runThread(static_cast<CFreeRTOSThread *>(paData));
-    /* Tasks must not attempt to return from their implementing
-     function or otherwise exit.
-     https://www.freertos.org/implementing-a-FreeRTOS-task.html */
-    vTaskDelete(nullptr);
+    auto paThreadInst = static_cast<CFreeRTOSThread *>(paData);
+    CThreadBase::runThread(paThreadInst);
+    /* join() is notified via mJoinSem.inc() inside runThread(), before we reach here.
+     * Park the task so the TCB and stack remain valid until ~CFreeRTOSThread()
+     * calls vTaskDelete() after join() has returned. */
+    vTaskDelay(portMAX_DELAY);
   }
 
   CThreadBase<TaskHandle_t, TaskHandle_t(0), CFreeRTOSThread>::TThreadHandleType
   CFreeRTOSThread::createThread(long paStackSize) {
-    TaskHandle_t handle = 0;
+    if (mFreeRTOSStack.empty() || !mTask) {
+      DEVLOG_ERROR("Error: Could not allocate memory for FreeRTOS Task!\n");
+      return TaskHandle_t(0);
+    }
 
-    if (pdPASS != xTaskCreate(threadFunction, "FORTE", paStackSize, this, scmForteTaskPriority, &handle)) {
+    /* Clean up any previously parked task before creating a new one (restart case). */
+    deleteFreeRTOSTask();
+    mFreeRTOSThreadHandle = xTaskCreateStatic(threadFunction, "FORTE", mFreeRTOSStack.size(), this,
+                                              scmForteTaskPriority, mFreeRTOSStack.data(), mTask.get());
+    if (mFreeRTOSThreadHandle == nullptr) {
       DEVLOG_ERROR("Error: Could not create FreeRTOS Task thread!");
     }
-
-    return handle;
+    return mFreeRTOSThreadHandle;
   }
 
   void CFreeRTOSThread::sleepThread(unsigned int paMilliSeconds) {
     vTaskDelay(pdMS_TO_TICKS(paMilliSeconds));
   }
+
 } // namespace forte::arch

core/arch/freeRTOS/src/main.cpp

@@ -1,5 +1,5 @@
 /************************************************************************************
- * Copyright (c) 2016, 2024 fortiss GmbH, Jose Cabral
+ * Copyright (c) 2016, 2024 fortiss GmbH, Jose Cabral, HR Agartechnik GmbH
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License 2.0 which is available at
  * http://www.eclipse.org/legal/epl-2.0.
@@ -14,6 +14,7 @@
 #include <freertos/task.h>
 
 #include "../c_interface/forte_c.h"
+#include "forte/util/devlog.h"
 
 namespace {
   const unsigned forteTaskPriority = tskIDLE_PRIORITY + 1;
@@ -43,7 +44,9 @@ int main() {
     return result;
   }
 
-  xTaskCreate(vForteTask, "forte", stackDepth, nullptr, forteTaskPriority, nullptr);
+  if (pdPASS != xTaskCreate(vForteTask, "forte", stackDepth, nullptr, forteTaskPriority, nullptr)) {
+    DEVLOG_ERROR("Failed to create forte task");
+  }
 
   vTaskStartScheduler();