`cyw43_arch_deinit()` corrupts FreeRTOS idle task's termination list under static allocation, causing hard fault in `uxListRemove()` #3174

New issue

Open

opened 2026-09-04 01:47:36 -05:00 by jondurrant · 0 comments

jondurrant commented

2026-09-04 01:47:36 -05:00

(Migrated from github.com)

Title

cyw43_arch_deinit() corrupts FreeRTOS idle task's termination list under static allocation, causing hard fault in uxListRemove()

Environment

pico-sdk: 2.3.0 (commit 98a542c1a6)
FreeRTOS-Kernel: v11.3.1 (bundled)
configSUPPORT_STATIC_ALLOCATION = 1
configSUPPORT_DYNAMIC_ALLOCATION = 1
configNUMBER_OF_CORES = 1 (single core)
Board: Raspberry Pi Pico W
Async context: default cyw43_arch_freertos (PICO_CYW43_ARCH_FREERTOS)

Summary

Calling cyw43_arch_init() then cyw43_arch_deinit() repeatedly from a FreeRTOS task (e.g. to power-cycle Wi-Fi between HTTP posts) reliably crashes FreeRTOS with a hard fault inside uxListRemove(), called from the idle task's prvCheckTasksWaitingTermination().

Crash trace

isr_hardfault() at crt0.S:349
<signal handler called>()
uxListRemove() at list.c:232
prvCheckTasksWaitingTermination() at tasks.c:6228
prvIdleTask() at tasks.c:5934

Root cause

With configSUPPORT_STATIC_ALLOCATION, cyw43_arch_freertos.c creates the async-context worker task with xTaskCreateStatic(), backed by StaticTask_t task_buf, a field embedded directly inside the static cyw43_async_context_freertos struct (async_context_freertos_t). This task_buf memory is the live FreeRTOS TCB for that task, not a separate copy.

In async_context_freertos_deinit() (src/rp2_common/pico_async_context/async_context_freertos.c):

if (self->task_handle) {
    async_context_execute_sync(self_base, end_task_func, self_base);
    if (self->task_complete_sem) {
        xSemaphoreTake(self->task_complete_sem, portMAX_DELAY);
    }
}
...
memset(self, 0, sizeof(*self));

Sequence of events:

end_task_func sets task_should_exit; the worker task (async_context_task) exits its loop, calls xSemaphoreGive(self->task_complete_sem), then calls vTaskDelete(NULL) on itself and yields.
vTaskDelete(NULL) does not immediately free/unlink the TCB — it moves it onto FreeRTOS's xTasksWaitingTermination list. Only the idle task, via prvCheckTasksWaitingTermination() → uxListRemove(), actually unlinks it later.
Meanwhile, async_context_freertos_deinit() (running in the caller task, which resumed once task_complete_sem was given) proceeds to memset(self, 0, sizeof(*self)). This zeroes task_buf, i.e. it wipes the TCB while it is still linked into xTasksWaitingTermination, corrupting the list's embedded pxNext/pxPrevious pointers.
The next time the idle task runs prvCheckTasksWaitingTermination(), uxListRemove() dereferences the corrupted pointers and hard-faults.

This is deterministic (not just a rare race) whenever the caller task's priority is higher than the idle task's — which is virtually always the case, since idle runs at tskIDLE_PRIORITY (0) and never gets scheduled between steps 1 and 3 to reap the TCB first. The default cyw43_arch worker task priority (ASYNC_CONTEXT_DEFAULT_FREERTOS_TASK_PRIORITY = tskIDLE_PRIORITY + 4) being higher than the app's calling task doesn't prevent this, since the corruption is caused by the caller task racing the idle task, not by the worker task itself.

This is closely related to, but distinct from, #2687 (which fixed the analogous issue for the statically-allocated FreeRTOS timer via xTimerPendFunctionCall synchronization) — the same class of bug still exists for the statically-allocated task TCB, which has no equivalent "wait until actually reaped" synchronization.

Reproduction

Minimal repro: in a FreeRTOS task, loop:

cyw43_arch_init();
WifiHelper::join(ssid, pass, 3); // or any cyw43_wifi_join
// ... do some work ...
cyw43_arch_deinit();

Crash typically occurs within the first 1-2 iterations, inside the idle task, some time after cyw43_arch_deinit() returns.

Suggested fix

In async_context_freertos_deinit(), after taking task_complete_sem, give the idle task a scheduling opportunity to reap the just-deleted task before zeroing the struct that backs its static TCB:

if (self->task_handle) {
    async_context_execute_sync(self_base, end_task_func, self_base);
    if (self->task_complete_sem) {
        xSemaphoreTake(self->task_complete_sem, portMAX_DELAY);
    }
#if configSUPPORT_STATIC_ALLOCATION
    // Let the idle task run prvCheckTasksWaitingTermination() to unlink the
    // just-deleted worker task's TCB before we zero the memory (task_buf)
    // that backs it below.
    vTaskDelay(pdMS_TO_TICKS(5));
#endif
}

A more robust fix would avoid the fixed delay and instead poll/wait until uxTaskGetNumberOfTasks() (or equivalent) confirms the task has actually been reaped, but the above resolves the crash in practice.

Files involved

src/rp2_common/pico_async_context/async_context_freertos.c (async_context_freertos_deinit)
src/rp2_common/pico_cyw43_arch/cyw43_arch_freertos.c (static task_buf allocation via cyw43_async_context_freertos)

## Title `cyw43_arch_deinit()` corrupts FreeRTOS idle task's termination list under static allocation, causing hard fault in `uxListRemove()` ## Environment - pico-sdk: 2.3.0 (commit 98a542c1a62fb549ffb5d66a3e5892b06276b670) - FreeRTOS-Kernel: v11.3.1 (bundled) - `configSUPPORT_STATIC_ALLOCATION` = 1 - `configSUPPORT_DYNAMIC_ALLOCATION` = 1 - `configNUMBER_OF_CORES` = 1 (single core) - Board: Raspberry Pi Pico W - Async context: default `cyw43_arch_freertos` (`PICO_CYW43_ARCH_FREERTOS`) ## Summary Calling `cyw43_arch_init()` then `cyw43_arch_deinit()` repeatedly from a FreeRTOS task (e.g. to power-cycle Wi-Fi between HTTP posts) reliably crashes FreeRTOS with a hard fault inside `uxListRemove()`, called from the idle task's `prvCheckTasksWaitingTermination()`. ## Crash trace ``` isr_hardfault() at crt0.S:349 <signal handler called>() uxListRemove() at list.c:232 prvCheckTasksWaitingTermination() at tasks.c:6228 prvIdleTask() at tasks.c:5934 ``` ## Root cause With `configSUPPORT_STATIC_ALLOCATION`, `cyw43_arch_freertos.c` creates the async-context worker task with `xTaskCreateStatic()`, backed by `StaticTask_t task_buf`, a field embedded directly inside the static `cyw43_async_context_freertos` struct (`async_context_freertos_t`). This `task_buf` memory *is* the live FreeRTOS TCB for that task, not a separate copy. In `async_context_freertos_deinit()` (`src/rp2_common/pico_async_context/async_context_freertos.c`): ```c if (self->task_handle) { async_context_execute_sync(self_base, end_task_func, self_base); if (self->task_complete_sem) { xSemaphoreTake(self->task_complete_sem, portMAX_DELAY); } } ... memset(self, 0, sizeof(*self)); ``` Sequence of events: 1. `end_task_func` sets `task_should_exit`; the worker task (`async_context_task`) exits its loop, calls `xSemaphoreGive(self->task_complete_sem)`, then calls `vTaskDelete(NULL)` on itself and yields. 2. `vTaskDelete(NULL)` does **not** immediately free/unlink the TCB — it moves it onto FreeRTOS's `xTasksWaitingTermination` list. Only the **idle task**, via `prvCheckTasksWaitingTermination()` → `uxListRemove()`, actually unlinks it later. 3. Meanwhile, `async_context_freertos_deinit()` (running in the caller task, which resumed once `task_complete_sem` was given) proceeds to `memset(self, 0, sizeof(*self))`. This zeroes `task_buf`, i.e. it wipes the TCB **while it is still linked into `xTasksWaitingTermination`**, corrupting the list's embedded `pxNext`/`pxPrevious` pointers. 4. The next time the idle task runs `prvCheckTasksWaitingTermination()`, `uxListRemove()` dereferences the corrupted pointers and hard-faults. This is deterministic (not just a rare race) whenever the caller task's priority is higher than the idle task's — which is virtually always the case, since idle runs at `tskIDLE_PRIORITY` (0) and never gets scheduled between steps 1 and 3 to reap the TCB first. The default `cyw43_arch` worker task priority (`ASYNC_CONTEXT_DEFAULT_FREERTOS_TASK_PRIORITY` = `tskIDLE_PRIORITY + 4`) being higher than the app's calling task doesn't prevent this, since the corruption is caused by the *caller* task racing the *idle* task, not by the worker task itself. This is closely related to, but distinct from, #2687 (which fixed the analogous issue for the statically-allocated FreeRTOS timer via `xTimerPendFunctionCall` synchronization) — the same class of bug still exists for the statically-allocated task TCB, which has no equivalent "wait until actually reaped" synchronization. ## Reproduction Minimal repro: in a FreeRTOS task, loop: ```c cyw43_arch_init(); WifiHelper::join(ssid, pass, 3); // or any cyw43_wifi_join // ... do some work ... cyw43_arch_deinit(); ``` Crash typically occurs within the first 1-2 iterations, inside the idle task, some time after `cyw43_arch_deinit()` returns. ## Suggested fix In `async_context_freertos_deinit()`, after taking `task_complete_sem`, give the idle task a scheduling opportunity to reap the just-deleted task before zeroing the struct that backs its static TCB: ```c if (self->task_handle) { async_context_execute_sync(self_base, end_task_func, self_base); if (self->task_complete_sem) { xSemaphoreTake(self->task_complete_sem, portMAX_DELAY); } #if configSUPPORT_STATIC_ALLOCATION // Let the idle task run prvCheckTasksWaitingTermination() to unlink the // just-deleted worker task's TCB before we zero the memory (task_buf) // that backs it below. vTaskDelay(pdMS_TO_TICKS(5)); #endif } ``` A more robust fix would avoid the fixed delay and instead poll/wait until `uxTaskGetNumberOfTasks()` (or equivalent) confirms the task has actually been reaped, but the above resolves the crash in practice. ## Files involved - `src/rp2_common/pico_async_context/async_context_freertos.c` (`async_context_freertos_deinit`) - `src/rp2_common/pico_cyw43_arch/cyw43_arch_freertos.c` (static `task_buf` allocation via `cyw43_async_context_freertos`)