# Call Function with External Stack

[中文]

## Overview

A given function can be executed with a user-allocated stack space which is independent of current task's stack. This mechanism helps reduce stack usage for tasks that call common functions with heavy stack demands such as `printf`. The given function can be executed on the shared stack space by calling `esp_execute_shared_stack_function()` and passing it as a parameter.

Warning

`esp_execute_shared_stack_function()` does only minimal preparation of the provided shared stack memory. The function passed to it for execution on the shared stack space or any of that function's callees should not do any of the following:

- Use thread-local storage

- Use the floating-point unit

- Use the AI co-processor

- Call vTaskDelete(NULL) to delete the currently running task

Furthermore, backtraces will be wrong when called from the function running on the shared stack or any of its callees. The limitations are quite severe, so that we might deprecate `esp_execute_shared_stack_function()` in the future. If you have any use case which can only be implemented using `esp_execute_shared_stack_function()`, please open a GitHub Issue.

## Usage

`esp_execute_shared_stack_function()` takes four arguments:

- a mutex object allocated by the caller, which is used to protect the shared stack space

- a pointer to the stack used for that function

- the size of stack in bytes

- a pointer to the shared stack function

The user-defined function is executed immediately as a callback, using a user‑allocated stack instead of the current task’s stack.

The usage may look like the code below:

    void external_stack_function(void)
    {
        printf("Executing this printf from external stack! \n");
    }

    //Let us suppose we want to call printf using a separated stack space
    //allowing the app to reduce its stack size.
    void app_main()
    {
        //Allocate a stack buffer, from heap or as a static form:
        StackType_t *shared_stack = malloc(8192 * sizeof(StackType_t));
        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_shared_stack_function(printf_lock,
                                        shared_stack,
                                        8192,
                                        external_stack_function);

        vSemaphoreDelete(printf_lock);
        free(shared_stack);
    }

## API Reference

### Header File

- components/esp_system/include/esp_expression_with_stack.h

- This header file can be included with:

  >     #include "esp_expression_with_stack.h"

### Functions

void esp_execute_shared_stack_function(SemaphoreHandle_t lock, void *stack, size_t stack_size, shared_stack_function function)

  Calls function on user defined shared stack space.

  After returning, the original stack is used again.

  Note

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

  Warning

  This function does minimal preparation of the provided piece of memory (`stack`). DO NOT do any of the following in `function` or any of its callees:

  - Use Thread-local storage

  - Use the Floating-point unit on ESP32-P4

  - Use the AI co-processor on ESP32-P4

  - Call vTaskDelete(NULL) (deleting the currently running task) Furthermore, backtraces will be wrong when called from `function` or any of its callees. The limitations are quite sever, so that we might deprecate this function in the future. If you have any use case which can only be implemented using this function, please open an issue on github.

  Parameters:

    - lock -- Mutex object to protect in case of shared stack

    - stack -- Pointer to user allocated stack

    - stack_size -- Size of current stack in bytes

    - function -- pointer to the shared stack function to be executed

### Macros

ESP_EXECUTE_EXPRESSION_WITH_STACK(lock, stack, stack_size, expression)

### Type Definitions

typedef void (*shared_stack_function)(void)

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.