docs(esp_system): Document limitations of esp_execute_shared_stack_function

components/esp_system/include/esp_expression_with_stack.h

@@ -22,9 +22,23 @@ typedef void (*shared_stack_function)(void);
     esp_execute_shared_stack_function(lock, stack, stack_size, expression)
 
 /**
- * @brief Calls user defined shared stack space function
+ * @brief Calls function on user defined shared stack space
+ *
+ * After returning, the original stack is used again.
+ *
+ * @warning This function does minimal preparation of the provided piece of memory (\c stack).
+ *          DO NOT do any of the following in \c 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 \c 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.
+ *
  * @param lock Mutex object to protect in case of shared stack
- * @param stack Pointer to user alocated stack
+ * @param stack Pointer to user allocated stack
  * @param stack_size Size of current stack in bytes
  * @param function pointer to the shared stack function to be executed
  * @note  if either lock, stack or stack size is invalid, the expression will

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

@@ -8,6 +8,17 @@ 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 shared stack space, which is a callback function deferred by calling :cpp:func:`esp_execute_shared_stack_function`, passing that function as a parameter.
 
+.. warning::
+
+  :cpp:func:`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 on ESP32-P4
+  - Use the AI co-processor on ESP32-P4
+  - 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 sever, so that we might deprecate :cpp:func:`esp_execute_shared_stack_function` in the future. If you have any use case which can only be implemented using :cpp:func:`esp_execute_shared_stack_function`, please open an issue on github.
+
 
 Usage
 -----