refactor(hal): extract assist_debug, debug_probe and trace into esp_hal_debug_assist

Move the following modules from the hal component into a new dedicated
esp_hal_debug_assist component, following the esp_hal_timg pattern:

- assist_debug (hal + target-specific LL headers)
- debug_probe (types + target-specific LL headers)
- riscv_trace (hal + types + source + target-specific LL headers)
- trace_ll (esp32/esp32s2/esp32s3 target-specific LL headers)

Update the following components to depend on esp_hal_debug_assist:
esp_system, riscv, bootloader_support, esp_hw_support, esp_riscv_trace

Remove riscv_trace_hal.c from the hal component.
This commit is contained in:
morris
2026-07-21 11:28:11 +08:00
parent e8a5192a18
commit 26a22512eb
32 changed files with 459 additions and 242 deletions
@@ -0,0 +1,174 @@
/*
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include "soc/assist_debug_reg.h"
#define ASSIST_DEBUG_SP_SPILL_BITS (ASSIST_DEBUG_CORE_0_SP_SPILL_MIN_ENA | ASSIST_DEBUG_CORE_0_SP_SPILL_MAX_ENA)
#define ASSIST_DEBUG_CORE_0_MONITOR_REG ASSIST_DEBUG_CORE_0_INTR_ENA_REG
#define ASSIST_DEBUG_CORE_1_MONITOR_REG ASSIST_DEBUG_CORE_1_INTR_ENA_REG
#ifndef __ASSEMBLER__
#include <stdbool.h>
#include <stdint.h>
#include "hal/assert.h"
#include "soc/hp_sys_clkrst_struct.h"
#include "soc/soc_caps.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* Most other peripherals have 4 interrupt-related registers: INT_ENA_REG, INT_CLR_REG, INT_RAW_REG, INT_ST_REG, the
* meaning of which is well-understood.
*
* Assist_debug peripheral uses a different structure of interrupt registers:
* INT_ENA_REG, INT_RLS_REG, INT_CLR_REG, INT_RAW_REG.
*
* Their behavior can be explained using the following (verilog-like) pseudo-code:
* reg sp_spill_max_st
* assign sp_spill_max = (sp > SP_MAX_REG)
* assign SP_SPILL_MAX_RAW = sp_spill_max & SPILL_MAX_ENA
* always (@posedge clk) begin
* if (reset) then sp_spill_max_st <= 0
* elif SP_SPILL_MAX_CLR then sp_spill_max_st <= 0
* else sp_spill_max_st <= SP_SPILL_MAX_RAW & SP_SPILL_MAX_RLS
* end
* // ...same for sp_spill_min and other things dsoc/hp_sys_clkrst_struct.hebug_assist can check.
*
* // this is the final interrupt line coming out of the peripheral:
* assign DEBUG_ASSIST_INT = sp_spill_max_st | sp_spill_min_st | ...
*
* Basically, there is no "ST" register showing the final (latched) interrupt state, and there is an additional
* "RLS" register which just like "ENA" can be used to mask the interrupt.
* Note that writing to CLR clears the (internal) latched interrupt state 'sp_spill_max_st',
* but doesn't affect the software-readable RAW register.
*
* In this code, we use "ENA" to enable monitoring of a particular condition, and "RLS" to enable the interrupt.
* This allows checking whether the condition (e.g. sp > SP_MAX) has occurred by reading the RAW register, without
* actually triggering the interrupt. Hence you will see the somewhat counter-intuitive use of "RLS" to enable the
* interrupt, instead of "ENA".
*/
/* These functions are optimized and designed for internal usage.
* So, the API may differ from general ll layer pattern */
__attribute__((always_inline))
static inline void assist_debug_ll_sp_spill_monitor_enable(uint32_t core_id)
{
REG_SET_BIT(core_id ? ASSIST_DEBUG_CORE_1_INTR_ENA_REG : ASSIST_DEBUG_CORE_0_INTR_ENA_REG, ASSIST_DEBUG_SP_SPILL_BITS);
}
__attribute__((always_inline))
static inline void assist_debug_ll_sp_spill_monitor_disable(uint32_t core_id)
{
REG_CLR_BIT(core_id ? ASSIST_DEBUG_CORE_1_INTR_ENA_REG : ASSIST_DEBUG_CORE_0_INTR_ENA_REG, ASSIST_DEBUG_SP_SPILL_BITS);
}
__attribute__((always_inline))
static inline void assist_debug_ll_sp_spill_interrupt_enable(uint32_t core_id)
{
REG_SET_BIT(core_id ? ASSIST_DEBUG_CORE_1_INTR_RLS_REG : ASSIST_DEBUG_CORE_0_INTR_RLS_REG, ASSIST_DEBUG_SP_SPILL_BITS);
}
__attribute__((always_inline))
static inline void assist_debug_ll_sp_spill_interrupt_disable(uint32_t core_id)
{
REG_CLR_BIT(core_id ? ASSIST_DEBUG_CORE_1_INTR_RLS_REG : ASSIST_DEBUG_CORE_0_INTR_RLS_REG, ASSIST_DEBUG_SP_SPILL_BITS);
}
__attribute__((always_inline))
static inline bool assist_debug_ll_sp_spill_is_fired(uint32_t core_id)
{
return REG_READ(core_id ? ASSIST_DEBUG_CORE_1_INTR_RAW_REG : ASSIST_DEBUG_CORE_0_INTR_RAW_REG) & ASSIST_DEBUG_SP_SPILL_BITS;
}
__attribute__((always_inline))
static inline void assist_debug_ll_sp_spill_interrupt_clear(uint32_t core_id)
{
REG_WRITE(core_id ? ASSIST_DEBUG_CORE_1_INTR_CLR_REG : ASSIST_DEBUG_CORE_0_INTR_CLR_REG, ASSIST_DEBUG_SP_SPILL_BITS);
}
__attribute__((always_inline))
static inline void assist_debug_ll_sp_spill_set_min(uint32_t core_id, uint32_t min)
{
REG_WRITE(core_id ? ASSIST_DEBUG_CORE_1_SP_MIN_REG : ASSIST_DEBUG_CORE_0_SP_MIN_REG, min);
}
__attribute__((always_inline))
static inline uint32_t assist_debug_ll_sp_spill_get_min(uint32_t core_id)
{
return REG_READ(core_id ? ASSIST_DEBUG_CORE_1_SP_MIN_REG : ASSIST_DEBUG_CORE_0_SP_MIN_REG);
}
__attribute__((always_inline))
static inline void assist_debug_ll_sp_spill_set_max(uint32_t core_id, uint32_t max)
{
REG_WRITE(core_id ? ASSIST_DEBUG_CORE_1_SP_MAX_REG : ASSIST_DEBUG_CORE_0_SP_MAX_REG, max);
}
__attribute__((always_inline))
static inline uint32_t assist_debug_ll_sp_spill_get_max(uint32_t core_id)
{
return REG_READ(core_id ? ASSIST_DEBUG_CORE_1_SP_MAX_REG : ASSIST_DEBUG_CORE_0_SP_MAX_REG);
}
__attribute__((always_inline))
static inline uint32_t assist_debug_ll_sp_spill_get_pc(uint32_t core_id)
{
return REG_READ(core_id ? ASSIST_DEBUG_CORE_1_SP_PC_REG : ASSIST_DEBUG_CORE_0_SP_PC_REG);
}
__attribute__((always_inline))
static inline void assist_debug_ll_enable_pc_recording(uint32_t core_id, bool enable)
{
uint32_t reg = core_id ? ASSIST_DEBUG_CORE_1_RCD_EN_REG : ASSIST_DEBUG_CORE_0_RCD_EN_REG;
uint32_t bits = ASSIST_DEBUG_CORE_0_RCD_PDEBUGEN | ASSIST_DEBUG_CORE_0_RCD_RECORDEN;
if (enable) {
REG_SET_BIT(reg, bits);
} else {
REG_CLR_BIT(reg, bits);
}
}
__attribute__((always_inline))
static inline void _assist_debug_ll_enable_bus_clock(__attribute__((unused)) uint32_t core_id, bool enable)
{
HP_SYS_CLKRST.soc_clk_ctrl0.reg_busmon_cpu_clk_en = enable;
REG_SET_FIELD(ASSIST_DEBUG_CLOCK_GATE_REG, ASSIST_DEBUG_CLK_EN, enable);
}
#define assist_debug_ll_enable_bus_clock(...) \
(void)__DECLARE_RCC_ATOMIC_ENV; _assist_debug_ll_enable_bus_clock(__VA_ARGS__)
__attribute__((always_inline))
static inline void _assist_debug_ll_reset_register(__attribute__((unused)) uint32_t core_id)
{
/* esp32p4 has no assist_debug reset register: disable & clear interrupts manually. */
for (int i = 0; i < SOC_CPU_CORES_NUM; i++) {
assist_debug_ll_sp_spill_monitor_disable(i);
assist_debug_ll_sp_spill_interrupt_clear(i);
assist_debug_ll_sp_spill_set_min(i, 0);
assist_debug_ll_sp_spill_set_max(i, 0xffffffff);
}
}
#define assist_debug_ll_reset_register(...) \
(void)__DECLARE_RCC_ATOMIC_ENV; _assist_debug_ll_reset_register(__VA_ARGS__)
__attribute__((always_inline))
static inline bool assist_debug_ll_is_debugger_active(void)
{
return REG_GET_BIT(ASSIST_DEBUG_CORE_0_DEBUG_MODE_REG, ASSIST_DEBUG_CORE_0_DEBUG_MODULE_ACTIVE);
}
#ifdef __cplusplus
}
#endif
#endif // __ASSEMBLER__
@@ -0,0 +1,166 @@
/*
* SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include "hal/misc.h"
#include "hal/assert.h"
#include "soc/hp_system_struct.h"
#include "soc/lp_system_struct.h"
#include "hal/debug_probe_types.h"
/**
* @brief Define how many channels are there in one debug probe unit
*/
#define DEBUG_PROBE_LL_CHANNELS_PER_UNIT 2
#ifdef __cplusplus
extern "C" {
#endif
// translate the HAL types into register values
#define DEBUG_PROBE_LL_PART_TO_REG_VAL(part) ((uint8_t[]) {0, 1}[(part)])
/**
* @brief Enable the debug probe module
*
* @param unit_id unit identifier, see debug_probe_unit_id_t
* @param en true: enable, false: disable
*/
static inline void debug_probe_ll_enable_unit(debug_probe_unit_id_t unit_id, bool en)
{
if (unit_id == DEBUG_PROBE_UNIT_HP) {
HP_SYSTEM.probea_ctrl.reg_probe_global_en = en;
} else {
LP_SYS.lp_probea_ctrl.probe_global_en = en;
}
}
/**
* @brief Enable a specific channel in the debug probe unit
*
* @param unit_id unit identifier, see debug_probe_unit_id_t
* @param channel channel number (only support 0 and 1)
* @param en true: enable, false: disable
*/
static inline void debug_probe_ll_enable_channel(debug_probe_unit_id_t unit_id, int channel, bool en)
{
// channel 0 is always enabled
if (channel == 1) {
if (unit_id == DEBUG_PROBE_UNIT_HP) {
HP_SYSTEM.probeb_ctrl.reg_probe_b_en = en;
} else {
LP_SYS.lp_probeb_ctrl.probe_b_en = en;
}
}
}
/**
* @brief Set the target module for a probe channel
*
* @param unit_id unit identifier, see debug_probe_unit_id_t
* @param channel channel number (only support 0 and 1)
* @param target_module HP: soc_debug_probe_target_t, LP: soc_debug_probe_target_lp_t
*/
static inline void debug_probe_ll_channel_set_target_module(debug_probe_unit_id_t unit_id, uint8_t channel, uint8_t target_module)
{
if (channel == 0) {
if (unit_id == DEBUG_PROBE_UNIT_HP) {
HP_SYSTEM.probea_ctrl.reg_probe_a_top_sel = target_module;
} else {
LP_SYS.lp_probea_ctrl.probe_a_top_sel = target_module;
}
} else {
if (unit_id == DEBUG_PROBE_UNIT_HP) {
HP_SYSTEM.probeb_ctrl.reg_probe_b_top_sel = target_module;
} else {
LP_SYS.lp_probeb_ctrl.probe_b_top_sel = target_module;
}
}
}
/**
* @brief Add signals from a specific group to the probe channel
*
* @note One sig_group contains 4 bytes of signals. The sig_byte_idx is used to select the byte in the sig_group.
*
* @param channel channel number (only support 0 and 1)
* @param sig_byte_idx signal byte index (0-3)
* @param sig_group signal group (0-15)
*/
static inline void debug_probe_ll_channel_add_signal_group(debug_probe_unit_id_t unit_id, uint8_t channel, uint8_t sig_byte_idx, uint8_t sig_group)
{
if (unit_id == DEBUG_PROBE_UNIT_HP) {
if (channel == 0) {
HP_SYSTEM.probea_ctrl.reg_probe_a_mod_sel &= ~(0xf << (sig_byte_idx * 4));
HP_SYSTEM.probea_ctrl.reg_probe_a_mod_sel |= (sig_group << (sig_byte_idx * 4));
} else {
HP_SYSTEM.probeb_ctrl.reg_probe_b_mod_sel &= ~(0xf << (sig_byte_idx * 4));
HP_SYSTEM.probeb_ctrl.reg_probe_b_mod_sel |= (sig_group << (sig_byte_idx * 4));
}
} else {
if (channel == 0) {
LP_SYS.lp_probea_ctrl.probe_a_mod_sel &= ~(0xf << (sig_byte_idx * 4));
LP_SYS.lp_probea_ctrl.probe_a_mod_sel |= (sig_group << (sig_byte_idx * 4));
} else {
LP_SYS.lp_probeb_ctrl.probe_b_mod_sel &= ~(0xf << (sig_byte_idx * 4));
LP_SYS.lp_probeb_ctrl.probe_b_mod_sel |= (sig_group << (sig_byte_idx * 4));
}
}
}
/**
* @brief Set the lower 16 bits of the probe output
*
* @param part where does the probe_top_out[15:0] come from
*/
static inline void debug_probe_ll_set_lower16_output(debug_probe_unit_id_t unit_id, int channel, debug_probe_split_u16_t part)
{
uint8_t val = (uint8_t)(channel * 2 + DEBUG_PROBE_LL_PART_TO_REG_VAL(part));
if (unit_id == DEBUG_PROBE_UNIT_HP) {
HP_SYSTEM.probea_ctrl.reg_probe_l_sel = val;
} else {
LP_SYS.lp_probea_ctrl.probe_l_sel = val;
}
}
/**
* @brief Set the upper 16 bits of the probe output
*
* @param part where does the probe_top_out[31:16] come from
* @note Only probe_top_out[15:0] can be routed to GPIO pads, but both HP and LP units still keep a 32-bit probe_top_out register.
*/
static inline void debug_probe_ll_set_upper16_output(debug_probe_unit_id_t unit_id, int channel, debug_probe_split_u16_t part)
{
uint8_t val = (uint8_t)(channel * 2 + DEBUG_PROBE_LL_PART_TO_REG_VAL(part));
if (unit_id == DEBUG_PROBE_UNIT_HP) {
HP_SYSTEM.probea_ctrl.reg_probe_h_sel = val;
} else {
LP_SYS.lp_probea_ctrl.probe_h_sel = val;
}
}
/**
* @brief Read the value that currently being probed
*
* @note Can only route the LSB probe_top_out[15:0] to the GPIO pad. But the register still saves 32 signal bits.
*
* @return the value that currently being probed
*/
static inline uint32_t debug_probe_ll_read_output(debug_probe_unit_id_t unit_id)
{
if (unit_id == DEBUG_PROBE_UNIT_HP) {
return HP_SYSTEM.probe_out.reg_probe_top_out;
} else {
return LP_SYS.lp_probe_out.probe_top_out;
}
}
#ifdef __cplusplus
}
#endif
@@ -0,0 +1,251 @@
/*
* SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include <stdint.h>
#include <stdbool.h>
#include "soc/trace_reg.h"
#include "soc/trace_struct.h"
#include "soc/hp_sys_clkrst_struct.h"
#include "hal/assert.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 || core == 1);
return core == 0 ? &TRACE0 : &TRACE1;
}
/*---------------------------------------------------------------------------
* Clock and reset
*--------------------------------------------------------------------------*/
/** @brief Enable or disable the common TRACE CPU and system clocks. */
static inline void riscv_trace_ll_enable_bus_clock(bool enable)
{
HP_SYS_CLKRST.soc_clk_ctrl0.reg_trace_cpu_clk_en = enable;
HP_SYS_CLKRST.soc_clk_ctrl0.reg_trace_sys_clk_en = enable;
}
/** @brief Assert and release the reset of the given encoder core. */
static inline void riscv_trace_ll_reset_register(int core)
{
if (core == 0) {
HP_SYS_CLKRST.hp_rst_en0.reg_rst_en_coretrace0 = 1;
HP_SYS_CLKRST.hp_rst_en0.reg_rst_en_coretrace0 = 0;
} else {
HP_SYS_CLKRST.hp_rst_en0.reg_rst_en_coretrace1 = 1;
HP_SYS_CLKRST.hp_rst_en0.reg_rst_en_coretrace1 = 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;
}
/*---------------------------------------------------------------------------
* Encoder options (config register)
*--------------------------------------------------------------------------*/
static inline void riscv_trace_ll_set_full_address(trace_dev_t *hw, bool full)
{
hw->config.full_address = full;
}
static inline void riscv_trace_ll_set_stall_ena(trace_dev_t *hw, bool enable)
{
hw->config.stall_ena = enable;
}
static inline void riscv_trace_ll_set_halt_ena(trace_dev_t *hw, bool enable)
{
hw->config.halt_ena = enable;
}
static inline void riscv_trace_ll_set_reset_ena(trace_dev_t *hw, bool enable)
{
hw->config.reset_ena = enable;
}
static inline void riscv_trace_ll_set_dm_trigger_ena(trace_dev_t *hw, bool enable)
{
hw->config.dm_trigger_ena = enable;
}
/*---------------------------------------------------------------------------
* Resynchronization
*--------------------------------------------------------------------------*/
static inline void riscv_trace_ll_set_resync_mode(trace_dev_t *hw, uint32_t mode)
{
hw->resync_prolonged.resync_mode = mode;
}
static inline void riscv_trace_ll_set_resync_threshold(trace_dev_t *hw, uint32_t threshold)
{
hw->resync_prolonged.resync_prolonged = threshold;
}
/*---------------------------------------------------------------------------
* AHB configuration
*--------------------------------------------------------------------------*/
static inline void riscv_trace_ll_set_ahb_burst(trace_dev_t *hw, uint32_t hburst)
{
hw->ahb_config.hburst = hburst;
}
static inline void riscv_trace_ll_set_ahb_max_incr(trace_dev_t *hw, uint32_t max_incr)
{
hw->ahb_config.max_incr = max_incr;
}
/*---------------------------------------------------------------------------
* 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;
}
/*---------------------------------------------------------------------------
* Filter unit
*--------------------------------------------------------------------------*/
static inline void riscv_trace_ll_set_filter_en(trace_dev_t *hw, bool enable)
{
hw->filter_control.filter_en = enable;
}
static inline void riscv_trace_ll_set_filter_control(trace_dev_t *hw, bool match_comp,
bool match_privilege, bool match_ecause,
bool match_interrupt)
{
hw->filter_control.match_comp = match_comp;
hw->filter_control.match_privilege = match_privilege;
hw->filter_control.match_ecause = match_ecause;
hw->filter_control.match_interrupt = match_interrupt;
}
static inline void riscv_trace_ll_set_filter_match_control(trace_dev_t *hw, bool priv_choice,
bool intr_value, uint32_t ecause_choice)
{
hw->filter_match_control.match_choice_privilege = priv_choice;
hw->filter_match_control.match_value_interrupt = intr_value;
hw->filter_match_control.match_choice_ecause = ecause_choice;
}
static inline void riscv_trace_ll_set_p_comparator(trace_dev_t *hw, uint32_t input,
uint32_t function, bool notify)
{
hw->filter_comparator_control.p_input = input;
hw->filter_comparator_control.p_function = function;
hw->filter_comparator_control.p_notify = notify;
}
static inline void riscv_trace_ll_set_s_comparator(trace_dev_t *hw, uint32_t input,
uint32_t function, bool notify)
{
hw->filter_comparator_control.s_input = input;
hw->filter_comparator_control.s_function = function;
hw->filter_comparator_control.s_notify = notify;
}
static inline void riscv_trace_ll_set_match_mode(trace_dev_t *hw, uint32_t mode)
{
hw->filter_comparator_control.match_mode = mode;
}
static inline void riscv_trace_ll_set_p_match_value(trace_dev_t *hw, uint32_t value)
{
hw->filter_p_comparator_match.p_match = value;
}
static inline void riscv_trace_ll_set_s_match_value(trace_dev_t *hw, uint32_t value)
{
hw->filter_s_comparator_match.s_match = value;
}
#ifdef __cplusplus
}
#endif