--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/os.rst	Mon Jan 27 19:58:07 2014 +0100
@@ -0,0 +1,103 @@
+OS
+==
+
+Design
+------
+
+Processes / threads
+~~~~~~~~~~~~~~~~~~~
+
+Processes are completely seperated and fully pre-emptive.
+This means a process can be unscheduled at any moment.
+
+Threads are co-operative. This means they yield control
+voluntary. This means that mutexes and locks are not required.
+This is done with the built-in language feature called tasks.
+
+If some heavy duty task must be performed, either way spawn
+a new process, or yield frequently from this hard labour.
+
+tasks
+~~~~~
+
+Consider the following:
+
+.. code::
+
+    function int insanemath(int a)
+    {
+        while (a > 0)
+        {
+           a = a -1;
+           resume agent1;
+        }
+        return a - 1;
+    }
+
+    task agent1()
+    {
+      start agent2;
+    }
+
+    task agent2()
+    {
+       insanemath(55);
+       insanemath(44);
+    }
+
+    task main()
+    {
+      start agent1;
+      join agent1;
+    }
+
+
+Say to tasks are running in concurrent / parallel.
+
+
+
+Stack layout for tasks.
+||
+||
+\/
++---------+
+| return address
+| locals
+|
++------
+| return address
+| locals
+|
++---
+
+Assembly code for the functions above:
+
+.. code::
+
+    .code
+    insanemath:
+    L1:
+    load r0, sp - 4
+    cmp r0, 0
+    jl L2
+    dec r0
+    store r0, sp - 4
+    jmp L1
+    L2:
+    ret
+
+    agent1:
+    hlt?
+
+    agent2:
+    hlt?
+
+    main:
+    jmp agent1
+
+    .data
+    agent1_task:
+    dd 0
+    agent2_task:
+    dd 0
+