Call function with external stack¶

Overview¶

A given function can be executed with a user allocated stack space which is independent of current task stack, this mechanism can be used to save stack space wasted by tasks which call a common function with intensive stack usage such as printf. The given function can be called inside the macro ESP_EXECUTE_EXPRESSION_WITH_STACK() it will redirect the target function to be executed using the space allocated by the user.

Usage¶

ESP_EXECUTE_EXPRESSION_WITH_STACK() takes three arguments, a mutex object allocated by the caller, which is used to protect if the same function shares its allocated stack, a pointer to the top of stack used to that fuction, and the function itself, note the function is passed exactly in the same way as do when you call it on a regular way.

The usage may looks like the code below:

//Let's suppose we wanting to call printf using a separated stack space
//allowing app to reduce its stack size.
void app_main()
{
    //Allocate a stack buffer, from heap or as a static form:
    portSTACK_TYPE *shared_stack = malloc(8192 * sizeof(portSTACK_TYPE));
    assert(shared_stack != NULL);

    //Allocate a mutex to protect its usage:
    SemaphoreHandle_t printf_lock = xSemaphoreCreateMutex();
    assert(printf_lock != NULL);

    //Call the desired function using the macro helper:
    ESP_EXECUTE_EXPRESSION_WITH_STACK(printf_lock,
                                    shared_stack,
                                    printf("Executing this from external stack! \n"));
    vSemaphoreDelete(printf_lock);
    free(shared_stack);
}

API Reference¶

Header File¶

esp_common/include/esp_expression_with_stack.h

Functions¶

StackType_t *esp_switch_stack_setup(StackType_t *stack, size_t stack_size)¶

Fill stack frame with CPU-specifics value before use.

Return

New pointer to the top of stack

Note

Application must not call this function directly

Parameters

stack: Caller allocated stack pointer
stack_size: Size of stack in bytes

void esp_switch_stack_enter(StackType_t *stack, uint32_t *backup_stack)¶

Changes CPU sp-register to use another stack space and save the previous one.

Note

Application must not call this function directly

Parameters

stack: Caller allocated stack pointer
backup_stack: Pointer to a place to save the current stack

void esp_switch_stack_exit(uint32_t *backup_stack)¶

Restores the previous CPU sp-register.

Note

Application must not call this function directly

Parameters

backup_stack: Pointer to the place where stack was saved

Macros¶

ESP_EXECUTE_EXPRESSION_WITH_STACK(lock, stack, stack_size, expression)¶

Executes a 1-line expression with a application alocated stack.

Note

if either lock, stack or stack size is invalid, the expression will be called using the current stack.

Parameters

lock: Mutex object to protect in case of shared stack
stack: Pointer to user alocated stack
stack_size: Size of current stack in bytes
expression: Expression or function to be executed using the stack

Provide feedback about this document