documentation on output

docs/vm.md

@@ -12,6 +12,56 @@ You can interpret bytecode by passing the "vm" flag (see below). The diagram bel
 
 You need to enable this via a feature flag. If using VSCode you can run `Cargo Run (VM)`. If using the command line you can pass `cargo run --features vm ../tests/js/test.js` from within the boa_cli folder.
 
+## Understanding the output
+
+Once set up you should you can try some very simple javascript in your test file. For example:
+
+```js
+let a = 1;
+let b = 2;
+```
+
+Should output:
+
+```
+VM start up time: 0μs
+Time       Instr                Top Of Stack
+
+27μs       DefLet(0)             <empty>
+3μs        One                   <empty>
+35μs       InitLexical(0)        1      0x7f727f41d0c0
+18μs       DefLet(1)             1      0x7f727f41d0c0
+4μs        Int32(2)              1      0x7f727f41d0c0
+19μs       InitLexical(1)        2      0x7f727f41d0d8
+
+Pool
+0          "a" 0x7f727f41d120
+1          "b" 0x7f727f41d138
+
+Stack
+0          1 0x7f727f41d0c0
+1          2 0x7f727f41d0d8
+
+2
+```
+
+The above will output 3 sections: Instructions, pool and Stack. We can go through each one in detail:
+
+### Instruction
+
+This shows each instruction being executed and how long it took. This is useful for us to see if a particular instruction is taking too long.
+Then you have the instruction itself and its operand. Last you have what is on the top of the stack **before** the instruction is executed, followed by the memory address of that same value. We show the memory address to identify if 2 values are the same or different.
+
+### Pool
+
+JSValues can live on the pool, which acts as our heap. Instructions often have an index of where on the pool it refers to a value.
+You can use these values to match up with the instructions above. For e.g (using the above output) `DefLet(0)` means take the value off the pool at index `0`, which is `a` and define it in the current scope.
+
+### Stack
+
+The stack view shows what the stack looks like for the JS executed.
+Using the above output as an exmaple, after `One` has been executed the next instruction (`InitLexical(0)`) has a `1` on the top of the stack. This is because `One` puts `1` on the stack.
+
 ### Comparing ByteCode output
 
 If you wanted another engine's bytecode output for the same JS, SpiderMonkey's bytecode output is the best to use. You can follow the setup [here](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Introduction_to_the_JavaScript_shell). You will need to build from source because the pre-built binarys don't include the debugging utilities which we need.