Task Management

Thread lifecycle control and secure task spawn utilities. More...

Functions
esp_err_t	eif_task_common_spawn (TaskHandle_t *const p_handle, const TaskFunction_t f_worker, const char *const p_name, const uint32_t u32_stack, const UBaseType_t u_prio)
	Common helper for secure FreeRTOS task spawning. More...
esp_err_t	eif_task_reboot_launch (void)
	Spawns an asynchronous task to execute a system reboot. More...
esp_err_t	eif_task_wifi_test_launch (uint8_t profile_index)
	Spawns an asynchronous task to execute a Wi-Fi profile test. More...
esp_err_t	eif_task_tls_recreate_launch (void)
	Spawns an asynchronous task to regenerate TLS credentials. More...
esp_err_t	eif_task_rollback_and_reboot_launch (void)
	Spawns an asynchronous task to execute a firmware rollback. More...

Detailed Description

This group establishes a unified, deterministic framework for spawning and managing FreeRTOS tasks within the ecosystem. It enforces strict input verification, runtime state validation, and centralized resource allocation boundaries. By formalizing task initialization paths, this subsystem eliminates generic firmware vulnerabilities such as race conditions during initialization, unhandled allocation failures, and orphan tasks causing heap fragmentation.

Warning

In the future, the documentation will be restored to its normal form.

Note

Before calling any function in this group, eif_core_initialize() must be executed exactly once.

Examples:

#include <esp_err.h>
#include <esp_iot_framework_core.h>
 
void app_main(void) {
    ESP_ERROR_CHECK(eif_core_initialize());
   
    // Further code...
}

Function Documentation

eif_task_common_spawn()

esp_err_t eif_task_common_spawn	(	TaskHandle_t *const	p_handle,
		const TaskFunction_t	f_worker,
		const char *const	p_name,
		const uint32_t	u32_stack,
		const UBaseType_t	u_prio
	)

This function provides a standardized mechanism to initialize FreeRTOS tasks. It sequential-validates input arguments, ensures protection against double spawning via the task handle state, and handles memory exhaustion failures safely.

Warning

The p_handle argument must point to a persistent variable (typically a module-scoped static) to maintain double-spawn protection. Once the task finishes execution or triggers a delete, the underlying task handle variable must be set back to NULL to allow future respawns.

Parameters

p_handle	Pointer to the TaskHandle_t variable. If the pointed handle is already initialized (not NULL), the function returns ESP_ERR_INVALID_STATE.
f_worker	Task function (worker).
p_name	Task name string for debugging and identification.
u32_stack	Stack size in bytes.
u_prio	Task priority.

Returns

• ESP_OK: Task created successfully.
• ESP_ERR_INVALID_ARG: The pointer p_handle, f_worker or p_name is NULL.
• ESP_ERR_INVALID_STATE: Task handle is already in use (task already exists).
• ESP_ERR_NO_MEM: Memory could not be allocated due to the lack of an empty block of the required size.

Example of use (but it's better to use EIF_TASK_LAUNCH macro):

#include <esp_log.h>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <esp_iot_framework_core_ext.h>
#include <esp_iot_framework_core_macros.h>
 
// Double-call protection
static TaskHandle_t mqtt_hdl = NULL;
 
void mqtt_task_worker(void *arg) {
    while(1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
    mqtt_hdl = NULL;
    vTaskDelete(NULL);
}
 
void start_app_tasks(void) {
    EIF_TAG_WITH_UNUSED "APP_START";
    esp_err_t ret = ESP_OK;
   
    ret = eif_task_common_spawn(mqtt_hdl, mqtt_task_worker, "mqtt_service", 4096, 5);
    if (ret != ESP_OK) {
        EIF_LOG_E("Failed to launch MQTT task");
    }
}

Note

If double-spawn restrictions are not required (e.g., creating multiple instances of the same task), pass a pointer to a temporary standalone task handle variable instead of the main module handle.

Example of use (without double-call protection, but it's better to use EIF_TASK_LAUNCH macro):

#include <esp_log.h>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <esp_iot_framework_core_ext.h>
#include <esp_iot_framework_core_macros.h>
 
void task_worker(void *arg) {
    while(1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
    vTaskDelete(NULL);
}
 
void start_app_tasks(void) {
    EIF_TAG_WITH_UNUSED "APP_START";
    esp_err_t ret = ESP_OK;
   
    for (int i = 0; i < 5; i++) {
        TaskHandle_t hdl = NULL;
       
        ret = eif_task_common_spawn(hdl, task_worker, "task_worker", 2048, 3);
        if (ret != ESP_OK) {
            EIF_LOG_E("Failed to launch task iteration %d", i);
        }
    }
}

eif_task_reboot_launch()

esp_err_t eif_task_reboot_launch

(

void

)

Spawns an asynchronous task to execute a system reboot.

Returns

• ESP_OK: Task created successfully and added to the FreeRTOS scheduler.
• ESP_ERR_INVALID_ARG: Internal error. One of the mandatory arguments is passed as a NULL pointer.
• ESP_ERR_INVALID_STATE: The task handle is already active, meaning this task is already running.
• ESP_ERR_NO_MEM: Memory could not be allocated due to the lack of an empty block of the required size.

eif_task_wifi_test_launch()

esp_err_t eif_task_wifi_test_launch

(

uint8_t

profile_index

)

Spawns an asynchronous task to execute a Wi-Fi profile test.

Parameters

profile_index

The index of the Wi-Fi profile under test. Must be from 0 to number of Wi-Fi profiles stored in the system. It is set using eif_set_wifi_profiles_count().

Returns

• ESP_OK: Task created successfully and added to the FreeRTOS scheduler.
• ESP_ERR_INVALID_ARG: Internal error. One of the mandatory arguments is passed as a NULL pointer.
• ESP_ERR_INVALID_STATE: The task handle is already active, meaning this task is already running.
• ESP_ERR_NO_MEM: Memory could not be allocated due to the lack of an empty block of the required size.

eif_task_tls_recreate_launch()

esp_err_t eif_task_tls_recreate_launch

(

void

)

Note

Must enable the CONFIG_EIF_ENABLE_TLS flag in Kconfig to use

Spawns an asynchronous task to regenerate TLS credentials.

Returns

• ESP_OK: Task created successfully and added to the FreeRTOS scheduler.
• ESP_ERR_INVALID_ARG: Internal error. One of the mandatory arguments is passed as a NULL pointer.
• ESP_ERR_INVALID_STATE: The task handle is already active, meaning this task is already running.
• ESP_ERR_NO_MEM: Memory could not be allocated due to the lack of an empty block of the required size.

eif_task_rollback_and_reboot_launch()

esp_err_t eif_task_rollback_and_reboot_launch

(

void

)

Spawns an asynchronous task to execute a firmware rollback.

Returns

• ESP_OK: Task created successfully and added to the FreeRTOS scheduler.
• ESP_ERR_INVALID_ARG: Internal error. One of the mandatory arguments is passed as a NULL pointer.
• ESP_ERR_INVALID_STATE: The task handle is already active, meaning this task is already running.
• ESP_ERR_NO_MEM: Memory could not be allocated due to the lack of an empty block of the required size.