首页 / 官方文档 / MCU系列 / G32S10X / SDK文档 / API指南 / TCU / API 概述

API GUIDE / TCU / OVERVIEW

G32S10 TCU API 概述

模块概述：本文档定义 G32S10 SDK TCU 模块的正式接口，覆盖以下两层：

1. 文档范围

本文档定义 G32S10 SDK TCU 模块的正式接口，覆盖以下两层：

  • HAL TCU：面向应用、BSP和驱动上层的功能级接口

  • LL TCU：面向寄存器与位操作的低层接口

补充说明：

  • LL层不返回状态码；需要返回寄存器值或数据时返回 uint32_t。

  • HAL层负责参数校验、状态管理、模式编排、中断回调分发。

2. 分层关系

APPLICATION  Application / BSP / Example  业务代码、板级支持与示例入口
↓
HAL  HAL TCU  模块级配置、状态管理与硬件访问
↓
LL  LL TCU  寄存器访问与字段级控制
↓
HARDWARE REGISTERS  TCU Registers  实例地址、寄存器布局与位域定义

分层职责如下：

  • HAL TCU

    • 封装普通timer、capture、quadrature和ADC trigger四类模式

    • 维护参数合法性、模块级状态、active channel mask、模式配置mask和统一返回码

    • 提供捕获值/正交采样值解包、回调注册、错误查询和寄存器dump接口

  • LL TCU

    • 提供寄存器位级访问入口

    • 不维护软件状态，不做复杂业务语义判断

    • 公开接口均为 static inline，首参数为 tcu_regs_t *tcux

  • tcu_regs.h

    • 定义TCU基地址、寄存器结构体布局、通道数量、事件mask和位域mask

3. 资源模型与公开类型

3.1 TCU硬件能力摘要

项目说明
普通通道支持通道0~7。
计数宽度FULL/HALF/COUNT 有效宽度为16 bit，范围0~0xFFFF。
计数使能cnt_status/cnt_enable/cnt_disable 控制通道计数器是否运行。
通道时钟clock_status/clock_enable/clock_disable 控制通道时钟门控。
最大计数时钟TCU通道计数时钟最大为24 MHz。
时钟分频PRESCALERn.TPRE 为16 bit；TPRE=0 表示不分频，TPRE=n,n>0 时实际分频为 (n + 1) * 2，硬件不支持2分频。
计数模式支持到FULL、溢出、到HALF、到HALF或Z输入四类模式。
事件ir/ie 中bit07为FULL事件，bit815为CAPTURE事件，bit16~23为HALF事件。
捕获HAL捕获模式开放通道0~7，固定使用GPIO0作为捕获输入；capture_num=0 不触发捕获，HAL配置接口不接受该值。
HALL状态hall_state 低8 bit对应通道0~7输入状态；HAL通过捕获电平接口读取。
正交编码HAL按group组织：group0使用通道1/2/3作为A/B/Z，group1使用通道4/5/6作为A/B/Z。
GPIO1输入GPIO1仅适用于正交编码模式。
输入滤波filter_value[n] 中GPIO0/GPIO1滤波字段均为10 bit，滤波计数器时钟为200 MHz。
Store值store_value[n] 提供current/previous两个16 bit字段，HAL用于正交编码采样值读取。
ADC触发通道0固定用于ADC trigger模式；HALF事件触发ADC0，FULL事件触发ADC1，两路可分别开启或关闭。

3.2 HAL返回状态约定

HAL层普通可失败接口统一返回SDK公共错误码类型：

error_code_t

常用返回值如下：

返回值说明
IM_OK操作成功。
IM_ERR_INVALID_PARAM参数为空、实例非法、通道/group越界、字段取值非法或模式组合非法。
IM_ERR_BUSY指定通道或group当前处于active状态，不能重配置或重复启动。
IM_ERR_NOT_READYhandle未初始化、目标通道未配置，或目标模式未配置完成。
IM_ERR_UNSUPPORTED当前编译配置不支持该操作，例如未打开dump宏控。

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

4.1 通道和模式范围

功能范围说明
Timer通道0~7每通道均有FULL/HALF/COUNT/CONTROL。
Capture通道0~7HAL固定GPIO0输入。
ADC Trigger通道0HALF触发ADC0，FULL触发ADC1。
Quadraturegroup0~1group0使用通道1/2/3，group1使用通道4/5/6。
HALL状态读取通道0~7hall_state 低8 bit有效。

4.2 模式组合

配置项TIMERCAPTUREQUADRATUREADC_TRIGGER
通道0支持支持不支持支持
通道1~6支持支持通过group使用不支持
通道7支持支持不支持不支持
EXTAL输入可选可选HAL按模式配置可选
GPIO0输入不由timer配置固定使用使用不使用
GPIO1输入不由timer配置不使用使用不使用
Store value不由timer读取不开放HAL读取用于位置/Z相采样读取不使用
中断可配置FULL/CAPTURE/HALF默认CAPTURE默认B/Z HALF不主动配置中断

4.3 捕获次数约束

  • capture_num == 0 时硬件不会进行捕获，HAL配置接口返回 IM_ERR_INVALID_PARAM。

  • capture_num 1~`HAL_TCU_CAPTURE_NUM_FINITE_MAX` 表示有限次捕获。

  • capture_num 大于 HAL_TCU_CAPTURE_NUM_FINITE_MAX 时作为连续捕获使用。

  • HAL默认配置使用 HAL_TCU_CAPTURE_NUM_DEFAULT，推荐普通应用使用连续捕获。

4.4 文件组织

code/include/drivers/g32s10/tcu/
  tcu_regs.h
  ll_tcu.h
  hal_tcu.h
code/drivers/g32s10/tcu/
  hal_tcu.c
code/examples/ll/
  tcu_trig_example.c
code/examples/hal/
  tcu_trig_adc_example.c

文件职责：

文件说明
tcu_regs.hTCU寄存器结构体、基地址、位定义和字段写辅助宏。
ll_tcu.hLL层 static inline API定义、寄存器位操作接口。
hal_tcu.hHAL层公开宏、枚举、配置结构、句柄、回调类型和API声明。
hal_tcu.cHAL层参数校验、状态管理、模式编排、中断处理和寄存器dump。
tcu_trig_example.cLL层TCU触发ADC示例。
tcu_trig_adc_example.cHAL层TCU分别触发ADC0和ADC1示例。

5. 推荐关注的错误标志

TCU HAL私有错误标志通过 hal_tcu_error_get() 读取，字段定义见 hal_tcu_error_t。

错误标志说明常见触发场景
HAL_TCU_ERROR_NONE无HAL私有错误。初始化后或错误状态清除后。
HAL_TCU_ERROR_INVALID_PARAMHAL记录的参数错误flag。空指针、非法实例、通道/group越界、字段取值非法、非法模式组合。
HAL_TCU_ERROR_NOT_READYHAL记录的未就绪flag。handle未初始化，或调用start/stop/get接口时目标模式未配置。
HAL_TCU_ERROR_BUSYHAL记录的忙状态flag。运行中通道重配置，或重复启动已active通道。