FPGA Debugger

Hardware-Debugger für das DE0-nano FPGA-Board.

Quickstart

Wenn du den Debugger ohne weitere Entwicklung zum laufen bringen möchtest, bist du hier richtig. Die Anleitung hier bezieht sich spezifisch auf die Verwendung mit unserer Implementierung eines Befehlssatzes für den FPGA.
Wenn du den Debugger für deinen eigenen Code verwenden möchtest, solltest du in das detaillierte HowTo schauen.

Schritt 1: FPGA mit Quartus flashen

Der FPGA Code muss kompiliert und via einem Programmer auf den FPGA geladen werden. Dafür empfehlen wir Quartus Prime Lite von Intel (die kostenlose Variante reicht vollkommen aus).
Nachdem du Quartus installiert hast und dieses Repo heruntergeladen hast, öffne Quartus und wähle File -> Open Project.... Dann Wähle die de0Board.qpf Datei aus dem /src/fpga Ordner aus.
Nun müsste Quartus das Projekt öffnen.

Drücke nun den Compile Knopf (blauer Pfeil) in Quartus, damit das Projekt kompiliert wird.
Drücke anschließend auf den Programmer Knopf (rechts vom Compile Knopf). Dadurch sollte sich ein neues Fenster öffnen. In diesem Fenster drücke auf Hardware Setup... und wähle den FPGA aus (Falls der FPGA nicht in der Liste erscheint, musst du noch den Treiber für den FPGA installieren. Dieser wird bei Quartus mitgeliefert (auf Windows in C:/intelFPGA_lite/21.1/quartus/drivers/usb-blaster)). Anschließend drücke Start, um den Programmer zu starten.

Schritt 2: Mikrocontroller (ESP32) mit Arduino IDE flashen

Zuerst solltest du das Projekt in /src/microcontroller mit der Arduino IDE öffnen. Natürlich kannst du z.B. auch die VS-Code Erweiterung nutzen, wir erklären hier aber die Variante mit der Arduino IDE selbst.
Da der von uns verwendete Mikrocontroller kein “echter” Arduino ist, müssen wir der IDE zunächst beibringen, wo die Board-Definitionen zu finden sind.
Dazu tragen wir unter Date -> Voreinstellungen im Feld Zusätzliche Bordverwalter-URLs folgendes ein:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Nachdem du mit OK bestätigt hast, sollte ein Eintrag esp32 unter Werkzeuge -> Board: [...] -> Bordverwalter auftauchen, bei welchem du auf Installieren klicken kannst.
Sobald die Boardinformationen fertig heruntergeladen wurden, kannst du nun unter Werkzeuge -> Board: [...] -> ESP32 Arduino den Eintrag ESP32 Dev Module wählen. Welcher Eintrag hier der richtige für dich ist, hängt allerdings davon ab, welcher Mikrocontroller genau verwendet wird - im Zweifel muss man hier etwas herumprobieren und auf der Hersteller-/Verkäuferwebsite nachschauen. Jetzt musst du unter Werkzeuge -> Port nur noch den richtigen Port wählen, an dem der Mikrocontroller mit dem Computer verbunden ist. Mit etwas Glück steht hier sogar die Bezeichnung des Mikrocontrollers mit in der Liste an Geräten. Wenn du Pech hast, musst du erstmal den richtigen Treiber herunterladen, damit der Mikrocontroller von deinem Betriebssystem erkannt wird - in diesem Fall hilft dir vielleicht die Seite von Espressif zu diesem Thema weiter: docs.espressif.com.
Wenn bis jetzt alles geklappt hat, musst du nur noch auf Sketch -> Hochladen klicken und hoffen, dass alles funktioniert. Gegebenenfalls muss beim Hochladen noch ein Button auf dem Mikrocontroller gedrückt werden, damit das schreiben erlaubt wird. Dieser Button kann z.B. mit BOOT beschriftet sein.

Schritt 3: Debugging-Software starten

Da wir mithilfe der Serial-API eine Website als Debugging-Software nutzen können, muss lediglich der Inhalt des Verzeichnisses /src/web mit einem simplen Webserver zur Verfügung gestellt werden. Alternativ ist die Website über GitHub Pages HIER bereitgestellt.

Schritt 4: Verwendung des Debuggers

Erste Schritte:

Die Debugger Website ist ähnlich wie ein terminal aufgebaut. Im rechten Bereich kannst du Befehle eintippen, während du auf der Linken Seite die Ausgabe des Mikrocontrollers siehst. Um eine Verbindung zwischen der Website und dem Mikrocontroller herzustellen, muss der Befehl connect eingegeben und mit Enter bestätigt werden. Anschließend sollte der Browser dich auffordern ein Serielles Gerät auszuwählen. Nachdem die Verbindugn erfolgreich hergestellt wurde, wird die Ausgabe zunächst automatisch synchronisiert. Dies kann auch manuell mit dem Befehl moin erzwungen werden.
Um den FPGA über den Pin GPIO0-0 zurückzusetzen, kannst du den Befehl reset eingeben. Nun sollte der FPGA die Ausführung des Programms starten und auf der linken Seite jede Aktualisierung des Programmzählers erscheinen. Falls bei einem Schritt des Programms etwas in ein Register geschrieben wird, wir die entsprechende Adresse und der zu schreibende Inhalt angezeigt.
Du solltest beachten, dass durch unsere Pipeline die Schreibvorgänge nicht zum eigentlichen Progrmmcounter, sondern etwas später im Log auftauchen.

(optional) Debugger-Board herstellen

Insgesamt sind 68 Pins des FPGA an den Mikrocontroller angeschlossen. Damit das möglich ist, benutzen wir sog. “Parallel-In-Serial-Out” Shiftregister. Um diese einfach zwischen den FPGA und den Mikrocontroller zu schalten, haben wir eine Platine entworfen. Der Pinout der Platine ist auf die Verwendung eines ESP-32 Dev Kit C von Espressif ausgelegt.

Die Projektdateien dazu befinden sich unter /src/board. In dem Ordner befindet sich auch eine Datei im Gerber-Format, sodass PCBs einfach bei Herstellern nachbestellt werden können.

Folgende Bauteile werden zum Bestücken der Platine benötigt: