diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md new file mode 100644 index 0000000..3f629bb --- /dev/null +++ b/docs/architecture/ARCHITECTURE.md @@ -0,0 +1,103 @@ +# 智能挂车AI-Box软件架构设计 + +## 1. 系统概述 +基于深明奥思Fellow 1芯片(138 TOPS)的异构三核架构(MCU+SoC+F1),实现商用车AI-Box Demo。系统采用双核心管理架构:MCU负责电源管理和硬件监控,SoC负责系统调度和应用逻辑,F1负责大模型和CNN推理加速。 + +## 2. 系统分层架构 + +### 2.1 驱动层 (MCU + SoC) +- **MCU子系统**: + - 电源管理状态机(4种模式) + - SPI/UART/GPIO通信驱动(严格遵循IPCL协议) + - SoC健康状态监控(1秒周期,3秒超时复位) + - 硬件故障检测与处理 +- **SoC子系统**: + - Linux内核驱动(GPIO/I2C/SPI/UART/PCIe/V4L2) + - Fellow 1 NPU驱动(PCIe 3.0接口) + - 摄像头V4L2框架驱动 + - 温度监控与保护 + +### 2.2 框架层 (SoC + F1) +- **通信中间件**: + - MCU-SoC: SPI(≥10Mbps) + UART(≥1Mbps) + GPIO(RESET_N) + - SoC-F1: PCIe 3.0 (8 GT/s) + - IPCL协议栈实现(含CRC校验、重传机制、大文件分片) +- **推理引擎**: + - ONNX Runtime + Fellow 1专用NPU加速器 + - INT4/INT8量化支持 + - 模型分片加载与内存管理 +- **系统服务**: + - 电源模式管理(运行/休眠/低功耗/关机) + - 唤醒源管理(钥匙/远程/传感器/定时) + - 故障恢复机制(强制复位、安全模式) + +### 2.3 应用层 (SoC) +- **AI服务**: + - 大模型推理API(Qwen-7B/LLaMA-7B) + - CNN物体识别服务 + - 多模态交互接口 +- **系统服务**: + - 电源状态机协调 + - 温度适应性控制 + - 远程管理接口 +- **多模态接口**: + - OpenAI API兼容层 + - WebSocket实时通信 + - RESTful管理API + +## 3. 大模型推理引擎集成方案 + +### 3.1 模型格式与优化 +- 统一使用ONNX格式,支持Qwen-7B/LLaMA-7B转换 +- INT4/INT8量化优化,适配F1芯片NPU特性 +- 模型剪枝和蒸馏,满足50g重量限制下的内存约束 + +### 3.2 部署策略 +- 模型分片加载,避免内存溢出(支持512字节SPI包长限制) +- 共享内存池管理,减少CPU-GPU数据拷贝 +- 异步推理队列,支持多任务并发 +- 温度自适应推理频率调整(-40℃~85℃环境适应) + +## 4. 电源管理模块设计 + +### 4.1 四种工作模式(基于IPCL规范) +- **运行模式**: 全功能开启,高性能推理 (~10W, 0ms唤醒) +- **休眠模式**: SoC降频,必要传感器工作 (~2W, 100ms唤醒) +- **低功耗模式**: SoC深度睡眠,仅关键唤醒源 (~0.5W, 500ms唤醒) +- **关机模式**: SoC完全关闭,仅MCU超低功耗 (~0.1W, 2000ms唤醒) + +### 4.2 状态机与协议实现 +- MCU主导电源状态切换,SoC通过SPI发送POWER_MODE_REQ +- 严格遵循IPCL电源模式切换流程(6步握手协议) +- 唤醒源优先级管理:钥匙启动 > 远程唤醒 > 传感器触发 > 定时唤醒 +- 故障处理:SoC异常时MCU通过GPIO RESET_N强制复位(≥100ms低电平) + +## 5. 摄像头数据处理流水线 + +### 5.1 数据通路(零拷贝优化) +``` +摄像头 → V4L2驱动 → 图像预处理 → DMA传输 → F1共享内存 → CNN推理 → 结果回调 +``` + +### 5.2 性能与可靠性 +- 零拷贝DMA传输,避免CPU内存瓶颈 +- 多缓冲区流水线处理,支持实时视频流 +- 端到端延迟 < 100ms(满足商用车实时性要求) +- 极端温度环境下的稳定性保障(-40℃~85℃) + +## 6. 关键技术指标 +- **硬件平台**: Fellow 1芯片,138 TOPS算力 +- **工作温度**: -40℃ ~ 85℃ +- **尺寸重量**: 60mm × 60mm, 50g +- **推理性能**: Qwen-7B @ 138 TOPS, LLaMA-7B @ 138 TOPS +- **通信性能**: SPI ≥10Mbps, UART ≥1Mbps, PCIe 3.0 8GT/s +- **电源管理**: 四级电源模式,智能功耗控制 +- **可靠性**: 3秒SoC健康监测,强制复位保护 + +## 7. 后续工作计划 +- [ ] 详细IPCL协议栈实现(SPI/UART/GPIO驱动) +- [ ] 电源管理状态机开发与测试 +- [ ] Fellow 1 NPU驱动集成与优化 +- [ ] 大模型量化与部署验证 +- [ ] 端到端系统集成与环境测试 +- [ ] 故障恢复机制验证 \ No newline at end of file diff --git a/docs/architecture/IMPLEMENTATION_GUIDE.md b/docs/architecture/IMPLEMENTATION_GUIDE.md new file mode 100644 index 0000000..726e2a4 --- /dev/null +++ b/docs/architecture/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错误率、重传次数 +- **告警机制**: 异常情况自动上报 + +--- +**注意**: 本文档需要与《软件需求规格说明书》和《软件架构设计》配合使用,确保实现与设计一致。 \ No newline at end of file diff --git a/docs/architecture/SOFTWARE_REQUIREMENTS.md b/docs/architecture/SOFTWARE_REQUIREMENTS.md new file mode 100644 index 0000000..1853a0d --- /dev/null +++ b/docs/architecture/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软件架构设计》 \ No newline at end of file