docs(esp_trace): restructure tracing docs with esp_trace as master

Reorganize the tracing documentation so esp_trace is the master
component, with app_trace, SystemView, and Gcov referenced from it.

(cherry picked from commit 6c6490d54c)

examples/network/simple_sniffer/README.md

@@ -32,7 +32,7 @@ Open the project configuration menu (`idf.py menuconfig`). Then go into `Example
 - Select where to save the pcap file in `Select destination to store pcap file` menu item.
   - `SD Card` means saving packets (pcap format) into the SD card you plug in. The default SD card work mode is set to SDMMC for target ESP32 and ESP32S3, but SPI is the only choice for other targets.
   - `Memory` means saving packets in memory and can parse packets in place.
-  - `JTAG (App Trace)` means sending packets (pcap format) to host via JTAG interface. This feature depends on [app trace component](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html), Component config -> Application Level Tracing -> Data Destination -> JTAG should be enabled to choose `JTAG (App Trace)` as destination.
+  - `JTAG (App Trace)` means sending packets (pcap format) to host via JTAG interface. This feature depends on [app trace component](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html), Component config -> Application Level Tracing -> Data Destination -> JTAG should be enabled to choose `JTAG (App Trace)` as destination.
 - Set the mount point in your filesystem in `SD card mount point in the filesystem` menu item. This configuration only takes effect when you choose to save packets into SD card.
 - Set max name length of pcap file in `Max name length of pcap file` menu item.
 - Set the length of sniffer work queue in `Length of sniffer work queue` menu item.
@@ -303,7 +303,7 @@ I (130566) cmd_pcap: .pcap file close done
 2. Build & Flash with `idf.py -p PORT flash`
 3. Connect JTAG, run OpenOCD (for more information about how-to please refer to [JTAG Debugging](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html)).
 4. Telnet to localhost with 4444 port: `telnet localhost 4444`.
-5. In the telnet session, run command like `esp32 apptrace start file://sniffer-esp32.pcap 1 -1 20` (more information about this command, please refer to [apptrace command](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#openocd-application-level-tracing-commands)).
+5. In the telnet session, run command like `esp32 apptrace start file://sniffer-esp32.pcap 1 -1 20` (more information about this command, please refer to [apptrace command](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html#openocd-application-level-tracing-commands)).
 6. Run the example, start sniffer with `sniffer` command.
 7. Stop sniffer by entering command `sniffer --stop` in the example console.
 8. Stop tracing by entering command `esp32 apptrace stop` in the telnet session.

examples/system/.build-test-rules.yml

@@ -68,7 +68,7 @@ examples/system/esp_timer:
     - *common_components
     - esp_timer
 
-examples/system/esp_trace:
+examples/system/esp_trace_custom_library:
   disable:
     - if: SOC_USB_SERIAL_JTAG_SUPPORTED != 1
       reason: example transport is USB Serial JTAG

examples/system/app_trace_basic/README.md

@@ -5,9 +5,9 @@
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 
-This example demonstrates how to use the [Application Level Tracing Library](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#) (henceforth referred to as **App Trace**) to log messages to a host via JTAG instead of the normal method of logging via UART.
+This example demonstrates how to use the [Application Level Tracing Library](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html) (henceforth referred to as **App Trace**) to log messages to a host via JTAG instead of the normal method of logging via UART.
 
-UART logs are time consuming and can significantly slow down the function that calls it. Therefore, it is generally a bad idea to use UART logs in time-critical functions. Logging to host via JTAG is significantly faster and can be used in time-critical functions. For more details regarding logging to host via JTAG, refer to the [Logging to Host Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#app-trace-logging-to-host).
+UART logs are time consuming and can significantly slow down the function that calls it. Therefore, it is generally a bad idea to use UART logs in time-critical functions. Logging to host via JTAG is significantly faster and can be used in time-critical functions. For more details regarding logging to host via JTAG, refer to the [Logging to Host Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html#app-trace-logging-to-host).
 
 ### Hardware Required
 
@@ -56,7 +56,7 @@ where OpenOCD was started). Assuming that OpenOCD was started in this example's
 esp apptrace start file://apptrace.log 0 2000 3 0 0
 ```
 
-**Note:** For more details on OpenOCD commands regarding App Trace, refer to the [OpenOCD Application Level Tracing Commands](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#openocd-application-level-tracing-commands)
+**Note:** For more details on OpenOCD commands regarding App Trace, refer to the [OpenOCD Application Level Tracing Commands](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html#openocd-application-level-tracing-commands)
 
 (To exit the serial monitor, type ``Ctrl-]``.)
 

examples/system/app_trace_to_plot/README.md

@@ -5,9 +5,9 @@
 
 (See the README.md file in the upper level 'examples' directory for more information about examples.)
 
-This example demonstrates how to use the [Application Level Tracing Library](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#) (henceforth referred to as **App Trace**) to send and plot dummy sensor data to a host via JTAG instead of the normal method of logging via UART.
+This example demonstrates how to use the [Application Level Tracing Library](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html) (henceforth referred to as **App Trace**) to send and plot dummy sensor data to a host via JTAG instead of the normal method of logging via UART.
 
-UART logs are time consuming and can significantly slow down the function that calls it. Therefore, it is generally a bad idea to use UART logs in time-critical functions. Logging to host via JTAG is significantly faster and can be used in time-critical functions. For more details regarding logging to host via JTAG, refer to the [Logging to Host Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#app-trace-logging-to-host).
+UART logs are time consuming and can significantly slow down the function that calls it. Therefore, it is generally a bad idea to use UART logs in time-critical functions. Logging to host via JTAG is significantly faster and can be used in time-critical functions. For more details regarding logging to host via JTAG, refer to the [Logging to Host Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html#app-trace-logging-to-host).
 
 ### Hardware Required
 
@@ -65,7 +65,7 @@ idf.py openocd --openocd-commands "-f board/esp32-wrover-kit-3.3v.cfg -c 'init;r
 
 **Note:** data.json file is an example for plot config file. It can be changed or modified.
 
-**Note:** For more details on OpenOCD commands regarding App Trace, refer to the [OpenOCD Application Level Tracing Commands](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#openocd-application-level-tracing-commands)
+**Note:** For more details on OpenOCD commands regarding App Trace, refer to the [OpenOCD Application Level Tracing Commands](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html#openocd-application-level-tracing-commands)
 
 (To exit the serial monitor, type ``Ctrl-]``.)
 

examples/system/esp_trace_custom_library/CMakeLists.txt

@@ -5,4 +5,4 @@ cmake_minimum_required(VERSION 3.16)
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 # "Trim" the build. Include the minimal set of components, main, and anything it depends on.
 idf_build_set_property(MINIMAL_BUILD ON)
-project(esp_trace_example)
+project(esp_trace_custom_library)

examples/system/esp_trace_custom_library/README.md

@@ -52,7 +52,7 @@ You should see the app start up and create a task. Whatever trace bytes your enc
 ## Project Layout
 
 ```
-esp_trace/
+esp_trace_custom_library/
 ├── CMakeLists.txt
 ├── sdkconfig.defaults
 ├── main/
@@ -147,7 +147,7 @@ The example defaults to USB Serial JTAG. To use a different transport, edit `sdk
 | Transport | Config | Notes |
 | --- | --- | --- |
 | USB Serial JTAG | `CONFIG_ESP_TRACE_TRANSPORT_USB_SERIAL_JTAG=y` | Default. Requires `ESP_CONSOLE_SECONDARY_NONE=y`. |
-| apptrace over JTAG | `CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y` + `CONFIG_APPTRACE_DEST_JTAG=y` | Needs OpenOCD on the host to drain the buffer. |
+| apptrace over JTAG | `CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y` + `CONFIG_APPTRACE_DEST_JTAG=y` | Needs OpenOCD on the host to read out the buffer. |
 | apptrace over UART | `CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y` + `CONFIG_APPTRACE_DEST_UART=y` | Pick a UART different from the console. |
 | External transport | `CONFIG_ESP_TRACE_TRANSPORT_EXTERNAL=y` | Another component must register a transport with `ESP_TRACE_REGISTER_TRANSPORT(...)`. |
 | None | `CONFIG_ESP_TRACE_TRANSPORT_NONE=y` | Useful if your library streams data over its own channel and just needs the FreeRTOS hooks. |
@@ -183,7 +183,7 @@ Because the transport is USB-Serial-JTAG and the console is on UART (`CONFIG_ESP
 esp_trace_start();    // resume emission (also resets the delta baseline)
 // ... do stuff ...
 esp_trace_stop();     // pause emission
-esp_trace_flush();    // drain transport buffers
+esp_trace_flush();    // flush transport buffers
 ```
 
 In this example the library boots with `s_enabled = false`, so nothing is emitted until `app_main()` calls `esp_trace_start()`. The trailing pair `esp_trace_flush(); esp_trace_stop();` makes sure the last events reach the host before the trace channel goes silent. Adapter wiring lives in [`adapter_encoder_ext_trace_lib.c`](components/ext_trace_lib/src/adapter_encoder_ext_trace_lib.c) (`start` / `stop` / `flush` callbacks); flush forwards to the transport's `flush_nolock`.

examples/system/esp_trace_custom_library/pytest_esp_trace_custom_library.py

@@ -86,7 +86,7 @@ def _capture_trace(ser: serial.Serial, trace_log_path: str, capture_s: float = 5
             except serial.SerialTimeoutException:
                 assert False, 'Timeout reached while reading from serial port, exiting...'
 
-        # Drain anything still in flight after the capture window.
+        # Read out anything still in flight after the capture window.
         time.sleep(0.2)
         end_time = time.time() + 1.0
         last_data_time = time.time()

examples/system/sysview_tracing/README.md

@@ -4,7 +4,7 @@
 
 This test code shows how to perform system-wide behavioral analysis of the program using [SEGGER SystemView tool](https://www.segger.com/products/development-tools/systemview/).
 
-For description of [SystemView tracing](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#system-behaviour-analysis-with-segger-systemview) please refer to **ESP32 Programming Guide**, section **Application Level Tracing library**. The following example provides practical implementation of this functionality.
+For description of [SystemView tracing](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/sysview.html) please refer to **ESP32 Programming Guide**, section **Application Level Tracing library**. The following example provides practical implementation of this functionality.
 
 
 ## Use Case

examples/system/sysview_tracing_heap_log/README.md

@@ -3,7 +3,7 @@
 
 # SystemView Heap and Log Tracing Example
 
-Heap memory leaking is quite widespread software bug. IDF provides [heap tracing feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/heap_debug.html#heap-tracing) which allows to collect information related to heap operations (allocations/deallocations) and detect potential memory leaks. This feature can be used in two modes: standalone and host-based. In standalone mode collected data are kept on-board, so this mode is limited by available memory in the system. Host-based mode does not have such limitation because collected data are sent to the host and can be analysed there using special tools. One of such tool is SEGGER SystemView. For description of [SystemView tracing feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#system-behaviour-analysis-with-segger-systemview) please refer to **ESP32 Programming Guide**, section **Application Level Tracing library**. SystemView is also can be useful to show log message sent from the target.
+Heap memory leaking is quite widespread software bug. IDF provides [heap tracing feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/heap_debug.html#heap-tracing) which allows to collect information related to heap operations (allocations/deallocations) and detect potential memory leaks. This feature can be used in two modes: standalone and host-based. In standalone mode collected data are kept on-board, so this mode is limited by available memory in the system. Host-based mode does not have such limitation because collected data are sent to the host and can be analysed there using special tools. One of such tool is SEGGER SystemView. For description of [SystemView tracing feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/sysview.html) please refer to **ESP32 Programming Guide**, section **Application Level Tracing library**. SystemView is also can be useful to show log message sent from the target.
 This example shows how to use this tool and IDF's scripts for host-based heap and log tracing analysis.
 
 Consider the following situation. User program have two tasks. One task allocates memory and puts obtained addresses into the queue. Another task waits on that queue, reads sent pointers and frees memory. The first task queues only part of the pointers so some of the allocated blocks are not freed and become leaked. Both tasks uses IDF's logging API to report their actions. This example uses IDF's heap tracing module to record allocations and deallocations to detect memory leaks. Both heap tracing records and log messages are redirected to the host.