From 64d6045d43c21345719bdeffc43277a0e2b771b5 Mon Sep 17 00:00:00 2001
From: Eyck-Alexander Jentzsch <alex@minres.com>
Date: Mon, 17 Jun 2024 18:38:55 +0200
Subject: [PATCH] expands README

---
 README.md | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index d296598..c0a28d8 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,25 @@
-# Firmware
+# MINRES Firmware Repository
+## Structure
+This repository comes with several executables ready to be built, such as `hello-world` or `coremark` and `dhrystone` in the `benchmark` directory.
+Creating the executables in the easiest way possible is done by calling `make`in the corresponding directory.
 
-Using `make clean && bear -- make ` will cause a correct compile_commands.json to be emitted. This allows using completion tools like clangd. 
\ No newline at end of file
+## Prerequisite
+This repository requires `riscv64-unknown-elf-gcc` to be located in `$PATH`.
+
+## How to Use
+When compiling executables, the target platform needs to be specified using the 'BOARD' variable. When compiling for the TGC5C for example, use  `make BOARD=tgc_vp`, when compiling for RTL `make BOARD=rtl`. The default value for the Board variable is 'iss'.
+The arch can be set with the 'ISA' variable, the default value is 'imc'.
+
+When compiling for the TGC5A VP for example, the call to create the correct binary is the following:
+```
+make BOARD=tgc_vp ISA=e
+```
+## Useful information
+Using `bear -- <build-command>` will cause a compile_commands.json to be emitted. This allows using completion tools like clangd. 
+
+## Current Limitations
+Currently, this repository only supports creation of 32-bit executables (Even when setting the `RISCV_ARCH` and `RISCV_ABI` manually).
+
+Compiling for the 'e' extension / ISA together with any other extension (`ISA=emc` for example), requires setting the `RISCV_ABI=ilp32e` explicitly. 
+
+When switching ABI ensure that object files in the corresponding 'env' dir in the 'bare-metal-bsp' submodule are removed, so they get created with the appropriate flags (namely the 'init.o' file).