docs: added esp-expression-with-stack on documentation
This commit is contained in:
parent
002f38c7f5
commit
dfea4196a2
4 changed files with 71 additions and 3 deletions
|
@ -39,11 +39,18 @@
|
||||||
})
|
})
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* These functions are intended to be use by the macro above, and
|
* @brief Changes CPU sp-register to use another stack space and save the previous one
|
||||||
* Should never be called directly, otherwise crashes could
|
* @param stack Caller allocated stack pointer
|
||||||
* occur
|
* @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);
|
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);
|
extern void esp_switch_stack_exit(uint32_t *backup_stack);
|
||||||
|
|
||||||
#endif
|
#endif
|
|
@ -223,6 +223,8 @@ INPUT = \
|
||||||
../../components/esp_common/include/esp_freertos_hooks.h \
|
../../components/esp_common/include/esp_freertos_hooks.h \
|
||||||
## Inter-Processor Call
|
## Inter-Processor Call
|
||||||
../../components/esp_common/include/esp_ipc.h \
|
../../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)
|
## Over The Air Updates (OTA)
|
||||||
../../components/app_update/include/esp_ota_ops.h \
|
../../components/app_update/include/esp_ota_ops.h \
|
||||||
## ESP HTTPS OTA
|
## ESP HTTPS OTA
|
||||||
|
|
58
docs/en/api-reference/system/esp_expression_with_stack.rst
Normal file
58
docs/en/api-reference/system/esp_expression_with_stack.rst
Normal file
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -18,6 +18,7 @@ System API
|
||||||
High Resolution Timer <esp_timer>
|
High Resolution Timer <esp_timer>
|
||||||
Himem (large external SPI RAM) API <himem>
|
Himem (large external SPI RAM) API <himem>
|
||||||
Inter-Processor Call <ipc>
|
Inter-Processor Call <ipc>
|
||||||
|
Call function with external stack<esp_expression_with_stack>
|
||||||
Interrupt Allocation <intr_alloc>
|
Interrupt Allocation <intr_alloc>
|
||||||
Logging <log>
|
Logging <log>
|
||||||
Miscellaneous System APIs <system>
|
Miscellaneous System APIs <system>
|
||||||
|
|
Loading…
Reference in a new issue