diff --git a/docs/en/api-reference/system/esp_function_with_shared_stack.rst b/docs/en/api-reference/system/esp_function_with_shared_stack.rst index 1c046de3ff..28af8d65c6 100644 --- a/docs/en/api-reference/system/esp_function_with_shared_stack.rst +++ b/docs/en/api-reference/system/esp_function_with_shared_stack.rst @@ -12,12 +12,14 @@ A given function can be executed with a user-allocated stack space which is inde :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 + .. list:: + + - Use thread-local storage + :esp32p4: - Use the floating-point unit + :esp32p4: - Use the AI co-processor + - 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. + Furthermore, backtraces will be wrong when called from the function running on the shared stack or any of its callees. The limitations are quite severe, 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 a `GitHub Issue `_. Usage diff --git a/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst b/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst index 2f8b29bf0b..5b7a9d1479 100644 --- a/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst +++ b/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst @@ -8,6 +8,19 @@ 执行某个给定函数时,可以使用用户分配的堆栈空间,且该堆栈空间独立于当前任务的堆栈。这一机制能够节省在调用常用函数时浪费大量堆栈空间,例如 ``printf`` 函数。具体而言,将给定函数作为参数传入 :cpp:func:`esp_execute_shared_stack_function` 中,给定函数便会在共享堆栈空间内作为回调函数延迟执行。 +.. warning:: + + :cpp:func:`esp_execute_shared_stack_function` 只会为所提供的共享堆栈内存做最基础的设置。传递给该函数以在共享堆栈空间上执行的函数,或调用该函数的任何函数,都不应执行以下任何操作: + + .. list:: + + - 使用线程局部存储 (TLS) + :esp32p4: - 使用浮点运算器 (FPU) + :esp32p4: - 使用 AI 协处理器 + - 调用 vTaskDelete(NULL) 删除当前运行的任务 + + 此外,从共享堆栈上运行的函数或调用该函数的任何函数来调用回溯,回溯信息都可能不正确。这方面的限制十分严格,因此将来 :cpp:func:`esp_execute_shared_stack_function` 可能会被弃用。如有用例必须使用 :cpp:func:`esp_execute_shared_stack_function` 函数才能实现,请提交 `GitHub Issue `_。 + 使用方法 --------