Getting Started and Basic Vitis 模块深度解析

概述：Vitis 统一平台的入门阶梯

Getting Started and Basic Vitis 是 AMD Versal 自适应计算生态系统的门户模块——它不仅仅是"Hello World"，而是一套精心设计的渐进式学习路径，让开发者从熟悉的 C/C++ 世界平滑过渡到异构加速计算领域。

想象你是一位传统嵌入式开发者，熟悉在 CPU 上编写代码，但面对 FPGA 和 AI 引擎时感到迷茫。这个模块就像一座桥梁：它展示了如何将 C++ 代码通过 Vitis HLS 转换为硬件逻辑，如何将 AI 引擎（AIE）内核与可编程逻辑（PL）协同工作，以及如何利用预构建的 Vitis 库加速开发。

模块定位与核心价值

┌─────────────────────────────────────────────────────────────────────────────┐
│                    Getting Started and Basic Vitis                          │
│                         「入门阶梯，由浅入深」                               │
├─────────────────────────────────────────────────────────────────────────────┤
│  子模块                    │  核心价值                                        │
├───────────────────────────┼─────────────────────────────────────────────────┤
│  Vitis (完整系统流)        │  展示 HLS 数据搬运核 + AIE 的完整异构集成         │
│  Vitis_HLS (独立 HLS 流)  │  从 C/C++ 到 RTL 的 HLS 设计入门                 │
│  Vitis_Libraries (库流)   │  利用预构建 Vitis 库（FFT）加速开发               │
│  Vitis_Platform (平台流)  │  基础平台创建概念                                │
└─────────────────────────────────────────────────────────────────────────────┘

架构全景：四重奏设计空间

这个模块采用四重奏架构，每个子模块展示 Vitis 统一平台的一个关键维度：

核心子模块详解

1. Vitis - 完整系统集成流

这是模块中最复杂的子系统，展示了如何将三个异构计算单元（HLS PL 核、AI 引擎、主机 CPU）编织成一个完整的工作流。

系统架构：数据搬运的接力赛

想象一个数据搬运的接力赛：

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  DDR Memory │     │   mm2s      │     │  AIE Graph  │     │    s2mm     │
│   (输入)     │ ──▶ │  (PL HLS)   │ ──▶ │(Matrix Mul)│ ──▶ │  (PL HLS)   │
│             │     │  内存到流    │     │  矩阵运算    │     │  流到内存    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                 │
                                                                 ▼
                                                          ┌─────────────┐
                                                          │  DDR Memory │
                                                          │   (输出)     │
                                                          └─────────────┘

system.cfg 的核心作用：就像机场的空管系统，它定义了数据流的航线：

# 声明 HLS 核的实例化
nk = mm2s:2:mm2s_1,mm2s_2    # 2 个 mm2s 实例
nk = s2mm:1:s2mm             # 1 个 s2mm 实例

# 定义 AXI Stream 连接（PL 到 AIE 的桥梁）
stream_connect = mm2s_1.s:ai_engine_0.DataIn1
stream_connect = mm2s_2.s:ai_engine_0.DataIn2
stream_connect = ai_engine_0.DataOut1:s2mm.s

HLS 数据搬运核的精妙设计

mm2s (Memory to Stream) 和 s2mm (Stream to Memory) 是 PL 侧的"数据搬运工"。它们的设计体现了硬件接口设计的核心原则：

// mm2s.cpp - 将 DDR 数据读取并转换为 AXI Stream
void mm2s(ap_int<32>* mem, hls::stream<ap_axis<32, 0, 0, 0>> &s, int size) {
    #pragma HLS INTERFACE m_axi port=mem offset=slave bundle=gmem  // AXI4-Full 接口
    #pragma HLS interface axis port=s                              // AXI4-Stream 接口
    #pragma HLS INTERFACE s_axilite port=mem bundle=control          // 控制寄存器
    #pragma HLS INTERFACE s_axilite port=size bundle=control
    #pragma HLS interface s_axilite port=return bundle=control
    
    for(int i = 0; i < size; i++) {
        #pragma HLS PIPELINE II=1  // 关键：每个周期输出一个数据
        ap_axis<32, 0, 0, 0> x;
        x.data = mem[i];
        s.write(x);
    }
}

设计要点解析：

1. 三种 AXI 接口类型的协同：

   • m_axi (AXI4-Full): 用于 DDR 内存的高带宽突发传输
   • axis (AXI4-Stream): 用于与 AIE 的流式数据交换
   • s_axilite: 用于主机软件配置（基地址、数据量等）

2. PIPELINE II=1 的关键意义：

   • Initiation Interval (II) = 1 意味着每个时钟周期可以启动一次新的迭代
   • 这是流式处理的黄金标准：数据像水流一样连续流动，没有气泡
   • 如果没有这个 pragma，HLS 可能生成一个状态机，每个数据需要多个周期

AIE 计算图的矩阵乘法

AIE 侧实现了矩阵乘法这一经典计算密集型任务，展示了 AI 引擎的核心价值：

// graph.h - AIE 计算图定义
class Simple_Graph : public adf::graph {
    kernel k1;
    input_plio in1, in2;    // PL 输入端口
    output_plio out_put;    // PL 输出端口

    Simple_Graph() {
        // 创建 MatMul 内核，设置运行时资源占用率 90%
        k1 = kernel::create(MatMul);
        source(k1) = "./MatMul.cpp";
        runtime<ratio>(k1) = 0.9;

        // 创建 PLIO 端口，32-bit 宽度，关联数据文件
        in1 = adf::input_plio::create("DataIn1", adf::plio_32_bits, "../data_srcs/MatrixA.txt");
        in2 = adf::input_plio::create("DataIn2", adf::plio_32_bits, "../data_srcs/MatrixB.txt");
        out_put = adf::output_plio::create("DataOut1", adf::plio_32_bits, "../data_srcs/output.txt");

        // 连接数据流：PLIO -> Kernel -> PLIO
        connect(in1.out[0], k1.in[0]);
        connect(in2.out[0], k1.in[1]);
        connect(k1.out[0], out_put.in[0]);

        // 设置缓冲区维度（以 int32 为单位）
        dimensions(k1.in[0]) = {16};  // 4x4 矩阵 = 16 元素
        dimensions(k1.in[1]) = {4};   // 4x1 矩阵 = 4 元素
        dimensions(k1.out[0]) = {4};  // 4x1 结果 = 4 元素
    }
};

关键概念解析：

1. Graph 编程模型：

   • AIE 使用数据流图而非传统的指令流编程
   • 节点（kernel）之间的边是** FIFO 缓冲区**，自动处理生产者-消费者同步
   • 这与 HLS 的 DATAFLOW 有相似之处，但 AIE 有专用硬件支持

2. runtime<ratio>(k1) = 0.9：

   • 这个设置告诉编译器：该内核占用 AI 引擎 tile 的 90% 计算资源
   • 剩余 10% 留给数据移动和同步开销
   • 如果设置为 1.0，可能导致时序违例，因为没有任何余量处理数据 I/O

3. __restrict 关键字：

   • 在 MatMul 函数中，输入输出缓冲区标记为 __restrict
   • 这是向 AIE 编译器保证：这些指针不会别名（指向重叠内存区域）
   • 没有此保证，编译器必须生成保守代码，可能牺牲并行性

2. Vitis_HLS - 独立 HLS 组件流

如果说 Vitis 子模块展示了系统集成，Vitis_HLS 则专注于内核开发——它是深入 HLS 方法论的理想起点。

DCT（离散余弦变换）示例

该子模块使用DCT作为教学载体，因为它既有实际价值（图像/视频压缩的核心算法），又足够简单便于理解：

# hls_config.cfg - HLS 组件配置
part=xcvu9p-flga2104-2-i

[hls]
flow_target=vitis           # 目标：Vitis 加速流
package.output.format=xo    # 输出：Vitis 内核对象 (.xo)
package.output.syn=false    # 不自动综合（手动控制）
syn.top=dct                 # 顶层函数：dct
syn.file=../../src/dct.cpp
tb.file=../../src/dct_test.cpp
tb.file=../../src/in.dat
tb.file=../../src/out.golden.dat
clock=8ns                   # 目标时钟：8ns (125MHz)
clock_uncertainty=12%       # 时钟不确定性余量
csim.code_analyzer=0
csim.clean=true

关键配置解析：

1. flow_target=vitis vs flow_target=vivado：

   • vitis：生成 .xo 文件，用于 Vitis 异构系统集成（与 AIE、主机代码协同）
   • vivado：生成 Vivado IP，用于纯 RTL 设计流程
   • 这是两个截然不同的生态位，选择错误会导致集成困难

2. clock=8ns 与 clock_uncertainty=12%：

   • 目标时钟周期为 8ns，但 HLS 工具会预留 12% 的余量（实际目标约为 7ns）
   • 这是为了容纳布局布线后的时钟偏差和工艺变化
   • 如果 HLS 报告的时序余量为负，即使综合成功，硬件也可能失败

3. Vitis_Libraries - 库集成流

该子模块回答了一个关键问题："我不想从零开始，如何用现成的优化库？"

FFT 库集成流程

# project.cfg - Vitis Libraries 项目配置
part=xcvu9p-flgc2104-2-e

[hls]
clock=10ns
flow_target=vivado               # 输出 Vivado IP
package.output.format=ip_catalog # IP 目录格式
syn.file=./ref_files/top_module.cpp
syn.file_cflags=./ref_files/top_module.cpp,-I ./ref_files/fixed  # 库头文件路径
tb.file=./ref_files/main.cpp
tb.file_cflags=./ref_files/main.cpp,-I ./ref_files/fixed
syn.top=fft_top
package.output.syn=0

关键差异点：

1. -I ./ref_files/fixed：

   • 这是指向 Vitis Libraries DSP 库的头文件路径
   • fixed 目录包含定点数 FFT 实现的头文件
   • 实际路径可能类似于 Vitis_Libraries/dsp/L1/include/hw/vitis_fft/fixed

2. 库使用模式：

   • L1 库提供头文件形式的硬件模块（类似于 C++ 模板库）
   • 通过 #include 引入，HLS 工具在综合时实例化
   • 这与传统软件库（链接预编译二进制）截然不同

设计权衡与决策分析

权衡 1：HLS vs 手工 RTL

决策理由：作为"入门"模块，选择 HLS 大幅降低门槛，让软件开发者能快速产出可工作的硬件加速器。

权衡 2：Vitis 流 vs Vivado 流

┌─────────────────────────────────────────────────────────────────┐
│                    输出格式选择                                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   .xo (Vitis Kernel)              vs         .zip (Vivado IP)   │
│   ───────────────────                        ────────────────   │
│                                                                 │
│   ✅ 用于异构系统集成                        ✅ 用于纯 RTL 设计    │
│   ✅ 包含连接性元数据                        ✅ 直接实例化到 Vivado │
│   ✅ 支持 AIE 集成                           ✅ 更精细的时序控制    │
│   ❌ Vivado 中可控性较低                     ❌ 需手动处理系统集成  │
│                                                                 │
│   本模块选择：两者都教！                                            │
│   • Vitis 子模块 → .xo（系统集成）                                  │
│   • Vitis_HLS 子模块 → 两者对比                                     │
│   • Vitis_Libraries 子模块 → IP Catalog（库复用）                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

权衡 3：AIE 用于计算密集型任务

为什么选择矩阵乘法作为 AIE 示例？

AIE vs PL HLS 的关键差异：

// HLS 版本：显式描述流水线
for(int i = 0; i < size; i++) {
    #pragma HLS PIPELINE II=1  // 请求硬件流水线
    // ... 计算逻辑
}

// AIE 版本：声明式数据流
connect(in1.out[0], k1.in[0]);  // 图连接隐式定义流水线
runtime<ratio>(k1) = 0.9;     // 资源分配声明
// AIE 编译器自动映射到 SIMD 单元和内存层次

数据流全景：端到端追踪

让我们追踪一个完整的数据生命周期，从主机内存到 AIE 计算再回到内存：

关键性能点分析

子模块导航与依赖关系

子模块文档入口

设计权衡与最佳实践

权衡矩阵：何时选择何种技术栈

┌──────────────────────────────────────────────────────────────────────────────┐
│                      技术选择决策树                                          │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Q1: 是否需要 AI 引擎 (AIE) 的 SIMD 计算能力？                                  │
│       ├── 是 → 选择 [Vitis 完整系统流]                                       │
│       │           • 需要 mm2s/s2mm 作为数据桥梁                               │
│       │           • 需要 system.cfg 定义 AIE 连接                              │
│       │           • 适合：矩阵运算、FFT、滤波等计算密集型任务                    │
│       │                                                                      │
│       └── 否 → 进入 Q2                                                       │
│                                                                              │
│  Q2: 是否有现成的 Vitis 库可用？                                                │
│       ├── 是 → 选择 [Vitis_Libraries 流]                                     │
│       │           • 克隆 Vitis_Libraries 仓库                               │
│       │           • 包含 L1/L2/L3 头文件路径                                   │
│       │           • 适合：FFT、BLAS、图像处理等标准算法                        │
│       │                                                                      │
│       └── 否 → 进入 Q3                                                       │
│                                                                              │
│  Q3: 是否需要与 Vivado  RTL 流程集成？                                         │
│       ├── 是 → 选择 [Vitis_HLS Vivado IP 流]                                  │
│       │           • flow_target=vivado                                      │
│       │           • package.output.format=ip_catalog                          │
│       │           • 导出 .zip IP 到 Vivado                                   │
│       │                                                                      │
│       └── 否 → 选择 [Vitis_HLS Vitis 内核流] 或通用 C/C++ 开发                   │
│                   • flow_target=vitis                                       │
│                   • package.output.format=xo                                  │
│                   • 用于 Vitis 系统集成                                      │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

常见陷阱与规避策略

陷阱 1：接口不匹配导致的数据停滞

// 错误示例：mm2s 生成 64-bit 数据，但 AIE 期望 32-bit
void mm2s_wrong(ap_int<64>* mem, hls::stream<ap_axis<64, 0, 0, 0>> &s, int size);
// AIE 侧：input_plio::create("DataIn", adf::plio_32_bits, ...)
// 结果：数据宽度不匹配，编译通过但运行时数据错位

// 正确做法：保持数据宽度一致
void mm2s_correct(ap_int<32>* mem, hls::stream<ap_axis<32, 0, 0, 0>> &s, int size);
// AIE 侧：adf::plio_32_bits 匹配

陷阱 2：HLS PIPELINE 的隐藏依赖

// 错误示例：存在循环携带依赖，但期望 II=1
void problematic(int* a, int n) {
    for(int i = 1; i < n; i++) {
        #pragma HLS PIPELINE II=1  // 期望：每个周期一次迭代
        a[i] = a[i-1] + 1;          // 实际：RAW 依赖，无法实现 II=1
    }
}
// HLS 报告：II 受限于循环携带依赖

// 解决方案：展开或重构算法
void resolved(int* a, int n) {
    #pragma HLS UNROLL factor=4
    for(int i = 0; i < n; i += 4) {
        a[i]   = i;
        a[i+1] = i+1;
        a[i+2] = i+2;
        a[i+3] = i+3;
    }
}

陷阱 3：AIE 缓冲区尺寸配置错误

// graph.h 中的配置
class Simple_Graph : public adf::graph {
    // ...
    Simple_Graph() {
        // ...
        // 错误配置：尺寸与内核期望不匹配
        dimensions(k1.in[0]) = {8};   // 声称 8 个 int32
        // 但 MatMul.cpp 期望 4x4=16 个元素用于矩阵 A
        // 结果：运行时缓冲区溢出或未定义行为
        
        // 正确配置：
        dimensions(k1.in[0]) = {16};  // 4x4 矩阵 A = 16 int32
        dimensions(k1.in[1]) = {4};   // 4x1 矩阵 B = 4 int32
        dimensions(k1.out[0]) = {4};  // 4x1 结果 C = 4 int32
    }
};

与生态系统的关联

模块依赖关系

与兄弟模块的对比

新贡献者快速指南

环境设置检查清单

# 1. 验证 Vitis 安装
which vitis
# 预期输出: <install_path>/Vitis/2024.2/bin/vitis

# 2. 验证 XRT 环境
source /opt/xilinx/xrt/setup.sh
xbutil examine  # 应显示设备信息（硬件运行时）

# 3. 验证平台
export PLATFORM_REPO_PATHS=<path_to_platforms>
ls $PLATFORM_REPO_PATHS/vck190_*/  # 应看到 VCK190 平台

# 4. 验证 Common Image
export COMMON_IMAGE_VERSAL=<path_to_common_image>
ls $COMMON_IMAGE_VERSAL/  # 应包含 rootfs, boot 等目录

# 5. 验证 Vitis Libraries（如使用）
ls <installdir>/Vitis_Libraries/dsp/L1/include/hw/vitis_fft/fixed/
# 应看到 fft.hpp 等头文件

调试策略矩阵

总结：从入门到精通的阶梯

Getting Started and Basic Vitis 模块是 AMD Versal 异构计算生态系统的门户与基石。它通过四个精心设计的子模块，展示了从 C/C++ 到硬件加速的完整转化路径：

1. Vitis 子模块展示了异构系统集成的艺术——如何将 HLS 数据搬运核、AI 引擎计算图和主机控制编织成无缝工作流。

2. Vitis_HLS 子模块传授硬件设计的函数式编程方法——通过 pragma 指导编译器将 C++ 代码转化为高效 RTL。

3. Vitis_Libraries 子模块演示生态系统的力量——如何站在巨人肩膀上，利用预优化的库加速开发。

4. Vitis_Platform 子模块奠定基础平台概念——理解软硬件协同设计的起点。

掌握这个模块后，你将具备继续探索更高级主题的基础：从 AIE_ML_Design_Graphs 的高级调度策略，到 AIE_ML_PL_HLS_Integration 的复杂数据流优化，再到 AIE_Design_Graphs_and_Algorithms 的完整信号处理链实现。

这个模块的真正价值不仅在于代码示例，而在于它传递的设计哲学：在 Versal 异构计算平台上，软件定义硬件不再是口号，而是可实践的方法论。