polish docs

and a bit of code style

lib/risc/README.md

@@ -1,5 +1,4 @@
-Risc Machine
-================
+# Risc Machine
 
 The RiscMachine, is an abstract machine with registers. Think of it as an arm machine with
 normal instruction names. It is not however an abstraction of existing hardware, but only
@@ -17,31 +16,29 @@ All data is in objects.
 The register machine is aware of Parfait objects, and specifically uses Message and Frame to
 express call semantics.
 
-Calls and syscalls
-------------------
+## Calls and syscalls
 
-The RiscMachine only uses 1 fixed register, the currently worked on Message.
+The RiscMachine only uses 1 fixed register, the currently worked on Message. (and assumes a
+program counter and flags, neither of which are directly manipulated)
 
-There is no stack, rather messages form a linked list, and preparing to call, the data is pre-filled
-into the next message. Calling then means moving the new message to the current one and jumping
-to the address of the method. Returning is the somewhat reverse process.
+There is no stack, rather messages form a linked list, and preparing to call, the data is
+pre-filled into the next message. Calling then means moving the new message to the current
+one and jumping to the address of the method. Returning is the somewhat reverse process.
 
 Syscalls are implemented by *one* Syscall instruction. The Risc machine does not specify/limit
 the meaning or number of syscalls. This is implemented by the level below, eg the arm/interpreter.
 
-Interpreter
-===========
+## Interpreter
 
 There is an interpreter that can interpret compiled register machine programs.
-This is very handy for debugging (an nothing else).
+This is very handy for debugging (and nothing else).
 
 Even more handy is the graphical interface for the interpreter, which is in it's own repository:
 rubyx-debugger.
 
-Arm / Elf
-=========
+## Arm / Elf
 
-There is also a (very strightforward) transformation to arm instructions.
+There is also a (very straightforward) transformation to arm instructions.
 Together with the also quite minimal elf module, arm binaries can be produced.
 
 These binaries have no external dependencies and in fact can not even call c at the moment

lib/risc/builtin/README.md

@@ -1,18 +1,19 @@
-### Builtin module
+## Builtin module
 
 The Builtin module contains functions that can not be coded in ruby.
 It is the other side of the parfait coin, part of  the runtime.
 
-The functions are organized by their respective class and get loaded in boot_classes! ,
+The functions are organised by their respective classes and get loaded in boot_classes! ,
 right at the start. (see register/boot.rb)
 
 These functions return their code, ie a Parfait::TypedMethod with a MethodSource object,
 which can then be called by ruby code as if it were a "normal"  function.
 
-A normal ruby function is one that is parsed and transformed to code. But not all functionality can
-be written in ruby, one of those chicken and egg things.
+A normal ruby function is one that is parsed and transformed to code. But not all
+functionality can be written in ruby, one of those chicken and egg things.
 C uses Assembler in this situation, we use Builtin functions.
 
 Slightly more here : http://ruby-x.org/2014/06/10/more-clarity.html (then still called Kernel)
 
-The Builtin module is scattered into several files, but that is just so the file doesn't get too long.
+The Builtin module is scattered into several files, but that is just so the file
+doesn't get too long.

lib/risc/machine.rb

@@ -5,7 +5,7 @@ module Risc
   # actual assembler level to allow for several cpu architectures.
   # The Instructions (see class Instruction) define what the machine can do (ie load/store/maths)
 
-  # The ast is transformed to virtual-machine objects, some of which represent code, some data.
+  # From code, the next step down is Vool, then Mom (in two steps)
   #
   # The next step transforms to the register machine layer, which is quite close to what actually
   #  executes. The step after transforms to Arm, which creates executables.