683 lines
15 KiB
Markdown
683 lines
15 KiB
Markdown
# ARCS 平台驱动设备文档编写规范
|
||
|
||
本规范基于 lisa_adc、lisa_gpio、lisa_uart 三个驱动文档的分析总结而成，旨在为 ARCS 平台的驱动开发提供统一的文档编写标准。
|
||
|
||
## 一、文档结构规范
|
||
|
||
### 1.1 标题与简介（必需）
|
||
|
||
**格式**:
|
||
```markdown
|
||
# <驱动名称> 驱动
|
||
|
||
基于 lisa_device 框架的 <设备类型> 设备驱动，为 ARCS 平台提供统一的<功能描述>接口。
|
||
```
|
||
|
||
**要求**:
|
||
- 标题使用一级标题，格式为 "<驱动名称> 驱动"
|
||
- 简介一句话说明驱动的定位和用途
|
||
- 必须提及基于 lisa_device 框架
|
||
- 必须说明为 ARCS 平台提供的核心功能
|
||
|
||
**示例**:
|
||
```markdown
|
||
# ADC 驱动
|
||
|
||
基于 lisa_device 框架的 ADC 设备驱动，为 ARCS 平台提供统一的模拟信号采样接口。
|
||
```
|
||
|
||
### 1.2 功能特性（必需）
|
||
|
||
**格式**:
|
||
```markdown
|
||
## 功能特性
|
||
|
||
- **特性名称**: 特性说明
|
||
- **特性名称**: 特性说明
|
||
...
|
||
```
|
||
|
||
**要求**:
|
||
- 使用二级标题 "功能特性"
|
||
- 使用无序列表，每项使用 `**粗体**` 突出特性名称
|
||
- 按重要性排序：设备支持 → 核心功能 → 高级功能
|
||
- 5-8 个要点，简洁明了
|
||
- 必须包含的特性：设备支持、核心功能、线程安全（如果支持）
|
||
|
||
**示例**:
|
||
```markdown
|
||
## 功能特性
|
||
|
||
- **设备支持**: UART0、UART1、UART2 三个串口设备
|
||
- **传输模式**: 支持中断模式和 DMA 模式
|
||
- **通信配置**: 灵活配置波特率、数据位、停止位、校验位、流控
|
||
- **数据传输**: 同步/异步读写、轮询收发
|
||
- **线程安全**: 支持全双工通信，可在多线程环境中使用
|
||
```
|
||
|
||
### 1.3 配置选项（必需）
|
||
|
||
**格式**:
|
||
```markdown
|
||
## 配置选项
|
||
|
||
在 `prj.conf` 中启用驱动：
|
||
|
||
```kconfig
|
||
CONFIG_LISA_<驱动名称>=y
|
||
CONFIG_LISA_<设备1>=y # 启用说明（可选）
|
||
CONFIG_LISA_<设备2>=y # 启用说明（可选）
|
||
```
|
||
|
||
根据需要选择启用的设备或功能。
|
||
```
|
||
|
||
**要求**:
|
||
- 使用二级标题 "配置选项"
|
||
- 明确说明配置文件位置（prj.conf 或 Kconfig）
|
||
- 使用 kconfig 代码块
|
||
- 提供必需和可选配置项
|
||
- 对每个配置项添加注释说明（如果有多个选项）
|
||
|
||
### 1.4 API 接口（必需）
|
||
|
||
**格式**:
|
||
```markdown
|
||
## API 接口
|
||
|
||
### <功能分类1>
|
||
|
||
```c
|
||
函数原型1;
|
||
函数原型2;
|
||
```
|
||
|
||
功能说明（可选）。
|
||
|
||
### <功能分类2>
|
||
|
||
```c
|
||
函数原型1;
|
||
函数原型2;
|
||
```
|
||
|
||
功能说明（可选）。
|
||
```
|
||
|
||
**要求**:
|
||
- 使用二级标题 "API 接口"
|
||
- 按功能分类组织，使用三级标题
|
||
- 常见分类：配置接口、数据传输接口、控制接口、中断管理等
|
||
- 仅提供函数原型，详细说明放在后续章节
|
||
- 如有重要提示，使用 **粗体** 或 `代码` 强调
|
||
|
||
**示例**:
|
||
```markdown
|
||
## API 接口
|
||
|
||
### 配置接口
|
||
|
||
```c
|
||
int lisa_uart_configure(lisa_device_t *dev, const lisa_uart_config_t *config);
|
||
int lisa_uart_get_config(lisa_device_t *dev, lisa_uart_config_t *config);
|
||
```
|
||
|
||
**重要**: 必须先调用 `lisa_uart_configure()` 配置设备后，才能使用下面的功能 API。
|
||
|
||
### 数据传输接口
|
||
|
||
```c
|
||
int lisa_uart_write_sync(lisa_device_t *dev, const uint8_t *buf, uint32_t len, uint32_t timeout_ms);
|
||
int lisa_uart_read_sync(lisa_device_t *dev, uint8_t *buf, uint32_t len);
|
||
```
|
||
```
|
||
|
||
### 1.5 使用示例/使用方法（必需）
|
||
|
||
**格式**:
|
||
|
||
**方式一：基本步骤 + 示例**（适用于步骤明确的驱动，如 ADC）
|
||
```markdown
|
||
## 使用方法
|
||
|
||
### 基本步骤
|
||
|
||
1. **步骤名称**: 步骤说明
|
||
2. **步骤名称**: 步骤说明
|
||
3. **步骤名称**: 步骤说明
|
||
|
||
### 基础使用示例
|
||
|
||
```c
|
||
// 完整代码示例
|
||
```
|
||
|
||
### 进阶示例1
|
||
|
||
```c
|
||
// 完整代码示例
|
||
```
|
||
```
|
||
|
||
**方式二：直接示例**（适用于使用模式多样的驱动，如 GPIO、UART）
|
||
```markdown
|
||
## 使用示例
|
||
|
||
### 场景1名称
|
||
|
||
```c
|
||
// 完整代码示例
|
||
```
|
||
|
||
### 场景2名称
|
||
|
||
```c
|
||
// 完整代码示例
|
||
```
|
||
```
|
||
|
||
**要求**:
|
||
- 使用二级标题 "使用示例" 或 "使用方法"
|
||
- 每个示例使用三级标题，标题应清晰描述使用场景
|
||
- 代码必须完整可运行，包含必要的头文件、错误处理
|
||
- 代码注释清晰，使用 `//` 单行注释说明步骤
|
||
- 从简单到复杂排序
|
||
- 至少提供 2-3 个典型使用场景
|
||
- 示例应覆盖主要 API 的使用
|
||
|
||
**代码风格**:
|
||
- 使用行内注释 `// 说明` 而非块注释
|
||
- 注释使用中文
|
||
- 关键步骤前添加序号注释：`// 1. 获取设备`
|
||
- 错误处理要简洁但完整
|
||
|
||
### 1.6 硬件配置（必需）
|
||
|
||
**格式**:
|
||
```markdown
|
||
## 硬件配置
|
||
|
||
### 引脚复用配置
|
||
|
||
<驱动名称> 驱动在初始化时会自动调用板型目录中定义的 `lisa_<驱动>_pinmux()` 函数，用于配置引脚复用。
|
||
|
||
**配置位置**:
|
||
- **定义**: `boards/<板型名>/pinmux.c` 中实现函数
|
||
- **声明**: `boards/<板型名>/pinmux.h` 中声明函数
|
||
- **调用时机**: 设备初始化时自动调用
|
||
|
||
**示例** (参考 `boards/arcs_evb/pinmux.c`):
|
||
```c
|
||
// 代码示例
|
||
```
|
||
|
||
**注意**:
|
||
- 该函数由板型相关代码实现，不同板型的引脚配置可能不同
|
||
- 只需配置实际使用的引脚
|
||
- 其他注意事项...
|
||
|
||
### 其他硬件相关配置（可选）
|
||
|
||
如：支持的通道、参考电压选择、中断触发模式等
|
||
```
|
||
|
||
**要求**:
|
||
- 使用二级标题 "硬件配置"
|
||
- 必须包含 "引脚复用配置" 三级标题
|
||
- 说明 pinmux 函数的定义位置、声明位置、调用时机
|
||
- 提供完整的代码示例（参考 arcs_evb 板型）
|
||
- 列出注意事项
|
||
- 如有其他硬件相关配置（通道、模式等），使用独立的三级标题
|
||
|
||
### 1.7 详细参数说明（可选，按需添加）
|
||
|
||
**适用场景**:
|
||
- 配置参数复杂（如 ADC 参考电压、UART 配置宏）
|
||
- 事件类型多样（如 UART 事件类型）
|
||
- 标志位组合（如 GPIO 配置标志）
|
||
|
||
**格式**:
|
||
```markdown
|
||
## <参数类型>说明
|
||
|
||
### <参数分类1>
|
||
|
||
说明文字或表格
|
||
|
||
### <参数分类2>
|
||
|
||
说明文字或表格
|
||
```
|
||
|
||
**要求**:
|
||
- 使用二级标题，标题应明确说明参数类型
|
||
- 复杂参数优先使用表格展示
|
||
- 表格包含：参数名/枚举、说明、示例（如适用）
|
||
- 如有组合使用，提供示例代码
|
||
|
||
**示例**:
|
||
```markdown
|
||
## 配置标志位
|
||
|
||
驱动使用标志位方式进行配置，可以通过按位或（`|`）组合多个标志：
|
||
|
||
### 方向标志
|
||
- `LISA_GPIO_INPUT` - 输入模式（默认）
|
||
- `LISA_GPIO_OUTPUT` - 输出模式
|
||
|
||
### 示例组合
|
||
```c
|
||
// 输入模式 + 上拉
|
||
LISA_GPIO_INPUT | LISA_GPIO_PULL_UP
|
||
```
|
||
```
|
||
|
||
### 1.8 注意事项（必需）
|
||
|
||
**格式**:
|
||
```markdown
|
||
## 注意事项
|
||
|
||
1. **注意点标题**: 详细说明
|
||
2. **注意点标题**: 详细说明
|
||
...
|
||
```
|
||
|
||
**要求**:
|
||
- 使用二级标题 "注意事项"
|
||
- 使用有序列表，每项使用 `**粗体**` 突出要点
|
||
- 包含但不限于：
|
||
- 使用限制（范围、顺序、前置条件）
|
||
- 常见错误和解决方法
|
||
- 性能影响
|
||
- 线程安全说明
|
||
- 硬件限制
|
||
- 按重要性和逻辑关系排序
|
||
- 10 条左右为宜，不超过 15 条
|
||
|
||
**示例**:
|
||
```markdown
|
||
## 注意事项
|
||
|
||
1. **必须先配置**: 设备初始化后必须先调用 `lisa_uart_configure()` 配置设备，才能使用功能 API
|
||
2. **引脚范围**: 每个 GPIO 控制器支持 0-31 共 32 个引脚
|
||
3. **线程安全**: 驱动内部使用互斥锁保护，可在多线程环境中使用
|
||
```
|
||
|
||
### 1.9 文件说明（可选）
|
||
|
||
**格式**:
|
||
```markdown
|
||
## 文件说明
|
||
|
||
- `文件名` - 文件用途说明
|
||
- `文件名` - 文件用途说明
|
||
```
|
||
|
||
**要求**:
|
||
- 使用二级标题 "文件说明"
|
||
- 使用无序列表
|
||
- 列出驱动目录下的主要文件
|
||
- 简要说明每个文件的用途
|
||
|
||
## 二、内容编写规范
|
||
|
||
### 2.1 术语使用
|
||
|
||
**设备名称**:
|
||
- 使用大写：ADC0、GPIOA、UART0
|
||
- 示例："支持 UART0、UART1、UART2 三个串口设备"
|
||
|
||
**API 函数**:
|
||
- 使用反引号包裹：`lisa_adc_read()`
|
||
- 示例："调用 `lisa_uart_configure()` 配置设备"
|
||
|
||
**配置项**:
|
||
- 使用反引号包裹：`CONFIG_LISA_ADC=y`
|
||
- 枚举使用反引号：`LISA_GPIO_INPUT`
|
||
|
||
**文件路径**:
|
||
- 使用反引号包裹：`boards/<板型名>/pinmux.c`
|
||
- 使用尖括号表示变量部分：`<板型名>`
|
||
|
||
### 2.2 代码示例规范
|
||
|
||
**完整性**:
|
||
```c
|
||
#include "lisa_xxx.h" // 必须包含头文件
|
||
|
||
// 获取设备
|
||
lisa_device_t *dev = lisa_device_get_by_name("xxx");
|
||
if (!dev) { // 必须有错误处理
|
||
return -1;
|
||
}
|
||
|
||
// 功能代码
|
||
...
|
||
|
||
// 返回值检查
|
||
int ret = lisa_xxx_function(dev, ...);
|
||
if (ret == LISA_DEVICE_OK) {
|
||
// 成功处理
|
||
}
|
||
```
|
||
|
||
**注释风格**:
|
||
- 使用 `//` 单行注释
|
||
- 关键步骤添加序号：`// 1. 获取设备`
|
||
- 代码后添加说明注释：`return -1; // 设备未找到`
|
||
- 使用中文注释
|
||
|
||
**错误处理**:
|
||
- 设备获取必须检查空指针
|
||
- API 调用必须检查返回值
|
||
- 简化示例可省略详细错误处理，但需保留结构
|
||
|
||
### 2.3 表格使用规范
|
||
|
||
**适用场景**:
|
||
- 参数列表（通道、引脚映射）
|
||
- 枚举说明（事件类型、配置标志）
|
||
- 返回值说明
|
||
- 配置选项对比
|
||
|
||
**格式要求**:
|
||
```markdown
|
||
| 列标题1 | 列标题2 | 列标题3 |
|
||
|--------|--------|--------|
|
||
| 内容1 | 内容2 | 内容3 |
|
||
```
|
||
|
||
**内容要求**:
|
||
- 表头简洁明确
|
||
- 单元格内容简短，避免长句
|
||
- 代码使用反引号包裹
|
||
- 对齐美观
|
||
|
||
### 2.4 强调和提示
|
||
|
||
**粗体强调**:
|
||
- 用于标题关键词："**设备支持**: UART0、UART1"
|
||
- 用于注意事项："**重要**: 必须先配置设备"
|
||
|
||
**代码强调**:
|
||
- 用于函数名：`lisa_uart_configure()`
|
||
- 用于配置项：`CONFIG_LISA_ADC=y`
|
||
- 用于枚举：`LISA_GPIO_INPUT`
|
||
|
||
**重要提示**:
|
||
```markdown
|
||
**重要**: 说明文字
|
||
|
||
**注意**: 说明文字
|
||
```
|
||
|
||
### 2.5 语言风格
|
||
|
||
**简洁明确**:
|
||
- 避免冗长描述
|
||
- 一句话说清楚一个概念
|
||
- 使用主动语态："调用函数配置设备" 而非 "设备通过调用函数被配置"
|
||
|
||
**专业准确**:
|
||
- 使用准确的技术术语
|
||
- 避免模糊表述："支持 0-7 通道" 而非 "支持多个通道"
|
||
- 数值明确：波特率范围、通道数量
|
||
|
||
**用户视角**:
|
||
- 从使用者角度组织内容
|
||
- 先说明"是什么"，再说明"怎么用"
|
||
- 提供足够的上下文信息
|
||
|
||
## 三、章节顺序规范
|
||
|
||
### 3.1 必需章节（按顺序）
|
||
|
||
1. 标题与简介
|
||
2. 功能特性
|
||
3. 配置选项
|
||
4. API 接口
|
||
5. 使用示例/使用方法
|
||
6. 硬件配置
|
||
7. 注意事项
|
||
|
||
### 3.2 可选章节（插入位置）
|
||
|
||
- **详细 API 说明**：插入在"API 接口"和"使用示例"之间（如果 API 需要详细说明）
|
||
- **配置宏/标志位说明**：插入在"API 接口"和"使用示例"之间
|
||
- **事件类型说明**：插入在"使用示例"之后，"硬件配置"之前
|
||
- **返回值说明**：插入在"硬件配置"之后，"注意事项"之前
|
||
- **数据转换/计算**：根据逻辑插入合适位置（如 ADC 的电压转换放在"使用示例"之后）
|
||
- **文件说明**：放在文档末尾
|
||
|
||
### 3.3 章节组织原则
|
||
|
||
1. 从概念到实践：功能特性 → API → 示例 → 配置
|
||
2. 从常用到进阶：基础 API → 进阶功能 → 硬件细节
|
||
3. 相关内容靠近：配置参数紧跟配置 API
|
||
4. 重要内容前置：常用功能优先介绍
|
||
|
||
## 四、文档质量检查清单
|
||
|
||
### 4.1 结构完整性
|
||
|
||
- [ ] 包含所有必需章节
|
||
- [ ] 章节顺序符合规范
|
||
- [ ] 标题层级正确（# ## ###）
|
||
- [ ] 代码块语言标注正确
|
||
|
||
### 4.2 内容准确性
|
||
|
||
- [ ] API 函数原型正确
|
||
- [ ] 配置选项有效
|
||
- [ ] 代码示例可运行
|
||
- [ ] 参数范围准确
|
||
- [ ] 返回值说明完整
|
||
|
||
### 4.3 可读性
|
||
|
||
- [ ] 术语使用一致
|
||
- [ ] 代码注释清晰
|
||
- [ ] 表格格式规范
|
||
- [ ] 强调使用恰当
|
||
- [ ] 无错别字
|
||
|
||
### 4.4 实用性
|
||
|
||
- [ ] 提供足够的使用示例
|
||
- [ ] 覆盖常见使用场景
|
||
- [ ] 包含错误处理示例
|
||
- [ ] 注意事项全面
|
||
- [ ] 硬件配置说明清晰
|
||
|
||
## 五、特殊场景处理
|
||
|
||
### 5.1 复杂 API 的详细说明
|
||
|
||
当 API 参数复杂或使用有特殊要求时，在"API 接口"章节后添加详细说明：
|
||
|
||
```markdown
|
||
## API 接口
|
||
|
||
### 配置 ADC 通道
|
||
|
||
```c
|
||
int lisa_adc_channel_setup(lisa_device_t *dev, uint32_t channel,
|
||
const lisa_adc_channel_config_t *config);
|
||
```
|
||
|
||
配置指定通道的参考电压和分辨率。应在读取通道之前调用。
|
||
|
||
**参数**:
|
||
- `dev`: ADC 设备指针
|
||
- `channel`: ADC 通道号（0-5：普通通道，6：VBAT，7：TEMP）
|
||
- `config`: 通道配置参数，包含：
|
||
- `reference`: 参考电压类型（枚举）
|
||
- `resolution`: ADC 分辨率（枚举）
|
||
|
||
**返回值**:
|
||
- `LISA_DEVICE_OK (0)`: 成功
|
||
- `LISA_DEVICE_ERR_INVALID`: 参数无效
|
||
```
|
||
|
||
### 5.2 多设备驱动
|
||
|
||
当驱动支持多个设备实例时（如 GPIOA/GPIOB、UART0/1/2）：
|
||
|
||
1. 在"功能特性"中明确列出支持的设备
|
||
2. 在"配置选项"中分别列出每个设备的配置项
|
||
3. 在"硬件配置"中为每个设备提供独立的 pinmux 示例
|
||
4. 在"使用示例"中展示不同设备的使用
|
||
|
||
### 5.3 特殊功能说明
|
||
|
||
对于特殊的计算、转换或配置逻辑，使用独立章节说明：
|
||
|
||
```markdown
|
||
## 电压转换
|
||
|
||
使用 `LISA_ADC_RAW_TO_MV` 宏进行转换：
|
||
|
||
```c
|
||
uint32_t voltage_mv = LISA_ADC_RAW_TO_MV(raw_value, reference_mv, resolution_bits);
|
||
```
|
||
|
||
**参数**:
|
||
- `raw_value`: ADC 原始采样值
|
||
- `reference_mv`: 参考电压（毫伏）
|
||
- `resolution_bits`: 分辨率（位数）
|
||
```
|
||
|
||
## 六、版本和维护
|
||
|
||
### 6.1 文档更新
|
||
|
||
- 驱动 API 变更时，同步更新文档
|
||
- 新增功能时，添加对应示例
|
||
- 发现问题时，补充注意事项
|
||
|
||
### 6.2 示例代码维护
|
||
|
||
- 确保示例代码与最新 API 保持一致
|
||
- 定期验证示例代码的可运行性
|
||
- 根据用户反馈改进示例
|
||
|
||
### 6.3 术语统一
|
||
|
||
- 维护统一的术语表
|
||
- 新驱动文档参考已有文档的术语使用
|
||
- 定期审查术语一致性
|
||
|
||
---
|
||
|
||
## 附录：快速模板
|
||
|
||
### A. 基础驱动文档模板
|
||
|
||
```markdown
|
||
# LISA <驱动名称> 驱动
|
||
|
||
基于 lisa_device 框架的 <设备类型> 设备驱动，为 ARCS 平台提供统一的<功能描述>接口。
|
||
|
||
## 功能特性
|
||
|
||
- **设备支持**:
|
||
- **核心功能**:
|
||
- **配置选项**:
|
||
- **线程安全**:
|
||
|
||
## 配置选项
|
||
|
||
在 `prj.conf` 中启用驱动：
|
||
|
||
```kconfig
|
||
CONFIG_LISA_<驱动名称>=y
|
||
```
|
||
|
||
## API 接口
|
||
|
||
### 配置接口
|
||
|
||
```c
|
||
int lisa_xxx_configure();
|
||
```
|
||
|
||
### 控制接口
|
||
|
||
```c
|
||
int lisa_xxx_xxx();
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 基础使用
|
||
|
||
```c
|
||
#include "lisa_xxx.h"
|
||
|
||
// 1. 获取设备
|
||
lisa_device_t *dev = lisa_device_get_by_name("xxx");
|
||
if (!dev) {
|
||
return -1;
|
||
}
|
||
|
||
// 2. 配置设备
|
||
// ...
|
||
|
||
// 3. 使用功能
|
||
// ...
|
||
```
|
||
|
||
## 硬件配置
|
||
|
||
### 引脚复用配置
|
||
|
||
<驱动名称> 驱动在初始化时会自动调用板型目录中定义的 `lisa_xxx_pinmux()` 函数。
|
||
|
||
**配置位置**:
|
||
- **定义**: `boards/<板型名>/pinmux.c`
|
||
- **声明**: `boards/<板型名>/pinmux.h`
|
||
- **调用时机**: 设备初始化时自动调用
|
||
|
||
**示例**:
|
||
```c
|
||
void lisa_xxx_pinmux()
|
||
{
|
||
// 配置引脚
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **使用限制**:
|
||
2. **配置要求**:
|
||
3. **线程安全**:
|
||
```
|
||
|
||
### B. 参数说明模板
|
||
|
||
```markdown
|
||
## <参数类型>说明
|
||
|
||
### <参数分类>
|
||
|
||
| 参数名 | 说明 | 备注 |
|
||
|-------|------|------|
|
||
| xxx | xxx | xxx |
|
||
|
||
**示例**:
|
||
```c
|
||
// 代码示例
|
||
```
|
||
```
|
||
|
||
---
|
||
|
||
**本规范基于以下文档分析**:
|
||
- drivers/lisa_adc/README.md
|
||
- drivers/lisa_gpio/README.md
|
||
- drivers/lisa_uart/README.md
|
||
|
||
**规范版本**: v1.0
|
||
**最后更新**: 2025-11-27
|