Chapter 4. API Guides
• Enabling Newlib nano formatting will reduce the stack usage of any task that calls printf() or other C string
formatting functions.
• Avoid allocating large variables on the stack. In C, any large struct or array allocated as an“automatic”variable
(i.e. default scope of a C declaration) will use space on the stack. Minimize the sizes of these, allocate them
statically and/or see if you can save memory by allocating them from the heap only when they are needed.
• Avoid deep recursive function calls. Individual recursive function calls don’t always add a lot of stack usage
each time they are called, but if each function includes large stack-based variables then the overhead can get
quite high.
• At runtime, call the function uxTaskGetStackHighWaterMark() with the handle of any task where
you think there is unused stack memory. This function returns the minimum lifetime free stack mem-
ory in bytes. The easiest time to call this is from the task itself: call uxTaskGetStackHighWater-
Mark(NULL) to get the current task’s high water mark after the time that the task has achieved its peak
stack usage (i.e. if there is a main loop, execute the main loop a number of times with all possible states and
then call uxTaskGetStackHighWaterMark()). Often, it’s possible to subtract almost the entire value
returned here from the total stack size of a task, but allow some safety margin to account for unexpected small
increases in stack usage at runtime.
• Call uxTaskGetSystemState() at runtime to get a summary of all tasks in the system. This includes
their individual stack “high watermark”values.
• When debugger watchpoints are not being used, set the CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK
option to trigger an immediate panic if a task writes the word at the end of its assigned stack. This is slightly
more reliable than the default CONFIG_FREERTOS_CHECK_STACKOVERFLOW option of “Check using
canary bytes”, because the panic happens immediately, not on the next RTOS context switch. Neither option
is perfect, it’s possible in some cases for stack pointer to skip the watchpoint or canary bytes and corrupt
another region of RAM, instead.
Internal Stack Sizes ESP-IDF allocates a number of internal tasks for housekeeping purposes or operating system
functions. Some are created during the startup process, and some are created at runtime when particular features are
initialized.
The default stack sizes for these tasks are usually set conservatively high, to allow all common usage patterns. Many
of the stack sizes are configurable, and it may be possible to reduce them to match the real runtime stack usage of
the task.
Important: If internal task stack sizes are set too small, ESP-IDF will crash unpredictably. Even if the root cause
is task stack overflow, this is not always clear when debugging. It is recommended that internal stack sizes are only
reduced carefully (if at all), with close attention to “high water mark”free space under load. If reporting an issue
that occurs when internal task stack sizes have been reduced, please always include this information and the specific
configuration that is being used.
• Main task that executes app_main function has stack size CONFIG_ESP_MAIN_TASK_STACK_SIZE.
• High Resolution Timer system task which executes callbacks has stack size CON-
FIG_ESP_TIMER_TASK_STACK_SIZE.
• FreeRTOS Timer Task to handle FreeRTOS timer callbacks has stack size CON-
FIG_FREERTOS_TIMER_TASK_STACK_DEPTH.
• Event Handling system task to execute callbacks for the default system event loop has stack size CON-
FIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE.
• lwIP TCP/IP task has stack size CONFIG_LWIP_TCPIP_TASK_STACK_SIZE
• The Ethernet driver creates a task for the MAC to receive Ethernet frames. If using the default config
ETH_MAC_DEFAULT_CONFIG then the task stack size is 4 KB. This setting can be changed by passing
a custom eth_mac_config_t struct when initializing the Ethernet MAC.
• FreeRTOS idle task stack size is configured by CONFIG_FREERTOS_IDLE_TASK_STACKSIZE.
• If using the mDNS and/or MQTT components, they create tasks with stack sizes configured by CON-
FIG_MDNS_TASK_STACK_SIZE and CONFIG_MQTT_TASK_STACK_SIZE, respectively. MQTT stack size
can also be configured using task_stack field of esp_mqtt_client_config_t.
Note: Aside from built-in system features such as esp-timer, if an ESP-IDF feature is not initialized by the firmware
Espressif Systems 1453
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General