cbb/DCU_APP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(device): 移除备份配置文件并完善ADC模块注释

Browse Source 
移除不再需要的 .cproject.yml.bak_dma 和 README.md 备份文件，
同时为 ADC.cpp 添加完整的 Doxygen 风格函数注释，提升代码可读性。
This commit is contained in:
cbb
2026-05-10 21:27:51 +08:00
parent 4b8b47bc9b
commit 078ea06317
77 changed files with 1326 additions and 6074 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+539
View File
@@ -0,0 +1,539 @@
# GD32E508_DCU_APP README
本 README 用来介绍 `/workzone/ROBOT_V2/DCU/DCU_APP/GD32E508_DCU_APP` 目录下各个代码文件的作用、分层关系和阅读顺序。
---
## 1. 项目概览
这是一个基于 **GD32E508** 的 DCU 应用工程，当前代码已经整理为：
- **应用入口层**：`main.cpp` / `main.h`
- **系统层（sys）**：负责初始化、节拍、任务调度、任务执行
- **设备层（device）**：负责 ADC、CANFD、Timer、串口、温度采样封装
- **RTE / Device 层**：芯片启动文件、链接脚本、厂商外设驱动
当前整体执行逻辑是：
1. `main.cpp` 调用 `app_init()` 完成硬件初始化
2. `task_runner_init()` 初始化任务运行时数据
3. `Timer` 周期中断驱动 `task_manager` 置位任务标志
4. 主循环中 `task_runner_run_pending()` 读取并执行任务
5. `ADC / CANFD / temp_sensor / usart0` 等模块提供具体功能
---
## 2. 推荐阅读顺序
如果第一次接手这个工程，建议按这个顺序看：
1. `main.cpp`
2. `main.h`
3. `sys/initial.*`
4. `sys/task_manager.*`
5. `sys/task_runner.*`
6. `device/Timer.*`
7. `device/ADC.*`
8. `device/temp_sensor.*`
9. `device/CANFD.*`
10. `device/usart0.*`
11. `sys/systick.*`
12. `RTE/Device/GD32E508VE/*`
这样能先看清主流程，再逐层下钻。
---
## 3. 应用层代码文件说明
### 3.1 根目录文件
#### `main.cpp`
**作用：**
- 应用主入口
- 调用系统初始化
- 启动任务运行时
- 进入主循环执行待处理任务
**当前职责很轻：**
- 不直接处理 ADC
- 不直接处理 CANFD
- 不直接实现业务任务逻辑
这是当前工程的“总入口 + 调度外壳”。
---
#### `main.h`
**作用：**
- 全局基础头文件
- 引入 `RTE_Components.h` 和芯片头文件
- 定义系统任务枚举 `system_task_t`
- 定义调度器状态结构 `task_scheduler_t`
- 声明全局调度器实例 `g_scheduler`
**这里的核心内容：**
- 任务类型定义
- 调度节拍状态定义
可以把它理解为“任务系统公共协议头”。
---
## 4. 系统层 `sys/` 文件说明
### `sys/initial.h`
**作用：**
- 声明应用初始化函数 `app_init()`
这是初始化入口的头文件。
---
### `sys/initial.cpp`
**作用：**
- 实现 `app_init()`
- 负责按顺序初始化各基础模块
**当前初始化内容包括：**
- SysTick
- USART0 GPIO
- USART0 串口
- 温度采样模块
- CANFD 模块
- 任务调度器
- 用户定时器
这是系统启动时的“初始化编排器”。
---
### `sys/systick.h`
**作用：**
- 声明系统毫秒节拍相关接口
**当前提供：**
- `systick_config_ms()`
- `delay_ms()`
---
### `sys/systick.cpp`
**作用：**
- 实现 SysTick 中断处理
- 维护毫秒计数器
- 提供毫秒级阻塞延时
**当前功能：**
- `SysTick_Handler()`：系统滴答中断
- `delay_ms()`：基于滴答计数的阻塞延时
- `systick_config_ms()`：配置 1ms 节拍
这是系统时间基准模块。
---
### `sys/task_manager.h`
**作用：**
- 声明任务调度器接口
**当前提供：**
- `task_manager_init()`
- `task_manager_tick_100us()`
- `task_manager_take_pending()`
- `task_manager_set()`
---
### `sys/task_manager.cpp`
**作用：**
- 维护全局任务标志位和节拍计数
- 根据 100us 节拍分发不同周期任务
**当前任务节拍划分：**
- 500us：采样 VREF 原始值
- 1ms：采样温度原始值 + 计算工程值
- 10ms：CAN 接收轮询 + 接收解析
- 100ms：CAN 发送准备 + CAN 发送 + 状态灯任务
- 1s：心跳任务 + 诊断打印任务
这是“什么时候执行任务”的核心模块。
---
### `sys/task_runner.h`
**作用：**
- 声明任务执行器接口
**当前提供：**
- `task_runner_init()`
- `task_runner_run_pending()`
---
### `sys/task_runner.cpp`
**作用：**
- 真正执行任务逻辑
- 保存应用运行时缓存
- 将任务位映射到具体函数
**当前内部任务包括：**
- ADC 原始采样任务
- ADC 工程值计算任务
- CAN RX 轮询任务
- CAN RX 解析任务
- CAN TX 准备任务
- CAN TX 发送任务
- 状态灯任务（占位）
- 心跳任务（占位）
- 诊断打印任务
**当前内部运行时缓存：**
- 最近一次温度采样结果
- 最近一次 VREF 原始值
- 最近一次温度原始值
- 最近一次接收 CAN 帧 ID / 长度 / 数据
这是“执行什么任务”的核心模块。
---
## 5. 设备层 `device/` 文件说明
### `device/adc.h`
**作用：**
- 定义 ADC 采样结果结构 `adc_sample_t`
- 声明 ADC 硬件初始化、采样、换算接口
**主要接口：**
- `adc_hw_init()`
- `adc_single_read()`
- `adc_read_vref_raw()`
- `adc_read_temp_raw()`
- `adc_calculate_vdda()`
- `adc_calculate_temperature()`
- `adc_collect_sample()`
---
### `device/ADC.cpp`
**作用：**
- 实现内部温度/VREF 的 ADC 采样流程
- 提供原始值读取与工程值换算
**当前能力：**
- 初始化 ADC0
- 读取内部参考电压
- 读取内部温度通道
- 根据参考电压估算 VDDA
- 根据内部温度特性曲线估算温度
- 输出完整采样结构
这是 ADC 采样核心模块。
---
### `device/temp_sensor.h`
**作用：**
- 对温度采样模块做轻量封装
- 将 `adc_sample_t` 别名为 `temp_sensor_data_t`
**主要接口：**
- `temp_sensor_init()`
- `temp_sensor_sample()`
---
### `device/temp_sensor.cpp`
**作用：**
- 基于 ADC 模块提供温度采样初始化和采样包装
**本质上：**
- `temp_sensor_init()` → 调用 `adc_hw_init()`
- `temp_sensor_sample()` → 调用 `adc_collect_sample()`
这是一个轻量适配层，让上层按“温度传感器模块”来理解，而不直接依赖 ADC 细节。
---
### `device/usart0.h`
**作用：**
- 声明 USART0 串口相关接口
**当前提供：**
- `usart0_gpio_config()`
- `usart0_config()`
- `fputc()`
---
### `device/usart0.cpp`
**作用：**
- 配置 USART0 的 GPIO 和串口参数
- 重定向 `printf` 到 USART0
**主要用途：**
- 启动信息输出
- 运行时诊断打印
这是当前工程的串口调试输出模块。
---
### `device/Timer.h`
**作用：**
- 声明用户任务定时器初始化接口
**当前提供：**
- `user_timer_init()`
---
### `device/Timer.cpp`
**作用：**
- 配置 TIMER2
- 配置 TIMER2 中断
- 在中断里驱动任务系统节拍
**当前逻辑：**
- `user_timer_init()` 完成 TIMER2 配置与 NVIC 配置
- `TIMER2_IRQHandler()` 在每次更新中断中调用 `task_manager_tick_100us()`
这是任务节拍的硬件入口模块。
---
### `device/canfd.h`
**作用：**
- 定义 CANFD 模块对外接口
- 定义诊断结构 `canfd_diag_t`
- 定义状态发送载荷结构 `canfd_status_payload_t`
**主要接口：**
- `canfd_init()`
- `canfd_poll()`
- `canfd_prepare_status()`
- `canfd_send_prepared()`
- `canfd_has_rx_frame()`
- `canfd_consume_rx_frame()`
- `canfd_get_diag()`
---
### `device/CANFD.cpp`
**作用：**
- 初始化 CANFD 工作模式
- 轮询接收 FIFO
- 缓存接收帧
- 构建状态发送帧
- 发送准备好的 FD 帧
- 维护 CANFD 诊断统计信息
**内部拆分特点：**
- RX 和 TX 已拆成两段式
- 接收侧：`poll -> cache -> consume`
- 发送侧：`prepare -> send`
**当前内部缓存：**
- `g_rx_frame`：单帧接收缓存
- `g_tx_buffer`：待发送帧缓存
- `g_can_diag`：收发与错误统计
这是当前最重要的通信模块之一。
---
## 6. RTE / Device 层文件说明
下面这些文件主要属于：
- 芯片启动代码
- 链接脚本
- 厂商标准外设驱动
- 自动生成的运行环境文件
**原则：**
- 这些文件通常不是业务逻辑主战场
- 不建议随意直接修改
- 如果一定要改，最好确认是可持续维护的变更
---
### `RTE/_Debug_GD32E508VE/RTE_Components.h`
**作用：**
- 自动生成的组件配置头文件
- 指定当前工程启用哪些外设组件
- 定义 `CMSIS_device_header`
这是编译入口层配置文件之一。
---
### `RTE/Device/GD32E508VE/startup_gd32e50x_cl.s`
**作用：**
- 启动汇编文件
- 定义中断向量表
- 复位入口
- 弱符号中断处理默认实现
这是 MCU 上电启动时最底层的入口。
---
### `RTE/Device/GD32E508VE/system_gd32e50x.c`
**作用：**
- 系统时钟配置与系统变量维护
- 提供 `SystemCoreClock` 相关支持
这是 CMSIS 系统层实现文件。
---
### `RTE/Device/GD32E508VE/ac6_linker_script.sct.src`
**作用：**
- AC6 工具链链接脚本模板
- 控制代码段、数据段、栈、堆等布局
---
### `RTE/Device/GD32E508VE/regions_GD32E508VE.h`
**作用：**
- 链接内存区域定义头文件
- 配合链接脚本使用
---
## 7. 厂商外设驱动源文件
以下文件属于厂商标准外设驱动，主要为 `gd32e50x_xxx.c`：
### `gd32e50x_adc.c`
**作用：** ADC 外设驱动实现。
### `gd32e50x_can.c`
**作用：** CAN / CANFD 相关底层驱动实现。
**说明：** 当前项目的 CANFD 能力依赖这个文件中的 GD32E508 分支实现。
### `gd32e50x_crc.c`
**作用：** CRC 外设驱动实现。
### `gd32e50x_dbg.c`
**作用：** 调试控制相关外设驱动实现。
### `gd32e50x_dma.c`
**作用：** DMA 外设驱动实现。
### `gd32e50x_exti.c`
**作用：** 外部中断控制驱动实现。
### `gd32e50x_fmc.c`
**作用：** Flash / FMC 相关驱动实现。
### `gd32e50x_gpio.c`
**作用：** GPIO 外设驱动实现。
### `gd32e50x_misc.c`
**作用：** 中断优先级 / 杂项系统控制驱动实现。
### `gd32e50x_pmu.c`
**作用：** 电源管理单元驱动实现。
### `gd32e50x_rcu.c`
**作用：** 时钟控制单元驱动实现。
### `gd32e50x_spi.c`
**作用：** SPI 外设驱动实现。
### `gd32e50x_usart.c`
**作用：** USART 外设驱动实现。
---
## 8. `.base@版本号` 文件说明
例如：
- `gd32e50x_can.c.base@1.0.0`
- `gd32e50x_adc.c.base@1.5.0`
- `startup_gd32e50x_cl.s.base@1.5.0`
这些文件通常表示：
- 原始基线版本
- 或工具生成时附带的参考副本
**建议：**
- 默认不要动
- 真要比对升级差异时再看
---
## 9. 当前应用层模块关系图（逻辑上）
```text
main.cpp
├─ sys/initial.cpp
│ ├─ sys/systick.cpp
│ ├─ device/usart0.cpp
│ ├─ device/temp_sensor.cpp
│ │ └─ device/ADC.cpp
│ ├─ device/CANFD.cpp
│ ├─ sys/task_manager.cpp
│ └─ device/Timer.cpp
│ └─ TIMER2_IRQHandler -> task_manager_tick_100us()
│
└─ sys/task_runner.cpp
├─ device/ADC.cpp
├─ device/CANFD.cpp
└─ sys/task_manager.cpp
```
---
## 10. 当前代码特点总结
### 已完成的结构化工作
- 应用层 `.c` 已整理为 `.cpp`
- `main` 已瘦身
- 任务管理与任务执行已分离
- CANFD 收发流程已拆成两段式
- ADC / 温度 / 定时器 / 串口 已模块化
### 当前仍可继续演进的方向
- 将 `task_runner.cpp` 再拆成 `task_adc.cpp / task_can.cpp / task_diag.cpp`
- 将 CANFD 单帧缓存升级为轻量环形缓冲
- 将协议帧定义抽到单独文件中
- 完善状态灯任务与心跳任务
---
## 11. 维护建议
### 建议优先修改的位置
如果是改业务逻辑，优先看：
- `sys/task_runner.cpp`
- `device/CANFD.cpp`
- `device/ADC.cpp`
- `sys/task_manager.cpp`
### 不建议随便改的位置
除非你明确知道在干什么，否则不要轻易改：
- `RTE/Device/GD32E508VE/startup_gd32e50x_cl.s`
- `RTE/Device/GD32E508VE/system_gd32e50x.c`
- `RTE/Device/GD32E508VE/gd32e50x_*.c`
- 链接脚本相关文件
---
## 12. 后续建议
如果准备继续把这个项目做成更长期可维护的结构，下一步最值的动作是：
1. 增加 `protocol/` 或 `frames/` 目录，专门放 CANFD 帧定义
2. 将 `task_runner.cpp` 按任务领域继续拆文件
3. 给应用层全部源码统一补齐函数级注释和参数说明
4. 根据目标总线速率进一步细化 CANFD nominal/data timing 参数
---
如果后面代码结构继续变化，记得同步更新本 README，避免它变成过期文档。