arcs/arcs-sdk/drivers/Devices_Docs_Spec.md

ARCS 平台驱动设备文档编写规范

本规范基于 lisa_adc、lisa_gpio、lisa_uart 三个驱动文档的分析总结而成，旨在为 ARCS 平台的驱动开发提供统一的文档编写标准。

一、文档结构规范

1.1 标题与简介（必需）

格式:

# <驱动名称> 驱动

基于 lisa_device 框架的 <设备类型> 设备驱动，为 ARCS 平台提供统一的<功能描述>接口。

要求:

• 标题使用一级标题，格式为 "<驱动名称> 驱动"
• 简介一句话说明驱动的定位和用途
• 必须提及基于 lisa_device 框架
• 必须说明为 ARCS 平台提供的核心功能

示例:

# ADC 驱动

基于 lisa_device 框架的 ADC 设备驱动，为 ARCS 平台提供统一的模拟信号采样接口。

1.2 功能特性（必需）

格式:

## 功能特性

- **特性名称**: 特性说明
- **特性名称**: 特性说明
...

要求:

• 使用二级标题 "功能特性"
• 使用无序列表，每项使用 **粗体** 突出特性名称
• 按重要性排序：设备支持 → 核心功能 → 高级功能
• 5-8 个要点，简洁明了
• 必须包含的特性：设备支持、核心功能、线程安全（如果支持）

示例:

## 功能特性

- **设备支持**: UART0、UART1、UART2 三个串口设备
- **传输模式**: 支持中断模式和 DMA 模式
- **通信配置**: 灵活配置波特率、数据位、停止位、校验位、流控
- **数据传输**: 同步/异步读写、轮询收发
- **线程安全**: 支持全双工通信，可在多线程环境中使用

1.3 配置选项（必需）

格式:

## 配置选项

在 `prj.conf` 中启用驱动：

​```kconfig
CONFIG_LISA_<驱动名称>=y
CONFIG_LISA_<设备1>=y        # 启用说明（可选）
CONFIG_LISA_<设备2>=y        # 启用说明（可选）
​```

根据需要选择启用的设备或功能。

要求:

• 使用二级标题 "配置选项"
• 明确说明配置文件位置（prj.conf 或 Kconfig）
• 使用 kconfig 代码块
• 提供必需和可选配置项
• 对每个配置项添加注释说明（如果有多个选项）

1.4 API 接口（必需）

格式:

## API 接口

### <功能分类1>

​```c
函数原型1;
函数原型2;
​```

功能说明（可选）。

### <功能分类2>

​```c
函数原型1;
函数原型2;
​```

功能说明（可选）。

要求:

• 使用二级标题 "API 接口"
• 按功能分类组织，使用三级标题
• 常见分类：配置接口、数据传输接口、控制接口、中断管理等
• 仅提供函数原型，详细说明放在后续章节
• 如有重要提示，使用 粗体 或 代码 强调

示例:

## 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）

## 使用方法

### 基本步骤

1. **步骤名称**: 步骤说明
2. **步骤名称**: 步骤说明
3. **步骤名称**: 步骤说明

### 基础使用示例

​```c
// 完整代码示例
​```

### 进阶示例1

​```c
// 完整代码示例
​```

方式二：直接示例（适用于使用模式多样的驱动，如 GPIO、UART）

## 使用示例

### 场景1名称

​```c
// 完整代码示例
​```

### 场景2名称

​```c
// 完整代码示例
​```

要求:

• 使用二级标题 "使用示例" 或 "使用方法"
• 每个示例使用三级标题，标题应清晰描述使用场景
• 代码必须完整可运行，包含必要的头文件、错误处理
• 代码注释清晰，使用 // 单行注释说明步骤
• 从简单到复杂排序
• 至少提供 2-3 个典型使用场景
• 示例应覆盖主要 API 的使用

代码风格:

• 使用行内注释 // 说明 而非块注释
• 注释使用中文
• 关键步骤前添加序号注释：// 1. 获取设备
• 错误处理要简洁但完整

1.6 硬件配置（必需）

格式:

## 硬件配置

### 引脚复用配置

<驱动名称> 驱动在初始化时会自动调用板型目录中定义的 `lisa_<驱动>_pinmux()` 函数，用于配置引脚复用。

**配置位置**:
- **定义**: `boards/<板型名>/pinmux.c` 中实现函数
- **声明**: `boards/<板型名>/pinmux.h` 中声明函数
- **调用时机**: 设备初始化时自动调用

**示例** (参考 `boards/arcs_evb/pinmux.c`):
​```c
// 代码示例
​```

**注意**:
- 该函数由板型相关代码实现，不同板型的引脚配置可能不同
- 只需配置实际使用的引脚
- 其他注意事项...

### 其他硬件相关配置（可选）

如：支持的通道、参考电压选择、中断触发模式等

要求:

• 使用二级标题 "硬件配置"
• 必须包含 "引脚复用配置" 三级标题
• 说明 pinmux 函数的定义位置、声明位置、调用时机
• 提供完整的代码示例（参考 arcs_evb 板型）
• 列出注意事项
• 如有其他硬件相关配置（通道、模式等），使用独立的三级标题

1.7 详细参数说明（可选，按需添加）

适用场景:

• 配置参数复杂（如 ADC 参考电压、UART 配置宏）
• 事件类型多样（如 UART 事件类型）
• 标志位组合（如 GPIO 配置标志）

格式:

## <参数类型>说明

### <参数分类1>

说明文字或表格

### <参数分类2>

说明文字或表格

要求:

• 使用二级标题，标题应明确说明参数类型
• 复杂参数优先使用表格展示
• 表格包含：参数名/枚举、说明、示例（如适用）
• 如有组合使用，提供示例代码

示例:

## 配置标志位

驱动使用标志位方式进行配置，可以通过按位或（`|`）组合多个标志：

### 方向标志
- `LISA_GPIO_INPUT` - 输入模式（默认）
- `LISA_GPIO_OUTPUT` - 输出模式

### 示例组合
​```c
// 输入模式 + 上拉
LISA_GPIO_INPUT | LISA_GPIO_PULL_UP
​```

1.8 注意事项（必需）

格式:

## 注意事项

1. **注意点标题**: 详细说明
2. **注意点标题**: 详细说明
...

要求:

• 使用二级标题 "注意事项"
• 使用有序列表，每项使用 **粗体** 突出要点
• 包含但不限于：
  • 使用限制（范围、顺序、前置条件）
  • 常见错误和解决方法
  • 性能影响
  • 线程安全说明
  • 硬件限制
• 按重要性和逻辑关系排序
• 10 条左右为宜，不超过 15 条

示例:

## 注意事项

1. **必须先配置**: 设备初始化后必须先调用 `lisa_uart_configure()` 配置设备，才能使用功能 API
2. **引脚范围**: 每个 GPIO 控制器支持 0-31 共 32 个引脚
3. **线程安全**: 驱动内部使用互斥锁保护，可在多线程环境中使用

1.9 文件说明（可选）

格式:

## 文件说明

- `文件名` - 文件用途说明
- `文件名` - 文件用途说明

要求:

• 使用二级标题 "文件说明"
• 使用无序列表
• 列出驱动目录下的主要文件
• 简要说明每个文件的用途

二、内容编写规范

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 代码示例规范

完整性:

#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 表格使用规范

适用场景:

• 参数列表（通道、引脚映射）
• 枚举说明（事件类型、配置标志）
• 返回值说明
• 配置选项对比

格式要求:

| 列标题1 | 列标题2 | 列标题3 |
|--------|--------|--------|
| 内容1  | 内容2  | 内容3  |

内容要求:

• 表头简洁明确
• 单元格内容简短，避免长句
• 代码使用反引号包裹
• 对齐美观

2.4 强调和提示

粗体强调:

• 用于标题关键词："设备支持: UART0、UART1"
• 用于注意事项："重要: 必须先配置设备"

代码强调:

• 用于函数名：lisa_uart_configure()
• 用于配置项：CONFIG_LISA_ADC=y
• 用于枚举：LISA_GPIO_INPUT

重要提示:

**重要**: 说明文字

**注意**: 说明文字

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 接口"章节后添加详细说明：

## 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 特殊功能说明

对于特殊的计算、转换或配置逻辑，使用独立章节说明：

## 电压转换

使用 `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. 基础驱动文档模板

# 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. 参数说明模板

## <参数类型>说明

### <参数分类>

| 参数名 | 说明 | 备注 |
|-------|------|------|
| xxx   | xxx  | xxx  |

**示例**:
​```c
// 代码示例
​```

---

本规范基于以下文档分析:

• drivers/lisa_adc/README.md
• drivers/lisa_gpio/README.md
• drivers/lisa_uart/README.md

规范版本: v1.0 最后更新: 2025-11-27