# RISC-V Playground Willkommen im RISC-V Playground! ## Installation *Dieser Schritt ist in der gelieferten VM bereits abgeschlossen.* 1. Um den RISC-V Emulator zu installieren wird Python 3 und den Python Package Manger pip benötigt. Unter Linux ist beides in den meisten Paketmanagern enthalten und sollte über die bekannten Möglichkeiten installiert werden können. 2. Installiere den Emulator als pip-Paket (das Paket heißt `riscemu`): `pip install riscemu` 3. Der Emulator wird als Python-Paket installiert und kann mit `python3 -m riscemu` ausgeführt werden. Teste deine Installation mit `python3 -m riscemu --version`, es sollte mindestens Version `2.0.3` installiert sein. ## RISC-V Code Ausführen *Der RISC-V Emulator hat nur ein Konsoleninterface, weswegen auch folgendes Beispiel auf der Konsole abläuft. In Ubuntu kann mithilfe des Kontextmenüs (Rechtsklick) im Dateibrowser über den Eintrag "Im Terminal öffnen" ein Terminal geöffnet werden, in dem bereits der entsprechende Ordner geöffnet ist.* Betrachten wir das Beispiel: `hello-world.asm` ``` # hello-world.asm # print "hello world" to stdout and exit .data text: .asci "Hello World\n" .text li a0, 1 la a1, text li a2, 12 li a7, 64 ecall li a0, 0 li a7, 93 ecall ``` Das Programm kann auf der Konsole mit dem dem Befehl `python3 -m riscemu hello-world.asm` ausgeführt werden. Dafür solltest du in der Konsole in dem gleichen Ordner wie dein assembly-Programm sein. Es sollte der folgende Output in deiner Konsole erscheinen: ``` > python3 -m riscemu hello-world.asm Hello World ``` Der emulator kann mit verschiedenen Parametern gestartet werden, z.B. kann mit `-v` die `verbosity` (die menge an Informationen die ausgegeben werden) erhöht werden. Das wiederholen der "v"s erhöht das level weiter. So wird z.B. mit dem ersten `-v` bei jedem Sprung das Sprungziel ausgegeben sowie mehr informationen über den Start und Stopp. Ab `-vv` wird jeder ausgeführte assembly Befehl ausgegeben: ``` [CPU] Created stack of size 524288 at 0x130 [CPU] Started running from hello-world.asm:.text at text (0x100) + 0x10 Program(name=hello-world.asm,sections=set(),base=['.data', '.text']) Running 0x00000110: li a0, 1 Running 0x00000114: la a1, text Running 0x00000118: li a2, 12 Running 0x0000011C: li a7, 64 Running 0x00000120: ecall Hello World Running 0x00000124: li a0, 0 Running 0x00000128: li a7, 93 Running 0x0000012C: ecall [CPU] Program exited with code 0 ``` ## Debugging Der RISC-V Standard hat einen Befehl reserviert, der als sogenannter "Breakpoint" agiert. Wenn der Emulator diesen Befehl ausführt, wird ein interaktiver Debugger gestartet. Lass uns nun hinter den ersten `ecall` Befehl in `hello-world.asm` einen Breakpoint-Befehl einfügen: ``` # ... .text li a0, 1 la a1, text li a2, 12 li a7, 64 ecall ebreak # Breakpoint um den Debugger zu starten li a0, 0 li a7, 93 ecall ``` Wenn das Programm nun ausgeführt wird, wird der folgende Output generiert: ``` Hello World Debug instruction encountered at 0x00000127 [CPU] Debugger launch requested! >>> ```` Dies ist der interaktive Debugger. Hier kann der Zustand der Register, der CPU und des Arbeitsspeichers betrachtet werden. Eine Übersicht der wichtigsten Funktionen sind in der debugging.md Datei zu finden. ## Installation der RISC-V Gnu Toolchain *Auch dieser Schritt ist in der VM schon erledigt.* Für die Installation unter Linux (Ubuntu) ist ein Installationsskript beigelegt, welches die RISC-V Toolchain für die Nutzung im Rahmen der Vorlesung konfiguriert und kompiliert. Ich bin mir nicht sicher ob die toolchain unter Windows kompilierbar ist, nehmt dafür am besten das [WSL](https://docs.microsoft.com/en-us/windows/wsl/install) Falls das Skript für eure Platform nicht funktioniert, hier noch ein paar Tipps: - Ihr braucht ca 8 Gigabyte Festplattenplatz um RISC-V GCC zu kompilieren. (Ein teil kann nach der Installation gelöscht werden). - In der [GitHub Readme](https://github.com/riscv-collab/riscv-gnu-toolchain#readme) findet ihr die genauen Pakete, die ihr auf eurer Distribution installieren müsst. - Klont das Repository mit `git clone --depth 1 https://github.com/riscv-collab/riscv-gnu-toolchain.git` um nicht die ganze git history mit herunter zu laden. - Konfiguriert die Installation mit dem folgenden Befehl (dafür müsst ihr in die geklonte Repo rein `cd`'en): `./configure --prefix=$(pwd)/../toolchain/ --with-arch=rv32ima --disable-linux --disable-gdb --disable-multilib`. Der Zielordner muss unbedingt per Hand angelegt werden, sonst funktioniert die Kompilation nicht! Also muss `mkdir $(pwd)/../toolchain/` ausgeführt werden (Legt den ordner `toolchain` im Überordner der Repo an). - Baut den Compiler mit allen verfügbaren Threads: `make -j `. Die Anzahl der verfügbaren Threads kann mit dem Befehl `grep -c ^processor /proc/cpuinfo` bestimmt werden. - Nach der Installation sollte der `toolchain/bin` Ordner zur `$PATH`-Variable hinzugefügt werden, hierfür gibt es mehrere Möglichkeiten. Hier ein tutorial zur `$PATH`-Variable: https://www.howtogeek.com/658904/how-to-add-a-directory-to-your-path-in-linux/ Jetzt kann mit Hilfe der Toolchain, C und RISC-V Assembly in RISC-V Objektdateien und Executables kompiliert werden: ``` # "riscv32-unknown-elf" ist das Präfix, und Folgendes der Befehl für den Assembler: > riscv32-unknown-elf-as hello-world.asm -o hello-world.out # Gleiches Präfix, hier benutzen wir objdump um den Inhalt zu decodieren: > riscv32-unknown-elf-objdump -SF hello-world.out hello-world.out: file format elf32-littleriscv Disassembly of section .text: 00000000 <.text> (File Offset: 0x34): 0: 00100513 li a0,1 4: 00000597 auipc a1,0x0 8: 00058593 mv a1,a1 c: 00c00613 li a2,12 10: 04000893 li a7,64 14: 00000073 ecall 18: 00000513 li a0,0 1c: 05d00893 li a7,93 20: 00000073 ecall ``` Dies wird jedoch erst im weiteren Verlauf der Vorlesung wirklich wichtig werden. Zunächst werden wir mit Klartext Assembly arbeiten.