Vivado : programmer le FPGA en ligne de commande Linux

Introduction

L’envoi d’un flux de bits (bitstream) au FPGA passe en général par une interface graphique. Des outils comme le Hardware Manager de Vivado offrent cette fonctionnalité, mais la procédure paraît souvent trop compliquée pour une tâche aussi simple. En particulier, lorsqu’un seul FPGA est relié à l’ordinateur par un unique câble JTAG, l’interface impose beaucoup d’étapes inutiles. S’il n’y a qu’un seul FPGA, pourquoi l’ordinateur ne peut-il pas en déduire qu’il doit écrire le fichier de flux de bits vers ce FPGA ? Pourquoi faut-il dire explicitement aux outils ce que l’on veut faire ? Il n’y a vraiment qu’une seule option.

Une solution possible consiste à utiliser un script bash qui accomplit cette tâche en une seule étape. Ce script détecte le FPGA relié à l’ordinateur via un câble JTAG, puis envoie le fichier de flux de bits à ce FPGA.

Le script

Voici le script qui envoie un fichier de flux de bits au 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

Remarquez que ce script bash contient un script Tcl. L’un des arguments transmis à la commande « vivado » est « -source /dev/stdin ». Cela amène Vivado à lire le script Tcl depuis l’entrée standard. La méthode bien connue du « here document » (document incorporé) est utilisée grâce à « << ».

Utilisation du script

Enregistrez le script ci-dessus dans un fichier, par exemple sous le nom fpga_program. Rendez ce fichier exécutable avec une commande semblable à celle-ci :

$ chmod a+x fpga_program

Avant de tenter d’exécuter le script, définissez les variables d’environnement avec une commande du type :

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

Modifiez la partie « /opt/xilinx/Vivado/2023.1 » de cette commande afin que le chemin (path) corresponde à l’emplacement où Vivado est installé sur votre ordinateur.

Exécutez ensuite le script avec une commande de ce genre :

$ ./fpga_program myproj.bit

Bien entendu, remplacez « myproj.bit » par le nom de votre fichier de flux de bits.

Vivado produit beaucoup de sorties pendant l’exécution de ce script, mais la dernière ligne affiche « Programming successful » ou « Programming failed ».

Quelques remarques sur le script

Ce script a été testé avec Vivado 2015.2 et Vivado 2023.1. Il y a donc de bonnes chances qu’il fonctionne avec toutes les versions de Vivado. Cependant, avec les versions récentes, le logiciel affiche l’avertissement suivant :

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

Le script fonctionne malgré cet avertissement. Il est cependant possible que les futures versions de Vivado ne reconnaissent plus la commande « open_hw ». Si cette commande provoque une erreur, remplacez-la dans le script par « open_hw_manager ».

Une autre modification possible du script concerne la quantité de texte produit par ce script. Si vous ne souhaitez pas autant de sortie, ajoutez une redirection afin que la sortie soit envoyée vers /dev/null.

Si vous le souhaitez, repérez cette ligne dans le script :

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

Et remplacez-la par :

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

Arrêter le serveur matériel

Si vous utilisez plusieurs versions de Vivado sur le même ordinateur, des difficultés de connexion avec le câble JTAG peuvent apparaître. La raison de ce problème est que Vivado utilise un serveur TCP/IP pour communiquer avec le matériel (il écoute sur le port 3121). Vivado démarre ce serveur automatiquement lorsque c’est nécessaire.

Mais si le serveur a été démarré par une version de Vivado, et qu’une autre version essaie de se connecter au FPGA, la communication peut échouer. La raison est que la version du serveur est celle de la version de Vivado. Cette situation se produit aussi lorsqu’on utilise le Hardware Manager avec son interface graphique.

Quand ce problème survient, on peut arrêter le serveur avec cette commande :

$ killall hw_server

À noter que le serveur s’arrête de lui-même s’il reste inutilisé pendant un certain temps.