Refresh vm docs and fix bytecode trace output (#1921)
It changes the following:
- Refreshes the vm and debugging docs to represent the current state
- Fix some bytecode trace output
- Rename a field in the `CodeBlock`
@ -10,7 +10,7 @@ We use a crate called [measureme](https://github.com/rust-lang/measureme), which
When the "profiler" flag is enabled, you compile with the profiler and it is called throughout the interpreter.
when the feature flag is not enabled, you have an empty dummy implementation that is just no ops. rustc should completely optimize that away. So there should be no performance downgrade from these changes
By default Boa does not use the VM branch; execution is done via walking the AST. This allows us to work on the VM branch whilst not interrupting any progress made on AST execution.
You can interpret bytecode by passing the "vm" flag (see below). The diagram below should illustrate how things work today (Jan 2021).
## Enabling ByteCode interpretation
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. You can also pass the `--trace` optional flag to print the trace of the code.
-------------------------------------- Vm Start --------------------------------------
Time Opcode Operands Top Of Stack
64μs DefLet 0000: 'a' <empty>
3μs PushOne 1
21μs InitLexical 0000: 'a' <empty>
32μs DefLet 0001: 'b' <empty>
2μs PushInt8 2 2
17μs InitLexical 0001: 'b' <empty>
------------------------------------------ VM Start ------------------------------------------
Time Opcode Operands Top Of Stack
386μs PushOne 1
6μs DefInitLet 0000: 'a' <empty>
1μs PushInt8 2 2
2μs DefInitLet 0001: 'b' <empty>
Stack:
<empty>
@ -57,38 +50,25 @@ Stack:
undefined
```
The above will output three sections that are divided into subsections:
The above output contains the following information:
- The code that will be executed
- `Code`: The bytecode.
- The bytecode and properties of the function that will be executed
- `Compiled Output`: The bytecode.
- `Location`: Location of the instruction (instructions are not the same size).
- `Count`: Instruction count.
- `Opcode`: Opcode name.
- `Operands`: The operands of the opcode.
- `Literals`: The literals used by the opcode (like strings).
- `Names`: Contains variable names.
- The code being executed (marked by `"Vm Start"`).
- `Literals`: The literals used by the bytecode (like strings).
- `Bindings`: Binding names used by the bytecode.
- `Functions`: Function names use by the bytecode.
- The code being executed (marked by `Vm Start` or `Call Frame`).
- `Time`: The amount of time that instruction took to execute.
- `Opcode`: Opcode name.
- `Operands`: The operands this opcode took.
- `Operands`: The operands of the opcode.
- `Top Of Stack`: The top element of the stack **after** execution of instruction.
- `Stack`: The trace of the stack after execution ends.
- The result of the execution (The top element of the stack, if the stack is empty then `undefined` is returned).
### 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 **after** 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.
### Literals
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 `PushOne` has been executed the next instruction (`InitLexical 0`) has a `1` on the top of the stack. This is because `PushOne` 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.
raskad
3 years ago
