esp_websocket_client: Add Kconfig options for PSRAM allocation (IDFGH-17011) #980

shardt68 · 2025-12-29T10:59:10Z

Description

This PR introduces two new Kconfig options to the esp_websocket_client component to allow memory allocation in external RAM (PSRAM):

ESP_WS_CLIENT_TASK_STACK_IN_EXT_RAM: Enables allocation of the WebSocket task stack in PSRAM using xTaskCreateStaticPinnedToCore.
ESP_WS_CLIENT_ALLOC_IN_EXT_RAM: Enables allocation of the esp_websocket_client structure and its internal configuration storage in PSRAM.

Motivation

In applications requiring multiple concurrent secure connections (e.g., TLS/HTTPS), internal RAM is a critical bottleneck. Each TLS session typically requires 16-20KB of internal RAM for buffers. By allowing the WebSocket client's task stack and internal structures to be moved to PSRAM, significant internal memory is freed for these critical network operations, improving overall system stability and preventing ESP_ERR_NO_MEM failures in memory-constrained scenarios.

Implementation Details

Uses heap_caps_calloc with MALLOC_CAP_SPIRAM for the client structure and config.
Implements xTaskCreateStaticPinnedToCore for the task stack when PSRAM is selected.
Safety: Includes a fallback mechanism that reverts to internal RAM allocation if PSRAM allocation fails at runtime.
Compatibility: The default behavior remains unchanged (internal RAM allocation).

Testing

Hardware: Tested on ESP32-S3 (8MB Octal PSRAM).
Scenario: Verified stable WebSocket connection while simultaneously performing multiple concurrent HTTPS/TLS requests to external APIs.
Memory Verification: Confirmed via heap_caps_get_free_size that internal RAM usage decreased by the expected amount (~5KB for structure + stack size).
Stability: Verified correct task startup and proper resource cleanup during client destruction.
Fallback Test: Verified that the client still initializes correctly on a device with PSRAM disabled/unavailable by falling back to internal RAM.

Note

Enables optional PSRAM usage and improves lifecycle safety for the WebSocket client.

New Kconfig options: ESP_WS_CLIENT_TASK_STACK_IN_EXT_RAM and ESP_WS_CLIENT_ALLOC_IN_EXT_RAM to allocate task stack and client/config in PSRAM
PSRAM-backed task creation: Uses xTaskCreateStaticPinnedToCore with PSRAM stack and internal-RAM TCB; falls back to internal RAM if allocation fails
Resource tracking/cleanup: Adds task_stack_buffer and task_buffer fields; ensures they are freed; clears status_bits after deletion
Safer destroy/stop flow: Introduces DESTRUCTION_IN_PROGRESS_BIT, defers self-destruction via ws_destroy task, suspends task before deletion, and prevents double-destroy; stop_wait_task now waits for suspension then deletes the task
Minor robustness: improved checks/logging and consistent state/bit handling during close and shutdown

^{Written by Cursor Bugbot for commit 391fb0b. This will update automatically on new commits. Configure here.}

CLAassistant · 2025-12-29T10:59:18Z

All committers have signed the CLA.

cursor

This PR is being reviewed by Cursor Bugbot

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

components/esp_websocket_client/esp_websocket_client.c

- Added CONFIG_ESP_WS_CLIENT_TASK_STACK_IN_EXT_RAM to allow allocating WebSocket task stack in PSRAM. - Added CONFIG_ESP_WS_CLIENT_ENABLE_DYNAMIC_BUFFER to allow dynamic allocation of RX/TX buffers. - Fixed memory leak in esp_websocket_client_destroy by deferring destruction to a separate task when called from the WebSocket task itself. - Fixed stack size calculation for xTaskCreateStaticPinnedToCore (expecting words). - Fixed race conditions and use-after-free in task destruction by using vTaskSuspend + vTaskDelete pattern instead of self-deletion. - Fixed double-free race condition in destroy_on_exit where manual destroy could race with deferred destruction. - Fixed deferred destruction never completing when called from task. - Fixed suspended task leak when STOPPED_BIT is already set.

shardt68 · 2026-01-23T18:34:06Z

Hi @gabsuren,

I wanted to follow up on this PR to see if there is any feedback or if any additional information is needed from my side to move this forward.

These changes are quite important for memory-constrained applications using multiple concurrent TLS/HTTPS connections (like Spotify Connect implementations). By allowing the WebSocket task stack and client structure to be moved to PSRAM, we can significantly free up critical internal RAM.

Beyond the memory allocation, this PR also introduces a more robust lifecycle management (using DESTRUCTION_IN_PROGRESS_BIT and deferred task deletion). This hardening has proven to be very stable and effectively prevents race conditions during rapid reconnect/destroy cycles that were previously an issue.

The branch is currently conflict-free and has been extensively tested on ESP32-S3. Looking forward to your thoughts!

gabsuren added the websocket label Dec 29, 2025