G32S10 Bus Monitor HAL 接口

1. 资源模型与公开类型

1.1 模块基地址与通道

Bus Monitor 基地址：

当前支持 8 个监测通道：

基础常量：

• HAL_BUS_MONITOR_CHANNEL_COUNT = 8

• HAL_BUS_MONITOR_CHANNEL_MASK(channel) 直接按((uint32_t)1U << (uint32_t)(channel)) 生成通道 mask。该宏不检查通道范围， 调用方必须保证 channel 为 0~`7`；非法值不保证产生有效 mask。

1.2 带宽监测模式

带宽监测支持两种停止模式：

1.3 公开结构体

1.3.1 hal_bus_monitor_handle_t

调用方提供存储的单实例 HAL 上下文。其字段均由 HAL 维护；hal_bus_monitor_init()成功后，应用不得直接修改。

1.3.2 hal_bus_monitor_channel_config_t

单通道带宽采样配置：

1.3.3 hal_bus_monitor_counter_t

单通道带宽计数结果：

1.3.4 hal_bus_monitor_bandwidth_t

单通道读写带宽计算结果：

1.3.5 hal_bus_monitor_debug_channel_config_t

单通道 debug 超时阈值与地址范围配置：

1.3.6 hal_bus_monitor_debug_snapshot_t

一次读取的原始 debug 现场：

1.3.7 hal_bus_monitor_axi_debug_status_t

AXI 通道 debug 状态解码结构体：

1.3.8 hal_bus_monitor_ahb_debug_status_t

AHB 通道 debug 状态解码结构体：

1.3.9 hal_bus_monitor_debug_channel_status_t

由一个原始通道状态解码得到的带类型结果：

2. HAL 接口规范

2.1 初始化与基础辅助

2.1.1 hal_bus_monitor_init

error_code_t hal_bus_monitor_init(hal_bus_monitor_handle_t *handle);

功能说明： 初始化调用方提供的 handle，并独占唯一的 Bus Monitor 硬件实例。

参数表：

返回值表：

补充说明：

• 初始化会停止全部带宽通道、关闭并清除 done IRQ、关闭 debug。

• 该过程会清除先前硬件状态；不能与其他 Bus Monitor 使用者并发执行。

2.1.2 hal_bus_monitor_deinit

error_code_t hal_bus_monitor_deinit(hal_bus_monitor_handle_t *handle);

功能说明： 停止 Bus Monitor 活动并释放唯一实例。

参数表：

返回值表：

补充说明：

• BSP 必须先停用并释放 IRQ_MONITOR，再调用本接口，避免 IRQ entry 使用失效 handle。

• 本接口会停止通道、关闭/清除 done IRQ、关闭 debug，并将 handle 清零。

2.1.3 hal_bus_monitor_channel_config_struct_init

void hal_bus_monitor_channel_config_struct_init(
    hal_bus_monitor_channel_config_t *config);

功能说明： 填充单通道带宽采样配置的手动停止默认值。

参数表：

返回值表：

补充说明：

• 默认 mode = HAL_BUS_MONITOR_MODE_MANUAL_STOP。

• 默认 auto_stop_threshold_cycles = 0。

2.2 带宽监测接口

2.2.1 hal_bus_monitor_channel_configure

error_code_t hal_bus_monitor_channel_configure(
    hal_bus_monitor_handle_t *handle,
    hal_bus_monitor_channel_t channel,
    const hal_bus_monitor_channel_config_t *config);

功能说明： 配置一个空闲通道的采样模式和 auto-stop 阈值；本接口不启动采样。

参数表：

返回值表：

补充说明：

• AUTO_STOP 必须提供非零 auto_stop_threshold_cycles。

• MANUAL_STOP 的阈值必须为 0。

• 配置手动模式会关闭该通道的 done IRQ。

2.2.2 hal_bus_monitor_start

error_code_t hal_bus_monitor_start(
    hal_bus_monitor_handle_t *handle,
    uint32_t channel_mask);

功能说明： 清除旧计数和 auto 模式旧 done 状态，然后启动已配置且未运行的通道。

参数表：

返回值表：

补充说明：

• 每次调用都开始一个新样本，不需要单独清计数 API。

• 对 auto-stop 通道，HAL 自动清 done、使能 done IRQ。

• 平台仍负责申请和使能 IRQ_MONITOR。

2.2.3 hal_bus_monitor_stop

error_code_t hal_bus_monitor_stop(
    hal_bus_monitor_handle_t *handle,
    uint32_t channel_mask);

功能说明： 完成正在运行的手动停止模式通道。

参数表：

返回值表：

2.2.4 hal_bus_monitor_abort

error_code_t hal_bus_monitor_abort(
    hal_bus_monitor_handle_t *handle,
    uint32_t channel_mask);

功能说明： 提前停止正在运行的手动或自动通道。

参数表：

返回值表：

补充说明：

• abort 后仍可读取计数器，但其值不代表完整 auto-stop 样本。

• abort 自动通道时，HAL 同时关闭并清除其 done IRQ。

2.2.5 hal_bus_monitor_counter_read

error_code_t hal_bus_monitor_counter_read(
    hal_bus_monitor_handle_t *handle,
    hal_bus_monitor_channel_t channel,
    hal_bus_monitor_counter_t *counter_out);

功能说明： 读取单个通道当前硬件计数器。运行中读到的是实时快照；手动 stop 或 auto callback 之后读到的是最终值。

参数表：

返回值表：

2.2.6 hal_bus_monitor_irq_callback_register

error_code_t hal_bus_monitor_irq_callback_register(
    hal_bus_monitor_handle_t *handle,
    hal_bus_monitor_irq_callback_t callback,
    void *user_ctx);

功能说明： 注册一个 auto-stop done callback；当 callback 为 NULL 时注销 callback。

参数表：

返回值表：

补充说明：

• auto-stop 通道必须在 start() 前注册非空 callback。

• auto-stop 样本启动后，在 done IRQ 被 hal_bus_monitor_irq_handler() 处理或被hal_bus_monitor_abort() 清除前，不允许更换或注销 callback。

• callback 在 IRQ 上下文执行，只允许调用 hal_bus_monitor_counter_read() 和hal_bus_monitor_bandwidth_calculate()；不得阻塞或调用任何状态变更 API。

2.2.7 hal_bus_monitor_irq_handler

void hal_bus_monitor_irq_handler(hal_bus_monitor_handle_t *handle);

功能说明： 由 BSP 注册的 IRQ_MONITOR entry 调用，处理 Bus Monitor done IRQ 并分发 callback。

参数表：

返回值表：

补充说明：

• 本接口运行在 IRQ 上下文。

• HAL 会停用并清除本次完成通道的 done IRQ，更新运行状态，再调用 callback。

• BSP/platform 负责 im_irq_request()、im_irq_enable()、im_irq_disable() 和im_irq_release()；HAL 不申请或释放中断。

2.2.8 hal_bus_monitor_bandwidth_calculate

error_code_t hal_bus_monitor_bandwidth_calculate(
    hal_bus_monitor_channel_t channel,
    const hal_bus_monitor_counter_t *counter,
    uint32_t channel_clock_hz,
    hal_bus_monitor_bandwidth_t *bandwidth_out);

功能说明： 根据通道类型、计数结果和实际 monitor 时钟频率计算读写带宽；本接口不访问硬件。

参数表：

返回值表：

补充说明：

带宽计算公式：

BW_write_B/s = Fch_Hz * WVAL_HIT_NUM * BYTES_PER_TRANSFER / VAL_CLK_NUM
BW_read_B/s  = Fch_Hz * RVAL_HIT_NUM * BYTES_PER_TRANSFER / VAL_CLK_NUM

AXI 通道 BYTES_PER_TRANSFER = 8，AHB 通道为 4。读写方向分别计算；若某个方向的 中间结果超过 uint64_t，该方向的输出字段饱和为 UINT64_MAX，不会回绕。此时hal_bus_monitor_bandwidth_calculate() 仍返回 IM_OK，而不是返回UINT64_MAX 作为错误码。

2.3 Debug 配置与快照接口

2.3.1 hal_bus_monitor_debug_channel_config_struct_init

void hal_bus_monitor_debug_channel_config_struct_init(
    hal_bus_monitor_debug_channel_config_t *config);

功能说明： 填充单通道 debug 配置为硬件复位默认值。

参数表：

返回值表：

补充说明：

• 默认 timeout 为 0。

• 默认地址范围为 0x00000000 到 0xffffffff。

2.3.2 hal_bus_monitor_debug_channel_configure

error_code_t hal_bus_monitor_debug_channel_configure(
    hal_bus_monitor_handle_t *handle,
    hal_bus_monitor_channel_t channel,
    const hal_bus_monitor_debug_channel_config_t *config);

功能说明： 在硬件 debug 关闭期间，配置一个通道的 debug 超时阈值和包含式地址范围。

参数表：

返回值表：

补充说明：

• DBG_THRES[n] 配置超时阈值。

• DBG_ADDR_START[n]、DBG_ADDR_END[n] 配置包含式地址范围。

• 调用方必须按 hal_bus_monitor_debug_disable()、配置通道、hal_bus_monitor_debug_enable() 的顺序操作。

• hal_bus_monitor_debug_channel_configure() 不会自动关闭或重新使能 debug； debug 已使能时它会直接返回 IM_ERR_BUSY。

2.3.3 hal_bus_monitor_debug_enable

error_code_t hal_bus_monitor_debug_enable(hal_bus_monitor_handle_t *handle);

功能说明： 使能 Bus Monitor debug 捕获。

参数表：

返回值表：

2.3.4 hal_bus_monitor_debug_disable

error_code_t hal_bus_monitor_debug_disable(hal_bus_monitor_handle_t *handle);

功能说明： 关闭 Bus Monitor debug 捕获，使 debug 通道配置可被修改。

参数表：

返回值表：

2.3.5 hal_bus_monitor_read_debug_snapshot

error_code_t hal_bus_monitor_read_debug_snapshot(
    hal_bus_monitor_handle_t *handle,
    hal_bus_monitor_debug_snapshot_t *snapshot_out);

功能说明： 一次读取全部八个通道和系统 debug 寄存器的原始值。

参数表：

返回值表：

补充说明：

• 原始快照是现场证据；解码结果不保存 raw 值。

• HAL 无法判断快照是否对应特定 watchdog/pprst 复位；调用方应另行记录复位原因和时间。

2.3.6 hal_bus_monitor_regs_dump

error_code_t hal_bus_monitor_regs_dump(void);

功能说明： 直接读取并打印全部已定义的 Bus Monitor 寄存器，不需要初始化 handle。

参数表：

返回值表：

2.3.7 hal_bus_monitor_decode_debug_channel

error_code_t hal_bus_monitor_decode_debug_channel(
    hal_bus_monitor_channel_t channel,
    uint32_t raw,
    hal_bus_monitor_debug_channel_status_t *status_out);

功能说明： 按通道的 AXI/AHB 类型解码一个 DBG_DDRC_CHn 原始值；本接口不访问硬件。

参数表：

返回值表：

3. 当前实现约束与行为说明

3.1 自动停止阈值只在自动停止模式下生效

• CH_CLK_THRES[n] 用于 auto-stop 模式。

• 内部 clock 计数器达到阈值后，硬件停止监测并置位 CH_INT_STATE.CHn_CNT_DONE。

• auto-stop 必须注册 callback；HAL 在 start() 时使能 done IRQ，并在 IRQ handler 中停止完成通道。

• 手动停止模式下软件应调用 hal_bus_monitor_stop() 结束监测。

3.2 start() 总是清理上一次样本状态

• HAL 每次 hal_bus_monitor_start() 都通过 CH_FUN_CTRL.CHn_FUN_CLR 清除选中通道的计数。

• 对 auto-stop 通道，HAL 同时清除旧 done 状态后再使能 done IRQ。

• 调用方不得绕过 HAL 直接操作相关寄存器，否则 handle 的运行状态可能与硬件不一致。

4. 典型用法

4.1 手动控制模式统计带宽

static hal_bus_monitor_handle_t monitor;
hal_bus_monitor_channel_config_t config;
hal_bus_monitor_counter_t counter;
hal_bus_monitor_bandwidth_t bandwidth;
/* FPGA 示例假设 CH0~CH2 的监测时钟为 25 MHz；实际值必须按目标配置确认。 */
uint32_t channel1_clock_hz = 25000000U;
uint64_t total_bytes_per_sec;

hal_bus_monitor_init(&monitor);
hal_bus_monitor_channel_config_struct_init(&config);
hal_bus_monitor_channel_configure(&monitor, HAL_BUS_MONITOR_CHANNEL_1, &config);

hal_bus_monitor_start(&monitor,
                      HAL_BUS_MONITOR_CHANNEL_MASK(HAL_BUS_MONITOR_CHANNEL_1));

/* Execute the desired sampling workload. */

hal_bus_monitor_stop(&monitor,
                     HAL_BUS_MONITOR_CHANNEL_MASK(HAL_BUS_MONITOR_CHANNEL_1));
hal_bus_monitor_counter_read(&monitor, HAL_BUS_MONITOR_CHANNEL_1, &counter);
hal_bus_monitor_bandwidth_calculate(HAL_BUS_MONITOR_CHANNEL_1,
                                    &counter,
                                    channel1_clock_hz,
                                    &bandwidth);
total_bytes_per_sec = bandwidth.write_bytes_per_sec + bandwidth.read_bytes_per_sec;
hal_bus_monitor_deinit(&monitor);

4.2 自动控制模式统计带宽

static hal_bus_monitor_handle_t monitor;
static volatile bool monitor_done;
hal_bus_monitor_channel_config_t config;
hal_bus_monitor_counter_t counter;

static void monitor_done_callback(hal_bus_monitor_handle_t *handle,
                                  uint32_t done_channel_mask,
                                  void *user_ctx)
{
    (void)handle;
    (void)user_ctx;

    if ((done_channel_mask & HAL_BUS_MONITOR_CHANNEL_MASK(HAL_BUS_MONITOR_CHANNEL_6)) != 0U) {
        monitor_done = true;
    }
}

/* BSP IRQ entry calls hal_bus_monitor_irq_handler(&monitor). */
hal_bus_monitor_init(&monitor);
hal_bus_monitor_irq_callback_register(&monitor, monitor_done_callback, NULL);
hal_bus_monitor_channel_config_struct_init(&config);
config.mode = HAL_BUS_MONITOR_MODE_AUTO_STOP;
config.auto_stop_threshold_cycles = 1000000U;
hal_bus_monitor_channel_configure(&monitor, HAL_BUS_MONITOR_CHANNEL_6, &config);
hal_bus_monitor_start(&monitor,
                      HAL_BUS_MONITOR_CHANNEL_MASK(HAL_BUS_MONITOR_CHANNEL_6));

/* Wait for monitor_done in task context; do not block in the callback. */
hal_bus_monitor_counter_read(&monitor, HAL_BUS_MONITOR_CHANNEL_6, &counter);

4.3 配置 debug 地址范围并读取原始快照

static hal_bus_monitor_handle_t monitor;
hal_bus_monitor_debug_channel_config_t config;
hal_bus_monitor_debug_snapshot_t snapshot;
hal_bus_monitor_debug_channel_status_t status;

hal_bus_monitor_init(&monitor);
hal_bus_monitor_debug_disable(&monitor);
hal_bus_monitor_debug_channel_config_struct_init(&config);
config.timeout_threshold_cycles = 10000U;
config.addr_start = 0x00000000U;
config.addr_end = 0xffffffffU;
hal_bus_monitor_debug_channel_configure(&monitor, HAL_BUS_MONITOR_CHANNEL_0, &config);
hal_bus_monitor_debug_enable(&monitor);

/* After watchdog reset or pprst reset, read the raw evidence first. */
hal_bus_monitor_read_debug_snapshot(&monitor, &snapshot);
hal_bus_monitor_decode_debug_channel(HAL_BUS_MONITOR_CHANNEL_0,
                                     snapshot.channel_raw[HAL_BUS_MONITOR_CHANNEL_0],
                                     &status);