Update examples and add simple example

examples/README.md

@@ -1,44 +1,50 @@
 # Example MiMa programs
 
-This folder contains a few example programs, both as `.mimasm` and as
+This folder contains a few example programs, both as `.mimasm` and as assembled
-assembled `.mima` files.
+`.mima` files.
 
 * [Basic programs](#basic-programs)
 * [Advanced programs](#advanced-programs)
 
 ## Basic programs
 
-### [`jmp_to_address_in_acc.mimasm`](jmp_to_address_in_acc.mimasm)
+### [`subtract.mimasm`](subtract.mimasm)
 
-This program demonstrates two different techniques for jumping to an
+This is a very simple program that just subtracts a value from another and
-address that is currently stored in the `ACC` register.
+stores the result in memory. It is meant as a starting point for working with
+this repo's tools.
 
 ### [`call_ret.mimasm`](call_ret.mimasm)
 
-This program demonstrates how the `CALL` and `RET` instructions
+This program demonstrates how the `CALL` and `RET` instructions behave. It
-behave. It doesn't use any sort of stack, so the call depth is limited
+doesn't use any sort of stack, so the call depth is limited and recursion is not
-to 1.
+easily possible.
 
 ### [`call_ret_stack.mimasm`](call_ret_stack.mimasm)
 
-This program works similar to `call_ret.mimasm`, but uses the `SP`
+This program works similar to `call_ret.mimasm`, but uses the `SP` register for
-register for a stack. This way, it can have nested `CALL`s by storing
+a stack. This way, it can have nested `CALL`s by storing the content of the `RA`
-the content of the `RA` register on the stack.
+register on the stack.
+
+### [`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.
 
 ## Advanced programs
 
 ### [`stack.mimasm`](stack.mimasm)
 
-This program demonstrates the use of stack frames for calling a
+This program demonstrates the use of stack frames for calling a function and
-function and passing parameters.  To call a function, it creates a
+passing parameters. To call a function, it creates a shared stack frame
-shared stack frame containing the function's input parameters and
+containing the function's input parameters and enough space for its return
-enough space for its return values.
+values.
 
 ### [`fib.mimasm`](fib.mimasm)
 
-This program calculates the first few fibonacci numbers and stores
+This program calculates the first few fibonacci numbers and stores them in
-them in consecutive memory locations. It uses a stack with stack
+consecutive memory locations. It uses a stack with stack frames and recursive
-frames and recursive calls according to the following pattern:
+calls according to the following pattern:
 
 ``` c++
 int fib(int n) {
@@ -48,6 +54,19 @@ int fib(int n) {
 }
 ```
 
-This recursive solution for calculating fibonacci numbers is by far
+This recursive solution for calculating fibonacci numbers is by far not the most
-not the most efficient, but it demonstrates recursion and stack usage
+efficient, but it demonstrates recursion and stack usage quite well.
-quite well.
+
+### [`bench.mimasm`](bench.mimasm)
+
+This program is `fib.miamsm`, but it calculates the first 24 fibonacci numbers
+instead of the first 10. It is meant as a benchmark for MiMa emulators and takes
+11877318 steps to execute (not counting the HALT instruction).
+
+### [`sort.mimasm`](sort.mimasm)
+
+This program sorts an array of numbers that starts at memory address 0. It
+demonstrates a few more advanced assembler directives, including flags, as well
+as a bit of non-trivial, non-stack-management logic. It is based on an exercise
+that defined areas for the array, temporary variables and code, as well as a
+field containg the address of the array's last element.

examples/subtract.mima-symbols

@@ -0,0 +1,4 @@
+00000: val1
+00001: val2
+00002: result
+00003: start

examples/subtract.mimasm

@@ -0,0 +1,22 @@
+; This program computes 'val1 - val2' and stores the result in memory again.
+
+; Set the IAR to the instruction at the 'start' label
+.reg IAR start
+
+; Prepare the input and output
+val1:   .lit 24
+val2:   .lit 13
+result: .lit 0
+
+; First, we load and negate val2
+start:
+LDV val2
+NOT
+ADC 1
+
+; Then, we can add val1 and store the result
+ADD val1
+STV result
+
+; Don't forget to halt, or the MiMa will run until the IAR hits the maximum address.
+HALT