---

基于 Zynq 芯片的嵌入式软件设计规范

---

1. 总体架构设计

1.1 系统架构

+---------------------------+     +---------------------------+
|        应用层              |     |        PL (FPGA)          |
|  - 用户逻辑/算法           |<--->|  - 硬件加速模块           |
|  - 通信协议栈              |     |  - 自定义IP核            |
+---------------------------+     +---------------------------+
|        中间件层            |     |        PS (ARM Cortex-A9) |
|  - 操作系统 (Linux/FreeRTOS)|     |  - 双核CPU (Cortex-A9)    |
|  - 驱动框架 (UIO/PL侧驱动) |<--->|  - 内存管理 (DDR/OCM)     |
+---------------------------+     +---------------------------+
|        硬件抽象层 (HAL)     |     |        外设接口           |
|  - 外设驱动 (GPIO/UART/SPI)|     |  - AXI总线交互            |
+---------------------------+     +---------------------------+

1.2 设计原则

• 模块化：功能模块解耦，通过标准接口通信（如 AXI、Mailbox、共享内存）。
• 可扩展性：预留 20% 的 PL 资源与 30% 的代码空间。
• 实时性：硬实时任务部署在 FreeRTOS（裸机或协处理器），软实时任务部署在 Linux。
• 安全性：
  • PS 端启用 MMU，隔离用户态与内核态。
  • PL 端关键逻辑进行三模冗余（TMR）设计。

---

2. 开发环境与工具链

2.1 工具配置

工具	用途	版本要求
Vivado	FPGA逻辑设计、IP核集成、比特流生成	≥ 2022.1
Vitis	PS端软件开发（裸机/Linux）	≥ 2022.1
PetaLinux	Linux镜像构建与定制	≥ 2022.1
Git	版本控制	≥ 2.30
Doxygen	代码文档生成	≥ 1.9.5

2.2 代码管理

• 分支策略：
  • main：稳定版本（仅允许合并已验证的代码）。
  • dev：开发分支（每日构建验证）。
  • feature/*：功能开发分支（按模块命名）。
• 提交规范：

  [类型] 模块名: 描述（如 [FIX] PL-DMA: 修复传输超时问题）
  类型标识：
    - [FEAT] 新增功能
    - [FIX] 问题修复
    - [DOC] 文档更新
    - [REFACTOR] 重构代码
  

---

3. PL (FPGA) 设计规范

3.1 硬件逻辑设计

• IP核复用：优先使用 Xilinx 官方 IP（如 AXI DMA、AXI GPIO）。
• 时钟管理：
  • 全局时钟网络使用 BUFG，局部时钟使用 BUFR。
  • 跨时钟域信号必须经过双触发器同步。
• 资源分配：
  • 保留 10% 的 LUT 和 FF 资源用于后期调试。
  • Block RAM 使用分布式模式以降低功耗。

3.2 接口定义

• AXI 总线：
  • 高性能数据传输使用 AXI4-Stream（如视频流）。
  • 控制寄存器使用 AXI4-Lite（位宽 32-bit）。
• 自定义接口：
  • 定义明确的时序图（如握手信号 valid/ready）。
  • 提供 Verilog 仿真模型（TestBench）。

3.3 DMA 使用

• 配置要求：
  • 数据对齐：64 字节对齐（匹配 Cache 行）。
  • 突发传输：长度不超过 256（AXI 限制）。
• 错误处理：
  • 启用 DMA 中断，超时时间 ≤ 50ms。

---

4. PS (ARM) 软件开发规范

4.1 操作系统选择

场景	方案
复杂UI、网络服务	Linux (PetaLinux) + 多线程
硬实时控制（μs级响应）	FreeRTOS（裸机） + 中断驱动
混合系统	AMP 模式（Linux + FreeRTOS 双核独立运行）

4.2 驱动开发

• Linux 驱动：
  • 用户态驱动使用 UIO（Userspace I/O）。
  • 内核态驱动需兼容 Device Tree 配置。
• 裸机驱动：
  • 寄存器操作必须封装为宏（示例）：

    #define GPIO_SET(base, pin)  (*(volatile uint32_t*)(base + 0x08) |= (1 << pin))
    

4.3 多核通信

• 共享内存：
  • 定义结构体对齐到 64 字节（避免 Cache 一致性冲突）。
  • 使用原子操作（如 __atomic_store_n）。
• IPC 机制：
  • Linux ↔ FreeRTOS：通过 OpenAMP 框架（RPMSG）。
  • FreeRTOS 任务间：使用队列（Queue）或信号量（Semaphore）。

---

5. 软件分层设计

5.1 驱动层（HAL）

• 职责：
  • 封装硬件操作（如 int gpio_read(uint8_t pin)）。
  • 提供统一的跨平台接口（Linux/裸机兼容）。
• 规范：
  • 禁止在驱动层使用 printf，改用日志回调函数。

5.2 中间件层

• 功能模块：
  • 通信协议栈（TCP/IP、CANopen）。
  • 文件系统（FAT32、RAMFS）。
  • 安全库（AES-256 加密、SHA-1 校验）。
• API 设计：
  • 异步接口必须支持超时（默认 1s）。

5.3 应用层

• 任务划分：
  • 周期任务（如传感器采集）：使用定时器触发。
  • 事件任务（如网络报文）：使用中断 + 信号量唤醒。
• 实时性保障：
  • Linux 端使用 SCHED_FIFO 优先级策略。
  • FreeRTOS 任务优先级按下表定义：

任务类型	优先级范围	示例
紧急硬件中断服务	31-28	看门狗喂狗、电源故障处理
实时控制任务	27-20	电机PID控制
通信任务	19-10	TCP Socket监听
后台任务	9-0	日志上传、状态显示

---

6. 安全与可靠性

6.1 内存管理

• Linux 端：
  • 用户态程序启用 ASLR（地址空间布局随机化）。
  • 内核模块禁用内存动态分配（预分配池）。
• FreeRTOS 端：
  • 使用静态内存分配（pvPortMallocStatic）。
  • 堆栈溢出检测：启用 configCHECK_FOR_STACK_OVERFLOW=2。

6.2 错误处理

• 分级策略：

  等级	处理方式	示例
  CRITICAL	系统复位	DDR 校验错误
  ERROR	记录日志并降级运行	传感器通信超时
  WARNING	记录日志并继续运行	缓存未命中

6.3 看门狗配置

• 硬件看门狗：
  • 超时时间 2s，喂狗间隔 ≤ 1.5s。
  • 分级喂狗机制（任务监控看门狗 + 独立硬件看门狗）。

---

7. 测试与验证

7.1 单元测试

• PL 逻辑：
  • 覆盖率 ≥ 95%（通过 Vivado Simulator）。
  • 关键路径时序分析（Slack ≥ 0.2ns）。
• PS 代码：
  • 使用 Ceedling 框架（示例）：

    void test_gpio_read(void) {
      gpio_init();
      TEST_ASSERT_EQUAL(0, gpio_read(PIN_5));
    }
    

7.2 集成测试

• 硬件在环 (HIL)：
  • 使用 JTAG 强制注入故障（如 DDR 写错误）。
  • 验证系统恢复机制。
• 性能测试：
  • AXI 总线吞吐率 ≥ 800MB/s（理论峰值 1200MB/s）。

7.3 环境测试

测试项	条件	标准
高温运行	85°C, 24h	无内存泄漏或死锁
电压波动	0.9V-1.1V (标称1.0V)	功能正常，误差 < 1%
振动测试	5Hz-500Hz, 5Grms	无硬件接触不良

---

8. 文档要求

8.1 设计文档

• PL 部分：
  • IP核数据手册（寄存器映射、时序图）。
  • 资源占用报告（Utilization Report）。
• PS 部分：
  • 软件架构图（PlantUML 或 Draw.io 绘制）。
  • API 参考手册（Doxygen 生成）。

8.2 用户手册

• 快速入门：
  • 比特流加载步骤（SD卡/UART引导）。
  • 关键命令示例（如 fpgautil -b design.bit）。
• 故障排查：
  • LED 状态编码表（如 快闪3次=内存错误）。

---

9. 版本发布

9.1 版本号规则

• 语义化版本：主版本.次版本.修订号（如 2.1.3）。
  • 主版本：架构重大变更。
  • 次版本：功能新增。
  • 修订号：Bug 修复。

9.2 发布包内容

/固件
  ├── bitstream/       # PL比特流文件
  ├── boot/            # FSBL + U-Boot
  ├── linux/           # 内核镜像 + 设备树
  └── app/             # 可执行文件（含版本签名）
/文档
  ├── 设计规范.pdf
  └── API参考手册.chm

---

附：代码风格示例（C语言）

/* 函数命名：模块_动作_目标（全小写 + 下划线） */
void gpio_set_level(uint8_t pin, bool level) {
    // 注释对齐，长度不超过80字符
    if (level) {
        GPIO_REGISTER |= (1 << pin);  // 寄存器操作使用宏封装
    } else {
        GPIO_REGISTER &= ~(1 << pin);
    }
}

// 结构体命名：大驼峰 + _t 后缀
typedef struct {
    uint32_t id;
    float    sensor_data;
} SensorPacket_t;

---

本规范可根据项目需求裁剪调整，建议每半年进行一次评审更新。