Merge branch 'esp32c6_h2_trace_encoder' into 'master'

feat(esp_riscv_trace): add ESP32-C6 and ESP32-H2 support

Closes IDF-16058 and IDF-16059

See merge request espressif/esp-idf!51385

components/esp_hal_debug_assist/esp32c5/include/hal/riscv_trace_ll.h

@@ -142,6 +142,13 @@ static inline void riscv_trace_ll_set_dm_trigger_ena(trace_dev_t *hw, bool enabl
  * Resynchronization
  *--------------------------------------------------------------------------*/
 
+/** @brief Whether the resync counter can represent the given mode. */
+static inline bool riscv_trace_ll_resync_mode_is_supported(uint32_t mode)
+{
+    return mode == RISCV_TRACE_RESYNC_DISABLED || mode == RISCV_TRACE_RESYNC_PACKET ||
+           mode == RISCV_TRACE_RESYNC_CYCLE;
+}
+
 static inline void riscv_trace_ll_set_resync_mode(trace_dev_t *hw, uint32_t mode)
 {
     hw->resync_prolonged.resync_mode = mode;

components/esp_hal_debug_assist/esp32c6/include/hal/riscv_trace_ll.h

@@ -0,0 +1,163 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * ESP32-C6 has a v1.0-spec trace encoder: no filter unit, no encoder config
+ * register (delta/full address, stall, halt, reset, debug trigger) and no AHB
+ * config register, so the LL only exposes the base register set. Its resync
+ * mode field is 1 bit with a different encoding than the v2.0 targets, handled
+ * in riscv_trace_ll_set_resync_mode() below.
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#include "soc/trace_reg.h"
+#include "soc/trace_struct.h"
+#include "soc/pcr_struct.h"
+#include "hal/assert.h"
+#include "hal/riscv_trace_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Return the register block for the given core. */
+static inline trace_dev_t *riscv_trace_ll_get_hw(int core)
+{
+    HAL_ASSERT(core == 0);
+    (void)core;
+    return &TRACE;
+}
+
+/*---------------------------------------------------------------------------
+ * Clock and reset
+ *--------------------------------------------------------------------------*/
+
+/** @brief Enable or disable the TRACE clock. */
+static inline void riscv_trace_ll_enable_bus_clock(bool enable)
+{
+    PCR.trace_conf.trace_clk_en = enable;
+}
+
+/** @brief Assert and release the reset of the encoder. */
+static inline void riscv_trace_ll_reset_register(int core)
+{
+    (void)core;
+    PCR.trace_conf.trace_rst_en = 1;
+    PCR.trace_conf.trace_rst_en = 0;
+}
+
+/** @brief Enable the per-module register clock gate. */
+static inline void riscv_trace_ll_enable_module_clock(trace_dev_t *hw, bool enable)
+{
+    hw->clock_gate.clk_en = enable;
+}
+
+/*---------------------------------------------------------------------------
+ * Memory configuration
+ *--------------------------------------------------------------------------*/
+
+static inline void riscv_trace_ll_set_mem_start_addr(trace_dev_t *hw, uint32_t addr)
+{
+    hw->mem_start_addr.mem_start_addr = addr;
+}
+
+static inline void riscv_trace_ll_set_mem_end_addr(trace_dev_t *hw, uint32_t addr)
+{
+    hw->mem_end_addr.mem_end_addr = addr;
+}
+
+static inline uint32_t riscv_trace_ll_get_mem_current_addr(trace_dev_t *hw)
+{
+    return hw->mem_current_addr.mem_current_addr;
+}
+
+/** @brief Reload the current address from the start address. */
+static inline void riscv_trace_ll_update_mem_current_addr(trace_dev_t *hw)
+{
+    hw->mem_addr_update.mem_current_addr_update = 1;
+}
+
+/*---------------------------------------------------------------------------
+ * Status
+ *--------------------------------------------------------------------------*/
+
+static inline uint32_t riscv_trace_ll_get_fifo_status(trace_dev_t *hw)
+{
+    return hw->fifo_status.val;
+}
+
+/*---------------------------------------------------------------------------
+ * Trigger, loop mode and restart
+ *--------------------------------------------------------------------------*/
+
+static inline void riscv_trace_ll_trigger_on(trace_dev_t *hw)
+{
+    hw->trigger.trigger_on = 1;
+}
+
+static inline void riscv_trace_ll_trigger_off(trace_dev_t *hw)
+{
+    hw->trigger.trigger_off = 1;
+}
+
+static inline void riscv_trace_ll_set_mem_loop(trace_dev_t *hw, bool loop)
+{
+    hw->trigger.mem_loop = loop;
+}
+
+static inline void riscv_trace_ll_set_restart_ena(trace_dev_t *hw, bool enable)
+{
+    hw->trigger.restart_ena = enable;
+}
+
+/*---------------------------------------------------------------------------
+ * Resynchronization
+ *--------------------------------------------------------------------------*/
+
+/** @brief Whether the resync counter can represent the given mode. */
+static inline bool riscv_trace_ll_resync_mode_is_supported(uint32_t mode)
+{
+    // 1-bit field: this encoder always counts and has no "disabled" mode.
+    return mode == RISCV_TRACE_RESYNC_PACKET || mode == RISCV_TRACE_RESYNC_CYCLE;
+}
+
+static inline void riscv_trace_ll_set_resync_mode(trace_dev_t *hw, uint32_t mode)
+{
+    // 1-bit field: 0 = count by cycle, 1 = count by packet.
+    hw->resync_prolonged.resync_mode = (mode == RISCV_TRACE_RESYNC_PACKET);
+}
+
+static inline void riscv_trace_ll_set_resync_threshold(trace_dev_t *hw, uint32_t threshold)
+{
+    hw->resync_prolonged.resync_prolonged = threshold;
+}
+
+/*---------------------------------------------------------------------------
+ * Interrupts
+ *--------------------------------------------------------------------------*/
+
+static inline void riscv_trace_ll_set_intr_ena(trace_dev_t *hw, uint32_t mask)
+{
+    hw->intr_ena.val = mask;
+}
+
+static inline uint32_t riscv_trace_ll_get_intr_raw(trace_dev_t *hw)
+{
+    return hw->intr_raw.val;
+}
+
+static inline void riscv_trace_ll_clear_intr(trace_dev_t *hw, uint32_t mask)
+{
+    hw->intr_clr.val = mask;
+}
+
+#ifdef __cplusplus
+}
+#endif

components/esp_hal_debug_assist/esp32h2/include/hal/riscv_trace_ll.h

@@ -0,0 +1,163 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * ESP32-H2 has a v1.0-spec trace encoder: no filter unit, no encoder config
+ * register (delta/full address, stall, halt, reset, debug trigger) and no AHB
+ * config register, so the LL only exposes the base register set. Its resync
+ * mode field is 1 bit with a different encoding than the v2.0 targets, handled
+ * in riscv_trace_ll_set_resync_mode() below.
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#include "soc/trace_reg.h"
+#include "soc/trace_struct.h"
+#include "soc/pcr_struct.h"
+#include "hal/assert.h"
+#include "hal/riscv_trace_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Return the register block for the given core. */
+static inline trace_dev_t *riscv_trace_ll_get_hw(int core)
+{
+    HAL_ASSERT(core == 0);
+    (void)core;
+    return &TRACE;
+}
+
+/*---------------------------------------------------------------------------
+ * Clock and reset
+ *--------------------------------------------------------------------------*/
+
+/** @brief Enable or disable the TRACE clock. */
+static inline void riscv_trace_ll_enable_bus_clock(bool enable)
+{
+    PCR.trace_conf.trace_clk_en = enable;
+}
+
+/** @brief Assert and release the reset of the encoder. */
+static inline void riscv_trace_ll_reset_register(int core)
+{
+    (void)core;
+    PCR.trace_conf.trace_rst_en = 1;
+    PCR.trace_conf.trace_rst_en = 0;
+}
+
+/** @brief Enable the per-module register clock gate. */
+static inline void riscv_trace_ll_enable_module_clock(trace_dev_t *hw, bool enable)
+{
+    hw->clock_gate.clk_en = enable;
+}
+
+/*---------------------------------------------------------------------------
+ * Memory configuration
+ *--------------------------------------------------------------------------*/
+
+static inline void riscv_trace_ll_set_mem_start_addr(trace_dev_t *hw, uint32_t addr)
+{
+    hw->mem_start_addr.mem_start_addr = addr;
+}
+
+static inline void riscv_trace_ll_set_mem_end_addr(trace_dev_t *hw, uint32_t addr)
+{
+    hw->mem_end_addr.mem_end_addr = addr;
+}
+
+static inline uint32_t riscv_trace_ll_get_mem_current_addr(trace_dev_t *hw)
+{
+    return hw->mem_current_addr.mem_current_addr;
+}
+
+/** @brief Reload the current address from the start address. */
+static inline void riscv_trace_ll_update_mem_current_addr(trace_dev_t *hw)
+{
+    hw->mem_addr_update.mem_current_addr_update = 1;
+}
+
+/*---------------------------------------------------------------------------
+ * Status
+ *--------------------------------------------------------------------------*/
+
+static inline uint32_t riscv_trace_ll_get_fifo_status(trace_dev_t *hw)
+{
+    return hw->fifo_status.val;
+}
+
+/*---------------------------------------------------------------------------
+ * Trigger, loop mode and restart
+ *--------------------------------------------------------------------------*/
+
+static inline void riscv_trace_ll_trigger_on(trace_dev_t *hw)
+{
+    hw->trigger.trigger_on = 1;
+}
+
+static inline void riscv_trace_ll_trigger_off(trace_dev_t *hw)
+{
+    hw->trigger.trigger_off = 1;
+}
+
+static inline void riscv_trace_ll_set_mem_loop(trace_dev_t *hw, bool loop)
+{
+    hw->trigger.mem_loop = loop;
+}
+
+static inline void riscv_trace_ll_set_restart_ena(trace_dev_t *hw, bool enable)
+{
+    hw->trigger.restart_ena = enable;
+}
+
+/*---------------------------------------------------------------------------
+ * Resynchronization
+ *--------------------------------------------------------------------------*/
+
+/** @brief Whether the resync counter can represent the given mode. */
+static inline bool riscv_trace_ll_resync_mode_is_supported(uint32_t mode)
+{
+    // 1-bit field: this encoder always counts and has no "disabled" mode.
+    return mode == RISCV_TRACE_RESYNC_PACKET || mode == RISCV_TRACE_RESYNC_CYCLE;
+}
+
+static inline void riscv_trace_ll_set_resync_mode(trace_dev_t *hw, uint32_t mode)
+{
+    // 1-bit field: 0 = count by cycle, 1 = count by packet.
+    hw->resync_prolonged.resync_mode = (mode == RISCV_TRACE_RESYNC_PACKET);
+}
+
+static inline void riscv_trace_ll_set_resync_threshold(trace_dev_t *hw, uint32_t threshold)
+{
+    hw->resync_prolonged.resync_prolonged = threshold;
+}
+
+/*---------------------------------------------------------------------------
+ * Interrupts
+ *--------------------------------------------------------------------------*/
+
+static inline void riscv_trace_ll_set_intr_ena(trace_dev_t *hw, uint32_t mask)
+{
+    hw->intr_ena.val = mask;
+}
+
+static inline uint32_t riscv_trace_ll_get_intr_raw(trace_dev_t *hw)
+{
+    return hw->intr_raw.val;
+}
+
+static inline void riscv_trace_ll_clear_intr(trace_dev_t *hw, uint32_t mask)
+{
+    hw->intr_clr.val = mask;
+}
+
+#ifdef __cplusplus
+}
+#endif

components/esp_hal_debug_assist/esp32p4/include/hal/riscv_trace_ll.h

@@ -156,6 +156,13 @@ static inline void riscv_trace_ll_set_dm_trigger_ena(trace_dev_t *hw, bool enabl
  * Resynchronization
  *--------------------------------------------------------------------------*/
 
+/** @brief Whether the resync counter can represent the given mode. */
+static inline bool riscv_trace_ll_resync_mode_is_supported(uint32_t mode)
+{
+    return mode == RISCV_TRACE_RESYNC_DISABLED || mode == RISCV_TRACE_RESYNC_PACKET ||
+           mode == RISCV_TRACE_RESYNC_CYCLE;
+}
+
 static inline void riscv_trace_ll_set_resync_mode(trace_dev_t *hw, uint32_t mode)
 {
     hw->resync_prolonged.resync_mode = mode;

components/esp_hal_debug_assist/esp32s31/include/hal/riscv_trace_ll.h

@@ -152,6 +152,13 @@ static inline void riscv_trace_ll_set_dm_trigger_ena(trace_dev_t *hw, bool enabl
  * Resynchronization
  *--------------------------------------------------------------------------*/
 
+/** @brief Whether the resync counter can represent the given mode. */
+static inline bool riscv_trace_ll_resync_mode_is_supported(uint32_t mode)
+{
+    return mode == RISCV_TRACE_RESYNC_DISABLED || mode == RISCV_TRACE_RESYNC_PACKET ||
+           mode == RISCV_TRACE_RESYNC_CYCLE;
+}
+
 static inline void riscv_trace_ll_set_resync_mode(trace_dev_t *hw, uint32_t mode)
 {
     hw->resync_prolonged.resync_mode = mode;

components/esp_hal_debug_assist/include/hal/riscv_trace_types.h

@@ -34,6 +34,20 @@ typedef enum {
     RISCV_TRACE_PRIV_MACHINE    = 3, /*!< Machine mode */
 } riscv_trace_priv_t;
 
+/**
+ * @brief Resynchronization mode selected by the resync counter.
+ *
+ * Values follow the v2.0 (2-bit) register encoding, which the driver's public
+ * enum also uses. Targets with a narrower field implement a subset and their LL
+ * translates the value when writing the register (see
+ * riscv_trace_ll_resync_mode_is_supported()).
+ */
+typedef enum {
+    RISCV_TRACE_RESYNC_DISABLED = 0, /*!< Periodic resync disabled */
+    RISCV_TRACE_RESYNC_PACKET   = 2, /*!< Resync counter counts by packet */
+    RISCV_TRACE_RESYNC_CYCLE    = 3, /*!< Resync counter counts by cycle */
+} riscv_trace_resync_mode_t;
+
 /**
  * @brief Trace encoder work-status field.
  *

components/esp_riscv_trace/src/esp_riscv_trace.c

@@ -120,6 +120,7 @@ static uint32_t trace_buffer_caps(esp_riscv_trace_buffer_mem_t mem)
            : ESP_RISCV_TRACE_BUFFER_CAPS_INTERNAL;
 }
 
+#if SOC_RISCV_TRACE_FILTER_SUPPORTED
 static bool is_valid_filter_comparator(const esp_riscv_trace_filter_comparator_t *c)
 {
     return (c->input == ESP_RISCV_TRACE_FILTER_INPUT_IADDR ||
@@ -155,6 +156,7 @@ static esp_err_t validate_filter_config(const esp_riscv_trace_filter_config_t *c
     }
     return ESP_OK;
 }
+#endif // SOC_RISCV_TRACE_FILTER_SUPPORTED
 
 static esp_err_t validate_trace_config(esp_riscv_trace_core_t core_id, const esp_riscv_trace_config_t *config,
                                        esp_riscv_trace_handle_t *ret_handle)
@@ -167,6 +169,8 @@ static esp_err_t validate_trace_config(esp_riscv_trace_core_t core_id, const esp
     ESP_RETURN_ON_FALSE(is_valid_address_mode(config->address_mode), ESP_ERR_INVALID_ARG, TAG, "invalid address mode");
     ESP_RETURN_ON_FALSE(is_valid_mem_mode(config->mem_mode), ESP_ERR_INVALID_ARG, TAG, "invalid memory mode");
     ESP_RETURN_ON_FALSE(is_valid_resync_mode(config->resync_mode), ESP_ERR_INVALID_ARG, TAG, "invalid resync mode");
+    ESP_RETURN_ON_FALSE(riscv_trace_ll_resync_mode_is_supported((uint32_t)config->resync_mode),
+                        ESP_ERR_NOT_SUPPORTED, TAG, "resync mode not supported on this target");
     ESP_RETURN_ON_FALSE(is_valid_ahb_burst(config->ahb_burst), ESP_ERR_INVALID_ARG, TAG, "invalid AHB burst");
     ESP_RETURN_ON_FALSE(is_valid_core_mask(config->core_mask), ESP_ERR_INVALID_ARG, TAG, "invalid core mask");
     ESP_RETURN_ON_FALSE(is_valid_buffer_mem(config->buffer_mem), ESP_ERR_INVALID_ARG, TAG, "invalid buffer memory");

components/esp_riscv_trace/test_apps/basic/README.md

@@ -1,5 +1,5 @@
-| Supported Targets | ESP32-C5 | ESP32-P4 | ESP32-S31 |
-| ----------------- | -------- | -------- | --------- |
+| Supported Targets | ESP32-C5 | ESP32-C6 | ESP32-H2 | ESP32-P4 | ESP32-S31 |
+| ----------------- | -------- | -------- | -------- | -------- | --------- |
 
 # RISC-V Trace Basic Test App
 

components/soc/esp32c6/include/soc/Kconfig.soc_caps.in

@@ -183,6 +183,10 @@ config SOC_APM_SUPPORTED
     bool
     default y
 
+config SOC_RISCV_TRACE_SUPPORTED
+    bool
+    default y
+
 config SOC_PMU_SUPPORTED
     bool
     default y
@@ -1350,3 +1354,7 @@ config SOC_LP_CORE_LP_UART_WAKEUP_KEEP_TRIGGERED
 config SOC_DEBUG_HAVE_OCD_STUB_BINS
     bool
     default y
+
+config SOC_RISCV_TRACE_PRIV_WIDTH
+    int
+    default 1

components/soc/esp32c6/include/soc/soc_caps.h

@@ -68,6 +68,7 @@
 #define SOC_SDIO_SLAVE_SUPPORTED        1
 #define SOC_BOD_SUPPORTED               1
 #define SOC_APM_SUPPORTED               1 /*!< Support for APM peripheral */
+#define SOC_RISCV_TRACE_SUPPORTED       1
 #define SOC_PMU_SUPPORTED               1
 #define SOC_PMU_PVT_SUPPORTED           1
 #define SOC_PAU_SUPPORTED               1
@@ -548,3 +549,6 @@
 
 /*------------------------------------- DEBUG CAPS -------------------------------------*/
 #define SOC_DEBUG_HAVE_OCD_STUB_BINS    (1)
+
+/*-------------------------- RISC-V TRACE CAPS ------------------------------*/
+#define SOC_RISCV_TRACE_PRIV_WIDTH                  (1U) /*!< Bits in the privilege field (privilege_width_p) */

components/soc/esp32c6/ld/esp32c6.peripherals.ld

@@ -73,3 +73,5 @@ PROVIDE ( LPPERI        = 0x600B2800 );
 PROVIDE ( LP_ANA_PERI   = 0x600B2C00 );
 PROVIDE ( LP_APM        = 0x600B3800 );
 PROVIDE ( OTP_DEBUG     = 0x600B3C00 );
+
+PROVIDE ( TRACE   = 0x600C0000 );

components/soc/esp32h2/include/soc/Kconfig.soc_caps.in

@@ -195,6 +195,10 @@ config SOC_APM_SUPPORTED
     bool
     default y
 
+config SOC_RISCV_TRACE_SUPPORTED
+    bool
+    default y
+
 config SOC_PMU_SUPPORTED
     bool
     default y
@@ -1250,3 +1254,7 @@ config SOC_BLE_PERIODIC_ADV_WITH_RESPONSE
 config SOC_DEBUG_HAVE_OCD_STUB_BINS
     bool
     default y
+
+config SOC_RISCV_TRACE_PRIV_WIDTH
+    int
+    default 1

components/soc/esp32h2/include/soc/soc_caps.h

@@ -87,6 +87,7 @@
 #define SOC_BOD_SUPPORTED               1
 #define SOC_VBAT_SUPPORTED              1
 #define SOC_APM_SUPPORTED               1 /*!< Support for APM peripheral */
+#define SOC_RISCV_TRACE_SUPPORTED       1
 #define SOC_PMU_SUPPORTED               1
 #define SOC_RTC_TIMER_SUPPORTED         1
 #define SOC_LP_AON_SUPPORTED            1
@@ -530,3 +531,6 @@
 
 /*------------------------------------- DEBUG CAPS -------------------------------------*/
 #define SOC_DEBUG_HAVE_OCD_STUB_BINS    (1)
+
+/*-------------------------- RISC-V TRACE CAPS ------------------------------*/
+#define SOC_RISCV_TRACE_PRIV_WIDTH                  (1U) /*!< Bits in the privilege field (privilege_width_p) */

components/soc/esp32h2/ld/esp32h2.peripherals.ld

@@ -67,3 +67,5 @@ PROVIDE ( LPPERI        = 0x600B2800 );
 PROVIDE ( LP_ANA_PERI   = 0x600B2C00 );
 PROVIDE ( LP_APM        = 0x600B3800 );
 PROVIDE ( OTP_DEBUG     = 0x600B3C00 );
+
+PROVIDE ( TRACE   = 0x600C0000 );

components/soc/esp32h2/register/soc/trace_struct.h

@@ -16,10 +16,10 @@ extern "C" {
  */
 typedef union {
     struct {
-        /** mem_staet_addr : R/W; bitpos: [31:0]; default: 0;
+        /** mem_start_addr : R/W; bitpos: [31:0]; default: 0;
          *  The start address of trace memory
          */
-        uint32_t mem_staet_addr:32;
+        uint32_t mem_start_addr:32;
     };
     uint32_t val;
 } trace_mem_start_addr_reg_t;

components/soc/esp32h21/register/soc/trace_struct.h

@@ -16,10 +16,10 @@ extern "C" {
  */
 typedef union {
     struct {
-        /** mem_staet_addr : R/W; bitpos: [31:0]; default: 0;
+        /** mem_start_addr : R/W; bitpos: [31:0]; default: 0;
          *  The start address of trace memory
          */
-        uint32_t mem_staet_addr:32;
+        uint32_t mem_start_addr:32;
     };
     uint32_t val;
 } trace_mem_start_addr_reg_t;