01signal: Guide de démarrage rapide avec Xillybus

Introduction

Cette page est un résumé succinct pour vous lancer avec Xillybus ou XillyUSB. C’est en général une procédure rapide et simple, qui ne demande pas beaucoup d’explications. Il existe cependant de légères variations selon les FPGA.

Seuls les cas d’utilisation les plus courants et les FPGA les plus récents sont traités ici. Si les informations de cette page ne suffisent manifestement pas, reportez-vous à la page de documentation de Xillybus, qui contient des informations plus détaillées et plus spécifiques.

Je n’aborderai pas Xillinux ici, car sa procédure est un peu différente.

Vue d’ensemble

Pour démarrer avec Xillybus, il y a trois étapes :

Générer un fichier bitstream pour le FPGA à partir du pack de démonstration (demo bundle).
Installer le pilote sur l’ordinateur (cette étape est souvent inutile).
Effectuer un test simple sur l’ordinateur pour vérifier que Xillybus fonctionne (expliqué sur des pages séparées pour Linux et pour Windows).

Par la suite, vous voudrez peut-être créer votre cœur IP personnalisé (custom IP core) sur l’IP Core Factory. Cela vous permettra de choisir autant de flux que vous le souhaitez. Mais avant d’en arriver là, essayer le pack de démonstration vous aidera à comprendre comment fonctionne Xillybus.

Xillybus vs XillyUSB

Si vous envisagez d’utiliser XillyUSB, pensez à choisir plutôt Xillybus pour PCIe, si c’est une option réaliste : le bus PCIe est nettement plus robuste que l’USB.

XillyUSB ne doit être choisi que lorsque le FPGA doit être physiquement à l’extérieur de l’ordinateur (par exemple si un ordinateur portable sert d’hôte).

Téléchargement du pack de démonstration et des logiciels

Tout ce qui est téléchargeable sur le site de Xillybus est entièrement fonctionnel. Cela inclut les cœurs IP (IP cores) de l’IP Core Factory ainsi que les packs de démonstration. Il n’est pas nécessaire de demander un code d’activation ni quoi que ce soit de ce genre. En revanche, l’autorisation légale d’utiliser le cœur IP est limitée : vous ne pouvez l’utiliser que pour une évaluation. Ensuite, il peut être nécessaire d’acheter une licence pour continuer à utiliser le cœur IP en toute légalité. Assurez-vous donc de bien comprendre les conditions.

Il existe deux pages web distinctes pour télécharger les fichiers : une pour Xillybus via PCIe, et une pour XillyUSB. Rendez-vous sur la page concernée et téléchargez les éléments suivants :

Le pack de démonstration prévu pour votre carte.
Le pilote pour Linux ou Microsoft Windows. Téléchargez-le même si vous utilisez Linux et que le pilote fait déjà partie de votre distribution Linux.
Utilisateurs de Windows uniquement : le pack Xillybus pour Windows.
Utilisateurs de XillyUSB sous Windows uniquement : l’utilitaire de diagnostic pour Windows.

Tous ces fichiers sont au format .zip ou .tar.gz. Commencez donc par décompresser leur contenu sur le disque.

Si votre carte ne figure pas dans la liste des packs de démonstration, vous devrez modifier ce pack de démonstration. Choisissez celui qui est basé sur la même famille de FPGA et suivez les instructions de la documentation pour Xilinx ou pour Intel FPGA.

L’étape suivante diffère entre AMD / Xilinx et Altera.

Création du bitstream pour AMD / Xilinx

Vous devez avoir Vivado installé sur votre ordinateur. La documentation contient une liste des versions adaptées à chaque FPGA. Mais si Vivado est déjà installé, essayez de l’utiliser. Si la version de Vivado ne convient pas, la procédure décrite ci-dessous échouera : vous obtiendrez une erreur indiquant qu’une version plus récente est requise. Si aucune erreur de ce type n’apparaît, votre version de Vivado convient.

Voici les étapes pour créer le fichier bitstream :

Dans Vivado, sélectionnez Tools > Tcl Script… et cherchez xillydemo-vivado.tcl. Ce fichier se trouve dans le sous-répertoire nommé verilog/ ou vhdl/. Vous savez probablement lequel vous préférez. Si vous ne savez pas, choisissez verilog/.
Vivado crée alors un nouveau projet FPGA. La console Tcl de Vivado affiche « INFO: Project created: xillydemo ».
Cliquez ensuite sur « Generate Bitstream ».
Vivado lance alors l’implémentation du projet. À la fin de ce processus, vous disposez d’un fichier bitstream prêt à l’emploi. Ce fichier s’appelle xillydemo.bit.

Vivado émet plusieurs avertissements pendant l’implémentation, mais il ne devrait y avoir ni erreur, ni avertissement critique (Critical Warning).

L’explication détaillée se trouve dans ce document : Prise en main du pack de démonstration FPGA pour Xilinx. Notez que Vivado ne prend pas en charge les Virtex-5, Spartan-6 et Virtex-6. Si vous utilisez l’un de ces FPGA, reportez-vous à ce document.

N’essayez pas de créer le projet FPGA sans le script Tcl. Si vous tentez de créer un nouveau projet et d’importer les fichiers sources, cela ne fonctionnera probablement pas correctement.

Création du bitstream pour Altera

Vous devez avoir Quartus installé sur votre ordinateur. La documentation contient une liste des versions adaptées à chaque FPGA. Mais si Quartus est déjà installé, essayez de l’utiliser. Si la version de Quartus ne convient pas, la procédure décrite ci-dessous échouera : vous obtiendrez une erreur indiquant qu’une version plus récente est requise. Si aucune erreur de ce type n’apparaît, votre version de Quartus convient.

Voici les étapes pour créer le fichier bitstream :

Double-cliquez sur le fichier « xillydemo.qpf ». Ce fichier se trouve dans le sous-répertoire nommé verilog/ ou vhdl/. Vous savez probablement lequel vous préférez. Si vous ne savez pas, choisissez verilog/.
Quartus ouvre alors le projet FPGA.
Cliquez sur « Compile Design ».
Quartus lance l’implémentation du projet. À la fin de ce processus, vous disposez d’un fichier bitstream prêt à l’emploi. Ce fichier s’appelle xillydemo.sof.

Quartus émet plusieurs avertissements pendant l’implémentation, mais il ne devrait y avoir ni erreur, ni avertissement critique (Critical Warning).

L’explication détaillée se trouve dans ce document : Prise en main du pack de démonstration FPGA pour Intel FPGA. Si votre FPGA est antérieur à la série V (par exemple Cyclone IV), la procédure est un peu plus longue. Consultez ce document pour plus d’informations.

Installation du pilote pour Microsoft Windows

Le pilote Windows de Xillybus s’installe de la manière standard : démarrez l’ordinateur avec la carte FPGA installée à l’intérieur. Le FPGA doit être chargé avec le bitstream contenant Xillybus avant que l’ordinateur ne soit allumé.

Commencez par extraire le contenu de l’archive Zip contenant le pilote sur le disque local. Ce fichier se trouve sur la page de téléchargement du pack de démonstration. Son nom ressemble à xillybus-windriver-1.2.0.0.zip.

Dans le Gestionnaire de périphériques (Device Manager), un périphérique doit apparaître sous la rubrique « Autres périphériques ». Son icône indique qu’il n’est pas installé correctement (avec un point d’exclamation). Faites un clic droit sur cette icône et sélectionnez « Mettre à jour le pilote… ». Choisissez de sélectionner un fichier sur l’ordinateur (« Parcourir mon ordinateur pour rechercher des pilotes »). Sélectionnez ensuite le répertoire nommé « xillybus-windriver-1.2.0.0 » (ou similaire). Cliquez sur « Suivant », puis sur « Installer ».

Une fois le pilote correctement installé, un nouveau groupe apparaît dans le Gestionnaire de périphériques, nommé « Xillybus ». Dans ce groupe se trouve un périphérique intitulé « Xillybus driver for generic FPGA interface ». Son icône ne doit pas indiquer d’erreur (c’est-à-dire pas de point d’exclamation sur l’icône).

Si vous utilisez XillyUSB, le périphérique apparaîtra sous le groupe « Contrôleurs Universal Serial Bus », et le pilote se trouve dans xillyusb-windriver-1.1.2.0-win10.zip.

Cette procédure d’installation est décrite plus en détail avec des captures d’écran dans le guide pour Windows.

Après l’installation du pilote Windows, l’étape suivante consiste à effectuer un test simple. C’est expliqué sur une page séparée.

Installation du pilote pour Linux(?)

Le pilote de Xillybus est inclus dans de nombreuses distributions Linux pour ordinateurs de bureau. Si vous utilisez Fedora, Ubuntu ou Mint, le pilote Xillybus est probablement déjà installé sur votre machine.

Pour vérifier si le pilote est déjà installé, tapez ceci à l’invite du shell :

$ modinfo xillybus_core

Si la réponse comporte plusieurs lignes, le pilote est déjà installé et vous n’avez rien à faire. Vous ne devez installer le pilote que si vous obtenez « modinfo: ERROR: Module xillybus_core not found ».

Si vous souhaitez utiliser XillyUSB, la commande est

$ modinfo xillyusb

Même si le pilote est déjà installé, il est conseillé d’installer le fichier udev de Xillybus. Voir le bas de cette page. Vous pouvez aussi passer cette étape et aller directement à un test simple.

Si le pilote n’est pas installé, deux options s’offrent à vous :

Installer le pilote comme module du noyau. La façon de procéder est expliquée ci-dessous. Cette option convient si vous n’avez pas préparé le noyau vous-même (par exemple si le noyau provient d’une distribution ou d’un BSP (Board Support Package)).
Activer le pilote intégré dans l’arborescence du noyau. Cette méthode exige une compilation du noyau entier. Si une compilation du noyau fait déjà partie de votre processus de travail, c’est la solution la plus simple. Les options correspondantes sont CONFIG_XILLYBUS et CONFIG_XILLYBUS_PCIE (ou CONFIG_XILLYUSB).

Le pilote Xillybus fait partie de l’arborescence du noyau Linux depuis la version v3.12. Si votre noyau est en v4.6 ou plus récent, il n’y a aucune raison de mettre le pilote à niveau : aucune modification significative n’y a été apportée depuis cette version (uniquement des changements de style de code). Le pilote XillyUSB a été ajouté dans Linux v5.14.

Vous trouverez plus d’informations pour démarrer avec Linux dans le guide associé.

Compilation du module noyau

La compilation du module noyau de Xillybus nécessite que trois éléments soient déjà installés sur l’ordinateur qui effectue la compilation :

Le compilateur gcc
« make »
Les en-têtes du noyau (kernel headers) pour le noyau utilisé avec Xillybus

Le guide Linux correspondant indique comment vérifier si ces éléments sont installés et comment les installer si ce n’est pas le cas.

La compilation du pilote se fait comme suit :

$ tar -xzf xillybus.tar.gz
$ cd xillybus/module/
$ make
make -C /lib/modules/4.15.0/build M=/home/01signal/xillybus/module modules
make[1]: Entering directory '/usr/src/linux-headers-4.15.0'
  CC [M]  /home/01signal/xillybus/module/xillybus_core.o
  CC [M]  /home/01signal/xillybus/module/xillybus_pcie.o
  Building modules, stage 2.
  MODPOST 2 modules
  CC      /home/01signal/xillybus/module/xillybus_core.mod.o
  LD [M]  /home/01signal/xillybus/module/xillybus_core.ko
  CC      /home/01signal/xillybus/module/xillybus_pcie.mod.o
  LD [M]  /home/01signal/xillybus/module/xillybus_pcie.ko
make[1]: Leaving directory '/usr/src/linux-headers-4.15.0'

Pour installer les modules du noyau, tapez « make install » (cette commande nécessite les droits root).

Le pilote sera chargé automatiquement au prochain démarrage du noyau si un périphérique Xillybus est présent sur le bus. Il est également possible d’utiliser insmod pour charger le pilote manuellement.

Notez que ceux qui comptent utiliser Xillybus sur un système Linux embarqué devront peut-être utiliser un compilateur croisé (cross compiler). Les en-têtes du noyau liés au noyau embarqué sont également nécessaires dans ce cas.

Si vous ne voulez pas utiliser « make install », il est possible de faire la même chose manuellement : copiez les fichiers des modules dans le répertoire qui contient les modules du noyau. Le nom de ce répertoire doit contenir le numéro de version du noyau qui fonctionnera avec Xillybus.

Par exemple,

# cp xillybus_core.ko /lib/modules/4.15.0/kernel/drivers/char/
# cp xillybus_pcie.ko /lib/modules/4.15.0/kernel/drivers/char/

Ensuite, exécutez depmod pour que le noyau prenne connaissance des nouveaux modules. Par exemple :

# depmod -a 4.15.0-20

Fichier udev (Linux)

Il est recommandé d’installer le fichier udev de Xillybus, même si le pilote est déjà installé. Cela permet d’accéder à Xillybus sans être root. Ce fichier fait partie de l’archive qui contient le pilote (xillybus.tar.gz ou xillyusb.tar.gz).

L’installation du fichier udev pour Xillybus consiste en la commande suivante (ou similaire), en tant que root :

# cp 10-xillybus.rules /etc/udev/rules.d/

Est-ce que ça fonctionne ?

L’étape suivante consiste à vérifier que vous avez tout fait correctement et que Xillybus fonctionne sur votre matériel. La procédure est présentée séparément pour Linux et pour Windows.