feat: add software requirements and implementation guide for AI-Box

2026-03-04 14:34:02 +08:00 · 2026-03-04 14:34:02 +08:00 · 421cf09e44
parent 1b66c9d060
commit 421cf09e44
2 changed files with 464 additions and 0 deletions
--- a/IMPLEMENTATION_GUIDE.md
+++ b/IMPLEMENTATION_GUIDE.md
@ -0,0 +1,306 @@
+# AI-Box软件实现指南
+
+## 1. 开发环境搭建
+
+### 1.1 系统要求
+- **主机系统**: Ubuntu 20.04 LTS 或更高版本
+- **交叉编译工具链**: aarch64-linux-gnu-gcc 9.3.0 或更高
+- **存储空间**: 至少20GB可用空间（包含模型文件）
+
+### 1.2 依赖安装
+```bash
+# 基础开发工具
+sudo apt update
+sudo apt install -y build-essential cmake git wget curl
+
+# 交叉编译工具链
+sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
+
+# Python环境（用于模型转换和测试）
+sudo apt install -y python3 python3-pip python3-venv
+python3 -m venv venv
+source venv/bin/activate
+pip install onnx onnxruntime numpy torch torchvision
+
+# Fellow 1 NPU SDK（需从厂商获取）
+# 解压到 ./fellow1-sdk 目录
+```
+
+### 1.3 代码仓库配置
+```bash
+# 克隆项目仓库
+git clone http://zxu:zxu123456@47.253.94.217:3000/zxu/its-gen1.git
+cd its-gen1
+
+# 配置Git用户信息
+git config user.name "Your Name"
+git config user.email "your.email@company.com"
+
+# 创建开发分支
+git checkout -b feature/your-feature-name
+```
+
+## 2. MCU软件开发指南
+
+### 2.1 项目结构
+```
+mcu/
+├── src/
+│   ├── main.c                 # 主函数入口
+│   ├── power_manager.c        # 电源管理模块
+│   ├── spi_driver.c           # SPI驱动实现
+│   ├── uart_driver.c          # UART驱动实现  
+│   ├── gpio_driver.c          # GPIO驱动实现
+│   └── ipcl_protocol.c        # IPCL协议栈
+├── include/
+│   ├── power_manager.h
+│   ├── spi_driver.h
+│   ├── uart_driver.h
+│   ├── gpio_driver.h
+│   └── ipcl_protocol.h
+├── test/
+│   └── mcu_unit_tests.c       # 单元测试
+└── CMakeLists.txt             # 构建配置
+```
+
+### 2.2 关键接口实现
+
+#### 2.2.1 SPI驱动实现要点
+```c
+// spi_driver.h
+#define SPI_BUFFER_SIZE 512
+#define SPI_SYNC_HEADER 0xAA55
+
+typedef struct {
+    uint16_t sync_header;      // 同步头 0xAA55
+    uint8_t command_type;      // 命令类型
+    uint16_t data_length;      // 数据长度 (0-512)
+    uint8_t data[SPI_BUFFER_SIZE]; // 数据区
+    uint16_t crc;              // CRC校验
+} spi_packet_t;
+
+// 关键函数
+int spi_init(uint32_t baudrate);           // 初始化SPI (≥10Mbps)
+int spi_send_packet(spi_packet_t* packet); // 发送数据包
+int spi_receive_packet(spi_packet_t* packet); // 接收数据包
+uint16_t calculate_crc(uint8_t* data, size_t len); // CRC计算
+```
+
+#### 2.2.2 电源管理状态机
+```c
+// power_manager.h
+typedef enum {
+    POWER_MODE_RUNNING,      // 运行模式
+    POWER_MODE_SLEEPING,     // 休眠模式  
+    POWER_MODE_LOW_POWER,    // 低功耗模式
+    POWER_MODE_SHUTDOWN      // 关机模式
+} power_mode_t;
+
+// 状态机函数
+int power_manager_init(void);
+int set_power_mode(power_mode_t mode);
+power_mode_t get_current_power_mode(void);
+int handle_wakeup_source(wakeup_source_t source);
+```
+
+#### 2.2.3 SoC健康监测
+```c
+// uart_driver.h  
+#define UART_HEALTH_REPORT_PERIOD_MS 1000
+#define UART_HEALTH_TIMEOUT_MS 3000
+
+typedef struct {
+    uint8_t sync_header;       // 0xAA
+    uint8_t status_type;       // CPU/MEM/PERIPH/SYSTEM
+    uint32_t status_data;      // 状态数据
+    uint8_t crc;               // CRC校验
+} uart_health_packet_t;
+
+// 健康监测函数
+int uart_health_monitor_init(void);
+int start_health_monitoring(void);
+int stop_health_monitoring(void);
+void handle_soc_timeout(void); // SoC超时处理（强制复位）
+```
+
+### 2.3 编译与调试
+```bash
+# MCU编译
+cd mcu
+mkdir build && cd build
+cmake .. -DCMAKE_TOOLCHAIN_FILE=../toolchain-arm-none-eabi.cmake
+make
+
+# 调试命令（使用JTAG/SWD）
+arm-none-eabi-gdb mcu_firmware.elf
+```
+
+## 3. SoC软件开发指南
+
+### 3.1 项目结构
+```
+soc/
+├── kernel/
+│   ├── drivers/               # 内核驱动
+│   │   ├── fellow1_npu.c      # F1 NPU驱动
+│   │   ├── camera_v4l2.c      # 摄像头V4L2驱动
+│   │   └── ipcl_interface.c   # IPCL接口驱动
+│   └── config/                # 内核配置
+├── userspace/
+│   ├── system_service/        # 系统服务
+│   ├── ai_service/            # AI服务
+│   ├── communication/         # 通信模块
+│   └── utils/                 # 工具库
+├── models/                    # 模型文件
+│   ├── qwen-7b.onnx
+│   └── llama-7b.onnx
+└── CMakeLists.txt
+```
+
+### 3.2 Linux内核配置要点
+```bash
+# 必需的内核配置选项
+CONFIG_GPIO_SYSFS=y
+CONFIG_SPI_MASTER=y  
+CONFIG_SPI_SPIDEV=y
+CONFIG_SERIAL_8250=y
+CONFIG_V4L_PLATFORM_DRIVERS=y
+CONFIG_PCIE_DW=y
+CONFIG_THERMAL=y
+```
+
+### 3.3 Fellow 1 NPU驱动开发
+```c
+// fellow1_npu.h
+struct fellow1_npu_device {
+    void __iomem *regs;        // 寄存器映射
+    struct pci_dev *pdev;      // PCIe设备
+    dma_addr_t shared_mem_dma; // 共享内存DMA地址
+    void *shared_mem_virt;     // 共享内存虚拟地址
+};
+
+// 关键API
+int fellow1_npu_init(struct pci_dev *pdev);
+int fellow1_npu_submit_inference(void *model_data, size_t model_size,
+                                void *input_data, size_t input_size,
+                                void *output_buffer, size_t output_size);
+int fellow1_npu_wait_completion(void);
+```
+
+### 3.4 AI服务实现
+```python
+# ai_service/model_manager.py
+class ModelManager:
+    def __init__(self):
+        self.loaded_models = {}
+        self.shared_memory_pool = SharedMemoryPool()
+    
+    def load_model(self, model_path, quantization='INT8'):
+        """模型分片加载，避免内存溢出"""
+        model_chunks = self._split_model(model_path)
+        for chunk in model_chunks:
+            self._load_chunk_to_npu(chunk, quantization)
+        return model_id
+    
+    def inference_async(self, model_id, input_data, callback):
+        """异步推理接口"""
+        task_id = self._submit_to_npu(model_id, input_data)
+        self._register_callback(task_id, callback)
+        return task_id
+```
+
+## 4. F1 NPU软件开发指南
+
+### 4.1 推理运行时架构
+```
+f1_runtime/
+├── scheduler/                 # 任务调度器
+├── memory_manager/            # 内存管理器  
+├── kernel_executor/           # 内核执行器
+├── quantization/              # 量化模块
+└── api/                       # 对外API
+```
+
+### 4.2 关键优化技术
+- **零拷贝传输**: 使用PCIe ATS (Address Translation Services)
+- **模型分片**: 将大模型分割为适合NPU缓存的小块
+- **量化感知训练**: INT4/INT8量化保持精度
+- **温度自适应**: 根据芯片温度动态调整频率
+
+## 5. 集成与测试
+
+### 5.1 构建脚本
+```bash
+#!/bin/bash
+# build_all.sh
+set -e
+
+echo "Building MCU firmware..."
+cd mcu && mkdir -p build && cd build
+cmake .. && make
+cd ../..
+
+echo "Building SoC kernel modules..."
+cd soc/kernel && make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-
+
+echo "Building userspace applications..."
+cd ../userspace && cmake . && make
+
+echo "Build completed successfully!"
+```
+
+### 5.2 测试策略
+- **单元测试**: 每个模块独立测试
+- **集成测试**: MCU-SoC-F1三端联调
+- **性能测试**: 推理延迟、功耗、唤醒时间
+- **可靠性测试**: 极端温度、电源波动、故障恢复
+
+### 5.3 调试技巧
+- **日志级别**: DEBUG/INFO/WARNING/ERROR
+- **串口调试**: MCU和SoC都输出调试信息
+- **性能分析**: 使用perf和ftrace分析瓶颈
+- **内存检查**: Valgrind检测内存泄漏
+
+## 6. 版本管理规范
+
+### 6.1 Git提交规范
+```
+feat: 添加新功能
+fix: 修复bug
+docs: 文档更新
+style: 代码格式调整
+refactor: 重构代码
+test: 添加测试
+chore: 构建或辅助工具变更
+```
+
+### 6.2 分支策略
+- **main**: 稳定版本，可发布
+- **develop**: 开发主干，集成各功能
+- **feature/***: 功能开发分支
+- **hotfix/***: 紧急修复分支
+
+### 6.3 代码审查清单
+- [ ] 代码符合编码规范
+- [ ] 单元测试覆盖率 ≥ 80%
+- [ ] 内存安全（无泄漏、越界）
+- [ ] 异常处理完整
+- [ ] 性能满足需求
+- [ ] 文档同步更新
+
+## 7. 部署与维护
+
+### 7.1 固件更新流程
+1. 构建完整固件包
+2. 通过远程管理接口推送
+3. MCU验证固件完整性
+4. 安全回滚机制（失败时恢复旧版本）
+
+### 7.2 远程监控
+- **健康状态**: CPU/内存/温度/电源状态
+- **AI性能**: 推理QPS、延迟、成功率
+- **通信质量**: SPI/UART错误率、重传次数
+- **告警机制**: 异常情况自动上报
+
+---
+**注意**: 本文档需要与《软件需求规格说明书》和《软件架构设计》配合使用，确保实现与设计一致。
--- a/SOFTWARE_REQUIREMENTS.md
+++ b/SOFTWARE_REQUIREMENTS.md
@ -0,0 +1,158 @@
+# 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软件架构设计》