its-gen1/SOFTWARE_REQUIREMENTS.md

# AI-Box软件需求规格说明书

## 1. 文档概述
本文档基于硬件团队提供的《AI-Box智能终端IPCL设计文档》和《AI-Box智能终端电源设计文档》，详细定义软件系统的功能需求、性能需求和接口需求，为后续编码实现提供明确指导。

## 2. 系统架构约束

### 2.1 硬件平台约束
- **主芯片**: 深明奥思Fellow 1 (138 TOPS)
- **架构**: 异构三核 (MCU + SoC + F1)
- **工作温度**: -40℃ ~ 85℃
- **尺寸重量**: 60mm × 60mm, 50g
- **电源**: 12V/24V车载电源

### 2.2 通信接口约束
- **MCU-SoC**: SPI(≥10Mbps) + UART(≥1Mbps) + GPIO(RESET_N)
- **SoC-F1**: PCIe 3.0 (8 GT/s)
- **协议标准**: 严格遵循IPCL通信协议规范

## 3. 功能需求

### 3.1 MCU软件功能需求

#### 3.1.1 电源管理模块
- **FR-MCU-001**: 实现四级电源模式状态机（运行/休眠/低功耗/关机）
- **FR-MCU-002**: 支持SPI POWER_MODE_REQ/ACK协议交互
- **FR-MCU-003**: 实现唤醒源优先级管理（钥匙>远程>传感器>定时）
- **FR-MCU-004**: 监控电池电压，低于阈值时自动进入低功耗模式

#### 3.1.2 通信管理模块  
- **FR-MCU-005**: 实现SPI驱动，支持10Mbps速率，512字节包长
- **FR-MCU-006**: 实现UART驱动，支持1Mbps速率，健康状态监测
- **FR-MCU-007**: 实现GPIO RESET_N控制（低电平有效，≥100ms）
- **FR-MCU-008**: 实现IPCL协议栈（CRC校验、重传、大文件分片）

#### 3.1.3 故障处理模块
- **FR-MCU-009**: SoC健康监测（1秒周期，3秒超时强制复位）
- **FR-MCU-010**: 电源异常检测和安全模式切换
- **FR-MCU-011**: 通信故障恢复（SPI/UART双通道失效时GPIO复位）

### 3.2 SoC软件功能需求

#### 3.2.1 系统服务模块
- **FR-SoC-001**: Linux内核配置（支持GPIO/I2C/SPI/UART/PCIe/V4L2）
- **FR-SoC-002**: Fellow 1 NPU驱动开发（PCIe 3.0接口）
- **FR-SoC-003**: 温度监控与自适应频率调整
- **FR-SoC-004**: 外设电源管理（动态开关非必要外设）

#### 3.2.2 AI推理模块
- **FR-SoC-005**: ONNX Runtime集成，支持Qwen-7B/LLaMA-7B
- **FR-SoC-006**: INT4/INT8量化模型部署
- **FR-SoC-007**: 模型分片加载，内存占用优化
- **FR-SoC-008**: 异步推理队列，多任务并发支持

#### 3.2.3 通信与监控模块
- **FR-SoC-009**: SPI客户端实现，支持POWER_MODE_REQ发送
- **FR-SoC-010**: UART健康状态报告（CPU/MEM/PERIPH/SYSTEM状态）
- **FR-SoC-011**: GPIO RESET_N中断处理
- **FR-SoC-012**: IPCL协议客户端实现

### 3.3 F1软件功能需求

#### 3.3.1 推理引擎模块
- **FR-F1-001**: Fellow 1 NPU专用推理运行时
- **FR-F1-002**: 多模型并发调度器
- **FR-F1-003**: 共享内存管理（SoC-F1零拷贝传输）
- **FR-F1-004**: 温度自适应推理频率控制

## 4. 性能需求

### 4.1 通信性能
- **PR-COMM-001**: SPI通信延迟 ≤ 1ms (512字节包)
- **PR-COMM-002**: UART健康报告周期 = 1s ± 10ms
- **PR-COMM-003**: PCIe 3.0带宽利用率 ≥ 80%

### 4.2 推理性能  
- **PR-AI-001**: Qwen-7B推理延迟 ≤ 500ms (输入长度512 tokens)
- **PR-AI-002**: LLaMA-7B推理延迟 ≤ 600ms (输入长度512 tokens)
- **PR-AI-003**: CNN物体识别延迟 ≤ 100ms (1080p图像)

### 4.3 电源性能
- **PR-POWER-001**: 运行模式功耗 ≤ 10W
- **PR-POWER-002**: 休眠模式功耗 ≤ 2W  
- **PR-POWER-003**: 低功耗模式功耗 ≤ 0.5W
- **PR-POWER-004**: 关机模式功耗 ≤ 0.1W

### 4.4 唤醒性能
- **PR-WAKE-001**: 休眠→运行唤醒时间 ≤ 100ms
- **PR-WAKE-002**: 低功耗→运行唤醒时间 ≤ 500ms
- **PR-WAKE-003**: 关机→运行唤醒时间 ≤ 2000ms

## 5. 接口需求

### 5.1 MCU-SoC接口
- **IR-MCU-SoC-001**: SPI接口遵循IPCL数据包格式（同步头0xAA55 + CRC）
- **IR-MCU-SoC-002**: UART接口遵循健康状态报告格式（同步头0xAA + CRC）
- **IR-MCU-SoC-003**: GPIO接口RESET_N低电平有效，持续≥100ms

### 5.2 SoC-F1接口  
- **IR-SoC-F1-001**: PCIe 3.0 x4接口，支持DMA传输
- **IR-SoC-F1-002**: 共享内存池接口，支持零拷贝数据传输
- **IR-SoC-F1-003**: 推理API接口，支持异步回调

### 5.3 应用层接口
- **IR-APP-001**: OpenAI API兼容接口（/v1/chat/completions）
- **IR-APP-002**: WebSocket实时通信接口
- **IR-APP-003**: RESTful设备管理接口（电源控制、状态查询）

## 6. 可靠性需求

### 6.1 故障恢复
- **RR-001**: SoC异常时，MCU必须在3秒内完成强制复位
- **RR-002**: 电源波动时，系统必须保持稳定运行或安全关机
- **RR-003**: 通信中断时，必须有备用恢复机制

### 6.2 环境适应性
- **RR-004**: -40℃~85℃温度范围内正常工作
- **RR-005**: 12V/24V电源电压波动范围内正常工作
- **RR-006**: 车载振动环境下通信可靠性 ≥ 99.9%

## 7. 开发与测试需求

### 7.1 开发环境
- **DR-001**: Linux交叉编译环境（ARM64架构）
- **DR-002**: Fellow 1 NPU SDK集成
- **DR-003**: Gitea版本控制（http://47.253.94.217:3000/zxu/its-gen1）

### 7.2 测试要求
- **TR-001**: 电源模式切换功能测试
- **TR-002**: IPCL通信协议一致性测试  
- **TR-003**: 大模型推理性能基准测试
- **TR-004**: 极端温度环境可靠性测试
- **TR-005**: 故障恢复机制验证测试

## 8. 验收标准

### 8.1 功能验收
- 所有功能需求项（FR-*）必须100%实现并通过测试

### 8.2 性能验收  
- 所有性能需求项（PR-*）必须满足指标要求

### 8.3 可靠性验收
- 故障恢复时间必须满足RR-001要求
- 环境适应性必须通过RR-004~RR-006测试

## 9. 附录

### 9.1 术语表
- **MCU**: Micro Controller Unit，微控制器单元
- **SoC**: System on Chip，系统级芯片  
- **F1**: Fellow 1 NPU，深明奥思大模型推理芯片
- **IPCL**: Inter-Processor Communication Layer，处理器间通信层

### 9.2 参考文档
- 《AI-Box智能终端IPCL设计文档》
- 《AI-Box智能终端电源设计文档》
- 《智能挂车AI-Box软件架构设计》