1 files changed, 12 insertions, 5 deletions
diff --git a/mu_instructions b/mu_instructions
index f9866aca..e0df3496 100644
--- a/mu_instructions
+++ b/mu_instructions
@@ -1,10 +1,17 @@
 ## Mu's instructions and their table-driven translation
 
-Mu is a statement-oriented language. Blocks consist of flat lists of instructions.
-The following chart shows all the instruction forms supported by Mu, along
-with the instruction they're translated to. Variables of the form 'var/reg'
-live in a register, and other variables are assumed to live on the stack at
-some 'stack-offset' from ebp.
+See http://akkartik.name/akkartik-convivial-20200315.pdf for the complete
+story. In brief: Mu is a statement-oriented language. Blocks consist of flat
+lists of instructions. Instructions can have inputs after the operation, and
+outputs to the left of a '<-'. Inputs and outputs must be variables. They can't
+include nested expressions. Variables can be literals ('n'), or live in a
+register ('var/reg') or in memory ('var') at some 'stack-offset' from the 'ebp'
+register. Outputs must be registers. To modify a variable in memory, pass it in
+by reference as an input. (Inputs are more precisely called 'inouts'.)
+Conversely, registers that are just read from must not be passed as inputs.
+
+The following chart shows all the instruction forms supported by Mu, along with
+the SubX instruction they're translated to.
 
 var/eax <- increment              => "40/increment-eax"
 var/ecx <- increment              => "41/increment-ecx"