async_context_freertos: Add support for configSUPPORT_STATIC_ALLOCATION (#2436)

* async_context_freertos: Add support for configSUPPORT_STATIC_ALLOCATION

The implementation of async_context_freertos currently assumes that
FreeRTOS has been configured with `configSUPPORT_DYNAMIC_ALLOCATION`,
which causes it to allocate semaphores, timers and tasks from the heap.
However, some projects may prefer `configSUPPORT_STATIC_ALLOCATION`,
which requires memory to be allocated ahead of time. This change allows
async_context_freertos to support either static or dynamic allocation.

The way this works is when `configSUPPORT_STATIC_ALLOCATION` is enabled,
`async_context_freertos` struct will reserve extra space for the static
objects (e.g. `StaticSemaphore_t`) and it will prefer to use the static
creation functions (e.g. `xSemaphoreCreateBinaryStatic()`). For the task
creation, the user will be responsible for allocating the stack memory
and setting the task_stack field in `async_context_freertos_config_t`.
For convenience, The `cyw43_arch_init_default_async_context()` function
will reserve `CYW43_TASK_STACK_SIZE` words of stack space in static
memory.

* Assert that task_stack is set

* Add CYW43_NO_DEFAULT_TASK_STACK

In theory you can use your own async context therefore bypassing
cyw43_arch_init_default_async_context, which would leave
cyw43_async_context_freertos_task_stack unused.

Add a #define for this rare situation.

* Update documentaton for async_context_freertos_config.task_stack

---------

Co-authored-by: Peter Harper <[email protected]>

Author: mbrase

src/rp2_common/pico_async_context/async_context_freertos.c

@@ -109,19 +109,43 @@ bool async_context_freertos_init(async_context_freertos_t *self, async_context_f
     self->core.type = &template;
     self->core.flags = ASYNC_CONTEXT_FLAG_CALLBACK_FROM_NON_IRQ;
     self->core.core_num = get_core_num();
+#if configSUPPORT_STATIC_ALLOCATION
+    assert(config->task_stack);
+    self->lock_mutex = xSemaphoreCreateRecursiveMutexStatic(&self->lock_mutex_buf);
+    self->work_needed_sem = xSemaphoreCreateBinaryStatic(&self->work_needed_sem_buf);
+    self->timer_handle = xTimerCreateStatic( "async_context_timer",       // Just a text name, not used by the kernel.
+                                             portMAX_DELAY,
+                                             pdFALSE,        // The timers will auto-reload themselves when they expire.
+                                             self,
+                                             timer_handler,
+                                             &self->timer_buf);
+    self->task_handle = xTaskCreateStatic( async_context_task,
+                                           "async_context_task",
+                                           config->task_stack_size,
+                                           self,
+                                           config->task_priority,
+                                           config->task_stack,
+                                           &self->task_buf);
+#else
     self->lock_mutex = xSemaphoreCreateRecursiveMutex();
     self->work_needed_sem = xSemaphoreCreateBinary();
     self->timer_handle = xTimerCreate( "async_context_timer",       // Just a text name, not used by the kernel.
                                     portMAX_DELAY,
                                     pdFALSE,        // The timers will auto-reload themselves when they expire.
                                     self,
                                     timer_handler);
+#endif
 
     if (!self->lock_mutex ||
         !self->work_needed_sem ||
         !self->timer_handle ||
+#if configSUPPORT_STATIC_ALLOCATION
+        !self->task_handle
+#else
         pdPASS != xTaskCreate(async_context_task, "async_context_task", config->task_stack_size, self,
-                config->task_priority, &self->task_handle)) {
+                config->task_priority, &self->task_handle)
+#endif
+    ) {
         async_context_deinit(&self->core);
         return false;
     }
@@ -179,6 +203,9 @@ void async_context_freertos_lock_check(__unused async_context_t *self_base) {
 typedef struct sync_func_call{
     async_when_pending_worker_t worker;
     SemaphoreHandle_t sem;
+#if configSUPPORT_STATIC_ALLOCATION
+    StaticSemaphore_t sem_buf;
+#endif
     uint32_t (*func)(void *param);
     void *param;
     uint32_t rc;
@@ -197,7 +224,11 @@ uint32_t async_context_freertos_execute_sync(async_context_t *self_base, uint32_
     call.worker.do_work = handle_sync_func_call;
     call.func = func;
     call.param = param;
+#if configSUPPORT_STATIC_ALLOCATION
+    call.sem = xSemaphoreCreateBinaryStatic(&call.sem_buf);
+#else
     call.sem = xSemaphoreCreateBinary();
+#endif
     async_context_add_when_pending_worker(self_base, &call.worker);
     async_context_set_work_pending(self_base, &call.worker);
     xSemaphoreTake(call.sem, portMAX_DELAY);

src/rp2_common/pico_async_context/include/pico/async_context_freertos.h

@@ -56,6 +56,12 @@ typedef struct async_context_freertos_config {
      * \brief Stack size for the async_context task
      */
     configSTACK_DEPTH_TYPE task_stack_size;
+     /**
+     * \brief Pointer to stack memory for the async_context task.
+     */
+#if configSUPPORT_STATIC_ALLOCATION
+    StackType_t *task_stack;
+#endif
     /**
      * \brief the core ID (see \ref portGET_CORE_ID()) to pin the task to.
      * This is only relevant in SMP mode.
@@ -71,6 +77,12 @@ struct async_context_freertos {
     SemaphoreHandle_t work_needed_sem;
     TimerHandle_t timer_handle;
     TaskHandle_t task_handle;
+#if configSUPPORT_STATIC_ALLOCATION
+    StaticSemaphore_t lock_mutex_buf;
+    StaticSemaphore_t work_needed_sem_buf;
+    StaticTimer_t timer_buf;
+    StaticTask_t task_buf;
+#endif
     uint8_t nesting;
     volatile bool task_should_exit;
 };

src/rp2_common/pico_cyw43_arch/cyw43_arch_freertos.c

@@ -25,13 +25,20 @@
 
 static async_context_freertos_t cyw43_async_context_freertos;
 
+#if configSUPPORT_STATIC_ALLOCATION && !CYW43_NO_DEFAULT_TASK_STACK
+static StackType_t cyw43_async_context_freertos_task_stack[CYW43_TASK_STACK_SIZE];
+#endif
+
 async_context_t *cyw43_arch_init_default_async_context(void) {
     async_context_freertos_config_t config = async_context_freertos_default_config();
 #ifdef CYW43_TASK_PRIORITY
     config.task_priority = CYW43_TASK_PRIORITY;
 #endif
 #ifdef CYW43_TASK_STACK_SIZE
     config.task_stack_size = CYW43_TASK_STACK_SIZE;
+#endif
+#if configSUPPORT_STATIC_ALLOCATION && !CYW43_NO_DEFAULT_TASK_STACK
+    config.task_stack = cyw43_async_context_freertos_task_stack;
 #endif
     if (async_context_freertos_init(&cyw43_async_context_freertos, &config))
         return &cyw43_async_context_freertos.core;

src/rp2_common/pico_cyw43_arch/include/pico/cyw43_arch/arch_freertos.h

@@ -7,6 +7,11 @@
 #ifndef _PICO_CYW43_ARCH_ARCH_FREERTOS_H
 #define _PICO_CYW43_ARCH_ARCH_FREERTOS_H
 
+// PICO_CONFIG: CYW43_NO_DEFAULT_TASK_STACK, Disables the default static allocation of the CYW43 FreeRTOS task stack, type=bool, default=0, group=pico_cyw43_arch
+#ifndef CYW43_NO_DEFAULT_TASK_STACK
+#define CYW43_NO_DEFAULT_TASK_STACK 0
+#endif
+
 // PICO_CONFIG: CYW43_TASK_STACK_SIZE, Stack size for the CYW43 FreeRTOS task in 4-byte words, type=int, default=1024, group=pico_cyw43_arch
 #ifndef CYW43_TASK_STACK_SIZE
 #define CYW43_TASK_STACK_SIZE 1024