From 3598cbe3b60416be97a4254e8e7145ad44e47ebb Mon Sep 17 00:00:00 2001 From: jasonwilliams Date: Sun, 24 Jan 2021 18:51:35 +0000 Subject: [PATCH] documentation on output --- docs/vm.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/vm.md b/docs/vm.md index b0d43309a10..1080d6dfb9a 100644 --- a/docs/vm.md +++ b/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) +3μs One +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.