Merge branch 'feat/enable_function_tracing_v6.0' into 'release/v6.0'

Enable function tracing (-finstrument-functions) (v6.0)

See merge request espressif/esp-idf!52656

docs/en/api-guides/tracing/function-tracing.rst

@@ -0,0 +1,42 @@
+.. _app_trace-function-tracing:
+
+Compiler-Instrumented Function Tracing
+======================================
+
+:link_to_translation:`zh_CN:[中文]`
+
+Function tracing records every function entry and exit automatically, without manual trace points. When a source file is built with the GCC flag ``-finstrument-functions``, the compiler inserts a call at the start and end of each function. These calls go to hooks provided by the :doc:`esp_trace <index>` component, which forward the events to the active trace encoder (for example SystemView). The events carry the raw function and call-site addresses. SystemView records them as raw addresses. Resolving the addresses to function names is done separately against the ELF file (for example with ``addr2line`` or a custom tool).
+
+Enabling Function Tracing
+-------------------------
+
+Enable :ref:`CONFIG_ESP_TRACE_FUNCTION_TRACE`. The following options control function tracing:
+
+- :ref:`CONFIG_ESP_TRACE_FUNCTION_TRACE` - build the function-trace hooks and runtime.
+- :ref:`CONFIG_ESP_TRACE_FUNCTION_TRACE_AUTO_START` - when enabled (default), recording follows the encoder's state and begins as soon as the host starts the session. When disabled, no events are emitted until the application calls :cpp:func:`esp_trace_function_trace_start`; an active host session alone is not enough.
+
+Enabling the option compiles the hooks and runtime into the build. It does not add ``-finstrument-functions`` to any code, so on its own it produces no events. To trace a component or file, add the flag from its own ``CMakeLists.txt`` for the sources you want traced:
+
+.. code-block:: cmake
+
+    if(CONFIG_ESP_TRACE_FUNCTION_TRACE)
+        target_compile_options(${COMPONENT_LIB} PRIVATE -finstrument-functions)
+    endif()
+
+Use the GCC ``-finstrument-functions-exclude-file-list`` and ``-finstrument-functions-exclude-function-list`` flags to skip specific files or functions. Keep instrumentation scoped to your own components, and do not instrument code that runs with the flash cache disabled (IRAM ISRs, SPI flash operations).
+
+Decoding Function-Trace Events
+------------------------------
+
+After collecting a SystemView capture (see :doc:`sysview`), decode the function-trace events with the processing script:
+
+.. code-block:: bash
+
+    $IDF_PATH/tools/esp_app_trace/sysviewtrace_proc.py -i func -b </path/to/program.elf> -t {IDF_TARGET_TOOLCHAIN_PREFIX}- file:///path/to/trace.svdat
+
+The ``-i func`` option selects the function-trace event stream. The script uses the ELF file and toolchain prefix to resolve addresses, then prints a per-function report listing each traced function with its address, entry and exit counts, and source location.
+
+Application Example
+-------------------
+
+- :example:`system/tracing/function_tracing` demonstrates compiler-instrumented function entry/exit tracing and how to control which code is instrumented.

docs/en/api-guides/tracing/index.rst

@@ -35,6 +35,8 @@ Choosing Your Path
       - :doc:`Application Level Tracing transport <transports>`
     * - Collect source code coverage
       - :doc:`Gcov <gcov>`
+    * - Trace every function entry and exit automatically
+      - :doc:`Function tracing <function-tracing>`
     * - Integrate a third-party trace recorder
       - :doc:`Custom trace library <custom-trace-library>`
 
@@ -87,6 +89,7 @@ Detailed Guides
     transports
     sysview
     gcov
+    function-tracing
     custom-trace-library
 
 Related Documentation
@@ -105,4 +108,5 @@ Examples
 - :example:`system/tracing/sysview_tracing`: SystemView tracing example
 - :example:`system/tracing/sysview_tracing_heap_log`: Heap tracing with SystemView
 - :example:`system/tracing/gcov`: Source code coverage over JTAG
+- :example:`system/tracing/function_tracing`: Compiler-instrumented function entry/exit tracing
 - :example:`system/tracing/esp_trace_custom_library`: External trace library integration template

docs/zh_CN/api-guides/tracing/function-tracing.rst

@@ -0,0 +1,42 @@
+.. _app_trace-function-tracing:
+
+编译器插桩的函数跟踪
+====================
+
+:link_to_translation:`en:[English]`
+
+函数跟踪可自动记录每次函数进入和退出，无需手动插入跟踪点。当源文件使用 GCC 标志 ``-finstrument-functions`` 编译时，编译器会在每个函数的开始和结束处插入调用。这些调用进入由 :doc:`esp_trace <index>` 组件提供的钩子，钩子再将事件转发给当前活动的跟踪编码器（例如 SystemView）。事件携带原始的函数地址和调用点地址，SystemView 将其记录为原始地址。将地址解析为函数名的工作单独针对 ELF 文件完成（例如使用 ``addr2line`` 或自定义工具）。
+
+启用函数跟踪
+------------
+
+启用 :ref:`CONFIG_ESP_TRACE_FUNCTION_TRACE`。以下选项控制函数跟踪：
+
+- :ref:`CONFIG_ESP_TRACE_FUNCTION_TRACE` - 构建函数跟踪钩子和运行时。
+- :ref:`CONFIG_ESP_TRACE_FUNCTION_TRACE_AUTO_START` - 启用时（默认），记录跟随编码器的状态，并在主机启动会话后立即开始。禁用时，在应用程序调用 :cpp:func:`esp_trace_function_trace_start` 之前不会发出任何事件；仅有活动的主机会话是不够的。
+
+启用该选项会将钩子和运行时编译进构建，但不会为任何代码添加 ``-finstrument-functions``，因此单独启用不会产生任何事件。要跟踪某个组件或文件，请在其自身的 ``CMakeLists.txt`` 中为需要跟踪的源文件添加该标志：
+
+.. code-block:: cmake
+
+    if(CONFIG_ESP_TRACE_FUNCTION_TRACE)
+        target_compile_options(${COMPONENT_LIB} PRIVATE -finstrument-functions)
+    endif()
+
+使用 GCC 的 ``-finstrument-functions-exclude-file-list`` 和 ``-finstrument-functions-exclude-function-list`` 标志可跳过特定文件或函数。请将插桩范围限定在你自己的组件内，且不要对在关闭 flash 缓存的情况下运行的代码（IRAM 中断服务程序、SPI flash 操作）进行插桩。
+
+解码函数跟踪事件
+----------------
+
+在采集到 SystemView 捕获数据后（参见 :doc:`sysview`），使用处理脚本解码函数跟踪事件：
+
+.. code-block:: bash
+
+    $IDF_PATH/tools/esp_app_trace/sysviewtrace_proc.py -i func -b </path/to/program.elf> -t {IDF_TARGET_TOOLCHAIN_PREFIX}- file:///path/to/trace.svdat
+
+``-i func`` 选项用于选择函数跟踪事件流。脚本使用 ELF 文件和工具链前缀解析地址，然后打印按函数分类的报告，列出每个被跟踪函数的地址、进入和退出次数以及源代码位置。
+
+应用示例
+--------
+
+- :example:`system/tracing/function_tracing` 演示编译器插桩的函数进入或退出跟踪，以及如何控制对哪些代码进行插桩。

docs/zh_CN/api-guides/tracing/index.rst

@@ -35,6 +35,8 @@ ESP-IDF 提供了一套跟踪系统，用于程序行为分析和调试。以较
       - :doc:`应用层跟踪传输 <transports>`
     * - 收集源代码覆盖率
       - :doc:`Gcov <gcov>`
+    * - 自动跟踪每次函数进入和退出
+      - :doc:`函数跟踪 <function-tracing>`
     * - 集成第三方跟踪记录器
       - :doc:`自定义跟踪库 <custom-trace-library>`
 
@@ -87,6 +89,7 @@ ESP-IDF 提供了一套跟踪系统，用于程序行为分析和调试。以较
     transports
     sysview
     gcov
+    function-tracing
     custom-trace-library
 
 相关文档
@@ -105,4 +108,5 @@ ESP-IDF 提供了一套跟踪系统，用于程序行为分析和调试。以较
 - :example:`system/tracing/sysview_tracing`：SystemView 跟踪示例
 - :example:`system/tracing/sysview_tracing_heap_log`：基于 SystemView 的堆跟踪
 - :example:`system/tracing/gcov`：通过 JTAG 获取源代码覆盖率
+- :example:`system/tracing/function_tracing`：编译器插桩的函数进入/退出跟踪
 - :example:`system/tracing/esp_trace_custom_library`：外部跟踪库集成模板