Merge branch 'bugfix/shared_stack_not_switching_correctly' into 'master'

bugfix/shared_stack: Fix task stack not being replaced by shared stack correctly

See merge request espressif/esp-idf!7956

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

@@ -8,24 +8,31 @@ 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.
+be called inside the shared stack space which is a callback function
+deferred by calling :cpp:func:`esp_execute_shared_stack_function`, 
+passing that function as parameter
 
 Usage
 -----
 
-:cpp:func:`ESP_EXECUTE_EXPRESSION_WITH_STACK` takes three arguments, 
+:cpp:func:`esp_execute_shared_stack_function` takes four 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. 
+of stack used to that fuction, the size in bytes of stack and, a pointer
+to a user function where the shared stack space will reside, after calling
+the function, the user defined function will be deferred as a callback
+where functions can be called using the user allocated space without
+taking space from current task stack. 
 
 The usage may looks like the code below:
 
 .. code-block:: c
 
+    void external_stack_function(void)
+    {
+        printf("Executing this printf from external stack! \n");
+    }
+
     //Let's suppose we wanting to call printf using a separated stack space
     //allowing app to reduce its stack size.
     void app_main()
@@ -39,9 +46,11 @@ The usage may looks like the code below:
         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"));
+        esp_execute_shared_stack_function(printf_lock, 
+                                        shared_stack,
+                                        8192,
+                                        external_stack_function);
+        
         vSemaphoreDelete(printf_lock);    
         free(shared_stack); 
     }

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

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