# dvp-module-design Specification

## Purpose
TBD - created by archiving change software-design-doc. Update Purpose after archive.
## 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)（低字节先发），否则温度值字节反序