Vivado:在 Linux 命令行下向 FPGA 进行 bitstream 编程

简介

将位流(bitstream)发送到 FPGA 通常都要用到图形界面。像 Vivado 的 Hardware Manager 这类工具确实具备这个功能,但对于这样一件简单的事,流程往往显得太复杂。特别是当电脑只通过一根 JTAG 线连接一块 FPGA 时,这个界面仍然要求你走一大堆不必要的步骤。既然只有一块 FPGA,电脑为什么不能自己推断出应该把位流文件写入它呢?为什么还要明确地告诉工具我们要做什么?明明只有一个可选对象。

一个可行的解决办法是使用一个 bash 脚本(script),一步完成这个任务。这个脚本会找出通过 JTAG 线连接到计算机的 FPGA,并把位流文件发送给它。

这个脚本

下面这个脚本会把位流文件发送到 FPGA:

#!/bin/bash

set -e

if [ "$#" -ne 1 ]; then
    echo "Usage: $0 bitstream-file.bit"
    exit 1
fi

if ! which vivado >/dev/null ; then
    echo Vivado is not in the execution path. Please run something like
    echo source /path/to/..../Vivado/20nn.n/settings64.sh
    exit 1
fi

if [ ! -f "$1" ] ; then
    echo \"$1\" file doesn''t exist
    exit 1
fi

if vivado -mode batch -nolog -nojournal -source /dev/stdin -tclargs "$1" <<"EOF"
# Tcl script begins here.
set bitfile [lindex $argv 0]

open_hw
connect_hw_server
open_hw_target [lindex [get_hw_targets -of_objects [get_hw_servers localhost*]] 0]
set thefpga [lindex [get_hw_devices] 0]

set_property PROGRAM.FILE "$bitfile" $thefpga
set_property PROBES.FILE {} $thefpga
current_hw_device $thefpga
refresh_hw_device -update_hw_probes false $thefpga
program_hw_devices $thefpga
# Tcl script ends here
EOF
then
    echo -e "\nProgramming successful.\n"
else
    echo -e "\nProgramming failed.\n"
fi

注意,这个 bash 脚本里包含一个 Tcl 脚本。传给 vivado 命令的参数之一是 “-source /dev/stdin”。这样 Vivado 就会从标准输入读取 Tcl 脚本。借助 “<<” 使用众所周知的 here document 方法。

使用脚本

把上面显示的脚本写到一个文件里,例如命名为 fpga_program。然后用类似下面的命令把这个文件加上可执行权限:

$ chmod a+x fpga_program

在尝试运行这个脚本之前,先用类似下面的命令设置环境变量:

$ source /opt/xilinx/Vivado/2023.1/settings64.sh

请修改命令里的 “/opt/xilinx/Vivado/2023.1” 部分,使路径与你的电脑上实际安装 Vivado 的位置一致。

然后用类似下面的命令运行脚本:

$ ./fpga_program myproj.bit

当然,要把 “myproj.bit” 换成你的位流文件名。

当这个脚本运行时,Vivado 会产生大量输出,不过最后一行会是 “Programming successful” 或 “Programming failed”。

关于脚本的几点说明

这个脚本在 Vivado 2015.2 和 Vivado 2023.1 上都测试过,所以大概率能兼容所有版本的 Vivado。不过在较新的 Vivado 版本中,软件会打印下面这条警告:

WARNING: 'open_hw' is deprecated, please use 'open_hw_manager' instead.

尽管有这条警告,脚本仍然可以正常工作。不过,未来的 Vivado 版本可能不再识别 “open_hw” 命令。如果这条命令导致报错,就把它改成 “open_hw_manager”。

对这个脚本可能做的另一处修改与它的输出量有关。如果你不希望看到那么多文字输出,可以加上一个重定向,让输出进入 /dev/null。

如果你希望这样做,请在脚本中找到这一行:

if vivado -mode batch -nolog -nojournal -source /dev/stdin -tclargs "$1" <<"EOF"

然后把它改成:

if vivado -mode batch -nolog -nojournal -source /dev/stdin -tclargs "$1" > /dev/null <<"EOF"

停止硬件服务器

如果你在同一台电脑上安装了多个版本的 Vivado,连接 JTAG 线可能会遇到问题。原因是这样的:Vivado 会使用一个 TCP/IP 服务器与硬件通信(它监听 3121 端口)。Vivado 会在需要时自动启动这个服务器。

但如果服务器是由某个版本的 Vivado 启动的,而另一个版本的 Vivado 又试图连接这块 FPGA,通信就可能失败。原因在于服务器的版本和 Vivado 的版本是绑定的。在使用图形界面的 Hardware Manager 时也会出现同样的情况。

遇到这种问题时,可以用下面这个命令停止服务器:

$ killall hw_server

注意,如果服务器有一段时间没有被使用,它也会自行停止。