📝 docs(design): 新增系统设计文档集

✨ feat(system-overview): 创建系统总览文档
- 描述项目背景与硬件平台配置
- 提供 FreeRTOS 任务拓扑表(任务优先级、栈大小、职责)
- 详细说明系统启动序列和初始化依赖关系
- 绘制 2D/1D 状态机完整流程图
- 解释 TEMP_REQ 辅助通道工作机制
- 说明任务间同步机制(Frame_Ready_Flag、双缓冲 TX)

✨ feat(dvp-module-design): 创建 DVP 模块设计文档
- 提供 DVP 硬件连接引脚映射表
- 描述 DVP 时序配置(信号极性、工作模式)
- 解释 DMA ping-pong 行缓冲机制和切换逻辑
- 说明 DVP IRQ 帧组装流程(STR_FRM/ROW_DONE)
- 定义 FrameBuffer 数据格式和像素访问方式
- 说明 TMP 模式温度换算公式和字节序要求

✨ feat(qdx-protocol-design): 创建 QDX 协议设计文档
- 描述完整 TLV 帧结构(FrameHeader + TLV + CRC)
- 列出所有 Class/Type 映射表和用途说明
- 解释零拷贝 TX 缓冲区架构(HeadOffset 机制)
- 说明分片机制和最大载荷限制
- 定义 Flags 字段各位含义和使用场景

✨ feat(tcp-module-design): 创建 TCP 通信模块设计文档
- 描述双流连接架构(控制流 5511 / 数据流 5512)
- 说明握手流程和连接建立时序
- 解释心跳机制和 TCP Keepalive 配置
- 描述配置下发与缓存机制
- 说明数据发送队列和背压处理策略
- 解释 WCHNET 网络栈驱动任务工作机制

✨ feat(integration-guide): 创建对接集成指南
- 提供网络接入参数表(IP、端口、协议)
- 详细说明握手流程和配置下发格式
- 提供 2D/1D 温度帧解析方法和示例代码
- 说明检测结果上报和 NG 响应机制
- 解释 TEMP_REQ 按需截图工作方式
- 列出错误码表和对接故障排查步骤
This commit is contained in:
2026-03-15 19:17:41 +08:00
parent c347c988f2
commit b69717b964
19 changed files with 1818 additions and 0 deletions
@@ -0,0 +1,49 @@
## ADDED Requirements
### Requirement: DVP 硬件初始化配置描述
文档 SHALL 描述 DVP 外设的完整初始化配置,包含 GPIO 引脚映射、工作模式和信号极性。
#### Scenario: 开发者核查 DVP GPIO 引脚分配
- **WHEN** 开发者进行硬件调试时
- **THEN** 文档 SHALL 提供引脚映射表:PA4/5/6/9/10(数据线 D0-D4)、PC8/9/11(D5-D7 + PCLK)、PB3/8/9(VSYNC/HSYNC/PIXCLK),所有引脚配置为浮空输入
#### Scenario: 开发者理解 DVP 信号极性配置
- **WHEN** 开发者对接不同传感器时
- **THEN** 文档 SHALL 说明:VSYNC 高有效(RB_DVP_V_POLAR=1,对应 DIGITAL_FIELD_VALID 高电平有效帧)、HSYNC 高有效(RB_DVP_H_POLAR=0)、PCLK 上升沿采样(RB_DVP_P_POLAR=0),与 Mini212G2 手册时序图一致
### Requirement: DMA ping-pong 行缓冲机制描述
文档 SHALL 描述 DVP DMA 双缓冲的工作原理,包含缓冲切换逻辑和 IRQ 中的正确读取方式。
#### Scenario: 开发者理解 DMA 缓冲切换逻辑
- **WHEN** 开发者排查行数据乱序问题时
- **THEN** 文档 SHALL 说明:DVP 硬件在 DMA_BUF0/BUF1 间自动切换,ROW_DONE 中断触发时硬件已切换到下一个缓冲;BUF_TOG=1 表示 DMA 正在写 BUF0,此时应读 BUF1(公式:`src = (CR1 & BUF_TOG) ? DMA_LineBuf0 : DMA_LineBuf1`)
#### Scenario: 开发者理解行缓冲大小约束
- **WHEN** 开发者修改传感器分辨率时
- **THEN** 文档 SHALL 说明:DMA_LineBuf0/1 各 512 字节(256 像素 × 2 字节),COL_NUM=512,ROW_NUM=1(每行触发一次 IRQ),修改分辨率需同时更新 `BYTES_PER_LINE`、`SENSOR_WIDTH`、`SENSOR_HEIGHT`
### Requirement: DVP IRQ 帧组装逻辑描述
文档 SHALL 描述 `DVP_IRQHandler` 的完整逻辑,包含帧同步机制和 FrameBuffer 组装方式。
#### Scenario: 开发者理解帧同步锚点
- **WHEN** 开发者排查帧错位问题时
- **THEN** 文档 SHALL 说明:STR_FRM 中断(VSYNC 上升沿)将 `current_line_idx` 清零,此为帧同步唯一锚点;ROW_DONE 中断依次将行数据 memcpy 至 `FrameBuffer[current_line_idx]` 并递增
#### Scenario: 开发者理解帧完成标志
- **WHEN** 开发者需要知道何时帧数据可用时
- **THEN** 文档 SHALL 说明:当 `idx == SENSOR_HEIGHT - 1`(即第 191 行完成)时,`Frame_Ready_Flag` 置 1,`Ready_Frame_Count` 更新为当前帧号;业务任务轮询此标志,读取后将其清零
#### Scenario: 开发者理解 IRQ 使用 fast interrupt 属性的原因
- **WHEN** 开发者修改 IRQ 属性时
- **THEN** 文档 SHALL 说明:`__attribute__((interrupt("WCH-Interrupt-fast")))` 使中断处理跳过寄存器入栈,减少中断延迟,确保在下一行像素时钟到来前完成 memcpy(每行约 42.67µs @ 25Hz)
### Requirement: FrameBuffer 数据格式描述
文档 SHALL 描述 FrameBuffer 的内存布局和像素值含义。
#### Scenario: 开发者访问特定像素的温度值
- **WHEN** 开发者需要读取第 row 行第 col 列的温度时
- **THEN** 文档 SHALL 说明:`FrameBuffer` 声明为 `uint8_t[192][512]`,通过 `(uint16_t*)FrameBuffer` 访问,像素值 = `((uint16_t*)FrameBuffer)[row * 256 + col]`,单位 0.1°C/LSB(TMP 模式,需传感器预配置为 TMP)
#### Scenario: 开发者理解字节序要求
- **WHEN** 开发者移植到大端序平台时
- **THEN** 文档 SHALL 说明:CH32V307 为小端序,`uint8_t[0]` = 低字节,`uint8_t[1]` = 高字节;传感器必须配置为 CMOS8(LSB)(低字节先发),否则温度值字节反序