Vivado: Bitstrom-Programmierung des FPGA über die Linux-Kommandozeile

Einführung

Das Senden eines Bitstroms (englisch: bitstream) an das FPGA erfolgt normalerweise über eine grafische Benutzeroberfläche. Werkzeuge wie der Hardware Manager von Vivado bieten diese Funktion; allerdings wirkt der Ablauf für diese einfache Aufgabe oft unnötig kompliziert. Gerade wenn nur ein einziges FPGA über ein einziges JTAG-Kabel mit dem Rechner verbunden ist, verlangt die Benutzeroberfläche viele überflüssige Schritte. Wenn es nur ein FPGA gibt, warum kann der Rechner dann nicht selbst darauf kommen, dass die Bitstromdatei in dieses FPGA geschrieben werden soll? Warum muss man den Werkzeugen ausdrücklich sagen, was man möchte? Es gibt doch wirklich nur eine Option.

Eine mögliche Lösung ist ein Bash-Skript (englisch: script), das diese Aufgabe in einem einzigen Schritt erledigt. Dieses Skript findet das FPGA, das über ein JTAG-Kabel mit dem Rechner verbunden ist, und sendet die Bitstromdatei an dieses FPGA.

Das Skript

Dies ist das Skript, das eine Bitstromdatei an das FPGA sendet:

#!/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

Beachte, dass dieses Bash-Skript ein Tcl-Skript enthält. Eines der Argumente, die dem Befehl „vivado“ übergeben werden, ist „-source /dev/stdin“. Dadurch veranlasst man Vivado, das Tcl-Skript von der Standardeingabe zu lesen. Die bekannte Methode des Here-Dokuments (englisch: here document) wird mit Hilfe von „<<“ verwendet.

Das Skript verwenden

Schreibe das oben gezeigte Skript in eine Datei, zum Beispiel mit dem Namen fpga_program. Mache diese Datei mit einem Befehl wie diesem ausführbar:

$ chmod a+x fpga_program

Bevor du das Skript ausführst, richte die Umgebungsvariablen mit einem Befehl ähnlich diesem ein:

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

Ändere den Teil „/opt/xilinx/Vivado/2023.1“ in diesem Befehl so ab, dass der Pfad (englisch: path) den Ort widerspiegelt, an dem Vivado auf deinem Rechner installiert ist.

Führe das Skript dann mit einem Befehl wie diesem aus:

$ ./fpga_program myproj.bit

Ändere natürlich „myproj.bit“ in den Namen deiner Bitstromdatei.

Während dieses Skript läuft, erzeugt Vivado eine Menge Ausgabe. Die letzte Zeile lautet jedoch entweder „Programming successful“ oder „Programming failed“.

Ein paar Anmerkungen zum Skript

Dieses Skript wurde mit Vivado 2015.2 und Vivado 2023.1 getestet. Die Chancen stehen also gut, dass es mit allen Vivado-Versionen funktioniert. Bei neueren Versionen von Vivado gibt die Software allerdings die folgende Warnung aus:

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

Das Skript funktioniert trotz dieser Warnung. Es ist jedoch möglich, dass zukünftige Versionen von Vivado den Befehl „open_hw“ nicht mehr kennen. Wenn dieser Befehl einen Fehler verursacht, ändere ihn im Skript in „open_hw_manager“.

Eine weitere mögliche Änderung betrifft die Menge an Ausgabe, die dieses Skript erzeugt. Wenn du nicht so viel Textausgabe haben möchtest, füge eine Umleitung hinzu, sodass die Ausgabe nach /dev/null geht.

Wenn du das möchtest, suche im Skript diese Zeile:

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

Und ändere sie in:

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

Den Hardware-Server stoppen

Wenn du mehrere Versionen von Vivado auf demselben Rechner verwendest, kann es zu Problemen mit der Verbindung zum JTAG-Kabel kommen. Der Grund dafür ist, dass Vivado zur Kommunikation mit der Hardware einen TCP/IP-Server verwendet, der auf Port 3121 lauscht. Vivado startet diesen Server bei Bedarf automatisch.

Wenn der Server jedoch von einer Version von Vivado gestartet wurde und eine andere Version von Vivado versucht, sich mit dem FPGA zu verbinden, funktioniert die Kommunikation unter Umständen nicht. Der Grund ist, dass der Server dieselbe Versionsnummer hat wie das Vivado, das ihn gestartet hat. Diese Situation tritt auch bei Verwendung des Hardware Managers mit der grafischen Benutzeroberfläche auf.

Wenn dieses Problem auftritt, kann der Server mit folgendem Befehl gestoppt werden:

$ killall hw_server

Beachte, dass der Server von selbst aufhört zu laufen, wenn er eine Zeit lang nicht benutzt wird.