diff --git a/components/esp_common/include/esp_expression_with_stack.h b/components/esp_common/include/esp_expression_with_stack.h index d23e7e833..f8cc65136 100644 --- a/components/esp_common/include/esp_expression_with_stack.h +++ b/components/esp_common/include/esp_expression_with_stack.h @@ -39,11 +39,18 @@ }) /** - * These functions are intended to be use by the macro above, and - * Should never be called directly, otherwise crashes could - * occur + * @brief Changes CPU sp-register to use another stack space and save the previous one + * @param stack Caller allocated stack pointer + * @param backup_stack Pointer to a place to save the current stack + * @note Application must not call this function directly */ extern void esp_switch_stack_enter(portSTACK_TYPE *stack, uint32_t *backup_stack); + +/** + * @brief Restores the previous CPU sp-register + * @param backup_stack Pointer to the place where stack was saved + * @note Application must not call this function directly + */ extern void esp_switch_stack_exit(uint32_t *backup_stack); #endif \ No newline at end of file diff --git a/docs/Doxyfile b/docs/Doxyfile index c880f3b68..a56f13cf4 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -223,6 +223,8 @@ INPUT = \ ../../components/esp_common/include/esp_freertos_hooks.h \ ## Inter-Processor Call ../../components/esp_common/include/esp_ipc.h \ + ## Call Function with External stack + ../../components/esp_common/include/esp_expression_with_stack.h \ ## Over The Air Updates (OTA) ../../components/app_update/include/esp_ota_ops.h \ ## ESP HTTPS OTA diff --git a/docs/en/api-reference/system/esp_expression_with_stack.rst b/docs/en/api-reference/system/esp_expression_with_stack.rst new file mode 100644 index 000000000..ed12dc444 --- /dev/null +++ b/docs/en/api-reference/system/esp_expression_with_stack.rst @@ -0,0 +1,58 @@ +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 :cpp:func:`ESP_EXECUTE_EXPRESSION_WITH_STACK` +it will redirect the target function to be executed using the space +allocated by the user. + +Usage +----- + +:cpp:func:`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 extactly in the same way as do when you call +it on a regular way. + +The usage may looks like the code below: + +.. code-block:: c + + //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)); + + //points to the top of stack, that is it the last word of allocated buffer: + portSTACK_TYPE *ext_stack_top = (portSTACK_TYPE *)&shared_stack[0] + + ((sizeof(8192 * sizeof(portSTACK_TYPE))) / + sizeof(portSTACK_TYPE)); + + //Allocate a mutex to protect its usage: + SemaphoreHandle_t printf_lock = xSemaphoreCreateMutex(); + + //Call the desired function using the macro helper: + ESP_EXECUTE_EXPRESSION_WITH_STACK(printf_lock, + ext_stack_top, + printf("Executing this from external stack! \n")); + free(shared_stack); + } + +.. _esp-call-with-stack-basic_usage: + +API Reference +------------- + +.. include:: /_build/inc/esp_expression_with_stack.inc + + diff --git a/docs/en/api-reference/system/index.rst b/docs/en/api-reference/system/index.rst index 8d0a659e2..13fbaf0fa 100644 --- a/docs/en/api-reference/system/index.rst +++ b/docs/en/api-reference/system/index.rst @@ -18,6 +18,7 @@ System API High Resolution Timer Himem (large external SPI RAM) API Inter-Processor Call + Call function with external stack Interrupt Allocation Logging Miscellaneous System APIs