riscv-playground-manual/README.md

# 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).  <!-- Den Schritt würde ich vorher erwähnen, wer liest sich schon den nächsten Schritt durch bevor der davor ausgeführt wird^^ -->
 - Baut den Compiler mit allen verfügbaren Threads: `make -j <anzahl der threads eures CPU>`. 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.