说明：如果原始文档的行数过多，应该进行拆分。接口说明文档的行数尽量控制在 1000 行内，最多不超过 2000 行。

<模块名> 接口说明文档

文档版本	V1.0
修订日期
对应头文件	<路径/xx.h>
类型定义	<路径/xx_define.h>
适用模块	<模块名（中文全称 / 英文缩写）>

说明：<> 为占位符，编写时替换为实际内容；不存在的章节（如命令通道、枚举、常量）可整体删除。

---

1 概述

<用 1~3 句话描述模块职责与对外能力，例如：本模块对外提供 xxx_* 系列接口，封装了……能力。>

模型层次（可选）：

<父对象>
  └─ <子对象>
        └─ <通道 / 端口>

---

2 接口总览

编号	接口	模块	功能概述
1	<接口名>	<模块 / 分类>	<功能一句话说明>
2	<接口名>	<模块 / 分类>	<功能一句话说明>

---

3 API 参考

每个接口按下方小节模板编写；

3.1 <接口名>

【描述】

<接口功能一句话说明，含关键逻辑、幂等性、模式差异（直连 / IPC）等。>

【语法】

td_s32 <接口名>(<参数类型> <参数名>, ...);

【参数】

参数名称	输入/输出	类型	描述
<参数名>	输入/输出	<类型>	<描述，含取值范围、NULL 约定、默认值>

若参数为结构体，补充成员表：

成员名称	描述
<成员名>	<描述>

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
<具体错误码>	<该错误码触发条件>

【注意】

<注意事项、约束、前置条件、调用时序、幂等性、参数校验等；无则写"无"。>

【举例】

<示例代码；无则写"无"。>

【相关主题】

<相关接口或文档；无则写"无"。>

---

4 数据类型

每个数据类型（结构体 / 枚举 / 命令字）按下方小节模板编写：

4.1 <数据类型名>

【说明】

<定义该类型的作用，一句话说明。>

【定义】

typedef struct/enum {
    ...
} <类型名>;

【成员】

成员名称	描述
<成员名>	<描述>

【注意事项】

<补充约束说明；无则写"无"。>

【相关数据类型及接口】

<列出相关类型与接口；无则写"无"。>

4.2 关键常量（可选）

常量	取值	说明
<常量名>	<值 / 范围>	<说明>

---

5 错误码

错误代码	宏定义	描述
<0xXXXXXX>	<MODULE>_ENULL_PTR	输入参数空指针错误。
<0xXXXXXX>	<MODULE>_EILLEGAL_PARAM	输入参数非法。
<0xXXXXXX>	<MODULE>_ENOTREADY	系统没有初始化 / 未就绪。
<0xXXXXXX>	<MODULE>_EINVALID_DEVID	设备号无效。
<0xXXXXXX>	<MODULE>_EBUSY	设备 / 资源忙。

---

6 使用注意事项

1. 句柄范围：<句柄合法范围说明>。

2. 时序依赖：遵循以下启停顺序（停止为逆序）；"xx 需在 xx 之后调用"等时序约束亦在此说明。

   启动：

   init(...)                    // 初始化 / 静态属性
     → set_attr(...)            // 属性配置
     → start(...)               // 启动
     → [循环] get_frame → ... → release_frame
   

   停止（逆序）：

stop(...)
  → deinit(...)

1. 资源配对：<如 get/release、bind/unbind、引用计数等成对调用约定>。
2. 属性语义：<静态属性 vs 动态属性>。
3. 模式差异：<直连 / IPC 等实现差异（如有）>。

---

7 附注 / 关联文档

• <架构设计文档、需求 / AR 表等关联文档路径或编号>