From bf0dfc2cb3cb5ca822c753dc7a525041d189e8b1 Mon Sep 17 00:00:00 2001
From: Erhan Kurubas <erhan.kurubas@espressif.com>
Date: Fri, 5 Dec 2025 18:05:08 +0100
Subject: [PATCH] docs(esp_trace): update README for SystemView as external
 managed component

---
 components/esp_trace/README.md                | 41 +++++++++++++++----
 components/esp_trace/include/esp_trace.h      | 10 -----
 .../sysview_tracing/main/CMakeLists.txt       |  2 +-
 .../main/CMakeLists.txt                       |  1 -
 4 files changed, 35 insertions(+), 19 deletions(-)

diff --git a/components/esp_trace/README.md b/components/esp_trace/README.md
index 3c6ca01c42..45196dd098 100644
--- a/components/esp_trace/README.md
+++ b/components/esp_trace/README.md
@@ -153,12 +153,13 @@ The architecture follows a layered Port & Adapter pattern where the core manages
 ### Using Menuconfig
 
 1. Go to `Component config` → `ESP Trace Configuration`
-2. Select your desired trace transport under `Trace transport`:
+2. Select your trace library under `Trace library`:
+   - **External library from component registry** - Use a custom encoder provided by an external component (e.g. SystemView)
+   - **Disabled** - Disable trace library
+3. Select your desired trace transport under `Trace transport`:
    - **ESP-IDF apptrace** - Use built-in apptrace for custom tracing
+   - **External transport from component registry** - Use a custom transport provided by an external component
    - **None** - Disable tracing transport
-3. Select your trace library under `Trace library`:
-   - **SEGGER SystemView** - Enable SystemView tracing
-   - **None** - Use standalone apptrace without a library
 
 ### Using sdkconfig
 
@@ -172,16 +173,41 @@ CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y
 
 For SystemView tracing over JTAG:
 
+1. Add `espressif/esp_sysview` component to your `idf_component.yml`:
+
+```yaml
+dependencies:
+  espressif/esp_sysview: "^1"
+```
+
+2. Configure in `sdkconfig`:
+
 ```
 CONFIG_ESP_TRACE_ENABLE=y
-CONFIG_ESP_TRACE_LIB_SYSVIEW=y
+CONFIG_ESP_TRACE_LIB_EXTERNAL=y
 CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y
 CONFIG_APPTRACE_DEST_JTAG=y
 ```
 
 ## Component Dependencies
 
-To use tracing in your application, add `esp_trace` to your component's dependencies in `CMakeLists.txt`:
+### When Using External Trace Libraries (e.g., SystemView)
+
+If you're using an external trace library from the component registry (like `espressif/esp_sysview`), you **don't need** to explicitly add `esp_trace` to your dependencies. The external component already has a public dependency on `esp_trace` (using `REQUIRES`), so it's automatically available to your application code:
+
+```cmake
+idf_component_register(
+    SRCS "main.c"
+    INCLUDE_DIRS "."
+    # No need to add esp_trace here when using esp_sysview
+)
+```
+
+This means you can directly use both the trace library APIs (e.g., SystemView) and `esp_trace` APIs (like `esp_trace_get_user_params()`, `esp_trace_is_host_connected()`, etc.) without explicitly declaring the dependency.
+
+### When Using Standalone Apptrace
+
+For standalone apptrace usage (without an external trace library), add `esp_trace` to your component's dependencies:
 
 ```cmake
 idf_component_register(
@@ -291,7 +317,7 @@ ESP_TRACE_REGISTER_ENCODER("my_encoder", &s_my_encoder_vt);
 - Use `ESP_TRACE_REGISTER_TRANSPORT(name, vtable)` if you're implementing a custom transport
 - Registration happens automatically at link time (no manual initialization needed)
 
-See `components/esp_trace/adapters/encoder/adapter_encoder_sysview.c` for a complete reference implementation.
+See `espressif/esp_sysview` component source (specifically `adapter_encoder_sysview.c`) for a complete reference implementation.
 
 ### FreeRTOS Trace Integration
 
@@ -381,3 +407,4 @@ For detailed usage instructions, see:
 Examples demonstrating trace usage can be found in:
 - `examples/system/app_trace_basic/` - Basic application tracing
 - `examples/system/sysview_tracing/` - SystemView tracing example
+- `examples/system/sysview_tracing_heap_log/` - SystemView heap and log tracing example
diff --git a/components/esp_trace/include/esp_trace.h b/components/esp_trace/include/esp_trace.h
index bbc96fa646..5ed7ccb324 100644
--- a/components/esp_trace/include/esp_trace.h
+++ b/components/esp_trace/include/esp_trace.h
@@ -100,16 +100,6 @@ esp_trace_handle_t esp_trace_get_active_handle(void);
  */
 esp_err_t esp_trace_write(esp_trace_handle_t handle, const void *data, size_t size, unsigned long tmo);
 
-/**
- * @brief Flush the trace handle
- *
- * @param handle The trace handle
- * @param tmo The timeout in us
- *
- * @return ESP_OK on success, otherwise see esp_err_t
- */
-esp_err_t esp_trace_flush(esp_trace_handle_t handle, unsigned long tmo);
-
 /**
  * @brief Check if the host is connected
  *
diff --git a/examples/system/sysview_tracing/main/CMakeLists.txt b/examples/system/sysview_tracing/main/CMakeLists.txt
index ff0df4c7b7..ca05ae8fac 100644
--- a/examples/system/sysview_tracing/main/CMakeLists.txt
+++ b/examples/system/sysview_tracing/main/CMakeLists.txt
@@ -1,3 +1,3 @@
 idf_component_register(SRCS "sysview_tracing.c"
-                    PRIV_REQUIRES esp_driver_gptimer esp_trace
+                    PRIV_REQUIRES esp_driver_gptimer
                     INCLUDE_DIRS ".")
diff --git a/examples/system/sysview_tracing_heap_log/main/CMakeLists.txt b/examples/system/sysview_tracing_heap_log/main/CMakeLists.txt
index f4f7b0740d..0383353f0a 100644
--- a/examples/system/sysview_tracing_heap_log/main/CMakeLists.txt
+++ b/examples/system/sysview_tracing_heap_log/main/CMakeLists.txt
@@ -1,3 +1,2 @@
 idf_component_register(SRCS "sysview_heap_log.c"
-                    PRIV_REQUIRES esp_trace
                     INCLUDE_DIRS ".")