G32S10 TPC API 概述

1. 文档范围

本文档描述 G32S10 SDK 的 TPC（热敏打印头控制器）HAL 与 LL 接口。TPC 同时驱动打印头 移位、锁存、加热、步进电机和内部 WDT；一次完整打印通常由这些子模块按确定顺序协同完成。

1.1 先认识几个概念

TPC 的典型分层关系如下。MID 是整图打印编排层；应用也可以跳过 MID，直接调用 HAL：

1.2 本文边界

HAL 只在“句柄、实例、参数范围、模块当前状态”这一层做校验。它不判断一次打印是否完整， 也不替应用决定错误后是否重试或停机。

不属于 HAL/LL 的职责：

1.3 源码依据

本文按以下源码核对编写；当代码、板级配置与外部规范不一致时，以当前 SDK 源码为准， 并在硬件联调时核对实际 SoC 地址表：

2. 构建配置与文件组织

直接使用 HAL/LL 时需要使能：

CONFIG_DRIVER_TPC=y

DRIVER_TPC 会自动选择 DRIVER_DMA（HAL 依赖 DMA HAL）。它不会选择 OS、中断框架 或 TPC middleware。

应用程序通常直接包含：

#include "hal_tpc.h"

开始调用启动、停止 API 前，板级初始化必须已经完成以下事项：

可选的寄存器 dump 助手（hal_tpc_regs_dump()）需要同时使能两个选项，缺一不可：

CONFIG_SDK_ENABLE_DEBUG_HELPERS=y
CONFIG_TPC_ENABLE_DEBUG_HELPERS=y

未同时使能时，hal_tpc_regs_dump() 保留公开符号但返回 IM_ERR_UNSUPPORTED，不会读取 或打印寄存器。

相关源文件：

hal_tpc.h 已经包含 hal_dma.h、ll_tpc.h、im_types.h 和 im_error.h，包含hal_tpc.h 后即可使用 tpc_regs_t、TPC 实例和 LL 接口。

HAL 还依赖两套 SDK 基础设施：

• 时间基准（im_time_*）：启动/停止时等待 FIFO 就绪和 Flush 完成，超时上限 1 s （内部常量 TPC_WAIT_TIMEOUT_US，轮询间隔 10 us）。调用前必须初始化 systick。

• 数据缓存维护（im_cache_*）：每次启动 DMA 前由 HAL 对源缓冲区做 data clean （write-back），应用无需重复调用。

3. 硬件资源

地址提示：当前 SDK 和所用地址表为 0x1349_0000。应用应使用 TPC/TPC_IOBASE，不要自行硬编码外部规范地址；若板上 访问异常，应先确认所测 SoC 版本和地址表。

4. DMA 与资源所有权

4.1 描述符

描述符在首次成功配置该模块时绑定，之后重新配置不会更换存储地址或容量。若之后 可能需要循环 DMA，必须在首次配置前提供对齐的 dma_desc 和非零 dma_desc_count。

hal_tpc_sync_write() 按每路窗口的逻辑单元数 unit_count = len / unit_size 选择实际 描述符数：

unit_count <= 128  ->  descriptor_count = unit_count
unit_count >  128  ->  descriptor_count = 2 ~ 128 范围内的最大整除数
无法得到 2 ~ 128 的整除数 -> 返回 IM_ERR_INVALID_PARAM

例如 218 个逻辑单元选择 109 个描述符，217 个逻辑单元选择 31 个描述符。配置容量必须 至少覆盖所选数量；逻辑单元数与描述符数并非总是一一对应。一个描述符负责窗口总字节数 / descriptor_count 的连续数据，所谓“共享描述符”不会丢弃其余逻辑单元。

每路逻辑单元数必须至少为 2。若单元数大于 128 且没有 2 ~ 128 的整除数，hal_tpc_sync_write() 返回 IM_ERR_INVALID_PARAM，不会启动任何 DMA，也不会退化为 单个自循环描述符。连续打印时应让窗口单元数具有不超过 128 的合法整除数，并为描述符内 的排空数据保留空间。

4.2 中断所有权

TPC 打印事件使用 IRQ_TPC。应用负责向 SoC 中断框架注册 IRQ_TPC，并在 handler 中 调用 hal_tpc_irq_handler()；TPC HAL 本身只处理 TPC 的 PINTS/PINTM0，不注册 PLIC 中断线。

共享 PDMA 中断遵循以下边界：

• TPC HAL/MID 不注册 IRQ_PDMA0 / IRQ_PDMA0_DIP；

• 系统已有统一 DMA owner 时，由该 owner 处理 PDMA IRQ，勿在 TPC 应用里重复注册；

• 没有 PDMA IRQ owner 时，TPC 依靠下一次启动或 deinit 做 handle reap，DMA 故障不会 自动转换为 TPC HAL 错误码，通常表现为进度停滞、等待超时或后续 IM_ERR_BUSY；

• 需要 DMA 错误明细时，应通过统一的 DMA 管理接口读取状态，不要从 TPC IRQ 里抢接 PDMA 中断线。

4.3 并发与实例

• TPC 只有一个寄存器块实例，HAL 句柄不是可重入的：同一句柄不能并发调用，多任务 共享时需要外部串行化。

• hal_tpc_init() / hal_tpc_deinit() 成对使用；重复 hal_tpc_init() 返回IM_ERR_BUSY。

• 模块正在运行时再次配置或启动该模块都会返回 IM_ERR_BUSY，需要先停止。

5. 错误码

HAL 自身会返回：

打开或启动 DMA 时，HAL 会透传 DMA HAL 的错误码（例如无可用通道、控制器未就绪）； 停止接口按 6.5 所述执行 best-effort 清理，不向上传播 DMA 停止或 Flush 失败。

6. 示例与参考实现

建议按“HAL 单模块 → HAL 整图 → MID 单次打印 → MID 多打印”的顺序阅读。只做接口查询时 可直接转到第 7、8 章。

7. 已知限制与注意事项

1. HAL 不管 CPM：模块时钟门控和软件复位由应用/板级完成；hal_tpc_init() 只做 寄存器层面的复位。

2. 错误事件不自动停机：各 *_FIFO_UNDERRUN、*_OVERTIME、AUTO_ALIGN_ERROR只通过回调上报，活动掩码不会自动清除，停机策略由应用选择。

3. 停止接口是 best-effort：DMA 停止和 Flush 的失败不会传播，只保证流程走完； 需要严格确认时自行读寄存器核对（PFCEN、PDEN、PMnEN、PINTS、PFFS、PFSM）。

4. sync_stream_end() 依赖 LINK 和描述符范围：只能用于由 2 ~ 128 个描述符组成的 循环窗口；单描述符或无法等长分片的窗口会被 hal_tpc_sync_write() 拒绝。传入的是最后 一份数据所在逻辑单元的源地址，HAL 会映射到一个或多个逻辑单元共用的描述符。LINK 清除 后仍会完成当前描述符，应用需预留收尾/排空数据。

5. WDT 分频字段只有 0 ~ 5 有效，6、7 为保留值，HAL 配置时校验。

6. 电机通道模式互斥：Motor0 使用 8 通道时 Motor1 不可配置；反之 Motor0 通道数 不能超过 4。

7. hal_tpc_deinit() 要求先停机：任何模块仍活动都会返回 IM_ERR_BUSY。正常顺序是 先 *_stop() 再 hal_tpc_deinit()；当前 deinit 对 DMA reap/close 采用 best-effort 清理，不向上传播这些错误。WDT 不受 active mask 管理，也不会由 deinit 自动关闭。

8. 实例基址以 SDK/地址表为准：见第 3 章，当前值为 0x1349_0000；不要按外部规范 地址硬编码。