11 KiB
11 KiB
ARCS SDK 设备驱动示例文档编写规范
本文档定义了 ARCS SDK 中设备驱动示例的 README.md 编写规范，确保所有示例文档风格统一、信息完整。
文档结构规范
必需章节（按顺序）
1. 标题（H1）
格式： # LISA_{DRIVER} {功能描述}示例{（可选附加说明）}
示例：
# LISA UART 同步接收示例（DMA 模式 + 循环缓冲区）
# LISA PWM 基础输出示例
# LISA GPIO 中断示例
规则：
- 使用驱动名称大写（如 UART、PWM、GPIO）
- 功能描述简洁明了（如：同步接收、异步发送、基础输出）
- 可选附加说明用括号注明特殊模式或特性（如：DMA 模式、中断模式）
2. 功能说明（H2）
格式： ## 功能说明
内容要求：
- 第一段：简明扼要地说明示例的核心功能（1-2 句话）
- 第二段（可选）：补充底层实现细节或技术特点
示例：
## 功能说明
演示在 DMA 模式下使用 UART 异步发送接口，通过事件回调接收发送完成通知。
底层使用中断方式异步发送，通过信号量实现同步等待，避免轮询，降低 CPU 占用。
3. 新特性（H3，可选但推荐）
格式： ### 新特性
使用场景：
- 示例展示高级功能（如 DMA、中断、循环缓冲区等）
- 与基础示例有明显技术差异
- 需要突出技术优势
内容要求：
- 使用无序列表（bullet points）
- 每项包含粗体标题和简短说明
- 3-5 个关键特性
示例：
### 新特性
- **DMA 硬件传输**：无需 CPU 参与数据搬移，降低 CPU 占用
- **异步非阻塞**：调用后立即返回，DMA 后台传输
- **事件回调通知**：传输完成后通过中断回调通知应用层
- **适合高速率场景**：支持高波特率连续发送，不阻塞主任务
4. 硬件连接（H2）
格式： ## 硬件连接
内容要求：
- 使用无序列表列出所有相关引脚
- 格式：
- **引脚编号**: 功能说明 - 如果无需外部连接，明确说明
示例：
## 硬件连接
- **PB2**: UART1 TX（发送）
- **PB3**: UART1 RX（接收）
连接到 PC 串口工具，配置为 **115200, 8N1, 无流控**
## 硬件连接
无需外部连接，RTC 为芯片内部外设。
5. 使用场景（H2，可选但推荐）
格式： ## 使用场景
使用时机：
- 示例有明确的应用场景
- 需要说明何时选择该示例方案
内容要求：
- 1-2 句话说明适用场景
- 突出技术选型的关键因素
示例：
## 使用场景
适用于需要高速率连续发送数据的场景，底层采用 DMA 硬件传输，CPU 占用更低，应用层通过回调确认发送完成。
6. 示例步骤（H2）
格式： ## 示例步骤 或 ## 示例内容
内容要求：
- 使用有序列表（编号列表）
- 每步简洁明了，突出关键操作
- 3-6 个步骤为宜
示例：
## 示例步骤
1. 创建信号量（用于同步 DMA 回调）
2. 获取 UART 设备
3. 配置引脚和参数（DMA 模式）
4. 设置事件回调函数（接收 TX_DONE 事件）
5. 调用 `lisa_uart_write_async()` 异步发送
6. 等待信号量确认发送完成
7. 编译运行（H2）
格式： ## 编译运行
内容要求：
- 使用代码块展示编译命令
- 标准命令为
./build.sh -C -DBOARD=arcs_evb - 如有特殊需求可添加说明
示例：
## 编译运行
\`\`\`bash
./build.sh -C -DBOARD=arcs_evb
\`\`\`
8. 预期输出（H2）
格式： ## 预期输出
内容要求：
- 分段展示不同输出源（终端、串口工具、LED等）
- 使用代码块展示实际输出
- 使用粗体标注输出源
示例：
## 预期输出
**终端输出：**
\`\`\`
=== LISA UART async send (DMA mode) example ===
UART ready, start sending...
Sent: Hello UART! Counter: 0
Sent: Hello UART! Counter: 1
...
\`\`\`
**PC 串口工具接收：**
\`\`\`
Hello UART! Counter: 0
Hello UART! Counter: 1
...
\`\`\`
9. 核心 API（H2，可选但推荐）
格式： ## 核心 API
内容要求：
- 使用表格列出关键 API
- 两列：API 名称 | 功能说明
- 按调用顺序排列
示例：
## 核心 API
| API | 说明 |
|-----|------|
| `lisa_device_get()` | 获取 UART 设备 |
| `lisa_uart_configure()` | 配置 UART 参数 |
| `lisa_uart_set_callback()` | 设置事件回调函数 |
| `lisa_uart_write_async()` | 异步发送数据（非阻塞） |
可选章节（根据需要添加）
10. API/功能详细说明（H2）
使用场景：
- 示例涉及复杂 API 或特殊工作机制
- 需要解释底层实现原理
命名规范：
## 同步接收说明## 异步发送说明## 中断模式说明
内容要求：
- 说明工作原理
- 列出关键行为特点（使用无序列表）
- 说明返回值/返回条件
示例：
## 异步发送说明
`lisa_uart_write_async()` 在 DMA 模式下的工作原理：
- **底层实现**：DMA 硬件自动搬移数据到 UART 发送 FIFO，CPU 无需参与
- **返回时机**：调用后立即返回，不等待发送完成
- **回调触发**：DMA 传输完成后触发 `LISA_UART_EVENT_TX_DONE` 事件
- **返回值**：
- 成功时返回实际发送字节数（> 0）
- 失败时返回负数错误码
11. 关键代码（H2）
格式： ## 关键代码
使用场景：
- 示例有重要代码片段需要特别说明
- 代码包含关键配置或特殊技巧
内容要求：
- 使用 C 语言代码块
- 添加关键注释
- 突出核心配置和 API 调用
示例：
## 关键代码
\`\`\`c
/* DMA 模式需要使用 32 字节对齐的内存 */
char msg[64] __attribute__((aligned(32)));
/* 配置 UART (115200, 8N1, DMA 模式) */
lisa_uart_config_t config = LISA_UART_CONFIG_DMA();
lisa_uart_configure(uart_dev, &config);
/* 设置事件回调 */
lisa_uart_set_callback(uart_dev, uart_event_callback, NULL);
/* 异步发送数据 */
int ret = lisa_uart_write_async(uart_dev, (uint8_t *)msg, strlen(msg));
\`\`\`
12. 配置说明（H2）
使用场景：
- 示例涉及重要配置参数
- 配置有特殊要求或限制
命名规范：
## 参数说明## 配置说明## DMA 配置说明## 循环缓冲区配置说明
内容要求：
- 使用 H3 小标题分段说明
- 使用无序列表说明配置项
示例：
## DMA 配置说明
### 内存对齐要求
- **要求**：DMA 模式下发送缓冲区必须 **32 字节对齐**
- **实现**：使用 `__attribute__((aligned(32)))` 属性
- **原因**：DMA 控制器对内存地址有对齐要求
### 配置宏说明
- **`LISA_UART_CONFIG_DMA()`**：自动配置 DMA 模式，包括：
- `tx_dma_enable = true`：使能 TX DMA
- `rx_dma_enable = true`：使能 RX DMA
- 其他参数使用默认值（115200, 8N1）
13. 验证方法（H2）
使用场景：
- 输出不是直接通过日志可见
- 需要外部工具或设备验证
内容要求：
- 使用 H3 小标题区分不同验证方法
- 提供详细的验证步骤
示例：
## 验证方法
### 方法 1: LED 验证
- 连接 LED（带限流电阻）到 PA20 引脚
- LED 应以中等亮度持续点亮（50% 占空比）
### 方法 2: 示波器验证
- 连接示波器探头到 PA20 引脚
- 观察波形应为：
- 频率：5000 Hz (5 kHz)
- 占空比：50%
14. 注意事项（H2）
格式： ## 注意事项
使用场景：
- 有重要的使用限制或约束
- 常见错误或易忽略的细节
- 安全或性能相关的提醒
内容要求：
- 使用有序列表
- 每项包含粗体关键词和详细说明
- 3-5 项为宜
示例：
## 注意事项
1. **内存对齐**：DMA 模式必须使用 32 字节对齐的发送缓冲区
2. **缓冲区生命周期**：发送完成前不能释放或修改发送缓冲区内容
3. **回调上下文**：回调函数在中断上下文中执行，应尽快返回，不要执行耗时操作
4. **超时处理**：建议设置合理的信号量超时时间，避免永久等待
5. **并发控制**：如需连续发送，应等待上一次发送完成后再发起下一次发送
文档编写通用规则
1. 语言风格
- 简洁明了：避免冗长描述，直击重点
- 技术准确：使用准确的技术术语
- 一致性：同一概念在文档中保持术语统一
2. 格式规范
- 中英文混排：中英文之间无需空格（除非是完整英文句子）
- 代码标注：API 名称、变量名使用反引号标注（如
lisa_uart_configure()） - 强调：关键概念或数值使用粗体（如 32 字节对齐）
- 列表缩进：子列表使用 2 空格缩进
3. 代码块
- 语言标注：代码块指定语言（c、bash 等）
- 注释：关键代码添加简洁注释
- 完整性：代码片段应能独立理解，避免断章取义
4. 专业术语
常用术语标准表达：
- DMA 模式（不是 dma 模式）
- 中断模式（不是 INT 模式）
- 同步/异步（不是 sync/async，除非在代码中）
- 循环缓冲区（不是环形缓冲区）
- Ping-Pong 缓冲区（保持英文）
- CPU 占用（不是 cpu 占用）
文档模板
基础示例模板
# LISA {DRIVER} {功能}示例
## 功能说明
{简要说明示例的核心功能}
## 硬件连接
- **引脚**: 功能说明
## 示例内容
1. 步骤1
2. 步骤2
3. 步骤3
## 编译运行
\`\`\`bash
./build.sh -C -DBOARD=arcs_evb
\`\`\`
## 预期输出
\`\`\`
输出内容
\`\`\`
高级示例模板
# LISA {DRIVER} {功能}示例（{模式/特性说明}）
## 功能说明
{简要说明示例的核心功能}
### 新特性
- **特性1**：说明
- **特性2**：说明
- **特性3**：说明
## 硬件连接
- **引脚**: 功能说明
## 使用场景
{说明适用场景和技术选型考虑}
## 示例步骤
1. 步骤1
2. 步骤2
3. 步骤3
## 编译运行
\`\`\`bash
./build.sh -C -DBOARD=arcs_evb
\`\`\`
## 预期输出
**终端输出：**
\`\`\`
输出内容
\`\`\`
## 核心 API
| API | 说明 |
|-----|------|
| `api_name()` | 功能说明 |
## {功能}说明
{详细说明工作原理和关键特性}
## 关键代码
\`\`\`c
/* 代码示例 */
\`\`\`
## 配置说明
### 配置项1
- 说明
### 配置项2
- 说明
## 注意事项
1. **关键点1**：说明
2. **关键点2**：说明
文档审查清单
在发布示例文档前，请确认以下项目：
- 标题格式符合规范
- 功能说明简洁明了
- 硬件连接信息完整准确
- 示例步骤清晰有序
- 预期输出与实际代码一致
- API 名称使用反引号标注
- 代码块指定了语言类型
- 术语表达统一准确
- 配置参数说明完整
- 注意事项涵盖关键限制
- 无拼写或格式错误
- 文档与实际代码完全匹配
版本历史
| 版本 | 日期 | 说明 |
|---|---|---|
| 1.0 | 2025-01-25 | 初始版本 |
维护者： ARCS SDK 团队 最后更新： 2025-01-25