its-gen1/docs/architecture/IMPLEMENTATION_GUIDE.md

# 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错误率、重传次数
- **告警机制**: 异常情况自动上报

---
**注意**: 本文档需要与《软件需求规格说明书》和《软件架构设计》配合使用，确保实现与设计一致。