Vitis HLS新手入门：从C++到FPGA硬件加速的实战与避坑

简介：面向具备C/C++基础、希望以高级语言完成FPGA硬件加速的工程师、研究生与自学者，这份中文版《Vitis高层次综合用户指南》（UG1399 v2022.2，2022年12月7日版）PDF文档适合从入门到进阶系统查用。全文按七个部分组织，依次讲解HLS简介、HLS编程指南、使用Vitis HLS、Vitis HLS命令、C语言驱动、HLS库及代码移植；编程指南涉及FPGA编程三大范例、控制驱动与数据驱动的任务级并行、循环入门与优化策略，工具部分覆盖环境设置、项目创建、代码分析、综合报告与仿真验证，库章节则提及数学运算、数据流处理和控制逻辑等常用能力。资源包共1个PDF文件，约16.41MB，单文件便于检索与离线查阅。已有737人学习下载，可作为FPGA算法加速、HLS工程移植和Vitis流程实践的系统参考，帮助读者理解设计思路、命令用法、库函数调用与测试平台搭建方法。

1. 先弄明白一件事：HLS 到底是个什么东西

如果你第一次听到 Vitis HLS 高层次综合这个名字，反应大概率是懵的——明明要做的是 FPGA 硬件电路，怎么突然让我去写 C 语言？我第一次听的时候也以为是某种新出的编译器插件，后来才琢磨明白：它本质上是一层翻译，把你写的 C/C++ 算法，翻译成能烧进 FPGA 里的硬件电路描述。打个比方，以前做 FPGA 像自己一粒一粒捏寿司，米蒸到什么程度、醋放几勺都得亲手定；高层次综合更像是把配方写成菜谱交给厨房，厨房照着菜谱直接出餐。这份中文版用户指南，就是那本把火候、规矩、摆盘全写清楚的说明书，从简介、编程指南、工具使用、命令、C 语言驱动、库到移植，七个部分一层层铺开。它适合谁？适合会用一点 C 或 C++、对“写代码就能做出硬件加速”心痒、但完全没碰过硬件描述语言的新手。

2. 算一笔时间账：为什么新手该先学 HLS 而不是直接学 Verilog

2.1 从手画电路到写代码描述算法，省下的是什么

传统的 FPGA 开发要写 Verilog 或 VHDL，这叫 RTL 设计。用这类语言写代码，你得自己在脑子里模拟时钟：第 1 个周期哪个寄存器赋值，第 2 个周期哪个信号拉高，状态机跳几个状态才算完。一个十六点向量加法，在 C 里五行写完，在 RTL 里可能要写一个状态机加若干个计数器，还得自己安排数据什么时候进、什么时候出。

高层次综合换了个思路。你只描述“我想算什么”，工具负责决定“用几个加法器、几级流水、什么时候锁存”。这就是它最朴素的价值：把设计的起点从门级细节抬到了算法级。你写的东西是可读的、可调试的、改一行就能重跑仿真的。对新手来说，这一点尤其重要——学习曲线最陡的那一段，你不用同时学硬件时序和语言语法两座山。

当然它不是白送的。工具自动做出来的电路，未必比你手写的更省资源，这也正是后面第四章要讲循环、数组、接口的原因。但作为入门第一步，先让一个设计完整跑通、看到报告、看到波形，比什么都重要。

2.2 三种并行，构成 HLS 全部的性能空间

看这份指南第 2 章的时候，有一组概念值得你先记下来：FPGA 编程的三大范例——顺序执行、数据并行、任务并行。听着玄乎，其实用生活场景一对就懂。

顺序执行就是一个人排队干活，一件事做完再做下一件，硬件里对应的是控制驱动、一步一步来的逻辑。数据并行是同一个动作在多个数据上同时做，比如十六个加法同时开十六个加法器，硬件里对应的是展开循环。任务并行则是几件不同的事同时推进，比如一边收数据一边算一边往外发，硬件里对应的是数据流（DATAFLOW）那一套。

新手最容易犯的错，是拿纯软件的脑子想问题：代码从上往下一行行跑，天然就是顺序的。但在硬件里，只要没有数据依赖，两句话完全可以同时发生。所以学 HLS 真正难的不是语法，而是这个思维切换——你得开始问自己“这两步之间有依赖吗？没有的话能不能一起做？”

指南里反复强调的“组合三种范例”，说的就是这件事：一个真实的设计，往往是外层任务并行、内层数据并行、局部还有顺序控制。你先有这个地图，后面看流水线、展开、数据流才不会觉得是一堆互不相干的开关。

2.3 这份指南七百多页，新手到底该从哪几页翻起

拿到一本厚文档，最怕的就是从第一页开始硬啃。按入门路径排一下优先级，你会省很多力气：

我把这个顺序叫“先跑起来，再回头补”。原因是新手在没有具体问题的时候读概念，读一遍忘一遍；一旦你手上有一个跑不通的工程，再去翻对应章节，那几页会突然变得特别好懂。第一次学的时候我就是从第一章一字一句读，读到接口那章已经忘了前面讲什么，血泪经验。

3. 第一个例子跑通：从建工程到屏幕上出现 PASS

3.1 动手前先认三个词：内核、测试激励、综合

这三个词会贯穿你整个入门期，先花两分钟弄明白，后面看文档就不卡。

内核，指的是你要变成硬件的那段函数。在 Vitis HLS 里，你通过 set_top 指定哪个函数是顶层，它就会变成硬件模块，函数名变成模块名，函数的参数变成模块对外的端口。一个工程只能有一个顶层函数，其他函数会被它调用，形成层级。

测试激励，英文叫 testbench，就是一个带 main 函数的普通 C++ 文件。它的作用是给内核喂数据、调用内核、检查结果对不对。你在电脑上跑它，用的是 CPU，跟硬件一点关系没有，但它能帮你确认算法逻辑没错。

综合，就是把 C++ 内核翻译成 RTL 的过程。这一步才真正开始谈硬件：用多少加法器、多少个时钟周期出结果、占多少 BRAM。综合本身不改你的代码，它只是按你给的约束和指示去生成电路。

理清这三者的关系，你就明白整个流程为什么是“先 C 仿真、再综合、再协同仿真”了：先在纯软件层面保证算法正确，再去关心硬件实现，最后用真正的 RTL 仿真器验证硬件行为和 C 代码一致。这个顺序不能乱，乱了就是给自己找麻烦。

3.2 写第一个内核：十几行 C++ 完成一次向量加法

先别急着建工程，打开任意一个文本编辑器，敲下面这段代码，存成 vector_add.cpp。

// vector_add.cpp // 顶层函数的名字会直接变成硬件模块名，起个一眼能看懂的名字 #define N 16 void vector_add(const int a[N], const int b[N], int c[N]) { // 最朴素的写法：一个循环，每次处理一个元素 for (int i = 0; i < N; i++) { // 让循环的每一次迭代尽量重叠执行，目标间隔 1 个时钟周期 #pragma HLS PIPELINE II=1 c[i] = a[i] + b[i]; } }

这段代码里有两个东西值得说。第一，顶层函数的三个参数都是数组，在硬件里它们会变成三组端口，至于具体变成什么形态的端口，是接口章节要解决的问题，现在先不管。第二，#pragma HLS PIPELINE II=1 是一句编译指示，意思是希望这个循环的相邻两次迭代之间只隔 1 个时钟周期。II 是 initiation interval 的缩写，中文常叫启动间隔，它是 HLS 里最重要的性能指标之一——II=1 意味着每个周期都能吃进一个新数据。

你现在不用完全理解它，先知道它是“调速旋钮”就行。把这一行删掉，综合出来的电路也能用，只是慢一些。保留它，是为了让你第一次看报告的时候，能亲眼看到数字的变化。

3.3 配一个测试激励，先让 C 仿真跑起来

硬件还没影，先用 CPU 验证算法。新建 vector_add_tb.cpp：

// vector_add_tb.cpp #include <cstdio> // 声明要和内核定义完全一致，参数类型、数组长度都不能改 void vector_add(const int a[16], const int b[16], int c[16]); int main() { int a[16], b[16], c[16]; // 造数据：a 递增、b 固定，结果用肉眼也能核对 for (int i = 0; i < 16; i++) { a[i] = i; b[i] = 100; } vector_add(a, b, c); // 逐项比对，任何一项不对就判 FAIL bool ok = true; for (int i = 0; i < 16; i++) { if (c[i] != a[i] + b[i]) ok = false; printf("c[%d] = %d\n", i, c[i]); } printf(ok ? "PASS\n" : "FAIL\n"); return ok ? 0 : 1; }

测试激励写得好不好，直接决定你后面调 bug 有多痛苦。新手常犯的错是只测一组“好看”的数据，比如全 0 或者全正数，结果综合出来的电路在负数、边界值上翻车。建议从第一个例子开始就养成习惯：至少覆盖正常值、边界值、负数各一组。这份指南第 13 章专门讲了怎么写测试激励，等你跑通第一个例子再回去补，会有共鸣得多。

3.4 用 Tcl 脚本把整条流程串起来

图形界面点起来直观，但入门阶段我更建议你直接用脚本跑一遍，因为脚本把每一步都写明了，你能清楚看到流程长什么样。新建 run_hls.tcl：

# run_hls.tcl # -reset 表示如果同名工程已存在，先清掉重建，避免残留配置干扰 open_project -reset vec_add_prj # 指定哪个函数是硬件顶层，这个名字必须和 cpp 里的函数名完全一致 set_top vector_add # 加入设计文件和测试激励文件，-tb 标记表示只用于仿真，不参与综合 add_files vector_add.cpp add_files -tb vector_add_tb.cpp # 创建一个解决方案，flow_target 选 vivado 表示目标是传统 FPGA 流程 open_solution -reset "solution1" -flow_target vivado # 目标器件型号，换成你手头板子上的型号即可 set_part xc7z020clg400-1 # 时钟约束：周期 10 纳秒，也就是 100MHz，工具按这个算时序 create_clock -period 10 -name default # 三步走：C 仿真 -> C 综合 -> C/RTL 协同仿真 csim_design csynth_design cosim_design # 最后把结果打包成 IP，方便在更大的系统里调用 export_design -format ip_catalog

存好之后，在命令行里执行：

# -f 表示把后面的文件当成 Tcl 脚本逐行执行 vitis_hls -f run_hls.tcl

跑起来之后你会看到一堆输出。第一段是 C 仿真，最后应该打印 PASS。第二段是综合，会输出一张报告表，里面有 Latency（延迟）和 II（启动间隔）两个数字，先记住它们，第四章要用。第三段协同仿真比较慢，因为它要调用 RTL 仿真器，第一次跑耐心等几分钟。

如果 csim_design 就报错，八成是函数签名对不上，或者测试激励里忘了 include。如果 csynth_design 报错，通常是用了综合不支持的 C++ 特性，比如动态内存分配、递归、系统调用——指南第 7 章列了一张“不受支持的 C/C++ 构造”清单，遇到这类报错先去那张表里对一对。

4. 三关：循环、数组、接口，决定你的设计是快还是慢

4.1 循环：流水线和展开，是两个方向的旋钮

循环是 HLS 里最值得先啃的一块，因为它同时决定了吞吐和面积。指南第 3 章把循环相关的技术拆成了几块：流水打拍、展开、合并、嵌套循环、可变边界循环。新手先掌握前两个就够用。

流水线（PIPELINE）的思路是“重叠”。一个循环体如果分三步：读数据、加法、写回，不流水的话每次迭代要花三个周期，上一轮写完下一轮才开始。加了流水线，第二轮在第一轮做加法的时候就去读数据了，理想情况下每个周期都能出一个结果，这就是 II=1。

void add_stream(const int a[64], const int b[64], int c[64]) { for (int i = 0; i < 64; i++) { // 让相邻迭代重叠执行，目标是每周期吃进一个新数据 #pragma HLS PIPELINE II=1 c[i] = a[i] + b[i]; } }

展开（UNROLL）是另一个方向：把循环彻底拆开，让多次迭代变成同时执行的并行逻辑。比如一个 4 次的循环完全展开，就变成四条并行的加法语句，一个周期出四个结果——吞吐上去了，但加法器也从 1 个变成 4 个，面积跟着涨。

void add_parallel(const int a[64], const int b[64], int c[64]) { for (int i = 0; i < 64; i++) { // factor=4 表示每次拆开 4 次迭代并行执行，循环次数相应减少 #pragma HLS UNROLL factor=4 c[i] = a[i] + b[i]; } }

两个旋钮的区别一句话说清：流水线是“用时间换面积”，展开是“用面积换时间”。新手最常见的误判，是以为加了 PIPELINE 就一定更快——如果你的循环体内部有跨迭代的数据依赖，比如第 i 次要用第 i-1 次的结果，流水线就会被卡住，II 会变成 2、3 甚至更大。看到这种情况先别怀疑工具，回去看代码里的依赖关系。

4.2 数组：软件里一块内存，硬件里可能是四种东西

在 C 语言里，数组就是内存里一段连续空间，你几乎不用关心它在哪。到了硬件里，这句话就不成立了——数组会被映射成具体的存储器，可能是寄存器堆，可能是块 RAM，可能是查找表 RAM，也可能是 UltraRAM，具体选哪个由工具按访问模式推断，你也可以手动指定。

为什么这件事重要？因为存储器端口数量是有限的。一块 BRAM 通常只有两个访问端口，如果你的循环在一个周期内要读数组的三个不同位置，端口不够，流水线就被迫降速。这就是为什么指南第 4 章花了很大篇幅讲阵列访问和性能。

解决办法是数组分割（ARRAY_PARTITION）。把一个 16 元素的数组拆成 16 个独立的小数组，每个都能独立访问，端口问题就解决了，代价是消耗更多存储资源。

void split_demo(int in[16], int out[16]) { // 把一维数组完全拆成 16 个独立元素，每个元素可用独立端口访问 #pragma HLS ARRAY_PARTITION variable=in complete dim=1 for (int i = 0; i < 16; i++) { #pragma HLS PIPELINE II=1 out[i] = in[i] * 2; } }

除了完全分割，还有块分割（block）和循环分割（cyclic）两种方式，分别适合不同的访问规律。入门阶段先记住一条判断标准：如果你的流水线报告里 II 一直降不下来，而循环体里又有多处数组访问，那大概率就是端口瓶颈，去试试数组分割。

4.3 接口：你的模块怎么跟外面的世界说话

内核写好了，综合也过了，但它现在是个孤零零的模块，得有人给它喂数据、把它算完的结果取走。这就轮到接口章节。

Vitis HLS 里最常用的几种接口类型，新手先认识三个：ap_ctrl_hs 是默认的握手控制接口，带 ap_start、ap_done、ap_idle、ap_ready 四个信号，适合做简单的控制流；AXI4-Lite 是轻量级寄存器接口，通常用来配置参数，比如你有个“放大倍数”要传进来，就走它；AXI4-Stream 是流式数据接口，一个周期进一个数，没有地址概念，特别适合图像、信号处理这类连续数据流。

void stream_add(int in_a, int in_b, int &out) { // 标量端口指定成 AXI4-Lite，方便 CPU 侧读写寄存器 #pragma HLS INTERFACE s_axilite port=in_a #pragma HLS INTERFACE s_axilite port=in_b #pragma HLS INTERFACE s_axilite port=out // 返回端口指定成 AXI-Lite，用于 CPU 侧启动和判断完成 #pragma HLS INTERFACE s_axilite port=return out = in_a + in_b; }

选接口的经验法则很朴素：数据是一段一段送的、有明确地址的，用 AXI4 主接口去访问内存；数据是连续不断的流，用 AXI4-Stream；只是几个配置参数，用 AXI4-Lite。选错了不会报错，但后面的系统集成会很别扭，改起来又得重新综合，所以一开始就定下来比较省事。

4.4 看懂报告里的 Latency 和 II，别再盯着时钟频率瞎猜

综合完会出一张汇总表，新手最该盯的是两个数字：Latency 和 II。

Latency 是这个模块从收到输入到给出输出要多少时钟周期。它决定了单个数据的处理延迟。II 是相邻两次处理之间的间隔，它决定了吞吐——II=1 时每个周期出一个结果，II=4 就是每四个周期出一个。很多人只盯着时钟频率，以为频率高就一定快，其实如果 II 很大，频率再高吞吐也上不去。这个坑我在第一次做图像处理的小 demo 时踩得很实：时钟从 100MHz 提到 200MHz，帧率几乎没变，因为瓶颈压根不在频率上。

除了这两个数，报告里还会告诉你每个循环的迭代次数、用了多少 BRAM、多少 DSP、多少触发器。指南第 15 章讲了调度查看器、函数调用图、数据流查看器和时间线轨迹查看器，这些工具的价值在于让你看到“为什么是这个数字”。入门阶段不必全用，但调度查看器值得早点打开看看，它会用一个横条图告诉你每个操作被排在哪个周期，哪一步是瓶颈，一眼就明白。

5. 避坑清单：新手最容易翻车的五个地方、原因和解决办法

5.1 第一条：C 仿真过了，协同仿真对不上

现象：csim_design 打印 PASS，cosim_design 跑完却报结果不一致，或者干脆卡住不动。

原因通常有两个。一是测试激励里用了综合不支持的写法，比如打印语句、动态内存、文件读写——这些在 C 仿真里正常工作，但 RTL 侧根本没有对应硬件，协同仿真自然对不上。二是有未定义行为，比如数组越界、读未初始化的变量，C 仿真时碰巧“运气好”没暴露，硬件上就露馅了。

解决办法：把测试激励里所有 printf 换成结果比对，把 new/delete 换成静态数组，把文件读写挪到 C 仿真之外。另外在综合前先看一眼指南第 7 章那张不支持构造的清单，逐条对一遍，能省大量时间。

5.2 第二条：综合直接报不支持，代码看着明明没问题

现象：csynth_design 中途退出，报 unsupported 之类的错误，指向某一行你看不出毛病的代码。

原因多半是用了软件世界很自然、硬件世界很难实现的东西：递归函数、虚函数、函数指针、系统调用、动态分配内存。这些东西的共同点是运行时才知道要分配多少资源，而硬件资源在综合时就必须定死。

解决办法：递归改成循环加显式栈，虚函数改成模板或者普通函数加重载，动态数组改成定长数组。指南第 7 章把这几类逐一列了出来，遇到报错直接去那一章对号入座，比全网搜答案快得多。

5.3 第三条：加了 PIPELINE，结果反而更慢

现象：明明写了 #pragma HLS PIPELINE II=1，报告里的 II 却是 3 或者 5，Latency 比不加还大。

原因是循环体内部存在阻止重叠的依赖。最常见的是跨迭代依赖，也就是第 i 次迭代要用第 i-1 次算出来的值；其次是数组端口冲突，一个周期内要访问同一块存储器的多个地址；还有就是循环里调用了不能流水的函数。

解决办法：先打开调度查看器，看是哪个操作把流水线卡住了。如果是数据依赖，考虑改写算法，比如用移位寄存器缓存中间结果；如果是端口冲突，加 ARRAY_PARTITION；如果是函数调用，把那个函数内联（INLINE）进来。改完重新综合，盯着 II 这个数字看，一次次逼近 1 的过程其实就是 HLS 调优的日常。

5.4 第四条：数组一综合，BRAM 用量爆炸

现象：一个不大的数组，综合后占用的块 RAM 数量远超预期，甚至放不进目标器件。

原因往往是你对数组做了完全分割或者过度分割。分割的代价就是把一块存储器拆成很多块，每块都有独立的最小存储单元开销，元素少、位宽小的时候浪费特别明显。

解决办法：先看数组的访问模式再决定分割方式。如果循环是顺序访问，其实不需要分割；如果是并行访问多个不同下标，优先考虑循环分割或者只分割部分维度。另外注意小数组（比如几十个元素）有时映射成寄存器反而更划算，工具会自己判断，你也可以用 pragma 强制指定。

5.5 第五条：导出的 IP 在系统里接不起来

现象：export_design 成功，IP 也导入了，但一连线就报地址或者位宽不匹配，或者接上去之后跑起来没反应。

原因通常是接口类型没提前规划好。比如你导出的是纯 AXI4-Stream 接口，外面却想用 AXI4-Lite 去读写它；或者数据位宽是 32 位，对接的总线是 64 位，工具不会自动帮你转。

解决办法：在写内核之前就把接口定下来，用 INTERFACE pragma 显式指定每个端口的类型和位宽，别让工具猜。导出前用综合报告里的接口一节核对一遍端口清单，确认类型、位宽、方向都对得上。这个习惯一旦养成，后面集成会顺很多，后悔药是没得吃的。

6. 下一步学什么：一份能照着走三个月的入门路线

跑通第一个例子之后，最怕的就是打开文档不知道翻哪一页。给你一条可以照着走的顺序，按周排，不按章节排。

具体到每天怎么练，我的建议是“改一个变量，看一次报告”。比如今天就练 PIPELINE 的 II 参数：分别写 II=1、II=2、不写，三次综合，把 Latency 和资源占用记在同一个表里。你会发现有些时候 II=1 根本达不到，工具会告诉你达不到的原因，那些提示就是你下一课要学的东西。这种练法比通读文档有效得多，因为你每次都在解决一个具体问题。

再往后走，就该碰真实场景了。找一个你熟悉的算法——比如图像卷积、矩阵乘、简单的 FIR 滤波——用 C 写出来，先保证 C 仿真通过，再一步步加 pragma 优化，每一步都记录数字。这个过程会逼你把前面所有碎片串起来。指南第 10 章讲的最优化技巧与故障排除，到那时候读起来会非常有感觉，因为你已经亲身经历过那些数字的起起落落了。

最后说一个我自己的习惯。从那以后我每次开新工程，都强制走一遍固定流程：先写测试激励并覆盖三组数据，再跑 C 仿真，再看综合报告的 II 和 Latency，最后才去改代码。听起来啰嗦，但它替我拦掉了至少一半的返工。入门阶段最重要的不是你写得多快，而是每一步都能看见结果、说清原因。希望这份路线能帮你把这个习惯早点建立起来，帮到你。

本文还有配套的精品资源，点击获取