G32S10 TCU HAL 接口

1. 资源模型与公开类型

1.1 模块基地址与实例

当前SDK中 TCU_IOBASE 定义在 base.h，tcu_regs.h 中提供如下实例宏：

#define TCU         ((tcu_regs_t *)(uintptr_t)TCU_IOBASE)

说明：

• 实例宏使用 (uintptr_t) 做整数地址到指针的中间转换，避免部分编译器对整数直接转指针产生告警。

• 驱动接口通过 tcu_regs_t * 或 hal_tcu_handle_t.instance 传递外设基地址。

1.2 HAL公开宏

1.3 HAL运行状态

typedef enum {
    HAL_TCU_STATE_RESET = 0,
    HAL_TCU_STATE_READY,
    HAL_TCU_STATE_BUSY,
} hal_tcu_state_t;

说明：state 为模块级状态；通道运行状态通过 active_channel_mask 独立跟踪。

1.4 HAL错误标志

typedef enum {
    HAL_TCU_ERROR_NONE = 0U,
    HAL_TCU_ERROR_INVALID_PARAM = (1UL << 0U),
    HAL_TCU_ERROR_NOT_READY = (1UL << 1U),
    HAL_TCU_ERROR_BUSY = (1UL << 2U),
} hal_tcu_error_t;

说明：

• error_code 是latched诊断bitmask，成功路径不清除历史错误。

• hal_tcu_handle_init()、hal_tcu_init() 和 hal_tcu_deinit() 会重置运行状态并清零错误标志。

• hal_tcu_error_get() 在无效句柄时返回 HAL_TCU_ERROR_INVALID_PARAM，这与ADC HAL保持一致；调用者应使用当前API返回值判断当前操作结果。

1.5 回调ID

typedef enum {
    HAL_TCU_CALLBACK_FULL = 0U,
    HAL_TCU_CALLBACK_HALF = 1U,
    HAL_TCU_CALLBACK_CAPTURE = 2U,
} hal_tcu_callback_id_t;

说明：TCU IRQ入口按FULL、HALF、CAPTURE三类事件分别调用对应回调。

1.6 计数模式、边沿和正交group

typedef enum {
    HAL_TCU_COUNT_MODE_FULL = TCU_COUNT_MODE_FULL,
    HAL_TCU_COUNT_MODE_OVERFLOW = TCU_COUNT_MODE_OVERFLOW,
    HAL_TCU_COUNT_MODE_HALF = TCU_COUNT_MODE_HALF,
    HAL_TCU_COUNT_MODE_HALF_OR_Z = TCU_COUNT_MODE_HALF_OR_Z,
} hal_tcu_count_mode_t;

typedef enum {
    HAL_TCU_EDGE_NONE = TCU_EDGE_NONE,
    HAL_TCU_EDGE_POSITIVE = TCU_EDGE_POSITIVE,
    HAL_TCU_EDGE_NEGATIVE = TCU_EDGE_NEGATIVE,
    HAL_TCU_EDGE_BOTH = TCU_EDGE_BOTH,
} hal_tcu_edge_t;

typedef enum {
    HAL_TCU_QUADRATURE_GROUP_0 = 0U,
    HAL_TCU_QUADRATURE_GROUP_1 = 1U,
} hal_tcu_quadrature_group_t;

说明：枚举值直接对应底层寄存器字段编码，配置结构体中使用 uint8_t 保存。

1.7 HAL配置结构

1.7.1 hal_tcu_timer_config_t

1.7.2 hal_tcu_capture_config_t

捕获模式固定使能GPIO0作为捕获输入；GPIO1仅在正交编码模式中使用。

1.7.3 hal_tcu_quadrature_config_t

1.7.4 hal_tcu_adc_trigger_config_t

说明：

• ADC trigger固定使用通道0。

• ADC0由HALF事件触发，ADC1由FULL事件触发。

1.8 读数结构

typedef struct {
    uint16_t high;
    uint16_t period;
} hal_tcu_capture_value_t;

typedef struct {
    uint16_t current;
    uint16_t previous;
} hal_tcu_quadrature_value_t;

说明：

• hal_tcu_capture_value_t.high 对应 CAP_VALUE bits15:0。

• hal_tcu_capture_value_t.period 对应 CAP_VALUE bits31:16。

• hal_tcu_quadrature_value_t.current 对应 STORE_VALUE bits15:0。

• hal_tcu_quadrature_value_t.previous 对应 STORE_VALUE bits31:16。

1.9 HAL回调和句柄

typedef struct hal_tcu_handle hal_tcu_handle_t;
typedef void (*hal_tcu_callback_t)(hal_tcu_handle_t *htcu, uint32_t event_mask);

hal_tcu_handle_t 主要成员如下：

回调函数可能运行在TCU IRQ上下文中，不应阻塞、睡眠、等待锁或执行大量日志输出。

2. HAL 接口规范

2.1 HAL层实现边界

• HAL层公开接口首参数优先使用 hal_tcu_handle_t *htcu 或 const hal_tcu_handle_t *htcu，寄存器基地址通过 htcu->instance 传递。

• HAL层使用 IM_HAL_PARAM_CHECK_RETURN / IM_HAL_PARAM_CHECK_RETURN_VOID 做参数合法性检查。

• HAL层普通可失败接口返回 error_code_t，不定义TCU私有状态码类型。

• HAL层不配置外部GPIO复用、电源时钟门控和中断控制器注册；这些由BSP或公共外设模块完成。

• HAL层模式配置接口只允许在目标通道或group空闲时调用，运行中重配置返回 IM_ERR_BUSY。

• ADC trigger模式由TCU HAL配置触发时序，ADC HAL只配置序列触发源为 HAL_ADC_TRIGGER_TCU。

2.2 默认配置、初始化和反初始化

2.2.1 hal_tcu_timer_config_default

error_code_t hal_tcu_timer_config_default(hal_tcu_timer_config_t *config);

功能说明： 填充普通timer默认配置，不访问硬件。

参数表：

返回值表：

补充说明：

• 默认通道为0，full_value/half_value 为 HAL_TCU_COUNTER_MAX，count_value 为0。

• 默认不分频，EXTAL使能，通道时钟上升沿计数，不预置中断mask。

2.2.2 hal_tcu_capture_config_default

error_code_t hal_tcu_capture_config_default(hal_tcu_capture_config_t *config);

功能说明： 填充capture默认配置，不访问硬件。

参数表：

返回值表：

补充说明：

• 默认通道为0，默认连续捕获，即 capture_num = HAL_TCU_CAPTURE_NUM_DEFAULT。

• 默认GPIO0滤波值为0，EXTAL使能，通道时钟上升沿计数。

2.2.3 hal_tcu_quadrature_config_default

error_code_t hal_tcu_quadrature_config_default(hal_tcu_quadrature_config_t *config);

功能说明： 填充quadrature默认配置，不访问硬件。

参数表：

返回值表：

补充说明：

• 默认group为 HAL_TCU_QUADRATURE_GROUP_0。

• 默认位置计数初值为 HAL_TCU_QUADRATURE_POSITION_INIT，滤波值为0。

2.2.4 hal_tcu_adc_trigger_config_default

error_code_t hal_tcu_adc_trigger_config_default(hal_tcu_adc_trigger_config_t *config);

功能说明： 填充ADC trigger默认配置，不访问硬件。

参数表：

返回值表：

补充说明：

• 默认ADC0和ADC1触发均开启，half_value/full_value 默认使用 HAL_TCU_ADC_TRIGGER_VALUE_MAX。

• 默认不分频，EXTAL使能，通道时钟上升沿计数。

2.2.5 hal_tcu_handle_init

error_code_t hal_tcu_handle_init(hal_tcu_handle_t *htcu, tcu_regs_t *instance);

功能说明： 初始化软件handle，绑定TCU实例并设置默认回调，不访问TCU业务寄存器。

参数表：

返回值表：

补充说明：

• 初始化后 state 为 HAL_TCU_STATE_RESET，模式mask、active mask和错误标志清零。

• 回调函数指针恢复为默认空回调。

2.2.6 hal_tcu_init

error_code_t hal_tcu_init(hal_tcu_handle_t *htcu);

功能说明： 初始化TCU HAL运行状态，关闭全部TCU通道0~7的计数器和通道时钟，屏蔽并清除普通TCU事件。

参数表：

返回值表：

补充说明：

• 初始化后 state 为 HAL_TCU_STATE_READY。

• configured_channel_mask、active_channel_mask、各模式mask和 configured_interrupt_mask 均清零。

• 本接口按 HAL_TCU_CHANNEL_MASK_ALL 关闭全部TCU通道，不只处理handle中已记录的通道。

2.2.7 hal_tcu_deinit

error_code_t hal_tcu_deinit(hal_tcu_handle_t *htcu);

功能说明： 反初始化TCU HAL，关闭全部TCU通道0~7的计数器和通道时钟，屏蔽并清除普通TCU事件，清空运行状态。

参数表：

返回值表：

补充说明：

• 反初始化后 state 为 HAL_TCU_STATE_RESET。

• 本接口会清零HAL记录的模式配置状态、active状态、中断配置状态和错误标志。

• 本接口按 HAL_TCU_CHANNEL_MASK_ALL 关闭全部TCU通道，不只处理handle中已记录的通道。

2.3 模式配置

2.3.1 hal_tcu_timer_config

error_code_t hal_tcu_timer_config(hal_tcu_handle_t *htcu,
                                  const hal_tcu_timer_config_t *config);

功能说明： 配置一个TCU通道为普通timer/counter模式，写入FULL、HALF、COUNT、PRESCALER和CONTROL相关字段。

参数表：

返回值表：

补充说明：

• config->channel 范围0~7。

• full_value/half_value/count_value 范围0~`HAL_TCU_COUNTER_MAX`。

• prescaler 为原始TPRE字段，不是实际分频系数。

• 配置为timer模式会设置 timer_channel_mask，并清除该通道的capture状态和相关quadrature group状态。

• 当配置通道0为timer时，会清除 adc_trigger_configured。

2.3.2 hal_tcu_capture_config

error_code_t hal_tcu_capture_config(hal_tcu_handle_t *htcu,
                                    const hal_tcu_capture_config_t *config);

功能说明： 配置一个TCU通道为capture模式，固定使用GPIO0作为捕获输入，并配置通道计数参数和GPIO0滤波。

参数表：

返回值表：

补充说明：

• capture通道范围0~7。

• capture_num 不能为0；推荐使用 HAL_TCU_CAPTURE_NUM_DEFAULT 连续捕获。

• capture模式固定使能GPIO0，GPIO1不适用于capture模式。

• 配置成功后会同时使能该通道的 clock_enable 位。

• 配置为capture模式会设置 capture_channel_mask，并清除该通道的timer状态和相关quadrature group状态。

• 当配置通道0为capture时，会清除 adc_trigger_configured。

2.3.3 hal_tcu_quadrature_config

error_code_t hal_tcu_quadrature_config(hal_tcu_handle_t *htcu,
                                       const hal_tcu_quadrature_config_t *config);

功能说明： 配置一个TCU正交编码group，按A/B/Z通道映射配置位置计数、相位采样、Z相采样、GPIO0/GPIO1输入和store功能。

参数表：

返回值表：

补充说明：

• group 只能为0或1。

• group0使用通道1/2/3作为A/B/Z；group1使用通道4/5/6作为A/B/Z。

• GPIO1仅适用于正交编码模式。

• 配置成功后会同时使能 group 内 A/B/Z 通道的 clock_enable 位。

• 配置为quadrature模式会清除group内通道的timer和capture状态，并设置 quadrature_group_mask。

2.3.4 hal_tcu_adc_trigger_config

error_code_t hal_tcu_adc_trigger_config(hal_tcu_handle_t *htcu,
                                        const hal_tcu_adc_trigger_config_t *config);

功能说明： 配置TCU通道0为ADC trigger模式。通道0 HALF事件触发ADC0，FULL事件触发ADC1。

参数表：

返回值表：

补充说明：

• adc0_trigger_enable 和 adc1_trigger_enable 至少一个为1。

• 开启某路触发时，对应比较值范围为 HAL_TCU_ADC_TRIGGER_VALUE_MIN ~ HAL_TCU_ADC_TRIGGER_VALUE_MAX。

• 关闭某路触发时，HAL内部将对应比较值写为 HAL_TCU_ADC_TRIGGER_DISABLE_VALUE。

• HAL根据触发输出开启状态和比较值关系配置通道0计数模式：仅开启ADC1时使用 HAL_TCU_COUNT_MODE_FULL，仅开启ADC0时使用 HAL_TCU_COUNT_MODE_HALF，两路都开启且 half_value > full_value 时使用 HAL_TCU_COUNT_MODE_HALF，其它两路都开启场景使用 HAL_TCU_COUNT_MODE_FULL。

• 配置为ADC trigger模式会清除通道0的timer/capture状态。

2.4 基础参数动态更新

2.4.1 hal_tcu_period_set

error_code_t hal_tcu_period_set(hal_tcu_handle_t *htcu,
                                uint8_t channel,
                                uint32_t full_value,
                                uint32_t half_value);

功能说明： 更新指定通道的FULL/HALF比较值。

参数表：

返回值表：

补充说明：

• 本接口支持通道运行中在线更新FULL/HALF值。

• 调用方需要自行考虑比较值修改时刻与当前COUNT值之间的关系。

2.4.2 hal_tcu_count_set

error_code_t hal_tcu_count_set(hal_tcu_handle_t *htcu,
                               uint8_t channel,
                               uint32_t count_value);

功能说明： 更新指定通道的COUNT当前值。

参数表：

返回值表：

补充说明：

• 本接口支持通道运行中在线更新COUNT值。

2.4.3 hal_tcu_count_get

error_code_t hal_tcu_count_get(const hal_tcu_handle_t *htcu,
                               uint8_t channel,
                               uint32_t *count_out);

功能说明： 读取指定通道COUNT当前值。

参数表：

返回值表：

补充说明：

• 返回值已按 TCU_CHANNEL_VALUE_MASK 过滤。

2.4.4 hal_tcu_prescaler_set

error_code_t hal_tcu_prescaler_set(hal_tcu_handle_t *htcu,
                                   uint8_t channel,
                                   uint32_t prescaler);

功能说明： 更新指定空闲通道的原始TPRE分频字段。

参数表：

返回值表：

补充说明：

• prescaler 不是实际分频系数。TPRE 0表示不分频，TPRE n > 0表示 (n + 1) * 2 分频。

• 建议使用 HAL_TCU_PRESCALER_DIV_TO_TPRE() 从实际分频系数换算到TPRE字段。

• 分频运行中修改会导致计数节拍不连续，HAL要求通道空闲。

2.4.5 hal_tcu_prescaler_get

error_code_t hal_tcu_prescaler_get(const hal_tcu_handle_t *htcu,
                                   uint8_t channel,
                                   uint32_t *prescaler_out);

功能说明： 读取指定通道原始TPRE分频字段。

参数表：

返回值表：

补充说明：

• 返回值已按 TCU_PRESCALER_TPRE_MASK 过滤。

• 可使用 HAL_TCU_PRESCALER_TPRE_TO_DIV() 将返回值换算为实际分频系数。

2.5 Timer模式启动和停止

2.5.1 hal_tcu_timer_start

error_code_t hal_tcu_timer_start(hal_tcu_handle_t *htcu, uint8_t channel);

功能说明： 启动已配置为timer模式的TCU通道，不主动使能中断。

参数表：

返回值表：

补充说明：

• 本接口会使能通道时钟并打开计数器。

• 使用 hal_tcu_timer_stop() 停止由本接口启动的通道。

2.5.2 hal_tcu_timer_start_it

error_code_t hal_tcu_timer_start_it(hal_tcu_handle_t *htcu, uint8_t channel);

功能说明： 启动已配置为timer模式的TCU通道，并使能该通道配置过的中断源。

参数表：

返回值表：

补充说明：

• 中断源来自 hal_tcu_timer_config() 的 interrupt_mask 或 hal_tcu_interrupt_enable() 记录的同通道事件。

• 使用 hal_tcu_timer_stop_it() 停止并关闭对应中断源。

2.5.3 hal_tcu_timer_stop

error_code_t hal_tcu_timer_stop(hal_tcu_handle_t *htcu, uint8_t channel);

功能说明： 停止已配置为timer模式的TCU通道，不改变中断配置状态。

参数表：

返回值表：

补充说明：

• 本接口关闭计数器和通道时钟，并清除HAL active状态。

• 本接口不修改 configured_interrupt_mask。

2.5.4 hal_tcu_timer_stop_it

error_code_t hal_tcu_timer_stop_it(hal_tcu_handle_t *htcu, uint8_t channel);

功能说明： 停止已配置为timer模式的TCU通道，并关闭该通道已配置的中断源。

参数表：

返回值表：

补充说明：

• 本接口会关闭该通道在 configured_interrupt_mask 中记录的事件中断。

2.6 Capture模式启动、停止和读数

2.6.1 hal_tcu_capture_start

error_code_t hal_tcu_capture_start(hal_tcu_handle_t *htcu, uint8_t channel);

功能说明： 启动已配置为capture模式的TCU通道，不主动使能中断。

参数表：

返回值表：

补充说明：

• capture模式固定使用GPIO0作为捕获输入。

• 使用 hal_tcu_capture_stop() 停止由本接口启动的通道。

2.6.2 hal_tcu_capture_start_it

error_code_t hal_tcu_capture_start_it(hal_tcu_handle_t *htcu, uint8_t channel);

功能说明： 启动已配置为capture模式的TCU通道，并使能捕获中断源。

参数表：

返回值表：

补充说明：

• 若未配置该通道中断mask，本接口默认使能 TCU_FLAG_CAPTURE(channel)。

• 使用 hal_tcu_capture_stop_it() 停止并关闭capture中断源。

2.6.3 hal_tcu_capture_stop

error_code_t hal_tcu_capture_stop(hal_tcu_handle_t *htcu, uint8_t channel);

功能说明： 停止已配置为capture模式的TCU通道，不改变中断配置状态。

参数表：

返回值表：

补充说明：

• 本接口关闭计数器和通道时钟，并清除HAL active状态。

2.6.4 hal_tcu_capture_stop_it

error_code_t hal_tcu_capture_stop_it(hal_tcu_handle_t *htcu, uint8_t channel);

功能说明： 停止已配置为capture模式的TCU通道，并关闭capture相关中断源。

参数表：

返回值表：

补充说明：

• 若配置接口未预置中断mask，本接口按 TCU_FLAG_CAPTURE(channel) 关闭capture中断。

2.6.5 hal_tcu_capture_value_get

error_code_t hal_tcu_capture_value_get(const hal_tcu_handle_t *htcu,
                                       uint8_t channel,
                                       hal_tcu_capture_value_t *value_out);

功能说明： 读取并解包指定capture通道的高电平持续时间和周期。

参数表：

返回值表：

补充说明：

• value_out->high 对应 CAP_VALUE bits15:0。

• value_out->period 对应 CAP_VALUE bits31:16。

2.6.6 hal_tcu_capture_level_get

error_code_t hal_tcu_capture_level_get(const hal_tcu_handle_t *htcu,
                                       uint8_t *level_out);

功能说明： 读取全部capture输入电平状态。

参数表：

返回值表：

补充说明：

• 输出bit07分别对应通道07当前输入电平。

2.6.7 hal_tcu_capture_channel_level_get

error_code_t hal_tcu_capture_channel_level_get(const hal_tcu_handle_t *htcu,
                                               uint8_t channel,
                                               uint8_t *level_out);

功能说明： 读取指定capture通道输入电平。

参数表：

返回值表：

2.7 Quadrature模式

2.7.1 hal_tcu_quadrature_start

error_code_t hal_tcu_quadrature_start(hal_tcu_handle_t *htcu, uint8_t group);

功能说明： 启动已配置的正交编码group，不主动使能中断。

参数表：

返回值表：

补充说明：

• 本接口同时启动group内A/B/Z三个通道。

• 使用 hal_tcu_quadrature_stop() 停止由本接口启动的group。

2.7.2 hal_tcu_quadrature_start_it

error_code_t hal_tcu_quadrature_start_it(hal_tcu_handle_t *htcu, uint8_t group);

功能说明： 启动已配置的正交编码group，并使能group中断源。

参数表：

返回值表：

补充说明：

• 若未配置group中断mask，本接口默认使能B通道HALF事件和Z通道HALF事件。

• 使用 hal_tcu_quadrature_stop_it() 停止并关闭group中断源。

2.7.3 hal_tcu_quadrature_stop

error_code_t hal_tcu_quadrature_stop(hal_tcu_handle_t *htcu, uint8_t group);

功能说明： 停止已配置的正交编码group，不改变中断配置状态。

参数表：

返回值表：

补充说明：

• 本接口同时停止group内A/B/Z三个通道。

2.7.4 hal_tcu_quadrature_stop_it

error_code_t hal_tcu_quadrature_stop_it(hal_tcu_handle_t *htcu, uint8_t group);

功能说明： 停止已配置的正交编码group，并关闭group中断源。

参数表：

返回值表：

补充说明：

• 若配置接口未预置中断mask，本接口按B/Z通道HALF事件关闭中断。

2.7.5 hal_tcu_quadrature_position_get

error_code_t hal_tcu_quadrature_position_get(const hal_tcu_handle_t *htcu,
                                             uint8_t group,
                                             uint32_t *position_out);

功能说明： 读取正交编码group当前位置计数器。

参数表：

返回值表：

补充说明：

• 当前实现不检查group是否已配置为quadrature模式。

• 本接口读取group A通道COUNT有效值。

2.7.6 hal_tcu_quadrature_position_value_get

error_code_t hal_tcu_quadrature_position_value_get(const hal_tcu_handle_t *htcu,
                                                   uint8_t group,
                                                   hal_tcu_quadrature_value_t *value_out);

功能说明： 读取正交编码AB相位置采样值。

参数表：

返回值表：

补充说明：

• 本接口读取group A通道 store_value，用于B通道HALF事件后的AB相位置采样值读取。

• current 对应bits15:0，previous 对应bits31:16。

2.7.7 hal_tcu_quadrature_index_value_get

error_code_t hal_tcu_quadrature_index_value_get(const hal_tcu_handle_t *htcu,
                                                uint8_t group,
                                                hal_tcu_quadrature_value_t *value_out);

功能说明： 读取正交编码Z相索引采样值。

参数表：

返回值表：

补充说明：

• 本接口读取group Z通道 store_value，用于Z通道HALF事件后的索引采样值读取。

2.8 ADC Trigger模式

2.8.1 hal_tcu_adc_trigger_start

error_code_t hal_tcu_adc_trigger_start(hal_tcu_handle_t *htcu);

功能说明： 启动已配置为ADC trigger模式的TCU通道0。

参数表：

返回值表：

补充说明：

• TCU通道0 HALF比较输出触发ADC0，FULL比较输出触发ADC1。

• ADC模块侧仅选择 HAL_ADC_TRIGGER_TCU，不选择TCU通道。

• 使用 hal_tcu_adc_trigger_stop() 停止由本接口启动的通道。

2.8.2 hal_tcu_adc_trigger_stop

error_code_t hal_tcu_adc_trigger_stop(hal_tcu_handle_t *htcu);

功能说明： 停止已配置为ADC trigger模式的TCU通道0。

参数表：

返回值表：

补充说明：

• 本接口关闭通道0计数器和通道时钟，并清除HAL active状态。

2.9 中断模式和回调

2.9.1 hal_tcu_interrupt_enable

error_code_t hal_tcu_interrupt_enable(hal_tcu_handle_t *htcu, uint32_t interrupt_mask);

功能说明： 使能指定TCU普通事件中断，并清除对应历史事件状态。

参数表：

返回值表：

补充说明：

• ie 硬件语义为1屏蔽、0使能，本接口内部写 ie_clr。

• 本接口会将 interrupt_mask 记录到 configured_interrupt_mask。

2.9.2 hal_tcu_interrupt_disable

error_code_t hal_tcu_interrupt_disable(hal_tcu_handle_t *htcu, uint32_t interrupt_mask);

功能说明： 屏蔽指定TCU普通事件中断，并同步清除HAL记录的对应中断配置状态。

参数表：

返回值表：

补充说明：

• ie 硬件语义为1屏蔽、0使能，本接口内部写 ie_set。

• 本接口会从 configured_interrupt_mask 中清除对应bit。

2.9.3 hal_tcu_interrupt_status_get

error_code_t hal_tcu_interrupt_status_get(const hal_tcu_handle_t *htcu,
                                          uint32_t *status_out);

功能说明： 读取TCU普通事件状态。

参数表：

返回值表：

补充说明：

• 输出值已按 HAL_TCU_INTERRUPT_MASK_ALL 过滤。

2.9.4 hal_tcu_interrupt_status_clear

error_code_t hal_tcu_interrupt_status_clear(hal_tcu_handle_t *htcu,
                                            uint32_t interrupt_mask);

功能说明： 清除指定TCU普通事件状态。

参数表：

返回值表：

补充说明：

• 本接口写 ir_clr 清除指定事件状态。

2.9.5 hal_tcu_irq_handler

void hal_tcu_irq_handler(hal_tcu_handle_t *htcu);

功能说明： TCU中断服务入口，由BSP ISR调用，分发FULL、HALF和CAPTURE回调并清除本次pending事件。

参数表：

返回值表：

补充说明：

• 无效句柄时直接返回。

• IRQ入口按FULL、HALF、CAPTURE三类事件分别调用注册回调。

• 回调运行在中断上下文中，不应阻塞、睡眠、等待锁或执行大量日志输出。

2.9.6 hal_tcu_callback_register

error_code_t hal_tcu_callback_register(hal_tcu_handle_t *htcu,
                                       hal_tcu_callback_id_t callback_id,
                                       hal_tcu_callback_t callback);

功能说明： 注册或恢复TCU事件回调函数。

参数表：

返回值表：

2.10 调试、状态和错误查询

2.10.1 hal_tcu_regs_dump

error_code_t hal_tcu_regs_dump(const hal_tcu_handle_t *htcu);

功能说明： 打印TCU常规寄存器值，用于调试。

参数表：

返回值表：

补充说明：

• 仅当 CONFIG_SDK_ENABLE_DEBUG_HELPERS 和 CONFIG_TCU_ENABLE_DEBUG_HELPERS 均打开时打印实际寄存器。

• dump不读取隐藏reserved区域。

2.10.2 hal_tcu_state_get

error_code_t hal_tcu_state_get(const hal_tcu_handle_t *htcu,
                               hal_tcu_state_t *state_out);

功能说明： 读取HAL TCU模块级运行状态。

参数表：

返回值表：

补充说明：

• 通道busy/idle状态通过 hal_tcu_active_channel_mask_get() 单独读取。

2.10.3 hal_tcu_active_channel_mask_get

uint32_t hal_tcu_active_channel_mask_get(const hal_tcu_handle_t *htcu);

功能说明： 读取HAL跟踪的active通道mask。

参数表：

返回值表：

补充说明：

• bit07分别对应TCU通道07。

2.10.4 hal_tcu_error_get

uint32_t hal_tcu_error_get(const hal_tcu_handle_t *htcu);

功能说明： 读取TCU HAL latched错误标志。

参数表：

返回值表：

补充说明：

• 错误标志为latched模型，成功API调用不清除历史错误。

• hal_tcu_handle_init()、hal_tcu_init() 和 hal_tcu_deinit() 会清零错误标志。

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

3.1 分频和边沿约束

• prescaler 参数表示原始TPRE字段，不是实际分频系数。

• prescaler == 0 表示不分频，实际分频系数为1。

• prescaler != 0 时实际分频系数为 (prescaler + 1) * 2。

• 硬件不支持2分频，应用传入实际分频系数2时，换算结果不能表达真实2分频。

• 示例和HAL用户代码建议使用 HAL_TCU_PRESCALER_DIV_TO_TPRE(div) 和 HAL_TCU_PRESCALER_TPRE_TO_DIV(tpre) 做换算。

3.2 ADC触发约束

• adc0_trigger_enable 和 adc1_trigger_enable 必须至少有一个为1。

• ADC0由通道0 HALF比较输出触发，比较值使用 half_value。

• ADC1由通道0 FULL比较输出触发，比较值使用 full_value。

• 关闭某路触发时，HAL内部将对应比较值配置为 HAL_TCU_ADC_TRIGGER_DISABLE_VALUE。

• ADC侧序列应配置为 HAL_ADC_TRIGGER_TCU；外部触发模式不调用 hal_adc_start()。

• ADC trigger模式和timer模式都使用通道0硬件计数资源，但HAL软件状态独立，应用必须使用对应模式的start/stop接口。

4. 典型用法

4.1 普通Timer中断

static void tcu_full_callback(hal_tcu_handle_t *htcu, uint32_t event_mask)
{
    (void)htcu;
    (void)event_mask;
}

hal_tcu_handle_t htcu;
hal_tcu_timer_config_t config;

(void)hal_tcu_handle_init(&htcu, TCU);
(void)hal_tcu_init(&htcu);

(void)hal_tcu_timer_config_default(&config);
config.channel = 0U;
config.full_value = 10000U;
config.half_value = 5000U;
config.prescaler = HAL_TCU_PRESCALER_DIV_TO_TPRE(1U);
config.interrupt_mask = TCU_FLAG_FULL(config.channel);

(void)hal_tcu_timer_config(&htcu, &config);
(void)hal_tcu_callback_register(&htcu, HAL_TCU_CALLBACK_FULL, tcu_full_callback);
(void)hal_tcu_timer_start_it(&htcu, config.channel);

4.2 捕获周期和高电平

hal_tcu_capture_config_t capture;
hal_tcu_capture_value_t value;

(void)hal_tcu_capture_config_default(&capture);
capture.channel = 0U;
capture.capture_num = HAL_TCU_CAPTURE_NUM_DEFAULT;
capture.gpio0_filter_value = 8U;

(void)hal_tcu_capture_config(&htcu, &capture);
(void)hal_tcu_capture_start_it(&htcu, capture.channel);
(void)hal_tcu_capture_value_get(&htcu, capture.channel, &value);

4.3 正交编码位置读取

hal_tcu_quadrature_config_t quad;
hal_tcu_quadrature_value_t sampled;
uint32_t position;

(void)hal_tcu_quadrature_config_default(&quad);
quad.group = (uint8_t)HAL_TCU_QUADRATURE_GROUP_0;

(void)hal_tcu_quadrature_config(&htcu, &quad);
(void)hal_tcu_quadrature_start_it(&htcu, quad.group);
(void)hal_tcu_quadrature_position_get(&htcu, quad.group, &position);
(void)hal_tcu_quadrature_position_value_get(&htcu, quad.group, &sampled);

4.4 TCU触发ADC0或ADC1

hal_tcu_adc_trigger_config_t trigger;

(void)hal_tcu_adc_trigger_config_default(&trigger);
trigger.adc0_trigger_enable = 1U;
trigger.adc1_trigger_enable = 0U;
trigger.half_value = 60000U;
trigger.full_value = HAL_TCU_ADC_TRIGGER_DISABLE_VALUE;
trigger.prescaler = HAL_TCU_PRESCALER_DIV_TO_TPRE(2000U);

(void)hal_tcu_adc_trigger_config(&htcu, &trigger);
(void)hal_tcu_adc_trigger_start(&htcu);

说明：ADC0触发使用 half_value，ADC1触发使用 full_value；ADC侧序列需要配置为 HAL_ADC_TRIGGER_TCU。