Schnellstart-Anleitung für Xillybus

Einführung

Diese Seite fasst kurz zusammen, wie Sie mit Xillybus oder XillyUSB loslegen. Normalerweise ist das eine schnelle und einfache Sache, für die Sie nicht viel Anleitung brauchen. Allerdings gibt es kleine Unterschiede zwischen den verschiedenen FPGAs.

Hier werden nur die häufigsten Anwendungsfälle und die neuesten FPGAs behandelt. Falls die Informationen auf dieser Seite erkennbar nicht ausreichen, schauen Sie in die Dokumentationsseite von Xillybus; dort finden Sie detailliertere und spezifischere Informationen.

Auf Xillinux gehe ich hier nicht ein, weil die Vorgehensweise dort etwas anders ist.

Überblick

Der Einstieg in Xillybus besteht aus drei Schritten:

1. Erzeugen einer Bitstrom-Datei (bitstream) für das FPGA aus dem Demopaket (demo bundle).
2. Installieren des Treibers auf dem Rechner (das ist oft nicht notwendig).
3. Durchführen eines einfachen Tests auf dem Rechner, der zeigt, dass Xillybus funktioniert (erklärt auf separaten Seiten für Linux und für Windows).

Später möchten Sie vielleicht einen eigenen IP-Core (custom IP core) erstellen, und zwar in der IP Core Factory. Dort können Sie dann so viele Streams wählen, wie Sie möchten. Aber bevor Sie so weit sind, hilft Ihnen das Ausprobieren des Demopakets zu verstehen, wie Xillybus funktioniert.

Xillybus vs. XillyUSB

Wenn Sie mit dem Gedanken spielen, XillyUSB zu verwenden, sollten Sie, falls das eine realistische Option ist, stattdessen Xillybus über PCIe in Betracht ziehen: Der PCIe-Bus ist bei weitem robuster als USB.

XillyUSB sollten Sie nur dann wählen, wenn das FPGA physisch außerhalb des Rechners liegen muss (zum Beispiel, wenn ein Laptop als Host dient).

Herunterladen des Demopakets und der Software

Alles, was auf der Xillybus-Website zum Download angeboten wird, ist völlig funktionsfähig. Das gilt sowohl für die IP-Cores (IP cores) aus der IP Core Factory als auch für die Demopakete. Sie müssen keinen Aktivierungscode anfordern oder Ähnliches. Allerdings ist die rechtliche Erlaubnis zur Nutzung des IP-Cores eingeschränkt: Sie dürfen den IP-Core nur zur Evaluierung verwenden. Danach kann es nötig sein, eine Lizenz zu erwerben, um den IP-Core weiterhin legal zu nutzen. Vergewissern Sie sich also, dass Sie die Bedingungen verstanden haben.

Es gibt zwei getrennte Webseiten zum Herunterladen der Dateien: für Xillybus per PCIe und für XillyUSB. Rufen Sie die passende Seite auf und laden Sie die folgenden Punkte herunter:

• Das Demopaket, das für Ihr Board gedacht ist.
• Den Treiber für Linux oder Microsoft Windows. Tun Sie das auch dann, wenn Sie Linux verwenden und der Treiber Teil Ihrer Linux-Distribution ist.
• Nur für Windows-Anwender: Das Xillybus-Paket für Windows.
• Nur für Windows-Anwender von XillyUSB: Das Diagnoseprogramm für Windows.

Alle diese Dateien sind im .zip- oder .tar.gz-Format. Entpacken Sie ihren Inhalt also zuerst auf die Festplatte.

Falls Ihr Board nicht in der Liste der Demopakete vorkommt, müssen Sie eines der Demopakete anpassen. Wählen Sie das Demopaket, das auf derselben FPGA-Familie basiert, und folgen Sie den Richtlinien in der Dokumentation für Xilinx oder Intel FPGA.

Der nächste Schritt unterscheidet sich zwischen AMD/Xilinx und Altera.

Erzeugen des Bitstroms für AMD / Xilinx

Sie müssen Vivado auf Ihrem Rechner installiert haben. Die Dokumentation enthält eine Liste geeigneter Versionen für jedes FPGA. Wenn Sie Vivado aber bereits installiert haben, versuchen Sie es einfach. Wenn die Vivado-Version nicht geeignet ist, schlägt die unten beschriebene Prozedur fehl: Sie erhalten dann einen Fehler, der besagt, dass eine neuere Version erforderlich ist. Wenn ein solcher Fehler nicht auftritt, ist Ihre Vivado-Version in Ordnung.

So erzeugen Sie die Bitstrom-Datei (bitstream):

• Wählen Sie in Vivado den Menüpunkt Tools > Tcl Script… und suchen Sie die Datei xillydemo-vivado.tcl. Diese Datei liegt im Unterverzeichnis verilog/ oder vhdl/. Sie wissen wahrscheinlich selbst, welche Variante Sie bevorzugen. Falls Sie es nicht wissen, nehmen Sie verilog/.
• Vivado erstellt daraufhin ein neues FPGA-Projekt. Die Tcl-Konsole von Vivado meldet „INFO: Project created: xillydemo“.
• Klicken Sie anschließend auf „Generate Bitstream“.
• Vivado beginnt daraufhin mit der Implementierung des Projekts. Am Ende erhalten Sie eine einsatzbereite Bitstrom-Datei. Diese Datei heißt xillydemo.bit.

Während der Implementierung erzeugt Vivado einige Warnungen, aber es sollten weder kritische Warnungen (Critical Warnings) noch Fehler auftreten.

Die ausführliche Erklärung finden Sie in diesem Dokument: Erste Schritte mit dem FPGA-Demopaket für Xilinx. Beachten Sie, dass Vivado nicht mit Virtex-5, Spartan-6 und Virtex-6 funktioniert. Wenn Sie eine dieser FPGA-Baureihen verwenden, lesen Sie dieses Dokument.

Versuchen Sie nicht, das FPGA-Projekt ohne das Tcl-Skript (script) zu erzeugen. Wenn Sie versuchen, ein neues Projekt anzulegen und die Quelldateien zu importieren, wird das vermutlich nicht richtig funktionieren.

Erzeugen des Bitstroms für Altera

Sie müssen Quartus auf Ihrem Rechner installiert haben. Die Dokumentation enthält eine Liste geeigneter Versionen für jedes FPGA. Wenn Sie bereits über Quartus verfügen, probieren Sie es einfach aus. Falls die Quartus-Version ungeeignet ist, schlägt die unten beschriebene Vorgehensweise fehl: Es erscheint ein Fehler, der besagt, dass eine neuere Version benötigt wird. Wenn kein solcher Fehler auftritt, ist Ihre Quartus-Version in Ordnung.

So erzeugen Sie die Bitstrom-Datei (bitstream):

• Doppelklicken Sie auf die Datei „xillydemo.qpf“. Diese Datei liegt im Unterverzeichnis verilog/ oder vhdl/. Sie wissen vermutlich, welche Variante Sie bevorzugen; falls nicht, nehmen Sie verilog/.
• Quartus öffnet daraufhin das FPGA-Projekt.
• Klicken Sie auf „Compile Design“.
• Quartus führt daraufhin die Implementierung des Projekts aus. Am Ende des Vorgangs gibt es eine einsatzbereite Bitstrom-Datei. Sie heißt xillydemo.sof.

Quartus erzeugt während der Implementierung mehrere Warnungen, aber es sollten weder kritische Warnungen (Critical Warnings) noch Fehler auftreten.

Die ausführliche Erklärung finden Sie in diesem Dokument: Erste Schritte mit dem FPGA-Demopaket für Intel FPGA. Wenn Ihr FPGA älter als die Baureihe V ist (z. B. Cyclone IV), dauert der Vorgang etwas länger. Weitere Informationen finden Sie in diesem Dokument.

Installieren des Treibers für Microsoft Windows

Der Xillybus-Treiber für Windows wird auf die übliche Weise installiert: Starten Sie den Rechner mit eingebautem FPGA-Board. Das FPGA muss bereits mit dem Bitstrom geladen sein, der Xillybus enthält, bevor der Rechner eingeschaltet wird.

Entpacken Sie zuerst den Inhalt der Zip-Datei mit dem Treiber auf die lokale Festplatte. Sie finden diese Datei auf der Download-Seite des Demopakets. Sie heißt ungefähr xillybus-windriver-1.2.0.0.zip.

Im Geräte-Manager (Device Manager) sollte ein Gerät unter „Andere Geräte“ (Other Devices) aufgeführt sein. Das Symbol dieses Geräts zeigt an, dass das Gerät nicht richtig installiert ist (mit einem Ausrufezeichen). Klicken Sie mit der rechten Maustaste auf das Symbol und wählen Sie „Treibersoftware aktualisieren…“. Wählen Sie dann die Option „Auf dem Computer nach Treibersoftware suchen“ (Browse my computer for driver software). Wählen Sie anschließend das Verzeichnis mit dem Namen „xillybus-windriver-1.2.0.0“ (oder ähnlich). Klicken Sie auf „Weiter“ und dann auf „Installieren“.

Nach der ordnungsgemäßen Installation des Treibers sollte im Geräte-Manager eine neue Gruppe mit dem Namen „Xillybus“ erscheinen. In dieser Gruppe gibt es ein Gerät mit der Bezeichnung „Xillybus driver for generic FPGA interface“. Das Symbol des Geräts sollte keinen Fehler anzeigen (also kein Ausrufezeichen auf dem Symbol).

Wenn Sie XillyUSB verwenden, erscheint das Gerät in der Gruppe „Universal Serial Bus controllers“ (USB-Controller); der Treiber befindet sich in xillyusb-windriver-1.1.2.0-win10.zip.

Diese Installationsprozedur ist ausführlicher mit Screenshots im Leitfaden für Windows beschrieben.

Nach der Installation des Windows-Treibers ist der nächste Schritt ein einfacher Test. Das wird auf einer separaten Seite erklärt.

Installieren des Treibers für Linux(?)

Der Xillybus-Treiber ist in vielen Linux-Distributionen für Desktop-Computer enthalten. Wenn Sie Fedora, Ubuntu oder Mint benutzen, ist der Xillybus-Treiber wahrscheinlich schon installiert.

Um festzustellen, ob der Treiber bereits installiert ist, geben Sie an der Eingabeaufforderung Ihrer Shell Folgendes ein:

$ modinfo xillybus_core

Wenn Sie mehrere Zeilen Ausgabe sehen, ist der Treiber bereits installiert, und Sie brauchen nichts weiter zu tun. Den Treiber müssen Sie nur installieren, wenn die Antwort „modinfo: ERROR: Module xillybus_core not found“ lautet.

Wenn Sie XillyUSB verwenden möchten, lautet der Befehl:

$ modinfo xillyusb

Es ist eine gute Idee, die udev-Datei von Xillybus auch dann zu installieren, wenn der Treiber bereits installiert ist. Siehe unten auf dieser Seite. Sie können diesen Schritt auch überspringen und direkt zu einem einfachen Test gehen.

Wenn der Treiber nicht installiert ist, haben Sie zwei Möglichkeiten:

• Installation des Treibers als Kernelmodul. Wie das funktioniert, wird weiter unten erklärt. Diese Möglichkeit ist geeignet, wenn Sie den Kernel nicht selbst vorbereitet haben (also den Kernel als Teil einer Distribution oder eines BSP (Board Support Package) erhalten haben).
• Den im Kernelbaum enthaltenen Treiber aktivieren. Diese Methode erfordert das Kompilieren des gesamten Kernels. Wenn eine Kernel-Kompilierung ohnehin zu Ihrem Arbeitsablauf gehört, ist dies der einfachere Weg. Die betreffenden Optionen heißen CONFIG_XILLYBUS und CONFIG_XILLYBUS_PCIE (bzw. CONFIG_XILLYUSB).

Der Xillybus-Treiber ist seit Version v3.12 Bestandteil des Linux-Kernels. Wenn Ihre Kernel-Version v4.6 oder neuer ist, gibt es keinen Grund, den Treiber zu aktualisieren: Seit dieser Version gab es keine nennenswerten Änderungen (nur am Codestil). Der XillyUSB-Treiber wurde in Linux v5.14 aufgenommen.

Weitere Informationen zum Einstieg unter Linux finden Sie im zugehörigen Leitfaden.

Kompilieren des Kernelmoduls

Die Kompilierung des Xillybus-Kernelmoduls setzt voraus, dass auf dem Rechner, auf dem die Kompilierung stattfindet, drei Dinge installiert sind:

• Der Compiler gcc
• „make“
• Die Kernel-Header des Kernels, der zusammen mit Xillybus verwendet wird

Der zugehörige Leitfaden für Linux erklärt, wie Sie prüfen können, ob diese Komponenten installiert sind, und wie Sie sie gegebenenfalls nachinstallieren.

Die Kompilierung des Treibers läuft so ab:

$ 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'

Um die Kernelmodule zu installieren, geben Sie „make install“ ein (dazu sind Root-Rechte erforderlich).

Der Treiber wird dann beim nächsten Start des Kernels automatisch geladen, sofern ein Xillybus-Gerät am Bus vorhanden ist. Sie können den Treiber aber auch manuell mit insmod laden.

Beachten Sie, dass diejenigen, die Xillybus auf einem eingebetteten Linux-System einsetzen möchten, unter Umständen einen Cross-Compiler benötigen. Auch die zum eingebetteten Kernel gehörenden Kernel-Header werden in diesem Fall benötigt.

Wenn Sie „make install“ nicht verwenden möchten, können Sie dasselbe von Hand erledigen: Kopieren Sie die Moduldateien in das Verzeichnis der Kernelmodule. Der Name dieses Verzeichnisses muss die Versionsnummer des Kernels enthalten, der mit Xillybus laufen wird.

Zum Beispiel:

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

Danach führen Sie depmod aus, damit der Kernel die neuen Module kennt. Zum Beispiel:

# depmod -a 4.15.0-20

udev-Datei (Linux)

Es wird empfohlen, die udev-Datei von Xillybus zu installieren, auch wenn der Treiber bereits installiert ist. Damit können Sie auf Xillybus zugreifen, ohne Root-Rechte zu besitzen. Diese Datei ist Teil des Pakets, das den Treiber enthält (xillybus.tar.gz oder xillyusb.tar.gz).

Die Installation der udev-Datei für Xillybus besteht aus folgendem Befehl (oder einem ähnlichen). Als Root-Benutzer:

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

Funktioniert es?

Im nächsten Schritt prüfen Sie, ob Sie alles richtig gemacht haben und Xillybus auf Ihrer Hardware funktioniert. Wie das geht, ist separat für Linux und für Windows beschrieben.