docs: added esp-expression-with-stack on documentation

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

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

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
+
+

docs/en/api-reference/system/index.rst

@@ -18,6 +18,7 @@ System API
     High Resolution Timer <esp_timer>
     Himem (large external SPI RAM) API <himem>
     Inter-Processor Call <ipc>
+    Call function with external stack<esp_expression_with_stack>
     Interrupt Allocation <intr_alloc>
     Logging <log>
     Miscellaneous System APIs <system>