ug902-ch1 Using Vivado HLS

在Linux平台上调用Vivado HLS(或从Windows上的Vivado HLS命令提示符)，在命令提示符下执行以下命令。
$ vivado_hls

创建一个新项目

IMPORTANT! 不要使用add files按钮(或关联的add_files Tcl命令)向项目添加头文件(.h后缀)。

Vivado HLS自动将以下目录添加到搜索路径

• Working directory
  Note: The working directory contains the Vivado HLS project directory.
• Any directory that contains C files added to the project
  目录中的头文件将自动包含在项目中。必须使用Edit CFLAGS按钮指定所有其他头文件的路径。

Edit CFLAGS：指定编译C代码所需的C编译器标记选项。
这些编译器标记选项与在gcc或g++中使用的相同。C编译器标记包括头文件的路径名、宏规范和编译器指令，如下面的示例所示

• -I/project/source/headers:提供相关头文件的搜索路径
  注意:必须指定相对于工作目录的相对路径名而不是项目目录。
• -DMACRO_1:在编译期间，定义宏MACRO_1
• -fnested-functions:定义任何包含嵌套函数的设计所需的指令
  TIP:要获得Edit CFLAGS选项支持的的完整列表，请参见GNU编译器集合(gcc)网站上的选项摘要页面(http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html)。
  TIP: You can use $::env(MY_ENV_VAR) to specify environment variables in CFLAGS. For example, to
  include the directory $MY_ENV_VAR/include for compilation, you can specify -I $::env(MY_ENV_VAR)/include in CFLAGS .

Note:对于SystemC设计，其带有与test bench相关（不是与设计文件相关）的头文件，必须使用Add files按钮将头文件添加到项目中。

在Vivado HLS提供的大多数示例设计中，test bench与设计在单独的文件中。将测试台和要综合的function放在单独的文件中，可以将simulation过程和synthesis.过程清晰地分离开来。如果test bench与要合成的function在同一个文件中，则应该将该文件添加为源文件，并在下一个步骤中添加为test bench文件。
Figure 11: Project Test Bench Files

与C源文件一样，单击Add files按钮来添加C test bench，单击Edit CFLAGS按钮来包含任何C编译器选项。
除了C源文件之外，test bench读取的所有文件都必须添加到项目中。在上图所示的示例中，测试工作台打开file In .dat来为设计提供输入刺激，然后file out.gold .dat来读取预期的结果。因为test bench访问这些文件，所以这两个文件都必须包含在项目中。
如果测试工作台文件存在于某个目录中，则可以使用Add Folders按钮将整个目录而不是单个文件添加到项目中。
如果没有C测试工作台，就不需要在这里输入任何信息，Next > 按钮将打开项目向导的最后一个窗口，它允许为solution1指定细节，如下图所示。
Figure 12: Initial Solution Settings

新项目向导中的最后一个窗口允许您指定第一个解决方案的详细信息

• Clock Period: The clock period specified in units of ns or a frequency value specified with the
  MHz suffix (For example, 150MHz).
• Uncertainty:用于合成的时钟周期是时钟周期减去时钟不确定性。Vivado HLS使用内部模型来估计每个FPGA的操作延迟。时钟不确定性值提供了一个可控制的裕度，以解释由于RTL逻辑综合、位置和路由而导致的任何净延迟的增加。如果没有指定纳秒(ns)或百分比，时钟不确定性默认为12.5%的时钟周期。
• Part:点击选择合适的工艺。

C simulation

Vivado HLS流中的验证可以分为两个不同的过程。

• C simulation：Pre-synthesis validation，验证C程序正确实现所需的功能。
• C/RTL co-simulation：Post-synthesis verification，验证RTL是正确的。这两个过程都称为仿真:C仿真和C/RTL联合仿真

Figure 15: C Simulation Dialog Box

C仿真对话框中的其他选项有:

• Launch Debugger:编译C代码并自动打开debug透视图。在debug透视图中，可以使用Synthesis透视图按钮(左上角)将窗口返回到Synthesis透视图。
• Build Only: C代码编译，但simulation不运行。
• Clean Build:在编译代码之前，从项目中删除所有现有的可执行文件和目标文件。
• Optimized Compiler: 默认情况下，设计是使用调试信息编译的，允许在debug透视图中分析编译。此选项在编译设计时使用更高级别的优化工作，但删除调试器所需的所有信息。这增加了编译时间，但是应该减少模拟运行时间。
• Compiler: 允许您选择使用gcc/g++来编译代码

检查C仿真输出

C仿真完成后，将在解决方案文件夹中创建一个文件夹csim，如下所示。
文件夹csim/build是与C simulation.相关的所有文件的主要位置。

• test bench读取的任何文件都会复制到这个文件夹中。
• C可执行文件csim.exe被创建并在此文件夹中运行。
• test bench写入的所有文件都在这个文件夹中创建。
  如果在C模拟对话框中选择Build Only选项，则在此文件夹中创建文件csim.exe，但不执行该文件。通过在命令shell中执行这个文件，可以手动运行C模拟。在Windows上，Vivado HLS命令shell可以通过开始菜单获得。
  文件夹csim/report包含一个C仿真的日志文件。

Synthesizing the C Code

Creating an Initial Solution

Reviewing the Output of C Synthesis

当综合完成时，syn文件夹现在在解决方案文件夹中可用。
report文件夹包含顶层和每一个子函数的report。
verilog、vhdl和systemc文件夹包含输出RTL文件。

Xilinx不建议使用这些文件进行RTL综合。相反，Xilinx建议使用本设计流中稍后讨论的打包的IP输出文件。仔细阅读紧跟着这个笔记的文本。

Vivado HLS在设计中使用Xilinx IP的情况时(例如使用浮点设计)，RTL目录包含一个脚本，用于在RTL合成期间创建IP。如果syn文件夹中的文件用于RTL合成，那么您有责任正确使用这些文件夹中出现的任何脚本文件。如果使用package IP，则此过程由design Xilinx工具自动执行。

Analyzing the Results of C Synthesis

Synthesis Reports

。。。
某些Xilinx设备使用堆叠硅互连(SSI)技术。在这些设备中，所有可用资源被划分到多个超级逻辑区域super logic regions (SLRs)。当您选择一个SSI技术设备作为目标技术时，使用情况报告包括SLR使用情况和总设备使用情况的详细信息。
IMPORTANT! 使用SSI技术设备时，重要的是要确保Vivado HLS创建的逻辑适合单个SLR。

延迟值都显示为“?””(问号)。
Vivado HLS执行分析以确定每个循环的迭代次数。如果循环迭代极限是一个变量，Vivado HLS无法确定最大上限。
在下面的示例中，for循环的最大迭代由输入num_samples的值决定。num_samples的值不是在C函数中定义的，而是从外部进入函数的。

void foo (char num_samples, ...);
void foo (num_samples, ...) {
int i;
...
loop_1: for(i=0;i< num_samples;i++) {
...
result = a + b;
}
}

如果设计的延迟或吞吐量依赖于带有变量索引的循环，Vivado HLS将循环的延迟报告为未知(在报告中用问号表示?)。
可以将TRIPCOUNT指令应用于循环，以手动指定循环迭代的次数，并确保报表包含有用的次数。-max选项告诉Vivado HLS循环遍历的最大迭代次数，-min选项指定执行的最小迭代次数。
注意:TRIPCOUNT指令不影响合成结果。
tripcount值仅用于报告，以确保Vivado HLS生成的报告显示有意义的延迟和间隔范围。这也允许在不同的解决方案之间进行有意义的比较。
如果在代码中使用了C assert宏，Vivado HLS可以使用它来自动确定循环限制，并创建完全符合这些限制的硬件。

Analysis Perspective

Schedule Viewer

Dataflow Viewer

Creating a New Solution

Applying Optimization Directives

Verifying the RTL is Correct

C/RTL cosimulation.
验证完成后，控制台显示消息SIM-1000以确认验证成功。C测试台上的任何printf命令的结果都会回显到控制台。
IMPORTANT! 只有当C test bench返回一个0值时，C/RTL联合模拟才会通过。联合仿真测试测试台上的场景，并通过它是否返回True或0。如果失败，则返回False或1。

Output of C/RTL Co-Simulation的输出

RTL验证完成后，将在解决方案文件夹中创建一个sim目录。下图显示了创建的子文件夹。

• report文件夹包含每种RTL模拟类型的报告和日志文件。
• 为每种验证的RTL类型创建一个verification文件夹。验证文件夹名为verilog或vhdl。如果未验证RTL格式，则不创建任何文件夹。
• 用于模拟的RTL文件存储在verification文件夹中。
• 在verification文件夹中执行RTL模拟。
• 任何输出，例如跟踪文件，都被写入verification文件夹。
• 文件夹autowrap, tv, wrap和wrap_pc是Vivado HLS使用的工作文件夹。这些文件夹中没有用户文件。

如果在C/RTL联合模拟对话框中选择了Setup Only选项，那么将在验证文件夹中创建可执行文件，但不会运行模拟。可以通过在命令提示符处执行模拟可执行文件来手动运行模拟。

使用命令提示符和Tcl接口

Windows:Xilinx Design Tools → Vivado 2018.x → Vivado HLS → Vivado HLS 2018.x Command Prompt.
在Windows和Linux上，使用-i选项和vivado_hls命令在交互模式下打开Vivado HLS。然后Vivado HLS等待输入Tcl命令。

$ vivado_hls -i [-l <log_file>]
vivado_hls>

默认情况下，Vivado HLS在当前目录中创建一个vivado_hls.log文件。要为日志文件指定不同的名称，可以使用-1 <log_file>选项。

vivado_hls> help
//通过使用命令名，可以对任何单个命令提供帮助。
vivado_hls> help <command>

键入exit命令退出交互模式并返回到shell提示

vivado_hls> exit

Vivado HLS的其他选项包括:
• vivado_hls -p: open the specified project
• vivado_hls -nosplash: open the GUI without the Vivado HLS splash screen
• vivado_hls -r: return the path to the installation root directory
• vivado_hls -s: return the type of system (for example: Linux, Win)
• vivado_hls -v: return the release version number.

Improving Runtime and Capacity

如果问题是关于C/RTL联合仿真的，请参考Verifying the RTL.的reduce_diskspace选项。本节的其余部分将回顾有关synthesis runtime时的问题。
Vivado HLS分级调度操作。循环中的操作被调度，然后循环、子函数和带有函数的操作被调度。Vivado HLS的运行时间在以下情况下增加:

• 有更多的对象需要调度。
• 有更多的自由和更多的可能性去探索。
  Vivado HLS调度对象（schedules objects.）。无论对象是浮点乘法操作还是单个寄存器，它仍然是一个需要调度的对象。浮点乘法可能需要多个周期来完成，并使用许多资源来实现，但在调度级别上它仍然是一个对象。
  展开循环和分割数组会创建更多要调度的对象，并可能增加运行时间。内联函数会创建更多对象以在此层次结构级别上进行调度，并且还会增加运行时间。
  partitioning arrays
  如果必须对阵列进行分区才能获得性能。根据吞吐量需求对数组进行分区，考虑对config_array_partition使用throughput_driven选项。

Unrolling loops
如果必须展开循环，或者上层中使用PIPELINE指令自动展开了循环，那么可以考虑将loop body捕获为一个单独的函数。这将把所有逻辑捕获到一个函数中，而不是在循环展开时创建逻辑的多个副本:定义的层次结构中的一组对象将被更快地调度。如果在pipelined区域中使用了unrolled loop，请记住对该函数进行pipelined处理。

The degrees of freedom in the code can also impact runtime. Consider Vivado HLS to be an expert designer who by default is given the task of finding the design with the highest throughput, lowest latency and minimum area. The more constrained Vivado HLS is, the fewer options it has to explore and the faster it will run. Consider using latency constraints over scopes within the code: loops, functions or regions. Setting a LATENCY directive with the same minimum and maximum values reduces the possible optimization searches within that scope.
Finally, the config_schedule configuration controls the effort level used during scheduling. This generally has less impact than the techniques mentioned above, but it is worth considering. The default strategy is set to Medium.
If this setting is set to Low, Vivado HLS will reduce the amount of time it spends on trying to improve on the initial result. In some cases, especially if there are many operations and hence combinations to explore, it may be worth using the low setting. The design may not be ideal but it may satisfy the requirements and be very close to the ideal. You can proceed to make progress with the low setting and then use the default setting before you create your final result.
With a run strategy set to High, Vivado HLS uses additional CPU cycles and memory, even after satisfying the constraints, to determine if it can create an even smaller or faster design. This exploration may, or may not, result in a better quality design but it does take more time and memory to complete. For designs that are just failing to meet their goals or for designs where many different optimization combinations are possible, this could be a useful strategy. In general, it is a better practice to leave the run strategies at the Medium default setting.