workstation/README.md

# RISC-V Linux-Workstation auf dem ML507

Dieses Repository enthält die Implementierung einer RISC-V-Workstation
für das Xilinx ML507-Entwicklungsboard mit Unterstützung für das Booten
von Linux von einer SD-Karte. Die Workstation wurde im Rahmen einer
[Masterarbeit] an der Universität Leipzig entwickelt.

## Kompilieren der RISC-V-Toolchain und des Linux-Bootimage

Da für die Synthese der Workstation aufgrund der Kompilierung des enthaltenen
Bootloaders ebenfalls eine RISC-V-Toolchain nötig ist, wird diese zuerst
zusammen mit dem Linux-Bootimage erzeugt.

```sh
cd freedom-u-sdk
make
```

Falls dabei bei einem „Bleeding edge“-System wie Arch-Linux Fehler auftreten,
können nach Bedarf die im `patches`-Ordner verfügbaren Patches angewendet
werden. Weitere Details zum Freedom-SDK finden sich u.a. im
[Freedom U500 VC707 FPGA Dev Kit Getting Started Guide].

Anschließend wird das erzeugte Bootimage auf eine SD-Karte übertragen. Dabei
darf kein Partitionslayout vorhanden sein.

```sh
sudo dd if=work/bbl.bin of=/dev/sd-card bs=1M
sudo sync
```

Während des Kompilierens wird im Ordner `freedom-u-sdk/toolchain` eine RISC-V
GCC-Toolchain erstellt. Der Unterordner `bin` sollte für die folgenden
Schritte zur `PATH`-Umgebungsvariablen hinzugefügt werden.

## Synthese der Workstation für das ML507-Entwicklungsboard

### Erzeugen des Rocket-SOC

Zuerst wird der Rocket-SoC ohne das BootROM erzeugt:

```sh
cd freedom
make -f Makefile.u500ml507devkit verilog
```

Anschließend muss der dabei generierte DeviceTree 
`sifive.freedom.unleashed.u500ml507devkit.U500ML507DevKitConfig.dts`
im Ordner `builds/u500ml507devkit` wie folgt angepasst werden:

1. Der verwendete Systemtakt muss zuerst im `soc`-Abschnitt definiert werden:
        sysclk: sysclk {
            #clock-cells = <0>;
            compatible = "fixed-clock";
            clock-frequency = <60000000>;
        };

2. Anschließend wird er über `clocks = <&sysclk 0>;` in den `serial` und `spi`
   Abschnitten referenziert.
3. Es muss ein Alias für den UART-Controller im Hauptlevel hinzugefügt werden:
        aliases {
            serial0 = &L8;
        };

4. Die `dts`-Datei muss mit Hilfe des `dtc`-Programms kompiliert werden. Mit
   dem Ergebniss sollte die in `builds/u500ml507devkit` vorhandenen `dtb`-
   Datei überschrieben werden.

Um diese Schritte zu vereinfachen, enthält der `patches`-Ordner bereits
fertig angepasste `dts` und `dtb`-Dateien, mit denen die vorhandenen
ersetzt werden können. 

Schließlich wird das noch fehlende BootROM erzeugt, wobei dabei auch
der Bootloader kompiliert wird:

```sh
make -f Makefile.u500ml507devkit romgen
```

### Erzeugen des MIG-Speichercontrollers

Da der von MIG erzeugte Speichercontroller nicht ohne weiteres weitergegeben
werden darf, muss er von Hand dem ISE-Projekt hinzugefügt werden. Falls beim
öffnen des ISE-Projektes eine Meldung bezüglich fehlender Dateien erscheint,
wurde entweder der Rocket-SoC nicht korrekt erzeugt oder nicht alle git-
Submodule korrekt geklont.

 1. Rechtsklick auf das Projekt, *New Source…*
 2. *IP (Core Generator & Architecture Wizard)* auswählen
 3. Als Dateinamen `ddr2_controller` angeben, *Location* übernehmen
 4. MIG auswählen (zB über die Suche), *Next*, *Finish* -> MIG startet
 5. Prüfen, ob der korrekte FPGA ausgewählt ist
 6. Bei den Ausgabeoptionen nochmals den Namen überprüfen und *Create Design*
    auswählen
 7. Es sollten keine PIN-kompatiblen FPGAs oder der PPC440 ausgewählt werden
 8. `DDR2 SDRAM` als Speichertyp auswählen
 9. 5000 ps / 200 MHz als Takt, bei *Memory Type* `SODIMMs`, bei *Memory Part*
    das gewünschte Speichermodul (zB `MT4HTF3264HY-667` auf dem ML507) und bei
    *Date Width* `64` auswählen; Prüfen, ob *Data Mask* aktiviert ist
10. Prüfen, ob als *Burst Length* `4` ausgewählt ist
11. Den Haken bei *Use PLL* deaktivieren
12. Auf der nächsten Seite muss nichts verändert werden
13. Bei der Pin-Auswahl *New Design* auswählen und zwei mal bestätigen
14. Die Zusammenfassung sollte wie unten lauten
15. Das Memory-Modell über *Decline* nicht erzeugen lassen
16. Die PCB-Informationen bestätigen und den Controller generieren

Anschließend kann die Workstation mit einem Doppelklick auf "Generate
Programming File" synthetisiert werden. Der erzeugte FPGA-Bitstream befindet
sich im Ordner `project/ise/work` und kann per Impact auf das FPGA geladen
werden. Details zum Anschluss der SD-Karte befinden sich im Unterordner
`sd-breakout`.

```text
CORE Generator Options:
   Target Device                  : xc5vfx70t-ff1136
   Speed Grade                    : -1
   HDL                            : verilog
   Synthesis Tool                 : ISE
MIG Output Options:
   Module Name                    : ddr2_controller
   No of Controllers              : 1
   Selected Compatible Device(s)  : --
   PPC440                         : --
   PowerPC440 Block Selection     : --
FPGA Options:
   PLL                            : disabled
   Debug Signals                  : Disable
   System Clock                   : Single-Ended
   Limit to 2 Bytes per Bank      : disabled
Extended FPGA Options:
   DCI for DQ/DQS                 : enabled
   DCI for Address/Control        : disabled
   Class for Address and Control  : Class II
Controller Options:
   Memory                         : DDR2_SDRAM
   Design Clock Frequency         : 5000 ps(200.00 MHz)
   Memory Type                    : SODIMMs
   Memory Part                    : MT4HTF3264HY-667
   Equivalent Part(s)             : --
   Data Width                     : 64
   Memory Depth                   : 1
   ECC                            : ECC Disabled
   Data Mask                      : enabled
Memory Options:
   Burst Length (MR[2:0])         : 4(010)
   Burst Type (MR[3])             : sequential(0)
   CAS Latency (MR[6:4])          : 4(100)
   Output Drive Strength (EMR[1]) : Fullstrength(0)
   RTT (nominal) - ODT (EMR[6,2]) : 75ohms(01)
   Additive Latency (EMR[5:3])    : 0(000)
FPGA Options:
   IODELAY Performance Mode       : HIGH
```

## Lizenzen

Alle Komponenten der Workstation sind, wenn nicht anders gekennzeichnet,
unter GPLv3 lizenziert. Der für den FPGA erzeugte Bitstream darf jedoch
nicht unter GPLv3 und damit gar nicht weitergegeben werden, da er den
MIG-Speichercontroller enthält, dessen Quellcode nur unter ganz bestimmten
Bedingungen modifiziert und weitergegeben werden darf. 

Die Freedom-Platform ist unter der GPLv3-kompatiblen Apache2 Lizenz und
Rocket außerdem unter der BSD-Lizenz lizenziert. Linux ist ausschließlich
unter GPLv2 lizenziert.

[Masterarbeit]: https://klemens.schoelhorn.eu/abschlussarbeiten/
[Freedom U500 VC707 FPGA Dev Kit Getting Started Guide]: https://static.dev.sifive.com/SiFive-U500-vc707-gettingstarted-v0.2.pdf