# 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、串口、温度采样封装，以及 SPI 命令总线与命令处理器拆分 - **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：采样温度原始值 + 计算工程值 - CAN RX 中断：置位接收解析任务，主循环按预算尽快消费 - 10ms：保留系统 10ms 节拍计数 - 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/` 文件说明 ### SPI 命令总线拆分说明 - `device/spi_command_handler.h`：SPI 命令处理器抽象与上下文结构。 - `device/app_spi_command_defs.h`：APP 运行期 SPI 协议公共常量。 - `device/app_spi_command.cpp`：当前仅负责 SPI 链路和命令路由。 - `device/app_spi_cmd_boot_request.cpp`：进入 Bootloader 的 SPI 命令处理器。 - `device/app_spi_cmd_ota_wait.cpp`：OTA 相关命令的 WAIT 响应处理器。 - `device/app_spi_cmd_ping.cpp`：APP Ping 命令处理器。 - `device/app_spi_cmd_can_bridge.cpp`：SPI→CAN 桥接命令处理器。 - 新增 SPI 业务时优先新增 `device/app_spi_cmd_*.cpp`，而不是继续膨胀 `app_spi_command.cpp`。 ### `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` - 定义状态发送载荷结构 `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 工作模式 - RX0 中断批量搬空硬件 FIFO0 - 按通道缓存接收帧 - 构建状态发送帧 - 发送准备好的 FD 帧 - 维护 CANFD 诊断统计信息 **内部拆分特点：** - RX 和 TX 已拆成两段式 - 接收侧：`rx interrupt -> queue -> consume` - 发送侧：`prepare -> send` **当前内部缓存：** - `s_rxQueues`：三路接收环形缓冲 - `s_txQueues`：三路待发送环形缓冲 - `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 收发流程已拆成两段式 - CANFD 接收已切换为中断事件驱动和环形缓冲 - ADC / 温度 / 定时器 / 串口 已模块化 ### 当前仍可继续演进的方向 - 将 `task_runner.cpp` 再拆成 `task_adc.cpp / task_can.cpp / task_diag.cpp` - 将协议帧定义抽到单独文件中 - 完善状态灯任务与心跳任务 --- ## 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，避免它变成过期文档。