From b0d68ed8d6bee69fcaec05e4f34bfc1c0de053d7 Mon Sep 17 00:00:00 2001
From: Joscha <joscha@plugh.de>
Date: Sun, 10 Nov 2019 21:57:11 +0000
Subject: [PATCH] Add readme for examples

---
 README.md          | 12 +++++++----
 examples/README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+), 4 deletions(-)
 create mode 100644 examples/README.md

diff --git a/README.md b/README.md
index 8d1bb74..0feec41 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,9 @@
 A set of tools and specifications related to the MiMa
 (Minimalmaschine).
 
-* [Programs](#programs)
+* [Tools](#tools)
+  * [mima-run](#mima-run)
+  * [mima-asm](#mima-asm)
 * [Specification](#specification)
   * [Instructions](#instructions)
   * [Registers](#registers)
@@ -11,9 +13,11 @@ A set of tools and specifications related to the MiMa
   * [Memory dump file format: `.mima`](#memory-dump-file-format-mima)
 * [Conventions](#conventions)
 
-## Programs
+For example MiMa programs, see the [examples folder](examples/).
 
-### `mima-run`
+## Tools
+
+### mima-run
 
 This program can load and run `.mima` files.
 
@@ -36,7 +40,7 @@ Available options:
                            further actions. Roughly equivalent to -n 0
 ```
 
-### `mima-asm`
+### mima-asm
 
 This program can parse `.mimasm` files and convert them to `.mima`
 files. More information and a specification of the `.mimasm` format
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..d323e8e
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,53 @@
+# Example MiMa programs
+
+This folder contains a few example programs, both as `.mimasm` and as
+assembled `.mima` files.
+
+* [Basic programs](#basic-programs)
+* [Advanced programs](#advanced-programs)
+
+## Basic programs
+
+### [`jmp_to_address_in_acc.mimasm`](jmp_to_address_in_acc.mimasm)
+
+This program demonstrates two different techniques for jumping to an
+address that is currently stored in the `ACC` register.
+
+### [`call_ret.mimasm`](call_ret.mimasm)
+
+This program demonstrates how the `CALL` and `RET` instructions
+behave. It doesn't use any sort of stack, so the call depth is limited
+to 1.
+
+### [`call_ret_stack.mimasm`](call_ret_stack.mimasm)
+
+This program works similar to `call_ret.mimasm`, but uses the `SP`
+register for a stack. This way, it can have nested `CALL`s by storing
+the content of the `RA` register on the stack.
+
+## Advanced programs
+
+### [`stack.mimasm`](stack.mimasm)
+
+This program demonstrates the use of stack frames for calling a
+function and passing parameters.  To call a function, it creates a
+shared stack frame containing the function's input parameters and
+enough space for its return values.
+
+### [`fib.mimasm`](fib.mimasm)
+
+This program calculates the first few fibonacci numbers and stores
+them in consecutive memory locations. It uses a stack with stack
+frames and recursive calls according to the following pattern:
+
+``` c++
+int fib(int n) {
+    if (n == 0) return 0;
+    if (n == 1) return 1;
+    return fib(n - 1) + fib(n - 2);
+}
+```
+
+This recursive solution for calculating fibonacci numbers is by far
+not the most efficient, but it demonstrates recursion and stack usage
+quite well.