added debugging info

README.md

@@ -52,6 +52,12 @@ disable_io              Disallow reading/writing from stdin/stdout/stderr
 If multiple files are specified, all are loaded into memeory, but only the last one is executed. This might be improved 
 later, maybe the `_init` section of each binary is executed before the main loop starts? 
 
+## Debugging
+See [docs/debugging.md](docs/debugging.md) for more info.
+
+![debuggin the fibs program](docs/debug-session.png)
+
+
 ## Resources:
   * Pseudo ops: https://www.codetd.com/article/8981522
   * RISC-V reference card: https://www.cl.cam.ac.uk/teaching/1617/ECAD+Arch/files/docs/RISCVGreenCardv8-20151013.pdf

docs/debugging.md

@@ -0,0 +1,63 @@
+# Using the debugger
+
+You are launched into the debugger either by an `ebreak/sbreak` instruction, or when an exception occurs while running executing instructions.
+
+Consider the example programm `examples/fibs.asm`:
+
+```asm riscv-asm
+        .data
+fibs:   .space 56
+
+        .text
+main:
+        addi    s1, zero, 0     ; storage index
+        addi    s2, zero, 56    ; last storage index
+        addi    t0, zero, 1     ; t0 = F_{i}
+        addi    t1, zero, 1     ; t1 = F_{i+1}
+loop:
+        sw      t0, fibs(s1)    ; save
+        add     t2, t1, t0      ; t2 = F_{i+2}
+        addi    t0, t1, 0       ; t0 = t1
+        addi    t1, t2, 0       ; t1 = t2
+        addi    s1, s1, 4       ; increment storage pointer
+        blt     s1, s2, loop    ; loop as long as we did not reach array length
+        ; exit gracefully
+        ebreak                  ; launch debugger
+        addi    a0, zero, 0
+        addi    a7, zero, 93
+        scall                   ; exit with code 0
+```
+
+This calculates the fibonacci sequence and stores it in memory at `fibs`. After it calculated all fibonacci numbers, it
+uses the `ebreak` instruction to open the debugger. Let's run it and see what happens:
+
+```
+> python -m riscemu examples/fibs.asm
+Successfully loaded: LoadedExecutable[examples/fibs.asm](base=0x00000100, size=72bytes, sections=data text, run_ptr=0x00000138)
+Debug instruction encountered at 0x00000143
+>>> 
+```
+
+In this interactive session, you have access to the cpu, registers, memory and syscall interface. You can look into everything,
+and most common tasks should have helper methods for them.
+
+Available objects are:
+
+* `mem`: (aka `mmu` or `memory`)
+  * `dump(address, fmt='hex', max_rows=10, group=4, bytes_per_row=16, all=False`:
+    Dumps the memory at `address`, in at most `max_rows` rows, each containing `bytes_per_row` bytes grouped
+    into groups of `group` bytes. They can be printed as:
+    * `hex`: hexadecimal, unsigned
+    * `int`: converted to integers
+    * `uint`: converted to unsigned integers
+  * `symbol(name)`: Lookup all symbols named `name`
+* `reg`: (aka `regs` or `registers`)
+  * `dump(full=False)` dumps all integer registers (unless `all` is true, then all registers are printed)
+  * `get(name)` get register content
+  * `set(name, val)` set register content
+* `cpu`:
+  * The CPU has the `pc` attribute and `cycle` attribute. Others won't be useful in this context. 
+  
+Example:
+
+![debuggin the fibs program](debug-session.png)

examples/fibs.asm

@@ -0,0 +1,24 @@
+; Example program (c) by Anton Lydike
+; this calculates the fibonacci sequence and stores it in ram
+
+        .data
+fibs:   .space 56
+
+        .text
+main:
+        addi    s1, zero, 0     ; storage index
+        addi    s2, zero, 56    ; last storage index
+        addi    t0, zero, 1     ; t0 = F_{i}
+        addi    t1, zero, 1     ; t1 = F_{i+1}
+loop:
+        sw      t0, fibs(s1)    ; save
+        add     t2, t1, t0      ; t2 = F_{i+2}
+        addi    t0, t1, 0       ; t0 = t1
+        addi    t1, t2, 0       ; t1 = t2
+        addi    s1, s1, 4       ; increment storage pointer
+        blt     s1, s2, loop    ; loop as long as we did not reach array length
+        ; exit gracefully
+        ebreak                  ; launch debugger
+        addi    a0, zero, 0
+        addi    a7, zero, 93
+        scall                   ; exit with code 0