Der „Hello, world“-Test von Xillybus
Dies ist der dritte Schritt beim Einstieg in Xillybus: Der Bitstrom (bitstream), der Xillybus enthält, ist bereits in das FPGA geladen, und der Treiber ist auf dem Host installiert. Jetzt ist es Zeit für einen einfachen Test. Der Zweck dieses Tests ist zu prüfen, ob die Gerätedateien (device files) angelegt wurden und funktionieren.
Diese Seite behandelt Xillybus auf einem Windows-Host. Für Linux gibt es eine ähnliche Seite.
Ich konzentriere mich hier auf Xillybus mit PCIe, aber bei XillyUSB läuft fast alles genauso ab. Die Unterschiede sind am Ende dieser Seite aufgelistet.
Weitere Informationen zu diesem Thema finden Sie im Leitfaden für Windows.
Wird das PCIe-Gerät erkannt?
Der Geräte-Manager (Device Manager) zeigt die erkannten PCIe-Geräte an. Das wurde bereits im Zusammenhang mit der Installation des Treibers erklärt.
Vor der Installation des Treibers erschien das Xillybus-Gerät in der Liste „Andere Geräte“ (Other Devices). Nach der Installation erscheint das Gerät in einer Gruppe namens „Xillybus“. Wenn der Geräte-Manager keine dieser beiden Möglichkeiten anzeigt, wird das FPGA nicht als PCIe-Gerät erkannt: Vermutlich gibt es ein Problem mit dem FPGA. Oft ist die Ursache ein Durcheinander dabei, welcher Bitstrom ins FPGA geladen wurde.
Eine ausführlichere Erklärung mit Screenshots zu diesem Thema finden Sie im Leitfaden für Windows.
Wurde der Treiber ordnungsgemäß gestartet?
Der nächste Schritt ist, den Status des Treibers zu prüfen. Das machen Sie im Geräte-Manager: Klicken Sie mit der rechten Maustaste auf das Symbol in der Gruppe „Xillybus“ (das Gerät heißt „Xillybus driver for generic FPGA interface“). Wählen Sie „Eigenschaften“. Daraufhin öffnet sich ein Pop-up-Fenster. Schauen Sie in den Textbereich mit dem Titel „Gerätestatus“ (Device status). Dort sollte „Das Gerät funktioniert einwandfrei.“ stehen. Das bedeutet, dass der Treiber Xillybus erfolgreich initialisiert und die erforderlichen Gerätedateien angelegt hat.
Wenn der Text etwas anderes besagt, ist bei der Initialisierung des Treibers etwas schiefgegangen. Das ist in der Regel ein Problem mit der FPGA-Logik. Insbesondere passiert das, wenn der PCIe-Block im FPGA falsch konfiguriert ist. Wenn Sie zum Beispiel die Parameter des PCIe-Blocks im Demopaket verändert haben, kann das Fehler dieser Art verursachen.
Weitere Informationen über das Problem finden Sie in der Ereignisanzeige (Event Viewer) von Windows. Die Meldungen des Xillybus-Treibers lassen sich herausfiltern: Erstellen Sie eine benutzerdefinierte Ansicht, die Meldungen aus der Quelle namens „Xillybus“ anzeigt. Wie das geht, wird im Leitfaden für Windows ausführlich erklärt.
„Hello, world“
Der Treiber legt fünf Gerätedateien an: \\.\xillybus_read_8, \\.\xillybus_read_32, \\.\xillybus_write_8, \\.\xillybus_write_32 und \\.\xillybus_mem_8. Beachten Sie, dass Sie, wenn Sie in der IP Core Factory einen eigenen IP-Core (custom IP core) erzeugen, selbst festlegen können, wie viele Gerätedateien angelegt werden, sowie deren Namen und Eigenschaften.
Aber im Moment enthält das FPGA das Demopaket. Probieren wir zwei der Gerätedateien aus. Bei diesen Gerätedateien handelt es sich eigentlich um Betriebssystemobjekte, aber sie lassen sich wie normale Dateien ansprechen. Der Teil „\\.\“ mag für Leute seltsam wirken, die mit der systemnahen Programmierung unter Windows nicht vertraut sind. Das ist jedoch die übliche Art, auf die Software im Benutzermodus (oft DLLs) auf die Hardware zugreift.
Im Demopaket existiert ein Loopback zwischen read_8 und write_8. Das heißt: Wenn der Rechner Daten an write_8 schreibt, gibt das FPGA über read_8 genau dieselben Daten zurück. Das ist nur als Demonstration gedacht. Für diesen Loopback gibt es keinen anderen praktischen Nutzen.
Der Test läuft wie folgt ab: Öffnen Sie zwei Eingabeaufforderungsfenster (Command Prompt windows) auf Ihrem Rechner. Wechseln Sie in beiden Eingabeaufforderungsfenstern in das Verzeichnis „precompiled-demoapps“. Dieses Verzeichnis liegt innerhalb des Verzeichnisses „xillybus-windowspack“. Erinnern Sie sich, dass ich vorgeschlagen habe, xillybus-windowspack.zip zusammen mit dem Demopaket herunterzuladen.
Geben Sie im ersten Eingabeaufforderungsfenster Folgendes ein:
$ streamread \\.\xillybus_read_8
Geben Sie dann im zweiten Eingabeaufforderungsfenster Folgendes ein:
$ streamwrite \\.\xillybus_write_8
Tippen Sie nun im zweiten Eingabeaufforderungsfenster einen beliebigen Text und drücken Sie die Eingabetaste. Der gleiche Text erscheint im ersten Eingabeaufforderungsfenster. Das veranschaulicht, wie der Text zuerst in die erste Gerätedatei geschrieben wurde, dann ins FPGA gelangte und schließlich wieder zum Rechner zurückkehrte.
Sie können diese beiden Programme mit STRG-C beenden.
Den Quellcode dieser Programme finden Sie im Unterverzeichnis demoapps (aus derselben Zip-Datei). Die Programme sind in C geschrieben und zeigen, wie Sie mit einer Standard-I/O-API auf die Gerätedateien von Xillybus zugreifen. Der Leitfaden für Windows erklärt, wie Sie diese Programme kompilieren können.
Auch wenn dieses Beispiel einfach ist, ist es wichtig zu verstehen, wie es funktioniert. Insbesondere ist es wichtig zu verstehen, wie die Logik im FPGA das zustande gebracht hat. Genau hier ist der Ausgangspunkt, um Ihre eigene Logik einzubinden.
XillyUSB
Wenn Sie XillyUSB verwenden, gilt alles, was oben gesagt wurde, allerdings mit einigen Unterschieden.
Zu XillyUSB gehört ein Werkzeug namens showdiagnostics, mit dem Sie die Qualität der physischen Verbindung zum FPGA untersuchen können. Es wird dringend empfohlen, mit diesem Werkzeug sicherzustellen, dass die Rohdatenverbindung (raw data link) fehlerfrei ist. Selbst wenn XillyUSB auf den ersten Blick einwandfrei funktioniert, ist diese Prüfung wichtig. Der Grund ist, dass das USB-3.0-Protokoll Fehler auf der Rohdatenverbindung verbirgt, diese Fehler aber trotzdem seltene Probleme verursachen können, die wie ein Bug aussehen.
Es gibt keinen Grund, Fehler dieser Art zu tolerieren. Oft ist die Lösung einfach, z. B. einen anderen USB-Port des Rechners zu verwenden.
Andere Unterschiede:
- Die Namen der Gerätedateien sind etwas anders. Anstelle von \\.\xillybus_read_8 lautet der Name zum Beispiel \\.\xillyusb_00_read_8. Der Teil „00“ kann variieren.
- Der Geräte-Manager zeigt das Gerät in der Gruppe „Universal Serial Bus controllers“ (USB-Controller) an, unabhängig davon, ob der Treiber installiert ist oder nicht.